< or greater.
* [MSPM0 SDK](https://dev.ti.com/tirex/explore/node?node=A__AMztb67RYAJCCVC9dL423Q__MSPM0-SDK__a3PaaoK__LATEST). This can be installed as a step of Lab 1 (recommended).
Hardware
* LP-MSPM0L1306 or LP-MSPM0G3507 LaunchPad
* Internet access
Lab 1: Importing, Editing, and Running an Example Project
---------------
This lab will go over importing an example project from the MSPM0 SDK, making some edits to modify the program's functionality, and flashing the program to the target (the MSPM0 LaunchPad) to run the program.
### Importing and Running an Example Project
The default steps use the CCS Theia **Resource Explorer** to download the MSPM0 SDK and import the example. This will require an internet connection.
[[+y For manual steps instead to install the SDK and import the example (without **Resource Explorer**) (Expand):
1. Download and install the MSPM0 SDK version that is compatible with your MSPM0 LaunchPad revision, and take note of the install location.
2. Connect your MSPM0 LaunchPad board to the computer via USB cable.
3. Open Code Composer Studio Theia.
4. From the top menu bar, select: **File → Preferences → Open Code Composer Studio Settings**
5. In the dialog, select the **Products** node in the left panel and check to see if there is an entry for the installed MSPM0 SDK under the list of **Discovered products**. If it does not appear in the list, press the **Refresh** button to have CCS Theia look for newly installed packages.
[[y Note
If the SDK was not installed in one of the parent directories listed in the **Product discovery-path** list, the parent directory path of the SDK will need to be added to that list before the **Refresh** attempt.
]]
After the SDK has been discovered, press the **OK** button to close the **Preferences** dialog.
6. From the top menu bar, open: **Project → Import CCS Project(s)**.
7. Click **Browse...** and navigate to the location of the MSPM0 SDK install. From there, we will find an example project to import into CCS Theia.
The example used in this lab is **gpio_toggle_output**, a simple (non RTOS-based) project that blinks the RGB LED on your board with a different colour every 10 million CPU cycles. This project is useful as a bare starting point to develop your application.
Navigate to the appropriate example folder - `examples/nortos/<BOARD>/driverlib/gpio_toggle_output/ticlang` - where `<BOARD>` should be your LaunchPad board model.
Click **Select Folder** then **Finish** to import the project.
Now skip to step 10 below.
+]]
1. Connect your MSPM0 LaunchPad board to the computer via USB cable.
2. Open Code Composer Studio Theia.
3. ***Skip directly to step 4 if the MSPMO SDK has NOT been manually pre-installed***:
If the MSPM0 SDK was manually pre-installed, select: **File → Preferences → Open Code Composer Studio Settings** from the top menu bar to open the CCS **Preferences** dialog.
In the dialog, select the **Products** node in the left panel and check to see if there is an entry for the installed MSPM0 SDK under the list of **Discovered products**. If it does not appear in the list, press the **Refresh** button to have CCS look for newly installed packages.
[[y Note
If the SDK was not installed in one of the parent directories listed in the **Product discovery-path** list, the parent directory path of the SDK will need to be added to that list before the **Refresh** attempt.
]]
After the SDK has been discovered, press the **OK** button to close the **Preferences** dialog.
4. If the **Getting Started** view is not already open, go to the top menu bar and select: **Help → Getting Started**.
5. Under the **Get Started** section in the **Getting Started** view, the MSPM0 Launchpad should be detected. If it is not detected, manually select the LaunchPad in the drop-down list.
6. Select the **Create a new project** option. This will open **Project Wizard**.
7. **Project Wizard** will then display a list of example for the specified LaunchPad. Scroll down the list to the **gpio_toggle_output** example and select the **Compiler** for **CCS - TI Arm Clang Compiler**. Press **CREATE** to continue.
8. ***Skip directly to step 10 if the MSPMO SDK has been manually pre-installed and discovered by CCS***:
If the MSPM0 SDK was not manually pre-installed, a prompt will appear indicating that the SDK package must be installed locally to proceed with the import. Press the **Download and Install** button to proceed.
Another prompt will appear, displaying information about the package (and any dependencies) to be downloaded and installed. Press the **Install** button to proceed with the download and installation of the SDK package.
This process will take several minutes. The below dialog will appear when the SDK has been successfully downloaded and installed.
9. After closing the above dialog, another dialog will appear to prompt for confirmation to proceed with the project import. Press the **Import** button to continue.
Then select the device applicable to your LaunchPad:
10. Check the **Explorer** in the **Side Bar** and confirm that the **gpio_toggle_output** example. The associated **README.md** file should also be opened in editor. This file provides more information about the example.
The example project has now been imported to the workspace. Optionally, the **Getting Started**, **Project Wizard** views, and the **README.md** file may optionally be closed since they will no longer be needed for the rest of this workshop.
11. Browse through the **gpio_toggle_output** project in the **Explorer**. Useful files to look through include **gpio_toggle_output.c** and **gpio_toggle_output.syscfg**.
* **gpio_toggle_output.c**: The *main()* function is defined here, and in this case, will power on and initialize the needed GPIO pins, before entering an infinite main loop. Other application functions such as interrupt callbacks can be defined in this file as well.
* **gpio_toggle_output.syscfg**: A tool to simplify the configuration of your application on an MSPM0 device.
You can also see the pins and resources being used by clicking **Show Device** at the top right corner of SysConfig.
<!-- TODO: Replace hyperlink with SysConfig module from MSPM0 SDK when available -->
More information regarding SysConfig can be found at this [SysConfig Guide](https://dev.ti.com/tirex/content/mspm0_sdk_2_01_00_03/docs/english/tools/sysconfig_guide/doc_guide/doc_guide-srcs/sysconfig_guide.html#introduction "SysConfig Guide") page.
12. Bring up the context menu (ex: mouse right-click) for the project in the **Explorer** and select **Properties...** to open the project properties. In the properties dialog, browse to **Build → Arm Compiler → Optimization** in the left pane and set **Select optimization paradigm/level (-O)** to **0** to disable optimization. This is to increase debug visibility of the project during debug. See the article [Debug versus Optimization Tradeoff](https://software-dl.ti.com/ccs/esd/documents/sdto_cgt_debug_versus_optimization_tradeoff.html "Debug versus Optimization Tradeoff") for more details.
13. Bring up the context menu (ex: mouse right-click) for the project in the **Explorer** and select **Debug Project** (or select **Run → Debug Project (...)** in the top menu bar). This will prompt to save source files, build the project, start the debugger, switch to the **Debug** view in the **Side Bar**, connect CCS Theia to the target, and then flash (load) the program to the target.
When running in debug mode, your LaunchPad is at first suspended. Click on the blue **Continue** icon near the top left of the **Debug** view, or click **Run → Continue** in the menu bar, for your LaunchPad to run the program.
* There are icons on the left sidebar which allow you to switch between the **Debug** and the **Explorer** views.
* Note that LED on your LaunchPad board is now switching between red and light blue at a fixed rate, as expected. The program is being run.
* You can **Pause** and **Continue** program execution on the target as desired.
14. When you are done with this part of the lab, **Stop** the debug session and return to the **Explorer** view.
### Modifying the Project
Currently the program simply blinks the LED on the LaunchPad every 16,000,000 cycles. Say that some functionality needs to be added to the program such that the blinking frequency is controllable. The program will be modified as follows.
* When the program is first run on the LaunchPad, the RGB LED (LED1, LED2, LED3) will initially be blinking with a delay of 10,000,000 cycles.
* Whenever the left button is pressed, the delay between blinks of the LED will be halved, up to a minimum of 312,500 cycles.
* If the button is pressed when the delay is already at its allowed minimum, it is reset to 10,000,000 cycles.
* Whenever the left button is pressed, the state of a different red LED (LED4) will be toggled.
Let's get started!
<!-- TODO: Currently, TI Drivers module is not available in SysConfig for MSPM0, so we are interfacing with GPIO directly for now - update code and remove below warning if/when this changes. -->
1. In **gpio_toggle_output.c**, the infinite main loop at the bottom of **main()** waits for 16,000,000 cycles to toggle the LEDs.
* Declare a new variable, `uint32_t led_on_off_cycles = 10000000`. Place it just below the include statements at the top of **gpio_toggle_output.c**, making this a global variable, so that its value can be more easily modified from any function.
``` cpp
/* GPIO_LEDS_USER_LED_1_PIN, GPIO_LEDS_USER_LED_2_PIN, and GPIO_LEDS_USER_LED_3_PIN on and off cycle delay */
uint32_t led_on_off_cycles = 10000000;
```
2. In the main while loop, look for the call to `delay_cycles` and replace the argument `DELAY` with the `led_on_off_cycles` variable.
``` cpp
while (1) {
/*
* Call togglePins API to flip the current value of LEDs 1-3. This
* API causes the corresponding HW bits to be flipped by the GPIO HW
* without need for additional R-M-W cycles by the processor.
*/
delay_cycles(led_on_off_cycles);
DL_GPIO_togglePins(GPIO_LEDS_PORT,
GPIO_LEDS_USER_LED_1_PIN | GPIO_LEDS_USER_LED_2_PIN |
GPIO_LEDS_USER_LED_3_PIN | GPIO_LEDS_USER_TEST_PIN);
}
```
3. In **main()**, configure and initialize the state of LED4 in the statement where this is already being done for LED1 and LED3.
``` cpp
DL_GPIO_setPins(GPIO_LEDS_PORT, GPIO_LEDS_USER_LED_1_PIN |
GPIO_LEDS_USER_LED_3_PIN |
GPIO_LEDS_USER_LED_4_PIN |
GPIO_LEDS_USER_TEST_PIN);
```
4. In between **main()** and the declaration of `led_on_off_cycles`, define the **GROUP1_IRQHandler** callback function which will be called whenever the left button is pressed. This function will double the switching frequency of the RGB LED (LED1, LED2, LED3) by halving the value of `led_on_off_cycles`. The function will also toggle the state of the red LED (LED4). Recall that the min cycle delay will be 312500, so that limit needs to be guarded. This callback function is defined in **startup_mspm0[variant]_ticlang.c** that is part of the example project.
``` cpp
/*
* ======== GROUP1_IRQHandler ========
* Callback function for the GPIO interrupts on GPIO_BUTTONS.
*/
void GROUP1_IRQHandler(void)
{
switch (DL_Interrupt_getPendingGroup(DL_INTERRUPT_GROUP_1)) {
case GPIO_BUTTONS_INT_IIDX:
if (led_on_off_cycles == 312500) { /* Reset to original frequency when limit reached */
led_on_off_cycles = 10000000;
} else if (led_on_off_cycles >= 625000) { /* Double LED frequency: LED delay currently >= 625000 cycles; can halve */
led_on_off_cycles /= 2;
}
else { /* limit LED cycles to 312500 min */
led_on_off_cycles = 312500;
}
/* Toggle LED4 */
DL_GPIO_togglePins(GPIO_LEDS_PORT, GPIO_LEDS_USER_LED_4_PIN);
break;
}
}
```
5. Double-click **gpio_toggle_output.sysconfig** to open SysConfig and select the `<>` (**Show Generated Files**) icon at the top right of the SysConfig GUI.
Click on **ti_msp_dl_config.c** to preview the file.
You will be able to see the changes you make in the SysConfig GUI reflected in this file in the next few steps.
6. Navigate to the **GPIO** section under the **Software** view, and ensure the **GPIO_LEDS** module is selected. Click the `+ ADD` button under the **Group Pins** section and change the settings to the following:
* **Name** : USER_LED_4
* **Assigned Pin** : 0
Note that the assigned pin corresponds to the red (non-RGB) LED on LP-MSPM0L1306 and LP-MSPM0G3507 boards. If you are using a different board, you may need to check your board's documentation to find the appropriate pin.
You can leave the rest of the settings as they are.
Notice that your changes are automatically updated in the **ti_msp_dl_config.c** file.
7. Still under the **Software** view, select the `+` beside **GPIO** to add a new GPIO module, and change the settings to the following:
* **Name** : GPIO_BUTTONS
8. Under the **Group Pins** section, change the settings for the existing **PIN_0** entry to the following:
* **Name** : USER_BUTTON_1
* **Direction** : Input
* **Assigned Pin** : 18
* **Enable Interrupts** : Checked
* **Trigger Polarity** : Trigger on Falling Edge
Note that the assigned pin corresponds to the left button on LP-MSPM0L1306 and LP-MSPM0G3507 PG1.x boards. If you are using a different board, you may need to check your board's documentation to find the appropriate pin.
You can leave the rest of the settings as they are.
Notice that your changes are automatically updated in the **ti_msp_dl_config.c** file.
9. Finally, add the following code to **main()** in **gpio_toggle_output.c** just before the main while loop to configure the button interrupt.
``` cpp
/* Enable interrupts */
NVIC_EnableIRQ(GPIO_BUTTONS_INT_IRQN);
```
[[+d Your **gpio_toggle_output.c** file should now look something like this. (expand)
``` cpp
/*
* Copyright (c) 2023, Texas Instruments Incorporated
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* * Neither the name of Texas Instruments Incorporated nor the names of
* its contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
#include "ti_msp_dl_config.h"
/* GPIO_LEDS_USER_LED_1_PIN, GPIO_LEDS_USER_LED_2_PIN, and GPIO_LEDS_USER_LED_3_PIN on and off cycle delay */
uint32_t led_on_off_cycles = 10000000;
/* This results in approximately 0.5s of delay assuming 32MHz CPU_CLK */
#define DELAY (16000000)
/*
* ======== GROUP1_IRQHandler ========
* Callback function for the GPIO interrupts on GPIO_BUTTONS.
*/
void GROUP1_IRQHandler(void)
{
switch (DL_Interrupt_getPendingGroup(DL_INTERRUPT_GROUP_1)) {
case GPIO_BUTTONS_INT_IIDX:
if (led_on_off_cycles == 312500) { /* Reset to original frequency when limit reached */
led_on_off_cycles = 10000000;
} else if (led_on_off_cycles >= 625000) { /* Double LED frequency: LED delay currently >= 625000 cycles; can halve */
led_on_off_cycles /= 2;
}
else { /* limit LED cycles to 312500 min */
led_on_off_cycles = 312500;
}
/* Toggle LED4 */
DL_GPIO_togglePins(GPIO_LEDS_PORT, GPIO_LEDS_USER_LED_4_PIN);
break;
}
}
int main(void)
{
/* Power on GPIO, initialize pins as digital outputs */
SYSCFG_DL_init();
/* Default: LED1 and LED3 ON, LED2 OFF */
DL_GPIO_clearPins(GPIO_LEDS_PORT, GPIO_LEDS_USER_LED_2_PIN);
DL_GPIO_setPins(GPIO_LEDS_PORT, GPIO_LEDS_USER_LED_1_PIN |
GPIO_LEDS_USER_LED_3_PIN |
GPIO_LEDS_USER_LED_4_PIN |
GPIO_LEDS_USER_TEST_PIN);
/* Enable interrupts */
NVIC_EnableIRQ(GPIO_BUTTONS_INT_IRQN);
while (1) {
/*
* Call togglePins API to flip the current value of LEDs 1-3. This
* API causes the corresponding HW bits to be flipped by the GPIO HW
* without need for additional R-M-W cycles by the processor.
*/
delay_cycles(led_on_off_cycles);
DL_GPIO_togglePins(GPIO_LEDS_PORT,
GPIO_LEDS_USER_LED_1_PIN | GPIO_LEDS_USER_LED_2_PIN |
GPIO_LEDS_USER_LED_3_PIN | GPIO_LEDS_USER_TEST_PIN);
}
}
```
+]]
Click **Run → Debug Project (...)** and then **Run → Continue** to build the project, start the debugger, and run the program on the target. Test the program by verifying that pressing the left button on the LaunchPad controls the RGB LED blink frequency and toggles the state of LED.
That's it!
[[b Note:
You can find very useful code snippets by browsing through the other example projects in the MSPM0 SDK. There will be simple projects that utilize hardware resources such as the ADC, timers, I2C, SPI, etc.
]]
Lab 2: Basic Debug Concepts
---------------
This lab will cover the basics of debugging, using [the modified **gpio_toggle_output.c** code from Lab 1](#modifying-the-project). Specific tools and concepts that are covered are:
* Breakpoints
* Watchpoints
* Watch
* Debug view
* Disassembly view
* Other Views
### Breakpoints
Breakpoints are specific points that can be set in the code, where the program is to halt execution. Once halted, the values in registers/memory/etc. can be inspected to gain a deeper understanding of the program execution. This is very useful when debugging.
[[y Hardware Breakpoints
A hardware breakpoint is required when setting a breakpoint in Flash. The number of available hardware breakpoint resources varies per device. The MSPM0 supports up to four simultaneous hardware breakpoints.
]]
1. If your MSPM0 LaunchPad is currently running, ensure you are in the **Debug** view and **Pause** it. Otherwise, click on **Run → Debug Project(...)** to flash the program to the target and pause it.
2. Click on the **Breakpoints** panel under the **Debug** view to expand it. There should be no breakpoints to start.
3. While staying in the **Debug** view, in **gpio_toggle_output.c**, scroll to the definition of the **GROUP1_IRQHandler()** function, and click on the margin to the left of the line number. This will insert a breakpoint that will halt program execution whenever it reaches this point in the code.
4. Click **Run → Continue** to resume program execution on the LaunchPad. Click the left button on the board, and note that the program has suspended due to the breakpoint.
5. By clicking **Run → Step Into** or **Run → Step Over** (or using the related buttons in the **Debug** view), the target will do the associated source step. Click **Run → Continue** to resume program execution.
* **Step Into** steps to the next line of code, including stepping into a new function call.
* **Step Over** steps to the next line of code in the current function, but will not step into a new function call. It will remain in the current function until it ends or returns.
* **Step Out** steps out of the current function before it reaches its end, and suspends execution on the next statement of the calling function.
6. After you are finished with this part of the lab, in the **Breakpoints** panel, remove the breakpoint. You can also remove it by clicking the margin next to the line number in **gpio_toggle_output.c**, where the breakpoint currently exists.
### Watchpoints
A watchpoint is a type of hardware breakpoint that monitors activity on a memory address, for example where a variable's value is stored.
1. If your MSPM0 LaunchPad is currently running, ensure you are in the **Debug** view and **Pause** it. Otherwise, click on **Run → Debug Project(...)** to flash the program to the target and pause it.
2. Click **Run → New Breakpoint → Hardware Watchpoint**. This will open a dialog to add a new data breakpoint.
3. Set the **Address** to `&led_on_off_cycles`(the address of `led_on_off_cycles`) and **Access type** to **Write**, and click **OK**. This installs a watchpoint which will pause program execution on the target whenever the value of `led_on_off_cycles` is modified (whenever it is written to).
4. A new breakpoint will be added under the **Breakpoints** panel under the **Debug** view.
5. Click **Run → Continue** to resume program execution on the LaunchPad. Click the left button on the board, and note that the program has paused due to the data breakpoint.
6. Leave the data breakpoint set as it will be used in the next section.
### Watch
The **Watch** view allows you to monitor the values of variables (local, global, static), C-valid expressions and even registers. The value of an expression may also be modified when the situation permits.
1. Ensure that the program is paused. In the **Debug** view, click on the **Watch** panel to expand it. Click on the `+` button and add `led_on_off_cycles` in **Expression to watch**. This will display the value of `led_on_off_cycles` whenever the program is paused. Resume the program and click the left button on the board again to pause the program and view the value of `led_on_off_cycles` change.
2. Click **Run → Continue** to resume program execution on the LaunchPad.
3. Take note of the speed at which the LED lights are blinking. Click **Run → Pause** to pause the execution of the program.
4. In the **Watch** panel, mouse right-click on the `led_on_off_cycles` expression and click **Edit Expression**. Set the value to `50000000` and click **OK**. Click **Run → Continue** to resume program execution. The LED blinking rate should be noticeably slower. This is an example of modifying variable values through the **Watch** panel.
5. In the **Breakpoints** panel, remove the data breakpoint. The press the **Continuous Refresh** button on the toolbar. It is the third button from the left which looks like a continuous circle. This will update the expressions in the view continuously. If the device supports non-intrusive memory accesses (allow the debugger to access memory while the target is running), then the values can be updated while the target is still running. MSPM0 supports non-intrusive memory accesses. Click the left button on the board periodically and note how the `led_on_off_cycles` expression will change as the button is pressed.
6. After you are finished with this part of the lab, in the **Watch** panel, remove the **led_on_off_cycles** expression.
### Debug View ###
In addition to the target execution toolbar and providing information on **Breakpoints**, the **Debug** view also provides more information in the following collapsable views:
* **Threads**: This view will show the current debug session and the status the CPU.
* **Call Stack**: This view will provide the current call stack information for the program.
* **Variables**: This view will display all local variables and related values.
* **Watch**: This view allows you to add/view desired expression. For example, use the `+` button to add the global variable `led_on_off_cycles` to the list of watch expressions.
* **Breakpoints**: This view allows you to view/enable/disable/remove breakpoints.
### Disassembly View
1. If your MSPM0 LaunchPad is currently running, ensure you can see the **Debug** view and that execution is **Paused**. Otherwise, click on **Run → Debug Project (...)** to flash the program to the target and pause it.
2. Click on **View → Disassembly** to open the **Disassembly** view. By default it will show the disassembly of the current location in the code. The location of the Program Counter is indicated with a small yellow arrow(s). Symbols will be highlighted in green text.
3. You can enter in an address or symbol in the location box at the top of the **Disassembly** view to change the address that the view starts at. Enter **main** to display diassembly content starting from the **main** symbol.
4. Note the toolbar with button to **Refresh view**, **Goto current PC location**, **Assembly step-into**, and **Assembly step-over**.
5. To toggle source interleaving, bring up the context menu in the **Disassembly** view and select **Show source** in the context menu. This will interleave the source lines with the disassembly. Source lines will be highlighted in yellow text
### Other Views
Several other views are available under the **View** menu. Experiment with the various views such as:
#### Register View
The **Registers** view is used to display and edit the values of core and memory mapped (peripheral) registers. Click on **View → Register** to open the view.
#### Memory View
The **Memory** view is used to display and edit the values memory. Click on **View → Memory** to open the view.
### Summary
Lab 1 covered using Code Composer Studio Theia to import an example project, modify it, and flash it to a target to run the program. Lab 2 provided information on the basics of using debug tools in Code Composer Studio Theia.
<!-- End of markdown source -->
<div id="footer"></div>
]]>