Sleep
RAIL API

These APIs help when putting the system to an EM2/EM3/EM4 sleep states where the high frequency clock is disabled.

Data Structures

struct  RAIL_TimerSyncConfig_t
 Channel values used to perform timer sync before and after sleep.

Macros

#define RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT   (7U)
 Default PRS channel to use when configuring sleep.
 
#define RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT   (0U)
 Default RTCC channel to use when configuring sleep.
 
#define RAIL_TIMER_SYNC_DEFAULT
 Default timer synchronization configuration.

Enumerations

enum  RAIL_SleepConfig_t {
  RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED,
  RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED
}
 The configuration.

Functions

void RAILCb_ConfigSleepTimerSync (RAIL_TimerSyncConfig_t *timerSyncConfig)
 Configure RAIL timer synchronization.
 
RAIL_Status_t RAIL_ConfigSleep (RAIL_Handle_t railHandle, RAIL_SleepConfig_t sleepConfig)
 Initialize RAIL timer synchronization.
 
RAIL_Status_t RAIL_ConfigSleepAlt (RAIL_Handle_t railHandle, RAIL_TimerSyncConfig_t *syncConfig)
 Initialize RAIL timer synchronization.
 
RAIL_Status_t RAIL_Sleep (uint16_t wakeupProcessTime, bool *deepSleepAllowed)
 Stop the RAIL timer and prepare RAIL for sleep.
 
RAIL_Status_t RAIL_Wake (RAIL_Time_t elapsedTime)
 Wake RAIL from sleep and restart the RAIL timer.
 
RAIL_Status_t RAIL_InitPowerManager (void)
 Initialize RAIL Power Manager.
 
RAIL_Status_t RAIL_DeinitPowerManager (void)
 Stop the RAIL Power Manager.

Detailed Description

These APIs help when putting the system to an EM2/EM3/EM4 sleep states where the high frequency clock is disabled.

The RAIL library has its own timebase and the ability to schedule operations into the future. When going to any power mode that disables the HF clock used for the radio (EM2/EM3/EM4), it is important that this timebase is synchronized to a running LFCLK and the chip is set to wake up before the next scheduled event. If RAIL has not been configured to use the power manager, RAIL_Sleep and RAIL_Wake must be called for performing this synchronization. If RAIL has been configured to use the power manager, RAIL_InitPowerManager, it will automatically perform timer synchronization based on the selected RAIL_TimerSyncConfig_t. Calls to RAIL_Sleep and RAIL_Wake are unsupported in such a scenario.

Following example code snippets demonstrate synchronizing the timebase with and without timer synchronization:

Sleep with timer synchronization:

When sleeping with timer synchronization, you must first get the required LFCLK up and running and leave it running across sleep so that the high frequency clock that drives the RAIL time base can be synchronized to it. The RAIL_Sleep() API will also set up a wake event on the timer to wake up wakeupTime before the next timer event so that it can run successfully. See the EFR32 sections on Low-Frequency Clocks and RAIL Timer Synchronization for more setup details.

This is useful when maintaining packet timestamps across sleep or use the scheduled RX/TX APIs while sleeping in between. It does take more time and code to do the synchronization. If your application does not need this, it should be avoided.

Example (without Power Manager):

#include <rail.h>
#include <rail_types.h>
extern RAIL_Handle_t railHandle;
// Wakeup time for your crystal/board/chip combination
extern uint32_t wakeupTime;
void main(void) {
RAIL_Status_t status;
bool shouldSleep = false;
// This function depends on your board/chip but it must enable the LFCLK
// you intend to use for RTCC sync before we configure sleep as that function
// will attempt to auto detect the clock.
BoardSetupLFCLK()
// Configure sleep for timer synchronization
status = RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED);
assert(status == RAIL_STATUS_NO_ERROR);
// Application main loop
while(1) {
// ... do normal app stuff and set shouldSleep to true when we want to
// sleep
if (shouldSleep) {
bool sleepAllowed = false;
// Go critical to assess sleep decisions
CORE_ENTER_CRITICAL();
if (RAIL_Sleep(wakeupTime, &sleepAllowed) != RAIL_STATUS_NO_ERROR) {
printf("Error trying to go to sleep!");
CORE_EXIT_CRITICAL();
continue;
}
if (sleepAllowed) {
// Go to sleep
}
// Wakeup and sync the RAIL timebase back up
RAIL_Wake(0);
CORE_EXIT_CRITICAL();
}
}
}

Example (with Power Manager):

#include <rail.h>
#include <rail_types.h>
#include <sl_power_manager.h>
extern RAIL_Handle_t railHandle;
void main(void) {
RAIL_Status_t status;
bool shouldSleep = false;
// This function depends on your board/chip but it must enable the LFCLK
// you intend to use for RTCC sync before we configure sleep as that function
// will attempt to auto detect the clock.
BoardSetupLFCLK();
// Configure sleep for timer synchronization
status = RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED);
assert(status == RAIL_STATUS_NO_ERROR);
// Initialize application-level power manager service
sl_power_manager_init();
// Initialize RAIL library's use of the power manager
RAIL_InitPowerManager();
// Application main loop
while(1) {
// ... do normal app stuff and set shouldSleep to true when we want to
// sleep
if (shouldSleep) {
// Let the CPU go to sleep if the system allows it.
sl_power_manager_sleep();
}
}
}

RAIL APIs such as, RAIL_StartScheduledTx, RAIL_ScheduleRx, RAIL_SetTimer, RAIL_SetMultiTimer can be used to schedule periodic wakeups to perform a scheduled operation. The call to sl_power_manager_sleep() in the main loop ensures that the device sleeps until the scheduled operation is due. Upon completion, each instantaneous or scheduled RX/TX operation will indicate radio busy to the power manager to allow the application to service the RAIL event and perform subsequent operations before going to sleep. Therefore, it is important that the application idle the radio by either calling RAIL_Idle or RAIL_YieldRadio. If the radio transitions to RX after an RX or TX operation, always call RAIL_Idle in order transition to a lower sleep state. If the radio transitions to idle after an RX or TX operation, RAIL_YieldRadio should suffice in indicating to the power manager that the radio is no longer busy and the device can sleep.

The following example shows scheduling periodic TX on getting a TX completion event:

void RAILCb_Event(RAIL_Handle_t railHandle, RAIL_Events_t events) {
// Omitting other event handlers
if (events & RAIL_EVENTS_TX_COMPLETION) {
// Schedule the next TX.
RAIL_ScheduleTxConfig_t config = {
.when = (RAIL_Time_t)parameters->startTime,
.mode = (RAIL_TimeMode_t)parameters->startTimeMode
};
(void)RAIL_StartScheduledTx(radio.handle, channel, 0, &config, NULL);
}
}
Note
The above code assumes that RAIL automatic state transitions after TX are idle. Set RAIL_SetTxTransitions to ensure the right state transitions. Radio must be idle for the device to enter EM2 or lower energy mode.
When using the power manager, usage of RAIL_YieldRadio in single protocol RAIL is similar to its usage in multiprotocol RAIL. See Yielding the Radio for more details.
Back to back scheduled operations do not require an explicit call to RAIL_YieldRadio if the radio transitions to idle.

Sleep without timer synchronization:

When sleeping without timer synchronization, you are free to enable only the LFCLKs and wake sources required by the application. RAIL will not attempt to configure any wake events and may miss anything that occurs over sleep.

This is useful when your application does not care about packet timestamps or scheduling operations accurately over sleep.

Example (without Power Manager):

#include <rail.h>
#include <rail_types.h>
extern RAIL_Handle_t railHandle;
void main(void) {
RAIL_Status_t status;
bool shouldSleep = false;
// Configure sleep for timer synchronization
status = RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED);
assert(status == RAIL_STATUS_NO_ERROR);
// Application main loop
while(1) {
// ... do normal app stuff and set shouldSleep to true when we want to
// sleep
if (shouldSleep) {
bool sleepAllowed = false;
uint32_t sleepTime = 0;
// Go critical to assess sleep decisions
CORE_ENTER_CRITICAL();
if (RAIL_Sleep(0, &sleepAllowed) != RAIL_STATUS_NO_ERROR) {
printf("Error trying to go to sleep!");
CORE_EXIT_CRITICAL();
continue;
}
if (sleepAllowed) {
// Go to sleep and optionally update sleepTime to the correct value
// in microseconds
}
// Wakeup and sync the RAIL timebase back up
RAIL_Wake(sleepTime);
CORE_EXIT_CRITICAL();
}
}
}

Example (with Power Manager):

#include <rail.h>
#include <rail_types.h>
#include <sl_power_manager.h>
extern RAIL_Handle_t railHandle;
void main(void) {
RAIL_Status_t status;
bool shouldSleep = false;
// This function depends on your board/chip but it must enable the LFCLK
// you intend to use for RTCC sync before we configure sleep as that function
// will attempt to auto detect the clock.
BoardSetupLFCLK();
// Configure sleep for timer synchronization
status = RAIL_ConfigSleep(railHandle, RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED);
assert(status == RAIL_STATUS_NO_ERROR);
// Initialize application-level power manager service
sl_power_manager_init();
// Initialize RAIL library's use of the power manager
RAIL_InitPowerManager();
// Application main loop
while(1) {
// ... do normal app stuff and set shouldSleep to true when we want to
// sleep
if (shouldSleep) {
// Let the CPU go to sleep if the system allows it.
sl_power_manager_sleep();
}
}
}

Macro Definition Documentation

◆ RAIL_TIMER_SYNC_DEFAULT

#define RAIL_TIMER_SYNC_DEFAULT
Value:
{ \
RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT, \
RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT, \
RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED, \
}

Default timer synchronization configuration.

Definition at line 1000 of file rail_chip_specific.h.

Enumeration Type Documentation

◆ RAIL_SleepConfig_t

enum RAIL_SleepConfig_t

The configuration.

Enumerator
RAIL_SLEEP_CONFIG_TIMERSYNC_DISABLED 

Disable timer sync before and after sleep.

RAIL_SLEEP_CONFIG_TIMERSYNC_ENABLED 

Enable timer sync before and after sleep.

Definition at line 382 of file rail_types.h.

Function Documentation

◆ RAIL_ConfigSleep()

RAIL_Status_t RAIL_ConfigSleep ( RAIL_Handle_t  railHandle,
RAIL_SleepConfig_t  sleepConfig 
)

Initialize RAIL timer synchronization.

Parameters
[in]railHandleA RAIL instance handle.
[in]sleepConfigA sleep configuration.
Returns
Status code indicating success of the function call.

◆ RAIL_ConfigSleepAlt()

RAIL_Status_t RAIL_ConfigSleepAlt ( RAIL_Handle_t  railHandle,
RAIL_TimerSyncConfig_t *  syncConfig 
)

Initialize RAIL timer synchronization.

Parameters
[in]railHandleA RAIL instance handle.
[in]syncConfigA pointer to the timer synchronization configuration.

The default structure used to enable timer synchronization across sleep is RAIL_TIMER_SYNC_DEFAULT.

Returns
Status code indicating success of the function call.

◆ RAIL_DeinitPowerManager()

RAIL_Status_t RAIL_DeinitPowerManager ( void  )

Stop the RAIL Power Manager.

Returns
Status code indicating success of the function call.
Note
The active RAIL configuration must be idle to disable radio power manager and there should be no outstanding requirements by radio power manager.

◆ RAIL_InitPowerManager()

RAIL_Status_t RAIL_InitPowerManager ( void  )

Initialize RAIL Power Manager.

Returns
Status code indicating success of the function call.
Note
Call this function only when the application is built and initialized with Power Manager plugin. RAIL will perform timer synchronization, upon transitioning from EM2 or lower to EM1 or higher energy mode or vice-versa, in the Power Manager EM transition callback. Since EM transition callbacks are not called in a deterministic order, it is suggested to not call any RAIL time dependent APIs in an EM transition callback.

◆ RAIL_Sleep()

RAIL_Status_t RAIL_Sleep ( uint16_t  wakeupProcessTime,
bool *  deepSleepAllowed 
)

Stop the RAIL timer and prepare RAIL for sleep.

Parameters
[in]wakeupProcessTimeTime in microseconds that the application and hardware need to recover from sleep state.
[out]deepSleepAllowedtrue - system can go to deep sleep. false - system should not go to deep sleep. Deep sleep should be blocked in this case.
Returns
Status code indicating success of the function call.
Warning
The active RAIL configuration must be idle to enable sleep.
Note
This API must not be called if RAIL Power Manager is initialized.

◆ RAIL_Wake()

RAIL_Status_t RAIL_Wake ( RAIL_Time_t  elapsedTime)

Wake RAIL from sleep and restart the RAIL timer.

Parameters
[in]elapsedTimeAdd the sleep duration to the RAIL timer before restarting the RAIL timer.
Returns
Status code indicating success of the function call.

If the timer sync was enabled by RAIL_ConfigSleep, synchronize the RAIL timer using an alternate timer. Otherwise, add elapsedTime to the RAIL timer.

Note
This API must not be called if RAIL Power Manager is initialized.

◆ RAILCb_ConfigSleepTimerSync()

void RAILCb_ConfigSleepTimerSync ( RAIL_TimerSyncConfig_t *  timerSyncConfig)

Configure RAIL timer synchronization.

This function is optional to implement.

Parameters
[in,out]timerSyncConfigA pointer to the RAIL_TimerSyncConfig_t structure containing the configuration parameters for timer sync. The RAIL_TimerSyncConfig_t::sleep field is ignored in this call.

This function is called during RAIL_ConfigSleep to allow an application to configure the PRS and RTCC channels used for timer sync to values other than their defaults. The default channels are populated in timerSyncConfig and can be overwritten by the application. If this function is not implemented by the application, a default implementation from within the RAIL library will be used that simply maintains the default channel values in timerSyncConfig.

If an unsupported channel is selected by the application, RAIL_ConfigSleep will return RAIL_STATUS_INVALID_PARAMETER.

void RAILCb_ConfigSleepTimerSync(RAIL_TimerSyncConfig_t *timerSyncConfig)
{
timerSyncConfig->prsChannel = MY_TIMERSYNC_PRS_CHANNEL;
timerSyncConfig->rtccChannel = MY_TIMERSYNC_RTCC_CHANNEL;
}