# 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

Two interleaved tracks:

**Track A (dmabuf):**
- Switch CAPTURE mem_ops to `vb2_dma_contig_memops`.
- New `DAEDALUS_IOC_GET_DMABUF` on the chardev — daemon
  fetches a dmabuf-fd for the in-flight CAPTURE buffer,
  mmaps it, decodes pixels in place.
- RESP_FRAME shrinks to metadata-only; chardev payload
  stops capping frame size.

**Track B (codecs + compliance):**
- AV1 + H.264 codec contexts in the daemon (FFmpeg supports
  both already).
- V4L2 stateless controls (VP9_FRAME, AV1_FRAME,
  H264_SLICE_PARAMS) — even if NULL-handled by the daemon,
  presence is needed for spec/compliance.
- Media controller binding via
  `v4l2_m2m_register_media_controller`.
- TRY_FMT colorspace round-trip.

Deliverable: real AV1/H.264 1080p clips decode end-to-end.

### Phase 8.7 — performance + 30fps@1080p

- Profile end-to-end pipeline.
- Eliminate copies where possible.
- Hit 30fps@1080p for daily YouTube videos
  (the project's user-facing success criterion per
  `30fps-floor-is-fine` memory).

Deliverable: 30fps stable on real content.

## Effort estimate

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

Could be split across multiple sessions / contributors.