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

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

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

MTB

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 based devices.

See the below article for more information on ERAD itself:

ERAD

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-A53

ARM Cortex-R5

ARM Cortex-M4 (only on select devices)

See the below article for more information on ETB itself:

ETB

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¶

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. Note that the Seq. column denotes the PC Discontinuity that each entry is associated with.

7.6.4.2.2. ETB¶

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

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

CC13xx/CC26xx

Note

EnergyTrace™ is available on CCS Theia 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:

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:

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

Click on the Preferences → Settings icon in the lower left corner of CCS Theia
Select General Settings from the context menu that is displayed
In the search bar at the top of the Settings tab, type "trace duration"
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:

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

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.

7.6. Trace¶

7.6.1. Glossary¶

7.6.2. Trace Tab¶

7.6.3. Trace View¶

7.6.4. Core Trace¶

7.6.4.1. Types of Core Trace¶

7.6.4.1.1. MTB Trace¶

7.6.4.1.2. ERAD Trace¶

7.6.4.1.3. ETB Trace¶

7.6.4.2. Starting Core Trace¶

7.6.4.2.1. MTB/ERAD¶

7.6.4.2.2. ETB¶

7.6.4.3. Source and Disassembly View Correlation¶

7.6.4.4. Example Use Cases¶

7.6.5. Custom Core Trace¶

7.6.6. EnergyTrace™¶

7.6.6.1. Starting EnergyTrace¶

7.6.6.2. Zooming and Panning¶

7.6.6.3. EnergyTrace Tab Toolbar¶

7.6.6.4. Changing the Maximum Capture Duration¶

7.6.6.5. Saving EnergyTrace Summary Data to a CSV File¶

7.6.6.6. References¶

7.6.7. EnergyTrace++™¶