Common Platform (CP) Tracer Library API Reference Guide (C6672 Version)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
Common Platform (CP) Tracer Library API Reference Guide (C6672 Version) Documentation

Introduction

The CPT Library provides a CP Tracer Module programming API. A CP Tracer unit provides
statistical and event trace data for the slave module the CP Tracer unit is associated with.
Typically a device will support CP Tracer units for each critical slave module.
This library also provides CPT specific STM logging capabilities.
Devices Supported
Devices currently supported by the library are:
  • TMS320TCI6612 and TMS320TCI6614
  • TMS320C6657
  • TMS320C6670 and TMS320TCI6616 (both devices support with the _C6670 build)
  • TMS320C6672
  • TMS320C6674
  • TMS320C6678
  • C66AK2Hxx
  • 66AK2Exx
  • TCI6630K2L
  • 66AK2Gxx
    \n Note - The library builds provided in this package are for TMS320C6670, TMS320TCI6616, TMS320C6657
       and TMS320C6614 devices. The library must be recompiled to support a different device types. 
       See the Build Notes for additional detail on configuring the library for a specific device. 
    
CPT Library Revision History
Revision Date Notes
0.0 7/15/2010 CPT Draft API Release (no code)
0.1 7/15/2010 CPT Draft API Release (no code). Moved AddrExportMask to CPT_CfgOptions from CPT_CfgAddrFilter() and update meta data to include AddrExportMask value. Moved EMU trigger out control to CPT_ModuleEnable()/CPT_ModuleDisable() from CPT_TrigQualifiers.
0.2 9/15/2010 Updated CPT Draft API Release (no code)
0.3 1/7/2011 First release implementation - minor API changes
0.4 5/3/2011 Added System Profile cases to eCPT_UseCase
0.5 5/3/2011 Added support for TCI6614 and TCI6612
0.6 3/23/2012 Added support for C6657
0.7 3/23/2012 Added predefined symbol compatibility with other cToolLibs. Modified ownership mechanism to include who owns (IDE or Lib) and not generate errors if the library already owns the module. This fixes conflicts when trying to restart an application using the library without resetting the device.
0.8 3/23/2012 Added forceOwnership parameter to CPT_CfgOptions. Updated all projects to CCSv5.
0.9 12/19/2012 Fixed power-up and module enable bugs in CPT_OpenModule().
0.10 2/1/2013 Added C66AK2Hxx support
0.11 5/15/2013 For C6670 target, Replaced TE_SS master ids with correct BCP master ids
0.12 4/28/2014 Added support for TCI6630K2L and 66AK2Exx
0.13 9/29/2014 Added missing CCS project files
0.14 10/09/2014 Keystone2 Master IDs 12-15 are marked as reserved. Updated master id naming and definitions to be compatible with datasheet.
0.15 5/14/2015

Added 66AK2Gxx support.

Build Notes

Conventions
The following public naming conventions are used by the API
  • CPT_ - Prefix for public CPT Library functions
  • eCPT - Prefix for public CPT enumerations
Pre-defined Symbols
The CPT Library supports the following pre-defined symbols that if defined
enable the functionality at compile time.  
  • _STM_Logging - If defined the following APIs, that require the library be opened with a valid STM Library handle, are included in the build:
    • CPT_LogMsg()
    • Private functions for meta data transport with STMLib. Meta data is needed to process the hw generated CP Tracer data for a specific use-case (such as conversion of CT Tracer throughput counter data to bytes/sec). If _STM_Logging is not defined meta data is not transported and no additional processing is performed on the CP Tracer data. See _CPT_CfgOptions which is used to define user provided meta data.


Note - The minimum revision STMLib that supports CPTLib logging and meta data transport is version 3.1.

The library must be configure for a specific device by providing at compile time one of the following pre-defined symbols:

  • TCI6612 or _TCI6612 TMS320TCI6612
  • TCI6614 or _TCI6614 TMS320TCI6614
  • C6657 or _C6657 TMS320C6657
  • C6670 or _C6670 TMS320C6670 and TMS320TCI6616
  • C6672 or _C6672 TMS320C6672
  • C6674 or _C6674 TMS320C6674
  • C6678 or _C6678 TMS320C6678
  • C66AK2Hxx or _C66AK2Hxx 66AK2Hxx
  • TCI6630K2L or _TCI6630K2L TCI6630K2L
  • C66AK2Exx or _66AK2Exx 66AK2Exx
  • C66AK2Gxx or _66AK2Gxx 66AK2Gxx
Directory Structure
STM is a component of cTools so it resides within the cTools directory structure.
|--cTools
|
|-- CPTLib
| |
| |-- doc
| | |
| | |--CPT_C6657_html
| | |--CPT_C6670_html
| | |--CPT_C6672_html
| | |--CPT_C6674_html
| | |--CPT_C6678_html
| | |--CPT_C66AK2Hxx_html
| | |--CPT_TCI6612_html
| | |--CPT_TCI6614_html
| | |--CPT_TCI6630K2L_html
| | |--CPT_66AK2Exx_html
| | |--CPT_66AK2Gxx_html
| | |
| | |-index.html (Doxygen API documentation)
| |
| |-- include (Public API include file)
| |-- src (Private .c and .h files )
| |-- projects (Target specific library builds)
| | |
| | |--C6657
| | |--C667x (Can build TCI6616, C6670, C6672, C6674 or C6678 versions)
| | |--C66AK2Hxx
| | |--TCI6614
| | |--TCI6630K2L
| | |--66AK2Exx
| | |--66AK2Gxx
|-- Examples (Target specific stand-alone example projects)
|
|--common (files common across examples)
|--C6657
| |-- CPT_L2_CorePac0 (C6657 specific)
| |-- CPT_SystemProfile_CorePac0 (C6657 specific)
|--C667x
| |-- CPT_L2_CorePac0 (Can run on any C667x device or TCI6616)
| |-- CPT_SystemProfile_CorePac0 (Can run on any C667x or TCI6616)
|--C66AK2Hxx
| |--CPT_L2_CorePac0
| |--CPT_SystemProfile_CorePacN
|--66AK2Exx
| |--CPT_L2_CorePac0
| |--CPT_SystemProfile_CorePacN
|--66AK2Gxx
| |--CPT_L2_CorePac0
| |--CPT_SystemProfile_CorePacN
|--TCI6630K2L
| |--CPT_L2_CorePac0
| |--CPT_SystemProfile_CorePacN
|--TCI6614
|-- CPT_L2_CorePac0 (TCI6614 specific)
|-- CPT_SystemProfile_CorePac0 (TCI6614 specific)
Helper Functions
Helper functions allow the library to be ported easily to different operating environments without modifications
to the library directly. Within the library these functions are declared extern so the library will build but
can not be linked without implementations for the following helper functions:
  • void * cTools_memAlloc(size_t sizeInBytes);

    If allocation successful returns pointer to allocated memory, else if not successful return NULL.
  • void * cTools_memMap(unsigned int phyAddr, unsigned int mapSizeInBytes);

    Map a physical address to a virtual address space. Return the virtual pointer if successful, else return NULL. Return phyAddr if virtual mapping not required.
  • void cTools_memFree(void * ptr);

    Free the memory at the ptr (returned from cTools_memAlloc()) call.
  • void cTools_memUnMap(void * vAddr, unsigned int mapSizeInBytes);

    Unmap virtual address space starting at vAddr (returned from cTools_memMap())of mapSizeInBytes length. If virtual address mapping not required simply return.
  • int cTools_mutexInit(uint32_t mutexId);

    Allocate a mutex object for the provided mutexId. This function is meant to provide cross process locking for a specific resource. cTools guarantees that mutexIds will be unique between libraries, and can be any value that fits in a uint32_t type. The mutex is created in the unlocked state. This function returns 0 if the mutex was created successfully or if the mutex already exists (regardless of state - locked or unlocked). This function returns -1 if an error occurred during creation of the mutex.

    The implementation of this function is dependent on the environment the CP Tracer library is executing within. If the user guarantees that across processors and processes that each physical CP Tracer is only opened once at any time, then this function (as with all cTools mutex functions) may simply always return 0. For SMP systems or cases where there are multiple instances of CPTLib running across multiple processes, if the same physical CP Tracer can be opened multiple times on the same processor, then implementation of this function is most likely required. In this case implementation will require allocating memory for the mutex in shared memory and possible use of the hardware semaphore to protect access. If the implementation is for a single instance of CPTLib (single or multi-threaded) then the implementation may only require allocation of the mutex from the heap.
  • int cTools_mutexTrylock(uint32_t mutexId);

    Attempt to lock the mutexId. If the lock is successful return 0. If the mutexId is already locked return -1. If this function is attempted on a mutexId that has not been opened the results are undefined.
  • int cTools_mutexUnlock(uint32_t mutexId);

    Attempt to unlock the mutexId. If the unlock is successful return 0. If the mutexId was already unlocked return 0. If this function is attempted on a mutexId that has not been opened the results are undefined.
CPT Export Notes
If you are using CCS to capture STM data (with either a trace enabled emulator or ETB)
you should enable the CPT module's STM messages through the CSS 4.x Breakpoint view by
creating a Trace job and settings the following Trace Properties:
  • Trace Type: System
  • STM Trace Type: Trace Export Configuration
  • Enable HW Message Sources:
  • CPT Event Profiling: True
    Note that CPT Event Profiling by default is disabled.
If you are working remotely from CCS and using the ETB to capture STM data then you must provide your own application code to enable the CPT module's STM messages.