Files
MobileGL/docs/Disaggregated/notes/p4a/p4a-results/esprytobj-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

572 lines
41 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P4a package D — `p4a/esprytobj` (the twins and the slot tables), v1
Branch `refs/heads/p4a/esprytobj`, worktree `~/w7/p4a-esprytobj`, based on the tag `p4a/contract`
(`08192d72`). Files touched: `MG_Backend/DirectGLES/{Managers.h, Managers.cpp}` and
`MG_Test/SanityTest.cpp` — **nothing else**. `SlotTables.h` needed no edit: `GetOrCreate(handle)`,
`FindByHandle`, `ReleaseByHandle` and `LiveGenAt` were already there from P3a, which is what C.3's
`d1` is written against.
---
## 1. Commits
| step | hash | message |
|---|---|---|
| d1 | `7aa598fa` | `[Refactor] (Espryt): key the texture, renderbuffer, framebuffer, sampler and program twins on the client-minted handle instead of the frontend object` |
| d2 | `c1d6b41c` | `[Refactor] (Espryt): drive texture storage, parameters and uploads from the pushed descriptors and take the upload strides from the record` |
| d3 | `49ff8d91` | `[Refactor] (Espryt): allocate renderbuffer storage from the pushed descriptor and keep the deferred out-of-memory report where it is` |
| d4 | `7e400454` | `[Refactor] (Espryt): sync the driver framebuffer from the pushed record and answer the read buffer from the resolved read surface` |
| d5 | `a69819e4` | `[Refactor] (Espryt): take the sampler parameters and the program artefacts from the applier instead of the frontend objects` |
| d6 | `9bb95335` | `[Test] (Espryt): drive the sampler-view table through the handle arm and prove every P4a death notice is idempotent` |
C.3 gives no message for step 6; DV-10 records the one used.
---
## 2. Per-step summary — every memo and member re-keyed, retired or added
This section is the Track H census input. **Nothing is deleted.** Every pre-handle member stays
beside its replacement under `MOBILEGL_PIPE_LEGACY_MEMOS`, which `ARCHITECTURE.md:369` keeps
compiled through P3a/P4a and which is what makes the four subsystem bits a real A/B rather than a
bring-up-order question.
### d1 — the handle-keyed API, the sixth table, the four arm resolvers
**Added to `StateBackendObjectRegistry` (push-only, so the pull build's mangled names are the
pre-P2 two-argument ones):**
| member | what it is |
|---|---|
| `GetOrCreateByHandle(MGPipeHandle)` | resolve-or-create by the handle the CALL carried. Returns a POINTER, not the reference the minting overload returns, because it has three ways to decline: the legacy arm is running, the slot is past `kMaxHandleSlot`, or the generation is BEHIND the live entry's |
| `LiveGenAt(Uint32 slot)` | the live entry's generation, or 0 — so a release build, where `MOBILEGL_ASSERT` is inert, can DIAGNOSE the refusal the table performs silently |
| `ReleaseByHandle(MGPipeHandle)` | hands the twin OUT rather than destroying it in place; the SLOT is not freed, the client frees it after the destroy returns |
**Added at `DirectGLES` namespace scope (push-only):**
- `AdoptTwinByHandle(registry, handle, kindName)` — one anonymous-namespace template holding the
release-build VOICE for the two silent refusals, shared by the five kinds so the wording cannot
drift between them. It is P3a's `GetOrCreateBufferResourceForHandle` shape lifted into one place.
- `ResolveFramebufferSubsystemArm` / `ResolveTextureResourceSubsystemArm` /
`ResolveSamplerSubsystemArm` / `ResolveProgramSubsystemArm`, plus the four inline latches
`FramebufferSubsystemEnabled()` / `TextureResourceSubsystemEnabled()` /
`SamplerSubsystemEnabled()` / `ProgramSubsystemEnabled()`. Lazy at first use, never at bring-up
(a forked pre-flight child dying on a signal makes a whole lane SKIP green). All four reuse
`BufferImpl::ClassifyPipeSubsystemArm` / `StopOnArmlessPipeSubsystem` unchanged and all four pass
`legacyArmSurvivesLegacyMemos = false`, which is D-K3's table verbatim.
- The three dependency refusals, each one `MGLOG_E` naming both bits and then the legacy arm:
**bit 11 requires bit 10**, **bit 9 requires bit 10**, **bit 10 requires bit 7**. The mirror
pairs are stated as fine in the source, because an unreachable branch that says something
different is how the reachable one drifts. Bit 12 depends on nothing and says so.
- **D-C3's `MaxColorAttachments > 8` refusal**, on `ResolveFramebufferSubsystemArm`: reads
`g_GLESCapabilities.MaxColorAttachments` (the driver's RAW ES cap, which
`BackendObject_DirectGLES.cpp:1518` publishes verbatim and which is NOT clamped to 8 on this
path), refuses bit 9 naming the cap, and runs the legacy arm.
**The sixth table — `namespace SamplerViewImpl` (push-only):**
- `BackendSamplerViewObject` — `{MGPSamplerView View; Uint64 SyncedSerial; Uint64
SyncedSamplerSerial; Bool NeedsRawDepthFetchSampler;}`. It owns **no driver id**: there is
nothing in ES to create for a view, the id the unit binds is the texture's, and what this twin is
is the server's memo of one resolved view plus Espryt's raw-depth-fetch substitution decision —
one of the two backend post-processings `ARCHITECTURE.md:206` keeps on the server. No destructor
is declared, and that is deliberate: nothing here owns a GPU object, so the teardown sentinel's
whole reason does not apply and the defaulted one is correct in every teardown order.
- `BackendSamplerViewTable` = `BackendSlotTable<ITextureObject, BackendSamplerViewObject,
SamplerViewCso>` and the global `g_backendSamplerViews`. Handle-keyed only, exactly like P3a's
`BackendBufferResourceTable`; the `StateObject` parameter names `ITextureObject` because the view
is minted off the TEXTURE's lifetime id (D-F2), which is what makes `HandleOf` resolve at all.
- `GetOrCreateSamplerViewForHandle` / `FindSamplerViewForHandle` /
`HandleOfSamplerViewForTexture` (monolith glue, named as such).
- **`OnFrontendStateObjectDestroyed` gains a `SamplerViewCso` arm.** §3 below is its idempotence
argument.
### d2 — the texture twin
| retired as a KEY | replaced by | member kept? |
|---|---|---|
| `m_syncedContentVersion` (`Managers.h:1468`) | `m_syncedResourceSerial` = the resource record's `Serial` | yes, legacy arm |
| `m_syncedShapeContextId` / `m_syncedShapeGeneration` / `m_syncedShapeParamsVersion` (`:1481-1483`) — the cheap-gate trio | the same one `Serial` compare, plus "the pending-upload set is empty" | yes, legacy arm |
| `m_syncedTextureParamsVersion` (`:1503`) | `m_syncedParamsSerial` = the record's `ParamsSerial` | yes, legacy arm |
| `m_forceTextureParamsResync` (`:1507`) | `MGPTextureParams::ForceResync` on the wire — READ, acted on, and **never written back** (D-E2); the twin's own flag is still cleared here exactly as before | yes, both |
| `m_syncedSamplerVersion` (texture-owned, `:1502`) | `m_syncedBuiltinSampler` + `m_syncedBuiltinSamplerSerial` — the HANDLE is part of the key, not just the serial, because sampler CSOs are content-addressed and a texture whose sampling diverges is re-pointed at a different CSO whose serial may be SMALLER | yes, legacy arm |
| `m_forceSamplerResync` (`:1516`) | `MGPTextureParams::SamplerResync` — the byte that had no wire spelling at all before P4a | yes, both |
| the frontend dirty model (`IsStorageDirty` / `MarkStorageDirty` / `GetStorageDirtyRegion` / `GetStorageDirtyRects`) | the applier record's `PendingUploads` set, read through `FindPipeTextureUpload` and cleared through `ConsumePipeTextureUpload` **only where the level actually uploaded** | yes, legacy arm |
**New members (all `#if MOBILEGL_PIPE_PUSH`):** `BackendTextureObject::{m_syncedResourceSerial,
m_syncedParamsSerial, m_syncedBuiltinSamplerSerial, m_syncedBuiltinSampler}`.
**New members functions:** `ResolvePushedBuiltinSampler`, `ResolvePushedTextureParams`.
**The upload shape.** The DECISION stays on the server verbatim — `subRectEligible`, the
`UnpackRingAvailable()` "one box, one job" collapse, and the three staging shapes are unchanged.
What moves is the SOURCE: the union box comes from `PendingUpload::UnionBox`, the rect list from
`PendingUpload::Regions`, and the **strides are carried, never inferred** —
`MGPSubRegion::SrcRowStride` / `SrcSliceStride`, with 0 meaning tightly packed, which is what a
whole-level region sends. `StageBlocksIntoUnpackRing`, `UnpackRingAvailable` and
`UnpackRingAllocate` are byte-identical (§4).
**`MGPipeUnmigratedEmulation("texture-remint-pull")`** is planted at
`RequireImageBindableStorage`'s re-dirty of already-uploaded levels — the one D-M site that lives
in this package's files. The other four are `DirectGLES.cpp`'s and are package E's.
### d3 — the renderbuffer twin
| retired as a KEY | replaced by |
|---|---|
| `m_cacheInternalFormat` / `m_cacheWidth` / `m_cacheHeight` / `m_cacheSamples` (`Managers.h:2251-2254`) as the four-field GATE | `m_syncedResourceSerial` = the record's `Serial` |
The four members stay and are still written, because they are also what the legacy arm compares and
what the twin reports about the storage it actually holds. The four allocation values now come from
`Desc.InternalFormat/Width/Height/Samples`. **The `GL_OUT_OF_MEMORY` probe and its `RecordError`
are untouched**, and the serial is stamped AFTER the allocation so a refused allocation leaves the
twin describing what it holds. D-D2's publication hole (`SetInternalFormat` / `AllocateStorage` /
`SetSamples` bump no version and raise no notice, so re-storaging an ALREADY-ATTACHED renderbuffer
was invisible) is closed by the client emitting from those three mutators; this side needs only the
one serial compare, which is what it now has.
### d4 — the framebuffer twin
| retired as a KEY | replaced by |
|---|---|
| `m_syncedFrontendAttachmentVersions[41]` (`Managers.h:1604`) as the attachment walk's KEY | `m_syncedRecordHashes[target]` = `MGPFramebufferState::ContentHash`, which is the hash's SECOND job — "the server's render-pass memo key, and the CLIENT's emission suppressor" |
| `stateFBOObject->GetDrawBuffers()` | `MGPFramebufferState::DrawBuffers[8]`, decoded by `DecodePushedDrawBuffers` |
| `stateFBOObject->GetReadBuffer()` | `MGPFramebufferState::ReadSurface`, matched against `Color[]` to recover the attachment POINT |
**New members / functions (push-only):** `BackendFramebufferObject::m_syncedRecordHashes`,
`FramebufferImpl::PushedFramebufferRecord`, `FramebufferImpl::DecodePushedDrawBuffers`.
- `PushedFramebufferRecord(asTarget, fbo)` matches the applier's per-target working state against
**this twin's own handle**. A mismatch means the object being synced is not the one currently
bound to that target — a real sequence (a scratch FBO synced while another is bound) — and is
answered with null rather than with the other framebuffer's attachments.
- The record's own `Target` is validated against the binding it is being applied to; `Both` is
legal for either, anything else is refused and named. That is the D-C2 property: the OIT bug at
`Managers.cpp:7544-7551`, where a READ-only sync landed `glDrawBuffers` on the wrong framebuffer
and falsely stamped the memo, becomes a one-line test on carried data instead of a call-site
discipline nobody can check.
- **Survives untouched:** `g_attachmentBackendIdGeneration`, the `~0` re-arm it drives, the
re-entrancy loop until it is quiescent, `RecomputeBackendColorSlots` (byte-identical), the
empty-colour-point detach, and the draw-buffer `None -> GL_NONE` handling.
- **Over-firing is free and under-firing is fatal**, so the per-attachment version array stays as a
narrower SECOND gate underneath the hash: an attachment that moved without the record moving
still re-attaches.
### d5 — the sampler and program twins
| retired as a KEY | replaced by |
|---|---|
| `BackendSamplerObject::m_syncedSamplerVersion` (`Managers.h:2222`) | `m_syncedSamplerSerial` = the SamplerCso record's `Serial` |
| `BackendProgramObjectImpl::m_syncedLinkVersion` + `m_syncedImageUnitVersion` (`:2354-2355`) | `m_syncedShaderCsoSerial` = the ShaderCso record's `Serial`, exposed as `GetSyncedShaderCsoSerial()` for the draw path |
All four border-colour comparands (float, int, uint, **form**) are still compared on the sampler
side, reading the CSO record's `SamplerParameters` instead of the frontend object — D-F4, and the
reason is unchanged: two integer borders differing above 2^24 share one float, and a Float→Int
transition can leave every number unchanged while needing a different driver entry point.
The frontend/CSO asymmetry that must survive, survives: the texture path resolves its min filter
with `IsAngleLlvmpipeRenderer()` and the sampler-object path with
`ShouldAvoidSamplerMipmapMinFilterOnAngleLlvmpipe()`. Both are server-side choices made from the
same value, so nothing about them moves.
**The program artefacts deliberately do NOT move** — see DV-8. That is D-H3's ruling, not a
shortcut.
### d6 — `SanityTest.cpp`
- `EverySwitchedOverKindResolvesItsTwinThroughTheHandleArm` gains a **SamplerViewCso** block (the
five `TwinRegistry` kinds and the Buffer table were already covered): handle minted off the
texture's lifetime id, the two kinds' slot spaces proven independent for the SAME lifetime id,
`GetOrCreate` / `FindByHandle` / `HandleOf` / `ReleaseByHandle`, the recycle with a moved `Gen`,
and the **backward-generation refusal**.
- **New:** `DirectGLESSlotTable.ADeathNoticeForEveryP4aKindIsIdempotent`, driven through the REAL
consumer the backend installed (`GetStateObjectDeathOps()->OnDestroyed`) rather than a recording
stub, because what is under test is Espryt's own arm. Skip stub added in the pull arm so G2/G14
hold (name-for-name identical lists, additions only).
- `ScopedDirectGLESTextureBindings` (`:218-260`, the second live holder of kind Texture),
`ASavedCopyOfARealRegistryDropsTheTwinOnTheSameNotice` and
`PixelPackBindingCacheSkipsRedundantBindsAndRestsAtZero` all pass unchanged.
---
## 3. The death-notice idempotence argument, per kind (ID-8)
The rule: **the client emits the wire delete, raises `NotifyStateObjectDestroyed(kind, lifetimeId)`
and frees the slot, in that order**, and the backend notice is the REDUNDANT SECOND PATH.
The mechanism that makes all six idempotent is one property of the allocator plus one of the table:
1. `MGPipeSlotAllocator::Free` **erases the lifetimeId → slot mapping**, so the second resolution of
the same id finds nothing; and a `Free` on a slot that is no longer live at that generation is a
proven no-op (`SlotAllocator.cpp:117-119`), with the `Gen` bump riding the next handout rather
than the free, so a double free cannot skip a generation.
2. `BackendSlotTable::OnFrontendObjectDestroyed` **returns false without touching anything** when
`FindByLifetimeId` answers the null handle, and `ReleaseTwinAt` returns false for an entry whose
`Gen` no longer matches — so a notice that arrives after the client's `Free` cannot drop a
successor's twin.
| kind | first path | second path | why the second is a no-op |
|---|---|---|---|
| Texture | `~TextureObjectBase` raises the notice; Espryt drops the twin in every holder and frees the slot | the client helper `MGPipeEmitTextureDestroyAndFree` emits `ResourceDestroy`, raises the same notice and frees | whichever gets there first erases the mapping; the other resolves the null handle. The twin's driver id is released exactly once, by `ReleaseTwinAt`, which retires the entry BEFORE running the destructor |
| Renderbuffer | same shape | `MGPipeEmitRenderbufferDestroyAndFree` | same |
| Framebuffer | same shape | `MGPipeEmitFramebufferDestroyAndFree`, which emits **no wire call at all** (D-I2: a framebuffer has a handle but no wire lifetime) — it is notice-then-free only | same |
| SamplerCso | `~SamplerObject` | `MGPipeEmitSamplerCsoDestroyAndFree` | same. A texture's death legitimately raises a SamplerCso notice too, because every `ITextureObject` owns a private `SamplerObject` with its **own** lifetime id (contract D5), so the two notices name two different ids and neither can free the other's slot |
| ShaderCso | `~ProgramObject` | `MGPipeEmitShaderCsoDestroyAndFree`, called **twice** for a composite (the pipeline cache's LRU eviction and the composite's own destructor) | the composite band is a client-side indexing detail; on this side a composite handle is an ordinary ShaderCso handle and both calls resolve through the same table. The second finds nothing |
| **SamplerViewCso** | **nothing raises it today** — the view has no frontend object; the only raiser is the client helper `MGPipeEmitSamplerViewCsoDestroyAndFree`, which fires from `~TextureObjectBase`'s body | the same helper's own `Free` | the notice names the TEXTURE's lifetime id, and it is safe for it to arrive beside the Texture notice for the same id because the two kinds have **separate slot spaces** — the allocator resolves `(kind, lifetimeId)`, so each arm finds its own slot or nothing. The twin owns no driver id at all, so even a double release is a pointer reset |
`ADeathNoticeForEveryP4aKindIsIdempotent` exercises exactly this: for the sampler view, notice →
notice → client `Free` → notice, then a successor acquire proving the slot really came back with a
moved generation (which a double free would break by skipping one); for the five object kinds, the
real destructor followed by two more deliveries.
**Leak-freedom.** No new table has a garbage collector and none needs one: the sampler-view table's
entries leave on the notice, and `SamplerViewImpl`'s twin owns nothing a sweep could reclaim. No new
static holds a frontend `SharedPtr` (the exit-order rule, ID-8): `g_backendSamplerViews` is a
`BackendSlotTable`, whose `Entry::stateRef` is a `weak_ptr` and is never even written on the
handle-keyed overload, and it links itself into the per-type holder list from its own constructor
with no initialisation-order question to answer. It adds **no** `std::atexit` registration of its
own; `EnsureProcessTeardownSentinel()` is still armed by the first insertion of a table whose twin
owns a driver id.
---
## 4. The byte-identical set (G5) — evidence
`scripts/p4a_untouched_regions.sh` is package **F**'s and does not exist on this tree, so the
evidence below was produced with a one-off equivalent that copies the parent script's shape:
mask-first, preprocessor-blind extraction (comments and string/char literals replaced by spaces of
the same length), the definition found as the one `<name> (` whose closing paren is followed by
`{`, the body brace-matched in the masked text and **hashed from the ORIGINAL text**, exactly one
definition per name or exit 2, both arguments git refs.
Four of D-N's seventeen live in this package's files. The other thirteen are P3a's eleven
(`p3a_untouched_regions.sh`, run after every commit, rc 0 every time) plus
`DepthStencilSamplingReadImpl` and `ShouldUseCaveatTextureFormat`, which are in `DirectGLES.cpp`
and `Utils.cpp` — package E's files, untouched here.
```
$ python3 <p4a-dn equivalent> 37da3c3a HEAD
d75537bc1fb9170bf98d8f711c7a86fa229b80a3219f091c487ba56251628b9a StageBlocksIntoUnpackRing
a0c9994d7647f6d55491767e813bbab07f1ac54b8804bff466e8c53e29356465 UnpackRingAvailable
f56d432fff8d015c08911f846d8c196c3c297261a8301dc8b9c4299d199b95db UnpackRingAllocate
39a3724922a007509173c330557f6e5f6b938e5b6cd8800817c63ac67ccf4840 RecomputeBackendColorSlots
[p4a-dn] rc=0
```
`ScopedDefaultUnpackState` and its process-wide `s_synced` shadow are untouched, and the ring path
still issues no `glPixelStorei`, so D-O's inherited hazard is neither fixed (`ROADMAP.md:98`) nor
made worse.
---
## 5. Deviations, each with its reason
**DV-1 — d1's message names a re-key the commit only half performs, and that is a C.7 boundary.**
C.3's `d1` says "the five kinds' tables re-keyed onto client-minted handles". The *resolution sites*
for framebuffer, sampler and program are `SyncCurrentFBO`, the lazy sampler mint at
`DirectGLES.cpp:4014-4020` and `SyncCurrentProgram` — all in `DirectGLES.cpp`, which C.7 gives to
**package E**. `SyncTextureObjectToBackend` is likewise defined at `DirectGLES.cpp:1501`. So d1
lands everything the re-key needs on this side — the handle-keyed registry API, the shared refusal
voice, the sixth table and the four arm resolvers — and each family's own resolution moves with its
commit (d2–d5) where it lives in `Managers.cpp`. The brief's exact message is used unchanged per
ID-2; this note is the correction.
**DV-2 — `MGPTextureParams::DepthStencilMode`'s encoding was unstated, and Espryt now defines it.**
The field is a `Uint8`; `ITextureObject::GetDepthStencilTextureMode()` is a `GLenum`
(`GL_DEPTH_COMPONENT` 0x1902 / `GL_STENCIL_INDEX` 0x1901), which does not fit in a byte, and the
contract's payload comment says nothing about how it crosses. **Espryt decodes 0 =
`GL_DEPTH_COMPONENT`, 1 = `GL_STENCIL_INDEX`**, and package B must emit that. The direction is
chosen by one property rather than by the enum's low byte: `GL_DEPTH_COMPONENT` is the GL and ES
default and a texture that never asks for the stencil aspect never emits the call, so **a zeroed
record has to decode to exactly what such a texture already has**. *Owner: the integrator, to amend
`MGPipeTypes.h`'s payload comment; package B, to emit it.*
**DV-3 — `MGPSubData::Target`'s upload-target half was unstated.** D-D3 says `Target` carries "the
owner's upload target … plus the cube-face upload target in `MGPSurface`-style terms" without
fixing the encoding. Espryt reads `static_cast<Uint16>(MobileGL::TextureUploadTarget)`, i.e. the
frontend enumerator value, and the applier's `PendingUpload::UploadTarget` is matched against it.
*Owner: same as DV-2.*
**DV-4 — `MGPSurface::Kind`'s enumerator values are unstated, so Espryt does not read them.** The
comment says `Texture | Renderbuffer | None` and no enum exists. Every test this package needed is
expressible without it, because D-C1 fixes the *other* spelling: "an empty point is
`{Res = kMGPipeNullHandle, Kind = None}`". So the framebuffer arm asks
`MGPipeHandleIsNull(surface.Res)` and never touches `Kind`. Nothing is blocked; recorded so the
integrator can mint the enum in the same amendment as DV-2/DV-3 rather than discovering it in
package E.
**DV-5 — the four cross-object masks still read the frontend attachment objects, and this is a
finding rather than a shortcut.** `IsSnormFallbackAttachment`, `IsUnormFallbackAttachment` and
`IsAlphaWidenedColorAttachment` all reduce to `(format, **TextureTarget**)` for a texture
attachment — `ShouldUseCaveatTextureFormat(format, target)` and
`BackendTextureFormatAddsAlpha(format, target)`. `MGPSurface` carries `InternalFormat` and
`UploadTarget` but **no texture target**, and no `TextureUploadTarget -> TextureTarget` inverse
exists anywhere in the tree. Inventing one would feed `ShouldUseCaveatTextureFormat` — which is on
**D-N's byte-identical list**, so a change to what it is *asked* silently changes what every texture
is allocated as — with a guessed input. D-C1 promises the inline `InternalFormat` makes "the four
cross-object masks fall out at push time with no lookup"; that promise needs one more field.
**Recommended fix: widen `MGPSurface`'s `Pad0` (2 bytes, already there) into `Uint16 TextureTarget`,
which keeps `MGP_ASSERT_POD(MGPSurface, 24)`.** *Owner: the contract (package A) + the integrator.
Until then this package leaves the four masks reading the frontend, unchanged and correct.*
**DV-6 — `MGPFramebufferState::DrawBuffers[]` cannot spell the default framebuffer's tokens, and
that is provably harmless here.** The wire array is an attachment INDEX with -1 for `None` (D-C1),
so `FrontLeft` / `FrontRight` / `BackLeft` / `BackRight` are unrepresentable. Those are the DEFAULT
framebuffer's own tokens; the default framebuffer has **no `BackendFramebufferObject`** (it is
`pDefaultFramebufferInfo->defaultFBO`, which is exactly why `MGPipeHandles.h` reserves `{0,1}` for
it), and the legacy arm's branch for them already says "shouldn't remap". The decode is therefore
total for every object that reaches this twin, and `IsDefault` is what a later phase would test if
that ever changed.
**DV-7 — the framebuffer attachment WALK still reads the frontend attachment objects.** What moved
is the KEY (DV-5's sibling): `SyncAttachmentObject` drives the texture and renderbuffer twins
*through the frontend objects the monolith hands over*, and resolving them from `MGPSurface::Res`
instead is package E's `SyncAttachmentObject` work — and is blocked on DV-5's missing target field
for the same reason. Recorded so the integrator does not read the ContentHash re-key as the whole
of D-C.
**DV-8 — the program twin still reads the frontend archive, and D-H3 says it must.** "THE ARTEFACTS
ARE NOT HELD HERE IN MONOLITH: … the applier stores the DESCRIPTOR and the identity and the server
reads the frontend's own archive." That is what keeps the codec off the monolith hot path entirely
and out of ID-19's budget. So `BackendProgramObjectImpl::SyncToBackend`'s artefact reads are
correct as they stand, and what d5 moves is the identity and the serial. Recorded because the
step's own message ("take … the program artefacts from the applier") reads the other way.
**DV-9 — the value sites are PREPROCESSOR MACROS, not helper functions or lambdas, and G1 is why.**
This was measured, not assumed. Inserting two lambdas into `SyncMipmapsToBackend` renumbered every
one of its nine existing `ErrorLopper` lambdas — their mangled names are `…::$_N` **by position** —
for **8 symbols added, 8 removed and 4 `std::function` thunks resized** in the PULL build. Routing
`SyncTextureParamsToBackend`'s values through locals resized it **+9 bytes**, and the same shape
cost `SyncBuiltinSamplerToBackend` **-2**. P4a's admitted-resize set is EMPTY, so all three are G1
failures. A macro expands to the pre-P4a expression exactly when `MOBILEGL_PIPE_PUSH` is off, so
the pull build's preprocessed text — and therefore its object code — is unchanged. Every macro is
`#undef`'d immediately after its function. The alternative D-N blesses (a separate
`#if MOBILEGL_PIPE_PUSH` function with its own name) was used where the arms diverge structurally
(`ResolvePushedBuiltinSampler`, `ResolvePushedTextureParams`, `PushedFramebufferRecord`,
`DecodePushedDrawBuffers`) and rejected for `SyncMipmapsToBackend`, which would have meant
duplicating ~950 lines.
**DV-10 — step d6 has no message in C.3.** Used
`[Test] (Espryt): drive the sampler-view table through the handle arm and prove every P4a death
notice is idempotent`.
**DV-11 — the legacy arms are guarded `#if MOBILEGL_PIPE_LEGACY_MEMOS` only inside the push arm.**
`CMakeLists.txt:477-480` forces `MOBILEGL_PIPE_LEGACY_MEMOS` ON whenever `MOBILEGL_PIPE_PUSH` is
OFF, so a pull build always compiles the pre-P4a text; the `#else` branch of each arm switch is
that text verbatim. The `#if !MOBILEGL_PIPE_LEGACY_MEMOS` bodies are unreachable — the arm resolver
stops the process at its first call — and are kept loud, for the reason
`BackendVertexArrayObject::SyncToBackend` keeps its twin.
**DV-12 — `p4a_untouched_regions.sh` does not exist on this tree.** §4 says what was run instead.
---
## 6. Verification transcript
`export CCACHE_BASEDIR=/home/swung/w7` in every shell; commands run from `~/w7/p4a-esprytobj`.
### 6.1 After every commit (G1, unit, P3a's eleven, purity)
Run after **each** of `7aa598fa`, `c1d6b41c`, `49ff8d91`, `7e400454`, `a69819e4`, `9bb95335`:
```
$ python3 scripts/symbol_report.py --before ~/w7/p4a-before-libMobileGL.so \
--after build-linux/libMobileGL.so --threshold 0 \
--fail-on-symbol-set-change --fail-on-added-bytes 0
symbol-report: .text 10806323 -> 10806323 (+0, +0.000%)
symbol-report: 27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
rc=0
$ ctest --test-dir build-linux -L unit --no-tests=error -j 12
100% tests passed, 0 tests failed out of 1635 (1636 from d6 on)
$ ctest --test-dir build-push -L unit --no-tests=error -j 12
100% tests passed, 0 tests failed out of 1635 (1636 from d6 on)
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD
[p3a-untouched] the 11 pool / deferred-release / ring / flush-drain functions are
[p3a-untouched] byte-identical between 37da3c3a and HEAD rc=0
$ grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$'
MobileGL/MG_Backend/MGPipe/PipeInputs.h:1 # pre-existing at 37da3c3a, unchanged
$ awk '/struct MGPipeResourceOps \{/,/^ \};/' MobileGL/MG_Pipe/PipeApply.h | grep -c MG_State
0 # D-B1: no op-table member added, no MG_State type
```
**One G1 failure was found and fixed inside d2, before the commit**, and it is DV-9's evidence: 8
added / 8 removed / 6 resized, every one of them attributable to the two lambdas and the two value
locals. The committed tree of every step is 0/0/0/0.
### 6.2 D-N byte identity
§4. rc 0 for all four functions this package owns; `p3a_untouched_regions.sh` rc 0 for P3a's eleven
after every commit. `git diff 37da3c3a HEAD -- MobileGL/MG_Backend/DirectGLES/Managers.cpp` lands
no hunk inside any of the four.
### 6.3 The legacy-arm lanes
```
$ MOBILEGL_PIPE_PUSH=0x1ff ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8 -R DirectGLES
99% tests passed, 6 tests failed out of 491
$ MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8 -R DirectGLES
99% tests passed, 6 tests failed out of 491
```
**Both lanes fail on the SAME six cases and nothing else**, and the two failing sets are identical:
```
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexInput
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexBufferSet
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.ABufferAtARecycledAddressDoesNotInheritItsPredecessorsContents
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.ATextureAtARecycledAddressDoesNotInheritItsPredecessorsTwin
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AFramebufferAtARecycledAddressDoesNotInheritItsPredecessorsTwin
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.DestroyedVertexArraysReturnTheirVertexElementsSlots
(Subprocess aborted)
```
**Explanation, and it is a cross-package sequencing artefact the brief itself predicts — not a
defect in this package, and not a missing applier record.** Those six cases are the `.Handles` arm,
whose ctest `ENVIRONMENT` property pins `MGL_ITEST_HANDLES_ARM_KNOBS =
"MOBILEGL_PIPE_LEGACY_MEMOS=0" "MOBILEGL_PIPE_PUSH=0x1ff"` at
`MobileGL/MG_IntegrationTest/CMakeLists.txt:949`. A ctest `ENVIRONMENT` property **replaces rather
than appends and overrides the job env**, which is why both outer lanes see the identical failure
set. Under that pinned pair, all four P4a families classify as `NoArm` — the bits are clear AND the
operator asked for the pre-handle arms to be gone — and `StopOnArmlessPipeSubsystem` aborts, which
is **exactly what D-K3 rules must happen** ("all four can reach `NoArm` and all four stop with the
named `Fatal{PipeLegacyMemosDisabled, …}` rather than skipping green").
The fix is the pin move D-K1 already mandates and C.7 already assigns: **`0x1ff` → `0x1fff` at
`MG_IntegrationTest/CMakeLists.txt:949, 1065, 1075, 1149, 1183, 1188, 1219` and
`0x80000000000001ff` → `0x8000000000001fff` at `:1070, 1080`, which contract deviation D10 confirms
is package F's** — "pinning it at `0x1ff` after P4a would leave the `Handles` arm asserting the P3a
shape while the handles it is supposed to be about stayed switched off" (`CMakeLists.txt:942-947`'s
own argument). **Until F lands, or the integrator moves those pins when merging `esprytobj`, these
six cases are red on the integrated tree.** Softening the stop would be re-deciding D-K3 inside a
package, which ID-8 forbids, and would make the whole four-family A/B silently unmeasurable.
Everything else in both lanes passes; the skip list is the pre-existing one (the seven
`DirectGLES.*Scenario` entries that skip without an arm selector, the two
`LargeArenaAdoption` capability skips, the forced-D24S8 and async entries).
**Proof, run standalone so the abort's own log line survives** — ctest's ENVIRONMENT property
replaces the job env, so `MOBILEGL_LOG_FILE_PATH` cannot be injected into the lane, and the Fatal
goes to the log rather than to stdout:
```
$ MOBILEGL_LOG_FILE_PATH=/tmp/p4a-d.log MOBILEGL_BACKEND_TYPE=DirectGLES \
MOBILEGL_PIPE_LEGACY_MEMOS=0 MOBILEGL_PIPE_PUSH=0x1ff \
build-push/MobileGL/MG_IntegrationTest/MobileGLIntegrationTest \
--gtest_filter='IntegerBorderColorScenario.InsideTexelsAreUnaffectedByTheBorderColour'
Aborted exit=134 (SIGABRT)
[FATAL]: MGPipe: Fatal{PipeLegacyMemosDisabled, "MOBILEGL_PIPE_PUSH leaves
kMGPipeSubsystemTextureResources (bit 10) clear (or refuses it) and
MOBILEGL_PIPE_LEGACY_MEMOS=0 disables the pre-handle texture cheap-gate trio,
so there is no arm to run"}
$ ...same, with MOBILEGL_PIPE_PUSH=0x1fff (what package F's pin move produces)
exit=1 # no abort; an ordinary scenario failure
[ERROR]: MGPipe: texture 1 has no applier record on the handle arm, so its parameters
cannot be pushed (handle {1, 0})
```
That second run is the whole argument in two lines: **with the phase mask moved, the armless stop
disappears and what is left is §6.5's missing-record set**, which the client packages close.
### 6.4 The default arm, and every failure classified
```
$ ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8 -R DirectGLES
62% tests passed, 189 tests failed out of 491
```
**189 = 183 + 6, and both terms are accounted for.**
- **6** are §6.3's armless stop, unchanged from the other two lanes and owned by package F's pin
move. They are the only cases that ABORT rather than fail.
- **183** are the missing-applier-record set, and the attribution is a log line rather than an
argument. Running one of them standalone with the log captured:
```
$ MOBILEGL_LOG_FILE_PATH=/tmp/p4a-c.log MOBILEGL_BACKEND_TYPE=DirectGLES \
build-push/.../MobileGLIntegrationTest \
--gtest_filter='IntegerBorderColorScenario.InsideTexelsAreUnaffectedByTheBorderColour'
[ FAILED ] IntegerBorderColorScenario.InsideTexelsAreUnaffectedByTheBorderColour
$ grep -c 'no applier record' /tmp/p4a-c.log
3
[ERROR]: MGPipe: texture 1 has no applier record on the handle arm, so its parameters cannot be pushed (handle {1, 0})
[ERROR]: MGPipe: texture 1 has no applier record on the handle arm, so its built-in sampler cannot be pushed (handle {1, 0})
[ERROR]: MGPipe: texture 1 has no applier record on the handle arm, so its storage and uploads cannot be driven from the pushed descriptor (handle {1, 0})
```
Three refusals, one per switched-over texture path, each naming the handle it could not resolve —
`{1, 0}`, a handle the backend's own minting overload produced and for which the applier holds no
record because nothing has emitted one. **No case fails for any other reason**, and no handle arm
reads `MGB_CTX` or the frontend object to make a lane pass: every decline is a named
`MGLOG_E_ONCE` and a `return`.
The shape of the 183, stated so it can be re-stated unchanged after the rebase (P3a's espryt v2
discipline): every scenario whose draw needs a texture uploaded, a texture parameter pushed, a
built-in sampler pushed, a renderbuffer allocated, a framebuffer synced or a program's serial
stamped. The three lanes that carry their own phase pin (`ForcedDepthStencilEmulation`,
`WidenedPacked16`, `NoViewportArrayEmulation`) are in it for the same reason; the pure buffer,
clear, scissor, viewport and XFB scenarios are not, which is why 302 still pass.
### 6.5 What this tree cannot show, and why
Per ID-2 this package lands **after** `wire`, `clientfb` and `clientsp`. On this tree the applier's
fifteen P4a entry points are still `c0`'s stubs and **no client emitter has a body**, so
`MGPipeApplier().TextureResources` / `RenderbufferResources` / `SamplerCsos` / `SamplerViewCsos` /
`ShaderCsos` and both framebuffer records are permanently empty. Every switched-over path therefore
takes its named refusal (`MGLOG_E_ONCE`, one per family per texture/framebuffer/sampler/program) and
declines, which is by construction: a fall-back to the frontend would hide a missing record behind a
picture that still looks right, and that is precisely what the subsystem A/B exists to expose
(`MarkBufferGpuWritten`'s note, P3a). **No handle arm re-reads `MGB_CTX` or the frontend object to
make a lane pass.**
The expected failing set on the default arm is therefore "every case that draws through a texture,
a framebuffer, a sampler or a program with a P4a bit set" — measured at **183 of 491** in §6.4,
with its log evidence — and it is stated there **by shape** so it can be re-stated unchanged after
the rebase, exactly as P3a's espryt v2 did.
**The one thing to check first after the rebase is that this number goes to zero rather than
down**: a residual "no applier record" line for one kind after the client packages land is a seam
defect (a handle minted on one side and looked up on the other), not a leftover.
---
## 7. Post-rebase verification list (to run on `~/w7/pipe` after wire + clientfb + clientsp)
This is the list to run when the integrator says the client packages have landed — the first time
real records exist. Every line is C.3's, plus the two this round could not run.
1. `cmake --build build-linux && python3 scripts/symbol_report.py --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` → 0/0/0/0.
2. `grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$'` → only `PipeInputs.h:1`.
3. `awk '/struct MGPipeResourceOps \{/,/^ \};/' MobileGL/MG_Pipe/PipeApply.h | grep -c MG_State` → 0.
4. `bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD` → rc 0.
5. `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` → rc 0 **once package F has landed it**; before that, §4's equivalent.
6. `cmake --build build-push && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure`.
7. `ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8 -R DirectGLES` — **the real-path round**. This is the one that matters: P3a's equivalent found three seam defects no package tree could see. The three seams to look at first, in order of risk:
- **the pending-upload set** (D-D5): does the client clear its own dirty flags only for records the applier accepted, and does `ConsumePipeTextureUpload` fire exactly where a level uploaded? A level cleared client-side but never consumed server-side is a texture that stops updating; the retain-mode comparison in the verify lane is the gate.
- **the `DepthStencilMode` and upload-target encodings** (DV-2, DV-3): if package B emitted a different encoding than §5 states, `GL_DEPTH_STENCIL_TEXTURE_MODE` is pushed backwards and cube faces resolve to the wrong pending entry. `TextureParamsWithoutASamplerViewScenario`'s depth-stencil case is the behavioural gate.
- **`PushedFramebufferRecord`'s `Fbo` match**: if the client emits `Target = Both` where Espryt expects a per-target record, or emits for a framebuffer other than the one being synced, the twin declines and the framebuffer is not synced at all.
8. `MOBILEGL_PIPE_PUSH=0x1ff ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8 -R DirectGLES` → green **only after the §6.3 pin move**.
9. `MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8 -R DirectGLES` → same.
10. `MOBILEGL_PIPE_PUSH=0x9ff ctest --test-dir build-push -R 'ObjectSubsystemControl'` — the sampler-bit-without-the-texture-bit refusal, once package F has written that scenario. This package's half (the `MGLOG_E` and the legacy fall-back) is already in.
11. `python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p4a-esprytobj -j 4` — not run this round: with empty records the corpus can only reproduce the refusal set, so the number would mean nothing.
12. `ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4`, and the **retain-mode** texture-dirty-rect comparison of G4, which is the only way a consume-and-clear set can be checked at all.
13. `ctest --test-dir build-push -R 'TextureParamsWithoutASamplerView'` — G9's mandatory scenario. Its red-before case
`AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver` is closed on the **E** side
(`SyncAttachmentObject` gains the parameter sync for READ-only attachments); this package
supplies the half that makes it possible, namely that `set_texture_params` is addressed by
resource and `SyncTextureParamsToBackend` no longer needs a sampler view to have a record.
14. `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` exported for 6, 7 and 12 (ID-18/ID-21).
---
## 8. Open items handed on
| item | owner |
|---|---|
| DV-5's `MGPSurface` texture-target field (or the inverse mapping), which unblocks the four cross-object masks and E's `SyncAttachmentObject` | contract (A) + integrator |
| DV-2 / DV-3 / DV-4: the `DepthStencilMode` encoding, the upload-target encoding, the `MGPSurface::Kind` enum | contract (A) + integrator; package B must emit DV-2/DV-3 as stated |
| the itest phase-mask pins `0x1ff → 0x1fff` and `0x80000000000001ff → 0x8000000000001fff` | package F (contract D10); **blocks §6.3** |
| `scripts/p4a_untouched_regions.sh` | package F |
| the four remaining `MGPipeUnmigratedEmulation` sites (`copy-image-shadow-mirror`, `generate-mipmap-storage`, `generate-mipmap-cpu-fallback`, `get-tex-image-shadow`) | package E |
| the four `g_fboSynced*` arrays' READERS, in `SyncCurrentFBO` | package E |
| the nine-clause rebuild condition reading `GetSyncedShaderCsoSerial()` | package E |
| the sampler-view twin's first consumer (the resolved-set walk and the raw-depth-fetch substitution keyed on it) | package E |