Debugging With Trace

Overview

XDS560 Trace (or Trace) is a very powerful tool that can be used to locate some of the most complex and inconspicuous code defects. However, Trace itself is a very complex tool, and it's capabilities and limitations need to be understood to use it effectively.

Introduction

The XDS560 Trace System provides Logic Analyzer like recording and playback of processor core PC, Memory and Event activity. The trace system consist of multiple components that are split between the device, XDS and CCS software on the host.

• Device components provide:

- Complex triggering (Advance Event Triggers)

- Data alignment (Trace Pipeline Flattener)

- Trace data compression

- On-chip collection (if ETB supported) for shallow collection (typically 4KB) and external export (through EMU pins) for deep collection (256K-64MB)

• Trace data collection facilitated through either:

- On-chip Embedded Trace Buffer (ETB)

• Any XDS may be used
• Typically very shallow buffer size (4-8K Bytes)
• Primary use case is debug
• May also be used remotely in field deployed products to capture exceptions (XDS not required)

- XDS capable Trace Receiver (XDS560 Trace Pod and XDS Pro Trace Receivers) for pin export of trace data:

• Collects and stores trace data in the XDS (XDS560T supports up to 64MB and XDS Pro Trace Receiver would support upto 2 GB)
• Manages trace buffer size, and operation mode - stop when full or wrap
• Provides calibration support for skew and signal margin
• Use cases include debug and profiling.
• See Trace XDS Requirements for additional information

• CCS host components provide:

- Setup and configuration

- Decode of compressed trace data

- Display with navigation and search capabilities

Trace Use Cases

Trace can be used for both debugging and profiling. Trace can be used to debug difficult problems where visibility to program execution, timing, or CPU data access history is required. Profiling can be used to identify bottlenecks in your application. Event trace can provide visibility to specific memory or system events that may be causing performance issues.

See Trace Use Cases for more details on debugging and profiling use cases.

Before using trace you should:

- If debugging understand and characterize the problem first. See Trace's Place in the Debug Tool Box for more discussion on why this is important.

- Understanding the Trace System's limitations.

What's in a Device to Facilitate Trace

TI devices typically support PC, timing, data and event trace streams. Within the device Advance Event Triggering (AET) is used to define both a trace trigger and what to trace. Trace export can be to either an ETB or the EMU pins for external capture. See Trace Device Features for details.

What's in CCS to facilitate trace

CCS is used to:

• Set trace triggers to control the export of trace data through Breakpoint jobs
• Set system wide export and capture options through Trace Control

See Trace CCS Features for details and examples.

CCS Target Configuration

When creating the target configuration file in CCS make sure to select the emulator that is connected to your 560T trace cable. This is typically the Blackhawk USB560-M emulator.

Trace Debug Examples

• Using Trace with an Embedded Trace Buffer (ETB)

- The ETB can be used with a standard XDS (XDS560T cable pod not required) to capture trace data. Because ETBs are shallow (7K to 10K samples typical) and only support circular buffer mode, the best method for capturing a bug is to use an End All Trace job to stop trace export either as the problem is occurring or shortly after the problem has occurred.

- The CCS Trace ETB Video shows step-by-step setup and expect results. The example presented will work equally well with an XDS560T.

- Using Trace with an ETB quick reference

• Using Trace to Capture Processor Exceptions

- Trace can be used to capture the cause of processor exceptions. Typically the processor captures the exception type and PC of the exception, but the actual cause of the exception could be many instruction behind where the actual exception context switch occurs.

- The CCS Trace Exception Video shows step-by-step setup and expect results. The example presented will work equally well with an XDS560T or ETB. With the ETB your trace depth will be limited to 7K-10K trace samples.

- Using Trace to Capture Processor Exceptions quick reference

• Using Trace to Capture Buffer Corruption

- Trace can be used to capture the instruction that wrote an invalid value to a buffer. Typically when debugging corruption problems you really need to look backwards in time to determine what sequence of events caused the corruption. If you know the location and corrupting value, an End All Trace job can be used to stop trace on the instruction that wrote the invalid value.

- The CCS Trace Buffer Corruption Video shows step-by-step setup and expect results. The example presented will work equally well with an XDS560T or ETB. With the ETB your trace depth will be limited to 7K-10K trace samples.

- Using Trace to Capture Buffer Corruption quick reference

Trace Profiling Examples

Cycle Accurate Trace Profiling with CCS Examples

• Cycle accurate trace profiling works best with an XDS560T because it can stop trace collection when the trace capture buffer fills and it supports deep trace buffers.
• When profiling your application you will need to set the trace buffer size large enough to accommodate your test case execution time. Using trace buffers larger than 1MB may take excessive time to decode.
• The Function Profile Video shows step-by-step setup instructions and expected results. The video covers:

- Function-Level Cycles Profile

- Function-Level Pipeline Stalls Profile

- Per-call Function profiling

- Function Execution Graph

- Program Address vs. Cycle

Trace Profiling using Scripts

See this section for details on scripts for:

• Statistical Profiling
• Dynamic Thread Aware Call Graph
• Pipeline Stall Analysis
• Event Analysis

cToolsLib Application libraries

• cToolsLibs can be used with CCS to capture (with ETB or XDS560T) and display trace data or can be used to facilitate remote trace (independent of an XDS and CCS)
• All cToolsLib Libraries are released with Doxygen API Reference Guides.
• Libraries supported:

- DSPTraceLib Provides setup of trace data export for ETB capture.

- ETBLib Provides setup of the DTF and ETB modules, and retrieval of the trace data. Note that ETBLib currently only supports TCI6488. ETBLib may need to be ported to other devices.

- AETLib provides setup of trace triggers required to export trace data.

• User must provide transport of binary trace data to a host for decode with td.exe.
• Format of trace data for consumption by td.exe must be binary trace data that is in the same form as retrieved from the ETB (with ETBLib). Any transport added data such as packet headers must be striped, any conversions applied to the data (endian) must be reversed).

See Capturing Trace Data with ETB and cToolsLibs for more details. The cToolsLibs can be downloaded from gforge.

Related

• XDS560 Trace
• Trace
• Advanced Event Triggering
• CToolsLib
• ETB
• AET Logic