Files
MobileGL/docs/Disaggregated/notes/anland/handoff-legacy-mobilegl-unified.md
T

12 KiB

Handoff: anland 5.x + MobileGL unified server

Updated 2026-10-04. This replaces the 2026-10-02 (post-P14) handoff; git history keeps the old text.

What this is

MobileGL runs disaggregated on a rooted Android tablet:

  • Client: the glibc library in the Droidspaces container arch-kde-mgl, where it is the system-wide glvnd EGL/GLX vendor and the GBM backend.
  • Transport: the client streams pipe records over abstract socket @anland-mobilegl.
  • Server: runs in-process in the anland APK's :mobilegl foreground service.
  • Backends: Espryt (DirectGLES) or Magma (DirectVulkan), chosen in the app settings.

KDE Plasma runs on top with zero-copy windows (server-allocated AHB dma-bufs over linux-dmabuf). Everything is vendor-agnostic: AHB, sync_file, EGL_ANDROID_, VK_ANDROID_; no kgsl or qcom specifics.

Remotes and heads

Where to start reading

Topic Doc
Reproduce the whole setup on a new machine or phone .claude/skills/anland-mobilegl-plasma/reproduce.md (and SKILL.md)
Day-to-day bring-up and checks runbook-plasma.md
Zero-copy windows plan-ahb-dmabuf.md
X11 on the GPU (glamor, DRI3/Present GLX) plan-x11-gpu.md
glmark2 performance: baseline and the optimization handoff ../../../Performance/glmark2-baseline.md, ../../../Performance/glmark2-handoff.md
VA-API driver on MediaCodec (plan only, nothing implemented) ../../../MobileVA/plan.md

State of the desktop (verified on the device, 2026-10-04)

  • App-driven bring-up: opening the anland app starts daemon → server → container → Plasma. A foreground service keeps it alive, the server idles while the app is hidden (KWin DPMS off), and the notification has a "Stop desktop" action.
  • Both backends run the desktop: KWin, plasmashell, Kickoff, notifications, the lock screen, resize on extra-keys-bar toggle, and suspend/resume on window loss.
  • Buffer age and damage work end to end on both backends.
  • glvnd vendor: MobileGL is the system-wide vendor (10_mobilegl.json, /etc/mobilegl/client.conf). It steps aside for LIBGL_ALWAYS_SOFTWARE, foreign GBM devices, and when no server answers (falls through in about 0.1 s).
  • X11: Xwayland glamor on MobileGL. GLX presents through DRI3 + Present shared images, with a MIT-SHM readback fallback.
  • Chrome:
    • runs its GPU in a separate process with real EGL native fences, with no flicker;
    • recovers from device loss (as do KWin and plasmashell);
    • Shadertoy-style GPU faults are contained per session;
    • a hanging client is cut off on Magma (watchdog MOBILEGL_GPU_HANG_BUDGET_MS) and on Espryt (GUILTY reset).
  • Chrome video: hardware decode works through the container's VA-API driver. NV12/P010 dma-bufs are sampled via GL_OES_EGL_image_external on both backends. Foreign YUV buffers are CPU-copied into server YUV images, and 4K60 is fine. MOBILEGL_CHROME_VIDEO_DECODE=software opts out.
  • Device state at handoff:
    • MobileGL anland on Magma, Plasma up, server/client build bb31f374; later commits are docs, CI and a DirectGLES multi-session fix that is not yet deployed;
    • clocks NOT pinned (restored); the original anland APK is stopped;
    • pin and restore helpers: su -c "sh /data/local/tmp/anl/pbclk.sh pin|restore".

Work streams and where each one stopped

1. glmark2 performance (stopped at a handoff)

Details: docs/Performance/glmark2-handoff.md.

  • Now: MobileGL beats the stock kgsl stack in windowed glmark2 on both backends (es2 800x600: Espryt ~1887, Magma ~1213, stock ~1100). Fullscreen is still about half of stock (Espryt ~561, Magma ~404, stock ~1177).
  • Next, ranked:
    1. render straight into the window's buffers (removes the fullscreen copy);
    2. non-blocking present;
    3. merge Magma's per-frame submissions;
    4. Magma descriptor and pipeline caching;
    5. profile terrain;
    6. Espryt per-draw state sync;
    7. non-blocking fences.
  • Bench scripts: tools/device_bench/anland_glmark2/.

2. GitHub Actions CI (stopped mid-way, no handoff from its agent)

  • Background: CI had been red since about 2026-09-26 (Test workflow) and since 2026-10-02 (APK workflow retraces). Most runs show cancelled only because each newer push cancels them.
  • Landed:
Commit What
eb71b669 The pull and verify builds compile again
c1e957cb Retired the P3a/P4a untouched-region gates; those phases closed and later work legitimately changed the regions
78c5f8da Census records Refuse{Recover} as a local refusal
32d27b14 Real bug: a session's backend registration no longer trips the strict apply-thread pin while another session is applying (DirectGLES)
2d424146 Failed ctest entries are annotated with their failure lines, so failures can be read from the check-run annotations without a signed-in log reader
  • Run on 2d424146: in progress at handoff. Gates, include-closure and flatc are green; the builds and integration jobs were still running.
  • Still open:
    • the APK workflow's retrace failures (Retrace and validate), on DirectGLES for minecraft-1.21.11-main-menu, 1.21.4 startup/in-world/main-menu, 1.17-main-menu-854 and OpenRA, and on DirectVulkan for 1.17-main-menu-854;
    • they first appeared around 5accb098 / 8da082f8 (2026-10-02); last green APK run 2f64ede8;
    • not yet bisected. Candidates:
      • the clear-colour default (0,0,0,0), which is GL-correct, so judge any golden against the spec;
      • anonymous-struct sampler handling in glslang;
      • sampler CSO publishing;
      • the scissor-shadow fix;
      • the inactive-fragment-output location fix;
      • the external-texture and YUV changes;
      • the perf commits.
  • User guidance on judging checks:
    • phase-era process gates may be overly strict, and superseded ones may be removed with a reason;
    • retraces and OpenGL-level checks must pass;
    • a feature a backend does not implement (e.g. iterationRP) may be excluded narrowly per backend.
  • Reading CI without gh: curl https://api.github.com/repos/MobileGL-Dev/MobileGL/actions/runs?branch=feat/disaggregated, then /actions/runs/<id>/jobs and /check-runs/<job>/annotations. Raw logs need sign-in.

3. Chrome hardware video (landed) → vendor-agnostic VA-API (planned only)

  • Container driver: /usr/lib/dri/msm_drm_drv_video.so is an unpackaged third-party, Qualcomm-only driver. It drives V4L2 at /dev/video32 with Qualcomm modes and copies frames on the CPU itself. libva picks it because the render node's DRM driver name is msm_drm.
  • Plan in docs/MobileVA/plan.md: a new MobileVA/ directory; MediaCodec decode in the :mobilegl process; H.264 first, then VP9, AV1, HEVC/10-bit; the old driver kept as A/B fallback.
  • Prerequisites the plan found:
    • per-plane R8/GR88 dma-buf import, which mpv's GL path and KWin's NV12 path need;
    • YUV sampling paths that wait on the shared image's write fence (they appear not to).

4. MobileGL work landed since the previous handoff (newest first, grouped)

  • Perf:
    • bb31f374 Magma keeps render passes open across draws;
    • e5ee31b0 android-30 for native TLS;
    • 915882b2 record timing only with stats on;
    • 963f4d81 Magma command buffer reuse;
    • d627fca3 the server wakes a parked client only when its sequence is applied;
    • 2de0d6dd client-array buffer reuse;
    • 66b47a10 glFinish waits for the GPU, plus ES OES strings.
  • YUV: 7218bacb NV12/P010 shared images, GL_OES_EGL_image_external, Espryt GL_EXT_YUV_target, Magma Ycbcr conversion.
  • Device loss and hangs:
    • 287e1df8 cut off the session that hangs the GPU;
    • 7823bcd9 client fresh-session recovery;
    • 90e63c9e robustness extensions;
    • 58c3d9bd per-session device-loss latch;
    • 36190b7c, cf763b40, 1dd888cb, f22ae625, f52a5467 loss and teardown edge cases.
  • Multi-thread and multi-context fixes: a9f22ebb, 25a76c1b, 393002a4, a84104a4, 2acc6c41, 8024b645.
  • Chrome:
    • 4f6f4125 real EGL native fences;
    • 30977c18 opt-in ES identity for ES contexts (the GPU process on ANGLE);
    • 5accb098 glslang anonymous-struct samplers (Shadertoy page fault).
  • X11:
    • 198d6fea GLX via DRI3/Present;
    • 08f23543 glFlush implicit sync for glamor;
    • 5de6ecd4, 7fd965ce shared-image upload and publish;
    • cd58f048 inactive fragment output location;
    • 316ffe02 never dial its own X display.
  • glvnd: 69e96f5b, 4095624f, 4f679d66, 3d69c375, 552dd3d3.
  • Present:
    • 74919a3b / 7090e31d buffer age and damage;
    • Espryt fixes 815217cc (scissor shadow is per-session), c822a9fe, 228bd24c;
    • 1ff7ca53 / caa00995 frame-callback pacing;
    • 5a7b23f6 / 258b9460 / 16b07cf4 suspend, resume and resize.
  • Shared images: 38842985, 3d17e8c1, 350fc699, 67226176, b5cab441, 7520e53b.
  • Misc:
    • 8da082f8 clear colour starts at (0,0,0,0);
    • 51c37bcb sampler param conversion;
    • 15f9b27a sampler CSO per share group;
    • 239fc228 gl_FragCoord access chains;
    • bfa7987c Magma declines invalid SPIR-V;
    • 6125f941 surfaceless/no-config EGL;
    • 4633ca22 frame-stats log gated (MOBILEGL_SERVER_FRAME_STATS);
    • 2a1889b8 gtest discovery at ctest start.

5. anland work landed (newest first)

  • 41ec066 / f60b261: Chrome video decode modes.
  • e48874c: KWin recovers from its own session loss.
  • b9f8162 / cf07bc7: Chrome GPU process by default.
  • 3d8c4dd / 5d30340: Xwayland glamor.
  • 89894f1 / a55e975: DPMS off while hidden.
  • 74bd2d3: the app starts the desktop, foreground service.
  • 0fd5d01 / 144f55c: APK build guards.
  • 90c44d7: system-wide vendor.
  • 23fc73f: buffer age and damage in KWin.
  • 9773d1e / 2dfda4a: resize follow.
  • f9e41df: GBM device for linux-dmabuf.
  • 5f15240: backend choice.

Known open issues (rough priority)

  1. CI: retrace failures (see stream 2) and whatever the 2d424146 run still shows red.
  2. Fullscreen performance at about half of stock (see stream 1).
  3. Espryt's ~10 s Preemption-Fault hang path: the driver doesn't report the reset to the server's contexts, so a hanging client stalls the desktop for 10 s per hang there.
  4. YUV gaps:
    • YUV sampling doesn't wait on the write fence (suspected);
    • no single-channel (R8/GR88) dma-buf import, so KWin advertises no YUV formats and mpv's GL interop won't work;
    • the CPU copy for foreign YUV buffers is a fallback, not zero-copy.
  5. Chrome doesn't use buffer age (full-frame repaints). The Magma text-caret frame costs about 24 ms.
  6. A rare Magma X11 rectangle glitch. The readback GLX fallback is slower with glamor.
  7. Two GoldControllerTest failures on Windows hosts. MSVC builds of this branch are broken; build tests in WSL with clang.
  8. Leftovers:
    • container probe files under ~swung0x48/yuvtest and the local v.html tabs in the Chrome profile;
    • an empty directory .claude/worktrees/quirky-poincare-df3f3e (locked by Windows);
    • WSL ~/mgl-espryt* / ~/mgl-magma* directories of unknown owner (kept).

Rules this work follows

  • Commits: --no-verify, one short sentence, no Co-Authored-By trailer. No external project names in code or comments.
  • Tests: never run the DirectVulkan integration tests (ctest -E DirectVulkan); never run two ctest suites at once.
  • Worktrees: one worktree and build directory per task; remove the worktree, branch and build directories right after merging. Keep anland-unified, mgl-unified, WSL ~/mgl-xbuild-a64, ~/mgl-anl-bld and ~/sysroots. Don't touch wgl-host or ~/repos/mobilegl-cts-gl33.
  • Core profile only: don't use fixed-function test apps such as glxgears.
  • Device:
    • stop device work while the user is using the phone;
    • on USB power, watch the battery (stop below 40%);
    • wireless adb needs re-enabling after a reboot.