Common Platform (CP) Tracer Library API Reference Guide (C6674 Version)
|
#include <stdlib.h>
#include <stdint.h>
#include <stdbool.h>
#include "../../STMLib/include/StmLibrary.h"
#include "CPTLib_C6674.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_t * | CPT_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 |
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) |
CPT Library Function Prototypes
#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 struct _CPT_Handle CPT_Handle_t |
typedef CPT_Handle_t* CPT_Handle_Pntr |
typedef void(* CPT_CallBack)(const char *funcName, eCPT_Error) |
[in] | funcName | Constant char pointer to the function name. Normally provided by the compiler using the FUNCTION macro. |
[in] | eCPT_Error | error returned by calling routine |
typedef struct _CPT_Qualifiers CPT_Qualifiers |
typedef struct _CPT_TrigQualifiers CPT_TrigQualifiers |
typedef struct _CPT_CfgOptions CPT_CfgOptions |
enum eCPT_Error |
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 |
enum eCPT_MsgSelects |
enum eCPT_CntSelects |
enum eCPT_TrigOut |
enum eCPT_ThroughputCntID |
enum eCPT_MasterState |
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 |
enum eCPT_SrcQual |
enum eCPT_RWQual |
enum eCPT_TrigIn |
enum eCPT_FilterMode |
enum eCPT_MsgPri |
enum eCPT_AddrMode |
enum eCPT_IntStatus |
enum eCPT_IntMask |
enum eCPT_WaitSelect |
enum eCPT_UseCase |
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.
eCPT_Error CPT_OpenModule | ( | CPT_Handle_Pntr *const | pCPT_Handle, |
const eCPT_ModID | CPT_ModId, | ||
CPT_CfgOptions const *const | pCPT_CfgOptions | ||
) |
Open a CPT Library API for a specific CP Tracer module.
[out] | pCPT_Handle | A 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_ModId | eCPT_ModID is the enumerated identifier for the physical CP tracer module that is opened. |
[in] | pCPT_CfgOptions | A pointer to the CPT_CfgOptions structure. If pCPT_CfgOptions is NULL all parameters are set to their default values. |
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:
If the function exits with eCPT_Success the device's CPT module default values are set to:
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) |
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.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
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 | ||
) |
Get CPT Library version and the Physical Module's version.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[out] | pLibMajorVersion | CPT Library Major Version (API modifications not backward compatible) |
[out] | pLibMinorVersion | CPT Library Minor Version (Backward compatible modifications and bug fixes) |
[out] | pSWFuncID | The device’s CMI Module Functional ID the library is compatible with |
[out] | pHwFuncID | The actual device's CMI Module Functional ID |
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 | ||
) |
Enable the CP Tracer module's STM message export and counters.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | CPT_MsgEnables | eCPT_MsgSelects provides selection for statistic and event STM messages enables |
[in] | CPT_CntEnables | eCPT_CntSelects provide selection of counters to enable. |
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:
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 | ||
) |
Disable the CP Tracer module's STM message export and counters.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | CPT_WaitSelect | eCPT_WaitSelect provides selection to disable or enable waiting for the next sample window to expire prior to disabling the CP Tracer. |
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 | ||
) |
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.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | CPT_MasterID | eCPT_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_ThroughputCnt | eCPT_ThroughputCntID provides Throughput Counter selection the CPT_MasterID is associated with. |
[in] | CPT_MasterState | eCPT_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). |
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 | ||
) |
Select qualifiers for Throughput Counters(0 and 1), New Request Events and Trigger out (on EMU0/1 pins).
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | pCPT_TPCnt0Qual | Pointer 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_TPCnt1Qual | Pointer 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_TPEventQual | Pointer 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_TrigQual | Pointer 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. |
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 | ||
) |
Modify address filters for Throughput Counters(0 and 1), New Request Events and Trigger out (on EMU0/1 pins).
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | AddrFilterMSBs | Address 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] | StartAddrFilterLSBs | Start address filter LSBs (address bits 31:0). |
[in] | EndAddrFilterLSBs | End address filter LSBs (address bits 31:0). |
[in] | CPT_FilterMode | eCPT_FilterMode provides selection for inclusive/exclusive address filter modes. |
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 | ||
) |
Configure Access Status pacing.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | PacingCntValue | 24-bit value to set pacing counter. |
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 | ||
) |
Configure STM message priorities.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | CPT_StatisticMsgsPri | eCPT_MsgPri provides priority level for Statistic messages (from counters). |
[in] | CPT_NewRequestEventMsgPri | eCPT_MsgPri provides priority level for Event B (New Request Event) messages. |
[in] | CPT_LastWriteEventMsgPri | eCPT_MsgPri provides priority level for Event C (Last Write Event) messages. |
[in] | CPT_LastReadEventMsgPri | eCPT_MsgPri provides priority level for Event E (Last Read Event) messages. |
[in] | CPT_AccessStatusMsgPri | eCPT_MsgPri provides priority level for Access Status messages. |
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 | ||
) |
Get Address mode for the specific CP Tracer.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[out] | pAddrModeRange | eCPT_AddrMode provides the available address mode returned for the specific CP trace module. |
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 | ||
) |
Get the current state of the specific CP Tracer's counters and Access Status.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[out] | pCPT_ThroughPutCnt0 | Return location for the current Throughput 0 Counter value. |
[out] | pCPT_ThroughPutCnt1 | Return location for the current Throughput 1 Counter value. |
[out] | pCPT_WaitCnt | Return location for the current Wait Count (in CP Tracer clocks) value |
[out] | pCPT_GrantCnt | Return location for the current Grant Counter value. |
[out] | pAccessStatus | Return location for the current Access Status value. |
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:
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 | ||
) |
Configure the CP Tracer for interrupt generation.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | CPT_IntMask | eCPT_IntMask provides interrupt disable and enable selection. |
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 | ||
) |
Get the current interrupt status (active or inactive) of the specific CP Tracer.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[out] | pCPT_IntStatus | An eCPT_IntStatus value is returned reflecting the state of the CP Tracer interrupt. |
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) |
Clear the current interrupt status of the specific CP Tracer.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
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 | ||
) |
Issue a user provided CP Tracer specific STM message.
[in] | pCPT_Handle | Pointer to a CPT_Handle provided by CPT_OpenModule(). |
[in] | FmtString | Format string (like printf format string) limited to a single int or unsigned int conversion character. |
[in] | pValue | Pointer to formatted value. NULL if not used in format string. |
The following information will be provided in the CPT client STM message:
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.