mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-18 15:33:22 +09:00
12 KiB
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
:mobileglforeground 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
- MobileGL: https://github.com/MobileGL-Dev/MobileGL
feat/disaggregated, head2d424146. Integration worktree:.claude/worktrees/anland-unified. - anland: https://github.com/MobileGL-Dev/anland
legacy-mobilegl-unified, head41ec066. Integration worktree:anland/.claude/worktrees/mgl-unified. - Version: 26.10 (
MobileGL/Config.h,android-plugin/app/build.gradle.kts).
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 forLIBGL_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_externalon both backends. Foreign YUV buffers are CPU-copied into server YUV images, and 4K60 is fine.MOBILEGL_CHROME_VIDEO_DECODE=softwareopts 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".
- MobileGL anland on Magma, Plasma up, server/client build
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:
- render straight into the window's buffers (removes the fullscreen copy);
- non-blocking present;
- merge Magma's per-frame submissions;
- Magma descriptor and pipeline caching;
- profile terrain;
- Espryt per-draw state sync;
- 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
cancelledonly 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 run2f64ede8; - 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>/jobsand/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.sois an unpackaged third-party, Qualcomm-only driver. It drives V4L2 at/dev/video32with Qualcomm modes and copies frames on the CPU itself. libva picks it because the render node's DRM driver name ismsm_drm. - Plan in
docs/MobileVA/plan.md: a newMobileVA/directory; MediaCodec decode in the:mobileglprocess; 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:
bb31f374Magma keeps render passes open across draws;e5ee31b0android-30 for native TLS;915882b2record timing only with stats on;963f4d81Magma command buffer reuse;d627fca3the server wakes a parked client only when its sequence is applied;2de0d6ddclient-array buffer reuse;66b47a10glFinish waits for the GPU, plus ES OES strings.
- YUV:
7218bacbNV12/P010 shared images,GL_OES_EGL_image_external, EsprytGL_EXT_YUV_target, Magma Ycbcr conversion. - Device loss and hangs:
287e1df8cut off the session that hangs the GPU;7823bcd9client fresh-session recovery;90e63c9erobustness extensions;58c3d9bdper-session device-loss latch;36190b7c,cf763b40,1dd888cb,f22ae625,f52a5467loss and teardown edge cases.
- Multi-thread and multi-context fixes:
a9f22ebb,25a76c1b,393002a4,a84104a4,2acc6c41,8024b645. - Chrome:
4f6f4125real EGL native fences;30977c18opt-in ES identity for ES contexts (the GPU process on ANGLE);5accb098glslang anonymous-struct samplers (Shadertoy page fault).
- X11:
198d6feaGLX via DRI3/Present;08f23543glFlush implicit sync for glamor;5de6ecd4,7fd965ceshared-image upload and publish;cd58f048inactive fragment output location;316ffe02never dial its own X display.
- glvnd:
69e96f5b,4095624f,4f679d66,3d69c375,552dd3d3. - Present:
74919a3b/7090e31dbuffer age and damage;- Espryt fixes
815217cc(scissor shadow is per-session),c822a9fe,228bd24c; 1ff7ca53/caa00995frame-callback pacing;5a7b23f6/258b9460/16b07cf4suspend, resume and resize.
- Shared images:
38842985,3d17e8c1,350fc699,67226176,b5cab441,7520e53b. - Misc:
8da082f8clear colour starts at (0,0,0,0);51c37bcbsampler param conversion;15f9b27asampler CSO per share group;239fc228gl_FragCoord access chains;bfa7987cMagma declines invalid SPIR-V;6125f941surfaceless/no-config EGL;4633ca22frame-stats log gated (MOBILEGL_SERVER_FRAME_STATS);2a1889b8gtest 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)
- CI: retrace failures (see stream 2) and whatever the
2d424146run still shows red. - Fullscreen performance at about half of stock (see stream 1).
- 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.
- 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.
- Chrome doesn't use buffer age (full-frame repaints). The Magma text-caret frame costs about 24 ms.
- A rare Magma X11 rectangle glitch. The readback GLX fallback is slower with glamor.
- Two GoldControllerTest failures on Windows hosts. MSVC builds of this branch are broken; build tests in WSL with clang.
- Leftovers:
- container probe files under
~swung0x48/yuvtestand the localv.htmltabs 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).
- container probe files under
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-bldand~/sysroots. Don't touchwgl-hostor~/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.