Multi-Core Debug with CCS

Overview

CCS supports debugging of multi-cores targets.

NOTE: This article applies to CCS versions 5.x and greater. For information on multi-core debugging with CCSv4.x, see: Multi-Core_Debug_with_CCSv4.x

Starting 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 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):

Fig. 1: Launching a Debug Session

Debug Properties

It is possible to specify different properties ('Generic Debugger Options') on a per CPU basis. For 'Project' debug sessions, right-click on the project in the ‘Project Explorer’ and select ‘Properties’ to access Debug properties:

Fig. 2: 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)

Note: an automated way of launching the debug and loading code to multiple cores is shown at the short clip Multicore Debug Launch made easy at the [Video Tutorials CCSv5] page.

Fig. 3: Debug Configurations

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, 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.

Fig. 4: Debug View

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' 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.

Fig. 5: Pinning the Memory View to the Current Debug Context

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).

Fig. 6: Multi-selecting Cores

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 Groups

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:

Fig. 7: Creating a 'Fixed Group' via 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:

Fig. 8: 'Fixed Group - Group 1'

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. This is similar to the CCStudio 3.3 multi-core debug environment where a CCStudio control window can be opened for each core.

Fig. 10: Multiple Workbench Windows

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:

Fig. 11: 'Breakpoints' View Grouping Options

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

Fig. 12: 'Breakpoints' View Groups

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:

Fig. 13: Enabling 'Global Breakpoints'

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").

Fig. 14: 'Global Breakpoints' - Cross-triggering Example

Known Issues

• Global breakpoints are supported only for CPUs that are on the same JTAG scan path (not across multiple emulators)
• C66x based devices: The DRM needs to be configured to output the proper signals to enable global breakpoints across different devices on the same JTAG scan path (ex: 2 separate C6670 devices on the same JTAG scan path). This can be done with this GEL file.

Load the GEL file and then before enabling global breakpoint, do the following actions:

1. Launch target configuration for TCI 66x.
2. Right click Debug pane and select menu item "Show all cores"
3. Expand Non Debuggable Device node
4. Connect CS_DAP_DebugSS node
5. Load the GEL file for CS_DAP_DebugSS
6. Run DRM_setDP0ForGlobalBreakpoint function

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 Scripting Console topic for further information. This link contains a script example of multi-core device bring up using a script.