CToolsLib Article

Introduction

CToolsLib provides a set of fundamental libraries for the configuration and control of debug and profiling trace modules common to CI and OMAP 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.

Core Trace Modules

Core trace CTools Libraries enable use-cases beyond application development profiling and debugging. Customers have integrated the core trace libraries into their production application code to provide remote exception visibility within fielded systems. This is especially important to customers who get charged for dropped calls and equipment down-time in remote locations. Another common 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.

DSPTraceLib

Core Trace PC and Timing

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.

The screen shot to the right shows a simple core trace session with source correlation, function execution graph and function profile windows.

AETLib

AETLib provides a configuration API for the Advance Event Triggering (AET) module. 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.

In the case of programming AETLib for exception visibility, two trace jobs are required; a Trace On job to start PC trace immediately and an End All trace job to terminate PC trace when the exception vector is executed.

ETMLib

ETMLib provides both core trace configuration and triggering functions for ARM ETM and PTM modules. The ETM and PTM modules utilize comparators to form start, stop and range trace triggers with the PC, and in the ETM case data accesses. In the case of the ETM, 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. With the PTM only PC and PC with cycle accurate timing trace export are supported. ETMLib provides basic APIs to setup triggers that control the flow of trace data for the most common use cases:

• Trace on (immediately)
• Start trace on PC
• Stop trace on PC
• Trace PC in a range (inclusive or exclusive)
• Trace data accesses to a specific location (must use a PC trigger to start trace)
• Trace data accesses within a address range (must use a PC trigger to start trace)

ETMLib also provides separate trace enable and disable controls that can be used to isolate core trace to a small region of code or allow trace across the entire application.

ETBLib

ETBLib provides configuration and trace data extraction APIs for both ARM Core-Sight and TI Embedded Trace Buffers (ETB). ETBs are used to capture both core trace and system trace. For some devices each core may have a dedicated ETB for core trace and a chip level ETB for system trace, while other devices have a single ETB for both core trace and system trace data. Trace funnels are used in devices that support multiple core and system trace streams to export trace data to a single ETB. ETBLib is used to configure any buffer options (circular or stop when full), enable trace capture, flush the input buffers when trace capture is disabled and then extract the captured trace data to system memory. In some devices DMA channels can be used effectively to extend the size of the captured data with system memory.

Typically when using ETMLib for an ARM application or DSPTraceLib and AETLib for a DSP applications, remote operation may be required such as in the exception tracking use-case. When using an ETB for remote operation the customer must transport the data back to a host for decoding and visualization TI’s tools include a decode utility (td.exe) that provides text or csv formats for import to Excel, and a binary to Trace Data File (bin2tdf) utility used to format the data for importing to CCS for display with Trace Analyzer.

For use cases, such as application profiling, where larger buffers than the ETB support are required, trace data can be exported out the pins (not supported by all devices). Core trace data can be captured with an XDS560T. Both Core and System Trace can be captured with the next generation XDS Trace Pro. The XDS560v2 System Trace can be used in cases where only system trace capture is needed. In these cases DSPTraceLib and AETLib are used in the customer validation system to profile modifications and certify they meet timing requirements.

System Trace Modules

System Trace data is provided by TI’s STM v1.0 (System Trace Module) or ARM’s STM v2.0 (System Trace Macrocell). In both cases STM provides message formatting, message interleaving, time-stamping and transport of messages. STM masters are made up of both software masters (DSP and MPU cores) and hardware masters. STM Hardware message generation is typically used to provide system level profile data for power, clocks and buses statistics. 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. Another significant STM advantage is that it’s available much earlier in the development cycle than traditional device communication mechanisms. When used with an ETB, STM can also be remotely captured for in-field applications. STM instrumentation can also be utilized to supplement STM HW profiling data, marking the occurrence of important events.

The following libraries are used to generate software messages for application instrumentation or to configure hardware profiling STM message generation. Any combination of these libraries can be used together as long as the device provides support for the module. In cases where the device supports an ETB at the system level (most modern devices) these libraries can be combined with ETBLib in an application to support remote capture of STM message data.

STMLib

STMLib Application Instrumentation Example

STMLib provides APIs for application software instrumentation. STMLib provides transfer functions for compressed printf and logging, character buffers, and binary data (individual values or arrays). Logging functions are restricted to a format string and a fixed number of integers, significantly increasing performance over the compressed printf. The character buffer transport supports applications that have an existing string based logging infrastructure.

The Trace Analyzer display at the right shows an example STMLib generated printf, logging and binary data transfers.

CPTLib

CP Tracer CorePac 1 L2 Bus Statistics

CPTLib provides use-case based APIs for configuration and control of the Common Platform Tracer (CPT) modules. CPT modules are located on strategic slave buses, and provide periodic bus statistics and bus events that are transported over STM CPT data generation is completely unobtrusive to the slave buses data flow. The statistic information is based on four counters; two throughput counters, a transaction counter and a wait counter. The periodic bus status provides a flag per master indicating the master that made at least a single access to the slave bus during the sample period. The CPT can generate event messages for any combination of new request, last read and last write events that are generated on demand. For throughput counting and new request events, slave bus accesses can be qualified and filtered by master to focus on a specific data source. Qualifiers include; Address ranges within a 32 bit address space (for > 32-bit buses the upper bits can be selected), access type (CPU Inst, CPU data, DMA data), and access direction (Read/Write). Multiple events can be enabled at the same time, although this is not recommended due to the high probability of STM message overflow.

The plot to the right was generated from CP tracer data collected from a TCI6616 device’s Corepac1’s L2 CP Tracer.

CPTLib provides use-case level APIs to make configuration and control easy. Control is facilitated through enable and disable functions that allow the user to isolate STM data generation relative to their application. A single instance of the library can support multiple instances of physical CP Tracers. Configuration includes selecting the use case, selecting masters to filter and setting up qualifiers. CTPLib is dependent on the STMLib to provide CPTLib logging messages and meta data. Meta data provides processing options and context information (use case selection, device operating frequency) used for decoding the data.

The CPTLib helper functions facilitate the following three use cases; System Bandwidth, Total Bandwidth and Master Bandwidth. The System Bandwidth use-case programs all (selected) CP Tracers to provide bandwidth utilization simultaneously providing a system wide view of bus utilization. The Total Bandwidth and Master Bandwidth use-cases provide detail information for individual buses. The Total Bandwidth Use Case allows the user to compare the bandwidth utilization by one master (or group of masters) against all other active masters. The Master Bandwidth Use Case allows the user to compare the bandwidth utilization by one master (or group of masters) against another master (or group of masters). The Total Bandwidth and Master Bandwidth use-cases provide the following statistics for an individual bus:

• Throughput in MBytes/sec of selected master
• Throughput as a percentage of selected master verses all other masters (or selected master)
• Transaction count
• Average access size
• Average latency

SCILib

OMAP4430 SDRAM Statistic Collector setup for EMIF1 and EMIF 2 Statistics - Raw View

OMAP4430 SDRAM Statistic Collector setup for EMIF1 and EMIF 2 Statistics - Plot

SCILib provides APIs for application configuration and control of the Statistic Collector module. These devices instantiate two types of Statistic Collector modules. The SDRAM module provides load statistics and Master modules provide both load and latency statistics. A Statistic Collector module is made up of a set of counters and filters. When enabled the counter values are exported periodically through STM. For each counter a probe (bus source) must be selected from which different bus transaction events can be chosen to count (such as clocks, transfer, wait, busy, and packet). How the event is counted must also be configured (such as for filter hit, min/max hit, event type (payload length, pressure or latency), and AND/OR of filters). Each counter can have zero, one or two filter sets associated with it that can be used to selected specific master or slave addresses, read or write cycle types, or error cycles. Each individual filter has match and mask components for each filter element allowing for very complex filter combination.

The screen shots to the right show throughput data captured for the SDRAM module set up for EMIF1 and EMIF2 activity running on an OMAP4430 A9. STMLib logging messages show when the SDMA unit is active.

SCILib presents a use-case based API that allows the user to register a specific use-case with the library:

• Throughput
• Average Burst Length
• Request Link Occupancy
• Response Link Occupancy
• Average Latency (Master only)

In addition to selecting the use-case, the use-case registration API allows the user to select a probe, and optionally one or two filters. The registration function finds a free counter that meets the requirements of the request and programs the use-case, probe and filters (but does not enable the counter). Separate registration functions are used for registering SDRAM and Master use-cases due to differences in programming requirements. Once the use-case is registered, the global enable and disable functions are used to control when the Statistic Counters are actively generating STM messages. SCILib is dependent on the STMLib to provide meta data. Meta data provides processing options and context information (use case selection, sample window size) used for decoding the data.

PMICMILib

OMAP4430 Initial Power and Clock States

PMICMILib provides APIs for application configuration and control of the Power Management Instrumentation (PMI) and Clock Management Instrumentation (CMI) modules in OMAP devices. The PMI and CMI modules are very similar to each other hence the reason the APIs are merged into a single library (although they can be built independent of each other). Both the PMI and CMI modules operate in Event mode where power and clock state changes are exported periodically through STM messages. The PMI and CMI modules can be configured to generate STM messages for specific domain state changes. The CMI Module can also be configured for Activity mode which provides with STM messages the percentage of clocks active during the sample period. With STMLib the PMI and CMI modules can also be enabled and disabled allowing the client to modulate when STM messages are generated.

The screenshot at the right shows the initial event power and clock states from the OMAP4430’s Power Module (PM) and two Clock Modules (CM1 and CM2). This example also shows STMLib logging used to supplement the PMI and CMI data.