Kinetis SDK v.2.0 API Reference Manual  Rev. 0
Freescale Semiconductor, Inc.
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Notification Framework

Overview

This section describes the programming interface of the Notifier driver.

Notifier Overview

The Notifier provides a configuration dynamic change service. Based on this service, applications can switch between pre-defined configurations. The Notifier enables drivers and applications to register callback functions to this framework. Each time that the configuration is changed, drivers and applications receive a notification and change their settings. To simplify, the Notifier only supports the static callback registration. This means that, for applications, all callback functions are collected into a static table and passed to the Notifier.

The configuration transition includes 3 steps:

  1. Before configuration transition, the Notifier sends a "BEFORE" message to the callback table. When this message is received, IP drivers should check whether any current processes can be stopped and stop them. If the processes cannot be stopped, the callback function returns an error.

The Notifier supports two types of transition policies, a graceful policy and a forceful policy. When the graceful policy is used, if some callbacks return an error while sending "BEFORE" message, the configuration transition stops and the Notifier sends a "RECOVER" message to all drivers that have stopped. Then, these drivers can recover the previous status and continue to work. When the forceful policy is used, drivers are stopped forcefully.

  1. After the "BEFORE" message is processed successfully, the system changes to the new configuration.
  2. After the configuration changes, the Notifier sends an "AFTER" message to the callback table to notify drivers that the configuration transition is finished.

This is an example to use the Notifier in the Power Manager application:

~~~~~{.c}

#include "fsl_notifier.h"

/* Definition of the Power Manager callback 
status_t callback0(notifier_notification_block_t *notify, void *data)
{

    status_t ret = kStatus_Success;

    ...
    ...
    ...

    return ret;
}
/* Definition of the Power Manager user function 
status_t APP_PowerModeSwitch(notifier_user_config_t *targetConfig, void *userData)
{
    ...
    ...
    ...
}
...
...
...
...
...
/* Main function 
int main(void)
{
    /* Define a notifier handle 
    notifier_handle_t powerModeHandle;

    /* Callback configuration 
    user_callback_data_t callbackData0;

    notifier_callback_config_t callbackCfg0 = {callback0,
                kNOTIFIER_CallbackBeforeAfter,
                (void *)&callbackData0};

    notifier_callback_config_t callbacks[] = {callbackCfg0};

    /* Power mode configurations 
    power_user_config_t vlprConfig;
    power_user_config_t stopConfig;

    notifier_user_config_t *powerConfigs[] = {&vlprConfig, &stopConfig};

    /* Definition of a transition to and out the power modes 
    vlprConfig.mode = kAPP_PowerModeVlpr;
    vlprConfig.enableLowPowerWakeUpOnInterrupt = false;

    stopConfig = vlprConfig;
    stopConfig.mode = kAPP_PowerModeStop;

    /* Create Notifier handle 
    NOTIFIER_CreateHandle(&powerModeHandle, powerConfigs, 2U, callbacks, 1U, APP_PowerModeSwitch, NULL);
    ...
    ...
    /* Power mode switch 
    NOTIFIER_switchConfig(&powerModeHandle, targetConfigIndex, kNOTIFIER_PolicyAgreement);
}

~~~~~{.c}

Data Structures

struct  notifier_notification_block_t
 notification block passed to the registered callback function. More...
 
struct  notifier_callback_config_t
 callback configuration structure More...
 
struct  notifier_handle_t
 Notifier handle structure. More...
 

Typedefs

typedef void notifier_user_config_t
 notifier user configuration type. More...
 
typedef status_t(* notifier_user_function_t )(notifier_user_config_t *targetConfig, void *userData)
 notifier user function prototype User can use this function to execute specific operations in configuration switch. More...
 
typedef status_t(* notifier_callback_t )(notifier_notification_block_t *notify, void *data)
 Callback prototype. More...
 

Enumerations

enum  _notifier_status {
  kStatus_NOTIFIER_ErrorNotificationBefore,
  kStatus_NOTIFIER_ErrorNotificationAfter
}
 Notifier error codes. More...
 
enum  notifier_policy_t {
  kNOTIFIER_PolicyAgreement,
  kNOTIFIER_PolicyForcible
}
 Notifier policies. More...
 
enum  notifier_notification_type_t {
  kNOTIFIER_NotifyRecover = 0x00U,
  kNOTIFIER_NotifyBefore = 0x01U,
  kNOTIFIER_NotifyAfter = 0x02U
}
 Notification type. More...
 
enum  notifier_callback_type_t {
  kNOTIFIER_CallbackBefore = 0x01U,
  kNOTIFIER_CallbackAfter = 0x02U,
  kNOTIFIER_CallbackBeforeAfter = 0x03U
}
 The callback type, indicates what kinds of notification the callback handles. More...
 

Functions

status_t NOTIFIER_CreateHandle (notifier_handle_t *notifierHandle, notifier_user_config_t **configs, uint8_t configsNumber, notifier_callback_config_t *callbacks, uint8_t callbacksNumber, notifier_user_function_t userFunction, void *userData)
 Create Notifier handle. More...
 
status_t NOTIFIER_SwitchConfig (notifier_handle_t *notifierHandle, uint8_t configIndex, notifier_policy_t policy)
 Switch configuration according to a pre-defined structure. More...
 
uint8_t NOTIFIER_GetErrorCallbackIndex (notifier_handle_t *notifierHandle)
 This function returns the last failed notification callback. More...
 

Data Structure Documentation

struct notifier_notification_block_t

Data Fields

notifier_user_config_ttargetConfig
 Pointer to target configuration. More...
 
notifier_policy_t policy
 Configure transition policy. More...
 
notifier_notification_type_t notifyType
 Configure notification type. More...
 

Field Documentation

notifier_user_config_t* notifier_notification_block_t::targetConfig
notifier_policy_t notifier_notification_block_t::policy
notifier_notification_type_t notifier_notification_block_t::notifyType
struct notifier_callback_config_t

This structure holds configuration of callbacks. 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.

Data Fields

notifier_callback_t callback
 Pointer to the callback function. More...
 
notifier_callback_type_t callbackType
 Callback type. More...
 
void * callbackData
 Pointer to the data passed to the callback. More...
 

Field Documentation

notifier_callback_t notifier_callback_config_t::callback
notifier_callback_type_t notifier_callback_config_t::callbackType
void* notifier_callback_config_t::callbackData
struct notifier_handle_t

Notifier handle structure. Contains data necessary for Notifier proper function. Stores references to registered configurations, callbacks, information about their numbers, user function, user data and other internal data. NOTIFIER_CreateHandle() must be called to intialize this handle.

Data Fields

notifier_user_config_t ** configsTable
 Pointer to configure table. More...
 
uint8_t configsNumber
 Number of configurations. More...
 
notifier_callback_config_tcallbacksTable
 Pointer to callback table. More...
 
uint8_t callbacksNumber
 Maximum number of callback configurations. More...
 
uint8_t errorCallbackIndex
 Index of callback returns error. More...
 
uint8_t currentConfigIndex
 Index of current configuration. More...
 
notifier_user_function_t userFunction
 user function. More...
 
void * userData
 user data passed to user function. More...
 

Field Documentation

notifier_user_config_t** notifier_handle_t::configsTable
uint8_t notifier_handle_t::configsNumber
notifier_callback_config_t* notifier_handle_t::callbacksTable
uint8_t notifier_handle_t::callbacksNumber
uint8_t notifier_handle_t::errorCallbackIndex
uint8_t notifier_handle_t::currentConfigIndex
notifier_user_function_t notifier_handle_t::userFunction
void* notifier_handle_t::userData

Typedef Documentation

typedef void notifier_user_config_t

Reference of user defined configuration is stored in an array, notifer switch between these configurations based on this array.

typedef status_t(* notifier_user_function_t)(notifier_user_config_t *targetConfig, void *userData)

Before and after this function execution, different notification will be sent to registered callbacks. If this function returns any error code, NOTIFIER_SwitchConfig() will exit.

Parameters
targetConfigtarget Configuration.
userDataRefers to other specific data passed to user function.
Returns
An error code or kStatus_Success.
typedef status_t(* notifier_callback_t)(notifier_notification_block_t *notify, void *data)

Declaration of callback. It is common for registered callbacks. Reference to function of this type is part of notifier_callback_config_t callback configuration structure. Depending on callback type, function of this prototype is called (see NOTIFIER_SwitchConfig()) before configuration switch, after it or in both cases to notify about the switch progress (see notifier_callback_type_t). When called, type of the notification is passed as parameter along with reference to the target configuration structure (see notifier_notification_block_t) and any data passed during the callback registration. When notified before configuration switch, depending on the configuration switch policy (see notifier_policy_t) the callback may deny the execution of user function by returning any error code different from kStatus_Success (see NOTIFIER_SwitchConfig()).

Parameters
notifyNotification block.
dataCallback 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 kStatus_Success.

Enumeration Type Documentation

Used as return value of Notifier functions.

Enumerator
kStatus_NOTIFIER_ErrorNotificationBefore 

Error occurs during send "BEFORE" notification.

kStatus_NOTIFIER_ErrorNotificationAfter 

Error occurs during send "AFTER" notification.

Defines whether user function execution is forced or not. For kNOTIFIER_PolicyForcible, the user function is executed regardless of the callback results, while kNOTIFIER_PolicyAgreement policy is used to exit NOTIFIER_SwitchConfig() when any of the callbacks returns error code. See also NOTIFIER_SwitchConfig() description.

Enumerator
kNOTIFIER_PolicyAgreement 

NOTIFIER_SwitchConfig() method is exited when any of the callbacks returns error code.

kNOTIFIER_PolicyForcible 

user function is executed regardless of the results.

Used to notify registered callbacks

Enumerator
kNOTIFIER_NotifyRecover 

Notify IP to recover to previous work state.

kNOTIFIER_NotifyBefore 

Notify IP that configuration setting is going to change.

kNOTIFIER_NotifyAfter 

Notify IP that configuration setting has been changed.

Used in the callback configuration structure (notifier_callback_config_t) to specify when the registered callback is called during configuration switch initiated by NOTIFIER_SwitchConfig(). Callback can be invoked in following situations:

  • before the configuration switch (Callback return value can affect NOTIFIER_SwitchConfig() execution. Refer to the NOTIFIER_SwitchConfig() and notifier_policy_t documentation).
  • after unsuccessful attempt to switch configuration
  • after sucecessful configuration switch
Enumerator
kNOTIFIER_CallbackBefore 

Callback handles BEFORE notification.

kNOTIFIER_CallbackAfter 

Callback handles AFTER notification.

kNOTIFIER_CallbackBeforeAfter 

Callback handles BEFORE and AFTER notification.

Function Documentation

status_t NOTIFIER_CreateHandle ( notifier_handle_t notifierHandle,
notifier_user_config_t **  configs,
uint8_t  configsNumber,
notifier_callback_config_t callbacks,
uint8_t  callbacksNumber,
notifier_user_function_t  userFunction,
void *  userData 
)
Parameters
notifierHandleA pointer to notifier handle
configsA pointer to an array with references to all configurations which is handled by the Notifier.
configsNumberNumber of configurations. Size of configs array.
callbacksA pointer to an array of callback configurations. If there are no callbacks to register during Notifier initialization, use NULL value.
callbacksNumberNumber of registered callbacks. Size of callbacks array.
userFunctionuser function.
userDatauser data passed to user function.
Returns
An error code or kStatus_Success.
status_t NOTIFIER_SwitchConfig ( notifier_handle_t notifierHandle,
uint8_t  configIndex,
notifier_policy_t  policy 
)

This function sets the system to the target configuration. Before transition, the Notifier sends notifications to all callbacks registered to the callback table. Callbacks are invoked in the following order: All registered callbacks are notified ordered by index in the callbacks array. The same order is used for before and after switch notifications. The notifications before the configuration switch can be used to obtain confirmation about the change from registered callbacks. If any registered callback denies the configuration change, further execution of this function depends on the notifier policy: the configuration change is either forced (kNOTIFIER_PolicyForcible) or exited (kNOTIFIER_PolicyAgreement). When configuration 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 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 NOTIFIER_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 NOTIFIER_SwitchConfig() exits.

Parameters
notifierHandlepointer to notifier handle
configIndexIndex of the target configuration.
policyTransaction policy, kNOTIFIER_PolicyAgreement or kNOTIFIER_PolicyForcible.
Returns
An error code or kStatus_Success.
uint8_t NOTIFIER_GetErrorCallbackIndex ( notifier_handle_t notifierHandle)

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

Parameters
notifierHandlepointer to notifier handle
Returns
Callback index of last failed callback or value equal to callbacks count.