Embedded Trace Buffer
From Texas Instruments Embedded Processors Wiki
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 XDS560 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 3.3 with Service Release (SR8) or later. User can connect, setup ETB and collect via XDS560 class JTAG emulators. A Quick Reference Guide is available to setup and collect ETB trace via Code Composer Studio help menu.
- Start CCS setup and import or define your device connection
- Make sure that you add ETB (ETB11 or CSETB) correctly in your CCS setup as per your device. This step is not needed for TCI6486 and TCI6488 devices.
- 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->XDS560 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.
- 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 Tools->XDS560 Trace->Setup menu to open triggering rules pane.
- Select "New" -> "Trace" to open up Trace setup 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
- 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
Additional reading on XDS560 Trace and ETB
- Detailed help on Trace and ETB tooling can be found in CCS Trace help sections.
- Tutorial: Using ETB with ARM processors Media:ArmETBv2.pdf
- Also read the section on AET and XDS560 Trace
Device Support
Please check your datasheet for details. The Embedded Trace buffer is available and has been used on the below example devices:
- Devices with ARM926 (ex: TMS320DM646x, TMS320DM644x, TMS320DM643x, TMS320DM3x, OMAP-L137, TMS320DM335).
- ARM11: OMAP2420, OMAP2430
- Cortex A8: OMAP34xx, OMAP35xx, AM35xx (available in CCS v4)
- Selected 64x+ devices: TNETV3020, TCI6487, TCI6488, etc.
- Devices with NO ETB support: 6455
Decoding from Memory dumps
To decoder trace from a binary dump of the ETB memory, two tools are avaialble:
Bin2TDF utility
- BIN2TDF utility (found in CCStudio_v3.3/cc/bin)
- Converts the raw ETB data into a Trace Data Format (TDF) file used by the XDS560 Trace display
- The TDF file can be opened with Code Composer Studio's Trace Display Analyzer in a standalone mode.
- Get help by "-help" option from command line
TD utility
- TD utility (located in CCStudio_v3.3/cc/bin)
- Converts the raw ETB data into a human readable text file or comma separated CSV file.
- Multiple options to format output as required by user
- Get help by "td.exe -help"
Sample command line using td.exe: C:\CCStudio_v3.3\cc\bin\td.exe -cpuid 6600 -sirev 3 -bin C:\test\FaradayETB\binfile.bin -coffname C:\test\FaradayETB\testapp.out -rcvrname ETB -dcmfile empty.txt
Sample output of td.exe
| ======================================================================================= Program Address Load Address Program Data Read Address Read Data Read Size (In Bits) Write Address Write Data Write Size (In Bits) Cycles Stall Cycle Data Memory/Cache Event External Event Target State Data Trace Status Tpos ======================================================================================= -------- -------- -------- -------- ---------------- -- -------- ---------------- -- ------ -- -- -- -------- Start of trace ---- -------- -------- -------- -------- ---------------- -- -------- ---------------- -- ------ -- -- -- -------- Incomplete frame, Missing start of frame marker, 00802368 00802368 00000427 -------- ---------------- -- -------- ---------------- -- 000001 -- -- -- -------- PC collection off, Timing collection off ---- 008022b0 008022b0 0000dc0d -------- ---------------- -- -------- ---------------- -- 000005 -- -- -- -------- PC collection on, Timing collection off ---- 008022b2 008022b2 00002401 -------- ---------------- -- -------- ---------------- -- 000001 -- -- -- -------- -------- ---- 008022b4 008022b4 0000dc05 -------- ---------------- -- -------- ---------------- -- 000001 -- -- -- -------- -------- ---- 008022b6 008022b6 00002c6e -------- ---------------- -- -------- ---------------- -- 000002 -- -- -- -------- -------- ---- 008022b8 008022b8 0191c028 -------- ---------------- -- -------- ---------------- -- 000001 -- -- -- -------- -------- ---- 008022c0 008022c0 01804068 -------- ---------------- -- -------- ---------------- -- 000001 -- -- -- -------- -------- ---- 008022c4 008022c4 023c22e4 -------- ---------------- -- -------- ---------------- -- 000001 -- -- -- -------- -------- ---- 008022c8 008022c8 000c1362 -------- ---------------- -- -------- ---------------- -- 000001 -- -- -- -------- -------- ---- 008022cc 008022cc 01856162 -------- ---------------- -- -------- ---------------- -- 000004 -- -- -- -------- -------- ---- 008022d0 008022d0 023d805a -------- ---------------- -- -------- ---------------- -- 000001 -- -- -- -------- -------- ----
|
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.
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.
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: XDS560 (Spectrum Digital XDS510 may also support this capability)
Software:
- CCS 3.3 + CCS Service Release 8 or newer.
- CCS v4.x
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:
- Set the Windows environment variable "TI_TRACE_LOGGING" to 6.
- Search for the trace log. It is likely in \ccs\bin and will be a text file.
- 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.
- 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)
- Copy the arm9etb11.xml to a new file.
- 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.
- Close and run CCS and try ETB again.
Q: How to add CSETB node to Omap3XXX device setup file in ccsv4?
Answer:
- First, double click on an existing Omap3XXX device setup file in ccsv4's "Target Configurations" section to bring up detail setup configuration.
- Once target configuration is opened, click on the "Advanced" tab at the bottom to bring up advanced section.
- 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.
- Highlight newly added subpath_X node, make sure "Force Configuration" and "Pseduo" options in Subpath Properties panel are checked.
- Highlight subpath_X again. Click on "Add" button. Select Cpus tab and highlight CSETB from the list then click on Finish.
- 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.
More information
- See: XDS560 Trace
- See: Advanced Event Triggering
