CMI Instrumentation Library API Reference Guide
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator
Data Structures | Typedefs | Enumerations | Functions
CMILib.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  _CMI_CfgParams
 

Typedefs

typedef struct CMI_Handle_t CMI_Handle
 
typedef CMI_HandleCMI_Handle_Pntr
 
typedef struct _CMI_CfgParams CMI_CfgParams
 
typedef ePCMI_Error eCMI_Error
 

Enumerations

enum  eCMI_ModEnableType { eCMI_Event, eCMI_Activity }
 
enum  eCMI_EventEnables {
  eCMI_ENABLE_EVENT_NONE = 0, eCMI_ENABLE_EVENT_CLOCK_DOMAIN_STATE_UPDATE = 0x000001, eCMI_ENABLE_EVENT_CLOCK_FREQDIVIDER_8BIT_UPDATE = 0x000002, eCMI_ENABLE_EVENT_CLOCK_FREQDIVIDER_4BIT_UPDATE = 0x000004,
  eCMI_ENABLE_EVENT_CLOCK_SOURCE_SELECTION_UPDATE = 0x000008, eCMI_ENABLE_EVENT_CM1_CORE_DPLL_UPDATE = 0x010000, eCMI_ENABLE_EVENT_CM1_MPU_DPLL_UPDATE = 0x020000, eCMI_ENABLE_EVENT_CM1_IVA_DPLL_UPDATE = 0x040000,
  eCMI_ENABLE_EVENT_CM1_ABE_DPLL_UPDATE = 0x080000, eCMI_ENABLE_EVENT_CM1_DDRPHY_DPLL_UPDATE = 0x100000, eCMI_ENABLE_EVENT_CM2_PER_DPLL_UPDATE = 0x010000, eCMI_ENABLE_EVENT_CM2_USB_DPLL_UPDATE = 0x020000,
  eCMI_ENABLE_EVENT_CM2_UNIPRO_DPLL_UPDATE = 0x040000, eCMI_ENABLES_EVENT_NOT_MODIFIED = -1
}
 
enum  eCMI_ActivityEnables { eCMI_ENABLE_ACTIVITY_NONE = 0, eCMI_ENABLE_ACTIVITY_TARGET = 0x3, eCMI_ENABLE_ACTIVITY_INITIATOR = 0xc, eCMI_ENABLES_ACTIVITY_NOT_MODIFIED = -1 }
 
enum  eCMI_ModID { eCMI_CM1, eCMI_CM2, eCMI_CM_ModuleCnt }
 

Functions

eCMI_Error CMI_OpenModule (CMI_Handle_Pntr *pCMI_Handle, eCMI_ModID CMI_ModId, CMI_CfgParams *pCMI_CfgParams)
 
eCMI_Error CMI_CloseModule (CMI_Handle_Pntr pCMI_Handle)
 
eCMI_Error CMI_GetVersion (CMI_Handle_Pntr pCMI_Handle, uint32_t *pLibMajorVersion, uint32_t *pLibMinorVersion, uint32_t *pSWFuncID, uint32_t *pHwFuncID)
 
eCMI_Error CMI_ModuleEnable (CMI_Handle_Pntr pCMI_Handle, eCMI_ModEnableType modEnableType)
 
eCMI_Error CMI_ModuleDisable (CMI_Handle_Pntr pCMI_Handle, int32_t retain)
 
eCMI_Error CMI_ConfigModule (CMI_Handle_Pntr pCMI_Handle, ePCMI_Triggers triggerEnables, eCMI_EventEnables eventEnables, eCMI_ActivityEnables activityEnables)
 
eCMI_Error CMI_GetSampleWindow (CMI_Handle_Pntr pCMI_Handle, uint32_t *pFuncClockDivider, uint32_t *pSampleWindowSize)
 
const char * CMI_GetErrorMsg (eCMI_Error errorCode)
 
eCMI_Error CMI_LogMsg (CMI_Handle_Pntr pCMI_Handle, const char *FmtString, int32_t *pValue)
 
eCMI_Error CMI_MarkClockDomainStateChange (CMI_Handle_Pntr pCMI_Handle, eCMI_ClockDomainStateChange clkDomain, eCMI_clkState clkState)
 
eCMI_Error CMI_MarkClockDividerRatioChange (CMI_Handle_Pntr pCMI_Handle, eCMI_ClockDividerRatioChange divDomain, eCMI_divState divState)
 
eCMI_Error CMI_MarkClockSourceSelectionChange (CMI_Handle_Pntr pCMI_Handle, eCMI_ClockSource clkSource)
 
eCMI_Error CMI_MarkDPLLSettingChange (CMI_Handle_Pntr pCMI_Handle, eCMI_DPLLSrc dlppSource)
 

Detailed Description

CMI Library Function Prototypes

Typedef Documentation

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.

CMI_Hande_Pntr
Pointer to a CMI Handle object
typedef struct _CMI_CfgParams CMI_CfgParams
CMI_CfgParams
CMI Configuration Parameters
eCMI_Error
CMI Error codes CMI specific version of ePCMI_Error type

Enumeration Type Documentation

eCMI_ModEnableType
CMI module enable type
Enumerator
eCMI_Event 

Enable the module for Event collection

eCMI_Activity 

Enable the module for Activity collection

eCMI_EventEnables;
CMI module event enables
Enumerator
eCMI_ENABLE_EVENT_NONE 

Clear all enabled events

eCMI_ENABLE_EVENT_CLOCK_DOMAIN_STATE_UPDATE 

Enable Event Clock Domain State Updates

eCMI_ENABLE_EVENT_CLOCK_FREQDIVIDER_8BIT_UPDATE 

Enable Event Clock Frequency Divider Ratio Updates that require 8-bit messages

eCMI_ENABLE_EVENT_CLOCK_FREQDIVIDER_4BIT_UPDATE 

Enable Event Clock Frequency Divider Ratio Updates that require 4-bit messages

eCMI_ENABLE_EVENT_CLOCK_SOURCE_SELECTION_UPDATE 

Enable Event Clock Source Selection Updates

eCMI_ENABLE_EVENT_CM1_CORE_DPLL_UPDATE 

Enable CM1 Core DPLL Event Updates

eCMI_ENABLE_EVENT_CM1_MPU_DPLL_UPDATE 

Enable CM1 MPU DPLL Event Updates

eCMI_ENABLE_EVENT_CM1_IVA_DPLL_UPDATE 

Enable CM1 IVA DPLL Event Updates

eCMI_ENABLE_EVENT_CM1_ABE_DPLL_UPDATE 

Enable CM1 ABE DPLL Event Updates

eCMI_ENABLE_EVENT_CM1_DDRPHY_DPLL_UPDATE 

Enable CM1 DDRPHY DPLL Event Updates

eCMI_ENABLE_EVENT_CM2_PER_DPLL_UPDATE 

Enable CM2 PER DPLL Event Updates

eCMI_ENABLE_EVENT_CM2_USB_DPLL_UPDATE 

Enable CM2 USB DPLL Event Updates

eCMI_ENABLE_EVENT_CM2_UNIPRO_DPLL_UPDATE 

Enable CM2 UNIPRO DPLL Event Updates

eCMI_ENABLES_EVENT_NOT_MODIFIED 

Do not modify enabled events

eCMI_ActivityEnables;
CMI module activity enables
Enumerator
eCMI_ENABLE_ACTIVITY_NONE 

Clear all enabled activity monitoring

eCMI_ENABLE_ACTIVITY_TARGET 

Enable target activity monitoring

eCMI_ENABLE_ACTIVITY_INITIATOR 

Enable initiator activity monorting

eCMI_ENABLES_ACTIVITY_NOT_MODIFIED 

Do not modify activity enables

enum eCMI_ModID
eCMI_ModID
Clock Module ID list
Enumerator
eCMI_CM1 

Clock Module 0 ID

eCMI_CM2 

Clock Module 1 ID (not valid for DRA7xx)

eCMI_CM_ModuleCnt 

Number of clock modules in the System

Function Documentation

eCMI_Error CMI_OpenModule ( CMI_Handle_Pntr pCMI_Handle,
eCMI_ModID  CMI_ModId,
CMI_CfgParams pCMI_CfgParams 
)
CMI_OpenModule

Open the CMI Library API, aquire ownership of the device's CMI module and allocate CMI Handle storage.

Parameters
[out]pCMI_HandleA 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_ModIdeCMI_ModID enumerated module intentifier.
[in]pCMI_CfgParamsPointer to a CMI_CfgParams structure.
Returns
eCMI_Error
Details:

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:

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

If pCMI_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 CMI_LogMsg().
eCMI_Error CMI_CloseModule ( CMI_Handle_Pntr  pCMI_Handle)
CMI_CloseModule

Close the CMI Library API. Disable the device's CMI module and release ownership. Free the CMI_Handle storage.

Parameters
[in]pCMI_HandleCMI Handle Pointer
Returns
eCMI_Error
Details:

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

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

Parameters
[in]pCMI_HandleCMI Handle Pointer
[out]pLibMajorVersionCMI Library Major Version (API modifications not backward compatible)
[out]pLibMinorVersionCMI Library Minor Version (Backward compatible modifications)
[out]pSWFuncIDThe deivce's CMI Module Functional ID the library is compatible with
[out]pHwFuncIDThe actual device's CMI Module Functional ID
Returns
eCMI_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 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 
)
CMI_ModuleEnable

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

Parameters
[in]pCMI_HandleCMI Handle Pointer
[in]modEnableTypeeCMI_ModEnableType enumerated value used to select the monitor type, activity or events.
Returns
eCMI_Error
Details:

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

Disable the CMI module's activity or event collection and the device's CMI STM message export.

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

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

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.

Parameters
[in]pCMI_HandleCMI Handle Pointer
[in]triggerEnables::ePCMI_Triggers enumerated optional module start and stop triggers (default set by CMI_OpenModule(), no triggers enabled)
[in]eventEnableseCMI_EventEnables enumerated event snapshot enables (default set by CMI_OpenModule(), all events enabled)
[in]activityEnableseCMI_ActivityEnables enumerated activity monitor enables (default set by CMI_OpenModule(), all activity enabled)
Returns
eCMI_Error

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.

Details:

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

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

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

This function provides the actual size of the sample window in functional clocks.

const char* CMI_GetErrorMsg ( eCMI_Error  errorCode)
CMI_GetErrorMsg

Retrieve a pointer to errorCode's text string.

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

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

Issue a client provided Clock Management relevant STM message.

Parameters
[in]pCMI_HandleCMI 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
eCMI_Error
Details:

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

  • Module - Pointer to the module's name string, typically "CM1" or "CM2". Derived from CMI_ModId (set by CMI_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 "CMI 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 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 
)
CMI_MarkClockDomainStateChange

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.

Parameters
[in]pCMI_HandleCMI Handle Pointer
[in]clkDomaineCMI_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]clkStateeCMI_clkState specifies the enumerated clock domain state
Returns
eCMI_Error
Details:

The following information will be provided in the STM message:

  • Module - Pointer to the module's name string, typically "CM0" or "CM1". Derived from CMI_ModId (set by CMI_OpenModule()).
  • Data Domain - Pointer to the clock domain name string. Dirived from enumerated pwrDomain parameter.
  • Data Class - Pointer to the class name, in this case it's "Clock Doamin State Change".
  • Data Type - Pointer to the data type, in this case it's "State".
  • Data Message - Pointer to the clock doamin state. Derived from the clkState parameter, "Clock gated" or "Clock running".

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

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.

Parameters
[in]pCMI_HandleCMI Handle Pointer
[in]divDomaineCMI_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]divStateeCMI_divState specifies the emunerated clock divider value (eCMI_DivBy1, eCMI_DivBy2, eCMI_DivBy4)
Returns
eCMI_Error
Details:

The following information will be provided in the STM message:

  • Module - Pointer to the module's name string, typically "CM0" or "CM1". Derived from CMI_ModId (set by CMI_OpenModule()).
  • Data Domain - Pointer to the clock domain name string. Dirived from enumerated pwrDomain parameter.
  • Data Class - Pointer to the class name, in this case it's "Clock Divider Ratio Change".
  • Data Type - Pointer to the data type, in this case it's "State".
  • Data Message - Pointer to the clock doamin state. Derived from the divState parameter ("Divide by 1", "Divide by 2" or "Divide by 4").

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

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.

Parameters
[in]pCMI_HandleCMI Handle Pointer
[in]clkSourceeCMI_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.
Returns
eCMI_Error
Details:

The following information will be provided in the STM message:

  • Module - Pointer to the module's name string, typically "CM0" or "CM1". Derived from CMI_ModId (set by CMI_OpenModule()).
  • Data Domain - Pointer to the clock domain name string. Dirived from enumerated clkSource parameter.
  • Data Class - Pointer to the class name, in this case it's "Clock Divider Ratio Change".
  • Data Type - Empty
  • Data Message - Empty

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

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.

Parameters
[in]pCMI_HandleCMI Handle Pointer
[in]dlppSourceeCMI_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.
Returns
eCMI_Error
Details:

The following information will be provided in the STM message:

  • Module - Pointer to the module's name string, typically "CM0" or "CM1". Derived from CMI_ModId (set by CMI_OpenModule()).
  • Data Domain - Pointer to the DPLL domain name string. Dirived from enumerated dlppSource parameter.
  • Data Class - Pointer to the class name, in this case it's "DLPP Setting Change".
  • Data Type - Empty
  • Data Message - Empty

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.