daedalus-fourier/README.md

# daedalus-fourier

Community-built video codec firmware for the VideoCore VII processor
on Broadcom BCM2712 (Raspberry Pi 5, Compute Module 5). Targets the
codecs Pi 5's purpose-built hardware doesn't cover — primarily VP9
and AV1 — by running software decoders on the programmable VPU cores
already sitting on the die.

> Daedalus built the Labyrinth for King Minos, then escaped from it
> by hand-forging flight firmware out of feathers and wax when no
> sanctioned exit existed.

That's the project shape. The Broadcom-locked VideoCore VII is the
Labyrinth; the Pi Foundation's "use the HEVC block and live with
software decode for everything else" is the official non-exit; and
this project is the wax-and-feathers attempt to make the silicon do
what its instruction set says it can.

**Status: empty scaffold.** Phase 0 not yet started. Don't try to
build this. Don't expect a milestone schedule. This is research-track
work that may take years or may turn out structurally impossible.

## Why this exists (rationale)

higgs is a Raspberry Pi Compute Module 5 in a small portable
chassis with a battery. Watching nerds review *Star Wars* on YouTube
while putting Mac Studios into virtual shopping baskets is a
core workload for the higgs class of device.

YouTube serves H.264 (legacy), VP9 (typical 4K), and AV1 (newer
high-bitrate / high-resolution content). It does not serve HEVC.
Pi 5's BCM2712 has one HW decoder block: HEVC. The intersection
of {what YouTube serves} ∩ {what BCM2712 decodes in HW} = ∅.

Every YouTube frame on higgs today is software-decoded on Cortex-A76
cores at ~50–90% CPU per video stream. Software decode at 1080p VP9
draws roughly 4–7 W under sustained load on Pi 5. HW decode of the
same content, if achievable, would draw under 1 W and free the CPU
for everything else.

For a battery-powered higgs that's a 3–5× session-time improvement.
For the global ~10M-unit Pi 5 install base watching mostly-VP9
video, it's measurable embodied-electron savings. Saving electrons
saves the planet — at least that seems to be consensus.

The Pi Foundation isn't going to do this work (per their own
statement: chromium-patch sustainment was too much; firmware-codec
sustainment would be moreso). The kernel `rpi-hevc-dec` series has
been 17 months in review for one decoder block they DID write
themselves. Whatever ships here ships through the community.

## Scope

### In scope (research-grade, no schedule)
- **VideoCore VII ISA + toolchain reverse-engineering.** Extending
  the existing VC4/VC6 community work (Mesa `vc4`/`v3d`, `vc4-asm`,
  Eric Anholt's docs) to VC7. VC4's ISA is open-sourced; VC6/VC7
  is mostly extrapolation but the boot path / firmware-load
  interface is documented enough to load custom code.
- **AV1 software decoder on VC7.** AV1 is the larger long-term win
  (newer codec, growing share, no licensing landmines comparable
  to HEVC). dav1d's reference C implementation is the porting
  target — significant work but a clean reference exists.
- **VP9 software decoder on VC7.** Older but currently the dominant
  4K YouTube codec. libvpx as porting target.
- **V4L2 stateless / stateful uAPI exposure.** Once firmware
  decodes, surface it as `/dev/videoNN` so existing userspace
  (ffmpeg, mpv, firefox-fourier via libavcodec) consumes it
  identically to rpi-hevc-dec. Reuse libva-v4l2-request-fourier
  + firefox-fourier plumbing unchanged.

### Out of scope
- HEVC (Pi 5 has a dedicated HW block; rpi-hevc-dec covers it).
- Pi 4 / BCM2711 / VideoCore VI. Different ISA, smaller compute
  budget, likely insufficient for VP9/AV1 even in optimal firmware.
- Non-Pi targets. VideoCore is Broadcom-Pi-specific silicon.
- Encode. Pi Foundation explicitly removed all HW encode in Pi 5;
  firmware encode on VC7 is a separate (larger) project.
- Replacing the existing GPU firmware. Custom codec firmware
  coexists with the graphics path; doesn't displace it.

## Conventions

This project follows the same 9(+1)-phase dev process as the rest
of the fresnel/ampere/firefox-fourier campaigns. See
`docs/dev_process.md` (mirrored from
`~/.claude/projects/-home-mfritsche-src/memory/feedback_dev_process.md`).

- Phase 0 (substrate / motivation / inventory) opens the chapter.
- Phase 5 (second-model review) is mandatory before implementation.
- Phase 8 (package & ship) goes through `marfrit-packages` ALARM.
- Phase 9 distills lessons into memory entries.

Gitea identity: `claude-noether` (per
`feedback_gitea_as_claude_noether.md`). No `marfrit` pushes from
Claude sessions.

## Open questions for Phase 0

Lock these empirically before Phase 1.

1. **Is VideoCore VII's ISA reachable from userspace today?** The
   Mesa `v3d` driver exposes compute shaders. Can arbitrary
   bytecode load via that path, or do we need a custom firmware
   loader through the mailbox interface?
2. **What's the VC7 instruction throughput envelope?** VC4 hit ~8
   GFLOPS at full clock. VC7 has 12 cores at higher clock. Need
   actual benchmark numbers for the kind of integer / SIMD load
   AV1 / VP9 entropy decode demands. Decode is fundamentally
   serial in places — does VC7's parallel structure even help?
3. **Is the boot / firmware-load path documented enough to load
   community firmware safely?** Pi Foundation publishes some VC
   binaries (`start.elf`, `fixup.dat`). What's the contract for
   side-loaded code that wants to coexist with the GPU path?
4. **What's the state of the prior art?** Search Mesa community,
   Phoronix archives, Eric Anholt's old posts, Herman Hermitage's
   VideoCore reverse-engineering. The "v3d firmware decode"
   concept may have been tried and abandoned for documented
   reasons we should learn before re-doing.
5. **Is dav1d / libvpx structurally amenable to GPU-shader-style
   parallelism, or does it assume conventional CPU execution?**
   This may be a hard architectural blocker that no amount of
   firmware brilliance fixes.

## Layout

```
daedalus-fourier/
├── README.md             ← this file
├── docs/
│   └── dev_process.md    ← reference copy of the 9(+1)-phase loop
├── src/                  ← empty; VC7 codec firmware lives here
└── tests/                ← empty; unit-test rig for individual
                            decode primitives
```

No build system yet. No PKGBUILD. Adding those before the first
real compilation unit is scaffold-creep.

## Sibling projects in the same orbit

- `libva-v4l2-request-fourier` — VA-API consumer-side backend.
  Would receive daedalus-fourier's decoded surfaces transparently
  once firmware exposes a V4L2 stateless / stateful node.
- `firefox-fourier` — Firefox fork that routes stateless V4L2
  through libavcodec's `v4l2_request` hwaccel. Same pickup point.
- `chromium-fourier` — sibling for Chromium.
- `kernel-agent` — manages the kernel-side bring-up. The V4L2
  driver wrapping daedalus's firmware would land here.
- `ampere-av1-enablement` — software-side AV1 bring-up on RK3588
  (rkvdec / vpu981). Provides the userspace conformance harness
  daedalus would reuse for VC7-AV1 verification.

## Source attribution

Daedalus-the-myth is public domain. The wax-and-feathers
metaphor is older than software engineering.

Anyone wanting to fail at this project: please file your failures
under `branches/icarus/`. Built-in self-deprecation slot, with
honor.