Multicore Words

Currently the only platform on which multicore execution is supported is the RP2040. On this platform cores communicate and synchronize via hardware spinlocks and hardware FIFO’s (i.e. mailboxes). On platforms other than the RP2040 multicore words exist in the dictionary but are merely stubs which will always raise exceptions when called.

Note that prior limitations to multicore operation on the RP2040 have been resolved, with there being no need to disable interrupt-driven serial IO, with tasks being able to be started arbitrarily on any core from a task on any core, with multitasking constructs being able to be used across cores, and with writing and erasing flash functioning properly when both cores are operational.

Multicore support in zeptoforth is largely implemented outside the zeptoforth kernel and is split between src/rp2040/forth/multicore.fs (on platforms other than RP2040 stubbed out in src/common/forth/multicore.fs) and src/common/forth/task.fs, with a bit of supporting functionality also in src/common/forth/systick.fs and src/rp2040/forth/erase.fs.

forth

Built into the kernel exists:

cpu-count

( – count )

Get the core count.

cpu-index

( – index )

Get the index of the core from which cpu-index was called.

cpu-offset

( – offset )

Return 4 times cpu-index.

sio-hook

( – addr )

Get the address of a hook for the current core which may be set to an xt ( u – ) to handle values written to that core’s FIFO by the other core; note that a value of 0 (the default value) means that values read from the core’s FIFO are discarded.

In src/common/forth/basic.fs, in forth, exists:

cpu-variable

( “global-name” “cpu-name” – )

Compile a one-cell-per-core variable into flash that has two words referring to it, a global-name which takes a core index when called and outputs the address for that core, and a cpu-name which returns its address for the current core.

multicore

In both src/rp2040/forth/multicore.fs and src/common/forth/multicore.fs, in multicore on all platforms, exists:

x-spinlock-out-of-range

( – )

Spinlock out of range exception.

x-core-out-of-range

( – )

Core out of range exception, i.e. core index not in range 0 <= core < cpu-count.

x-core-not-addressable

( – )

Core not addressable exception, i.e. invalid core for an operation carried out ont the current core.

In src/rp2040/forth/multicore.fs, in multicore on the rp2040 platform, exists:

sev

( – )

Signal an event to the other core.

wfe

( – )

Wait for an event.

SIO_IRQ_PROC0

( – irq )

SIO processor 0 IRQ index, i.e. 15.

SIO_IRQ_PROC1

( – irq )

SIO processor 1 RIQ index, i.e. 16.

FIFO_ST

( – addr )

FIFO status register; note that core 0 can see the read side of the 1 -> 0 FIFO and the write side of the 0 -> 1 FIFO; the converse is true of core 1

FIFO_ST_ROE

( – bit )

Sticky flag indicating the RX FIFO was read when empty; write to clear.

FIFO_ST_WOF

( – bit )

Sticky flag indicating the TX FIFO was written when full; write to clear.

FIFO_ST_VLD

( – bit )

Set if this core’s RX FIFO is not empty.

FIFO_WR

( – bit )

Write access from this core’s TX FIFO.

FIFO_RD

( – bit )

Read access to this core’s RX FIFO.

SPINLOCK

( index – addr )

Returns the address of a spinlock with a given index. Note that reading from an spinlock claims it if a value other than 0 is read (which will be the index of the spinlock), with a value of 0 indicating that the spinlock is already held, and writing to a spinlock releases it.

spinlock-count

( – count )

Returns the spinlock count, i.e. 32.

claim-spinlock

( spinlock-index – )

Claim a spinlock; no validation is carried out.

release-spinlock

( spinlock-index – )

Release a spinlock; no validation is carried out.

claim-same-core-spinlock

( – )

Claim a multitasker spinlock for the current core.

release-same-core-spinlock

( – )

Release a multitasker spinlock for the current core.

claim-other-core-spinlock

( core – )

Claim a multitasker spinlock for the specified core.

release-other-core-spinlock

( core – )

Release a multitasker spinlock for the specified core.

claim-all-core-spinlock

( – )

Claim all the multitasker spinlocks.

release-all-core-spinlock

( – )

Release all the multitasker spinlocks.

with-spinlock

( xt spinlock – )

Claim a spinlock while executing xt, releasing it afterwards

critical-with-spinlock

( xt spinlock – )

Claim a spinlock, enter a critical section, execute xt, release the spinlock, and then exit the critical section.

critical-with-other-core-spinlock

( xt core – )

Claim a multitasker spinlock for the specified core, enter a critical section, execute xt, release the spinlock, and then exit the critical section.

fifo-drain

( core – )

Drain a FIFO for inter-core communication; if core is outside the range 0 <= x < 2 x-core-out-of-range is raised; if core is equal to cpu-index x-core-not-addressable is raised.

fifo-push-blocking

( x core – )

Do a blocking push onto a FIFO for inter-core communication; if core is outside the range 0 <= x < 2 x-core-out-of-range is raised; if core is equal to cpu-index x-core-not-addressable is raised.

fifo-pop-blocking

( core – x )

Do a blocking pop from a FIFO for inter-core communication; if core is outside the range 0 <= x < 2 x-core-out-of-range is raised; if core is equal to cpu-index x-core-not-addressable is raised.

fifo-push-confirm

( x core – confirmed? )

Do a blocking push onto a FIFO for inter-core communication; if core is outside the range 0 <= x < 2 x-core-out-of-range is raised; if core is equal to cpu-index x-core-not-addressable is raised. Afterwards do a blocking pop from the FIFO for receiving fromt he same core and return whether the value pushed is the same as the value popped.

launch-aux-core

( vector-table stack-ptr rstack-ptr entry-xt core – )

Launch an auxiliary core, i.e. a core core other than core 0 and execute entry-xt on it with the return stack pointer rstack-ptr, the data stack pointer stack-ptr, and the vector table base vector-table. Note that it is not recommended that this be used by the user, rather the user should use spawn-aux-main in src/common/forth/task.fs.

with-hold-core

( xt – )

Hold the other core, execute the provided xt, release the other core even if an exception had been raised, and if an exception had been raised re-raise it.

In src/common/forth/multicore.fs, in multicore for all platforms other than rp2040, exists:

spinlock-count

( – count )

Returns the spinlock count, i.e. 0.

claim-spinlock

( spinlock-index – )

Drop spinlock-index.

release-spinlock

( spinlock-index – )

Drop spinlock-index.

claim-same-core-spinlock

( – )

This is a no-op.

release-same-core-spinlock

( – )

This is a no-op.

claim-other-core-spinlock

( core – )

Drop core.

release-other-core-spinlock

( core – )

Drop core.

claim-all-core-spinlock

( – )

This is a no-op.

release-all-core-spinlock

( – )

This is a no-op.

with-spinlock

( xt spinlock – )

Drop spinlock and execute xt.

critical-with-spinlock

( xt spinlock – )

Drop spinlock and execute xt in a critical section.

critical-with-other-core-spinlock

( xt core – )

Drop core and execute xt in a critical section.

test-set

( value addr – set? )

Atomically test a value at addr and set it to value if it was previously 0, and return whether it was previously 0.

test-set-raw

( value addr – set? )

Atomically test a value at addr and set it to value if it was previously 0, and return whether it was previously 0. This is different from test-set in that it assumes that interrupts were already disabled, and does not enable interrupts.

fifo-drain

( core – )

Placeholder for draining a FIFO for inter-core communication; this will always raise x-core-out-of-range.

fifo-push-blocking

( x core – )

Placeholder for doing a blocking push onto a FIFO for inter-core communication; this will always raise x-core-out-of-range.

fifo-pop-blocking

( core – x )

Placeholder for doing a blocking pop from a FIFO for inter-core communication; this will always raise x-core-out-of-range.

fifo-push-confirm

( x core – confirmed? )

Placeholder for attempting to send data on a FIFO and confirming that the same data is sent back; this will always raise x-core-out-of-range.

launch-aux-core

( xt stack-ptr rstack-ptr core – )

Placeholder for attempting to launch an auxiliary core; this will always raise x-core-out-of-range.

with-hold-core

( xt – )

This simply executes the provided xt.