From 9e7305b885803a2c7b104eadfee37c9ba333f90a Mon Sep 17 00:00:00 2001
From: Swung0x48 <swung0x48@outlook.com>
Date: Sat, 3 Oct 2026 01:34:25 -0400
Subject: [PATCH] [Docs] (Anland): plan and device scripts for X11 apps on the
 GPU

---
 .../skills/anland-mobilegl-plasma/SKILL.md    |   6 +-
 .../scripts/device/x11-measure.sh             |  47 +++++++
 .../scripts/x11-verify.sh                     | 132 ++++++++++++++++++
 .../notes/anland/plan-x11-gpu.md              | 132 ++++++++++++++++++
 4 files changed, 315 insertions(+), 2 deletions(-)
 create mode 100644 .claude/skills/anland-mobilegl-plasma/scripts/device/x11-measure.sh
 create mode 100644 .claude/skills/anland-mobilegl-plasma/scripts/x11-verify.sh
 create mode 100644 docs/Disaggregated/notes/anland/plan-x11-gpu.md

diff --git a/.claude/skills/anland-mobilegl-plasma/SKILL.md b/.claude/skills/anland-mobilegl-plasma/SKILL.md
index 947c5d8b..d8e59ad9 100644
--- a/.claude/skills/anland-mobilegl-plasma/SKILL.md
+++ b/.claude/skills/anland-mobilegl-plasma/SKILL.md
@@ -26,7 +26,7 @@ nobody else is mid-test.  Use your own `ct.sh` channel names (others use c, c2,
 7. KWin 6.7.4 with anland's `anland` backend renders straight into the anland Android Surface through the server. While the window is not on screen (consumer disconnected) the backend powers its output down (DPMS Off + RenderLoop inhibited: no compositing, no frame callbacks) and back up when the window returns. Every other GL process is `MOBILEGL_IPC_SURFACE=offscreen` and presents through KWin.
 8. Client = `/opt/mobilegl/lib/libMobileGL.so` (glibc aarch64), the container's **system-wide** GL vendor (section below): glvnd EGL vendor `/usr/share/glvnd/egl_vendor.d/10_mobilegl.json` (sorts before the distribution's `50_*.json`, which serves whenever MobileGL declines), GLX vendor `/usr/lib/libGLX_mobilegl.so.0`, settings from `/etc/mobilegl/client.conf` (`MOBILEGL_TRANSPORT=spawn MOBILEGL_IPC_DATA=shm MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl`) + `/etc/mobilegl/backend`. No per-process environment is needed.
 9. Zero-copy windows: client `wl_egl_window` frames are server-allocated AHardwareBuffer "shared images" exported as dma-buf fds over `zwp_linux_dmabuf_v1`; KWin imports them with EGL and the server recognises its own buffer by inode. KWin gets a DRM device via `GBM_BACKEND=mobilegl` -> `/usr/lib/gbm/mobilegl_gbm.so` (node is only an identity, never ioctl'd). Without linux-dmabuf the client falls back to wl_shm readback.
-10. X11 apps (Xwayland) use the MobileGL GLX vendor with per-frame readback + `xcb_put_image`. Chrome runs ANGLE-GLES over MobileGL EGL with the GPU in-process (`mobilegl-startup.sh chrome`).
+10. X11 (`docs/Disaggregated/notes/anland/plan-x11-gpu.md`): Xwayland draws with **glamor on MobileGL** (an offscreen session; `GBM_BACKEND=mobilegl` on KWin's render node; window pixmaps are shared images handed to KWin as linux-dmabuf buffers; its `glFlush` publishes them through the server, `/tmp/mgl-xwayland.client.log`); `ANLAND_XWAYLAND_GLAMOR=0` in KWin's drop-in brings back the software `-shm` Xwayland. GLX windows present their frames as shared images through **DRI3 + Present** (log `presented through DRI3+Present shared images`), falling back to readback + MIT-SHM / `xcb_put_image` when the X server has no DRI3 (`MOBILEGL_GLX_PRESENT=readback` forces it per app). Chrome runs ANGLE-GLES over MobileGL EGL with the GPU in-process (`mobilegl-startup.sh chrome`).
 
 ## First-time prerequisites (Windows host)
 
@@ -108,7 +108,7 @@ Installed by `xdeploy.sh` (and anland's `anland-build-client.sh`), so any proces
 
 Precedence is environment > `/etc/mobilegl/backend` (backend only) > client.conf > built-in; `MOBILEGL_CONFIG_FILE` / `MOBILEGL_BACKEND_FILE` name other files (empty = off); a server process never reads them.
 
-**Fallback.** Before bringing anything up the client probes the configured endpoint (one non-blocking connect, `MOBILEGL_IPC_PROBE_TIMEOUT_MS`, default 250, 0 = off; a refused abstract socket answers in ~0.2 ms). With no server: the EGL vendor returns `EGL_NO_DISPLAY` and no devices (glvnd moves on to the other vendor), the GLX vendor fails `__glx_Main` (libGLX falls back to the vendor Xwayland names), and `mobilegl_gbm` fails `create_device` (libgbm falls back to the device's own backend). Client queries (`eglQueryString(EGL_NO_DISPLAY)`, `eglGetProcAddress`) never bring a session up. MobileGL also steps aside for a GBM device another backend created and for `LIBGL_ALWAYS_SOFTWARE=1` - that is how Xwayland (KWin's patch sets it) keeps the software stack. Show it without stopping the real server:
+**Fallback.** Before bringing anything up the client probes the configured endpoint (one non-blocking connect, `MOBILEGL_IPC_PROBE_TIMEOUT_MS`, default 250, 0 = off; a refused abstract socket answers in ~0.2 ms). With no server: the EGL vendor returns `EGL_NO_DISPLAY` and no devices (glvnd moves on to the other vendor), the GLX vendor fails `__glx_Main` (libGLX falls back to the vendor Xwayland names), and `mobilegl_gbm` fails `create_device` (libgbm falls back to the device's own backend). Client queries (`eglQueryString(EGL_NO_DISPLAY)`, `eglGetProcAddress`) never bring a session up. MobileGL also steps aside for a GBM device another backend created and for `LIBGL_ALWAYS_SOFTWARE=1` - that is how a software Xwayland (`ANLAND_XWAYLAND_GLAMOR=0`, KWin's patch sets it then) keeps the software stack. MobileGL never opens an X connection to a display its own process serves (`MG_Util/X11/DisplayGuard.h`; `MOBILEGL_X11_DIAL=0` forbids all), which is what made a glamor Xwayland deadlock on itself before. Show it without stopping the real server:
 ```sh
 sed 's|^MOBILEGL_IPC_CONTROL=.*|MOBILEGL_IPC_CONTROL=unix:@nobody|' /etc/mobilegl/client.conf > /tmp/down.conf
 sudo -u swung0x48 env -i HOME=/home/swung0x48 PATH=/usr/bin XDG_RUNTIME_DIR=/run/user/1000 WAYLAND_DISPLAY=wayland-0 \
@@ -117,6 +117,8 @@ sudo -u swung0x48 env -i HOME=/home/swung0x48 PATH=/usr/bin XDG_RUNTIME_DIR=/run
 
 ## Test clients and how to verify
 
+X11 on the GPU has its own driver, `scripts/x11-verify.sh` (preflight, measure before/after with glxgears at `vblank_mode=0` on both GLX paths, deploy-client/-kwin/-server, check, apps, stop); `scripts/device/x11-measure.sh` refuses to load the phone below 40% battery.
+
 Inside the container as root (`printf '...' | bash scripts/ct.sh <chan>`), `mgrun offscreen <cmd>` runs a client as swung0x48 in the live session through a login shell, with nothing but the surface mode and the log path set (log `/tmp/mgl-run.client.log`, override base with `MGLOG=/tmp/x.log`); a plain `env -i ... bash -l -c '<cmd>'` as swung0x48 gets MobileGL the same way:
 ```sh
 mgrun offscreen eglinfo -B ; mgrun offscreen glxinfo -B
diff --git a/.claude/skills/anland-mobilegl-plasma/scripts/device/x11-measure.sh b/.claude/skills/anland-mobilegl-plasma/scripts/device/x11-measure.sh
new file mode 100644
index 00000000..b5c45e0d
--- /dev/null
+++ b/.claude/skills/anland-mobilegl-plasma/scripts/device/x11-measure.sh
@@ -0,0 +1,47 @@
+# x11-measure.sh <label> <app-process-name> [seconds] - (Android root shell) CPU of the X11 path while
+# an X11 app runs: % of ONE core (800 = all 8 cores) for the whole phone, the app, Xwayland,
+# kwin_wayland, the app's :mobilegl server; mean kgsl gpu_busy_percentage; and the number of dma-buf
+# descriptors Xwayland and KWin hold (window pixmaps / client buffers as dma-bufs). Refuses to run
+# below 40% battery: the phone drains faster under load than USB charges it.
+# Run: su -c "sh /data/local/tmp/anl/x11-measure.sh glamor glxgears 10"      Env: PKG, MIN_BATTERY.
+L=${1:-sample}
+APP=${2:-glxgears}
+N=${3:-10}
+P=${PKG:-com.anland.consumer.mobilegl}
+GPU=/sys/class/kgsl/kgsl-3d0/gpu_busy_percentage
+level=$(dumpsys battery | sed -n 's/^ *level: *//p')
+if [ "${level:-0}" -lt "${MIN_BATTERY:-40}" ]; then
+    echo "battery ${level}% < ${MIN_BATTERY:-40}%: not loading the phone; charge first" >&2
+    exit 3
+fi
+ticks() {
+    t=0
+    for p in "$@"; do
+        [ -r /proc/$p/stat ] || continue
+        v=$(sed 's/^.*) //' /proc/$p/stat | awk '{print $12 + $13}')
+        t=$((t + v))
+    done
+    echo $t
+}
+total() { awk '/^cpu /{print $2+$3+$4+$6+$7+$8}' /proc/stat; }
+dmabufs() {   # dma-buf descriptors held by the pids (Android kernels link them to /dmabuf:...)
+    n=0
+    for p in "$@"; do n=$((n + $(ls -l /proc/$p/fd 2>/dev/null | grep -c dmabuf))); done
+    echo $n
+}
+AP="$(pidof $APP)"
+XW="$(pidof Xwayland)"
+KW="$(pidof kwin_wayland)"
+SV="$(pidof $P:mobilegl)"
+[ -n "$AP" ] || { echo "no running process named $APP" >&2; exit 2; }
+a0=$(total); p0=$(ticks $AP); x0=$(ticks $XW); k0=$(ticks $KW); v0=$(ticks $SV)
+g=0; i=0
+while [ $i -lt $N ]; do
+    sleep 1
+    b=$(cat $GPU 2>/dev/null | tr -dc '0-9'); g=$((g + ${b:-0})); i=$((i + 1))
+done
+a1=$(total); p1=$(ticks $AP); x1=$(ticks $XW); k1=$(ticks $KW); v1=$(ticks $SV)
+pct() { echo $(( ($2 - $1) / N )); }
+printf '%-12s %3ss  phone %4s%%  %s %3s%%  Xwayland %3s%%  kwin %3s%%  server %3s%%  gpu %3s%%  dmabufs Xwayland %s kwin %s  battery %s%%\n' \
+    "$L" "$N" "$(pct $a0 $a1)" "$APP" "$(pct $p0 $p1)" "$(pct $x0 $x1)" "$(pct $k0 $k1)" "$(pct $v0 $v1)" "$((g / N))" \
+    "$(dmabufs $XW)" "$(dmabufs $KW)" "$level"
diff --git a/.claude/skills/anland-mobilegl-plasma/scripts/x11-verify.sh b/.claude/skills/anland-mobilegl-plasma/scripts/x11-verify.sh
new file mode 100644
index 00000000..2c96ec66
--- /dev/null
+++ b/.claude/skills/anland-mobilegl-plasma/scripts/x11-verify.sh
@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# x11-verify.sh <step> [...] - device verification of X11 on the GPU (docs/Disaggregated/notes/anland/
+# plan-x11-gpu.md): Xwayland drawing with glamor on MobileGL, and GLX windows presented through
+# DRI3 + Present from shared images. Steps, in the order a full run takes them:
+#
+#   preflight             read-only: battery, stack status, Xwayland package, render node, xcb libs,
+#                         test apps, Xwayland's extensions and its GLX vendor
+#   measure <label> [s]   glxgears (vblank_mode=0) for s seconds (10): its fps, then CPU/GPU/dma-buf
+#                         counts (device/x11-measure.sh); also with MOBILEGL_GLX_PRESENT=readback
+#   deploy-client         xbuild.sh + xdeploy.sh of this worktree's client (MGL_XBUILD_DIR)
+#   deploy-kwin           kwin-stage.sh build from ANLAND_WORKTREE; waits for "== ALL DONE =="
+#   deploy-server         build-android.sh + cyc.sh x11-server (swaps the APK lib, RESTARTS the session)
+#   check                 the evidence: Xwayland took glamor (journal), its MobileGL log, GLX's path
+#                         line, dma-buf counts in Xwayland/KWin, the server's import lines
+#   apps                  xterm + xeyes + glxgears on screen, two screenshots (hashes must differ)
+#   stop                  kill the test apps
+#
+# Typical run: preflight; measure before; deploy-client; deploy-kwin; deploy-server; check; measure
+# after; apps; stop. Battery: every load step refuses below MIN_BATTERY (40) %.
+# Env: CHANNEL (ct.sh channel, default x11), ANLAND_WORKTREE (anland x11-gpu worktree, Windows
+# form), MGL_XBUILD_DIR (default /home/swung/mgl-xbuild-x11), MIN_BATTERY.
+set -euo pipefail
+here=$(cd "$(dirname "$0")" && pwd)
+. "$here/env.sh"
+CH=${CHANNEL:-x11}
+: "${MGL_XBUILD_DIR:=/home/swung/mgl-xbuild-x11}"
+: "${ANLAND_WORKTREE:=$(cygpath -m "$USERPROFILE" 2>/dev/null)/AndroidStudioProjects/anland/.claude/worktrees/x11-gpu}"
+export MGL_XBUILD_DIR ANLAND_WORKTREE
+
+battery_ok() {
+    local level
+    level=$(adb_ shell "dumpsys battery" | sed -n 's/^ *level: *//p' | tr -d '\r')
+    echo "battery: ${level}%"
+    if [ "${level:-0}" -lt "${MIN_BATTERY:-40}" ]; then
+        echo "below ${MIN_BATTERY:-40}%: stopping GPU-heavy work; charge the phone first" >&2
+        return 1
+    fi
+}
+
+push_measure() {
+    tr -d '\r' < "$here/device/x11-measure.sh" > "$ANL_DIR/x11-measure.sh"
+    adb_ push "$ANL_DIR/x11-measure.sh" "$DEV_TOOLS/x11-measure.sh" >/dev/null
+}
+
+step=${1:?usage: x11-verify.sh <preflight|measure|deploy-client|deploy-kwin|deploy-server|check|apps|stop>}
+shift
+case "$step" in
+preflight)
+    battery_ok || true
+    adb_ shell "su -c 'sh $DEV_TOOLS/status.sh'" || true
+    bash "$here/ct.sh" "$CH" <<'IN'
+echo "== packages"; pacman -Q xorg-xwayland libxcb mesa-utils xorg-xeyes xterm xorg-xdpyinfo 2>&1 | sed 's/^/  /'
+echo "== render nodes"; ls -l /dev/dri/ 2>&1 | sed 's/^/  /'
+U=swung0x48; for n in /dev/dri/renderD*; do sudo -u $U test -r "$n" -a -w "$n" && echo "  $U can open $n"; done
+echo "== KWin's thin node"; tr '\0' '\n' < /proc/$(pgrep -x kwin_wayland)/environ 2>/dev/null | grep -E "MOBILEGL_GBM_NODE|ANLAND_XWAYLAND_GLAMOR|GBM_BACKEND" | sed 's/^/  /'
+echo "== xcb libraries"; for l in libxcb-dri3.so.0 libxcb-present.so.0 libxcb-xfixes.so.0 libxcb-shm.so.0; do ls /usr/lib/$l >/dev/null 2>&1 && echo "  $l ok" || echo "  $l MISSING"; done
+echo "== Xwayland"; pgrep -a -x Xwayland | sed 's/^/  /'
+mgrun offscreen xdpyinfo 2>/dev/null | grep -E "^ +(DRI3|Present|MIT-SHM|XFIXES|GLX)$" | sed 's/^/  ext/'
+mgrun offscreen glxinfo -B 2>&1 | grep -E "vendor|renderer|direct rendering" | sed 's/^/  /'
+IN
+    ;;
+measure)
+    label=${1:?usage: x11-verify.sh measure <label> [seconds]}
+    secs=${2:-10}
+    battery_ok
+    push_measure
+    for mode in auto readback; do
+        printf '%s\n' \
+            "pkill -x glxgears; rm -f /tmp/mgl-x11-gears.client.log /tmp/x11-gears.out" \
+            "MGLOG=/tmp/mgl-x11-gears timeout $((secs + 8)) mgrun offscreen env vblank_mode=0 MOBILEGL_GLX_PRESENT=$mode glxgears > /tmp/x11-gears.out 2>&1 &" \
+            "sleep 3" | bash "$here/ct.sh" "$CH" >/dev/null
+        adb_ shell "su -c 'sh $DEV_TOOLS/x11-measure.sh $label-$mode glxgears $secs'" || true
+        sleep 6
+        printf '%s\n' "grep -a 'frames in' /tmp/x11-gears.out | tail -3; grep -a 'presented through' /tmp/mgl-x11-gears.client.log | head -1; pkill -x glxgears; true" \
+            | bash "$here/ct.sh" "$CH"
+    done
+    ;;
+deploy-client)
+    bash "$here/xbuild.sh"
+    CHANNEL=$CH bash "$here/xdeploy.sh"
+    ;;
+deploy-kwin)
+    CHANNEL=$CH bash "$here/kwin-stage.sh" build
+    for _ in $(seq 1 120); do
+        out=$(printf 'tail -3 /root/kwin-build.log\n' | bash "$here/ct.sh" "$CH" 2>/dev/null || true)
+        echo "$out" | tail -1
+        echo "$out" | grep -q "== ALL DONE ==" && exit 0
+        echo "$out" | grep -qiE "error|failed" && { echo "KWin build failed" >&2; exit 1; }
+        sleep 30
+    done
+    echo "KWin build did not finish in an hour" >&2; exit 1
+    ;;
+deploy-server)
+    battery_ok
+    bash "$here/build-android.sh"
+    CHANNEL=$CH bash "$here/cyc.sh" x11-server
+    ;;
+check)
+    bash "$here/ct.sh" "$CH" <<'IN'
+echo "== Xwayland's command line (no -shm with glamor)"; pgrep -a -x Xwayland | sed 's/^/  /'
+echo "== Xwayland's glamor (journal)"
+journalctl --no-pager --since -30min 2>/dev/null | grep -aiE "glamor|Xwayland.*(EGL|gbm|dri3|falling back)" | tail -10 | sed 's/^/  /'
+echo "== Xwayland's MobileGL client log"; grep -aE "presented|shared image|declin|Fatal|ERROR" /tmp/mgl-xwayland.client.log 2>/dev/null | tail -8 | sed 's/^/  /' || echo "  (none)"
+X=$(pgrep -x Xwayland); K=$(pgrep -x kwin_wayland)
+echo "== dma-bufs held: Xwayland $(ls -l /proc/$X/fd 2>/dev/null | grep -c dmabuf), kwin $(ls -l /proc/$K/fd 2>/dev/null | grep -c dmabuf)"
+echo "== Xwayland's GLX vendor and extensions"
+mgrun offscreen xdpyinfo 2>/dev/null | grep -E "^ +(DRI3|Present|MIT-SHM)$" | sed 's/^/  ext/'
+echo "== a GLX window's path"
+rm -f /tmp/mgl-x11-check.client.log
+MGLOG=/tmp/mgl-x11-check timeout 6 mgrun offscreen glxgears >/dev/null 2>&1
+grep -a "presented through\|leaves DRI3" /tmp/mgl-x11-check.client.log | sed 's/^/  /'
+IN
+    adb_ logcat -d | grep -aE "MobileGL.*(shared image|dma-buf import|refused)" | tail -8 || true
+    adb_ logcat -b crash -d | tail -5 || true
+    ;;
+apps)
+    battery_ok
+    printf '%s\n' \
+        "pkill -x xterm; pkill -x xeyes; pkill -x glxgears" \
+        "MGLOG=/tmp/mgl-x11-xterm mgrun offscreen xterm -geometry 80x24+40+40 >/dev/null 2>&1 &" \
+        "MGLOG=/tmp/mgl-x11-xeyes mgrun offscreen xeyes -geometry 200x150+700+40 >/dev/null 2>&1 &" \
+        "MGLOG=/tmp/mgl-x11-gears mgrun offscreen glxgears >/dev/null 2>&1 &" \
+        "sleep 4; pgrep -a -x xterm; pgrep -a -x xeyes; pgrep -a -x glxgears; true" | bash "$here/ct.sh" "$CH"
+    bash "$here/shot.sh" x11-apps 2 1
+    ;;
+stop)
+    printf '%s\n' "pkill -x xterm; pkill -x xeyes; pkill -x glxgears; true" | bash "$here/ct.sh" "$CH"
+    ;;
+*)
+    echo "unknown step $step" >&2; exit 2
+    ;;
+esac
diff --git a/docs/Disaggregated/notes/anland/plan-x11-gpu.md b/docs/Disaggregated/notes/anland/plan-x11-gpu.md
new file mode 100644
index 00000000..cfdf7263
--- /dev/null
+++ b/docs/Disaggregated/notes/anland/plan-x11-gpu.md
@@ -0,0 +1,132 @@
+# Plan: X11 apps on the GPU, zero-copy (Xwayland glamor + GLX DRI3/Present) (2026-10-03)
+
+> Follows [`plan-ahb-dmabuf.md`](plan-ahb-dmabuf.md) (the Wayland half: server-allocated AHB
+> "shared images" exported as dma-bufs). Same hard rules: vendor-neutral (AHB, dma-buf, sync_file,
+> the libgbm backend ABI, linux-dmabuf, DRI3/Present), no layout assumptions (modifier INVALID).
+
+## Today
+
+```
+GLX app --glXSwapBuffers--> ReadPixels (server->client CPU) --xcb_put_image--> Xwayland (-shm, llvmpipe)
+Xwayland --wl_shm--> KWin --glTexSubImage2D upload--> server
+```
+Two full-frame CPU trips per frame for every X11 GL app, and every ordinary X11 app is drawn by
+pixman/llvmpipe and uploaded again by KWin.
+
+## Target
+
+```
+GLX app  --render--> pbuffer --GPU copy (PresentToSharedImage)--> [AHB image]
+         --DRI3 PixmapFromBuffer(s)(dma-buf, once per buffer)--> Xwayland pixmap (glamor: gbm_bo_import -> EGLImage)
+         --Present PresentPixmap--> Xwayland flips it (attaches the pixmap's dma-buf wl_buffer) or GPU-copies it
+Xwayland (glamor on MobileGL EGL/GBM) --linux-dmabuf wl_buffer (window pixmaps are shared images)--> KWin
+```
+Every hop is a session of the same MobileGL server sampling or writing the same AHardwareBuffer.
+CPU copies: zero.
+
+## Stage 1 - Xwayland on MobileGL (glamor)
+
+What Xwayland 24.1.13 (`hw/xwayland/xwayland-glamor-gbm.c`, `glamor/glamor.c`) needs, and where it is:
+
+| Need | Status |
+|---|---|
+| render node from linux-dmabuf v4 feedback `main_device` (drmGetDeviceFromDevId) | KWin's thin node: must be a real DRM render node (`MOBILEGL_GBM_NODE`=/dev/dri/renderD128). `/dev/null` makes glamor fail -> shm fallback |
+| `gbm_create_device(fd)` with `GBM_BACKEND=mobilegl` | `mobilegl_gbm.so` (exists) |
+| EGL client ext `EGL_KHR/MESA_platform_gbm`, `eglGetPlatformDisplay(GBM, gbm)` | exists; the foreign-device decline keys on the backend name `mobilegl` |
+| `eglCreateContext(EGL_NO_CONFIG_KHR, core 3.1)` + surfaceless `eglMakeCurrent` | cherry-picked from the surfaceless branch (6125f941), to be dropped on rebase |
+| GL >= 2.1 desktop, `GL_ARB_vertex_array_object`, `GL_OES_EGL_image`; renderer not llvmpipe | exists on a split client |
+| `EGL_EXT_image_dma_buf_import(_modifiers)` -> dmabuf_capable | exists (shared images) |
+| `gbm_bo_create_with_modifiers2(XRGB8888/ARGB8888, {INVALID, LINEAR})`, `gbm_bo_get_fd_for_plane`, `_handle_for_plane`, `_stride_for_plane`, `_offset`, `_modifier`, `gbm_bo_import(FD / FD_MODIFIER)` | exists; now covered by a host test through the real libgbm loader |
+| `eglCreateImageKHR(EGL_LINUX_DMA_BUF_EXT)` of its own bos, `glEGLImageTargetTexture2DOES` | exists (server identifies its image by inode) |
+| KWin's tranche lists XRGB8888/ARGB8888 with modifier INVALID | KWin adds INVALID+LINEAR when the EGL reports no modifiers (ours) |
+| **implicit sync**: glamor renders into window pixmaps and commits after `glFlush`, assuming the kernel orders KWin's read after it | **new**: see below |
+| **Xwayland must never dial its own display** | **new**: see below |
+
+### Implicit sync by flush (new shared_image op `Flush`)
+
+The server already orders an image between sessions: a writer publishes a sync_file per write
+(`PublishWrite`), a reader waits on it at its first use and publishes its frame's read fence at
+its frame boundary (swap). glamor has neither a swap nor an explicit write: it renders into the
+image through an FBO and calls `glFlush` before committing.
+
+- Client: `glFlush`/`glFinish` in a process that has bound a shared image to a texture
+  (`glEGLImageTargetTexture2DOES`) and does not own the server window (not KWin) send the new
+  in-stream `shared_image Flush` op and wait for its reply. Policy is a pure function
+  (`SharedImageFlushPolicy`), overridable with `MOBILEGL_SHARED_IMAGE_FLUSH_SYNC=0/1`.
+- Server: `BackendObject::PublishSharedImageAccesses()` - every image the session used since its
+  last boundary gets the flush's fence as a write (generation moves) and as a read.
+  Espryt: `ExportFence` (EGL_ANDROID_native_fence_sync), Magma: release held images, submit with
+  the exportable semaphore, export it. A session that has flushed this way also waits (GPU) for
+  the pending read fences of an image before its first use in a frame (write-after-read).
+- The reply comes after the fence is published, so KWin (which samples after Xwayland's commit,
+  which follows the reply) always finds the new generation.
+
+### X-connection safety (`MG_Util/X11/DisplayGuard`)
+
+One rule, one function: `MayDialX11Display(name)` is false when this process **serves** that
+display: it holds a listening unix socket named `/tmp/.X11-unix/X<n>` (path or abstract) per
+`/proc/net/unix` + `/proc/self/fd`, or its executable is an X server (Xwayland, Xorg, Xvfb, ...).
+`MOBILEGL_X11_DIAL=0` turns all dialing off. Every place MobileGL opens an X connection asks it
+first: EGLState's default-visual query (eglGetDisplay of a non-X native display has platform NONE,
+so the old "only on X displays" test still dialed for `eglGetDisplay(gbm_device)`), DirectGLES's
+visual query and window-surface display, Magma's Xlib surface. GLX never opens a connection (it
+uses the application's). KWin's launcher also drops `DISPLAY` from Xwayland's environment.
+
+### KWin (anland `kwin.patch`, `mobilegl-startup.sh`)
+
+`ANLAND_MOBILEGL=1` and `ANLAND_XWAYLAND_GLAMOR != 0`: Xwayland starts **without** `-shm`, with
+`MOBILEGL_IPC_SURFACE=offscreen`, its own `MOBILEGL_LOG_FILE_PATH=/tmp/mgl-xwayland`, `GBM_BACKEND`
+kept, no `LIBGL_ALWAYS_SOFTWARE`/`GALLIUM_DRIVER`, no `DISPLAY`. Otherwise the old `-shm` +
+software environment. If glamor cannot initialise, Xwayland itself falls back to shm rendering.
+
+## Stage 2 - GLX presentation through DRI3 + Present
+
+Per GLX window drawable (`GLXImpl/X11Present.{h,cpp}`, logic behind two small interfaces so the
+host tests drive it with fakes):
+
+- **Path selection** (`SelectPresentPath`): DRI3 >= 1.0 and Present >= 1.0 on the connection,
+  shared images available, depth 24/32, `MOBILEGL_GLX_PRESENT` not `readback` -> `Dri3Present`;
+  else MIT-SHM >= 1.2 with fd passing -> `ShmPutImage`; else `PutImage` (today's bands).
+- **Buffers**: up to 3 (4 when Xwayland holds all three past a 1 s wait) shared images of the
+  window's format (depth 24 -> XRGB8888, 32 -> ARGB8888: exactly what glamor imports them as), each
+  imported once as a pixmap (`PixmapFromBuffers` with modifier INVALID on DRI3 >= 1.2, else
+  `PixmapFromBuffer`, checked). A buffer is busy from its PresentPixmap until its `IdleNotify`.
+- **Present**: `PresentToSharedImage` (GPU copy, rows top first, returns once submitted with the
+  write fence published), then `PresentPixmap` with an XFixes update region from the swap's
+  damage (flipped to X's top-left origin; none = whole), serial per frame. Events arrive on a
+  special-event queue (`xcb_register_for_special_xge`), never in the application's queue.
+- **Pacing**: `FrameThrottle` (the Wayland rules) on `CompleteNotify`: interval >= 1 waits for the
+  previous frame's completion, `target_msc = last_msc + interval`; interval 0 uses
+  `PresentOptionAsync`, unpaced while completions come, ~1 fps once one is 200 ms overdue.
+- **Errors**: a refused `PixmapFromBuffer`, a `PresentPixmap` error (checked lazily, no round
+  trip), or the window's destruction (`ConfigureNotify` with `PresentWindowDestroyed`) latch the
+  drawable onto the readback path for good, logged once.
+- **Resize**: `ConfigureNotify` (and the existing throttled `XGetGeometry`) resize the pbuffer;
+  buffers of the old size are dropped as they come back idle.
+- **Fallback** (no DRI3/Present: Xwayland `-shm`, a remote X server): readback into a MIT-SHM
+  segment (memfd, `xcb_shm_attach_fd`) + `xcb_shm_put_image`; without MIT-SHM, today's bands.
+- `GLX_EXT_buffer_age` (`GLX_BACK_BUFFER_AGE_EXT`) answers the EGL buffer age of the drawable.
+
+## Tests (host, WSL)
+
+`X11DisplayGuardTest` (display names, /proc parsing, the Xwayland case), `X11PresentTest` (path
+selection, rotation, idle/complete/configure handling, pacing, resize, error latching, fake xcb
+and fake images), `SharedImageSync` additions (accesses publish as write + read),
+`SharedImageFlushPolicyTest`, `GbmGlamorTest` (the real libgbm loader with `GBM_BACKEND=mobilegl`
+over a fake shared-image library: glamor's create/export/import calls).
+
+## Device verification (phase B)
+
+`scripts/x11/` in the skill: deploy, check Xwayland's glamor log lines and its dma-buf wl_buffers in
+KWin (`WAYLAND_DEBUG`-free: `/proc/<kwin>/fdinfo` dma-buf count and the server log's import lines),
+glxgears/glxinfo/an X11 GL app before/after (fps, `top` CPU of app/Xwayland/KWin/server), and
+ordinary X apps (xterm, xeyes) for glamor rendering.
+
+## Risks
+
+- `drmGetDeviceFromDevId` on the borrowed render node inside the container (sysfs visibility).
+- Adreno: cross-context ordering relies on the Flush op's fence; a missed flush shows as tearing,
+  not corruption of other windows.
+- The extra round trip per Xwayland `glFlush` (glamor flushes once per main-loop wakeup).
+- DRI3 clients that are not MobileGL (Mesa Vulkan WSI) hand Xwayland dma-bufs the server never
+  allocated: `PixmapFromBuffers` fails with BadAlloc for them, as on any driver mismatch.