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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

3. Inconsistencies fixed in passing

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

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

32 KiB
Raw Blame History


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:

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

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.

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).

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.

# {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.

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 rmtrees 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.

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 dlopens 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).

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 dlopens 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.

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.

# 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_asserts 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 memcmps 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.