Bottom-~50px flicker during animation: hypothesis list for board experiments

User report (real glass, 568x1232 RM69A10 @ 52.19 Hz): the bottom ~50 px band of the panel flickers while the screen animates — during bottom-edge app-switch dragging and while the overview/app-switcher is shown. The user is explicit the band is not shaped like app icons; it reads as a banding/ tearing artifact, not mis-rendered content.

While investigating this, a genuine but separate compositor-scene bug turned up and was fixed on this same branch: home_layer_sync (nix/ card-shell/adapter.c) only ran from card_shell’s own state-machine transitions, so an unrelated Sway focus change while the overview stayed open could re-enable Home’s layer without shell.active ever changing — see openspec/changes/the-overview-hides-the-home-screen/tasks.md section 6 and tests/test_card_shell_home_layer_self_heal.py. That is a real, independent defect (content-shaped, would show Home’s own grid/dock), not the hardware-level banding this document investigates, and it does not change any hypothesis below.

What the compositor side already rules out

grim bursts of the bottom 80 px strip taken while the overview is held open via IPC (swaymsg card_shell enter, no further input) are pixel-identical frame to frame — see the coordinator’s prior capture. That is a static scene: nothing re-renders once settled, so it cannot exercise a race that only exists while the compositor is actually producing a new frame every ~19.2 ms. It does not clear the render or scanout path during animation.

Relevant grounding already in this repo

• docs/evidence/drm-info.txt: driver canaan-drm (“Canaan K230 DRM driver”) 1.0.0 20230501, dumb buffers only (/dev/dri/renderD* absent), imported via PRIME as usual for wlroots’ DRM backend. DRM_CAP_CRTC_IN_VBLANK_EVENT = 1, DRM_CAP_ATOMIC_ASYNC_PAGE_FLIP not supported, DRM_CAP_ASYNC_PAGE_FLIP = 0. Primary plane format list omits XRGB8888 (wlroots’ default); the system runs Pixman software rendering at render_bit_depth 6 -> RGB565 (nix/shell.nix, output DSI-1 ... render_bit_depth 6).
• docs/evidence/flicker-after-headroom-revert.md: a different, already-investigated flicker symptom (whole-frame vertical roll, steady state, no animation) was traced to the RM69A10 being a DSI command-mode panel with its own GRAM: the init sequence issues 35 00 (SET_TEAR_ON) but nothing in this driver stack consumes the Tearing-Effect (TE) signal. That investigation’s conclusion was explicitly “not tearing” for that symptom (a uniform modulo-height roll), but it establishes as fact that this panel’s host-side write and the panel’s own internal scan are not synchronized by TE today. A different symptom (a torn/unstable band rather than a clean roll) from the same unsynchronized-write root cause is plausible under different timing conditions (e.g. CPU render duration varying frame to frame during an animation, rather than the steady low-load case that investigation measured).
• No kernel or DRM patch in this repo wires TE (grep -rl "tear\|te-gpio" nix/kernel* nix/patches/*.patch matches only the Sway-side frame-timing and splash patches, none of which touch TE).
• nix/patches/wlroots-vglite-dumb-stride.patch shows this exact vendor driver has already had one dumb-buffer stride/alignment surprise, but it is gated on WLR_RENDERER=vglite and does not apply to the default pixman renderer path this system actually ships.

Prioritised hypotheses and board-side experiments

Ordered by (a) how directly each is supported by the grounding above, and (b) how cheap the experiment is. None of steps 1-2 need a rebuild.

1. Confirm with the existing telemetry pipeline first (no rebuild, ~5 min)

This compositor already has a mature, reviewed benchmark/telemetry path built exactly for “how long does rendering take, and were frames presented on the expected cadence” (nix/card-shell/telemetry.c, tools/card-shell-benchmark.py, documented in nix/card-shell/README.md’s “Benchmark IPC” section). Run it against the real reported gesture before touching anything else:

swaymsg card_shell benchmark physical
# perform the exact reported gesture: a bottom-edge app switch, and
# separately, opening the app switcher by a real swipe; wait 3s before/after
swaymsg card_shell benchmark-stop
journalctl -u <sway-service> | grep K230_CARD_BENCH > telemetry.log
python3 tools/card-shell-benchmark.py --input telemetry.log --renderer pixman

Read tracking_present_interval_ms (spacing between successive presented frames while dragging — this is DRM/vblank feedback, not a guess) and frame_update_cpu_ms (Pixman scene-build + commit-submit CPU time per frame) in the JSON report:

• If tracking_present_interval_ms stays close to 19.2 ms (budget p95 33.334 ms / max 100 ms passes cleanly) and frame_update_cpu_ms is well under 16.7 ms: the compositor is submitting frames on a clean, on-time cadence. That rules out “the CPU render is slow and racing scanout” and points squarely at the panel/driver side (hypotheses 3-4 below) — exactly what the pixel-identical IPC capture already suggested, now confirmed for the animating case too.
• If frame_update_cpu_ms is at or above ~16-19 ms (i.e. Pixman sometimes takes longer than one refresh period to build+submit a frame): that supports hypothesis 2 (host-side render occasionally overruns the frame budget). Note the caveat in the tool’s own limits: presentation timestamps are DRM backend feedback, not proof of what the panel actually displayed — this stage only tells you whether the compositor missed its own deadline, not whether the glass tore.

This single run should reorder the rest of this list with real numbers before any hardware toggle is flipped.

2. Host render occasionally overruns the ~19.2 ms budget (no rebuild)

The panel refreshes at 52.19 Hz (~19.2 ms/frame). This is a CPU/Pixman software-rendering compositor, and this project already has a whole set of in-flight branches (perf/card-scaled-cache, measure/card-render-cost, perf/card-mirror-order, perf/theme-background-decode, …) tracking that full-screen card-shell animation frames are expensive to render. If a frame’s build+commit occasionally exceeds one refresh period, the next commit lands after scanout has already started reading the previous buffer for that period.

Experimental toggle: swaymsg output DSI-1 max_render_time 12 (render each frame starting ~12 ms before wlroots’ predicted deadline, rather than sway’s default “start as late as possible” latency-minimising schedule), then repeat the gesture and watch the panel. If the band goes away or gets markedly rarer, this supports “occasional CPU overrun, no headroom” as (part of) the cause; revert with swaymsg output DSI-1 max_render_time off. Cross-check against hypothesis 1’s frame_update_cpu_ms numbers, since max_render_time only changes when rendering starts, not whether a genuinely slow frame finishes in time.

3. K230 DRM driver’s flip-done/vblank signalling is not trustworthy (no rebuild for the toggle; needs a session restart, not a package rebuild)

docs/evidence/drm-info.txt shows atomic KMS and DRM_CAP_CRTC_IN_VBLANK_EVENT are both advertised, but this is an early vendor driver (canaan-drm “1.0.0 20230501”) with no render node and dumb-buffer-only allocation — exactly the profile of a driver whose atomic commit / vblank-event path has not been exercised much. If the driver signals “flip complete” to wlroots before the hardware has actually finished scanning out the previous buffer (or before the next buffer is safely presentable), wlroots could legitimately believe it is safe to recycle/write a buffer that is still on-glass, producing exactly a band of stale/torn pixels that only shows up when frames are produced back-to-back (i.e. during animation, never in the static IPC capture).

Experimental toggle: WLR_DRM_NO_ATOMIC=1 in the compositor’s environment, then restart the Sway session (no rebuild) and repeat the gesture. This forces wlroots onto the legacy drmModePageFlip KMS path, whose page-flip completion semantics are a different code path in both wlroots and the vendor driver than the atomic commit path. If the band changes character or disappears, that isolates the bug to the atomic-commit/vblank-event path specifically (a very plausible immature-driver bug class). If it is identical, legacy and atomic share whatever is wrong (more likely a deeper issue such as hypothesis 4).

4. The command-mode panel’s own scan is not synchronized to host writes at all (TE never wired) — same root cause already found for the whole-frame-roll symptom

Per docs/evidence/flicker-after-headroom-revert.md, SET_TEAR_ON is sent but nothing consumes the panel’s TE line, so the panel’s internal GRAM scan and the host’s writes into that GRAM already run on independent, unsynced clocks. At idle/steady state that showed up as a slow, uniform roll. Under per-frame CPU render-time jitter (animation), the same lack of synchronization could plausibly show up instead as a locally unstable band near wherever the write “catches up to or is caught by” the panel’s own scan position for that instant — which would look like flicker rather than a clean roll, and would be worse exactly when render timing is least uniform (i.e. during animation), matching the report.

This is a real hardware/driver gap, not a toggle: fixing it needs the panel driver to actually wait for (or schedule around) the TE GPIO/interrupt, which is display/panel work, not something flippable from the compositor today. It can be supported or weakened by combining hypothesis 1’s present-interval numbers (clean cadence at the DRM-feedback level) with direct visual correlation: if the band’s position/character does not track frame_update_cpu_ms variance at all (i.e. it happens identically even during the cheapest, fastest-rendering frames of a gesture), that argues against hypothesis 2/3 and toward this one — a free-running panel-side scan that doesn’t care how fast the host writes.

5. Lower priority / weaker support

• allow_tearing: Sway’s own tearing path (output_can_tear in sway/desktop/output.c) only applies to a wlr fullscreen container with output->allow_tearing set and the view itself opted in via the tearing-control protocol. Neither is set anywhere in this repo (nix/shell.nix’s swayConfig has no allow_tearing line), and card-shell’s own “ordinary maximized” cards are floating, not wlr fullscreen. This mechanism is very unlikely to be engaged at all today; worth a one-line confirmation (swaymsg output DSI-1 allow_tearing no, which should already be a no-op) rather than a real suspect.
• WLR_SCENE_DISABLE_DIRECT_SCANOUT=1: worth trying if 1-4 are inconclusive. Direct scanout (handing a single eligible client buffer straight to the KMS primary plane, bypassing Pixman composition) is a different code path from full composition, and eligibility flips on/off frame to frame exactly at the boundaries of an animation (a maximized card is eligible when static, not while multiple scene layers are animating over it), which is a classic source of visible hitches if one of the two paths has a driver-side bug the other doesn’t. No rebuild; session restart only.
• WLR_DRM_NO_MODIFIERS=1: worth trying only if 1-4 point at a structured/banded corruption consistent with a stride or modifier mismatch specifically (the wlroots-vglite-dumb-stride.patch history shows this vendor driver has had at least one such surprise, though on a different, currently-inactive renderer path). No rebuild; session restart only.

What each experiment would mean, summarised

Explicitly not done here

No DRM, KMS, panel, or wlroots render-path code was changed to “fix” this. Nothing here has been run on the board; every toggle above is proposed, not verified. This file records hypotheses and the commands to test them so the coordinator’s webcam-equipped board session can gather evidence efficiently, per .skills/k230-spec-change/SKILL.md’s grounding order: an observation on the board outranks everything in this file.