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
offsetandoffset + 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
clocksin the pair atoffsetthrough 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
clocksin the pair atoffsetthrough 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
wakenames a pin or a timeout, and only pins belowpin_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
wakewhose 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_hzdivided bypost1andpost2, or from clk_ref, the crystal, divided bydividerwith PLL_SYS stopped.hzis 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
hzfrom acrystal_hzcrystal. The default rate, a VCO ofdefault_vco_hzdivided bydefault_post1anddefault_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, abovemax_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 ifwakeis empty, names a pin frompin_countup, 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 inretain(DOMAIN_SRAM0 and DOMAIN_SRAM1) powered, and request a power state with the switched core and the XIP domain off. A timeout fires atalarm_mson 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:
powmanmust 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.