Sleep functions for delaying execution in a lower power state. More...

Functions

void sleep_until (absolute_time_t target)
 Wait until after the given timestamp to return. More...
 
void sleep_us (uint64_t us)
 Wait for the given number of microseconds before returning. More...
 
void sleep_ms (uint32_t ms)
 Wait for the given number of milliseconds before returning. More...
 
bool best_effort_wfe_or_timeout (absolute_time_t timeout_timestamp)
 Helper method for blocking on a timeout. More...
 

Detailed Description

Sleep functions for delaying execution in a lower power state.

These functions allow the calling core to sleep. This is a lower powered sleep; waking and re-checking time on every processor event (WFE)

Note
These functions should not be called from an IRQ handler.
Lower powered sleep requires use of the default alarm pool which may be disabled by the PICO_TIME_DEFAULT_ALARM_POOL_DISABLED define or currently full in which case these functions become busy waits instead.
Whilst sleep_ functions are preferable to busy_wait functions from a power perspective, the busy_wait equivalent function may return slightly sooner after the target is reached.
See also
busy_wait_until()
busy_wait_us()
busy_wait_us_32()

Function Documentation

◆ best_effort_wfe_or_timeout()

bool best_effort_wfe_or_timeout ( absolute_time_t  timeout_timestamp)

Helper method for blocking on a timeout.

This method will return in response to an event (as per __wfe) or when the target time is reached, or at any point before.

This method can be used to implement a lower power polling loop waiting on some condition signalled by an event (__sev()).

This is called best_effort because under certain circumstances (notably the default timer pool being disabled or full) the best effort is simply to return immediately without a __wfe, thus turning the calling code into a busy wait.

Example usage:

bool my_function_with_timeout_us(uint64_t timeout_us) {
absolute_time_t timeout_time = make_timeout_time_us(timeout_us);
do {
// each time round the loop, we check to see if the condition
// we are waiting on has happened
if (my_check_done()) {
// do something
return true;
}
// will try to sleep until timeout or the next processor event
} while (!best_effort_wfe_or_timeout(timeout_time));
return false; // timed out
}
bool best_effort_wfe_or_timeout(absolute_time_t timeout_timestamp)
Helper method for blocking on a timeout.
Definition: time.c:396
static absolute_time_t make_timeout_time_us(uint64_t us)
Convenience method to get the timestamp a number of microseconds from the current time.
Definition: time.h:129
Definition: types.h:33
Parameters
timeout_timestampthe timeout time
Returns
true if the target time is reached, false otherwise

◆ sleep_ms()

void sleep_ms ( uint32_t  ms)

Wait for the given number of milliseconds before returning.

Note
This method attempts to perform a lower power sleep (using WFE) as much as possible.
Parameters
msthe number of milliseconds to sleep

◆ sleep_until()

void sleep_until ( absolute_time_t  target)

Wait until after the given timestamp to return.

Note
This method attempts to perform a lower power (WFE) sleep
Parameters
targetthe time after which to return
See also
sleep_us()
busy_wait_until()

◆ sleep_us()

void sleep_us ( uint64_t  us)

Wait for the given number of microseconds before returning.

Note
This method attempts to perform a lower power (WFE) sleep
Parameters
usthe number of microseconds to sleep
See also
busy_wait_us()