# PM_[Append|Prepend|Insert]*ExitCallback

## Syntax

      #include <twl/spi.h>

      void PM_AppendPreExitCallback( PMExitCallbackInfo info );
      void PM_PrependPreExitCallback( PMExitCallbackInfo info );
      void PM_InsertPreExitCallback( PMExitCallbackInfo info, int priority );

      void PM_AppendPostExitCallback( PMExitCallbackInfo info );
      void PM_PrependPostExitCallback( PMExitCallbackInfo info );
      void PM_InsertPostExitCallback( PMExitCallbackInfo info, int priority );

      typedef void (*PMExitCallback)( void* );

## Arguments

info | Pointer to a structure that contains the information of the exit callback to add.
priority | Priority level. Used to determine the registration order in the callback list. Takes a value from 0 to 255.

## Return Values

None.

## Description

Adds an exit callback. This function is exclusive to TWL mode.

Adds an exit callback to be invoked when the hardware detects something that will cause either hardware reset or power-off (such as when the Power Button is pressed, or the remaining battery life is depleted). These situations are actually detected by the ARM7. The ARM9 invokes the callbacks configured here when it receives a notification from the ARM7. The ARM9 then tells the ARM7 that exit preparations are complete, and the power is turned OFF or the hardware is reset. The exit callbacks must return promptly.

The callbacks are `void` functions that take a single `void*` argument.

Multiple callbacks can be registered and are connected by a list. There are two callback lists: one that performs pre-processing and one that performs post-processing. Each callback has a priority, and is ordered in the list and run in ascending priority order.

Use the `PM_SetExitCallbackInfo` function to register the callback and callback argument in the exit callback information structure pointed to by info. This function registers info on the callback list. If info has already been added to the list, this function returns without doing anything. When a callback is registered on the callback list, it is ordered according to the callback priority given by priority. The value of priority can range from -255 (`PM_CALLBACK_PRIORITY_MIN`) to 255 (`PM_CALLBACK_PRIORITY_MAX`).

The `PM_AppendPreExitCallback` function registers a callback at the end of the pre-processing list, giving it a priority of 255.

The `PM_PrependPreExitCallback` function registers a callback at the start of the pre-processing list , giving it a priority of -255.

The `PM_InsertPreExitCallback` function registers a callback in the pre-processing list and gives it the specified priority.

The `PM_AppendPostExitCallback` function registers a callback at the end of the post-processing list, giving it a priority of 255.

The `PM_PrependPostExitCallback` function registers a callback at the start of the post-processing list, giving it a priority of -255.

The `PM_InsertPostExitCallback` function registers a callback in the post-processing list and gives it the specified priority.

When a callback is registered using an "`Append`" function, it is placed after any other existing callbacks that also have a priority of 255. When a callback is registered using a "`Prepend`" function, it is placed before any other existing callbacks that also have a priority of 0. When a callback is registered using an "`Insert`" function, it is placed after any other existing callbacks that have the same priority. In other words, specifying a priority of 255 to an `Insert` function causes it to behave identically to an `Append` function. However, specifying a priority of -255 to an `Insert` function does not result in the same behavior as a `Prepend` function.

Causes for the Exit Callback

The `PM_GetExitFactor` function can be used in an exit callback to determine what caused it to be invoked.

Callbacks Registered with the Post-processing List

Callbacks registered with this list are called from an interrupt handler or an application thread, depending on the system state. They are called from an interrupt handler if the system has been configured to run all processing automatically when it detects something that will cause hardware reset or power-off. They are called by the application from the `PM_ReadyToExit` function if `PM_SetAutoExit( FALSE )` has been run to disable automatic processing.

When the application has called the `PM_ForceToResetHardware` or `PM_ForceToPowerOff*` functions, callbacks registered with the post-processing list are invoked, but callbacks registered with the pre-processing list are not.

Callback Removal

Call the `PM_DeletePreExitCallback` or `PM_DeletePostExitCallback` functions to remove callbacks from the lists.

## See Also

`PM_SetExitCallbackInfo`
`PM_GetExitFactor`
`PM_DeletePreExitCallback`
`PM_DeletePostExitCallback`
`PM_SetAutoExit`
`PM_ReadyToExit`

## Revision History

2008/07/15 Changed the lowest priority value available to developers from 0 to -255.
2008/06/11 Added "insert" functions.
2008/03/13 Added a clarification about callbacks in the post-processing list.
2008/02/07 Initial version.

CONFIDENTIAL