daedalus-v4l2/docs/phase_8_12_closure.md

# Phase 8.12 closure — first VP9 frame decoded via libva

**Status:** closed 2026-05-18.

The libva path now drives our daemon end-to-end: a 1566-byte
VP9 keyframe submitted via `ffmpeg -hwaccel vaapi` →
`libva-v4l2-request-fourier` → `/dev/video0` → daedalus_v4l2
kernel → REQ_DECODE on the chardev → daemon FFmpeg decode →
**byte-exact NV12 output** (FNV-1a `0x1eb34bfe` — same hash
as the standalone `test_m2m_stream` produces for the same
input).

The pixel-correct decode is the milestone.  What's *not* yet
working is the libva-side request-completion signal: `ffmpeg`
times out waiting for the media_request to complete and reports
"Decoding error" even though the kernel-side decode succeeded.
That's Phase 8.13 scope.

## What lands

### Kernel V4L2 request API integration (`kernel/daedalus_v4l2_main.c`)

- **`media_device_ops.req_validate / req_queue`** wired in
  Phase 8.11 — exposed `MEDIA_IOC_REQUEST_ALLOC` to userspace.
- **`vb2_queue.supports_requests = true`** on the OUTPUT
  queue — without this v4l2-core rejects
  `VIDIOC_S_EXT_CTRLS(which=REQUEST_VAL)` before reaching any
  driver code.
- **`vb2_ops.buf_request_complete = daedalus_buf_request_complete`**
  — calls `v4l2_ctrl_request_complete(req, &ctx->hdl)` so the
  per-request control state gets unbound when the request
  completes.  Without this v4l2-core WARNs at qbuf:
  `videobuf2-v4l2.c:440: WARN_ON(!q->ops->buf_request_complete)`.
- **`vb2_ops.buf_out_validate`** — sets the OUTPUT buf's
  `field = V4L2_FIELD_NONE`.  Required on request-supporting
  OUTPUT queues for the same WARN check (one above the
  buf_request_complete one).

### Stateless control re-registration

Switched from `v4l2_ctrl_new_std_compound(NULL p_def)` to
`v4l2_ctrl_new_custom(&cfg, NULL)` with a no-op `s_ctrl`
callback — the pattern rkvdec / cedrus / hantro use for known
`V4L2_CID_STATELESS_*` ids.  v4l2-core auto-fills `elem_size`
and `type` from its internal std-control table (verified via
debug prints: VP9_FRAME registers with `elem_size=168`,
matching `sizeof(struct v4l2_ctrl_vp9_frame)`).

## Verification

### End-to-end decode through libva

```
$ LIBVA_DRIVERS_PATH=… LIBVA_DRIVER_NAME=v4l2_request \
  LIBVA_V4L2_REQUEST_VIDEO_PATH=/dev/video0 \
  LIBVA_V4L2_REQUEST_MEDIA_PATH=/dev/media3 \
  ffmpeg -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 \
         -hwaccel_output_format nv12 \
         -i /tmp/vp9_small.ivf -f rawvideo -y /tmp/out.nv12

daemon log:
  REQ_DECODE cookie=1 codec=1 bitstream=1566 bytes capture=128x96 1 planes
  decoder: opened vp9 context
  decoder: OK 128x96 fmt=0 (yuv420p) fnv1a=0x1eb34bfe luma=12288 chroma=6144
```

Daemon decoded byte-exact, same hash as the standalone test
path produces for the same VP9 keyframe.

### libva side hangs on the request-completion poll

```
v4l2-request: Unable to set control(s): Invalid argument
v4l2-request: Timeout when waiting for media request
v4l2-request: Unable to reinit media request: Device or resource busy
[vp9] Failed to end picture decode issue: 1 (operation failed)
[vp9] Decoding error: Input/output error
```

ffmpeg sees nothing because libva times out before any DQBUF.
`/tmp/out.nv12` ends up zero bytes.

The S_EXT_CTRLS still returns EINVAL on `V4L2_CID_STATELESS_
VP9_FRAME` (size=168, struct shape matches the kernel's
registered control), but the buffer apparently gets queued
ANYWAY (without proper request binding) — that's why the
decode runs.  Then `buf_request_complete` never fires
because `vb->req_obj.req` is NULL when `buf_done` runs, and
libva's wait on the media_request fd times out.

## Design decisions

### Why ship even though libva still times out

The actual pixel-decode pipeline through the libva path
works.  That's a major milestone — Phase 8.10/8.11 stopped
at "all setup ioctls succeed but no decode runs"; Phase 8.12
makes the decode run with byte-exact output.

What remains is plumbing on the V4L2 framework side: making
the request fd see the buffer's completion.  That's a deeper
investigation (probably reachable by fixing the S_EXT_CTRLS
EINVAL so the request actually binds the buffer, then
buf_request_complete fires naturally on buf_done) — but it's
a distinct workstream from "is the decode itself working."

### Why the no-op s_ctrl is right for our daemon

FFmpeg in the daemon re-parses the bitstream itself; the
per-frame stateless controls from libva are advisory.  Our
`s_ctrl` returns 0 unconditionally because we don't act on
the values — we just need v4l2-core to accept the writes so
the request validation passes.

If we ever wanted to skip FFmpeg's parse step and trust
libva's parsed values, `s_ctrl` would need to forward them
to the daemon over the chardev — that's a different
architecture (Phase 8.14+ if motivated).

### Why `supports_requests` without `requires_requests`

`requires_requests=true` would reject `VIDIOC_QBUF` without
a bound `media_request_fd`.  That'd break our existing
test_m2m_stream which queues buffers directly (no request).

Keeping `requires_requests=false` lets both consumers
coexist: the libva path uses requests, the test client uses
direct QBUF.  The cost is that libva queueing failures might
fall back to direct QBUF (which is what we see — the buffer
runs anyway after S_EXT_CTRLS fails), masking the actual
issue.

## What's NOT here (Phase 8.13 scope)

- **Fix the S_EXT_CTRLS EINVAL** so request bind actually
  takes.  Likely sub-issue: the request's per-handler
  control state isn't initialised correctly when our
  controls were registered via `v4l2_ctrl_new_custom` —
  may need explicit `v4l2_ctrl_request_setup` or different
  registration approach.
- **Verify byte-exact CAPTURE buffer returned to ffmpeg**
  after request fixes.
- **Multi-frame stream via libva** (P-frame reference handling
  across requests).
- **AV1 + H.264 via libva** (different control sets, may
  need adjustments).

## Phase 8.13 plan

1. Deep-dive S_EXT_CTRLS EINVAL: trace what v4l2-core
   validates beyond elem_size.  Possible suspects:
   - `validate_new_compound` may require `ctrl->p_def` non-NULL
     for std compound controls.
   - The control's "request setup" callback may need
     explicit registration.
2. Either resolve the EINVAL or document what cedrus/rkvdec
   do differently (their controls are also `v4l2_ctrl_new_custom`
   with bare `.id` — so why do theirs work?).
3. Once S_EXT_CTRLS succeeds, buf_request_complete should
   fire naturally and the request poll should return.
4. End-to-end byte-exact verification.