--- cycle: 3 phase: 4 status: open (awaiting Phase 5''' review) date_opened: 2026-05-18 parent: k3_mc_phase3.md template: phase4.md (cycle 1) + k2_deblock_phase4.md (cycle 2) — same constraints, same patterns --- # Cycle 3, Phase 4 — Plan QPU MC kernel Compact plan. Cycle 1+2 phase4 docs cover the constraint matrix (C1-C10) and the dev-discipline patterns. Phase 4''' references them rather than re-deriving. ## 1. Constraints (carried) Same V3D 7.1 device. New for MC specifically: - SMUL24 covers 16-bit filter × 8-bit pixel mults (max ~32K product, fits) - Sum of 8 products fits in int32 trivially - No DP4A — must use 8 separate scalar muls per output pixel - 16 filter phases × 8 taps × 2 B = 256 B — too big for push constants (max 128 B), small enough for one const array in shader ## 2. Workload model Per 8×8 block: - 512 SMUL24 (8 mults × 64 output pixels) - 448 ADD (7 adds × 64 output pixels) - 64 round (+64 → >>7) operations - 64 clip-to-[0,255] - ≈ 1150 ALU ops per block - 120 B read + 64 B write = 184 B per block Per 1080p frame (32 400 blocks): - ~37 Mops compute → 1.8 ms at v3d 23 % sustained (compute-bound estimate) - ~5.9 MB traffic → 1.48 ms at 4 GB/s GPU share (bandwidth-bound estimate) ## 3. Workgroup geometry Bake in the v4 lesson and the cycle-2 single-WG-size-from-start: - `local_size_x = 256` (16 subgroups × 16 lanes) - 8 lanes per block (1 lane per row r=0..7), 2 blocks per subgroup - **32 blocks per WG** - 1080p: 1 013 WGs Same lane decomposition as cycle 2 LPF: ``` edge_slot = lane_in_sg >> 3 // 0 or 1 — "which block in this subgroup" row = lane_in_sg & 7 // 0..7 block_local = sg_in_wg * 2 + edge_slot block_idx = wg_id * 32 + block_local oob = block_idx >= n_blocks ``` No barrier needed, no shared mem. Safe early-return on oob. ## 4. Per-thread algorithm ```glsl if (block_idx >= pc.n_blocks) return; uvec4 m = u_meta.meta[block_idx]; uint dst_off = m.x; uint src_off = m.y; uint mx = m.z & 15u; // Read 15 source pixels for this row. uint src_row_addr = src_off + row * pc.src_stride_u8; int s0 = int(u_src.src[src_row_addr + 0u]); int s1 = int(u_src.src[src_row_addr + 1u]); int s2 = int(u_src.src[src_row_addr + 2u]); int s3 = int(u_src.src[src_row_addr + 3u]); int s4 = int(u_src.src[src_row_addr + 4u]); int s5 = int(u_src.src[src_row_addr + 5u]); int s6 = int(u_src.src[src_row_addr + 6u]); int s7 = int(u_src.src[src_row_addr + 7u]); int s8 = int(u_src.src[src_row_addr + 8u]); int s9 = int(u_src.src[src_row_addr + 9u]); int s10 = int(u_src.src[src_row_addr + 10u]); int s11 = int(u_src.src[src_row_addr + 11u]); int s12 = int(u_src.src[src_row_addr + 12u]); int s13 = int(u_src.src[src_row_addr + 13u]); int s14 = int(u_src.src[src_row_addr + 14u]); // Filter coefficients — const REGULAR table, indexed by mx. int F0 = FILTER_REGULAR[mx][0]; ... int F7 = FILTER_REGULAR[mx][7]; // 8 output pixels (each = 8-tap convolution of 8 consecutive source). uint dst_row_addr = dst_off + row * pc.dst_stride_u8; int o0 = F0*s0 + F1*s1 + F2*s2 + F3*s3 + F4*s4 + F5*s5 + F6*s6 + F7*s7; int o1 = F0*s1 + F1*s2 + F2*s3 + F3*s4 + F4*s5 + F5*s6 + F6*s7 + F7*s8; int o2 = F0*s2 + F1*s3 + F2*s4 + F3*s5 + F4*s6 + F5*s7 + F6*s8 + F7*s9; int o3 = F0*s3 + F1*s4 + F2*s5 + F3*s6 + F4*s7 + F5*s8 + F6*s9 + F7*s10; int o4 = F0*s4 + F1*s5 + F2*s6 + F3*s7 + F4*s8 + F5*s9 + F6*s10+ F7*s11; int o5 = F0*s5 + F1*s6 + F2*s7 + F3*s8 + F4*s9 + F5*s10+ F6*s11+ F7*s12; int o6 = F0*s6 + F1*s7 + F2*s8 + F3*s9 + F4*s10+ F5*s11+ F6*s12+ F7*s13; int o7 = F0*s7 + F1*s8 + F2*s9 + F3*s10+ F4*s11+ F5*s12+ F6*s13+ F7*s14; u_dst.dst[dst_row_addr + 0u] = uint8_t(clamp((o0 + 64) >> 7, 0, 255)); u_dst.dst[dst_row_addr + 1u] = uint8_t(clamp((o1 + 64) >> 7, 0, 255)); u_dst.dst[dst_row_addr + 2u] = uint8_t(clamp((o2 + 64) >> 7, 0, 255)); u_dst.dst[dst_row_addr + 3u] = uint8_t(clamp((o3 + 64) >> 7, 0, 255)); u_dst.dst[dst_row_addr + 4u] = uint8_t(clamp((o4 + 64) >> 7, 0, 255)); u_dst.dst[dst_row_addr + 5u] = uint8_t(clamp((o5 + 64) >> 7, 0, 255)); u_dst.dst[dst_row_addr + 6u] = uint8_t(clamp((o6 + 64) >> 7, 0, 255)); u_dst.dst[dst_row_addr + 7u] = uint8_t(clamp((o7 + 64) >> 7, 0, 255)); ``` Mirrors `tests/vp9_mc_ref.c` directly. ## 5. SSBOs / push constants | binding | name | type | usage | |---|---|---|---| | 0 | `meta` | `readonly uvec4[]` | per-block (dst_off, src_off, mx, _pad) | | 1 | `dst` | `uint8_t[]` | output pixels | | 2 | `src` | `readonly uint8_t[]` | input pixels | Push constants (16 B): ``` n_blocks, dst_stride_u8, src_stride_u8, _pad ``` Filter table: hard-coded in shader as `const int FILTER_REGULAR[16][8] = { ... };` — 128 const ints. **Race safety:** lane r writes `dst[dst_off + r*dst_stride + 0..7]` (8 contiguous bytes). For rows r and r+1, writes are `r*stride + 7` and `(r+1)*stride + 0`. Disjoint iff `dst_stride ≥ 8`. **Contracts (revised per phase5''' findings 4 + 6):** 1. `dst_stride_u8 ≥ 8` (race-safety lower bound) 2. `src_stride_u8 ≥ 15` (per-row read span) 3. `dst_off + 7 + (r_max)*dst_stride < dst_buffer_size` 4. `src_off + 14 + (r_max)*src_stride < src_buffer_size` 5. **`src_off` is the byte offset of the FIRST byte of the source block's row 0 in the SSBO buffer — NOT shifted by +3.** The C bench's `src + 3` C-caller convention does not carry into the SSBO offset. Shader reads `s[k] = u_src.src[src_off + row*stride + k]` for k=0..14, which equals `master_src[block_base + row*stride + k]`, matching the C ref's per-row read of `master_src[block_base + row*stride + (x..x+7)]` for output col x ∈ 0..7. **Phase 6 MUST** add `assert(dst_stride_u8 >= 8 && src_stride_u8 >= 15)` in `bench_v3d_mc.c`'s meta-construction loop. **Phase 6 MUST** also run `V3D_DEBUG=shaderdb` after first compile and record uniform count. If uniform count > ~144 (a fall-out indicator that the filter LUT inflated unfavorably), escalate filter to a dedicated SSBO binding 3. ## 6. Predicted M2''' / R''' From Phase 3: - Compute envelope: 17.5 Mblock/s - Bandwidth envelope: 22.0 Mblock/s - min ≈ 17.5 Mblock/s - R''' isolation = 17.5 / 20.997 ≈ **0.83** (YELLOW, near GREEN) Honest lower bound R''' = 0.5-0.6 if SMUL24-vs-DP4A penalty bites harder. Phase 7''' measures. ## 7. WILL / WILL NOT touch WILL (Phase 6 creates): - `src/v3d_mc_8h.comp` — GLSL shader - `tests/bench_v3d_mc.c` — harness with contract asserts - CMake updates WILL NOT touch: - Cycle 1/2 artifacts (frozen Phase 3 baselines) - `external/ffmpeg-snapshot/` (frozen vendored sources, including the just-added `vp9_subpel_filters_table.c`) - `src/v3d_runner.{c,h}` (reusable as-is) ## 8. Phase 5''' review prompts Specific high-risk decisions: 1. **Orientation / arithmetic correctness** — the 8 `o0..o7` expressions in §4 are stencil-aligned. Verify the off-by-one in `F[k] * s[c+k]` matches `F[k] * src[x+k-3]` after the `src+3` indexing shift used by the bench. 2. **Filter table residency** — hard-coded const array vs SSBO vs push constants. Const is simplest but may cause v3d_compiler to generate a large constant LUT. Worth verifying via shaderdb. 3. **Race safety** — same shape as cycle 2 (different rows of same block disjoint iff stride ≥ row-width). Verify `dst_stride ≥ 8` contract. 4. **`src+3` index shift** — the bench's source layout puts the "row-0 col-0 source pixel" at `src + 3` (so src has -3..+12 reachable). Make sure the QPU shader applies this offset consistently to its `src_off` meta value. **RESOLVED (phase5''' finding 4, RED):** `src_off` is the raw block-base offset (NOT +3-shifted). See §5 contract 5. 5. **Anything missing.** ## 9. Phase 6 execution order 1. Write shader, get glslang to accept (likely 0 spills, ≥2 threads) 2. Write bench with asserts + meta layout 3. Run M1''' bit-exact (gate) 4. Run M2''' (throughput) 5. If R''' < 1.0 → M4''' concurrent 6. Phase 7''' verdict