Description

Sleep Management Driver (DEPRECATED)

Introduction

Warning: This driver is deprecated and will be removed in a later release. Use the Power Manager service instead. For more information about Power Manager, see Services section.

Note: See AN1358: Migrating from Sleep Driver to Power Manager for information on how to migrate from Sleep Driver to Power Manager.

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

To enter a low energy mode, an application 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.

The following is an example of the sleep driver initialization and how it can be used to enter EM2.

       
        SLEEP_Init_t
       
       sleepConfig = {0};
      
        SLEEP_InitEx
       
       (&sleepConfig);
      
        SLEEP_SleepBlockBegin
       
       (
       
        sleepEM3
       
       );
       
        // Block EM3 entry
       
        SLEEP_Sleep
       
       ();
      
        SLEEP_SleepBlockEnd
       
       (
       
        sleepEM3
       
       );

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.

The following is an example of sleep and wakeup callbacks usage.

       
        static
       
        bool
       
       beforeSleep(
       
        SLEEP_EnergyMode_t
       
       mode)
      
       {
      
       printf(
       
        "sleep\n"
       
       );
      
        return
       
        true
       
       ;
      
       }
      
        static
       
        void
       
       afterWakeup(
       
        SLEEP_EnergyMode_t
       
       mode)
      
       {
      
       printf(
       
        "wakeup\n"
       
       );
      
       (void) mode;
      
       }
      
        void
       
       main(
       
        void
       
       )
      
       {
      
        SLEEP_Init_t
       
       sleepConfig = {
      
       .
       
        sleepCallback
       
       = beforeSleep,
      
       .wakeupCallback = afterWakeup
      
       };
      
        SLEEP_InitEx
       
       (&sleepConfig);
      
        SLEEP_SleepBlockBegin
       
       (
       
        sleepEM3
       
       );
       
        // Block EM3 entry
       
        while
       
       (
       
        true
       
       ) {
      
        SLEEP_Sleep
       
       ();
      
       }
      
        SLEEP_SleepBlockEnd
       
       (
       
        sleepEM3
       
       );
      
       }

Data Structures
struct	SLEEP_Init_t
	Initialization structure for the sleep driver.

Functions
void	SLEEP_Init ( SLEEP_CbFuncPtr_t pSleepCb, SLEEP_CbFuncPtr_t pWakeUpCb)
	Initialize the Sleep module.

void	SLEEP_InitEx (const SLEEP_Init_t *init)
	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.

SLEEP_EnergyMode_t	SLEEP_LowestEnergyModeGet (void)
	Gets the lowest energy mode that the system is allowed to be set to.

Macros
#define	SLEEP_FLAG_NONE 0x0
	This flag is returned from the restoreCallback function to signal that the sleep driver should continue as normal.

#define	SLEEP_FLAG_NO_CLOCK_RESTORE 0x1u
	This flag is returned from the restoreCallback function to signal to the sleep driver that HF clocks should not be restored and that the sleep driver should go right back to sleep again.

#define	SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED false
	Enable/disable the HW block for protecting accidental setting of low energy modes.

#define	SLEEP_EM4_WAKEUP_CALLBACK_ENABLED true
	Enable/disable calling wakeup callback after EM4 reset.

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

Function Documentation

◆ SLEEP_Init()

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.

◆ SLEEP_InitEx()

void SLEEP_InitEx ( const SLEEP_Init_t * init )

Initialize the Sleep module.

Use this function to initialize the Sleep module.

Parameters

[in] init Pointer to the sleep module init structure containing callback function and configuration parameters.

◆ SLEEP_Sleep()

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

◆ SLEEP_ForceSleepInEM4()

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.

◆ SLEEP_SleepBlockBegin()

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:

sleepEM2 - Begin to block the system from being set to EM2/EM3/EM4.
sleepEM3 - Begin to block the system from being set to EM3/EM4.

◆ SLEEP_SleepBlockEnd()

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
         
         (
         
          sleepEM3
         
         );
         
          // EM3 and EM4 are blocked
         
          SLEEP_SleepBlockBegin
         
         (
         
          sleepEM2
         
         );
         
          // EM2, EM3 and EM4 are blocked
         
          SLEEP_SleepBlockBegin
         
         (
         
          sleepEM2
         
         );
         
          // EM2, EM3 and EM4 are blocked
         
          SLEEP_SleepBlockEnd
         
         (
         
          sleepEM3
         
         );
         
          // EM2, EM3 and EM4 are still blocked
         
          SLEEP_SleepBlockEnd
         
         (
         
          sleepEM2
         
         );
         
          // EM2, EM3 and EM4 are still blocked
         
          SLEEP_SleepBlockEnd
         
         (
         
          sleepEM2
         
         );
         
          // all energy modes are allowed now

Parameters

[in]


              eMode

Energy mode to end to block. Possible values:

sleepEM2 - End to block the system from being set to EM2/EM3/EM4.
sleepEM3 - End to block the system from being set to EM3/EM4.

◆ SLEEP_LowestEnergyModeGet()

SLEEP_EnergyMode_t SLEEP_LowestEnergyModeGet ( void )

Gets the lowest energy mode that the system is allowed to be set to.

This function uses the low energy mode block counters to determine the lowest possible that the system is allowed to be set to.

Returns

Lowest energy mode that the system can be set to. Possible values:

sleepEM1
sleepEM2
sleepEM3

Macro Definition Documentation

◆ SLEEP_FLAG_NONE

#define SLEEP_FLAG_NONE 0x0

This flag is returned from the restoreCallback function to signal that the sleep driver should continue as normal.

◆ SLEEP_FLAG_NO_CLOCK_RESTORE

#define SLEEP_FLAG_NO_CLOCK_RESTORE 0x1u

This flag is returned from the restoreCallback function to signal to the sleep driver that HF clocks should not be restored and that the sleep driver should go right back to sleep again.

◆ SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED

#define SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED false

Enable/disable the HW block for protecting accidental setting of low energy modes.

Note that some devices do not support blocking energy mode entry in hardware, on these devices SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED will have no effect.

◆ SLEEP_EM4_WAKEUP_CALLBACK_ENABLED

#define SLEEP_EM4_WAKEUP_CALLBACK_ENABLED true

Enable/disable calling wakeup callback after EM4 reset.

◆ SLEEP_LOWEST_ENERGY_MODE_DEFAULT

#define SLEEP_LOWEST_ENERGY_MODE_DEFAULT sleepEM3

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

Possible values:

sleepEM2 - EM2, CPU core is turned off, 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.

Typedef Documentation

◆ SLEEP_CbFuncPtr_t

typedef void(* SLEEP_CbFuncPtr_t) ( SLEEP_EnergyMode_t )

Callback function pointer type.

Enumeration Type Documentation

◆ SLEEP_EnergyMode_t

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.

SLEEP - Sleep Driver

Description

Introduction

Sleep and Wakeup Events/Callbacks

Data Structures

Functions

Macros

Typedefs

Enumerations

Function Documentation

◆ SLEEP_Init()

◆ SLEEP_InitEx()

◆ SLEEP_Sleep()

◆ SLEEP_ForceSleepInEM4()

◆ SLEEP_SleepBlockBegin()

◆ SLEEP_SleepBlockEnd()

◆ SLEEP_LowestEnergyModeGet()

Macro Definition Documentation

◆ SLEEP_FLAG_NONE

◆ SLEEP_FLAG_NO_CLOCK_RESTORE

◆ SLEEP_HW_LOW_ENERGY_BLOCK_ENABLED

◆ SLEEP_EM4_WAKEUP_CALLBACK_ENABLED

◆ SLEEP_LOWEST_ENERGY_MODE_DEFAULT

Typedef Documentation

◆ SLEEP_CbFuncPtr_t

Enumeration Type Documentation

◆ SLEEP_EnergyMode_t