MCSDK UG Chapter Developing Debug Trace

---

---

Developing with MCSDK: Debug and Trace

Last updated: 02/28/2014

Overview

This chapter provides information on tools for debug and trace.

Acronyms

The following acronyms are used throughout this chapter.

Acronym	Meaning
CCS	Texas Instruments Code Composer Studio
DSP	Digital Signal Processor
DVT	Texas Instruments Data Analysis and Visualization Technology
IP	Internet Protocol
JTAG	Joint Test Action Group
MCSA	Texas Instruments Multi-Core System Analyzer
MCSDK	Texas Instruments Multi-Core Software Development Kit
TI	Texas Instruments
UART	Universal Asynchronous Receiver/Transmitter
UIA	Texas Instruments Unified Instrumentation Architecture

Trace Framework

The trace framework in PDK supports the ring producer and consumer libraries.
Please refer to pdk_keystone2_1_00_00_##\packages\ti\instrumentation\traceframework\docs\html\index.html

for traceframework library API information
Please refer to \pdk_keystone2_1_00_00_##\packages\ti\instrumentation\traceframework\docs\trace_frmwrk_ug.pdf

for the traceframework concept and example applications.

The system level representation for the trace framework library is as below.

Note:
System Analyzer's Tutorial 5B is now available at System_Analyzer_Tutorial_5B link - it covers using LoggerStreamer and the PDK Trace Framework ‘producer/consumer’ model.
Trace Framework on DSP depends on UIA, UIA is a DSP component that is included in the MCSDK installer. The documentation for the UIA packages are in the docs folder, that contains the system analyzer's user guide. UIA’s API documentation can be located from CCS’s help window (Help->Help Contents).

Trace Framework Library Summary
Component Type	Library
Install Package	PDK for keystone2
Install Directory	pdk_keystone_<version>\packages\ti\instrumentation\traceframework
Project Type	CCS
Endian Support	Little & Big
Library Name	Select for the TCI6638 EVM ti.instrumentation.traceframework.ae66 (little) ti.instrumentation.traceframework.ae66e (big)
Linker Path	$(TI_PDK_INSTALL_DIR)\packages\ti\instrumentation\traceframework\lib - for release version
Linker Sections	.tf_genLogBuffersNull
Section Preference	none
Include Paths	$(TI_PDK_INSTALL_DIR)\packages\ti\instrumentation\traceframework\traceframework.h
Reference Guides	See docs under Install Directory
Support	Technical Support
Additional Resources	Texas Instruments Embedded Processors Wiki
Downloads	Product Updates
License	BSD

cToolsLibrary

The cTools library provides APIs for using the individual instrumentation libraries for advanced users and also few use case based libraries that are built on top of the individual instrumentation libraries.

As shown in the figure below, the ctoolslib_sdk module provided in the package is intended to provide the glue between the use case based libraries, individual instrumentation libraries and application:

cToolsLibrary SW architecture

The ctoolslib_sdk is a collection of libraries for Advanced Event Triggering(AET), Common Platform Tracers(CPT), Ctools use case library(Ctools_UC), DSPTrace, Embedded Trace Buffer(ETB) and System Trace Module(STM) - located under \aet\lib, \CPTLib\lib, \Ctools_UCLib\lib, \DSPTraceLib\lib, \ETBLib\lib and \STMLib\lib

Note: To run examples, import the included CCS project. If KeyStone II folder does not exist, set "C6678Debug" as the active build configuration for KeyStone II.

Ctools Library Package Summary
Component Type	Library
Install Package	CtoolsLibrary for keystone2
Install Directory	ctoolslib_<version>
Project Type	CCS
Endian Support	Little & Big
Library Name	Select for the KeyStone2 EVM Please see GettingStarted.htm for details
Linker Path	$(TI_CTOOLSLIB_INSTALL_DIR)\packages\ti\LIBRARY_NAME\lib - for release/debug version, where LIBRARY_NAME = aet, CPTLib, Ctools_UCLib, DSPTraceLib, ETBLib and STMLib.
Linker Sections	none
Section Preference	none
Include Paths	$(TI_CTOOLSLIB_INSTALL_DIR)\packages\ti\LIBRARY_NAME\include\*.h and ti\ctoolslib_sdk\evmk2h\package.xdc define the interface for keystone2 EVM use case library support
Reference Guides	See doc\*html*\index.html file under respective libraries for details and CtoolsLib
Support	Technical Support
Additional Resources	Texas Instruments Embedded Processors Wiki
Downloads	Product Updates
License	BSD

ctools Image processing Demo example

MCSDK demonstrates Common Platform Tracer (CPT) capabilities using image processing demo as an application. Please refer to Image processing demo guide for details on the demo and steps to be followed to run it on the KeyStone2 EVM. The instrumentation examples are provided on the IPC version of the demo. Please refer to Run instructions and Expected output for details on steps to be followed and expected output for use case based MCSDK instrumentation examples. The following are the supported use cases:

1. System Bandwidth Profile
   1. Captures bandwidth of data paths from all system masters to the slave (or) slaves associated with one or more CP Tracers
   2. Demo: For the Image demo, instrument the external memory (MSMC & DDR3) bandwidth used by all system masters
2. System Latency Profile
   1. Captures Latency of data paths from all system masters to the slave (or) slaves associated with one or more CP Tracers
   2. Demo: For the Image demo, instrument the external memory (MSMC & DDR3) Latency values from all system masters
3. The CP tracer messages (system trace) can be exported out for analysis in 3 ways:
   1. System ETB drain using CPU (capture only 32KB (SYS ETB size in keystone devices) of system trace data)
   2. System ETB drain using EDMA (ETB extension to capture more than 32KB (SYS ETB size in keystone devices))
   3. External Emulator like XDS560 PRO or XDS560V2
4. Total Bandwidth Profile
   1. The bandwidth of data paths from a group of masters to a slave is compared with the total bandwidth from all masters to the same slave.
      1. The following statistics are captured:
         1. Percentage of total slave activity utilized by a selected group of masters
         2. Slave Bus Bandwidth (bytes per second) utilized by the selected group of masters
         3. Average Access Size of slave transactions (for all system masters)
         4. Bus Utilization (transactions per second) (for all system masters)
         5. Bus Contention Percentage (for all system masters)
         6. Minimum Average Latency (for all system masters)
      2. Demo: For Image Demo, compare DDR3 accesses by Core0 (master core) with the DDR3 accesses by all other masters (which includes Core1, Core2…)
5. Master Bandwidth Profile
   1. The bandwidth of data paths from two different group of masters to a slave is measured and compared.
      1. The following statistics are captured:
         1. Slave Bus Bandwidth (bytes per second) utilized by master group 0
         2. Slave Bus Bandwidth (bytes per second) utilized by master group 1
         3. Average Access Size of slave transactions (for both the master groups)
         4. Bus Utilization (transactions per second) (for both the master groups)
         5. Bus Contention Percentage (for both the master groups)
         6. Minimum Average Latency (for both the master groups)
      2. Demo: For Image Demo, compare DDR3 accesses by Core0 and Core1 with the DDR3 accesses by Core2 and Core3
6. Event Profile
   1. Capture new request transactions accepted by the slave. Filtering based on Master ID or address range is supported.
      1. The following statistics are captured for every new request event: Master ID which initiated this particular transaction
         1. Bus Transaction ID
         2. Read/Write Transaction
         3. 10 bits of the address (Address export mask selects, which particular 10 bits to export)
      2. Demo: For Image Demo, implement a Global SoC level watch point on a variable in DDR3 memory. Only Core0 is intended to read/write to this DDR3 variable. Unintended accesses by other masters (or Cores) should be captured and flagged.
7. Statistical profiling provides a light weight(based on the number of Trace samples needed to be captured) and coarse profiling of the entire application.
   1. PC trace is captured at periodic sampling intervals. By analyzing these PC trace samples, a histogram of all functions called in the application, with the following information:
      1. percent of total execution time
      2. number of times encountered
   2. Demo: In the Image Demo, Statistically profile the process_rgb() function, which processes a single slice of the Image.

Ctools PC trace example

There is a hardsupport for logging the PC trace in KeyStone2 in the ETB (Extended Trace Buffer), which is 4Kb in size. The Program Counter Trace along with Timing trace examples are located under \mcsdk_bios_#_##_##_##\examples\ctools\evmtk2h folder. The examples include the following.

PC Trace where ETB is drained by CPU

This demonstrates the PC trace where ETB is drained by CPU. The PC Trace can be logged in either circular mode or stop mode to get 4Kb encoded PC trace information. Please follow below steps.

1. Power Cycle the EVM, make sure the EVM is brought up with Linux and you get to root prompt on the console.
2. Open CCS
3. Connect to DSP Core 0
4. Load the DSP ELF executable provided in the Example's Debug folder on DSP Core 0.
5. After the program is executed, the trace bin file gets generated in the same location which has the DSP ELF executable.
6. CCS provides a trace decoder tool, which consumes the .bin file and provides the PC trace decoded information. Please follow the steps outlined in the below section Using_the_Trace_Decoder_Utility.

PC Trace where ETB is drained by EDMA

This demonstrates the PC trace where ETB is drained by EDMA. This mode provides the capability to extend the 4Kb ETB buffer size using EDMA. The PC Trace can be logged in either circular mode or stop mode to get more than 4Kb encoded PC trace information. Please follow below steps to execute the program.

1. Power Cycle the EVM, make sure the EVM is brought up with Linux and you get to root prompt on the console.
2. Open CCS
3. Connect to DSP Core 0
4. Load the DSP ELF executable provided in the Example's Debug folder on DSP Core 0.
5. After the program is executed, the trace bin file gets generated in the same location which has the DSP ELF executable.
6. CCS provides a trace decoder tool, which consumes the .bin file and provides the PC trace decoded information. Please follow the steps outlined the below section Using_the_Trace_Decoder_Utility.

PC Trace where ETB is drained by CPU targetted for Exception debug

This demonstrates the PC trace when the application is hitting an exception. The ETB is drained by CPU. The test example code demontrates the APIs provided in the ctools Use case library. The PC Trace is always logged in circular mode. Please follow below steps to execute the program.

1. Power Cycle the EVM, make sure the EVM is brought up with Linux and you get to root prompt on the console.
2. Open CCS
3. Connect to DSP Core 0
4. Load the DSP ELF executable provided in the Example's Debug folder on DSP Core 0.
5. After the program is executed, the trace bin file gets generated in the same location which has the DSP ELF executable.
6. CCS provides a trace decoder tool, which consumes the .bin file and provides the PC trace decoded information. Please follow the steps outlined the below section Using_the_Trace_Decoder_Utility.

Using the Trace Decoder Utility

Trace Decoder utility is available from CCS. Please refer to TraceDecoder page for details. The below sample usage should provide the PC trace dump to the console.

''<Dir Containing the Bin file>''\''<CCS Install DIR>''\ccs_base\emulation\analysis\bin\td -procid 66x -bin <binfilename>.bin -app <DSP ELF Executable Name>.out -rcvr ETB

Other Ctools Library examples

Please refer to CCSv5 CtoolsLib Examples for more information and to download other supported Ctools library examples. The downloaded Examples.zip should be extracted into [<CTOOLSLIB INSTALL>\packages\ti\] location. All the examples are CCSv5 compatible.