7.1. Debug Overview

This section provides a summary of the CCS debug system and the debug process for a typical embedded software program.

Embedded software debugging is the process of evaluating the behaviour of an application that is placed in its target environment and subjected to different boundary conditions. The debugger and its supporting hardware elements assist in providing tight control over the execution and complete visibility over the internal aspects of the target environment, so it allows to detect errors or modify behaviours of the application.

In the CCS environment, the debug is the next step after the project build which, after a successful assemble/compile/link process, allows the application executable file to be loaded to the target environment for debugging.

Note

For a detailed description about projects, check the chapter Projects and Build Management in the References section.

Debugging can also happen in a system that has code already loaded and running, typically on advanced stages of the product design or with a finished product. These two methods are fundamentally identical with only procedural differences that can be seen in the section Launching a debug session.

CCS can also debug an OS-hosted executable, which requires a high level operating system running on the target device/board (embedded Linux is the most common). However, the process of creating a project, building and debugging is outside the scope of this document but references can be found in the section Linux Debug References

7.1.1. The basic elements

_images/ccs_debug-process.png

The physical debugging setup is shown above with the two main components involved during a debug session: 1. The connection is the piece of hardware between the host PC that runs CCS and the device or board where the code is supposed to be executed. Throughout this document the connection will also be called the Debug Probe. 2. The Board or Device is the hardware that contains one or more devices required for the executable to run. Throughout this document it will be called the target.

This setup, when used with CCS, allows the host PC to communicate with the target, load data and code, control the execution of the program loaded via breakpoints, watchpoints and step operations, as well as read data back to the host PC to be displayed in views such as Watch, Memory and Disassembly.

To properly make CCS aware of the physical aspects of the debugging environment, a Target Configuration File must be created. This file is populated with the appropriate Debug Probe type (XDS, ICDI or MSP-FET) and host interface (USB or Ethernet). This file also contains the exact specification of the Device or Board being used.

Once the Target Configuration File is created and all the appropriate hardware is connected and powered up, the debugger is ready to be launched.

7.1.2. The launching process

_images/ccs_debug-files.png

The elements of the debug subsystem are shown above and are processed in the following manner:

  1. At launch, CCS switches the active perspective to the CCS Debug perspective with many views that are useful for the debugging process.
  2. CCS then parses the Target Configuration File, creates a Debug Configuration and uses the information in these two files to connect to the JTAG debugger and communicate to the device in the target.
  3. Once this communication is established, the CCS debugger starts executing a series of hardware initialization commands from a GEL script (if one is configured in the Target Configuration File.
  4. If loading an executable, the CCS debugger splits the information of the executable file: - The contents of both code and data sections are sent through JTAG and stored in the appropriate memory locations of the device/board. The placement of this code follows the directives on the Linker Command File. - The debug symbols are kept in the host PC to allow correlating the memory addresses of the device/board with the source code of the project. - The process is the same whether the code is being downloaded to RAM or Flash. For Flash based devices, the built-in flash programmer automatically handles the flashing process. 5. The CCS debugger performs one last step: it automatically sets a breakpoint in the device memory address that corresponds to the function main() and runs the device until it breaks at it.

Note

These last two steps are optional and depend on the settings present inside the Debug Configuration.

Once the launch process is finished, the debugger is ready and not only keeps the target on hold, waiting for user control, but also opens many views that help the debugging process.

  • The interaction can be done by issuing commands such as Run, Halt, Step Into, Step Over, set breakpoints and watchpoints, among others
  • The inspection can be done by opening the various views such as Disassembly, Memory Browser, Watch, Expressions, among others

The iterative process of debugging and modifying the application can be done by simply rebuilding the project and reloading the code to the target.

7.2. Configuring the debugger

This section covers in detail the two elements responsible for the debugger configuration in CCS: Target Configuration Files and the Debug Configurations.

7.2.1. Target Configuration Files

As mentioned in the Debug Overview section, Target Configuration Files are responsible to describe the physical aspects of the debugging environment.

The Target Configuration File is a plain text XML file that has a .ccxml extension and contains all the necessary information for a debug session: the type of Debug Probe, the target board or device (or even multiple devices) and optionally contains a path to a GEL (General Extension Language) script, which is responsible for performing device and/or hardware initialization.

_images/ccs_debug-target_config_file.png

As shown above, the Target Configuration File includes one or more connection XML files (one per each core and JTAG entity, but all of them tied to the chosen Debug Probe) and either a Board XML file (which contains a Device XML file plus the GEL script for the board) or a Device XML file directly (which may or may not contain a GEL script). The Device XML file contains the internal JTAG structure of the device and can optionally include several Module XML files, which describe a device’s peripheral registers.

Despite the complexity, there are two simple ways to create the Target Configuration File: either automatically or manually.

7.2.1.1. Automatic method

This method automatically creates a Target Configuration File when creating a project or modifying its properties.

To create it, simply find out which Debug Probe model (XDS, ICDI, MSP-FET) and interface (USB, Ethernet) is used by your hardware and set this parameter in the drop-down menu Connection in the New Project Wizard or in the Project settings.

  • Common selections for the Connection can be found at the page Common Target Configurations. Simply search for the part number of your development board and find out the appropriate setting.

New project:

_images/ccs_debug-new_proj_connection.png

Existing project:

_images/ccs_debug-existing_proj_connection.png
  • The file is placed in a subdirectory named targetConfigs inside the project directory
  • This method is very simple as it automatically assigns the correct device and set it as the Active target configuration for the project
  • Also, several example projects already create this file automatically.
  • The Verify button performs a test routine to validate the configuration chosen, similarly to what is shown in the section Test Connection below.

7.2.1.2. Manual method

This method creates a Target Configuration File by manually invoking the Target Configuration Editor.

The Target Configuration Editor is a GUI inside Code Composer Studio that allows creating and modifying Target Configuration Files. It also allows configuring advanced aspects of the Debug Probe and the target, as well as creating configurations for complex devices (with multiple cores) and boards (with multiple devices in the same scan chain).

_images/ccs_debug-target_config_editor.png
  • The file can be placed in an arbitrary directory in the system. By default it is the subdirectory ti/CCSTargetConfigurations inside the user area. The location may be changed from CCS menu Window → Preferences → Code Composer Studio → Debug.
  • This method allows creating configurations for more complex devices or boards, as shown at the Custom Target Cnfigurations page.
  • The Target configuration editor can also be used to edit the file that is automatically created with the previous method.

To create the Target Configuration File manually, simply launch the Target Configuration Editor from one of the several places inside CCS:

  • Menu File → New → Target Configuration File.
  • From the Target configurations view (menu View → Target Configurations), click on the new target configuration button newtargetconfigimage
  • From the project itself by right-clicking on the project and selecting New → Target Configuration File.

7.2.1.3. Test Connection

Once the Target Configuration File is created and saved, you can use the Test Connection button to verify that the JTAG connection is working at the lowest level. This button will execute various low level JTAG tests on the configured device.

If the button is grayed out, it means that either the Target Configuration File has not been saved or the connection type being used is not supported (such as non XDS based connections such as MSP-FET430UIF or Jlink).

  • For the MSP-FET430UIF, an alternative to the Test Connection button is the Identify… button which is next to the connection under the CCS Project Properties → CCS General → Main.

To see a video demo on how to test the connection, check the How to test your JTAG connection with CCS in the References section.

7.2.1.4. Advanced target configuration options

The procedure above mostly covers the Basic tab of the Target Configuration editor, but other two tabs are also important:

The Advanced tab allows configuring important parameters of the Debug Probe (mode of operation, clock speed, special signaling, endianess, among others), the device’s internal JTAG structures (addresses, ports, cores) and the addition/removal of GEL files. - One of the most common Debug Probe settings is the clock speed. This is covered in detail in the quicktip videos Experimenting with JTAG clock speed and Experimenting with XDS110 JTAG clock speed in the References section. - GEL files are automatically added to all board configurations and several devices, therefore only need to be added/modified if a specific demand is required. If such editing is required, check the section Adding GEL Files to a Target Configuration. - Another important setting is the JTAG Mode of operation (JTAG, cJTAG, etc.) of all XDS Debug Probes except XDS100v1 and XDS100v2. Additional details can be found at the section Debug and trace usage modes of the XDS110 and XDS200 pages. - This tab also allows to manually specify a Board Data File. Although unusual, this setting is important under certain circumstances.

The Source tab shows the XML code of the Target Configuration File with all references to the XML files mentioned at the start of this section.

Note

Check the section Advanced Debug Probe configurations for a complete list of advanced configurations of each debug probe.

7.2.1.5. Launch context

Target Configuration files can be tagged as Active or Default. This tagging affects which configuration the Debug Launch button greenbugimage will use. The Debug launch button will search for and use a Target Configuration File in the order below:

  • Use the file that is part of the project (physically or linked) - specified as Active
  • Use the file that is set as the Default in the Target Configurations view.

One exception is if you have a Target Configuration File opened in the editor and in focus. In this case, the Debug Launch button uses it instead of the Default or Active Target Configuration File.

  • Active configuration is assigned per project
  • Default configuration is set per workspace

7.2.1.6. Target Configuration view

The Target Configuration view will display all target configuration files associated to the workspace. Target configurations can be easily managed from this view, including renaming/opening/deleting configurations, setting a configuration as the Default, linking a configuration to an existing project, and so on.

_images/ccs_debug-target_config_view.png

The top toolbar contains the following buttons:

_images/ccs_debug-target_config_view_toolbar.png
  • Create a new target configuration file.
  • Delete the selected target configuration file.
  • Refresh the target configuration view.
  • Collapse the tree.
  • Minimize/maximize the view.

The right-click context menu contains the following options:

_images/ccs_debug-target_config_view_context.png

Most of the options are self-explainable apart from three of them:

  • Set as Default. It sets the highlighted target configuration file as the Default configuration of the workspace, as mentioned in the section Launch context.
  • Link File to Project. This sets the highlighted target configuration as the Active configuration of the selected project, overriding any Default configurations when the project is in focus.
  • Properties. This is a shortcut to open the various Debug Properties of the Debug Configurations view.

Note

Video demo: The short video How to use the CCS Target Configuration view demonstrates the features listed above.

Tip

Information about the settings required to configure the Launchpads and other development kits can be found at the Common target configurations page

7.2.2. Debug Configurations

A Debug Configuration (sometimes also called Launch Configuration) is the way that standard Eclipse (and by extension, CCS) describes how to launch a program in Debug mode. Eclipse FAQ about Launch configurations: What is a launch configuration?

Debug Configurations are unique for each workspace. A Debug configuration can be manually created by going to menu Run → Debug Configurations, or it is automatically created when the debugger is launched. Debug configurations may be cached and reused for future sessions that use the same configuration.

The name and physical location of the debug configuration is determined by how the debugger is launched.

  • If the debugger is launched automatically on a project (using the Debug Launch button greenbugimage), the Debug Configuraton has the same name as the project. Physically the files are located in the project subdirectory /.launches
  • If the debugger is launched manually, the Debug configuration has the same name as the Target Configuration File. Physically the files are located in the workspace subdirectory .metadata/.plugins/org.eclipse.debug.core/.launches

Note

One of the advantages of directly editing the Debug Configuration is to automate tasks when loading code to complex devices that have multiple cores. The short video Multicore debugging made easy shows this process.

You can also create and assign a different debug configuration for each build configuration of your project. The short video Customizing debug launch for different build configurations shows the process.

The Debug Configuration contains various settings separated by the following tabs:

_images/ccs_debug-debug-config-tabs.png

Main: configures the main options for the debugger.

  • Target Configuration: points to the Target Configuration File
  • Initialization Script: (optional) points to a JavaScript that can be used to initialize the target, pass parameters, etc. This is useful if you wish to run a custom set of steps during debug launch. Check the short video Customize Debugger Launch with Scripts for more information on using an initialization script.
  • JTAG entity checkboxes: allows selecting what JTAG elements (cores/CPUs, routers, DAPs, etc.) are shown in the Debug view of the debugger. By default only CPUs are selected.
  • Synchronize the properties for all compatible CPUs and Use the same console for the CIO of all CPUs: These two options are applicable to targets with multiple cores. For example, if you wish to display console CIO of the different cores in different views, then uncheck the CIO check box.
  • Reset Debug Probe Connection S/N: (XDS110 only) resets the serial number parameter pre-configured in the Target Configuration File. This is useful in case different Debug Probes are being constantly changing.

Program: configures the main options for program loading.

  • Device: a drop down selection of each of the JTAG elements (cores/CPUs, routers, DAPs, etc.), which affects the selections in all the options below
  • Project and Program: used to select either the project in the current workspace or the executable file to be loaded to the JTAG element selected above.
  • Loading options: affects how the executable selected previously will be loaded: either by transferring its data to the target and the symbols to the debugger or simply loading the latter.

Target: all the options in this tab are described in the section Debug Properties.

Source and Common: all the options in this tab match the standard Eclipse options which are described in the online Eclipse help at Using Run/Debug Configurations

7.2.2.1. Portable Debug configurations

Sometimes it is desirable to share project debug/launch configurations along with the project. In such cases, it is recommended to avoid absolute paths to help with “portability”. While relative paths are not supported in debug/launch configurations, it is possible to avoid absolute paths with the use of some default variables to reference files related to the project. For details, check the topic below: Portable target and debug configurations

7.2.3. Debug Properties

There are many settings that define the debug properties, such as Program/Memory Load Options, Auto run options and Flash settings, to name a few. This section describes the more commonly used debug settings.

These settings can be viewed and customized through:

  • Project Properties → Debug (if target configuration file is part of the project) or
  • Right-click on the target configuration file in Target Configurations view and select Properties.

Note that if you are using the first option above, you need to have already specified a Connection in your Project Properties in order for the Debug Properties to be populated. If you do not explicitly have a Connection specified, it may use the Default target configuration file and show the Properties based on that which may be incorrect/not match up with your device, so make sure you have the correct Connection selected for your project.

Note

For multi-core devices, make sure the Device drop-down shows the relevant core, for example as shown below for IDK AM65x:

_images/multi_core_device.png

These settings can also be accessed, when already in a debug session (and in the CCS Debug perspective), either by going to:

  • menu Run → Debug Configurations, and going to the Target tab or
  • menu Tools → Debugger options and/or Tools → On-Chip Flash

The Debug properties are displayed under several categories. Each category allows you to control certain settings related to that category. Most users will not need to modify the default settings. The default settings are optimally chosen based on the processor being debugged, hence they may vary slightly by processor. For example, the default settings for MSP430 may be different than those for F28x.

7.2.4. Program/Memory Load Options

This category defines settings related to program/memory loading, verification options, connection options, disabling interrupts and resetting/restarting target during load.

_images/program_load_options.png

Program/Memory Load Options:

  • Disable all breakpoints when loading a different program: as the name says, when loading a different .out file in the same debug session, selects between maintaining the status of breakpoints previously set or disable them. This option is enabled by default.
  • Halt at program exit for TI compilers (requires a breakpoint): when enabled, sets a breakpoint at end of program to allow debugger to halt there. This is only functional when using a TI compiler, which has the predefined symbol C$$EXIT or C$$EXITE.
  • Enable CIO function use (requires setting a breakpoint): (TI Compiler) when enabled, allows having Console I/O output in the Console view.
  • Enable Semihosting (requires setting a breakpoint at SVC_Handler): (GCC Compiler) when enabled, allows having Console I/O output in the Console view This is available only for certain devices (Cortex A/M). See the CCS Semihosting page for more information.

Verification Options: after the code/data is loaded to the device, sets the level of verification performed on it. This is done by reading back the code/data from the device’s memory and comparing it to the executable in the host. The choices are:

  • Full: reads back the entire program loaded to the device. This is the default option for MSP430.
  • Fast: reads back only the first and last 20 words loaded to the device. This is the default option for all other devices.
  • No verification: no verification is performed.

Connection Options: These settings control actions performed immediately after the Debug Probe connects to the target device. The choices are:

  • Halt the target on a connect: halts the core execution. It is set by default in all devices.
  • Reset the target on a connect: issues a soft reset on the device.
  • Auto connect if a child connects: enables a proper connection to the cores in complex SoC devices and should be used only on specific cases.

Disable interrupts: These settings control whether to disable or enable interrupts when stepping and/or running code. The options are self-explainable.

Reset the target on a program load or restart: issues a soft reset on the target device when a program is loaded or restarted.

Restart the target on a symbol load as well as program load: issues a restart when either symbols or a program is loaded to the target device. A Restart simply re-positions the PC register to the entry point (typically _c_int00 or the reset vector).

7.2.5. Auto Run and Launch Options

This category defines Realtime Options, Auto Run Options and Launch options.

_images/auto_run_options.png

Realtime Options: these options control real-time access to the target device.

  • Halt the debugger before any debugger access: enables transparent access from the Debugger to the target device and its memory by performing an automatic sequence of Halt ► Access ► Resume. This option has the potential to disrupt the service of time critical interrupts, therefore it is disabled by default.
  • Enable realtime mode: enables complete memory and control access to the target without the need to halt it. Additional details are shown in the section Real-time mode.
  • Enable polite mode: enables the polite real-time mode, which respects the current device status. Additional details are shown in the section Real-time mode.

Auto Run Options: these options control which condition will cause the debugger to automatically run and halt at the pre-defined symbol. By default, this is set to run to main() On a program load or restart.

  • This symbol can be set to any other C or assembly symbol desired.
  • If leaving the symbol field empty and disabling all the checkboxes, the debugger will be halted at the code entry point (typically _c_int00 or the reset vector) when the executable is loaded.
  • If leaving the symbol field empty but leaving at least one of the checkboxes enabled, the debugger will run freely immediately after the code is loaded.

Launch Options: These options control the actions taken automatically when the debugger is launched.

  • Connect to the target on debugger startup: when performing a Manual launch, skips the connect step. This option shouldn’t be enabled with SoCs, given that most cores are held in reset during the debugger startup.
  • Restore breakpoints from previous session: restores all breakpoints and their status from a previous debug session. This option is very useful to reduce the setup time when performing sequential debugging sessions on the same target device and hardware.
  • Continue debug launch if target connection or program load fails: as the option shows, in case of errors the debug launch process will continue normally. The sources of errors are commonly caused by a project that fails to build or connection problems between the host and the target device.

7.2.6. Misc/Other Options

This category defines OS Aware debug options (when doing OS Aware debugging) and other miscellaneous options.

_images/misc_other_options.png

OS Aware Debug Options: these options control the Debugger awareness level when used with a High Level Operating System, such as embedded Linux or Android.

  • The proper use of this option requires a device driver built into Linux to properly correlate the source code.

Automatically step over functions without debug information when source stepping: enables a Step Over operation if the function does not have symbols and source code loaded into the debugger. If disabled, the debugger performs an Assembly Step Into these functions.

Allow power transitions while running if supported (low power running): maintains the JTAG Debug Probe connection when the target device goes through a power transition or reset. This is heavily dependent on the device and board capabilities.

Add timestamp information to target output: adds timestamps to operations in the target that print out information in the Console view (GEL, Console I/O, etc.)

Allow software breakpoints to be used: enables the use of Advanced Event Triggering (AET) resources to enable software breakpoints to be used when allowed by the target device. This is advantageous given that hardware breakpoints are limited in number by the target device, while software breakpoints are completely unlimited.

Default directory for file IO: sets the default directory to be the target of any File I/O operations.

When added to a sync group: these options control the level of interaction when synchronized execution (Sync Group) is enabled. This is dependent on the target device and is effective with Symmetrical Multi Processing (SMP). Check the document SMP Debug with CCS in the section References.

7.2.7. Disassembly Style Options

7.2.7.1. ARM

This category is only applicable for ARM7, ARM9, Cortex R/A devices and sets the mode in which instructions are displayed in the Disassembly view.

Cortex R4, R5, A8, A9 and A15:

_images/cortexr_dis_options.png

Cortex A53:

_images/cortexa53_dis_options.png

The default is Mixed ARM/Thumb or Mixed A32/A64 and automatically selects the mode depending on the core mode (the CPSR/xPSR register).

7.2.7.2. F28x

This category is only applicable for F28x devices and sets the mode for the Disassembly view.

_images/f28x_dis_options.png

The default options are shown above.

7.2.8. Flash Settings

This category defines several flash memory related settings and operations, that are described in more detail in the section Configuring Flash Settings.

7.2.9. MSP430 Debugger Options

This category is only applicable for MSP430 and sets several debugger options:

_images/msp430_properties.png

Disable breakpoints on a free run: disables all breakpoints when the Free Run option is used. For certain devices, Free Run is a less obtrusive mode of running the device through power transitions and low-power modes.

Default breakpoint type: sets which default breakpoint will be used. Hardware breakpoints are mandatory for code located in Flash or ROM, thus this is the default option for this device.

Connection Options: these options set the actions performed by the debugger during connection.

Low Power Mode Settings: maintains the JTAG Debug Probe connection when the target device goes through a ULP mode.

Clock Control: allows full control over the clocks that are stopped upon emulation halt. The debugger must be connected to the target device to get a list of available clocks.

Additional details can be seen at the document CCS IDE v8.x for MSP430 MCUs

7.3. Launching a debug session

Once a configuration is created the debugging process can be launched either automatically (Automatic Launch) or manually (Manual Launch):

7.3.1. Automatic launch

This process launches a Project-based debug session. Simply highlight the project in the Project Explorer view and do one of the following options:

  • Go to menu Run → Debug (or the F11 key).
  • Click on the Debug Launch button greenbugimage

Note

If a project has multiple target configuration files, the Active configuration of the project will be launched.

This will perform the sequence of steps shown in the section The launching process. In summary:

  1. Switch to the CCS Debug perspective.
  2. Connect to the Debug Probe.
  3. Prompt for which core the program needs to be loaded (this is usually done only once if the device has multiple cores of the same ISA).
  4. Automatically connect to the core/device.
  5. Run any GEL scripts to configure the hardware (if configured on the Target Configuration File).
  6. Load the project’s output file .OUT to the core/device memory. The code will be automatically written to the flash memory of the MSP430, F28x and SimpleLink MCU devices.
  7. Run to the function main() if configured on the Debug Configurations.

Note

The code will be automatically written to the flash memory of the Simplelink MCU, MSP430, F28x, Hercules and Digital Power devices. To configure the flash loader properties, check the Debug Configurations or the Flash Settings.

Note

Launching the debugger will cause CCS to build the active project if any modifications to the source code or the build options are made.

7.3.2. Manual launch

This process launches a Project-less debug session. Simply highlight a Target Configuration File in the Target Configurations view and do one of the following options:

  • Right-click on the desired target configuration file and select Launch Selected Configuration.
  • Double-click on the desired target configuration file to open the Target Configuration Editor and click on the Debug Launch button greenbugimage

Note

If no target configuration file or project is highlighted, the Default configuration of the workspace will be launched.

This will perform the sequence of steps shown in the section The launching process. In summary:

  1. Switch to the CCS Debug perspective.
  2. Connect to the Debug Probe.
  3. The manual launching process stops at this point, but additional steps can be done:
  4. Connection to a core can be established by right-clicking on the core and selecting Connect. Once the core finishes executing its initialization GEL script (if one is required), the code or symbols can be loaded by going to menu Run → Load → Load Program or Load symbols. Load Program loads the executable file produced by building your program onto the target board. Load Symbols loads symbol information only. It is useful when working in a debugging environment where the debugger need not load the object code, but simply debug existing code in Flash. When loading symbols, the existing symbol table is cleared before adding new symbols.
  5. Connection to a JTAG entity (ICEPICK router, DAP, etc.) can be done by right-clicking on the Debug view and selecting Show All Cores.

Launching the debugger manually can be useful in many scenarios:

  • If you don’t have a CCS project or simply have an executable or binary file to be loaded to the target.
  • It helps troubleshooting any JTAG connectivity issues.
  • It is one of the only options to connect to targets that have multiple cores, and some of them are held in reset when the device is powered up.
  • It is the only option if you don’t want to load code to the target but want to simply debug code that was previously flashed. In this case the debug launch is usually followed by loading symbols.
  • It can be useful to debug an ARM Cortex core by accessing its memory map directly via the Debug Access Port (DAP). The short video How to access memory using the DAP in the References section shows how to do that.

Note

For a project-less debug session, CCS may sometimes not be able to locate the source files to do the source-disassembly correlation. In such cases, there are a couple of ways to tell the debugger where to look for sources. Please see the section Debugging library code.

7.4. Debugging the application

The process of debuggging the application requires multiple features and helper views that allow complete control over the execution state of the target. Also, many data views complete the picture by exposing the status of the various subsystems of the target. This section describes in detail all these views and features.

7.4.1. After launch

After launching, the Eclipse perspective is switched from the CCS Edit editperspectiveicon to the CCS Debug debugperspectiveicon (indicated at the top right corner of the Workbench), with the default arrangement of views shown below.

Note

The display contents will greatly vary depending if changes were done in a prior run or if a different Debug Probe, target and code are used.

_images/ccs_debug-main_view.png
  • The Debug view contains the target configuration and the call stack for each core.
  • The source code view shows the program halted at the beginning of main().
  • For convenience, the Variables, Expressions and Registers views are also opened by default.
  • If the target configuration requires a script to run before the code is loaded, the Console view will open.

Basic debugging functionality is located in the bar at the top of the Debug view.

_images/ccs_debug-toolbar_basic.png
  • Run: starts execution of the target core.
  • Halt: halts the exeuction of the target core.
  • Terminate: disconnects from all hardware (cores, devices, Debug Probes) and terminates the Debug Session. Closes the CCS Debug perspective and returns of the CCS Edit perspective.
  • Step in: executes a single C source line, jumping into subroutines or functions, allowing to run its internal code step-by-step.
  • Step over: similar as above, but jumping over subroutines or functions, running its internal code at once.
  • Step out: similar as above, but running all lines, subroutines or functions until it reaches the caller function (given by the call stack or return()).

The extended bar shows advanced debugging tools in addition to the basic ones above.

_images/ccs_debug-toolbar_complete.png
  • Terminal: opens a Terminal view.
  • Runtime Object Viewer: launches the Runtime Object Viewer for SYSBIOS and TI-RTOS systems.
  • Connect/Disconnect: connects or disconnects from the core highlighted on the Debug view below.
  • Restore Debug State: restore all debug settings from the core or device most recently disconnected or terminated. Among the settings restored are hardware and software breakpoints, global breakpoints, profiling state among others.
  • Load: loads code to the highlighted core on the Debug view below. The small inverted arrow allows selecting the other operations Reload Program, Load Symbols, ** Add Symbols**, Verify Program and Remove All Symbols.
  • Real-time modes: enables/disables the Real-time modes supported by the core.
  • Reset: performs a reset on the core or device. The small inverted arrow allows selecting among the available resets.
  • Restart: issues a restart when either symbols or a program is loaded to the target device. A Restart simply re-positions the PC register to the entry point (typically _c_int00 or the reset vector).
  • New Breakpoint: adds or toggles a Breakpoint at the line pointed by the mouse cursor. The small inverted arrow allows selecting among the available types of breakpoints.
  • Debug As: starts a new Debug Session, terminating the currently active one. The small inverted arrow allows selecting among the previously launched Debug Sessions.
  • Assembly Step Into: executes a single assembly instruction, jumping into subroutines or functions, allowing to run its internal code step-by-step.
  • Assembly Step Over: similar as above, but jumping over subroutines or functions, running its internal code at once.
  • EnergyTrace: starts a EnergyTrace session.

Note

These toolbar functions are also available in both the menus Views and Target, which also feature several additional options.

7.4.2. Debug view

The Debug view is the most prominent view when the debugger is launched and is opened by default.

Without a program loaded:

_images/ccs_debug-debug_view_noload.png

With a program loaded:

_images/ccs_debug-debug_view.png

It contains several areas:

  • A tree that shows the target configuration file used and the type of Debug Session being used (Code Composer Studio - Device Debugging is the default type).

  • A series of nodes that show the Debug Probe that is linked to each core of the target, followed by its status:

    • Disconnected or Connected
    • Unknown, Suspended, Suspended
    • SW Breakpoint, Suspended
    • HW Breakpoint, Running, Free Running are the most common.
  • Either the current address of the Program Counter or the call stack of the program currently loaded.

Right-clicking on it shows the following context menu:

_images/ccs_debug-debug_rclk.png

7.4.3. Watching variables, expressions and registers

The cluster of tabbed views named Variables, Expressions and Registers is opened when the debug session is launched.

7.4.3.1. Variables view

The Variables view shows only Local variables that belong to the function currently being executed.

Variables that contain more than one element, such as arrays, structures, or pointers, are displayed with either a plus sign (+) or minus sign (-) immediately preceding the expression name.

  • The (+) symbol indicates that the expression contains elements that can be further expanded.
  • The (-) symbol indicates that the expression is fully expanded and can be collapsed to reduce the information displayed.

Variables whose values have changed since the last time they were seen are highlighted in yellow background. Whenever the situation permits it, the value of a variable may be modified by clicking its value column and entering a new value.

_images/ccs_debug-variables_view.png

It consists of the following columns:

  • Name: name of the variable.
  • Type: the variable datatype.
  • Value: the value of the variable. For arrays, this field displays the first few values of its elements.
  • Address: the address of the variable in the device memory.
    • In devices that have separate program and data pages, this is suffixed by the at symbol (@) followed by the page name (Program, Data, IO).
    • If the variable is allocated to a register, this field will show the word Register followed by its register name.

Note

This view does not allow adding or removing rows, since it is automatically populated by the variables present on the context of the program being debugged.

The toolbar contains several formatting options.

_images/ccs_debug-variables_toolbar.png

The options are:

  • Show type names: shows the type names when columns are disabled. This option is always disabled in the CCS debug sessions.
  • Show logical structure: shows the logical structure types of large variables (structs, objects, etc.). This option has no effect in CCS debug sessions.
  • Collapse All: collapses all expanded variables or registers.
  • Open new view: opens a new view to allow side-by-side comparison of values.
  • Pin to debug context: when debugging devices with multiple cores, this option locks the view to the core in context.
  • Refresh: updates the contents of the view with data from the target.
  • View Menu: drop-down menu with several options to customize how the data is displayed inside the view.
  • Minimize/Maximize: minimize or maximize the view.

Right-clicking on a given variable shows the following context menu:

_images/ccs_debug-variables_rclk.png

The options are:

  • Select All: selects all variables shown on the view
  • Copy Variables: copies the selected variables in tab separated format
  • Number Format: changes the numeric format of the selected variable to Hex, Decimal, Octal or Binary.
  • Cast To Type: changes the data type format of the selected variable to any C-valid data type.
  • View Memory: opens a Memory Browser view at the Location of the selected variable
  • View Memory at Value: similar as above but at the Location pointed to by the selected variable
  • Find: search for variable names
  • Q-Values: for signed integers, changes the representation of the variable to Q format.
  • Breakpoint (Code Composer Studio): adds a Watchpoint to the variable location in memory.
  • Graph: opens a Graph using the parameters of the selected row. Cannot be used for multiple rows.
  • Watch: adds the variable to the Expressions view.

7.4.3.2. Expressions view

The Expressions view is a typical watch window where variables (local, global, static), C-valid expressions and even registers can be monitored.

Expressions that contain more than one element, such as arrays, structures, or pointers, are displayed with either a plus sign (+) or minus sign (-) immediately preceding the expression name.

  • The (+) symbol indicates that the expression contains elements that can be further expanded.
  • The (-) symbol indicates that the expression is fully expanded and can be collapsed to reduce the information displayed.

Expressions whose values have changed since the last time they were seen are highlighted in yellow background. Whenever the situation permits it, the value of an expression may be modified by clicking its value column and entering a new value.

_images/ccs_debug-expressions_view.png

To add a variable, simply select the column that reads Add new expression and type a valid expression.

It consists of the following columns:

  • Name: name of the variable.
  • Type: the variable datatype.
  • Value: the value of the variable. For arrays, this field displays the first few values of its elements.
  • Address: the address of the variable in the device memory.
    • In devices that have separate program and data pages, this is suffixed by the at symbol (@) followed by the page name (Program, Data, IO).
    • In devices that have a Memory Management Unit (MMU), this variable will show by default the address from the CPU context. Its address can be mapped to the physical address by adding the at (@) symbol followed by the word PHY (for physical).
    • If the variable is allocated to a register, this field will show the word Register followed by its register name.

The toolbar contains several formatting options.

_images/ccs_debug-expressions_toolbar.png

The options are:

  • Show type names: shows the type names when columns are disabled. This option is always disabled in the CCS debug sessions.
  • Show logical structure: shows the logical structure types of large variables (structs, objects, etc.). This option has no effect in CCS debug sessions.
  • Collapse All: collapses all expanded variables or registers.
  • Create a new watch expression: identical function to the Add new expression, but opens a dialog box that allows easier editing of complex expressions.
  • Remove Selected Expressions/Remove All Expressions: removes the selected or all expressions of the view.
  • Continuous Refresh: updates the contents of the view with data from the target at a constant rate (configurable by the View Menu option).
  • Open new view: opens a new view to allow side-by-side comparison of values.
  • Pin to debug context: when debugging devices with multiple cores, this option locks the view to the core in context.
  • Refresh: updates the contents of the view by loading them from the target.
  • View Menu: drop-down menu with several options to customize how the data is displayed inside the view.
  • Minimize/Maximize: minimize or maximize the view.

Right-clicking on a given variable shows the following context menu:

_images/ccs_debug-expressions_rclk.png

The options are:

  • Select All: selects all variables shown on the view
  • Copy Expressions: copies the selected variables in tab separated format
  • Remove/Remove All: removes the selected or all expressions of the view.
  • Number Format: changes the numeric format of the selected variable to Hex, Decimal, Octal or Binary.
  • Add Expression Group:
  • View Memory: opens a Memory Browser view at the Location of the selected variable.
  • View Memory at Value: similar as above but at the Location pointed to by the selected variable.
  • Find: search for variable names.
  • Add Watch Expression: identical function to the Create a new watch expression.
  • Disable/Enable: disables or enables updates to the selected expression(s). Useful to increase performance during debugging by preventing the added data transfers from the target.
  • Edit Watch Expression: allows editing the selected expression and opens the same dialog box for easier editing of complex expressions.
  • Q-Values: for signed integers, changes the representation of the variable to Q format.
  • Cast To Type: changes the data type format of the selected variable to any C-valid data type.
  • Add Global Variables: add global variables with a useful dialog box that lists all global variables loaded to the target. The global variables can be searched by name.
  • Export/Import: export or import the entire contents of this view to ease the task of configuring future debug sessions.
  • Breakpoint (Code Composer Studio): adds a Watchpoint to the variable location in memory.
  • Graph: opens a Graph using the parameters of the selected row. Cannot be used for multiple rows.
  • Watch: adds the variable to the Expressions view.

7.4.3.3. Registers view

The Registers view allows viewing and editing the contents of core and peripheral registers of the device, including bitfields and individual bits. Register values that have changed are highlighted in yellow background. To change a register or register bit field value, single click in the value column of the register and modify it. This is only allowed for registers that are not read-only.

_images/ccs_debug-registers_view.png

It consists of the following columns:

  • Name: name of the register, bitfield or bit.
  • Value: the value of the register, bitfield or bit.
    • For bitfields and bits, this column can either have a freeform box to input the values directly or a drop-down with valid values.
  • Description: a brief description of the register, bitfield or bit.

Note

This view does not allow adding or removing rows, as they are automatically populated with the device information.

The toolbar contains several formatting options.

_images/ccs_debug-registers_toolbar.png

The options are:

  • Show type names: shows the type names when columns are disabled. This option is always disabled in the CCS debug sessions.
  • Show logical structure: shows the logical structure types of large registers. This option has no effect in CCS debug sessions.
  • Collapse All: collapses all expanded registers.
  • Continuous Refresh: updates the contents of the view with data from the target at a constant rate (configurable by the View Menu option).
  • Open new view: opens a new view to allow side-by-side comparison of values.
  • Pin to debug context: when debugging devices with multiple cores, this option locks the view to the core in context.
  • Refresh: updates the contents of the view by loading them from the target.
  • View Menu: drop-down menu with several options to customize how the data is displayed inside the view.
  • Minimize/Maximize: minimize or maximize the view.

Right-clicking on a given register, bitfield or bit shows the following context menu:

_images/ccs_debug-registers_rclk.png

The options are:

  • Select All: selects all variables shown on the view.
  • Copy Registers: copies the selected registers in tab separated format.
  • Number Format: changes the numeric format of the selected register to Hex, Decimal, Octal or Binary.
  • Cast To Type: changes the data type format of the selected register to any C-valid data type.
  • View Memory at Address: opens a :ref:memory-browser-view` at the Location of the selected register.
  • View Memory at Value: similar as above but at the Location pointed to by the selected register.
  • Find: search for register names.
  • Export: opens a dialog that allows selecting one or more registers to be exported to a .txt file.
  • Watch: adds the register to the :ref:expressions-view`.

7.4.4. Disassembly view

The disassembly view is an integral part of the debugger that translates machine language into assembly language, as it displays the disassembled instructions and symbolic information needed for debugging. This view is not opened by default but can be viewed by going to menu View → Disassembly, unless there is no loaded program or there are no debug symbols attached to the program.

_images/ccs_debug-disassembly_view.png

The Disassembly view contains several fields in its default configuration: - At the left of the view the program addresses are shown - The line numbers of the source file in context are also shown, if the loaded program contains symbolic debug information and the option Show Symbols is enabled. - Still at the left of the view, the small blue arrow indicates the location of the Program Counter - the next instruction to be executed. - To the right of the addresses the opcode is shown in hex format, as well as the disassembled instruction. - If the opcode references a function or variable, their names are also shown if debug symbols are present. - Hovering the mouse cursor over a specific function name shows its name and the address. - To the right of the line numbers the actual C source code is shown.

Many other features can be displayed depending on the options enabled.

The toolbar contains several functions:

_images/ccs_debug-disassembly_toolbar.png

The options are:

  • Address box: this box allows typing an address or a symbol name to navigate to the directory.
  • Refresh view: updates the contents of the view by loading them from the target.
  • Go to Current Program Counter (Home): scrolls the view to the current Program Counter position.
  • Link with Active Debug Context: when debugging devices with multiple cores, this option locks the view to the core in context.
  • Show source: enables viewing the source code intertwined with the assembly.
  • Assembly Step Into: executes a single assembly instruction, jumping into subroutines or functions, allowing to run its internal code step-by-step.
  • Assembly Step Over: similar as above, but jumping over subroutines or functions, running its internal code at once.
  • Open new view: opens a new view to allow side-by-side comparison of values.
  • Pin to debug context: when debugging devices with multiple cores, this option locks the view to the core in context.
  • View Menu: drop-down menu with several options to customize how the data is displayed inside the view.
  • Minimize/Maximize: minimize or maximize the view.

Right-clicking on the main view shows the following context menu:

_images/ccs_debug-disassembly_rclk.png

The options are:

  • Copy: copies the selected content in text form.
  • Select All: selects all content shown on the view.
  • Show Source: shows source code intertwined with the disassembled instructions.
  • Show Symbols: shows the debug symbols at their corresponding addresses.
  • Preferences… opens the Preferences view with display options.
  • Patch Assembly… allows editing the memory to modify opcodes.
  • Disassembly Style… shows a list of disassembly styles and allows switching among the various types. Device dependent.
  • Run to line: runs to the line pointed by the mouse cursor.
  • Move to line: moves the PC register to the line pointed by the mouse cursor.
  • Resume at line: moves the PC register to the line pointed by the mouse cursor and starts running from this point.

Right-clicking on the address view shows the following context menu:

_images/ccs_debug-disassembly_rclk2.png

The options are:

  • Breakpoint: adds or toggles a Breakpoint at the line pointed by the mouse cursor.
  • Enable/Disable Breakpoint: enables/disables a Breakpoint previously added to the line pointed by the mouse cursor.
  • Add Dynamid Printf: (C/C++ Eclipse debugger only) adds a watchpoint that prints out a message when the Program Counter reaches the line pointed by the mouse cursor.
  • Toggle Breakpoint: adds or removes a Breakpoint at the line pointed by the mouse cursor.
  • Breakpoint Properties: opens the dialog box to set the properties of the Breakpoint.
  • Show Addresses: shows the memory addresses at the left of each disassembled line.
  • Show Opcodes: (C/C++ Eclipse debugger only) shows the opcodes of the assembly instructions.
  • Show Function Offsets: shows the offsets relative to the prior function symbol defined in memory. Requires that debug symbols are previously loaded to the debugger.
  • Copy: copies the selected content in text form.

7.4.5. Memory Browser view

The Memory Browser view is another integral part of the debugger that shows the contents of the target memory starting at a specified address and with various data formatting features. The memory view is not opened by default but can be viewed by going to menu View → Memory Browser.

_images/ccs_debug-memory_view.png

It features multiple viewing formats and types: char, integer (signed/unsigned), float and multiple Hexadecimal data sizes (8 through 64-bits). Additional capabilities include: memory fill with predefined values, save to/load from files in the host PC, all the variables and functions can be viewed, and every memory position has a context-sensitive information box.

In certain architectures it can also display cache information:

_images/ccs_debug-memory_view_cache.png

To use it, simply enter a starting address in the Address Text box at the top of the view and select the appropriate memory page of the device.

Note

F28x MCUs, C5500 DSPs and PRU cores have separate code, data and I/O memory pages.

The contents of a selected memory location can be edited by double-clicking the value.

Multiple instances of the memory view can be displayed simultaneously, allowing comparisons of memory contents.

  • Any property changes made within an open memory view apply only to that memory view.

The toolbar contains several functions:

_images/ccs_debug-memory_toolbar.png

The options are:

  • Load / Save / Fill Memory: this button accesses the options to Load and Save Memory and Fill Memory.
  • Virtual/Physical Memory View: toggles between the Virtual and the Physical memory contents. For C6600 cores, it bypasses the MPAX for full 36-bit addressing. For Cortex A cores, it bypasses the Memory Management Unit (MMU).
  • Memory Analysis: it toggles the cache memory coloring. Device dependent.
  • Continuous Refresh: updates the contents of the view with data from the target at a constant rate (configurable by the View Menu option).
  • Refresh: updates the contents of the view by loading them from the target.
  • Open new view: opens a new view to allow side-by-side comparison of values.
  • Pin to debug context: when debugging devices with multiple cores, this option locks the view to the core in context.
  • View Menu: drop-down menu with several options to customize how the data is displayed inside the view.
  • Minimize/Maximize: minimize or maximize the view.

Right-clicking on the memory view shows the following context menu:

_images/ccs_debug-memory_rclk.png

The options are:

  • Add Watchpoint (C/C++)…: adds a Watchpoint to the highlighted address.
  • Find and Replace: search and replace data patterns in the target memory.
  • Configure…: configures what elements are displayed on the view, as well as the behaviour when saving modifications to the target memory.
  • Copy to Clipboard? copies the contents of the highlighted address or the entire view to the host clipboard.
  • Copy to Memory? copies the contents of the highlighted address or the entire view to another address region in the target memory.
  • Load Memory: loads contents of a file in the host to the target memory. Check the section Load and Save Memory.
  • Save Memory: saves the contents of the target memory to a file in the host. Check the section Load and Save Memory.
  • Fill Memory: fills contents of the target memory with configurable data types, address and memory length. Check the section Fill Memory.
  • Print: sends the contents of the highlighted address or the entire view to a printer attached to the host.
  • Reference Buffer: captures and saves a linear buffer (reference) to memory so it can be easily compared with changes as the code execution progresses.
  • Tiler Display: formats the memory contents to be displayed as a two-dimensional frame of data in 4x4 or 8x2 arrangements. Very useful for video processing.
  • Refresh: updates the contents of the view by loading them from the target.

7.4.5.1. Load and Save Memory

The Load Memory dialog is shown below. The Save Memory dialog is very similar.

_images/ccs_debug-memory_load_save.png

It supports several data formats and settings:

  • TI Data: a text file that follows the TI .dat file format. It parses the file and automatically fills the target memory address and length of the data to be copied.
  • TI Raw Data: a text file with no preformatted data. It requires providing the target memory address where the data will be copied and the type size of the source file.
  • Binary: a bitstream of binary data. It requires providing the target memory address where the data will be copied.
  • COFF: a binary file that follows the TI COFF file format. It parses the file and automatically fills the memory.
  • ELF: a binary file that follows the ELF file format. It parses the file and automatically fills the memory. Not supported by the Save Memory function.
  • Hex: a text file that follows the Hex file format. It parses the file and automatically fills the memory. Not supported by the Save Memory function.

For additional information about the various data formats supported by the Save Memory function, please check the section Data File Formats.

7.4.5.2. Fill Memory

The Fill Memory dialog is shown below.

_images/ccs_debug-memory_fill.png

The options are:

  • Start Address: sets the initial address to be filled.
  • Length: sets the amount of words in memory to be filled. The word size is defined in the Type-size setting.
  • Data Value: sets the data to be filled. Its size must match the Type-size setting.
  • Type-size: sets the size of the data to be written to the target memory. It can be set to the default size defined by the hardware ISA or to an arbitrary value.

7.4.6. Console view

The Console view is another integral part of the debugger that shows several informative messages of the debug session. It is not opened by default but it is usually shown as soon as the Debug Session starts to show various status and progress messages.

_images/ccs_debug-console_view.png

Among the several messages it can display are:

  • Output from the target configuration scripts (GEL scripts).
  • Errors and Warnings coming from the Debug Probe or its protocol stack.
  • Any Console I/O output coming from printf() statements in the code.

For multi-processor environments, there is the possibility of having multiple console views tied to each core.

The toolbar contains several functions:

_images/ccs_debug-console_toolbar.png
  • Clear Console: clears the contents of the Console view.
  • Scroll Lock: locks the automatic scroll when new content is added.
  • Word Wrap: wraps long lines of the text output to fit the width of the view.
  • Pin Console: when debugging devices with multiple cores, this option locks the view to the core in context.
  • Display Selected Console: allows selecting the multiple types of consoles available: Build, CIO and GEL output are the most common.
  • Open Console: creates a new Console view, which can be useful to monitor multiple cores or the output of multiple sources of data.
  • Minimize/Maximize: minimize or maximize the view.

Right-clicking on the console view shows the following context menu:

_images/ccs_debug-console_rclk.png
  • Cut/Copy/Paste: cuts, copies or pastes information to/from the clipboard.
  • Select All: selects all text in the view.
  • Find/Replace: search and replace strings in the view.
  • Open Link: opens a URL or a HTML link on an external web browser.
  • Clear: clears the contents of the Console view.
  • Scroll Lock: locks the automatic scroll when new content is added.
  • Word Wrap: wraps long lines of the text output to fit the width of the view.

7.4.7. Breakpoints

Breakpoints are one of the most basic features in any debugger, allowing the execution of the processor or core to halt at a pre-defined place in the code.

Breakpoints can be set at a line in a source file, which gets translated to an address in the device memory, or directly at an address on the Disassembly view. They can also be set on a method in the Outline or Project view.

They are displayed at the left side of the source editor view (in the vertical editor ruler, together with line numbers, code folding symbols, and others) and in the Breakpoints view.

Breakpoints can also be enabled and disabled via the context menu in all the views. An enabled breakpoint causes a thread to suspend whenever the breakpoint is encountered. Enabled breakpoints are shown in blue and have a checkmark overlay once successfully set up by the debugger (Software breakpoint: , Hardware breakpoint: ). A disabled breakpoint does not cause threads to suspend and are greyed out in all views.

There are two types of breakpoints: Software and Hardware.

A Software breakpoint is implemented as an opcode replacement. The debugger modifies the opcode by inserting an estop_0 instruction where the previous instruction was. The program counter stops immediately before it executes the software breakpoint instruction. In general this instruction is hidden from the main interface, but in certain instances this instruction is displayed in the Disassembly view.

Software breakpoints can only be set in memory regions with write access (RAM), therefore there is no limit to the number of software breakpoints that can be used.

A Hardware breakpoint is implemented internally by the target hardware. The method used to do this is heavily dependent on the device or core, but typically the debugger writes the address to a register on the device and sets a flag to enable breakpoints. Thess registers are not exposed to the IDE.

A hardware breakpoint can be set in any memory type (RAM, Flash or ROM), but it is limited by the number of registers on the device (typically 4 or 6). This is mandatory for the types of console I/O devices

Note

CCS automatically uses hardware breakpoints first for all breakpoints set. When the device/core runs out of hardware breakpoints, it attempts to set software breakpoints.

Hardware breakpoints can also have a count, which determines the number of times a location is encountered before a breakpoint is generated - e.g. if the count is 2, a breakpoint is generated every second time.

A special category of hardware breakpoints is called Watchpoint, which are breakpoints triggered by memory accesses instead of instruction acquisitions.

In addition to simply halting the code, breakpoints in CCS add a range of other actions such as file I/O transfers, screen updating, etc. and accessible via the Breakpoint Properties.

To set a breakpoint, simply double-click on the left side of either the line number in the source code view or the address in the disassembly view. The icon for either hardware or software breakpoint will indicate its status and placement.

_images/ccs_debug-bkpt_placement.png

Note

In optimized code sometimes the breakpoint cannot be set to the exact line in the C source code. This is because the optimizer may condense code and impact the correlation between the assembly instruction and the C source.

7.4.7.1. Breakpoint Properties

Breakpoint properties shows all details of a breakpoint (address location, related source code, type) and allows modifying its behaviour (actions, counter, type of event) associated can be accessed from all views viewed within the roperties window or within the Breakpoint view. If you have placed your cursor in the Breakpoint view window, you can right-click on a breakpoint and select Properties from the context menu to see a more detailed property list. The breakpoint properties are saved in the workspace, so you do not need to reset them in between debug sessions. You can modify any breakpoint property even after the breakpoint has been created.

_images/ccs_debug-bkpt_properties.png

In addition to simply halting the code, breakpoints in CCS add a range of other actions such as file I/O transfers, screen updating, etc. which are accessible via the Action option of its properties.

_images/ccs_debug-bkpt_actions.png

Some of these actions open a new of parameter options immediately below the Action field. The choice of parameters will depend on the chosen action.

The main actions are:

  • Halt Target: the default action when you create a breakpoint is to halt the target when it hits this part of the program.
  • Refresh All Windows: updates the contents of all open views of the debug session.
  • Execute Expression (GEL): executes a single GEL scripting command. When selected, a new option field is opened and requests to provide a one line of code written on GEL scripting language.
  • Update View: updates the contents of a single view of the debug session. When selected, a new option field is opened and requests to choose which view will be updated. After the update, the execution continues.
  • Read Data from File/Write Data to File: performs a read/write operation from/to the host computer when the breakpoint location is reached. After the data is transferred, the execution continues. When selected, four other fields are opened that request to choose a filename, memory address, length and data format.
    • The file is saved in either the TI .dat or .coff formats, which are described in the section Data File Formats.

Other breakpoint properties configurable are:

  • Skip Count: Sets the number of passes before the breakpoint action is executed.
  • Group: Allows grouping breakpoints for advanced control.

7.4.7.2. Watchpoints

Watchpoints are a special category of hardware breakpoints that can be triggered for a particular memory read, memory write, or memory read orwrite. Watchpoints are only shown in the Breakpoints view.

Watchpoints are extremely useful to catch exceptions, invalid memory boundary accesses, overrun buffers, etc. and can be set to access any memory region, including Memory Mapped Registers (MMR).

To set a Watchpoint, simply highlight a variable on the source code editor, right click and select Breakpoint → Hardware Watchpoint. It can also be set by clicking on the small blue dot in the Breakpoints view toolbar.

7.4.7.3. Conditional breakpoints

Conditional breakpoints are a special category that is triggered by a pre-configured condition such that the breakpoint suspends execution of a thread when the enabling condition is true. It is displayed with an overlay on the breakpoint icon.

To set a condition on a breakpoint:

  • Right-click on the Breakpoint that needs to be modified, either in the Breakpoints view, the Disassembly view or the Editor view.
  • From the Breakpoint’s context menu, select Breakpoint Properties.
  • In the Properties dialog, locate the branch Debugger Response.
  • In the Condition field, enter the expression for the Breakpoint condition. Enter the desired GEL expression in the field. Note that if the expression calls a GEL function, it must be defined in one of the already loaded GEL files.
  • Select Apply and Close to close the dialog and commit the changes.

While the breakpoint is enabled, thread execution suspends before that line of code is executed if the breakpoint condition evaluates to true.

7.4.7.4. Breakpoints view

The Breakpoints view is an integral part of the debugger that allows complete management of Breakpoints, as well as other extensions such as Watchpoints, Event Counters, among others. The memory view is not opened by default but can be viewed by going to menu View → Breakpoints.

_images/ccs_debug-bkpt_view.png

The view above contains the status of all breakpoints and allows configuring their properties directly via context menu (right-click).

_images/ccs_debug-bkpt_rclk.png
  • Breakpoint: expands to a list of list of Breakpoints, counters or Watchpoints.
  • Go to File: navigates to the source file where the Breakpoint is located.
  • Enable/Disable: it enables/disables the selected Breakpoints without removing them. This helps re-set them at a later time.
  • Remove: removes the highlighted breakpoint(s).
  • Remove All Triggers: it disables all Breakpoints set on this view but without removing them. This helps re-set them at a later time.
  • Remove All: removes all breakpoints in the view.
  • Select All: selects all breakpoints in the view.
  • Copy/Paste: copies or pastes breakpoint information to/from the clipboard.
  • Import/Export Breakpoints: import or export breakpoint information from/to a file in XML format. Very useful for complex debug sessions where multiple Breakpoints are set.

The toolbar contains various options.

_images/ccs_debug-bkpt_toolbar.png
  • New breakpoint: creates a new breakpoint by opening a dialog box to specify the Location (address) in memory. The small arrow next to this button allows selecting a list of Breakpoints, counters or Watchpoints.
  • Remove Selected Breakpoints: removes the highlighted breakpoint(s).
  • Remove All Breakpoints: removes all breakpoints in the view.
  • Show Breakpoints Supported by Selected Target: shows only the breakpoints that belong to a specific Debug Context. It is useful to differentiate between Breakpoints set on various cores or devices of a Debug Session.
  • Go to File for Breakpoint: navigates to the source file where the Breakpoint is located.
  • Skip All Breakpoints: it disables all Breakpoints set on this view but without removing them. This helps re-set them at a later time.
  • Expand/Collapse All: expands or collapses all breakpoints shown.
  • Link with Debug View: locks the view to the specific debug context.
  • View Menu: drop-down menu with several options to customize how the data is displayed inside the view.
  • Minimize/Maximize: minimize or maximize the view.

7.4.7.5. Terminal view

A simple Terminal view is avaiable to perform serial or networked communications from inside the CCS IDE. Details about this are available at the reference below:

7.4.8. Advanced data visualization

Advanced graph and image visualization tools are available in CCS. These tools can display arrays of data in graphical format in both time and frequency domains and accept various data types (integer, floating point, Q-values, real, complex, etc.) as well as Image Analyzer.

Check the pages below:

7.4.8.1. Cache view

The Cache view shows the cache configuration of the C6000 DSP core separated by type of cache and ordered by memory address. It contains various fields displayed in a spreadsheet format.

_images/ccs_debug-cache-view.png

The columns are:

  • Cache: type of cache being used at the row.
  • Line Start/End Adrs: the initial and final addresses of the line.
  • Set: the ID of the cache set.
  • Way: the way of the cache set. Requires the cache to operate in N-way associative mode.
  • Valid: indicates the data is valid.
  • Dirty: indicates the data is dirty.
  • LRU Way: indicates the least used way of the cache set.
  • Symbols in cache: shows a list of the debug symbols allocated in the cache line.

Right-clicking on the Cache view shows the following options:

_images/ccs_debug-cache-rclk.png
  • View cache line contents in Memory View: toggles the line separator for each cache line in the Memory Browser view.
  • Copy selected cell: copies the contents of the cell to the clipboard in text format.
  • Show Dashboard: displays the cache Dashboard, resetting any other view modifiers.
  • Highlight Cache Lines with Memory Differences: sets the cache lines with differences to a bold font for easier visualization.
  • Show each symbol in a separate row: expands the symbols shown in column Symbols in cache to display each in its own row.

The toolbar contains various options:

_images/ccs_debug-cache-toolbar.png
  • Address bar: a free text field to input the desired address to be evaluated by the Cache view.
  • Show cache line details: expands the highlighted cache line to display all symbols currently allocated to it.
  • Filter: sets different view configurations for the Cache view.
  • Refresh: updates the contents of the view by loading them from the target.
  • Pin to current device: when debugging devices with multiple cores, this option locks the view to the core in context.
  • New cache view: opens a new view to allow side-by-side comparison of values.
  • View Menu: drop-down menu with several options to customize how the data is displayed inside the view.
  • Minimize/Maximize: minimize or maximize the view.

7.4.9. Measuring Performance

The ability to measure low-level code performance by counting cycles is available through the Profile Clock tool. Details about this feature can be seen at the reference below:

7.4.10. Data File Formats

CCS is able to import and export data in a few file formats, including COFF, flat binary format and TI DAT.

7.4.10.1. Common Object File Format

The Common Object File Format or COFF for short, is a binary file format used for object code, libraries and executables and originated in Unix systems. TI uses this file format with modifications suitable for embedded systems.

Additional details and references can be found at the TI Assembly Language Tools User’s Guides or at the COFF Wikipedia page.

7.4.10.2. Binary Format

The Binary format has no specified header or translation. It is a simple bitstream of data with no information about symbols, address placement or relocation. The length of the data is equal to the length of the file.

One important aspect: when creating binary files using tiobj2bin or objcopy from a project, care must be taken to place all initialized code/data in adjacent memory locations. Any holes are filled with zeros. If a file with zero-filled gaps is loaded to a device, it may trigger invalid memory access errors.

7.4.10.3. TI Raw Data Format

The TI Raw Data Format is identical to the Binary Format above.

7.4.10.4. TI DAT Format

A text file that contains one line of header information and stores the data as one sample per line.

The header information for data files uses this syntax:

MagicNumber Format StartingAddress PageNum Length SubFormat
  • MagicNumber: fixed at 1651.
  • Format: the format type:
    • 1: Hexadecimal
    • 2: Integer
    • 3: Long
    • 4: Float
    • 9: Extended types
  • StartingAddress: the start address in hex
  • PageNum: the memory page:
    • 0: Program
    • 1: Data
    • 2: I/O
  • Length: the number of blocks in hex
  • SubFormat: The extended data type when Format is set to 9.

The Format types 1 through 4 are used by older versions of CCS and should be used only for legacy compatibility. The current versions only use format type 9 with the extended data type.

The table below shows a list of supported extended data types per target.

The list can be obtained by connecting to a device or core, then opening the Scripting Console and issuing the command eval(‘GEL_MemoryListSupportedTypes(0)’);

  ARM Cortex 32-bit ARM Cortex 64-bit F28x, PRU C66x MSP430
0 32-Bit Hex - TI Style 64-Bit Hex - TI Style 8-Bit Hex - TI Style 64-Bit Hex - TI Style 32-Bit Hex - C Style
1 32-Bit Hex - C Style 64-Bit Hex - C Style 8-Bit Hex - C Style 64-Bit Hex - C Style 32-Bit Hex - TI Style
2 32-Bit Signed Int 64-Bit Floating Point 8-Bit Signed Int 64-Bit Floating Point 32-Bit Signed Int
3 32-Bit UnSigned Int 64-Bit Exponential Float 8-Bit UnSigned Int 64-Bit Exponential Float 32-Bit UnSigned Int
4 32-Bit Binary 32-Bit Hex - TI Style 8-Bit Binary 32-Bit Hex - TI Style 32-Bit Binary
5 32-Bit Floating Point 32-Bit Hex - C Style Character 32-Bit Hex - C Style 32-Bit Floating Point
6 32-Bit Exponential Float 32-Bit Signed Int Packed Char 32-Bit Signed Int 32-Bit Exponential Float
7 16-Bit Hex - TI Style 32-Bit UnSigned Int 16-Bit Hex - C Style 32-Bit UnSigned Int 16-Bit Hex - C Style
8 16-Bit Hex - C Style 32-Bit Binary 16-Bit Hex - TI Style 32-Bit Binary 16-Bit Hex - TI Style
9 16-Bit Signed Int 32-Bit Floating Point 16-Bit Signed Int 32-Bit Floating Point 16-Bit Signed Int
10 16-Bit UnSigned Int 32-Bit Exponential Float 16-Bit UnSigned Int 32-Bit Exponential Float 16-Bit UnSigned Int
11 16-Bit Binary 16-Bit Hex - TI Style 16-Bit Binary 16-Bit Hex - TI Style 16-Bit Binary
12 8-Bit Hex - TI Style 16-Bit Hex - C Style 32-Bit Signed Int 16-Bit Hex - C Style 8-Bit Hex - C Style
13 8-Bit Hex - C Style 16-Bit Signed Int 32-Bit UnSigned Int 16-Bit Signed Int 8-Bit Hex - TI Style
14 8-Bit Signed Int 16-Bit UnSigned Int 32-Bit Hex - C Style 16-Bit UnSigned Int 8-Bit Signed Int
15 8-Bit UnSigned Int 16-Bit Binary 32-Bit Hex - TI Style 16-Bit Binary 8-Bit UnSigned Int
16 8-Bit Binary 8-Bit Hex - TI Style 32-Bit Floating Point 8-Bit Hex - TI Style 8-Bit Binary
17 Character 8-Bit Hex - C Style 32-Bit Exponential Float 8-Bit Hex - C Style Character
18 64-Bit Hex - TI Style 8-Bit Signed Int 32-Bit IEEE Floating Point 8-Bit Signed Int  
19 64-Bit Hex - C Style 8-Bit UnSigned Int 32-Bit IEEE Exp’l Float 8-Bit UnSigned Int  
20 64-Bit Signed Int 8-Bit Binary 64-Bit Hex - C Style 8-Bit Binary  
21 64-Bit UnSigned Int Character 64-Bit Hex - TI Style Character  
22 64-Bit Floating Point Packed Char 64-Bit Floating Point Packed Char  
23 64-Bit Exponential Float   64-Bit Exponential Float    

7.5. Advanced debugging topics

7.5.1. Debugging library code

When debugging the application, the target may be halted (either intentionally or unintentionally) within a routine in one of the libraries linked to the application. In such cases, the editor view will display the message Can’t find a source file at… or No source available for…. In most cases, there will also be two buttons named View Disassembly… and Locate File….

_images/nosource.png

The reason for the message is that the program is halted at a location where the debugger is unable to locate the corresponding source file. This is typical when halted within a library that was built outside of the main project.

This type of message can occur when halted within any library, including the C runtime library, BIOS libraries, driverlibs, or other custom libraries linked to the project.

Some situations when the message will appear:

  • if the Halt button is pressed and the Program Counter is located within a library routine.
  • if a Breakpoint is set at a label inside a library routine and the debugger is halted at it.
  • if the code is halted within a library routine for some unintended reason.

The message itself is harmless and can be ignored. But if it is required to do source level debugging of the library code, the debugger can point to the location of the source file by clicking on Locate File… and browsing to the location where the source file resides (a directory, a mounted remote drive, etc.).

Libraries from TI such as the C runtime library, driverlib (part of SimpleLink SDKs, C2000Ware, MSPWare, TivaWare etc.) come with sources, so these directories can be pointed to by the debugger.

If you do not have access to the source, you can still view and step through the disassembly code by clicking on View Disassembly….

Without the source file correlation, the debugger will also be unable to set breakpoints within a library routine from the editor view. For example, if you open a source file that is part of a library and try to set a breakpoint in it from the editor view before making the correlation between the debugger and source file, then the breakpoint will not be enabled. You can still set the breakpoint from the Breakpoints view by specifying the symbol name. Then when the program is halted at the breakpoint, you can click on the Locate File… button to tell the debugger where the source files are located. Once the association with the source is made, you should then be able to set future breakpoints from the editor view.

Besides the Locate File… button, there are a couple of other ways to tell the debugger where to look for sources that are not part of the project. Please see slides 53-58 of the CCSv6 Tips and Tricks presentation.

7.5.2. Debugging optimized code

If you have optimization enabled in your project that will impact the debug experience. The higher the level of optimization the more it will degrade the ease of debugging. Please see this article about tradeoff between debug and optimization: Debug versus Optimization Tradeoff

7.5.3. Trace

If you see the need to use Trace debugging for your platform, there are a few references (external links) for each device family:

7.5.3.1. Sitara, Keystone, OMAPL, Hercules, C6000 DSPs:

7.5.4. Multi-core Debug

CCS has advanced functionality to support Multi-core debugging, including the ability to control multiple cores and devices either in symmetric or assymmetric fashion. Details are covered in the articles below:

7.5.5. Configuring Flash Settings

CCS comes with an integrated On-Chip Flash Programmer. When a project is configured to use Flash memory regions of the device, the debugger automatically programs the Flash memory for those sections.

Note

Only devices with internal memory are automatically programmed with the built-in flash programmer. External Flash IC devices (I2C, SPI, parallel NAND/NOR) must use a custom method to be programmed.

To configure several flash memory related settings and operations of the device being used, the view can be opened in a few ways:

  • From the CCS Debug perspective, go to menu Tools → On-Chip Flash.
  • From the CCS Edit perspective, right click on the project and select Project Properties → Debug → Flash Settings.
  • Certain operations such as erase, protect, program can only be performed after connecting to the device.

To connect to the device prior to or even without loading a program, see the section Manual launch.

A summary of options per device variant is shown in the next sections, but consult the device documentation for additional information.

7.5.5.1. CC32xx (Cortex M4)

The following settings/operations are supported for CC32xx devices:

Flash Settings:

  • Crystal frequency: sets the crystal frequency required by the Flash algorithm to properly operate. It needs to match the target board hardware and is set to a default value that matches common development kits.
  • Reset target during program load to Flash memory: enables/disables the system reset signal before the Flash is programmed.

Program Load - Erase Method: sets the erase method when programming the device.

  • Necessary Pages Only: will erase only the flash regions to which the linker has allocated storage.
  • Use the Erase Options Specified Below: enables the options under the Erase section below.
  • Do Not Erase Flash Memory: do not erase anything.

Erase: manually erase the device’s Flash memory.

  • Entire Flash: erases everything.
  • By Address Range: specify the start and end address of flash to erase.

Enable Verbose Output: sets verbose mode output to the Console view.

7.5.5.2. CC13xx/CC26xx (Cortex M3/M4)

The following settings/operations are supported for CC13xx and CC26xx devices:

Program Load Settings: sets the erase method and gives the option to perform blank check and calculate CRC32 on flash memory immediately after the operation.

  • All Unprotected Sectors: erases everything that is not previously set as protected.
  • Necessary Sectors Only: will erase only the flash regions to which the linker has allocated storage.
  • Necessary Sectors Only (Retain untouched content within sector): performs a higher level of granularity for differential Flash programming. This can be used to load multiple executable files that reside in different sectors of memory.
  • Specific Sectors: allows erasing only specific sectors using the Sectors option below.
  • Do not erase sectors (program load only): performs the Flash programming only. Helps speed up the process for knowingly blank devices but can have problems with pre-flashed devices.
  • Use CRC Verification during program load: performs a CRC calculation and verification of the entire Flash contents.
  • Perform Blank Check: performs a verification if the entire Flash is blank.

Skip Sectors during Program Load: allows specifying sectors that remain untouched during Flash erase/program/verification. It can exclude sections based on its previous contents as well.

Customer Configuration (CCFG): allows setting various additinoal device configurations: - Keep CCFG data: retains the upper N bytes of the device’s CCFG. Consult the device’s documentation for additional details. - Disable Bootloader: disables the built-in device’s bootloader - Lock debug interface: prevents access to the debug interface after programming. This is not reversible and should not be used during the debug phase. - Write-protect sectors: prevents overwriting of specific sectors using the Sectors option below.

Erase Actions: manually erase the device’s Flash memory. - Erase entire flash: erases everything. The device must be reconnected after this operation. - Erase specific flash sectors: erases the sectors specified by the Sectors option below. - The Flash can be manually erased by clicking on the button Erase Flash.

Device Information: when connected, allows gathering information about the connected device.

Device MAC Addresses: when connected, allows reading and setting the Primary BLE, Secondary BLE, Primary IEEE and Secondary IEEE addresses. Consult the device’s documentation for additional details.

Enable Verbose Output: sets verbose mode output to the Console view

7.5.5.3. MSP432 (Cortex M4)

The following settings/operations are supported for MSP432 devices:

Program Load Settings: sets the erase method and gives the option to perform blank check and calculate CRC32 on flash memory immediately after the operation.

  • Necessary Pages Only: will erase only the flash regions to which the linker has allocated storage.
  • Use the Erase Options Specified Below: enables the options under the Erase section below.
  • Do Not Erase Flash Memory: do not erase anything.

Erase Configuration: specifies the various memory types to be erased during Flash programming.

  • Erase main memory only: erases only the main memory.

  • Erase main and information memory: erases both memory segments.

  • Factory Reset: restores all the memory and user registers to default settings.

  • Erase and download necessary segmnents only (Differential Download): keeps track of the executable previously loaded, performs a comparison between the two, determines the incremental changes and downloads only the modified memory sections. This is particularly useful for development stages where only minor changes are being performed on a large executable.

    • This option should NOT be used to load two different programs (such as a bootloader program and application program), as it might erase the first program when loading the second program, and it will also slow down programming as it will try to compare two totally separate programs unnecessarily.
  • Replace written memory locations, retain unwritten memory locations: can be used to load multiple executable files that reside in different sections of memory.

    • If there is a section that overlaps (such as vector table), the last executable to be downloaded is the one whose vector table needs to be retained, so the correct one is preserved on the target device.
  • By Address Range (specify below): specify the start and end address of flash to erase.

Allow BSL information memory erase: allows access to the BSL memory region. This is used to create custom BSL code.

Perform CRC verification: performs a CRC calculation of the entire Flash contents.

Perform Blank Check: performs a verification if the entire Flash is blank.

Device Security Configuration: locks the device permanently or a single time.

Enable Verbose Output: sets verbose mode output to the Console view

7.5.5.4. TM4C (Cortex M4)

The following settings/operations are supported for TM4C devices:

Flash Settings:

  • Crystal frequency: sets the crystal frequency required by the Flash algorithm to properly operate. It needs to match the target board hardware and is set to a default value that matches common development kits.
  • Reset target during program load to Flash memory: enables/disables the system reset signal before the Flash is programmed.

Program Load Settings: sets the erase method and gives the option to perform blank check and calculate CRC32 on flash memory immediately after the operation.

  • Necessary Pages Only: will erase only the flash regions to which the linker has allocated storage.
  • Use the Erase Options Specified Below: enables the options under the Erase section below.
  • Do Not Erase Flash Memory: do not erase anything.

Erase: specifies the various memory ranges to be erased during Flash programming.

  • Entire Flash: erases everything.
  • By Address Range: specify the start and end address of flash to erase.

Blank Check: performs a verification if the Flash is blank. Defaults to the entire flash but can be set for a specified address range.

CRC32: performs a CRC32 calculation on the Flash contents. Defaults to perform this on the entire flash but can be set for a specified address range.

User Register Programming: allows direct programming of the non-volatile User registers (USER_REG0 and USER_REG1).

MAC Address Mode: programs the User registers above in the format of an Ethernet MAC address.

Debug Port Unlock: allows the JTAG/SWD debug pins to be unlocked if you configure the pins as GPIOs or there is some other issue that causes the device to lock up, such as configuring the system clock out of specification.

ICDI Firmware Update: can be used to update the ICDI firmware for boards that use a TM4C123-based ICDI Debug Probe. For the last three settings, refer to the LMFlash Programmer Help for more information.

Device Information: when connected, allows gathering information about the connected device.

Enable Verbose Output: sets verbose mode output to the Console view.

7.5.5.5. F28x

The following settings/operations are supported for F28x devices:

Clock/PLL Settings: these options are critical to configure the device’s System Frequency for Flash operations.

  • These fields are not modifiable when using a Piccolo device, since the clock control is entirely based on the device’s on-chip oscillator.

Download Settings: these options control the actions to be executed.

  • Erase and Program: performs the Erase followed by Flash programming of the device. This is the safer method to program the devices.
  • Program Only: performs the Flash programming only. Helps speed up the process for knowingly blank devices but can have problems with pre-flashed devices.
  • Verify Only: does a sanity check on the data flashed to the device.
  • Perform Blank Check before loading data to Flash memory: does a blank verification before start programming the Flash.
  • Verify Flash after Program: does a sanity check on the data written to the target device.
  • Auto ECC Generation: enables the generation of Error Correcting Code of the data flashed to the device.

Range Avoidance Settings: allows specifying ranges that are left untouched by the Flash programmer.

Performance Settings: enables faster Flash programming by combining memory sections. The use of this option has several tradeoffs shown in the dialog box. Consult the device’s documentation for additional details.

Erase Settings: specifies the various memory ranges to be erased during Flash programming.

  • Entire Flash: erases everything.
  • Necessary Sections Only: will erase only the Flash regions to which the linker has allocated storage.
  • Selected Sectors Only: specifies the Flash Banks and Sectors to erase. The Flash can be manually erased by clicking on the button Erase Flash.
  • The Flash can be manually erased by clicking on the button Erase Flash.

Blank Check Settings: performs a verification if the Flash is blank.

  • Checksum: shows the checksup results for the various memory types.
  • Click on the button Calculate Checksum to perform the calculations.

Security Settings: used to program the code security password and other security settings for the various peripherals and memory.

Enable Verbose Output: sets verbose mode output to the Console view.

Backup RAM during Flash Programming/Operations: creates a backup copy of the RAM contents during Flash operations.

7.5.5.6. MSP430

The following settings/operations are supported for MSP430 devices:

Target Voltage (mV): sets the voltage used by the target device.

Download Options: sets options specific to certain devices.

  • Copy application to external SPI memory after program load: copies the application to external SPI memory. This is used by the Loader ROM code in certain devices.
  • Allow Read/Write/Erase access to BSL memory: allows access to the BSL memory region. This is used to create custom BSL code.

Flash Settings

  • Crystal frequency: sets the crystal frequency required by the Flash algorithm to properly operate. It needs to match the target board hardware and is set to a default value that matches common development kits.
  • Reset target during program load to Flash memory: enables/disables the system reset signal before the Flash is programmed.

Program Load Settings: sets the erase method and gives the option to perform blank check and calculate CRC32 on flash memory immediately after the operation.

  • Necessary Pages Only: will erase only the flash regions to which the linker has allocated storage.
  • Use the Erase Options Specified Below: enables the options under the Erase section below.
  • Do Not Erase Flash Memory: do not erase anything.

Erase Options: specifies the various memory types to be erased during Flash programming.

  • Erase main memory only: erases only the main memory.
  • Erase main and information memory: erases both memory segments.
  • Erase main, information and protected information memory: erases the entire memory of the device.
  • Erase and download necessary segmnents only (Differential Download): keeps track of the executable previously loaded, performs a comparison between the two, determines the incremental changes and downloads only the modified memory sections. This is particularly useful for development stages where only minor changes are being performed on a large executable.
    • This option should NOT be used to load two different programs (such as a bootloader program and application program), as it might erase the first program when loading the second program, and it will also slow down programming as it will try to compare two totally separate programs unnecessarily.
  • Replace written memory locations, retain unwritten memory locations: performs a higher level of granularity for differential Flash programming. This can be used to load multiple executable files that reside in different sections of memory.
    • If there is a section that overlaps (such as vector table), the last executable to be downloaded is the one whose vector table needs to be retained, so the correct one is preserved on the target device.
  • By Address Range (specify below): specifies the start and end address of flash to erase.

Erase Settings: sets the Start Address and the End Address when the option By Address Range above is selected.

Device Information: when connected, allows gathering information about the connected device.

Enable Verbose Output: sets verbose mode output to the Console view

7.5.5.7. Hercules (Cortex R)

The following settings/operations are supported for Hercules devices:

Flash Settings:

  • OSCIN Frequency (MHz) sets the crystal frequency required by the Flash algorithm to properly operate. It needs to match the target board hardware and is set to a default value that matches common development kits.
  • Enable Programming to OTP Memory: enables the writing to the OTP memory region of the device. Avoid enabling this option during the debug phase.
  • Auto ECC Generation: enables the generation of Error Correcting Code of the data flashed to the device.
  • Align program segments to 64-bit memory regions (for ECC calculation): forces the alignment to 64-bit boundary so the ECC calculation can be accurate.
  • System Reset on Connect: enables/disables the system reset signal before the device is connected.

Flash verification settings:

  • Verify Only: does a sanity check on the data flashed to the device.
  • Fast Verify: performs the Erase followed by Flash programming of the device. This is the safer method to program the devices.
  • None: performs the Flash programming only. Helps speed up the process for knowingly blank devices but can have problems with pre-flashed devices.

Program Load Settings: sets the erase method and gives the option to perform blank check and calculate CRC32 on flash memory immediately after the operation.

  • Necessary Pages Only: will erase only the flash regions to which the linker has allocated storage.
  • Use the Erase Options Specified Below: enables the options under the Erase section below.
  • Do Not Erase Flash Memory: do not erase anything.

Blank Check Options: performs a verification if the Flash is blank. Can be manually done bia the Blank Check button or enable an automatic verification before the program is Flashed.

Erase Options: specifies the various memory ranges to be erased during Flash programming.

  • Entire Flash: erases everything.
  • Necessary Sections Only (for Program Load): will erase only the Flash regions to which the linker has allocated storage.
  • Selected Sectors Only: specifies the Flash Banks and Sectors to erase.
  • The Flash can be manually erased by clicking on the button Erase Flash.

Flash Profiling: allows performing a complete profile of code previously loaded to the Flash and track for possible errors or inconsistencies when compared to a correct executable. It can also be useful to validate different Flash programming tools apart from CCS. Consult the device’s documentation for additional details.

Enable Verbose Output: sets verbose mode output to the Console view.

7.5.6. Connecting to slave cores of SoC devices

Most of the devices have a single core. However, in SoC devices usually one of the cores is the master (usually an ARM) and controls one or more additional cores (the slaves). In these cases it is impossible to load and debug code in the slave cores without previous intervention from the master core, which is not only responsible for releasing the slave cores from reset but can also initialize PLLs and external memory interfaces (EMIF).

  1. First make sure the Target Configuration File contains the proper GEL files - either by selecting a Board or manually adding them to the Device using the Advanced target configuration options.
  2. Manually launch the Debugger and connect to the Master core of the device.
  3. After that, the menu Scripts will have a number of options to connect to the slave cores. Unfortunately these options vary depending on the device, but some examples are:
  • For OMAPL138 the menu is shown as DSP Wakeup
  • For AM3359 the menu is shown as PRU_ICSS → PRU_ICSS_Init
  • Several devices such as AM57xx, AM65xx already release the slave cores from reset when connecting to the Master core.
  1. On the Debug View, right-click on the slave core and select Connect Target.
  2. Optionally code can be loaded to the core by going to menu Run → Load… → Load Program…

7.5.7. Core Status

The status of the cores of the SoC can be inspected using the Target Status view.

  1. Once the Debugger is launched, go to the Debug View, right click on it and select Show All Cores
  2. Expand the tree under Non Debuggable Devices, select the first core (the one which ends with IcePick_C or IcePick_D) and connect to it (Ctrl+Alt+C or menu Run → Connect Target)
  3. Go to menu View → Other and type Target Status on the Type filter text box.
  4. Select the Target Status and click OK.
  5. The Target Status view will be shown. Expand the selections and check the status of all the cores of your device.
  • The processor cores will be shown under a tree of non-debuggable cores (mostly named CS_DAP_xx). These non-debuggable cores must be connected to expose the status of the processor core.
  • A core that is ready to be connected will be shown as Clk On, Power On, CLK Down inactive, Power Down inactive, Not In Reset, Reset (None)
  • A core that is not ready to be connected will be shown as Clk Off, Power Off, CLK Down inactive, Power Down inactive, In Reset, Reset (None)
  • A core that is deliberately powered down will be shown as Clk Off, Power Off, CLK Down active, Power Down active, In Reset, Reset (None)

7.5.8. Real-time mode

Real-time mode is a special feature of selected devices and configurable via the CCS debugger that allows developers to halt and examine the program and its memory without blocking the service of any critical pre-configured interrupts.

The devices that support Real-time mode are all TI C55x, C64x, C674x, C66x and F28x devices through a built-in module called ICEMaker.

This mode is mostly used by F28x developers operating with high power systems, thus usage references for this device family can be seen at the following topics:

7.5.9. Advanced Debug Probe configurations

The Advanced tab of the Target Configuration Editor has a set of common configurations and a few items specific to each Debug Probe. Below follows a short list of the configurations present for each model and variant.

7.5.9.1. XDS110

_images/ccs_debug-xds110_advoptions.png
  • Board Data File: CCS requires a small text file to properly characterize the Debug Probe an board or device attached to it. This option controls the generation of this file. Leave it in auto generate unless in very special circumstances.

  • Debug Probe Selection: informs CCS if there are one or more Debug Probes tied to the host. it features the options One one XDS110 installed or Select by serial number.

    • The option Select by serial number opens the extra option Enter the serial number to allow typing the serial number of the Debug Probe to be used.
  • Power Selection: configures the type of power method applied to the target: Target supplied power or Probe supplied power (EnergyTrace).

    • The option Probe supplied power opens the extra option Enter voltage: with a form to input the voltage supplied by the XDS110 to the target.
  • Power isolation: sets the behaviour of the XDS110 probe after the CCS debug session disconnects from the target device/board: Remove power at final disconnect or Keep power at final disconnect. For additional details, check the section 3.1.2.2 of the <em>Addendum and errata to XDS110 Users Guide</em> at the - XDS110 page

  • JTAG TCLK Frequency (MHz): sets the JTAG TCLK frequency between Fixed default 8.5MHz frequency, Fixed with user specified value or Fixed with user selected faster value.

    • The two last selections open an extra option to either type the desired frequency or select among three pre-selected options.
  • JTAG / SWD / cJTAG Mode: configures the type of signaling to be used: 4-pin JTAG (IEEE1149.1), SWD modes with either Auxiliary UART or SWO Trace enabled, 4-pin cJTAG (IEEE1149.7) and 2-pin cJTAG (IEEE1149.7). Consult the device’s Technical Reference Manual for the modes supported by the device being used.

    • The 2-pin cJTAG option opens two extra options:

      • Target Scan Format, which configures the mode of operation of the cJTAG module
      • Auxiliary COM Por Connection, which enables either the UART communications port or SWO Trace.

7.5.9.2. XDS200

_images/ccs_debug-xds200_advoptions.png
  • Board Data File: CCS requires a small text file to properly characterize the Debug Probe an board or device attached to it. This option controls the generation of this file. Leave it in auto generate unless in very special circumstances.

  • Debug Probe I/O Port Number: configures which Debug Probe tied to the host has to be used. Each I/O port is dynamically allocated and is set by the order of which Debug Probe was plugged to the host.

    • The option User Defined Port Number opens the extra option Enter a User Defined Port Number to allow typing port numbers greater than 3.
  • The JTAG nTRST Boot-Mode: sets the status of the EMU0 and EMU1 pins to allow special Boundary scan modes to be sampled at the switch of the TRST signal. Consult the device’s Technical Reference Manual for the modes supported by the device being used.

  • The Power On-Reset Boot-Mode: sets the status of the EMU0 and EMU1 pins to allow special device boot modes to be sampled at power up. Read the device’s Technical Reference Manual for details.

  • JTAG TCLK Frequency (MHz): sets the JTAG TCLK frequency between Fixed with user specified faster value, Adaptive with user specified limit.

    • The option Enter a value is always enabled to allow typing the desired frequency.
  • The JTAG Signals Isolation Upon Disconnect: sets the behaviour of the Debug Probe after the CCS debug session disconnects from the target device/board: Do not isolate JTAG signals when last client disconnects or Isolate JTAG signals when last client disconnects.

  • Apply nRESET/SRST pin on the debug header: configures the behaviour of the nRESET pin to be asserted at the beginning of every debug session.

  • JTAG / SWD / cJTAG Mode: configures the type of signaling to be used: 4-pin JTAG (IEEE1149.1), SWD modes with either Auxiliary UART or SWO Trace enabled, 4-pin cJTAG (IEEE1149.7) and 2-pin cJTAG (IEEE1149.7). Consult the device’s Technical Reference Manual for the modes supported by the device being used.

    • The 4-pin cJTAG option opens two extra options:

      • The Converter 1149.7 Frequency Source: adjusts the clock source and type for the cJTAG operation.
      • The Target Pin Width: adjusts the bus width of the target hardware.
    • The 2-pin cJTAG option opens four extra options:

      • Target Scan Format: configures the mode of operation of the cJTAG module.
      • The Target Pin Width: adjusts the bus width of the target hardware.
      • User COM Por Connection, which enables either the UART communications port or the standard TDO data pin.

7.5.9.3. XDS560v2

_images/ccs_debug-xds560v2_advoptions.png
  • Board Data File: CCS requires a small text file to properly characterize the Debug Probe an board or device attached to it. This option controls the generation of this file. Leave it in auto generate unless in very special circumstances.

  • Emulator I/O Port Number: configures which Debug Probe tied to the host has to be used. Each I/O port is dynamically allocated and is set by the order of which Debug Probe was plugged to the host.

    • The option User Defined Port Number opens the extra option Enter a User Defined Port Number to allow typing port numbers greater than 3.
  • JTAG TCLK Frequency (MHz): sets the JTAG TCLK frequency between:

    • Automatic with faster 35.0MHz limit: the debug probe performs a signal integrity test until it reaches the highest speed up to 35.0MHz.
    • Automatic with legacy 10.368MHz limit: the debug probe performs a signal integrity test until it reaches the highest speed up to 10.368MHz. It can help connecting to boards in noisier environments.
    • Automatic with user specified limit: the debug probe performs a signal integrity test until it reaches the highest speed up to the user-defined value passed to the option Enter a value.
    • Adaptive with user specified limit: the debug probe performs a signal integrity test until it reaches the highest speed up to the user-defined value passed to the option Enter a value.
    • Adaptive without any limit at all: the debug probe performs a signal integrity test until it reaches the highest speed possible.
    • Fixed with user specified faster value: the debug probe attempts to connect at the speed defined by the user-defined value passed to the option Enter a value. If the connection is unreliable, it reduces the TCLK speed to get a reliable connection.
    • Fixed with user specified slower value: the debug probe attempts to connect at the speed defined by the user-defined value passed to the option Enter a value. If the connection is unreliable, it increases the TCLK speed to get a reliable connection.
    • TCLK looped-back with user specified limit: the debug probe shorts TCK and RTCK internally to allow connecting to targets that do not have this connection provisioned.
  • TMS/TDO Output Timing: adjusts the operation mode of the TMS signal to allow for a faster but less compatible operation mode.

  • The JTAG nTRST Boot-Mode: sets the status of the EMU0 and EMU1 pins to allow special Boundary scan modes to be sampled at the switch of the TRST signal. Consult the device’s Technical Reference Manual for the modes supported by the device being used.

  • The Power On-Reset Boot-Mode: sets the status of the EMU0 and EMU1 pins to allow special device boot modes to be sampled at power up. Read the device’s Technical Reference Manual for details.

  • The Boot-Mode Pin Map: sets the functions of each EMU0 and EMU1 pins, giving limited GPIO control over these pins to set modes and hardware features (if the target board is routed to do so).

  • The JTAG Signals Isolation Upon Disconnect: sets the behaviour of the Debug Probe after the CCS debug session disconnects from the target device/board: Do not isolate JTAG signals when last client disconnects or Isolate JTAG signals when last client disconnects.

  • The cJTAG Converter Features: configures the type of signaling to be used: 4-pin JTAG (IEEE1149.1), 4-pin cJTAG (IEEE1149.7) or 2-pin cJTAG (IEEE1149.7). Consult the device’s Technical Reference Manual for the modes supported by the device being used.

    • The 4-pin cJTAG option opens two extra options:

      • The Converter 1149.7 Frequency Source: adjusts the clock source and type for the cJTAG operation.
      • The Target Pin Width: adjusts the bus width of the target hardware.
    • The 2-pin cJTAG option opens four extra options:

      • The Converter 1149.7 Frequency Source: adjusts the clock source.
      • The Converter 1149.7 Frequency Value: adjusts the clock frequency.
      • The Target Pin Width: adjusts the bus width of the target hardware.
    • Target Scan Format: configures the mode of operation of the cJTAG module.

7.5.9.4. XDS 560v2 ProTrace

_images/ccs_debug-protrace_advoptions.png
  • Board Data File: CCS requires a small text file to properly characterize the Debug Probe an board or device attached to it. This option controls the generation of this file. Leave it in auto generate unless in very special circumstances.

  • Emulator I/O Port Number: configures which Debug Probe tied to the host has to be used. Each I/O port is dynamically allocated and is set by the order of which Debug Probe was plugged to the host.

    • The option User Defined Port Number opens the extra option Enter a User Defined Port Number to allow typing port numbers greater than 3.
  • JTAG TCLK Frequency (MHz): sets the JTAG TCLK frequency between Adaptive, Fixed with specified value or TCLK looped-back with user specified limit.

    • The last two selections enable the option Choose a value, which allows selecting between Slow, Typical and Fast (maximum of 6.5MHz)
  • TMS/TDO Output Timing: adjusts the operation mode of the TMS signal to allow for a faster but less compatible operation mode.

  • The JTAG nTRST Boot-Mode: sets the status of the EMU0 and EMU1 pins to allow special Boundary scan modes to be sampled at the switch of the TRST signal. Consult the device’s Technical Reference Manual for the modes supported by the device being used.

  • The Power On-Reset Boot-Mode: sets the status of the EMU0 and EMU1 pins to allow special device boot modes to be sampled at power up. Read the device’s Technical Reference Manual for details.

  • The Boot-Mode Pin Map: sets the functions of each EMU0 and EMU1 pins, giving limited GPIO control over these pins to set modes and hardware features (if the target board is routed to do so).

  • The JTAG Signals Isolation Upon Disconnect: sets the behaviour of the Debug Probe after the CCS debug session disconnects from the target device/board: Do not isolate JTAG signals when last client disconnects or Isolate JTAG signals when last client disconnects.

  • The cJTAG Converter Features: configures the type of signaling to be used: 4-pin JTAG (IEEE1149.1), 4-pin cJTAG (IEEE1149.7) or 2-pin cJTAG (IEEE1149.7). Consult the device’s Technical Reference Manual for the modes supported by the device being used.

    • The 4-pin cJTAG option opens two extra options:

      • The Converter 1149.7 Frequency Source: adjusts the clock source and type for the cJTAG operation.
      • The Target Pin Width: adjusts the bus width of the target hardware.
    • The 2-pin cJTAG option opens four extra options:

      • The Converter 1149.7 Frequency Source: adjusts the clock source.
      • The Converter 1149.7 Frequency Value: adjusts the clock frequency.
      • The Target Pin Width: adjusts the bus width of the target hardware.
    • Target Scan Format: configures the mode of operation of the cJTAG module.

7.5.9.5. XDS100v2 and XDS100v3

_images/ccs_debug-xds100v2_advoptions.png _images/ccs_debug-xds100v3_advoptions.png
  • Board Data File: CCS requires a small text file to properly characterize the Debug Probe an board or device attached to it. This option controls the generation of this file. Leave it in auto generate unless in very special circumstances.

  • Debug Probe Selection: informs CCS if there are one or more Debug Probes tied to the host. it features the options One one XDS100 installed or Select by serial number.

    • The option Select by serial number opens the extra option Enter the serial number to allow typing the serial number of the Debug Probe to be used.
  • The JTAG nTRST Boot-Mode: sets the status of the EMU0 and EMU1 pins to allow special Boundary scan modes to be sampled at the switch of the TRST signal. Consult the device’s Technical Reference Manual for the modes supported by the device being used.

  • The Power On-Reset Boot-Mode: sets the status of the EMU0 and EMU1 pins to allow special device boot modes to be sampled at power up. Read the device’s Technical Reference Manual for details.

  • JTAG TCLK Frequency (MHz): sets the JTAG TCLK frequency between:

    • Fixed default 1.0MHz frequency: connects at the fixed frequency of 1.0MHz.
    • Adaptive with user specified limit: connects using Adaptive clock using the user-defined TCLK value passed to the option Enter a value.
    • Fixed with user specified faster value: the debug probe attempts to connect at the speed defined by the user-defined value passed to the option Enter a value. If the connection is unreliable, it reduces the TCLK speed within a narrow range to get a reliable connection.
    • Fixed with user specified slower value: the debug probe attempts to connect at the speed defined by the user-defined value passed to the option Enter a value. If the connection is unreliable, it increases the TCLK speed within a narrow range to get a reliable connection.

The XDS100v3 adds the following options:

  • The JTAG Signals Isolation Upon Disconnect: sets the behaviour of the Debug Probe after the CCS debug session disconnects from the target device/board: Do not isolate JTAG signals when last client disconnects or Isolate JTAG signals when last client disconnects.

  • The Converter Usage: configures the type of signaling to be used: 4-pin JTAG (IEEE1149.1), 4-pin cJTAG (IEEE1149.7) or 2-pin cJTAG (IEEE1149.7). Consult the device’s Technical Reference Manual for the modes supported by the device being used.

    • The 2-pin cJTAG option opens three extra options:

      • The Converter 1149.7 Frequency: adjusts the clock source of the cJTAG converter.
      • The Debug Probe 1149.1 Frequency: adjusts the clock frequency of the 4-pin JTAG/cJTAG.
    • Target Scan Format: configures the mode of operation of the cJTAG module.