ampere-kernel-decoders/iter4_close.md

# Iter4 close — second kernel bug: missing HEVC_SLICE_PARAMS registration

Date: 2026-05-16 (afternoon, immediately following iter3 close)
Branch: `master`
Substrate: ampere `7.0.0-rc3-devices+` with iter3 fix (ext_sps NULL init) carried in.
Backend: iter3 instrumented build, md5 `404041ea2dcc03c769e0ab8c43ddadd6`, deployed at `/usr/lib/dri/`.

## Bottom line

**The Casanova/Collabora v7.0 HEVC series forgot to register `V4L2_CID_STATELESS_HEVC_SLICE_PARAMS` in the new `vdpu38x_hevc_ctrl_descs[]` table.** The legacy `rkvdec_hevc_ctrl_descs[]` (RK3399 path) has it; the new vdpu381/vdpu383 path doesn't. Result: every per-frame `VIDIOC_S_EXT_CTRLS` returns `-EINVAL` ("cannot find control id 0xa40a92") and userspace falls through to queue requests with no controls committed → decoder runs on zero-init control state → all-zero output (or worse, OOPSes on uninit memory before iter3 fix).

## Falsifier outcome

F1 (kernel rejects 5-ctrl batch with EINVAL): **TRUE pre-patch** — confirmed by enabling `V4L2_DEV_DEBUG_CTRL` (bit 0x20) on `/sys/class/video4linux/videoN/dev_debug`, which surfaced the previously-silent `prepare_ext_ctrls: cannot find control id 0xa40a92` dprintk.

F2 (registering HEVC_SLICE_PARAMS in `vdpu38x_hevc_ctrl_descs` makes the batch accept): **FALSE → TRUE** — 1-line patch (5 source lines with formatting) eliminated the EINVAL. ffmpeg exit 0, dmesg fully clean of `S_EXT_CTRLS: error` and `cannot find control id`. Decoder runs.

F3 (decoder produces non-empty output post-patch): **FALSE** — output `/tmp/o.nv12` is 4147200 bytes (correct 3×NV12 frames) but contains only Y=16 (luma "video black") and Cb/Cr=128 (chroma neutral) — solid black. Decoder runs but bitstream isn't being interpreted. This is the iter5 hand-off bug.

## Root cause (iter4 Phase 6)

`drivers/media/platform/rockchip/rkvdec/rkvdec.c` has two HEVC ctrl_descs arrays:

| array | line | registers SLICE_PARAMS? |
|-------|------|-------------------------|
| `rkvdec_hevc_ctrl_descs[]` (legacy RK3399 path) | 189 | YES — dynamic array, dims={600} |
| `vdpu38x_hevc_ctrl_descs[]` (Casanova RK3588/RK3576 path) | ~240 | **NO** |

Both are passed to the same `rkvdec_hevc_run_preamble` (rkvdec-hevc-common.c:478) which calls `v4l2_ctrl_find(&ctx->ctrl_hdl, V4L2_CID_STATELESS_HEVC_SLICE_PARAMS)`. With the new table, the ctrl isn't in the handler — userspace `VIDIOC_S_EXT_CTRLS` for this CID fails in `prepare_ext_ctrls` → return -EINVAL → kernel sets `error_idx = cs->count` (since `set=true`) → backend sees `error_idx=5, count=5, err=-22`.

The reason this stayed silent in earlier debugging: dprintks for `cannot find control id 0x%x` are gated behind `V4L2_DEV_DEBUG_CTRL = 0x20`. Default `/sys/.../dev_debug` is 0 — no ctrl-class dprintks. Setting `0x3f` (all 6 bits) on every video device surfaced the lookup failure immediately.

## Minimal kernel patch (verified working)

```diff
--- a/drivers/media/platform/rockchip/rkvdec/rkvdec.c
+++ b/drivers/media/platform/rockchip/rkvdec/rkvdec.c
@@ -242,6 +242,12 @@ static const struct rkvdec_ctrl_desc vdpu38x_hevc_ctrl_descs[] = {
        {
                .cfg.id = V4L2_CID_STATELESS_HEVC_DECODE_PARAMS,
        },
+       {
+               .cfg.id = V4L2_CID_STATELESS_HEVC_SLICE_PARAMS,
+               .cfg.flags = V4L2_CTRL_FLAG_DYNAMIC_ARRAY,
+               .cfg.type = V4L2_CTRL_TYPE_HEVC_SLICE_PARAMS,
+               .cfg.dims = { 600 },
+       },
        {
                .cfg.id = V4L2_CID_STATELESS_HEVC_SPS,
                .cfg.ops = &rkvdec_ctrl_ops,
```

Mirror of the legacy `rkvdec_hevc_ctrl_descs[]` entry. `600` is the absolute maximum slices per frame for HEVC level > 6 (matches `visl` and legacy rkvdec).

## Verification (on-target empirical)

```
$ ssh ampere 'sudo dmesg --clear; LIBVA_DRIVER_NAME=v4l2_request ffmpeg -hwaccel vaapi -hwaccel_output_format vaapi -i bbb_60s_720p.hevc.mp4 -vf hwdownload,format=nv12 -frames:v 3 -f rawvideo -pix_fmt nv12 /tmp/o.nv12; echo exit=$?'
exit=0

$ ssh ampere 'sudo dmesg | grep -E "rkvdec|cannot find|S_EXT_CTRLS: error"'
[Sat May 16 13:17:08 2026] rkvdec fdc40100.video-codec: missing multi-core support, ignoring this instance

$ ssh ampere 'ls -la /tmp/o.nv12; md5sum /tmp/o.nv12; head -c 4147200 /tmp/o.nv12 | od -An -tu1 -w1 | sort -u'
-rw-r--r-- 1 mfritsche mfritsche 4147200 May 16 13:17 /tmp/o.nv12
25ae521379343783da65b1fc80b1e8e8  /tmp/o.nv12
  16
 128
```

No dmesg errors. No EINVAL. ffmpeg exit 0. 3-frame NV12 output (correct size). All bytes are 16 (Y) or 128 (Cb/Cr) — solid black, but a structurally-valid decode (no OOPS, no truncation).

## Why output is still black (deferred to iter5)

Possible causes for iter5 to investigate:

1. **OUTPUT bitstream not reaching hardware** — backend assembles slice NALs into `source_data`, but maybe slices_size or QBUF length is wrong → hardware reads empty buffer → produces blank frame.
2. **Slice header field mismatch** — backend's `h265_fill_slice_params` may put bit_size/data_byte_offset/slice_segment_addr in fields the kernel doesn't expect. Strace shows `bit_size=0x1038` (519 bytes), `data_byte_offset=17` — plausible but unverified against the actual NAL.
3. **start_code prefix handling** — backend prepends Annex-B `00 00 00 01` when `h264_start_code=true`. For HEVC under DECODE_MODE_FRAME_BASED + START_CODE_ANNEX_B (both registered in vdpu38x_hevc_ctrl_descs), this should match — but the iter2 backend used `h264_start_code` as a profile-independent flag (per `feedback_unconditional_codec_state`); verify it gates correctly for HEVC.
4. **DECODE_PARAMS dpb/poc fields** — for IDR frame 1, dpb should be empty (num_active_dpb_entries=0), num_poc_st_curr_before/after/lt_curr=0. If backend sets non-zero, kernel may interpret as needing references that don't exist.

iter5 starts with: enable `LIBVA_V4L2_DUMP_OUTPUT=<dir>` to capture the per-frame OUTPUT bitstream bytes, diff against the input HEVC stream's raw NALs to confirm the bitstream is being forwarded correctly. From there, branch into (2)/(3)/(4) depending on findings.

## Phase 6 question completion (iter4)

| Q | Answer |
|---|--------|
| Q1 — empirical: validate_sps fires per-frame? | NO — fires twice (CreateContext dummy + rkvdec_hevc_start), NOT per-frame. Rules out validate_sps as the EINVAL source. |
| Q2a/b — which check fails | Neither validate_sps nor validate_new. Failure is in `prepare_ext_ctrls`'s `find_ref_lock` for `0xa40a92` (HEVC_SLICE_PARAMS) which isn't registered. |
| Q3 — request-API extra steps | Not the issue. The clone path replicates whichever ctrls are registered in master, so missing SLICE_PARAMS propagates. |
| Q4 — st_rps_bits field mapping | Not relevant to this iteration — iter4's bug is upstream of EXT_SPS_*_RPS handling. iter5 may revisit. |

## Substrate state at close

- Backend `.so`: unchanged (md5 `404041ea2dcc03c769e0ab8c43ddadd6`)
- Kernel module: includes both iter3 fix (`run->ext_sps_st_rps/lt_rps = NULL` in preamble) AND iter4 fix (HEVC_SLICE_PARAMS registered in vdpu38x_hevc_ctrl_descs)
- diagnostic `pr_warn` from iter4 Phase 6 still present in `rkvdec_hevc_validate_sps` — harmless, fires twice per session
- Both kernel fixes need filing as separate kernel-agent issues against Casanova v7.0 series (iter3 → kernel-agent#14 (filed); iter4 → kernel-agent#15 (TBD))
- diagnostic `0x3f` on `/sys/.../dev_debug` should be reset to 0 for production (`echo 0 | sudo tee /sys/class/video4linux/video*/dev_debug`)

## Iter4 takeaway

The 8-phase loop's Phase 6 question-driven instrumentation (Q1 empirical validate_sps trace) worked again: pr_warn falsified the assumed culprit immediately, redirecting attention to the dprintk-gated `prepare_ext_ctrls: cannot find control id` log that revealed the actual missing registration. Total iter4 wall-clock: ~30 min from Phase 0 lock-in to verified fix.

Iter5 picks up the "decoder runs but output is solid black" downstream bug.