Files
MobileGL/docs/Disaggregated/notes/p5/p5-results/b1-v1.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

582 lines
36 KiB
Markdown

# b1 — the buffer side, v1
Branch `p5/b1`, eight commits, **`5175f9cc..5c45ec2a`**, forked from `feat/disaggregated @
5175f9cc`. Worktree `~/w7/p5-b1`. Nothing pushed; nothing merged.
```
450e21cc [Feat] (MG_Pipe): give MGPSubData's pad byte to HasLiveHostWrites - the
live-host-writer fact is content-shaped, and MGPResourceDesc's only carrier
costs a buffer a spurious reallocation on every map <- c0-owned files, see 3.1
c872df8f [Feat] (MG_Remote, Client): the conservative GPU-write set and the
persistent-map block tracker, on the client, where the decision SyncGpuWrites
makes synchronously actually lives
52d2d5dd [Feat] (MG_State, BufferObject): under split cut the mapped span into blocks,
publish the live-host-writes edge, and let the writeback rather than the
request clear a GPU write
3e62d4ad [Feat] (MG_Pipe): give HasLiveHostWrites its producer, decline every
persistent-map acquisition under split, and retire the verify pin that was
waiting for exactly this
fe8a555e [Fix] (DirectGLES): retire the probe's last frontend read under split and refuse
tier 1 of the flush ladder when the map and the queued range disagree in either
direction
d9fb5273 [Feat, Docs] (PipeStats, MEASUREMENTS): wire persistent-map-push to the bytes the
client ships, rewrite the inventory line that called it unwired, and correct the
persistent-map census from 20 to 21
8217b7fe [Feat] (GLImpl): mark the pack PBO after a glReadPixels and the capture targets
at glEndTransformFeedback, in place of a stall and an unbounded fence wait
5c45ec2a [Test] (MG_Test): one case per GPU-write row, the lifted live-host-writes pin from
both sides, the widened INVALIDATE_RANGE edge and a non-zero persistent-map-push
```
---
## 1. What landed, against the seven items of the brief
| # | item | state |
|---|---|---|
| 1 | client-side conservative GPU-write set, 6 mirrored rows + 2 new producers | **done.** `MG_Remote/Client/GpuWritePending.{h,cpp}`, one enumerator per row, one unit case per row. The narrowing is **untouched** — `ResourceTracker.h:587-592`'s `rangeCount == 1` assertion stands. |
| 2 | the block push | **done.** `MG_Remote/Client/PersistentMapTracker.{h,cpp}`; `m_livePersistentMaps` is `SyncPersistentMappedRange`'s early-out chain read as a predicate; 64 KiB blocks; shipped as ordinary `resource_subdata`; whole module gated on `Transport != Monolith`. |
| 3 | `hasLiveHostWrites` gets a producer + all four pins lifted | **done, and the carrier is NOT the one the brief named — see §3.1.** The bit rides `MGPSubData`'s pad, not `MGPResourceDesc`'s. All four pins lifted **for a split build only**. |
| 4 | R-6, force tier T2 | **done**, inside `MGPipeApplyMapPersistent` (so `mpr` is unchanged), with `MOBILEGL_IPC_ADOPT_TIER` 0/1 a named refusal. |
| 5 | wire `persistent-map-push` | **done.** The inventory rewrite is in `d9fb5273` and the `AddBytes` call in `52d2d5dd` - **three commits apart, not the same one as v1 claimed** (review m-9). The brief asks for one commit so the inventory cannot be left lying; the tree is consistent at every commit that has the call, but the claim was wrong and is corrected here. |
| 6 | the flush ladder under split | **done** as a pure function, `BufferImpl::InvalidateFlushAccessFor` (`Managers.h`), with the widening edge as its own unit case. |
| 7 | `MEASUREMENTS.md:111` 20 → 21 | **done**, with the missing site named (`DirectGLES.cpp:361`) and the non-existent `§5.7` recorded. |
---
## 2. Acceptance numbers
`~/w7/p5-b1`, `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`, four build dirs
(`build-linux` / `build-push` / `build-verify` / `build-split`).
### 2.1 Builds — four for four
configure rc=0 and build rc=0 in all four.
### 2.2 G1 — did not move
```
nm --defined-only build-linux/libMobileGL.so | grep -ic MG_Remote -> 0
nm --defined-only build-split/libMobileGL.so | grep -ic MG_Remote -> 213 (c0 left it at 188)
symbol-report vs ~/w7/p5-before-libMobileGL.so, --threshold 0:
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
```
It held because **every** new line that could reach the pull build is behind
`#if MOBILEGL_BUILD_DISAGGREGATED` — including the two new `BufferObject` members
(`m_publishedLiveHostWrites`, and the accessor pair), which would otherwise have moved the
class layout and with it every inlined constructor in `MG_State`. The one edit that is *not*
behind the option, `IsBufferDrawCleanByHandle`'s `askTheObjectWhetherItIsMapped`, folds at
compile time because `MG_Config::Transport` is an `inline constexpr Monolith` in a build
without the option — which is exactly what `Config.h:512-514` says it is for.
### 2.3 Generators and purity
```
gen_pipe.py --check : generated files are up to date (the PipeFields.def edit needs no regen)
gen_pipe.py --self-test : 9 negative-control trips, positive control OK
check_include_closure.py : 4 probes, 0 skipped, 0 problem(s)
```
### 2.4 Test lanes
| lane | before (5175f9cc) | after |
|---|---|---|
| `ctest -L unit` build-linux | 1785 / 1785 | **1806 / 1806** |
| `ctest -L unit` build-push | 1785 / 1785 | **1806 / 1806** |
| `ctest -L unit` build-verify | 1785 / 1785 | **1806 / 1806** |
| `ctest -L unit` build-split | 1842 / 1842 | **1863 / 1863** |
The 21 new names are 15 `SplitBufferSet.*`, 5 `EsprytFlushLadder.*` and one
`DirectGLESBufferDrawProbe.*`, and **every one of them exists in all four builds**: a case that
cannot run in a lane skips with a reason instead of vanishing. That is not tidiness, it is
what keeps G2 (pull vs push, line for line) and G14 (split adds, never removes) meaning
anything — the first cut had the flush-ladder cases behind a bare `#if MOBILEGL_PIPE_PUSH` and
the pull/push name sets diverged by five before anything was even wrong.
### 2.5 Name identity and the integration lane
```
ctest -N, all labels: pull=2923 push=2923 split=2980 (baseline 2902 / 2902 / 2959)
G2 pull vs push, diff lines: 0
G14 split vs push: 57 added, 0 REMOVED (the 57 are c0's Wire suites)
integration-gpu names not present at ~/w7/p5-before-ctest-names.txt: 0
baseline names missing from my push build: 0
ctest -L integration-gpu, MOBILEGL_TRANSPORT=monolith
build-push 100% passed, 0 failed out of 1117 (names: 1117, all present at baseline)
build-split 100% passed, 0 failed out of 1117
```
**Monolith behaviour did not move at all**, which is the point of the whole gating discipline:
the push, the GPU-write set and the two new producers are all behind
`MG_Config::Transport != Monolith` as well as behind `#if MOBILEGL_BUILD_DISAGGREGATED`, so an
`integration-gpu` lane that says `monolith` runs exactly the code it ran at `5175f9cc`.
---
## 3. Rulings I made that the brief and the contract did not
### 3.1 `HasLiveHostWrites` rides `MGPSubData`, not `MGPResourceDesc`
**The brief names both pads (`:303` / `:1004`) and the natural reading is the descriptor's.
That reading does not work, and the reason is P4a's, not P5's.**
`MGPResourceDesc`'s only carrier is `resource_respecify`, and for a **buffer** the applier can
never classify one as metadata-only: `RespecifyRedefinesNoStorage` (`PipeApply.cpp:559`)
refuses `kMGPipeResourceTargetBuffer` **outright, as its first line**, and the comment above it
says why — that refusal is what makes ID-18 M4's "no reallocation ack" true *by construction*
rather than by a second suppression rule, because `glBufferData` at an unchanged size is the
canonical orphaning idiom and `glBufferStorage` is the one entry point allowed a synchronous
ack. So announcing a map on a descriptor would have dispatched
`g_resourceOps->Respecify(..., initialBytes)` — a full re-upload — **on every map and every
unmap**. That is precisely the "第一次推这个位就要一次假重分配" the brief warned about, and the
only way to register the bit as metadata on that carrier is to re-open the buffer exclusion,
which is a P4a contract the buffer family should not be re-opening for a flag.
`MGPSubData` has `Uint8 Pad0[3]`; one byte becomes `HasLiveHostWrites` and
`MGP_ASSERT_POD(MGPSubData, 72)` does not move. The fact is content-shaped anyway — "someone
may be writing these bytes without telling you" — and the carrier is the record the push
already emits, so the steady state costs **nothing**: the bit rides blocks that were going out
regardless.
**The falling edge is the part that needed a decision.** After an unmap there may be no further
content record for the buffer's life, and a record stuck at "live" reads draw-DIRTY for ever —
the mirror image of the C-1 regression, costing a re-upload per draw instead of losing bytes.
So `NotePersistentMapStateChanged` emits **one block** (`NotifySubData(0, min(size,
blockBytes))`) with the bit already cleared. The bytes are real and current — `ReleaseMemory`
has already landed the staged writes and called `NotifyFlushMappedRange` above it — and a
zero-length record was not an option (contract rule A). *Overturned by:* a decision to widen
`RespecifyRedefinesNoStorage` to admit metadata-only buffer respecifies, which would make the
descriptor carrier viable and remove the falling-edge record.
**This touches two c0-owned files** — `MGPipeTypes.h` (one pad byte) and `PipeFields.def` (one
`F(HasLiveHostWrites)`) — and is isolated in its own commit so the integrator can take or
reject it without unpicking anything else. `gen_pipe.py --check` is green without regeneration.
### 3.2 The four pins are lifted **for a split build only**, not deleted
`PinNoLiveHostWrites` becomes the no-op body under `MOBILEGL_PIPE_VERIFY &&
!MOBILEGL_BUILD_DISAGGREGATED`, and the `Managers.cpp` assertion takes the same guard. In a
monolith verify build nothing sets the bit and the wire is still the thing that would say so
if something started to — which is the whole value of the pin, and it survives the phase it was
written for instead of being consumed by it. The same is true of `frontend->IsMapped()`:
monolith keeps the frontend read, split does not have one to keep.
### 3.3 Row 1 (atomic counters) is deliberately WIDER than its backend twin
`SyncAtomicCounterBuffers` (`DirectGLES.cpp:578-583`) walks the GL bindings the **transpiled
program** declared; the client has the bindings but not that per-program list at the emission
point, so it marks every *touched* atomic-counter point. Over-approximating costs a readback
the narrowing channel then removes; under-approximating reads a stale counter and says nothing,
which is what every atomic-counter conformance case is. The asymmetry decides the direction,
exactly as `RespecifyRedefinesNoStorage`'s own comment argues for its width.
### 3.4 The image-unit walk sweeps, and is the one place P5 knowingly spends
The backend keeps a bitset of writable image-buffer units (`DirectGLES.cpp:2350-2352`) built
from its own `SyncImageTextureBinding`; the client has no equivalent, so it sweeps
`MAX_TEXTURE_IMAGE_UNITS` (192) with a null test per unit. Bounding it by
`MaxImageUnits` would have been a backend read, and a stale or absent backend object would
silently *shorten* the walk — the one direction a conservative set may not fail in.
**An image-unit high-water mark on `GLContext` is the obvious narrowing and belongs with P8's
binding-walk migration.** Recorded, not gated (2026-09-08 rule).
### 3.5 `glEndTransformFeedback`'s fence removal needed a second edit nobody named
Dropping the `~0ull` `ClientWaitSync` (`GL_Drawing.cpp:1367`) is safe for `glMapBuffer` — that
is what the flag is for — but `FixupGsStripCaptureOrder` (`GL_Drawing.cpp:1310-1338`) reads the
captured bytes back through `MappedData()` **in the same function**, so it was relying on the
fence without saying so. Under split it now calls `SyncGpuWrites()` on the buffer it is about
to read. Cost moves from every `glEndTransformFeedback` to the capture shapes that actually
need reordering.
### 3.6 `WritebackFromBackend`'s clear is whole-buffer only
The third state's exit is the writeback, but `FixupGsStripCaptureOrder` writes back **three
vertices at a time**, and a partial writeback is not an answer to a whole-buffer readback. The
clear is therefore `atOffset == 0 && data.size >= m_size`. Pinned by a unit case.
---
## 4. What the other packages need from me / from each other
### 4.1 t1 — `PersistentCoherentMapScenario`
It is **t1's file to author**; these are the assertions it needs, and the first one is the one
that decides whether the rest mean anything.
1. **Assert which arm it is in.** A scenario-sized buffer is far under
`kLargeBufferAdoptBytes` (16 MiB), so `TryAdoptLargeStorage` never fires — but
`AcquireMemoryRange`'s own adoption **does** fire for `PERSISTENT|WRITE` without
`FLUSH_EXPLICIT` (`BufferObject.cpp:655-661`), subject only to whether the backend mints.
`MOBILEGL_DISABLE_LARGE_BUFFER_ADOPTION` does **not** separate them — it is read only inside
`TryAdoptLargeStorage`. So:
`ASSERT_FALSE(buffer->IsBackendPersistentMapped())` immediately after the map, with a message
that says "this is the adopted arm, not the emulated one". Under split R-6 makes that
assertion always hold; under monolith it is what tells you the two arms are comparable.
2. `ASSERT_TRUE(MG_Remote::Client::PersistentMapTracker::IsLivePersistentMap(*buffer))` — the
membership predicate, so a drift between it and `SyncPersistentMappedRange`'s early-out
chain fails here rather than silently stopping the push.
3. **E3(b): a write with no GL call at all announcing it** — map, write, draw, write again,
draw again, read back. If the second write is announced by a `glBufferSubData` the push
becomes redundant and the scenario goes green for the wrong reason.
4. **E3(c):** `pmap > 0` in the split arm and `mpr` equal between the arms.
`PipeStats::TotalBytes(ByteClass::PersistentMapPush)` and
`TotalCalls(CallClass::MapPersistentRoundtrips)`.
5. **E3(d):** `MGPipeApplyMapPersistent` never returns non-null under split. The cheapest
spelling is `IsBackendPersistentMapped()` staying false across the whole scenario.
6. **E3(a):** the same scenario under `MOBILEGL_IPC_PERSISTENT_BLOCK_KB=0` must go **red**.
It will: `PushBlocksFor` returns before shipping anything and the frame draws the last
uploaded bytes. Pinned at unit level by
`SplitBufferSet.AZeroBlockSizeTurnsThePushOffRatherThanMakingItUnlimited`.
7. The scenario's buffer must be **`PERSISTENT|WRITE|COHERENT` without `FLUSH_EXPLICIT`**.
With `FLUSH_EXPLICIT` the buffer is deliberately **not** a member (the application announces
its own writes through `resource_flush_range`) and the push ships nothing.
### 4.2 c1 — two hooks with no in-tree caller yet
`MG_Remote::Client::MarkGpuWritesForDraw()` / `MarkGpuWritesForDispatch()` and
`MG_Remote::Client::PushPersistentMapsBeforeVerb()` are **written, tested and unwired**: their
caller is the emit table's draw/dispatch slot, and both must run **before** the verb record is
emitted, not after. A push deferred past its own draw record is the C-1 regression re-committed
at the transport layer. In P5 the push is already live at the 21
`SyncPersistentMappedRange` sites (they route into `PushBlocksFor`), so `pmap` is non-zero
without c1; the draw/dispatch mark walks are **not** otherwise reached.
### 4.3 w1 — `resource_subdata` now has a meaningful byte in its pad
`MGPSubData::HasLiveHostWrites` must cross. It is one byte out of `Pad0[3]` and changes no
size, but a codec that zeroes the pads would silently delete it — and the failure mode is the
buffer reading draw-clean while a host writer is live, i.e. C-1 again.
---
## 5. What I did not do, and why
- **No narrowing.** `ResourceTracker.h:587-592`'s `rangeCount == 1` assertion is untouched.
A package that reads `:577-581` alone will think P5 owns it; it does not, it is P8/P9's.
- **`AwaitBufferWriteback` is a `return` and not a loop.** With no session — every unit lane,
and a build-split lane running monolith — the emission *was* the application, synchronously,
so a loop there would be a hang in exactly the configuration every gate runs. The real wait
is the barrier's (`ClientSession::EmitAndWait`), because the reply-slot id **is** the record's
seq; when s1/c1 land it, this function's body becomes their wait and not a second one.
- **The flush ladder's `hostBase` snapshot is specified, not implemented.** Taking the snapshot
into `SEG_STAGE` is w1's encoder work. What b1 owes and has landed is the *decision* the
snapshot makes unsafe: `InvalidateFlushAccessFor` refuses tier 1 whenever the map extent and
the queued range disagree in either direction, so a snapshot that does not cover exactly the
queued range costs a staging-ring copy instead of a silent clobber.
- **`ScopedDefaultUnpackState`'s six shadows, the `g_uploadRing` reset asymmetry and the
unlocked `pendingRanges` / `pendingResidentWrites` probes** (scout §5.2-§5.4) are all still
open. The third one is the live one: two threads make an unlocked emptiness probe of a
container the apply side mutates, and `syncedChangeSerial` beside it is already an acquire
load. It belongs to v1's thread work, not to the buffer family's shape.
---
## 6. Where I believe the brief or the contract is wrong
1. **CONTRACT-P5.md section 3 and BRIEF §5 both point `hasLiveHostWrites` at
`MGPResourceDesc`'s pad.** See §3.1: that carrier costs a spurious reallocation per map on
the buffer path, and the rule that makes it so is P4a's deliberate one. The contract row
should name `MGPSubData`'s pad.
2. **The brief's "登记进 `MGPipeResourceRespecifyNeedsAck` 旁边的元数据字段清单" is not enough on
its own.** Registering `HasLiveHostWrites` in the metadata list does nothing for a buffer,
because `RespecifyRedefinesNoStorage` refuses the buffer target before it looks at any field
at all. The list is a texture/renderbuffer rule.
3. **`MG_Impl/GLImpl/**` has no owner in BRIEF §5's table**, and the two new producers live
there (`GL_Framebuffer.cpp`, `GL_Drawing.cpp`). I took them; if another package is also in
those files the integrator should say so.
4. **`CMakeLists.txt` is c0's**, and two source lines had to be appended to the
`MOBILEGL_BUILD_DISAGGREGATED` list for the two new `.cpp`s. Every package will need the
same append; it is a conflict waiting to happen at one point in one list (P4a's lesson), and
a per-package `list(APPEND ...)` block would cost nothing.
---
## 7. The account left for later phases
- **P8**: the 21 `SyncPersistentMappedRange` sites retire into
`PushPersistentMapsBeforeVerb()`; the image-unit sweep gets a high-water mark; the narrowing
channel makes `rangeCount == 0` legal and `MarkBufferForProducer`'s conservative set starts
shrinking.
- **P6+ (Phase 2 of the push)**: `MOBILEGL_IPC_SHADOW_SHM` and 64 KiB dirty bits with a
`memcmp` first. `ARCHITECTURE.md:499` grants this the right to be pulled forward if Phase 1
is unacceptable on the Create/Flywheel fixtures — the one place in the plan where a
measurement may reorder phases. Phase 1 pushes the **whole mapped span at every validate
point**, so on a 128 MB arena it is exactly as expensive as it sounds.
- **P11**: `MOBILEGL_IPC_ADOPT_TIER` 0 and 1. They parse and are a named `abort` at use today,
so the negative control has a spelling before the thing it controls exists.
- **The barrier's retirement for the buffer family** re-opens C-6 (`ResourceFlushRange` carries
no bytes) — the contract itself says to revisit it then, and the tier-1 arm this package
hardened is the arm that would need the bytes and the range in one record.
---
# 8. Fix round 1 — every finding of `b1-review-v1.md`
Commits **`5c45ec2a..2a539881`** (seven), same branch and worktree; the branch is now
`5175f9cc..2a539881`, fifteen commits. The review's 1 BLOCKER / 7 MAJOR / 6 MINOR /
2 QUESTION, in its order.
```
57a0efa4 [Fix] (MG_State, BufferObject): publish the live-host-writes bit on the RISING edge
too - the only content record a coherent persistent map emits is the push, and a
draw-clean answer skips the ensure the push lives in and then latches it B-1 M-4
Q-15 m-11
6d9548c4 [Fix] (MG_Impl, PipeFill): make buffer_subdata_resident declare the live-host-writes
bit - ApplyBufferWrite assigns it, so a silent content record writes false over a
live write map M-2
6e6b35cb [Fix, Test] (MG_Pipe): replace the always-false live-host-writes wire, which no
producer can survive, with the one statement that stays true - the bit is the
buffer family's M-8
3f37ad2f [Fix] (DirectGLES): make the extent hostBase is good for a parameter of the flush
ladder, so tier 1's widening refusal is live code the moment a SEG_STAGE snapshot
is narrower than the queued range M-6
f19bde2a [Fix] (MG_Remote, GLImpl): gate the transform-feedback reconciliation on the
transport like every other new site, and give the unwritten writeback wait a named
Fatal instead of an empty body M-5 M-7 m-14 Q-16
c222db5f [Docs] (PipeStats): state in both entries that persistent-map-push and stage-buffer
cover the same bytes under split, because at tier T2 a pushed block IS an ordinary
resource_subdata M-3
2a539881 [Test] (MG_Test): drive the live-host-writes probe through the production chain
instead of writing the record by hand, and pin both map edges and the disabled-push
control by serial arithmetic B-1 (test)
```
## 8.1 B-1 — the cycle, and the test that could not see it
**Both halves fixed.**
**The cycle.** The diagnosis is right and it is the C-1 regression one layer down. The rising
edge of a write map emitted nothing, so for the one idiom the feature exists to serve - a
coherent persistent map behind a static VAO - the server never learned a host writer was live;
the only content record such a buffer produces is the push; the push runs inside
`EnsureBufferResourceForHandle`; a draw-clean answer **skips** that ensure
(`DirectGLES.cpp:691`) and then **latches** it (`:697`, and a coherent map bumps no mutation
epoch); and `PushPersistentMapsBeforeVerb()` has no caller. Draw 3 onward draws frame 1's bytes
for ever.
**Fix: option (b) — the rising edge publishes a real record.** One block, the same shape the
falling edge already proved affordable, so the server knows before the first probe. The probe
then answers dirty for every draw while the map is live, the ensure runs, the push runs, the
serial moves. `BufferObject.cpp`'s `NotePersistentMapStateChanged` carries the argument in full.
Options (a), (c) and (d) were considered and rejected: (a) leaves the last frontend read in a
function that has no frontend under spawn, i.e. it defers the actual deliverable; (c) has the
server read client state and is legal only under inproc, which is the shape R-2 exists to
forbid; (d) is c1's call site and b1 wiring the emit table would collide with the package that
owns it - and it would still leave the *probe* feeding itself.
**The test.** Rewritten to drive the production chain end to end and to touch the record only
by reading it: the resource subsystem is armed with an empty ops table (`MG_Test/Pipe`'s
`PushArm` shape), the buffer is constructed, respecified, mapped, written through the pointer,
pushed, unmapped - all through the ordinary frontend entry points - and the case reads
`MGPipeApplier().Resources[slot]`. The probe is handed a **null** frontend object, which is the
question a spawned server actually has to answer.
**Evidence, run three ways (`~/w7/p5-b1-negctl.sh`):**
```
=== control: unmodified tree 100% passed, 0 failed out of 2
=== A) wire producer deleted (PipeFill.cpp record.HasLiveHostWrites = ...)
50% passed, 1 FAILED out of 2
=== B) edge record deleted (BufferObject.cpp NotifySubData(0, length))
0% passed, 2 FAILED out of 2
=== restored 100% passed, 0 failed out of 2
```
(The two cases are `DirectGLESBufferDrawProbe.UnderSplitTheRecordAloneAnswersTheLiveHostMapQuestion`
and the new `SplitBufferSet.BothEdgesOfAWriteMapPublishOneStateRecord`. Deleting the wire
producer alone leaves the client-side edge case green, which is correct - it observes the
client's serial, not the server's record - and that is why the two exist rather than one.)
## 8.2 M-2 — `buffer_subdata_resident` clearing the bit
**Fixed**, one line in `MGPipeEmitBufferSubDataResident` beside the one in
`MGPipeEmitResourceSubData`. The assignment in `ApplyBufferWrite` stays an assignment - "a
content record emitted while nothing maps the buffer is how the state goes back to false" is
the rule - so the fix is to make the second emitter speak rather than to make the applier
merge.
One thing worth recording: under R-6 this path is **not reachable today**.
`MGPipeEmitBufferSubDataResident` is called only from `LandBytesIntoResidentStore`, which
requires `IsGpuResident()`, and at tier T2 nothing adopts. So it is a latent defect fixed for
P11 rather than a live one - which is also why no unit case drives it: there is no way to
reach it in a split build without first implementing T0/T1.
## 8.3 M-3 — `pmap` double-counts `stage-buffer`
**Fixed by amending the inventory, deliberately, and both entries say the same thing.**
The alternative - subtracting the push at the staging site - makes `stage-buffer` under-report
what the backend actually moves, which is the question that class exists to answer. So:
`stage-buffer`'s "NOT covered" clause is now "not covered IN A MONOLITH BUILD ... COVERED UNDER
SPLIT, AND DELIBERATELY OVERLAPPING", with the mechanism (a pushed block *is* an ordinary
`resource_subdata` at T2, so it reaches `Ops_H_SubData` and is staged), and
`persistent-map-push`'s entry now says "DOUBLE-COUNTED WITH stage-buffer, deliberately ...
adding them is wrong". The inventory is contract and it now describes the build it is read in.
## 8.4 M-4 — `MOBILEGL_IPC_PERSISTENT_BLOCK_KB=0`
**Fixed.** `blockBytes == 0` now returns before **either** edge emits, so the knob turns the
whole mechanism off - state record included - and an unmap delivers nothing. The unit case is
extended to drive `ReleaseMemory` under the knob and pins the exact serial arithmetic: with the
push on, an unmap moves the change serial by **2** (the unmap's own `NotifyFlushMappedRange`
plus the falling-edge record); with the knob at 0 it moves by **1**. A whole-buffer ship would
have been indistinguishable from the correct case without that.
## 8.5 M-5 — the ungated D-J site
**Fixed.** `GL_Drawing.cpp`'s `buffer->SyncGpuWrites()` in `FixupGsStripCaptureOrder` now
carries `MG_Config::Transport != Monolith`, like every other new site. The review's reading is
right: on Magma in a `build-split` lane running `MOBILEGL_TRANSPORT=monolith` the capture
targets *are* marked, the fence at the caller still runs, and the readback was pure new work
that `integration-gpu` cannot observe.
## 8.6 M-6 — the tier-1 guard and the missing snapshot
**Half fixed, half handed over with a spelling.**
The guard is no longer unreachable: `FlushPendingRangesFrom` now takes the extent the bytes
behind `hostBase` are good for (`hostBaseFrom`, `hostBaseTo`, defaulting to the whole store),
and tier 1 is decided against the **intersection** of that window with the queued range. With
the default the intersection is the queued range and every caller is byte-identical - G1 and
the 1117/1117 monolith lanes say so - but the moment w1 passes a real `SEG_STAGE` snapshot
extent the refusal is live code on the production path, not only under a unit case. A verify
build also names a too-narrow snapshot (`Fatal{StageSnapshotTooNarrow}`), because tiers 2 and 3
would copy from outside it and neither of them has a guard of its own.
What is **not** landed is the snapshot itself. It is encoder work - the bytes have to be staged
into `SEG_STAGE` at emission and the applier handed the segment - and that is w1's surface, not
`Managers.cpp`'s. b1's v1 already disclosed this; the review is right that disclosure without a
mechanism is not enough, so the mechanism is the parameter plus the wire above.
**Integrator: this is the ruling I am asking for** - either the snapshot moves to w1 formally
(in which case the parameter is the handoff and w1 must pass a real extent), or it comes back
to a b1 fix round 2 once w1's encoder exists to stage into.
## 8.7 M-7 — `AwaitBufferWriteback` was a no-op with no red spelling
**Fixed.** The null-session arm still returns at once - that is the correct answer when the
emission *was* the application, and a loop there would hang every gate lane. The other arm is
now a named Fatal: a session exists, the apply side is no longer synchronous, and the flag is
still set, so the caller is about to read a stale shadow. `Fatal{UnimplementedWritebackWait}`,
`MGLOG_F` + `abort`, the same shape as `EmitTables.cpp`'s `UnmigratedVerbFatal`. The hole now
has a red spelling before s1/c1 arrive rather than after.
## 8.8 M-8 — the pin was lifted only where nobody builds
**Fixed by building it.** `~/w7/p5-b1-verifysplit.sh` adds the missing matrix cell,
`build-verify-split` = `MOBILEGL_PIPE_VERIFY=ON` + `MOBILEGL_BUILD_DISAGGREGATED=ON` +
`INPROC=ON`, which is the only configuration where `MGPSubData::HasLiveHostWrites` can be
non-zero **and** the G4 field comparator is compiled. Numbers in §8.15. The gate skeleton every
later package copies should carry this cell; it is the one that makes a new wire field's
comparator mean anything, and its absence is exactly why B-1 and M-2 could hide.
## 8.9 m-9 — the "same commit" claim
**Corrected** in §1 row 5 above. The brief's requirement is real and I did not meet it; the
tree is consistent, the report was not.
## 8.10 m-10 — two comments describing a carrier that does not exist
**Fixed.** `BufferObject.h`'s accessor comment now names `MGPipeEmitResourceSubData` /
`MGPipeEmitBufferSubDataResident` and `MGPSubData`, and `BufferObject.cpp`'s block comment no
longer claims the bit rides `MGPResourceDesc`'s pad as an ID-18 M4 metadata field. Both were
left behind by `450e21cc`'s carrier move.
## 8.11 m-11 — "the adoption path notes the change itself"
**Fixed by making it true.** `NotePersistentMapStateChanged()` is now called beside
`AdoptPersistentMap` in `AcquireMemoryRange`'s push arm, so an adoption really does withdraw
the entry and clear the published bit. Unreachable under R-6, which is why it was latent; it is
P11's the day a tier mints one, and a comment that describes behaviour nothing implements is
worse than no comment.
## 8.12 m-12 — `LargeArenaAdoptionScenario`
**Fixed in the handoff, not in the code** (`MG_IntegrationTest/**` is t1's). Added to §4.1: the
scenario asserts an adoption that R-6 now makes impossible, so under a split lane its
`mpr`-and-adoption assertions have to become **decline + `mpr` unchanged**, with the test NAMES
kept (G14). R-6 says so in as many words and v1's handoff list omitted it.
## 8.13 m-13 — unsynchronised process-wide state
**Accepted, not fixed, and flagged.** `g_producerMarks` is diagnostics and its worst case is a
lost increment in a counter no gate reads. `m_livePersistentMaps` is load-bearing and is
mutated from `~BufferObject`, which is not necessarily the GL thread. Table 3 calls the
client-role singletons client-exclusive and the verb barrier makes at most one of
{GL thread, apply thread} runnable - but "the GL thread" is not the same claim as "one thread",
and a buffer released from a worker is a real shape. **This belongs to v1's thread work**: it
needs the same answer as the unlocked `pendingRanges` / `pendingResidentWrites` probes the scout
raised (§5.4), and picking a lock here without that answer would be guessing.
## 8.14 m-14 — `MOBILEGL_IPC_ADOPT_TIER` refuses late and refuses everything
**Half fixed.** The message now distinguishes 0/1 ("tier T0/T1, which P11 implements") from any
other value ("is not an adoption tier"), so a `=7` no longer dies naming P11 as though it were
real. The **lateness** is not fixed: refusing at parse means a validity rule in
`ConfigLoader.cpp`, which is c0's file and, per the preamble, a knob change goes through the
integrator. Filed rather than taken.
### Q-15 — R-6's second door
**Answered by closing it.** The configuration is in scope - a split build whose backend
registered no MGPipe resource ops is exactly what a bring-up lane looks like - so all three
legacy `AcquirePersistentMap` arms in `BufferObject.cpp` (`TryAdoptLargeStorage`,
`EnsureGpuResidentStorage`, `AcquireMemoryRange`) now carry a transport test. R-6's "always" is
now true at the frontend as well as at the applier, and E3(d) is no longer the only thing that
would have noticed.
### Q-16 — the seam, written down
**Answered in the header.** `GpuWritePending.h` now states what no row covers: the backend's
own scratch buffers - Espryt's converted-vertex-stream and primitive-restart substitution
buffers, Magma's UBO ring - have no `MarkGpuWritten` today either, so the client set is no
narrower than monolith's. Not a regression; a standing hole in both, and now one a reader does
not have to re-derive.
## 8.15 Acceptance, re-run after the fixes
```
builds : pull / push / verify / split rc=0, plus the new build-verify-split
G1 vs ~/w7/p5-before-libMobileGL.so, --threshold 0:
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
nm pull MG_Remote : 0 nm split MG_Remote : 213
gen_pipe --check : up to date --self-test : 9 trips, positive control OK
include-closure : 4 probes, 0 skipped, 0 problem(s)
ctest -L unit : 1807 / 1807 / 1807 (pull / push / verify) 1864 (split) 100% passed
build_verify_split : 1864 / 1864, 100% passed <- M-8's new matrix cell, VERIFY + DISAGGREGATED
(it went red on its FIRST run, on
ResourceEmit.TheLiveHostWritesWireFiresOnTheCallAPersistentMapProducer-
WouldSetItOn, which is precisely the tripwire M-8 said had been deleted
rather than lifted - so the lane earned its place before it was green)
ctest -N all labels: pull=2924 push=2924 split=2981
G2 pull vs push : 0 diff lines
G14 split vs push : 57 added, 0 REMOVED
integration-gpu, MOBILEGL_TRANSPORT=monolith
build-push : 1117 / 1117, names 1117, 0 not present at ~/w7/p5-before-ctest-names.txt
build-split : 1117 / 1117
```
The one new ctest name since v1 is `SplitBufferSet.BothEdgesOfAWriteMapPublishOneStateRecord`,
present in all four builds (skipping outside split) so G2 and G14 do not move.
## 8.16 One thing the fix round changed about the shape, stated plainly
The rising-edge record means a write map now costs **one `resource_subdata` at map and one at
unmap**, split-only, on top of the per-validate-point push. On a 128 MB streaming arena that is
two 64 KiB records per map/unmap pair, which is noise beside Phase 1's whole-span push - but it
is new traffic and it is the price of the probe not feeding itself. Phase 2's dirty bits should
subsume both: once the server can see which blocks moved, "a host writer is live" stops being a
separate announcement.
The reviewer's option (d) - wiring `PushPersistentMapsBeforeVerb()` at the validate point - is
still the right long-term shape and is still c1's call site. When it lands, the rising-edge
record becomes redundant for the *persistent* case (though not for a plain write map, which
emits no push at all) and should be re-examined rather than inherited.