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_rtc"
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 |
rp_rtc.dodo |
time |
std/time |
rp_rtc.dodo |
CALENDAR_LAST_YEAR
Constant · Source
The RTC’s largest year and clock.
pub const CALENDAR_LAST_YEAR: i32 = 4095
CALENDAR_MAX_HZ
Constant · Source
pub const CALENDAR_MAX_HZ: u32 = 65_536
CALENDAR_MIN_HZ
Constant · Source
The slowest clock
calendar_divideraccepts: the RTC takes a few of its cycles to apply each change, which this code waits for.
pub const CALENDAR_MIN_HZ: u32 = 1_000
TICK_CRYSTAL
Constant · Source
AonTimer.tick_source values.
pub const TICK_CRYSTAL: u32 = 1
TICK_LPOSC
Constant · Source
pub const TICK_LPOSC: u32 = 2
TICK_CLOCK_INPUT
Constant · Source
An external clock on a GPIO in place of the LPOSC.
pub const TICK_CLOCK_INPUT: u32 = 3
TICK_INPUT
Constant · Source
An external 1 kHz tick on a GPIO.
pub const TICK_INPUT: u32 = 4
LPOSC_HZ
Constant · Source
The LPOSC’s nominal frequency, and the frequencies AonTimer accepts for it or a clock in its place: its divider has a 6-bit integer part, in kilohertz, of at least 2 (12.10.5.2).
pub const LPOSC_HZ: u32 = 32_768
LPOSC_MIN_HZ
Constant · Source
pub const LPOSC_MIN_HZ: u32 = 2_000
LPOSC_MAX_HZ
Constant · Source
pub const LPOSC_MAX_HZ: u32 = 63_999
Calendar
Struct · Source
The RP2040’s RTC over
R. Implements hal.Rtc and hal.RtcAlarm with a resolution of one second.
pub struct Calendar<R: hal.Registers>: hal.Rtc + hal.RtcAlarm {
// Private implementation fields omitted.
}
Calendar.new
Function · Source
Take the RTC, fresh from its reset, counting from a
clock_hzclock (clk_rtc): stopped, with no alarm. InvalidInput for a clock of 0 or above CALENDAR_MAX_HZ. SAFETY:registersmust be the RTC’s own, and nothing else may touch them while the Calendar exists.
pub unsafe fn new(registers: R, clock_hz: u32) -> Calendar<R>!hal.Error from(registers)
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
Calendar.is_set
Function · Source
pub fn is_set(&mut self) -> bool!hal.Error
Calendar.resolution_ms
Function · Source
pub fn resolution_ms(&self) -> u32
Calendar.now_ms
Function · Source
pub fn now_ms(&mut self) -> u64!hal.Error
Calendar.set_ms
Function · Source
Stop the RTC, load the time, and start it again. The new time shows a few of the RTC’s clock cycles later, which this waits for. InvalidInput past CALENDAR_LAST_YEAR.
pub fn set_ms(&mut self, time_ms: u64) -> void!hal.Error
Calendar.set_alarm_ms
Function · Source
Fire at the first whole second at or after
time_ms. The RTC only matches its exact second, so a time already reached forces the interrupt instead.
pub fn set_alarm_ms(&mut self, time_ms: u64) -> void!hal.Error
Calendar.alarm_fired
Function · Source
True from the alarm’s second until clear_alarm. The RTC raises its interrupt only during that second; the time decides afterwards.
pub fn alarm_fired(&mut self) -> bool!hal.Error
Calendar.clear_alarm
Function · Source
pub fn clear_alarm(&mut self) -> void!hal.Error
Calendar.listen
Function · Source
Raise the RTC’s interrupt when the alarm fires.
pub fn listen(&mut self)
Calendar.ignore
Function · Source
Stop raising the interrupt; alarm_fired still reports.
pub fn ignore(&mut self)
Calendar.is_listening
Function · Source
pub fn is_listening(&mut self) -> bool
Calendar.is_pending
Function · Source
True while the interrupt is raised: the alarm’s second, or a time set past it.
pub fn is_pending(&mut self) -> bool
Calendar.pause
Function · Source
Stop counting, so that its clock can change, and return whether it was running. The time holds meanwhile; a stopped RTC has none.
pub fn pause(&mut self) -> bool!hal.Error
Calendar.resume
Function · Source
Count from a
clock_hzclock from now on, and run again ifrunning, from the time it held: up to a second is lost, as the RTC’s divider starts again. InvalidInput for a clock of 0 or above CALENDAR_MAX_HZ; nothing changes then.
pub fn resume(&mut self, clock_hz: u32, running: bool) -> void!hal.Error
Calendar.release
Function · Source
Stop the clock and the alarm, and give back the registers.
pub fn release(self) -> R from(self)
AonTimer
Struct · Source
The RP2350’s always-on timer over
R. Implements hal.Rtc and hal.RtcAlarm with a resolution of one millisecond.
pub struct AonTimer<R: hal.Registers>: hal.Rtc + hal.RtcAlarm {
// Private implementation fields omitted.
}
AonTimer.new
Function · Source
Take the power manager’s timer, ticking from a
crystal_hzcrystal. A timer that is running already, set before a reset, keeps its time and tick; a stopped one is set up to tick from the crystal. Either way its alarm is disarmed. InvalidInput for a crystal below 1 kHz or above 65.5 MHz. SAFETY:registersmust be the power manager’s, and nothing else may write its timer, alarm, or interrupt registers while the AonTimer exists.
pub unsafe fn new(registers: R, crystal_hz: u32) -> AonTimer<R>!hal.Error from(registers)
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
AonTimer.is_set
Function · Source
pub fn is_set(&mut self) -> bool!hal.Error
AonTimer.resolution_ms
Function · Source
pub fn resolution_ms(&self) -> u32
AonTimer.now_ms
Function · Source
pub fn now_ms(&mut self) -> u64!hal.Error
AonTimer.set_ms
Function · Source
Stop the timer, load the time, and start it from the crystal. The alarm stays armed; a time set past it fires it. Timeout if the counter never shows the new time.
pub fn set_ms(&mut self, time_ms: u64) -> void!hal.Error
AonTimer.set_alarm_ms
Function · Source
The timer’s alarm fires once the time is at or past it, so a time already reached fires at once.
pub fn set_alarm_ms(&mut self, time_ms: u64) -> void!hal.Error
AonTimer.alarm_fired
Function · Source
pub fn alarm_fired(&mut self) -> bool!hal.Error
AonTimer.clear_alarm
Function · Source
The alarm fires for as long as the time is past it while it is armed, so this disarms it before acknowledging it.
pub fn clear_alarm(&mut self) -> void!hal.Error
AonTimer.listen
Function · Source
Raise POWMAN_IRQ_TIMER when the alarm fires.
pub fn listen(&mut self)
AonTimer.ignore
Function · Source
Stop raising the interrupt; alarm_fired still reports.
pub fn ignore(&mut self)
AonTimer.is_listening
Function · Source
pub fn is_listening(&mut self) -> bool
AonTimer.tick_source
Function · Source
Where the tick comes from: TICK_CRYSTAL, TICK_LPOSC, TICK_CLOCK_INPUT, or TICK_INPUT. A stopped timer reports the source it starts from.
pub fn tick_source(&mut self) -> u32
AonTimer.reference_pin
Function · Source
The GPIO that EXT_TIME_REF selects as the time reference, for a tick of TICK_CLOCK_INPUT or TICK_INPUT: 12, 20, 14, or 22.
pub fn reference_pin(&mut self) -> u32
AonTimer.use_crystal
Function · Source
Tick from a
crystal_hzcrystal, as take() sets up: the most precise source, but the crystal stops while the chip is dormant or powered down. InvalidInput for a crystal below 2 kHz or above 65.5 MHz, Timeout if the switch never shows.
pub fn use_crystal(&mut self, crystal_hz: u32) -> void!hal.Error
AonTimer.use_lposc
Function · Source
Tick from the on-chip low-power oscillator, running at
lposc_hz: LPOSC_HZ nominally, but it varies by up to 20% between chips and with voltage and temperature, so pass a measured frequency, such as the one each RP2350 stores in OTP (the chip package reads it). It keeps running while the chip is dormant or powered down. InvalidInput outside LPOSC_MIN_HZ to LPOSC_MAX_HZ, Timeout if the switch never shows.
pub fn use_lposc(&mut self, lposc_hz: u32) -> void!hal.Error
AonTimer.use_clock_input
Function · Source
Tick from an external clock of
clock_hz, typically a 32.768 kHz oscillator, on the GPIO that EXT_TIME_REF sourcesourceselects (ext_time_source names them). It replaces the LPOSC everywhere, including the power manager’s own clock while the switched core is off, and keeps running in every power state. The pin must be an input already. InvalidInput for a source above 3 or a clock outside LPOSC_MIN_HZ to LPOSC_MAX_HZ, Timeout if the switch never shows.
pub fn use_clock_input(&mut self, source: u32, clock_hz: u32) -> void!hal.Error
AonTimer.use_tick_input
Function · Source
Tick from an external 1 kHz tick, counted on its falling edges, on the GPIO that EXT_TIME_REF source
sourceselects. Pulses and gaps must each last longer than the LPOSC’s period, 31 us. It keeps running in every power state; the switch may advance the time by up to a millisecond. The pin must be an input already. InvalidInput for a source above 3, Timeout if the switch never shows.
pub fn use_tick_input(&mut self, source: u32) -> void!hal.Error
AonTimer.release
Function · Source
Disarm the alarm and stop its interrupt, and give back the registers. The timer keeps counting.
pub fn release(self) -> R from(self)
ext_time_source
Function · Source
The EXT_TIME_REF source that selects GPIO
pinas the always-on timer’s time reference: GPIO 12, 20, 14, and 22 are sources 0 to 3 (RP2350 datasheet 12.10.7). InvalidInput for another pin.
pub fn ext_time_source(pin: u32) -> u32!hal.Error
calendar_divider
Function · Source
The divider for clk_rtc from a GPIO clock of
input_hz, so that the RTC counts from a whole number of hertz, CALENDAR_MIN_HZ to CALENDAR_MAX_HZ: the smallest that divides the input exactly. InvalidInput if none does.
pub fn calendar_divider(input_hz: u32) -> u32!hal.Error
CalendarAlarm
Struct · Source
What a timed dormant state borrows from the RP2040’s RTC, to give back.
pub struct CalendarAlarm {
// Private implementation fields omitted.
}
calendar_borrow_alarm
Function · Source
Borrow the RTC’s alarm to end a dormant state at least
timeout_msfrom now: it matches a whole second, later by up to a second, as the RTC’s time has no fractions. Its interrupt is enabled, as the oscillators wake on it. Busy if the RTC is not running.SAFETY:
rtcmust be the RTC’s registers, interrupts must be masked, and nothing else may use them until calendar_return_alarm.
pub unsafe fn calendar_borrow_alarm<R: hal.Registers>(rtc: &mut R, timeout_ms: u64) -> CalendarAlarm!hal.Error
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
calendar_alarm_due
Function · Source
Whether the RTC has reached the borrowed alarm’s second.
pub fn calendar_alarm_due<R: hal.Registers>(rtc: &mut R, saved: &CalendarAlarm) -> bool
calendar_return_alarm
Function · Source
Put back the alarm calendar_borrow_alarm borrowed.
SAFETY: as for calendar_borrow_alarm.
pub unsafe fn calendar_return_alarm<R: hal.Registers>(rtc: &mut R, saved: CalendarAlarm) -> void!hal.Error
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
aon_running
Function · Source
Whether the always-on timer runs.
pub fn aon_running<R: hal.Registers>(powman: &mut R) -> bool
aon_now
Function · Source
The always-on timer’s time, read as AonTimer.now_ms does.
pub fn aon_now<R: hal.Registers>(powman: &mut R) -> u64
aon_arm_alarm
Function · Source
Arm the always-on timer’s alarm for
time_ms, replacing its alarm.
pub fn aon_arm_alarm<R: hal.Registers>(powman: &mut R, time_ms: u64)
aon_tick_from_lposc
Function · Source
Move a running timer’s tick from the crystal to the LPOSC, at
lposc_hzunless 0 (which keeps the frequency it has), as the power sequencer does before the crystal stops. Timeout if the switch never shows.
pub fn aon_tick_from_lposc<R: hal.Registers>(powman: &mut R, lposc_hz: u32) -> void!hal.Error
aon_tick_from_crystal
Function · Source
Move a running timer’s tick back to the crystal.
pub fn aon_tick_from_crystal<R: hal.Registers>(powman: &mut R) -> void!hal.Error
AonAlarm
Struct · Source
What a timed dormant state borrows from the RP2350’s always-on timer, to give back.
pub struct AonAlarm {
// Private implementation fields omitted.
}
aon_borrow_alarm
Function · Source
Borrow the always-on timer’s alarm to end a dormant state
timeout_msfrom now. A tick from the crystal, which stops while dormant, moves to the LPOSC atlposc_hz(as for aon_tick_from_lposc) until aon_return_alarm. The alarm’s interrupt stays off: the alarm itself wakes the oscillators (RP2350 datasheet 6.5.3.1). Busy if the timer is not running, Timeout if the tick does not move.SAFETY:
powmanmust be the power manager’s registers, interrupts must be masked, and nothing else may use the timer until aon_return_alarm.
pub unsafe fn aon_borrow_alarm<R: hal.Registers>(powman: &mut R, timeout_ms: u64, lposc_hz: u32) -> AonAlarm!hal.Error
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
aon_alarm_fired
Function · Source
Whether the borrowed alarm has fired.
pub fn aon_alarm_fired<R: hal.Registers>(powman: &mut R) -> bool
aon_return_alarm
Function · Source
Put back the alarm, interrupt, and tick that aon_borrow_alarm borrowed. An alarm whose time has passed meanwhile fires as soon as it is armed again. Timeout if the tick does not move back.
SAFETY: as for aon_borrow_alarm.
pub unsafe fn aon_return_alarm<R: hal.Registers>(powman: &mut R, saved: AonAlarm) -> void!hal.Error
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.