Overview

The Kinetis SDK Power Manager provides a set of API/services to configure the power-related IPs, such as SMC, PMC, RCM, and so on.

Modules
	Power Manager driver

Data Structures
struct	power_manager_user_config_t
	Power mode user configuration structure. More...

struct	power_manager_notify_struct_t
	Power notification structure passed to the registered callback function. 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 power_manager_error_code_t(*	power_manager_callback_t )(power_manager_notify_struct_t notify, power_manager_callback_data_t dataPtr)
	Callback prototype. More...

Enumerations
enum	power_manager_modes_t { kPowerManagerRun, kPowerManagerVlpr, kPowerManagerWait, kPowerManagerVlpw, kPowerManagerStop, kPowerManagerVlps, kPowerManagerVlls1, kPowerManagerVlls3 }
	Power modes enumeration. More...

enum	power_manager_error_code_t { kPowerManagerSuccess, kPowerManagerError, kPowerManagerErrorOutOfRange, kPowerManagerErrorSwitch, kPowerManagerErrorNotificationBefore, kPowerManagerErrorNotificationAfter, kPowerManagerErrorClock }
	Power Manager success code and error codes. More...

enum	power_manager_policy_t { kPowerManagerPolicyAgreement, kPowerManagerPolicyForcible }
	Power Manager policies. More...

enum	power_manager_notify_t { kPowerManagerNotifyRecover = 0x00U, kPowerManagerNotifyBefore = 0x01U, kPowerManagerNotifyAfter = 0x02U }
	The Power Manager notification type. More...

enum	power_manager_callback_type_t { kPowerManagerCallbackBefore = 0x01U, kPowerManagerCallbackAfter = 0x02U, kPowerManagerCallbackBeforeAfter = 0x03U }
	The callback type, indicates what kinds of notification this callback handles. More...

Functions
power_manager_error_code_t	POWER_SYS_Init (power_manager_user_config_t const powerConfigsPtr, uint8_t configsNumber, power_manager_callback_user_config_t callbacksPtr, uint8_t callbacksNumber)
	Power Manager initialization for operation. More...

power_manager_error_code_t	POWER_SYS_Deinit (void)
	This function deinitializes the Power Manager. More...

power_manager_error_code_t	POWER_SYS_SetMode (uint8_t powerModeIndex, power_manager_policy_t policy)
	This function configures the power mode. More...

power_manager_error_code_t	POWER_SYS_GetLastMode (uint8_t *powerModeIndexPtr)
	This function returns power mode set as the last one. More...

power_manager_error_code_t	POWER_SYS_GetLastModeConfig (power_manager_user_config_t const **powerModePtr)
	This function returns user configuration structure of power mode set as the last one. More...

power_manager_modes_t	POWER_SYS_GetCurrentMode (void)
	This function returns the 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 last failed notification callback configuration structure. More...

bool	POWER_SYS_GetVeryLowPowerModeStatus (void)
	This function returns whether very low power mode is running. More...

bool	POWER_SYS_GetLowLeakageWakeupResetStatus (void)
	This function returns whether reset was caused by low leakage wake up. More...

bool	POWER_SYS_GetAckIsolation (void)
	Gets the acknowledge isolation flag. More...

void	POWER_SYS_ClearAckIsolation (void)
	Clears the acknowledge isolation flag. More...

Data Structure Documentation

struct power_manager_user_config_t

This structure defines Kinetis power mode with additional power options and specifies transition to and out of this mode. Application may define multiple power modes and switch between them. List of defined power modes is passed to the Power Manager during initialization as an array of references to structures of this type (see POWER_SYS_Init()). Power modes can be switched by calling POWER_SYS_SetMode() which accepts index to the list of power modes passed during manager initialization. Currently used power mode can be retrieved by calling POWER_SYS_GetLastMode(), which returns index of the current power mode, or by POWER_SYS_GetLastModeConfig(), which returns reference to the structure of current mode. List of power mode configuration structure members depends on power options available for specific chip. Complete list contains: mode - Kinetis power mode. List of available modes is chip-specific. See power_manager_modes_t list of modes. This item is common for all Kinetis chips. sleepOnExitOption - Controls whether the sleep-on-exit option value is used (when set to true) or ignored (when set to false). See sleepOnExitValue. This item is common for all Kinetis chips. sleepOnExitValue - When set to true, ARM core returns to sleep (Kinetis wait modes) or deep sleep state (Kinetis stop modes) after interrupt service finishes. When set to false, core stays woken-up. This item is common for all Kinetis chips. lowPowerWakeUpOnInterruptOption - Controls whether the wake-up-on-interrupt option value is used (when set to true) or ignored (when set to false). See lowPowerWakeUpOnInterruptValue. This item is chip-specific. lowPowerWakeUpOnInterruptValue - When set to true, system exits to Run mode when any interrupt occurs while in Very low power run, Very low power wait or Very low power stop mode. This item is chip-specific. powerOnResetDetectionOption - Controls whether the power on reset detection option value is used (when set to true) or ignored (when set to false). See powerOnResetDetectionValue. This item is chip-specific. powerOnResetDetectionValue - When set to true, power on reset detection circuit is enabled in Very low leakage stop 0 mode. When set to false, circuit is disabled. This item is chip-specific. RAM2PartitionOption - Controls whether the RAM2 partition power option value is used (when set to true) or ignored (when set to false). See RAM2PartitionValue. This item is chip-specific. RAM2PartitionValue - When set to true, RAM2 partition content is retained through Very low leakage stop 2 mode. When set to false, RAM2 partition power is disabled and memory content lost. This item is chip-specific. lowPowerOscillatorOption - Controls whether the Low power oscillator power option value is used (when set to true) or ignored (when set to false). See lowPowerOscillatorValue. This item is chip-specific. lowPowerOscillatorValue - When set to true, the 1 kHz Low power oscillator is enabled in any Low leakage or Very low leakage stop mode. When set to false, oscillator is disabled in these modes. This item is chip-specific.

Data Fields
power_manager_modes_t	mode
	Power mode.

bool	sleepOnExitValue
	true - Sleep or deep sleep after interrupt service finished, false - core stays woken-up.

struct power_manager_notify_struct_t

Data Fields
uint8_t	targetPowerConfigIndex
	Target power configuration index. More...

power_manager_user_config_t const *	targetPowerConfigPtr
	Pointer to target power configuration.

power_manager_policy_t	policy
	Clock transition policy. More...

power_manager_notify_t	notifyType
	Clock notification type. More...

Field Documentation

uint8_t power_manager_notify_struct_t::targetPowerConfigIndex

power_manager_policy_t power_manager_notify_struct_t::policy

power_manager_notify_t power_manager_notify_struct_t::notifyType

struct power_manager_callback_user_config_t

This structure holds configuration of callbacks passed to the Power Manager during its initialization. Callbacks of this type are expected to be statically allocated. This structure contains following application-defined data: callback - pointer to the callback function callbackType - specifies when the callback is called callbackData - pointer to the data passed to the callback.

struct power_manager_state_t

Power Manager internal structure. Contains data necessary for Power Manager proper function. Stores references to registered power mode configurations, callbacks, information about their numbers and other internal data. This structure is statically allocated and initialized after POWER_SYS_Init() call.

Data Fields
power_manager_user_config_t const **	configs
	Pointer to power configure table. More...

uint8_t	configsNumber
	Number of power configurations.

power_manager_callback_user_config_t **	staticCallbacks
	Pointer to callback table. More...

uint8_t	staticCallbacksNumber
	Maximum number of callback configurations.

uint8_t	errorCallbackIndex
	Index of callback returns error. More...

uint8_t	currentConfig
	Index of current configuration. More...

Field Documentation

power_manager_user_config_t const** power_manager_state_t::configs

power_manager_callback_user_config_t** power_manager_state_t::staticCallbacks

uint8_t power_manager_state_t::errorCallbackIndex

uint8_t power_manager_state_t::currentConfig

Typedef Documentation

typedef void power_manager_callback_data_t

Reference to data of this type is passed during callback registration. The reference is part of the power_manager_callback_user_config_t structure and is passed to the callback during power mode change notifications.

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

Declaration of callback. It is common for registered callbacks. Reference to function of this type is part of power_manager_callback_user_config_t callback configuration structure. Depending on callback type, function of this prototype is called during the 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, type of the notification is passed as parameter along with reference to entered 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 the 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 different from kPowerManagerSuccess (see POWER_SYS_SetMode()).

Parameters

notify	Notification structure.
dataPtr	Callback data. Refers 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 kPowerManagerSuccess.

Enumeration Type Documentation

enum power_manager_modes_t

Defines power mode. Used in the power mode configuration structure (power_manager_user_config_t). From ARM core perspective, power modes can be generally divided to run modes (high-speed run, run, and very low power run), sleep (wait and very low power wait), and deep sleep modes (all stop modes). List of power modes supported by a specific chip along with requirements for entering and exiting of these modes can be found in the chip documentation. List of all supported power modes:

kPowerManagerHsrun - High speed run mode. Chip-specific.
kPowerManagerRun - Run mode. All Kinetis chips.
kPowerManagerVlpr - Very low power run mode. All Kinetis chips.
kPowerManagerWait - Wait mode. All Kinetis chips.
kPowerManagerVlpw - Very low power wait mode. All Kinetis chips.
kPowerManagerStop - Stop mode. All Kinetis chips.
kPowerManagerVlps - Very low power stop mode. All Kinetis chips.
kPowerManagerPstop1 - Partial stop 1 mode. Chip-specific.
kPowerManagerPstop2 - Partial stop 2 mode. Chip-specific.
kPowerManagerLls - Low leakage stop mode. All Kinetis chips.
kPowerManagerLls2 - Low leakage stop 2 mode. Chip-specific.
kPowerManagerLls3 - Low leakage stop 3 mode. Chip-specific.
kPowerManagerVlls0 - Very low leakage stop 0 mode. Chip-specific.
kPowerManagerVlls1 - Very low leakage stop 1 mode. All Kinetis chips.
kPowerManagerVlls2 - Very low leakage stop 2 mode. All Kinetis chips.
kPowerManagerVlls3 - Very low leakage stop 3 mode. All Kinetis chips.

Enumerator
kPowerManagerRun	Run mode. All Kinetis chips.
kPowerManagerVlpr	Very low power run mode. All Kinetis chips.
kPowerManagerWait	Wait mode. All Kinetis chips.
kPowerManagerVlpw	Very low power wait mode. All Kinetis chips.
kPowerManagerStop	Stop mode. All Kinetis chips.
kPowerManagerVlps	Very low power stop mode. All Kinetis chips.
kPowerManagerVlls1	Very low leakage stop 1 mode. All Kinetis chips.
kPowerManagerVlls3	Very low leakage stop 3 mode. All Kinetis chips.

enum power_manager_error_code_t

Used as return value of Power Manager functions.

Enumerator
kPowerManagerSuccess	Success.
kPowerManagerError	Some error occurs.
kPowerManagerErrorOutOfRange	Configuration index out of range.
kPowerManagerErrorSwitch	Error occurs during mode switch.
kPowerManagerErrorNotificationBefore	Error occurs during send "BEFORE" notification.
kPowerManagerErrorNotificationAfter	Error occurs during send "AFTER" notification.
kPowerManagerErrorClock	Error occurs due to wrong clock setup for power modes.

enum power_manager_policy_t

Defines whether the power mode change is forced or not. Used to specify whether the mode switch initiated by the POWER_SYS_SetMode() depends on the callback notification results. For kPowerManagerPolicyForcible, the power mode is changed regardless of the results, while kPowerManagerPolicyAgreement policy is used the POWER_SYS_SetMode() is exited when any of the callbacks returns error code. See also POWER_SYS_SetMode() description.

Enumerator
kPowerManagerPolicyAgreement	POWER_SYS_SetMode() method is exited when any of the callbacks returns error code.
kPowerManagerPolicyForcible	Power mode is changed regardless of the results.

enum power_manager_notify_t

Used to notify registered callbacks

Enumerator
kPowerManagerNotifyRecover	Notify IP to recover to previous work state.
kPowerManagerNotifyBefore	Notify IP that system changes power setting.
kPowerManagerNotifyAfter	Notify IP that have changed to new power setting.

enum power_manager_callback_type_t

Used in the callback configuration structures (power_manager_callback_user_config_t) to specify when the registered callback is called during power mode change initiated by POWER_SYS_SetMode(). Callback can be invoked in following situations:

before the 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 entering one of the run modes or after exiting from one of the (deep) sleep power modes back to the run mode.
after unsuccessful attempt to switch power mode

Enumerator
kPowerManagerCallbackBefore	Before callback.
kPowerManagerCallbackAfter	After callback.
kPowerManagerCallbackBeforeAfter	Before-After callback.

Function Documentation

power_manager_error_code_t POWER_SYS_Init	(	power_manager_user_config_t const **	powerConfigsPtr,
		uint8_t	configsNumber,
		power_manager_callback_user_config_t **	callbacksPtr,
		uint8_t	callbacksNumber
	)

This function initializes the Power Manager and its run-time state structure. Reference to an array of power mode configuration structures has to be passed as a parameter along with a parameter specifying its size. At least one power mode configuration is required. Optionally, reference to the array of predefined callbacks can be passed with its size parameter. For details about callbacks, refer to the power_manager_callback_user_config_t. As Power Manager stores only references to array of these structures, they have to exist while Power Manager is used. It is expected that prior to the POWER_SYS_Init() call the write-once protection register was configured appropriately allowing for entry to all required low power modes. The following is an example of how to set up two power modes and three callbacks, and initialize the Power Manager with structures containing their settings. The example shows two possible ways the configuration structures can be stored (ROM or RAM), although it is expected that they are placed in the read-only memory to save the RAM space. (Note: In the example it is assumed that the programmed chip doesn't support any optional power options described in the power_manager_user_config_t) :

const power_manager_user_config_t waitConfig = {
    kPowerManagerVlpw,
    true,
    true,
};
const power_manager_callback_user_config_t callbackCfg0 = {
    callback0,
    kPowerManagerCallbackBefore,
    &callback_data0
};
const power_manager_callback_user_config_t callbackCfg1 = {
    callback1,
    kPowerManagerCallbackAfter,
    &callback_data1
};
const power_manager_callback_user_config_t callbackCfg2 = {
    callback2,
    kPowerManagerCallbackBeforeAfter,
    &callback_data2
};
const power_manager_callback_user_config_t * const callbacks[] = {&callbackCfg0, &callbackCfg1, &callbackCfg2};
void main(void)
{
    power_manager_user_config_t idleConfig;
    power_manager_user_config_t *powerConfigs[] = {&idleConfig, &waitConfig};
    idleConfig.mode = kPowerManagerVlps;
    idleConfig.sleepOnExitOption = true;
    idleConfig.sleepOnExitValue = false;
    POWER_SYS_Init(&powerConfigs, 2U, &callbacks, 3U);
    POWER_SYS_SetMode(0U, kPowerManagerPolicyAgreement);
}

Parameters

powerConfigsPtr	A pointer to an array with references to all power configurations which is handled by the Power Manager.
configsNumber	Number of power configurations. Size of powerConfigsPtr array.
callbacksPtr	A pointer to an array with references to callback configurations. If there are no callbacks to register during Power Manager initialization, use NULL value.
callbacksNumber	Number of registered callbacks. Size of callbacksPtr array.

Returns: An error code or kPowerManagerSuccess.

power_manager_error_code_t POWER_SYS_Deinit ( void )

Returns: An error code or kPowerManagerSuccess.

power_manager_error_code_t POWER_SYS_SetMode	(	uint8_t	powerModeIndex,
		power_manager_policy_t	policy
	)

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 kPowerManagerCallbackBefore 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 kPowerManagerCallbackAfter). 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 (kPowerManagerPolicyForcible) or exited (kPowerManagerPolicyAgreement). When mode change is forced, the result of the before switch notifications are ignored. If agreement is required, if any callback returns an error code then further notifications before switch notifications are cancelled and all already notified callbacks are re-invoked with kPowerManagerCallbackAfter set as callback type parameter. The index of the callback which returned error code during pre-switch notifications is stored (any error codes during callbacks re-invocation are ignored) and POWER_SYS_GetErrorCallback() can be used to get it. Regardless of the policies, if any callback returned an error code, an error code denoting in which phase the error occurred is returned when POWER_SYS_SetMode() exits. It is possible to enter any mode supported by the processor. Refer to the chip reference manual for list of available power modes. If it is necessary to switch into intermediate power mode prior to entering 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

powerModeIndex	Requested power mode represented as an index into array of user-defined power mode configurations passed to the POWER_SYS_Init().
policy	Transaction policy

Returns: An error code or kPowerManagerSuccess.

power_manager_error_code_t POWER_SYS_GetLastMode ( uint8_t * powerModeIndexPtr )

This function returns index of power mode which was set using POWER_SYS_SetMode() as the last one. If the power mode was entered even though some of the registered callback 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 kPowerManagerError value.

Parameters

powerModeIndexPtr Power 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 kPowerManagerSuccess.

power_manager_error_code_t POWER_SYS_GetLastModeConfig ( power_manager_user_config_t const ** powerModePtr )

This function returns reference to configuration structure which was set using POWER_SYS_SetMode() as the last one. If the current power mode was entered even though some of the registered callback 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 kPowerManagerError value.

Parameters

powerModePtr Pointer to power mode configuration structure of power mode set as last one.

Returns: An error code or kPowerManagerSuccess.

power_manager_modes_t POWER_SYS_GetCurrentMode ( void )

This function reads hardware settings and returns currently running power mode. Generally, this function can return only kPowerManagerRun, kPowerManagerVlpr or kPowerManagerHsrun value.

Returns: Currently used run power mode.

uint8_t POWER_SYS_GetErrorCallbackIndex ( void )

This function returns index of the last callback that failed during the power mode switch while the last POWER_SYS_SetMode() was called. If the last POWER_SYS_SetMode() call ended successfully value equal to callbacks number is returned. Returned value represents index in the array of static call-backs.

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

power_manager_callback_user_config_t* POWER_SYS_GetErrorCallback ( void )

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

Returns: Pointer to the callback configuration which returns error.

bool POWER_SYS_GetVeryLowPowerModeStatus ( void )

This function is used to detect whether very low power mode is running.

Returns: Returns true if processor runs in very low power mode, otherwise false.

bool POWER_SYS_GetLowLeakageWakeupResetStatus ( void )

This function is used to check that processor exited low leakage power mode through reset.

Returns: Returns true if processor was reset by low leakage wake up, otherwise false.

bool POWER_SYS_GetAckIsolation ( void )

This function is used to check certain peripherals and the I/O pads are in a latched state as a result of having been in a VLLS mode.

After recovery from VLLS, the LLWU continues to detect wake-up events until the user has acknowledged the wake-up via POWER_SYS_ClearAckIsolation()

Returns: Returns true if ACK isolation is set.

void POWER_SYS_ClearAckIsolation ( void )

This function clears the ACK Isolation flag. Clearing releases the I/O pads and certain peripherals to their normal run mode state.

After recovery from VLLS, the LLWU continues to detect wake-up events until the user has acknowledged the wake-up via POWER_SYS_ClearAckIsolation()

Overview

Modules

Data Structures

Typedefs

Enumerations

Functions

Data Structure Documentation

Data Fields

Data Fields

Field Documentation

Data Fields

Field Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation