Sleep#

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();
    }
  }
}

Modules#

RAIL_TimerSyncConfig_t

Enumerations#

enum
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_ConfigSleep(RAIL_Handle_t railHandle, RAIL_SleepConfig_t sleepConfig)

Initialize RAIL timer synchronization.

RAIL_ConfigSleepAlt(RAIL_Handle_t railHandle, RAIL_TimerSyncConfig_t *syncConfig)

Initialize RAIL timer synchronization.

RAIL_Sleep(uint16_t wakeupProcessTime, bool *deepSleepAllowed)

Stop the RAIL timer and prepare RAIL for sleep.

RAIL_Wake(RAIL_Time_t elapsedTime)

Wake RAIL from sleep and restart the RAIL timer.

Initialize RAIL Power Manager.

Stop the RAIL Power Manager.

Macros#

#define

Default PRS channel to use when configuring sleep.

#define

Default RTCC channel to use when configuring sleep.

#define

Default timer synchronization configuration.

Enumeration Documentation#

RAIL_SleepConfig_t#

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 424 of file common/rail_types.h

Function Documentation#

RAILCb_ConfigSleepTimerSync#

void RAILCb_ConfigSleepTimerSync (RAIL_TimerSyncConfig_t *timerSyncConfig)

Configure RAIL timer synchronization.

Parameters
[inout]timerSyncConfig

A 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 optional to implement.

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;
}

Definition at line 1481 of file common/rail.h

RAIL_ConfigSleep#

RAIL_Status_t RAIL_ConfigSleep (RAIL_Handle_t railHandle, RAIL_SleepConfig_t sleepConfig)

Initialize RAIL timer synchronization.

Parameters
[in]railHandle

A RAIL instance handle.

[in]sleepConfig

A sleep configuration.

Returns

  • Status code indicating success of the function call.


Definition at line 1491 of file common/rail.h

RAIL_ConfigSleepAlt#

RAIL_Status_t RAIL_ConfigSleepAlt (RAIL_Handle_t railHandle, RAIL_TimerSyncConfig_t *syncConfig)

Initialize RAIL timer synchronization.

Parameters
[in]railHandle

A RAIL instance handle.

[in]syncConfig

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


Definition at line 1505 of file common/rail.h

RAIL_Sleep#

RAIL_Status_t RAIL_Sleep (uint16_t wakeupProcessTime, bool *deepSleepAllowed)

Stop the RAIL timer and prepare RAIL for sleep.

Parameters
[in]wakeupProcessTime

Time in microseconds that the application and hardware need to recover from sleep state.

[out]deepSleepAllowed

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

Warnings

  • The active RAIL configuration must be idle to enable sleep.

Note

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


Definition at line 1524 of file common/rail.h

RAIL_Wake#

RAIL_Status_t RAIL_Wake (RAIL_Time_t elapsedTime)

Wake RAIL from sleep and restart the RAIL timer.

Parameters
[in]elapsedTime

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


Definition at line 1540 of file common/rail.h

RAIL_InitPowerManager#

RAIL_Status_t RAIL_InitPowerManager (void)

Initialize RAIL Power Manager.

Parameters
N/A

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.


Definition at line 1555 of file common/rail.h

RAIL_DeinitPowerManager#

RAIL_Status_t RAIL_DeinitPowerManager (void)

Stop the RAIL Power Manager.

Parameters
N/A

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.


Definition at line 1566 of file common/rail.h

Macro Definition Documentation#

RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT#

#define RAIL_TIMER_SYNC_PRS_CHANNEL_DEFAULT
Value:
(7U)

Default PRS channel to use when configuring sleep.


Definition at line 325 of file chip/efr32/efr32xg1x/rail_chip_specific.h

RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT#

#define RAIL_TIMER_SYNC_RTCC_CHANNEL_DEFAULT
Value:
(0U)

Default RTCC channel to use when configuring sleep.


Definition at line 332 of file chip/efr32/efr32xg1x/rail_chip_specific.h

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 336 of file chip/efr32/efr32xg1x/rail_chip_specific.h