APIs for using lower power states. More...

Functions
void	low_power_set_pins_low_leakage_exclude_mask (uint32_t exclude_mask)
	Set all pins to a low leakage state.

static void	low_power_set_pins_low_leakage_exclude_mask64 (uint64_t exclude_mask)
	Set all pins to a low leakage state (64-bit mask version)

int	low_power_sleep_until_irq (const clock_dest_bitset_t *keep_enabled)
	Sleep until an interrupt occurs.

int	low_power_sleep_until_timer (timer_hw_t timer, absolute_time_t until, const clock_dest_bitset_t keep_enabled, bool exclusive)
	Sleep until time using timer.

static int	low_power_sleep_until_default_timer (absolute_time_t until, const clock_dest_bitset_t *keep_enabled, bool exclusive)
	Sleep until time using default timer.

int	low_power_sleep_until_aon_timer (absolute_time_t until, const clock_dest_bitset_t *keep_enabled, bool exclusive)
	Sleep until time using AON timer.

int	low_power_sleep_until_gpio_pin_state (uint gpio_pin, bool edge, bool high, const clock_dest_bitset_t *keep_enabled, bool exclusive)
	Sleep until GPIO pin state changes.

int	low_power_set_external_clock_source (uint src_hz, uint gpio_pin)
	Set the external clock source for the AON timer.

int	low_power_dormant_until_aon_timer (absolute_time_t until, dormant_clock_source_t dormant_clock_source, const clock_dest_bitset_t *keep_enabled)
	Go dormant until time using AON timer.

int	low_power_dormant_until_gpio_pin_state (uint gpio_pin, bool edge, bool high, dormant_clock_source_t dormant_clock_source, const clock_dest_bitset_t *keep_enabled)
	Go dormant until GPIO pin state changes.

static bool	low_power_start_aon_timer_at_time_ms (uint64_t ms)
	Start the AON timer at a specific time in milliseconds.

static bool	low_power_start_aon_timer (void)
	Start the AON timer at the current system time.

static int	low_power_sleep_for_us (timer_hw_t timer, uint64_t us, const clock_dest_bitset_t keep_enabled, bool exclusive)
	Sleep for a number of microseconds.

static int	low_power_sleep_for_ms (uint32_t ms, const clock_dest_bitset_t *keep_enabled, bool exclusive)
	Sleep for a number of milliseconds.

static int	low_power_dormant_for_ms (uint32_t ms, dormant_clock_source_t dormant_clock_source, const clock_dest_bitset_t *keep_enabled)
	Go dormant for a number of milliseconds.

Detailed Description

APIs for using lower power states.

There are three modes of operation: sleep, dormant, and Pstate, with the lowest power consumption being Pstate.

NOTE: On RP2040, there is no Pstate mode, and going dormant using the AON timer requires an external clock source for the RTC (see low_power_set_external_clock_source).

In sleep mode:

Some clocks can be left running controlled by the SLEEP_EN registers in the clocks block. For example you could keep clk_rtc running.
Some destinations (proc0 and proc1 wakeup logic) can't be stopped in sleep mode otherwise there wouldn't be enough logic to wake up again.
You can wake up from sleep by any interrupt, provided the clock for that interrupt is kept enabled
The sleep APIs will keep the clocks enabled for stdio during sleep, along with USB clocks when using tinyusb.

In dormant mode:

Both xosc and rosc are stopped, until the dormant clock source is started again by an external event.
USB will be disabled before going into dormant, and re-enabled after waking up.
You can only wake up from dormant using the AON timer, or a GPIO interrupt configured using gpio_set_dormant_irq_enabled. All other interrupts will be disabled during dormant.

Some rough power consumption values when going to low power modes using timers, measured on Pico-series boards (powered either from VSYS at 5.2V, or from 3V3 at 3.3V, running low_power_test_simple):

Mode	Pico (VSYS)	Pico 2 (VSYS)	Pico (3V3)	Pico 2 (3V3)
Sleep	7.3mA (37.9mW)	5.9mA (30.7mW)	8.7mA (28.5mW)	6.9mA (22.7mW)
Dormant	0.95mA (5.0mW)	3.3mA (17.0mW)	1.2mA (4.0mW)	3.7mA (12.0mW)
Pstate (SRAM0 On)	N/A	0.25mA (1.32mW)	N/A	0.14mA (0.47mW)
Pstate (XIP SRAM On)	N/A	0.22mA (1.21mW)	N/A	0.10mA (0.44mW)
Pstate (All SRAM Off)	N/A	0.18mA (1.10mW)	N/A	0.08mA (0.40mW)

NOTE: The RP2350 dormant values are higher than the RP2040 ones because RP2350 continues running clk_ref from the LPOSC to run the timer, whereas RP2040 only runs clk_rtc from the XOSC.

Function Documentation

◆ low_power_dormant_for_ms()

static int low_power_dormant_for_ms	(	uint32_t	ms,
		dormant_clock_source_t	dormant_clock_source,
		const clock_dest_bitset_t *	keep_enabled
	)

inlinestatic

Go dormant for a number of milliseconds.

See low_power_dormant_until_aon_timer for more information.

Parameters

ms	The number of milliseconds to go dormant for.
dormant_clock_source	The clock source to use for dormant.
keep_enabled	The clocks to keep enabled during dormant.

Returns: 0 on success, non-zero on error.

◆ low_power_dormant_until_aon_timer()

int low_power_dormant_until_aon_timer	(	absolute_time_t	until,
		dormant_clock_source_t	dormant_clock_source,
		const clock_dest_bitset_t *	keep_enabled
	)

Go dormant until time using AON timer.

Go dormant until the given AON timer reaches the specified value. The clocks specified in keep_enabled will be kept enabled during dormant, but XOSC and ROSC will be stopped.

If the clock source is set to DORMANT_CLOCK_SOURCE_RTC, all clocks will be switched to the ROSC while dormant so they can be stopped, except clk_rtc which will be run from the XOSC so that it continues running for the timer. In this case the XOSC will not be stopped.

Otherwise, this requires an external clock source to be set using low_power_set_external_clock_source before calling this function. If the external clock source is not set, or it is not running, this will return PICO_ERROR_PRECONDITION_NOT_MET.

Parameters

until	The time to go dormant until.
dormant_clock_source	The clock source to use for dormant. Must be DORMANT_CLOCK_SOURCE_LPOSC on RP2350.
keep_enabled	The clocks to keep enabled during dormant.

Returns: 0 on success, non-zero on error.

◆ low_power_dormant_until_gpio_pin_state()

int low_power_dormant_until_gpio_pin_state	(	uint	gpio_pin,
		bool	edge,
		bool	high,
		dormant_clock_source_t	dormant_clock_source,
		const clock_dest_bitset_t *	keep_enabled
	)

Go dormant until GPIO pin state changes.

Go dormant until the given GPIO pin changes state. The clocks specified in keep_enabled will be kept enabled during dormant, but XOSC and ROSC will be stopped.

If the clock source is set to DORMANT_CLOCK_SOURCE_RTC, all clocks will be switched to the ROSC while dormant so they can be stopped, except clk_rtc which will be run from the XOSC. In this case the XOSC will not be stopped. For the lowest power consumption, you should use DORMANT_CLOCK_SOURCE_ROSC instead, as the GPIO interrupt does not require a clock.

Parameters

gpio_pin	The GPIO pin to use.
edge	Whether to listen for edge or level.
high	Whether to listen for high level / rising edge (true), or low level / falling edge (false).
dormant_clock_source	The clock source to use for dormant.
keep_enabled	The clocks to keep enabled during dormant.

Returns: 0 on success, non-zero on error.

◆ low_power_set_external_clock_source()

int low_power_set_external_clock_source	(	uint	src_hz,
		uint	gpio_pin
	)

Set the external clock source for the AON timer.

Set the external clock source for the AON timer. This is only used on RP2040.

Parameters

src_hz	The frequency of the external clock source.
gpio_pin	The GPIO pin to use for the external clock source.

Returns: 0 on success, non-zero on error.

◆ low_power_set_pins_low_leakage_exclude_mask()

void low_power_set_pins_low_leakage_exclude_mask ( uint32_t exclude_mask )

Set all pins to a low leakage state.

Disables pulls & inputs on the pads, and disables the IO output with all pins set to inputs. This results in the lowest leakage current.

Does not change the state of pins in the exclude_mask.

Parameters

exclude_mask Mask of the pins to exclude from this

◆ low_power_set_pins_low_leakage_exclude_mask64()

static void low_power_set_pins_low_leakage_exclude_mask64 ( uint64_t exclude_mask )

inlinestatic

Set all pins to a low leakage state (64-bit mask version)

See also: low_power_set_pins_low_leakage_exclude_mask

Parameters

exclude_mask Mask of the pins to exclude from this

◆ low_power_sleep_for_ms()

static int low_power_sleep_for_ms	(	uint32_t	ms,
		const clock_dest_bitset_t *	keep_enabled,
		bool	exclusive
	)

inlinestatic

Sleep for a number of milliseconds.

See low_power_sleep_until_default_timer for more information.

Parameters

ms	The number of milliseconds to sleep.
keep_enabled	The clocks to keep enabled during sleep.
exclusive	Whether to only listen for the timer interrupt, or other interrupts.

Returns: 0 on success, non-zero on error.

◆ low_power_sleep_for_us()

static int low_power_sleep_for_us	(	timer_hw_t *	timer,
		uint64_t	us,
		const clock_dest_bitset_t *	keep_enabled,
		bool	exclusive
	)

inlinestatic

Sleep for a number of microseconds.

See low_power_sleep_until_default_timer for more information.

Parameters

us	The number of microseconds to sleep.
keep_enabled	The clocks to keep enabled during sleep.
exclusive	Whether to only listen for the timer interrupt, or other interrupts.

Returns: 0 on success, non-zero on error.

◆ low_power_sleep_until_aon_timer()

int low_power_sleep_until_aon_timer	(	absolute_time_t	until,
		const clock_dest_bitset_t *	keep_enabled,
		bool	exclusive
	)

Sleep until time using AON timer.

Sleep until the AON timer reaches the specified value. The clocks specified in keep_enabled will be kept enabled during sleep, along with clocks required for the AON timer. If exclusive is true, only the AON timer interrupt will be listened for, otherwise other interrupts will also be listened for.

Parameters

until	The time to sleep until.
keep_enabled	The clocks to keep enabled during sleep.
exclusive	Whether to only listen for the AON timer interrupt, or other interrupts.

Returns: 0 on success, non-zero on error.

◆ low_power_sleep_until_default_timer()

static int low_power_sleep_until_default_timer	(	absolute_time_t	until,
		const clock_dest_bitset_t *	keep_enabled,
		bool	exclusive
	)

inlinestatic

Sleep until time using default timer.

See low_power_sleep_until_timer for more information.

Parameters

until	The time to sleep until.
keep_enabled	The clocks to keep enabled during sleep.
exclusive	Whether to only listen for the timer interrupt, or other interrupts.

Returns: 0 on success, non-zero on error.

◆ low_power_sleep_until_gpio_pin_state()

int low_power_sleep_until_gpio_pin_state	(	uint	gpio_pin,
		bool	edge,
		bool	high,
		const clock_dest_bitset_t *	keep_enabled,
		bool	exclusive
	)

Sleep until GPIO pin state changes.

Sleep until the given GPIO pin changes state. The clocks specified in keep_enabled will be kept enabled during sleep. If exclusive is true, only the GPIO interrupt will be listened for, otherwise other interrupts will also be listened for.

Parameters

gpio_pin	The GPIO pin to use.
edge	Whether to listen for edge or level.
high	Whether to listen for high level / rising edge (true), or low level / falling edge (false).
keep_enabled	The clocks to keep enabled during sleep.
exclusive	Whether to only listen for the GPIO interrupt, or other interrupts.

Returns: 0 on success, non-zero on error.

◆ low_power_sleep_until_irq()

int low_power_sleep_until_irq ( const clock_dest_bitset_t * keep_enabled )

Sleep until an interrupt occurs.

Sleep until any interrupt occurs. The clocks specified in keep_enabled will be kept enabled during sleep.

Parameters

keep_enabled The clocks to keep enabled during sleep.

Returns: 0 on success, non-zero on error.

◆ low_power_sleep_until_timer()

int low_power_sleep_until_timer	(	timer_hw_t *	timer,
		absolute_time_t	until,
		const clock_dest_bitset_t *	keep_enabled,
		bool	exclusive
	)

Sleep until time using timer.

Sleep until the given timer reaches the specified value. The clocks specified in keep_enabled will be kept enabled during sleep, along with clocks required for the timer. If exclusive is true, only the timer interrupt will be listened for, otherwise other interrupts will also be listened for.

Parameters

timer	The timer to use.
until	The time to sleep until.
keep_enabled	The clocks to keep enabled during sleep.
exclusive	Whether to only listen for the timer interrupt, or other interrupts.

Returns: 0 on success, non-zero on error.

◆ low_power_start_aon_timer()

static bool low_power_start_aon_timer ( void )

inlinestatic

Start the AON timer at the current system time.

See aon_timer_start for more information.

If the AON timer is already running, this function will not restart it.

Returns: true on success, false on failure.

◆ low_power_start_aon_timer_at_time_ms()

static bool low_power_start_aon_timer_at_time_ms ( uint64_t ms )

inlinestatic

Start the AON timer at a specific time in milliseconds.

See aon_timer_start for more information.

If the AON timer is already running, this function will restart it from the specified time.

Parameters

ms	The time in milliseconds to start the AON timer at.

Returns: true on success, false on failure.

Functions

Detailed Description

Function Documentation

◆ low_power_dormant_for_ms()

◆ low_power_dormant_until_aon_timer()

◆ low_power_dormant_until_gpio_pin_state()

◆ low_power_set_external_clock_source()

◆ low_power_set_pins_low_leakage_exclude_mask()

◆ low_power_set_pins_low_leakage_exclude_mask64()

◆ low_power_sleep_for_ms()

◆ low_power_sleep_for_us()

◆ low_power_sleep_until_aon_timer()

◆ low_power_sleep_until_default_timer()

◆ low_power_sleep_until_gpio_pin_state()

◆ low_power_sleep_until_irq()

◆ low_power_sleep_until_timer()

◆ low_power_start_aon_timer()

◆ low_power_start_aon_timer_at_time_ms()