MobileGL/docs/archive/notes/p5d/reports/B.md

# P5d round 3, package B: persistent-map push - page-granular shadows, no edge hashing

Worktree `MobileGL-p5d-B` (branch `p5d-B`, base `85362a85`). Patch: `patches/B.patch` (5 files,
+416/-91). Not built, not committed.

## What changed (per file)

**`MG_State/GLState/BufferState/PipeResource.h`**
- `ShadowAllocationBytesFor(count)` (split-only): rounds an allocation SIZE up to a multiple of
  `SHADOW_ALLOCATION_ALIGNMENT` (4096). `MapAlignedAllocator::allocate` asks the heap for that many
  bytes under `#if MOBILEGL_BUILD_DISAGGREGATED`; the pull-build arm of `allocate` is the old text,
  token for token. Round 2 gave shadows a page-aligned BASE only; the last page could still end
  mid-way with a neighbour allocation in the remainder.
- `PipeResource::ShadowAllocationBytes()` (split-only): `ShadowAllocationBytesFor(m_shadow->capacity())`,
  0 for an adopted store or an unsized shadow. `capacity()` is exactly the count `std::vector` passed to
  `allocate()` (libc++/libstdc++/MSVC all record it), and the rounding is the allocator's own function,
  so the extent the tracker widens into can never exceed what was allocated.
- Confirmed: a live member's `MappedData()` is always `m_shadow->data()` - `Bytes()` returns the GPU map
  only when `m_gpuMapped != nullptr`, and `IsLivePersistentMap`'s second row (`IsBackendPersistentMapped`)
  excludes exactly that; nothing else backs a shadow. `ResizeShadow` is reserve(bit_ceil)+resize, so the
  allocation is `capacity()` bytes and `[0, size) ⊆ [0, capacity)`; the shadow is never reallocated while a
  map is live (Respecify/AllocateImmutableStorage call `ReleaseMemory(false)` first, which untracks;
  EnsureGpuResidentStorage/TryAdoptLargeStorage refuse while mapped).

**`MG_State/GLState/BufferState/BufferObject.h`**: `ShadowAllocationBytes()` accessor inside the existing
`#if MOBILEGL_BUILD_DISAGGREGATED` block (pull build: no text, no layout change).

**`MG_Remote/Client/PersistentMapTracker.cpp`**
- `TrackWriteMap(..., shadowExtent)`: **outward** alignment when the shadow is page-granular (base
  page-aligned, extent != 0, extent a page multiple, `rangeEnd <= extent`): `base = RoundDown(begin)`,
  `end = RoundUp(end)` clamped to `shadow + extent`; `hasEdges = base > rawBegin || end < rawEnd` is then
  false and a sub-page map is one protected page. Anything failing the test keeps the **inward** arm
  (fallback, comment rewritten to state both ownership arguments; the round-1 reasoning is kept, not
  deleted). `static_assert(SHADOW_ALLOCATION_ALIGNMENT % kPageBytes == 0)` pins the precondition.
- `InstallWriteFaultHandler`: refuses (once, `g_pageSizeRefused`) when `sysconf(_SC_PAGESIZE) != 4096`.
  Every ownership claim is made at 4 KB; on a 16 KB-page kernel (Android 15 admits them) a 4 KB
  `mprotect` covers three foreign quarters - the process-killer. Pre-existing hazard, made deterministic:
  hash arm on such kernels, never an unsafe protect.
- `PushBlocksForChecked`: both XXH3 edge hashes are gated on `tracked->hasEdges`; the `interiorBegin/End`
  comments no longer claim `>= begin / <= end`; the page loop's clamp to `[begin, end)` is unchanged and is
  what keeps a head/tail page that starts before `begin` or runs past `end` inside the mapped range.
- `PushDrawConsumers` epoch skip: walks the new `m_edgedMembers` set (members whose slot has unprotected
  edges - inward fallback only) instead of the whole membership; empty in steady state. Keys copied out
  before the walk because `PushBlocksForChecked` may `Forget()`.
- `NoteMapStateChanged` passes `buffer.ShadowAllocationBytes()` and maintains `m_edgedMembers` beside
  `m_untrackedMembers` (erase on re-note, Forget, ClearForTest).
- Test hooks: `MprotectArmAvailableForTest`, `TrackedSlotForTest`, `TrackForTest`, `UntrackForTest`,
  `FaultEpochForTest`.
- SIGSEGV handler: logic untouched. Comment on the every-overlapping-slot loop updated (no two tracked
  ranges can share a page any more; loop kept as the checkable form).

**`MG_Remote/Client/PersistentMapTracker.h`**: `TrackedWriteMap` edge-field comments (edges exist only on
the inward fallback), `m_edgedMembers`, the five test hooks.

**`MG_Test/Buffer/SplitBufferTest.cpp`**: two cases + two skip stubs (G2/G14 name-set rule, "eighteen").

## Why (profile)
Client thread at 56a77348: `XXH3_hashLong_64b_default` 6.51 + `XXH3_64bits` 2.02 = 8.5%, 98% via
`PushBlocksForChecked` from `PushDrawConsumers`; plus `PushBlocksForChecked` 5.57 self, `MappedData` 1.16,
`IsMapped` 0.58, `GetMappedRange` 0.43 around it. Cause: nearly every mapped end is not page-aligned, so
nearly every tracked map had `hasEdges` and the epoch-skip fast path hashed its edges for EVERY live map
on EVERY draw. With page-granular shadows there are no edges, the fast path touches no member, and steady
state has zero per-draw hashing and zero `MappedData/IsMapped/GetMappedRange` calls from this module.

## The ownership argument, precisely (cb06538c's danger note)
A page may be protected only if every byte of it belongs to this shadow. Outward: the heap handed the
shadow out as ONE block of `extent` bytes at a 4096-aligned base (`operator new(extent, align_val_t{4096})`,
extent a multiple of 4096); allocator metadata lives before the block, never inside; therefore
`[shadow, shadow + extent)` contains no byte of any other allocation, and every page intersecting
`[shadow+begin, shadow+end)` with `end <= extent` lies inside it. A signal-blocked driver/runtime worker
never writes a client shadow (rule E: the server reads its own staged copy). Bytes of a head/tail page
outside the mapped range are written only by the client's API paths (SubData/FlushMappedRange/Respecify
memcpy, the readback writeback landing in `WaitForApplied`'s event drain on the client thread) - threads
that run the handler; such a fault is answered like an interior one, the push clamps to `[begin, end)`,
and the byte itself crossed by its own record. `Forget`/unmap/re-note all route through `UntrackWriteMap`
(restore writable, then retire) before any reallocation, unchanged.

## Per-draw work remaining in PushDrawConsumers, epoch unmoved
| step | cost |
|---|---|
| `PersistentMapTracker::Instance()` (3 call sites in EmitTables) | function-static guard load |
| `PushIsArmed()` | one `MG_Config::Transport` load + compare |
| `OnServerRole()` | `ServerLoop::OnApplyThread()` (package D makes it a relaxed load + compare) |
| `m_livePersistentMaps.empty()` | one load |
| `g_faultEpoch.load(acquire)` + compare with `m_lastFaultEpoch` | one atomic load |
| `m_untrackedMembers.empty()`, `m_edgedMembers.empty()` | two loads |
| per member | nothing |
First push after a map still ships everything once (all bits set at registration; first fault moves the
epoch, the walk pushes every set bit). The loop was kept (over `m_edgedMembers`, not the membership) because
the inward fallback still exists; it is not entered in steady state.

## Red-once
- `SplitBufferSet.ASubPageMapIsOneProtectedPageAndAWriteThroughItFaults`: reverting the outward alignment
  gives `pageCount == 0`, `hasEdges == true`, and a write through the pointer that does not move the fault
  epoch - three red assertions. Reverting the allocator rounding alone: `ShadowAllocationBytes() % 4096`
  fails for a 100-byte buffer (capacity 128).
- `SplitBufferSet.AShadowThatFailsThePageGranularTestKeepsTheInwardAlignmentAndItsEdges`: an unaligned base,
  an unknown extent (0) and a range past its extent each register inward (1 page, edges); the true extent
  widens to 3 pages, no edges, end == extent. Widening without the extent test goes red on the third
  registration.
- Existing: `ThePushCutsTheMappedSpanIntoBlocksAndMovesPmap`, `TheLastBlockIsTheRemainderAndNotAWholeBlock`
  (64K+7: now one page-rounded span, still 2 blocks / kSize bytes by the clamp), `PersistentCoherentMapScenario`
  (pixels through the push) keep passing by inspection.

## G1 / monolith
Pull build (`MOBILEGL_BUILD_DISAGGREGATED=OFF`): zero delta. `ShadowAllocationBytesFor`,
`PipeResource::ShadowAllocationBytes`, `BufferObject::ShadowAllocationBytes` exist only under the option;
`allocate()`'s pull arm is the previous text verbatim. Push monolith build with the option ON but
`Transport=Monolith`: allocations of shadows/staging stores round up to 4096 multiples (invisible to the
application; capacities >= 4096 are already powers of two, so only sub-4K stores grow), tracker inert as
before (`PushIsArmed` false).

## Risks / not done
- Not built (per rules). Watch for: `sysconf`/`unistd.h` already included; `uintptr_t` in the test via
  `<cstdint>` through the tracker header; `flat_hash_map::value_type::first` for `m_edgedMembers`.
- The 16 KB-page refusal is new behaviour on such kernels (hash arm instead of mprotect); on the Redmi
  (4 KB) it is a no-op. It is the honest answer, but it is a performance cliff there rather than a fix.
- Two tracked shadows can no longer share a page; the handler still scans every slot per fault (unchanged).
- Not touched: role guards (`RefuseLegacyBufferArmFromApplyThread`, `OnServerRole`) - package D; the hash
  arm's `MOBILEGL_IPC_PERSISTENT_HASH_SUPPRESS` XXH3 for untracked members - still exists for table-full /
  handler-unavailable / >256 MB maps; docs (`P5D-INPROC-PERFORMANCE.md`) not updated - integrator's row.

## Fix round

Patch regenerated from `MobileGL-p5d-B` (6 files, +654/-149; BufferObject.cpp is new to the set). Not built.

**Blocker (both reviews): the epoch skip lost the drain the old edge service did by accident.**
Agreed, and the diagnosis is exact: `m_lastFaultEpoch = epoch` before a walk that pushed only
consumers left a faulted non-consumer marked, writable and unable to move the epoch again. Fix, in
`PersistentMapTracker.cpp`:
- The walk now DRAINS every tracked member with a marked page, consumer or not, before the binding
  walk (`AnyPageMarked`, one word load per 64 pages, walk-time only). The skip's proof then holds:
  the epoch moves only on a mark, and the last walk drained every mark there was. A drained push is
  bitmap-driven (faulted blocks only), so nothing pays the whole-range rescan the consumer filter
  exists to avoid. `m_lastFaultEpoch` is still taken before the drain, so a fault landing mid-drain
  forces the next draw to walk again.
- `TrackWriteMap` bumps the epoch after publishing a slot: a fresh slot has every page marked, which
  is a fault of every page as far as the push is concerned. This closes the second review's
  "registered and drawn without a fault is never shipped" hole - "first push ships everything once"
  is now true of the draw path, not only of the read-only verbs' whole push.
- The handler's `g_faultEpoch.fetch_add` is now `release` (was relaxed) so the walk's existing
  `acquire` load actually orders the bit before the epoch across threads (chunk builders write
  arenas off the GL thread). Cheap: handler-only.
- Skip path unchanged in cost: one atomic load, two empties, nothing per member. The per-draw table
  above still stands. The walk (epoch moved) gained one word-scan per tracked member.
- The binding walk moved under `if (ctx != nullptr)` so the drain runs without a context too; the
  walk body is re-indented, otherwise unchanged.

**Major (review 1): no red-once for the skip semantic.** Added
`SplitBufferSet.AFaultedMapTheDrawDidNotBindStillShipsBeforeTheDrawThatDoes` (+ skip stub; name
sets 20/20, "TWENTY"). Two one-page maps A and B, B bound to SSBO point 0, driven through
`PushDrawConsumers` itself: draw 1 ships both (2 blocks: fresh A ships although unbound - the
registration bump), draw 2 ships nothing, a write through A's pointer faults (asserted via the
epoch), draw 3 with only B bound must ship A's block (3), draw 4 binding A ships nothing more (3,
`BytesPushed == 3 * 4096`). Reverting the drain: draw 3 stays at 2 and draw 4 skips - red at the
"3u" assertion. Reverting the registration bump alone: draw 1 stays at 0 - red at "2u".

**Minor (review 1): `g_segvInstalled` published before the page-size check.** The check is now
`KernelPageIsTheTrackerPage()`, a function-static memo asked BEFORE the CAS; `g_pageSizeRefused`
is gone. No caller can pass `TrackWriteMap`'s installed gate while the size is undecided.

**Minor (review 1): `ShadowAllocationBytes()` unguarded.** Now out of line in `BufferObject.cpp`
(under the option) with `RefuseLegacyBufferArmFromApplyThread("ShadowAllocationBytes")`, beside
`MappedData`. Pull build: no text (declaration and definition are both under the option).

**Minor (review 1): outward can exceed `kMaxTrackedPages` by one page where inward fit.** Widening
never demotes: if the outward count exceeds the capacity, `TrackWriteMap` takes the inward arm for
that map (edges, `m_edgedMembers`) instead of refusing it onto the hash arm, so no map that was
tracked before this round becomes an untracked member that vetoes the skip process-wide. Only a
~256 MB map on the boundary pays the old edge-hash cost; no test (it would need a 256 MB shadow).

**Minor (review 2): extent inferred from `capacity()`.** `PipeResource` now records
`m_shadowExtent = ShadowAllocationBytesFor(reserved)` in `ResizeShadow` (the count it asked the
allocator for) and zeroes it in `AdoptPersistentMap`; `ShadowAllocationBytes()` returns it (0 while
GPU-resident). When the reserve did not reallocate, the block behind `Bytes()` is a larger earlier
reserve's, so the recorded value is at most the true extent in every case; `size <= reserved`
keeps `rangeEnd <= extent`. `Shadow()` has no callers, and every shadow allocation goes through
`ResizeShadow`, so nothing else can move the block. Split-only member (G1 layout unchanged).

**Minor (review 2): the `hasEdges &&` conjuncts were dead.** Dropped both; the comment now says
the two geometric conditions are self-gating under outward alignment and that this, not a flag,
is what removed the per-draw XXH3. `hasEdges` stays for `m_edgedMembers` (header comment updated).

**Not changed:** the 16 KB refusal, the outward arithmetic, the allocator rounding, the SIGSEGV
handler's ownership tests, `PushAllMembers`. Risks: not built - watch `if (const auto& ctx =
MG_State::pGLContext)` (UniquePtr in an if-declaration, same shape as the `vao` line below it),
`entry.first` on `UnorderedMap<Uint64, MemberEntry>`, and `MGLOG_W` inside the function-static
lambda.