# daedalus-v4l2

V4L2 stateless decoder for the Raspberry Pi 5 / CM5, backed by the
`daedalus-fourier` kernel library (VP9 + AV1 CDEF + H.264 video
decode kernels on VideoCore VII compute + ARM NEON).

**Status:** scaffold (2026-05-18). Architecture locked per
[daedalus-fourier session memory](https://git.reauktion.de/marfrit/daedalus-fourier);
implementation not yet begun.

## What this is

Sibling repo to
[daedalus-fourier](https://git.reauktion.de/marfrit/daedalus-fourier)
(the kernel library; cycles 1-9 closed).

A two-piece userspace + kernel-module stack that exposes a V4L2
stateless decoder interface (`/dev/videoNN`) so that
`libva-v4l2-request-fourier` → `firefox-fourier` /
`chromium-fourier` can drive it the same way they drive existing
hardware-decode pipelines on Pi 5 / RK3588.

```
+-----------------------------------------------------------+
| firefox-fourier / chromium-fourier  (existing)            |
+-----------------------------------------------------------+
| VA-API                                                    |
+-----------------------------------------------------------+
| libva-v4l2-request-fourier  (existing, sibling project)   |
+-----------------------------------------------------------+
| V4L2 stateless ioctl uAPI                                 |
+-----------------------------------------------------------+
| daedalus-v4l2 kernel module  (`kernel/`)                  |
|   - registers /dev/videoNN                                |
|   - parses V4L2 stateless ioctls (VP9/AV1/H.264 controls) |
|   - forwards bitstream + controls to userspace daemon     |
|     via chardev or netlink                                |
+-----------------------------------------------------------+
| daedalus-v4l2 userspace daemon  (`daemon/`)               |
|   - takes bitstream blobs + per-slice controls            |
|   - drives FFmpeg parsers via dlopen (Option γ)           |
|   - dispatches per-block ops via daedalus-fourier         |
|     public API (daedalus_dispatch_*)                      |
|   - posts decoded frames back to kernel module            |
+-----------------------------------------------------------+
| daedalus-fourier kernel library  (sibling project)        |
|   - exports include/daedalus.h public API                 |
|   - per-kernel CPU NEON + opportunistic V3D QPU dispatch  |
|   - 9 closed cycles across VP9, AV1 CDEF, H.264           |
+-----------------------------------------------------------+
| V3D 7.1 (Mesa userspace v3dv) + ARM NEON (BCM2712)        |
+-----------------------------------------------------------+
```

## Why this architecture (Option B + γ + sibling)

Locked by user 2026-05-18 from 3 options in
`daedalus-fourier/docs/phase8_scoping.md`:

- **Option B** over A (userspace v4l2loopback): real `/dev/videoNN`,
  proper DRM PRIME / dmabuf for browser zero-copy.
- **Option γ**: dlopen FFmpeg as parser at runtime. No vendoring,
  fastest to v1.
- **Sibling repo**: per `project_consumer_target` convention,
  V4L2-side work lives outside daedalus-fourier so the
  kernel-library has a clean API boundary.

## Status

Initial scaffold only. See `docs/architecture.md` for the
deeper design and `docs/roadmap.md` for the
sub-phase breakdown.

## Repo layout

- `kernel/` — Linux kernel module (V4L2 device registration +
  ioctl handling + userspace chardev bridge). Out-of-tree.
- `daemon/` — userspace decoder daemon (links
  `libdaedalus_core.a` from sibling daedalus-fourier; uses
  dlopen for FFmpeg parser).
- `include/` — shared headers between kernel and daemon.
- `docs/` — architecture + roadmap.

## License

Kernel module: GPLv2 (required for kernel-tree compatibility).
Userspace daemon: BSD-2-Clause (matches daedalus-fourier).