# Sleep: Overview

## Description

To conserve power, the TWL system can enter sleep mode, separate from the normal (active) mode. Normally, games are created to enter sleep mode when the cover is closed and to recover from sleep mode when the cover is opened. This is not a hardware feature. The application detects that the cover was closed and calls a function to put the system to sleep. This document describes sleep-related functions.

## Causes for Sleep Mode

Call the `PM_GoSleepMode` function to enter sleep mode.

You can specify the following causes for recovery from sleep mode with this command. You can specify several of these items by taking the logical OR of their values. See the `PM_GoSleepMode` function for more information.

Platform | Value | Cause of recovery
--- | --- | ---
| ``PM_TRIGGER_KEY`` | A key interrupt
| `PM_TRIGGER_RTC_ALARM` | An RTC alarm interrupt
| `PM_TRIGGER_COVER_OPEN` | Opening the cover
| `PM_TRIGGER_CARD` | A card interrupt or Game Card removal
| `PM_TRIGGER_CARTRIDGE` (Note 1) | A Game Pak interrupt or remove the Game Pak
| `PM_TRIGGER_SDIO` | SDIO interrupt

Note 1: Waking from sleep upon removal of a Game Pak is prohibited by the programming guidelines.

## Sleep Callback List

The sleep callback is defined as follows:
`typedef void (*PMGenCallback) (void *);`
It is a `void` function that takes a single `void*` argument.

The callback invoked immediately after entering sleep mode and the callback invoked immediately after recovering from sleep mode are each stored internally in a list. These are called the pre-sleep and post-sleep callbacks.

## Sleep Callback Registration

Callbacks have configurable priority levels. Applications can use priorities ranging from -255 (`PM_CALLBACK_PRIORITY_MIN`) to 255 (`PM_CALLBACK_PRIORITY_MAX`). The system (such as the SDK library and middleware) can use priorities ranging from -65,535 (`PM_CALLBACK_PRIORITY_SYSMIN`) to 65,535 (`PM_CALLBACK_PRIORITY_SYSMAX`). These priorities are used only to determine the order of the callback list. Items having smaller values are placed closer to the start of the list.

Use the `PM_SetSleepCallbackInfo` function to configure a callback function and its arguments in a callback information structure, and then register that structure to the list.

It can be registered in one of three ways.

- The `PM_PrependPreSleepCallback` and `PM_PrependPostSleepCallback` functions.
  Register in the list at priority level -255. If there is already a registered callback with a priority of -255, the new callback will be registered in front of it.
  In other words, if you consider it only in terms of the priorities that the application can use, this inserts the new callback at the front of the list.
- The `PM_AppendPreSleepCallback` and `PM_AppendPostSleepCallback` functions.
  Register in the list at priority level 255. If there is already a registered callback with a priority of 255, the new callback will be registered behind it.
  In other words, if you consider it only in terms of the priorities that the application can use, this inserts the new callback at the end of the list.
- The `PM_InsertPreSleepCallback` and `PM_InsertPostSleepCallback` functions.
  Specifies a priority level and registers in the appropriate position. It will be registered behind any other items with the same priority.

These specifications are the same as the exit callback, so see Exit Callback Registration in Overview (Hardware Reset and Shutdown).

## Sleep Callback Removal

The configured callbacks can be removed using the `PM_DeletePreSleepCallback` and `PM_DeletePostSleepCallback` functions.

## Sleep Callback Display (For Debugging)

The `PM_DumpSleepCallback` function is used in debugging to display the list of callbacks. It will not do anything in FINALROM builds.

## Preparations for Powering Down in Sleep Mode

It is difficult to perform the same shutdown processing (make the same guarantees) in sleep mode as in active mode because the overall system state is different. Necessary processing must therefore be done in advance when entering sleep mode, rather than during sleep mode.

Consequently, a sudden power disruption during sleep mode does not have any ill effects on the TWL system. The resulting behavior is the same as if the Power Button was pressed in active mode.

## Registered Sleep Callbacks

Sleep callbacks registered by the SDK run the processes described below.

Pre-sleep callbacks are as follows.

- Stop the Rumble feature (if necessary).
- Put the camera into standby mode.
- Stop the DSP.
- Wait until the process terminates during IIR filter configuration. Restore the speaker volume if a value has been saved by the `SNDEX_SetIgnoreHWVolume` function.
- Flash NAND memory.
- Disconnect from access points and stop any active TWL wireless communications.

Post-sleep callbacks are as follows.

- Synchronize the software clock, which shifted while in sleep mode, with the real-time clock.

## Revision History

2009/02/03 Added a description of the process in SNDEX for the shutdown callback to be registered.
2008/09/13 Initial version.

CONFIDENTIAL