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

431 lines
39 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 B — `clientfb`, adversarial review v1
Reviewed: `refs/heads/p4a/clientfb` @ `f7de87b5` (`51d1760f` / `a78eaf93` / `f7de87b5`) against the tag
`p4a/contract` = `08192d72`, and against `refs/heads/feat/disaggregated` @ `17db7598` (= c0 + c0b + c0c) and
`refs/heads/p4a/wire` for the seams the rework has to meet. 13 files, +2647 / −55.
**Method.** Read-only. I did not create a worktree and did not re-run B's gates — the report's transcript is
internally consistent, the file list matches C.7 exactly, and every finding below is decided by reading code
across four refs rather than by a build. Where a finding needed a fact I could not read off B's branch (the
wire applier's arity, c0b's declarations, C's cache seam) I read it out of the branch that owns it. Every
finding carries the refutation I tried.
---
## Verdict: **REWORK**
Not because the package is weak — it is the most carefully argued of the client packages, its eleven
deviations are honest, and D4 (the blocked texture flip) is a real find that D.1's ordering justifies after
the fact. It is REWORK because three of the brief's own named properties are not actually delivered:
- **M1** the `MGPSubRegion[]` tail is built and never handed to the applier, so D-D6's "the SERVER picks the
upload shape" is unimplemented and, after the rebase onto wire, becomes a record that declares N regions
and supplies none;
- **M2** no emission site covers the thirteenth `MGP_NOTE_AGGREGATE(TextureParams)` site — the built-in
sampler's own choke point — so `MGPTextureParams::{MinLod, MaxLod, LodBias}` go stale on
`glTexParameterf(GL_TEXTURE_MIN_LOD)`, and it is the exact hook ID-14's re-emit needs;
- **M3** the client clears its own dirty flag on *dispatch*, not on *acceptance*, which is the one thing
D-D5 step 1 spells out and the one thing its unit case claims to pin;
- plus **M4**, the sticky `BindMask` / `ImageBindableHint` never reaching the applier for the canonical
immutable-storage order.
The mandatory c0b / c0c / ID-14 reconciliation is by itself a rework of comparable size, so folding these in
costs one round rather than two.
---
## 1. Findings
### MAJOR
#### M1 — `RegionCount` is emitted; the regions are not. `MG_Impl/Pipe/TextureEmit.h:939-941`
```cpp
if constexpr (MGPipeTextureRecordsReachTheApplier()) {
MGPipeApplyResourceSubData(m_lastSubData, shadow); // <- two arguments
}
```
`m_regions` is filled at `:909-914`, its size is written into `m_lastSubData.RegionCount` at `:928`, it is
exposed to unit cases through `LastRegions()` at `:778` — and it is never passed to anybody. On the tag the
applier's signature is two-argument (`MG_Pipe/PipeApply.h:585`), so today the omission is unobservable and
compiles. On `refs/heads/p4a/wire` W1 closed contract-review M2 by giving that call a defaulted trailing
`const MGPSubRegion*` (`PipeApply.h:628`) — **and B still passes nothing**, so after the rebase the applier
receives `RegionCount = N` with a null tail on every scattered upload.
*Failure scenario.* Atlas traffic (`rei`, `xaero-*`, `journeymap`, `modernui` — the fixtures D-D5 names) is
the scattered case: two far-apart sprite writes produce `RegionCount = 2` and a null list. Either the applier
faults on the mismatch (the loud direction, and the best case), or it stores a pending set with two declared
regions it cannot read and Espryt picks the box — which silently discards D-D6's entire measured argument
(635 KB/frame box vs 40 KB/frame rects, 16×, and Mali's per-job +6 ms/frame). Nothing in the tree can see the
difference: SSIM is blind to upload shape, so the retrace's 79/79 proves nothing here, and the four unit cases
that touch regions all read `LastRegions()` — the emitter's own staging vector — rather than what the applier
was handed.
*Refutation attempted, and it fails.* (a) "The record is not sent at all today, so it cannot matter" — true
for `resource_subdata` under `kMGPipeWiredTextureSubsystem = 0`, but §9's one-line flip is made *in the same
commit as the rebase*, which is precisely when both halves become live at once. (b) "RegionCount 0 is the
common case" — `MipmapStorage::MarkDirtyRegion` seeds the rect list from the union box and inserts, so a
*single* `glTexSubImage2D` on a clean level already produces `RegionCount = 1`; zero is the *whole-level*
case, not the common one. (c) "The applier could recover the regions from the box" — that is exactly the
information the box does not carry.
**Fix**: pass `m_regions.data()` (and keep passing `nullptr` when the list is empty) at the rebase, and change
`AScatteredUploadCarriesTheLevelShadowsStridesAndNotZero` to assert on what the applier received rather than on
`LastRegions()`.
---
#### M2 — the built-in sampler's parameter mutators publish no `set_texture_params`
C.1's MODIFY row asks for *"`set_texture_params` from the thirteen `MGP_NOTE_AGGREGATE(TextureParams)` sites"*.
There are exactly thirteen in the tree:
| where | count | hooked by B? |
|---|---|---|
| `MG_State/GLState/TextureState/TextureObject.cpp` :174 :208 :226 :244 :297 :308 :329 :347 :371 | 9 | yes (`PipePublishParams` at :181 :210 :228 :246 :299 :310 :335 :350 :378) |
| `TextureObject.h:192` (`SetDepthStencilTextureMode`) | 1 | yes (`:197`) |
| `TextureObject.cpp:417` (`SetSamples`), `:430` (`SetFixedSampleLocations`) | 2 | **no** — descriptor only, and that is *defensible*: neither field exists in `MGPTextureParams` |
| **`MG_State/GLState/SamplerState/SamplerObject.cpp:53`** (`SamplerObject::BumpVersion`, whose own comment calls it *"the one choke point every setter reaches"*) | 1 | **NO — and this one is a defect** |
`MGPipeBuildTextureParams` reads three of its ten fields off that object
(`TextureEmit.h:346-351`: `MinLod`, `MaxLod`, `LodBias` from `texture.GetSamplerObject()`). Every
`glTexParameter*` that writes them lands on the `SamplerObject` and on nothing B watches —
`GL_Texture.cpp:1265-1276` (`GL_TEXTURE_MIN_LOD` / `MAX_LOD` → `SetLodRange`), `:1313` and `:1391`
(`GL_TEXTURE_LOD_BIAS` → `SetLodBias`), and their DSA twins at `:2038-2087` and the `*fv` families at
`:3062-3392`.
*Failure scenario.* `glTexStorage2D(…); glTexParameterf(GL_TEXTURE_MIN_LOD, 2.0f); draw;` — no
`set_texture_params` is emitted, the applier's record still says `MinLod = 0`, and Espryt's
`SyncTextureParamsToBackend` pushes the wrong LOD clamp. Wrong pixels, not a lost optimisation.
*And this is the ID-14 hook.* ID-14 requires B to *"re-emit `set_texture_params` when the sampler object's
parameters change"*, because C's cache is content-addressed and the handle moves with the content. Judged as
the review was asked to: **`SamplerResync` does not cover it** — `MGPipeBuildTextureParams:345` writes
`params.SamplerResync = 0` unconditionally, D-E2 makes both resync bytes the *server's* to set, and a resync
byte on a record that is never emitted is inert anyway. There is today **no path at all** from a sampler
parameter change to a `set_texture_params`.
*Refutation attempted.* (a) "Some other setter publishes afterwards" — `SetInternalFormat` publishes both
records, but no `glTexParameter*` touches the format; `SetBaseLevel` / `SetMaxLevel` are different pnames.
(b) "It is C's file, so it is C's problem" — `MG_State/GLState/SamplerState/**` is C's after the tag, so B
genuinely cannot hook `BumpVersion`; but the *record* is B's and C.7 grants B
`MG_Impl/GLImpl/Texture/GL_Texture.cpp` under exactly this rule (*"if an implementer finds a path that does not
go through them, the grant is one call site per path and it is recorded as a deviation"*). B did not take the
grant and §6 records it as "not needed", which is wrong for this class. (c) "The wired bit is 0, so nothing
breaks" — again, the flip is the integrator's next commit.
**Fix**, and it lands with ID-14 rather than beside it: latch `(m_textureParamsVersion,
sampler->GetVersion())` per texture in the emitter, and re-publish from the granted `GL_Texture.cpp`
`glTexParameter*` sites (or, if A/C prefer, have `SamplerObject::BumpVersion` call a B-provided hook — that is
a contract change and should be raised, not assumed).
---
#### M3 — the client clears its own dirty flag on *dispatch*, not on *acceptance*. `TextureEmit.h:947-951`
```cpp
if constexpr (MGPipeTextureRecordsReachTheApplier()) { MGPipeApplyResourceSubData(...); }
++m_subDatas;
...
mipmap->MarkStorageDirty(uploadTarget, level, false); // unconditional
```
D-D5 step 1 is explicit: *"the client clears its own `m_isDirty`/`m_dirtyRects`/`m_dirtyRegions` for the level
at emission, and **only for levels whose record the applier accepted** (the emit helper returns 'applied')"*.
`MGPipeApplyResourceSubData` returns `void` on the tag and on wire — the wire review's own m4 says no
acceptance signal exists — so B clears whatever happened. Worse, the clear runs **even when the record was
never dispatched at all**: with the texture bit still 0 the `if constexpr` discards the call and line 950 still
fires, which is exactly the state every `ArmForTest(true)` unit case runs in.
*Failure scenario, post-flip.* Any applier refusal on a `resource_subdata` — a stale generation, a box that
fails `SubDataBoxFault`, a resource whose record the applier does not hold (which is the *normal* state for a
texture born while the bit was clear until the self-healing create at `:601-608` catches it) — leaves the
server with nothing and the client with a clean flag. `MG_Impl` contains no reader of the texture's dirty
state, so nothing ever notices: **the level stops updating for the life of the texture**. This is the exact
"a texture that stops updating" the review brief asks about, and yes, it is reachable.
*The unit case pins the wrong property.* `TextureEmit.ABailedLevelStaysDirtyAndStaysOnTheDrainList`
(`TextureEmitTest.cpp`, second half) asserts `EXPECT_FALSE(good->IsStorageDirty(...))` with the message
*"the client must clear its own flag for a level whose record the applier accepted"* — on a build where the
applier was never called. It is green for the wrong reason, and it would stay green under a refusal.
*Refutation attempted.* (a) "There is no acceptance signal to check, so B did the only thing possible" —
partly true, and it is why this is shared with wire rather than B's alone; but B's *report* declares neither
the deviation nor the risk, and the honest minimum is a declared deviation plus a `MGLOG_E_ONCE` on the
non-dispatched path. (b) "The applier's pending-upload set is the safety net (D-D5 step 2)" — the net catches
Espryt's bails, which is a different failure; it cannot catch a record the applier refused.
**Fix**: either wire adds the return value (one line in `PipeApply.{h,cpp}`, and it is m4 of its own review),
or B clears only inside the `if constexpr` arm and logs once on the other. The first is correct; take it to
the integrator as a joint item.
---
#### M4 — the sticky `BindMask` / `ImageBindableHint` never reach the applier for immutable storage
`NoteTextureBoundAs` (`TextureEmit.h:482-494`) ORs the bit into the client entry and returns. Nothing
republishes. The comment at `FramebufferEmit.h:406-408` states the consequence as if it were the design:
*"the mask is republished on the resource's next respecify"*.
*Failure scenario.* `glTexStorage2D(…)` → one respecify with `BindMask = 0`, `ImageBindableHint = 0`. Then
`glBindImageTexture(…)` (or an FBO attachment) sets the bit client-side. An **immutable** texture has no next
respecify — that is what immutable means — so the applier's record keeps `ImageBindableHint = 0` forever. The
hint is described in B's own comment as *"the PREVENTION half of the texture-remint stall class — a texture the
server knows may be image-bound is allocated image-bindable up front, so the re-mint that would have to pull
its texels back never happens"*. For the canonical order (allocate, then bind) it never fires, so the
prevention half is a no-op for exactly the textures it was written for. The same is true of `RENDER_TARGET` /
`DEPTH_STENCIL`, whose only producers are `FramebufferEmit.h:409-421`.
*The unit case hides it.* `AnImageBoundTextureCarriesTheImageBindableHintForever` calls
`NoteTextureBoundAs(handle, kMGPipeBindShaderImage)` **before** `AllocateStorage`, i.e. in the one order in
which the mask does reach the wire. Reverse the two statements and the case goes red.
*Refutation attempted.* (a) "D-A4 only says the mask is *emitted on* create and respecify" — it does, and B
satisfies the letter; but D-A4 also says `ImageBindableHint` *"is the prevention half of §8.4's four
mitigations"*, and a value that cannot reach the server before the allocation it is meant to steer prevents
nothing. (b) "A mutable texture will respecify eventually" — true and irrelevant; the atlas and image-load/store
textures this targets are `glTexStorage`'d. (c) "The applier could re-derive it from `MGPImageView::Res`" —
that is C's family and a different bit; the descriptor field would still be wrong.
**Fix**: make `NoteTextureBoundAs` / `NoteRenderbufferBoundAs` republish the descriptor when the mask actually
*changes* (the memcmp dedupe at `:596` already makes the no-change case free), and add the reversed-order
assertion to the case.
---
### MINOR
| # | file:line | finding | scenario | refutation tried |
|---|---|---|---|---|
| m1 | `FramebufferEmit.h:83-91` | `MGPipeResolveAttachmentUploadTarget` falls back to `texture->GetUploadTargets()[0]` when the attachment carries `Unknown`. For a **cube map** that is six faces and `[0]` is `CubeMapPositiveX`. | `glFramebufferTexture(GL_COLOR_ATTACHMENT0, cube, 0)` (layered, no face token) emits a *resolved* record naming +X. Espryt reads `MGPSurface::UploadTarget` to pick the face; with `Layered = 1` it should ignore it, but the record now asserts a face that is not the truth. | The cited precedent (`FramebufferAttachmentObject::GetSize`, `FramebufferObject.cpp`) applies the same fallback — but it only needs an **extent**, which is identical across the six faces. Face *identity* is not. The precedent does not transfer. |
| m2 | `FramebufferEmit.h:136-143`, refusal loop `:345-357` | D-C3's over-wide refusal scans **attachments** only. A draw-buffer token may name a colour point ≥ 8 with nothing attached there; `MGPipeDrawBufferIndex` then returns 8..31 into an 8-wide `Color[]`. | `glDrawBuffers(1, {GL_COLOR_ATTACHMENT10})` with no attachment at 10 (legal state, incomplete for draw) → `DrawBuffers[0] = 10`. The server indexes `Color[10]` out of bounds, or must invent a bound the record does not carry. | The FBO would be draw-incomplete, so `Complete = 0` and a well-behaved server would not draw — but the record still carries an out-of-range index, and "truncating silently is the bug class this phase is closing" is the same argument that produced the attachment refusal. One extra test in the same loop. |
| m3 | `TextureEmit.h:564` vs `:569` vs `:609` | `Entry& entry = EntryFor(m_textures, handle);` is taken, then `AcquireTexture(owner…)` may `resize()` the same `Vector`, then `entry.LastDesc = desc` writes through the reference. | Dangling reference / heap corruption if the owner's slot exceeds the table's size. | **Refuted for production**: every texture registers its slot in `TextureObjectBase`'s constructor, so the table always already covers the owner. **Not refuted after `ResetForTest()`**, which clears `m_textures` while the allocator keeps its slots — an owner allocated at a higher slot than its view then resizes mid-function. Make `EntryFor` return an index, or re-fetch. |
| m4 | `TextureEmit.h:1060-1070`, `:442-448`, `:865-869` | `MGPipeEmitTextureResourceDestroy` returns **before** `NoteTextureRecordDestroyed` when the record was never published, so `Retire()` never runs; and `AcquireTexture` sets only `Texture` and `Gen`, leaving `BindMask`, `ForceParamsResync`, `HasLastDesc`, `LastDesc`, `DrainKeys` from the previous occupant. | Live **today**: the texture bit is 0 (nothing publishes) while the framebuffer bit is wired and `SurfaceOf` ORs `RENDER_TARGET`/`DEPTH_STENCIL` into those entries. A recycled slot's new texture inherits the dead one's sticky mask, hence a wrong `BindMask`/`ImageBindableHint` on its first descriptor. | `LastDesc` inheritance is harmless (it embeds `Resource`, whose `Gen` differs, so the memcmp cannot false-hit). The mask inheritance is not. c0b's `{kind, slot, gen}` latch fixes the publication half; the Entry reset is still B's. |
| m5 | `FramebufferEmit.h:240-241`, `:379` | A `Target = Draw` record's `ReadSurface` is resolved from the **read** framebuffer, so it describes a surface that is not part of the framebuffer its own `Fbo` names — and a `glReadBuffer` on the read FBO moves the *draw* record's `ContentHash` and forces a redundant draw emission. | Correct per D-C2's letter (*"resolved from the READ framebuffer's own read buffer"*), muddled in substance. Cost is one extra 304-byte record per `glReadBuffer`. | Not a defect, but the server must be told to read `ReadSurface` only off a `Read`/`Both` record; say so in the payload comment so E's `SyncCurrentFBO` cannot read it off the draw record. |
| m6 | `FramebufferEmit.h:122`, test `FramebufferEmitTest.cpp` empty-point assertion | `MGPSurface::UploadTarget` is written `0` on renderbuffer and empty points, and `0 == TextureUploadTarget::Texture1D` — the *same* enumerator collision ID-12 ruled on for `MGPSubData::Target`. | A consumer that reads `UploadTarget` without first testing `Kind` reads "1D texture". | `Kind` disambiguates, so it is currently unreachable; but c0c's `MGPSurface::TextureTarget` explicitly takes `0xFFFF = Unknown` on non-texture points, and `UploadTarget` should follow the same rule in the same rework. The unit case pins the ambiguous value and must move with it. |
| m7 | `FramebufferEmit.h:56` + `TextureEmit.h:98` | The branch ships **bit 9 wired, bit 10 unwired** — the arm D-K2 forbids (*"bit 9 (framebuffer) requires bit 10"*), because every `MGPSurface::Res` names a handle the applier has no record for. | Inert today (nothing consumes `set_framebuffer_state` before Espryt lands), and §9 already makes the flip mandatory in the rebase commit. Recorded so it cannot be dropped: **the branch must never be integrated with only one constant flipped.** | Refuted as a live defect; kept as an integration hard constraint. |
| m8 | `TextureObject.cpp:263` (`SetInternalFormat` → `PipePublishDescriptor`) | The first `resource_respecify` for a texture is emitted from `SetInternalFormat`, before any storage exists, carrying `Width = Height = 0`, `Levels = 0`, `HasDefinedContent = 0` — a "storage definition" that defines none. | Extra record per texture; a strict applier could count it as a respecify to a zero extent. | Harmless as long as the applier tolerates a zero-extent respecify (P3a's buffer bodies do). Declare it, or gate the publish on `storageDefined`. |
| m9 | `FramebufferEmitTest.EveryAttachmentFieldSurvivesTheSurfaceConversion` | C.1 asks G6 to be driven *"through the texture, the DSA-named, the renderbuffer and the layered entry points"*; the case drives `AttachTexture` / `AttachRenderbuffer` / the layered flag but not a DSA-named path. | Weaker coverage than the brief asks. | All four GL entry points funnel into `FramebufferObject::AttachTexture`, so a state-level unit case genuinely cannot distinguish them. Declare it rather than fake it. |
---
## 2. The declared deviations, judged
| dev | judgement |
|---|---|
| **D1** MG_State reaches the emitter through two TUs | **Superseded by c0b (ID-13).** The reasoning was right at the tag and is now moot: `PipeMutation.h:281-358` declares four mints and nine emissions and `PipeFill.cpp:1042-1114` forwards them through `ForwardWhenWired<kWired>`. The rework deletes B's six free functions and re-points the MG_State call sites. Full site list in §3. |
| **D2** `MGPSubData::Target` PACKED | **ADOPTED (ID-12 DV-3).** B's spelling wins. c0c has moved `MGPipePackSubDataTarget` / `…ResourceTargetOf` / `…UploadTargetOf` into `MGPipeTypes.h` under the same names with `Uint32` arguments; B's copies at `TextureEmit.h:162-176` must be deleted (they are `inline constexpr` in the same namespace — leaving them is a redefinition). |
| **D3** step 1 emitted from the destructor | **Superseded by c0b (ID-13).** `MGPipeEmitTextureDestroyAndFree` / `…RenderbufferDestroyAndFree` now read `MGPipeHandleIsPublished` and emit `MGPipeApplyResourceDestroy` themselves (contract-v2 §M1(b), `PipeFill.cpp:1199-1200` / `:1235-1236`). B's `MGPipeEmitTextureResourceDestroy` / `…RenderbufferResourceDestroy` and both destructor call sites are deleted. |
| **D4** `kMGPipeWiredTextureSubsystem` stays 0 | **ACCEPTED, and it is the report's best work.** The `Fatal{ProtocolCorruption} … the buffer half carries a mip level` was found, not argued, and it is direct evidence for D.1's stated order. Verified independently: `PipeFill.cpp:1292-1310` ORs the constant into `kMGPipeWiredSubsystems` and `static_assert`s it is 0-or-its-own-bit, and `:1934` gates `DrainTextureSubData` on that OR — so the one-line flip really is the whole switch, and nothing else moves. **The flip claim checks out.** |
| **D5** drain flag on the client, not on `MipmapStorage` | **ACCEPTED.** Better than D-D4's letter: no MG_State member, so G1's admitted-resize set stays empty, and the ≤96-entry scan sits on a path that has just memcpy'd texels. |
| **D6** descriptor deduped on its own bytes | **ACCEPTED.** An 88-byte memcmp against the emission it avoids is the right trade and it is what keeps `glRenderbufferStorage`'s three setters one record. |
| **D7** `MGPSurface::Kind` reuses `MGPipeKind` | **ADOPTED (ID-12 DV-4).** c0c mints `kMGPipeSurfaceKindNone/Texture/Renderbuffer`; B's copies at `FramebufferEmit.h:73-77` are deleted. |
| **D8** `DrawBuffers[]` narrowing of the four default tokens | **ACCEPTED with m2.** The stereo argument is right (`FramebufferObject`'s constructor seeds `BackLeft` and nothing writes another). The narrowing is not the problem; the *widening* above the array bound is (m2). |
| **D9** `DepthStencilMode` numbered | **ADOPTED (ID-12 DV-2).** c0c mints `kMGPipeDepthStencilModeDepth/Stencil`; B's copies at `TextureEmit.h:182-183` are deleted, `MGPipeDepthStencilModeByte` stays B's. |
| **D10** `BuiltinSampler` identity-addressed | **REWORK (ID-14).** See §3. B's own §9 flagged it first and correctly; ID-14 rules the direction. Note the ordering problem in §3.4 — B cannot do this on its own branch. |
| **D11** one `SamplerCso` slot per texture not released | **Dissolved by ID-14.** After the rework B mints no `SamplerCso` at all, so there is nothing to leak; C's LRU eviction is the only `delete_sampler_state` emitter. Delete the deviation rather than carry it. |
**On C1 (wire), asked directly: does B's emission order make the loss reachable today?** **Yes, and by the
ordinary path.** `glTexImage2D(level 0, data)` → `AllocateStorage` → respecify → mark dirty → validate →
`resource_subdata` accepted into `PendingUploads[(target,0)]` **and the client's flag cleared** → Espryt bails
on the incomplete texture and keeps the pending set → `glTexImage2D(level 1, …)` → `AllocateStorage` →
**another respecify**, which under `PipeApply.cpp:1485` clears the *whole* `PendingUploads` → level 0's texels
exist nowhere. `glGenerateMipmap` is worse: `GL_Texture.cpp:524-536` emits one respecify per generated level
plus a `TruncateMipmapLevels`. So wire's C1 fix (scope the clear to the redefined level) is a **hard
prerequisite for the texture flip**, not a tidy-up, and M3 above is the client half of the same hole.
---
## 3. The exact rework list
### 3.1 c0b reconciliation (ID-13) — every site that changes
`MG_Impl/Pipe/TextureEmit.h`, emitter class — **rename to contract-v2 §3.4's exact spellings** (the wired
constant makes a mismatch a compile error in B's own commit):
| now | must become |
|---|---|
| `EmitTextureCreate` / `EmitTextureCreateFromBase` | one `void EmitResourceCreate(MG_State::GLState::ITextureObject&)`. **Keep the target-derived storage kind** — the hook is still called from `TextureObjectBase`'s constructor, so `GetStorageType()` is still pure-virtual there and `MGPipeTextureStorageKindForTarget` is still the only legal source. Bind the reference to `*this`; read only non-virtual members. |
| `EmitTextureRespecify` | `void EmitResourceRespecify(MG_State::GLState::ITextureObject&)` |
| `EmitTextureParams` | unchanged name, already matches |
| `NoteLevelDirty(ITextureObject&, MobileGL::TextureUploadTarget, Uint)` | `NoteLevelDirty(ITextureObject& storageOwner, Uint32 uploadTarget, Uint32 level)` — parameter types change |
| `EmitRenderbufferCreate` / `EmitRenderbufferRespecify` | unchanged names, already match |
Free functions in `TextureEmit.h` — **delete all eight** and repoint the MG_State call sites:
| delete | MG_State site now calling it | calls instead |
|---|---|---|
| `MGPipeMintAndCreateTexture` (`:992`) | `TextureObject.cpp:248` (ctor) | `MGPipeMintTextureHandle(*this)` **and** `MGPipeEmitTextureResourceCreate(*this)` |
| `MGPipeEmitTextureRespecify` (`:1002`) | `TextureObject.cpp:216` (`PipePublishDescriptor`) | `MGPipeEmitTextureResourceRespecify` |
| **`MGPipeEmitTextureParams` (`:1007`)** | `TextureObject.cpp:220` | `MGPipeEmitTextureParams` — **name collision**: `PipeMutation.h:301-358` declares this exact signature and `PipeFill.cpp` defines it. B's `inline` definition is a second definition of the same function and **will not compile after the rebase.** |
| `MGPipeNoteTextureLevelDirty` (`:1012`, 4 params incl. `Bool dirty`) | `TextureObject.cpp:225` | see §3.2 — the contract's hook has **no clean arm** |
| `MGPipeMintAndCreateRenderbuffer` (`:1023`) | `RenderbufferObject.cpp:67` (ctor) | `MGPipeMintRenderbufferHandle` **and** `MGPipeEmitRenderbufferResourceCreate` |
| `MGPipeEmitRenderbufferRespecify` (`:1032`) | `RenderbufferObject.cpp:131` | `MGPipeEmitRenderbufferResourceRespecify` |
| `MGPipeEmitTextureResourceDestroy` (`:1060`) | `TextureObject.cpp:209` | **delete the call** — c0b's helper emits the destroy itself |
| `MGPipeEmitRenderbufferResourceDestroy` (`:1072`) | `RenderbufferObject.cpp:88` | **delete the call** |
Publication latch — **deviation D17 makes the latch A's, not B's**:
- delete `Entry::Published`, `TextureRecordIsPublished`, `RenderbufferRecordIsPublished`,
`NoteTextureRecordDestroyed`, `NoteRenderbufferRecordDestroyed`, `PublishedIn`, `Retire`
(`TextureEmit.h:503-517`, `:860-869`);
- call `MGPipeNoteHandlePublished(MGPipeKind::Texture|Renderbuffer, handle)` in `EmitResourceCreate` /
`EmitRenderbufferCreate` **and** in the self-healing create branch at `:601-608` / `:676-682`;
- keep the self-heal — it is still needed and c0b does not provide it.
Also: `MGPipeMintTextureHandle` is pure allocator work and does **not** populate `Entry::Texture`, which
`ResolveTexture` needs at drain time. Confirm every path that can put a level on the drain list has first run
through `NoteLevelDirty`'s own `AcquireTexture` (it does today), or populate the entry from the mint.
Finally, `MGPipeTextureEmitter::ArmForTest` becomes redundant once the constant is flipped — `PipeFill.cpp`'s
`FamilyIsLive(kMGPipeSubsystemTextureResources, kMGPipeWiredTextureSubsystem)` gate does not consult it, so
after the rebase the two suites' `ArmForTest(true)` no longer arms anything the frontend drives. **Delete
`ArmForTest` and `m_armed` in the same commit as the flip**, and let `MGPipeTextureSubsystemEnabled()` be the
config-bit test alone; leaving it is a latch that lies.
### 3.2 The one thing c0b does not give B
`MGPipeNoteTextureLevelDirty(ITextureObject&, Uint32, Uint32)` has **no `dirty = false` arm**, but B needs one:
`TextureObjectWithOneMipmap::MarkStorageDirty(t, l, false)` and `GL_Texture.cpp:529`'s generated-mip clean both
have to reach `NoteLevelClean`. Options, in preference order: (a) ask A to widen the hook to carry the flag
(one parameter, and it is the honest shape); (b) keep a second B-owned entry point and record it as a fresh
deviation. **Do not** silently drop the clean arm — the drain list then keeps keys for levels that are no
longer dirty and `EmitOneLevel`'s `IsStorageDirty` early-out becomes the only thing collecting them.
### 3.3 c0c helper deletions and the `TextureTarget` fill (ID-12)
- delete `TextureEmit.h:162-176` (`MGPipePackSubDataTarget` / `…ResourceTargetOf` / `…UploadTargetOf` and the
`static_assert`) — they are now `MGPipeTypes.h`'s, same names, `Uint32` arguments;
- delete `TextureEmit.h:182-183` (`kMGPipeDepthStencilModeDepth/Stencil`), keep `MGPipeDepthStencilModeByte`;
- delete `FramebufferEmit.h:73-77` (`kMGPipeSurfaceKind*` and the `static_assert`);
- **fill `MGPSurface::TextureTarget`** (was `Pad0`) in `MGPipeBuildSurface`
(`FramebufferEmit.h:101-124`): `static_cast<Uint16>(texture->GetTarget())` on the texture arm, `0xFFFF` on
the renderbuffer arm **and on the empty-attachment early return at `:104`** (a zero-initialised `MGPSurface`
would otherwise say `TextureTarget = 0`, not Unknown — check what c0c's field default requires);
- **add it to the hash**: `MGPipeCopySurfaceForHash` (`:164-172`) must copy the new field, or a texture-target
change alone is suppressed. It is now a `PipeFields.def` row, so the field-wise copy is mandatory;
- apply m6 in the same edit: `UploadTarget = Unknown` rather than `0` on non-texture points, and move
`FramebufferEmitTest`'s `Color[1].UploadTarget == 0u` assertion with it.
### 3.4 ID-14 — the built-in sampler acquisition, and an ordering problem
`TextureEmit.h:636-637` must stop calling `MGPipeSlots().Acquire(MGPipeKind::SamplerCso,
sampler->GetLifetimeId())` and instead obtain the handle from C's content-addressed cache
(`MGPipeSamplerCsoCache::Acquire(params, payloadBytes)`, `SamplerEmit.h` on `p4a/clientsp`); `TextureEmit.h`
may include `SamplerEmit.h`, and `check_include_closure.py --mode both --require-all` must be re-run.
Re-emit `set_texture_params` whenever the built-in sampler's parameters move — **which is M2**, so the two are
one edit. Drop the per-texture `SamplerCso` death path (there is none today; keep it that way) and delete D11.
**Ordering problem the integrator must resolve.** `SamplerEmit.h` on `p4a/clientfb` is still the contract stub
(76 lines, no cache), and D.1's order integrates `clientfb` **before** `clientsp`. So B cannot make this edit
on its own branch. Either (a) land B's rework with D10 still identity-addressed and a `TODO`-free declared
deviation, then make the acquisition a first-class item of **C's** verification round on the integrated tree
(with `TwoTexturesWithIdenticalSamplingShareOneBuiltinCso` as its gate — it SKIPs today with the reason
printed, which is the right shape), or (b) swap the two packages' integration order. (a) is cheaper and is
what §9 already anticipates; say which, in writing, before B's rework starts.
### 3.5 The wired-bit flip
`TextureEmit.h:98`: `= 0` → `= kMGPipeSubsystemTextureResources`, **in the same commit as the rebase**, per
§9 and per m7. Verified: `PipeFill.cpp:1292-1310` and `:1934` make this the entire switch; the four
`static_assert`s and the `EmittedCallSuppliesTheWholeField` rows are untouched by it.
### 3.6 The findings
M1 (pass `m_regions.data()`), M2 (§3.4), M3 (acceptance signal — joint with wire), M4 (republish on a mask
change), m1, m2, m3, m6 (folded into §3.3). m5, m7, m8, m9 may be **declared** rather than fixed.
---
## 4. What I checked and did not fault
- **Handle minting and death (D-A/D-B, ID-8).** One handle per texture object including views, buffer
textures and cube maps (the cube's six faces are six blobs on one handle, `TextureEmit.h:220-224` — right).
Stale-generation refusal is present and doubled in `ResolveTexture` (`:466-473`: entry gen **and**
`MGPipeSlots().GenOfSlot`). `MGPipeSlots().Acquire` is `FindByLifetimeId`-then-allocate
(`SlotAllocator.h:73-74`), so the repeated `AcquireTexture` on the respecify / params / dirty paths is
idempotent and mints nothing — I checked this specifically, because a mint-per-call would have been a slot
leak on the hottest path in the package. Destroy-then-notify-then-free order is exactly `PipeMutation.h`'s.
The `ObjectLifetimeIdTest` extension is a genuine 64-round churn check under push. No leak-test gap found;
the DirectVulkan lane matters here only through the death helpers, which are backend-neutral by
construction (no op table involved at all — D-B1).
- **Exit-order rule (ID-8).** Both emitters are `new`'d singletons, never destroyed
(`TextureEmit.h:971-978`, `FramebufferEmit.h:466-472`), with the right reason stated
(`~TextureObjectBase` reads *and writes* the emitter's tables through the death path). `Entry::Texture` is a
**raw** pointer — no new static holder of a frontend `SharedPtr` anywhere in the package. Clean.
- **MGLOG discipline.** Exactly two log statements, both `MGLOG_E_ONCE`, both on real error paths. No
`MGLOG_I`, no `printf`, no `TODO`/`FIXME`, no macros defined (so no `#undef` hygiene question).
- **G1 mechanism (dimension 8).** Not macros and not separate TUs: *every* MG_State edit is a statement (or a
declaration) inside the file's existing `#if MOBILEGL_PIPE_PUSH`, including the three
`TextureObjectBase::PipePublish*` **declarations** in `TextureObject.h:446-472`, the inline body inside
`SetDepthStencilTextureMode` (`:190-198`), `RenderbufferObject::PipePublishDescriptor`'s declaration
(`RenderbufferObject.h:145-151`), and `TextureObjectBuffer::SetBufferRange`'s call (a header inlined into
many TUs). **No new data member and no new virtual anywhere** — so the pull build's preprocessed text is
unchanged and P4a's admitted-resize set stays empty. The report's 0/0/0/0 with `.text` 10806323 → 10806323
is consistent with what the diff can do. P3a's eleven untouched: nothing in the file list can reach them.
- **The 22 emitter cases + pull==push names (dimension 7).** 14 `TextureEmit` + 8 `FramebufferEmit`; the two
`MGL_*_CLIENT_TEST_LIST` pull-skip macros name exactly the same 14 and 8, so pull and push register
identical names and the report's empty `diff` is structurally guaranteed. Reading each body against its
reason: 20 of 22 can go red for the reason they claim. The two that cannot are called out above —
`ABailedLevelStaysDirtyAndStaysOnTheDrainList`'s second half (M3: it says "accepted" and tests "dispatched")
and `AnImageBoundTextureCarriesTheImageBindableHintForever` (M4: it tests the order in which the bug does
not occur). `MoreThanKMaxDirtyRectsCollapsesToTheBoxWithRegionCountZero` reads the storage's own answer as
the oracle before the drain clears it, which is the right shape.
- **`ArmForTest` gating.** Both scopes arm `MG_Config::Features.PipePush` explicitly and restore it, and both
call `ResetForTest()` on entry *and* exit, so no case leaks an armed emitter into the next. The report's
finding 2 (`Features.PipePush` defaults to 0, so an unarmed case is green for the wrong reason) is real and
correctly handled. See §3.1 for why `ArmForTest` must not survive the flip.
- **`EmittedCallSuppliesTheWholeField`.** `PipeFill.cpp` untouched, all six P4a rows in the `false` arm.
`GetFramebufferBindingSlot` = **NO** is right and the reason is exactly P3a's `GetBoundVertexArray`
precedent: the field's storage is a frontend heap reference and the call carries handles. The consequence B
draws — this package retires no pull at all, so the 79-case verify retrace reports zero divergences rather
than "no divergence we looked for" — is honest and worth keeping in the record.
- **File list vs C.7.** 13 files: `MG_Impl/Pipe/{Framebuffer,Texture}Emit.h` (B's), `MG_State/GLState/`
`{FramebufferState,TextureState,RenderbufferState}/**` (B's), `MG_Test/Pipe/{Framebuffer,Texture}EmitTest.cpp`
(B's `b3` half), and the one granted `MG_Test/State/ObjectLifetimeIdTest.cpp`. **Nothing outside.** The two
GLImpl grants were declined — correctly for `GL_Framebuffer.cpp`, **incorrectly for `GL_Texture.cpp`**
(M2 needs it).
- **The LFS trap** (§8's retrace note) is already ID-13's ruling; every reviewer worktree runs
`git lfs checkout` first. I ran no retrace.
---
## 5. What the integrator must re-run on the integrated tree
B's §9 order is right as far as it goes. Add to it:
1. **Before anything**: confirm wire's C1 fix (scoped `PendingUploads` clear) is in the tree. The texture flip
without it is the mipmap-chain data loss in §2. This is a **gate**, not a preference.
2. `ctest -L unit` in **build-verify**, alone and first. Named expected-failing-before set, re-stated
unchanged from B's §9: `TextureEmit`'s four drain cases
(`TheUnionBoxAndTheRegionListDescribeTheSameTexels`, `AScatteredUploadCarriesTheLevelShadowsStridesAndNotZero`,
`AWholeLevelUploadCarriesZeroStrides`, `MoreThanKMaxDirtyRectsCollapsesToTheBoxWithRegionCountZero`) plus
`TextureTest.GetTexImageReadsALevelWhoseLowerLevelsWereNeverDefined` — five, and they must be **green after**
the flip on a tree carrying `w1`. Any of them still red means `w1` did not do what its report says.
3. `ctest -L integration-gpu` on build-push at the **default** mask and at **`0x1ff`**. Also add a third arm:
the D-K2 dependency refusals must fire — `0x9ff`-shaped (framebuffer without textures) and `0x5ff`-shaped
(textures without samplers, ID-15's H1) must be **refused with one `MGLOG_E`**, not half-run. That is
package F's scenario, but the integrated tree is the first place it is answerable.
4. `ctest -L integration-verify` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`, for
`~TextureObjectBase` and `~RenderbufferObject` reaching a live applier — **on both lanes**, DirectVulkan
included (ID-8's per-kind leak test).
5. The 79-case verify retrace (`git lfs checkout` first). It is the only thing that drives the drain list on
real atlas traffic, and after M1 is fixed it is the only place the region tail is exercised at volume.
Compare `PipeStats::ClientTextureUploadEmissions` against the server-side
`TextureUpload{Emissions,Box,Rect,Jobs}` — a rect count of zero on `rei`/`xaero-*` after M1's fix means the
tail is still not arriving.
6. **G1** after the flip, because it moves a `constexpr` in a push-only header.
7. `check_include_closure.py --mode both --compiler clang++ --self-test --require-all` after §3.4 adds
`SamplerEmit.h` to `TextureEmit.h`'s closure.
8. **The residual-record sweep** ID-12 names: the 183 "no applier record" refusals on the default arm must go
to **zero** once B and C have landed. A residual one on a texture or renderbuffer handle is a B seam defect.
9. **New, and it is the check M4 exists for**: a scenario (or a unit case) that allocates immutable storage
**and then** binds the texture as an image / attaches it, and asserts the applier's record carries
`ImageBindableHint = 1` and the right `BindMask`. Without it M4's fix is unverified.
---
*Reviewer note.* Everything above is from reading `p4a/clientfb`, `p4a/wire`, `feat/disaggregated` and the
frontend at `08192d72`. No build, no device, no worktree created; nothing on the shared box was modified.