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 CCS Theia:

  • 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

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 CCS 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 CCS Theia 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 CCS Theia, 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
  • 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, open the Core Trace tab and disable the EnergyTrace icon. Clicking on the Core Trace icon again will disable Core Trace and enable the EnergyTrace icon again
  • EnergyTrace button will enable EnergyTrace, open the EnergyTrace tab and disable the Core Trace icon. Clicking on the EnergyTrace icon again will disable EnergyTrace and enable the Core Trace icon again
  • Trace Serer status icon reflects the status of the Trace Server, which handles all of the low level details involved with capturing and displaying trace data

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

When either Core Trace or 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 both the Core Trace icon and EnergyTrace icon 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 CCS for further post processing and displayed in the CCS trace views. CCS 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 CCS Theia 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 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 type of Core Trace, though more limited in scope than some other implementations.

ERAD Trace is only available for F28P65x based devices.

See the below article for more information on ERAD 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.

_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 the opcode 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.

Warning

ERAD based core trace will only display PCs discontinuities - PC pairs of branch and destination. Full display of all addresses between the discontinuities will be available in a future release.

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. EnergyTrace™

EnergyTrace™ technology is a power analyzer tool for CCS Theia 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 CCS Theia is currently supported on the following devices families:

  • MSPM0
  • MSP430

Note

EnergyTrace™ is available on CCS Theia Windows and Linux desktop hosts only.

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

7.6.5.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.5.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.5.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 CCS Theia
  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.5.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.5.6. References

See the below page for more resources on EnergyTrace: