sleep

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

Collaboration diagram for sleep:

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

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
}

NOTE: This method should always be used in a loop associated with checking another "event" variable, since processor events are a shared resource and can happen for a large number of reasons.

Parameters

timeout_timestamp

the timeout time

Returns

true if the target time is reached, false otherwise

Definition at line 443 of file time.c.

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

ms	the number of milliseconds to sleep

Definition at line 439 of file time.c.

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

target

the time after which to return

See also

sleep_us()

busy_wait_until()

Definition at line 392 of file time.c.

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

us	the number of microseconds to sleep

See also

busy_wait_us()

Definition at line 422 of file time.c.