From Texas Instruments Wiki
Jump to: navigation, search


See CToolsLib Article for a comprehensive article on cToolsLibs and the hardware modules supported.


  • CToolsLib is collection of embedded target APIs/library focused to enable easy programmatic access to CTools debug capabilities
  • CToolsLib purpose is provided in source code for easy integration into applications
  • CToolsLib consists of several libraries



  • This library provides the ability to program and read trace data from an Embedded Trace Buffer (ETB). The ETB can be used with other libraries to setup and capture DSP core trace data, ARM core trace data, or STM data sources.
  • In some devices each core has a dedicated ETB, while others have a single ETB shared between trace sources.
  • After the ETB data is read into local memory, the user must transport the binary trace data back to a host where the binary trace data can be converted to text, csv or a .tdf file that can be imported into CCS for display. The GettingStarted.htm file (available at gForge)provides instructions for generating these files from utilities provided with CCS.
  • The Examples projects are also a good source of information on using ETBLib for different cases.


  • This library provides the ability to programmaticly setup 64x+ DSP trace export.


  • The ETM Library provides the interface to configure and control instruction and data tracing during program execution. A trace session is defined as the time frame from the trace system getting armed(enabled and waiting for a start trace condition), to the time when the trace completes, either from an end trace condition that has been configured or a manual call to stop tracing.
  • Developed and tested for the CortexA8 on TCI6614 and C6A816x devices.
  • The ETMLib Examples page provides instructions on how to run the examples and display the results.


  • This library provides "C" printf and binary APIs for hardware assisted (System Trace software messages) instrumentation in your code. STM messages are captured via an ETB or with an external XDS560v2 System Trace receiver.
  • For instructions on setting up CCS to capture STM data see Using System Trace(STM).


  • The ITMLib provides "C" string amd binary value logging APIs for TI M3/M4 devices that includes an ITM module and supports SWD (Serial Wire Debug) with SWO (Serial Wire Output) Trace. ITM requires at a minimum CCSv5.5 and emupack 5.1.340.0 with an XDS2xx or XDS110 (Note: your XDS may need a firmware update to work with "SWD with SWO Trace". See your XDS vendor for firmware update instructions).


  • The Common Platform Tracer modules provides profile information via STM messages for critical buses within the device. CPTLib provides low level CP Tracer module setup. The provided use case based helper file combined with CPTLib makes for an easy to use environment. For examples see Common platform Tracer Examples. For debug help see Debugging with Common Platform Tracer.


  • The cTools_UCLib is a library for Keystone family devices (C66xx, TCI66xx, 66AK2Hxx, 66AK2Exx and TCI6630K2L) that consolidates the most common CP Tracer and AET/DSP Trace uses cases into a single library. The Library also consolidates ETB setup and operation into a few easy to use functions.
  • Use cases supported include:
    • Exception tracking with DSP Trace
    • Application Program Counter Trace
    • Illegal Memory Access Watching with DSP Trace
    • CP Tracer Strategic Bus Throughput and Latency profiling
    • Function Statistical Profiling with DSP Trace
  • Keystone Ctools_UCLib examples (platform specific CCSv5 projects) are available as a separate zip package in the ctoolslib gforge site.
  • Keystone Ctools_UCLib examples are also available as a part of Keystone MCSDK instrumentation. For more details please refer to Keystone MCSDK instrumentation examples
  • For more information about Ctools use-cases, please refer to Ctools_UCLib doxygen at Ctools_UCLib/doc/Ctools_UCLib.html/index.html


  • The PMI and CMI units provide power and clock state profiling via STM messages. The PMICMILib provides a common programming and control API for both units. For more details see OMAP4 Power and Clock management Profiling.

Linux Kernel Driver for STM printf

  • Linux kernel module device driver enables applications to use MIPI STM as a standard character device driver. Users can redirect output (from printf) to a STM device, or directly write() to the STM device from their application. For details and examples see STM Linux Device Driver.


  • The OMAP44xx and OMAP54xx Statistic Collectors provides profile data for SDRAM load monitoring and Master load and Latency monitoring. Data is exported as STM messages. SCILib provides a use case based API for configuring and controlling bus profile data for all the statistic collectors on a device.
  • Use cases supported include:
    • Average Throughput (for SDRAM and Master SC Modules)
    • Link Occupancy (for SDRAM and Master SC Modules)
    • Average Burst Length (for SDRAM and Master SC Modules)
    • Average Latentcy (For Master SC Module only)


  • The CToolsLib examples package contains device or platform specific CCSv5 examples, which portrays typical use case scenarios involving individual or multiple CTools libraries. These examples also show how to integrate various CTools libraries into one's application SW.
  • The following are the various supported devices or platforms:
    • Keystone1 family of devices (C667x, C665x and TCI661x)
    • Keystone2 family of devices (66AK2Hxx, 66AK2Exx and TCI6630K2L)
    • TCI648x family of devices
    • OMAP family of devices (OMAP44xx and OMAP54xx)
    • C6A816x family of devices
    • DRA7xx family of devices


  • There is a generated Doxygen API description included with each CToolsLib.


All cToolsLib libraries and example source are available in zip files from the cToolsLib gForge site. From the gforge summary page you can navigate using the menu on the left hand side of the screen to the files page to get the latest version of each library and example code. Or you can use the links below to get to a specific file repository. After downloading the zips you need, simply expand each zip under the same top level directory. All library and example projects are compatible with CCSv5.

Library Purpose File Repository
GettingStarted Provides processor specific notes for libraries and examples

GettingStarted gForge

STMLib Software Message Library

STMLib gForge

AETLib Software library for programmatically using the 64x+ AET hardware breakpoint and watchpoint units. Also useful for triggering/halting trace.

AETLib gForge

ETBLib Software Library for configuring and retrieving the ETB contents.

ETBLib gForge

ETMLib Software Library for configuring ARM CortexA8 Core Trace triggering.

ETMLib gForge

DSPTraceLib  Software Library to configure DSP Trace export

DSPTraceLib gForge

cTools_UCLib  Library that configures key Keystone CP Tracer and DSP Trace Use Case

cTools_UCLib gForge

PMICMILib Power and Clock management Instrumentation Library 

PMICMILib gForge

SCILib Statistic Collector Instrumentation Library

SCILib gForge

CPTLib CP Tracer Instrumentation Library

CPTLib gForge

ITMLib Instrumentation Trace Macrocell Library

ITMLib gForge

Examples CToolsLib Examples

Examples gForge

Ctools_UCLib_Examples CTools Use-Case Library Examples

Ctools_UCLib_Examples gForge

The latest release of all libraries now come with CCSv5 projects. Please refer GettingStarted.htm(gforge) for more details.

Trace Decoding

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 .



Frequent Asked Questions (FAQ)

Q: Can I get the source code?

  • A: The source code is included with each library.

Q: How do I know if my device supports CTools?

  • A: The datasheet or Technical Reference Manual (TRM) will usually contain details on the features support and avaialble on your device. If you are unsure, you may wish to ask in the support forum.

Q: Do I have to use CToolsLib with Code Composer Studio?

  • A: No, other tools such as Lauterbach Trace32 can be used with the CToolsLib. Please contact your tools vendor regarding support.

Q: Do you have approximate cycle counts for each library?

  • A: For AETlib there is a file called "aetlib_profiling_stats.txt" that gives this information
  • A: For ETBLib, on the TI c6x compiler on a 64x+ device, it takes approximately 1000 cycles per call at the "-o2" optimization level.

Q: Do you have the code size for each library?

  • A: For AETlib there is a file called "aetlib_size_stats.txt" that gives this information
  • A: For ETBLib, on the TI c6x compiler on a 64x+ device, it is approximately 4KB at the "-o2" optimization level.

Q: What license is this code provided under? / Is the code GPL compatible?

  • A: The header files in CToolsLib will have the relevant licenses. Generally, CToolsLib is licnesed under modified BSD license which is GPL compatible. Please see this wikipedia article.