Embedded Trace Buffer

What is it? What does it do?

Trace provides a detailed, historical account of application code execution, timing, and data accesses. This information is useful for finding bugs and performance analysis. Trace works in real-time and does not impact the execution of the system.

ETB is an on-chip circular memory buffer where the compressed trace information is stored. The size of the buffer depends on the chip implementation. Typical sizes are between 2-8k. Because of the compression, the user will get roughly 10k to 30k lines of program trace. This buffer operates as a circular buffer, continuously capturing trace information until the halted.

When a program fails, if the trace buffer is enabled, you can see a portion of program history. With this program history, it is easier to walk back through your program to see what happened just before the point of failure. This is particularly useful for investigating intermittent and real-time failures, which can be difficult to identify through traditional debug methods that require stopping and starting the processor. The use of hardware tracing can significantly reduce the amount of time needed to find these failures.

How to get started with CCS Embedded Trace Buffer (ETB) Trace tooling

Texas Instruments XDS560v2 Trace tooling supports triggering, collection and decode/analysis of trace information in Code Composer Studio debug environment via JTAG. All the needed support is part of CCS . User can connect, setup ETB and collect via a XDS100, XDS110, XDS200, or XDS560v2 class JTAG emulators. A Quick Reference Guide is available to setup and collect ETB trace via Code Composer Studio help menu.

See How and When to Use Trace for help with determining when to use trace.

• Start CCS setup and import or define your device connection
• Make sure that you have ETB (ETB11 or CSETB) correctly in your CCS setup as per your device.
• Once setup is completed, connect the target (and ETB, if added as a node in setup)
• Connect target and open CCS window for the CPU; build your app and load the out file to the target.
• Open “Trace Control” using Tools->Trace Control menu. Click on the “Receiver” button. If the pop-up dialog box comes up with “ETB” selection, no further action is needed; cancel the dialogs. See ETB Trace System Control for details.
• If “ETB” is not selected, select ETB and press OK. Press OK on the main dialog box as well. This is one time setup step and in the subsequent sessions, this information is reused from previous session settings.
• From CCS, apply Trace triggering rules to define rules to generate and control trace export. Use Windows->Show View->Breakpoints menu to open triggering pane.

• Select "New" -> "Trace" to create a new Trace trigger rule and right click on the rule to open and setup Trace properties. Following triggering "Actions" are available. You can use one or more of these to define your trace triggering rules and "What to Trace" (PC timing data etc).
  • Trace ON – Trace always
  • Start Trace – Trace start at given PC
  • End Trace – Trace stop at given PC; used in conjunction with Start Trace
  • Trace In range – Trace In give PCs range
  • Don’t Trace In range – Do not Trace In give PCs range
  • Trace Variable – Trace given data variable and/or range

See Trace Jobs for additional details.

• Once done, submit/enable the triggering rule by clicking the check box for the "Action" in the "Breakpoint" view.

• Once a triggering rule is applied successfully, you would notice a Trace Display popping up.
• Now you can start you execution and Trace will start as per your triggering rules.
• Trace would stop when you halt target or when you start trace collection from Trace Display by pressing ‘Stop” button.
• You can view and analyze Trace information in Trace Display Analyzer

 

ARM/Cortex Trace

• Tutorial: Using ETB with ARM processors Media:ArmETBv2.pdf (**** Support is available in CCSv4/CCSv5 even if the document demonstrates example in CCS v3 context ****)

Device Support

Please check your datasheet for details. The Embedded Trace buffer is available and has been used on the below example devices:

• ARM926: DM644x, DM646x, DM33x, DM35x, DM36x, OMAP-L13x, AM17x, AM18x.
• ARM11: OMAP2420, OMAP2430
• Cortex-A: all AM devices (AM335x, AM35xx, AM37xx, AM38xx), DM37xx, DM81xx, OMAP34xx, OMAP35xx, OMAP44x.
• Selected C6000 devices: TNETV3020, TCI648x, TCI66xx, C66xx
• DSP+ARM: C6A816x (single shared ETB)
• Devices with NO ETB support: Cortex-M, Cortex-R, C645x, C642x, DM64x, DM643x, C64x, C62x, C67x, C55x, C54x, C28x, C24x.

Note: In the case of multicore DSPs (C6000 devices) each core has a dedicated ETB. Unless otherwise noted ubove, all other multicore devices have an ETB for the main ARM core only. For example, a DM8148 has ETB for the Cortex-A core only.

Decoding from Memory dumps

To decoder trace from a binary dump of the ETB memory, two tools are avaialble:

Bin2TDF utility

• Refer here for the detail on using BIN2TDF
  

TD utility

• Refer here for the detail on using TD
  

Frequently Asked Questions

Q: In order to use the ARM ETB on the DM355/DM365/DM644x/DM646x/OMAPL13x, do we have to use Code Composer Studio? Or is there another tool that supports ETB capability?

A: In order to use the ARM ETB, you need to use some debugger to get the full ETB capability. There is no means for using the ETB from within the application running on the device. Code Composer Studio is one debugger that can be used to get full ETB trace, and the only one provided by Texas Instruments. Other companies may provide tools that give similar capability.

The free, open-source OpenOCD JTAG debug software has some (at the time of writing, very basic) support for ARM ETM, ETB and DaVinci EVM boards. Contributions and improvements are welcomed.

Note that the ETB for DM355/DM365/DM644x/DM646x devices is located at ICEpick port 0x11.

Q: What if trace depth beyond the size of the built in buffer is required? Can the buffer operate in some kind of FIFO mode, or do we have to halt the processor and resume after the ETB is emptied.

A: The Embedded Trace Buffer can only operate in Circular Buffer Mode. However, a trigger can be configured to stop target tracing when a buffer is full. This trigger has 3 settings Before, Middle, and After. The setting specifies where this trigger will be located in the trace buffer. A setting of "After" effectively tells trace to stop being captured when the buffer is full. Note that the options available for ETB depend on the type of ETB present. For example the above settings are valid for ARM9 ETB but are not valid for the ETB present on C6474.

Q: What do I need to use it?

A: ETB requires a hardware connection to the target and software:

Hardware:

• A device that includes an ETB
• JTAG Emulator: Any XDS class

Software:

• CCSv5.x and newer
• CCSv4.2
• CCSv3.3 + CCS Service Release 8 or newer.

Q: Is there a special JTAG header needed to use the ETB? / I just have a basic JTAG connection, can I use the ETB?

A: No special header is needed to use the ETB. Only the standard JTAG signals are used for ETB acccess. Please see JTAG Connectors for information. The EMU0/1 pins are not used for ETB access. An ETM port on the card is not needed to access the ETB, just a basic JTAG connection.

Q: How can I figure out whether I have a HW problem or a SW problem with accessing the ETB?

A: If your debugger can access the device, and can load, run, halt, step the processor, the JTAG connection to the device is working, and there should be no HW issue and the issue will likely be with SW configuration or usage. If you cannot access the processor, then the problem can be either in SW processor setup (ex: CCS Config) or in hardware. Please see Debugging JTAG Connectivity Problems for tips.

Q: Can I read the ETB memory from the ARM on the OMAP34xx/OMAP35xx?

A: Yes, the ETB memory should be available to be read, though it would need to be read one-word at a time. Please see ARM ltd. documentation on ETB and ETM access/programming. Once read, you could decode the buffer using the tools described here: Embedded Trace Buffer#Decoding_from_Memory_dumps

When using the application to read the ETB, you cannot be putting trace information into the ETB. Accessing the ETB programmatically is described here. Note that it uses an in-direct register address scheme to read the values.

Q: When I tried to enable ETB from Trace Control, it says, "ETB device definition cannot be loaded. Device not supported" What is wrong?

A: This can be caused because the device definition is not available in CCS and it cannot load the device toplogy to setup trace. In CCS 3.3 the device definition XML files can be found in CCS_INSTALL/cc/bin/trace_devices directory. If you do not find yopur device file in the directory, it means the device definition is not added to the release or you have an older release. You can easily add new device by copying a similar file in the dir. You just need to update the file making sure that the deviceid is correct for the device you are using and you have right set of cores/cpus and associated trace modules (such as ETB). Some additional details are below. Use support if you can't get sufficient information to build a definition file.

• For AM3517 user, please download and unzip this file Media:Device_omap3430.zip to [CCSV4_DIR]\ccsv4\emulation\analysis\xmldb\trace_config\devices directory to replace current device_omap3430.xml. This file is only valid for ccsv4.0 and ccsv4.1 build.

• A: Note that the JTAG is working fine for everything except for the ETB. You should also check to see whether there is an ETB configuration on your setup. The problem is because the XDS560 Trace control device defintition database does not contain the proper JTAG ID and thus reports the device is not supported. Please report such errors to: https://e2e.ti.com/support/development_tools/code_composer_studio/default.aspx with your device part #, revision, CCS version and emulator model and type. This problem was fixed in CCS versions newer than v4.0.
• A: A temporary fix can be implemented in CCS v3.3 if you have the JTAG deviceID. DO NOT ATTEMPT THIS UNLESS YOU ARE EXPERIENCED WITH WINDOWS AND CCS. If you don't have it, it can be found following the instructions below:

1. Set the Windows environment variable "TI_TRACE_LOGGING" to 6.
2. Search for the trace log. It is likely in \ccs\bin and will be a text file.
3. Open the text file and search for the line, ""DevId: Mask value is 0xfffffff xmlId: 0x9202f devId: 0x9202f" where 0x9202f is the number for your device.
4. Goto the \cc\bin\trace_devices directory and search for a file such as device_arm9etb11.xml (for an ARM9 based device with an ETB11)
5. Copy the arm9etb11.xml to a new file.
6. Edit the new xml file and change the device value to be the JTAG ID that you found for your device. For example, <device id="DM6446" value="0x0b70002F".....> you would need to change the 0x0b70002F to your new JTAG ID.
7. Close and run CCS and try ETB again.

Q: How to add CSETB node to Omap3XXX device setup file in ccsv4?

Answer:

1. First, double click on an existing Omap3XXX device setup file in ccsv4's "Target Configurations" section to bring up detail setup configuration.
2. Once target configuration is opened, click on the "Advanced" tab at the bottom to bring up advanced section.
3. Click on CS_DAP_PC_0 on the configuration, and then click on "Add" button. Highlight "subpath" inside "subpath(1)" box and click on Finish button. You will see a new subpath_X is added under CS_DAP_PC_0.
4. Highlight newly added subpath_X node, make sure "Force Configuration" and "Pseduo" options in Subpath Properties panel are checked.
5. Highlight subpath_X again. Click on "Add" button. Select Cpus tab and highlight CSETB from the list then click on Finish.
6. In the Cpu Properties panel, enter CSETB's base address to Address text box. The base address value for CSETB on Omap3 is 0x5401b000.

This is the screen shot of what the configuration looks like using Omap3430 as an example:

Q: What kind of capacity can the ETB hold for 64x+ DSP trace?

• A: The trace data collected can vary significantly based on the application and the type of information being captured. For example, it is most efficient to only capture program instructions. Adding timing information will increase the volume of information being captured, thus decreasing the amount of trace that can be captured into an ETB or an XDS560 Trace. Turning on Data trace will further increase the volume of information and decrease the amount of trace that can be captured into an ETB or an XDS560 Trace. In one experiment using the etblib_demo example, we can capture approxiamtely 7500 instructions of program trace into a 4Kb buffer. This application has many small functions and thus many branches which cannot be compressed efficiently. With fairly linear code execution, >20000 samples are possible in a 4Kb buffer on the 64x+, with 10000 being average.

Q: does ETB work without AET on the 64x+?

• A: No, you need the AET unit to trigger trace on and off. The ETB is merely the trace collection mechanism. The other trace collector for DSP Trace is XDS560 Trace.

Q: Does ETB work with ETB 11 on Spectrum Digital XDS510 USB?

• A: Yes. This should be included with the latest Spectrum Digital drivers.

Q: Can I transport the ETB information across Ethernet/SRIO/HPI, etc. without using JTAG?

• A: yes, please see Capturing ETB Trace Data With ETBLib

Related

• See: XDS560 Trace
• See: Advanced Event Triggering
• See: Capturing ETB Trace Data With ETBLib