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_multicore"
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_multicore.dodo |
cpu |
core/cpu |
rp_multicore.dodo |
executor |
std/embedded/executor |
rp_multicore.dodo |
hal |
std/embedded/hal |
rp_multicore.dodo |
mem |
core/mem |
rp_multicore.dodo |
mmio |
core/mmio |
rp_multicore.dodo |
ptr |
core/ptr |
rp_multicore.dodo |
sync |
std/embedded/sync |
rp_multicore.dodo |
CORE_COUNT
Constant · Source
pub const CORE_COUNT: u32 = 2
SPINLOCK_COUNT
Constant · Source
pub const SPINLOCK_COUNT: u32 = 32
DOORBELL_COUNT
Constant · Source
pub const DOORBELL_COUNT: u32 = 8
CORE_LOCK
Constant · Source
The spinlock std/embedded/sync’s sections take once core 1 runs; never handed out by Spinlocks.
pub const CORE_LOCK: u32 = 31
MIN_STACK_BYTES
Constant · Source
The smallest stack
Core1.startaccepts, in bytes, besides the task.
pub const MIN_STACK_BYTES: usize = 256
LOCKOUT_ATTEMPTS
Constant · Source
Polls of the lockout’s mailbox before a core that does not answer is reported with Timeout: tens of milliseconds, far longer than a short critical section or interrupt handler. And attempts to take the lockout while the other core holds it before
lockoutreports Busy; between them this core lets the other’s request in, so it is parked meanwhile.
pub const LOCKOUT_ATTEMPTS: u32 = 1_000_000
LOCKOUT_REQUEST
Constant · Source
The lockout mailbox, in SRAM (the runtime’s dodo_lockout_mailbox): the request number the locking core writes, 0 for none, and the one the parked core acknowledged.
pub const LOCKOUT_REQUEST: usize = 0
LOCKOUT_ACKNOWLEDGE
Constant · Source
pub const LOCKOUT_ACKNOWLEDGE: usize = 4
LOCKOUT_FORCE_STRIDE
Constant · Source
PROC1_INTF follows PROC0_INTF by this many bytes in IO_QSPI on both chips.
pub const LOCKOUT_FORCE_STRIDE: usize = 12
core1_running
Function · Source
Whether core 1 runs a task from Core1.start, and so may be executing from flash:
lockouton core 0 parks it only while it does. Core 1 waiting in the boot ROM, before it is started or after it is stopped, does not count.
pub fn core1_running() -> bool
Chip
Struct · Source
What differs between the RP2040 and the RP2350, from their chip packages.
pub struct Chip {
// The power-on state machine's base address, and core 1's bit in its
// FRCE_OFF register.
pub psm_base: usize
pub core1_bit: u32
// The FIFO interrupt of core 0 and of core 1.
pub core0_fifo_irq: u32
pub core1_fifo_irq: u32
// Spinlocks that must not be handed out, one bit each.
pub reserved_locks: u32
// The doorbell interrupt, if the chip has doorbells.
pub doorbell_irq: Option<u32>
// How one core interrupts the other for the lockout.
pub lockout: LockoutLine
}
LockoutLine
Struct · Source
The lockout’s interrupt (see “The lockout”): IO_QSPI’s base address, the offset of its PROC0_INTF register (PROC1_INTF follows by LOCKOUT_FORCE_STRIDE), the bit to force there, which must be the one the chip runtime’s dodo_lockout_handler clears, and IO_IRQ_QSPI’s number.
pub struct LockoutLine {
pub qspi_base: usize
pub force: usize
pub bit: u32
pub irq: u32
}
Cores
Struct · Source
The parts the chip’s take() hands out.
pub struct Cores {
pub core1: Core1
pub fifos: Fifos
pub spinlocks: Spinlocks
pub doorbells: Doorbells
}
take
Function · Source
The parts for
chip. SAFETY: call once, from the chip’s take(), so that each part is the only one of its kind.
pub unsafe fn take(chip: Chip) -> Cores
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
reset_spinlocks
Function · Source
Unlock every spinlock not in
reserved, as at power-up, for a program started by a reset that left them locked, such as a debugger’s. SAFETY: core 1 must not be running, and nothing may hold a lock.
pub unsafe fn reset_spinlocks(reserved: u32)
Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.
core_id
Function · Source
The number of the core running this code: 0 or 1.
pub fn core_id() -> u32
Core1
Struct · Source
Core 1, handed out once by the chip’s take().
pub struct Core1 {
// Private implementation fields omitted.
}
Core1.start
Function · Source
Run
task.run()on core 1, with the top ofstackas its stack, and return a handle that keeps core 1 running until it is dropped or stopped. The task, a value with a publicrun(self)method, moves into the stack’s top; besides it, the stack needs MIN_STACK_BYTES and whatever the task’s calls use. On the RP2350 a deeper stack faults, so the chip’s panic hook reports it; the RP2040 cannot detect that.Core 1 is restarted first, so it starts the same way every time, and words it wrote to core 0 before are discarded. Call this on core 0. InvalidInput if the stack is too small, Unsupported on core 1, and Timeout or Bus if core 1’s boot ROM does not answer as it should.
pub fn start<T>(&mut self, stack: &mut[u64], task: T) -> Running!hal.Error from(self, stack)
Running
Struct · Source
Core 1 running a task, from Core1.start. Dropping the handle stops core 1, as
stopdoes.
pub struct Running {
// Private implementation fields omitted.
}
Running.is_finished
Function · Source
True once the task’s run method has returned; core 1 then sleeps.
pub fn is_finished(&self) -> bool
Running.stop
Function · Source
Stop core 1 wherever it is by holding it in reset, which frees its stack and lets Core1 start it again. Its task is not dropped, so peripherals it owned stay claimed, and a spinlock it held stays locked. Words already in the FIFOs stay there.
pub fn stop(self)
hold
Function · Source
Hold core 1 in reset, through the power-on state machine registers
psmwhose FRCE_OFF bitcore1_bitis core 1’s: it stops at once, wherever it is. Reading the bit back makes sure the write took effect.
pub fn hold<P: hal.Registers>(psm: &mut P, core1_bit: u32) -> void!hal.Error
release
Function · Source
Let core 1, held by
hold, out of reset. Its boot ROM empties core 1’s FIFO end and writes a 0 to this core’s when it is ready forlaunch. Words core 1 wrote before are discarded first. Timeout if the 0 does not come.
pub fn release<S: hal.Registers, P: hal.Registers>(sio: &mut S, psm: &mut P, core1_bit: u32) -> void!hal.Error
launch
Function · Source
Send core 1’s boot ROM the launch sequence through the SIO registers
sio: 0, 0, 1, then the vector table, stack pointer, and entry point (with the Thumb bit) that core 1 starts with. The boot ROM echoes each word; a wrong echo starts the sequence over, and the zeros, sent after emptying this core’s FIFO end, bring the boot ROM back to its start.notifywakes the other core fromwfeafter each write. Timeout if the boot ROM stops answering; Bus if it keeps answering wrongly.
pub fn launch<S: hal.Registers>(sio: &mut S, vector_table: u32, stack_pointer: u32, entry: u32, notify: fn()) -> void!hal.Error
Fifos
Struct · Source
Each core’s end of the FIFOs, handed out by
claim.
pub struct Fifos {
// Private implementation fields omitted.
}
Fifos.claim
Function · Source
One of the two ends, for the core that will use it: claim one for core 0 and one to move into core 1’s task. Both are alike, since each core reaches only its own end; a third claim is Busy.
pub fn claim(&mut self) -> Fifo!hal.Error
Fifos.release
Function · Source
Give back an end, which stops raising its signal.
pub fn release(&mut self, fifo: Fifo)
Fifo
Struct · Source
One core’s end of the FIFOs between the cores, claimed from
Fifos. A Fifo always reaches the end of the core that uses it: what it writes, the other core reads, and it reads what the other core wrote. Each direction holds 8 words on the RP2040 and 4 on the RP2350;writewaits for room andreadfor a word.
pub struct Fifo {
// Private implementation fields omitted.
}
Fifo.try_write
Function · Source
Write
wordfor the other core if there is room, and wake it fromread; false if the FIFO is full.
pub fn try_write(&mut self, word: u32) -> bool
Fifo.write
Function · Source
Write
word, waiting while the FIFO is full: until the other core reads.
pub fn write(&mut self, word: u32)
Fifo.try_read
Function · Source
The next word the other core wrote, if there is one.
pub fn try_read(&mut self) -> Option<u32>
Fifo.read
Function · Source
The next word the other core wrote, sleeping (
wfe) until there is one.
pub fn read(&mut self) -> u32
Fifo.can_read
Function · Source
True if a word is waiting to be read.
pub fn can_read(&self) -> bool
Fifo.can_write
Function · Source
True if there is room to write.
pub fn can_write(&self) -> bool
Fifo.drain
Function · Source
Discard the words waiting to be read; returns how many there were.
pub fn drain(&mut self) -> u32
Fifo.irq
Function · Source
This core’s FIFO interrupt, raised while a word is waiting: SIO_IRQ_PROC0 or SIO_IRQ_PROC1 on the RP2040, SIO_IRQ_FIFO on either RP2350 core.
pub fn irq(&self) -> u32
Fifo.set_signal
Function · Source
Raise
signalon this core whenever the other core has written, so that a task of this core’s executor waits for words without polling: take the signal, then read withtry_readuntil none is left. The chip runtime’s handler of this core’s FIFO interrupt raises the signal and holds the interrupt back until the nexttry_read,read, ordrain. A program’s own@interrupthandler for the FIFO interrupt replaces this.
pub fn set_signal(&mut self, signal: &executor.Signal)
Fifo.clear_signal
Function · Source
Stop raising the signal, and the interrupt.
pub fn clear_signal(&mut self)
Spinlocks
Struct · Source
The hardware spinlocks, handed out by number. On the RP2350, locks 0 to 4, 8, 9, and 12 to 17 are never handed out: writes to other SIO registers unlock them (erratum RP2350-E2). Locks 18 to 31 work on both chips.
pub struct Spinlocks {
// Private implementation fields omitted.
}
Spinlocks.claim
Function · Source
Claim lock
number, 0 to 31. InvalidInput for another number or one this chip reserves; Busy if it is claimed already.
pub fn claim(&mut self, number: u32) -> Spinlock!hal.Error
Spinlocks.claim_free
Function · Source
Claim the lowest-numbered usable lock that is free. Busy if none is.
pub fn claim_free(&mut self) -> Spinlock!hal.Error
Spinlocks.release
Function · Source
Give back a lock so it can be claimed again. Clones of it keep working and must no longer be used.
pub fn release(&mut self, lock: Spinlock)
Spinlocks.is_usable
Function · Source
True if lock
numberexists on this chip and is not reserved.
pub fn is_usable(&self, number: u32) -> bool
Spinlock
Struct · Source
A hardware spinlock: either core may hold it, and while one does, the other waits in
lock. Give each core its own copy withclone. Holding it also masks interrupts on the holding core, so a handler on that core cannot wait for the lock its own core holds. Hold it briefly: the other core spins meanwhile.static mut TOTAL: u32 = 0
guard := lock.lock() unsafe { TOTAL += 1 } core.drop(guard)
pub struct Spinlock {
// Private implementation fields omitted.
}
Spinlock.number
Function · Source
pub fn number(&self) -> u32
Spinlock.lock
Function · Source
Take the lock, waiting while the other core holds it, and keep it until the guard is dropped. Waiting on the lock this core holds already never ends.
pub fn lock(&self) -> Guard
Spinlock.try_lock
Function · Source
Take the lock if no core holds it.
pub fn try_lock(&self) -> Option<Guard>
Spinlock.is_locked
Function · Source
True if a core holds the lock now.
pub fn is_locked(&self) -> bool
Spinlock.clone
Function · Source
The same lock, for the other core.
pub fn clone(&self) -> Spinlock
Guard
Struct · Source
A held spinlock, from Spinlock.lock or try_lock. Dropping it releases the lock, then unmasks interrupts if they were enabled before.
pub struct Guard {
// Private implementation fields omitted.
}
Lockout
Struct · Source
The other core parked in SRAM, from
lockout; see “The lockout” in the package comment. Interrupts stay masked on this core until it is dropped, which lets the other core go on.
pub struct Lockout {
// Private implementation fields omitted.
}
Lockout.is_parked
Function · Source
True if this Lockout parked the other core; false if there was no need: on core 0 while core 1 runs no task, or inside another Lockout of this core, which keeps it parked.
pub fn is_parked(&self) -> bool
lockout
Function · Source
Park the other core in SRAM, with its interrupts masked, until the returned Lockout is dropped, so that this core can take the flash away from execute-in-place; see “The lockout”. On core 0 this parks core 1 only while it runs a task (core1_running); on core 1 it always parks core 0. This core’s interrupts are masked meanwhile too. Inside another Lockout of this core it changes nothing.
Timeout if the other core does not answer within LOCKOUT_ATTEMPTS polls, for example while it keeps its interrupts masked, and Busy if it holds the lockout itself and does not give it up in time. Either way nothing is parked.
pub fn lockout() -> Lockout!hal.Error
request_lockout
Function · Source
Ask the other core to park: write
request, nonzero and different from the last, into the mailbox registersmailbox, then setbitin its PROCn_INTF register atforcein the IO_QSPI registersqspi, through the atomic set alias, and wait for the request to come back in the mailbox’s acknowledgement word. Timeout after LOCKOUT_ATTEMPTS polls, once the request is withdrawn: its word cleared and the bit with it, so a handler that still runs returns at once.
pub fn request_lockout<Q: hal.Registers, M: hal.Registers>(qspi: &mut Q, mailbox: &mut M, force: usize, bit: u32, request: u32) -> void!hal.Error
end_lockout
Function · Source
Let the parked core go on: clear the request in the mailbox registers
mailbox, after this core’s accesses to the flash.
pub fn end_lockout<M: hal.Registers>(mailbox: &mut M)
Doorbells
Struct · Source
The RP2350’s eight doorbells, handed out by number. A doorbell interrupts the other core without passing data: ring it on one core, and the other core’s SIO_IRQ_BELL is raised until that core acknowledges the ring. It suits waking the other core’s executor, as a signal does on one core, without using the FIFO. On the RP2040, which has no doorbells,
claimreturns Unsupported.
pub struct Doorbells {
// Private implementation fields omitted.
}
Doorbells.claim
Function · Source
Claim doorbell
number, 0 to 7. Unsupported on a chip without doorbells, InvalidInput for another number, Busy if claimed already.
pub fn claim(&mut self, number: u32) -> Doorbell!hal.Error
Doorbells.claim_free
Function · Source
Claim the lowest-numbered doorbell that is free. Busy if none is.
pub fn claim_free(&mut self) -> Doorbell!hal.Error
Doorbells.is_supported
Function · Source
True if the chip has doorbells.
pub fn is_supported(&self) -> bool
Doorbells.release
Function · Source
Give back a doorbell; it stops raising its signal on the calling core. Clones of it keep working and must no longer be used.
pub fn release(&mut self, bell: Doorbell)
Doorbell
Struct · Source
One doorbell between the cores, claimed from
Doorbells. Give the other core its own copy withclone: whichever core rings it interrupts the other one.const WAKE: executor.Signal = executor.Signal { id: 4 }
On core 0, before starting core 1’s task with
bell.clone(): bell.set_signal(&WAKE) … await WAKE.wait() // in an async task of core 0’s executorOn core 1: bell.ring()
pub struct Doorbell {
// Private implementation fields omitted.
}
Doorbell.number
Function · Source
pub fn number(&self) -> u32
Doorbell.ring
Function · Source
Ring the doorbell on the other core. Rings before it acknowledges are one ring.
pub fn ring(&self)
Doorbell.withdraw
Function · Source
Withdraw a ring of this core’s that the other core has not acknowledged yet.
pub fn withdraw(&self)
Doorbell.is_ringing
Function · Source
True if the other core rang the doorbell and this core has not acknowledged it.
pub fn is_ringing(&self) -> bool
Doorbell.answer
Function · Source
Acknowledge a ring on this core: true if the doorbell was ringing.
pub fn answer(&mut self) -> bool
Doorbell.set_signal
Function · Source
Raise
signalon this core whenever the other core rings: the chip runtime’s handler of this core’s SIO_IRQ_BELL acknowledges the ring and raises the signal, so a task of this core’s executor waits withawait signal.wait()orsignal.take(cx). A program’s own@interrupt(SIO_IRQ_BELL)handler replaces this.
pub fn set_signal(&mut self, signal: &executor.Signal)
Doorbell.clear_signal
Function · Source
Stop raising the signal on this core.
pub fn clear_signal(&self)
Doorbell.irq
Function · Source
The doorbell interrupt, SIO_IRQ_BELL, which each core has.
pub fn irq(&self) -> u32
Doorbell.clone
Function · Source
The same doorbell, for the other core.
pub fn clone(&self) -> Doorbell