mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-18 23:43:23 +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.
252 lines
32 KiB
Markdown
252 lines
32 KiB
Markdown
|
||
---
|
||
|
||
## D. Integration order, and what the integrator runs
|
||
|
||
### D.0 Preconditions
|
||
|
||
- The baseline captures of §A (`~/w7/p2-before-libMobileGL.so`, `~/w7/p2-before-ctest-names.txt`, `~/w7/p2-before-syncrenderstate.sha`, `~/w7/p2-before-dirty-surface.txt`), taken in `~/w7/pipe` at `48268068` **before any package lands**.
|
||
- `~/w7/pipe` clean at `48268068`; fixture binaries hidden the way `wsl_p2_tree.sh` does it (`git update-index --assume-unchanged` on `tools/trace_replay/fixtures`).
|
||
- `~/w7/retrace_gate.py` copied from `scratchpad/wf2/retrace_gate.py`.
|
||
- Both devices reachable and **not** locked by the GL4.6 Wave-7 campaign (`ls .../8ab6b3cb-.../scratchpad/w7/locks/`).
|
||
|
||
### D.1 Order: **contract → tracker → magma → espryt → gates**
|
||
|
||
Reason for that order, and it is not P1's by default:
|
||
|
||
- `contract` first because everything else compiles against it.
|
||
- `tracker` second because it is the only package that changes semantics; after it, both backends are still reading the same bytes they read before, through unmodified code. If `tracker` is wrong, the verify lane says so before any backend has been touched.
|
||
- `magma` third rather than last, because D's `m1`/`m2` (the render-state re-key) is the deliverable the day-43 number depends on and it is the one most likely to need iteration; `m3`/`m4` (subsystem 4) then land against a Magma that is already CSO-keyed.
|
||
- `espryt` fourth: Espryt needs **zero** render-state change by construction (G5), so C is purely Track H and is independent of everything except the contract.
|
||
- `gates` last, so its lanes assert against the finished tree — except `HandleRecycleScenario`, whose `AbaControl` red is recorded on the contract tree at D.2.
|
||
|
||
Copy `scratchpad/wf2/wsl_integrate_p05.sh` → `wsl_integrate_p2.sh` (`p05`→`p2`). Per slug: rebase `p2/<slug>` onto `feat/disaggregated` in its own worktree, `git merge --ff-only` in `~/w7/pipe`, then:
|
||
|
||
```sh
|
||
cmake --build build-linux --parallel 28 && ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
|
||
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test
|
||
python3 scripts/gen_pipe_dirty_surface.py --check # from `tracker` onward
|
||
python3 scripts/check_include_closure.py
|
||
python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so \
|
||
--threshold 0 --markdown ~/w7/p2-symbol-<slug>.md
|
||
# 0 added / 0 removed / 0 renamed after every merge; resized ⊆ the three RenderState symbols of D15
|
||
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # empty
|
||
awk '/namespace RenderStateImpl \{/,/\} \/\/ namespace RenderStateImpl/' MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp | sha256sum
|
||
# equal to ~/w7/p2-before-syncrenderstate.sha after EVERY merge (G5)
|
||
ctest --test-dir build-linux -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort | comm -23 ~/w7/p2-before-ctest-names.txt - # empty
|
||
```
|
||
|
||
### D.2 On the contract tree, before `tracker`: record the "red before" evidence
|
||
|
||
```sh
|
||
cd ~/w7/p2-gates && cmake --build build-verify --parallel 28
|
||
ctest --test-dir build-verify -R HandleRecycle --no-tests=error --output-on-failure | tee ~/w7/p2-handlerecycle-before.log
|
||
# .AbaControl PASSES (it asserts the corrupted pixels), .Legacy PASSES, .Handles SKIPs
|
||
```
|
||
That log is the artefact `ROADMAP.md:18`'s "重键前红" asks for. Keep it; it goes into `MEASUREMENTS.md`.
|
||
|
||
### D.3 After every package has landed: the five-part gate on `~/w7/pipe`
|
||
|
||
**Part 1 — interface purity.**
|
||
```sh
|
||
python3 scripts/check_include_closure.py # gate A
|
||
nm --undefined-only build-linux/libMobileGL.so | grep -E 'MG_State::GLState::|glslang' ; echo rc=$? # gate B (n/a in monolith; recorded)
|
||
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # gate C: empty
|
||
ctest --test-dir build-verify -R HandleRecycle --no-tests=error --output-on-failure # the {slot,gen} memo-key assertion (G8)
|
||
```
|
||
|
||
**Part 2 — the semantic shadow comparison (the decisive one).**
|
||
```sh
|
||
cmake --build build-verify --parallel 28
|
||
ctest --test-dir build-verify -L unit --no-tests=error --output-on-failure
|
||
ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4 --output-on-failure
|
||
MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-verify/libMobileGL.so \
|
||
--out ~/w7/retrace-out/p2-verify -j 4
|
||
grep -L 'MGPipe verify:' ~/w7/retrace-out/p2-verify/*/mobilegl.log # empty: every case armed
|
||
grep -l 'Fatal{' ~/w7/retrace-out/p2-verify/*/mobilegl.log # empty
|
||
```
|
||
A `Fatal{UnmigratedPipeInput, "F@V"}` is a missing `FillPoints.def` row — add the row (never a sticky flag, `FillPoints.def:24-27`), regenerate, rerun. A `Fatal{PipeVerifyDiffer, …, where=read}` is a real push/pull divergence — most likely a D5 derivation transcribed wrongly; it names the field, and it is fixed, never silenced. A `Fatal{PipeResidualDiverged}` means a capability lost its carrier (D9).
|
||
|
||
**Part 3 — behavioural A/B.**
|
||
```sh
|
||
# {pull, push} name-for-name on both backends (G2)
|
||
for d in build-linux build-push; do ctest --test-dir $d -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort > ~/w7/p2-names-$d.txt; done
|
||
diff ~/w7/p2-names-build-linux.txt ~/w7/p2-names-build-push.txt # empty
|
||
ctest --test-dir build-linux -L integration-gpu --no-tests=error -j 4
|
||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
|
||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
|
||
# 40 traces (79 desktop cases) under push, both backends, SSIM >= 0.99 (G3)
|
||
python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-push/libMobileGL.so --out ~/w7/retrace-out/p2-push -j 4 --ssim 0.99
|
||
# the render-state-sensitive integration scenarios, called out by name because they are the ones a
|
||
# chunk-table mistake shows up in first:
|
||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 \
|
||
-R 'ClipDistance|SampleMaskScope|SampleVariables|DualSourceBlend|ViewportArray|PrimitiveRestart'
|
||
# the negative controls, always-on entries (G7, G8, G12)
|
||
bash scripts/g7_negative_control.sh build-push
|
||
ctest --test-dir build-push -R CsoContentAddressing --no-tests=error --output-on-failure
|
||
ctest --test-dir build-verify -R 'PoisonOmitted\.|VerifyCorrupted\.|HandleRecycle' --no-tests=error
|
||
```
|
||
**CTS**: P2 is **not** one of the five architecture boundaries that need the full `gl44to46` caselist (`ROADMAP.md:34`) and no named block is assigned to it. The full 56,271-case run happens once, on both devices, when P2 merges to `dev` — scheduled off the critical path.
|
||
|
||
**Part 4 — performance non-regression.** D.4 below.
|
||
|
||
**Part 5 — coverage, poison, handle discipline.**
|
||
```sh
|
||
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test # G6 regenerates, 0 UNMAPPED
|
||
python3 scripts/gen_pipe_dirty_surface.py --check && python3 scripts/gen_pipe_dirty_surface.py --self-test # G9
|
||
ctest --test-dir build-push -R 'RenderStateSpans\.|Residual' --no-tests=error --output-on-failure # G6, G10
|
||
```
|
||
|
||
**CI.** `gh workflow run test.yml --ref feat/disaggregated`, then once green `gh workflow run test.yml --ref feat/disaggregated -f baseline_sha=48268068` for `monolith-symbol-report`. Record both run URLs. Expected green: `pipe-gates`, `include-graph-check`, `test`, `integration`, `benchmark`, `build-linux-verify`, `integration-verify`, `retrace`, `retrace-verify`, `monolith-symbol-report`. **Note for the schedule**: the three verify lanes have never yet produced a green CI run — they were added at `0fe7bf82` / `97b997d5` and the only run whose head contained them was still in progress when the scouts were written, so their CI wall time is unknown. The only cost datum is local (`MEASUREMENTS.md:142`): 818 `integration-verify` entries at `-j 4` are about the same order as `integration-gpu`, and 79 retrace cases at `-j 4` take ~20 minutes on a 28-core WSL box. Budget accordingly and do not put the device runs behind them.
|
||
|
||
**A P2 decision the CI file forces**: `test.yml:520-526` records that `integration`'s second, `MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1` filtered pass (186 entries) is not run under the comparator and says "P2 can take it once the comparator's cost is known". **Decision: P2 does not take it.** The comparator's cost is now known to be 5–10× and the 186 entries are a buffer/readback filter that P2 changes nothing in; revisit at P3b, and the integrator records that decision in `MEASUREMENTS.md` rather than leaving the note dangling.
|
||
|
||
### D.4 The measurement runs P2 owes the day-43 GO/NO-GO
|
||
|
||
Four numbers, in the order they must be produced. Items 2–7 of `ROADMAP.md:46-52` are all here; item 1 is P1's and is already recorded at `MEASUREMENTS.md:126-142`.
|
||
|
||
#### D.4.1 Prerequisite: a per-thread CPU series in the retrace harness (package E)
|
||
|
||
**There is no per-thread CPU-time instrumentation anywhere in the tree** — greps for `CLOCK_THREAD_CPUTIME_ID`, `CLOCK_PROCESS_CPUTIME_ID`, `getrusage`, `RUSAGE_THREAD` and `/proc/self/task` across `MobileGL/`, `tools/`, `android-plugin/` and `scripts/` return nothing. The metric the whole GO/NO-GO hangs on (`ROADMAP.md:56`) therefore has no first-party collector today, and the cheapest way to get one is inside the retrace benchmark itself: retrace runs `--singlethread` (`trace_replay_core.cpp:459`) and `trace_benchmark.hpp:12-13` states that `Begin` / `OnFrameBoundary` / `End` are only ever reached from that one thread, so **that thread's CPU time is the client-side CPU cost** — no sampling, no root, no debuggable build, no profiler.
|
||
|
||
E's four edits (D.4's cost is one afternoon, and it is pre-flighted on the desktop CLI, which shares the same core):
|
||
`trace_benchmark.cpp:74-76` takes `clock_gettime(CLOCK_THREAD_CPUTIME_ID, …)` beside `Clock::now()`; `trace_benchmark.hpp:32-39`'s `Report` gains `frameCpuMs`; `SummarizeBenchmark` (`trace_replay_core.cpp:832-865`) is reused verbatim for the CPU series; `WriteBenchmarkJson` (`:867-899`) emits `meanFrameCpuMs` / `medianFrameCpuMs` / `p95FrameCpuMs` and the full `frameCpuTimesMs[]` array beside `frameTimesMs[]`. **p99 needs no device change even today** — the full per-frame array is dumped, so any percentile is computed host-side from `benchmark.json`; only the headline fields stop at p95.
|
||
|
||
**Do not** put a timer inside `MGPipeValidateForVerb`. `ROADMAP.md:7` forbids committing hot-path instrumentation, and D17 explains where the ns number comes from instead.
|
||
|
||
#### D.4.2 The paired two-device A/B (GO/NO-GO items 4 and 3)
|
||
|
||
Protocol, per device, one lock hold per arm, `scratchpad/wf2/stats_baseline.sh:16-29` as the template:
|
||
|
||
- **reboot-clean**: `adb -s $SER reboot`, wait for boot completion, wake and unlock (`input keyevent KEYCODE_WAKEUP; input keyevent 82`), let the device settle to the thermal floor before the first arm, and run the two arms **back to back in the same session** so they share a thermal window (`tools/device_bench/README.md:45-58`).
|
||
- **CPU/GPU pinned** per the project protocol (big 1.96 GHz / little 1.55 GHz, GPU maxed, 40 °C gate), the pin re-checked at the end of each window and the window discarded if it drifted off-pin.
|
||
- **serially from one tree**: `run_android_retrace_local.py` shares one `.trace-work/android-retrace-result` root per tree and `rmtree`s it per invocation (`:14`, `:354-356`), so the two devices **must not** be driven concurrently from one worktree (`MEASUREMENTS.md:93`).
|
||
- **device lock** held ≤ 25 min per acquisition, `owner` file written, `rm -rf` on the way out; a lock held > 60 min is not to be broken — report "blocked by device lock".
|
||
- **ColorOS traps** on `3B159D009VZ00000`: the first install of a not-yet-installed package blocks on `com.oplus.appdetail InstallGuideActivity` until "继续安装" is tapped (`input tap 353 2349` on the 1272×2772 panel); a foreign-signed APK must be uninstalled first.
|
||
- `MSYS_NO_PATHCONV=1` on every invocation, because a `/data/...` inside an `--env` value is path-converted otherwise.
|
||
|
||
Arms: **{pull APK, push APK} × {`--benchmark-no-finish`, finish} × 4 cases × 2 backends**, per device.
|
||
|
||
```sh
|
||
LOCKS=.../8ab6b3cb-.../scratchpad/w7/locks
|
||
for SER in 35d0befa 3B159D009VZ00000; do
|
||
for c in minecraft-1.21.4-in-world minecraft-1.21.4-fabric-iris-bsl-in-world improved-transparency-minecraft-26.3 minecraft-1.21.4-startup; do
|
||
for b in DirectGLES DirectVulkan; do
|
||
for arm in pull push; do
|
||
until mkdir "$LOCKS/$SER" 2>/dev/null; do sleep 20; done; echo "p2-ab $(date)" > "$LOCKS/$SER/owner"
|
||
ANDROID_SERIAL=$SER MSYS_NO_PATHCONV=1 python3 tools/trace_replay/run_android_retrace_local.py \
|
||
--case "$c" --backend "$b" --benchmark --benchmark-no-finish --benchmark-repeats 3 --benchmark-tail-frames 200 \
|
||
--env MOBILEGL_PIPE_STATS=1 --env MOBILEGL_PIPE_STATS_PERIOD=120
|
||
# the same invocation yields BOTH artefacts: benchmark.json (frameCpuTimesMs[]) and
|
||
# mobilegl.log (the 'MGPipe stats:' windows) - trace-replay-ci.sh:489,491 copies both
|
||
rm -rf "$LOCKS/$SER"
|
||
done; done; done; done
|
||
```
|
||
|
||
Then, host-side, reduce `frameCpuTimesMs[]` over the trailing 200 frames to **p50 and p99** per arm and publish the delta `push − pull` per (device, case, backend). `--benchmark-no-finish` is the **primary** arm because P2's question is CPU cost (`trace_benchmark.hpp:16-24`); the finish-ON arm is the sanity check that GPU time did not move.
|
||
|
||
Also read out of the same runs, because they survive the accessor-tally relocation problem (D17): the six memo gate hit/miss pairs (`ers etl eub mfp mpm mdt`) from the **last complete window** of `grep 'MGPipe stats:' mobilegl.log`, the `resid=` byte class (G10), and the two new `csom` / `csob` call classes.
|
||
|
||
**Excluded**: `minecraft-1.21.1-neoforge-create-indirect-in-world` — it fails on both devices on the `dev@81b17c0b` baseline APK itself (Espryt black frame after ~4.5 min on Adreno 830, Magma `VK_ERROR_DEVICE_LOST` during a texture-upload submit; Mali SSIM 0.85 / 0.45), so it is not this branch's regression (`MEASUREMENTS.md:96`, open question 17). It stays in the 40-trace desktop SSIM corpus and out of the device A/B.
|
||
|
||
**Trap**: `MOBILEGL_PIPE_STATS_FILE` never produces a file on device — the JSON is written from `PipeStats::Shutdown()` (`PipeStats.cpp:271-278`) which runs from `MobileGL::Destroy` (`Init.cpp:50`), and the trace app never reaches that teardown. Only the periodic `mobilegl.log` lines exist, and a run shorter than one period yields nothing at all; hence `MOBILEGL_PIPE_STATS_PERIOD=120` (or lower for a short fixture).
|
||
|
||
#### D.4.3 The tracker's absolute ns per draw (GO/NO-GO item 5)
|
||
|
||
From `DriverBench`'s `ns_per_op` (`MobileGL/MG_Benchmark/Driver/DriverBench.c:31-32`, printed at `:288-289`), on the desktop, against the same library built three ways. `DriverBench` is a headless EGL client that is **not** linked against MobileGL: it `dlopen`s exactly one provider from `$DRIVERBENCH_EGL_LIB` (`DriverBench.c:9-18`), so the same binary measures the native driver and both MobileGL backends. It loops 30 warmup + 120 timed frames, each closed with a real fence wait rather than `glFinish` (MobileGL implements `glFinish` as a no-op, `DriverBench.c:245-266`).
|
||
|
||
```sh
|
||
cd ~/w7/pipe && cmake --build build-bench --parallel 28
|
||
for lib in build-linux build-push; do # pull vs push, same tree, same flags
|
||
for be in espryt magma; do
|
||
DRIVERBENCH_EGL_LIB=$PWD/$lib/libMobileGL.so \
|
||
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh $be $PWD/$lib/libMobileGL.so
|
||
done
|
||
done
|
||
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh native # the control
|
||
```
|
||
|
||
Two deltas, both published, on `mc_vanilla_draw` (5495 draws/frame — the per-draw denominator):
|
||
|
||
- **T1, the gate number** = `ns_per_op(push, default bitmask) − ns_per_op(pull)`. This is the whole boundary cost per draw.
|
||
- **T2** = `ns_per_op(push, MOBILEGL_PIPE_PUSH=0) − ns_per_op(pull)`. This is P1's residual fill alone, so **T1 − T2** isolates exactly what P2 added and what it removed.
|
||
|
||
**The ceiling, and it is pinned in `MEASUREMENTS.md` before the run** (`ARCHITECTURE.md:504` demands an absolute threshold precisely because a relative one would pass trivially). Derivation: the pull baseline is **6.5–9.3 accessor calls plus memo probes per draw** (`MEASUREMENTS.md:64`, table `:50-58`: MC 1.21.4 in-world Espryt 9.28 / Magma 8.56 at 91.6 draws/frame; improved-transparency 26.3 Espryt 8.44 / Magma 6.53 at 1320 draws/frame). Priced at a non-inlined accessor call plus a load — 6–10 cycles, ~4 ns at 1.96 GHz — plus six memo probes at ~2 ns, that is **~44 ns/draw of work push has to be no worse than**. So:
|
||
|
||
> **T1 ≤ 45 ns/draw on Adreno 830 (`35d0befa`) and ≤ 60 ns/draw on the Mali device (`3B159D009VZ00000`)**, pinned before the A/B is run. If the pre-run calibration (one DriverBench run of the pull library, reporting `ns_per_op` for `mc_vanilla_draw`, minus the `native` control) says the per-accessor price on these devices is different, the *measured* price replaces the estimate and the ceiling is re-derived by the same arithmetic — but it is pinned before the push arm is measured, not after.
|
||
|
||
`DriverBench` is Linux-desktop only (`Driver/CMakeLists.txt:7-9`) and the whole benchmark tree is force-disabled on Android (`CMakeLists.txt:33-35`). That is acceptable: P2's ns question is a client-side CPU question and the desktop run answers it, while the two-device requirement (`ROADMAP.md:49`) applies to the per-thread CPU deltas, which come from D.4.2. **Do not** enable the google-benchmark tree on Android to change this; if an on-device blend-toggle is ever wanted the cheap route is a new Android-only target modelled on `DriverBench.c`, which already `dlopen`s EGL and falls back to surfaceless (`DriverBench.c:294-300, 417`).
|
||
|
||
#### D.4.4 The Blaze3D blend-toggle microbenchmark (GO/NO-GO item 6)
|
||
|
||
**The case already exists**: `case_mc_state_toggle` (`DriverBenchCases.inc:558-570`) is `glEnable(GL_BLEND); glBlendFuncSeparate(...); glDrawElements(...); glDisable(GL_BLEND); glDrawElements(...)` × 46, registered as `{"mc_state_toggle", case_mc_state_toggle, 46, 0, 46}` (`:627`) at exactly the vanilla-frame rate (46 toggle pairs and 28 `glBlendFuncSeparate` per frame). Note the case is `enable/draw/disable/draw`, which is what `ROADMAP.md:51` writes verbatim.
|
||
|
||
```sh
|
||
for be in native espryt magma; do
|
||
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh $be ... | grep '^mc_state_toggle'
|
||
done
|
||
```
|
||
Published as a table of `ns_per_op` for `{native, espryt-pull, espryt-push, magma-pull, magma-push}`, alongside `mc_vanilla_draw` and `mc_pass_switch` so the toggle number is read against a non-toggling baseline. This is the workload the whole "push at validate, not in the setter" decision (`ARCHITECTURE.md:151`) was made for, and it is where a per-setter design would have shown up as a loss.
|
||
|
||
#### D.4.5 The CSO negative control (GO/NO-GO item 7)
|
||
|
||
The knob is `kMGPipeBehaviourNoCsoContentAddressing` (bit 63 of the runtime `MOBILEGL_PIPE_PUSH` bitmask, D14). **It disables the map probe and the handle reuse, not the CSO records** — otherwise it measures a different thing: with it set, every pipeline-version change mints a fresh CSO, binds it and evicts, which is precisely "whole-block content addressing" and reproduces the regression `RenderState.h:165-170` records.
|
||
|
||
```sh
|
||
# desktop: the microbenchmark and the per-draw case, with and without
|
||
MOBILEGL_PIPE_PUSH=0x800000000000007f bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh espryt ...
|
||
MOBILEGL_PIPE_PUSH=0x7f bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh espryt ...
|
||
# device: one extra arm of D.4.2 on minecraft-1.21.4-in-world only, both backends, one device
|
||
ANDROID_SERIAL=35d0befa MSYS_NO_PATHCONV=1 python3 tools/trace_replay/run_android_retrace_local.py \
|
||
--case minecraft-1.21.4-in-world --backend DirectGLES --benchmark --benchmark-no-finish \
|
||
--env 'MOBILEGL_PIPE_PUSH=0x800000000000007f' --env MOBILEGL_PIPE_STATS=1 --env MOBILEGL_PIPE_STATS_PERIOD=120
|
||
```
|
||
The point of the control is to separate **"push is slower"** from **"the CSO design is slower"**: if T1 is over the ceiling *and* the control is not, the cost is in the tracker; if both are over, the cost is in the wire shape. And because a dead switch would pass silently, `CsoContentAddressingScenario` (E) is an always-on ctest pair asserting that `csom` / `csob` move in opposite directions with and without the bit while the pixels do not move at all.
|
||
|
||
#### D.4.6 The Track H unit costs (GO/NO-GO item 3)
|
||
|
||
`ROADMAP.md:56`'s criterion is "Track H 单位成本不超出估计的 50%", against the deleted `PLAN.md`'s estimates of **Espryt 0b = 5–7 days** and **Magma subsystem 4 = 2–3 days**. So the measurement is calendar, not nanoseconds: record the actual elapsed days for packages C and D, the diff sizes, and the count of memos actually retired against `ARCHITECTURE.md:363`'s census (11 direct deletions, 2 moved to client debounce, 7 re-keyed, 1 unchanged). P2 pays into that census: **11 of the 11 direct deletions and 2 of the 7 re-keys**. The remaining slices are P3a/P3b/P4a/P4b/P7 and their unit cost is extrapolated from these two.
|
||
|
||
### D.5 Docs, and the merge to `dev` (integrator, one commit)
|
||
|
||
`scripts/check_doc_citations.py docs/Disaggregated/*.md` must stay clean — every `file:line` a doc edit adds has to be true.
|
||
|
||
- `README.md:3` — status → P2 landed with the hash.
|
||
- `ROADMAP.md:18` — ✅, with the real numbers: 7 pipeline chunks / 396 B and 8 dynamic chunks / 772 B; CsoCache 64; the residual ratchet 1248 → 8; 11 memos deleted and 2 re-keyed.
|
||
- `ROADMAP.md:74` (open question 1) — answered with T1/T2 and the two-device p50/p99 table; `:77` (Q4) — answered with the chunk granularity and the note that 64 is retuned at P13 with the counters live; `:78` (Q5) — answered, and **corrected to three capabilities** (the preamble's correction 1).
|
||
- `ARCHITECTURE.md:153` — eight validate entries → nine, named (D1).
|
||
- `ARCHITECTURE.md:172` and `:568` — "P1 起成为门" → P2, matching what `test.yml` actually runs.
|
||
- `ARCHITECTURE.md:186` — the split's one place is now real; `:189` — the "~25-30 字" estimate → 396 B / 49.5 words; `:190` — the `FramebufferSrgb`/`DepthClamp` open question is closed, and `TextureCubeMapSeamless` is added.
|
||
- `ARCHITECTURE.md:504` — `tools/bench.sh` → `tools/device_bench/bench.sh`.
|
||
- `ARCHITECTURE.md:580`, `:588` — `MOBILEGL_PIPE_LEGACY_MEMOS` gains its CMake row; the `MOBILEGL_PIPE_PUSH` bitmask row gains the bit list and the new default.
|
||
- `MEASUREMENTS.md` — a new §8 with: the D.4.2 two-device p50/p99 table, T1/T2 and the pinned ceiling with its derivation, the blend-toggle table, the CSO negative control, the D.2 "red before" log, the six gate hit/miss pairs before and after, the `resid=` and `csom`/`csob` numbers, the per-dirty-bit fire rates, the payload histogram, the verdict on the 8 over-approximated fill rows, and the `integration-verify` filtered-pass decision of D.3.
|
||
|
||
Then `[Merge]` to `dev` per the milestone flow, and schedule the full `gl44to46` caselist on both devices off the critical path (`ROADMAP.md:34`).
|
||
|
||
---
|
||
|
||
## E. Risks and mitigations
|
||
|
||
| risk | mitigation |
|
||
|---|---|
|
||
| **The `[581,584)` padding hole is not where this brief computes it**, so the three new capability bools grow `RenderStateParameters` past 1168 — which breaks the `static_assert` at `MGPipeValueTypes.h:541`, `MGL_RESIDUAL_BLOCK_SIZE`, and every offset in D6's table. | It is a **compile error on the first build of `c0`**, not a silent drift, and it is the very first thing the contract package builds. If it fires, find the real hole with a temporary `static_assert(offsetof(...))` — do **not** grow the struct: the residual ratchet only goes down and a growth is a deliberate build break by design (`MGPipeTypes.h:527-535`). |
|
||
| **The hand-derived chunk offsets in D6 are wrong.** They were computed from declarations, not compiled. | `MGPipeRenderStateSpans.cpp` computes every boundary with `offsetof`/`sizeof` and `static_assert`s that the chunks are sorted, non-overlapping and cover exactly `[0, sizeof(RenderStateParameters))`. A mistake in this brief is a build break in that file, and the file is right. |
|
||
| **The pipeline subset is now a superset of what Magma hashes, so more state mints CSOs** — a scissor or sample-coverage toggle that used to cost nothing now costs a hash and a probe. | Hashing runs only when `m_pipelineStateVersion` moves, which is exactly when Magma recomputes `ComputePipelineStateHash` today, so the work is moved, not added. `TrackerTest.BlendToggleReusesTwoCsos` pins that a two-state ping-pong mints two CSOs and then reuses them forever, and D.4.4's blend-toggle table is the measurement. If the number disappoints, the escape hatch is demoting the offending setters to `++m_version` — but that is a **pull-build** semantic change and therefore a P3 decision with its own gate, not an in-flight P2 fix. |
|
||
| **A D5 derivation is transcribed wrongly**, so a backend reads a value that is subtly not what `GLContext` would have returned. `GetViewport`'s float→int rounding and the 35-way `IsCapabilityEnabled` switch are the two candidates. | This is exactly what the P1 verify comparator was built for and why the entry compare stops being tautological here: the compare-at-read re-reads every one of those fields from the live context at every backend read, field-wise, across 79 retraces and 818 integration-verify entries. On top of it, `RenderStateSpansTest.DerivationMatchesTheFrontendGetters` drives every setter and compares all 29. |
|
||
| **A dirty bit fires too rarely** — the dangerous direction (`ARCHITECTURE.md:502`), and one the current harness is blind to for object-class state, because the verify comparator compares O-class fields **by identity only** (`PipeInputs.h:248-249`). | P2 emits for value-class bits 0–4 only; bits 5–17 are computed and *counted* but nothing depends on them yet, so an under-firing object-class bit cannot render anything stale in P2. `TrackerTest.AggregateGenerationCatchesABoundTextureMoving` is the first real test of the direction, and the per-bit fire rates go into `MEASUREMENTS.md` so P3a starts from data. The verify "保留模式" extension for consume-and-clear groups is P3b work and is recorded as such. |
|
||
| **A slot table has no garbage collector, so an object nobody destroys leaks its twin forever** — worse than today's lazy `weak_ptr` sweep. | C's `e2` lands the explicit `delete_*` notification **before** `e3` switches the tables over, and `e3` is not merged without it. `SanityTest.cpp:2575-2596` (deleted-texture scrub) and the ~100 CTS cases `Managers.h:306-314` describes are the existing coverage; a leak check on the 79-case retrace (peak RSS, push vs pull) goes into `MEASUREMENTS.md`. |
|
||
| **`EnsureProcessTeardownSentinel()` stops being armed** because the arming site moved off `GetOrCreate`, and a twin then `glDelete*`s a recycled name during process teardown. | The arming moves onto the slot table's first insertion in the same commit, and `Managers.h:52-57` documents why a destructor hook is the wrong answer. `SanityTest.cpp:2650-2665, 2765-2790` pin the context-generation guards that back it up. |
|
||
| **The `g_fbSlotCache` rewrite reintroduces `pGLContext` in `MG_Backend/`** (it is the one place tempted to, since it caches a pointer into frontend storage). | Purity gate C (`grep -rc pGLContext MobileGL/MG_Backend`) runs after every merge, and the replacement is a plain `MGB_CTX->` read, which is also what closes the P1 poison bypass at those five sites. |
|
||
| **`HandleRecycleScenario` is green for the wrong reason** — the allocator never actually reproduces the address, so the scenario proves nothing. | The `AbaControl` arm exists precisely to prove the reproducer reproduces: it defeats the two guards and asserts the *wrong* pixels. If the ABA stops happening, that arm fails. `ObjectLifetimeIdTest.cpp:120-121,130` shows the precedent of skipping rather than passing when the allocator refuses to repeat — the scenario does the same, with a visible skip. |
|
||
| **P2 changes `glEnable(GL_FRAMEBUFFER_SRGB)` behaviour**: Espryt now issues a real `glEnable(GL_FRAMEBUFFER_SRGB)` where it previously always disabled. | `MEASUREMENTS.md:84` records that none of the 41 fixtures enables it, so G3's SSIM ≥ 0.99 over 40 traces on both backends is the gate, plus the full `gl44to46` caselist at the `dev` merge. The change is recorded in `MEASUREMENTS.md` as a deliberate conformance fix (it was a silently-swallowed `glEnable` and a lying `glIsEnabled`), not as a side effect. |
|
||
| **The pull build's `.text` moves more than the three named symbols.** | `symbol_report.py --threshold 0` after every merge (D.1). Anything outside the named set is a defect. If a compiler schedules the `{}` differently than expected, the delta is attributed line by line in the commit message; the gate admits an attributed delta, never an unexplained one. |
|
||
| **`acc/draw` improves for the wrong reason.** `CallClass::AccessorCalls` is a static tally at ~10 hot entry points (`PipeStats.cpp:76-88`), so a tracker that merely *relocates* reads out of `SyncRenderState` / `GetOrCreatePipeline` / `ApplyDynamicDrawStateTail` scores a lower number without removing work. | The report leads with the **gate hit/miss pairs** (which survive relocation, `PipeStats.cpp:93-99`) and the **CPU-time series**, and quotes `acc/draw` only alongside a re-audit of the tally constants at `DirectGLES.cpp:1421,1524,2043,2053,2977` and `VulkanRenderer.cpp:5009,5016,5274,5927,5934,6416,6449,6462`. This caveat is written into `MEASUREMENTS.md` above the numbers, not below them. |
|
||
| **Device time is the schedule's long pole**, and both devices are shared with the GL4.6 Wave-7 campaign under the mkdir lock. | The desktop numbers (T1/T2, blend toggle, CSO control, all of the correctness gates) come first and can NO-GO the phase without touching a device. The device A/B is 2 devices × 4 cases × 2 backends × 2 arms ≈ 32 lock holds of ~10 min; budget two days and hold ≤ 25 min per acquisition. A lock held > 60 min is not broken — report "blocked by device lock". |
|
||
| **The three verify CI lanes have never produced a green run**, so their wall time is unknown and could dominate. | The P2 exit does not depend on them: the local WSL verify run (D.3 part 2) is the evidence, exactly as it was for P1 (`MEASUREMENTS.md:129-142` is local `~/w7/pipe` evidence, not CI evidence). CI green is required before the `dev` merge, not before the GO/NO-GO. |
|
||
| **`MOBILEGL_PIPE_LEGACY_MEMOS` doubles the Espryt and Magma sync code and rots.** `ARCHITECTURE.md:367` budgets +1 day per phase for it. | Both arms sit behind the same `PipeInputs` interface, and every A/B command in §C runs the suite twice (`MOBILEGL_PIPE_PUSH=0` and default) so the legacy arm cannot silently stop compiling or stop passing. It retires with the pull path at P13. |
|
||
| **A collision in the 64-bit CSO key aliases two render states.** | The cache `memcmp`s the 396 pipeline bytes on a hash hit before reusing the handle (D7), and `CsoCacheTest.HashCollisionDoesNotAliasTwoStates` forces a collision through a test seam. The memcmp only runs when the pipeline version moved. |
|
||
| **The patch trio travels twice** (pipeline chunk P0 and `set_patch_state`), so the two carriers could disagree. | The applier asserts under verify that they agree, which turns the redundancy into a trip wire (D6). The bytes are 28 and the state changes about once per program, so the cost is nil. |
|
||
| **`gen_pipe_dirty_surface.py`'s three blind spots** (a mutator inside a lambda is attributed to the enclosing function; a mutation published through a helper reads as deferred; the scan root is `MG_Impl/GLImpl` only, so the four `MGP_NOTE_MUTATION` sites in `TextureState.h` are outside it) let an unmapped mutation slip past a green gate. | The gaps are written into `DirtySurface.def`'s header comment rather than left implicit, and the gate is a *completeness* gate over what the scanner does see — the semantic proof stays the verify lane, which is blind to none of them. Widening the scan root is recorded as a P3a item. |
|
||
| **A test that drives a backend helper directly aborts on the poison** because no verb filled the block — the P1 F3 class of failure. | `MG_Test/ScopedPipeVerb.h` already exists for exactly this and eleven tests already use it (`ef6227e1`). Any new test C or D writes that calls a backend helper directly declares its verb the same way; the poison is never weakened and no test name changes. |
|
||
| **A/B/C/D/E land against an outdated contract.** | The contract is one commit, tagged `p2/contract`. A must not change any signature in `MGPipeRenderStateSpans.h`, `PipeApply.h`, `SlotAllocator.h`, the subsystem bit constants or `RenderStateParameters` after the tag without telling the other four; a rebase-time compile error is the backstop. |
|