*************************************************************

Copyright (c) 2010-2012 Texas Instruments Inc. (www.ti.com)

All rights reserved.

Last updated: September 25, 2013

Description: This document navigates through all the CToolsLib contents and usage of the

ETBLib, DSPTraceLib, AETLib, STMLib, CPTLib, Ctools_UCLib, PMICMILib and SCILib.

*************************************************************

 

Except where noted all projects are CCSv5.

 

ETBLib:

ETBLib provides an application interface to program and drain the Embedded Trace Buffer (ETB). There are two kinds of ETB in TI devices, CSETB and TIETB. The ETBLib contains CCSv5 projects in the ETBLib/project directory specifying the supported devices and rules to pickup specific files and flags for different devices.

 

New for C66xx, TCI66xx, 66AK2Hxx, TCI6636K2H and TCI663xK2K devices: EDMA draining to system memory for TI-ETB expansion. Supported by all devices in keystone1 and keystone2 family.

 

Docs

ETBLib API documentation (Doxygen) at:

ETBLib/doc/html/index.html

 

API

ETBLib/include/ETBInterface.h

 

Sources

ETBLib/src/ti (for TI ETB)

ETBLib/src/coresight (for CS ETB)

 

 

Projects

TCI6488 - ETBLib/project/TCI6488

TCI6484 - ETBLib/project/TCI6484

C66xx - ETBLib/project/C66xx

C6678 - ETBLib/project/C6678

TCI6614 - ETBLib/project/TCI6614

C6657 - ETBLib/project/C6657

C66AK2Hxx - ETBLib/project/C66AK2Hxx-C66x

C66AK2Hxx - ETBLib/project/C66AK2Hxx-A15

C6A816x - ETBLib/project/C6A816x (Formerly TI816x)

OMAP-A9 – ETBLib/project/OMAP-A9

OMAP-A15 - ETBLib/project/OMAP-A15

DRA7xx - ETBLib/project/DRA7xx-A15

AM437x – ETBLib/project/AM437x-A9

 

Libraries

ETBLib/lib

 

If you do not plan to use the CCSV5/5 project to build these libraries, you need to use the following information in your non-CCSv5 makefile

 

TCI6486 - \ETBLib\src\coresight\CSETB.c, preprocessor flag TCI6486 (Do not use TIETB.c)

TCI6488 - \ETBLib\src\coresight\CSETB.c, preprocessor flag TCI6488 (Do not use TIETB.c)

CA6816x - \ETBLib\src\coresight\CSETB.c, preprocessor flag TI816X & ETM,  DSP or STM (Do not use TIETB.c)

TCI6484 - \ETBLib\src\ti\TIETB.c, preprocessor flag TCI6484 (Do not use CSETB.c)

C66xx  - \ETBLib\src\ti\TIETB.c, preprocessor flag C6670 (Do not use CSETB.c)

C6678  - \ETBLib\src\ti\TIETB.c, preprocessor flag C6678 (Do not use CSETB.c)

C6657  - \ETBLib\src\ti\TIETB.c, preprocessor flag C6657 (Do not use CSETB.c)

C66AK2Hxx-C66x  - \ETBLib\src\ti\TIETB.c, preprocessor flag C66AK2Hxx (Do not use CSETB.c)

C66AK2Hxx-A15  - \ETBLib\src\ti\TIETB.c, preprocessor flag C66AK2Hxx_CSSTM_ETB (Do not use CSETB.c)

TCI6614  - \ETBLib\src\ti\TIETB.c, preprocessor flag TCI6614 (Do not use CSETB.c)

OMAP4xxx - \ETBLib\src\coresight\CSETB.c, preprocessor flag _OMAP & ETM, DSP or STM (Do not use TIETB.c)

OMAP54xx ES2 - \ETBLib\src\ti\TIETB.c, preprocessor flag _OMAP54xx & STM (Do not use CSETB.c)

DRA7xx - \ ETBLib\src\ti\TIETB.c, preprocessor flag _DRA7xx (Do not use CSETB.c)

AM437x - \ETBLib\src\coresight\CSETB.c, preprocessor flag _AM437x (Do not use TIETB.c)

 

DSPTraceLib:

DSPTraceLib provides an application interface to program the DSP trace export. The DSPTraceLib contains the CCSv5 projects in the DSPTraceLib/project directory specifying the supported devices and rules to pickup specific files and flags for different devices

 

Docs

DSPTraceLib API documentation (Doxygen) at:

DSPTraceLib/doc/html/index.html

 

API

DSPTraceLib/include/DSPTraceExport.h

 

Projects

TCI6488 - DSPTraceLib/project/TCI6488

TCI6484 - DSPTraceLib/project/TCI6484

C66xx - DSPTraceLib/project/C66xx 

 

Libraries

DSPTraceLib/lib

 

If you do not plan to use the CCSV5 project to build these libraries, you need to use the following information in your non-CCSv5 makefile

 

TCI6488 - DSPTraceLib/src/DSPTraceExport.c, preprocessor flag TCI6488

TCI6484 - DSPTraceLib/src/DSPTraceExport.c, preprocessor flag TCI6484

C66xx - DSPTraceLib/src/DSPTraceExport.c, preprocessor flag C66x

 

 

AETLib:

AETLib provides an application interface to program the Advanced Event Triggering (AET) module. This interface can be used to program the Trace trigger rules specifying trace start, stop, and ranges, etc.

Implementation of AET does not change from device to device. The single library can be used for different devices.

 

Docs

AETLib API documentation (Doxygen) at:  

AET/doc/html/index.html

 

API

AET/include/aet.h

 

Libraries

AET/lib

 

 

STMLib:

STMLib provides an application interface for the STM instrumentation. The STMLib contains the CCSv5 projects in the STMLib/projects directory specifying the supported devices and rules to pickup specific files and flags for different devices.

 

Docs

STMLib API documentation (Doxygen) at:

STMLib/doc/html//index.html

 

API

STMLib/include/StmLibrary.h

 

Projects

CortexA8 - STMLib/projects/A8

CortexA9 - STMLib/projects/A9

CortextA15 – STMlib/projects/A15

CortexM3 - STMLib/projects/M3

C66xx - STMLib/projects/C66xx

 

Libraries

STMLib/lib

 

If you do not plan to use the CCSV5 project to build these libraries, you need to use the following information in your non-CCSv5 makefile

 

CortexA8 -STMLib/src/StmLibrary.c, preprocessor flag _STM

CortexA9 - STMLib/src/StmLibrary.c, preprocessor flag _STM

CortexA15 - STMLib/src/StmLibrary.c, preprocessor flag _STM (for MIPI STM module) or _CS_STM (for ARM 2.0 module)

CortexM3 - STMLib/src/StmLibrary.c, preprocessor flag _STM

C66xx - STMLib/src/StmLibrary.c, preprocessor flag _STM

 

 

CPTLib:

CPTLib provides an application interface to program the Common Platform Tracers (CPT). CPTLib contains the CCSv5 projects in the CPTLib/projects directory specifying the supported devices and rules to pickup specific files and flags for different devices.

 

Docs

Each device supported has unique CPTLib API documentation (Doxygen) at:

CPTLib/doc/CPT_C6670_html.index.html for both TMS320C6670 and TMS320TCI6616

CPTLib/doc/CPT_C6672_html.index.html for TMS320C6672

CPTLib/doc/CPT_C6674_html.index.html for TMS320C6674

CPTLib/doc/CPT_C6678_html.index.html for TMS320C6678

CPTLib/doc/CPT_TCI6612_html.index.html for TMS320TCI6612

CPTLib/doc/CPT_TCI6614_html.index.html for TMS320TCI6614

CPTLib/doc/CPT_C6657_html.index.html for TMS320C6657

CPTLib/doc/CPT_C66AK2Hxx_html.index.html for keystone2 devices (66AK2Hxx, TCI6636K2H and TCI663xK2K)

 

 

A helper API is provided that can be used as a library wrapper to setup the supported use cases. Documentation is included in the API header include file at:

CPTLib/src/CPTHelper.h

 

For a CP Tracer detailed description and instructions for running the use case examples see:

http://processors.wiki.ti.com/index.php/Common_Platform_Tracer_Examples

 

API

CPTLib/include/CPTLib.h

 

Sources

CPTLib/src/

 

Projects

C667x - CTPLib/projects/C667x for TMS320C6670 and TMS320TCI6616/18

Note that TMS320C6672, TMS320C6674, TMS320C6678 versions can be built by modifying the CCSv5 project build properties predefined symbol from _C6670 to _C6672, _C6674, or _C6678.

C6657 - CTPLib/projects/C6657 for TMS320C6657

TCI6614 - CTPLib/projects/TCI6614 for TMS320TCI6614

C66AK2Hxx - CTPLib/projects/C66AK2Hxx for 66AK2Hxx, TCI6636K2H and TCI663xK2K family of devices

 

Libraries

CPTLib/lib

 

If you do not plan to use CCSV5 project to build this library, you need to use the following information in your non-CCSv5 makefile

 

_C6670 - Predefined symbol required for TMS320C6670 and TMS320TCI6616 builds

_C6672 - Predefined symbol required for TMS320C6672 build

_C6674 - Predefined symbol required for TMS320C6674 build

_C6678 - Predefined symbol required for TMS320C6678 build

_TCI6614 - Predefined symbol required for TMS320TCI6614 build

_TCI6612 - Predefined symbol required for TMS320TCI6612 build

_C6657- Predefined symbol required for TMS320C6657 build

_C66AK2Hxx- Predefined symbol required for 66AK2Hxx, TCI6636K2H and TCI663xK2K build

_STM_Logging – Predefined symbol for all builds that enables the designed-in STMLib dependency. The STM Library is used to provide logging and metadata transport for the CPTLib. Without the metadata, all CP Tracer data is displayed in its raw format. CPTLib supports both internal logging for CP Tracer state changes and user logging. The user logging support provides a mechanism for users to annotate their CP Tracer data.

 

 

Ctools_UCLib:

Ctools_UCLib is a Keystone specific library that provides a use case based API for configuring and controlling AETLib, DSPTraceLib, ETBLib, STMLib and CPTLib.

 

Docs

CTools_UCLib API documentation (Doxygen) at:

Ctools_UCLib/doc/Ctools_UCLib.html/index.html

 

API

Ctools_UCLib /include/ctools_uclib.h

 

Projects

C6657 - Ctools_UCLib/projects/C6657 for TMS320C6657

C6670 - Ctools_UCLib/projects/C6670 for TMS320C6670

C6678 - Ctools_UCLib/projects/C6678 for TMS320C6678

C6657 - Ctools_UCLib/projects/TCI6614 for TMS320TCI6614

C66AK2Hxx - Ctools_UCLib/projects/C66AK2Hxx for 66AK2Hxx, TCI6636K2H and TCI663xK2K family of devices

 

Libraries

Ctools_UCLib /lib

 

Examples

Keystone Ctools_UCLib use-case examples are available as a part of Keystone MCSDK instrumentation. For more details please refer to the link below:

http://processors.wiki.ti.com/index.php/BIOS_MCSDK_2.0_User_Guide#cToolsLibrary

 

If you do not plan to use the CCSV5 project to build these libraries, you need to use the following pre-define symbols in your non-CCSv5 makefile

TCI6614 - Predefined symbol required for TMS320TCI6614 build

C6657 - Predefined symbol required for TMS320C6657 build

C6670 - Predefined symbol required for TMS320C6670 build

C6678 - Predefined symbol required for TMS320C6678 build

C66AK2Hxx and _MIPI_STM - Predefined symbol required for 66AK2Hxx, TCI6636K2H and TCI663xK2K build

_STM_LOGGING – See CPTLib for details.

 

ETMLib:

ETMLib provides APIs to program and capture ETM trace on TCI6614 ARM A8 and C6A816x ARM A8. The same APIs also support programming and capture of PTM trace from 66AK2Hxx, TCI6636K2H, TCI6638K2K, OMAP54xx, and DRA7xx ARM A15s.

 

Docs

ETMLib API documentation (Doxygen) at:

ETMLib/doc/html/index.html

 

API

ETMLib /include/etm_lib.h

 

Projects

ETMLib /projects/A8

 

Libraries

ETMLib /lib

 

 

PMICMILib:

PMICMILib provides an application interface for the PMI and CMI instrumentation. It contains the CCSv5 projects in the PMICMILib/projects directory specifying the supported devices and rules to pickup specific files and flags for different devices.

 

Docs

PMICMILib API documentation (Doxygen) at:

PMICMILib/doc/html/index.html

 

API

PMICMILib/include/CMILib.h

PMICMILib/include/PMILib.h

 

Projects

CMI CortexA9 - PMICMILib/projects/CMI_A9

PMI CortexA9 - PMICMILib/projects/PMI_A9

PMICMI CortexA9 - PMICMILib/projects/PMICMI_A9

PMICMI CortexA9 Linux - PMICMILib/projects/PMICMI_A9_Linux

PMICMI CortexA15 (OMAP5430) - PMICMILib/projects/PMICMI_A15

PMICMI CortexA15 (DRA7xx) - PMICMILib/projects/PMICMI_A15_DRA7xx

 

Libraries

PMICMILib/lib

 

If you do not plan to use the CCSV5 project to build these libraries, you need to use the following information in your non-CCSv5 makefile

 

_OMAP4430 (not required for OMAP54xx)

_DRA7xx – For DRA7xx PMICMILib builds

_CMI – For CMILib and PMICMILib builds

_PMI – For PMILib and PMICMILib builds

_STMLogging – When using STM library

 

Note: The STMLib directory structure must exist to build the PMICMILib.

 

 

SCILib:

SCILib provides a use case based API for configuring and controlling OMAP44xx, OMAP54xx, and DRA7xx Statistic Collectors. The Statistic Collectors generate bus profile data for SDRAM and Masters.

 

Docs

SCILib API documentation (Doxygen) at:

SCILib/doc/sci_omap4430_html/index.html

SCILib/doc/sci_omap4460_html/index.html

SCILib/doc/sci_omap4470_html/index.html

SCILib/doc/sci_omap5430_html/index.html

SCILib/doc/sci_dra7xx_html/index.html

SCILib/doc/sci_am437x_html/index.html

 

API

SCILib/include/SCILib.h

 

Projects

SCILib/projects/omap4430_A9

SCILib/projects/omap4460_A9

SCILib/projects/omap4470_A9

SCILib/projects/omap5430_A15

SCILib/projects/dra7xx_A15

SCILib/projects/am437x_A9

 

 

Libraries

SCILib/lib

 

If you do not plan to use the CCSV5 project to build these libraries, you need to use the following pre-define symbols in your non-CCSv5 makefile

_OMAP4430 - Predefined symbol required for OMAP4430 build

_SC_VER_1_12 - Predefined symbol required for OMAP4430 build

_STM_LOGGING - Predefined symbol for all builds that enables the designed-in STMLib dependency. The STM Library is used to provide logging and metadata transport for SCILib. Without the metadata, all Statistic Collector data is displayed in its raw format. SCILib supports both internal logging for Statistic Collector state changes and user logging. The user logging support provides a mechanism for users to annotate their Statistic Collector data.

_OMAP4460 - Predefined symbol required for OMAP4460 build

_SC_VER_1_16 - Predefined symbol required for OMAP4460, OMAP4470, OMAP5430, DRA7xx and AM437x builds

_OMAP4470 - Predefined symbol required for OMAP4470 build

_OMAP5430 - Predefined symbol required for OMAP5430 build

_DRA7xx - Predefined symbol required for DRA7xx build

_AM437x - Predefined symbol required for AM437x build

 

Examples:

Examples of using all these libraries together are also posted as part of Examples.zip file (CCSv5 projects)

 

TCI6488

TCI6484

C667x

Note – All supported devices are enclosed inside the parentheses.

Note: Some projects include ETB and non-ETB Debug and Release versions (non-ETB version requires XDS560v2 System Trace)

 

C6678

Note – All supported devices are enclosed inside the parentheses.

Note: Some projects include ETB and non-ETB Debug and Release versions (non-ETB version requires XDS560v2 System Trace)

 

TCI6614

Note – All supported devices are enclosed inside the parentheses.

 

C6657

Note – All supported devices are enclosed inside the parentheses.

C66AK2Hxx (Keystone2 family)

Note – All supported devices are enclosed inside the parentheses.

 

Note: Before running ARM PTM examples on 66AK2Hxx, TCI6636K2H and TCI6638K2K EVMs, the ARM PLL initialization and switching ON ARM cores needs to be done. Please, follow the below steps to do the same:

o   connect to the C66xx_0 core and run it’s startup gel

o   Run the GEL script: Scripts --> TCI66x_Functions --> TETRIS_POWERUP_PLL_INIT_100MHZ_to_1000Mhz

Note: Some projects include ETB and non-ETB Debug and Release versions (non-ETB version requires XDS560v2 System Trace)

 

C6A816x

 

OMAP44xx

 

OMAP5430

 

DRA7xx

 

AM437x

 

Prebuilt Example Apps

Examples\bin

 

Instructions to convert and import binary trace data for CC Trace Display:

The BIN2TDF utility converts a binary trace file as exported from the embedded app to the CCS Trace Display readable format (TDF). A TDF file can be imported/loaded in the CCS Trace Display for decode and analysis.

 

BIN2TDF.exe can be found in the CCS_INSTALL/CCSv5/emulation/analysis/bin directory.

 

For more details on how to use BIN2TDF.exe see:

http://processors.wiki.ti.com/index.php/BIN2TDF

 

Examples command line parameters:

 

DSP Trace  

bin2tdf -bin C:/temp/etbdata.bin -app C:/Examples/bin/dsptrace_csetb_d_core0.tci6488.out -procid 64x+ -sirev 3 -rcvr ETB -output C:/Examples/bin/mytrace.tdf -dcmfile C:/temp/dcm.txt'

 

Note that dcm.txt is an empty file unless you are using event trace.

 

 

STM Trace C667x, TCI6616, TCI6614, TCI6612

bin2tdf -bin C:/temp/etbdata.bin -app C66X_0=C:/Examples/bin/stm_d_corepacN.c6670.out -procid stm -sirev 1 -cpuname CSSTM_0 -rcvr ETB -devicekey 0x0009D02F -dcmfile C:/temp/dcm.txt -output C:/Examples/bin/mytrace.tdf

 

Note that C66x_0 is the name of the CPU running the app. 0x0009D02F is the device ID for C667x and TCI6616. 0x0B96202F is the device ID for TCI6614 and TCI6612. 0xB97A02F is the device id for C6657. ETB examples export  etbdata bin and dcm  file  (using CIO for demonstration). Please see examples for specific bin and dcm filenames.

 

 

STM Trace C6A816x A8

bin2tdf -bin C:/temp/etbdata.bin -app CortexA8_0=C:/Examples/bin/ stm_csetb_d_A8.c6a816x.out -procid stm -sirev 1 -cpuname CSSTM_0 -rcvr ETB -devicekey 0x0B81E02F -dcmfile C:/temp/dcm.txt -output C:/Examples/bin/mytrace.tdf'

 

Note that CortexA8_0 is the name of the CPU running the app. 0x0B81E02F is the device ID for C6A816x. etbdata.bin and dcm.txt files are exported by the example application (uses CIO for demonstration)

 

 

PTM Trace DRA7xx A15

bin2tdf -bin C:/temp/ETM_etbdata.bin -app C:/Examples/bin/ptm_tietb_A15.dra7xx.out -procid cortexa15 -rcvr ETB -devicekey 0x0B99002F -dcmfile C:/temp/ETM_etbdata.dcm -output C:/Examples/bin/mytrace.tdf

 

0x0B99002F is the device ID for DRA7xx. ETM_etbdata.bin and ETM_etbdata.dcm files are exported by the PTM Trace example application.