7.6. Trace

Trace is an advanced debugging capability that allows capturing various run-time analysis data, such as code execution and system events, in real-time. It can be an invaluable tool to detect complex, intermittent bugs and to profile and fine tune code performance.

There are several types of trace available with Code Composer Studio:

  • Core Trace: Provides a history of program addresses that were executed

  • EnergyTrace™: Provides visibility into the energy usage of the device while it is running

  • EnergyTrace++™: Provides visibility into the energy usage of the device and also:

    • Correlates the energy consumption with the CPU states, including whether the device is in active mode or one of the many low-power modes (LPM)
    • Shows the ON-OFF status of the peripherals and all system clocks (regardless of the clock source) while it is running

Note

The availability of each type of trace can vary depending on the device, debug probe, and host OS used.

Warning

Only one trace feature can be used at a time. You can switch from one trace feature to the other by closing the tab view for the open trace data, or by clicking on the Run → Trace menu item that has a checkmark next to it to disable that trace feature.

7.6.1. Glossary

This section provides information on some of the terminology and abbreviations used throughout this chapter.

  • Core: An embedded processor. Also called a CPU
  • CSV (Comma Separated Value) file: A comma-delimited output file type that can be opened with Microsoft Excel or spreadsheets and text editors
  • Host:. The processor that communicates with the target(s) to collect instrumentation data. For example, a Microsoft Windows computer running Code Composer Studio
  • Micro Trace Buffer (MTB): A buffer area on-chip where execution trace data is stored. It records changes in the CPU's program flow, referred to in this document as "PC Discontinuities". The Code Composer Studio Debugger can access the trace records and reconstruct the program flow. Timestamps are not available for the contents of the MTB
  • PC (Program Counter): Core register used to specify the address of the opcode to be executed. Sometimes referred to as a program address
  • PC Discontinuity: A change in the CPU's program flow, typically caused by a branch instruction, function call, return instruction, looping mechanism, interrupt or exception. May also occur when an invalid instruction has been read from either memory or cache (e.g. after some form of memory corruption has occurred)
  • Target: A processor running target code. Generally this is an embedded processor such as a DSP, ARM, or microcontroller
  • Trace View: the trace-related information that is displayed in the left panel of Code Composer Studio when the Trace icon in the Activity bar is clicked on
  • Trace Tab: the tab in the bottom panel that is used to display captured trace data
  • Trace Tab displays: the views within the Trace Tab that contain trace-related information

7.6.2. Trace Tab

When trace enabled, the captured data is displayed in a tab in the bottom panel, referred to here as the "Trace tab".

_images/ccs_debug-trace_view.png

As with other tabs in Code Composer Studio, you can do the following:

  • Change Layout: Drag the tab to a different position in the bottom panel or to a different panel entirely if you prefer a different layout for your screen.
  • Maximize Tab: Maximize the bottom pane contents by entering Alt+M, or by right-clicking on the tab and selecting Toggle Maximized from the context menu. To go back to the normal tabbed display, enter Alt+M again or right click on the left-most tab at the top of the display and select Toggle Maximized from the context menu that is displayed.
  • Close Tab: When the tab is in focus or you hover over it, an X will be displayed on the right edge of the tab itself which allows you to close the tab.

Closing the Trace tab will disable the selected Trace feature and re-enable all of the Trace-related icons and menu items.

The displays shown in the Trace tab have a number of features which allow you to configure what is displayed:

  • Vertical Toolbar at the left edge of each display

    • X allows you to close the display
    • Show View Options provides additional options for the display when clicked on

  • Resizing Handles along the bottom edge of each display

    • Allow you to change the height of the display. Click and drag up or down to decrease or increase the height of the display

  • Scroll bars

    • When the full height of a display is not shown, a vertical scroll bar is displayed on the right edge of the display which allows you to scroll the display contents up or down. For EnergyTrace, there may be two scroll bars displayed on the right side of the Trace tab - one for the tab itself, allowing you to scroll through the displays contained in the tab, and to the left of that a second scroll bar associated with the display itself. Scrolling the display scroll bar will control the contents of the display without changing the Trace tab's scroll bar.

7.6.3. Trace View

The Trace view provides a convenient interface of the Trace environment. To display the Trace view, select View → Trace from the main menu or click on the Trace icon in the Activity bar. (Note that this icon is only displayed in the Activity bar after a Trace feature has been enabled or after View → Trace has been selected from the main menu).

_images/ccs_debug-trace_view_activity.png

The Trace View Toolbar at the top of the left-hand panel in the Trace view contains three icons for:

  • Core Trace button
  • EnergyTrace button
  • EnergyTrace++ button
  • Trace Server status icon

Starting a debug session for an MSPM0Gxxx device enables the Core Trace and EnergyTrace buttons:

  • Core Trace button will enable Core Trace and open the Core Trace tab. Clicking on the Core Trace icon again will disable Core Trace
  • EnergyTrace button will enable EnergyTrace and open the EnergyTrace tab. Clicking on the EnergyTrace icon again will disable EnergyTrace
  • EnergyTrace++ button will enable EnergyTrace++ and open the EnergyTrace++ tab. Clicking on the EnergyTrace++ icon again will disable EnergyTrace++
  • Trace Server status icon reflects the status of the Trace Server, which handles all of the low level details involved with capturing and displaying trace data. A checkmark will indicate that the server is operational. A red error icon will indicate that the server encountered and error and is offline. This often will require Code Composer Studio to be restarted.

Note that Core Trace, EnergyTrace, and EnergyTrace++ can also be enabled and accessed directly from the top menu using the Run → Trace → Enable Core Trace, Run → Trace → Enable EnergyTrace, and Run → Trace → Enable EnergyTrace++ menu items respectively.

When Core Trace, EnergyTrace, and EnergyTrace++ is enabled, the Trace view is updated to display the following:

  • OPENED TRACES: Displays the name of the Trace tab that has been opened. Hovering over this item causes an X to appear in the upper right corner of the item which, ,when clicked, will close the Trace tab and re-enable the Core Trace, EnergyTrace, and EnergyTrace++ icons in the Trace toolbar
  • AVAILABLE VIEWS: Displays the name of each of the views that are shown in the Trace tab. If you choose to close one of these views by clicking on the X in the left-hand toolbar for the view, you can re-open the view in the tab by double-clicking on the entry in the AVAILABLE VIEWS list
  • ITEM PROPERTIES: Displays information about a table entry that has been selected. Clicking on a row in the Core Trace table or EnergyTrace Records table will cause the ITEM PROPERTIES display to be updated with entries for each column in the table

7.6.4. Core Trace

Core Trace (also referred to as "Processor", "Instruction", or "CPU" Trace) is an advanced debug feature that performs real-time gathering of all instructions being executed by the core. A timestamp is stored with each instuction. The collected trace data is then sent to Code Composer Studio for further post processing and displayed in the Code Composer Studio trace views. Code Composer Studio can correlate the instructions with the source code and thus allows for looking the code execution more easily. The ability to see the program's execution history allows for finding places where the code behaves erratically or took an unexpected branch.

Typical uses of Core Trace include:

  • Debugging program crashes: allows you to see the path the code took leading up to a user-defined exception breakpoint, for example
  • Debugging program execution: the branches / calls / ISRs / if-then-else statement execution leading up to a user-defined breakpoint

Since the execution speed of modern processors can reach billions of instructions per second, it is impossible to gather all this information without special hardware and some buffering between the device and the host machine. Hence, core trace is not available in all devices. For the ones which have this feature, there are several types of Core Trace with different levels of functionality.

Note

Core Trace is available on Code Composer Studio Windows and Linux desktop hosts only.

7.6.4.1. Types of Core Trace

7.6.4.1.1. MTB Trace

MTB Trace provides a single execution trace capability for supported MSPM0+ devices - recording any PC discontinuities. It is a type of Core Trace, though more limited in scope than other implementations. MTB Trace uses SRAM to store the data and it is configured to store four entries.

MTB Trace is only available for MSPM0Gxxx devices.

See the below article for more information on the Micro Trace Buffer (MTB) itself:

7.6.4.1.2. ERAD Trace

ERAD Trace provides a single execution trace capability for supported F28x devices - recording any PC discontinuities in a dedicated trace buffer. The size of the buffer can vary depending on the exact device (from 1Kb to 4Kb). It is a type of Core Trace, though more limited in scope than some other implementations.

ERAD Trace is only available for F28Pxxx and F29xxxx based devices.

See the below article for more information on ERAD itself:

7.6.4.1.3. ETB Trace

ETB Trace provides a single execution trace capability for supported devices - recording any PC discontinuities in a dedicated trace buffer. The size of the buffer can vary depending on the exact core and device. It is a type of Core Trace, with more capability than either MTB or ERAD based trace options.

ETB Trace is available on the following cores:

  • ARM Cortex-A72/A53
  • ARM Cortex-R5
  • ARM Cortex-M4 (only on select devices)
  • C66x
  • C7x

See the below article for more information on ETB itself:

7.6.4.2. Starting Core Trace

Core Trace is enabled via the Run menu. Once you have started a debug session for a device that supports trace, select Run → Trace → Enable Core Trace (or use the Core Trace button in the Trace view) to open the Core Trace tab in the bottom panel. When you next run and then halt the debugger, the Core Trace tab will be updated to show a table of the Program Addresses that were captured leading up to the debugger halting.

The contents of the Core Trace tab will vary depending on the the type of Core Trace.

7.6.4.2.1. MTB/ERAD

_images/ccs_debug-core_trace.png

The address executed by the program being run on the device is determined by the device's Program Counter (PC) register. A branch or an interrupt causes the PC to not be incremented as it normally would, but instead load in a new address into the register. This is called a PC Discontinuity. Since trace buffers have a limited size (only 4 PC discontinuities are captured by the MTB), the amount of trace data that is presented in the table will depend on how frequently branches occur in the code. For some devices (such as MSPM0Gxxxx), all addresses that were executed between each of the PC Discontinuities will be displayed in the table along with corresponding assembly (Asm), Function, source Line / File / Directory (Dir), and Source code for that address.. The Discontinuity column uses the => entry to indicate the new address that was loaded into the Program Counter for each PC Discontinuity.

7.6.4.2.2. ETB

_images/ccs_debug-core_trace_etb.png

The address executed by the program being run on the device is determined by the device's Program Counter (PC) register. A branch or an interrupt causes the PC to not be incremented as it normally would, but instead load in a new address into the register. This is called a PC Discontinuity. Since trace buffers have a limited size, the amount of trace data that is presented in the table will depend on how frequently branches occur in the code. All addresses that were executed between each of the PC Discontinuities will be displayed in the table along with the Opcode and corresponding assembly (Asm), Function, source Line / File / Directory (Dir), Source code, and cycle count (Cycles) for that address.

7.6.4.2.3. Additional View Options

Clicking on Show View Options will have options for:

  • Pin View: Pin the view to a specific core. This can be helpful during Multi-core Debug.
  • Toggle Columns: Select which columns to show/hide in the view.

7.6.4.3. Source and Disassembly View Correlation

Clicking on an entry in the Core Trace table will:

  • Open the correlating source file in the editor and jump to the associated source line
  • Cause the Disassembly view to display the associated address as the top entry in the Disassembly view

7.6.4.4. Example Use Cases

If you are running a FreeRTOS application, interrupt #3 in the *_startup.c file has the label HardFault and the handler assigned is HardFault_Handler() which is aliased to Default_Handler(). Set a breakpoint at HardFault_Handler to catch hard faults. The Core Trace will then be able to show you the last 4 PC discontinuities leading up to the Hardfault_Handler being called.

7.6.5. Custom Core Trace

Custom Core Trace is essentially Core Trace with additional features for configuring the trace hardware. Selecting the Run → Trace → Enable Custom Core Trace menu item will open the Enable Custom Core Trace dialog.

_images/ccs_debug-trace-custom_core.png
  • Receiver: Configure the trace receiver Buffer Type to be either Circular (wrap around) or Stop-on-full (disable trace collection when the buffer is full)
  • Range: Specify an address range the trace data is collected for. Multiple ranges can be specified using the + button to add additional ranges.
  • Start/Stop Trigger Addresses: Specify when trace collection is active by turning trace on (Start Trace) or off (Stop Trace) when instructions at specific addresses are executed. This allows for very precise control over when trace data is collected, making sure only data of interest is collected. This is especially helpful when working with the limited buffer size of the ETB. Multiple start/stop triggers can be specified using the + button to add additional ranges.

Once the trace hardware is configured, press the OK button to start the core trace session.

Custom Core Trace is only supported on ETB based Core Trace sessions.

7.6.6. EnergyTrace™

EnergyTrace™ technology is a power analyzer tool for Code Composer Studio that measures and displays the energy profile of an application and helps optimize it for ultra-low-power consumption. The tool can be used standalone as a power profiling tool, or in a debug session for code analysis to help optimize the application for ultra-low-power consumption.

EnergyTrace in Code Composer Studio is currently supported on the following devices families:

  • MSPM0
  • MSP430
  • CC13xx/CC26xx

Note

EnergyTrace™ is available on Code Composer Studio Windows and Linux desktop hosts only.

7.6.6.1. Starting EnergyTrace

EnergyTrace is enabled via the Run menu. Once you have started a debug session for a device that supports EnergyTrace, select Run → Trace → Enable EnergyTrace (or use the EnergyTrace button in the Trace view) to open the EnergyTrace tab in the bottom panel. When you next run and then halt the debugger, the EnergyTrace tab will be updated to show information about the EnergyTrace that was captured leading up to the debugger halting.

The EnergyTrace displays will only be updated if sufficient EnergyTrace data is captured. Typically, debug operations such as single step and step over do not capture enough information to allow the displays to be updated. A recommended way to capture EnergyTrace data is to select Run → Free Run from the main menu and let the target run for around 20 seconds. Before 20 seconds elapses, a message should be displayed in the lower right corner saying that the EnergyTrace Capture is complete:

_images/ccs_debug-et_complete.png

If this does not occur within 20 seconds, halt the processor and repeat the procedure.

Once the EnergyTrace capture is complete, a Trace tab will be opened or updated to show the following displays:

_images/ccs_debug-et_displays.png

From top to bottom:

  • Overview: Graph of the entire captured current waveform

  • Current: Graph that shows the region of the Overview graph after zooming and panning (see below for more info)

    • The X-axis is time in seconds. The time axis associated with the Current graph is shown above the Current graph
    • The Y-axis is the current in nano-Amperes (nA).

  • Summary: Provides information about the captured EnergyTrace data over the entire capture duration

  • Records: Displays a table of the raw EnergyTrace data that was captured

Hovering the mouse pointer over specific data in the view will pop-up additional information.

7.6.6.2. Zooming and Panning

The Overview graph displayed at the top of the Trace tab provides the ability to select a region of the captured data for closer inspection. The Current graph located below the Overview graph shows the selected region, and auto-scales the Y-axis automatically. The following operations on the Overview graph are provided in order to allow the user to select a specific region for display in the Current graph:

  • Zoom: To zoom in to our out from a region of data in the Overview graph, click on the graph and do the following:

    • Ctrl + mouse wheel: push the mouse wheel forward (away from you) while holding down the ctrl key to zoom in, and pull the wheel backwards (towards you) while holding down the ctrl key to zoom out

  • Pan: To shift the selected region left or right in the Overview graph, with the Overview graph in focus do the following:

    • Ctrl + shift key: push the mouse wheel forward while holding down the shift key to pan left, pull the wheel backwards while holding down the shift key to pan right.
    • Horizontal scroll bar: the horizontal scroll bar underneath the Current view also can be used to pan left or right

7.6.6.3. EnergyTrace Tab Toolbar

In the upper right corner of the bottom panel, a toolbar is displayed which provides the following features. These can be used, for example, if you do not have a wheel mouse connected to your computer.

_images/ccs_debug-et_toolbar.png

From left to right, these icons are:

  • Undo: Undoes the last operation
  • Redo: Re-does the last operation that was undone
  • Zoom In: Click this button to narrow the region selected in the Overview graph
  • Zoom Out: Click this button to widen the region selected in the Overview graph
  • Reset: Click this button in order to re-sync and re-align the Overview graph and the Current graph relationship. Repeated zoom and pan operations or use of the undo / redo buttons can cause the zoom region displayed in the Overview graph to become out of sync with the time region displayed by the Current graph, and clicking this button will re-sync them.
  • Show trace overview: If you close the Overview graph, you can re-open it by clicking on this button
  • Keyboard Shortcuts: Displays a popup box with information about how to navigate through the graphs using keyboard shortcuts

7.6.6.4. Changing the Maximum Capture Duration

By default, the Maximum Capture duration that EnergyTrace is configured for is set to 10 seconds. You can change this value as follows:

  1. Click on the Preferences → Settings icon in the lower left corner of Code Composer Studio
  2. Select General Settings from the context menu that is displayed
  3. In the search bar at the top of the Settings tab, type "trace duration"
  4. Enter the number of seconds you wish to capture

7.6.6.5. Saving EnergyTrace Summary Data to a CSV File

To save the contents of the EnergyTrace Summary table to a file, select the Show View Options button in the upper left corner of the Summary display and select Export to csv.

7.6.6.6. References

See the below page for more resources on EnergyTrace:

7.6.7. EnergyTrace++™

EnergyTrace++™ proves the same core functionality as EnergyTrace with the additional features below:

  • Correlates the energy consumption with the CPU states, including whether the device is in active mode or one of the many low-power modes (LPM)
  • Shows the ON-OFF status of the peripherals and all system clocks (regardless of the clock source) while it is running

EnergyTrace++ in Code Composer Studio is currently supported on the following devices families:

  • MSP430FR59xx/69xx
  • CC13xx/CC26xx (requires XDS110 HDR support)

All the information in the above EnergyTrace™ section applies to EnergyTrace++ with the exception of selecting the EnergyTrace++ option in the menus/views when available. One other main difference is the addition of an extra view in the Trace tab called the States view:

_images/ccs_debug-etpp_states.png

This view provides a graphical representation of the various power states (PowerMode) of the CPU and active state of the device peripherals and system clocks (Peripheral) over time.