# PM_GoSleepMode

## C Specification

      #include <nitro/spi.h>

      void PM_GoSleepMode( PMWakeUpTrigger trigger, PMLogic logic, u16 keyPattern );

## Arguments

trigger | The trigger to recover from sleep state.
logic | The key combination logic when recovering with a key interrupt.
keyPattern | The key when recovering with a key interrupt.

## Return Values

None.

## Description

This function changes both ARM9 and ARM7 to sleep state. The function sends a sleep command to ARM7. The ARM9 itself also enters halt state with `OS_Halt()`. trigger is a `PMWakeUpTrigger` enum type, and specifies a trigger to recover from the sleep state. The trigger can specify multiple items by obtaining a logical OR. The following items can be specified.

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 | Generate a cartidge interrupt or remove the cartridge

(CAUTION) Recovery from sleep mode by removing a Game Pak is prohibited in the Guidelines.

> Example: When recovering from sleep mode by opening the cover or removing the Game Card, use `PM_GoSleepMode( PM_TRIGGER_COVER_OPEN | PM_TRIGGER_CARD | PM_TRIGGER_CARTRIDGE );`

In terms of the hardware specification, these recovery triggers are level triggers, not edge triggers. For example, strictly speaking, `PM_TRIGGER_CARTRIDGE` does not detect when a Game Pak is removed, but rather that no Game Pak is inserted, and then returns. (More specifically, it detects the status of the `OS_IE_CARTRIDGE_IREQ` interrupt in operation.) Therefore, if you try to enter sleep mode with `PM_TRIGGER_CARTRIDGE` as the recovery trigger while no Game Pak is inserted (already removed), it recovers immediately. However, Game Card and Game Pak interrupts check (within the function) whether a Game Card or Game Pak is actually inserted. As a result, when you try to insert a recovery trigger while no Game Card or Game Pak is inserted, that trigger is discarded.

When you include key interrupt in recovery trigger, specify the keys to trigger recovery and their combination logic with `keyPattern` and `logic`. The combination logic is either `PM_PAD_LOGIC_AND` (when input is from all keys), or `PM_PAD_LOGIC_OR` (when input is from any key). For example, to make recovery possible only by pressing the A button and START at the same time:

`PM_GoSleepMode( PM_TRIGGER_KEY, PM_PAD_LOGIC_AND, PAD_BUTTON_A | PAD_BUTTON_START );`

To make recovery possible by pushing either the A button or START:

`PM_GoSleepMode( PM_TRIGGER_KEY, PM_PAD_LOGIC_OR, PAD_BUTTON_A | PAD_BUTTON_START );`

When you do not include a key interrupt in the recovery trigger, specifications for `keyPattern` and `logic` are meaningless. Also, when there is only one key assignment, combination logic may be either `PM_PAD_LOGIC_AND` or `PM_PAD_LOGIC_OR`.

Before you use this function, initialize the PM library by using the `PM_Init()` function. The `PM_Init()` function has to be called only once. Also, when you call `OS_Init()`, there is no need to call `PM_Init()` separately since it is called from within `OS_Init()`.)

Callback Functions

It is possible to set callback functions to be called before entering sleep mode and after awakening from sleep mode. The callback function that is called when entering sleep mode is called at the beginning of `PM_GoSleepMode()`, and the function that is called after awakening from sleep mode is called at the end of `PM_GoSleepMode()`. This is equivalent to calling these functions before and after `PM_GoSleepMode()`.

The callback function is a `PMSleepCallback` type (a function type that retains one `void*` argument and no return values), and multiple functions can be registered. The registered functions are called in order, so pay special attention when registering functions that must be performed in a specific order.

When registering a callback, specify with the callback function and the callback information including the arguments. For more information, see `PM_AppendPreSleepCallback()`.

## See Also

`PM_Init,
PM_AppendPreSleepCallback, PM_PrependPreSleepCallback,
PM_AppendPostSleepCallback, PM_PrependPostSleepCallback,
PM_DeletePreSleepCallback, PM_DeletePostSleepCallback,`
`PM_SetSleepCallbackInfo`

## Revision History

05/16/2006 Changed the description about Game Pak removal as a trigger for recovery from sleep mode
09/14/2005 Changed `PM_SetSleepCallback` to `PM_SetSleepCallbackInfo`
03/08/2005 Standardized wording.
10/06/2004 Corrected callbacks to allow registration of multiple callbacks.
10/05/2004 Added description regarding callbacks.
08/07/2004 Separated combination logic in Arguments.
08/02/2004 Initial version.

CONFIDENTIAL