Files
MobileGL/docs/Disaggregated/notes/p5/scout-test-ci-plumbing.md
T
swung0x48 aba329cc53 [Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.

1. P6's plan and contract draft (neither started; not one line of code)

     docs/Disaggregated/P6-SPAWN-PLAN.md      the package plan
     docs/Disaggregated/P6-CONTRACT-DRAFT.md  the contract draft (moves to
                                              MG_Remote/CONTRACT-P6.md when c6 lands)

   The three findings that mattered, all written into the documents:

   a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
      the tree and already tested: SocketDoorbell including hangup detection and the two
      lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
      passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
      protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
      SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
      assembly plus a control plane plus a process, not "write a socket transport".

   b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
      audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
      the tree again. So the first package, a6, is a read-only audit that writes no code, and
      every contract row that depends on it is marked PENDING a6 rather than decided in
      advance.

   c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
      and protocol.fbs:186-196's own comment says Android transfers the window out of band -
      that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
      the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
      gate measures. A real window reaching the server is a named refusal. This gets its own
      section because "P6 is done" would otherwise read as "the game runs now".

   The contract adds rule G: a role may not name a process-local handle. It extends P5c's
   rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
   EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
   a token this contract defines or they do not cross, and a descriptor crosses only through
   SCM_RIGHTS, where the kernel renumbers it.

   What P5e left for P6 gets its own section. The latch semantics are already designed
   (ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
   client no longer waits while the peer process can DIE: the client holds records that were
   published and will never be applied, and Android's freezer suspends the child without
   closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
   That is P6's only new design; everything else is carriage. It shares a predicate with E1's
   outstanding re-specification (ID-122), and the two should be designed together.

   Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
   match integration-split's name for name, because a differing set means the lane is quietly
   running less; and the arm-proof gate requires every entry to record the child pid and
   transport=spawn in its OWN private log - ID-124 established that this kind of false green
   really happens, and a spawn lane that actually ran monolith would pass every other gate.
   S2's shape must be settled before it is written, and the document says why: E1 is the
   cautionary case.

2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)

   ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
   the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
   is under no version control. A record cited hundreds of times that lives only locally is not
   a record, so it moves in whole, with its directory structure intact.

   Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
   stay where they are: they are evidence DATA rather than documents - large, regenerated per
   run, and mostly carrying absolute paths and device serials that mean something only on the
   machine that produced them. The mapping and this split are written in
   docs/Disaggregated/notes/README.md.

   Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
   document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
   material salvaged from failed workflow runs, which may duplicate the like-named phase
   directories and is kept because a few of those were the only complete version at the time.

   CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
   deliberately outside it: those notes' file:line citations were written against their own
   code heads, and resolving them against today's HEAD would fail wholesale - which is not an
   error, it is their correct state as a historical record. To check one, use the revision it
   declares (--rev).

3. Inconsistencies fixed in passing

   - README.md's status line still said P5e was in progress while the stage table already said
     closed.
   - CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
     (a) and (b) were run in the previous commit; rewritten to closed plus the one item that
     actually remains (E1).
   - ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
     package order, the scope boundary and the two new gates.

Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
2026-09-18 23:31:39 -04:00

526 lines
34 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P5 scout — test/CI plumbing a SPLIT arm needs
Read-only survey of `/home/swung/w7/pipe` @ a29807cc (P4a landed). Nothing built, nothing run,
nothing edited. Paths are tree-relative unless they start with `~`.
**The three headline facts** (also the return summary):
1. **Nothing in CI or in the phase gate ever configures `MOBILEGL_BUILD_DISAGGREGATED=ON`.** Not
one `cmake` invocation in `.github/workflows/test.yml` passes it, and `wsl_p4a_gate.sh` does
not either — so every line of `MG_Remote/Transport/` and all five `MG_Test/Wire` suites are
compiled by nothing today. P5 is the phase that must create the first `ON` configuration.
2. **`ClearThenReadPixelsScenario` exists; `TriangleScenario` and `PersistentCoherentMapScenario`
do not exist in any form.** Two new scenario files plus three `gtest_discover_tests` blocks.
3. **`~/w7/retrace_gate.py` structurally cannot see a `SPLIT`-suffixed ctest name**, because it
parses a *foreign* reference `CTestTestfile.cmake` from `~/mgl/MobileGL/build-retrace/` rather
than the tree under test, and its name regex rejects the suffix.
---
## 1. The integration test harness (`MobileGL/MG_IntegrationTest`)
### 1.1 How a scenario is registered
Three layers, all explicit — no globbing anywhere:
* **One executable**: `MobileGLIntegrationTest`, `MG_IntegrationTest/CMakeLists.txt:51-144`. The
source list is hand-written: `Main.cpp`, five `Harness/*.cpp`, then 85 `Scenarios/*.cpp` lines
(52-143). A new scenario file is invisible until a line is added here.
* **One gtest fixture per scenario file**: `class XxxScenario : public ScenarioTest {}` and then
`TEST_F(XxxScenario, CaseName)`. `ScenarioTest` is `Harness/ScenarioFixture.h:67-125`; its
`SetUp` brings up the shared headless context, skips (or, under
`MOBILEGL_ITEST_REQUIRE_GPU`, fails — `ScenarioFixture.h:73-84`) when there is no GPU, and
exposes `Ready()` as the *only* legal gate a derived `SetUp` may use (`:106-109`).
`Main.cpp:61-65` installs only a banner `::testing::Environment`, so `--gtest_list_tests`
(what CMake discovery runs) never touches EGL.
* **ctest names = `TEST_PREFIX` + gtest name.** The backend is latched from
`MOBILEGL_BACKEND_TYPE` at init, i.e. one process = one backend, so the *same binary* is
registered many times with different prefixes and environments.
### 1.2 How `DirectGLES.` / `DirectVulkan.` are built
Two ambient registrations:
```
gtest_discover_tests(MobileGLIntegrationTest
TEST_PREFIX "DirectGLES." ... ENVIRONMENT "${MGL_ITEST_GLES_ENVIRONMENT}") # :738-745
gtest_discover_tests(MobileGLIntegrationTest
TEST_PREFIX "DirectVulkan." ... ENVIRONMENT "${MGL_ITEST_VULKAN_ENVIRONMENT}") # :747-754
```
and then **23 further "lane" registrations**, each = `TEST_PREFIX` + `TEST_FILTER` +
`PROPERTIES {LABELS, TIMEOUT, [RESOURCE_LOCK], ENVIRONMENT}`. Representative shapes P5 should
copy:
| lane | line | shape |
|---|---|---|
| `DirectVulkan.AsyncCompile.` | 767-775 | whole scenario, one env knob pinned |
| `DirectGLES.ForcedDepthStencilEmulation.` | 785-793 | wildcard filter `DepthStencilReadback*Scenario.*` |
| `DirectGLES.UnlocatedIoBlocks.` | 816-825 | adds `RESOURCE_LOCK <logfile>` because the case reads the library log |
| `DirectGLES.MallocPerturb.` | 838-846 | single case by full name in `TEST_FILTER` |
| `DirectGLES.MapPersistentRoundtrips.` | 1377-1394 | **two registrations sharing one prefix**, different `TEST_FILTER` each |
| `DirectGLES.ObjectSubsystemControl.{On,Off,Refused,...}` | 1512-1565 | one lane per bitmask arm |
Environment strings are *never* written inline. They are assembled by
`mgl_itest_join_environment()` (`:321-331`), which escapes the `;` separators — without it only
the first entry survives `gtest_discover_tests`' flat `PROPERTIES` forwarding (`:315-320`). And
every list **must append `${MGL_ITEST_COMMON_ENV}` / `${MGL_ITEST_VULKAN_ENV}`**, because a ctest
`ENVIRONMENT` property *replaces* rather than adds, so an entry naming only its own knobs silently
loses the EGL-vendor / Vulkan-ICD pinning (`:678-682`, restated at `:1036-1039` and `:1064-1066`).
### 1.3 What it takes to add `DirectGLES.Split.*`
**`ClearThenReadPixels` exists.** `Scenarios/ClearThenReadPixelsScenario.cpp`; fixture declared at
`:60`; five cases at `:80, :143, :191, :241, :308`; already in the source list at
`CMakeLists.txt:76`. So `DirectGLES.Split.ClearThenReadPixelsScenario.*` needs **only** a
registration block.
**`Triangle` does not exist.** There is no `TriangleScenario` anywhere in the tree. A whole-tree
grep for `Triangle` under `MobileGL/` returns only helper functions inside other scenarios:
`PostLinkAttachScenario.cpp:204` `DrawFullViewportTriangle`, `RelinkStageSetScenario.cpp:212`
`DrawTriangle`, `ClipDistanceScenario.cpp:134` `DrawClippedTriangle`,
`PipelineFailureScenario.cpp:86` `FullscreenTriangleStrip`. Two readings of the gate row:
(a) P5 authors a new minimal `Scenarios/TriangleScenario.cpp` (one VBO, one program, one
`glDrawArrays`, one `glReadPixels`) — this is what `ROADMAP.md:21`'s literal
`DirectGLES.Split.*(ClearThenReadPixels|Triangle)` reads as; or (b) the gate is satisfied by
pointing the Split prefix at an existing draw scenario. **Evidence that settles it**: the same
ROADMAP row also demands `PersistentCoherentMapScenario`, which likewise exists nowhere but in
`ARCHITECTURE.md:500` — a phase that is expected to author one new scenario file is being asked
for two. I read the gate as (a).
**`PersistentCoherentMapScenario` does not exist.** Only citations:
`docs/Disaggregated/ARCHITECTURE.md:500` (map `PERSISTENT|WRITE|COHERENT`, write, no other GL
call, draw, readback) and `ROADMAP.md:21`. New file + new source-list line + registration.
So the P5 integration-test package is, concretely:
1. `Scenarios/TriangleScenario.cpp` and `Scenarios/PersistentCoherentMapScenario.cpp`, added to
`CMakeLists.txt`'s source list around line 143.
2. `mgl_itest_join_environment(MGL_ITEST_GLES_SPLIT_ENVIRONMENT "MOBILEGL_BACKEND_TYPE=DirectGLES"
"MOBILEGL_TRANSPORT=inproc" "MOBILEGL_IPC_SERVER_PATH=..." ${MGL_ITEST_CAPABILITY_ENV}
${MGL_ITEST_COMMON_ENV})`. The `MOBILEGL_IPC_SERVER_PATH` entry is required by
`ARCHITECTURE.md:543`: "每条新 ctest `ENVIRONMENT` 与 `add_trace_replay_test` 的 `SPLIT`
分支带 `MOBILEGL_IPC_SERVER_PATH`" — because the integration test links `MobileGL_s`
statically and `dladdr` fallback cannot find the server.
3. Two (or three) `gtest_discover_tests(... TEST_PREFIX "DirectGLES.Split." TEST_FILTER
"<Scenario>.*" ...)` blocks. **Use one block per scenario**, following the
`DirectGLES.MapPersistentRoundtrips.` precedent at `:1377-1394`: a `:`-separated multi-pattern
`TEST_FILTER` is not used anywhere in this file today, so its CMake/list escaping is unproven
(guess: it would work, since `TEST_FILTER` is forwarded to `--gtest_filter`, but two blocks
cost nothing and are already proven).
4. Gate it on the build option, or not — see §2.
**Two standing rules the lane must not break.** (i) *G2*: `ctest -L integration-gpu` must be
name-for-name identical between the pull build and the push build (`:366-369`, and
`wsl_p4a_gate.sh:50` measures it). A Split family registered inside
`if (MOBILEGL_BUILD_DISAGGREGATED)` is absent from *both* of those builds, so G2 is untouched.
Registered unconditionally, it is present in both, so G2 is *also* untouched — but then the lane
either skips (if it reports "this build has no transport") or goes red. The house answer for a
capability a build may lack is a SKIP that names the missing thing, never a deleted registration
(`:341-345`). (ii) *G14*: an existing ctest name may never disappear (`:813-815`);
`wsl_p4a_gate.sh:51` counts removed/added against `~/w7/p4a-before-ctest-names.txt`. Adding names
is fine; P5 will want a fresh `~/w7/p5-before-ctest-names.txt` snapshot.
---
## 2. ctest labels
Five labels exist in the tree (plus one stray). Full inventory from a `LABELS` grep over all
`CMakeLists.txt`/`*.cmake` outside `build*` and `3rdparty`:
| label | where | count |
|---|---|---|
| `unit` | every `MG_Test/**/CMakeLists.txt`; `MG_Test/CMakeLists.txt:65`; **`MG_Test/Wire/CMakeLists.txt:35`** | ~45 registrations |
| `integration-gpu` | `MG_IntegrationTest/CMakeLists.txt` — 25 registrations (`:742` … `:1755`) | 25 |
| `integration-verify` | only inside `if (MOBILEGL_PIPE_VERIFY)` (`:1614-1759`), always paired: `LABELS "integration-gpu\;integration-verify"` at `:1684, :1692, :1706, :1715, :1728, :1737, :1746, :1755` | 8 |
| `retrace` | `tools/trace_replay/CMakeLists.txt:376, :380` | all trace cases |
| `benchmark` | `MG_Benchmark/**` (`CMakeLists.txt:41`, `Driver/CMakeLists.txt:35,60`, …) | 6 |
| `integration` (stray) | `MG_Test/Backend/DirectVulkan/CMakeLists.txt:52` — `DirectVulkanSanityTest` | 1; **nothing in CI selects it** |
How the phase gates select them:
* `test.yml:204/206` — `ctest -L unit --no-tests=error`
* `test.yml:293-298` — `ctest -L integration-gpu --no-tests=error`, then the *same whole label*
again with `MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1` exported in the **job** environment
(deliberately not a ctest property, `:290-292`)
* `test.yml:547/549` — `ctest -L integration-verify --no-tests=error`
* `test.yml:633` — a filtered `-L integration-gpu` run for the handle-ABA/CSO/subsystem controls
* `test.yml:850` — `ctest -L benchmark`
* the retrace jobs do **not** use the `retrace` label at all; they select by anchored name regex
(`test.yml:1187`, `:1338`)
* `wsl_p4a_gate.sh:52-63` — `-L unit` in all three build dirs, `-L integration-gpu` in
build-linux and build-push (plus re-runs at `MOBILEGL_PIPE_PUSH=0 / 0x1ff / 0x7f`),
`-L integration-verify` in build-verify (`:66`)
**What label a Split arm should carry.** Copy the verify precedent exactly: `LABELS
"integration-gpu\;integration-split"`. Both halves matter and are argued in-file:
* the **second, private label** is what makes the lane falsifiable — `ctest -L integration-split
--no-tests=error` in a build that forgot `-DMOBILEGL_BUILD_DISAGGREGATED=ON` matches nothing
and *fails*, instead of reporting a green run of nothing (`:1025-1028`, the verify block's own
argument for this);
* keeping **`integration-gpu`** too is why "a verify build's `ctest -L integration-gpu` still
describes the whole registration set" (`:1676-1679`) — the same sentence will want to be true
of a split build.
Note the escaping: a two-label list is written `"a\;b"`, not `"a;b"` (`:1684`).
---
## 3. The trace-replay harness
### 3.1 How a backend is chosen today
```
add_trace_replay_test(CASE_NAME BACKEND ...) tools/trace_replay/CMakeLists.txt:311
add_test(NAME MobileGLTraceReplay.${CASE_NAME}.${BACKEND} :350-351
COMMAND cmake -DTRACE_BACKEND=${BACKEND} ... -P run_trace_case.cmake) :352-372
set_tests_properties(... ENVIRONMENT "EGL_PLATFORM=surfaceless;LIBGL_ALWAYS_SOFTWARE=1;..."
LABELS retrace) :373-381
add_trace_replay_test_for_backends(CASE ...) = the same twice :384-387
```
Cases come from `trace_cases.json` through `trace_cases.py --format cmake`
(`CMakeLists.txt:389-397`; emitter at `trace_cases.py:143-172`). `OpenRA` is
`trace_cases.json:14-28` — `verify: true`, target call 31249, 640x480, crop 1,1,638,478,
default `ssim_threshold` 0.99 (`defaults` block `trace_cases.json:2-12`, and the CMake default at
`CMakeLists.txt:335-337`).
The backend reaches the library as: `-DTRACE_BACKEND=` → `run_trace_case.cmake:61` `--backend` →
`trace_replay_cli.cpp:130` → `android-plugin/app/src/trace/cpp/trace_replay_core.cpp:161`
`setenv("MOBILEGL_BACKEND_TYPE", ...)`. That `setenv` block (`trace_replay_core.cpp:136-260`) runs
immediately before `libMobileGL.so` is loaded, and ends with
`ApplyEnvOverrides(request.envOverrides)` (`:237`) — the generic `K=V;K=V` passthrough. **That
passthrough is reachable only from the Android path**: `trace_replay_core.hpp:70`
`envOverrides`, filled by `trace_replay_jni.cpp:158` and driven by
`android-plugin/trace-replay-ci.sh:174 --env` / `run_android_retrace_local.py:197,374`. The
desktop CLI has **no `--env` option** (`trace_replay_cli.cpp:116-179` — the full option list, no
env entry).
### 3.2 Where `SPLIT` and `-DTRACE_TRANSPORT=` have to be threaded
Four edits, in order of increasing cost:
1. **`run_trace_case.cmake` consumes the transport.** Two possible spellings.
*(a) environment* — add `TRACE_TRANSPORT` to the required/optional list at `:1-29` and
`set(ENV{MOBILEGL_TRANSPORT} "${TRACE_TRANSPORT}")` before the `execute_process` at `:54`. This
has exact precedent: the file already reads `$ENV{MOBILEGL_PIPE_VERIFY}` at `:153` and turns it
into three assertions (`:153-190`). Zero C++ change, and `cmake -P`'s child inherits it.
*(b) CLI flag* — a new `--transport` in `trace_replay_cli.cpp`, a new `request` field, a new
`setenv` in `trace_replay_core.cpp` beside `:161`. Matches how `--backend` works.
**Which is right is settled by** whether the split lane also needs the *Android* replay path
(`trace_replay_jni.cpp`) to carry the transport: the Android path already has `--env`, so (a)
covers desktop and Android both and (b) buys nothing. I'd brief (a).
2. **`add_trace_replay_test` grows a variant/suffix parameter.** `ARCHITECTURE.md:584` is explicit:
the `SPLIT` suffix exists because otherwise the entry collides with the same case+backend
(`add_test` with a duplicate NAME is a hard CMake error). The name line to change is
`CMakeLists.txt:351`; the `-D` block to extend is `:352-372`; the `set_tests_properties` at
`:373-381` must also carry `MOBILEGL_IPC_SERVER_PATH` (`ARCHITECTURE.md:543`).
3. **`trace_cases.py` has no notion of a variant.** `github_test_matrix` (`:111-118`) emits
`{backend, case}` only; `emit_cmake` (`:143-172`) emits one
`add_trace_replay_test_for_backends(...)` per case. A split subset would mirror the existing
`verify` flag exactly — `verify` is validated at `:29-38`, filtered at `:85-92`, and surfaced
as `github-verify-matrix` at `:121-122` and `--format` at `:180-192`. A `split: true` flag plus
a `github-split-matrix` format is a four-hunk change of the same shape.
4. **`test.yml`'s retrace job cannot match a suffixed name.** `test.yml:1187` is
`ctest -V --no-tests=error -R '^MobileGLTraceReplay\.${{ matrix.case }}\.${{ matrix.backend }}$'`
— anchored at both ends, so `...DirectGLES.SPLIT` never matches. A split arm needs its own job
(or a third matrix key folded into the regex).
### 3.3 What the retrace gate would need to run an inproc arm
`~/w7/retrace_gate.py` (109 lines). It does **not** read the tree's CMake:
* `REF = ~/mgl/MobileGL/build-retrace/tools/trace_replay/CTestTestfile.cmake` (`:14`) — a *foreign*
reference build. New tests added to `~/w7/pipe`'s CMakeLists will simply not be in this file.
* `parse()` (`:18-31`) lifts each `add_test` argv and its `ENVIRONMENT` property.
* `wanted()` (`:47-50`) requires the name to match
`r'MobileGLTraceReplay\.(.+)\.(DirectGLES|DirectVulkan)$'` **and** `group(2)` to be in the
tree's `ci_backends` for `group(1)`. A trailing `.SPLIT` fails the regex outright; an infix
`.SPLIT.` makes `group(1)` = `"OpenRA.SPLIT"`, which misses the `ci_backends` dict (`:46`) and
is **silently dropped** — the gate would report "39 of 39 passed" having never run the split arm.
* `run()` (`:54-92`) rewrites exactly five argv shapes — `-DMOBILEGL_LIBRARY=`,
`-DTRACE_OUTPUT_DIR=`, `-DTRACE_ARTIFACT_DIR=`, the three fixture paths, and the
`run_trace_case.cmake` path (`:59-68`). A `-DTRACE_TRANSPORT=` would pass through unchanged —
but the reference file emits none.
* `env = dict(os.environ)` at `:70`, then the per-test `ENVIRONMENT` on top (`:71-72`).
**So there are two P5 paths, and they cost very different amounts:**
* **Cheap, works today, zero code change**: run the *existing* names with the transport exported
in the process environment — `MOBILEGL_TRANSPORT=inproc python3 ~/w7/retrace_gate.py --tree
~/w7/pipe --lib ~/w7/pipe/build-split/libMobileGL.so --out ... --only OpenRA`. Line `:70`
inherits it. This is character-for-character what `wsl_p4a_gate.sh:69` already does for
`MOBILEGL_PIPE_VERIFY=1`, and what `test.yml:1334` does for the same knob in CI. The OpenRA
SSIM ≥ 0.99 gate is satisfied by the case's own default threshold, unchanged.
*Caveat*: the per-test `ENVIRONMENT` from the reference file is applied **after** `os.environ`
(`:71-72`), so this works only because no reference entry names `MOBILEGL_TRANSPORT`.
* **Full, needed for the `SPLIT` ctest name to mean anything**: point `REF` at a
`build-retrace` configured from `~/w7/pipe` itself, and relax `wanted()`/the `ci_backends`
lookup to tolerate a variant segment. Note `REF_FIX`/`REF_ROOT` (`:15-16`) also hard-code
`/home/swung/mgl/MobileGL/`.
A split retrace arm in CI has an exact template: **`retrace-verify`** (`test.yml:1246-1400`). It
reuses the *unchanged* ctest names, swaps the library into the frozen
`build-linux/libMobileGL.so` path (`:1303-1322`, with an `nm` check that makes the swap
falsifiable), exports the mode knob in the job env (`:1334`), and carries a one-case negative
control (`:1356-1385`). A `retrace-split` job is that file, with `MOBILEGL_PIPE_VERIFY=1` →
`MOBILEGL_TRANSPORT=inproc` and `MGPipeVerifyInputs` → an `MG_Remote` symbol.
---
## 4. `.github/workflows/test.yml`
### 4.1 Triggers, and the TEMPORARY one
```
on:
push:
branches:
- dev :6
- Feat/Backend-Direct-GLES :7
- Feat/Backend-Direct-Vulkan :8
# TEMPORARY, remove before merging the MGPipe work into dev: ...
- feat/disaggregated :9-12
workflow_dispatch: :13-21 (input: baseline_sha, default 087685d1)
```
The trigger is `test.yml:9-12`. It is not alone — **four job steps carry the same branch guard**
and are documented as retiring with it:
* `pipe-gates` → "The buffer pool, the deferred-release drain and the rings did not move (G5)"
and its self-test, `if: github.ref == 'refs/heads/feat/disaggregated' || github.event_name ==
'workflow_dispatch'` (`:1694`, `:1698`; rationale `:1684-1689`);
* the P4a twin of the same pair (`:1727`, `:1731`; rationale `:1714-1717`).
`~/w7/notes/p4a/INTEGRATOR-DECISIONS.md:730` and `:792` already carry it as an open cleanup item
("TEMPORARY test.yml:9-12 trigger still present (remove before dev)", "the TEMPORARY CI trigger
branch in test.yml/apk.yml (must be ...)"). **P5 must not build anything that only runs on that
branch**: new split steps should use `workflow_dispatch` or run unconditionally, so that the day
the four lines are deleted nothing of P5's goes dark.
### 4.2 The job matrix (18 jobs)
| job | line | needs | what it does |
|---|---|---|---|
| `build-linux` | 24 | — | the ordinary library + tests + integration + benchmark; artifact `mobilegl-linux-runtime` |
| `test` | 161 | build-linux | `ctest -L unit` |
| `integration` | 217 | build-linux | `ctest -L integration-gpu` twice (ambient + `DISABLE_INVALIDATE_FLUSH=1`) |
| `build-linux-verify` | 315 | — | `-DMOBILEGL_PIPE_VERIFY=ON`; artifact `mobilegl-linux-runtime-verify`; `nm` proof the comparator is in (`:415`) |
| `integration-verify` | 484 | build-linux-verify | `-L integration-verify`, `-L unit`, the control lanes, and two "this step passes when ctest FAILS" negative controls (`:676`, `:705`) |
| `flatc-check` | 745 | — | regenerates `protocol_generated.h` with an out-of-tree flatc and diffs; **compiles no MG_Remote code** |
| `include-graph-check` | 773 | — | include-closure purity gate |
| `benchmark` | 804 | build-linux | `-L benchmark` |
| `build-retrace` | 860 | build-linux(+) | builds `mobilegl_trace_replay`; artifact carries `build-retrace/tools/trace_replay/CTestTestfile.cmake` |
| `trace-cases` | 1005 | test, benchmark, integration | emits `matrix`, `names`, `verify-matrix` from `trace_cases.py` |
| `trace-fixtures` | 1029 | trace-cases | per-case fixture cache / LFS fetch / upload |
| `retrace` | 1094 | build-linux, build-retrace, trace-cases, trace-fixtures | one job per {case, backend}, `ctest -R '^…$'` |
| `retrace-summary` | 1200 | | |
| `retrace-verify` | 1246 | build-linux-verify, build-retrace, trace-cases, trace-fixtures | `verify-matrix` subset under `MOBILEGL_PIPE_VERIFY=1` |
| `monolith-symbol-report` | 1403 | — | **workflow_dispatch only**; builds the library twice with `-DMOBILEGL_BUILD_DISAGGREGATED=OFF` (`:1467`, `:1484`) and asserts `nm --defined-only … \| grep MG_Remote` is empty (`:1491-1500`) |
| `remove-artifact-clutter` | 1522 | | |
| `pipe-gates` | 1582 | — (deliberately independent of build-linux) | `gen_pipe.py` + self-test, `symbol_report.py --self-test`, the stdio-instrumentation grep, `gen_pipe_dirty_surface.py --check/--self-test`, the two untouched-region gates, the citation lint |
**Where a split arm slots.** The verify pair is a ready-made template and P5 should clone it:
* `build-linux-split` — clone `build-linux-verify` (`:315-482`) with
`-DMOBILEGL_BUILD_DISAGGREGATED=ON` (plus `-DMOBILEGL_PIPE_PUSH=ON`, since a remote backend
needs the pushed block) and its own artifact name. Copy the "the library really carries it"
`nm` step at `:415-437`, asserting an `MG_Remote` symbol instead of the comparator's. That step
is what makes the lane falsifiable, and its absence is precisely what would let a split lane
pass having run monolith.
* `integration-split` — clone `integration-verify` (`:484-743`), running
`ctest -L integration-split --no-tests=error` plus a whole-label `-L integration-gpu` run under
`MOBILEGL_TRANSPORT=inproc` in the **job** env (the `DISABLE_INVALIDATE_FLUSH` precedent at
`:290-298` is exactly this: a knob that must not be a ctest property so it reaches every entry).
* `retrace-split` — clone `retrace-verify` (`:1246-1400`), see §3.3.
* `trace-cases` gains a `split-matrix` output beside `verify-matrix` (`:1012-1027`) if the split
retrace arm is a subset (recommended: `OpenRA` only, which the gate names).
Note `build-linux` itself passes **no** `-DMOBILEGL_PIPE_PUSH` (`:91-105`), so it is a *pull*
build; the only push build in CI is the verify one (`MOBILEGL_PIPE_VERIFY=ON` forces
`MOBILEGL_PIPE_PUSH` ON, `CMakeLists.txt:467-473`). A split arm therefore cannot ride on
`build-linux`'s artifact.
---
## 5. `MOBILEGL_BUILD_DISAGGREGATED`
### 5.1 What the option gates
Declared `CMakeLists.txt:23`, default **OFF**, with the contract written at `:17-22`: with it OFF
"nothing under `MobileGL/MG_Remote/` is compiled, no include path is added, and no library is
linked, so `nm --defined-only libMobileGL.so | grep -i MG_Remote` is empty".
Four gated blocks, all in the root `CMakeLists.txt`:
| line | effect |
|---|---|
| `453-465` | if the flatbuffers submodule headers are missing, shadow the option OFF **as a normal variable, not a cache force** (`:460-463` explains why) |
| `503-520` | append 8 sources to `SOURCE_FILES`: `Transport/{Ring,Doorbell,ShmSegment,ShmSegmentPosix,ShmSegmentWin32,FdPassing,InProcessTransport,WireLog}.cpp` |
| `572-574` | append `-DMOBILEGL_BUILD_DISAGGREGATED=1` to `MOBILEGL_COMPILE_DEF` |
| `605-610` | append `3rdparty/flatbuffers/include` to the include path (header-only; no `add_subdirectory`, no flatc in the graph) |
Both library targets get the same `SOURCE_FILES`: `add_library(MobileGL SHARED ${SOURCE_FILES})`
at `:612-614` and `add_library(MobileGL_s STATIC ${SOURCE_FILES})` at `:681-684`. `MobileGL_s` is
what the desktop integration test links (`MG_IntegrationTest/CMakeLists.txt:29-37`), so a split
integration lane gets `MG_Remote` for free once the option is on.
One more thing the macro arms outside `MG_Remote`: the poison `#if` in
`MG_Backend/MGPipe/PipeInputs.h:19-21` has `MOBILEGL_BUILD_DISAGGREGATED` as its third arm.
`MG_Test/Wire` is registered **only** under the option: `MG_Test/CMakeLists.txt:105-106`
(`if (MOBILEGL_BUILD_DISAGGREGATED) add_subdirectory(Wire)`). Its five suites are
`Framing, Ring, InProcessTransport, ProtocolSmoke` + `FdPassing` on non-Windows
(`Wire/CMakeLists.txt:7-17`), all labelled `unit` (`:35`).
### 5.2 Is MG_Remote built in the normal CI configuration? **No.**
Every `cmake -S . -B` in `test.yml`, checked one by one:
* `build-linux` `:91-105` — no `-DMOBILEGL_BUILD_DISAGGREGATED`
* `build-linux-verify` `:384-397` — no, and the comment at `:375-382` says so explicitly: "this
job needs neither a Debug log level nor `MOBILEGL_BUILD_DISAGGREGATED`"
* `build-retrace` `:944-955` — no
* `monolith-symbol-report` `:1461-1472` and `:1477-1489` — passes **`=OFF`** twice, on purpose,
as the G1 control, then asserts at `:1491-1500` that the pull build defines no `MG_Remote`
symbol
`flatc-check` (`:745-771`) only runs `scripts/gen_protocol.py` against an out-of-tree flatc build
and diffs the committed header; it compiles nothing of `MG_Remote`.
Local evidence agrees: `build-linux/CMakeCache.txt:437`, `build-push/CMakeCache.txt:437`,
`build-verify/CMakeCache.txt:437`, `build-bench/CMakeCache.txt:489` and all three
`.cxx/*/arm64-v8a/CMakeCache.txt` read `MOBILEGL_BUILD_DISAGGREGATED:BOOL=OFF`.
`wsl_p4a_gate.sh:12` (`$COMMON`) and its three configures (`:19-23`) never set it either.
**Consequence to put in the P5 brief in bold**: `MG_Remote/Transport/*.cpp` and all five
`MG_Test/Wire` suites — written in P0 and never touched since — have **never been compiled or run
by any lane**. The first `-DMOBILEGL_BUILD_DISAGGREGATED=ON` configure in P5 may well be the first
time those files see a compiler on this branch's current HEAD. Budget for it.
### 5.3 What does not exist yet
* `MOBILEGL_BUILD_DISAGGREGATED_INPROC` — not in `CMakeLists.txt`; `ARCHITECTURE.md:581` and the
switch table at `:595` list it as "计划(P5)".
* `MG_Config::Transport` — a grep of `MobileGL/Config.h` and `MobileGL/ConfigLoader.cpp` for
`Transport` returns **nothing**. `MOBILEGL_TRANSPORT` parsing is P5 work
(`ARCHITECTURE.md:583`).
* The `Init.cpp` hook — `MG_Backend/Init.cpp:49-63` is a plain `switch (MG_Config::ActiveBackendType)`
with `DirectGLES` / `DirectVulkan` / `Unknown` arms and **no `#if`**. `ARCHITECTURE.md:29`:
"分支在 P5 落地;P0 的 `Init.cpp` 尚未含它".
* `MG_Remote/Client/` and `MG_Remote/Server/` directories — do not exist. The tree has only
`MG_Remote/Protocol/` (3 files) and `MG_Remote/Transport/` (16 files).
---
## 6. `~/w7/notes/tools/wsl_p4a_gate.sh` — the five parts
77 lines; `wsl_p4a_gate.sh quick` skips the three retrace sweeps (`:3`, `:67`). `BASE=37da3c3a`
(`:7`). It runs the parts in the order 1, 5, 3, 2 (fast source-level answers first).
**Preamble (`:5-25`)** — three build directories, all failure-fast so a stale binary can never
produce a verdict (`:25`):
* `build-linux` — pull, reconfigured in place (`:19`)
* `build-push` — `$COMMON -DMOBILEGL_PIPE_PUSH=ON` (`:20-21`)
* `build-verify` — `$COMMON -DMOBILEGL_PIPE_VERIFY=ON -DMOBILEGL_ITEST_REQUIRE_GPU=ON` (`:22-23`)
`$COMMON` (`:12`) pins clang + ccache + Release + INFO + TEST/INTEGRATION ON + BENCHMARK OFF +
the mesa EGL vendor + the lavapipe ICD. `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` (`:16`)
makes an exit-order UAF reproduce natively (ID-18/21).
**Part 1 — interface purity (`:27-38`)**
`check_include_closure.py`; gate C (`grep -rc pGLContext MobileGL/MG_Backend` must be empty);
G13 (`MG_State` must not be inside `MG_Pipe/PipeApply.h`'s ops block); G13b
(`MGPipeUnmigratedEmulation` site count in DirectGLES); G1 `symbol_report.py` against
`~/w7/p4a-before-libMobileGL.so` with `--threshold 0`; G5 `p3a_untouched_regions.sh` (eleven
regions) and `p4a_untouched_regions.sh` (seventeen) against `$BASE`; the `RenderStateImpl` sha vs
`~/w7/p4a-before-syncrenderstate.sha`; `ctest -R HandleRecycle` in build-verify.
**Part 5 — coverage, poison, handle discipline (`:40-46`)**
`gen_pipe.py --check` + `--self-test`; `gen_pipe_dirty_surface.py --check` + `--self-test`; the
emitter/CSO unit suites in build-push via `$UNIT_RE` (`:15`); both untouched-region `--self-test`s;
`PoisonOmitted.|VerifyCorrupted.` in build-verify.
**Part 3 — behavioural A/B (`:48-63`)**
G2 (`ctest -N` name diff, pull vs push, must be 0 lines — `:49-50`); G14 (removed/added vs
`~/w7/p4a-before-ctest-names.txt` — `:51`); `ctest -L unit` in all three dirs (`:52`);
`-L integration-gpu` in build-linux and build-push with `--rerun-failed` (`:53-54`); the same
whole label three more times at `MOBILEGL_PIPE_PUSH=0 / 0x1ff / 0x7f` (`:55`); once more under
`MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1` (`:56`); the 41-scenario `$FAMILY` regex (`:13`,
`:57`); G9 `TextureParamsWithoutASamplerView` (`:58`); `TextureUploadShape` (recorded, not gated —
`:59`); three negative-control scripts (`:60`); the CSO/Resource/Object subsystem controls plus
the `0x9ff` dependency-refusal arm (`:61-62`); the verify controls (`:63`).
**Part 2 — semantic shadow comparison (`:65-76`)**
`ctest -L integration-verify -j 4` in build-verify, counting and classifying `Fatal{` lines
(`:66`); then unless `quick`, three `retrace_gate.py` sweeps (`:68-75`): verify
(`MOBILEGL_PIPE_VERIFY=1`, build-verify's lib, then a check that every log carries
"MGPipe verify:" and none carries `Fatal{`), push (build-push's lib), and the `$NAMED` subset
(`:14` — `create-indirect|create-instancing|rd12-odinlite|improved-transparency-minecraft-26.3|fabric-sodium|photon-v1.3b`).
**Part 4 (device performance) is not in this script** — it lives in
`~/w7/notes/tools/wsl_p4a_bench.sh` and the A/B reducers beside it.
### P5's gate delta against this (proposal for the brief)
1. **A fourth build dir** `build-split`: `$COMMON -DMOBILEGL_PIPE_PUSH=ON
-DMOBILEGL_BUILD_DISAGGREGATED=ON` (and `-DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON` once it
exists). Same fail-fast rule as `:25`.
2. **Part 1 gains the surviving byte equality** `ARCHITECTURE.md:524`:
`nm --defined-only build-linux/libMobileGL.so | grep MG_Remote` must be **empty**, and
`nm -D build-split/libMobileGLServer.so | grep mobilegl_server_main` must **hit** in
RelWithDebInfo. Neither is asserted anywhere today outside `test.yml:1491-1500`
(workflow_dispatch-only).
3. **Part 3 gains the split A/B**: `ctest -L unit` in `build-split` — **this is the first run of
the five `MG_Test/Wire` suites** — plus `ctest -L integration-gpu` there under
`MOBILEGL_TRANSPORT=monolith` and again under `=inproc`, diffed name-for-name (the G2 shape,
extended to a third arm, which `ARCHITECTURE.md:521` asks for verbatim: "`ctest -L
integration-gpu` 在 `DirectGLES.` 与 `DirectGLES.Pipe.`/`DirectGLES.Split.` 之间逐名相同").
Plus `ctest -L integration-split` (falsifiability: it must match something).
4. **Part 2 gains an inproc retrace arm**: the zero-code-change form is
`MOBILEGL_TRANSPORT=inproc python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib
~/w7/pipe/build-split/libMobileGL.so --out ~/w7/retrace-out/p5-split -j 4 --only 'OpenRA'`
(§3.3). The gate row asks only for OpenRA ≥ 0.99.
5. **Peak RSS for both roles is a brand-new measurement.** Nothing in the tree or in
`~/w7/notes/tools/` measures RSS: a grep for `maxrss|VmHWM|peak rss|peakRss` across all
`*.py/*.sh/*.cpp/*.h/*.yml/*.cmake` outside `build*`/`3rdparty` returns three **comments**
only (`MG_State/GLState/ProgramState/ProgramLinkTask.h:105`,
`MG_Util/Async/ShaderCompilePool.h:79`, `MG_Util/Async/ShaderCompilePool.cpp:20`) and zero
hits under `~/w7/notes/tools/*.sh`. `--benchmark`'s JSON carries frame times only
(`trace_replay_cli.cpp:32-40`). So "两个角色峰值 RSS 在案" needs a new mechanism — cheapest is
`/usr/bin/time -v` or `/proc/<pid>/status:VmHWM` sampling around the inproc retrace, recorded
into MEASUREMENTS rather than gated.
6. **`persistent-map-push` 出数** likewise needs a counter published through `PipeStats`, the way
`mpr=` is (`MG_Util/Metrics/PipeStats.h:126`, emitter `MG_Impl/Pipe/PipeFill.cpp:736`), and a
scenario that reads the summary line back from a **per-lane** `MOBILEGL_LOG_FILE_PATH` with a
`RESOURCE_LOCK` — the rule at `MG_IntegrationTest/CMakeLists.txt:802-815` and `:1318-1322`
(the library opens its log `fopen(path,"w")`, so every process in a lane truncates it; a
log-reading case needs a lane whose `TEST_FILTER` selects it alone).
---
## 7. Traps worth repeating in the brief
* ctest `ENVIRONMENT` **replaces**, never appends; a property entry **overrides the job env**
(`MG_IntegrationTest/CMakeLists.txt:678-682`, `:1036-1043`). That last point is load-bearing in
the other direction too: the ambient `Verify.` lanes deliberately name *neither*
`MOBILEGL_PIPE_VERIFY_CORRUPT` nor `MOBILEGL_PIPE_POISON_OMIT`, precisely so CI's job-level
exports can reach them (`:1040-1043`). A split lane that wants a job-level `MOBILEGL_TRANSPORT`
override must likewise not name it in its property.
* `;` inside an `ENVIRONMENT` or `LABELS` value must be escaped `\;` (`:321-331`, `:1684`).
* A log-reading case needs its own lane, its own `MOBILEGL_LOG_FILE_PATH`, and a
`RESOURCE_LOCK` named after that log (`:802-815`) — measured: 3 runs of the full label at
`-j 8` produced 4 / 0 / 2 spurious failures without it.
* An existing ctest name may never disappear (G14); renaming to fix a race is not allowed, which
is why `RESOURCE_LOCK` exists (`:813-815`).
* `gtest_discover_tests` runs `--gtest_list_tests` at build time; it must not need a GPU, a
transport, or a server process. A Split registration that made discovery spawn anything would
break every build.
* The P4a-era capability markers (`MGL_ITEST_CAPABILITY_ENV`, `:358-655`) are the house pattern
for "this arm only asserts once the owning package landed": a `file(GLOB_RECURSE …
CONFIGURE_DEPENDS)` content probe for a **symbol**, never a filename (`:389-398` argues this at
length). If P5's Split lanes need to skip before `MG_Remote/Client` exists, copy
`mgl_itest_probe_for_symbol` (`:402-414`) rather than inventing a guard.