low_power.h

Go to the documentation of this file.

/*
 * Copyright (c) 2026 Raspberry Pi (Trading) Ltd.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */
 
#ifndef _PICO_LOW_POWER_H_
#define _PICO_LOW_POWER_H_
 
#include "pico.h"
#include "hardware/timer.h"
#include "pico/time.h"
#include "pico/aon_timer.h"
 
#ifdef __cplusplus
extern "C" {
#endif

 
// PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_PICO_LOW_POWER, Enable/disable assertions in the pico_low_power module, type=bool, default=0, group=pico_low_power
#ifndef PARAM_ASSERTIONS_ENABLED_PICO_LOW_POWER
#define PARAM_ASSERTIONS_ENABLED_PICO_LOW_POWER 0
#endif
 
// PICO_CONFIG: PICO_LOW_POWER_MIN_AON_SLEEP_TIME_MS, Minimum supported time to spend in sleep using the AON timer in milliseconds, type=int, default=2000 on RP2040, 10 otherwise, group=pico_low_power
#ifndef PICO_LOW_POWER_MIN_AON_SLEEP_TIME_MS
#if PICO_RP2040
#define PICO_LOW_POWER_MIN_AON_SLEEP_TIME_MS 2000
#else
#define PICO_LOW_POWER_MIN_AON_SLEEP_TIME_MS 10
#endif
#endif
 
// PICO_CONFIG: PICO_LOW_POWER_MIN_DORMANT_TIME_MS, Minimum supported time to spend dormant in milliseconds, type=int, default=2000 on RP2040, 10 otherwise, group=pico_low_power
#ifndef PICO_LOW_POWER_MIN_DORMANT_TIME_MS
#if PICO_RP2040
#define PICO_LOW_POWER_MIN_DORMANT_TIME_MS 2000
#else
#define PICO_LOW_POWER_MIN_DORMANT_TIME_MS 10
#endif
#endif
 
// PICO_CONFIG: PICO_LOW_POWER_MIN_PSTATE_TIME_MS, Minimum supported time to spend in Pstate in milliseconds, type=int, default=10, group=pico_low_power
#ifndef PICO_LOW_POWER_MIN_PSTATE_TIME_MS
#define PICO_LOW_POWER_MIN_PSTATE_TIME_MS 10
#endif
 
#include "hardware/clocks.h"
#if HAS_RP2040_RTC
#include "hardware/rtc.h"
#endif
#if HAS_POWMAN_TIMER
#include "hardware/powman.h"
#endif
 
typedef enum {
    DORMANT_CLOCK_SOURCE_XOSC,
    DORMANT_CLOCK_SOURCE_ROSC,
#if PICO_RP2040
    DORMANT_CLOCK_SOURCE_RTC,
#else
    DORMANT_CLOCK_SOURCE_LPOSC,
#endif
    NUM_DORMANT_CLOCK_SOURCES
} dormant_clock_source_t;
 
#if PICO_RP2040
#define DORMANT_CLOCK_SOURCE_DEFAULT DORMANT_CLOCK_SOURCE_RTC
#else
#define DORMANT_CLOCK_SOURCE_DEFAULT DORMANT_CLOCK_SOURCE_LPOSC
#endif
 
#if PICO_RP2040
#define DORMANT_CLOCK_HZ_DEFAULT RTC_CLOCK_FREQ_HZ
#else
#define DORMANT_CLOCK_HZ_DEFAULT 0  // ignored
#endif
 
#if HAS_POWMAN_TIMER
typedef void (*low_power_pstate_resume_func)(pstate_bitset_t *pstate);
#endif

void low_power_set_pins_low_leakage_exclude_mask(uint32_t exclude_mask);

#if NUM_BANK0_GPIOS <= 32
static inline void low_power_set_pins_low_leakage_exclude_mask64(uint64_t exclude_mask) {
    low_power_set_pins_low_leakage_exclude_mask((uint32_t)exclude_mask);
}
#else
void low_power_set_pins_low_leakage_exclude_mask64(uint64_t exclude_mask);
#endif

int low_power_sleep_until_irq(const clock_dest_bitset_t *keep_enabled);

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

static inline int low_power_sleep_until_default_timer(absolute_time_t until, const clock_dest_bitset_t *keep_enabled, bool exclusive) {
    return low_power_sleep_until_timer(PICO_DEFAULT_TIMER_INSTANCE(), until, keep_enabled, exclusive);
}

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

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

#if PICO_RP2040
int low_power_set_external_clock_source(uint src_hz, uint gpio_pin);
#else
static inline int low_power_set_external_clock_source(__unused uint src_hz, __unused uint gpio_pin) {
    return PICO_OK;
}
#endif

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

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);
 
#if HAS_POWMAN_TIMER
int low_power_pstate_until_aon_timer(absolute_time_t until, pstate_bitset_t *pstate, low_power_pstate_resume_func resume_func);

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

pstate_bitset_t *low_power_persistent_pstate_get(pstate_bitset_t *pstate);
#endif
 
 
// Convenience functions to avoid needing the correct absolute_time_t

static inline bool low_power_start_aon_timer_at_time_ms(uint64_t ms) {
    struct timespec ts;
    ms_to_timespec(ms, &ts);
    return aon_timer_start(&ts);
}

static inline bool low_power_start_aon_timer(void) {
    if (aon_timer_is_running()) return true;
    return low_power_start_aon_timer_at_time_ms(0);
}

static inline int low_power_sleep_for_us(timer_hw_t *timer, uint64_t us, const clock_dest_bitset_t *keep_enabled, bool exclusive) {
    return low_power_sleep_until_timer(timer, make_timeout_time_us(us), keep_enabled, exclusive);
}

static inline int low_power_sleep_for_ms(uint32_t ms, const clock_dest_bitset_t *keep_enabled, bool exclusive) {
    return low_power_sleep_until_default_timer(make_timeout_time_ms(ms), keep_enabled, exclusive);
}

static inline int low_power_dormant_for_ms(uint32_t ms, dormant_clock_source_t dormant_clock_source, const clock_dest_bitset_t *keep_enabled) {
    low_power_start_aon_timer();
    return low_power_dormant_until_aon_timer(aon_timer_make_timeout_time_ms(ms), dormant_clock_source, keep_enabled);
}
 
#if HAS_POWMAN_TIMER
static inline int low_power_pstate_for_ms(uint32_t ms, pstate_bitset_t *pstate, low_power_pstate_resume_func resume_func) {
    low_power_start_aon_timer();
    return low_power_pstate_until_aon_timer(aon_timer_make_timeout_time_ms(ms), pstate, resume_func);
}
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif