mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-18 07:23:24 +09:00
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.
526 lines
34 KiB
Markdown
526 lines
34 KiB
Markdown
# 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.
|