kwin_overlay_subsurface — README

Campaign to identify and remove the per-frame cost in KWin's overlay-subsurface composite path on Mali-G52 / panfrost / KDE Plasma 6.6.4 Wayland.

Spun off from ohm_gl_fix campaign on 2026-05-02 after Phase 3 re-measurement isolated KWin specifically as the residual drop source on the in-scope use case (Brave/Chromium 1080p30 H.264).

Per Sonnet Architect's 2026-05-02 second consultation (response quoted in phase0_findings):

• Different code surface — KWin internals, not libva or Chromium ozone.
• Different upstream — KDE invent, not bootlin or Chromium.
• Different reviewer culture.
• Carrying it into ohm_gl_fix's README muddies both. ohm_gl_fix is done in the strict sense (its diagnostic loop has reached the answer it was supposed to reach); ending it cleanly is more valuable than extending it again.

ohm — PineTab2, Rockchip RK3568 (4× Cortex-A55, Mali-G52 MP2, hantro G1/G2 VPU). Kernel 6.19.10-danctnix1-1-pinetab2. Mesa 26.0.5. KDE Plasma 6.6.4 Wayland.

Existing fourier-flavoured packages already installed and load-bearing for this campaign:

• qt6-base-fourier 1:6.11.0-3 — fixes the GL_ALPHA stall (a separate KWin issue from the overlay-subsurface composite cost). Necessary precondition; not sufficient.
• kwin-fourier 1:6.6.4-3 — fixes the watchDmaBuf fence-wait issue. Necessary precondition; not sufficient.

Without these the cage A/B (the entire Phase 0 finding that motivates this campaign) can't run — the GL_ALPHA stall halts playback before any meaningful drop measurement can complete.

See phase1_lock for the full row schema.

One-line goal: “On PineTab2 RK3568 + Mali-G52 panfrost + KDE Plasma 6.6.4 Wayland, with one wp_subsurface presenting a NV12 dmabuf at 1080p30 and the parent surface being the Brave UI, KWin's per-frame compositor cost reaches parity with the cage single-surface case (drops_post_warmup = 0, drops ⇐ 10, kwin_wayland %CPU within ±20 % of the cage baseline kwin_wayland %CPU).”

In:

• KWin's overlay-subsurface composite path (src/scene/surfaceitem_wayland.cpp, src/scene/itemrenderer_opengl.cpp, src/wayland/linuxdmabufv1clientbuffer.cpp, src/backends/drm/).
• Possibly: wp_drm_lease_v1 direct-scanout path (KWin already advertises this protocol).

Out:

• Step 1 (libva-v4l2-request) — closed in ohm_gl_fix.
• Step 2 (Chromium WaylandConnection) — closed in ohm_gl_fix. Step 2 patch IS engaging the overlay subsurface route per ohm_gl_fix phase3_remeasure_2026-05-02/task23_per_frame_route.md; it just doesn't help under default KWin because of the cost this campaign targets.
• Mesa-panfrost WSI pitch bug (separate Mesa upstream issue, see ohm_gl_fix phase3_remeasure_2026-05-02/A3_mesa_wsi_pitch.md).

• This README + phase0_findings + phase1_lock + worklist.
• metrics.csv — locked binding cells.
• ohm_gl_fix for the upstream measurements that motivate this campaign.

Per architect's recommendation, baked in from Phase 0 to avoid the “AI slop” rejection mode the user previously hit:

1. Reproducer minimised to a weston or cage test client + kwin_wayland (no full Brave needed for the bug report).
2. Before/after measurement under the campaign's locked metric (drops_post_warmup, drops total, kwin_wayland %CPU steady state).
3. Patch description explains the mechanism not just the symptom.
4. At least one KDE upstream reviewer has acknowledged the underlying bug report before the MR is filed.
5. Phase 2 source-read documented (per worklist) BEFORE any patch is written.

Without these the MR risks the same rejection that earlier attempts received.

Per ohm_gl_fix README line 68-73:

“Patches and changes must be aligned to upstream in syntax and semantics. But no upstream will happen (no pull requests or merge requests, no bug reports) unless specifically tasked to do so. Making Markus aware of the worth of upstreaming something is accepted and welcomed, together with an explanation, why. Upstreaming is cost (mentally and socially) and this cost must be taken in consideration.”

This campaign inherits that default. Bug reports and MRs are explicit user-tasked decisions, not background process steps.