S32 SDK
Power Manager

Detailed Description

The S32 SDK Power Manager provides a set of API/services that enables applications to configure and select among various operational and low power modes.

Driver consideration

The Power Manager driver is developed on top of an appropriate hardware access layer (SMC, MC_ME etc). The Power Manager provides API to handle the device power modes. It also supports run-time switching between multiple power modes. Each power mode is described by configuration structures with multiple power-related options. The Power Manager provides a notification mechanism for registered callbacks and API for static and dynamic callback registration.

The Driver uses structures for configuration. The actual format of the structure is defined by the underlying device specific header file. There is a power mode and a callback configuration structure. These structures may be generated using Processor Expert. The user application can use the default for most settings, changing only what is necessary.

This driver provides functions for initializing power manager and changing the power mode.

All methods that access the hardware layer will return an error code to signal if the operation succeeded or failed. The values are defined by the status_t enumeration, and the possible values include: success, switch error, callback notification errors, wrong clock setup error.

Modules

 Power Manager Driver
 This module covers the device-specific clock_manager functionality implemented for S32K1xx SOC.
 
 Power_s32k1xx
 

Data Structures

struct  power_manager_notify_struct_t
 Power mode user configuration structure. More...
 
struct  power_manager_callback_user_config_t
 callback configuration structure More...
 
struct  power_manager_state_t
 Power manager internal state structure. More...
 

Typedefs

typedef void power_manager_callback_data_t
 Callback-specific data. More...
 
typedef status_t(* power_manager_callback_t) (power_manager_notify_struct_t *notify, power_manager_callback_data_t *dataPtr)
 Callback prototype. More...
 

Enumerations

enum  power_manager_policy_t { POWER_MANAGER_POLICY_AGREEMENT, POWER_MANAGER_POLICY_FORCIBLE }
 Power manager policies. More...
 
enum  power_manager_notify_t { POWER_MANAGER_NOTIFY_RECOVER = 0x00U, POWER_MANAGER_NOTIFY_BEFORE = 0x01U, POWER_MANAGER_NOTIFY_AFTER = 0x02U }
 The PM notification type. Used to notify registered callbacks. Callback notifications can be invoked in following situations: More...
 
enum  power_manager_callback_type_t { POWER_MANAGER_CALLBACK_BEFORE = 0x01U, POWER_MANAGER_CALLBACK_AFTER = 0x02U, POWER_MANAGER_CALLBACK_BEFORE_AFTER = 0x03U }
 The callback type indicates when a callback will be invoked. More...
 

Functions

status_t POWER_SYS_Init (power_manager_user_config_t *(*powerConfigsPtr)[], uint8_t configsNumber, power_manager_callback_user_config_t *(*callbacksPtr)[], uint8_t callbacksNumber)
 Power manager initialization for operation. More...
 
status_t POWER_SYS_Deinit (void)
 This function deinitializes the Power manager. More...
 
status_t POWER_SYS_SetMode (uint8_t powerModeIndex, power_manager_policy_t policy)
 This function configures the power mode. More...
 
status_t POWER_SYS_GetLastMode (uint8_t *powerModeIndexPtr)
 This function returns the last successfully set power mode. More...
 
status_t POWER_SYS_GetLastModeConfig (power_manager_user_config_t **powerModePtr)
 This function returns the user configuration structure of the last successfully set power mode. More...
 
power_manager_modes_t POWER_SYS_GetCurrentMode (void)
 This function returns currently running power mode. More...
 
uint8_t POWER_SYS_GetErrorCallbackIndex (void)
 This function returns the last failed notification callback. More...
 
power_manager_callback_user_config_tPOWER_SYS_GetErrorCallback (void)
 This function returns the callback configuration structure for the last failed notification. More...
 

Typedef Documentation

Callback-specific data.

Pointer to data of this type is passed during callback registration. The pointer is part of the power_manager_callback_user_config_t structure and is passed to the callback during power mode change notifications. Implements power_manager_callback_data_t_Class

Definition at line 118 of file power_manager.h.

typedef status_t(* power_manager_callback_t) (power_manager_notify_struct_t *notify, power_manager_callback_data_t *dataPtr)

Callback prototype.

Declaration of callback. It is common for all registered callbacks. Function pointer of this type is part of power_manager_callback_user_config_t callback configuration structure. Depending on the callback type, the callback function is invoked during power mode change (see POWER_SYS_SetMode()) before the mode change, after it, or in both cases to notify about the change progress (see power_manager_callback_type_t). When called, the type of the notification is passed as parameter along with a pointer to power mode configuration structure (see power_manager_notify_struct_t) and any data passed during the callback registration (see power_manager_callback_data_t). When notified before a mode change, depending on the power mode change policy (see power_manager_policy_t) the callback may deny the mode change by returning any error code other than STATUS_SUCCESS (see POWER_SYS_SetMode()).

Parameters
notifyNotification structure.
dataPtrCallback data. Pointer to the data passed during callback registration. Intended to pass any driver or application data such as internal state information.
Returns
An error code or STATUS_SUCCESS. Implements power_manager_callback_t_Class

Definition at line 172 of file power_manager.h.

Enumeration Type Documentation

The callback type indicates when a callback will be invoked.

Used in the callback configuration structures (power_manager_callback_user_config_t) to specify when the registered callback will be called during power mode change initiated by POWER_SYS_SetMode().

Implements power_manager_callback_type_t_Class

Enumerator
POWER_MANAGER_CALLBACK_BEFORE 

Before callback.

POWER_MANAGER_CALLBACK_AFTER 

After callback.

POWER_MANAGER_CALLBACK_BEFORE_AFTER 

Before-After callback.

Definition at line 103 of file power_manager.h.

The PM notification type. Used to notify registered callbacks. Callback notifications can be invoked in following situations:

  • before a power mode change (Callback return value can affect POWER_SYS_SetMode() execution. Refer to the POWER_SYS_SetMode() and power_manager_policy_t documentation).
  • after a successful change of the power mode.
  • after an unsuccessful attempt to switch power mode, in order to recover to a working state. Implements power_manager_notify_t_Class
Enumerator
POWER_MANAGER_NOTIFY_RECOVER 

Notify IP to recover to previous work state.

POWER_MANAGER_NOTIFY_BEFORE 

Notify IP that the system will change the power setting.

POWER_MANAGER_NOTIFY_AFTER 

Notify IP that the system has changed to a new power setting.

Definition at line 87 of file power_manager.h.

Power manager policies.

Defines whether the mode switch initiated by the POWER_SYS_SetMode() is agreed upon (depending on the result of notification callbacks), or forced. For POWER_MANAGER_POLICY_FORCIBLE the power mode is changed regardless of the callback results, while for POWER_MANAGER_POLICY_AGREEMENT policy any error code returned by one of the callbacks aborts the mode change. See also POWER_SYS_SetMode() description. Implements power_manager_policy_t_Class

Enumerator
POWER_MANAGER_POLICY_AGREEMENT 

Power mode is changed if all of the callbacks return success.

POWER_MANAGER_POLICY_FORCIBLE 

Power mode is changed regardless of the result of callbacks.

Definition at line 72 of file power_manager.h.

Function Documentation

status_t POWER_SYS_Deinit ( void  )

This function deinitializes the Power manager.

Returns
An error code or STATUS_SUCCESS.

Definition at line 120 of file power_manager.c.

power_manager_modes_t POWER_SYS_GetCurrentMode ( void  )

This function returns currently running power mode.

This function reads hardware settings and returns currently running power mode.

Returns
Currently used run power mode.

Definition at line 202 of file power_manager_S32K1xx.c.

power_manager_callback_user_config_t* POWER_SYS_GetErrorCallback ( void  )

This function returns the callback configuration structure for the last failed notification.

This function returns a pointer to configuration structure of the last callback that failed during the power mode switch when POWER_SYS_SetMode() was called. If the last POWER_SYS_SetMode() call ended successfully, a NULL value is returned.

Returns
Pointer to the callback configuration which returns error.

Definition at line 218 of file power_manager.c.

uint8_t POWER_SYS_GetErrorCallbackIndex ( void  )

This function returns the last failed notification callback.

This function returns the index of the last callback that failed during the power mode switch when POWER_SYS_SetMode() was called. The returned value represents the index in the array of registered callbacks. If the last POWER_SYS_SetMode() call ended successfully, a value equal to the number of registered callbacks is returned.

Returns
Callback index of last failed callback or value equal to callbacks count.

Definition at line 206 of file power_manager.c.

status_t POWER_SYS_GetLastMode ( uint8_t *  powerModeIndexPtr)

This function returns the last successfully set power mode.

This function returns index of power mode which was last set using POWER_SYS_SetMode(). If the power mode was entered even though some of the registered callbacks denied the mode change, or if any of the callbacks invoked after the entering/restoring run mode failed, then the return code of this function has STATUS_ERROR value.

Parameters
[out]powerModeIndexPtrPower mode which has been set represented as an index into array of power mode configurations passed to the POWER_SYS_Init().
Returns
An error code or STATUS_SUCCESS.

Definition at line 143 of file power_manager.c.

status_t POWER_SYS_GetLastModeConfig ( power_manager_user_config_t **  powerModePtr)

This function returns the user configuration structure of the last successfully set power mode.

This function returns a pointer to configuration structure which was last set using POWER_SYS_SetMode(). If the current power mode was entered even though some of the registered callbacks denied the mode change, or if any of the callbacks invoked after the entering/restoring run mode failed, then the return code of this function has STATUS_ERROR value.

Parameters
[out]powerModePtrPointer to power mode configuration structure of the last set power mode.
Returns
An error code or STATUS_SUCCESS.

Definition at line 175 of file power_manager.c.

status_t POWER_SYS_Init ( power_manager_user_config_t *(*)  powerConfigsPtr[],
uint8_t  configsNumber,
power_manager_callback_user_config_t *(*)  callbacksPtr[],
uint8_t  callbacksNumber 
)

Power manager initialization for operation.

This function initializes the Power manager and its run-time state structure. Pointer to an array of Power mode configuration structures needs to be passed as a parameter along with a parameter specifying its size. At least one power mode configuration is required. Optionally, pointer to the array of predefined callbacks can be passed with its corresponding size parameter. For details about callbacks, refer to the power_manager_callback_user_config_t. As Power manager stores only pointers to arrays of these structures, they need to exist and be valid for the entire life cycle of Power manager.

Parameters
[in]powerConfigsPtrA pointer to an array of pointers to all power configurations which will be handled by Power manager.
[in]configsNumberNumber of power configurations. Size of powerConfigsPtr array.
[in]callbacksPtrA pointer to an array of pointers to callback configurations. If there are no callbacks to register during Power manager initialization, use NULL value.
[in]callbacksNumberNumber of registered callbacks. Size of callbacksPtr array.
Returns
An error code or STATUS_SUCCESS.

Definition at line 80 of file power_manager.c.

status_t POWER_SYS_SetMode ( uint8_t  powerModeIndex,
power_manager_policy_t  policy 
)

This function configures the power mode.

This function switches to one of the defined power modes. Requested mode number is passed as an input parameter. This function notifies all registered callback functions before the mode change (using POWER_MANAGER_CALLBACK_BEFORE set as callback type parameter), sets specific power options defined in the power mode configuration and enters the specified mode. In case of run modes (for example, Run, Very low power run, or High speed run), this function also invokes all registered callbacks after the mode change (using POWER_MANAGER_CALLBACK_AFTER). In case of sleep or deep sleep modes, if the requested mode is not exited through a reset, these notifications are sent after the core wakes up. Callbacks are invoked in the following order: All registered callbacks are notified ordered by index in the callbacks array (see callbacksPtr parameter of POWER_SYS_Init()). The same order is used for before and after switch notifications. The notifications before the power mode switch can be used to obtain confirmation about the change from registered callbacks. If any registered callback denies the power mode change, further execution of this function depends on mode change policy: the mode change is either forced(POWER_MANAGER_POLICY_FORCIBLE) or aborted(POWER_MANAGER_POLICY_AGREEMENT). When mode change is forced, the results of the before switch notifications are ignored. If agreement is requested, in case any callback returns an error code then further before switch notifications are cancelled and all already notified callbacks are re-invoked with POWER_MANAGER_CALLBACK_AFTER set as callback type parameter. The index of the callback which returned error code during pre-switch notifications is stored and can be obtained by using POWER_SYS_GetErrorCallback(). Any error codes during callbacks re-invocation (recover phase) are ignored. POWER_SYS_SetMode() returns an error code denoting the phase in which a callback failed. It is possible to enter any mode supported by the processor. Refer to the chip reference manual for the list of available power modes. If it is necessary to switch into an intermediate power mode prior to entering the requested mode (for example, when switching from Run into Very low power wait through Very low power run mode), then the intermediate mode is entered without invoking the callback mechanism.

Parameters
[in]powerModeIndexRequested power mode represented as an index into array of user-defined power mode configurations passed to the POWER_SYS_Init().
[in]policyTransaction policy
Returns
An error code or STATUS_SUCCESS.

Definition at line 338 of file power_manager.c.