pico_low_power

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.
static int	low_power_set_external_clock_source (__unused uint src_hz, __unused 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.
int	low_power_pstate_until_aon_timer (absolute_time_t until, pstate_bitset_t *pstate, low_power_pstate_resume_func resume_func)
	Go to Pstate until time using AON timer.
int	low_power_pstate_until_gpio_pin_state (uint gpio_pin, bool edge, bool high, pstate_bitset_t *pstate, low_power_pstate_resume_func resume_func)
	Go to Pstate until GPIO pin state changes.
pstate_bitset_t *	low_power_persistent_pstate_get (pstate_bitset_t *pstate)
	Get Pstate which keeps persistent data powered on.
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.
static int	low_power_pstate_for_ms (uint32_t ms, pstate_bitset_t *pstate, low_power_pstate_resume_func resume_func)
	Go to Pstate 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.

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.

In Pstate mode:

• Some power domains are switched off and don't retain state (eg specified SRAMs). By default, only the power domains required to keep persistent data powered on will be kept on.
• You can only wake up from Pstate using the AON timer, or a GPIO wakeup configured using powman_enable_gpio_wakeup.
• Waking up from Pstate will run your program from the start, optionally executing a resume_func during runtime init. All non-persistent data will be overwritten by crt0 when the program starts again.
• Variables can be marked as persistent using the __persistent_data macro. The location of the data can be set using the CMake function pico_set_persistent_data_loc. The persistent data can be stored in XIP_SRAM or main SRAM.
• The Pstate APIs will overwrite the last 2 powman scratch registers - the other scratch registers are not modified, so can be used for other persistent data.

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.

The clock source must be set to DORMANT_CLOCK_SOURCE_LPOSC, which means clk_sys will be switched to the ROSC while dormant so it can be stopped, while clk_ref will be run from the LPOSC so that it continues running for the timer.

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_LPOSC, clk_sys will be run from the ROSC while dormant so it can be stopped, while clk_ref will be run from the LPOSC. 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_persistent_pstate_get()

pstate_bitset_t * low_power_persistent_pstate_get

(

pstate_bitset_t *

pstate

)

Get Pstate which keeps persistent data powered on.

Parameters

pstate

Pointer to the Pstate to write the result to.

Returns

The Pstate.

low_power_pstate_for_ms()

static int low_power_pstate_for_ms ( uint32_t  ms, pstate_bitset_t *  pstate, low_power_pstate_resume_func  resume_func  )

inlinestatic

Go to Pstate for a number of milliseconds.

See low_power_pstate_until_aon_timer for more information.

Parameters

ms	The number of milliseconds to go to Pstate for.
pstate	The Pstate to use.
resume_func	The function to call on reboot.

Returns

0 on success, non-zero on error.

low_power_pstate_until_aon_timer()

int low_power_pstate_until_aon_timer	(	absolute_time_t	until,
		pstate_bitset_t *	pstate,
		low_power_pstate_resume_func	resume_func
	)

Go to Pstate until time using AON timer.

Go to Pstate until the given AON timer reaches the specified value. The function specified in resume_func will be called on reboot, with the low power Pstate passed to it.

If pstate is NULL, it will go to the minimum Pstate that will keep persistent data powered on.

To also wake up from a GPIO, configure that using powman_enable_gpio_wakeup before calling this function.

NOTE: This function will overwrite the last 2 powman scratch registers - the other scratch registers are not modified.

Parameters

until	The time to go to Pstate until.
pstate	The Pstate to use. If NULL, the Pstate will keep persistent data powered on.
resume_func	The function to call on reboot.

Returns

0 on success, non-zero on error.

low_power_pstate_until_gpio_pin_state()

int low_power_pstate_until_gpio_pin_state	(	uint	gpio_pin,
		bool	edge,
		bool	high,
		pstate_bitset_t *	pstate,
		low_power_pstate_resume_func	resume_func
	)

Go to Pstate until GPIO pin state changes.

Go to Pstate until the given GPIO pin changes state. The function specified in resume_func will be called on reboot, with the low power Pstate passed to it.

If pstate is NULL, it will go to the minimum Pstate that will keep persistent data powered on.

NOTE: This function will overwrite the last 2 powman scratch registers - the other scratch registers are not modified.

Parameters

gpio_pin	The GPIO pin to use.
edge	Whether to listen for edge or level.
high	Whether to listen for the high/low level, or rising/falling edge.
pstate	The Pstate to use. If NULL, the Pstate will keep persistent data powered on.
resume_func	The function to call on reboot.

Returns

0 on success, non-zero on error.

low_power_set_external_clock_source()

static int low_power_set_external_clock_source ( __unused uint  src_hz, __unused uint  gpio_pin  )

inlinestatic

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.