Part V · Writing firmware

FW-8 The CPU and the COP

On this page

Draft. This edition has only the part of FW-8 that every contributor needs: which core runs what, and the rules for memory both cores touch. Threads, scheduling and the kernel come in a later edition. The layout below is the one 0.8.0 ships, decided on 2026-11-07 (0.8.0-rc.6).

The PP5022 has two ARM7TDMI cores, identical in silicon, sharing one bus and one memory map. Rockbox calls them the CPU and the COP (coprocessor), and so does this reference. The names describe a convention, not a difference: either core can run any code. What differs is that the CPU starts at reset and the COP waits until the CPU wakes it. [rockbox-derived]

Getting the split between the two cores right is the largest design question in ProkBox. This chapter says where it stands, so that you put new work on the right core.

8.1 Why the split is hard#

The two cores have separate caches, and the PP5022 does nothing to keep them coherent. [silicon] If both cores use the same data through their caches, each can see a stale copy, and the result is wrong without any error. Every byte that crosses between the cores therefore has to be written back from one cache and dropped from the other at exactly the right moment, or kept in memory that neither caches.

That has a direct consequence for design: the fewer things that cross between the cores, the fewer places that can go wrong. A layout where the cores exchange a few messages a second is far easier to keep correct than one where hundreds of functions are called across. The project learnt this the hard way. An earlier plan, known as 19-9, put the user interface on the COP; it needed 238 cross-core call stubs, and two faults on real hardware came from data shared between the cores by accident. [silicon] That plan is retired.

docs/data-paths.md records which part of the player can move bytes where, and what has been proven. Read it before touching anything that crosses the cores.

8.2 The layout in 0.8.0#

In release 0.8.0 both ends of the audio pipeline run on the COP: the decoder, and the audio output. The CPU runs everything else, including the audio processing between them.

CoreRuns in 0.8.0
CPUThe user interface, the file system, the disk, USB, the BCM2722 driver and playback control. In the audio pipeline, the producers: the codec thread’s DSP (equaliser, resampler, speed, replaygain) and pcmbuf_insert, the beep and the Clicker. Every start, stop, pause and seek of the output
COPThe codec’s decoding, as a job per run. The audio output: the interrupt of DMA channel 0 (source 26, taken as a FIQ) and its refill (fiq_playback), the mixer’s frame mix, and the PCM buffer’s consumer callback

This goes past Apple’s own firmware, which also runs its audio engine on the second core but keeps the audio DMA’s interrupt on the main core. [apple-RE]

The decode (since 0.8.0-rc.5):

The output (since 0.8.0-rc.6):

Both fallbacks keep music playing. They are a safety net that logs loudly, not a mode to ship on.

The user interface stays on the CPU. The machinery of the retired 19-9 plan (HAVE_UI_THREAD_SPLIT) is compiled only into developer builds; a release contains none of it.

How it was checked: on 2026-11-07, sitting 4gh-b8 on a 5.5G passed the p1 and pcop rows, which take the audio DMA’s interrupt on the COP and return it to the CPU, and the heap row, an album decoding on the COP and then on the CPU with the heap checked every two seconds. [silicon] That proves the route on the bench; the release layout is soaked before 0.8.0 ships. The code statements in this chapter were checked by reading the 0.8.0-rc.6 source; docs/changes-from-rockbox.md §2.67 and §2.70 record the two changes.

8.3 What comes next#

The hybrid target decided on 2026-11-06 kept the audio output on the CPU and moved the producers to the COP. 0.8.0 does the opposite for the output end: the output is on the COP, and the producers, the DSP and pcmbuf_insert, are still on the CPU. Moving them as well would leave the CPU with no audio work at all while music plays. The open design is in docs/design/layoutA-engine-brief.md, with the comparison of layouts in docs/design/core-layout-decision.md; read both before working on the audio pipeline.

8.4 Memory both cores touch#

Every track now crosses between the cores twice: the decode’s job on the way in, and the PCM buffer on the way out. These are the rules for memory both cores touch, and the reason for each:

The first rule came from a real defect: the codec’s tag record (its “id3”, with the track’s length and elapsed time) was written uncached by the codec on the COP and through its cache by the CPU, so each could undo the other’s writes. It was found by reading code and shown by a host model, not seen on a player, and 0.8.0 fixes it: the record now has lines of its own and both cores reach it uncached (apps/codec_id3.c, docs/changes-from-rockbox.md §2.68).

docs/design/cop-shared-state.md lists every object both cores touch, for the decode and for the output, with a verdict for each and the open questions; the output’s open questions are settled by the soak before release. Read it, and add a row to it, before you change anything the codec, the COP’s worker or the audio FIQ can reach.

What to do in your own code:

8.5 Gotchas#

FW-8.5.1. A memory allocation while music plays can stop the music. Playback keeps the rest of the heap as its audio buffer. If code allocates memory while a track is playing, the heap takes the space from the audio buffer, and playback stops and restarts to shrink it: an audible gap, and a brief “stopped” state that screens watching playback can see. Opening the visualiser did exactly this until 2026-11-06. The fix is the rule: allocate what a feature needs once, at start-up, before the audio buffer exists, and keep it. The visualiser’s overlay buffer, 8,208 bytes, is now allocated once when the BCM2722 driver starts, and never freed. If it is lost, the visualiser falls back to drawing on the CPU rather than allocate again while music plays. [sim]