PMI 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 | _PMI_CfgParams |
Typedefs | |
typedef struct PMI_Handle_t | PMI_Handle |
typedef PMI_Handle * | PMI_Handle_Pntr |
typedef struct _PMI_CfgParams | PMI_CfgParams |
typedef ePCMI_Error | ePMI_Error |
Enumerations | |
enum | ePMI_EventEnables { ePMI_ENABLE_NONE =0, ePMI_ENABLE_LOGIC_VOLTAGE_DOMAIN_OPP_CHANGE = 1, ePMI_ENABLE_MEMORY_VOLTAGE_DOMAIN_OPP_CHANGE = 2, ePMI_ENABLE_LOGIC_POWER_DOMAIN_STATE_CHANGE = 4, ePMI_ENABLE_MEMORY_POWER_DOMAIN_STATE_CHANGE = 8, ePMI_ENABLES_NOT_MODIFIED = -1 } |
enum | ePMI_ModID { ePMI_PM, ePMI_PM_ModuleCnt } |
PMI Library Function Prototypes
typedef struct PMI_Handle_t PMI_Handle |
PMI_Handle PMI Handle object. Note that PMI_Handle is an incomplete struct hiding the actual PMI_Handle_t implementation from clients.
typedef PMI_Handle* PMI_Handle_Pntr |
PMI_Handle_Pntr Pointer to a PMI Handle object
typedef struct _PMI_CfgParams PMI_CfgParams |
typedef ePCMI_Error ePMI_Error |
enum ePMI_EventEnables |
enum ePMI_ModID |
ePMI_Error PMI_OpenModule | ( | PMI_Handle_Pntr * | pPMI_Handle, |
ePMI_ModID | PMI_ModId, | ||
PMI_CfgParams * | pPMI_CfgParams | ||
) |
Open the PMI Library API. Aquire ownership of the device's PMI module and allocate PMI Handle storage.
[out] | pPMI_Handle | Pointer to a NULL PMI_Handle_Pntr. If PMI_OpenModule exits with the return value of ePCMI_Success, the location pointed to by ::pPMI_Handle is set to a valid PMI_Handle pointer. |
[in] | PMI_ModId | ePMI_ModID enumerated module intentifier. |
[in] | pPMI_CfgParams | Pointer to a PMI_CfgParams structure. |
This function must be called and return ePCMI_Success prior to any other PMI Library function that requires a PMI_Handle_Pntr paramter. Initially this function will check that the PMI module is functional. If the module is not in the functional state, this function will attempt to change the module's 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 PMI 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 PMI module. If ownership is not achieved this function will exit with the return value set to ::ePMI_Error_Ownership_Not_Granted. If ownership successful a soft reset will be applied to the PMI 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 PMI_Handle is allocated through a call to the client provided external function STM_memAlloc(). STM_memMap(), also a client provided function, is called by PMI_OpenModule to map the physical PMI_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 PMI module default values are set to:
If pPMI_CfgParams->pSTMHandle is not NULL the PMI Library will:
ePMI_Error PMI_CloseModule | ( | PMI_Handle_Pntr | pPMI_Handle | ) |
Close the PMI Library. Disable the device's PMI module and release ownership. Free the PMI_Handle storage.
[in] | pPMI_Handle | PMI Handle Pointer |
Confirm PMI 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 PMI_Handle is destroyed through a call to the client provided external function STM_memFree. The PMI_BaseAddress is unmapped through a call to the client provided external function STM_memUnMap. In the event a PMI module error is detected, the PMI_Handle is still destroyed. No PMI Library functions can be called with PMI_Handle after PMI_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.
ePMI_Error PMI_GetVersion | ( | PMI_Handle_Pntr | pPMI_Handle, |
uint32_t * | pLibMajorVersion, | ||
uint32_t * | pLibMinorVersion, | ||
uint32_t * | pSWFuncID, | ||
uint32_t * | pHwFuncID | ||
) |
Get PMI Library version, software functional ID and hardware functional ID.
[in] | pPMI_Handle | PMI Handle Pointer |
[out] | pLibMajorVersion | PMI Library Major Version (API modifications not backward compatible) |
[out] | pLibMinorVersion | PMI Library Minor Version (Backward compatible modifications) |
[out] | pSWFuncID | The deivce's PMI Module Functional ID the library is compatible with |
[out] | pHwFuncID | The actual device's PMI 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 pPMISWFuncID value must match the pPMIHwFuncID value for a call to PMI_OpenModule not to return ePCMI_Error_Not_Compatible.
ePMI_Error PMI_ModuleActivityEnable | ( | PMI_Handle_Pntr | pPMI_Handle | ) |
Enable the PMI module's activity collection and STM message export.
[in] | pPMI_Handle | PMI Handle Pointer |
Confirm PMI 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). The PMI module is then enabled and the enable state confirmed. If the enable state cannot be confirmed ePCMI_Error_ModuleEnableFailed is returned.
If PMI_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 power activity.
The module is then enabled to start the device's PMI STM message generation.
ePMI_Error PMI_ModuleActivityDisable | ( | PMI_Handle_Pntr | pPMI_Handle, |
int32_t | retain | ||
) |
Disable the PMI module's activity collection and the device's PMI STM message export.
[in] | pPMI_Handle | PMI Handle Pointer |
[in] | retain | if true (non-zero) do not reset the module, if false perform soft reset of the PMI module |
Confirm PMI 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 PMI module for activity collection. If PMI module ownership state Enabled, ownership state changed to Claimed. If retain is true, the current programming is retained, else a Softreset asserted and reset done confirmed. If reset done not confirmed exit and return ePCMI_Error_ResetDone_Not_Detected.
If PMI_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 power activity.
Note: The meta data is provided, in addition to being provided by PMI_ModuleActivityEnable(), 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: PMI_ModuleActivityDisable may be called with retain set true, and then called a second time with retain false prior to reprogramming the module.
ePMI_Error PMI_ConfigModule | ( | PMI_Handle_Pntr | pPMI_Handle, |
ePCMI_Triggers | triggerEnables, | ||
ePMI_EventEnables | eventEnables | ||
) |
Configure the PMI module's triggers or select events for activity collection. If the module has been previously enabled for activity collection, PMI_ModuleActivityDisable() must be called prior to calling this function. The PMI module triggers and selected events are set to default values by PMI_OpenModule().
[in] | pPMI_Handle | PMI Handle Pointer |
[in] | triggerEnables | ::ePCMI_Triggers enumerated optional module start and stop triggers (default after calling PMI_OpenModule(), no triggers enabled) |
[in] | eventEnables | ePMI_EventEnables enumerated event enables (default after calling PMI_OpenModule(), all events enabled) |
Confirm PMI 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 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 values can be ored with any other event enable to set multiple event classes. Any events not explicitly enabled will be disabled.
Note: There is no requirement that PMI_ConfigModule be called prior to PM_ModuleActivityEnable().
ePMI_Error PMI_GetSampleWindow | ( | PMI_Handle_Pntr | pPMI_Handle, |
uint32_t * | pFuncClockDivider, | ||
uint32_t * | pSampleWindowSize | ||
) |
Retrieve the actual PMI module's sample window time frame in sysclocks.
[in] | pPMI_Handle | PMI 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 components to compute the actual size of the sample window in functional clocks ( FuncClockDivider * SampleWindowSize).
const char* PMI_GetErrorMsg | ( | ePMI_Error | errorCode | ) |
Retrieve a pointer to errorCode's text string.
[in] | errorCode | ePMI_Error enumerated error code. |
It's expected this function will only be used when a client implements their own error handling process. 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 in non-existent memory space if this function is not used.
ePMI_Error PMI_LogMsg | ( | PMI_Handle_Pntr | pPMI_Handle, |
const char * | FmtString, | ||
int32_t * | pValue | ||
) |
Issue a client provided Power Management relevant STM message.
[in] | pPMI_Handle | PMI 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 PMI STM message:
If PMI_OpenModule() is opened with a NULL STMHandle, this function exits and returns ePCMI_Error_NULL_STMHandle.
ePMI_Error PMI_MarkLogicVoltageOPPChange | ( | PMI_Handle_Pntr | pPMI_Handle, |
ePMI_LVD_OPP | pwrDomain, | ||
uint8_t | pwrValue | ||
) |
Issue a standard Logic Voltage OPP Change STM message. This function provides the client a mechansim to mark when a logic voltage change has occured in the STM data output, thus allowing latency measurements between when the application attempts to change the voltage setting, and when the device responds to the request.
[in] | pPMI_Handle | PMI Handle Pointer |
[in] | pwrDomain | ePMI_LVD_OPP specifies the logic vlotage domain that changed. |
[in] | pwrValue | Is the 8-bit SMPS Output Voltage Selection Code (Standard Mode) used for voltage level selection. Valid values are 0 to 0x3E. |
The following information will be provided in the PMI STM message:
If PMI_OpenModule() is opened with a NULL STMHandle, this function exits and returns ePCMI_Error_NULL_STMHandle. If pwrValue value is not in the range of 0 to 3E the function exits with a ePCMI_Error_Invalid_Parameter error.
All text for these mesages are provided in the .dataImageMsgStrings:PMILib section and at link time may be placed in non-existant memory.
ePMI_Error PMI_MarkMemoryVoltageOPPChange | ( | PMI_Handle_Pntr | pPMI_Handle, |
ePMI_MVD_OPP | pwrDomain, | ||
ePMI_MVD_PwrState | pwrState | ||
) |
Issue a standard Memory Voltage OPP Change STM message. This function provides the client a mechansim to mark when a memory voltage change has occured in the STM data output, thus allowing latency measurements between when the application attempts to change the voltage setting, and when the device responds to the request.
[in] | pPMI_Handle | PMI Handle Pointer |
[in] | pwrDomain | ePMI_MVD_OPP specifies the memory voltage domain that changed. |
[in] | pwrState | ePMI_MVD_PwrState specifies the memory voltage domain state. |
The following information will be provided in the STM message:
If PMI_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:PMILib section and at link time may be placed in non-existant memory.
ePMI_Error PMI_MarkLogicPowerStateChange | ( | PMI_Handle_Pntr | pPMI_Handle, |
ePMI_LPD_StateChange | pwrDomain, | ||
ePMI_LPD_PwrState | pwrState | ||
) |
Issue a standard Logic Power State Change STM message. This function provides the client a mechansim to mark when a logic power state change has occured in the STM data output, thus allowing latency measurements between when the application attempts to change the power setting, and when the device responds to the request.
[in] | pPMI_Handle | PMI Handle Pointer |
[in] | pwrDomain | ePMI_LPD_StateChange specifies the logic power domain that changed. |
[in] | pwrState | ePMI_LPD_PwrState specifies the logic power domain state. |
The following information will be provided in the STM message:
If PMI_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:PMILib section and at link time may be placed in non-existant memory.
ePMI_Error PMI_MarkMemoryPowerStateChange | ( | PMI_Handle_Pntr | pPMI_Handle, |
ePMI_MPD_StateChange | pwrDomain, | ||
ePMI_MPD_PwrState | pwrState | ||
) |
Issue a standard Memory Power State Change STM message. This function provides the client a mechansim to mark when a memory power state change has occured in the STM data output, thus allowing latency measurements between when the application attempts to change the power setting, and when the device responds to the request.
[in] | pPMI_Handle | PMI Handle Pointer |
[in] | pwrDomain | ePMI_MPD_StateChange specifies the memory power domain that changed. |
[in] | pwrState | ePMI_MPD_PwrState specifies the memory power domain state. |
The following information will be provided in the STM message:
If PMI_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:PMILib section and at link time may be placed in non-existant memory.