<!-- Start of markdown souce --> # 1. Introduction CTools are the Chip Tools which are system level debug facilities included on selected TI devices. CToolsLib provides a set of fundamental libraries for the configuration and control of debug and profiling trace modules common to AM65x and Jacinto 7 devices. Trace modules exist at two levels within TI devices supporting core trace and system trace. Core trace at a minimum provides program counter and instruction timing, and in the case of TI DSPs core memory accesses and core events. System Trace provides multi-core application instrumentation (for both printf logging and binary data), and depending on the device, power and bus profiling data. This article will provide a brief overview of each module and associated library, introduce the library supported use-cases, and show how the libraries can be combined to provide additional features. # 2. Overview - CToolsLib is a collection of embedded target APIs/library focused to enable easy programmatic access to CTools debug and trace capabilities. - CToolsLib is provided in source code for easy integration into applications. - CToolsLib consists of several libraries. ## 2.1 System Trace Modules ### 2.1.1 CPTracer2 Libraries The SoC debug framework provides support for monitoring transactions on the various interconnects in the system via CPTracer2 probes and probe/trace aggregators. The probes provide the following high level functions: - Statistical profiling of access latency at an interconnect node - Statistical profiling of data throughput at an interconnect node - Transaction trace at a probed node The trace aggregators are responsible for merging trace from multiple probes and forwarding it to local TBR buffers in Debug Cells and/or to TPIU for pin export. The following libraries are provided for above functionalities. - CPT2Lib provides APIs for low level setup for CPTracer2 bus probes. - TraceAggrLib provides APIs for low level setup for CPTracer2 aggregator modules. ### 2.1.2 STM Libraries STM software messaging is provided by ARM’s CoreSight STM-500 (System Trace Macrocell) module. STM software masters consist of DSP cores, MPU cores, and MCU cores in the device. For software masters, data can be broadcast on any of N channels to categorize data or to provide thread safety. Software messages are typically used for multi-core application instrumentation which is a very productive debug and software maintenance capability. STM’s transport performance is orders of magnitude faster (80MB/sec to 100MB/sec) than CIO or UARTS. When used with an TBR, STM software messages can also be remotely captured for in-field applications. STM Export library provides "C" printf and binary APIs for hardware assisted (System Trace software messages) instrumentation in your code. STM messages are captured via an TBR or with an external XDS560Pro Trace receiver. The following libraries are provided for above functionalities. - STMLib provides APIs for low level setup for CoreSight STM-500 module. - STMXPORTLib provides APIs for software instrumentation. It provides methods for transporting instrumentation messages and application data. ## 2.2 Core Trace Modules Core trace CTools Libraries enable use-cases beyond application development profiling and debugging. Customers can integrate the core trace libraries into their production application code to provide remote visibility within fielded systems. Another use case is for detailed profiling and performance analysis integrated in the customer’s validation systems to assure new software modules or modifications are meeting performance requirements. ### 2.2.1 DSPTraceLib [[b Note: **This library is still under construction.** ]] DSPTraceLib provides for configuration and control of DSP core trace module. The library provides APIs to configure the trace module, enable and disable trace data flow, and a state function that allows clients to terminate core trace gracefully on demand (rather than through an AET trigger). DSP core trace consists of multiple streams of data from the core’s program counter (PC), instruction timing, core memory accesses and core events (such as stalls and interrupts). DSPTraceLib by itself can not initiate trace data export from the core. Trace triggers configured with the Advance Event Triggering (AET) module are required to trigger the export of trace data. ### 2.2.2 AETLib [[b Note: **This library is still under construction.** ]] AETLib provides a configuration API for the Advance Event Triggering (AET) module on DSP cores. The AET module is made up of comparators and trigger builders that are combined to provide complex trigger events. Trigger events can then be used to form watchpoints or trace triggers. Watchpoints can be used to halt core execution when the trigger conditions is satisfied, or exported as cross triggers to other cores or devices. Trace triggers are used to start and end trace generation. Trace triggers can be setup on the program counter, memory accesses or core events. Triggers can be setup on individual PC or data addresses or ranges, and triggers on data values can be masked. Each trigger can be used to enable or disable a single stream or multiple streams (PC, Timing, memory accesses or events) simultaneously. When enabling multiple streams care does have to be taken to not overflow the trace export buffer. ### 2.2.3 ETMLib [[b Note: **This library is still under construction.** ]] ETMLib provides both core trace configuration and triggering functions for ARM ETM modules. The ETM modules utilize comparators to form start, stop and range trace triggers with the PC, and data accesses. Triggers can be setup to enable and disable the export of PC, PC with cycle accurate timing, PC with data trace, and PC with cycle accurate timing and data trace. ETMLib 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. ### 2.2.4 ITMLib [[b Note: **This library is still under construction.** ]] 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. ## 2.3 Common Trace Modules This section covers the CTools libraries for common trace modules that are required to facilitate the system trace and core trace functionalities described in previous sections. ### 2.3.1 TBRLib CT-TBR (cTools Trace Buffer-Router) module is the on-chip trace buffer. It is responsible for buffering large amounts of trace data from various trace sources including DSP core trace data, ARM core trace data, STM SW messages, and CPTracer2 data etc. TBRLib library provides APIs to program and read trace data from CT-TBR. TBRLib can be used with other libraries to setup and capture trace data from various trace sources across SoC. After the CT-TBR 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 for post processing or to be imported into CCS for display. ### 2.3.2 ATBREPLib The merged trace stream needs to be available to both the TPIU (for export over device pins) and a CT-TBR (for on-chip collection). The ATB Replicator supports this requirement by taking the ATB bus created by the ATB Funnel and essentially making two copies of it. These two copies are exposed as ATB Master #0 (used by the TPIU) and ATB Master #1 (used by the CT-TBR). An ATID-based filtering mechanism is implemented within the ATB Replicator to help constrain the amount of traffic provided over either of the two copies. This filtering mechanism and the programmer’s interface for the ATB Replicator can be found in CoreSight SoC Technical Reference Manual. ATBREPLib provides APIs for low level setup for ATB Replicators. ### 2.3.3 GTCLib Global Timebase Counter (GTC) module provides a free-running counter that generates global timestamp in various trace streams to allow correlation of traces from across the SoC. GTCLib provides APIs for low level setup for GTC counter. ## 2.4 Examples ### 2.4.1 DDR Benchmarking Example with CPTracer2 This example shows how to use CToolsLib to set up and capture DDR benchmarking data (DDR throughput, DDR latency, and DDR transactions) into TBR. The following libraries are used in this example. The intention is to show the user how to integrate CToolLib into their application code. - CPT2Lib - TraceAggrLib - TBRLib - ATBREPLib - GTCLib ### 2.4.2 STM Software Messaging Example with STM Libraries This example shows how to use CToolsLib to set up CoreSight STM-500 module to transport instrumentation messages and application data and how to capture messages and data into TBR. The following libraries are used in this example. The intention is to show the user how to integrate CToolLib into their application code. - STMLib - STMXPORTLib - TBRLib - ATBREPLib - GTCLib # 3. Downloads [CToolsLib Download Page](https://software-dl.ti.com/emulation/esd/ctoolslib_k3/CToolsLib_K3_download.html) # 4. Support [Support Forum - Please put CToolsLib in title](https://e2e.ti.com/support/development_tools/code_composer_studio/f/81.aspx) **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: 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](https://en.wikipedia.org/wiki/BSD_License#3-clause_license_.28.22New_BSD_License.22_or_.22Modified_BSD_License.22.29). <!--# Alerts/Notes Use Red box for Alerts or Notes. {{r Note: This is a red box with some notes to highlight }} --> <!-- End of markdown source --> <div id="resources" align="center" style="margin-top: 4em; font-size: smaller;"> </div> <div align="center" style="margin-top: 4em; font-size: smaller;"> <a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://software-dl.ti.com/ccs/esd/documents/web_support_v2/cc_license_icon.png" /></a><br />This work is licensed under a <a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/">Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License</a>.</div> <div id="timestamp" align="center" style="margin-top: 4em; font-size: smaller;"> </div>