API referencestd/embedded

std/embedded/chip/rp_power

Public declarations, types, methods, and source contracts for std/embedded/chip/rp_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/chip/rp_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
cortex_m std/embedded/cortex_m rp_power.dodo
cpu core/cpu rp_power.dodo
hal std/embedded/hal rp_power.dodo
power std/embedded/power rp_power.dodo
rp_rtc std/embedded/chip/rp_rtc rp_power.dodo

Layout

Struct · Source

The register offsets that differ between the chips.

pub struct Layout {
    // In the clocks block: WAKE_EN0 and SLEEP_EN0, each followed by its
    // second register.
    pub wake_en: usize
    pub sleep_en: usize
    // In the ROSC block: STATUS.
    pub rosc_status: usize
    // In IO_BANK0: DORMANT_WAKE_INTE0 and DORMANT_WAKE_INTS0, each the
    // first of one register per eight pins.
    pub dormant_wake_inte: usize
    pub dormant_wake_ints: usize
    // GPIOs that can wake the chip, 0 to pin_count - 1.
    pub pin_count: u32
}

read_clocks

Function · Source

A clock set from a pair of registers at offset and offset + 4.

pub fn read_clocks<R: hal.Registers>(block: &mut R, offset: usize) -> power.Clocks

write_clocks

Function · Source

Write a whole clock set to the pair of registers at offset.

pub fn write_clocks<R: hal.Registers>(block: &mut R, offset: usize, clocks: power.Clocks)

set_clocks

Function · Source

Set the bits of clocks in the pair at offset through the set alias, so other bits, and a concurrent change to them, stay as they are.

pub fn set_clocks<R: hal.Registers>(block: &mut R, offset: usize, clocks: power.Clocks)

clear_clocks

Function · Source

Clear the bits of clocks in the pair at offset through the clear alias.

pub fn clear_clocks<R: hal.Registers>(block: &mut R, offset: usize, clocks: power.Clocks)

mode

Function · Source

The calling core’s mode, from its SCR.SLEEPDEEP.

pub fn mode() -> power.Mode

set_mode

Function · Source

pub fn set_mode(mode: power.Mode)

sleep

Function · Source

Wait once for an interrupt in the calling core’s mode.

pub fn sleep()

check_wake

Function · Source

InvalidInput unless wake names a pin or a timeout, and only pins below pin_count.

pub fn check_wake(wake: &power.Wake, pin_count: u32) -> void!hal.Error

arm_wake

Function · Source

Let wake’s events restart a dormant chip, through IO_BANK0’s set aliases. Bits of other pins stay as they are.

pub fn arm_wake<R: hal.Registers>(io: &mut R, layout: &Layout, wake: &power.Wake)

disarm_wake

Function · Source

Undo arm_wake.

pub fn disarm_wake<R: hal.Registers>(io: &mut R, layout: &Layout, wake: &power.Wake)

woken_pins

Function · Source

The pins of wake whose events DORMANT_WAKE_INTS shows, bit n for pin n.

pub fn woken_pins<R: hal.Registers>(io: &mut R, layout: &Layout, wake: &power.Wake) -> u64

stop_oscillators

Function · Source

Stop the ROSC if it runs, stop the XOSC until a wake event, wait until the crystal is stable again, and restart the ROSC if it ran. Timeout if the crystal does not become stable.

SAFETY: clk_ref and clk_sys must run from the XOSC, nothing may use the ROSC or a PLL, interrupts must be masked, and the caller must own both oscillators’ registers.

pub unsafe fn stop_oscillators<X: hal.Registers, O: hal.Registers>(xosc: &mut X, rosc: &mut O, layout: &Layout) -> void!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

MAX_SYSTEM_DIVIDER

Constant · Source

The largest whole-number divider of clk_sys this code uses when it runs from the crystal.

pub const MAX_SYSTEM_DIVIDER: u32 = 256

SystemClock

Struct · Source

How clk_sys runs: from PLL_SYS with a VCO at vco_hz divided by post1 and post2, or from clk_ref, the crystal, divided by divider with PLL_SYS stopped. hz is the result.

pub struct SystemClock {
    pub hz: u32
    pub from_pll: bool
    pub vco_hz: u32
    pub post1: u32
    pub post2: u32
    pub divider: u32
}

plan_system_clock

Function · Source

The settings for clk_sys at exactly hz from a crystal_hz crystal. The default rate, a VCO of default_vco_hz divided by default_post1 and default_post2, keeps the settings take() uses. A rate the crystal divides into by a whole number up to MAX_SYSTEM_DIVIDER runs from the crystal with PLL_SYS stopped, which saves the most; another runs from PLL_SYS with the slowest VCO that reaches it exactly. InvalidInput for 0, above max_hz, or a rate neither reaches exactly.

pub fn plan_system_clock(crystal_hz: u32, hz: u32, default_vco_hz: u32, default_post1: u32, default_post2: u32, max_hz: u32) -> SystemClock!hal.Error

DOMAIN_SRAM1

Constant · Source

The power domains in POWMAN’s STATE order: SRAM1 (SRAM4 to SRAM9, the upper 264 KiB), SRAM0 (SRAM0 to SRAM3, the lower 256 KiB), the XIP cache and boot RAM, and the switched core.

pub const DOMAIN_SRAM1: u32 = 1 << 0

DOMAIN_SRAM0

Constant · Source

pub const DOMAIN_SRAM0: u32 = 1 << 1

DOMAIN_XIP

Constant · Source

pub const DOMAIN_XIP: u32 = 1 << 2

DOMAIN_SWCORE

Constant · Source

pub const DOMAIN_SWCORE: u32 = 1 << 3

POWER_UP_SOURCES

Constant · Source

GPIO events that can power the chip up, PWRUP0 to PWRUP3.

pub const POWER_UP_SOURCES: u32 = 4

SCRATCH_WORDS

Constant · Source

SCRATCH0 to SCRATCH6 are the program’s; SCRATCH7 holds the record of a power-down: RECORD_MAGIC, the domains kept, and whether the always-on timer ticked from the crystal before.

pub const SCRATCH_WORDS: u32 = 7

PowerDown

Struct · Source

The PWRUP sources of a power-down and its timeout, from plan_power_down.

pub struct PowerDown {
    // The PWRUPn values, without ENABLE, for n below `count`.
    pub sources: [4]u32
    pub count: u32
    // 0 for none.
    pub timeout_ms: u64
}

plan_power_down

Function · Source

The PWRUP sources for wake: one per pin event, as a GPIO’s level or edge, low or falling, high or rising. InvalidInput if wake is empty, names a pin from pin_count up, or more than POWER_UP_SOURCES events.

pub fn plan_power_down(wake: &power.Wake, pin_count: u32) -> PowerDown!hal.Error

enter_power_down

Function · Source

Arm plan’s sources, keep the SRAM domains in retain (DOMAIN_SRAM0 and DOMAIN_SRAM1) powered, and request a power state with the switched core and the XIP domain off. A timeout fires at alarm_ms on the always-on timer, which replaces its alarm. lposc_hz, unless 0, is the low-power oscillator’s frequency: a timer ticking from the crystal changes to it now, as the power sequencer would, and the record says so for take_power_down_wake. The switched core powers off once both processors wait for an interrupt. Busy if the power manager ignores the request, as for a power-up request already pending, InvalidInput if it refuses the state, Timeout if it never waits for the processors; the sources are disarmed then.

SAFETY: powman must be the power manager’s registers, interrupts must be masked, and nothing else may use its timer, PWRUP, STATE, or SCRATCH7 registers meanwhile.

pub unsafe fn enter_power_down<R: hal.Registers>(powman: &mut R, plan: &PowerDown, retain: u32, alarm_ms: u64, lposc_hz: u32) -> void!hal.Error

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

power_down_cancelled

Function · Source

True once a power-up request has cancelled the power-down that enter_power_down requested.

pub fn power_down_cancelled<R: hal.Registers>(powman: &mut R) -> bool

cancel_power_down

Function · Source

Undo enter_power_down after it returned or failed: disarm the sources and the alarm, and forget the record.

pub fn cancel_power_down<R: hal.Registers>(powman: &mut R)

PowerDownWake

Struct · Source

What take_power_down_wake found.

pub struct PowerDownWake {
    // The reset was the restart after a power-down that enter_power_down
    // requested.
    pub happened: bool
    // What powered the chip up, as a power.Power.dormant result: the pins
    // of the PWRUP sources that did, and power.BY_TIME for the alarm.
    pub woken: u64
    // The SRAM domains kept powered, DOMAIN_SRAM0 and DOMAIN_SRAM1.
    pub retained: u32
    // The always-on timer ticked from the crystal before.
    pub crystal_tick: bool
}

take_power_down_wake

Function · Source

After a reset, report a power-down that enter_power_down requested, and forget its record and PWRUP sources whatever the reset was.

SAFETY: as for enter_power_down.

pub unsafe fn take_power_down_wake<R: hal.Registers>(powman: &mut R) -> PowerDownWake

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Search every guide, reference page, and API declaration.