NOTICE: The Processors Wiki will End-of-Life in December of 2020. It is recommended to download any files or other content you may need that are hosted on The site is now set to read only.


From Texas Instruments Wiki
Jump to: navigation, search

Starting in v4.3, Processor SDK documentation is no longer hosted on processors wiki.

Please bookmark the new links:


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 [1] )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 CCS projects) are available as a separate zip package in the file repository listed below.
  • 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 the links below. After downloading the zips you need, simply expand each zip under the same top level directory. All library and example projects are compatible with CCSv6.

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


STMLib Software Message Library


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


ETBLib Software Library for configuring and retrieving the ETB contents.


ETMLib Software Library for configuring ARM CortexA8 Core Trace triggering.


DSPTraceLib  Software Library to configure DSP Trace export


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


PMICMILib Power and Clock management Instrumentation Library 


SCILib Statistic Collector Instrumentation Library


CPTLib CP Tracer Instrumentation Library


ITMLib Instrumentation Trace Macrocell Library


Examples CToolsLib Examples


Ctools_UCLib_Examples CTools Use-Case Library Examples


The latest release of all libraries now come with CCS projects. Please refer GettingStarted.htm 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.