daedalus-fourier/docs/k3_mc_phase4.md

cycle, phase, status, date_opened, parent, template

cycle	phase	status	date_opened	parent	template
3	4	open (awaiting Phase 5''' review)	2026-05-18	k3_mc_phase3.md	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

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