Code Composer Studio Theia IDE Version 1.1.0+ for MSPM0 MCUs¶

Table of Contents¶

Read This First
Software Installation
Development Flow
Debugging the Application
Known Issues and Frequently Asked Questions (FAQs)

Read This First¶

How to Use This Guide¶

This guide describes only the setup and basic operation of the software development environment, but it does not fully describe the MSPM0 microcontrollers or the complete development software and hardware systems. For details of these items, see the appropriate TI and CCS documents listed in section Related Documentation From Texas Instruments.

Information About Cautions¶

This guide may contain cautions.

Caution - This is an example of a caution statement. A caution statement describes a situation that could potentially damage your software or equipment.

Read each caution carefully.

If You Need Assistance¶

The E2E Community Support Forums for MSPM0 MCUs are available to provide open interaction with peer engineers, TI engineers, and other experts. Additional device-specific information can be found on the MSPM0 website.

1. Software Installation¶

Code Composer Studio Theia IDE is available from TI.com.

MSPM0 microcontrollers and the MSPM0 SDK require CCS Theia 1.1.0 or higher.

See the MSPM0 SDK documentation for finding the right SDK for your IDE version.

2. Development Flow¶

This chapter describes how to use CCS Theia to run the demonstration programs and develop application software.

2.1 Overview¶

Code Composer Studio (CCS) Theia is an integrated development environment (IDE) that supports TI’s Microcontroller and Embedded Processors portfolio. Code Composer Studio Theia comprises a suite of tools used to develop and debug embedded applications.

This guide only explains some features and capabilities of the Code Composer Studio Theia IDE using MSPM0.

More documentation for CCS Theia is available at TI.com or in the Help menu included in the IDE.

2.2 Creating a New Project using Project Wizard¶

CCS Theia includes a new project wizard which provides an intuitive and easy way to create new project.

Select File → Create New Project
Select the board or device and use filters as needed
Select a project and click on Create

Note that CCS Theia will automatically detect any dependencies, including SDKs and compilers, and it will request installation if needed.

2.3 Using TI Resource Explorer in CCS Theia¶

TI Resource Explorer (TI-Rex) helps you find all the latest examples, libraries, demo applications, datasheets, and more for your chosen platform.

This tool is available at https://dev.ti.com/tirex, but it’s also integrated into CCS Theia allowing for a more integrated user experience.

Select Help → Getting Started. Note that CCS Theia can automatically detect your LaunchPad for easier navigation.
Click on Browse software and examples with Resource Explorer
The navigation panel can be used to view different TI products, documentation, software, etc.
TI Resource Explorer also allows to select a specific SDK version by clicking next to a product and selecting Manage Versions. Note that installed products are also shown with a green check mark.
Use the integrated search to filter by device (i.e. MSPM0L), middleware (i.e. DriverLib), or solution (i.e. LIN).
Selecting an example will show a useful Readme document with a description of the example, peripheral and pin usage and how to run it.
Select a CCS project for the example and click on Import to add it to your workspace.

Note that CCS Theia will automatically detect any dependencies, including SDKs and compilers, and it will request installation if needed.

2.4 Using SysConfig with CCS Theia¶

Some examples in the MSPM0 SDK have SysConfig support. SysConfig is an intuitive and comprehensive collection of graphical utilities for configuring pins, peripherals, radios, subsystems, and other components. SysConfig helps you manage, expose, and resolve conflicts visually so that you have more time to create differentiated applications.

The SysConfig tool is delivered as a standalone installer, it can be used on the cloud at dev.ti.com, or it’s integrated into CCS Theia for better and easier experience.

After importing a MSPM0 project in CCS Theia, simply double-click the .syscfg file and this will open SysConfig.

For more information about using SysConfig with MSPM0, visit the Using SysConfig with MSPM0 guide.

2.5 Migrating Between MSPM0 Derivatives¶

In order to migrate a project configuration to a new MSPM0 derivative (such as a new board, device, or package), the MSPM0 SDK supports several project migration processes. Project migration in this scope means updating relevant project configuration files and settings that are specific to the derivative, including linker files, startup files, and included libraries. The available options for migration depend on the project configuration, and the user should consult the desired project’s README for more information on which approach is supported. An overview of the available migration options and when they can be used are given below: - SysConfig Project Migration: This is the default approach for SysConfig compatible projects, in which all the configuration files can be handled by SysConfig. - Manual Migration: For all other cases that require custom projectspecs or other incompatible configurations, the user can follow these steps for manual migration.

2.5.1 SysConfig Project Migration¶

In order to facilitate project migration, SysConfig will generate Project Configuration files by default, which can be controlled through the Project Configuration module. The steps below apply to TI Arm Clang and Arm GCC.

For more details on generated Project Configuration files, visit the Using SysConfig with MSPM0 Guide.

In SysConfig, enable the Device View and click on SWITCH

Select the New Values for the Device, Package, and CCS Launch Device to migrate the project configuration to, and then click CONFIRM.

After Confirming the new device values, SysConfig will highlight an error on the Project Configuration module. The user must choose the new device in the Select Device options. Make sure the device selection matches what was chosen for CCS Launch Device in the previous step.

Note that SysConfig will highlight any conflicts with the migration, such as unavailable pins and peripherals. Fix any conflicts as needed, and save all the changes to the SysConfig configuration script.

CCS will automatically migrate the device variant and will add a corresponding .ccxml file. SysConfig will update the relevant project configuration files, including linker and startup files.

Migration is now complete and the user can build their project for the new target device.

Note: If the user wants to manually modify any Project Configuration files, they should disable the option to generate that file from the Project Configuration module and then manually add their desired file to the project. Otherwise, changes that are made to any generated file will be overwritten by SysConfig when the project is built. Keep in mind that the steps above are intended to be followed when all the project configuration files are handled by SysConfig.

2.5.2 Manual Migration¶

SysConfig allows for an easier migration between MSPM0 derivatives; however for some projects manual modifications are required. The steps below apply to TI Arm Clang but similar steps apply to Arm GCC.

Note: Steps 1-3 don’t apply when not using SysConfig, and step 4 needs to be done manually.

In SysConfig, enable the Device View and click on SWITCH

Select the corresponding options for the new MSPM0 device and click CONFIRM.

Note that SysConfig will highlight any conflicts with the migration, such as unavailable pins and peripherals. Fix any conflicts as needed.
CCS Theia will automatically migrate the device variant and will add a corresponding .ccxml file.

In the project properties, select Build → Arm Compiler → Predefined Symbols. Select the device definition and update it.

Update the linker and startup files. The MSPM0 SDK includes default files for all MSPM0 derivatives at <sdk>\source\ti\devices\msp\m0p\linker_files\ticlang and <sdk>\source\ti\devices\msp\m0p\startup_system_files\ticlang respectively.

Note that previous files should be excluded or removed from the project.

Resolve any other dependencies such as incompatible libraries and source code.

2.6 Stack and Heap Management and Linker Files¶

The reserved stack and heap size can be configured using project settings or in the linker files.

2.6.1 Configure Stack and Heap using TI Arm Clang compiler¶

Right-click on a project and select Properties. Select Build Tools → Arm Linker → Basic Options and set the stack and heap accordingly.

The stack and heap can also be modified directly on the linker .cmd file by adding or editing --stack_size=xx or --heap_size=xx.

2.6.2 Configure Stack and Heap using Arm GCC¶

The stack can be modified directly on the linker .lds file by adding or editing _Min_Heap_Size = xx or _Min_Stack_Size = xx.

2.7 How to Generate TI .TXT (and Other Format) Files¶

CCS includes utilities which can be used to generate output objects in multiple formats for use with programming tools such as MSP-GANG and UniFlash.

2.7.1 Using Arm Hex Utility¶

The following steps explain how to enable the TI TXT format using the Hex Utility which is integrated into CCS.

Right-click on a project and select Properties. Select Build Tools → Arm Hex Utility → Output Format Options. Then select the TI-TXT hex (–ti_txt) option.

This same process can be used to generate other formats; however, some formats might require other parameters.

A common one is Intel HEX format which in addition to selecting the output format Intel hex (–intel, -i), requires to specify the memory and ROM width as parameters.

When using Intel HEX for MSPM0, select a memory and ROM width of 8 in Build Tools → Arm Hex Utility → General Options.

For more information, visit Hex utility in CCS.

2.7.2 Using Objcopy Utility¶

CCS includes the Arm Objcopy Utility which is a LLVM-based tool that can be used to generate binaries in multiple formats.

The following steps explain how to enable intel Hex format using ObjCopy.

Right-click on a project and select Properties. Select Build → Arm ObjCopy Utility and select Enable Arm Objcopy Utility.

Specify the output file name using .hex extension.

Specify the ihex output format.

For more information about Objcopy, visit this Objcopy guide.

2.8 Overriding Pre-built Libraries¶

Projects might include pre-built libraries which simplify development and build time; however, they don’t allow developers to modify source code easily.

An example of such libraries is the MSPM0 DriverLib which is shown below.

One option to override the library is to simply add any or all source files to the project. The MSPM0 SDK includes the empty_driverlib_src example which includes all DriverLib source by default:

2.9 Running from SRAM¶

The examples included in the MSPM0-SDK will commonly have linker files which create applications which are intended to run from internal Flash and will execute after reset or power cycling the device. However, in some scenarios, it can be useful to download and execute code from SRAM.

This section describes step-by-step instructions to execute some functions or complete applications from SRAM.

2.9.1 Running a complete application from SRAM¶

The following steps show how to modify a basic gpio_toggle_output example for the LP_MSPM0L1306 to run from SRAM. Similar steps apply to other examples and devices.

Open the linker .cmd file and modify it to use SRAM as shown below:

Disable the System Reset which is executed by default in CCS.

CCS includes .gel files which execute certain functions on the device. These files are included inside the CCS installation folder at <ccs>\ccs_base\emulation\gel>. The screenshot below shows the modification necessary for MSPM0L1306:

Download code and note that the device will execute from SRAM.

2.9.2 Running a function from SRAM¶

The following steps show how to declare a function which is executed from SRAM.

Move the function to the .TI.ramfunc section. This can be accomplished by declaring the function with the attributes __attribute__((section(".TI.ramfunc"))) __attribute__((noinline)) as observed below:

The linker file should include a placement of .TI.ramfunc. Note that the linker files included in MSPM0-SDK already include this placement but it will only be applicable if any functions are placed in .TI.ramfunc.

Download code and note that the device will execute the function from SRAM.

3. Debugging the Application¶

The following debug probes have been tested successfully with Code Composer Studio Theia IDE.

TI XDS Tools, including the XDS-110 integrated into MSPM0 LaunchPads.

3.1 Using TI XDS Tools¶

TI offers a range of debug probes for Arm-based devices, including the XDS-110 which is integrated with MSPM0 LaunchPads.

To use the TI-XDS debug probes, open the project options, click on General → Connection and select Texas Instruments XDS110 USB Debug Probe.

3.1.1 Flash Loader¶

The Flash Loader settings allow to configure some settings when programming and erasing the device.

To view and modify these settings, open the project properties and select Debug → Category:MSPM0 Flash Settings.

The Flash Loader has the following options:

Reset Configuration: allows to perform soft or hard reset before and after programming.
Program Configuration: enables/disables CRC verification while programming. Note that CRC validation of NONMAIN is performed when programming/erasing NONMAIN regardless of this setting.
Erase Configuration: configures the behavior when erasing memory. The options are:
- Erase MAIN memory only: Only MAIN memory will be mass erased. An error will be thrown when attempting to write NONMAIN.
- Erase MAIN and NONMAIN memory: Both MAIN and NONMAIN will be mass erased. See Erasing and Updating NONMAIN Memory for information about NONMAIN usage.
- Erase MAIN and NONMAIN necessary sectors only: Only sectors being updated will be erased, including both MAIN and NONMAIN. Check the device datasheet for information on the size of flash sectors. See Erasing and Updating NONMAIN Memory for information about NONMAIN usage.
- Erase MAIN memory sectors by range: Only sectors defined between Sector Erase Start Address and Sector Erase End Address will be erased. Check the device datasheet for information on the size of flash sectors and note that the addresses are inclusive. For example, a region from 0x0000_0100 to 0x0000_0400 on a MSPM0 device with 1kB sectors will erase sectors 0x0000_0000-0x0000_03FF and 0x0000_0400-0x0000_07FF. Note that only sectors in MAIN will be erased. An error will be thrown when attempting to write NONMAIN.
- Do not erase Flash memory: Flash will not be erased. An error will be thrown when attempting to write NONMAIN without erasing.
Advanced Configuration: disables validating the device ID. Used for debugging purposes and not recommended to disable.
Enable Verbose Output: enables showing debug information while running the flash loader.

3.1.2 Erasing and Updating NONMAIN Memory¶

Caution: Extreme care should be taken when erasing and programming NONMAIN. If done incorrectly, the device will become locked in a permanently unrecoverable state.

NONMAIN is a dedicated region of flash memory which stores configuration data which define the behavior of the device after booting. NONMAIN should not be used for any other purpose. See the device Technical Reference Manual for more information.

TI recommends using the NONMAIN configurator available in SysConfig when configuring NONMAIN. See Using SysConfig with MSPM0 for more information.

As described in the Flash Loader section, NONMAIN is erased by selecting Erase main and NON-MAIN memory or Erase MAIN and NONMAIN necessary sectors only in the erase configuration.

Note that the Flash Loader will erase NONMAIN if any of these options are enabled; however, it will run a CRC after the programming sequence is completed, and it will attempt to restore default values if NONMAIN is corrupted.

3.2 Breakpoint Types¶

The CCS Theia debugger uses a limited number of on-chip debugging resources (specifically 4 hardware breakpoints and 2 hardware watchpoints). Software breakpoints in Flash are not supported on MSPM0. This means that a maximum of 4 hardware breakpoints can be set within CCS Theia.

CCS Theia can use a breakpoint to stop at main or halt the device at exit. These settings can be updated in the project properties by selecting Debug → Category:Program/Memory Load Options.

If the max number of breakpoints are set, the following warning will be displayed.

3.3 Connecting to an Incorrect Device¶

CCS Theia will show an error if an unsupported device is connected as shown below:

Programming an incorrect device is not recommended and can lead to unexpected and unrecoverable behavior.

3.4 DSSM Commands¶

MSPM0 allows communication to the device over SWD from a debug probe using the Debug Subsystem Mailbox (DSSM). These commands are not available in SWD security level 2, but they are optionally available in security level 0 and 1. See the device Technical Reference Manual for more information about security policies and DSSM.

The MSPM0 CCS support package includes GEL files not only to perform device initialization, but to send DSSM commands which are explained in the following sections.

For more information about GEL commands in CCS, visit the CCS online documentation.

3.4.1 DSSM Mass Erase and Factory Reset¶

DSSM Mass Erase: A DSSM mass erase is an erase of the MAIN flash regions only, which typically includes the user application. NONMAIN flash region are not affected by a mass erase. A mass erase is useful for erasing all application code and data while leaving the device configuration itself intact.
DSSM Factory Reset: A DSSM factory reset is an erase of the MAIN flash regions followed by a reset of the NONMAIN flash region to default values. Such an erase is useful for completely resetting the NONMAIN boot policies while also erasing the application code and data.

The SWD mass erase and factory reset DSSM commands superseded any static write protection policies. For example, if SWD factory reset is configured to be enabled or enabled with password, the NONMAIN configuration data can be reset even if it is statically write protected.

To execute a DSSM Mass Erase or DSSM Factory Reset, follow the next steps:

Go to an active project and open the targetConfigs folder.
Right-click the .ccxml file and select Start Project-less Debug.
On the debugger window menu, select Scripts → MSPM0xxxx_Commands (where MSPM0xxxx depends on the current MSPM0 device), and select one of the following options:
- MSPM0_MailboxMassErase_Manual: A mass erase will be performed asking the user to press the reset button.
- MSPM0_MailboxMassErase_Auto: A mass erase will be performed forcing reset using the XDS110 reset line.
- MSPM0_MailboxFactoryReset_Manual: A factory reset will be performed asking the user to press the reset button.
- MSPM0_MailboxFactoryReset_Auto: A factory reset will be performed forcing reset using the XDS110 reset line.

3.4.1.1 DSSM after Power-up¶

The device might not respond to DSSM commands in some scenarios such as when the reset line or SWD pins are used for other functions. In such conditions, it can be useful to follow the next steps:

Power off the device
Hold the reset line (NRST) low
Power up the device, while holding NRST low
Execute one of the Manual DSSM commands mentioned in previous section
When prompted, release NRST

3.4.2 DSSM SWD Password Mechanism¶

The SWD interface can be configured to be disabled, enabled, or enabled with a 128-bit password by writing the BOOTCFG0 and SWDPW registers in NONMAIN. See the device Technical Reference Manual for more information about NONMAIN and SWD password.