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.
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_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_t * | POWER_SYS_GetErrorCallback (void) |
This function returns the callback configuration structure for the last failed notification. More... | |
typedef void power_manager_callback_data_t |
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()).
notify | Notification structure. |
dataPtr | Callback data. Pointer to the data passed during callback registration. Intended to pass any driver or application data such as internal state information. |
Definition at line 172 of file power_manager.h.
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:
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.
status_t POWER_SYS_Deinit | ( | void | ) |
This function deinitializes the Power manager.
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.
Definition at line 218 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.
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.
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.
[out] | powerModeIndexPtr | Power mode which has been set represented as an index into array of power mode configurations passed to the POWER_SYS_Init(). |
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.
[out] | powerModePtr | Pointer to power mode configuration structure of the last set power mode. |
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.
[in] | powerConfigsPtr | A pointer to an array of pointers to all power configurations which will be handled by Power manager. |
[in] | configsNumber | Number of power configurations. Size of powerConfigsPtr array. |
[in] | callbacksPtr | A pointer to an array of pointers to callback configurations. If there are no callbacks to register during Power manager initialization, use NULL value. |
[in] | callbacksNumber | Number of registered callbacks. Size of callbacksPtr array. |
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.
[in] | powerModeIndex | Requested power mode represented as an index into array of user-defined power mode configurations passed to the POWER_SYS_Init(). |
[in] | policy | Transaction policy |
Definition at line 338 of file power_manager.c.