Library guide · API index and notation
This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.
import "std/embedded/chip/esp_power"
Names used in signatures
Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.
| Alias | Package | Source file |
|---|---|---|
hal |
std/embedded/hal |
esp_power.dodo |
power |
std/embedded/power |
esp_power.dodo |
GATE_COUNT
Constant · Source
One past the last gate.
pub const GATE_COUNT: u32 = 57
enabled_clocks
Function · Source
The gates in
clocksthat run.
pub fn enabled_clocks<R: hal.Registers>(pcr: &mut R, clocks: power.Clocks) -> power.Clocks
start_clocks
Function · Source
Open the gates in
clocks; bits past the last gate are ignored. Other fields of the registers stay as they are.
pub fn start_clocks<R: hal.Registers>(pcr: &mut R, clocks: power.Clocks)
stop_clocks
Function · Source
Close the gates in
clocks.
pub fn stop_clocks<R: hal.Registers>(pcr: &mut R, clocks: power.Clocks)
init_active_state
Function · Source
Put the PMU’s HP_ACTIVE state, which the chip runs in and returns to after every PMU sleep, the analog bus’s power, and the power domains’ overrides (release_power_domains) where ESP-IDF’s and esp-hal’s start-up code put them. These registers are in the always-on domain: a core reset, as
dodo rundoes, keeps what an earlier program left, and their power-up values power neither the PLL nor the bias and gate the system clock, the radio domain’s clocks, and the analog configuration bus behind the ADC. The regulator settings are left as they are; they are what the chip runs on. The radio domain’s clock gating maps must already allow the ACTIVE code (the chip package opens them first), as this applies that code.
pub fn init_active_state<R: hal.Registers>(pmu: &mut R)
WAKE_GPIO
Constant · Source
Wakeup sources, for
sleep’s masks andwakeup_cause.
pub const WAKE_GPIO: u32 = 1 << 2
WAKE_LP_TIMER
Constant · Source
pub const WAKE_LP_TIMER: u32 = 1 << 4
configure_sleep
Function · Source
Write the HP_SLEEP and LP_SLEEP states for a light sleep that keeps the CPU, memory, and registers but stops the crystal, the PLL, and the fast RC oscillator, as esp-hal’s and ESP-IDF’s light sleep do with the radios off and the flash powered, and make the HP_ACTIVE state the chip wakes into power the PLL, the crystal, and the bias and run the system clock.
save_sleep_statefirst,restore_sleep_stateafterwards.
pub fn configure_sleep<R: hal.Registers>(pmu: &mut R)
save_sleep_state
Function · Source
pub fn save_sleep_state<R: hal.Registers>(pmu: &mut R, saved: &mut[24]u32)
restore_sleep_state
Function · Source
pub fn restore_sleep_state<R: hal.Registers>(pmu: &mut R, saved: &[24]u32)
sleep
Function · Source
Ask the PMU for a light sleep that
wake’s sources end, or that it rejects if one ofreject’s is active already, and wait until it has done either: true if the chip slept, false if the request was rejected. The CPU stalls inside, on the poll of INT_RAW, while the chip sleeps. Timeout if the PMU never answers.SAFETY:
configure_sleepmust have run, interrupts must be masked, the system clock must run from the crystal, and nothing may use the PLL.
pub unsafe fn sleep<R: hal.Registers>(pmu: &mut R, wake: u32, reject: u32) -> bool!hal.Error
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
wakeup_cause
Function · Source
The wakeup sources that ended the last sleep, as WAKE_ bits.
pub fn wakeup_cause<R: hal.Registers>(pmu: &mut R) -> u32
wait_for_pll
Function · Source
Wait until the PLL runs stably again after a sleep. Timeout if it does not.
pub fn wait_for_pll<R: hal.Registers>(pmu: &mut R) -> void!hal.Error
use_rc_fast
Function · Source
Run the LP fast clock from RC_FAST for a sleep; return the setting for
restore_lp_fast_clock.
pub fn use_rc_fast<R: hal.Registers>(lp_clkrst: &mut R) -> u32
restore_lp_fast_clock
Function · Source
pub fn restore_lp_fast_clock<R: hal.Registers>(lp_clkrst: &mut R, conf: u32)
PIN_LIMIT
Constant · Source
The pins a dormant state can watch, GPIO 0 to PIN_LIMIT - 1: the ESP32-C6’s GPIO matrix has 31.
pub const PIN_LIMIT: u32 = 31
levels_present
Function · Source
The pins of
wakewhose level events hold now: they end a dormant state before it starts.levelshas bit n set while pin n is high.
pub fn levels_present(wake: &power.Wake, levels: u32) -> u32
events_seen
Function · Source
The pins of
wakewhose events happened while the chip slept with each pin armed for the opposite of its level inbefore: those inchangednow show the opposite level, so they show a level event of the new level or the edge between the two; those inpulsedshowed it and returned, latched in GPIO STATUS, so they also crossed both edges.
pub fn events_seen(wake: &power.Wake, before: u32, changed: u32, pulsed: u32) -> u32
arm_pins
Function · Source
Let each of
pinswake a light sleep when it leaves its level inlevels: every event a dormant state waits for begins with that change. Saves the pins’ PINn registers insavedfordisarm_pins.
pub fn arm_pins<R: hal.Registers>(gpio: &mut R, pins: u32, levels: u32, saved: &mut[31]u32)
latched_pins
Function · Source
The pins of
pinswhose armed level was seen, latched in GPIO STATUS.
pub fn latched_pins<R: hal.Registers>(gpio: &mut R, pins: u32) -> u32
levels
Function · Source
The levels of the GPIOs, bit n set while pin n is high.
pub fn levels<R: hal.Registers>(gpio: &mut R) -> u32
disarm_pins
Function · Source
Undo arm_pins, and clear the conditions it latched.
pub fn disarm_pins<R: hal.Registers>(gpio: &mut R, pins: u32, saved: &[31]u32)
save_lp_alarm
Function · Source
Target 0 as it was, for
restore_lp_alarm: the PMU’s timer wakeup needs that comparator, which an RTC alarm may be using.
pub fn save_lp_alarm<R: hal.Registers>(timer: &mut R) -> u64
restore_lp_alarm
Function · Source
pub fn restore_lp_alarm<R: hal.Registers>(timer: &mut R, saved: u64)
lp_ticks
Function · Source
The low-power timer’s count, 48 bits of slow clock cycles.
pub fn lp_ticks<R: hal.Registers>(timer: &mut R) -> u64
arm_lp_alarm
Function · Source
Wake a sleep with WAKE_LP_TIMER once the count reaches
ticks.
pub fn arm_lp_alarm<R: hal.Registers>(timer: &mut R, ticks: u64)
lp_alarm_reached
Function · Source
Whether the count has reached target 0, armed or not.
pub fn lp_alarm_reached<R: hal.Registers>(timer: &mut R) -> bool
disarm_lp_alarm
Function · Source
pub fn disarm_lp_alarm<R: hal.Registers>(timer: &mut R)
DEEP_SLEEP_RESET
Constant · Source
LP_CLKRST RESET_CAUSE after a wake from hibernation.
pub const DEEP_SLEEP_RESET: u32 = 0x05
WAKE_EXT1
Constant · Source
Wakeup sources of a hibernation, as SLP_WAKEUP_CNTL2 and SLP_WAKEUP_STATUS0 number them: the LP IO pads (EXT1), the LP timer (WAKE_LP_TIMER above), and the LP core.
pub const WAKE_EXT1: u32 = 1 << 1
WAKE_LP_CORE
Constant · Source
pub const WAKE_LP_CORE: u32 = 1 << 11
LP_PIN_LIMIT
Constant · Source
The pads EXT1 watches, GPIO 0 to LP_PIN_LIMIT - 1, the LP IO pads.
pub const LP_PIN_LIMIT: u32 = 8
configure_hibernation
Function · Source
Write the HP_SLEEP and LP_SLEEP states for a hibernation. With
keep_lp, the LP peripherals and the fast RC oscillator stay on, so the LP core can run and wake the chip; the LP fast clock must then run from that oscillator (use_rc_fast).
pub fn configure_hibernation<R: hal.Registers>(pmu: &mut R, keep_lp: bool)
release_power_domains
Function · Source
pub fn release_power_domains<R: hal.Registers>(pmu: &mut R)
prepare_hibernation_request
Function · Source
Everything
request_sleepwrites before SLP_WAKEUP_CNTL0, which the caller writes from SRAM: enablewake, reject nothing (a source already active ends the hibernation at once, as a reset), and clear the interrupts and the reject cause.
pub fn prepare_hibernation_request<R: hal.Registers>(pmu: &mut R, wake: u32)
SLEEP_REQUEST_REGISTER
Constant · Source
The PMU register that starts a sleep and its request bit, for the caller’s SRAM code.
pub const SLEEP_REQUEST_REGISTER: usize = SLP_WAKEUP_CNTL0
SLEEP_REQUEST_BIT
Constant · Source
pub const SLEEP_REQUEST_BIT: u32 = SLEEP_REQUEST
mark_deep_sleep_boot
Function · Source
Tell the boot ROM that the next boot ends a deep sleep and runs no wake stub, so it boots the firmware from flash as after a reset.
pub fn mark_deep_sleep_boot<R: hal.Registers>(lp_aon: &mut R)
arm_ext1
Function · Source
Arm EXT1 to end a hibernation when one of
pins(bit n for GPIO n, below LP_PIN_LIMIT) is at its level inlevels(bit set: high). Each pad moves to the LP IO MUX with the pulls IO MUX gave it, as input, and is held, so its level is defined while the HP system is off.
pub fn arm_ext1<A: hal.Registers, L: hal.Registers, M: hal.Registers>(lp_aon: &mut A, lp_io: &mut L, io_mux: &mut M, pins: u32, levels: u32)
ext1_status
Function · Source
The pads whose level ended the last hibernation through EXT1, bit n for GPIO n.
pub fn ext1_status<R: hal.Registers>(lp_aon: &mut R) -> u32
release_ext1
Function · Source
After a wake, give the pads EXT1 watched back to the HP system: release their holds, return them to IO MUX, and clear EXT1’s pads and status.
pub fn release_ext1<R: hal.Registers>(lp_aon: &mut R)
clear_wakeup_sources
Function · Source
After a wake, stop the wakeup sources so that none of them ends a later sleep it was not asked for.
pub fn clear_wakeup_sources<R: hal.Registers>(pmu: &mut R)