API referencestd/embedded

std/embedded/chip/rp_multicore

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

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_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.start accepts, 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 lockout reports 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: lockout on 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 of stack as its stack, and return a handle that keeps core 1 running until it is dropped or stopped. The task, a value with a public run(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 stop does.

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 psm whose FRCE_OFF bit core1_bit is 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 for launch. 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. notify wakes the other core from wfe after 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; write waits for room and read for a word.

pub struct Fifo {
    // Private implementation fields omitted.
}

Fifo.try_write

Function · Source

Write word for the other core if there is room, and wake it from read; 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 signal on 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 with try_read until none is left. The chip runtime’s handler of this core’s FIFO interrupt raises the signal and holds the interrupt back until the next try_read, read, or drain. A program’s own @interrupt handler 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 number exists 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 with clone. 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 registers mailbox, then set bit in its PROCn_INTF register at force in the IO_QSPI registers qspi, 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, claim returns 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 with clone: 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 executor

On 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 signal on 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 with await signal.wait() or signal.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

Search every guide, reference page, and API declaration.