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/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 |
power.dodo |
Mode
Enum · Source
What a core does when it waits for an interrupt.
pub enum Mode {
// Only the core stops; every clock keeps running. The mode at reset.
Sleep,
// The clocks outside the sleep set stop too, until the core wakes.
DeepSleep
}
Clocks
Type alias · Source
A set of clock gates, one bit each, named by the chip package.
pub type Clocks = u64
NO_CLOCKS
Constant · Source
The empty set.
pub const NO_CLOCKS: Clocks = 0
LEVEL_LOW
Constant · Source
Pin events that end a dormant state, for
Wake.on: the pin is low or high, or it fell or rose. The RP2040 and RP2350 number their pin events forPin.listenthe same way.
pub const LEVEL_LOW: u32 = 1 << 0
LEVEL_HIGH
Constant · Source
pub const LEVEL_HIGH: u32 = 1 << 1
FALLING_EDGE
Constant · Source
pub const FALLING_EDGE: u32 = 1 << 2
RISING_EDGE
Constant · Source
pub const RISING_EDGE: u32 = 1 << 3
MAX_PINS
Constant · Source
The pins a
Wakecan name, 0 to MAX_PINS - 1. Chips with fewer refuse the others indormant.
pub const MAX_PINS: u32 = 63
BY_TIME
Constant · Source
The bit of a
dormantresult that says the wake’s timeout ended it. The other bits are pins, bit n for pin n, below MAX_PINS.
pub const BY_TIME: u64 = 1u64 << 63
Wake
Struct · Source
The pin events, and the timeout, that end a dormant state:
wake := power.Wake.new() wake.on(BUTTON_PIN, power.FALLING_EDGE) wake.after_ms(60_000) woken := b.power.dormant(&wake)! if power.by_time(woken) { … }
Claim each pin as an input first, with the pull it needs, so its level is defined while the chip is dormant.
pub struct Wake {
// Private implementation fields omitted.
}
Wake.new
Function · Source
No pins and no timeout yet.
pub fn new() -> Wake
Wake.on
Function · Source
Also wake on
eventsofpin, a combination of LEVEL_LOW, LEVEL_HIGH, FALLING_EDGE, and RISING_EDGE. Traps if the pin is MAX_PINS or more, oreventsis empty or names something else.
pub fn on(&mut self, pin: u32, events: u32)
Wake.forget
Function · Source
Stop waking on any event of
pin.
pub fn forget(&mut self, pin: u32)
Wake.events
Function · Source
The events of
pinthat wake, 0 for none.
pub fn events(&self, pin: u32) -> u32
Wake.after_ms
Function · Source
Also wake once
millisecondshave passed, counted from the call todormant, replacing an earlier timeout. A chip whose clock is coarser than a millisecond rounds it up, so the chip may wake later, never earlier. Traps for 0.
pub fn after_ms(&mut self, milliseconds: u64)
Wake.forget_timeout
Function · Source
Stop waking on a timeout.
pub fn forget_timeout(&mut self)
Wake.timeout_ms
Function · Source
The timeout in milliseconds, 0 for none.
pub fn timeout_ms(&self) -> u64
Wake.pins
Function · Source
The pins with events, bit n for pin n.
pub fn pins(&self) -> u64
Wake.is_empty
Function · Source
True with neither pins nor a timeout, which nothing could end.
pub fn is_empty(&self) -> bool
by_time
Function · Source
Whether the
dormantresultwokensays the timeout ended it.
pub fn by_time(woken: u64) -> bool
woken_pins
Function · Source
The pins of the
dormantresultwoken, without BY_TIME.
pub fn woken_pins(woken: u64) -> u64
Power
Interface · Source
A chip’s low-power controls. Chip packages implement it, boards hand it out as
Board.power, and std/embedded/hal/fake.Power implements it for tests. See the package comment.
pub interface Power {
// What waiting for an interrupt does on the calling core.
fn mode(&self) -> Mode
// Make every later wait on the calling core, by `sleep`,
// `cpu.wait_for_interrupt`, an alarm, or an executor, sleep this deeply.
fn set_mode(&mut self, mode: Mode)
// Wait once for an interrupt in the current mode. To wait for something
// an interrupt handler records, check it inside a `hal.Critical`
// section and sleep there: an interrupt that becomes pending in between
// still ends the sleep, and its handler runs once the section ends.
fn sleep(&mut self)
// The clocks that run while the program runs.
fn enabled_clocks(&self) -> Clocks
// Start `clocks` again. Bits the chip does not have are ignored.
fn enable_clocks(&mut self, clocks: Clocks)
// Stop `clocks` while the program runs. InvalidInput if the chip lacks
// one or the program cannot run without it, Busy if a claimed
// peripheral uses one; nothing changes then.
fn disable_clocks(&mut self, clocks: Clocks) -> void!hal.Error
// Stop the clocks of every peripheral the chip manages that nothing has
// claimed, and return them. Claiming one starts its clocks again.
fn disable_unused_clocks(&mut self) -> Clocks
// The clocks that keep running while the cores deep-sleep.
fn sleep_clocks(&self) -> Clocks
// Keep only `clocks` running while the cores deep-sleep. Include the
// clocks of whatever should wake the core, such as the chip's
// ALARM_CLOCKS for a timer alarm. Bits the chip does not have are
// ignored.
fn set_sleep_clocks(&mut self, clocks: Clocks)
// Stop every oscillator until one of `wake`'s events or its timeout,
// then restart the clocks and return what woke the chip: the pins whose
// events did, bit n for pin n (none if a level ended before the chip was
// running again), and BY_TIME if the timeout passed. An edge or level
// present already ends it at once. InvalidInput if `wake` is empty or
// names a pin the chip lacks, Busy if a running peripheral cannot be
// stopped, such as a USB connection, or if the clock that would count
// the timeout has no time set, Unsupported if the chip has no dormant
// state, or for a timeout, no clock that runs while it is dormant.
fn dormant(&mut self, wake: &Wake) -> u64!hal.Error
}
deep_sleep
Function · Source
Deep-sleep once with only
keeprunning, then restore the mode and sleep set as they were: for a program that otherwise sleeps lightly.
pub fn deep_sleep<P: Power>(power: &mut P, keep: Clocks)
dormant_until
Function · Source
Dormant until
pinshowsevents:dormantwith a one-pin Wake.
pub fn dormant_until<P: Power>(power: &mut P, pin: u32, events: u32) -> u64!hal.Error
dormant_for
Function · Source
Dormant for
milliseconds:dormantwith only a timeout. Returns BY_TIME once it has passed.
pub fn dormant_for<P: Power>(power: &mut P, milliseconds: u64) -> u64!hal.Error
count
Function · Source
How many gates
clocksholds.
pub fn count(clocks: Clocks) -> u32