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.
258 lines
29 KiB
Markdown
258 lines
29 KiB
Markdown
|
||
---
|
||
|
||
## C. Packages
|
||
|
||
**Five packages on five branches, five WSL worktrees.** The split is chosen by the code, not by P1's precedent: the value types + the chunk table + the applier are one shared contract everything else compiles against; the tracker and its caches are one client-side unit that touches no backend file; the two Track H slices are per-backend and share only the `SlotAllocator` (which is therefore in the contract); the gates, the scenario, the CI file and the measurement plumbing are cross-cutting tooling that must be able to land before the thing it gates.
|
||
|
||
**Branch points.** `p2/contract` from `feat/disaggregated@48268068`. Its single commit `c0` is the contract; `p2/{tracker, espryt, magma, gates}` all branch from the tag `p2/contract`, so their push builds compile and link while A finishes. `p2/spans` continues on from `c0`.
|
||
|
||
**Tree creation.** `scratchpad/wf4/wsl_p1_tree.sh` copied to `wsl_p2_tree.sh` with `p1`→`p2` throughout, then per slug:
|
||
|
||
```sh
|
||
bash ~/w7/wsl_p2_tree.sh contract 48268068 verify # first, and it must finish before the rest
|
||
bash ~/w7/wsl_p2_tree.sh spans p2/contract verify
|
||
bash ~/w7/wsl_p2_tree.sh tracker p2/contract verify
|
||
bash ~/w7/wsl_p2_tree.sh espryt p2/contract
|
||
bash ~/w7/wsl_p2_tree.sh magma p2/contract
|
||
bash ~/w7/wsl_p2_tree.sh gates p2/contract verify
|
||
```
|
||
|
||
Each tree gets three build directories, flags identical to `~/w7/pipe/build-linux`:
|
||
|
||
```sh
|
||
# pull (the G1 build)
|
||
cmake -S . -B build-linux -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
|
||
-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_BUILD_TYPE=Release \
|
||
-DMOBILEGL_LOG_ACTIVE_LEVEL=MOBILEGL_LOG_LEVEL_INFO -DMOBILEGL_BUILD_TEST=ON -DMOBILEGL_BUILD_INTEGRATION_TEST=ON \
|
||
-DMOBILEGL_BUILD_BENCHMARK=OFF -DMOBILEGL_ITEST_EGL_VENDOR=/usr/share/glvnd/egl_vendor.d/50_mesa.json \
|
||
-DMOBILEGL_ITEST_VK_ICD=/usr/share/vulkan/icd.d/lvp_icd.json -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
|
||
-DCMAKE_POLICY_VERSION_MINIMUM=3.5
|
||
# push
|
||
cmake -S . -B build-push ... same ... -DMOBILEGL_PIPE_PUSH=ON
|
||
# verify
|
||
cmake -S . -B build-verify ... same ... -DMOBILEGL_PIPE_VERIFY=ON -DMOBILEGL_ITEST_REQUIRE_GPU=ON
|
||
# benchmark (package E and the integrator only; DriverBench is Linux-desktop only, CMakeLists.txt:33-35
|
||
# force-disables the whole benchmark tree on Android)
|
||
cmake -S . -B build-bench ... same ... -DMOBILEGL_BUILD_BENCHMARK=ON
|
||
```
|
||
|
||
### C.0 Package A — `p2/contract` then `p2/spans` (trees `~/w7/p2-contract`, `~/w7/p2-spans`)
|
||
|
||
**Commit `c0` — the contract. Nothing in it may change after the tag without telling the other four packages.**
|
||
|
||
| action | file | what |
|
||
|---|---|---|
|
||
| MODIFY | `MobileGL/MG_Pipe/MGPipeValueTypes.h` | D3.1 — the three new `Bool`s in the `[581,584)` hole, between `ColorMasks` and `ClearColor`. The `sizeof == 1168` assert at `:541` is the check. |
|
||
| MODIFY | `MobileGL/MG_Pipe/PipeFields.def` | D3.2 — three rows in `MGP_FIELDS_RenderStateParameters` (`:230-247`); `MGP_FIELDS_ResidualValueBlock` (`:147-148`) drops to `F(CapabilityBits)` |
|
||
| MODIFY | `MobileGL/MG_State/GLState/RenderState/RenderState.{h,cpp}` | D3.3 (three `SET_CAPABILITY` + three `RETURN_CAPABILITY` arms, in `CapabilityInput` order) and D3.4 (`{}` on `m_parameters`, `m_pixelStorePackParameters`, `m_pixelStoreUnpackParameters`) |
|
||
| MODIFY | `MobileGL/MG_Pipe/MGPipeTypes.h` | D9 — `ResidualValueBlock` down to `Uint64 CapabilityBits`, `MGL_RESIDUAL_BLOCK_SIZE` 1248 → 8; fix the `MGPDynamicState` comment (`:232-235`) to move "sample coverage" to the pipeline half (D6) |
|
||
| MODIFY | `MobileGL/MG_Pipe/MGPipe.h` | D14 — the subsystem / behaviour bit constants |
|
||
| CREATE | `MobileGL/MG_Pipe/MGPipeRenderStateSpans.{h,cpp}` | D6 — the chunk table computed with `offsetof`, the partition `static_assert`s, `MGPipeComputePipelineSubsetHash()`, and `VulkanRenderer.cpp:4780-4794`'s enumeration comment moved in as provenance |
|
||
| CREATE | `MobileGL/MG_Pipe/PipeApply.{h,cpp}` | D2 + D5 — the seven `MGPipeApply*` entry points, the per-context CSO store, `MGPipeDeriveRenderStateFields()` |
|
||
| CREATE | `MobileGL/MG_Impl/Pipe/SlotAllocator.{h,cpp}` | D13 — per-kind `{slot, gen}` allocator, free list + high-water, `lifetimeId → slot` maps, debug wrap assert (in the contract because both C and D need it) |
|
||
| MODIFY | `scripts/gen_pipe.py` | extend `PIPELINE_STATE_MEMBERS` (`:75-99`) to the D6 set and rewrite `PipeSpanTable.inc`'s "deliberately absent" block (`gen_span_table()`, `:1040-1072`) to record what P2 decided; emit the `ResidualValueBlock` `offsetof` asserts; emit `kMGPipeFieldEmittedBy[]` from `MGP_COVERAGE_EMITTED_LIST` |
|
||
| MODIFY | `MobileGL/MG_Pipe/generated/*.inc` | regenerate and commit |
|
||
| MODIFY | `MobileGL/MG_Pipe/Coverage.def` | `MGP_COVERAGE_EMITTED_LIST` (D5); the `GetProvokingVertexMode` note at `:74-77` is answered ("in the pipeline half as of P2") |
|
||
| MODIFY | `CMakeLists.txt` | the three new sources inside `if (MOBILEGL_PIPE_PUSH)` (`:462-468`); `option(MOBILEGL_PIPE_LEGACY_MEMOS … ON)` + `-DMOBILEGL_PIPE_LEGACY_MEMOS=1`, forced ON with a `message(STATUS)` when `MOBILEGL_PIPE_PUSH=OFF` (D14) |
|
||
| MODIFY | `MobileGL/Config.h`, `MobileGL/ConfigLoader.cpp` | D14 — the bitmask default under `#if MOBILEGL_PIPE_PUSH`, the bit list in the comment; D18 — `Features.PipeHandleAbaControl` |
|
||
| MODIFY | `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | D17 — `CallClass::{RenderStateCsoMints, RenderStateCsoBinds}` with short names `csom` / `csob` |
|
||
| MODIFY | `MobileGL/MG_Test/Util/PipeStatsTest.cpp` | pin the two new names in `CounterNamesAreStable` (`:260`) and in `SummaryLineCarriesEveryClassAndGate` (`:137`) |
|
||
| CREATE (stubs) | `MobileGL/MG_Test/Pipe/{RenderStateSpansTest, TrackerTest, SlotAllocatorTest, CsoCacheTest}.cpp` | each a compiling file with one placeholder `TEST`, so the packages that own their contents never edit `MG_Test/Pipe/CMakeLists.txt` |
|
||
| MODIFY | `MobileGL/MG_Test/Pipe/CMakeLists.txt` | register the four stubs, `LABELS unit` |
|
||
| MODIFY | `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp` | `:111-112` residual size 1248 → 8; `PipelineSubsetMembersArePinned` (`:354-358`) count 24 → the D6 count |
|
||
|
||
Ordered steps for `c0`: value types and `RenderState` first (build pull, confirm `sizeof` is still 1168 and `symbol_report --threshold 0` shows only the three named resizes) → `MGPipeTypes.h` / `PipeFields.def` / generator / regenerate → the three new source files with complete signatures and **stub bodies for `PipeApply`'s derivation** so B/C/D link → CMake / Config → tests. Then **tag `p2/contract`** and tell the other packages.
|
||
|
||
Message: `[Feat] (Pipe): land the P2 contract - real storage for the three swallowed capabilities, the render-state chunk table and its subset hash, the in-process applier, the slot allocator, the subsystem bitmask and the residual ratchet down to 8`.
|
||
|
||
**Then `p2/spans` continues** with the work only A can do:
|
||
|
||
- `c1`: `MGPipeDeriveRenderStateFields()` in full — the 29 derivations of D5, each transcribed from its `RenderState` getter. Message: `[Feat] (Pipe): derive every render-state PipeInputs field from the assembled working block instead of pulling it again from GLContext`.
|
||
- `c2`: `RenderStateSpansTest.cpp` in full — D19's four tests. Message: `[Test] (Pipe): walk every RenderState setter and assert the pipeline-subset hash moves exactly when the pipeline version does`.
|
||
- `c3`: `SlotAllocatorTest.cpp` — `Gen` moves on slot reuse and only on slot reuse; a freed slot is handed back before the high-water grows; `lifetimeId → slot` survives a recycled heap address (the `void* volatile` sink of `MG_Test/State/ObjectLifetimeIdTest.cpp:44`); slot 0 is never handed out; the composite `ShaderCso` band (`MGPipeHandles.h:83-97`) is never handed out by the ordinary allocator. Message: `[Test] (Pipe): pin the slot allocator's identity contract - gen moves only on reuse and a recycled address never reproduces a handle`.
|
||
|
||
**Verification (`~/w7/p2-spans`)**
|
||
|
||
```sh
|
||
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test
|
||
python3 scripts/check_include_closure.py
|
||
cmake --build build-linux --parallel 28 && ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
|
||
python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||
# expect added 0 / removed 0 / renamed 0; resized == exactly RenderState::{RenderState,SetCapability,IsCapabilityEnabled}
|
||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||
cmake --build build-verify --parallel 28 && ctest --test-dir build-verify -L unit --no-tests=error
|
||
bash scripts/g7_negative_control.sh build-push # must report "negative control tripped" (G7)
|
||
sha_of_syncrenderstate () { awk '/namespace RenderStateImpl \{/,/\} \/\/ namespace RenderStateImpl/' "$1" | sha256sum; }
|
||
sha_of_syncrenderstate MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp # equal to ~/w7/p2-before-syncrenderstate.sha (G5)
|
||
```
|
||
|
||
### C.1 Package B — `p2/tracker` (tree `~/w7/p2-tracker`, from `p2/contract`)
|
||
|
||
**Files**
|
||
|
||
| action | file | what |
|
||
|---|---|---|
|
||
| CREATE | `MobileGL/MG_Impl/Pipe/Tracker.{h,cpp}` | D4 — `MGPipeDirty`, the tracker struct, `m_lastPushed[]` with the widened `Uint16` shutters, the per-class dirty walk, the per-bit fire counters |
|
||
| CREATE | `MobileGL/MG_Impl/Pipe/CsoCache.{h,cpp}` | D7 — 64-entry LRU, hash → probe → `memcmp` → handle, `DeleteRenderState` on evict, the `kMGPipeBehaviourNoCsoContentAddressing` arm |
|
||
| CREATE | `MobileGL/MG_Impl/Pipe/SetHashSuppressor.h` | D11 |
|
||
| MODIFY | `MobileGL/MG_Impl/Pipe/PipeFill.{h,cpp}` | D1 — `MGPipeFillForVerb` → `MGPipeValidateForVerb`, the five-step body, the residual fill restricted by `kMGPipeFieldEmittedBy[]`, the `MGP_FILL` expansion |
|
||
| MODIFY | `MobileGL/MG_Pipe/PipeMutation.h` | D4 — `MGP_NOTE_AGGREGATE(Aggregate)`, `((void)0)` in the pull build |
|
||
| MODIFY | `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayState.*, FramebufferState/FramebufferState.*, TextureState/TextureState.*, BufferState/BufferState.*}` | D4 — the five aggregate generations, all `#if MOBILEGL_PIPE_PUSH` |
|
||
| MODIFY | `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayObject.cpp, FramebufferState/FramebufferObject.cpp, TextureState/TextureObject.cpp, TextureState/TextureObject2DCube.cpp, SamplerState/SamplerObject.cpp, BufferState/BufferObject.cpp}` | the ~20 `MGP_NOTE_AGGREGATE` statements at the bump points D4 lists |
|
||
| CREATE | `MobileGL/MG_Pipe/DirtySurface.def` | D16 — 73 rows |
|
||
| MODIFY | `scripts/gen_pipe_dirty_surface.py` | D16 — `--check`, `--self-test`, mapped output |
|
||
| MODIFY | `MobileGL/MG_Pipe/FillPoints.def` | tighten the fill table: **re-check the 8 statically over-approximated rows first** (`MEASUREMENTS.md:114-115` names the three groups: `kReadback` + `IsTransformFeedbackActive`/`IsTransformFeedbackPaused`; `kTextureOp` and `kDispatch` + `IsCapabilityEnabled`; `kBlitOrCopy`/`kTextureOp` + the shader blit's viewport and vertex/buffer bindings), and record the verdict per row in the def's comment |
|
||
| MODIFY | `MobileGL/MG_Test/Pipe/{TrackerTest, CsoCacheTest}.cpp` | contents (the stubs are A's) |
|
||
|
||
**Ordered steps**
|
||
|
||
1. `b1`: the five aggregate generations + `MGP_NOTE_AGGREGATE`, with a unit test that each bump point moves its aggregate and no other. Build pull; `symbol_report --threshold 0` unchanged. Message: `[Feat] (State): give the frontend five aggregate generations so a tracker can answer "did any bound texture, buffer, attachment or attribute move" with one Uint64 compare`.
|
||
2. `b2`: `Tracker.{h,cpp}` + the `MGPipeValidateForVerb` rewrite, emitting **nothing** yet — dirty computed and counted, then the full P1 residual fill runs unchanged. This step is the safety net: it proves the walk is semantically free before anything is removed. Message: `[Feat] (Pipe): compute the per-verb dirty mask at the validate point and count how often each bit fires`.
|
||
3. `b3`: `CsoCache` + `create/bind_render_state` + `set_dynamic_state` emission; the residual fill drops the 29 derived fields. **This is where the render-state family stops being pulled.** Message: `[Feat] (Pipe): mint render-state CSOs on the pipeline subset and send only the dynamic chunks that moved - the steady-state cost of the whole render-state family is now two Uint16 compares`.
|
||
4. `b4`: `set_pixel_pack_state`, `set_patch_state`, `set_vertex_attrib_defaults` + `SetHashSuppressor` wired to the last of the three. Message: `[Feat] (Pipe): push pixel-pack, patch and vertex-attribute-default state as their own calls, the last one behind the set-hash suppressor`.
|
||
5. `b5`: `set_residual_value_state` + the tripwire (D9). Message: `[Feat] (Pipe): carry what has no call of its own in the residual value block and abort when it disagrees with the assembled state`.
|
||
6. `b6`: `DirtySurface.def` + the scanner's `--check` / `--self-test`; the `FillPoints.def` tightening and the 8-row re-check. Message: `[Feat] (Pipe): map every frontend mutator onto the aggregate generation that publishes it, and make the dirty-surface scanner a gate`.
|
||
7. `b7`: `TrackerTest.cpp` and `CsoCacheTest.cpp`.
|
||
|
||
**Tests to add**
|
||
|
||
- `TrackerTest.SteadyStateEmitsNothing` — two identical draws in a row move no `PipeStats` call counter.
|
||
- `TrackerTest.BlendToggleReusesTwoCsos` — `enable / draw / disable / draw` × N mints exactly **2** CSOs and issues 2N binds. This is the Blaze3D shape `ARCHITECTURE.md:151` names as the reason push happens at validate and not in the setter.
|
||
- `TrackerTest.ViewportDoesNotMintACso` — `glViewport` in a loop mints 0 CSOs and emits N `set_dynamic_state`s carrying only chunk D0. This is the regression `RenderState.h:165-170` records.
|
||
- `TrackerTest.WrapAroundRePushesButNeverMisses` — drive `m_version` past 65535 and assert no missed emission.
|
||
- `TrackerTest.AggregateGenerationCatchesABoundTextureMoving` — bind a texture, draw, `glTexSubImage` it, draw again; `NEW_SAMPLER_VIEWS` fires on the second draw. **This is the one direction the P1 verify comparator cannot see**, because it compares O-class fields by identity only (`PipeInputs.h:248-249`) and `ARCHITECTURE.md:502` names under-firing as the dangerous direction.
|
||
- `CsoCacheTest.LruEvictsTheOldestAndEmitsDelete`; `CsoCacheTest.HashCollisionDoesNotAliasTwoStates` (force a collision through a test seam and assert the `memcmp` rejects it); `CsoCacheTest.ContentAddressingOffMintsEveryTime`.
|
||
|
||
**Constraints**: B touches **no** file under `MG_Backend/`. B does not edit `MG_Pipe/{MGPipeValueTypes.h, MGPipeTypes.h, MGPipeRenderStateSpans.*, PipeApply.*, Coverage.def, PipeFields.def}` or `scripts/gen_pipe.py` (A owns them), and does not edit `.github/workflows/test.yml` (E owns it) — so B's scanner change must keep `--summary` working until E lands.
|
||
|
||
**Verification (`~/w7/p2-tracker`)**
|
||
|
||
```sh
|
||
python3 scripts/gen_pipe_dirty_surface.py --check && python3 scripts/gen_pipe_dirty_surface.py --self-test
|
||
python3 scripts/gen_pipe.py --check
|
||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||
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 # the all-pull arm, same names, same result
|
||
cmake --build build-verify --parallel 28 && 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/p2-tracker --lib build-verify/libMobileGL.so --out ~/w7/retrace-out/p2-tracker -j 4
|
||
grep -l 'Fatal{' ~/w7/retrace-out/p2-tracker/*/mobilegl.log # empty
|
||
```
|
||
|
||
### C.2 Package C — `p2/espryt` (tree `~/w7/p2-espryt`, from `p2/contract`)
|
||
|
||
**Files**: `MobileGL/MG_Backend/DirectGLES/{DirectGLES.cpp, Managers.h, Managers.cpp}`, new `MobileGL/MG_Backend/DirectGLES/SlotTables.h`, and `MobileGL/MG_Test/SanityTest.cpp` (the `ScopedDirectGLESTextureBindings` fixture, `:145-197`).
|
||
|
||
**Ordered steps**
|
||
|
||
1. `e1`: `SlotTables.h` — per-kind dense arrays with a live bitset, whole-table save / reset / restore, and the `EnsureProcessTeardownSentinel()` arming moved onto first insertion (`Managers.h:295`, with `:52-57` explaining why a destructor hook is wrong). Both arms compile; nothing uses the new one yet.
|
||
2. `e2`: the explicit-destroy hook — `delete_*` emitted when a frontend object's last `SharedPtr` drops, following `BufferBackendOps`' shape (`BufferObject.h:76-103`, fired at `BufferObject.cpp:39-41`). **This must land before the tables switch over**, because a slot table has no garbage collector; today the only death signal is the registry's `weak_ptr` expiring (`Managers.h:306-314` quantifies the dead gigabytes that costs).
|
||
3. `e3`: switch the six kinds over behind `kMGPipeSubsystemEsprytSlots`, deleting `OwnerEquals` (`DirectGLES.cpp:63-66`), the three `TwinLookupMemo`s (`:83-132`, use sites `:1206, 1214, 2769, 2777, 2874, 2879`), `UnitSamplerLookupMemo`'s `WeakPtr` test (`:3157-3177`), the seven `CollectGarbageIfNeeded` calls (`:1223, 1533, 1898, 1899, 1900, 2728, 2729`), `SyncTextureObjectToBackend`'s by-value copy and second `Find` (`:1310-1345`), and the four `pDefaultFramebufferInfo->defaultFBO` compares (`:1939, 2874, 2898, 6420`). Keep every one of them compiled under `MOBILEGL_PIPE_LEGACY_MEMOS`.
|
||
4. `e4`: `g_fbSlotCache` / `GetFramebufferBindingSlotFast` (`:134-157`) → a plain `MGB_CTX->GetFramebufferBindingSlot(target)` read at all five call sites (`:1613, 1907, 2745, 2860, 2935`), closing the P1 poison bypass.
|
||
5. `e5`: the `SanityTest.cpp` fixture.
|
||
|
||
Messages: `[Refactor] (Espryt): key every backend twin on {slot, gen} instead of the frontend object's heap address - six registries become slot arrays and eleven identity memos go away`; `[Fix] (Espryt): tell the backend when a frontend object dies instead of discovering it in a garbage sweep`; `[Refactor] (Espryt): read the framebuffer binding slot through MGB_CTX at every call site instead of caching a raw pointer past the poison`.
|
||
|
||
**Must not break** — the D13 list. Each item has a named existing test: `SanityTest.cpp:2575-2596` (scratch-FBO scrub), `:2650-2665`, `:2757-2790` (context-generation guards on texture/framebuffer/renderbuffer twins), `:3020-3062` (sampled-set staleness), and `Scenarios/{SampledSetStalenessScenario, CrossFrameBufferScenario, VertexArrayEnableDisableScenario, VertexAttribBindingScenario, MultiDrawScenario, ResidentIndexScenario}.cpp`.
|
||
|
||
**Verification (`~/w7/p2-espryt`)**
|
||
|
||
```sh
|
||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # empty (G13)
|
||
grep -n 'OwnerEquals\|TwinLookupMemo\|g_fbSlotCache\|CollectGarbageIfNeeded' MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp
|
||
# every remaining hit must be inside a MOBILEGL_PIPE_LEGACY_MEMOS arm
|
||
cmake --build build-push --parallel 28
|
||
ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R DirectGLES
|
||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R DirectGLES # legacy arm
|
||
python3 ~/w7/retrace_gate.py --tree ~/w7/p2-espryt --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p2-espryt -j 4 --backend DirectGLES --ssim 0.99
|
||
```
|
||
|
||
### C.3 Package D — `p2/magma` (tree `~/w7/p2-magma`, from `p2/contract`)
|
||
|
||
**Files**: `MobileGL/MG_Backend/DirectVulkan/Renderer/{VulkanRenderer.h, VulkanRenderer.cpp, VertexInputStateFactory.h, VertexInputStateFactory.cpp}` and `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h` (deleting the three backend-memo triples — a different file from the four state containers B edits).
|
||
|
||
**Ordered steps**
|
||
|
||
1. `m1`: re-key `GetOrCreatePipeline`'s memo on the bound CSO handle (`VulkanRenderer.cpp:4997-5013`) and delete the cached-hash fields (`VulkanRenderer.h:855, 856, 860, 861, 862`; `InvalidatePipelineMemo()` at `:881-885` loses them), behind `kMGPipeSubsystemRenderState`. `renderPassHash` stays in the key — it is what separates draws that differ only in `colorAttachmentCount` / `sampleCount`. Message: `[Refactor] (Magma): key the pipeline memo on the render-state CSO handle and stop recomputing a hash the client already computed`.
|
||
2. `m2`: `ApplyDynamicDrawStateTail` (`:5902-6004`) re-sourced from the pushed dynamic version, plus the `DynamicTailKey`-coverage unit test (D12.3). Message: `[Refactor] (Magma): drive the dynamic tail from the pushed dynamic version so a pipeline-only change stops invalidating it`.
|
||
3. `m3`: subsystem 4 — `VertexInputStateFactory::ComputeHash`'s `bufferKey` (`VertexInputStateFactory.cpp:48`) and a slot-indexed `VaoDrawMemo` (`VulkanRenderer.h:1244-1272`, `VulkanRenderer.cpp:3540-3579`), behind `kMGPipeSubsystemMagmaVertexInput`. Message: `[Refactor] (Magma): key the vertex-input cache and the VAO draw memo on {slot, gen} instead of a lifetime id and a heap address`.
|
||
4. `m4`: delete `SetBackendStateMemo` / `SetBackendAuxMemo` / `SetBackendHashMemo` and their storage from the frontend VAO (`VertexArrayObject.h:106-150`, `:190-197`) and the eviction-epoch dance with them (`VertexInputStateFactory.cpp:78`, `:318`, `VertexInputStateFactory.h:141`). Message: `[Refactor] (State, Magma): take the backend's raw pointers out of the frontend VAO - the state memo is deleted, the hash and aux memos become server-side per-slot fields`.
|
||
|
||
**Out of scope, do not touch**: `ProgramObject::{Get,Set}BackendHashMemo` (`ProgramObject.h:798-826`, sole user `ProgramFactory.cpp:3446-3448`) and the wider `SetupDrawSnapshot` re-key (`VulkanRenderer.h:958-979`) beyond collapsing its `vao` / `vaoLifetimeId` pair into the handle.
|
||
|
||
**Verification (`~/w7/p2-magma`)**
|
||
|
||
```sh
|
||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||
grep -rn 'BackendStateMemo\|BackendAuxMemo\|m_backendHashMemo' MobileGL/MG_State MobileGL/MG_Backend # only ProgramObject's, which is out of scope
|
||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R DirectVulkan
|
||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R DirectVulkan
|
||
python3 ~/w7/retrace_gate.py --tree ~/w7/p2-magma --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p2-magma -j 4 --backend DirectVulkan --ssim 0.99
|
||
```
|
||
|
||
### C.4 Package E — `p2/gates` (tree `~/w7/p2-gates`, from `p2/contract`)
|
||
|
||
Cross-cutting tooling. E branches from the contract and integrates **last**, but writes `HandleRecycleScenario` **first**, so its `AbaControl` arm is proven red before C and D exist — that is the "重键前红" evidence, recorded with the run log.
|
||
|
||
| action | file | what |
|
||
|---|---|---|
|
||
| CREATE | `MobileGL/MG_IntegrationTest/Scenarios/HandleRecycleScenario.cpp` | D18 |
|
||
| CREATE | `MobileGL/MG_IntegrationTest/Scenarios/CsoContentAddressingScenario.cpp` | G12 — two entries, `kMGPipeBehaviourNoCsoContentAddressing` set vs clear, asserting `csom` / `csob` move in the expected direction and the pixels do not |
|
||
| MODIFY | `MobileGL/MG_IntegrationTest/CMakeLists.txt` | register both scenarios (source list from `:55`) and their environments, following the negative-control precedent at `:695-725` |
|
||
| MODIFY | `android-plugin/app/src/trace/cpp/trace_benchmark.{hpp,cpp}` | D.4.1 — a second per-frame series taken with `clock_gettime(CLOCK_THREAD_CPUTIME_ID, …)` beside the wall delta at `trace_benchmark.cpp:74-76`; `Report` gains `std::vector<double> frameCpuMs` next to `frameMs` (`trace_benchmark.hpp:32-39`) |
|
||
| MODIFY | `android-plugin/app/src/trace/cpp/trace_replay_core.{hpp,cpp}` | `SummarizeBenchmark` (`:832-865`) reused verbatim for the CPU series; `WriteBenchmarkJson` (`:867-899`) gains `meanFrameCpuMs`, `medianFrameCpuMs`, `p95FrameCpuMs` and `frameCpuTimesMs[]` beside `frameTimesMs[]` (`:889-896`) |
|
||
| MODIFY | `tools/trace_replay/run_android_retrace_local.py` | `format_benchmark` (`:228-237`) prints the CPU numbers |
|
||
| CREATE | `tools/device_bench/devices/{xiaomi-adreno830.env, oppo-mali.env}` | the two missing device profiles (only `odinlite.env` exists) |
|
||
| MODIFY | `MobileGL/MG_Benchmark/Driver/CMakeLists.txt` | a second ctest entry `DriverBenchStateToggle` running `mc_state_toggle` — `:14` currently runs only `draw_tiny`, and `mc_state_toggle` is already in `kBenchCases` (`DriverBenchCases.inc:558-570`, `:627`), so exposing it costs ~1.2 s in an existing 3 min job |
|
||
| CREATE | `scripts/g7_negative_control.sh` | D19 |
|
||
| MODIFY | `.github/workflows/test.yml` | `pipe-gates` (`:1477`): `gen_pipe_dirty_surface.py --check && --self-test` replacing the informational `--summary` (`:1524-1528`); a `ctest -L unit` step on the verify runtime inside `integration-verify` (`:473`) so G6 / G10's push-only unit tests actually run in CI; the two new scenario entries |
|
||
|
||
Messages: `[Test] (Pipe): reproduce the handle ABA through public GL and prove the pre-rekey guards are what stops it`; `[Feat] (Trace): record per-frame thread CPU time beside wall time so a paired A/B can be read as CPU cost`; `[CI] (Pipe): make the dirty-surface report a gate and run the push-only unit tests on the verify runtime`.
|
||
|
||
**Verification (`~/w7/p2-gates`)**
|
||
|
||
```sh
|
||
cmake --build build-verify --parallel 28
|
||
ctest --test-dir build-verify -R HandleRecycle --no-tests=error --output-on-failure
|
||
# on the contract tree, before C/D land: .Legacy and .AbaControl pass, .Handles SKIPs with
|
||
# "subsystem not implemented on this tree" - a visible skip, never a vanishing test
|
||
cmake --build build-bench --parallel 28 && ctest --test-dir build-bench -L benchmark --no-tests=error
|
||
cmake --build build-retrace --parallel 28 && ./build-retrace/trace_replay_cli --benchmark --benchmark-no-finish ...
|
||
# the desktop CLI shares the same core (tools/trace_replay/CMakeLists.txt:229,254-255), so the
|
||
# CPU-series change is pre-flighted on WSL before any device time is spent
|
||
```
|
||
|
||
### C.5 File-ownership table
|
||
|
||
No two packages edit the same file. The contract is one commit that all four other branches descend from, so the integrator's rebase never sees an edit on both sides of a file.
|
||
|
||
| file / glob | A contract+spans | B tracker | C espryt | D magma | E gates |
|
||
|---|---|---|---|---|---|
|
||
| `MobileGL/MG_Pipe/{MGPipeValueTypes.h, MGPipeTypes.h, MGPipe.h, MGPipeRenderStateSpans.*, PipeApply.*, Coverage.def, PipeFields.def, generated/*.inc}` | **owner** | – | – | – | – |
|
||
| `MobileGL/MG_Pipe/{FillPoints.def, PipeMutation.h, DirtySurface.def}` | – | **owner** | – | – | – |
|
||
| `scripts/gen_pipe.py` | **owner** | – | – | – | – |
|
||
| `scripts/gen_pipe_dirty_surface.py` | – | **owner** | – | – | – |
|
||
| `scripts/g7_negative_control.sh` | – | – | – | – | **owner** |
|
||
| `MobileGL/MG_Impl/Pipe/SlotAllocator.*` | **owner** (contract) | – | – | – | – |
|
||
| `MobileGL/MG_Impl/Pipe/{Tracker.*, CsoCache.*, SetHashSuppressor.h, PipeFill.*}` | – | **owner** | – | – | – |
|
||
| `MobileGL/MG_State/GLState/RenderState/RenderState.{h,cpp}` | **owner** | – | – | – | – |
|
||
| `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayState.*, VertexArrayState/VertexArrayObject.cpp, FramebufferState/*, TextureState/*, BufferState/*, SamplerState/*}` | – | **owner** | – | – | – |
|
||
| `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h` | – | – | – | **owner** | – |
|
||
| `MobileGL/MG_Backend/DirectGLES/**` | – | – | **owner** | – | – |
|
||
| `MobileGL/MG_Backend/DirectVulkan/**` | – | – | – | **owner** | – |
|
||
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}`, `MobileGL/MG_Test/Util/PipeStatsTest.cpp` | **owner** (contract) | – | – | – | – |
|
||
| root `CMakeLists.txt`, `MobileGL/Config.h`, `MobileGL/ConfigLoader.cpp` | **owner** (contract) | – | – | – | – |
|
||
| `MobileGL/MG_Test/Pipe/CMakeLists.txt` and the four stubs' creation | **owner** (contract) | – | – | – | – |
|
||
| `MobileGL/MG_Test/Pipe/{RenderStateSpansTest, SlotAllocatorTest}.cpp` contents | **owner** | – | – | – | – |
|
||
| `MobileGL/MG_Test/Pipe/{TrackerTest, CsoCacheTest}.cpp` contents | – | **owner** | – | – | – |
|
||
| `MobileGL/MG_Test/SanityTest.cpp` | – | – | **owner** | – | – |
|
||
| `MobileGL/MG_IntegrationTest/**`, `.github/workflows/test.yml`, `tools/device_bench/**`, `tools/trace_replay/run_android_retrace_local.py`, `android-plugin/app/src/trace/cpp/**`, `MobileGL/MG_Benchmark/**` | – | – | – | – | **owner** |
|
||
| `docs/Disaggregated/*.md` | – | – | – | – | – (integrator only) |
|
||
| everything else | nobody | nobody | nobody | nobody | nobody |
|
||
|
||
The one file two packages both *touch conceptually* is `VertexArrayObject`: B edits `VertexArrayState.h` / `VertexArrayObject.cpp` (the aggregate generation), D edits `VertexArrayObject.h` (deleting the memo triples). They are different files, so the rebase is clean; the integrator still lands B before D so a compile error, if the split is wrong, surfaces at D's rebase and not at C's.
|