API referencestd/embedded

std/embedded/power

Public declarations, types, methods, and source contracts for std/embedded/power.

On this page

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 for Pin.listen the 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 Wake can name, 0 to MAX_PINS - 1. Chips with fewer refuse the others in dormant.

pub const MAX_PINS: u32 = 63

BY_TIME

Constant · Source

The bit of a dormant result 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 events of pin, a combination of LEVEL_LOW, LEVEL_HIGH, FALLING_EDGE, and RISING_EDGE. Traps if the pin is MAX_PINS or more, or events is 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 pin that wake, 0 for none.

pub fn events(&self, pin: u32) -> u32

Wake.after_ms

Function · Source

Also wake once milliseconds have passed, counted from the call to dormant, 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 dormant result woken says the timeout ended it.

pub fn by_time(woken: u64) -> bool

woken_pins

Function · Source

The pins of the dormant result woken, 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 keep running, 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 pin shows events: dormant with 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: dormant with 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 clocks holds.

pub fn count(clocks: Clocks) -> u32

Search every guide, reference page, and API declaration.