# daedalus-v4l2 — roadmap

## Sub-phases

### Phase 8.1 — kernel module skeleton

Out-of-tree kernel module that:
- Registers `/dev/videoNN` with `VFL_TYPE_VIDEO` + a no-op
  V4L2 stateless dispatch table.
- Accepts open/close, S_FMT, REQBUFS ioctls without doing
  anything (yet).
- Builds against `/lib/modules/$(uname -r)/build`.

Deliverable: `modprobe daedalus_v4l2` works, `v4l2-ctl --list-devices`
shows the new device.

### Phase 8.2 — kernel ↔ daemon chardev bridge

- Kernel module creates `/dev/daedalus-v4l2` chardev.
- Defines a simple req/resp protocol in `include/daedalus_v4l2_proto.h`.
- Daemon connects, exchanges echo requests.

Deliverable: ping-pong test passes.

### Phase 8.3 — daemon FFmpeg dlopen + parse

- Daemon links `libdaedalus_core.a` from sibling.
- Daemon dlopens FFmpeg.
- Test program: feed a VP9 IVF file to FFmpeg parsers,
  extract block-level metadata, validate against expected.

Deliverable: daemon can parse a VP9 frame and walk the
block-level info.

### Phase 8.4 — daemon ↔ kernel decode round-trip (closed 2026-05-18)

Shipped as a debugfs-triggered chardev round-trip rather than
the original V4L2-ioctl plan (which moved to Phase 8.5).

- REQ_DECODE / RESP_FRAME wire protocol
- Daemon decodes VP9 via FFmpeg dlopen, returns FNV-1a digest
- Verified content-dependent + deterministic; structured
  error handling for bad bitstreams

See `docs/phase_8_4_closure.md`.

### Phase 8.5 — full V4L2 m2m driver (closed 2026-05-18)

Real V4L2 m2m driver — userspace clients drive
`S_FMT`/`REQBUFS`/`QBUF`/`DQBUF` the standard way.  Bitstream
flows kernel→daemon as inline REQ_DECODE payload; decoded NV12
pixels flow daemon→kernel as inline RESP_FRAME payload.  Works
end-to-end for small frames (≤ ~64 KiB NV12).

Deliverable hit: kernel m2m driver passes most v4l2-compliance
checks; `tools/test_m2m_decode` produces a NV12 frame that's
byte-for-byte identical to `ffmpeg -pix_fmt nv12` reference.

See `docs/phase_8_5_closure.md`.

### Phase 8.6 — dmabuf + AV1 + H.264 + stateless controls (closed 2026-05-18)

- CAPTURE (and OUTPUT) on `vb2_dma_contig_memops`.
- New `DAEDALUS_IOC_GET_DMABUF` chardev ioctl — daemon
  mmaps the in-flight CAPTURE buffer, decodes pixels in
  place, sends RESP_FRAME metadata-only.
- 64 KiB frame-size cap removed.  1080p VP9 + 128×96 AV1
  + 128×96 H.264 all byte-exact against reference FFmpeg
  decode.
- V4L2 stateless controls registered for VP9 / AV1 /
  H.264 (11 controls visible to userspace).
- Colorspace round-trip fix (TRY_FMT preserve, S_FMT
  OUTPUT→CAPTURE propagation).
- Cookie unified across V4L2 + debugfs paths.
- v4l2-compliance: 47/48 (only DECODER_CMD remains,
  needs media controller — moved to 8.7).

See `docs/phase_8_6_closure.md`.

### Phase 8.7 — media controller, perf, HDR, long-form streams

1. Media controller binding via
   `v4l2_m2m_register_media_controller` (closes the last
   v4l2-compliance fail and unlocks the request API).
2. Profile the daemon's per-frame cost on hertz; substitute
   `daedalus_dispatch_*` for FFmpeg's per-block paths where
   the kernel implementation matches.  Target the
   `30fps-floor-is-fine` memory's daily-YouTube criterion:
   30fps@1080p with CPU left over for vscode.
3. HDR / 10-bit support — P010M CAPTURE, depth-aware
   `pack_nv12_to_planes`.
4. Long-form multi-frame streaming tests (B-frame refs,
   GOP boundaries) — current test client is one keyframe
   per run.

Deliverable: 30fps stable on real content + full
compliance pass.

## Effort estimate

Each phase: ~1 week of focused work (~40 hours).
Total: 7 weeks for v1.

Could be split across multiple sessions / contributors.