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/cortex_m"
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 |
cortex_m.dodo |
mmio |
core/mmio |
cortex_m.dodo |
MAX_IRQS
Constant · Source
Interrupt numbers below this exist on some Cortex-M: Armv7-M and Armv8-M allow 496 (Armv8-M even 480 per security state), Armv6-M 32.
pub const MAX_IRQS: u32 = 496
SYSTICK_MAX_RELOAD
Constant · Source
The largest SysTick reload value: the counter is 24 bits wide.
pub const SYSTICK_MAX_RELOAD: u32 = 0xFF_FFFF
enable
Function · Source
Let interrupt
irqreach the core. Its handler runs whenever the peripheral raises it and interrupts are not masked.
pub fn enable(irq: u32)
disable
Function · Source
Keep interrupt
irqfrom reaching the core. It may still become pending.
pub fn disable(irq: u32)
is_enabled
Function · Source
pub fn is_enabled(irq: u32) -> bool
pend
Function · Source
Make interrupt
irqpending as if its peripheral had raised it, for example to run its handler from software or in a self-test.
pub fn pend(irq: u32)
unpend
Function · Source
Forget that interrupt
irqis pending, so its handler does not run for what happened so far.
pub fn unpend(irq: u32)
is_pending
Function · Source
pub fn is_pending(irq: u32) -> bool
set_priority
Function · Source
Set the priority of interrupt
irq: 0 is the most urgent, and a handler is interrupted only by more urgent ones. Cores implement only the high bits of the byte: two on the Cortex-M0+ (0x00, 0x40, 0x80, 0xC0), four on the RP2350’s Cortex-M33. Every interrupt starts at 0.
pub fn set_priority(irq: u32, priority: u8)
priority
Function · Source
pub fn priority(irq: u32) -> u8
pend_sv
Function · Source
Make the PendSV exception pending. Its handler,
@interrupt(PendSV_Handler), runs once no more urgent handler is active: the usual way to defer work out of an urgent interrupt.
pub fn pend_sv()
set_vector_table
Function · Source
Run handlers from the vector table at
addressfrom now on, for example a table in RAM whose entries the program changes.SAFETY:
addressholds a complete vector table for this chip (initial stack pointer, then one handler address with the Thumb bit set per exception and interrupt), aligned to its size rounded up to a power of two and at least 128 bytes, as@aligncan arrange; it stays valid while it is installed.
pub unsafe fn set_vector_table(address: usize)
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
vector_table
Function · Source
The installed vector table’s address.
pub fn vector_table() -> usize
systick_start
Function · Source
Start SysTick counting down from
reloadto 0 at the processor clock, then reloading, so a period is reload + 1 cycles. Withinterrupt, each wrap runs@interrupt(SysTick_Handler). InvalidInput unless reload is 1 to SYSTICK_MAX_RELOAD.
pub fn systick_start(reload: u32, interrupt: bool) -> void!hal.Error
systick_stop
Function · Source
pub fn systick_stop()
systick_value
Function · Source
The current count, from the reload value down to 0.
pub fn systick_value() -> u32
systick_wrapped
Function · Source
True once the counter has reached 0 since the last call: reading the flag clears it.
pub fn systick_wrapped() -> bool
enable_interrupts
Function · Source
Unmask interrupts (
cpsie i), as at reset.SAFETY: this ends any critical section the caller is in, including a
hal.Criticalthat is still alive.
pub unsafe fn enable_interrupts()
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
set_deep_sleep
Function · Source
Make this core’s later sleeps (
wfi,wfe) deep sleeps, or light ones again. What a deep sleep stops is up to the chip; std/embedded/power describes it, and a chip’s Power implements that protocol on top of this. Each core has its own setting.
pub fn set_deep_sleep(deep: bool)
deep_sleep
Function · Source
True when this core’s sleeps are deep sleeps (SCR.SLEEPDEEP).
pub fn deep_sleep() -> bool
set_sleep_on_exit
Function · Source
Sleep again whenever the last active handler returns to thread mode, instead of resuming the program (SCR.SLEEPONEXIT): for firmware that does all its work in interrupt handlers. Thread mode runs again only once this is turned off, by a handler.
pub fn set_sleep_on_exit(on: bool)
sleep_on_exit
Function · Source
pub fn sleep_on_exit() -> bool
set_event_on_pend
Function · Source
Let an interrupt that becomes pending wake
wait_for_eventeven while it is disabled in the NVIC or masked (SCR.SEVONPEND), so a program polls a peripheral’s flag betweenwfes without a handler.
pub fn set_event_on_pend(on: bool)
wait_for_event
Function · Source
Sleep until an event (
wfe): an interrupt, orsend_eventon another core.
pub fn wait_for_event()
send_event
Function · Source
Signal an event to every core (
sev), waking one inwait_for_event.
pub fn send_event()
data_barrier
Function · Source
Complete every memory access before the next one starts (
dsb), for example after disabling an interrupt or before sleeping.
pub fn data_barrier()
memory_barrier
Function · Source
Order memory accesses before and after (
dmb), without waiting for them.
pub fn memory_barrier()
instruction_barrier
Function · Source
Fetch the following instructions again (
isb), so they see a changed vector table, interrupt mask, or code written to RAM.
pub fn instruction_barrier()
interrupts_masked
Function · Source
The interrupt mask (PRIMASK): true while interrupts are masked, as in a
hal.Criticalsection.
pub fn interrupts_masked() -> bool
active_exception
Function · Source
The exception number of the running handler (IPSR): 0 in thread mode, 15 in SysTick_Handler, and 16 + n in the handler of IRQ n.
pub fn active_exception() -> u32