Common Platform (CP) Tracer Library API Reference Guide (TCI6630K2L Version)
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros
CPTLib.h File Reference
#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
#include "../../STMLib/include/StmLibrary.h"
#include "CPTLib_TCI6630K2L.h"

Go to the source code of this file.

Data Structures

struct  _CPT_Qualifiers
 
struct  _CPT_TrigQualifiers
 
struct  _CPT_CfgOptions
 

Macros

#define CPTLIB_MAJOR_VERSION   (0x0)
 
#define CPTLIB_MINOR_VERSION   (0xF)
 
#define CPTLIB_FUNC   (0xe89)
 
#define CPT_FUNC_ID_SCHEME   (0x0)
 

Typedefs

typedef struct _CPT_Handle CPT_Handle_t
 
typedef CPT_Handle_tCPT_Handle_Pntr
 
typedef void(* CPT_CallBack )(const char *funcName, eCPT_Error)
 
typedef struct _CPT_Qualifiers CPT_Qualifiers
 
typedef struct _CPT_TrigQualifiers CPT_TrigQualifiers
 
typedef struct _CPT_CfgOptions CPT_CfgOptions
 

Enumerations

enum  eCPT_Error {
  eCPT_Success = 0, eCPT_Error_Not_Compatible = -1, eCPT_Error_Busy =-2, eCPT_Error_Memory_Allocation =-3,
  eCPT_Error_Module_Enabled = -4, eCPT_Error_Invalid_Parameter = -5, eCPT_Error_NULL_STMHandle = -6, eCPT_Error_MappingError = -8,
  eCPT_Error_ModuleEnableFailed = -9, eCPT_Error_ModuleDisableFailed = -10, eCPT_Error_InvalidHandlePointer = -11, eCPT_Error_DomainPowerUp = -12,
  eCPT_Error_DomainEnable = -13, eCPT_Error_PowerOrModuleDisabled = -14, eCPT_Error_STM = -15
}
 
enum  eCPT_MsgSelects {
  eCPT_MsgSelect_None = 0, eCPT_MsgSelect_Statistics = 1, eCPT_MsgSelect_Event_NewReq = 2, eCPT_MsgSelect_Event_LastWrt = 4,
  eCPT_MsgSelect_Event_LastRd = 8, eCPT_MsgSelect_Event_AccessStatus = 16, eCPT_MsgSelect_Num = 5
}
 
enum  eCPT_CntSelects {
  eCPT_CntSelect_None = 0, eCPT_CntSelect_Grant = 1, eCPT_CntSelect_Wait = 2, eCPT_CntSelect_WaitAndGrant = 3,
  eCPT_CntSelect_Num = 2
}
 
enum  eCPT_TrigOut { eCPT_TrigOut_None = 0, eCPT_TrigOut_EMU1 = 1, eCPT_TrigOut_EMU0 = 2 }
 
enum  eCPT_ThroughputCntID { eCPT_Throughput_Cnt0 = 0, eCPT_Throughput_Cnt1 = 1 }
 
enum  eCPT_MasterState {
  eCPT_Mstr_Disable_Grp, eCPT_Mstr_Enable_Grp, eCPT_Mstr_Disable, eCPT_Mstr_Enable,
  eCPT_Mstr_DisableALL, eCPT_Mstr_EnableAll
}
 
enum  eCPT_SrcQual { eCPT_SrcQual_IncludeALL = 0, eCPT_SrcQual_ExCPUDataAccess = 1, eCPT_SrcQual_ExCPUInstAccess = 2, eCPT_SrcQual_ExDMAAccess = 4 }
 
enum  eCPT_RWQual { eCPT_RWQual_None, eCPT_RWQual_ReadOnly, eCPT_RWQual_WriteOnly, eCPT_RWQual_ReadWrite }
 
enum  eCPT_TrigIn { eCPT_TrigInDisable, eCPT_TrigInEnable }
 
enum  eCPT_FilterMode { eCPT_FilterMode_Inclusive, eCPT_FilterMode_Exclusive }
 
enum  eCPT_MsgPri {
  eCPT_MsgPri_0, eCPT_MsgPri_1, eCPT_MsgPri_2, eCPT_MsgPri_3,
  eCPT_MsgPri_4, eCPT_MsgPri_5, eCPT_MsgPri_6, eCPT_MsgPri_7
}
 
enum  eCPT_AddrMode {
  eCPT_AddrMode_32bits, eCPT_AddrMode_36bits, eCPT_AddrMode_40bits, eCPT_AddrMode_44bits,
  eCPT_AddrMode_48bits
}
 
enum  eCPT_IntStatus { eCPT_IntStatus_Inactive, eCPT_IntStatus_Active }
 
enum  eCPT_IntMask { eCPT_IntMask_Disable, eCPT_IntMask_Enable }
 
enum  eCPT_WaitSelect { eCPT_WaitDisable, eCPT_WaitEnable }
 
enum  eCPT_UseCase {
  eCPT_UseCase_Raw, eCPT_UseCase_TotalProfile, eCPT_UseCase_MasterProfile, eCPT_UseCases_SysBandwidthProfile = 0xFFE1,
  eCPT_UseCases_SysLatencyProfile = 0xF2F1
}
 

Functions

eCPT_Error CPT_OpenModule (CPT_Handle_Pntr *const pCPT_Handle, const eCPT_ModID CPT_ModId, CPT_CfgOptions const *const pCPT_CfgOptions)
 
eCPT_Error CPT_CloseModule (CPT_Handle_Pntr *const pCPT_Handle)
 
eCPT_Error CPT_GetVersion (CPT_Handle_Pntr const pCPT_Handle, uint32_t *const pLibMajorVersion, uint32_t *const pLibMinorVersion, uint32_t *const pSWFuncID, uint32_t *const pHwFuncID)
 
eCPT_Error CPT_ModuleEnable (CPT_Handle_Pntr const pCPT_Handle, const eCPT_MsgSelects CPT_MsgEnables, const eCPT_CntSelects CPT_CntEnables)
 
eCPT_Error CPT_ModuleDisable (CPT_Handle_Pntr const pCPT_Handle, eCPT_WaitSelect CPT_WaitSelect)
 
eCPT_Error CPT_CfgMaster (CPT_Handle_Pntr const pCPT_Handle, const eCPT_MasterID CPT_MasterID, const eCPT_ThroughputCntID CPT_ThroughputCnt, const eCPT_MasterState CPT_MasterState)
 
eCPT_Error CPT_CfgQualifiers (CPT_Handle_Pntr const pCPT_Handle, CPT_Qualifiers const *const pCPT_TPCnt0Qual, CPT_Qualifiers const *const pCPT_TPCnt1Qual, CPT_Qualifiers const *const pCPT_TPEventQual, CPT_TrigQualifiers const *const pCPT_TrigQual)
 
eCPT_Error CPT_CfgAddrFilter (CPT_Handle_Pntr const pCPT_Handle, const uint32_t AddrFilterMSBs, const uint32_t StartAddrFilterLSBs, const uint32_t EndAddrFilterLSBs, const eCPT_FilterMode CPT_FilterMode)
 
eCPT_Error CPT_CfgPacing (CPT_Handle_Pntr const pCPT_Handle, const uint32_t PacingCntValue)
 
eCPT_Error CPT_CfgMsgPriority (CPT_Handle_Pntr const pCPT_Handle, const eCPT_MsgPri CPT_StatisticMsgsPri, const eCPT_MsgPri CPT_NewRequestEventMsgPri, const eCPT_MsgPri CPT_LastWriteEventMsgPri, const eCPT_MsgPri CPT_LastReadEventMsgPri, const eCPT_MsgPri CPT_AccessStatusMsgPri)
 
eCPT_Error CPT_GetAddrMode (CPT_Handle_Pntr const pCPT_Handle, eCPT_AddrMode *const pAddrModeRange)
 
eCPT_Error CPT_GetCurrentState (CPT_Handle_Pntr const pCPT_Handle, uint32_t *const pCPT_ThroughPutCnt0, uint32_t *const pCPT_ThroughPutCnt1, uint32_t *const pCPT_WaitCnt, uint32_t *const pCPT_GrantCnt, uint32_t *const pAccessStatus)
 
eCPT_Error CPT_CfgInt (CPT_Handle_Pntr const pCPT_Handle, const eCPT_IntMask CPT_IntMask)
 
eCPT_Error CPT_GetIntStatus (CPT_Handle_Pntr const pCPT_Handle, eCPT_IntStatus *const pCPT_IntStatus)
 
eCPT_Error CPT_ClrIntStatus (CPT_Handle_Pntr const pCPT_Handle)
 
eCPT_Error CPT_LogMsg (CPT_Handle_Pntr const pCPT_Handle, const char *FmtString, uint32_t *const pValue)
 

Detailed Description

CPT Library Function Prototypes

Macro Definition Documentation

#define CPTLIB_MAJOR_VERSION   (0x0)

Major version number - Incremented for API changes

#define CPTLIB_MINOR_VERSION   (0xF)

Minor version number - Incremented for bug fixes

#define CPTLIB_FUNC   (0xe89)

CP Tracer Module Func ID this library supports

#define CPT_FUNC_ID_SCHEME   (0x0)

Library is functionally compatible with modules that have this id scheme

Typedef Documentation

typedef struct _CPT_Handle CPT_Handle_t
CPT_Handle_t
CPT Handle object. This is an incomplete structure, thus making the actual implementation private to the CPTLib.
CPT_Handle_Pntr
Pointer to a CPT Handle object
typedef void(* CPT_CallBack)(const char *funcName, eCPT_Error)
CPT_CallBack
Parameters
[in]funcNameConstant char pointer to the function name. Normally provided by the compiler using the FUNCTION macro.
[in]eCPT_Errorerror returned by calling routine
CPT_Qualifiers
Throughput counter qualifiers
CPT_TrigQualifiers
Trigger out qualifiers and enable/disable control
CPT_CfgOptions
CPT Configuration Options

Enumeration Type Documentation

enum eCPT_Error
eCPT_Error
CPT Library error codes
Enumerator
eCPT_Success 

Function completed successfully, handle allocated

eCPT_Error_Not_Compatible 

Library and device module not compatible

eCPT_Error_Busy 

CP Tracer module already owned, potential conflict with Debugger

eCPT_Error_Memory_Allocation 

Memory allocation error

eCPT_Error_Module_Enabled 

Can't change module state while module enabled

eCPT_Error_Invalid_Parameter 

Invalid function parameter

eCPT_Error_NULL_STMHandle 

Invalid function call because library opened with a NULL STM Handle

eCPT_Error_MappingError 

Attempt to map module's base address failed

eCPT_Error_ModuleEnableFailed 

Module Enable Failed

eCPT_Error_ModuleDisableFailed 

Module Disable Failed

eCPT_Error_InvalidHandlePointer 

Invalid handle Pointer

eCPT_Error_DomainPowerUp 

Error occurred while attempting to power-up the CP Tracer power domain

eCPT_Error_DomainEnable 

Error occurred while attempting to enable the CP Tracer module

eCPT_Error_PowerOrModuleDisabled 

The domain power is off or the module is disabled. Both the domain power and module are enabled by CPT_OpenModule(). If a function finds the power has been turned off or the module disabled, this error will be returned.

eCPT_Error_STM 

error value - eCPT_Error_STM provides STMError value

eCPT_MsgSelects
STM message generation select options
Enumerator
eCPT_MsgSelect_None 

Don't modify STM message export selection

eCPT_MsgSelect_Statistics 

Select statistic counters for STM messages generation

eCPT_MsgSelect_Event_NewReq 

Select Event B (New Request events) for STM messages generation

eCPT_MsgSelect_Event_LastWrt 

Select Event C (Last write events) for STM messages generation

eCPT_MsgSelect_Event_LastRd 

Select Event E (Last read events) for STM messages generation

eCPT_MsgSelect_Event_AccessStatus 

Select access status for STM messages generation

eCPT_CntSelects
Counter select options
Enumerator
eCPT_CntSelect_None 

Don't Modify Counter enables

eCPT_CntSelect_Grant 

Enable grant counter

eCPT_CntSelect_Wait 

Enable wait counter

eCPT_CntSelect_WaitAndGrant 

Enable wait and grant counters

eCPT_TrigOuts
Trigger out select options
Enumerator
eCPT_TrigOut_None 

Trigger out none - trigger out disabled

eCPT_TrigOut_EMU1 

EMU1 Trigger out

eCPT_TrigOut_EMU0 

EMU0 Trigger out

eCPT_ThroughputCntID
Counter select options
Enumerator
eCPT_Throughput_Cnt0 

Throughput Counter 0 Select

eCPT_Throughput_Cnt1 

Throughput Counter 1 Select

eCPT_MasterState
Counter select options
Enumerator
eCPT_Mstr_Disable_Grp 

Disabled a master group. This disable also works for masters with a single id and should be the typical disable used for most cases. Master id groups are designated with an _n in the eCPT_MasterID table.

eCPT_Mstr_Enable_Grp 

Enabled a master group. This enable also works for masters with a single id and should be the typical enable used for most cases. Master id groups are designated with an _n in the eCPT_MasterID table.

eCPT_Mstr_Disable 

Disabled a single master

eCPT_Mstr_Enable 

Enabled a single master

eCPT_Mstr_DisableALL 

Disable All Masters

eCPT_Mstr_EnableAll 

Enable All Masters

eCPT_SrcQual
New Request source selection options. Any source not explicitly excluded is enabled for data capture. Note: Some CP Tracer modules DTYPE field are tied off to DMA access. This means that if you exclude DMA accesses for these CP Tracer modules you will in effect exclude all access types. See eCPT_MasterID for details.
Enumerator
eCPT_SrcQual_IncludeALL 

Include all sources

eCPT_SrcQual_ExCPUDataAccess 

Exclude CPU Data Accesses

eCPT_SrcQual_ExCPUInstAccess 

Exclude Inst Access

eCPT_SrcQual_ExDMAAccess 

Exclude DMA Access

eCPT_RWQual
Transaction (read/write) selection options
Enumerator
eCPT_RWQual_None 

Do not capture read or write transactions

eCPT_RWQual_ReadOnly 

Capture only read transactions

eCPT_RWQual_WriteOnly 

Capture only write transactions

eCPT_RWQual_ReadWrite 

Capture read and write transactions

eCPT_TrigInState
Counter select options
Enumerator
eCPT_TrigInDisable 

EMU Trigger in disable

eCPT_TrigInEnable 

EMU Trigger in enable

eCPT_FilterMode
Address filter inclusive/Exclusive selection
Enumerator
eCPT_FilterMode_Inclusive 

Inclusive address filter

eCPT_FilterMode_Exclusive 

Exclusive address filter

eCPT_MsgPri
Message transport priority
Enumerator
eCPT_MsgPri_0 

Priority level 0 - Highest Priority

eCPT_MsgPri_1 

Priority level 1

eCPT_MsgPri_2 

Priority level 2

eCPT_MsgPri_3 

Priority level 3

eCPT_MsgPri_4 

Priority level 4

eCPT_MsgPri_5 

Priority level 5

eCPT_MsgPri_6 

Priority level 6

eCPT_MsgPri_7 

Priority level 7 - Lowest priority, default priority

eCPT_AddrMode
CPT Address Mode
Enumerator
eCPT_AddrMode_32bits 

32 bit address mode

eCPT_AddrMode_36bits 

36 bit address mode

eCPT_AddrMode_40bits 

40 bit address mode

eCPT_AddrMode_44bits 

44 bit address mode

eCPT_AddrMode_48bits 

48 bit address mode

eCPT_IntStatus
CPT Interrupt status
Enumerator
eCPT_IntStatus_Inactive 

CPT Interrupt Inactive

eCPT_IntStatus_Active 

CPT Interrupt Active

eCPT_IntState
CPT Interrupt state
Enumerator
eCPT_IntMask_Disable 

CPT Interrupt Disable

eCPT_IntMask_Enable 

CPT Interrupt Enable

eCPT_WaitSelect
CPT Wait for the next CP Tracer sample window to expire enabled/disable
eCPT_UseCase
Use Case element used by CPT_CfgOptions


Note - Event messages can be generated with any use case. When only generating event messages either the eCPT_UseCase_TotalProfile or eCPT_UseCase_MasterProfile use cases can be used.

Enumerator
eCPT_UseCase_Raw 

CPT data provided on host will consist of raw CPT messages

eCPT_UseCase_TotalProfile 

The raw CPT messages will be processed into the following data:

  • Percentage of total slave activity utilized by selected masters
  • Slave Bus Bandwidth (bytes/second*) utilized by the selected master
  • Average Access Size of slave transactions
  • Bus Utilization (transactions per second*)
  • Contention Percentage
  • Minimum Average Latency
                                    \n Note - See CPUClockRateMhz on requirements for reporting time related data (bytes/second)
eCPT_UseCase_MasterProfile 

The raw CPT messages will be processed into the following data:

  • Slave Bus Bandwidth (bytes/second*) utilized by master 0
  • Slave Bus Bandwidth (bytes/second*) utilized by master 1
  • Average Access Size of slave transactions for the two master groups
  • Bus Utilization (transactions per second*)
  • Contention Percentage
  • Minimum Average Latency
                                    \n Note - See CPUClockRateMhz on requirements for reporting time related data (bytes/second)
eCPT_UseCases_SysBandwidthProfile 

This is the System Bandwidth Profile use case. All data host processing is disabled except for the Slave Bus Bandwidth.

eCPT_UseCases_SysLatencyProfile 

This is the System Latency Profile use case. All data host processing is disabled except for the Slave Bus Average Latency.

Function Documentation

eCPT_Error CPT_OpenModule ( CPT_Handle_Pntr *const  pCPT_Handle,
const eCPT_ModID  CPT_ModId,
CPT_CfgOptions const *const  pCPT_CfgOptions 
)
CPT_OpenModule

Open a CPT Library API for a specific CP Tracer module.

Parameters
[out]pCPT_HandleA pointer to a NULL CPT_Handle_Pntr . If CPT_OpenModule exits with the return value of eCPT_Success, pCPT_Handle is set to a valid CPT_Handle pointer.
[in]CPT_ModIdeCPT_ModID is the enumerated identifier for the physical CP tracer module that is opened.
[in]pCPT_CfgOptionsA pointer to the CPT_CfgOptions structure. If pCPT_CfgOptions is NULL all parameters are set to their default values.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

This function must be called and return eCPT_Success prior to calling any other CPT Library function that requires a CPT_Handle_Pntr. If this function is called with a non-NULL pCPT_Handle pointer this function will exit and return eCPT_Error_InvalidHandlePointer immediately.

Before any CP Tracer registers can be accessed, the DebugSS power domain (includes the CP Tracers) must be powered up and enabled. If the domain is powered down the library will attempt to power up and enable the domain. The transition (to the power up and enable state) is tested using a retry count (CPT_PU_RETRY_CNT). If the number of retries reaches 0 this function will exit with eCPT_Error_DomainPowerUp or eCPT_Error_DomainEnable errors.

If the device's CP Tracer module is not compatible with this version of the library, this function will exit and return eCPT_Error_Not_Compatible.

If the CP Tracer Module is already owned by the IDE (Debugger) this function will exit and return eCPT_Error_Busy. This error can occur if the IDE is using the module and has not released the CP Tracer module (clear both the Ownership and Destination Registers - set them to their reset state). The error can also occur if the eCPT_ModID requested is already opened (possibly by a different instance of the library), or the client software has changed the state of the CPT Register directly. In the case where a ownership conflict is not with the IDE, the forceOwnership configuration option can be used to avoid an ownership conflict if the users application is simply restarted (not reset). Note that the ownership check is performed by every CPT Library function to protect the client in case the IDE forces ownership to itself.

Storage for CPT_Handle is allocated through a call to the client provided external function cTools_memAlloc(). If a memory allocation error occurs this function returns eCPT_Error_Memory_Allocation. cTools_memMap(), also a client provided function, is called to map the physical CPT Module base address to a virtual address space. If a mapping error occurs this function returns eCPT_Error_MappingError. The client provided cTools_mutexInit() and cTools_mutexTrylock() functions are called to initialize and attempt to lock the requested CP Tracer to this instance of the CPTLib. If the lock fails eCPT_Error_Busy is returned. See index for client provided Helper Function prototypes used by CPT_OpenModule.

If there are no errors detected the function exits with eCPT_Success.

Base addresses for each supported CP Tracer are provided in device specific include files.

If pCPT_CfgOptions is a NULL pointer, the default configuration parameters are:

  • CPT_CallBack is NULL.
  • pSTMHandle is NULL.
  • Sample window size is 64K.
  • AddrExportMask is 0.

If the function exits with eCPT_Success the device's CPT module default values are set to:

  • Sample window size is set to 0 to leave unit disabled.
  • Message export address mask set from pCPT_CfgOptions. If pCPT_CfgOptions is NULL the default value is used.
  • All STM Export Message priorities are set to the lowest priority.
  • Trigger in and Trigger out functions are disabled (EMU0 and EMU1) and the Trigger out Qualifiers are disabled.
  • All Trigger Out (EMU0/1), Throughput Counters and New Request Event (Event B) data selection qualifiers (CPU Data, CPU Inst, DMA) and read and write transactions are enabled. These must be explicitly disabled by calls to CPT_CfgQualifiers().
  • Address filtering disabled.
  • Access Status pacing is disabled.
  • The CPT interrupt (on the sample window) is disabled.
  • No masters enabled for statistic counting or event generation. Must call CPT_CfgMaster() to select a master to enable.
  • Message export is disabled. Must call CPT_ModuleEnable() to start export of CP Tracer STM Messages.

If a client is satisfied with the default parameters after CPT_OpenModule()is called, the minimum set of functions that must be called to enable STM message generation are CPT_CfgMaster() and CPT_ModuleEnable().

If pCPT_CfgOptions->pSTMHandle is not NULL the CPT Library is capable of generating both client provided messages (see CPT_LogMsg())and meta data messages (generated by CPT_ModuleEnable() and CPT_ModuleDisable()). Meta data messages provide information needed by data analysis tools (such as the Trace Analyzer).

If pCPT_CfgOptions->pCPT_CallBack is set to a none NULL value, then any library function that returns an error will call CPT_CallBack()prior to exiting the function.

pCPT_CfgOptions->SampleWindowSize and pCPT_CfgOptions->AddrExportMask can only be set when the library is opened to gaurd against modification of these parameters during a STM data recording session.

eCPT_Error CPT_CloseModule ( CPT_Handle_Pntr *const  pCPT_Handle)
CPT_CloseModule

Close the CPT Library for a specific CP Tracer module. Disable STM export from the CP Tracer module, release ownership, and free the CPT_Handle storage.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action. If the CP Tracer module is enabled (see CPT_ModuleEnable()), STM data export is disabled (CPT_ModuleDisable() called automatically). Ownership of the CP Tracer module is released. The CPT_Handle is destroyed through a call to the client provided external function STM_memFree. The CPT Module Base Address is unmapped through a call to the client provided external function cTools_memUnMap. In the event a CPT module error is detected, the CPT_Handle is still destroyed. The pCPT_Handle pointer is also set to NULL, thus making CPT Library functions called with this CPT_Handle after CPT_CloseModule is called invalid. If the CPT library was opened with a non-null CPT_CallBack function, prior to exiting with any error condition the CPT_CallBack function is called.

This function may be used at any time with a valid pCPT_Handle (provided by CPT_OpenModule()).


Prototype for client provided functions:
void STM_memFree(void *p)
void STM_memUnMap(void * vAddr, unsigned int mapSizeInBytes) if virtual address mapping not required simply return.

eCPT_Error CPT_GetVersion ( CPT_Handle_Pntr const  pCPT_Handle,
uint32_t *const  pLibMajorVersion,
uint32_t *const  pLibMinorVersion,
uint32_t *const  pSWFuncID,
uint32_t *const  pHwFuncID 
)
CPT_GetVersion

Get CPT Library version and the Physical Module's version.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[out]pLibMajorVersionCPT Library Major Version (API modifications not backward compatible)
[out]pLibMinorVersionCPT Library Minor Version (Backward compatible modifications and bug fixes)
[out]pSWFuncIDThe device’s CMI Module Functional ID the library is compatible with
[out]pHwFuncIDThe actual device's CMI Module Functional ID
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

This function provides the major and minor version numbers of the CPT library. These values can be compared with the following macro values in CPT_Common.h to confirm that the version of the library matches that of the header file.

The pCMISWFuncID value must match the pCMIHwFuncID value for a call to CMI_OpenModule not to return eCPT_Error_Not_Compatible error.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

This function can be called while the CP Tracer is enabled (see CPT_ModuleEnable()) or disabled (see CPT_ModuleDisable()).

eCPT_Error CPT_ModuleEnable ( CPT_Handle_Pntr const  pCPT_Handle,
const eCPT_MsgSelects  CPT_MsgEnables,
const eCPT_CntSelects  CPT_CntEnables 
)
CPT_ModuleEnable

Enable the CP Tracer module's STM message export and counters.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]CPT_MsgEnableseCPT_MsgSelects provides selection for statistic and event STM messages enables
[in]CPT_CntEnableseCPT_CntSelects provide selection of counters to enable.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

Multiple eCPT_MsgSelects can be or'ed together to select multiple message sources at the same time. Multiple eCPT_CntSelects can be or'ed together to select multiple counters. Any eCPT_MsgSelects or eCPT_CntSelects not selected are cleared (disabled).

This is normally the last command issued to enable the CP Tracer counters, start STM message generation (if enabled) for statistic and event messages.

Sample window size is set to the value provided CPT_openModule() through pCPT_CfgOptions to enable the physical unit. If pCPT_CfgOptions was NULL the default value is used (see CPT_openModule()).

Parameters that must be set before calling this function are:

  • Masters selected (see CPT_CfgMaster() )
  • Qualifiers if any required (see CPT_setQualifiers()
  • Filters if any required (see CPT_setAddressFilter())

If CPT_OpenModule() was called with a non-NULL pCPT_CfgOptions->pSTMHandle, and CPT_CfgOptions->STM_LogMsgEnable is enabled, the appropriate CPT logging messages will be transported for each active eCPT_MsgSelects and eCPT_CntSelects:
Module "CPT", Data Message:"Statistic counters msg gen enabled", Type: "Message", Domain: "CP_TracerName", Class "CPTLib Message"
Module "CPT", Data Message:"New Request event msg gen enabled", Type: "Message", Domain: "CP_TracerName", Class "CPT Message"
Module "CPT", Data Message:"Last Write event msg gen enabled ", Type: "Message", Domain: "CP_TracerName", Class "CPT Message"
Module "CPT", Data Message:"Last Read event msg gen enabled", Type: "Message", Domain: "CP_TracerName", Class "CPT Message"
Module "CPT", Data Message:"Access Status msg gen enabled", Type: "Message", Domain: "CP_TracerName", Class "CPT Message"
Module "CPT", Data Message:"Wait Counter enabled", Type: "Message", Domain: "CP_TracerName", Class "CPT Message"
Module "CPT", Data Message:"Grant Counter enabled", Type: "Message", Domain: "CP_TracerName", Class "CPT Message"

If CPT_OpenModule() was called with a non-NULL pCPT_CfgOptions->pSTMHandle, the following CPT meta data messages will be transported:
Module: "CPTLib", Data Message:"CP Tracer UID, SID, major ver, minor ver, sampleWindowValue, AddrExportMask, CPUClockRateMhz", Type: "Meta", Domain: "CP Tracer Name", Class NULL

The module is then enabled for activity collection, STM message generation if enabled and trigger outs if enabled.

This function may be used at any time the physical CPT module is disabled (see CPT_ModuleDisable()). If the CP Tracer is already enabled this function will exit and return eCPT_Error_Module_Enabled.

During a STM message data recording session the client may call CPT_ModuleEnable() and CPT_ModuleDisable() as needed to restrict CP Tracer STM data export to just those times where the CP Tracer data is relevant. If capturing data to a circular buffer, it's also advisable to disable the CP Tracer STM data export once the observation period is complete, stopping the flow of CP Tracer STM data coordinated with the event being monitored. This will cause the meta data to be re-broadcast to allow for recovery if the meta data exported by the last call to CPT_ModuleEnable() was lost due to the capture buffer wrapping, which is very likely in the ETB case.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_ModuleDisable ( CPT_Handle_Pntr const  pCPT_Handle,
eCPT_WaitSelect  CPT_WaitSelect 
)
CPT_ModuleDisable

Disable the CP Tracer module's STM message export and counters.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]CPT_WaitSelecteCPT_WaitSelect provides selection to disable or enable waiting for the next sample window to expire prior to disabling the CP Tracer.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

If CPT_WaitSelect is set to eCPT_WaitEnable then prior to disabling the CP tracer, this function will spin in a wait loop until it detects the next expired sample window. This will guarantee the last CP tracer data is exported before the CP Tracer unit is disabled. The maximum number of cycles this function will wait for the sample window to expire is the sample window size multiplied by the CP tracers clock divide-by-factor(either 2 0r 3), so this function could be in the spin loop for a very long time (thus the user option to enable or disable this capability). To disable the unit the sample window size is set to 0 disabling all STM message generation and counters. This function must be called prior to any CPT_cfgXXXX functions that changes the selected CP Tracer's programming.

If CPT_OpenModule() was called with a non-NULL pCPT_CfgOptions->pSTMHandle, and CPT_CfgOptions->STM_LogMsgEnable is enabled, the following CPT logging messages will be transported.


Module "CPT", Data Message:"Msg generation disabled", Type: Message, Domain: "CP_TracerName", Class "CPT Message"

If CPT_OpenModule was called with a non-NULL pCPT_CfgOptions->pSTMHandle a CPT meta data message is transported.

The module is then disabled and STM message generation is suspended.

This function may be used at any time the CP Tracer is enabled (see CPT_ModuleDisable()). If the CP Tracer is already disabled this function does nothing and returns eCPT_Success.

During a STM message data recording session the client may call CPT_ModuleEnable() and CPT_ModuleDisable() as needed to restrict CP Tracer STM data export to just those times where the CP Tracer data is relevant. If capturing data to a circular buffer, it's also advisable to disable the CP Tracer STM data export once the observation period is complete, stopping the flow of CP Tracer STM data coordinated with the event being monitored. This will cause the meta data to be re-broadcast to allow for recovery if the meta data exported by the last call to CPT_ModuleEnable() was lost due to the capture buffer wrapping, which is very likely in the ETB case.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_CfgMaster ( CPT_Handle_Pntr const  pCPT_Handle,
const eCPT_MasterID  CPT_MasterID,
const eCPT_ThroughputCntID  CPT_ThroughputCnt,
const eCPT_MasterState  CPT_MasterState 
)
CPT_CfgMaster

Select a master to enable or disable for a Throughput Counter. Note that the master selections for Throughput Counter 0 also apply to New Request events and Access Status events.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]CPT_MasterIDeCPT_MasterID provides master id selection for throughput counting. Master Ids selected for Throughput Counter 0 also apply to Event B (New Request) and Event E (Last Read).
[in]CPT_ThroughputCnteCPT_ThroughputCntID provides Throughput Counter selection the CPT_MasterID is associated with.
[in]CPT_MasterStateeCPT_MasterState provides enable or disable selection for a single bus master id or a bus master id group (in both cases designated by CPT_MasterID) or can provide enable/disable of all bus masters (CPT_MasterID ignored). A master id group is a special case bus master that utilize more than one master id for different types of accesses. To accommodate these eCPT_MasterState also has provisions for enabling/disabling all the masters in the group (eCPT_Mstr_Disable_Grp/eCPT_Mstr_Enable_Grp). Master id groups are designated with an _GrpN suffix in the eCPT_MasterID table. When modifying the state (eCPT_Mstr_Disable_Grp/eCPT_Mstr_Enable_Grp) of a group id the "_Grp0" master id must be specified with the CPT_MasterID parameter. Using the group state selection (enabling or disabling)is the typical case and will work for masters that have just a single id (no _GrpN suffix).
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

The default state, set by a successful call to CPT_OpenModule, is all masters are disabled for statistic counting and event generation.

This function may be called multiple times to enable/disable more than one master. Enabling or disabling a master does not effect the state of other masters.

Note that not every master can physically access every slave. This function makes no attempt to protect the client from enabling masters that are invalid for the specific slave. If a statistic counter does not advance when enabled then the reason can be either the selected master is not generating the expected cycles or the selected master can't reach the slave.

This function may only be called while the CP Tracer is disabled. If the CP Tracer is already enabled ( see CPT_ModuleEnable()) the Master parameters will not be updated and this function will exit and return eCPT_Error_Module_Enabled.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_CfgQualifiers ( CPT_Handle_Pntr const  pCPT_Handle,
CPT_Qualifiers const *const  pCPT_TPCnt0Qual,
CPT_Qualifiers const *const  pCPT_TPCnt1Qual,
CPT_Qualifiers const *const  pCPT_TPEventQual,
CPT_TrigQualifiers const *const  pCPT_TrigQual 
)
CPT_CfgQualifiers

Select qualifiers for Throughput Counters(0 and 1), New Request Events and Trigger out (on EMU0/1 pins).

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]pCPT_TPCnt0QualPointer to a CPT_Qualifiers structure. A CPT_Qualifiers structure provides Event B (New Request) Data Qualifiers (CPU Data, CPU Inst, DMA) and read/write transaction qualifiers for Throughput Counter 0.
[in]pCPT_TPCnt1QualPointer to a CPT_Qualifiers structure. A CPT_Qualifiers structure provides Event B (New Request) Data Qualifiers (CPU Data, CPU Inst, DMA) and read/write transaction qualifiers for Throughput Counter 1.
[in]pCPT_TPEventQualPointer to a CPT_Qualifiers structure. A CPT_Qualifiers structure provides New Request Data Qualifiers (CPU Data, CPU Inst, DMA) and read/write transaction qualifiers for New Request Event generation.
[in]pCPT_TrigQualPointer to a CPT_TrigQualifiers structure. A CPT_TrigQualifiers structure provides enable/disable control of trigger inputs and outputs (using EMU0/1 signals), and provides New Request Data Qualifiers (CPU Data, COU Inst, DAM) and read/write transaction qualifiers for trigger outputs.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

The default state, set by a successful call to CPT_OpenModule, is all dtype qualifiers are enabled, all read/write qualifiers are enabled, EMU0/1 start/stop qualification is disabled.

For a non-NULL argument structure, any qualifier that is not explicitly excluded through one of the structure elements will be enabled. For a NULL argument structure, the qualifiers are not modified.

This function may only be called while the CP Tracer is disabled. If the CP Tracer is already enabled ( see CPT_ModuleActivityEnable())the Qualifier parameters will not be updated and this function will exit and return eCPT_Error_Module_Enabled.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

For some CP Tracers there are filtering limitations built into the implementation. Limitations are defined per eCPT_MasterID.

eCPT_Error CPT_CfgAddrFilter ( CPT_Handle_Pntr const  pCPT_Handle,
const uint32_t  AddrFilterMSBs,
const uint32_t  StartAddrFilterLSBs,
const uint32_t  EndAddrFilterLSBs,
const eCPT_FilterMode  CPT_FilterMode 
)
CPT_CfgAddrFilter

Modify address filters for Throughput Counters(0 and 1), New Request Events and Trigger out (on EMU0/1 pins).

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]AddrFilterMSBsAddress filter MSBs (address bits 63:32). The bits used must be valid for the CP Tracer slave (See CPT_getAddrMode()). These bits are applied to both the start and end address.
[in]StartAddrFilterLSBsStart address filter LSBs (address bits 31:0).
[in]EndAddrFilterLSBsEnd address filter LSBs (address bits 31:0).
[in]CPT_FilterModeeCPT_FilterMode provides selection for inclusive/exclusive address filter modes.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

The default state, set by a successful call to CPT_OpenModule, is all address filters are disabled.

Setting the EndAddrFilterLSBs to zero disables address filtering. Setting the EndAddrFilter to a non-zero value enables address filtering. If the AddrFilterMSBs are set outside the range defined for the CP Tracer slave (from address mode range - see CPT_GetAddrMode()), the Address Filter parameters will not be updated and the function will exit with eCPT_Error_Invalid_Parameter.

This function may only be called while the CP Tracer is disabled. If the CP Tracer is already enabled ( see CPT_ModuleActivityEnable()) the Address Filter parameters will not be updated and this function will exit and return eCPT_Error_Module_Enabled.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_CfgPacing ( CPT_Handle_Pntr const  pCPT_Handle,
const uint32_t  PacingCntValue 
)
CPT_CfgPacing

Configure Access Status pacing.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]PacingCntValue24-bit value to set pacing counter.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

The default Access Status Pacing state, set by a successful call to CPT_OpenModule, is disabled (Pacing Counter is set to zero).

If PacingCntValue is set to zero, the Access Status STM messages are exported periodically as the sample window expires. If the PacingCntValue is a non-zero value that is less than the sample window size, then the Access Status STM messages are exported periodically as the pacing counter expires (at a rate set by the PacingCntValue). In this case when the sample window expires an additional Access Status message is generated and the pacing counter restarted. In the case the PacingCntValue is greater than the Sample Window size, Access Status messages are only generated periodically as the sample window expires.

If the PacingCntValue exceeds 24 bits the PacingCntValue will not be updated and the function will exit with eCPT_Error_Invalid_Parameter.

This function may only be called while the CP Tracer is disabled. If the CP Tracer is already enabled ( see CPT_ModuleActivityEnable()) the Pacing parameter will not be updated and this function will exit and return eCPT_Error_Module_Enabled.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_CfgMsgPriority ( CPT_Handle_Pntr const  pCPT_Handle,
const eCPT_MsgPri  CPT_StatisticMsgsPri,
const eCPT_MsgPri  CPT_NewRequestEventMsgPri,
const eCPT_MsgPri  CPT_LastWriteEventMsgPri,
const eCPT_MsgPri  CPT_LastReadEventMsgPri,
const eCPT_MsgPri  CPT_AccessStatusMsgPri 
)
CPT_CfgMsgPriority

Configure STM message priorities.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]CPT_StatisticMsgsPrieCPT_MsgPri provides priority level for Statistic messages (from counters).
[in]CPT_NewRequestEventMsgPrieCPT_MsgPri provides priority level for Event B (New Request Event) messages.
[in]CPT_LastWriteEventMsgPrieCPT_MsgPri provides priority level for Event C (Last Write Event) messages.
[in]CPT_LastReadEventMsgPrieCPT_MsgPri provides priority level for Event E (Last Read Event) messages.
[in]CPT_AccessStatusMsgPrieCPT_MsgPri provides priority level for Access Status messages.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

The default priority for all message types, set by a successful call to CPT_OpenModule, is the lowest.

This function may only be called while the CP Tracer is disabled. If the CP Tracer is already enabled ( see CPT_ModuleActivityEnable()) the STM message priorities will not be updated and this function will exit and return eCPT_Error_Module_Enabled.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_GetAddrMode ( CPT_Handle_Pntr const  pCPT_Handle,
eCPT_AddrMode *const  pAddrModeRange 
)
CPT_GetAddrMode

Get Address mode for the specific CP Tracer.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[out]pAddrModeRangeeCPT_AddrMode provides the available address mode returned for the specific CP trace module.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

This function may be used at any time.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_GetCurrentState ( CPT_Handle_Pntr const  pCPT_Handle,
uint32_t *const  pCPT_ThroughPutCnt0,
uint32_t *const  pCPT_ThroughPutCnt1,
uint32_t *const  pCPT_WaitCnt,
uint32_t *const  pCPT_GrantCnt,
uint32_t *const  pAccessStatus 
)
CPT_GetCurrentState

Get the current state of the specific CP Tracer's counters and Access Status.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[out]pCPT_ThroughPutCnt0Return location for the current Throughput 0 Counter value.
[out]pCPT_ThroughPutCnt1Return location for the current Throughput 1 Counter value.
[out]pCPT_WaitCntReturn location for the current Wait Count (in CP Tracer clocks) value
[out]pCPT_GrantCntReturn location for the current Grant Counter value.
[out]pAccessStatusReturn location for the current Access Status value.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

This function may be used at any time.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

Note that this function provides values relative to the last sample window expiration and the values are read atomically (with interrupts disabled). If all the registers are read while the current sample window expires the context of the registers will not match. So it's recommended that this function be called from an ISR (see CPT_CfgInt()) that:

  • Call CPT_ClrIntStatus() to clear the current CPT interrupt status
  • Call CPT_GetCurrentState() to get the current state values
  • Call CPT_GetIntStatus() to confirm confirm the sample window has not expired (eCPT_IntStatus_Inactive returned). If the call to CPT_GetIntStatus() returns eCPT_IntStatus_Active (indicates the sample window expired) either the sample window is set to small or your interrupt was delayed suffiecently to lose the current state context, in which case a retry of CPT_GetCurrentState() would be appropriate.

Note: You can't check the sample counter register because this value is really just the counter's reload value.

eCPT_Error CPT_CfgInt ( CPT_Handle_Pntr const  pCPT_Handle,
const eCPT_IntMask  CPT_IntMask 
)
CPT_CfgInt

Configure the CP Tracer for interrupt generation.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]CPT_IntMaskeCPT_IntMask provides interrupt disable and enable selection.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

The default CPT interrupt state, set by a successful call to CPT_OpenModule, is disabled.

This function only provides access to the local CP tracer state. This function assumes the client has integrated appropriate CP Tracer interrupt setup and service handling into their application.

This function may be used at any time.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_GetIntStatus ( CPT_Handle_Pntr const  pCPT_Handle,
eCPT_IntStatus *const  pCPT_IntStatus 
)
CPT_GetIntStatus

Get the current interrupt status (active or inactive) of the specific CP Tracer.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[out]pCPT_IntStatusAn eCPT_IntStatus value is returned reflecting the state of the CP Tracer interrupt.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

This function only provides access to the local CP tracer state. This function assumes the client has integrated appropriate CP Tracer interrupt setup and service handling into their application.

This function may be used at any time.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_ClrIntStatus ( CPT_Handle_Pntr const  pCPT_Handle)
CPT_ClrIntStatus

Clear the current interrupt status of the specific CP Tracer.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

This function only provides access to the local CP tracer state. This function assumes the client has integrated appropriate CP Tracer interrupt setup and service handling into their application.

This function may be used at any time.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

eCPT_Error CPT_LogMsg ( CPT_Handle_Pntr const  pCPT_Handle,
const char *  FmtString,
uint32_t *const  pValue 
)
CPT_LogMsg

Issue a user provided CP Tracer specific STM message.

Parameters
[in]pCPT_HandlePointer to a CPT_Handle provided by CPT_OpenModule().
[in]FmtStringFormat string (like printf format string) limited to a single int or unsigned int conversion character.
[in]pValuePointer to formatted value. NULL if not used in format string.
Returns
eCPT_Error See details for conditions that cause the following errors:
Details:

The following information will be provided in the CPT client STM message:

  • Module - Pointer to the module name "CPTLib" .
  • Data Domain - Pointer to the domain name, in this case it's the CPT Tracer's name string.
  • Data Class - Pointer to the class name, in this case it's "CPT User Message".
  • Data Type - Pointer to the data type, in this case it's "Message".
  • Data Message - Pointer to the FmtString.
  • value - If pValue is not NULL, value is provided.

If CPT_OpenModule() is opened with a NULL STMHandle, this function exits and returns eCPT_Error_NULL_STMHandle.

Note: _STMLogging must be defined for this function to be included by the complier.

This function may be used at any time.

If this function is called with a NULL pCPT_Handle pointer or the contents of the handle are not valid this function will return eCPT_Error_InvalidHandlePointer immediately and take no other action.

If a STM Library error is returned this function will exit with CPT_Error_STM + STM_Error.