CMI Instrumentation Library API Reference Guide
|
#include <stdlib.h>
#include <stdint.h>
#include "../../PMICMILib/src/PCMI_Omap4430.h"
#include "../../STMLib/include/StmLibrary.h"
#include "../../STMLib/src/StmSupport.h"
#include "../../PMICMILib/src/PCMI_Common.h"
Go to the source code of this file.
Data Structures | |
struct | _CMI_CfgParams |
Typedefs | |
typedef struct CMI_Handle_t | CMI_Handle |
typedef CMI_Handle * | CMI_Handle_Pntr |
typedef struct _CMI_CfgParams | CMI_CfgParams |
typedef ePCMI_Error | eCMI_Error |
CMI Library Function Prototypes
typedef struct CMI_Handle_t CMI_Handle |
CMI_Handle CMI Handle object. Note that CMI_Handle is an incomplete struct hiding the actual PMI_Handle_t implementation from clients.
typedef CMI_Handle* CMI_Handle_Pntr |
typedef struct _CMI_CfgParams CMI_CfgParams |
typedef ePCMI_Error eCMI_Error |
enum eCMI_ModEnableType |
enum eCMI_EventEnables |
enum eCMI_ActivityEnables |
enum eCMI_ModID |
eCMI_Error CMI_OpenModule | ( | CMI_Handle_Pntr * | pCMI_Handle, |
eCMI_ModID | CMI_ModId, | ||
CMI_CfgParams * | pCMI_CfgParams | ||
) |
Open the CMI Library API, aquire ownership of the device's CMI module and allocate CMI Handle storage.
[out] | pCMI_Handle | A pointer to a NULL CMI_Handle_Pntr. If CMI_OpenModule exits with the return value of ePCMI_Success, the location pointed to by ::pCMI_Handle is set to a valid CMI_Handle pointer. |
[in] | CMI_ModId | eCMI_ModID enumerated module intentifier. |
[in] | pCMI_CfgParams | Pointer to a CMI_CfgParams structure. |
This function must be called and return ePCMI_Success prior to any other CMI Library function that requires a CMI_Handle_Pntr paramter. Initially this function will check that the CMI module is functional. If the module not in the functional state, this function will attempt to change the modules state to functional. If the module's state can not be changed to functional this function will exit and return ePCMI_Error_ModuleClkStateModifyFailed. This function will then confirm the device's CMI module is compatible with this version of the library. If not compatible the function will exit and return ePCMI_Error_Not_Compatible. The function will attempt to claim ownership of the device's CMI module. If ownership is not achieved this function exit with the return value set to ePCMI_Error_Ownership_Not_Granted. If ownership successful a soft reset will be applied to the device's CMI module. If ResetDone is not detected, ownership will be released and this function exited with ePCMI_Error_ResetDone_Not_Detected. If function exits with ePCMI_Success storage for CMI_Handle is allocated through a call to the client provided external function STM_memAlloc(). STM_memMap(), also a client provided function, is called by CMI_OpenModule to map the physical CMI_BaseAddress provided to a virtual address space.
Prototype for client provided functions:
void * STM_memAlloc(size_t sizeInBytes) return NULL if memory not allocated
void * STM_memMap(unsigned int phyAddr, unsigned int mapSizeInBytes) return phyAddr if virtual mapping not required.
If the function exits with ePCMI_Success the device's CMI module default values are set to:
If pCMI_CfgParams->pSTMHandle is not NULL the PMI Library will:
eCMI_Error CMI_CloseModule | ( | CMI_Handle_Pntr | pCMI_Handle | ) |
Close the CMI Library API. Disable the device's CMI module and release ownership. Free the CMI_Handle storage.
[in] | pCMI_Handle | CMI Handle Pointer |
Confirm CMI module ownership and exit with return value set to ePCMI_Error_Ownership_Not_Confirmed if application does not own the module (debugger can override ownership). If ownership confirmed attempt to release the module. If ownership is not released exit and return ePCMI_Error_Ownership_Not_Released. The CMI_Handle is destroyed through a call to the client provided external function STM_memFree. The CMI_BaseAddress is unmapped through a call to the client provided external function STM_memUnMap. In the event a CMI error is detected, the CMI_Handle is still destroyed. No CMI Library functions can be called with CMI_Handle after CMI_CloseModule is called.
Prototype for client provided functions:
void STM_memFree(void *p)
void STM_memUnMap(void * vAddr, unsigned int mapSizeInBytes) if vitual address mapping not required simply return.
eCMI_Error CMI_GetVersion | ( | CMI_Handle_Pntr | pCMI_Handle, |
uint32_t * | pLibMajorVersion, | ||
uint32_t * | pLibMinorVersion, | ||
uint32_t * | pSWFuncID, | ||
uint32_t * | pHwFuncID | ||
) |
Get CMI Library version, software functional ID and hardware functional ID.
[in] | pCMI_Handle | CMI Handle Pointer |
[out] | pLibMajorVersion | CMI Library Major Version (API modifications not backward compatible) |
[out] | pLibMinorVersion | CMI Library Minor Version (Backward compatible modifications) |
[out] | pSWFuncID | The deivce'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 library's build. These values can be compared with the following macro values in PMI_CMI_Common.h to confirm that the version of the library matches that of the header file.
PMICMILIB_MAJOR_VERSION
PMICMILIB_MINOR_VERSION
Major version releases of the same level will be backward compatible with lower minor release versions. Any change in the API will be reflected in a change to the major release version. The minor release version is typically for bug fixes.
The pCMISWFuncID value must match the pCMIHwFuncID value for a call to CMI_OpenModule not to return ePCMI_Error_Not_Compatible.
eCMI_Error CMI_ModuleEnable | ( | CMI_Handle_Pntr | pCMI_Handle, |
eCMI_ModEnableType | modEnableType | ||
) |
Enable the CMI module's activity collection and STM message export.
[in] | pCMI_Handle | CMI Handle Pointer |
[in] | modEnableType | eCMI_ModEnableType enumerated value used to select the monitor type, activity or events. |
Confirm CMI module ownership and exit with return value set to ePCMI_Error_Ownership_Not_Confirmed if application does not own the module (debugger can override our ownership). If the module is already enabled, this function will exit with either eCMI_Error_InUseForEventCapture or eCMI_Error_InUseForModuleActivity. The device's CMI module is then enable and the enable state confirmed. If the enable state cannot be confirmed ePCMI_Error_ModuleEnableFailed is returned. If enabled successfully the module is then set for either activity or event monitoring.
If CMI_OpenModule was called with a non-NULL STMHandle, the PMI meta data STM messages are sent and a PMI Library logging message indicating the PMI HW module has started monitoring clock activity.
The module is then set for either activity or event monitoring to start device's CMI STM message generation.
eCMI_Error CMI_ModuleDisable | ( | CMI_Handle_Pntr | pCMI_Handle, |
int32_t | retain | ||
) |
Disable the CMI module's activity or event collection and the device's CMI STM message export.
[in] | pCMI_Handle | CMI Handle Pointer |
[in] | retain | if true (non-zero) do not reset the module, if false perform soft reset of the CMI module |
Confirm STM module ownership and exit with return value set to ePCMI_Error_Ownership_Not_Confirmed if application does not own the module (debugger can override our ownership).
If not already Disabled, Disable the CMI module for both activity and event monitoring. If CMI module ownership state is Enabled, ownership state is changed to Claimed. If retain is true, the current programming is retained, else a soft reset asserted and reset done confirmed. If reset done not confirmed exit and return ePCMI_Error_ResetDone_Not_Detected.
If CMI_OpenModule was called with a non-NULL STMHandle, the PMI meta data STM messages are sent and a PMI Library logging message indicating the PMI HW module has ended monitoring clock activity.
Note: The meta data is provided, in addition to being provided by CMI_ModuleEnable(), incase the buffer wrapped thus allowing the sample window size to be applied to the previous data by analysis tools (such as the Trace Analyzer).
Note: CMI_ModuleDisable may be called with retain set true, and then called a second time with retain false prior to reprogramming the module.
eCMI_Error CMI_ConfigModule | ( | CMI_Handle_Pntr | pCMI_Handle, |
ePCMI_Triggers | triggerEnables, | ||
eCMI_EventEnables | eventEnables, | ||
eCMI_ActivityEnables | activityEnables | ||
) |
Configure the CMI module's triggers, select activity monitoring enables, or select event snapshot capture enables . If the module has been previously enabled for activity collection, this function must be called before any CMI module configuration parameters (triggers, event enables, activity enables, or sample window) may be modified.
[in] | pCMI_Handle | CMI Handle Pointer |
[in] | triggerEnables | ::ePCMI_Triggers enumerated optional module start and stop triggers (default set by CMI_OpenModule(), no triggers enabled) |
[in] | eventEnables | eCMI_EventEnables enumerated event snapshot enables (default set by CMI_OpenModule(), all events enabled) |
[in] | activityEnables | eCMI_ActivityEnables enumerated activity monitor enables (default set by CMI_OpenModule(), all activity enabled) |
Note: Since eventEnables and activityEnables share control register bits (they are mode dependent), either eventEnables must be set to eCMI_ENABLE_EVENT_NONE or activityEnables must be set to eCMI_ENABLE_ACTIVITY_NONE. Trying to set both eventEnables and activityEnables at the same time will result in a ePCMI_Error_Invalid_Parameter. To clear all event and activity configuration bits the eventEnables parameter must be set to eCMI_ENABLE_EVENT_NONE and activityEnables must be set to eCMI_ENABLE_ACTIVITY_NONE.
Confirm CMI module ownership and return ePCMI_Error_Ownership_Not_Confirmed if application does not own the module (debugger can override our ownership). If this function is attempted while module activity or event capture is enabled this function will exit and return ePCMI_Error_Module_Enabled.
The start and stop trigger enable values can be ored together to enable both start and stop triggers at the same time. Triggers not explicitly set are disabled. Any event enable can be ored with any other event enable to set multiple event classes. Any events not explicitly enabled will be disabled. Any activity enables can be ored with any other activity enable to set multiple activity classes. Any activity classes not explicitly enabled will be disabled.
eCMI_Error CMI_GetSampleWindow | ( | CMI_Handle_Pntr | pCMI_Handle, |
uint32_t * | pFuncClockDivider, | ||
uint32_t * | pSampleWindowSize | ||
) |
Retrieve the actual CMI module's sample window time frame in sysclocks.
[in] | pCMI_Handle | CMI Handle Pointer |
[out] | pFuncClockDivider | Functional clock divider parameter (1-16 are valid values). |
[out] | pSampleWindowSize | Sample window size (1-256 are valid values). |
This function provides the actual size of the sample window in functional clocks.
const char* CMI_GetErrorMsg | ( | eCMI_Error | errorCode | ) |
Retrieve a pointer to errorCode's text string.
[in] | errorCode | :eCMI_Error enumerated error code. |
Note: It's expected this function will only be used when a client implements their own error handling processes. Error message strings are centralized in the .dataImageErrStrings:PCMILib data section so the user can choose to link this section to real memory (to access the error strings from their application) or link them to non-existent memory space.
eCMI_Error CMI_LogMsg | ( | CMI_Handle_Pntr | pCMI_Handle, |
const char * | FmtString, | ||
int32_t * | pValue | ||
) |
Issue a client provided Clock Management relevant STM message.
[in] | pCMI_Handle | CMI Handle Pointer |
[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 CMI STM message:
If CMI_OpenModule() is opened with a NULL STMHandle, this function exits and returns ePCMI_Error_NULL_STMHandle.
eCMI_Error CMI_MarkClockDomainStateChange | ( | CMI_Handle_Pntr | pCMI_Handle, |
eCMI_ClockDomainStateChange | clkDomain, | ||
eCMI_clkState | clkState | ||
) |
Issue a standard Clock Doamin State Change STM message. This function provides the client a mechansim to mark when a clock domain state change has occured in the STM data output, thus allowing latency measurements between when the application attempts to change the clock setting, and when the device responds to the request.
[in] | pCMI_Handle | CMI Handle Pointer |
[in] | clkDomain | eCMI_ClockDomainStateChange specifies the enumerated clock domain that changed. If you attempt to select a clock domain that is not associated with the CM module the library is opened for, a Mark STM Message is not generated and the function exits with ePCMI_Error_Invalid_Parameter error. |
[in] | clkState | eCMI_clkState specifies the enumerated clock domain state |
The following information will be provided in the STM message:
If CMI_OpenModule() is opened with a NULL STMHandle, this function exits and returns ePCMI_Error_NULL_STMHandle.
All text for these mesages are provided in the .dataImageMsgStrings:PCMILib section and at link time may be placed in non-existant memory.
eCMI_Error CMI_MarkClockDividerRatioChange | ( | CMI_Handle_Pntr | pCMI_Handle, |
eCMI_ClockDividerRatioChange | divDomain, | ||
eCMI_divState | divState | ||
) |
Issue a standard Clock Divider Ratio Change STM message. This function provides the client a mechansim to mark when a clock divider ratio change has occured in the STM data output, thus allowing latency measurements between when the application attempts to change the divider setting, and when the device responds to the request.
[in] | pCMI_Handle | CMI Handle Pointer |
[in] | divDomain | eCMI_ClockDividerRatioChange specifies the emunerated clock divider that changed. If you attempt to select a clock divider that is not associated with the CM module the library is opened for, a Mark STM Message is not generated and the function exits with ePCMI_Error_Invalid_Parameter error. |
[in] | divState | eCMI_divState specifies the emunerated clock divider value (eCMI_DivBy1, eCMI_DivBy2, eCMI_DivBy4) |
The following information will be provided in the STM message:
If CMI_OpenModule() is opened with a NULL STMHandle, this function exits and returns ePCMI_Error_NULL_STMHandle.
All text for these mesages are provided in the .dataImageMsgStrings:PCMILib section and at link time may be placed in non-existant memory.
eCMI_Error CMI_MarkClockSourceSelectionChange | ( | CMI_Handle_Pntr | pCMI_Handle, |
eCMI_ClockSource | clkSource | ||
) |
Issue a standard Clock Source Selection Change STM message. This function provides the client a mechansim to mark when a clock source selection change has occured in the STM data output, thus allowing latency measurements between when the application attempts to change the clock source, and when the device responds to the request.
[in] | pCMI_Handle | CMI Handle Pointer |
[in] | clkSource | eCMI_ClockSource specifies the emunerated clock source that changed. If you attempt to select a clock source that is not associated with the CM module the library is opened for, a Mark STM Message is not generated and the function exits with a ePCMI_Error_Invalid_Parameter error. |
The following information will be provided in the STM message:
If CMI_OpenModule() is opened with a NULL STMHandle, this function exits and returns ePCMI_Error_NULL_STMHandle.
All text for these mesages are provided in the .dataImageMsgStrings:PCMILib section and at link time may be placed in non-existant memory.
eCMI_Error CMI_MarkDPLLSettingChange | ( | CMI_Handle_Pntr | pCMI_Handle, |
eCMI_DPLLSrc | dlppSource | ||
) |
Issue a standard DPLL Setting Change STM message. This function provides the client a mechansim to mark when a DPLL Setting Change has occured in the STM data output, thus allowing latency measurements between when the application attempts to change a DLPP setting, and when the device responds to the request.
[in] | pCMI_Handle | CMI Handle Pointer |
[in] | dlppSource | eCMI_DPLLSrc specifies the emunerated DLPP source whose settings were changed. If you attempt to select a DPLL Source that is not associated with the CM module the library is opened for, a Mark STM Message is not generated and the function exits with a ePCMI_Error_Invalid_Parameter error. |
The following information will be provided in the STM message:
If CMI_OpenModule() is opened with a NULL STMHandle, this function exits and returns ePCMI_Error_NULL_STMHandle.
All text for these mesages are provided in the .dataImageMsgStrings:PCMILib section and at link time may be placed in non-existant memory.