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.
34 KiB
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):
- Nothing in CI or in the phase gate ever configures
MOBILEGL_BUILD_DISAGGREGATED=ON. Not onecmakeinvocation in.github/workflows/test.ymlpasses it, andwsl_p4a_gate.shdoes not either — so every line ofMG_Remote/Transport/and all fiveMG_Test/Wiresuites are compiled by nothing today. P5 is the phase that must create the firstONconfiguration. ClearThenReadPixelsScenarioexists;TriangleScenarioandPersistentCoherentMapScenariodo not exist in any form. Two new scenario files plus threegtest_discover_testsblocks.~/w7/retrace_gate.pystructurally cannot see aSPLIT-suffixed ctest name, because it parses a foreign referenceCTestTestfile.cmakefrom~/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, fiveHarness/*.cpp, then 85Scenarios/*.cpplines (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 thenTEST_F(XxxScenario, CaseName).ScenarioTestisHarness/ScenarioFixture.h:67-125; itsSetUpbrings up the shared headless context, skips (or, underMOBILEGL_ITEST_REQUIRE_GPU, fails —ScenarioFixture.h:73-84) when there is no GPU, and exposesReady()as the only legal gate a derivedSetUpmay use (:106-109).Main.cpp:61-65installs 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 fromMOBILEGL_BACKEND_TYPEat 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:
Scenarios/TriangleScenario.cppandScenarios/PersistentCoherentMapScenario.cpp, added toCMakeLists.txt's source list around line 143.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}). TheMOBILEGL_IPC_SERVER_PATHentry is required byARCHITECTURE.md:543: "每条新 ctestENVIRONMENT与add_trace_replay_test的SPLIT分支带MOBILEGL_IPC_SERVER_PATH" — because the integration test linksMobileGL_sstatically anddladdrfallback cannot find the server.- Two (or three)
gtest_discover_tests(... TEST_PREFIX "DirectGLES.Split." TEST_FILTER "<Scenario>.*" ...)blocks. Use one block per scenario, following theDirectGLES.MapPersistentRoundtrips.precedent at:1377-1394: a:-separated multi-patternTEST_FILTERis not used anywhere in this file today, so its CMake/list escaping is unproven (guess: it would work, sinceTEST_FILTERis forwarded to--gtest_filter, but two blocks cost nothing and are already proven). - 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=errortest.yml:293-298—ctest -L integration-gpu --no-tests=error, then the same whole label again withMOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1exported in the job environment (deliberately not a ctest property,:290-292)test.yml:547/549—ctest -L integration-verify --no-tests=errortest.yml:633— a filtered-L integration-gpurun for the handle-ABA/CSO/subsystem controlstest.yml:850—ctest -L benchmark- the retrace jobs do not use the
retracelabel at all; they select by anchored name regex (test.yml:1187,:1338) wsl_p4a_gate.sh:52-63—-L unitin all three build dirs,-L integration-gpuin build-linux and build-push (plus re-runs atMOBILEGL_PIPE_PUSH=0 / 0x1ff / 0x7f),-L integration-verifyin 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=errorin a build that forgot-DMOBILEGL_BUILD_DISAGGREGATED=ONmatches nothing and fails, instead of reporting a green run of nothing (:1025-1028, the verify block's own argument for this); - keeping
integration-gputoo is why "a verify build'sctest -L integration-gpustill 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:
run_trace_case.cmakeconsumes the transport. Two possible spellings. (a) environment — addTRACE_TRANSPORTto the required/optional list at:1-29andset(ENV{MOBILEGL_TRANSPORT} "${TRACE_TRANSPORT}")before theexecute_processat:54. This has exact precedent: the file already reads$ENV{MOBILEGL_PIPE_VERIFY}at:153and turns it into three assertions (:153-190). Zero C++ change, andcmake -P's child inherits it. (b) CLI flag — a new--transportintrace_replay_cli.cpp, a newrequestfield, a newsetenvintrace_replay_core.cppbeside:161. Matches how--backendworks. 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).add_trace_replay_testgrows a variant/suffix parameter.ARCHITECTURE.md:584is explicit: theSPLITsuffix exists because otherwise the entry collides with the same case+backend (add_testwith a duplicate NAME is a hard CMake error). The name line to change isCMakeLists.txt:351; the-Dblock to extend is:352-372; theset_tests_propertiesat:373-381must also carryMOBILEGL_IPC_SERVER_PATH(ARCHITECTURE.md:543).trace_cases.pyhas no notion of a variant.github_test_matrix(:111-118) emits{backend, case}only;emit_cmake(:143-172) emits oneadd_trace_replay_test_for_backends(...)per case. A split subset would mirror the existingverifyflag exactly —verifyis validated at:29-38, filtered at:85-92, and surfaced asgithub-verify-matrixat:121-122and--formatat:180-192. Asplit: trueflag plus agithub-split-matrixformat is a four-hunk change of the same shape.test.yml's retrace job cannot match a suffixed name.test.yml:1187isctest -V --no-tests=error -R '^MobileGLTraceReplay\.${{ matrix.case }}\.${{ matrix.backend }}$'— anchored at both ends, so...DirectGLES.SPLITnever 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 eachadd_testargv and itsENVIRONMENTproperty.wanted()(:47-50) requires the name to matchr'MobileGLTraceReplay\.(.+)\.(DirectGLES|DirectVulkan)$'andgroup(2)to be in the tree'sci_backendsforgroup(1). A trailing.SPLITfails the regex outright; an infix.SPLIT.makesgroup(1)="OpenRA.SPLIT", which misses theci_backendsdict (: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 therun_trace_case.cmakepath (:59-68). A-DTRACE_TRANSPORT=would pass through unchanged — but the reference file emits none.env = dict(os.environ)at:70, then the per-testENVIRONMENTon 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:70inherits it. This is character-for-character whatwsl_p4a_gate.sh:69already does forMOBILEGL_PIPE_VERIFY=1, and whattest.yml:1334does 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-testENVIRONMENTfrom the reference file is applied afteros.environ(:71-72), so this works only because no reference entry namesMOBILEGL_TRANSPORT. - Full, needed for the
SPLITctest name to mean anything: pointREFat abuild-retraceconfigured from~/w7/pipeitself, and relaxwanted()/theci_backendslookup to tolerate a variant segment. NoteREF_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— clonebuild-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"nmstep at:415-437, asserting anMG_Remotesymbol 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— cloneintegration-verify(:484-743), runningctest -L integration-split --no-tests=errorplus a whole-label-L integration-gpurun underMOBILEGL_TRANSPORT=inprocin the job env (theDISABLE_INVALIDATE_FLUSHprecedent at:290-298is exactly this: a knob that must not be a ctest property so it reaches every entry).retrace-split— cloneretrace-verify(:1246-1400), see §3.3.trace-casesgains asplit-matrixoutput besideverify-matrix(:1012-1027) if the split retrace arm is a subset (recommended:OpenRAonly, 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_DISAGGREGATEDbuild-linux-verify:384-397— no, and the comment at:375-382says so explicitly: "this job needs neither a Debug log level norMOBILEGL_BUILD_DISAGGREGATED"build-retrace:944-955— nomonolith-symbol-report:1461-1472and:1477-1489— passes=OFFtwice, on purpose, as the G1 control, then asserts at:1491-1500that the pull build defines noMG_Remotesymbol
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 inCMakeLists.txt;ARCHITECTURE.md:581and the switch table at:595list it as "计划(P5)".MG_Config::Transport— a grep ofMobileGL/Config.handMobileGL/ConfigLoader.cppforTransportreturns nothing.MOBILEGL_TRANSPORTparsing is P5 work (ARCHITECTURE.md:583).- The
Init.cpphook —MG_Backend/Init.cpp:49-63is a plainswitch (MG_Config::ActiveBackendType)withDirectGLES/DirectVulkan/Unknownarms and no#if.ARCHITECTURE.md:29: "分支在 P5 落地;P0 的Init.cpp尚未含它". MG_Remote/Client/andMG_Remote/Server/directories — do not exist. The tree has onlyMG_Remote/Protocol/(3 files) andMG_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-tests;
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)
- A fourth build dir
build-split:$COMMON -DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_BUILD_DISAGGREGATED=ON(and-DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ONonce it exists). Same fail-fast rule as:25. - Part 1 gains the surviving byte equality
ARCHITECTURE.md:524:nm --defined-only build-linux/libMobileGL.so | grep MG_Remotemust be empty, andnm -D build-split/libMobileGLServer.so | grep mobilegl_server_mainmust hit in RelWithDebInfo. Neither is asserted anywhere today outsidetest.yml:1491-1500(workflow_dispatch-only). - Part 3 gains the split A/B:
ctest -L unitinbuild-split— this is the first run of the fiveMG_Test/Wiresuites — plusctest -L integration-gputhere underMOBILEGL_TRANSPORT=monolithand again under=inproc, diffed name-for-name (the G2 shape, extended to a third arm, whichARCHITECTURE.md:521asks for verbatim: "ctest -L integration-gpu在DirectGLES.与DirectGLES.Pipe./DirectGLES.Split.之间逐名相同"). Plusctest -L integration-split(falsifiability: it must match something). - 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. - Peak RSS for both roles is a brand-new measurement. Nothing in the tree or in
~/w7/notes/tools/measures RSS: a grep formaxrss|VmHWM|peak rss|peakRssacross all*.py/*.sh/*.cpp/*.h/*.yml/*.cmakeoutsidebuild*/3rdpartyreturns 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 -vor/proc/<pid>/status:VmHWMsampling around the inproc retrace, recorded into MEASUREMENTS rather than gated. persistent-map-push出数 likewise needs a counter published throughPipeStats, the waympr=is (MG_Util/Metrics/PipeStats.h:126, emitterMG_Impl/Pipe/PipeFill.cpp:736), and a scenario that reads the summary line back from a per-laneMOBILEGL_LOG_FILE_PATHwith aRESOURCE_LOCK— the rule atMG_IntegrationTest/CMakeLists.txt:802-815and:1318-1322(the library opens its logfopen(path,"w"), so every process in a lane truncates it; a log-reading case needs a lane whoseTEST_FILTERselects it alone).
7. Traps worth repeating in the brief
- ctest
ENVIRONMENTreplaces, 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 ambientVerify.lanes deliberately name neitherMOBILEGL_PIPE_VERIFY_CORRUPTnorMOBILEGL_PIPE_POISON_OMIT, precisely so CI's job-level exports can reach them (:1040-1043). A split lane that wants a job-levelMOBILEGL_TRANSPORToverride must likewise not name it in its property. ;inside anENVIRONMENTorLABELSvalue must be escaped\;(:321-331,:1684).- A log-reading case needs its own lane, its own
MOBILEGL_LOG_FILE_PATH, and aRESOURCE_LOCKnamed after that log (:802-815) — measured: 3 runs of the full label at-j 8produced 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_LOCKexists (:813-815). gtest_discover_testsruns--gtest_list_testsat 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": afile(GLOB_RECURSE … CONFIGURE_DEPENDS)content probe for a symbol, never a filename (:389-398argues this at length). If P5's Split lanes need to skip beforeMG_Remote/Clientexists, copymgl_itest_probe_for_symbol(:402-414) rather than inventing a guard.