Overview

It is more and more common to see devices consisting of multiple debuggable cores. This article provides an overview on what features are available in Code Composer Studio (CCS) to assist debugging such devices.

NOTE

The scope of this article is strictly from a tools standpoint of what CCS features are available for multi-core environments.

Launching a Debug Session

There are several options for starting a debug session for a multi-core target:

  • Project-less Debug Session: This will launch a debug session for the target without any project association. The user can then manually choose which core(s) to load a program for
  • Project Debug: Build the project in context and then launch a debug session for the project, connect, and load the application to desired CPUs. CCS will detect which CPUs match the project type and then prompt the user asking which CPUs to debug the project on (connect, load program):

Debug Properties

It is possible to specify different Debug Properties on a per CPU basis. For Project debug sessions, right-click on the project in the Project Explorer view and select Properties to access the Debug properties:

Project-less debug session can use the Debug Configurations to access these options (see below)

Debug Configurations

Modify the Debug Configuration to:

  • Use the Initialization Script field to specify a single JavaScript for target initialization for all CPUs (Main)
  • GEL startup scripts can only be specified on a per CPU basis in the Target Configuration file
  • Specify CPUs to show in the Debug view (Main)
  • Specify if all CPUs share the same console for C I/O (Main)
  • C I/O will be interleaved in the same console (preceded with the CPU name)
  • Uncheck the option to create a separate C I/O console for each CPU (CCSv4 behavior)
  • Specify which CPU loads which programs (Program)
  • Specify different Generic Debugger Options per CPU (Target)
  • Specify different source debug lookup paths per CPU (Source)

Debug Context

The Debug view displays the stack frames for each debug-able core on a multi-core target. Most of the various views in the Debug perspective (Register, Variables, Disassembly, Memory Browser, etc) will reflect the context of the highlighted stack frame for the specified core. To switch the context to another core, simply highlight the stack frame for that other core in the Debug view and the various views will be updated to reflect the context of that core.

Most debugging views, such as the Memory Browser view, allow you to "pin" the view to the context of the currently selected core. This can be done using the Pin to Debug Context icon in the view, as long as this function is supported by the view. Doing this will allow you to change the debug context to another core but still have that view reflect the context of the core it was originally "pinned" to. An example use case would be to open up several instances of the Memory Browser view with each view tied (or "pinned") to a different core to allow side-by-side analysis of the current contents of memory for each core during debug.

Debugger commands (run, step, reset, etc) will apply only to the selected core in the Debug view.

Grouping Cores

Commands can be sent to a specific set of cores at the same time. This can be done by "grouping" the cores of interest in the Debug view.

Temporary Group

This can be done by multi-selecting the cores of interest in the Debug view (CTRL key + left mouse click) to create a Temporary Group of cores. This is useful when you want to send a debug command to only some (but not all) cores. When multiple cores are multi-selected, they will appear highlighted in the Debug view and debug commands will be sent to all the cores that are part of the group. Note that commands are SENT to the cores and it does not guarantee that execution of the commands are carried out simultaneously. It is important to remember this for target execution commands (run, halt, step, etc) where such precise synchronous execution of commands may be desirable. In such cases, a Fixed Group is preferred to ensure synchronous execution of the group (see Fixed Groups section above).

When multiple cores are grouped, the debug context of the various views will always switch to the first core listed in the Debug view with the exception of views pinned to a particular debug context.

NOTE

After sending a debug action to the custom group, the group will be 'unselected'. Hence the group must be reselected to send another debug action to the same group of cores. To avoid this behavior when constantly working with groups, it is recommended to use Fixed Groups instead (see below).

Fixed Group

Once a debug session is started, the user may create a more permanent group This Fixed Group has a specific node in the Debug view that has its own debug context. Selecting this group debug context will cause debug commands to be sent to all group members without the need to select them individually. Note, that while the commands will be sent simultaneously, how synchronously the commands are executed depends on if the HW target itself supports synchronous execution.

In the screenshot below, a Fixed Group will be created for just the first and second CPUs in the Debug view by multi-selecting them and then using the Group core(s) option:

This will cause a new group called Group 1 to appear in the Debug view, with the first two CPUs as members:

Sync Group

For more recent versions of CCS, there is another type of group that can be created - called a Sync Group. This group is similar to a Fixed Group, with the exception that the cores are more tightly grouped - the debugger will treat all member cores of the sync group as one single debug entity. This type of group is commonly required for effective debugging of an Symmetric Multi-Processing (SMP) environment. For more details on SMP Debugging and sync groups, please refer to the article: SMP Debug with Code Composer Studio.

Hiding CPUs

It is possible to filter the list of CPUs visible in the Debug view that will not be used. This helps to avoid clutter in the view to avoid accidentally selecting a debug context of a CPU that is not to be used. To hide CPUs:

  • Multi-select the CPUs to hide, right-click and select Hide core(s) in the context menu
  • Selected CPUs will disappear from the view
  • Unhide all CPUs with Show all cores option

Note that you can set this filter before starting a debug session by specifying which CPUs to display in the Debug Configuration options.

Using Multiple Workbench Windows

Multiple main windows (called Workbench windows) can be created to have each window dedicated to a specified core during the debug session. A new window can be created using the Window → New Window option. A Workbench window has its own debug context (Workbench window 1 can show data for core 1 while Workbench window 2 shows data for core 2, etc). Note that creating a new window does not mean creating a new debug session. Each window will be associated with the same debug session but can be specified, using the Debug view, to reflect the context of a different core.

The debug sessions for all cores are displayed in all Workbench windows by default, but the user can filter the cores shown in each workbench widow (Workbench window 1 can be set to shows only core 1, while Workbench window 2 shows cores 2 and 3.) For more information on filtering cores, see the Fixed Group section above.

Breakpoints

Grouping Breakpoints

The Breakpoints view can display all breakpoints set for all cores and group them by cores. This can be enabled by selecting Group By → Debug Contexts in the options for the Breakpoints view:

This will group breakpoints under their respective cores to easily identify which core a breakpoint if set for:

Global Breakpoints

Each debug context can be configured for Global Breakpoints. This feature will essentially make breakpoints global across all debug contexts that have it enabled. For example, if the debug contexts for CPU 1 & 3 have global breakpoints enabled, and CPU 1 hits a breakpoint, CPU 3 will also be halted (if it was running). And vice versa.

The below screenshot shows an example of enabling global breakpoints for the whole group. This will enable global breakpoints for each CPU in the group:

The next screenshot shows an example of where the first CPU in the group hits a breakpoint (as shown with the Suspended - SW Breakpoint message) and triggers the second CPU in the group to be halted (Suspended - "Cross-triggering).

Known Issue

Global breakpoints are supported only for CPUs that are on the same JTAG scan path (not across multiple debug probes)

Scripting Multiple Cores

Scripting console language may be used to automate repetitious tasks when working with multi-core device. e.g. A script may be written to start a debugger, open debug sessions only for desired cpus and then connect, load program and perform additional steps, such as setting a breakpoint and running to it. Script may also be constructed to create a menu in a GUI that will invoke this script, thus resulting in a single action bring up of a complex multi cpu device. Please see the Scripting Console view topic for further information. This link contains a script example of multi-core device bring up using a script.