Four-Character Codes

A four-character 7-bit ASCII word could carry the signal “functor” and arity—lending the concept from functional and logic programming. Suppose that core 1 does some work. Perhaps it interacts with some external device, does some computation, and presents the results as a signal with some arguments to core 0.

Talking to an I²C peripheral might be one example. Core 1 arrives at a point in time where it wants to push \(\text{RDY}_1(x, y)\) to core 0, which will in turn record and publish to a USB communication endpoint, which also takes time to complete. This is just one of many possible scenarios, of course. The \(\text{RDY}_1\) signal has two arguments, arity of 2 words carrying two 32-bit floating-point numbers, for example.

Four 7-bit ASCII characters leaves four bits of a 32-bit word unused. Four bits can encode the \(0\le arity\le2^4-1\). In short, a 32-bit word passing through the SIO FIFO can simultaneously carry four 7-bit ASCII characters, good for a signal name, and an arity counter between zero and 15. Consecutive words can carry a signal’s additional 32-bit arguments, if any.

/*!
 * \brief Creates a FOURCC word from four 7-bit characters.
 *
 * \param a Most significant byte.
 * \param b Second byte.
 * \param c Third byte.
 * \param d Least significant byte.
 */
#define MULTICORE_FIFO_FOURCC(a, b, c, d) \
  (((uint32_t)((a) & 0x7f) << 24) | ((uint32_t)((b) & 0x7f) << 16) | ((uint32_t)((c) & 0x7f) << 8) | (uint32_t)((d) & 0x7f))

/*!
 * \brief Masks out arity bits to extract the bare FOURCC code from a word.
 */
#define MULTICORE_FIFO_FOURCC_FROM_WORD(word) ((word) & 0x7f7f7f7fUL)

Arity and the FOURCC

Since arity lives in the most-significant bit position within each of the four bytes, its encoding and decoding requires some bit shifting. A simple helper macro can implement the functional mapping between \(bit\) position and amount of required shifting within a 32-bit word.

/*!
 * \brief Computes the shift that places arity bit \p bit into a FOURCC high-bit position.
 *
 * \param bit Arity bit index (0–3).
 *
 * \return Shift amount for bit \p bit.
 *
 * \details Places each arity bit at the high bit of one FOURCC character:
 *
 * - Bit 0 → position 7  (shift = 7)
 * - Bit 1 → position 15 (shift = 14)
 * - Bit 2 → position 23 (shift = 21)
 * - Bit 3 → position 31 (shift = 28)
 *
 * For arity 3 (0b011), bits 7 and 15 are set, yielding 0x00008080.
 */
#define MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(bit) ((((bit) & 0xf) << 3) + 7 - ((bit) & 0xf))

The translation applies to where an arity bit lives in its FIFO word and where it lives in the arity value, e.g. 7 and 0 respectively for the least-significant arity bit because \(7=0\times8+7-0\). Two mapping macros that apply the shift appear below.

/*!
 * \brief Encodes a 4-bit payload arity into the high-bit positions of a FOURCC word.
 *
 * \param arity Payload arity in words (0–15).
 *
 * \return A 32-bit mask to OR with a bare FOURCC code.
 */
#define MULTICORE_FIFO_WORD_FROM_ARITY(arity)                                                                                      \
  ((((arity) & 0x8) << MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(3)) | (((arity) & 0x4) << MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(2)) | \
   (((arity) & 0x2) << MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(1)) | (((arity) & 0x1) << MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(0)))

/*!
 * \brief Decodes the 4-bit payload arity from the high-bit positions of a FOURCC word.
 *
 * \param word A FOURCC word with arity encoded in its high bits.
 *
 * \return Payload arity in words.
 */
#define MULTICORE_FIFO_ARITY_FROM_WORD(word)                                                                                     \
  ((((word) >> MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(3)) & 0x8) | (((word) >> MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(2)) & 0x4) | \
   (((word) >> MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(1)) & 0x2) | (((word) >> MULTICORE_FIFO_FOURCC_ARITY_BIT_SHIFT(0)) & 0x1))

Pushing a FOURCC with Arity

Pushing a FOURCC and arity to the multicore FIFO then just becomes a trivial mask and shift operation. Given some code and arity, for example “RDY1” of arity 2, calling multicore_fifo_push_fourcc_blocking(MULTICORE_FIFO_FOURCC('R', 'D', 'Y', '1'), 2U) will push \(5244B931_{16}=52445931_{16}\lor00008000_{16}\) to the FIFO.

/*!
 * \brief Pushes the FOURCC functor word (with encoded arity) into the multicore FIFO.
 *
 * \param fourcc FOURCC code to push.
 * \param arity  Number of payload words to follow (0–15); encodes this value
 *               into the high bit of each FOURCC character.
 *
 * \warning Does \b not push payload words. The caller must push \p arity additional
 * words immediately after, creating a critical section that spans both operations.
 */
void multicore_fifo_push_fourcc_blocking(uint32_t fourcc, size_t arity) {
  multicore_fifo_push_blocking(MULTICORE_FIFO_FOURCC_FROM_WORD(fourcc) | MULTICORE_FIFO_WORD_FROM_ARITY(arity));
}

ASCII codes for R, D, Y and 1 are:

• R: 0x52
• D: 0x44
• Y: 0x59
• 1: 0x31

Notice that arity is encoded in the most significant bit of each character’s byte. So \(2\) shifts to bit 15, which is the most significant bit of the second character’s byte, resulting in \(00008000_{16}\).

/*!
 * \brief Pushes the FOURCC functor word and all payload words atomically.
 *
 * \param fourcc FOURCC code to push.
 * \param arity  Number of payload words (0–15).
 * \param args   Array of \p arity 32-bit payload words.
 *
 * \note Disables interrupts for the duration of the push to prevent
 * interleaving with interrupt-driven FIFO writes, ensuring the other
 * core receives a coherent, complete message.
 */
void multicore_fifo_push_fourcc_args_blocking(uint32_t fourcc, size_t arity, const uint32_t *args) {
  while (!multicore_fifo_wready()) {
    tight_loop_contents();
  }
  uint32_t status = save_and_disable_interrupts();
  multicore_fifo_push_fourcc_blocking(fourcc, arity);
  while (arity--) {
    multicore_fifo_push_blocking(*args);
    args++;
  }
  restore_interrupts(status);
}

Popping

Popping the FIFO is not quite as simple as pushing, but still straightforward. The receiving core pops the FIFO under interrupts, and decodes the FOURCC and arity from the popped word. The receiving core can then pop the appropriate number of arguments from the FIFO based on the decoded arity.

It requires a simple structure to hold the decoded FOURCC and arity, plus any extra arguments, and a simple function to perform the decoding.

/*!
 * \brief Holds the decoder state and buffer for one FOURCC message.
 */
struct multicore_fifo_fourcc {
  /*!
   * \brief Decoder state: counts words received so far for the current message.
   *
   * \details The arity bits in the first functor word set the expected total.
   * The field increments as each word arrives:
   *
   * - 0: idle, ready to accept a new functor word.
   * - 1 to total−1: accumulating payload words.
   * - equals total: message complete, ready to dispatch.
   */
  size_t arity;

  /*!
   * \brief Message buffer: words[0] carries the functor; words[1..arity] carry the payload.
   */
  uint32_t words[16];
};

/*!
 * \brief Feeds one word into the FOURCC decoder.
 *
 * \param fourcc Decoder state to update.
 * \param word   Next word from the FIFO. Supply the functor word first;
 *               subsequent calls deliver payload words.
 *
 * \return 0 when the decoder assembles a complete message; negative while
 *         still accumulating words.
 */
int multicore_fifo_fill_fourcc(struct multicore_fifo_fourcc *fourcc, uint32_t word) {
  fourcc->words[fourcc->arity] = word;
  const size_t arity = multicore_fifo_fourcc_arity(fourcc);
  int rc = fourcc->arity - arity;
  if (rc < 0) {
    fourcc->arity++;
  } else {
    fourcc->arity = 0U;
  }
  return rc;
}

Core 0 Sets Up Its SIO Interrupt Handler

The example is very simple. Core 0 sets up its SIO interrupt handler after draining the core-0 FIFO. It then launches core 1 and enters an infinite loop. All the work by core 0 runs at interrupt time; see the SIO Interrupt Handler section below.

int main() {
  stdio_init_all();

  multicore_fifo_drain();
  irq_set_exclusive_handler(SIO_FIFO_IRQ_NUM(0), core0_sio_irq);
  irq_set_enabled(SIO_FIFO_IRQ_NUM(0), true);
  multicore_launch_core1(core1_entry);

  for (;;) {
    tight_loop_contents();
  }
}

The drain proves necessary because the SIO FIFO is not guaranteed to be empty at reset. It may contain some random data, which could cause the interrupt handler to misinterpret it as a valid message. Draining ensures that the interrupt handler starts with a clean slate.

Core 1 Pushes Signals to Core 0

Core 1 pushes a zero-arity “COR1” message, then three consecutive delayed “TICK” messages with the current microsecond timestamp as an argument, and finally a zero-arity “DEAD” message before halting itself.

static void core1_entry(void) {
  multicore_fifo_push_fourcc_blocking(MULTICORE_FIFO_FOURCC('C', 'O', 'R', '1'), 0);
  for (size_t count = 3U; count; count--) {
    sleep_ms(1000);
    multicore_fifo_push_fourcc_arg_blocking(MULTICORE_FIFO_FOURCC('T', 'I', 'C', 'K'), time_us_32());
  }
  multicore_fifo_push_fourcc_blocking(MULTICORE_FIFO_FOURCC('D', 'E', 'A', 'D'), 0);
}

SIO Interrupt Handler

The interrupt handler pops and fills the FOURCC structure which decodes the stacked words one by one.

static void core0_sio_irq(void) {
  while (multicore_fifo_rvalid()) {
    if (multicore_fifo_pop_fourcc_blocking(&core0_fourcc) == 0) {
      const uint32_t cccc = multicore_fifo_fourcc_peek(&core0_fourcc);
      const size_t arity = multicore_fifo_fourcc_arity(&core0_fourcc);
      const uint32_t *const args = multicore_fifo_fourcc_args(&core0_fourcc);

      printf("Received FOURCC by core %u: %c%c%c%c with arity %zu and args:",
             /* by core */ get_core_num(),
             /* first FOURCC */ (cccc >> 24) & 0xFF,
             /* second FOURCC */ (cccc >> 16) & 0xFF,
             /* third FOURCC */ (cccc >> 8) & 0xFF,
             /* fourth FOURCC */ cccc & 0xFF, arity);
      for (size_t i = 0; i < arity; ++i) {
        printf(" 0x%08x", args[i]);
      }
      printf("\n");

      switch (cccc) {
      case MULTICORE_FIFO_FOURCC('C', 'O', 'R', '1'):
        switch (arity) {
        case 0:
          printf("Core 1 has started.\n");
        }
        break;
      case MULTICORE_FIFO_FOURCC('T', 'I', 'C', 'K'):
        switch (arity) {
        case 1:
          printf("Core 1 ticked at %u microseconds.\n", args[0]);
        }
        break;
      case MULTICORE_FIFO_FOURCC('D', 'E', 'A', 'D'):
        switch (arity) {
        case 0:
          printf("Core 1 is dead.\n");
          multicore_reset_core1();
          multicore_launch_core1(core1_entry);
        }
        break;
      default:
        printf("Unknown FOURCC received.\n");
      }
    }
  }
  multicore_fifo_clear_irq();
}

The switch implementation matches the four-character code and the arity. This is proper since the same FOURCC could have various alternative arities.

Serial Monitor

Output on the serial monitor appears as follows:

Received FOURCC by core 0: COR1 with arity 0 and args:
Core 1 has started.
Received FOURCC by core 0: TICK with arity 1 and args: 0x000f44ea
Core 1 ticked at 1000682 microseconds.
Received FOURCC by core 0: TICK with arity 1 and args: 0x001e8737
Core 1 ticked at 2000695 microseconds.
Received FOURCC by core 0: TICK with arity 1 and args: 0x002dc978
Core 1 ticked at 3000696 microseconds.
Received FOURCC by core 0: DEAD with arity 0 and args:
Core 1 is dead.

This sequence repeats indefinitely because core 0 resets and relaunches core 1 after it sees a “DEAD” signal from core 1.

This is the primary take away: the SIO FIFO carries signals with variable arguments. The arguments need to be 32 bits in size, or at least padded to 32 bits. The argument or arguments flexibly carry data along with a signal through a core-synchronised hardware unit.