# SLEEP
[EM_Drivers]

Energy Modes management driver. More...

Collaboration diagram for SLEEP:

## Defines
#define | SLEEP_EM4_WAKEUP_CALLBACK_ENABLED true
| Enable/disable the HW block for protecting accidental setting of low energy modes (recommended to be set to true).
#define | SLEEP_LOWEST_ENERGY_MODE_DEFAULT sleepEM3
| Configure default lowest energy mode that the system can be set to.
## Typedefs
typedef void(* | SLEEP_CbFuncPtr_t )(SLEEP_EnergyMode_t)
| Callback function pointer type.
## Enumerations
enum | SLEEP_EnergyMode_t { sleepEM0 = 0, sleepEM1 = 1, sleepEM2 = 2, sleepEM3 = 3, sleepEM4 = 4 }
| Status value used for showing the Energy Mode the device is currently in. More...
## Functions
void | SLEEP_Init (SLEEP_CbFuncPtr_t pSleepCb, SLEEP_CbFuncPtr_t pWakeUpCb)
| Initialize the Sleep module.
SLEEP_EnergyMode_t | SLEEP_Sleep (void)
| Sets the system to sleep into the lowest possible energy mode.
void | SLEEP_ForceSleepInEM4 (void)
| Force the device to go to EM4 without doing any checks.
void | SLEEP_SleepBlockBegin (SLEEP_EnergyMode_t eMode)
| Begin sleep block in the requested energy mode.
void | SLEEP_SleepBlockEnd (SLEEP_EnergyMode_t eMode)
| End sleep block in the requested energy mode.

## Detailed Description

Energy Modes management driver.

This is a energy modes management module consisting of sleep.c and sleep.h source files. The main purpose of the module is to ease energy optimization with a simple API. The module allows the system to always sleep in the lowest possible energy mode. Users could set up callbacks that are being called before and after each and every sleep. A counting semaphore is available for each low energy mode (EM1/EM2/EM3) to protect certain system states from being corrupted. This semaphore has limit set to maximum 255 locks.

## Define Documentation

#define SLEEP_EM4_WAKEUP_CALLBACK_ENABLED true

Enable/disable the HW block for protecting accidental setting of low energy modes (recommended to be set to true).

Enable/disable calling wakeup callback after EM4 reset.

Definition at line 100 of file sleep.h.

#define SLEEP_LOWEST_ENERGY_MODE_DEFAULT sleepEM3

Configure default lowest energy mode that the system can be set to.

Possible values:

- sleepEM1 - EM1, the CPU core is turned off.
- sleepEM2 - EM2, like EM1 + all HF clocks are turned off, LF clocks are on.
- sleepEM3 - EM3, like EM2 + LF clocks are off, RAM retention, GPIO and ACMP interrupt is on.

Definition at line 110 of file sleep.h.

## Typedef Documentation

typedef void(* SLEEP_CbFuncPtr_t)(SLEEP_EnergyMode_t)

Callback function pointer type.

Definition at line 137 of file sleep.h.

## Enumeration Type Documentation

enum SLEEP_EnergyMode_t

Status value used for showing the Energy Mode the device is currently in.

Enumerator:

  sleepEM0 | Status value for EM0.
  sleepEM1 | Status value for EM1.
  sleepEM2 | Status value for EM2.
  sleepEM3 | Status value for EM3.
  sleepEM4 | Status value for EM4.

Definition at line 118 of file sleep.h.

## Function Documentation

void SLEEP_ForceSleepInEM4 | ( | void |  | ) |

Force the device to go to EM4 without doing any checks.

This function unblocks the low energy sleep block then goes to EM4.

Note:
  Regular RAM is not retained in EM4 and the wake up causes a reset. If the configuration option SLEEP_EM4_WAKEUP_CALLBACK_ENABLED is set to true, the SLEEP_Init() function checks for the reset cause and calls the EM4 wakeup callback.

Definition at line 238 of file sleep.c.

References sleepEM4.

void SLEEP_Init | ( | SLEEP_CbFuncPtr_t | pSleepCb,
|  | SLEEP_CbFuncPtr_t | pWakeUpCb |
| ) |  |  |

Initialize the Sleep module.

Use this function to initialize the Sleep module, should be called only once! Pointers to sleep and wake-up callback functions shall be provided when calling this function. If SLEEP_EM4_WAKEUP_CALLBACK_ENABLED is set to true, this function checks for the cause of the reset that implicitly called it and calls the wakeup callback if the reset was a wakeup from EM4 (does not work on Gecko MCU).

Parameters:

  `[in]` | pSleepCb | Pointer to the callback function that is being called before the device is going to sleep.
  `[in]` | pWakeUpCb | Pointer to the callback function that is being called after wake up.

Definition at line 156 of file sleep.c.

References sleepEM4.

SLEEP_EnergyMode_t SLEEP_Sleep | ( | void |  | ) |

Sets the system to sleep into the lowest possible energy mode.

This function takes care of the system states protected by the sleep block provided by SLEEP_SleepBlockBegin() / SLEEP_SleepBlockEnd(). It allows the system to go into the lowest possible energy mode that the device can be set into at the time of the call of this function. This function will not go lower than EM3 because leaving EM4 requires resetting MCU. To enter into EM4 call SLEEP_ForceSleepInEM4().

Returns:
  Energy Mode that was entered. Possible values:
  - sleepEM0
  - sleepEM1
  - sleepEM2
  - sleepEM3

Definition at line 202 of file sleep.c.

References sleepEM0, sleepEM1, and sleepEM3.

void SLEEP_SleepBlockBegin | ( | SLEEP_EnergyMode_t | eMode | ) |

Begin sleep block in the requested energy mode.

Blocking a critical system state from a certain energy mode makes sure that the system is not set to that energy mode while the block is not being released. Every SLEEP_SleepBlockBegin() increases the corresponding counter and every SLEEP_SleepBlockEnd() decreases it.

Example:

          SLEEP_SleepBlockBegin(sleepEM2);  // do not allow EM2 or higher
          // do some stuff that requires EM1 at least, like ADC sampling
          SLEEP_SleepBlockEnd(sleepEM2);    // remove restriction for EM2

Note:
  Be aware that there is limit of maximum blocks nesting to 255.

Parameters:

  `[in]` | eMode | Energy mode to begin to block. Possible values: sleepEM1 - Begin to block the system from being set to EM1 (and EM2..4). sleepEM2 - Begin to block the system from being set to EM2 (and EM3/EM4). sleepEM3 - Begin to block the system from being set to EM3 (and EM4).

Definition at line 274 of file sleep.c.

References sleepEM1, sleepEM2, and sleepEM4.

void SLEEP_SleepBlockEnd | ( | SLEEP_EnergyMode_t | eMode | ) |

End sleep block in the requested energy mode.

Release restriction for entering certain energy mode. Every call of this function reduce blocking counter by 1. Once the counter for specific energy mode is 0 and all counters for lower energy modes are 0 as well, using particular energy mode is allowed. Every SLEEP_SleepBlockBegin() increases the corresponding counter and every SLEEP_SleepBlockEnd() decreases it.

Example:

          // at start all energy modes are allowed
          SLEEP_SleepBlockBegin(sleepEM2); // EM2, EM3, EM4 are blocked
          SLEEP_SleepBlockBegin(sleepEM1); // EM1, EM2, EM3, EM4 are blocked
          SLEEP_SleepBlockBegin(sleepEM1); // EM1, EM2, EM3, EM4 are blocked
          SLEEP_SleepBlockEnd(sleepEM2);   // still EM1, EM2, EM3, EM4 are blocked
          SLEEP_SleepBlockEnd(sleepEM1);   // still EM1, EM2, EM3, EM4 are blocked
          SLEEP_SleepBlockEnd(sleepEM1);   // all energy modes are allowed now

Parameters:

  `[in]` | eMode | Energy mode to end to block. Possible values: sleepEM1 - End to block the system from being set to EM1 (and EM2..4). sleepEM2 - End to block the system from being set to EM2 (and EM3/EM4). sleepEM3 - End to block the system from being set to EM3 (and EM4).

Definition at line 318 of file sleep.c.

References sleepEM1, sleepEM2, and sleepEM4.