SLEEPEMDRV

Detailed Description

Sleep management driver.

Energy Modes Management Driver.

Introduction

This is a sleep management module consisting of sleep.c and sleep.h source files. The main purpose of the module is to make it easy for an application to always enter the lowest possible energy mode using a simple API.

The module works by providing an API for defining "sleep blocks" in the application code. A "sleep block" will block the MCU from entering a certain energy mode. A "sleep block" can for instance block EM2 entry because an EM1 only peripheral is in use. These "sleep blocks" are created by the calls to SLEEP_SleepBlockBegin() and end with SLEEP_SleepBlockEnd().

When an application wants to enter a low energy mode it can call SLEEP_Sleep() to enter the lowest possible energy mode. This module will use the "sleep blocks" to figure out the lowest possible energy mode.

Here is an example of how the sleep driver is initialized and how it can be used to enter EM2.

Sleep and Wakeup Events/Callbacks

This module also provides a way to add application callbacks to notify the application that the MCU is entering sleep, or waking up from sleep. These callbacks can be provided to the driver when calling SLEEP_InitEx().

The sleepCallback function is called before entering sleep and the wakeupCallback is called after waking up from sleep. The sleepCallback function has a bool return value. This return value can be used to control if the MCU should really go to sleep or not. Returning true will make the MCU enter the selected energy mode, while returning false will force the sleep driver to return without entering a sleep.

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 (EM2/EM3) to protect certain system states from being corrupted. This semaphore has limit set to maximum 255 locks.

Typedef Documentation

Enumeration Type Documentation

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 176 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.

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.

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().

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.

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:

1 // at start all energy modes are allowed

2 SLEEP_SleepBlockBegin(sleepEM3); // EM3 and EM4 are blocked

3 SLEEP_SleepBlockBegin(sleepEM2); // EM2, EM3 and EM4 are blocked

4 SLEEP_SleepBlockBegin(sleepEM2); // EM2, EM3 and EM4 are blocked

5 SLEEP_SleepBlockEnd(sleepEM3); // EM2, EM3 and EM4 are still blocked

6 SLEEP_SleepBlockEnd(sleepEM2); // EM2, EM3 and EM4 are still blocked