API referencestd/embedded

std/embedded/chip/rp_rtc

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

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_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_divider accepts: 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_hz clock (clk_rtc): stopped, with no alarm. InvalidInput for a clock of 0 or above CALENDAR_MAX_HZ. SAFETY: registers must 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_hz clock from now on, and run again if running, 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_hz crystal. 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: registers must 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_hz crystal, 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 source source selects (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 source selects. 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 pin as 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_ms from 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: rtc must 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_hz unless 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_ms from now. A tick from the crystal, which stops while dormant, moves to the LPOSC at lposc_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: powman must 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.

Search every guide, reference page, and API declaration.