x11-session-research/worklist.md

# Work items — x11-session-research

## Governing rule (every phase)

**Campaign-contained data acquisition.** Every measurement
this campaign relies on is acquired in this campaign's
session. Predecessor numbers are reference history, never
imported as binding cells, comparison targets, or success
thresholds. The A1 baseline below is not optional — it is
the in-session Wayland anchor against which X11 cells are
compared. See `phase0_findings.md` § "Campaign-contained data
discipline" and `README.md` § "Campaign-contained data
discipline" for the full rule and the predecessor lesson
that motivated it.

## Phase 0 — substrate + research question + inventory

**Status: IN PROGRESS.** Motivation LOCKED 2026-05-03 in
`phase0_findings.md` § "Research question". Pre-Phase-1
inventory and baseline-anchor work below.

- [x] Predecessor close-out summarised. Substrate doc lists
  what transfers from `kwin_overlay_subsurface` and what's
  Wayland-specific (KWin source-reads don't transfer to X11
  path).
- [x] **Research question locked.** "Does cutting out the
  KWin compositor enable faster video display of Brave,
  chromium-fourier, and Firefox — for full SW decoding, and
  for libva decoding (where possible) — on PineTab2 RK3568?"
- [x] **Mechanism captured.** Operator-supplied insight
  2026-05-03: hantro emits NV12, rockchip-drm overlay plane
  doesn't accept NV12, so KWin must own the only NV12-capable
  plane (Primary, Plane 39) and forces GL-composite of every
  NV12 buffer. X11 + non-compositing WM can give the video
  region directly to Plane 39 and put rest of desktop on
  Plane 45 (RGB AFBC) — hardware-blended, no GL-composite.
- [x] **Experimental matrix drafted.** 3 browsers × 2 decode
  paths × 2 sessions = 12 cells (some N/A where libva isn't
  supported). See `phase0_findings.md` § "Experimental matrix".
- [ ] State snapshot of ohm under current Plasma Wayland —
  the campaign-start *before* photo. Unattended-tractable
  via SSH. Captures package versions, kernel, kwin_wayland
  PID + cmdline, governor, services, browser binary versions,
  test asset paths, thermal_zone temps.
- [x] Inventory of available X11 paths on ohm. Captured
  2026-05-03 in `phase0_evidence/x11_inventory_2026-05-03/`
  (raw `02_x11_paths.txt` + summary `inventory.md` § "Deliverable 2").
  Verdict: xorg-server 21.1.22 + Mesa 26.0.5 / Panfrost healthy,
  modesetting (in-server) is sole DDX, only `kwin_x11` WM
  installed today, six WM candidates available in extra,
  Plasma X11 + Plasma Wayland + Weston are the SDDM-advertised
  sessions. Operator action: `pacman -S` a non-compositing WM
  (recommend openbox) and create/switch to its SDDM session
  before without-KWin cells can run.
- [ ] **NEW: Browser X11-overlay-path inventory.** Per
  `phase0_findings.md` § "Open questions": determine whether
  Brave 147 ozone-x11, chromium-fourier 149 ozone-x11, and
  Firefox X11 backends actually request hardware-overlay
  presentation for windowed video, or whether they always
  internally composite to RGB. Browser-specific source-grep
  + chrome trace inspection.
- [ ] **NEW: Add mpv as a reference X11-overlay client.**
  mpv with `--vo=xv` or `--vo=gpu --gpu-context=x11` is a
  known-good X11 hardware-overlay path. Adding mpv to the
  matrix as a 4th client provides "is the X11 hardware-overlay
  path even reachable on this hardware" baseline, separate
  from "do browsers use it." If mpv hits Plane 39 NV12 cleanly
  but browsers don't, the answer is "X11 path is fast, but
  the browsers don't take advantage of it."
- [x] Inventory of X11-side measurement instruments. Captured
  2026-05-03 in `phase0_evidence/x11_inventory_2026-05-03/`
  (raw `04_measurement_instruments.txt` + summary `inventory.md`
  § "Deliverable 4"). Live X server supports all 7 needed
  extensions (Composite, DAMAGE, DRI3, Present, RANDR, SYNC,
  XVideo). Tools installed: xprop, xdpyinfo, xset, glxinfo,
  drm_info, perf, mpv, libxcb-present. Tools missing-but-in-extra:
  xrandr CLI, xev, xinput, xwininfo, xkill, sysprof — one
  `pacman -S` away. AUR-only: X-protocol `xtrace` (the
  `/usr/bin/xtrace` from glibc is a syscall tracer, unrelated);
  optional, matrix doesn't strictly need protocol traces.
  perf_event_paranoid=2 — set to 1 once for unattended runs.
- [ ] **A1 baseline: in-session Wayland-with-KWin anchor.**
  Mandatory per the governing rule. 3 reps minimum (variance
  is a real concern on this hardware per the predecessor
  data) of a `kwin_timing_nodebug`-equivalent run on the
  current Plasma Wayland session, captured into
  `phase0_evidence/wayland_baseline_repN/`. **This is the
  only Wayland baseline this campaign uses.** No
  predecessor number substitutes for these reps even if the
  predecessor measured an "identical" condition. The 3 reps
  also surface the session-internal variance up front, so
  Phase 1 thresholds aren't drawn against a single sample.

## Phase 1 — binding cells + measurement protocol

**Pending Phase 0 inventory + A1 baseline anchor.** Phase 1
lock will produce `phase1_lock.md` with:

- Binding cells per matrix cell (effective_fps, drops_total,
  drops_post_warmup, end-to-end-latency-if-testable,
  compositor+browser CPU at steady state).
- The clear-pass / clear-fail thresholds: what "X11 is faster"
  means quantitatively. Thresholds are drawn from the A1
  Wayland baseline acquired in *this* campaign — not from
  predecessor numbers. Provisional shape (numbers TBD from
  A1): a matrix cell counts as "X11 faster" if its effective
  fps exceeds the campaign's same-cell Wayland median by a
  margin larger than the campaign's same-cell Wayland IQR,
  and its drops_post_warmup is materially below the same
  cell's Wayland median.
- The measurement protocol per matrix cell, including how the
  X11 sessions are entered and how the browser is launched
  with libva forced on/off. Mirrors the structure of
  `kwin_overlay_subsurface/phase3_protocol.md`.

## Phase 2-onwards

Pending.

## Discipline carry-overs from `kwin_overlay_subsurface`

- *Campaign-contained data acquisition* — see governing rule
  at the top of this file. The strongest version of the
  predecessor's "replicate the baseline first" lesson:
  **don't import predecessor data at all**, acquire it fresh.
- *Phase discipline* — no patches before source-read is
  documented. Re-scoping must be honest about deferral target.
- *Non-upstreaming default* — bug reports + MRs are explicit
  operator-tasked decisions.
- *Memory persistence rule* — when this campaign reaches its
  diagnostic terminal state (success or honest closure), update
  `project_campaign_overview.md` and add any new feedback
  memory worth carrying forward to the next campaign.