PMI Instrumentation Library API Reference Guide
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator
Data Structures | Typedefs | Enumerations | Functions
PMILib.h File Reference
#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_HandlePMI_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 }
 

Functions

ePMI_Error PMI_OpenModule (PMI_Handle_Pntr *pPMI_Handle, ePMI_ModID PMI_ModId, PMI_CfgParams *pPMI_CfgParams)
 
ePMI_Error PMI_CloseModule (PMI_Handle_Pntr pPMI_Handle)
 
ePMI_Error PMI_GetVersion (PMI_Handle_Pntr pPMI_Handle, uint32_t *pLibMajorVersion, uint32_t *pLibMinorVersion, uint32_t *pSWFuncID, uint32_t *pHwFuncID)
 
ePMI_Error PMI_ModuleActivityEnable (PMI_Handle_Pntr pPMI_Handle)
 
ePMI_Error PMI_ModuleActivityDisable (PMI_Handle_Pntr pPMI_Handle, int32_t retain)
 
ePMI_Error PMI_ConfigModule (PMI_Handle_Pntr pPMI_Handle, ePCMI_Triggers triggerEnables, ePMI_EventEnables eventEnables)
 
ePMI_Error PMI_GetSampleWindow (PMI_Handle_Pntr pPMI_Handle, uint32_t *pFuncClockDivider, uint32_t *pSampleWindowSize)
 
const char * PMI_GetErrorMsg (ePMI_Error errorCode)
 
ePMI_Error PMI_LogMsg (PMI_Handle_Pntr pPMI_Handle, const char *FmtString, int32_t *pValue)
 
ePMI_Error PMI_MarkLogicVoltageOPPChange (PMI_Handle_Pntr pPMI_Handle, ePMI_LVD_OPP pwrDomain, uint8_t pwrValue)
 
ePMI_Error PMI_MarkMemoryVoltageOPPChange (PMI_Handle_Pntr pPMI_Handle, ePMI_MVD_OPP pwrDomain, ePMI_MVD_PwrState pwrState)
 
ePMI_Error PMI_MarkLogicPowerStateChange (PMI_Handle_Pntr pPMI_Handle, ePMI_LPD_StateChange pwrDomain, ePMI_LPD_PwrState pwrState)
 
ePMI_Error PMI_MarkMemoryPowerStateChange (PMI_Handle_Pntr pPMI_Handle, ePMI_MPD_StateChange pwrDomain, ePMI_MPD_PwrState pwrState)
 

Detailed Description

PMI Library Function Prototypes

Typedef Documentation

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.

PMI_Handle_Pntr Pointer to a PMI Handle object

typedef struct _PMI_CfgParams PMI_CfgParams
PMI_CfgParams
PMI Configuration Parameters
ePMI_Error
PMI Error codes PMI specific version of ePCMI_Error type

Enumeration Type Documentation

ePMI_EventEnables
PMI Event Enable selections
Enumerator
ePMI_ENABLE_NONE 

Clear all event enable bits

ePMI_ENABLE_LOGIC_VOLTAGE_DOMAIN_OPP_CHANGE 

Set Logic Voltage Domain OPP change bit

ePMI_ENABLE_MEMORY_VOLTAGE_DOMAIN_OPP_CHANGE 

Set Memory Voltage Domain OPP change bit

ePMI_ENABLE_LOGIC_POWER_DOMAIN_STATE_CHANGE 

Set Logic power domain state change bit

ePMI_ENABLE_MEMORY_POWER_DOMAIN_STATE_CHANGE 

Set Memory power domain state change bit

ePMI_ENABLES_NOT_MODIFIED 

Don't modify the event enable bits

enum ePMI_ModID
ePMI_ModID
Power Module ID list
Enumerator
ePMI_PM 

Power Module ID

ePMI_PM_ModuleCnt 

Number of power modules in the System

Function Documentation

ePMI_Error PMI_OpenModule ( PMI_Handle_Pntr pPMI_Handle,
ePMI_ModID  PMI_ModId,
PMI_CfgParams pPMI_CfgParams 
)
PMI_OpenModule

Open the PMI Library API. Aquire ownership of the device's PMI module and allocate PMI Handle storage.

Parameters
[out]pPMI_HandlePointer 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_ModIdePMI_ModID enumerated module intentifier.
[in]pPMI_CfgParamsPointer to a PMI_CfgParams structure.
Returns
ePMI_Error
Details:

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:

  • Sample window size set to 4096 sysclks
  • All events enabled for capture

If pPMI_CfgParams->pSTMHandle is not NULL the PMI Library will:

  • Generating STM messages for meta parameters needed by data analysis tools (such as the Trace Anaylzer)
  • Enables library provided logging messages that reflect important state changes to the user.
  • Enables user generated messages through PMI_LogMsg().
ePMI_Error PMI_CloseModule ( PMI_Handle_Pntr  pPMI_Handle)
PMI_CloseModule

Close the PMI Library. Disable the device's PMI module and release ownership. Free the PMI_Handle storage.

Parameters
[in]pPMI_HandlePMI Handle Pointer
Returns
ePMI_Error
Details:

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 
)
PMI_GetVersion

Get PMI Library version, software functional ID and hardware functional ID.

Parameters
[in]pPMI_HandlePMI Handle Pointer
[out]pLibMajorVersionPMI Library Major Version (API modifications not backward compatible)
[out]pLibMinorVersionPMI Library Minor Version (Backward compatible modifications)
[out]pSWFuncIDThe deivce's PMI Module Functional ID the library is compatible with
[out]pHwFuncIDThe actual device's PMI Module Functional ID
Returns
ePMI_Error
Details:

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)
PMI_ModuleActivityEnable

Enable the PMI module's activity collection and STM message export.

Parameters
[in]pPMI_HandlePMI Handle Pointer
Returns
ePMI_Error
Details:

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 
)
PMI_ModuleActivityDisable

Disable the PMI module's activity collection and the device's PMI STM message export.

Parameters
[in]pPMI_HandlePMI Handle Pointer
[in]retainif true (non-zero) do not reset the module, if false perform soft reset of the PMI module
Returns
ePMI_Error
Details:

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 
)
PMI_ConfigModule

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().

Parameters
[in]pPMI_HandlePMI Handle Pointer
[in]triggerEnables::ePCMI_Triggers enumerated optional module start and stop triggers (default after calling PMI_OpenModule(), no triggers enabled)
[in]eventEnablesePMI_EventEnables enumerated event enables (default after calling PMI_OpenModule(), all events enabled)
Returns
ePMI_Error
Details:

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 
)
PMI_GetSampleWindow

Retrieve the actual PMI module's sample window time frame in sysclocks.

Parameters
[in]pPMI_HandlePMI Handle Pointer
[out]pFuncClockDividerFunctional clock divider parameter (1-16 are valid values).
[out]pSampleWindowSizeSample window size (1-256 are valid values).
Returns
ePMI_Error
Details:

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)
PMI_GetErrorMsg

Retrieve a pointer to errorCode's text string.

Parameters
[in]errorCodeePMI_Error enumerated error code.
Returns
char * Pointer to the error string.
Details:

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 
)
PMI_LogMsg

Issue a client provided Power Management relevant STM message.

Parameters
[in]pPMI_HandlePMI Handle Pointer
[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
ePMI_Error
Details:

The following information will be provided in the PMI STM message:

  • Module - Pointer to the module's name string, typically "PM". Derived from PMI_ModId (set by PMI_OpenModule()).
  • Data Domain - Pointer to the doamin name, in this case it's "SW".
  • Data Class - Pointer to the class name, in this case it's "PMI User Message".
  • Data Type - Pointer to the data type, in this case it's "Msg".
  • Data Message - Pointer to the FmtString.
  • value - If pValue is not NULL, value is provided.

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 
)
PMI_MarkLogicVoltageOPPChange

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.

Parameters
[in]pPMI_HandlePMI Handle Pointer
[in]pwrDomainePMI_LVD_OPP specifies the logic vlotage domain that changed.
[in]pwrValueIs the 8-bit SMPS Output Voltage Selection Code (Standard Mode) used for voltage level selection. Valid values are 0 to 0x3E.
Returns
ePMI_Error
Details:

The following information will be provided in the PMI STM message:

  • Module - Pointer to the module's name string, typically "PM". Derived from PMI_ModId (set by PMI_OpenModule()).
  • Data Domain - Pointer to the logic voltage domain name string. Dirived from enumerated pwrDomain parameter.
  • Data Class - Pointer to the class name, in this case it's "Logic Voltage OPP Change".
  • Data Type - Pointer to the data type, in this case it's "Value".
  • Data Message - Pointer to the pwrValue converted to Vout(mV) string ("612.5 mV").

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 
)
PMI_MarkMemoryVoltageOPPChange

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.

Parameters
[in]pPMI_HandlePMI Handle Pointer
[in]pwrDomainePMI_MVD_OPP specifies the memory voltage domain that changed.
[in]pwrStateePMI_MVD_PwrState specifies the memory voltage domain state.
Returns
ePMI_Error
Details:

The following information will be provided in the STM message:

  • Module - Pointer to the module's name string, typically "PM". Derived from PMI_ModId (set by PMI_OpenModule()).
  • Data Domain - Pointer to the memory voltage domain name string. Dirived from enumerated pwrDomain parameter.
  • Data Class - Pointer to the class name, in this case it's "Memory Voltage OPP Change".
  • Data Type - Pointer to the data type, in this case it's "State".
  • Data Message - Pointer to the voltage state. Derived from the pwrState parameter.

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 
)
PMI_MarkLogicPowerStateChange

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.

Parameters
[in]pPMI_HandlePMI Handle Pointer
[in]pwrDomainePMI_LPD_StateChange specifies the logic power domain that changed.
[in]pwrStateePMI_LPD_PwrState specifies the logic power domain state.
Returns
ePMI_Error
Details:

The following information will be provided in the STM message:

  • Module - Pointer to the module's name string, typically "PM". Derived from PMI_ModId (set by PMI_OpenModule()).
  • Data Domain - Pointer to the memory voltage domain name string. Dirived from enumerated pwrDomain parameter.
  • Data Class - Pointer to the class name, in this case it's "Logic Power State Change".
  • Data Type - Pointer to the data type, in this case it's "State".
  • Data Message - Pointer to the logic power state. Derived from the pwrState parameter.

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 
)
PMI_MarkMemoryPowerStateChange

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.

Parameters
[in]pPMI_HandlePMI Handle Pointer
[in]pwrDomainePMI_MPD_StateChange specifies the memory power domain that changed.
[in]pwrStateePMI_MPD_PwrState specifies the memory power domain state.
Returns
ePMI_Error
Details:

The following information will be provided in the STM message:

  • Module - Pointer to the module's name string, typically "PM". Derived from PMI_ModId (set by PMI_OpenModule()).
  • Data Domain - Pointer to the memory power domain name string. Dirived from enumerated pwrDomain parameter.
  • Data Class - Pointer to the class name, in this case it's "Memory Power State Change".
  • Data Type - Pointer to the data type, in this case it's "State".
  • Data Message - Pointer to the memory power state. Derived from the pwrState parameter.

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.