[Docs] (.claude/skills, .github/workflows, CMakeLists.txt, docs/archive, docs/Disaggregated, docs/MobileVA, docs/Performance, MG_Backend, MG_Backend/DirectGLES, MG_Backend/DirectVulkan, MG_Backend/Record, MG_Gbm, MG_Impl, MG_Impl/EGLImpl, MG_Impl/GLImpl, MG_Impl/GLXImpl, MG_Impl/Pipe, MG_IntegrationTest, MG_IntegrationTest/Harness, MG_IntegrationTest/Scenarios, MG_Pipe, MG_Pipe/generated, MG_Remote, MG_Remote/Client, MG_Remote/Server, MG_Remote/Transport, MG_Remote/Wire, MG_State/GLState, MG_Test/Pipe, MG_Test/Util, MG_Test/Wire, MobileGL, scripts, scripts/data, tools/device_bench, userguide): archive the planning notes and agent contracts under docs/archive

- DEBTS.md and OPEN-QUESTIONS.md stay maintained, now in docs/Disaggregated.
This commit is contained in:
2026-10-15 20:01:45 -04:00
parent 0e3e2b7761
commit aabca3c171
1035 changed files with 410 additions and 398 deletions
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,806 @@
# P4a integrator decisions (feat/disaggregated, 2026-09-08)
## ID-1 Base ref `37da3c3a` (= P3a docs commit; code fde5fda3), baselines captured there
`BRIEF-P4A.md` was verified at 37da3c3a. `~/w7/p4a-before-*` (pull lib, ctest names, RenderStateImpl sha,
dirty-surface) are the pull build of 37da3c3a; P4a's admitted-resize set is EMPTY (G1 0/0/0/0 after every merge).
P3a's eleven G5 functions stay byte-identical (`scripts/p3a_untouched_regions.sh 37da3c3a HEAD`); P4a names its
own byte-identical set per the brief's D-N (package F adds the script).
## ID-2 Order: contract -> wire -> clientfb -> clientsp -> esprytobj -> esprytdraw -> gates
Every package branches from the tag `p4a/contract`; branch refs are spelled `refs/heads/...` (the tag makes the
short name ambiguous). Each Espryt package gets a real-path verification round on the integrated tree after the
client packages land (P3a found three seam defects that way), then a focused re-review; a final whole-diff
review closes the phase. wire is behaviour-neutral (nothing consumes its records until Espryt lands).
## ID-3 Tools (all phase-parameterised, in ~/w7/notes/tools)
`wsl_tree.sh p4a <slug> <base> [verify]`, `wsl_integrate.sh p4a <slug>...`, `wsl_capture_baseline.sh p4a`,
`wsl_p3a_gate.sh` -> `wsl_p4a_gate.sh` (integrator writes it per the brief's D.3 delta), `wsl_build_trace_apks.sh
p4a` (Release + debug-signed; prints the lib size - Release .text ~9.4 MB, ID-17 of P3a), `p3a_ab.sh` ->
`p4a_ab.sh` with the previous mask 0x1fff-vs-0x1ff arms via `p3a_ab_7f.sh`'s shape, `ab_reduce3.py`,
`wsl_p3a_bench.sh` -> `wsl_p4a_bench.sh` (T2 = 0x1ff arm). Package agents never touch ~/w7/pipe.
## ID-4 Models and rounds
Package agents and reviewers run on opus (user rule 2026-09-08). One adversarial review per package, at most
two rework rounds; declared minors do not block integration.
## ID-5 Durable locations
Brief `~/w7/notes/p4a/BRIEF-P4A.md`; scouts `~/w7/notes/p4a/scout-*.md`; results and reviews
`~/w7/notes/p4a/p4a-results/<package>-v<N>.md` / `<package>-review-v<N>.md`; A/B `~/w7/notes/p4a/ab*`; bench
`~/w7/notes/p4a/bench`. Package logs `~/w7/p4a-<slug>-*.log` are deleted by their owner when the round ends.
## ID-6 Performance is recorded, not gated (user, 2026-09-08)
Against MEASUREMENTS.md §20's Release baseline (pull / 0x7f / 0x1ff); P4a adds the 0x1fff arm. Correctness
gates stay hard. Device A/B on Release APKs only; the create-indirect and rd12/Magma/Adreno fixtures stay out.
## ID-7 Working over UNC and WSL
Edit worktrees through `//wsl.localhost/Arch/home/swung/w7/p4a-<slug>/...` (files yes, mkdir no). Commands
through a script file `<scratchpad>/wsl/<name>.sh` (LF) run as `MSYS_NO_PATHCONV=1 wsl.exe -d Arch -- bash
/mnt/c/<scratchpad>/wsl/<name>.sh`; never pass ~ or $vars inline; foreground under 8 minutes, longer via
`setsid nohup ... &` + log polling; never delete the shared `wsl` scratchpad directory, only your own files.
## ID-8 Rulings carried from P3a that bind every P4a package
- Exit-order rule (P3a ID-18/21): no frontend destructor may run from an exit handler into pipe/backend state.
Every new static holder of frontend SharedPtrs is leak-at-exit storage; every new singleton reachable from a
destructor is never-destroyed. Prove with `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` on both lanes.
- Backend-neutral death paths from day one (P3a final-review C-1): the client emits delete/destroy and frees the
slot from the frontend destructor for EVERY kind it mints; a backend death notice is a redundant second path
and must be idempotent. A leak test per new kind, run on the DirectVulkan lane too.
- Stale-generation refusal in every GetOrCreate(handle) (P3a contract-review M2).
- The ownership table lists generated/.def interfaces; a package that retires a .def row must not leave another
referencing the enumerator (P2's bb2a236d trap) - the contract owns the enum-coupled PipeFill.cpp block.
- Files C.7 gives to nobody are granted explicitly by the integrator when a package needs them (GLImpl entry
points, MG_Test fixtures such as BufferTest's ScopedBackendOps that must scope BOTH op tables).
- ColorOS install dialog = topResumedActivity InstallGuideActivity (not mCurrentFocus); tapping mid-install drops
adb for seconds; the Xiaomi needs cpuss-0-0 < 42 C before pinning; a crash resets the GPU pwrlevel range.
## ID-9 Contract integrated: feat/disaggregated = `08192d72` (pushed) = the tag `p4a/contract`
Fast-forwarded (pipe was at 37da3c3a): pull symbols 0/0/0/0, unit 1635 x 3, G2 0, G14 0 removed / +13, P3a's
eleven byte-identical. contract-v1 deviations the packages must know: **D1** c0 CREATED the five emit headers
MG_Impl/Pipe/{Framebuffer,Texture,Sampler,Image,Program}Emit.h with a stub emitter and `kMGPipeWired*Subsystem
= 0` each - packages B (Framebuffer/Texture) and C (Sampler/Image/Program) own those headers' BODIES and never
touch PipeFill.cpp; the wired bit is added in the commit that gives the emitter its body. **D13** the ShaderCso
composite band has its own dense table in the allocator and the applier (band base 983040; a slot-indexed
vector would cost ~236 MB per composite). **D5** six death helpers, one per kind (the texture helper releases
the sampler view, not the built-in sampler CSO, which has its own lifetime). **D2** MGPipeResourceTarget has a
13th enumerator TexRect. **D6** two UNDECIDED dirty-surface rows (UseProgram/NEW_SHADER, BindVertexArray/
NEW_VERTEX_ELEMENTS) are marked with the tool's reason, not silenced. **D7** BindProgramPipelineObject is
kPulledEveryVerb. **D16** clang++-20 does not exist on the box; the gate spells `clang++`. Contract review v1
in flight; the six sibling trees were reset to the tag and are rebuilding (~/w7/p4a-trees2.log).
## ID-10 Contract review v1 = ACCEPT WITH MAJORS; c0b in flight on p4a/contract, M2 goes to wire
Six majors: M1 the birth half of the MG_State coupling is missing (PipeMutation.h declares only the six death
helpers; the death helpers hard-code published=false) so B/C cannot emit create/respecify/params without
touching A's files; M2 MGPipeApplyResourceSubData has no MGPSubRegion tail (D-D3/D-D5 unreachable); M3 wants()
ignores kMGPipeWiredSubsystems so P4a's emitters are live under 0x1fff before their bodies exist; M4 the
sampler-view death helper skips the death notice; M5 HighWater(ShaderCso) returns the band top (leak test
vacuous); M6 check_include_closure.py exits 0 without a compiler. Disposition: M1/M3/M4/M5/M6 = commit(s) c0b on
p4a/contract by a fix agent touching ONLY PipeMutation.h, PipeFill.{h,cpp}, SlotAllocator.*, the closure script
and an A-owned test (no overlap with the six in-flight packages); M2 = wire's rework (it owns PipeApply after
the tag). The tag stays at c0; B..F rebase onto pipe (c0 + c0b) at their rework/verification round; B/C v1 will
show M1-driven deviations that the rework reconciles against contract-v2.md's exact birth-hook declarations.
## ID-11 c0b integrated: feat/disaggregated = `2cb44039` (pushed); wire v1 landed on p4a/wire
c0b (32033d69 + 2cb44039): PipeMutation.h now declares the birth half (4 mints, 9 emissions, a 3-call
publication latch read by both halves; `if constexpr` seams keyed on each family's wired constant forward to
the entry points B/C must provide - contract-v2.md lists them exactly); wants() consults kMGPipeWiredSubsystems;
the sampler-view helper raises the notice; composites are counted apart (CompositeHighWater/LiveCount/FreeCount);
check_include_closure.py validates --compiler in every mode (test.yml:774's clang++-20 is fine in CI, where
clang-20 is installed; the local gate spells clang++). On pipe: G1 0/0/0/0, unit 1636 x 3, G2 0, G14 0/+14.
wire v1 (86835b50 / bc9abfbd / 0f990633 / 3c07c8c3): W1 closes M2 with a defaulted trailing `const MGPSubRegion*`
tail; W3 fixed a real destroy-dispatch defect; hazard H1 (BuiltinSampler == null is Fatal but D-K2 allows bit 10
without bit 11) awaits the wire review's assignment (contract dependency rule vs client minting). Every package
rework/verification round rebases onto refs/heads/feat/disaggregated (c0 + c0b).
## ID-12 esprytobj v1 landed (`9bb95335`, six commits on p4a/esprytobj); four contract seams ruled, c0c in flight
- **DV-3 (`MGPSubData::Target`)**: the brief's D-D3 names BOTH halves (resource target + cube-face upload target).
clientfb v1 packs `low byte = MGPipeResourceTarget, high byte = TextureUploadTarget`; wire's `SubDataNamesABuffer`
keys on the whole field `== 0`; `TextureUploadTarget::Texture1D` is 0, so the bare enumerator Espryt v1 matches on
would collide with Buffer. RULING: the packed form is the contract encoding. c0c moves `MGPipePackSubDataTarget` /
`MGPipeSubDataResourceTargetOf` / `MGPipeSubDataUploadTargetOf` into MGPipeTypes.h (Uint32 arguments, backend-
neutral); B's rework deletes its copies; D's rework decodes the HIGH BYTE at every `PendingUploads` match
(`FindPipeTextureUpload` and the consume site); wire is unchanged (it matches the field verbatim).
- **DV-2 (`DepthStencilMode`)**: 0 = GL_DEPTH_COMPONENT, 1 = GL_STENCIL_INDEX; both sides already agree. c0c mints
`kMGPipeDepthStencilModeDepth/Stencil` in MGPipeTypes.h; B's rework drops its copies (the GLenum->byte helper is B's).
- **DV-4 (`MGPSurface::Kind`)**: the numeric `MGPipeKind::{None,Texture,Renderbuffer}` values (what B emits). c0c mints
`kMGPipeSurfaceKindNone/Texture/Renderbuffer`; B's rework drops its copies.
- **DV-5 (`MGPSurface::Pad0`)** -> `Uint16 TextureTarget` = `static_cast<Uint16>(MobileGL::TextureTarget)`, 0xFFFF
(= Unknown) on every non-texture point, consulted only when `Kind == Texture`; listed in `MGP_FIELDS_MGPSurface`;
size stays 24. B's rework fills it; D's rework moves the four cross-object masks onto it; E's `SyncAttachmentObject`
reads it.
- DV-1/DV-7/DV-8 accepted as C.7 boundary notes (E owns the resolution sites); DV-6 harmless as argued; DV-9 macros
accepted as G1-forced (the review checks `#undef` hygiene and pull-text identity); DV-10/11/12 fine. The 183 named
"no applier record" refusals on the default arm are the expected pre-client shape and must go to ZERO on the
integrated tree (a residual one is a seam defect, P3a's lesson).
- c0c = one commit on p4a/contract by a fix agent touching only MGPipeTypes.h + PipeFields.def (+ an A-owned unit
test); integrated (fast-forward) BEFORE wire; every package rework rebases onto it.
## ID-13 clientsp v1 landed (`ecd5b2e7`, four commits on p4a/clientsp); the LFS fixture trap
- Every lane green on its tree (G1 0/0/0/0, unit x3, integration-gpu 966/966 on three arms, verify 844/844 zero
Fatal under tcache_count=0, retrace 79/79, +38 test names). Its findings F2 (wants() ignores the wired constants)
and F3 (death helpers hard-code published=false) are contract-review M3/M1, CLOSED by c0b (contract-v2.md): the
rework rebases onto pipe and reconciles against the exact birth-hook declarations, nothing more. F1 (member-wise
assignment of SamplerParameters leaves padding unspecified; the cache rejected its own entries, hit rate zero,
suite-order dependent) is a real bug the design predicted; the fix is memset+memcpy and is pinned - the review
verifies it. **LFS trap**: the 12:24 WSL restart left tools/trace_replay/fixtures/*.tgz as LFS POINTERS (132 bytes)
in the wire / esprytobj / esprytdraw / gates trees (clientfb and contract were fine); a retrace on such a tree reads
2/79. I ran `git lfs checkout` in wire/esprytobj/gates (pointers 0 afterwards; esprytdraw and pipe were already
clean). Every private worktree a reviewer creates must run `git lfs checkout` before any retrace.
## ID-14 The built-in sampler seam between B and C is ruled: B acquires it through C's cache
clientfb v1 (TextureEmit.h ~636) mints `MGPipeSlots().Acquire(MGPipeKind::SamplerCso, sampler->GetLifetimeId())`
per sampler OBJECT; clientsp content-addresses sampler CSOs (D-F1, `MGPipeSamplerCsoCache::Acquire(params,
payloadBytes)`, SamplerEmit.h ~186 names this as B's seam) and c0b's hook comment says the handle rule for this kind
is THE EMITTER'S. B's handle would never receive a create_sampler_state record, so on the integrated tree every
texture's params would be refused (or, with a null, Fatal{ProtocolCorruption}) - the seam C called the highest
post-rebase risk. RULING: B's rework obtains `MGPTextureParams::BuiltinSampler` from C's cache seam (the exact call
is named by the two reviews; TextureEmit.h may include SamplerEmit.h - the include-closure gate must be re-run) and
re-emits set_texture_params whenever the built-in sampler's parameters change (the content-addressed handle changes
with content; D-E2's SamplerResync covers the re-sync). B keeps NO per-texture death path for the sampler CSO: LRU
eviction in C's cache is the only delete_sampler_state emitter (contract D5/M4 unchanged). Hazard H1 (wire): the
Fatal on a null BuiltinSampler stays; the D-K2 "bit 10 without bit 11" arm must therefore be refused at the CONTRACT
dependency rule (texture bit implies sampler bit), which is package F's 0x9ff-style dependency-refusal scenario.
## ID-15 wire review v1 = REWORK (C1 + five minors); H1 becomes a fourth D-K2 dependency row; esprytdraw v1 landed
- wire C1 (PipeApply.cpp:1485): resource_respecify clears the WHOLE PendingUploads vector, but AllocateStorage /
MarkStorageDirty are per (uploadTarget, level), so defining level 1 (or glGenerateMipmap) after level 0's accepted
upload was kept by Espryt's incomplete-texture bail loses level 0's texels silently. Fix as specified: scope the
clear to the redefined level via a trailing defaulted pointer (null = whole resource), one case + one mutation.
Minors m1-m5 (ReleaseObjectRecords leaves framebuffer records + three unit windows populated - contract-review m2
assigned to wire; the PipeApply.h:422-428 framebuffer-refusal promise; the Renderbuffer enumerator accepted as an
upload target; no acceptance signal to the emitter; unmap_persistent's inert kind check) are fixed or declared in
the same rework. W1-W6/W8 accepted; W7 rejected (= C1). Rework rebases onto refs/heads/feat/disaggregated.
- H1 ruling (refines ID-14): the brief's D-K2 says "bit 10 without 11 is fine"; that sentence is WRONG for P4a as
built - MGPTextureParams::BuiltinSampler is a SamplerCso handle, only bit 11 mints sampler CSOs (c0b's four
unconditional mints deliberately exclude it), and a null there is Fatal. D-K2 gains a FOURTH row: **bit 10 requires
bit 11**. Sites: PipeFill.cpp:1062-1069's precedent (contract, folded into c0c), Managers.cpp:2393-2410's mirror in
the texture family's Resolve*SubsystemArm (package D's rework), and package F's dependency-refusal scenario gains
the 0x5ff-shaped arm. Client-side minting of the built-in sampler is REJECTED (it would run the content-addressed
cache in the arm meant to exclude it and crosses the B/C boundary).
- esprytdraw v1 (98bdfa3e..0b00f7f0, five commits, DirectGLES.cpp only): every arm green on its tree because its
handle arms DECLINE TO THE PRE-HANDLE ARM when the applier holds no record (a serial is never an "emitted" test -
MGPipeApplierReset advances every P4a serial unconditionally). On the integrated tree that shape is the silent
fallback P3a's lesson forbids: a missing record must be a LOUD refusal (MGLOG_E_ONCE + decline to draw nothing /
Fatal per family), never a quiet legacy read. The review judges every decline site; E's verification round flips
them once B/C records exist. Its closing of D-E3's READ-attachment gap from SyncNeccessaryTextures may make G9's
red-before obtainable (R1 of the gates review) - the E review says whether.
- ID-15 correction on WHERE the fourth D-K2 row lives: the precedent is SERVER-side (Managers.cpp ~2426, Espryt's
ResolveVertexInputSubsystemArm refuses bit 8 without bit 7 and runs the legacy arm; PipeFill.cpp ~1585 only
documents that the client's calls then land in RefusedResourceCalls). So "bit 10 requires bit 11" is implemented
in package D's texture-family Resolve*SubsystemArm (its rework), pinned by package F's dependency-refusal scenario
(a 0x5ff-shaped arm), and recorded in the brief/docs D-K2 table. c0c's scope is unchanged (no contract code).
## ID-16 gates review v1 = ACCEPT WITH MAJORS (six, all local); gates rework v2 launched
F-M1/M2/M3 G7 (`scripts/p4a_descriptor_negative_control.sh`): the borderColorForm patch writes 0 into a scoped enum
(never compiles), the patcher's print pollutes the captured verdict, PATCHED_HEADER is set inside a command
substitution so repair() on EXIT/INT/TERM is a no-op (a SIGINT leaves the patch in the tree) - all hidden because the
script exits at step 0 today. F-M4 the composite leak case reads HighWater(ShaderCso) which c0b redefined; use
`PeekPipeCompositeSlotHighWater` (contract-v2 §4.3/§7.6). F-M5 (R2) the ABA-flip probe needs both regexes in ONE
file - make it directory-wide so the flip cannot be forgotten. F-M6 the 0x9ff refusal matches lowercase "sampler"
anywhere in the log - match the exact refusal line. R1 partial: the TextureParamsWithoutASamplerView net catches
emitted-but-not-applied, not deferred-to-first-view; package D's verification-round probe must cover the second.
G5 (`p4a_untouched_regions.sh`) survived four attacks incl. a tail-perturbation probe - accepted as is. Rework v2
also: rebase onto refs/heads/feat/disaggregated, add the ID-15 0x5ff-shaped arm (bit 10 without bit 11 must be
refused by Espryt once D's rework lands - the scenario is written now, expected to SKIP-visibly until then), keep
R3 (four commits fine).
## ID-17 c0c integrated (pipe = `17db7598`, post-merge checks running); clientsp review v1 = REWORK; c0d for Tracker.h
- clientsp C-M1 (CompositeResolver.h:138/104): Reset() clears Live and the reuse branch returns before restoring
it, so after any make-current ReleaseEntry early-returns forever - fix + a test that drives release THROUGH the
resolver after a Reset. C-M2 (ProgramEmit.h:168 vs :200): the (Cso, Version) latch for the default uniform block is
never invalidated when a re-issued create_shader_state clears the applier's block (wire W6) - a failed relink of a
bound program leaves a zeroed block; invalidate the latch on every re-issue. C-M3 (SamplerEmit.h:299): LRU eviction
invalidates sampler CSO handles that texture params records still name, and nothing re-emits. RULING: the cache
keeps a REFERENCE COUNT per entry (B's Acquire for a texture's built-in sampler takes a ref; texture death or a
parameter change that re-acquires releases it; bound sampler states hold one while bound); LRU evicts only
unreferenced entries; when every entry is pinned the cache mints beyond 256 and counts it (OverCapacityMints, a
recorded number, not a gate). B's rework uses Acquire/Release exactly as C's v2 report spells them.
- Two cross-package under-fires the review found in A's Tracker.h: (1) glBindSampler bumps TextureBindGeneration
(bit 12) not SamplingResolutionGeneration (bit 13), so bind_sampler_states never fires for a sampler bind; (2) bits
6/7/8 read GetCurrentProgram(), null under SSO, so a re-composited pipeline never gets a ShaderCso handle. Both are
contract defects -> c0d on p4a/contract (Tracker.h + an A-owned unit test), integrated before wire v2.
- Ten minors + 15 deviations judged in the review; the c0b reconciliation list (3 missing entry points, 4 latch
calls, 2 stale comments) is part of the rework. clientsp rework rebases onto pipe (17db7598 + c0d when it lands).
## ID-18 clientfb review v1 = REWORK (four majors, nine minors); two of them are wire-side rules; B's rework waits for wire v2
- M1 (TextureEmit.h:939): m_regions is built and counted but never passed - wire W1's defaulted `const MGPSubRegion*`
tail must receive it; every scattered upload otherwise declares N regions and supplies none. Fix + a unit case
that asserts the applier's stored region list equals the emitted one.
- M2: SamplerObject::BumpVersion (the 13th MGP_NOTE_AGGREGATE(TextureParams) site) has no hook, so MinLod/MaxLod/
LodBias go stale on glTexParameterf; it is ALSO the re-emit hook ID-14/ID-17 need when the built-in sampler's
content changes (re-Acquire from C's cache, Release the old handle, re-emit set_texture_params). The GL_Texture.cpp
grant exists for this - B takes it.
- M3: the client clears its dirty flag on DISPATCH, not on ACCEPTANCE (D-D5 step 1), even when the if-constexpr
discarded the call. RULING: the applier returns acceptance. wire v2 was asked to implement m4 "if small, else
declare"; if v2 declares, a wire v3 adds `Bool` acceptance returns to MGPipeApplyResourceSubData / Respecify /
Create (default-tail-compatible; the wire path is untouched because gen_pipe never parses PipeApply.h - wire
review W1). B clears a level's flags only when the call returned accepted.
- M4: the sticky BindMask/ImageBindableHint reach the applier only on a LATER respecify, which an immutable texture
never has. RULING: a mask change after allocation emits a resource_respecify whose storage-defining fields equal
the stored descriptor; the applier treats such a record as a METADATA UPDATE - no reallocation ack, no
PendingUploads clear (this refines C1's level-scoped rule: identical storage fields clear nothing) - and Espryt's
twin re-derives the storage flags from the new mask on its next sync (recreate only where the backend needs it).
Wire side = the same v3 (or v2 if the agent read this in time); Espryt side = D's verification round.
- Nine minors: cube face resolved to targets[0], draw-buffer tokens >= 8 escape D-C3's refusal (must refuse), a
dangling Entry&, unpublished entries never retired so a recycled slot inherits the mask (must retire) - fix all
four; declare the rest with reasons. D4's blocked flip verified: kMGPipeWiredTextureSubsystem flips to 1 in the
rework (one line) with the named expected-failing set re-run. The rework rebases onto pipe AFTER wire v2 is
integrated (it builds against the applier's tail and acceptance returns); c0c's helper deletions + TextureTarget
fill and ID-14/ID-17's Acquire/Release calls (clientsp-v2.md spells the API) are in the same round.
## ID-19 esprytobj review v1 = REWORK (1 critical, 4 majors); esprytdraw review v1 = REWORK (3 majors + 1 for D); the framebuffer record becomes PER OBJECT
- CRITICAL (esprytobj, Managers.cpp:8216/8450): the applier holds only the two BOUND-target records (wire
DrawFramebuffer/ReadFramebuffer) and B emits only for bound slots, so on the handle arm every DSA entry point
(BlitNamedFramebuffer, the four ClearNamedFramebuffer*) blits or clears into a driver FBO that never got its
attachments; SyncToBackend binds and returns on a mismatch. RULING (design, the phase's main correction):
the framebuffer record is keyed by the FRAMEBUFFER HANDLE. (a) c0e (contract, after c0d in the same tree):
`MGPipeFramebufferTarget::Named = 3` = "this record describes the framebuffer it names; no binding changes",
comment on MGPFramebufferState stating the per-object table and that Draw/Read/Both records ALSO set the bound
handle(s); D-K2 fourth row and G9-as-white-box recorded in the brief/docs there too. (b) wire v3:
`MGPipeApplier().FramebufferRecords` slot-indexed by the handle's slot (gen checked on lookup - stale gen refuses;
framebuffers have no wire lifetime, D-I2, so a slot is simply overwritten by its successor's record),
`MGPipeApplier().BoundFramebuffer[Draw|Read]` = handles; set_framebuffer_state Draw/Read/Both writes the record at
Fbo's slot and the bound handle(s); Named writes the record only; the FramebufferSerial advances on every write;
ReleaseObjectRecords clears the table and the bound handles (wire m1). `DrawFramebuffer`/`ReadFramebuffer` become
accessors resolving through the bound handle so E's SyncCurrentFBOByRecord keeps its shape. (c) B v2: emit a
Named record at every DSA entry point that hands a framebuffer to Espryt by name (Blit/ClearNamed*, and the
DSA attachment/drawbuffer/readbuffer setters at their validate point) - "any framebuffer Espryt is about to
receive by name has a record". (d) D v2: PushedFramebufferRecord(target, fbo) -> FramebufferRecordFor(handle);
the bound-target question is answered by BoundFramebuffer[t] == handle.
- esprytobj majors: M-1 the server's own re-dirty (RequireImageBindableStorage, :5127) is invisible to the pending
set -> the twin re-arms the record's PendingUploads itself (server-side state); M-2 pushedStorage->Desc has zero
readers - d2 must allocate storage FROM the descriptor (that is the step's purpose); M-3 SyncAttachmentObject
(:7947) is D's file -> D does the attachment resolution incl. the TextureTarget masks (ID-12 DV-5); M-4 the two
registry methods and AdoptTwinByHandle with no caller are removed or wired. Ten minors fixed or declared. DV-9's
wording corrected (38 non-semantic preprocessed-line differences: __LINE__, parens, reflow - accepted).
- esprytdraw majors (E v2, launched now, rebased onto pipe): (1) SyncImageTextureBindings:2527 narrows the DRIVER
sweep to the record's window and returns, so a unit outside it keeps a deleted texture name - sweep the full
driver range; (2) BindCurrentUnitSamplers:4361 `continue`s outside the window instead of unbinding - restore the
`else UnbindSampler`; (3) the image (:2369) and program (:3699) seam checks are silent - log the same line the
framebuffer one logs; (4->D) InvalidateFramebufferHandleArmMemos belongs inside InvalidateFramebufferBindingCache.
Decline sites: 27 classified; the two SILENT ones (SyncCurrentFBOByRecord:2709 half-described applier;
ResolveGlobalConstantsRecord:3701 short block image falling back to MapUBO = protocol corruption) become loud
NOW; the rest flip per the review's table at E's verification round on the integrated tree.
- G9: not obtainable through public GL (readback emulation sets DEPTH_STENCIL_TEXTURE_MODE itself; IsDrawSyncClean
pushes params on first sample) -> F's G9 becomes a WHITE-BOX assertion (gates v3 / F's verification round).
- Order now: c0d -> c0e -> wire v3 (v2 + table + acceptance returns + metadata respecify) -> B v2 -> C v2 (running)
-> D v2 (needs wire v3's table to build) -> E verification -> D verification -> F v3.
## ID-20 c0c integrated and pushed: feat/disaggregated = `17db7598` (origin)
Post-merge on pipe: G1 0/0/0/0, unit 1638 x 2 (pull/push), P3a's eleven byte-identical, names pull == push 2604,
0 removed / +16 vs baseline. Tool note: the post-merge name comparison needs LC_ALL=C on both sides (the baseline
was sorted under a different locale; the unfixed comm reported 236/252 - a false alarm). Detached WSL jobs must be
launched `setsid nohup bash <script> < /dev/null > log 2>&1 & disown` and verified with pgrep - with only stdout
redirected the job died before writing a line.
## ID-21 wire v2 landed (`6f263284`, five commits, rebased on 2cb44039); wire v3 + c0e launched in parallel
wire v2: C1 fixed as specified (trailing defaulted `const MGPRespecifiedLevel*`, null = whole resource); m4 done -
`MGPipeApplyResourceSubData` returns Bool; m1/m2/m3/m5 fixed; unit 1673 x 3, applier suites 125/125, names +51,
five mutations each red on its own case. m3's packed-Target decode is LOCAL (c0c had not landed) - retired at the
rebase onto 17db7598. wire v3 (same agent lineage, new round): rebase onto 17db7598; ID-19(b) the per-object
`FramebufferRecords` table + `BoundFramebuffer[Draw|Read]` + `DrawFramebuffer()/ReadFramebuffer()` accessors;
ID-18 M3 acceptance Bool on Respecify and Create too; ID-18 M4 metadata respecify (storage-defining fields equal
the stored descriptor -> no ack, no PendingUploads clear, masks updated). `Named` = 3 comes from c0e; until it
lands wire v3 accepts 3 through a declared local constant that wire's verification round retires. The wire v2
re-review is FOLDED into the v3 review (one review over v2+v3). c0e runs in its own worktree `~/w7/p4a-c0e`
(branch p4a/c0e from 17db7598) in parallel with c0d (Tracker.h, disjoint files); integration order c0d -> c0e
(rebased) -> wire v3.
## ID-22 c0d integrated: pipe = `9ea44389` (post-merge running, push follows); brief amendments recorded
c0d (Tracker.h + TrackerTest.cpp): bit 13's shutter now also reads TextureBindGeneration (a texture bind changes
the sampler-state set through the built-in sampler; the shutter, not the wants() gate, because the dirty-surface
table is derived from the shutter); an `else if (pipeline)` arm drives bits 6/7/8/14 from the pipeline name + per-
stage {lifetimeId, linkVersion} + the four mirror counters (fields read directly - the two helpers made the bits
UNRESOLVED and broke self-test control 6b). Both UNDECIDED rows stay marked. Gates: symbols 0/0/0/0, unit 1642 x 3,
names +20, dirty-surface self-test 27 controls, integration-gpu DirectGLES 491 identical before/after.
Brief amendments (appended to BRIEF-P4A.md as section F): D-K2 fourth row "bit 10 requires bit 11" (server-side,
D's resolver; F's 0x5ff arm); G9 is a WHITE-BOX assertion (public GL cannot observe the gap: the readback emulation
sets DEPTH_STENCIL_TEXTURE_MODE itself and IsDrawSyncClean pushes params on first sample); D-C2's "per bound target"
becomes "per framebuffer object + two bound handles, Named = 3" (ID-19); D-D5's "clear on dispatch" reads "clear on
ACCEPTANCE" (ID-18 M3); a mask-only respecify is a metadata update (ID-18 M4).
- ID-22 addendum: c0d post-merge on pipe G1 0/0/0/0, unit 1642 x 2, G5 rc 0, names 2608 == 2608, 0 removed / +20;
pushed: origin feat/disaggregated = `9ea44389`.
## ID-23 esprytdraw v2 landed (`9b8441a6`, five rework commits, rebased on 17db7598)
MAJOR-1 sweep = [0, min(max(Start+Count, g_imageUnitHighWaterMark), unitCount)); MAJOR-2 UnbindSampler outside the
window; MAJOR-3 all three seams share the stem "does not describe the binding it names" (the image seam latches
to the validate point so the eager glBindImageTexture funnel does not spam - DEV-14, ACCEPTED); the two silent
sites: F2 loud when exactly one target is recorded, P7 Fatal{ProtocolCorruption} on poison/verify and loud-once
elsewhere (DEV-15, ACCEPTED - no unconditional abort on a shipped draw path); D-K2's fourth row is in E's arm
too (D's resolver stays the owner); a v1 pGLContext token in a comment fixed (G13 = 1 file). Gates: G1 0/0/0/0,
unit 1638 x 2, integration-gpu 491/491 on three arms, family 497/497 x 3, LEGACY_MEMOS=OFF build rc 0. The focused
re-review of v2 is FOLDED into E's verification-round review on the integrated tree (after B v2 / C v2 / D v2).
## ID-24 wire v3 landed (`70e742a3`); wire v2+v3 review, B v2 and D v2 launched on a TEMPORARY merged base
wire v3: FramebufferRecords (slot-indexed, gen-checked, StaleFramebufferRecordLookups), BoundFramebuffer[Draw|Read],
FramebufferRecordFor(handle) / DrawFramebuffer() / ReadFramebuffer() accessors, kMGPipeFramebufferTargetNamed = 3
local (retired by a static_assert when c0e lands), Bool on Create/Respecify, metadata respecify (W10: buffers
excluded, wider field set; W11 the level-pointer clause) - unit 1680 x 3, applier 130/130, names +58, nine
mutations red. Because B v2 and D v2 must build against wire's applier before wire is integrated, both were launched
on `refs/heads/feat/disaggregated` (9ea44389) + `git merge refs/heads/p4a/wire` (+ p4a/c0e when it exists) as a
TEMPORARY base; the integrator's rebase onto the pipe that contains wire/c0e drops those merge commits (identical
patch-ids are skipped). D v2 does NOT merge B/C (its verification round follows their integration). Integration
order stays c0e -> wire (with the Named-constant retirement edit done by the integrator in the wire tree after its
rebase, unit-tested, one commit) -> C v2 -> B v2 -> D v2 -> E verification -> D verification -> F v3.
## ID-25 c0e integrated: pipe = `e8502a61` (= 11446f35 rebased onto c0d; post-merge running, push follows)
c0e: `MGPipeFramebufferTarget::Named = 3` (Count 4), the per-object-table comment on the enum and MGPFramebufferState
(only Target is binding-specific; ReadSurface = that framebuffer's own read buffer under every Target), the
metadata-respecify note beside MGPipeResourceRespecifyNeedsAck naming the storage-defining set (metadata = BindMask,
ImageBindableHint, GlNameForDiag; HasDefinedContent is storage-defining). Sizes 304 / 88 unchanged; G1 0/0/0/0;
unit 1638 x 2 on its base. The contract is now c0..c0e; the brief's section F carries the docs half.
- ID-25 addendum: post-merge on pipe G1 0/0/0/0, unit 1642 x 2, G5 rc 0, names 2608 == 2608, 0 removed / +20;
pushed: origin feat/disaggregated = `e8502a61`.
## ID-26 clientsp v2 landed (`00a86d2a`, three rework commits on 17db7598); focused re-review launched
C-M1 Live/Fresh split in the composite resolver; C-M2 the constants-key latch invalidated on re-issue + a counted
refusal in the program emitter; C-M3 per ID-17 ref-counted cache. B-facing API (clientsp-v2.md): `#include
<MG_Impl/Pipe/SamplerEmit.h>`; `MGPipeSamplerCsoCacheInstance().Acquire(sampler->GetAllSamplerParameters(), bytes)`
(bytes is a Uint64& lvalue) -> handle + ref; `.Release(previous)` on re-acquire / texture death; B deletes its
`MGPipeSlots().Acquire(SamplerCso, ...)`. Gates on its base: G1 0/0/0/0, unit 1668 x 3, names +46, emit suites
34/34, integration-gpu 966/966, verify 844/844, retrace 79/79, four negative controls red. C does not contain c0d
(9ea44389) or c0e - the rebase at integration brings them; the re-review names the tests to re-run.
## ID-27 wire review v2 = ACCEPT WITH MAJORS (merge not blocked); wire integrating with the Named-constant retirement
Verified by the review: C1's three-arm clear (metadata -> whole-resource -> keyed erase, precedence right), the
per-object table + gen check ({0,1} admitted, {0,0} faults), acceptance Bools on every path with counters intact,
M4's field set == c0e's ruling, m1/m2/m3/m5 fixed, no bare packed decodes, no new static holders; three mutations
re-killed plus two of the reviewer's own. RULINGS: MAJOR-1 (stored State.Target is now the LAST emission's target,
Named included, so E's `record.Target == Both` skip at DirectGLES.cpp:2983 degrades to a redundant per-frame sync
after a DSA Named record) -> E's verification round replaces that test with `BoundFramebuffer[Draw] ==
BoundFramebuffer[Read]` (the applier's own fact). MINOR-1 (the UploadTarget half of the level-scoped erase key has
no gate - deleting it is green on all 74 tests) -> wire's verification round adds the cube-face case. The coarse
FramebufferSerial memo key (no per-record serial) is RECORDED for the optimisation list (perf, not gated).
Integration: p4a/wire rebased onto e8502a61 (head 8f1eaafa before the retirement commit), the local
kMGPipeFramebufferTargetNamed replaced by MGPipeFramebufferTarget::Named everywhere incl. PipeApply.cpp:2148/2153
(`>= Count` refusal) and the three test sites; the integrator's retirement commit is unit-tested and G1-checked
in the wire tree before the fast-forward.
## ID-28 wire integrated and pushed: feat/disaggregated = `712c9467` (origin)
Twelve wire commits rebased onto e8502a61 + the integrator's retirement commit 712c9467. Post-merge on pipe: G1
0/0/0/0, unit 1684 x 2, P3a's eleven byte-identical, names 2650 == 2650, 0 removed / +62 vs baseline. The applier
is now real on pipe: B v2 / D v2 (built on the temporary merged base) rebase onto this head at integration - wire's
rebased commits carry the same patch-ids so the temporary merges drop out; if a rebase reports conflicts in
PipeApply.* the integrator resolves toward pipe. Next: C v2 (after its re-review) -> B v2 -> D v2.
## ID-29 gates v2 landed (`ecf9cb45`, four rework commits on 2cb44039); focused re-review launched
All six majors proved on a scaffold: G7 exits 0 naming Layered and borderColorForm ({} not 0; verdict via a global);
SIGINT mid-rebuild -> repair ran, exit 130, tree clean; the composite leak case reads PeekPipeCompositeSlot
{HighWater,LiveCount,BandBase} and went red on all three live-allocator lanes when one composite leaked; the ABA
probe is directory-wide; the 0x9ff refusal matches one ERROR line naming both bits; the 0x5ff arm SKIPs by name.
Twelve minors fixed, F-m13 declared. Gates on its base: G1 0/0/0/0, unit 1636 x 3, names 2711 == 2711, +123,
p4a_untouched 17 rows + 8 controls, integration-gpu 1075/1075 both builds. NOT rebased on 712c9467 (moved mid-
round); the re-review reports the rebase; F integrates LAST (after D v2) and F v3 adds the white-box G9 (ID-19)
and wire's cube-face case is wire's own.
## ID-30 clientsp re-review v2 = REWORK (one item, demonstrated); C v3 launched on 712c9467
Every v1 item closed (C-M2 the one-line invalidation; C-M3 exactly ID-17 - one reference per binding, ABA closed;
all eight c0b items at the source; C-m7's refutation upheld). NEW C2-M1: the composite resolver is a process
singleton keyed on the pipeline GL NAME, but names are per context (Core.h:658-659), so a make-current between two
contexts holding the same name makes Observe emit delete_shader_state, clear the latch and free the OTHER
context's live composite - probe red on v2, green with v1's Reset() restored; c0d makes it reachable. RULING: key
the entry on (context identity, name) using the SAME context identity the rest of the pipe client already uses
(no second notion); a destroyed context's entries released exactly once; the probe becomes a unit case + mutation.
Three minors fixed in the same round. This is C's second rework (the limit); C integrates after v3 on the gates'
strength plus the probe - no third review round unless v3 changes shape.
- CI: Test lane GREEN on 2cb44039 (c0b) and on 17db7598 (c0c, two runs); 9ea44389 / e8502a61 / 712c9467 queued
behind the runner backlog (monitor re-armed).
## ID-31 gates re-review v2 = ACCEPT WITH MINORS; F integrates last, F v3 at that turn
Re-proved by the reviewer: G7 tripped + exit 0; SIGINT -> repaired, tree clean, died by signal; the child>=128
path exits 2; one leaked band slot -> 3 failed of 8 on exactly the three live-allocator lanes (983042->983090);
the ABA conjunction directory-wide with no false positive on any in-flight tree; the F-M6 matcher matches Espryt
v2's exact sentence and rejects four near-misses; G5 17 rows + 8 controls rc 0 also on 712c9467; G14 0 removed /
+123; rebase onto 712c9467 clean (8/8, zero overlap; built: unit 1684, P4a families 165/165, ctest -N 2759).
F v3 owes: ID-19's white-box G9 (shape in the review), F-v2-m1 the symmetric refusal matcher (roles-swapped claim
unchecked), F-v2-m2 the 0x5ff arm goes GREEN not red at integration (esprytobj v2 already carries the row - fix the
wording), F-v2-m3 MagmaPipeAbaControlCoversKind uncalled, F-v2-m4 REPAIR_RC write-only, and a re-take of section 6
on the integrated tree.
## ID-32 esprytobj v2 landed (`ef6beb28`, seven rework commits on a temporary base); focused re-review launched
Base = 9ea44389 + merge p4a/wire 70e742a3 + merge p4a/c0e 11446f35 + TEMPORARY commit cce81d19 (retires wire's
stand-in Named constant so the merged base compiles) - the integrator drops all of it with
`git rebase --onto refs/heads/feat/disaggregated cce81d19` (replays only the seven rework commits onto 712c9467,
which already carries the retirement). Closed: the CRITICAL (FramebufferRecordFor + BoundFramebuffer[], refusal
before the bind), M-1 (server re-dirty arms the applier's PendingUploads), M-2 (storage from Desc + metadata
respecify), M-3/M-4 (attachments + four masks from MGPSurface; AdoptTwinByHandle wired; ReleaseByHandle removed),
ID-12, ID-15's row, E's item (4) handshake, the white-box G9 probe (green, red under mutation), ten minors. Gates:
G1 0/0/0/0 at all eight commits, unit 1686 x 2, D-N scripts rc 0, DirectVulkan 475/475, default arm 189/491 =
183 named refusals + 6 armless (0x1ff pin) - the pre-client shape; 0x1ff and 0 arms 6/491 identical sets.
## ID-33 clientsp v3 landed (`92dffb81`) and integrated: pipe = `92dffb81` (post-merge running, push follows)
C v3 on 712c9467 (four MG_Test/Pipe files conflicted with wire's ae1a1c50 - resolved as an overlap-checked union,
0 of wire's 20 cases lost): C2-M1 keyed on (ContextId = ctx.GetTextureContextId(), the tree's never-reused per-
context id, PipelineName); a destroyed context's entries released once via ~ProgramObject's death path, Reset()
sweeps stranded ones (counter Sweeps); Fresh/HandleFor deleted; minors C2-m2/m3, nits. NEW defect fixed in C's
four test files (79b58198): the forked refusal drives unlinked the log while Initialize() held it open (child
wrote a deleted inode) - 6 verify-build failures -> 0. Gates on 712c9467: G1 0/0/0/0, unit 1717 x 3, names
2683 == 2683 / +95, emit 57/57 x 3, integration-gpu 491/491 default + 0x1ff (966/966 whole label), verify
844/844 zero Fatal, retrace 79/79. Integrated per ID-30 without a third review round (v3 kept its shape).
- Tool note (ID-33): the integrator's one-off scripts in the shared scratchpad wsl dir were deleted by an agent's
cleanup (only p4a_integrate_clientsp.sh survived). The post-merge check now lives durably as
`~/w7/notes/tools/wsl_p4a_postmerge.sh` + `wsl_p4a_postmerge_bg.sh` (detached launcher); integrator scripts go
in notes/tools from now on, the scratchpad is for agents.
- ID-33 addendum: post-merge on pipe G1 0/0/0/0, unit 1717 x 2, G5 rc 0, names 2683 == 2683, 0 removed / +95;
pushed: origin feat/disaggregated = `92dffb81`. Next: B v2 (its result + focused review) -> D v2.
## ID-34 esprytobj re-review v2 = ACCEPT WITH MINORS; integration recipe corrected; two items owed at D's verification round
All v1 items and rulings closed (FramebufferRecordFor + refusal above Bind, no record.Target test anywhere; packed-
key re-arm decoded both directions; seven storage macros incl. buffer-texture/multisample; the four masks off
MGPSurface with the D-N shas identical; G9 probe green x4). ID-32's `rebase --onto cce81d19` is WRONG (it drops D's
six v1 commits, which sit below the temporary merges). CORRECT RECIPE (verified clean by the reviewer, builds, unit
1686 x 2, G1 0/0/0/0, 189/6/6 with identical arms, DirectVulkan 475/475): on a branch from pipe, `git cherry-pick
9ea44389..8338c18f` (D's six v1 commits as replayed on the temporary base) then `git cherry-pick cce81d19..ef6beb28`
(the seven rework commits). Owed before/at D's verification round: N-1 the refusal line's "left unbound" is false
(SyncAndBindFramebufferObject and BindCurrentFBO bind anyway - reword); N-2 the refusal census names six of eight
shapes - sampler (:12174) and renderbuffer (:12418) missing; the "zero refusals" check on the integrated tree must
count all EIGHT families. Seven further minors recorded for the round (AdoptTwinByHandle's refusals unreachable,
the remint-pull marker on the prevention path, raw SrcOffset, the silent empty-surface arm, high-byte-vs-packed key
asymmetry, unread HasDefinedContent, G9 in-function deferral only). D integrates AFTER B v2 (ID-2 order).
## ID-35 clientfb v2 landed (`d1215fbc`); B and D integrate BACK-TO-BACK, the push waits for D
B's temporary base = 9ea44389 + wire 70e742a3 + c0e 11446f35 + clientsp 00a86d2a (a fourth merge - the ID-14/ID-17
cache call cannot compile against the contract's SamplerEmit.h stub; accepted). All ten items done: M1 region
tail, M2 three GL_Texture.cpp hooks + both-versions latch, M3 acceptance-gated clears, M4 metadata respecify,
ID-19(c) 16 Named sites in GL_Framebuffer.cpp (granted per ID-8), c0b/c0c reconciliation, D4 flipped with an EMPTY
expected-failing set, 6 minors fixed / 3 declared. Gates: G1 0/0/0/0, unit 1756 x 2, names +134, emit 148/148,
integration-gpu 0x1ff and 0 = 491/491, default 444/491, retrace(0x1ff) 79/79. RULING on its finding (1): the 47
default-arm failures / 109 verify / retrace 0 at the default mask have one proved cause - bit 10's acceptance-
gated dirty clear with NO server consumer (Espryt twins are not on B's base; 0x3ff/0x9ff/0x11ff are 491/491 and
removing only the clear gives 491/491). That is the designed dependency, not a defect: D lands immediately after
B; pipe's post-merge after B runs G1/unit/G5/G14 only; the full lanes and the PUSH happen after D. Finding (2) the
6 verify-lane unit failures are wire's refusal-drive cases fixed by C v3 (79b58198), absent from B's base - expected
to vanish on 92dffb81 (the re-review checks). B's replay onto pipe = the D-shaped recipe (v1 commits as they sit
on the temporary base, then the rework commits, merges skipped); the re-review verifies it and records any
test-file union.
## ID-36 clientfb re-review v2 = ACCEPT WITH MINORS; B and D landing back-to-back (detached run)
Verified by replay onto 92dffb81: cherry-pick 5e87d3d2 5fac004a e2bf183a a390bb1a d013b7ec 4ec43194 d1215fbc,
SKIP 549ef30b (B's own retirement of wire's stand-in constant - already on pipe); one empty-base conflict in
e2bf183a (FramebufferEmitTest.cpp / TextureEmitTest.cpp) resolved as a union with B's block FIRST (theirs-first;
ours-first compiles but breaks 4ec43194); B's files byte-identical to d1215fbc afterwards. Lanes on the replayed
tree: unit 1759 x 3, emit 152/152, gpu default 444/491 (the 47 = B's appendix, D is the missing consumer - an
independent negative control confirmed no MG_Backend file reads PendingUploads/TextureResources), 0x1ff and 0x3ff
491/491; the six verify failures gone. Minors n1-n5 recorded (n2 framebuffer records latch on dispatch = wire's;
n3 sampler-CSO refs released only on slot recycle - D/E verification rounds watch the counters). Tooling:
`notes/tools/wsl_p4a_integrate_replay.sh <slug> <range>...` (+ UNION_THEIRS_FIRST=1 with
`union_theirs_first.py`), `wsl_p4a_land_bd.sh` chains B -> D -> post-merge into ~/w7/p4a-land-bd.log.
## ID-37 B replay: the theirs-first union was wrong for the second conflict; reconciled from d1215fbc instead
The replay hit e2bf183a (FramebufferEmitTest.cpp) AND 4ec43194 (TextureEmitTest.cpp) - not the reviewer's single
e2bf183a in both - and the blind union of the second duplicated a block (redefinition errors). Rule: after replaying
a client package whose test suites share a file with wire's cases, take the package's FINAL version of those files
(d1215fbc is a pure superset of pipe's: +817 / +566, zero deletions) and re-apply the Named-spelling retirement;
that is what `wsl_p4a_land_bd2.sh` does, as one reconciliation commit on top of the seven replayed ones, unit- and
suite-tested before the fast-forward. CI: Test lane GREEN on 92dffb81 (clientsp v3).
## ID-38 B and D landed: pipe = `17396216` (B = seven replayed + reconciliation 568d587a; D = thirteen replayed); quick gate running; NOT pushed yet
Post-merge on pipe: G1 0/0/0/0, unit 1761 x 2, P3a's eleven byte-identical, names 2727 == 2727, 0 removed / +139.
The push waits for the quick gate's verdict (the six armless `.Handles` aborts from the 0x1ff itest pins are F's
and stay until F lands - a known transient, so the decision is: push after F v3 lands unless the gate is otherwise
clean, in which case push now and let CI show the six). Verification rounds launched on the integrated tree:
E (p4a/esprytdraw rebased onto 17396216: the 27 decline-site flips, ID-27's BoundFramebuffer comparison, the
assumptions reconciled against D v2's real API, the family lanes, the eight-family refusal census) and D (new
worktree ~/w7/p4a-esprytobj3 on branch p4a/esprytobj3 from 17396216: N-1 wording, N-2 eight-family census, the
seven minors, the verification checklist, and the first real-path run whose default arm must reach ZERO named
refusals - a residual is a seam defect). F v3 (rebase, white-box G9, four minors, wire's cube-face erase-key case
under an integrator grant, section-6 re-take) follows E/D; then the final whole-diff review, the full gate, APKs,
device A/B, bench, docs.
## ID-39 quick gate on 17396216: push default arm 74/966 red = 66 DirectVulkan + 6 pinned HandleRecycle + 2 DirectGLES sampler seams; c0f launched
Static half clean (three builds rc 0, unit 1761 x 3, pull integration-gpu 966/966, emitter/CSO suites 166/166,
G2 0, G14 +139, dirty-surface 27 controls). Push arm at 0x1fff: 74 failed - ALL 66 DirectVulkan failures are
texture-upload-shaped (ImageTargetKind loads, CopyImage*, NonCoreImageFormat, TextureView, PackedWordReadback,
GuiBatch, LayeredAttachment*, ClearTexImage...). ROOT CAUSE (B's own finding (1) applied to Magma): the P4a texture
family has NO "a backend registered the consumer" gate - P3a's buffers have one (PipeFill.cpp ~656:
MGPipeResourceSubsystemEnabled() = bit 7 AND a backend registered MGPipeResourceOps; Magma registers none, so
buffers stay legacy there) - so with kMGPipeWiredTextureSubsystem = 1 the client emits, the applier ACCEPTS, the
client clears its dirty flags on acceptance, and Magma's legacy path finds nothing to upload. RULING (c0f, one
commit on a branch from 17396216 by a fix agent with an integrator grant on BOTH files): (a) PipeFill.cpp - the
four P4a families' enable predicates and wants() rows require bit N AND wired AND "a backend registered
MGPipeResourceOps" (the existing per-backend signal; the texture family rides the resource rows per D-D1, and the
framebuffer/sampler/program families name texture handles so they follow); no emission at all on a backend
without the consumer; (b) PipeApply.cpp - belt: every P4a-family entry point returns accepted = false and counts
RefusedNoConsumer when no ops are registered, so a stray record can never clear a client flag. Tests: a unit case
per half; the DirectVulkan lane must return to all-green. The two DirectGLES failures (SampledSetStaleness
...ASamplerObjectCompletesTheTexture, IntegerBorderColor ...SamplerParameterIivBorderColourSurvives...) are the
B/C/D built-in-sampler seam - the D and E verification rounds classify them. The six HandleRecycle are the 0x1ff
pins (F). No push until c0f + F land.
- ID-39 addendum (gate complete): 0x1ff / 0x7f / 0 arms = 6/966 (the pinned HandleRecycle aborts only, so every
DirectVulkan case passes with bit 10 off - the diagnosis holds); ESPRYT_DISABLE_INVALIDATE_FLUSH=1 = the same 74
(not flush-related); family regex 51/497 = the same DirectVulkan set; integration-verify 68/844 = the same 66 + 2
with ZERO Fatal; G7 and P3a-G7 controls trip and recover; CSO/ResourceSubsystem/ObjectSubsystem controls 10/10;
G9's scenario and p4a_untouched_regions.sh are F's (land with it). G13 lists MG_State names in PipeApply.h at
:37/:40 (forward declarations) and :999-:1000 (LinkArtifacts/SpirvArtifacts pointers on the shader-state entry
point, D-H3's "the server reads the frontend's archive") - both OUTSIDE the ops block; accepted.
## ID-40 c0f integrated: pipe = `29d51ab9` (post-merge running; still NOT pushed - F v3 next)
c0f (PipeFill.{h,cpp} + PipeApply.{h,cpp} + tests, one commit): `kMGPipeP4aFamilySubsystems` + `P4aFamilyHasItsConsumer()`
joined into FamilyIsLive / wants() / the DrainTextureSubData gate / the residual `supplied`; `MGPipeP4aFamilyEmits`
exported; the applier's `NoP4aConsumer()` counts `RefusedNoConsumer` at 15 entry points (silent - on Magma it is
the designed state); death paths not belted; g_resourceOps untouched by Reset/ReleaseObjectRecords so gate and
belt cannot disagree mid-frame. Gates on its base: symbols 0/0/0/0, unit 1762/1763, DirectVulkan 475/475 (from
409/475), DirectGLES 483/491 = the gate's exact eight unchanged. Mutations reported (walk-side conjuncts alone are
defence-in-depth). TextureEmitTest/FramebufferEmitTest register an empty ops table in main() (consumer-present arm).
E and D verification rounds run on 17396216-based trees and rebase onto this head at their integration (no file
overlap with c0f).
- ID-40 addendum: c0f's post-merge showed G2 pull 2728 != push 2729 - the no-consumer texture case lacked its
pull-build skip twin (TextureEmitTest.cpp's MGL_TEXTURE_EMIT_CLIENT_TEST_LIST). Integrator commits 245daca0
(twin added, but a nested-heredoc escape wrote a literal backslash-n and the PULL build of the suite did not
compile - the fast-forward went through on a green push suite only) and ee31944b (the fix): both suites 34/34,
the name present in both builds; pipe = `ee31944b`, post-merge re-running. Lesson: never edit sources through a
quoted heredoc inside a quoted heredoc; write the editing script to its own file, and gate a fast-forward on
BOTH builds' compile, not one.
## ID-41 D verification round landed: pipe = `588b2277` (p4a/esprytobj3 56453191 rebased onto ee31944b); c0g launched
On 17396216 the default arm reached 485/491 - the six pinned `.Handles` aborts only - and the EIGHT-family refusal
census is ZERO over 477 per-test logs (`notes/tools/wsl_p4a_refusal_census.sh`: the console sink is compiled out
and the file sink truncates, so the census runs one ctest per name with its own log); StaleFramebufferRecordLookups
0; G9 4/4; verify zero Fatal; DirectVulkan still 409/475 on that tree = c0f, already on pipe. Seam defects: S-1
FIXED in D (BackendSamplerObject::SyncToBackend resolved the record by the twin's IDENTITY handle while C content-
addresses - every bound sampler's params refused, the two DirectGLES sampler scenarios of ID-39) - D now takes the
handle from the caller (push-only defaulted parameter, G1-safe) with a loud fallback; E owes ONE LINE at
DirectGLES.cpp:4021 (pass the handle, `#if MOBILEGL_PIPE_PUSH` guarded) - proved to close it, reverted, applied at
E's integration if E's round did not. S-2 = c0f (landed). S-3 (contract, c0g now): D-K2's fourth row refuses on
the SERVER but the client already cleared its flags, so 0x7ff = 438/491 - the client's texture family gate must
require every D-K2 dependency bit of the family (bit 11 and bit 7) as well as the consumer; generalised: a family
is live on the client only if all of its dependency bits are set (PipeFill.cpp ~885). S-4 fixed (ParamsSerial == 0
read as a malformed null BuiltinSampler). Follow-up recorded: G4's retain-mode comparison cannot run -
PipeTexelRetainMb has no reader (post-P4a item).
## ID-42 c0g integrated (post-merge running): the client's D-K2 dependency table
c0g (`29bd4d2c` on p4a/c0f, rebased on 588b2277): `kMGPipeP4aFamilyDependencies` (bit 9 -> 10; bit 10 -> 7|11;
bit 11 -> 10; bit 12 -> none; NON-transitive, mirroring Espryt's resolvers bit for bit; mirror pairs stated;
five static_asserts) consulted at c0f's four sites; every mask arm (0x7ff 438 -> 485, 0x1fff/0x3ff/0x5ff/0x9ff/
0xdff all 485/491 with the identical pinned-six list) and DirectVulkan 475/475; unit 1766 x 2, names 2732 == 2732;
M2 mutation fails to compile (static_assert). NOTE: TextureScope/FramebufferScope fixtures were arming masks
D-K2 forbids (no bit 7) - both now arm kMGPipeSubsystemResources.
- ID-42 addendum: post-merge on pipe 29bd4d2c G1 0/0/0/0, unit 1766 x 2, G5 rc 0, names 2732 == 2732, 0 removed /
+144. Still unpushed (E round + F v3 pending). (A comment-condensing request was queued here and then
CANCELLED by the user.)
## ID-43 E verification round landed on p4a/esprytdraw (`0cd0d1ec`, four commits on ee31944b); landing with two integrator patches; fable seam audit launched
E: A4 + wire v3 accessors, ID-27's bound-handle comparison (no `record.Target` reader left), F2/F4/F5/F7 loud, the
remaining flips (T2/I2/S2/P2/P3/P4/P6; T2/S2 scoped to draws touching a unit). Default arm 483/491 on ee31944b
= the pinned six + the two sampler scenarios (fixed by D3's S-1 once E's line lands), 0x7ff 438 (= c0g),
DirectVulkan 475/475, verify 842/844 zero Fatal, unit 1763 x 3, G1 0/0/0/0, both untouched scripts rc 0.
Findings: SD-0 (E's own regression, bisected to commit e3 and to the `Level` field): NewShaderImages' shutter
mixes only textureContent/textureParams/programImages, none of which moves when glBindImageTexture re-binds
the same texture with a different level, so the applier keeps the previous bind's Level and e3 (the first reader
of the field) paints the wrong mip (create-indirect ssim 0.887) - VERIFIED four-line patch for Tracker.h (mix
ctx.GetTextureBindGeneration() in, the NewSamplers shape) - applied by the integrator (contract grant) together
with S-1's DirectGLES.cpp:4021 call-site line (`wsl_p4a_land_e.sh` / `p4a_e_patches.py`, one commit on top of
E's rebased four, gated on both builds + unit + the two sampler scenarios + the create-indirect retrace + the
dirty-surface check). SD-1/SD-3 ("C never emits create_sampler_state"; built-in sampler CSO refuses x3) = the
S-1 seam as seen from E's base (no D3 there) - re-checked after landing. SD-4: set_shader_images never emitted
for imageBuffer x5 -> C's (final-review fix list). SD-5 = c0g. The ctest -V census is a FALSE ZERO (console
sink compiled out) - D's per-test-log tool is the valid one, and its phrase list is short by two shapes whose
sentence straddles a string-literal line break (:7584, :7895) - fix in the census tool. Handed up: retrace
62/79 at the default mask WITHOUT E on ee31944b (17 Iris shader-pack traces wrong, no refusal) - D3's S-1 is
the prime suspect (shader packs are sampler-heavy); the fable seam audit (user rule 2026-09-08: too many
reworks -> a fable research agent) verifies on the landed head.
- TRAP (E, cost two runs): `git lfs checkout` is DESTRUCTIVE on this box when the LFS content is not local - it
replaces every real fixture with its 130-byte pointer (retrace 1/79, ssim=None). The ONLY safe recipe is
wsl_tree.sh's: copy from ~/w7/pipe/tools/trace_replay/fixtures/ + `git update-index --assume-unchanged`; and
`git reset --hard` undoes assume-unchanged, so re-copy immediately before every retrace. ID-13's instruction
to reviewers is WITHDRAWN.
- ID-43 addendum, USER RULE (2026-09-08, binding for every agent): GitHub LFS can hit its quota - do not pull LFS at
all unless a fixture is genuinely needed; when it is, FIRST copy from the hydrated local copy
(~/w7/pipe/tools/trace_replay/fixtures/ + `git update-index --assume-unchanged`, wsl_tree.sh's recipe), SECOND
use the CI script `.github/scripts/fetch-trace-fixture-lfs.sh <case> [dir]` (mirrors git.hit.moe then
repo.miawa.cn before any LFS fallback). `git lfs checkout` / `git lfs pull` are forbidden in package and review
trees. Pointer test: the first 80 bytes start with `version https://git-lfs.github.com/spec/v1`.
## ID-44 E landed with the two integrator patches: pipe = `41b79050` (E's four rebased on 29bd4d2c + 41b79050)
The patch commit (S-1's DirectGLES.cpp call site under `#if MOBILEGL_PIPE_PUSH`, passing
MGPipeApplier().BoundSamplerStates[unit]; SD-0's NewShaderImages shutter mixing ctx.GetTextureBindGeneration()):
dirty-surface --check rc 0 (no table change), G1 0/0/0/0, unit 1766 x 2, the two sampler scenarios' suites 16/16,
create-indirect retrace 2/2 (was ssim 0.887 on E's tree). Post-merge on pipe: G1 0, unit 1766 x 2, G5 rc 0, names
2732 == 2732, 0 removed / +144. Remaining before the push: F v3 (pins, G9 white-box, minors) + the full gate with
the three retrace sweeps on the final tree; the fable seam audit feeds the final whole-diff review.
- USER RULE (2026-09-08): a package that needs more than two rework rounds goes to a fable agent (a read-only
root-cause study or the round itself), not another opus rework. In P4a that threshold was crossed by the
contract (c0b..c0g) - the fable seam audit is the response; any package needing a v4 goes to fable directly.
## ID-45 fable seam audit (fable-seam-audit.md): four seams to fix before close, three recorded; Iris = S-1, now 20/20; fable fix round launched
Proven (class 6 = a setter changes a record field no emitter-read shutter sees; class 2 = identity vs content):
F-3 set_framebuffer_state inlines each attachment's InternalFormat at emission (FramebufferEmit.h:115-144); a
texture/renderbuffer respecify WHILE ATTACHED moves TextureContent/TextureParams, never bit 9's aggregate, so D's
four cross-object masks (Managers.cpp:8678-8723, :9328-9353) read a stale surface while the legacy arm reads the
frontend at the same re-sync - public GL: glTexImage2D(RGB8) -> attach -> draw -> glTexImage2D(RGBA8) -> alpha
diverges; no scenario. F-1/F-1b bit 12's shutter (Tracker.h:494) is textureContent xor bindGen but EmitSamplerViews
resolves the set for the CURRENT PROGRAM (SamplerEmit.h:742-767): a glUseProgram alone never re-emits; E's epoch
(DirectGLES.cpp:1868) keys the texture sync list on it -> an empty-slot bind under P1 then a switch to P2 leaves
the texture never synced, no refusal. F-4 BindCurrentUnitSamplers' record arm FindByHandle(csoHandle) on the
identity-keyed twin registry (DirectGLES.cpp:4847) never finds - latent until the pre-handle program pass is
retired (S-1 one loop over). F-2 bit 14's plain-program arm mixes a per-program counter without the lifetime id
(program switch invisible; loud-ish fallback). Recorded for later: SD-5's non-transitive dependency table on both
sides, three encodings living only in package headers, the latch-before-acceptance of set_texture_params.
Iris: bisect ee31944b 3/20 -> 1e8cdc59 (D3's S-1) 20/20; every failing log carried "sampler N has no applier
record" - the backend-minted raw-depth-fetch sampler refused by the identity lookup; E's "zero refusals" was
itest-only. 41b79050: 20/20, zero refusal lines. Brief root causes: D-K4's "shutters are already computed" (no
record-field -> setter -> shutter table), no per-kind handle-rule table for BOTH sides, dependency rules stated
about masks not emissions, no census recipe for retrace runs -> the P4b brief states all four up front.
Per the user's rule (rework > 2 -> fable): ONE fable fix agent takes F-1/F-1b, F-2, F-3, F-4 + E's SD-4
(imageBuffer set_shader_images) + the census tool's two missing phrases, on a branch from 41b79050, with an
integrator grant on Tracker.h / SamplerEmit.h / ImageEmit.h / FramebufferEmit.h / DirectGLES.cpp / Managers.cpp
and a NEW scenario file (to stay clear of F v3's files). The final whole-diff review will be fable as well.
## ID-46 gates v3 landed: pipe = `4678519f` (15 commits on 41b79050; post-merge running); fable fix round launched from it
F v3: 0x1fff pins (the six `.Handles` aborts closed), G9's white-box half (new Harness/PipeApplyPeek.{h,cpp};
mutation 4/4 red), wire MINOR-1's cube-face case, c0f's belt pinned on both backends, F-v2-m1..m4. On 41b79050:
integration-gpu 1079/1079 at 0x1fff / 0x1ff / 0 and pull (DirectVulkan 540/540, DirectGLES 539/539), verify
884/884 zero Fatal, unit 1767 x 3, G1 0/0/0/0, G2 2846 == 2846, G14 +258, G5 17 rows + 8 controls, all three
negative controls rc 0, HandleRecycle 144/180/144 + .Handles 36/36, ObjectSubsystemControl 14/14. Four defects
the gates caught during the round were fixed upstream already (0x5ff emit disagreement = c0g, the G2-breaking
c0f name = ee31944b, the two-case-wider sampler seam = S-1, D-E3's read-attachment gap = E). The fable fix round
(p4a/fablefix from 4678519f: F-1/F-1b, F-2, F-3, F-4, SD-4, the census phrases, the shutter table comment) is the
last code round; then the full gate with the three retrace sweeps, the push, the fable whole-diff review, APKs,
device A/B, bench, docs.
- ID-46 addendum: post-merge on pipe 4678519f G1 0/0/0/0, unit 1767 x 2, G5 rc 0, names 2846 == 2846, 0 removed /
+258. Worktrees left: p4a-c0f (c0g's branch), p4a-esprytdraw, p4a-gates, p4a-fablefix (in flight).
- USER (2026-09-08): after P4a closes (gate, push, final review, APKs, device A/B, bench, docs) STOP - do not start P5.
## ID-47 fable fix round landed: pipe = `6035c9d7` = the P4a CODE HEAD; full gate + fable whole-diff review + Release APK build launched in parallel
fablefix (seven commits from 4678519f): F-3 the framebuffer aggregate bumped from PipePublishDescriptor (texture +
renderbuffer, no counter added) + the pre-handle arm's in-place regeneration / renderbuffer re-storage bump compiled
PUSH-ONLY (G1 caught the pull-side version as 0/0/2/0 - the pre-P4a monolith hole stays in the pull build and is
RECOMMENDED AS A SEPARATE dev COMMIT after P4a; the texture cases decline by name there, the renderbuffer case
asserts on the handle arm only); F-1/F-1b bit 12 mixes program identity x link x backend state (pipeline-aware) +
the params aggregate (F-1b reproduced black 144/144, closed without widening E's epoch); F-2/SD-4 bit 14's plain
arm mixes lifetime id x link version (SD-4 was this, not reflection); F-4 ResolveSamplerCsoTwin on the content-
addressed record shared by the record arm and the program pass; the record-field -> setter -> shutter table in
Tracker.h; the census tool's two straddling shapes. On 6035c9d7: G1 0/0/0/0, both untouched scripts rc 0 (+8
controls), gen_pipe / dirty-surface (27 controls) / include closure rc 0, unit 1772 x 3, G2 2863 == 2863, G14
+275, integration-gpu 1091/1091 at 0x1fff / 0x1ff / 0 / pull, DirectVulkan 546/546, verify 896/896 zero Fatal,
retrace 79/79, retrace census 0 on 13 needles, itest census 0. Deviations accepted: its own peek TU (second CMake
line, F's file untouched); seven commits. USER: after P4a closes, STOP (no P5).
## ID-48 full gate on 6035c9d7 green through verify; APKs built; device A/B running; the Oppo install flow fixed (pipe = `a38bdab4`, tools only)
Gate so far: builds x3 rc 0; G1 0/0/0/0; G5 P3a eleven + P4a 17 rows (8 controls) rc 0; HandleRecycle (verify)
180/180; emitter/CSO suites 172/172; G2 0; G14 +275; unit 1772 x 3; pull integration-gpu 1091/1091; push at
0x1fff / 0 / 0x1ff / 0x7f / ESPRYT_DISABLE_INVALIDATE_FLUSH=1 all 1091/1091 (the "rerun 53" lines are a stale
LastTestsFailed.log - nothing failed on the first pass); family 497/497; G9 8/8; TextureUploadShape 3/3
(recorded); three negative controls rc 0 (G7 exit 0 naming Layered + borderColorForm); CSO/Resource/
ObjectSubsystemControl 24/24 + 0x9ff arm 14/14; controls 184/184; integration-verify 896/896, zero Fatal. The
three retrace sweeps are running. APKs: ~/w7/notes/p4a/apk/trace-{pull,push}.apk (8504077 / 8622861 bytes,
debug-signed, MGPipe strings 3 / 107, mpr present in push) - Release size class (not the -O0 trap).
Device A/B: Xiaomi running (session pinned 21:38:16 after cool-down; 26.3 GLES pull nofinish p50 10.76 ms). Oppo's
first attempt died the P3a way - the tapper hit the ColorOS dialog while the streamed install was in flight and adb
dropped (device not found for runs 2/3). FIX: `MOBILEGL_TRACE_SKIP_INSTALL=1` in android-plugin/trace-replay-ci.sh
(pipe a38bdab4, tools-only commit on top of the gated 6035c9d7; the Windows runner tree fast-forwarded with
GIT_LFS_SKIP_SMUDGE=1) and, on the Oppo only, the A/B script installs each arm itself (tapper handles the dialog,
`adb wait-for-device`, `pm path` poll up to 90 s) before running the case with the install skipped. Both A/B
scripts also gained the Xiaomi cool-down wait (< 42 C), the rd12/Magma-on-Xiaomi skip (ID-6) and the tapper.
- ID-48 addendum (tooling lesson): `pkill -f` from the Git Bash tool does NOT kill a detached A/B script on
Windows (the old Oppo run kept going, holding the device lock while the restarted one waited); enumerate with
PowerShell `Get-CimInstance Win32_Process` filtered on the command line (excluding the query's own process) and
kill with `taskkill /PID <pid> /T /F`; a `wmic ... like '%<pattern>%'` query from the Bash tool matches the tool's
own shell command line and killing it aborts the tool call. Remove the device lock dir by hand afterwards.
- A/B note: Xiaomi rd12 GLES push nofinish ran with pin=1/1 (DRIFT before and after - the thermal clamp, ID-8);
p50 12.94 vs pull 8.24 ms is NOT a valid pair - re-run the rd12 push arms on the Xiaomi after a cool-down at the
end of the session (single-case re-run, package left installed); ab_reduce3.py must exclude drifted samples.
## ID-49 FULL GATE GREEN on 6035c9d7; pushed: origin feat/disaggregated = `a38bdab4` (= 6035c9d7 + the tools-only harness commit)
Gate: every part green (ID-48's static + lanes) plus the three retrace sweeps - verify 79/79 with 79 armed and zero
Fatal, push 79/79, G3b named 12/12. Device A/B: Xiaomi session 1 finished with the thermal clamp drifting every
sample from rd12 push onwards (pin 1/1) - 14 of 36 samples clean; the scripts gained a per-case cool-down (< 42 C,
up to 15 min) + re-pin and a clean-pin skip, and session 2 is redoing the 22 drifted samples. Oppo: session 2 (pre-
install flow) running. Desktop bench (`wsl_p4a_bench.sh`, idle box) launched; the fable final review is relaunched
(the first attempt died at start on an API ECONNRESET) with its build/mutation experiments deferred until the bench
is done so the bench stays on an idle box.
- A/B tooling (ID-49 addendum): the Xiaomi cool-down loop timed out once at a reading below the threshold (the
raw `su -c cat` output is not always clean digits right after a reboot); both scripts now read the zone with
`tr -cd "0-9"` and compare `${T:-99999} -lt 42000`. Session 2 killed by PID (PowerShell), lock released,
session 3 launched (log ab-35d0befa-3.log); already-clean samples are skipped, drifted ones redone.
## ID-50 desktop DriverBench on 6035c9d7 (recorded, not gated; ~/w7/notes/p4a/bench/driverbench.{csv,md})
mc_vanilla_draw ns/draw: espryt T1 = push(0x1fff) - pull = +1269.7; T2 = push(0x1ff) - pull = +1135.8; T1 - T2
(what P4a added) = +133.9; PIPE_PUSH=0 - pull = +697.8; no-CSO-addressing - push = +276.6. magma T1 = +139.1;
T2 = -191.7; T1 - T2 = +330.8 (Magma emits nothing for P4a families after c0f - the delta is the tracker's
extra shutter work plus noise; the pull/push spread on magma is within its repeat noise). mc_state_toggle:
espryt pull 24695 / push 26265 (+1570), magma 36225 / 37149 (+923); mc_pass_switch: espryt +7695, magma -5609.
Compared with P3a's table (espryt T1 +1047.7, T2 +348.5): the P3a-boundary arm itself moved (+1136 vs +349)
because the 0x1ff arm now also runs P4a's tracker/shutter work with the families off - to be stated in
MEASUREMENTS.md as a caveat (T2 is no longer a pure P3a number).
## ID-51 device A/B, Xiaomi (Adreno 830) main pairs complete - 36/36 clean pins after session 3; Release APKs; push - pull p50 (ms, nofinish / finish)
26.3 GLES +1.67 / +1.57 (10.76 -> 12.43; +15%); 26.3 Magma +0.91 / +0.86 (Magma emits nothing for P4a families
after c0f: this is the P2+P3a boundary + the tracker); rd12 GLES +2.97 / +3.03 (8.24 -> 11.20; +36% - the
largest; the 0x1ff arm will say how much is P4a's); sodium GLES +0.06 / +0.16, sodium Magma -0.42 / +0.08;
vanilla GLES +0.50 / +0.49 (2.34 -> 2.84; +21%); vanilla Magma +0.69 / -0.16 (noisy); iris-bsl GLES +0.64 /
-0.36 (p50 ~1.3-1.9 ms with 300+ ms p99 spikes on both arms - the shader-pack compile stalls dominate). Oppo main
session running (pre-install flow OK); Xiaomi 0x1ff arm running; then the three-arm reduce (ab_reduce3) and the
per-case MGPipe stats. Performance is recorded, not gated (user rule); rd12's +36% goes on the optimisation list
with the P3a +17-19 pts it stacks on.
## ID-52 final whole-diff review (fable) = REWORK: two criticals + one major; fable fix round launched (B is past two reworks)
C-1 (critical, TextureEmit.h:955-960): every respecify calls MGPipeApplyResourceRespecify(desc, nullptr) - no
emitter builds an MGPRespecifiedLevel - so a per-level glTexImage*D / glGenerateMipmap grow takes the whole-
resource arm (PipeApply.cpp:1684) and drops every accepted-but-unconsumed pending upload while the client flag
is already clear: `L0; draw(other); L1; draw(T)` and `L0; draw(other); glGenerateMipmap; draw(T)` read 100% black
at 0x1fff, red at 0x1ff (three controls red on both) - wire-v3 §5 item 5 required B to pass the level and no review
checked it. C-2 (critical): a dead-but-unrecycled texture handle still resolves to the freed ITextureObject*
(ResolveTexture checks GenOfSlot, which moves only at re-acquire; the death helper does not forward to the emitter;
the drain list survives death): `glTexImage2D; glDeleteTextures; draw` -> SIGABRT "pure virtual method called" on
the handle arm. M-A (major): no producer of kMGPipeBindSampler / kMGPipeBindShaderImage - ImageBindableHint is
always 0, D-A4's remint mitigation undelivered, ROADMAP.md:85's number unmeasurable. Minors: F-7 latch-before-
acceptance for set_texture_params; Config.h omits the 10 -> 11 dependency row; "ORed" vs replace-whole comment;
F-6 encodings in package headers; the CPU three-channel mipmap re-arm gap; G9 blind when row + mark drop together.
Verified green by the review: G1 at TU granularity, G5 red on a statement mutation, G7 both controls, G9 red on a
decidable row, first-attempt mutations red, TEMPORARY test.yml:9-12 trigger still present (remove before dev), all
D.5 placeholders unfilled (§6). RULING: one fable fix round on a branch from a38bdab4 - C-1 (B passes the level;
a unit case + the two llvmpipe scenarios as itest), C-2 (death path: the death helper forwards to the emitter,
the drain list drops the dead entry, ResolveTexture refuses a dead slot; the delete-then-draw scenario), M-A (the
bind-bit producers at glBindSampler / glBindImageTexture and wherever D-A4 names; ImageBindableHint measurable),
the cheap minors; then the review's §8 re-runs + quick gate + push retrace, a focused fable re-review, and the
device A/B GLES pairs redone on APKs built from the fixed head (C-1 drops uploads, which biases the push arm).
- CI: Test lane GREEN on a38bdab4 (the pushed P4a head + harness switch).
## ID-53 Xiaomi 0x1ff arm complete; Oppo session hung on a re-install - hardened and relaunched (session 3)
Xiaomi push(0x1ff) p50 nofinish (ms): 26.3 GLES 11.86 (pull 10.76 / push 12.43 -> P4a's own share +0.57 of +1.67),
26.3 Magma 11.53 (= its 0x1fff arm, no P4a consumer), rd12 GLES 10.84 (pull 8.24 / push 11.20 -> P4a +0.36 of
+2.96; the P2+P3a boundary carries +2.60), sodium GLES 1.40 / Magma 1.01, vanilla GLES 2.72 (pull 2.34 / push 2.84
-> P4a +0.12 of +0.50), vanilla Magma 1.15, iris-bsl GLES 1.86 / Magma 0.78. Oppo session 2 hung at 21:49:45 in
the pre-install `adb install -r` of the push arm - the ColorOS dialog for a REPLACE install was never tapped (the
tapper matched InstallGuideActivity only) and the streamed install session dangled for 1.5 h with the device
back on its launcher. Hardening (both scripts): the tapper matches InstallGuide|PackageInstaller|installer|appdetail;
the pre-install runs under `timeout 150` with three attempts (Back key + wait-for-device between them). The hung
tree killed by PID (54088 adb + 48100/48936/48268), lock released, mixed results moved to 3B159D009VZ00000-old;
session 3 launched (log ab-3B159D009VZ00000-2.log). Monitors for the dead logs are left idle.
## ID-54 Xiaomi three-arm table (Release APKs from 6035c9d7, pre-finalfix; nofinish p50 ms: pull / 0x1ff / 0x1fff, d P3a-boundary / d P4a total)
26.3 GLES 10.76 / 11.86 / 12.43 (+10.2% / +15.5%); 26.3 Magma 10.67 / 11.53 / 11.58 (+8.0% / +8.5%); rd12 GLES
8.24 / 10.84 / 11.20 (+31.6% / +36.0%); sodium GLES 1.38 / 1.40 / 1.44 (+1.3% / +4.3%); vanilla GLES 2.34 / 2.72 /
2.84 (+16.4% / +21.4%); iris-bsl GLES 1.30 / 1.86 / 1.95 (+42.7% / +49.2% on a ~1.5 ms p50 with 317 ms p99 compile
stalls - shape-dominated). Magma rows other than 26.3 are noise-dominated at these frame times (sodium Magma push
0.52 vs 1ff 1.01; vanilla Magma pull-nofinish 1.05 vs pull-finish 1.97) and are reported with that caveat; Magma
emits nothing for P4a families (c0f), so its "P4a" arm is the tracker only. So P4a's own share on Espryt is
+0.5-0.6 ms on 26.3 and +0.1-0.4 ms elsewhere; the P2+P3a boundary carries the rest (rd12 +2.6 ms). Raw results
and the table copied to ~/w7/notes/p4a/ab/prefix-a38bdab4/ (tool: ab_reduce3_p4a.py, the P3a reducer re-labelled
for push1ff). These are the PRE-finalfix numbers: the GLES pairs will be re-measured on APKs built from the fixed
head (C-1 dropped uploads on the push arm, which flatters it).
## ID-55 final fix round integrated: pipe = `8c458cd5` (five commits; post-merge running; fable re-review running; APKs rebuilding)
finalfix (from a38bdab4): 173f1dd2 C-1 (storage entry points state their scope - one level / chain cut / whole
resource - the emitter builds MGPRespecifiedLevel with the drain's packed target, per-level calls never deduped,
the applier drops exactly the named level), a690032f C-2 (every death helper forwards to its emitter between the
wire delete and the free; ResolveTexture refuses a dead slot loudly; sticky-mask producers stamp the generation;
delete-then-use pinned per kind, for a recycled slot, under MALLOC_PERTURB_ on both backends), 9f60aadc M-A (the
SAMPLER bit from view resolution, SHADER_IMAGE at glBindImageTexture through a contract door; ImageBindableHint
precedes the first sync; `tex-remint-pulls` = ROADMAP:85's number), c2c6a655 minors (F-7 latch-on-acceptance with
a Bool return, Config.h row, the comment), 8c458cd5 (census residual: default textures born before consumer
registration heal from their first set_texture_params - the re-review judges whether that is a legitimate late
birth). Gate on 8c458cd5 (the agent's): G1 0/0/0/0, G5 x4 rc 0, gen tools rc 0, unit 1785 x 3, names 2902 ==
2902, +314, integration-gpu 1117/1117 on seven arms (DirectVulkan 559/559), verify 920/920 zero Fatal, retrace
79/79, retrace census 0 on 16 needles, itest census 0/13, negative controls tripped. Declared m-4 (P4b), m-5,
m-6, m-7 benign, m-8 not reproduced. No Co-Authored-By anywhere (user rule re-confirmed 2026-09-09). Pre-fix APKs
kept at ~/w7/notes/p4a/apk-prefix/; the Release APKs are being rebuilt from 8c458cd5 for the GLES A/B redo.
Lesson (memory subagent-parked-notifications): a "finished" notification whose result says "waiting on the
build/gate" is a PARKED agent, not a dead one - the continuation agent launched for it was stopped.
- ID-55 addendum: post-merge on pipe G1 0/0/0/0, unit 1785 x 2, G5 rc 0, names 2902 == 2902, 0 removed / +314;
pushed: origin feat/disaggregated = `8c458cd5`; the Windows runner tree fast-forwarded to it (LFS smudge off).
## ID-56 STOPPED HERE by the user (2026-09-09 ~01:20): origin feat/disaggregated = `8c458cd5`
Done: contract c0..c0g, wire v3, clientsp v3, clientfb v2, esprytobj v3, esprytdraw v3 (+ the two integrator
patches), gates v3, the fable seam-audit fix round, the final-review fix round - all integrated, the full gate
green on 6035c9d7 and the fix agent's own full gate green on 8c458cd5 (itest 1117/1117 on seven arms, verify
920/920, retrace 79/79, census 0); CI green through a38bdab4 (8c458cd5's run pending); Release APKs from 6035c9d7;
device three-arm A/B on both devices (pre-fix APKs) in ~/w7/notes/p4a/ab/prefix-a38bdab4/ + three-arm-prefix.md;
desktop bench in ~/w7/notes/p4a/bench/. NOT done, by the user's decision to stop: the fable focused re-review of the
five fix commits (stopped mid-read), the GLES A/B redo on post-fix APKs (the rebuild was stopped; the pre-fix
numbers flatter the push arm slightly because C-1 dropped uploads), docs D.5 (README status line, ROADMAP P4a row,
MEASUREMENTS §22+ - all placeholders unfilled), the TEMPORARY CI trigger branch in test.yml/apk.yml (must be
removed before merging to dev), worktrees p4a-{c0f,esprytdraw,fablefix,finalfix,gates} and 47 logs under ~/w7
left in place. Known open items are listed in the closing summary to the user and in final-review-v1.md §recorded,
fable-seam-audit.md §D, finalfix-v1.md §declared.
## ID-57 P4a 收尾(2026-09-11,新设备):docs D.5 写作中,红米上重测
用户接了一台**红米 `2f7cbe2e`**(Redmi M332BF "warsaw",SM8750 / Adreno 830v2、Magisk root、**带主动风扇**)并规定:**之后实验只用它,其他 adb 设备一律不碰**;同时指出本分支的活应当在 `MobileGL-disagg` worktree(feat/disaggregated)而不是主 dev 树上做——dev 树上那两处调试 `fprintf` 插桩已按用户指示丢弃。
- **设备工装**:`pin_device.sh` 加了 `2f7cbe2e` 条目。同 SoC 同 OPP(`1958400`/`1555200` 两个战役定频点都在),唯一差别是 policy6 的 stock 上限 3072000(旧机 2841600)。**GPU 定频点是 1050 MHz 不是 1100**:厂商把 `kgsl-3d0/thermal_pwrlevel` 永久钉在 1,`max_gpuclk` 因此 1050,root 写 0 无效(33 °C + 风扇 16k rpm 下验证过)——旧小米那个间歇性的"pwrlevel 0 但 gpuclk=1050 DRIFT"几乎肯定就是它。
- **风扇**:`/sys/class/xm_power/hw_monitor/pwm_fan`,A/B 全程 level 2(~14.5k rpm)恒定——它是常量不是处理项,两臂同风量。降温从 20–30 分钟变成 <1 分钟。档位表与两个坑(101–104 debug 锁存要写 100 退出、`pwm_duty` 是绕过档位表的原始旋钮、状态只能看 `real_speed`)记在 memory `fcl-device-testing`。
- **新 A/B 驱动**:`notes/tools/p4a_ab_redmi.sh`(序列号硬保护,只认 `2f7cbe2e`;风扇常开;无安装点击器——这台 `adb install` 直接过;**不跳过 rd12/Magma**)。实测:rd12 在 DirectVulkan 上 **rc=1 照样崩**,和旧小米一致,确认是 `dev` 侧问题不是设备个例。
- **APK 重建自 `8c458cd5`**:pull 8504077 B(与修复前同字节,正是 G1 要的 pull 不动)、push 8626957 B / 109 条 MGPipe 串。修复前那对存 `~/w7/notes/p4a/apk-prefix/`。
- **补测**:79 例 retrace 带 `MOBILEGL_PIPE_STATS=1` 各跑一遍 push/pull 臂,为的是 ROADMAP 开放问题 2(`trp` = 780 窗口里 **2 次**,只在两条 Iris 光影用例的 DirectGLES 侧)、§20 读法 (5)(新的 `csob-blob` 字节类:DirectGLES 27 例中位 **2928 B/帧**、rd12 峰值 **1.06 MB/帧**、DirectVulkan 恒 0 = 消费者门的量化)与 D.4.3 的上传形状头条。DriverBench 在 `8c458cd5` 上重跑(原 ID-50 的数出自 `6035c9d7`)。
- **docs D.5 进度**:README 状态行与文件地图、ROADMAP 的 P4a 行/P3b-P4b 行/39 天检查点/通用纪律(补上"不顺手修 dev bug",让课题 17 的 `ROADMAP.md:7` 引用成真)/开放问题 2、8、17、ARCHITECTURE 十二处、MEASUREMENTS 读法 (5) 与 `g_uploadRing` 旁的第二条同类项、新增 §22(五部分门两个头对照)与 §23(**缝的分类**——九类,每类给症状与预防,是这一波最值钱的产出)均已写;§24(设备三臂表 + p99 + 上传形状)与 §25(T1/T2/T3)等测完补。`check_doc_citations.py` 97 处引用 0 问题。
- **清理踩坑**:`rm ~/w7/p4a-*.log` 把两个**正在被写**的 retrace 日志删了,导致以日志标记为条件的 bench 等待者永远等待(输出目录无损);改成 `while pgrep -f retrace_gate...; do sleep 30; done` 等进程。已记进 memory `temp-file-hygiene`。
- ID-57 addendum: **P4a 收官,docs D.5 已推送:origin feat/disaggregated = `a29807cc`**(`8c458cd5` 代码 + 一条 docs 提交,citation lint 100 处 0 问题,无任何 attribution 行)。红米三臂表与原始结果在 `~/w7/notes/p4a/ab-redmi/`(40/40 干净 pin),bench 在 `~/w7/notes/p4a/bench/`(重跑于 8c458cd5)。**桌面 bench 分辨不出 P4a 自身**(两轮 T1−T2 = +133.9 与 +11.4 ns/draw,而两臂绝对值各自漂 ~200 ns),可引用的是 T1 ≈ +1.1 µs/draw 的总边界与设备侧三臂表。设备侧 P4a 自身 = +3.4~+5.7 个百分点(0.05–0.38 ms/帧),Magma 两臂差在噪声内 = c0f 消费者门的读数。上传形状 pull/push 全语料只差 +2(正好是 2 次 trp)。**留给优化阶段的第一条线索**:设备上 26.3 Espryt 的 `sve` ≈ draw 数(9143/9138),桌面同 fixture 只有 ~0.07/draw。
+95
View File
@@ -0,0 +1,95 @@
# P4a — handle wave 2(Espryt):FBO / 纹理 / sampler / program(`8c458cd5`)
> 本页是该阶段的**阶段汇总**:阶段表行、实测与落地形状的完整文本(2026-09-24 从上层索引移入,原文照录)都在这里;上层只留摘要——[`ROADMAP.md`](../../../Disaggregated/ROADMAP.md)、[`MEASUREMENTS.md`](../../../Disaggregated/MEASUREMENTS.md)、[`ARCHITECTURE.md`](../../../Disaggregated/ARCHITECTURE.md)。文中 `file:line` 与"今天""当前"按各段写成时的头理解;文中的 `MEASUREMENTS.md §N` / `ARCHITECTURE.md §17.x` 编号保留,对照表见 [`../README.md`](../README.md)。
## 摘要
- 落地:十四条族调用接线(framebuffer、sampler state / view、texture params、shader images、shader state、draw / dispatch program、global constants);纹理 / renderbuffer 复用 `resource_*`;六种 kind 按 `{slot, gen}` 重键;`CompositeResolver`;`Named = 3` framebuffer 记录;消费者门 + 客户端依赖表;子系统位 9–12,push 默认 `0x1fff`。
- 门:G1 0/0/0/0;G5 17 区;单元 1785×3;`integration-gpu` 1117 七臂;verify 920;八族拒绝普查 0。实际 1 天。
- 方法论:六个包 v1 全过自己的门、六份复审全判 REWORK,最贵的两个缺陷(丢上传、delete 后 UAF)只有**整体 diff 终审**抓得到。
- 设备换为 Redmi `2f7cbe2e`:P4a 自己在 Espryt 上 +3.4–5.7 pt,Magma 在噪声内。
## 阶段表行(原 `ROADMAP.md`)
- **阶段**:**P4a** handle wave 2(Espryt):FBO / 纹理 / sampler / program
- **状态**:✅ `8c458cd5`
- **落地什么 / 范围**:十四条族调用接线(framebuffer state、sampler state / view、texture params、shader images、shader state、draw / dispatch program、global constants);纹理 / renderbuffer 复用 `resource_*`(目录不加行);六种 kind 按 `{slot, gen}` 重键;`CompositeResolver`;`Named = 3` framebuffer 记录;消费者门 + 客户端依赖表;位 9–12,push 默认 `0x1fff`;emulation 在 split 下具名 Fatal
- **验收门 / 证据**:全门:G1 0/0/0/0;G5 17 区;G2 2902;单元 1785×3;`integration-gpu` 1117 七臂;verify 920;retrace 79/79;八族拒绝普查 0;`PipeApplyPeek` 白盒对照。实际 1 天。§5
## 实测:P4a(`8c458cd5`,基线 `37da3c3a`,101 个提交,86 文件 / +30066 / −384)(原 `MEASUREMENTS.md` §5)
### 5.1 全门(`6035c9d7` 全量 + `8c458cd5` 复跑)
| 门 | `6035c9d7` | `8c458cd5` |
|---|---|---|
| **G1**(认定 resize 集为空) | 0 / 0 / 0 / 0,`.text` 不变 | 同上 |
| **G5** | P3a 十一函数 rc 0;P4a **17 区 / 3 文件** rc 0,self-test 8 个阴性对照按名变红 | 同上 |
| G2 / G14 | 差 0 / +275 | 差 0(2902 条)/ +314 |
| 单元 | 1772 × 3 | **1785 × 3** |
| `integration-gpu` | 1091/1091 × 七臂 | **1117/1117 × 七臂**(默认 `0x1fff`、`0x1ff`、`0`、`0x9ff`、`0x5ff`、pull、`ESPRYT_DISABLE_INVALIDATE_FLUSH=1`;DirectVulkan 559/559) |
| `integration-verify` | 896/896 零 `Fatal{` | **920/920** |
| retrace(79 例) | verify 79/79 armed 零分歧;push 79/79;G3b 12/12 | push 79/79 |
| 阴性对照脚本 | `g7_negative_control.sh`、`p3a_vertex_input_negative_control.sh`(`IsBgra`)、**`p4a_descriptor_negative_control.sh`(`Layered` 与 `borderColorForm`)** rc 0 | 同上 |
| 子系统对照套件 | `CsoContentAddressing` + `ResourceSubsystemControl` + `ObjectSubsystemControl` 24/24;`0x9ff` 依赖拒绝臂 14/14;`HandleRecycle`(verify)180/180 | 同上 + 184/184 controls |
| 八族拒绝普查 | — | **0**(逐用例读私有日志;`ctest -V` 是假零) |
G9 的"落地前必须红"没能通过公共 GL 达成(回读模拟自己会设 `GL_DEPTH_STENCIL_TEXTURE_MODE`):改成 `PipeApplyPeek` 白盒断言,变异下 4/4 变红。真正红过再绿的两条来自终审:per-level respecify 丢上传(`0x1fff` 下读回全黑)与 delete-then-draw(`pure virtual method called`)。CTS `direct_state_access.framebuffers*` / `packed_pixels`(G15)未跑,随 P3b/P4b 补。
### 5.2 缝的分类(契约七次修正 `c0b`…`c0g` + 一轮缝类审计 + 一轮终审修复)
| 类 | 实例 | 症状 | 预防 |
|---|---|---|---|
| 编码没定死 | `MGPSubData::Target`、`DepthStencilMode`、`MGPSurface::Kind`、缺 `TextureTarget` | 两侧各自发明一套;`Texture1D == 0` 与 `kMGPipeResourceTargetBuffer == 0` 撞上 | 编码表放进契约 |
| 身份 vs 内容 | 内置 sampler:client 按身份铸、cache 按内容铸 | 查找永远落空 → 17 条 Iris trace 用驱动默认采样器 | 每 kind 两侧 handle 规则表 |
| 记录键错了维度 | framebuffer 记录按"当前绑定"存,DSA 按名字来 | 打进从没收到附件的 FBO | 记录按对象存;`Named = 3` |
| 进程级单例 vs 每上下文命名 | `CompositeResolver` 按管线 GL 名记忆 | 释放另一个上下文还活着的合成体 | 单例的键含上下文身份 |
| 破坏性客户端动作缺前置条件 | 按 acceptance 清 dirty,但 Magma 无消费者、依赖位只在服务端拒 | 上传丢失:66 条 DirectVulkan 用例、`0x7ff` 下 438/491 | 消费者门 + 依赖门都在客户端:一条不发 |
| 快门看不见自己的主体 | `glBindSampler`、SSO 下 `GetCurrentProgram()`、`glBindImageTexture` 只换 level | 记录停在上一次的值(`create-indirect` SSIM 0.887) | "记录字段 → setter → 快门"完备表;优先混入已有世代 |
| 清得太宽 | `resource_respecify` 清掉整张待上传表 | 已接受的那一级永久丢失 | 作用域随调用走 |
| 死亡没通知发射方 | 六个死亡 helper 只释放 slot | 已删句柄解析到已释放对象 → UAF | 死亡转发给每个 emitter |
| 门不能变红 | G7 脚本永远编译不过、`HighWater(ShaderCso)` 取段顶、G9 红前态公共 GL 不可见 | 绿得毫无意义 | 每个门带阴性对照并真跑过一次红 |
方法论结论:六个包的 v1 全部通过自己的门、六份对抗性复审全部判 REWORK,最贵的两个缺陷(丢上传、delete 后 UAF)是**整体 diff 终审**才抓到的——它们跨包,各方自洽。终审是唯一能看见跨包契约的那一轮。
### 5.3 Redmi 三臂 A/B、MC 26.3 的 p99、上传形状(记录项)
设备换为 Redmi `2f7cbe2e`(与小米同 SoC 同定频点,数值可比;GPU 当时钉 1050 MHz;主动风扇 level 2,40 个样本 40 个 PINNED)。APK `8c458cd5` Release 双臂;`--benchmark-no-finish`,尾 200 帧、best-of-3、逐线程 CPU p50 ms;`0x1ff` = P2+P3a 边界,`0x1fff` = P4a 默认。
| 用例 | 后端 | pull | `0x1ff` | `0x1fff` | Δ P2+P3a | Δ 合计 | **P4a 自己** |
|---|---|---|---|---|---|---|---|
| improved-transparency-26.3 | Espryt | 10.716 | 11.754 | 12.124 | +9.7% | +13.1% | **+3.4 pt / +0.37 ms** |
| improved-transparency-26.3 | Magma | 10.603 | 11.543 | 11.585 | +8.9% | +9.3% | +0.4 pt(噪声) |
| rd12-odinlite | Espryt | 8.210 | 10.798 | 11.182 | +31.5% | +36.2% | **+4.7 pt / +0.38 ms** |
| rd12-odinlite | Magma | — | — | — | — | — | 三臂全 `rc=1`(`scudo`,`dev` 侧,换机仍复现) |
| fabric-sodium | Espryt | 1.312 | 1.406 | 1.454 | +7.2% | +10.8% | +3.6 pt / +0.05 ms |
| fabric-sodium | Magma | 0.474 | 0.502 | 0.507 | +5.9% | +7.0% | +1.1 pt(噪声) |
| 1.21.4-in-world | Espryt | 2.369 | 2.732 | 2.867 | +15.3% | +21.0% | **+5.7 pt / +0.14 ms** |
| 1.21.4-in-world | Magma | 1.028 | 1.147 | 1.145 | +11.6% | +11.4% | −0.2 pt(噪声) |
| fabric-iris-bsl | Espryt | 1.727 | 1.740 | 1.811 | +0.8% | +4.9% | +4.1 pt / +0.08 ms |
| fabric-iris-bsl | Magma | 0.742 | 0.788 | 0.786 | +6.2% | +5.9% | −0.3 pt(噪声) |
读法:P4a 自己在 Espryt 上是 +3.4 – +5.7 pt(0.05–0.38 ms/帧),大头仍是 P2+P3a 的边界;Magma 两臂在四个用例上落在噪声内——消费者门在设备上的读数(Magma 一条 P4a 记录都不发);`vanilla` 是 P4a 占比最高的用例(draw 少、状态切换密)。**MC 26.3 在 Adreno 上的 p99**:pull 25.297 → P4a 26.841 ms(+6.1%),仍在 21–26 ms 档。**上传形状 pull 与 push 逐项相同**(79 例两臂 `tex[emit/box/rect/jobs]`:18451/16060/2391/39926 对 18453/16062/2391/39928,唯一差异是 2 次 `trp` 带来的重放上传)。线索:设备上 26.3 Espryt 的 `sve` ≈ draw 数(9143 / 9138),桌面 ~0.07/draw——每 draw 重发一次 sampler-view 集合,进 P3b/P4b 优化清单。`acc/draw` 在这一波普遍下降而 CPU 上升,不是矛盾而是该计数器的定义。
### 5.4 DriverBench(`wsl_p4a_bench.sh`,`8c458cd5`,`mc_vanilla_draw` ns/draw)
Espryt T1(`0x1fff` − pull)= +1076.1,T2(`0x1ff` − pull)= +1064.7,T1 − T2 = +11.4;Magma T1 = +629.0、T2 = +452.6、T1 − T2 = +176.4。两臂绝对值在两轮之间各漂 ~200 ns 而差只有 10–130 ns,**桌面 bench 分辨不出 P4a 这一档**;可引用的是 T1 ≈ +1.1 µs/draw 的总边界(Espryt)与设备侧三臂表。Magma 的 +176 ns 不是"Magma 在跑 P4a"(消费者门让它一条不发),是 tracker 多算的快门加噪声。
## 里程碑记录(原 `ROADMAP.md`)
- **P3a / P4a 出口(2026-09-08)**:各 1 天,远低于 27 / 39 天的再基线绊线,未触发重定基线。
## 本目录
| 文件 | 内容 |
|---|---|
| [`BRIEF-P4A.md`](BRIEF-P4A.md) | P4a implementation brief — handle wave 2 (Espryt): framebuffer, texture, renderbuffer, sampler, program identity and descriptors |
| [`INTEGRATOR-DECISIONS.md`](INTEGRATOR-DECISIONS.md) | P4a integrator decisions (feat/disaggregated, 2026-09-08) |
| [`scout-docs-spec.md`](scout-docs-spec.md) | P4a docs specification — everything `docs/Disaggregated/` says about handle wave 2 |
| [`scout-espryt-framebuffer.md`](scout-espryt-framebuffer.md) | Scout — Espryt's framebuffer / renderbuffer / texture surface that P4a converts |
| [`scout-espryt-sampler-program.md`](scout-espryt-sampler-program.md) | P4a scout — Espryt's sampler / image / program surface |
| [`scout-frontend-state.md`](scout-frontend-state.md) | Scout — the frontend (MG_State/GLState + MG_Impl/GLImpl) as P4a's client emission must read it |
| [`scout-pipe-and-client.md`](scout-pipe-and-client.md) | P4a scout — the MGPipe scaffolding and the P3a client conventions |
| [`ab/`](ab/) | 5 个文件:小米三臂 A/B(含前缀 `a38bdab4` 的一轮) |
| [`ab-redmi/`](ab-redmi/) | 2 个文件:Redmi 两臂 / 三臂 A/B |
| [`bench/`](bench/) | 1 个文件:DriverBench |
| [`p4a-results/`](p4a-results/) | 41 个文件:各包的实现、评审与终审修复稿(含 `finalfix-v1-logs/`) |
@@ -0,0 +1,27 @@
# P4a device A/B - per-thread CPU per frame (ms), best-of-3 repeat, trailing window
| device | case | backend | finish | pull p50 | P3a boundary (0x1ff) p50 | P4a (0x1fff) p50 | d P3a-boundary | d P4a total | pull p99 | P4a p99 | pins pull/1ff/P4a | mpr 1ff/P4a |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2f7cbe2e | improved-transparency-minecraft-26.3 | DirectGLES | on | 10.727 | - | 12.320 | - | +14.9% | 26.805 | 26.972 | P/P / - / P/P | - / 8 |
| 2f7cbe2e | improved-transparency-minecraft-26.3 | DirectGLES | off | 10.716 | 11.754 | 12.124 | +9.7% | +13.1% | 25.297 | 26.841 | P/P / P/P / P/P | 8 / 8 |
| 2f7cbe2e | improved-transparency-minecraft-26.3 | DirectVulkan | on | 10.634 | - | 11.570 | - | +8.8% | 24.975 | 25.958 | P/P / - / P/P | - / 0 |
| 2f7cbe2e | improved-transparency-minecraft-26.3 | DirectVulkan | off | 10.603 | 11.543 | 11.585 | +8.9% | +9.3% | 24.979 | 26.021 | P/P / P/P / P/P | 0 / 0 |
| 2f7cbe2e | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 1.759 | - | 1.839 | - | +4.5% | 322.670 | 320.204 | P/P / - / P/P | - / 2 |
| 2f7cbe2e | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 1.727 | 1.740 | 1.811 | +0.8% | +4.9% | 319.025 | 319.226 | P/P / P/P / P/P | 2 / 2 |
| 2f7cbe2e | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.736 | - | 0.788 | - | +7.1% | 455.587 | 462.612 | P/P / - / P/P | - / 0 |
| 2f7cbe2e | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.742 | 0.788 | 0.786 | +6.2% | +5.9% | 462.639 | 454.128 | P/P / P/P / P/P | 0 / 0 |
| 2f7cbe2e | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.312 | - | 1.458 | - | +11.1% | 2.370 | 2.554 | P/P / - / P/P | - / 1 |
| 2f7cbe2e | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.312 | 1.406 | 1.454 | +7.2% | +10.8% | 2.423 | 2.524 | P/P / P/P / P/P | 1 / 1 |
| 2f7cbe2e | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.477 | - | 0.504 | - | +5.7% | 1.174 | 1.179 | P/P / - / P/P | - / 0 |
| 2f7cbe2e | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.474 | 0.502 | 0.507 | +5.9% | +7.0% | 1.158 | 1.150 | P/P / P/P / P/P | 0 / 0 |
| 2f7cbe2e | minecraft-1.21.4-in-world | DirectGLES | on | 2.343 | - | 2.833 | - | +20.9% | 5.272 | 5.674 | P/P / - / P/P | - / 0 |
| 2f7cbe2e | minecraft-1.21.4-in-world | DirectGLES | off | 2.369 | 2.732 | 2.867 | +15.3% | +21.0% | 5.281 | 5.752 | P/P / P/P / P/P | 0 / 0 |
| 2f7cbe2e | minecraft-1.21.4-in-world | DirectVulkan | on | 1.034 | - | 1.148 | - | +11.0% | 2.304 | 2.405 | P/P / - / P/P | - / 0 |
| 2f7cbe2e | minecraft-1.21.4-in-world | DirectVulkan | off | 1.028 | 1.147 | 1.145 | +11.6% | +11.4% | 2.270 | 2.419 | P/P / P/P / P/P | 0 / 0 |
| 2f7cbe2e | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 8.315 | - | 11.223 | - | +35.0% | 21.901 | 24.904 | P/P / - / P/P | - / 0 |
| 2f7cbe2e | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 8.210 | 10.798 | 11.182 | +31.5% | +36.2% | 21.778 | 24.804 | P/P / P/P / P/P | 0 / 0 |
| 2f7cbe2e | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | on | - | - | - | - | - | - | - | P/P / - / P/P | - / None |
| 2f7cbe2e | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | off | - | - | - | - | - | - | - | P/P / P/P / P/P | None / None |
d P3a-boundary = push(0x1ff) vs pull; d P4a total = push(0x1fff) vs pull; the P4a-only share is the difference of the two.
A '-' p50 means the run produced no result (rc != 0); see the runner.log in that directory.
@@ -0,0 +1,68 @@
# P2 paired A/B - per-thread CPU per frame (ms), trailing window, push - pull
pin columns: before/after verdict per run (P=PINNED, D=DRIFT = a cluster clamped by thermal management, U=UNPINNED) @ cpuss temperature C
p50/p99: the runner's best-of-N repeat (lowest mean wall frame time), trailing tailFrames window, device median rule / nearest-rank p99; 'best' says which repeat
| device | case | backend | mode | pull p50 | push p50 | d p50 | pull p99 | push p99 | d p99 | frames | best pull/push | pull acc/draw | push acc/draw | pin pull | pin push |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 2f7cbe2e | improved-transparency-minecraft-26.3 | DirectGLES | finish | 10.727 | 12.320 | +1.593 | 26.805 | 26.972 | +0.167 | 200/200 | run 1/3 / run 2/3 | 8.39 | 6.39 | P@40.3/P@40.3 | P@41.1/P@40.7 |
| 2f7cbe2e | improved-transparency-minecraft-26.3 | DirectGLES | nofinish | 10.716 | 12.124 | +1.408 | 25.297 | 26.841 | +1.544 | 200/200 | run 3/3 / run 1/3 | 8.39 | 6.39 | P@39.1/P@41.5 | P@39.9/P@41.5 |
| 2f7cbe2e | improved-transparency-minecraft-26.3 | DirectVulkan | finish | 10.634 | 11.570 | +0.936 | 24.975 | 25.958 | +0.983 | 200/200 | run 2/3 / run 2/3 | 6.52 | 6.52 | P@41.5/P@42.6 | P@40.3/P@43.0 |
| 2f7cbe2e | improved-transparency-minecraft-26.3 | DirectVulkan | nofinish | 10.603 | 11.585 | +0.982 | 24.979 | 26.021 | +1.042 | 200/200 | run 2/3 / run 1/3 | 6.52 | 6.52 | P@41.5/P@41.8 | P@40.3/P@42.2 |
| 2f7cbe2e | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | finish | 1.759 | 1.839 | +0.080 | 322.670 | 320.204 | -2.466 | 123/123 | run 1/3 / run 2/3 | 40.95 | 39.07 | P@39.9/P@41.5 | P@41.5/P@41.8 |
| 2f7cbe2e | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | nofinish | 1.727 | 1.811 | +0.084 | 319.025 | 319.226 | +0.201 | 123/123 | run 2/3 / run 3/3 | 40.95 | 39.07 | P@41.1/P@42.2 | P@41.5/P@41.8 |
| 2f7cbe2e | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | finish | 0.736 | 0.788 | +0.052 | 455.587 | 462.612 | +7.025 | 123/123 | run 1/3 / run 2/3 | 14.25 | 14.25 | P@40.3/P@43.0 | P@40.3/P@42.6 |
| 2f7cbe2e | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | nofinish | 0.742 | 0.786 | +0.044 | 462.639 | 454.128 | -8.511 | 123/123 | run 1/3 / run 1/3 | 14.25 | 14.25 | P@41.5/P@42.6 | P@40.7/P@42.2 |
| 2f7cbe2e | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | finish | 1.312 | 1.458 | +0.146 | 2.370 | 2.554 | +0.184 | 200/200 | run 2/3 / run 1/3 | 15.64 | 13.52 | P@41.5/P@42.2 | P@41.1/P@42.2 |
| 2f7cbe2e | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | nofinish | 1.312 | 1.454 | +0.142 | 2.423 | 2.524 | +0.101 | 200/200 | run 3/3 / run 2/3 | 15.64 | 13.52 | P@41.1/P@42.2 | P@40.3/P@42.2 |
| 2f7cbe2e | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | finish | 0.477 | 0.504 | +0.027 | 1.174 | 1.179 | +0.005 | 200/200 | run 3/3 / run 1/3 | 19.51 | 19.51 | P@41.1/P@43.8 | P@40.7/P@43.8 |
| 2f7cbe2e | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | nofinish | 0.474 | 0.507 | +0.033 | 1.158 | 1.150 | -0.008 | 200/200 | run 3/3 / run 3/3 | 19.51 | 19.51 | P@41.5/P@43.8 | P@40.7/P@42.2 |
| 2f7cbe2e | minecraft-1.21.4-in-world | DirectGLES | finish | 2.343 | 2.833 | +0.490 | 5.272 | 5.674 | +0.402 | 200/200 | run 2/3 / run 3/3 | 9.4 | 7.44 | P@40.7/P@41.1 | P@41.8/P@41.8 |
| 2f7cbe2e | minecraft-1.21.4-in-world | DirectGLES | nofinish | 2.369 | 2.867 | +0.498 | 5.281 | 5.752 | +0.471 | 200/200 | run 1/3 / run 1/3 | 9.4 | 7.44 | P@40.3/P@42.2 | P@41.8/P@42.6 |
| 2f7cbe2e | minecraft-1.21.4-in-world | DirectVulkan | finish | 1.034 | 1.148 | +0.114 | 2.304 | 2.405 | +0.101 | 200/200 | run 1/3 / run 3/3 | 8.76 | 8.76 | P@40.3/P@42.6 | P@41.5/P@42.2 |
| 2f7cbe2e | minecraft-1.21.4-in-world | DirectVulkan | nofinish | 1.028 | 1.145 | +0.117 | 2.270 | 2.419 | +0.149 | 200/200 | run 1/3 / run 3/3 | 8.76 | 8.76 | P@40.3/P@42.6 | P@40.3/P@42.2 |
| 2f7cbe2e | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | finish | 8.315 | 11.223 | +2.908 | 21.901 | 24.904 | +3.003 | 200/200 | run 2/3 / run 1/3 | 8.08 | 6.08 | P@40.7/P@41.8 | P@40.7/P@43.4 |
| 2f7cbe2e | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | nofinish | 8.210 | 11.182 | +2.972 | 21.778 | 24.804 | +3.026 | 200/200 | run 1/3 / run 2/3 | 8.08 | 6.08 | P@40.7/P@43.4 | P@40.7/P@42.6 |
## GO/NO-GO reading (items 3-4: p50 and p99 per-thread CPU deltas must not be negative for the push arm, i.e. push must not cost more)
Windows where push costs MORE CPU than pull (d > 0):
- 2f7cbe2e / improved-transparency-minecraft-26.3 / DirectGLES / finish: d p50 +1.593 ms, d p99 +0.167 ms
- 2f7cbe2e / improved-transparency-minecraft-26.3 / DirectGLES / nofinish: d p50 +1.408 ms, d p99 +1.544 ms
- 2f7cbe2e / improved-transparency-minecraft-26.3 / DirectVulkan / finish: d p50 +0.936 ms, d p99 +0.983 ms
- 2f7cbe2e / improved-transparency-minecraft-26.3 / DirectVulkan / nofinish: d p50 +0.982 ms, d p99 +1.042 ms
- 2f7cbe2e / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectGLES / finish: d p50 +0.080 ms, d p99 -2.466 ms
- 2f7cbe2e / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectGLES / nofinish: d p50 +0.084 ms, d p99 +0.201 ms
- 2f7cbe2e / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectVulkan / finish: d p50 +0.052 ms, d p99 +7.025 ms
- 2f7cbe2e / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectVulkan / nofinish: d p50 +0.044 ms, d p99 -8.511 ms
- 2f7cbe2e / minecraft-1.21.4-fabric-sodium-in-world / DirectGLES / finish: d p50 +0.146 ms, d p99 +0.184 ms
- 2f7cbe2e / minecraft-1.21.4-fabric-sodium-in-world / DirectGLES / nofinish: d p50 +0.142 ms, d p99 +0.101 ms
- 2f7cbe2e / minecraft-1.21.4-fabric-sodium-in-world / DirectVulkan / finish: d p50 +0.027 ms, d p99 +0.005 ms
- 2f7cbe2e / minecraft-1.21.4-fabric-sodium-in-world / DirectVulkan / nofinish: d p50 +0.033 ms, d p99 -0.008 ms
- 2f7cbe2e / minecraft-1.21.4-in-world / DirectGLES / finish: d p50 +0.490 ms, d p99 +0.402 ms
- 2f7cbe2e / minecraft-1.21.4-in-world / DirectGLES / nofinish: d p50 +0.498 ms, d p99 +0.471 ms
- 2f7cbe2e / minecraft-1.21.4-in-world / DirectVulkan / finish: d p50 +0.114 ms, d p99 +0.101 ms
- 2f7cbe2e / minecraft-1.21.4-in-world / DirectVulkan / nofinish: d p50 +0.117 ms, d p99 +0.149 ms
- 2f7cbe2e / minecraft-1.21.4-rd12-odinlite-in-world / DirectGLES / finish: d p50 +2.908 ms, d p99 +3.003 ms
- 2f7cbe2e / minecraft-1.21.4-rd12-odinlite-in-world / DirectGLES / nofinish: d p50 +2.972 ms, d p99 +3.026 ms
## Memo gates, residual bytes and CSO counters (last complete window, push arm)
- 2f7cbe2e / improved-transparency-minecraft-26.3 / DirectGLES / finish: gates[ers=78960/1367 etl=75258/5069 eub=80327/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/8
- 2f7cbe2e / improved-transparency-minecraft-26.3 / DirectGLES / nofinish: gates[ers=78960/1367 etl=75258/5069 eub=80327/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/8
- 2f7cbe2e / improved-transparency-minecraft-26.3 / DirectVulkan / finish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=10740/68928 mpm=67660/1268 mdt=78800/868] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/0
- 2f7cbe2e / improved-transparency-minecraft-26.3 / DirectVulkan / nofinish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=10740/68928 mpm=67660/1268 mdt=78800/868] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectGLES / finish: gates[ers=113/133 etl=80/166 eub=246/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=370.67 csom/csob=csom=1/csob=122 mpr(last window/total)=0/2
- 2f7cbe2e / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectGLES / nofinish: gates[ers=113/133 etl=80/166 eub=246/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=370.67 csom/csob=csom=1/csob=122 mpr(last window/total)=0/2
- 2f7cbe2e / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectVulkan / finish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/177 mpm=86/91 mdt=81/96] resid=370.67 csom/csob=csom=1/csob=122 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectVulkan / nofinish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/177 mpm=86/91 mdt=81/96] resid=370.67 csom/csob=csom=1/csob=122 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-fabric-sodium-in-world / DirectGLES / finish: gates[ers=81/859 etl=244/696 eub=940/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=171.8 csom/csob=csom=2/csob=811 mpr(last window/total)=0/1
- 2f7cbe2e / minecraft-1.21.4-fabric-sodium-in-world / DirectGLES / nofinish: gates[ers=81/859 etl=244/696 eub=940/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=171.8 csom/csob=csom=2/csob=811 mpr(last window/total)=0/1
- 2f7cbe2e / minecraft-1.21.4-fabric-sodium-in-world / DirectVulkan / finish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/657 mpm=109/548 mdt=0/657] resid=171.8 csom/csob=csom=2/csob=811 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-fabric-sodium-in-world / DirectVulkan / nofinish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/657 mpm=109/548 mdt=0/657] resid=171.8 csom/csob=csom=2/csob=811 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-in-world / DirectGLES / finish: gates[ers=6020/1850 etl=6411/1459 eub=7870/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=178.31 csom/csob=csom=2/csob=1719 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-in-world / DirectGLES / nofinish: gates[ers=6020/1850 etl=6411/1459 eub=7870/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=178.31 csom/csob=csom=2/csob=1719 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-in-world / DirectVulkan / finish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/7278 mpm=6030/1248 mdt=5928/1350] resid=178.31 csom/csob=csom=2/csob=1719 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-in-world / DirectVulkan / nofinish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/7278 mpm=6030/1248 mdt=5928/1350] resid=178.31 csom/csob=csom=2/csob=1719 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-rd12-odinlite-in-world / DirectGLES / finish: gates[ers=16038/224 etl=16104/158 eub=16262/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=162.91 csom/csob=csom=0/csob=209 mpr(last window/total)=0/0
- 2f7cbe2e / minecraft-1.21.4-rd12-odinlite-in-world / DirectGLES / nofinish: gates[ers=16038/224 etl=16104/158 eub=16262/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=162.91 csom/csob=csom=0/csob=209 mpr(last window/total)=0/0
+73
View File
@@ -0,0 +1,73 @@
# P2 paired A/B - per-thread CPU per frame (ms), trailing window, push - pull
pin columns: before/after verdict per run (P=PINNED, D=DRIFT = a cluster clamped by thermal management, U=UNPINNED) @ cpuss temperature C
p50/p99: the runner's best-of-N repeat (lowest mean wall frame time), trailing tailFrames window, device median rule / nearest-rank p99; 'best' says which repeat
| device | case | backend | mode | pull p50 | push p50 | d p50 | pull p99 | push p99 | d p99 | frames | best pull/push | pull acc/draw | push acc/draw | pin pull | pin push |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | finish | 10.797 | 12.363 | +1.566 | 25.557 | 27.004 | +1.447 | 200/200 | run 1/3 / run 1/3 | 8.39 | 6.39 | P@47.8/P@50.5 | P@50.2/P@50.5 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | nofinish | 10.759 | 12.431 | +1.672 | 25.406 | 27.013 | +1.607 | 200/200 | run 1/3 / run 1/3 | 8.39 | 6.39 | P@43.6/P@48.6 | P@49.8/P@51.3 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | finish | 10.729 | 11.591 | +0.862 | 24.924 | 25.976 | +1.052 | 200/200 | run 3/3 / run 3/3 | 6.52 | 6.52 | P@52.1/P@50.2 | P@52.1/P@53.6 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | nofinish | 10.671 | 11.583 | +0.912 | 25.034 | 26.117 | +1.083 | 200/200 | run 2/3 / run 1/3 | 6.52 | 6.52 | P@49.8/P@52.5 | P@50.2/P@53.2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | finish | 1.702 | 1.346 | -0.356 | 315.989 | 316.342 | +0.353 | 123/123 | run 3/3 / run 1/3 | 40.95 | 39.07 | P@50.2/P@52.5 | P@45.1/P@49.8 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | nofinish | 1.304 | 1.946 | +0.642 | 317.280 | 317.310 | +0.030 | 123/123 | run 2/3 / run 2/3 | 40.95 | 39.07 | P@45.5/P@49.4 | P@45.9/P@49.0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | finish | 0.722 | 0.817 | +0.095 | 459.039 | 447.908 | -11.131 | 123/123 | run 1/3 / run 1/3 | 14.25 | 14.25 | P@44.8/P@50.9 | P@44.8/P@50.9 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | nofinish | 0.763 | 0.794 | +0.031 | 453.873 | 451.470 | -2.403 | 123/123 | run 3/3 / run 1/3 | 14.25 | 14.25 | P@45.1/P@51.3 | P@45.1/P@49.4 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | finish | 1.285 | 1.446 | +0.161 | 2.436 | 2.715 | +0.279 | 200/200 | run 2/3 / run 2/3 | 15.64 | 13.52 | P@44.8/P@47.8 | P@50.2/P@50.5 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | nofinish | 1.380 | 1.440 | +0.060 | 2.455 | 2.493 | +0.038 | 200/200 | run 1/3 / run 3/3 | 15.64 | 13.52 | P@44.8/P@47.5 | P@45.5/P@46.3 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | finish | 0.961 | 1.037 | +0.076 | 2.086 | 2.097 | +0.011 | 200/200 | run 2/3 / run 3/3 | 19.51 | 19.51 | P@47.1/P@51.7 | P@51.7/P@52.5 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | nofinish | 0.944 | 0.522 | -0.422 | 1.992 | 1.337 | -0.655 | 200/200 | run 1/3 / run 1/3 | 19.51 | 19.51 | P@45.5/P@49.0 | P@50.9/P@52.1 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | finish | 2.362 | 2.853 | +0.491 | 5.184 | 5.683 | +0.499 | 200/200 | run 2/3 / run 3/3 | 9.4 | 7.44 | P@45.5/P@49.8 | P@45.1/P@49.8 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | nofinish | 2.341 | 2.841 | +0.500 | 5.183 | 5.633 | +0.450 | 200/200 | run 1/3 / run 3/3 | 9.4 | 7.44 | P@45.5/P@49.8 | P@45.1/P@49.4 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | finish | 1.966 | 1.802 | -0.164 | 4.256 | 4.369 | +0.113 | 200/200 | run 1/3 / run 1/3 | 8.76 | 8.76 | P@45.9/P@49.0 | P@45.9/P@49.0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | nofinish | 1.050 | 1.735 | +0.685 | 2.363 | 5.902 | +3.539 | 200/200 | run 1/3 / run 1/3 | 8.76 | 8.76 | P@45.5/P@48.6 | P@45.9/P@49.4 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | finish | 8.221 | 11.253 | +3.032 | 23.081 | 24.987 | +1.906 | 200/200 | run 3/3 / run 1/3 | 8.08 | 6.08 | P@41.3/P@49.4 | P@45.1/P@52.9 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | nofinish | 8.236 | 11.204 | +2.968 | 21.918 | 24.882 | +2.964 | 200/200 | run 2/3 / run 1/3 | 8.08 | 6.08 | P@52.1/P@54.8 | P@45.1/P@53.2 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | finish | 9.857 | 11.404 | +1.547 | 26.125 | 27.013 | +0.888 | 200/200 | run 1/3 / run 1/3 | 8.39 | 6.39 | P@50.5/P@50.0 | P@49.3/P@47.8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | nofinish | incomplete: push |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | nofinish | incomplete: pull |
## GO/NO-GO reading (items 3-4: p50 and p99 per-thread CPU deltas must not be negative for the push arm, i.e. push must not cost more)
Windows where push costs MORE CPU than pull (d > 0):
- 35d0befa / improved-transparency-minecraft-26.3 / DirectGLES / finish: d p50 +1.566 ms, d p99 +1.447 ms
- 35d0befa / improved-transparency-minecraft-26.3 / DirectGLES / nofinish: d p50 +1.672 ms, d p99 +1.607 ms
- 35d0befa / improved-transparency-minecraft-26.3 / DirectVulkan / finish: d p50 +0.862 ms, d p99 +1.052 ms
- 35d0befa / improved-transparency-minecraft-26.3 / DirectVulkan / nofinish: d p50 +0.912 ms, d p99 +1.083 ms
- 35d0befa / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectGLES / finish: d p50 -0.356 ms, d p99 +0.353 ms
- 35d0befa / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectGLES / nofinish: d p50 +0.642 ms, d p99 +0.030 ms
- 35d0befa / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectVulkan / finish: d p50 +0.095 ms, d p99 -11.131 ms
- 35d0befa / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectVulkan / nofinish: d p50 +0.031 ms, d p99 -2.403 ms
- 35d0befa / minecraft-1.21.4-fabric-sodium-in-world / DirectGLES / finish: d p50 +0.161 ms, d p99 +0.279 ms
- 35d0befa / minecraft-1.21.4-fabric-sodium-in-world / DirectGLES / nofinish: d p50 +0.060 ms, d p99 +0.038 ms
- 35d0befa / minecraft-1.21.4-fabric-sodium-in-world / DirectVulkan / finish: d p50 +0.076 ms, d p99 +0.011 ms
- 35d0befa / minecraft-1.21.4-in-world / DirectGLES / finish: d p50 +0.491 ms, d p99 +0.499 ms
- 35d0befa / minecraft-1.21.4-in-world / DirectGLES / nofinish: d p50 +0.500 ms, d p99 +0.450 ms
- 35d0befa / minecraft-1.21.4-in-world / DirectVulkan / finish: d p50 -0.164 ms, d p99 +0.113 ms
- 35d0befa / minecraft-1.21.4-in-world / DirectVulkan / nofinish: d p50 +0.685 ms, d p99 +3.539 ms
- 35d0befa / minecraft-1.21.4-rd12-odinlite-in-world / DirectGLES / finish: d p50 +3.032 ms, d p99 +1.906 ms
- 35d0befa / minecraft-1.21.4-rd12-odinlite-in-world / DirectGLES / nofinish: d p50 +2.968 ms, d p99 +2.964 ms
- 3B159D009VZ00000 / improved-transparency-minecraft-26.3 / DirectGLES / finish: d p50 +1.547 ms, d p99 +0.888 ms
## Memo gates, residual bytes and CSO counters (last complete window, push arm)
- 35d0befa / improved-transparency-minecraft-26.3 / DirectGLES / finish: gates[ers=78960/1367 etl=75258/5069 eub=80327/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/8
- 35d0befa / improved-transparency-minecraft-26.3 / DirectGLES / nofinish: gates[ers=78960/1367 etl=75258/5069 eub=80327/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/8
- 35d0befa / improved-transparency-minecraft-26.3 / DirectVulkan / finish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=10740/68928 mpm=67660/1268 mdt=78800/868] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/0
- 35d0befa / improved-transparency-minecraft-26.3 / DirectVulkan / nofinish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=10740/68928 mpm=67660/1268 mdt=78800/868] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectGLES / finish: gates[ers=113/133 etl=80/166 eub=246/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=370.67 csom/csob=csom=1/csob=122 mpr(last window/total)=0/2
- 35d0befa / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectGLES / nofinish: gates[ers=113/133 etl=80/166 eub=246/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=370.67 csom/csob=csom=1/csob=122 mpr(last window/total)=0/2
- 35d0befa / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectVulkan / finish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/177 mpm=86/91 mdt=81/96] resid=370.67 csom/csob=csom=1/csob=122 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-fabric-iris-bsl-in-world / DirectVulkan / nofinish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/177 mpm=86/91 mdt=81/96] resid=370.67 csom/csob=csom=1/csob=122 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-fabric-sodium-in-world / DirectGLES / finish: gates[ers=81/859 etl=244/696 eub=940/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=171.8 csom/csob=csom=2/csob=811 mpr(last window/total)=0/1
- 35d0befa / minecraft-1.21.4-fabric-sodium-in-world / DirectGLES / nofinish: gates[ers=81/859 etl=244/696 eub=940/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=171.8 csom/csob=csom=2/csob=811 mpr(last window/total)=0/1
- 35d0befa / minecraft-1.21.4-fabric-sodium-in-world / DirectVulkan / finish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/657 mpm=109/548 mdt=0/657] resid=171.8 csom/csob=csom=2/csob=811 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-fabric-sodium-in-world / DirectVulkan / nofinish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/657 mpm=109/548 mdt=0/657] resid=171.8 csom/csob=csom=2/csob=811 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-in-world / DirectGLES / finish: gates[ers=6020/1850 etl=6411/1459 eub=7870/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=178.31 csom/csob=csom=2/csob=1719 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-in-world / DirectGLES / nofinish: gates[ers=6020/1850 etl=6411/1459 eub=7870/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=178.31 csom/csob=csom=2/csob=1719 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-in-world / DirectVulkan / finish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/7278 mpm=6030/1248 mdt=5928/1350] resid=178.31 csom/csob=csom=2/csob=1719 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-in-world / DirectVulkan / nofinish: gates[ers=0/0 etl=0/0 eub=0/0 mfp=0/7278 mpm=6030/1248 mdt=5928/1350] resid=178.31 csom/csob=csom=2/csob=1719 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-rd12-odinlite-in-world / DirectGLES / finish: gates[ers=16038/224 etl=16104/158 eub=16262/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=162.91 csom/csob=csom=0/csob=209 mpr(last window/total)=0/0
- 35d0befa / minecraft-1.21.4-rd12-odinlite-in-world / DirectGLES / nofinish: gates[ers=16038/224 etl=16104/158 eub=16262/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=162.91 csom/csob=csom=0/csob=209 mpr(last window/total)=0/0
- 3B159D009VZ00000 / improved-transparency-minecraft-26.3 / DirectGLES / finish: gates[ers=78960/1367 etl=75258/5069 eub=80327/0 mfp=0/0 mpm=0/0 mdt=0/0] resid=185.36 csom/csob=csom=0/csob=1157 mpr(last window/total)=0/8
- 3B159D009VZ00000 / improved-transparency-minecraft-26.3 / DirectGLES / nofinish: gates[-] resid=- csom/csob=-/- mpr(last window/total)=-/None
@@ -0,0 +1,49 @@
# P4a device A/B - per-thread CPU per frame (ms), best-of-3 repeat, trailing window
| device | case | backend | finish | pull p50 | P3a boundary (0x1ff) p50 | P4a (0x1fff) p50 | d P3a-boundary | d P4a total | pull p99 | P4a p99 | pins pull/1ff/P4a | mpr 1ff/P4a |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | on | 10.797 | - | 12.363 | - | +14.5% | 25.557 | 27.004 | P/P / - / P/P | - / 8 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | off | 10.759 | 11.857 | 12.431 | +10.2% | +15.5% | 25.406 | 27.013 | P/P / P/P / P/P | 8 / 8 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | on | 10.729 | - | 11.591 | - | +8.0% | 24.924 | 25.976 | P/P / - / P/P | - / 0 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | off | 10.671 | 11.526 | 11.583 | +8.0% | +8.5% | 25.034 | 26.117 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 1.702 | - | 1.346 | - | -20.9% | 315.989 | 316.342 | P/P / - / P/P | - / 2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 1.304 | 1.861 | 1.946 | +42.7% | +49.2% | 317.280 | 317.310 | P/P / P/P / P/P | 2 / 2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.722 | - | 0.817 | - | +13.2% | 459.039 | 447.908 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.763 | 0.784 | 0.794 | +2.8% | +4.1% | 453.873 | 451.470 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.285 | - | 1.446 | - | +12.5% | 2.436 | 2.715 | P/P / - / P/P | - / 1 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.380 | 1.398 | 1.440 | +1.3% | +4.3% | 2.455 | 2.493 | P/P / P/P / P/P | 1 / 1 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.961 | - | 1.037 | - | +7.9% | 2.086 | 2.097 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.944 | 1.010 | 0.522 | +7.0% | -44.7% | 1.992 | 1.337 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | on | 2.362 | - | 2.853 | - | +20.8% | 5.184 | 5.683 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | off | 2.341 | 2.724 | 2.841 | +16.4% | +21.4% | 5.183 | 5.633 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | on | 1.966 | - | 1.802 | - | -8.3% | 4.256 | 4.369 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | off | 1.050 | 1.154 | 1.735 | +9.9% | +65.2% | 2.363 | 5.902 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 8.221 | - | 11.253 | - | +36.9% | 23.081 | 24.987 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 8.236 | 10.840 | 11.204 | +31.6% | +36.0% | 21.918 | 24.882 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | on | 9.733 | - | 11.230 | - | +15.4% | 26.133 | 28.727 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | off | 9.819 | 10.660 | 11.224 | +8.6% | +14.3% | 26.154 | 26.980 | P/P / P/P / P/P | 8 / 8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | on | 8.165 | - | 9.267 | - | +13.5% | 22.985 | 23.979 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | off | 8.267 | 9.236 | 9.189 | +11.7% | +11.2% | 22.852 | 23.921 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 2.205 | - | 2.550 | - | +15.6% | 233.721 | 230.771 | P/P / - / P/P | - / 2 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 2.215 | 2.407 | 2.502 | +8.7% | +13.0% | 230.013 | 230.830 | P/P / P/P / P/P | 2 / 2 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.641 | - | 0.649 | - | +1.2% | 262.991 | 266.935 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.644 | 0.697 | 0.707 | +8.2% | +9.8% | 263.017 | 263.919 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.724 | - | 1.951 | - | +13.2% | 3.170 | 3.177 | P/P / - / P/P | - / 1 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.697 | 1.835 | 1.917 | +8.1% | +13.0% | 2.927 | 3.116 | P/P / P/P / P/P | 1 / 1 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.417 | - | 0.446 | - | +7.0% | 1.126 | 1.152 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.430 | 0.474 | 0.447 | +10.2% | +4.0% | 1.221 | 1.135 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectGLES | on | 2.957 | - | 3.579 | - | +21.0% | 4.878 | 5.638 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectGLES | off | 2.892 | 3.365 | 3.521 | +16.4% | +21.7% | 4.925 | 5.772 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectVulkan | on | 0.898 | - | 1.035 | - | +15.3% | 2.065 | 2.234 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectVulkan | off | 0.893 | 1.029 | 1.040 | +15.2% | +16.5% | 2.050 | 2.215 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 9.863 | - | 15.390 | - | +56.0% | 27.202 | 29.596 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 10.027 | 13.003 | 12.967 | +29.7% | +29.3% | 27.715 | 28.130 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | on | 7.681 | - | 10.662 | - | +38.8% | 23.912 | 28.533 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | off | 7.891 | 9.959 | 10.415 | +26.2% | +32.0% | 25.083 | 28.348 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectGLES | on | 9.857 | - | 11.404 | - | +15.7% | 26.125 | 27.013 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectGLES | off | 9.601 | - | 11.487 | - | +19.6% | 26.230 | 27.477 | P/P / - / P/P | - / None |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectVulkan | on | - | - | - | - | - | - | - | P/? / - / - | - / - |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectVulkan | off | 8.197 | - | - | - | - | 23.349 | - | P/P / - / - | - / - |
d P3a-boundary = push(0x1ff) vs pull; d P4a total = push(0x1fff) vs pull; the P4a-only share is the difference of the two.
A '-' p50 means the run produced no result (rc != 0); see the runner.log in that directory.
@@ -0,0 +1,49 @@
# P4a device A/B - per-thread CPU per frame (ms), best-of-3 repeat, trailing window
| device | case | backend | finish | pull p50 | P3a boundary (0x1ff) p50 | P4a (0x1fff) p50 | d P3a-boundary | d P4a total | pull p99 | P4a p99 | pins pull/1ff/P4a | mpr 1ff/P4a |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | on | 10.797 | - | 12.363 | - | +14.5% | 25.557 | 27.004 | P/P / - / P/P | - / 8 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | off | 10.759 | 11.857 | 12.431 | +10.2% | +15.5% | 25.406 | 27.013 | P/P / P/P / P/P | 8 / 8 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | on | 10.729 | - | 11.591 | - | +8.0% | 24.924 | 25.976 | P/P / - / P/P | - / 0 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | off | 10.671 | 11.526 | 11.583 | +8.0% | +8.5% | 25.034 | 26.117 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 1.702 | - | 1.346 | - | -20.9% | 315.989 | 316.342 | P/P / - / P/P | - / 2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 1.304 | 1.861 | 1.946 | +42.7% | +49.2% | 317.280 | 317.310 | P/P / P/P / P/P | 2 / 2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.722 | - | 0.817 | - | +13.2% | 459.039 | 447.908 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.763 | 0.784 | 0.794 | +2.8% | +4.1% | 453.873 | 451.470 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.285 | - | 1.446 | - | +12.5% | 2.436 | 2.715 | P/P / - / P/P | - / 1 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.380 | 1.398 | 1.440 | +1.3% | +4.3% | 2.455 | 2.493 | P/P / P/P / P/P | 1 / 1 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.961 | - | 1.037 | - | +7.9% | 2.086 | 2.097 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.944 | 1.010 | 0.522 | +7.0% | -44.7% | 1.992 | 1.337 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | on | 2.362 | - | 2.853 | - | +20.8% | 5.184 | 5.683 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | off | 2.341 | 2.724 | 2.841 | +16.4% | +21.4% | 5.183 | 5.633 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | on | 1.966 | - | 1.802 | - | -8.3% | 4.256 | 4.369 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | off | 1.050 | 1.154 | 1.735 | +9.9% | +65.2% | 2.363 | 5.902 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 8.221 | - | 11.253 | - | +36.9% | 23.081 | 24.987 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 8.236 | 10.840 | 11.204 | +31.6% | +36.0% | 21.918 | 24.882 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | on | 9.733 | - | 11.230 | - | +15.4% | 26.133 | 28.727 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | off | 9.819 | - | 11.224 | - | +14.3% | 26.154 | 26.980 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | on | 8.165 | - | 9.267 | - | +13.5% | 22.985 | 23.979 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | off | 8.267 | - | 9.189 | - | +11.2% | 22.852 | 23.921 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 2.205 | - | 2.550 | - | +15.6% | 233.721 | 230.771 | P/P / - / P/P | - / 2 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 2.215 | - | 2.502 | - | +13.0% | 230.013 | 230.830 | P/P / - / P/P | - / 2 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.641 | - | 0.649 | - | +1.2% | 262.991 | 266.935 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.644 | - | 0.707 | - | +9.8% | 263.017 | 263.919 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.724 | - | 1.951 | - | +13.2% | 3.170 | 3.177 | P/P / - / P/P | - / 1 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.697 | - | 1.917 | - | +13.0% | 2.927 | 3.116 | P/P / - / P/P | - / 1 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.417 | - | 0.446 | - | +7.0% | 1.126 | 1.152 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.430 | - | 0.447 | - | +4.0% | 1.221 | 1.135 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectGLES | on | 2.957 | - | 3.579 | - | +21.0% | 4.878 | 5.638 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectGLES | off | 2.892 | - | 3.521 | - | +21.7% | 4.925 | 5.772 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectVulkan | on | 0.898 | - | 1.035 | - | +15.3% | 2.065 | 2.234 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectVulkan | off | 0.893 | - | 1.040 | - | +16.5% | 2.050 | 2.215 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 9.863 | - | 15.390 | - | +56.0% | 27.202 | 29.596 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 10.027 | - | 12.967 | - | +29.3% | 27.715 | 28.130 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | on | 7.681 | - | 10.662 | - | +38.8% | 23.912 | 28.533 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | off | 7.891 | - | 10.415 | - | +32.0% | 25.083 | 28.348 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectGLES | on | 9.857 | - | 11.404 | - | +15.7% | 26.125 | 27.013 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectGLES | off | 9.601 | - | 11.487 | - | +19.6% | 26.230 | 27.477 | P/P / - / P/P | - / None |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectVulkan | on | - | - | - | - | - | - | - | P/? / - / - | - / - |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectVulkan | off | 8.197 | - | - | - | - | 23.349 | - | P/P / - / - | - / - |
d P3a-boundary = push(0x1ff) vs pull; d P4a total = push(0x1fff) vs pull; the P4a-only share is the difference of the two.
A '-' p50 means the run produced no result (rc != 0); see the runner.log in that directory.
@@ -0,0 +1,49 @@
# P4a device A/B - per-thread CPU per frame (ms), best-of-3 repeat, trailing window
| device | case | backend | finish | pull p50 | P3a boundary (0x1ff) p50 | P4a (0x1fff) p50 | d P3a-boundary | d P4a total | pull p99 | P4a p99 | pins pull/1ff/P4a | mpr 1ff/P4a |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | on | 10.797 | - | 12.363 | - | +14.5% | 25.557 | 27.004 | P/P / - / P/P | - / 8 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | off | 10.759 | 11.857 | 12.431 | +10.2% | +15.5% | 25.406 | 27.013 | P/P / P/P / P/P | 8 / 8 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | on | 10.729 | - | 11.591 | - | +8.0% | 24.924 | 25.976 | P/P / - / P/P | - / 0 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | off | 10.671 | 11.526 | 11.583 | +8.0% | +8.5% | 25.034 | 26.117 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 1.702 | - | 1.346 | - | -20.9% | 315.989 | 316.342 | P/P / - / P/P | - / 2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 1.304 | 1.861 | 1.946 | +42.7% | +49.2% | 317.280 | 317.310 | P/P / P/P / P/P | 2 / 2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.722 | - | 0.817 | - | +13.2% | 459.039 | 447.908 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.763 | 0.784 | 0.794 | +2.8% | +4.1% | 453.873 | 451.470 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.285 | - | 1.446 | - | +12.5% | 2.436 | 2.715 | P/P / - / P/P | - / 1 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.380 | 1.398 | 1.440 | +1.3% | +4.3% | 2.455 | 2.493 | P/P / P/P / P/P | 1 / 1 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.961 | - | 1.037 | - | +7.9% | 2.086 | 2.097 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.944 | 1.010 | 0.522 | +7.0% | -44.7% | 1.992 | 1.337 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | on | 2.362 | - | 2.853 | - | +20.8% | 5.184 | 5.683 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | off | 2.341 | 2.724 | 2.841 | +16.4% | +21.4% | 5.183 | 5.633 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | on | 1.966 | - | 1.802 | - | -8.3% | 4.256 | 4.369 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | off | 1.050 | 1.154 | 1.735 | +9.9% | +65.2% | 2.363 | 5.902 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 8.221 | - | 11.253 | - | +36.9% | 23.081 | 24.987 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 8.236 | 10.840 | 11.204 | +31.6% | +36.0% | 21.918 | 24.882 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | on | 9.733 | - | 11.230 | - | +15.4% | 26.133 | 28.727 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | off | 9.819 | 10.660 | 11.224 | +8.6% | +14.3% | 26.154 | 26.980 | P/P / P/P / P/P | 8 / 8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | on | 8.165 | - | 9.267 | - | +13.5% | 22.985 | 23.979 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | off | 8.267 | 9.236 | 9.189 | +11.7% | +11.2% | 22.852 | 23.921 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 2.205 | - | 2.550 | - | +15.6% | 233.721 | 230.771 | P/P / - / P/P | - / 2 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 2.215 | 2.407 | 2.502 | +8.7% | +13.0% | 230.013 | 230.830 | P/P / P/P / P/P | 2 / 2 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.641 | - | 0.649 | - | +1.2% | 262.991 | 266.935 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.644 | 0.697 | 0.707 | +8.2% | +9.8% | 263.017 | 263.919 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.724 | - | 1.951 | - | +13.2% | 3.170 | 3.177 | P/P / - / P/P | - / 1 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.697 | 1.835 | 1.917 | +8.1% | +13.0% | 2.927 | 3.116 | P/P / P/P / P/P | 1 / 1 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.417 | - | 0.446 | - | +7.0% | 1.126 | 1.152 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.430 | 0.474 | 0.447 | +10.2% | +4.0% | 1.221 | 1.135 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectGLES | on | 2.957 | - | 3.579 | - | +21.0% | 4.878 | 5.638 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectGLES | off | 2.892 | 3.365 | 3.521 | +16.4% | +21.7% | 4.925 | 5.772 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectVulkan | on | 0.898 | - | 1.035 | - | +15.3% | 2.065 | 2.234 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectVulkan | off | 0.893 | 1.029 | 1.040 | +15.2% | +16.5% | 2.050 | 2.215 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 9.863 | - | 15.390 | - | +56.0% | 27.202 | 29.596 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 10.027 | 13.003 | 12.967 | +29.7% | +29.3% | 27.715 | 28.130 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | on | 7.681 | - | 10.662 | - | +38.8% | 23.912 | 28.533 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | off | 7.891 | 9.959 | 10.415 | +26.2% | +32.0% | 25.083 | 28.348 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectGLES | on | 9.857 | - | 11.404 | - | +15.7% | 26.125 | 27.013 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectGLES | off | 9.601 | - | 11.487 | - | +19.6% | 26.230 | 27.477 | P/P / - / P/P | - / None |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectVulkan | on | - | - | - | - | - | - | - | P/? / - / - | - / - |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectVulkan | off | 8.197 | - | - | - | - | 23.349 | - | P/P / - / - | - / - |
d P3a-boundary = push(0x1ff) vs pull; d P4a total = push(0x1fff) vs pull; the P4a-only share is the difference of the two.
A '-' p50 means the run produced no result (rc != 0); see the runner.log in that directory.
+49
View File
@@ -0,0 +1,49 @@
# P4a device A/B - per-thread CPU per frame (ms), best-of-3 repeat, trailing window
| device | case | backend | finish | pull p50 | P3a boundary (0x1ff) p50 | P4a (0x1fff) p50 | d P3a-boundary | d P4a total | pull p99 | P4a p99 | pins pull/1ff/P4a | mpr 1ff/P4a |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | on | 10.797 | - | 12.363 | - | +14.5% | 25.557 | 27.004 | P/P / - / P/P | - / 8 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectGLES | off | 10.759 | 11.857 | 12.431 | +10.2% | +15.5% | 25.406 | 27.013 | P/P / P/P / P/P | 8 / 8 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | on | 10.729 | - | 11.591 | - | +8.0% | 24.924 | 25.976 | P/P / - / P/P | - / 0 |
| 35d0befa | improved-transparency-minecraft-26.3 | DirectVulkan | off | 10.671 | 11.526 | 11.583 | +8.0% | +8.5% | 25.034 | 26.117 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 1.702 | - | 1.346 | - | -20.9% | 315.989 | 316.342 | P/P / - / P/P | - / 2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 1.304 | 1.861 | 1.946 | +42.7% | +49.2% | 317.280 | 317.310 | P/P / P/P / P/P | 2 / 2 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.722 | - | 0.817 | - | +13.2% | 459.039 | 447.908 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.763 | 0.784 | 0.794 | +2.8% | +4.1% | 453.873 | 451.470 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.285 | - | 1.446 | - | +12.5% | 2.436 | 2.715 | P/P / - / P/P | - / 1 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.380 | 1.398 | 1.440 | +1.3% | +4.3% | 2.455 | 2.493 | P/P / P/P / P/P | 1 / 1 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.961 | - | 1.037 | - | +7.9% | 2.086 | 2.097 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.944 | 1.010 | 0.522 | +7.0% | -44.7% | 1.992 | 1.337 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | on | 2.362 | - | 2.853 | - | +20.8% | 5.184 | 5.683 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectGLES | off | 2.341 | 2.724 | 2.841 | +16.4% | +21.4% | 5.183 | 5.633 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | on | 1.966 | - | 1.802 | - | -8.3% | 4.256 | 4.369 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-in-world | DirectVulkan | off | 1.050 | 1.154 | 1.735 | +9.9% | +65.2% | 2.363 | 5.902 | P/P / P/P / P/P | 0 / 0 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 8.221 | - | 11.253 | - | +36.9% | 23.081 | 24.987 | P/P / - / P/P | - / 0 |
| 35d0befa | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 8.236 | 10.840 | 11.204 | +31.6% | +36.0% | 21.918 | 24.882 | P/P / P/P / P/P | 0 / 0 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | on | 9.733 | - | 11.230 | - | +15.4% | 26.133 | 28.727 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectGLES | off | 9.819 | - | 11.224 | - | +14.3% | 26.154 | 26.980 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | on | 8.165 | - | 9.267 | - | +13.5% | 22.985 | 23.979 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | improved-transparency-minecraft-26.3 | DirectVulkan | off | 8.267 | - | 9.189 | - | +11.2% | 22.852 | 23.921 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | on | 2.205 | - | 2.550 | - | +15.6% | 233.721 | 230.771 | P/P / - / P/P | - / 2 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectGLES | off | 2.215 | - | 2.502 | - | +13.0% | 230.013 | 230.830 | P/P / - / P/P | - / 2 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | on | 0.641 | - | 0.649 | - | +1.2% | 262.991 | 266.935 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-iris-bsl-in-world | DirectVulkan | off | 0.644 | - | 0.707 | - | +9.8% | 263.017 | 263.919 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | on | 1.724 | - | 1.951 | - | +13.2% | 3.170 | 3.177 | P/P / - / P/P | - / 1 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectGLES | off | 1.697 | - | 1.917 | - | +13.0% | 2.927 | 3.116 | P/P / - / P/P | - / 1 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | on | 0.417 | - | 0.446 | - | +7.0% | 1.126 | 1.152 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-fabric-sodium-in-world | DirectVulkan | off | 0.430 | - | 0.447 | - | +4.0% | 1.221 | 1.135 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectGLES | on | 2.957 | - | 3.579 | - | +21.0% | 4.878 | 5.638 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectGLES | off | 2.892 | - | 3.521 | - | +21.7% | 4.925 | 5.772 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectVulkan | on | 0.898 | - | 1.035 | - | +15.3% | 2.065 | 2.234 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-in-world | DirectVulkan | off | 0.893 | - | 1.040 | - | +16.5% | 2.050 | 2.215 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | on | 9.863 | - | 15.390 | - | +56.0% | 27.202 | 29.596 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectGLES | off | 10.027 | - | 12.967 | - | +29.3% | 27.715 | 28.130 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | on | 7.681 | - | 10.662 | - | +38.8% | 23.912 | 28.533 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000 | minecraft-1.21.4-rd12-odinlite-in-world | DirectVulkan | off | 7.891 | - | 10.415 | - | +32.0% | 25.083 | 28.348 | P/P / - / P/P | - / 0 |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectGLES | on | 9.857 | - | 11.404 | - | +15.7% | 26.125 | 27.013 | P/P / - / P/P | - / 8 |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectGLES | off | 9.601 | - | 11.487 | - | +19.6% | 26.230 | 27.477 | P/P / - / P/P | - / None |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectVulkan | on | - | - | - | - | - | - | - | P/? / - / - | - / - |
| 3B159D009VZ00000-old | improved-transparency-minecraft-26.3 | DirectVulkan | off | 8.197 | - | - | - | - | 23.349 | - | P/P / - / - | - / - |
d P3a-boundary = push(0x1ff) vs pull; d P4a total = push(0x1fff) vs pull; the P4a-only share is the difference of the two.
A '-' p50 means the run produced no result (rc != 0); see the runner.log in that directory.
@@ -0,0 +1,27 @@
# P4a DriverBench (desktop, lavapipe/llvmpipe) - median ns_per_op over repeats
| arm | mc_vanilla_draw | mc_state_toggle | mc_pass_switch |
|---|---|---|---|
| native | 4398.9 (n=5, min 4349.1) | 21387.3 (n=5, min 21208.2) | 412657.8 (n=5, min 407294.9) |
| espryt-pull | 4684.4 (n=5, min 4669.6) | 22010.4 (n=5, min 21461.7) | 410936.2 (n=5, min 407814.3) |
| espryt-push | 5760.5 (n=5, min 5728.0) | 22974.9 (n=5, min 22642.5) | 419703.1 (n=5, min 407773.8) |
| espryt-push7f | 5749.1 (n=5, min 5672.9) | 23768.2 (n=5, min 23188.9) | 419288.0 (n=5, min 407072.0) |
| espryt-push0 | 5355.2 (n=5, min 5299.2) | 23618.8 (n=5, min 23046.1) | 420362.2 (n=5, min 418725.9) |
| espryt-nocso | 5929.0 (n=5, min 5791.3) | 23685.0 (n=5, min 22996.2) | 418677.0 (n=5, min 416263.8) |
| magma-pull | 15394.9 (n=5, min 15206.4) | 31678.5 (n=5, min 30485.3) | 420197.6 (n=5, min 411290.5) |
| magma-push | 16023.9 (n=5, min 15876.0) | 32417.4 (n=5, min 32084.8) | 415641.9 (n=5, min 414170.3) |
| magma-push7f | 15847.5 (n=5, min 15733.7) | 32100.3 (n=5, min 30750.9) | 416670.4 (n=5, min 413160.7) |
| magma-push0 | 15946.6 (n=5, min 15808.2) | 31610.2 (n=5, min 30971.6) | 417410.5 (n=5, min 411148.7) |
| magma-nocso | 15846.2 (n=5, min 15748.2) | 32495.9 (n=5, min 31919.9) | 411306.4 (n=5, min 410235.6) |
## Deltas on mc_vanilla_draw (ns/draw)
- espryt: T1 = push(0x1fff) - pull = **+1076.1**; T2 = push(0x1ff, P2+P3a boundary) - pull = +1064.7; T1 - T2 (what P4a added) = **+11.4**; push(PIPE_PUSH=0) - pull = +670.8; no-CSO-content-addressing - push = +168.5
- magma: T1 = push(0x1fff) - pull = **+629.0**; T2 = push(0x1ff, P2+P3a boundary) - pull = +452.6; T1 - T2 (what P4a added) = **+176.4**; push(PIPE_PUSH=0) - pull = +551.7; no-CSO-content-addressing - push = -177.7
## Blaze3D blend toggle (mc_state_toggle, ns per toggle pair) and pass switch
- espryt mc_state_toggle: pull 22010.4, push 22974.9, delta +964.5, native 21387.3
- espryt mc_pass_switch: pull 410936.2, push 419703.1, delta +8766.9, native 412657.8
- magma mc_state_toggle: pull 31678.5, push 32417.4, delta +738.9, native 21387.3
- magma mc_pass_switch: pull 420197.6, push 415641.9, delta -4555.7, native 412657.8
@@ -0,0 +1,430 @@
# 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.
@@ -0,0 +1,362 @@
# P4a package B — `clientfb`, focused re-review v2
Reviewed: `refs/heads/p4a/clientfb` @ **`d1215fbc`** against `clientfb-review-v1.md` (M1–M4, nine minors,
the c0b/c0c reconciliation, D4), `clientfb-v2.md`, and the rulings ID-8 / ID-12 / ID-14 / ID-17 / ID-18 /
ID-19(c) / ID-21 / ID-25 / ID-27 / ID-28 / ID-33 / ID-34 / ID-35.
**Method — this round is a REPLAY, not a read.** B's eight commits were cherry-picked onto the real pipe
head `92dffb81` in a private worktree (`p4a/bint-review`), built (push, verify and pull), and the four lanes
run. Every number below is off that tree. Every finding carries file:line, a failure scenario and the
refutation I tried. The worktree and its three build dirs were removed afterwards.
---
## Verdict: **ACCEPT WITH MINORS**
All ten items of the v1 review and every ruling are closed, and closed by code rather than by argument:
the region tail reaches the applier and the case asserts on what the applier **stored**; the three
`GL_Texture.cpp` hooks cover every path that writes the built-in sampler and the latch reads both
counters; the clears are acceptance-gated with a refusal case that constructs a real refusal; the metadata
respecify moves the hint on an immutable texture without eating its pending upload; the Named sites cover
every DSA framebuffer entry point in the tree. Nothing new was introduced: G1's mechanism is intact
(every MG_State and GLImpl statement is inside `#if MOBILEGL_PIPE_PUSH`, the **pull build and its 1759-case
unit lane are green on the replayed tree** and G2 is 0 diff lines), the exit-order rule holds, MGLOG
discipline holds, and the file list is B's plus the two ID-8 grants.
The five findings are minors and one of them is a documentation inaccuracy in B's own report that the
integrator should not carry forward as a proved property.
**Both of B's findings are confirmed and neither is a B defect** — §5.
---
## 1. The lane numbers on the replayed tree
Replayed HEAD `aa0fd5aa` = `92dffb81` + B's seven cherry-picked commits (§4).
| lane | replayed tree | B's report (its own base) |
|---|---|---|
| `build-push` configure + build | **rc 0** | rc 0 |
| `build-verify` configure + build | **rc 0** | rc 0 |
| `build-linux` (pull) configure + build | **rc 0** | rc 0 |
| `ctest -L unit` **build-push** | **1759 / 1759** | 1756 / 1756 |
| `ctest -L unit` **build-verify** | **1759 / 1759** | 1750 / 1756 — *the six vanish, §5(b)* |
| `ctest -L unit` **build-linux** | **1759 / 1759** | 1756 / 1756 |
| **G2** pull vs push ctest name sets | **1759 == 1759, 0 diff lines** | 0 diff lines |
| emit suites (the eight `*Emit` + `CompositeResolver`) | **152 / 152** | 148 / 148 |
| `integration-gpu -R DirectGLES -j 8`, **default mask** | **444 / 491 — 47 failures** | 444 / 491 |
| the 47 by name vs `clientfb-v2.md`'s appendix | **IDENTICAL, 47 == 47, 0 diff** | — |
| `integration-gpu`, **`MOBILEGL_PIPE_PUSH=0x1ff`** | **491 / 491** | 491 / 491 |
| `integration-gpu`, **`MOBILEGL_PIPE_PUSH=0x3ff`** | **491 / 491** | 491 / 491 |
The three-count deltas (1756 → 1759, 148 → 152) are C v3's own new cases, which are on `92dffb81` and were
not on B's temporary base. **The default arm's shape and count reproduce exactly**, which is what makes
§5(a)'s ruling checkable rather than reported.
---
## 2. Findings
### n1 — `clientfb-v2.md` §2(5)'s M3 sentence is not what the code proves. `TextureEmit.h:1064-1097`
The report states *"`dispatched` is the `if constexpr` itself, so a discarded call never clears either."*
The code is
```cpp
Bool accepted = false; Bool dispatched = false;
if constexpr (MGPipeTextureRecordsReachTheApplier()) { dispatched = true; accepted = MGPipeApplyResourceSubData(...); }
...
if (dispatched && !accepted) { ++m_refusedSubDatas; MGLOG_E_ONCE(...); return false; }
mipmap->MarkStorageDirty(uploadTarget, level, false);
```
so with the constant back at 0 `dispatched == false`, the guard is false, and the flag **is** cleared. The
same shape is in `PublishCreate` (`:1050`, `if (dispatched && !accepted) return;` — a discarded create still
takes `MGPipeNoteHandlePublished`) and `NoteRespecified` (`:1069`, the discarded arm always advances
`LastDesc`).
*Failure scenario.* The A/B arm the predicate exists to keep compilable — an operator or a bisect setting
`kMGPipeWiredTextureSubsystem = 0` — would clear a level's dirty flag with the record nowhere, i.e. v1's M3
data loss reintroduced by the very arm that is supposed to be inert, and `MGPipeHandleIsPublished` would
answer true for handles the applier never received.
*Refutation attempted, and it succeeds — for reachability, not for the sentence.* `PipeFill.cpp:1059-1092`
gates all six birth hooks on `FamilyIsLive(kMGPipeSubsystemTextureResources, kMGPipeWiredTextureSubsystem)`
and forwards through `ForwardWhenWired<kWired>`; with the constant 0 `NoteLevelDirty` is never reached,
`m_drain` is permanently empty, and `DrainTextureSubData` (`TextureEmit.h:786`) returns at
`if (m_drain.empty())` before `EmitOneLevel` exists on the call graph. `PublishCreate` and `NoteRespecified`
are unreachable for the same reason. So all three sites are dead code on that arm and the property holds —
**because the family is gated off upstream, not because of `dispatched`.**
**Not a defect.** But the integrator should not carry the sentence forward as a local guarantee, and
`d1215fbc`'s comment ("the two places a discarded call may not be treated as an accepted one") names
`PublishCreate` and `NoteRespecified` while the third site, the one M3 is actually about, reads the other
way. One line — `if (!dispatched || !accepted) return false;` — makes the paragraph true at zero cost on
the live arm; `PublishCreate` / `NoteRespecified` must keep their current shape, since on the A/B arm their
"pretend it landed" bookkeeping is what keeps the dedupe coherent.
### n2 — a bound-target record emitted from a DSA site latches on dispatch, not on acceptance. `FramebufferEmit.h:319-360`
`EmitFramebufferByName` writes `m_lastEmitted[kDraw|kRead]` (or `m_named[slot]`) from `Emit()`, which counts
bytes. `MGPipeApplySetFramebufferState` returns `void` and can still refuse — a null handle,
`Fbo.Slot >= kMGPipeMaxFramebufferSlots`, or an out-of-range `DrawBuffers[i]` (`PipeApply.cpp:2157-2190`).
A refused record therefore latches and is never re-sent until its content moves: M3's class, one family over.
*Refutation, and it holds today.* Two of the applier's three refusals are unreachable from this client:
`HandleFor` (`:254`) returns `kMGPipeDefaultFramebuffer` `{0,1}` or an allocator handle, and
`MGPipeSlotAllocator::Allocate` documents and enforces *"never returns slot 0 (reserved: null, and the
default framebuffer for kind Framebuffer)"*, so the null-handle arm cannot fire; and m2's client-side gate
(`FramebufferEmit.h:160-172` + `:479-495`) refuses an over-wide draw-buffer token before the record is
built. The third needs 65 536 live framebuffers and is a loud `MGLOG_E` on the far side. Pre-existing in v1,
untouched by the rework, and out of B's scope — **record it for wire's next round**, since the resource
family now has acceptance returns and this one does not.
### n3 — the built-in sampler's cache reference is given back only when the texture's SLOT is recycled. `TextureEmit.h:1017-1024`
`RetireIfRecycled` (and `ResetForTest`, `:911-918`) are the only `MGPipeSamplerCsoCache::Release` callers on
this side; I confirmed `MGPipeEmitTextureDestroyAndFree` (`MG_Impl/Pipe/PipeFill.cpp:1197-1228`) never
reaches this emitter, so a destroyed texture leaves one reference standing.
*Failure scenario.* A workload whose live-texture count falls — a dimension unload, a resource-pack swap —
parks (peak − live) references the LRU cannot evict; C's cache then mints over capacity and
`OverCapacityMints` / referenced evictions climb, unattributably.
*Refutation.* `NotifyAndFree` returns the slot to the free list at death, `MGPipeSlotAllocator::Acquire`
pops the free list before the high-water mark, and `AcquireTexture` runs `RetireIfRecycled` on the very next
texture creation — so the residency bound is the texture-slot **high-water mark**, which is exactly the bound
`m_textures` itself already carries. It is monotone-bounded, not a leak, and C v3 counts rather than asserts
(`92dffb81`). **Accepted as declared** (B says "bounded by live texture slots"; "peak" is the exact word).
The integrator should read C's two counters once D lands and the texture family runs real traffic.
### n4 — the never-destroyed singleton's stated reason is now false. `TextureEmit.h:1119-1124`
The comment justifies "never destroyed" with *"~TextureObjectBase reaches this emitter through the death
helper's RecordIsPublished / NoteRecordDestroyed pair, which read and WRITE its tables"*. That pair was
deleted in this very rework (the latch is A's), and the death helper does not touch the emitter at all.
Documentation only: ID-8's rule is unconditional for every MGPipe process singleton, the object is still
`new`'d and never deleted, and `FramebufferEmit.h:631-637` states the unconditional reason correctly.
Reword at the next touch of the file.
### n5 — `RepublishMask` now runs inside the framebuffer record build. `FramebufferEmit.h:539+` → `TextureEmit.h:1084-1101`
`SurfaceOf` calls `NoteTextureBoundAs`, which after M4 can emit a `resource_respecify`. So attaching a
texture to an FBO emits a resource record from inside `BuildFramebufferState`'s attachment walk.
*Refutation, and this one is right by construction.* The ordering is the correct one — the resource record
precedes the surface that names it — there is no re-entrancy (`RepublishMask` touches only `m_textures` and
the applier; `BuildFramebufferState` holds no reference into either), and `NoteTextureBoundAs`'s
`if (now == before) return;` makes every attachment after the first free. **Not a defect**; recorded because
it is a new emission on the validate-point path whose cost will show up in D's payload histogram, and
because on the `0x3ff` arm `RepublishMask`'s own `MGPipeTextureSubsystemEnabled()` gate is what keeps it
silent (verified: 0x3ff is 491/491).
---
## 3. The per-item closure table
| item | verdict | evidence on the replayed tree |
|---|---|---|
| **M1** region tail reaches the applier | **CLOSED** | `TextureEmit.h:1068-1069` passes `m_regions.empty() ? nullptr : m_regions.data()`. `TextureEmit.TheApplierStoresTheRegionListTheEmitterBuiltAndNotAnEmptyOne` (`TextureEmitTest.cpp:731-765`) asserts on `MGPipeApplier().TextureResources[slot]`'s `PendingUpload::Regions`, field by field (X, Y, W, H, SrcOffset, SrcRowStride, SrcSliceStride) — **the STORED list**, and it first asserts `RefusedSubDataCount() == 0` so a declared-but-missing tail fails loudly. |
| **M2** three `GL_Texture.cpp` hooks | **CLOSED** | **All 36** `GetSamplerObject()->Set*` writes in the file (`:1262-1320`, `:1379-1422`, `:2083-2142`) are inside one of the three hooked functions `TextureParameterObject_State` (hook `:1365`), `TextureParameterObjectf_State` (`:1467`), `TexParameterf_State` (`:2181`). Every other family funnels in: `TexParameteriv/IIv/IUiv → TexParameteri_State:2196 → TextureParameterObject_State`, `TexParameterfv:2233 → TexParameterf_State`, DSA `:6334/:6340 → the two Object forms`. **Every `return;` before the hook in all three switches is a `RecordError` arm** (checked at `:1296 :1331 :1341 / :1433 :1443 / :2115 :2157`); every success arm `break`s and reaches the hook. The four border-colour helpers at `:44-70` are outside the three, and correctly so: `MGPTextureParams` (`MGPipeTypes.h`) carries `Res, BuiltinSampler, BaseLevel, MaxLevel, Swizzle[4], DepthStencilMode, ForceResync, SamplerResync, MinLod, MaxLod, LodBias` and **no border colour**, and `MGPipeBuildTextureParams` (`TextureEmit.h:303-331`) reads only those three floats off the sampler object. So the record has no field a path outside the hooks can move. |
| **M2** both-versions latch | **CLOSED** | `TextureEmit.h:660-673` reads `GetTextureParamsVersion()` **and** `sampler->GetVersion()` **and** `ForceParamsResync`. `ALodWriteOnTheBuiltinSamplerRepublishesTheParams` asserts the texture's own version did **not** move before driving the sampler write — the case cannot pass for the wrong reason. MinLod/MaxLod/LodBias all asserted. |
| **M2** no double Release, no leak | **CLOSED (with n3)** | `:675-700`: one `Acquire` per emission; the duplicate reference is handed straight back when the value did not move, the previous handle released when it did; `SamplerEmit.h:305` makes `Release(null)` a no-op. Exactly one reference per entry. Death: n3. |
| **M3** clear on acceptance | **CLOSED (with n1)** | `TextureEmit.h:1090-1097`; `ARefusedUploadLeavesTheLevelDirtyAndOnTheDrainList` constructs a real refusal via `MGPipeApplierReleaseObjectRecords()` and asserts flag + drain entry + counter, then drives the self-heal. The if-constexpr-discarded case is n1. |
| **M3** refusal survives | **CLOSED** | as above; plus the second finding B made itself (a refused respecify republishes the create and retries once, `:600-621`) is pinned by the same case's second half. |
| **M4** metadata respecify | **CLOSED** | `RepublishMask` (`:1084-1101`) starts from `entry.LastDesc` and writes only `BindMask` + `ImageBindableHint`. `AnImmutableTexturesImageBindableHintReachesTheApplierAfterItsAllocation` (`:819-853`) allocates immutable storage, stands a pending upload, then image-binds, and asserts on the **applier's** record: hint 1, mask set, `Width` unmoved, serial advanced, pending upload survived. |
| **ID-19(c)** the Named sites | **CLOSED** | All 23 `Named*Framebuffer*` symbols in the tree enumerated. **17 call sites over 12 entry points**, not sixteen — B's table counts `glBlitNamedFramebuffer`'s two objects as one row. Mutators, published after the mutation: `:1461 :1490` (Texture), `:1516 :1546` (TextureWithUploadTarget, i.e. the 1D/2D helper), `:1603 :1708` (TextureLayer), `:1780 :1792` (Renderbuffer), `:1994` (DrawBuffers), `:2011` (DrawBuffer), `:2023` (ReadBuffer) — 11. Consumers, published before `MGP_FILL`: `:672 :673` (blit, both objects), `:688 :702 :716 :730` (the four clears) — 6. **Nothing is missed:** every `->AttachTexture` / `->AttachRenderbuffer` / `->Detach` / draw- or read-buffer mutation in a `Named*` entry point is followed by a publish. `NamedFramebufferTexture3D` is a pure `RecordUnsupported…` stub; `InvalidateNamedFramebuffer{Data,SubData}` validate only; the three getters and `CheckNamedFramebufferStatus` are queries. `NamedFramebufferParameteri` is declared-not-hooked and that is **safe by a stronger argument than B gives**: it moves only the no-attachment defaults `FillGeometry` reads, and every *consumer* republishes before handing the object over, so a stale record can never reach the server. |
| ID-19(c) default framebuffer | **CORRECT, not wrongly emitted** | Every `framebuffer == 0` path reaches `pDefaultFramebufferInfo->defaultFBO`, `HandleFor` returns `kMGPipeDefaultFramebuffer {0,1}` and `IsDefault = 1` with the colour surface under `Color[0]` (`:504-512`). That is the record ID-19(c) wants for `glClearNamedFramebufferfv(0, …)`. No collision in `m_named[0]`: the allocator never returns slot 0 for kind Framebuffer. |
| ID-19(c) ReadSurface | **CLOSED** | `out.ReadSurface = SurfaceOf(fbo, fbo.GetReadBuffer())` (`:520`); `BuildFramebufferState` lost its `readFbo` parameter entirely, so the v1 shape is unrepresentable. |
| ID-19(c) sticky mask + content hash | **CLOSED** | `MGPipeCopySurfaceForHash` copies the new `TextureTarget` (`:205-209`); `Target` is a hash input, so a Named record can never be suppressed against a bound one; the per-object `m_named` table with the generation checked buys the other direction; `Reset()` clears it in the safe direction. |
| ID-19(c) no Named record for a null handle | **CLOSED** | `PipePublishFramebufferByName` returns on `!fbo`; `HandleFor` cannot produce null. |
| **c0b** no MG_State TU includes an emitter | **CLOSED** | `grep -rn "MG_Impl/Pipe/" MG_State/` returns three **comment** lines and no `#include`. `RenderbufferObject.cpp` now includes `MG_Pipe/PipeMutation.h`. |
| **c0b** helper/latch deletions | **CLOSED** | all eight free functions, `Entry::Published`, both `RecordIsPublished`, both `NoteRecordDestroyed`, `PublishedIn`, `Retire`, `ArmForTest`/`m_armed` gone; both destructors call one helper. |
| **c0c** helper/constant deletions | **CLOSED** | `MGPipePackSubDataTarget`/`…ResourceTargetOf`/`…UploadTargetOf`, `kMGPipeDepthStencilModeDepth/Stencil`, `kMGPipeSurfaceKind*` all deleted; `MGPipeDepthStencilModeByte` kept. |
| **c0c** `TextureTarget` filled, 0xFFFF elsewhere | **CLOSED** | `MGPipeEmptySurface()` (`:113-118`) sets `kMGPipeSurfaceNoTextureTarget` (= 0xFFFF, `MGPipeTypes.h:533`) **and** `TextureUploadTarget::Unknown`, used on the empty point and both `SurfaceOf` early returns; the texture arm writes `GetTarget()`. |
| **D4** flip verified, expected-failing set empty | **CLOSED** | `kMGPipeWiredTextureSubsystem = kMGPipeSubsystemTextureResources`; the five named cases all pass in the 1759/1759 push lane, and again in verify and pull. |
| **the six minors fixed** | **CLOSED** | m1 `targets.size() == 1` (`:88-91`); m2 the second refusal loop (`:479-495`); m3 the owner acquired before any `Entry&` (`:544-590`); m4 `RetireIfRecycled` in both `Acquire*`; m5 dissolved by c0e's per-object rule; m6 the Unknown sentinels. Each has its own named case. |
| **the three declared** | **JUDGED SOUND** | §3 below. |
| **exit order (ID-8)** | **HOLDS** (n4 on the comment) | both emitters `new`'d and never deleted; `Entry::Texture` is a raw pointer; the new `Entry::BuiltinSampler` is a POD handle — no new static holder of a frontend `SharedPtr`. |
| **MGLOG discipline / no leftovers** | **CLEAN** | B's two headers contain exactly four log statements, all `MGLOG_E_ONCE` on error paths (`TextureEmit.h:623 :1092`, `FramebufferEmit.h:472 :489`); B's added lines in the two GLImpl files contain **no** log statement at all; no `TODO`/`FIXME`/`printf`. |
| **files vs ownership** | **CLEAN** | 15 files: B's six MG_State + two MG_Impl/Pipe + two MG_Test/Pipe + the granted `MG_Test/State/ObjectLifetimeIdTest.cpp` + the two ID-8 grants `GL_Texture.cpp` and `GL_Framebuffer.cpp`. Nothing outside. |
| **clientsp v3 API shapes** | **CONFIRMED** | B calls `MGPipeSamplerCsoCacheInstance().Acquire(params, Uint64& payloadBytes)` and `Release(handle)` — `SamplerEmit.h:266` / `:305` on `92dffb81` — plus `RefCountOf` / `RecordIsPublished`, which is exactly the seam C v3 names as B's. Nothing else. It compiles and the emit suites are 152/152, so the v2→v3 move did not touch it. |
| **wire v3 acceptance returns** | **CONFIRMED** | `PipeApply.h:786 :834 :863` all return `Bool` on the pipe head; B reads all three. |
### 3.1 The three declarations, judged
- **m8** (`SetInternalFormat`'s zero-extent respecify) — **accept.** Gating it needs a `TextureObjectBase`
member, which resizes the pull build's object and breaks G1; every applier body tolerates a zero-extent
respecify, and it is not byte-equal to the create so it is a real record rather than a duplicate.
- **m9** (no DSA-named path in G6's case) — **accept, and it is now stronger than a declaration:** ID-19(c)'s
two new cases (`AFramebufferHandedOverByNameGetsANamedRecordWithoutMovingABinding`,
`ANamedRecordIsSuppressedPerObjectAndNeverAgainstABoundRecord`) give the DSA paths coverage one level up.
- **D14** (the three `GL_Texture.cpp` sites unpinned by a unit case) — **accept.** A `MG_Test/Pipe` binary
cannot drive `glTexParameterf`; the unit case drives the exact call the sites make, and the wiring rides
the integration lane's texture family. Note this is exactly the class of thing the default arm will
exercise once D lands.
- **D15** (the ten mutators publish after the mutation) — **accept.** `FillPoints.def` is A's and has no verb
for any of them; "the point at which the object is final for this call" is the only available reading, and
the five **consumers** — the calls that actually hand the object over — do publish before `MGP_FILL`.
- **D12** (no clean arm on the drain list) — **accept, verified.** `EmitOneLevel`'s third statement is
`if (!mipmap->IsStorageDirty(uploadTarget, level)) return true;` and `true` drops the entry from both
lists; `ALevelMarkedCleanIsCollectedAtTheNextDrain` pins the collection **and** the re-append after a later
write, which is the half that would have made this a texel-loss bug.
- **D13** (clientsp merged as a fourth head) — **dissolved by the replay.** On `92dffb81` the cache is in the
tree; the merge disappears with the other three.
- **D16 / D17** — recorded; D17 (the dedupe can suppress a respecify the applier no longer holds) is honest
and its blast radius is bounded by the loud refused-upload path that heals it.
---
## 4. THE VERIFIED REPLAY RECIPE
Verified end to end: it applies with exactly **one** conflict, builds in all three configurations, and
reproduces B's lane numbers.
```sh
cd /home/swung/w7/pipe
git worktree add -b p4a/bint-review /home/swung/w7/p4a-bint refs/heads/feat/disaggregated # = 92dffb81
cd /home/swung/w7/p4a-bint
git submodule update --init --recursive
cp -a /home/swung/w7/pipe/3rdparty/glslang/External 3rdparty/glslang/
cp -a /home/swung/w7/pipe/tools/trace_replay/fixtures/. tools/trace_replay/fixtures/
git ls-files -m tools/trace_replay/fixtures | xargs -r git update-index --assume-unchanged
# B's three v1 commits, as they sit on the temporary base:
git cherry-pick -x 5e87d3d2 # mint {slot,gen} for texture + renderbuffer -> clean
git cherry-pick -x 5fac004a # push the bound framebuffers -> clean
git cherry-pick -x e2bf183a # wire bit 9 + the emitter cases -> CONFLICT, see below
# 549ef30b IS SKIPPED — see §4.1
# B's four remaining rework commits:
git cherry-pick -x a390bb1a # birth hooks, D4 flip, region tail, acceptance -> clean
git cherry-pick -x d013b7ec # the two granted GLImpl files -> clean
git cherry-pick -x 4ec43194 # the twelve new cases and the six changed -> clean
git cherry-pick -x d1215fbc # the docs refresh -> clean
```
Configure with `~/w7/notes/tools/wsl_tree.sh`'s `COMMON` flags, `CCACHE_BASEDIR=/home/swung/w7`, `-j 8`:
`build-push` (`-DMOBILEGL_PIPE_PUSH=ON`), `build-verify` (`-DMOBILEGL_PIPE_VERIFY=ON
-DMOBILEGL_ITEST_REQUIRE_GPU=ON`), `build-linux` (no extra flag).
### 4.1 `549ef30b` must be SKIPPED, not resolved
It retires wire v3's local `kMGPipeFramebufferTargetNamed` for c0e's enumerator. **Wire v3 already did
that itself on the pipe** (`712c9467`, ID-21/ID-27/ID-28): the constant does not occur anywhere in
`92dffb81` — `git grep kMGPipeFramebufferTargetNamed 92dffb81` is empty — and wire's own cases already spell
`static_cast<Uint8>(MGPipeFramebufferTarget::Named)`. Cherry-picking it conflicts in `PipeApply.h` against a
hunk that no longer exists. B's own §7 item 7 anticipated exactly this. `git cherry-pick --skip`, or simply
omit it from the list as above. Nothing in B's remaining commits references the retired constant.
### 4.2 The one conflict, and its recorded resolution
`e2bf183a` conflicts in **`MG_Test/Pipe/FramebufferEmitTest.cpp`** and **`MG_Test/Pipe/TextureEmitTest.cpp`**
— wire's cases (already on the pipe, from `ae1a1c50` / `5ab90dec` / `8f1eaafa`) and B's cases are appended at
the same anchor.
**One conflict hunk per file, and the base region of each is EMPTY** (Framebuffer: ours 359 / base 0 /
theirs 360; Texture: ours 620 / base 0 / theirs 477) — i.e. both sides are pure additions with nothing
removed, the same shape B resolved its own wire merge with. **Resolve as an overlap-checked union with
B's block FIRST** (`theirs` before `ours`), which reproduces the layout `p4a/clientfb` itself has: on B's
branch its own cases sit above wire's (`TextureEmitTest.cpp:319..991` are B's, `1074..` are wire's).
> **This ordering is load-bearing.** Resolving `ours`-first also compiles, but the later `4ec43194` then
> fails to apply (4 hunks, non-empty bases) because its context assumes B's block comes first. With
> `theirs`-first every remaining commit applies clean.
Checks run on the union result, all green: **0 duplicate `TEST(` names** in either file, exactly **1**
`MGL_*_CLIENT_TEST_LIST` macro per file (the macro region merged automatically, outside the conflict, and
carries both sets: 13 framebuffer + 21 texture client entries), and no overlapping helper names — B's side
adds `MakeTexture2D` / `MakeColorTexture` / `BindDrawAndRead`, wire's adds `TextureDesc` / `TextureParams` /
`TextureUpload` / `Region` / `TextureRecordOf` / `FramebufferRecord`, each inside its own
`namespace { … }` under its own `#if` guard.
### 4.3 Fidelity of the replay
`git diff d1215fbc <replayed HEAD>` over B's own paths is **empty**:
`MG_Impl/Pipe/TextureEmit.h`, `MG_Impl/Pipe/FramebufferEmit.h`,
`MG_Impl/GLImpl/Texture/GL_Texture.cpp`, `MG_Impl/GLImpl/Framebuffer/GL_Framebuffer.cpp` and **all of
`MG_State/`** are byte-identical. The only residue is wire v3's and C v3's own tails
(`CompositeResolver.h`, `SamplerEmit.h`, `ProgramEmit.h`, `PipeApply.{h,cpp}`, C's four test files) plus
3 lines in the two conflicted test files: wire's Named-constant retirement applied to **wire's own** cases,
and one blank line from the union. So the replayed tree carries B's work exactly.
---
## 5. B's two findings, checked
### (a) The 47 default-arm failures are bit 10 with no server consumer — **confirmed, and it is NOT a B defect**
Reproduced exactly: **444/491, and the 47 names are identical to `clientfb-v2.md`'s appendix, 0 diff.**
`0x1ff` and `0x3ff` are both 491/491 on the replayed tree, so bit 9 — every line of B's framebuffer work
including the 17 Named sites — is independently clean and the cause is bit 10 alone.
**An independent negative control, stronger than B's probe-variable one.** On this tree
`MGPipeResourceRecord::PendingUploads` is read by `MG_Pipe/PipeApply.{h,cpp}` (the applier's own storage),
`MG_Test/Pipe/TextureEmitTest.cpp` and `MG_Impl/Pipe/TextureEmit.h` — **and by nothing in `MG_Backend/`**
(`VkTextureManager::FlushPendingUploads` is DirectVulkan's unrelated internal staging, not the applier's
set), and no file under `MG_Backend/` reads `MGPipeApplier().TextureResources[…]` at all. So the accepted
uploads land in a set that has no reader: package D is the consumer and is not in this tree. The client half
of D-D5's inversion is present and correct and is destructive on its own, exactly as ID-35 rules.
**Concur with ID-35 and with B's recommendation 1**: the one line `TextureEmit.h:98` is the whole switch, so
moving the flip into D's landing commit keeps every intermediate tree green and keeps a bisect meaningful.
If it stays in B's commit, the B→D window is knowingly red on the default arm and the retrace and must be
gated at `0x1ff`.
**D-K2 gains the row B asks for, and the wording is right:** *bit 10 requires the server-side texture
consumer*, and it is the only P4a subsystem bit that is not independently switchable, because it is the only
one whose emission **takes state away from the legacy path** rather than adding a record the server may
ignore. (Bits 9, 11 and 12 are each 491/491 alone.)
### (b) The six verify-lane unit failures vanish on `92dffb81` — **confirmed**
`build-verify` on the replayed tree: **1759 / 1759, zero failures.** All six of B's named cases pass:
```
SamplerEmit.ARecordThatDoesNotDescribeItsOwnParametersIsRefusedNamingTheLength Passed
SamplerEmit.AUnitWindowPastTheMergedUnitSpaceIsRefusedRatherThanTruncated Passed
ImageEmit.AnImageWindowPastTheImageUnitSpaceIsRefusedRatherThanTruncated Passed
ProgramEmit.ACreateWithNoArtefactsAnOversizedBlockOrACorruptSlotIsRefusedNamingTheProgram Passed
ProgramEmit.TheDefaultUniformBlockLandsOnTheProgramsRecordAndTheSentinelIsRefused Passed
CompositeResolver.ASlotAtTheShaderCsoLimitIsRefusedWhileTheLastBandSlotIsNot Passed
```
They were the wire × clientsp-v2 seam that C v3's `79b58198` fixed (*the forked refusal drive unlinked the
log while `Initialize()` held it open, so the child wrote into a deleted inode*) — the empty-child-log shape
B described. B's control run was right and its diagnosis was right. **Nothing owed here.**
---
## 6. B's post-integration checklist
1. **Decide the flip's home first** (§5a). Recommendation: move `TextureEmit.h:98` into D's landing commit.
If it stays with B, gate the B→D window's default arm and the retrace at `0x1ff` and say so in the log.
2. **Skip `549ef30b`** and use §4's cherry-pick list; resolve the one test-file conflict **theirs-first**
per §4.2 — `ours`-first breaks `4ec43194`.
3. After the merge, re-run what this round could not: **G1** (`symbol_report --threshold 0` vs
`~/w7/p4a-before-libMobileGL.so`), **G5** (`scripts/p3a_untouched_regions.sh 37da3c3a HEAD`),
`gen_pipe.py --check`, `gen_pipe_dirty_surface.py --check`, and
`check_include_closure.py --mode both --compiler clang++ --self-test --require-all` (B's new
`TextureEmit.h → SamplerEmit.h` and `GL_Framebuffer.cpp → FramebufferEmit.h` edges). G2 is already
verified on the replayed tree at 0 diff lines.
4. **After D lands**, and these are the checks B's work is actually gated on:
- the default arm and the retrace back to **491/491 and 79/79**;
- the **residual-record sweep** (ID-12): the 183 "no applier record" refusals to zero, counting all
**eight** families per ID-34's N-2 — a residual one on a texture or renderbuffer handle is a B seam
defect;
- `PipeStats::ClientTextureUploadEmissions` against the server's `TextureUpload{Emissions,Box,Rect,Jobs}`
on the 79-case retrace: **a rect count of zero on `rei`/`xaero-*` means M1's tail is still not
arriving**, and it is the only place the region list is exercised at volume;
- C's `OverCapacityMints` and referenced-eviction counters, for n3.
5. `integration-verify` on the **DirectVulkan** lane under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`
for ID-8's per-kind leak test — still owed; this tree's `integration-verify` label runs DirectGLES.
6. Package F's `0x5ff` / `0x9ff` dependency-refusal arms cannot be read off any tree before D
(`0x5ff` is 444/491 for §5a's reason, not for D-K2's).
7. Optional, and one line each: n1's `EmitOneLevel` guard, n4's comment. n2 goes to wire's next round.
---
*Reviewer note.* Replay worktree `/home/swung/w7/p4a-rereview-clientfb` on branch `p4a/bint-review`, its
three build directories and all scratch logs were removed; `git worktree prune` run and the branch deleted.
No device work. `~/w7/pipe` and `~/w7/p4a-clientfb` were read only.
@@ -0,0 +1,434 @@
# P4a package B — `clientfb`, the framebuffer and texture/renderbuffer client. Result, v1
Branch `refs/heads/p4a/clientfb`, three commits on top of the tag `p4a/contract` (`08192d72`).
Working tree clean. **Not pushed.** No other worktree touched.
| step | hash | message |
|---|---|---|
| `b1` | `51d1760f` | `[Feat] (Pipe, State): mint a {slot, gen} handle for every texture and renderbuffer and publish its create, respecify, parameters and accumulated sub-data as pipe calls` |
| `b2` | `a78eaf93` | `[Feat] (Pipe): push the bound framebuffers with a resolved read surface, inline attachment formats and a content hash that covers the draw-buffer array` |
| `b3` | `f7de87b5` | `[Feat, Test] (Pipe): wire the framebuffer subsystem bit and pin the resolved read surface, the sticky bind mask, the level-shadow strides and the union-box/region-list invariant` |
`b3`'s message is **not** C.1's wording, because C.1's wording would have been false: only ONE of the
two wired-subsystem constants is flipped. §5 (D4) is the whole reason and it is the single most
important thing in this document for the integrator.
13 files, +2708 / −56 against the tag.
---
## 1. Verdict on the hard rules
| rule | result |
|---|---|
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` | **0 added / 0 removed / 0 renamed / 0 resized**, `.text` 10806323 → 10806323 (+0, +0.000%), 27811 → 27811 defined symbols. Run after every commit. P4a's admitted-resize set stays EMPTY. |
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0 (the two contract-marked UNDECIDED rows unchanged) |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all` | rc 0, 4 probes, 0 skipped, 0 problems, 6 controls tripped |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | rc 0 |
| `p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, the eleven byte-identical |
| three builds (pull / push / verify) | all three, rc 0 |
| `ctest -L unit` ×3 | **1665 / 1665 in each**, 0 failed |
| ctest names pull == push | `diff` empty |
| no name removed vs `~/w7/p4a-before-ctest-names.txt` | 0 removed, **43 added** (§7) |
| `ctest -L integration-gpu -j 8`, default mask | 966 / 966 |
| same, `MOBILEGL_PIPE_PUSH=0` | 966 / 966 |
| same, `MOBILEGL_PIPE_PUSH=0x1ff` (P4a off, G12's T2 arm) | 966 / 966 |
| `ctest -L integration-verify -j 4` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` | 844 / 844, **0 `Fatal{` lines** |
| `MOBILEGL_PIPE_VERIFY=1 retrace_gate.py … -j 4` | **79 / 79**; `grep -l 'Fatal{'` empty; `grep -L 'MGPipe verify:'` empty |
| only B's files (+ granted sites) | yes, §6 |
| no push, no attribution lines | yes |
---
## 2. Per-file summary
### `MG_Impl/Pipe/TextureEmit.h` (+1024, B owns it)
The whole texture and renderbuffer client. Pure builders first, so every case is one `EXPECT` per
field and G7's scripted control can name the field it dropped:
- `MGPipeTextureStorageKindForTarget` — `StorageKind` derived from the TARGET rather than from
`GetStorageType()`, because `resource_create` is emitted from `TextureObjectBase`'s constructor
where the derived object does not exist and that accessor is **pure virtual**. Calling it there
is undefined behaviour, not a wrong answer; the target mapping is exact.
- `MGPipePackSubDataTarget` / `…ResourceTargetOf` / `…UploadTargetOf` — the low byte is
`MGPipeResourceTarget` (so a buffer record still compares `== kMGPipeResourceTargetBuffer`
whole, unchanged from P3a) and the high byte is `TextureUploadTarget`, which is the only place a
cube face can ride. §5 (D2) records it as a deviation.
- `MGPipeTextureExtentOf` — the extent trio plus the layer count, which the frontend answers in
three different axes by target (1D array in `y`, other layered targets in `z`, cube = six blobs).
- `MGPipeBuildTextureResourceDesc`, `MGPipeBuildRenderbufferResourceDesc`,
`MGPipeBuildTextureParams`, `MGPipeLevelPitchOf`, `MGPipeBoxOfDirtyRegion`,
`MGPipeBuildSubRegion`.
- `MGPipeTextureEmitter` — the handles and their inverse, the sticky `BindMask` with the
`ImageBindableHint` transition arming `ForceResync` exactly once, the publication latch, the
descriptor **memcmp dedupe**, the drain list, and `DrainTextureSubData` with the
empty-list early-out.
- Six MG_State entry points and the two step-1 death emitters (§5, D3).
### `MG_Impl/Pipe/FramebufferEmit.h` (+425, B owns it)
`MGPipeBuildSurface` (one statement per field), `MGPipeResolveAttachmentUploadTarget`,
`MGPipeDrawBufferIndex`, `MGPipeFramebufferStateContentHash` (field-wise into a zero-initialised
staging copy, `ContentHash` left 0), and `MGPipeFramebufferEmitter::EmitFramebufferState` — the
per-target discrimination, the `Target = Both` collapse, the suppressor slot fed the combined hash
with per-target latches deciding which record goes out, `Complete` from `CheckCompleteness()`, and
the client half of D-C3's over-wide-attachment refusal.
### `MG_State/GLState/TextureState/TextureObject.{h,cpp}` (+34 / +142)
Three non-virtual, push-only protected helpers on `TextureObjectBase`
(`PipePublishDescriptor`, `PipePublishParams`, `PipeNoteLevelDirty`) declared in the header and
defined in the `.cpp`, which is the ONE MG_State translation unit that sees the client emitter
(§5, D1). `~TextureObjectBase` becomes the three-step death path. Hooks: the constructor (mint +
create), `SetInternalFormat`, the three border-colour setters, both swizzle setters,
`SetBaseLevel`, `SetMaxLevel`, `SetImmutableLevels`, `SetSamples`, `SetFixedSampleLocations`,
`SetDepthStencilTextureMode` (header, inline), and — **after** the storage mutation, never before
`BumpShapeVersion` — `TextureObjectWithOneMipmap::{AllocateStorage, TruncateMipmapLevels,
MarkStorageDirty, MarkStorageDirtyRegion}`.
### `TextureObject2DCube.cpp` (+17), `TextureObjectView.cpp` (+12), `TextureObjectBuffer.h` (+9)
The cube's four storage overrides call the inherited helpers; the view's constructor publishes
`ViewOf` explicitly (because `SetImmutableLevels` early-returns on a degenerate view); the buffer
texture's `SetBufferRange` publishes the `BufferForTexBuffer` / `BufOffset` / `BufSize` trio at the
first statement at which it is complete.
### `MG_State/GLState/RenderbufferState/RenderbufferObject.{h,cpp}` (+7 / +61)
One push-only private `PipePublishDescriptor`, the constructor's mint + create, the three storage
setters (D-D2's hole closed by EMISSION, with no new member and no widened shutter), and the
three-step death path.
### `MG_State/GLState/FramebufferState/FramebufferObject.cpp` (+25)
`~FramebufferObject` now calls `MGPipeEmitFramebufferDestroyAndFree` — steps 2 and 3 only, because
D-I2 gives this kind a handle and no wire lifetime.
### `MG_Test/Pipe/{TextureEmitTest, FramebufferEmitTest}.cpp` (+484 / +367)
14 + 8 emitter-side cases, appended before `main()` and disjoint from the wire package's
applier-side cases. All 24 registered names exist in a pull build as visible skips.
### `MG_Test/State/ObjectLifetimeIdTest.cpp` (+69, granted)
`ProbeLifetimeIdAcrossAddressReuse` extended to `TextureObject2D`, `FramebufferObject`,
`SamplerObject` and `ProgramObject` (8 new cases, all green). The texture case doubles as a
64-round mint/free churn check under push.
---
## 3. `EmittedCallSuppliesTheWholeField`, per field
`PipeFill.cpp` is the contract package's for the whole phase and **was not touched**; the six P4a
rows already sit in its **false** arm. This package's job was to confirm each answer against what
it actually emits, and it concurs with all six. Only two of them are this package's families:
| field | emitted by | supplies the whole field? | why |
|---|---|---|---|
| `GetFramebufferBindingSlot` | `SetFramebufferState` (this package) | **NO** | The field's storage is `BindingSlot<FramebufferObject>` — a frontend heap reference — and the call carries an eight-byte `{slot, gen}` `Fbo` plus a fully resolved descriptor. The applier has no way to produce the pointer and P4a deliberately does not give it one (a payload never contains a pointer). Skipping the pull would leave the mirror null on every draw of every push build. What retires it is the phase where the backend stops reading a frontend `FramebufferObject`, not a better applier. This is P3a's `GetBoundVertexArray` precedent, one for one. |
| *(none)* | the texture-resource family | **n/a** | `kMGPipeSubsystemTextureResources` names NO emitted field and cannot: `resource_create`/`_respecify`/`_subdata`/`_destroy` and `set_texture_params` are dispatched at the GL call that causes them rather than filled into a `PipeInputs` field. `PipeFill.cpp` asserts this (`NoDirtyBitOwnsTheTextureResourceSubsystem`), and no `Coverage.def` row exists or may exist. |
The other four (`GetImageTextureBinding`, `GetTextureUnitObject`, `GetProgramForDraw`,
`GetProgramForDispatch`, plus `GetMaxTouchedTextureUnit`) belong to package C and are untouched.
**Consequence, and it is the one that matters for the verify lane: this package retires no pull at
all.** Every field it could have affected keeps coming through the residual fill, which is why the
79-case verify retrace reports zero divergences rather than "no divergence we looked for".
---
## 4. The wired-bit commit
`b3` (`f7de87b5`) sets `kMGPipeWiredFramebufferSubsystem = kMGPipeSubsystemFramebuffer` in
`MG_Impl/Pipe/FramebufferEmit.h`. `PipeFill.cpp`'s OR and its four `static_assert`s were not
touched; the assert that the constant is either 0 or its own bit still holds.
`kMGPipeWiredTextureSubsystem` **stays 0**. §5 (D4) is the full argument and the one-line edit the
integrator makes after the rebase.
---
## 5. Deviations
**D1 — MG_State reaches the client emitter through TWO translation units, not zero.**
P3a's buffer family declares its emission points in `MG_Pipe/PipeMutation.h` and defines them in
`MG_Impl/Pipe/PipeFill.cpp`, so `BufferObject.cpp` sees a declaration and never the client's
tracker. P4a cannot copy that: **both of those files belong to the contract package for the whole
phase** (C.7 gives them to A, and the "no file touched twice" rule is what discharges the
`bb2a236d` merge trap structurally), and neither carries a texture emission declaration. The
next-best arrangement keeps the same property one level in:
* every texture emission point is a **protected, non-virtual, push-only member of
`TextureObjectBase`** declared in `TextureState/TextureObject.h` and defined in
`TextureState/TextureObject.cpp` — the one MG_State TU that includes
`MG_Impl/Pipe/TextureEmit.h`. The cube's, the view's and the buffer texture's TUs call the
inherited helper and still see only a declaration;
* the renderbuffer half has no base class to hang helpers on and exactly one `.cpp`, so
`RenderbufferState/RenderbufferObject.cpp` is the second and last such TU.
So the client's tracker reaches exactly **two** MG_State translation units instead of zero.
`check_include_closure.py`'s mutation-header probe is unaffected (it asserts
`MG_Pipe/PipeMutation.h`'s own closure, which is unchanged) and is green. **The integrator can fold
the six free functions into `PipeMutation.h` and `PipeFill.cpp` in one mechanical commit once the
phase's file ownership relaxes; nothing else has to move.**
**D2 — `MGPSubData::Target` is PACKED for a texture: low byte the resource target, high byte the
upload target.**
D-D3's table asks `Target` to carry "the owner's upload target (`MGPipeResourceTarget` from D-A3,
**plus** the cube-face upload target in `MGPSurface`-style terms)". The payload has one `Uint16`
for two facts the server needs and no other field can hold either: which kind of storage the
destination is (the applier branches on it — a buffer target dispatches into `MGPipeResourceOps`,
every other target stores and returns) and which cube face the level belongs to, which is not
derivable from the resource target. The buffer half is preserved exactly: a buffer record's upload
byte is 0, so `Target == kMGPipeResourceTargetBuffer` still holds for the whole field and `w1`'s
branch is right whether it tests the whole `Uint16` or only the low byte. A `static_assert` pins
that. **If A would rather own the encoding, moving these three `constexpr` helpers to
`MGPipeTypes.h` beside `MGPSubData` is a copy-paste.**
**D3 — step 1 of the death order is emitted from the destructor, one statement before the
contract's helper.**
`MG_Impl/Pipe/PipeFill.cpp`'s `MGPipeEmitTextureDestroyAndFree` and
`…RenderbufferDestroyAndFree` hard-code `published = false` at the tag, with the note "the texture
emitter publishes nothing yet". That file is A's for the whole phase, so this package supplies the
answer from the object's destructor instead:
```
~TextureObjectBase / ~RenderbufferObject
-> MGPipeEmit<Kind>ResourceDestroy(lifetimeId) // 1. the wire delete, published-gated
-> MGPipeEmit<Kind>DestroyAndFree(lifetimeId) // 2. the notice, 3. the slot
```
which is **exactly** `PipeMutation.h`'s fixed three-step order and not a variation on it. Both new
functions are published-gated rather than slot-gated, for the reason `PipeFill.cpp` states in full.
The integrator can fold them into the helpers' bodies when D1 is folded.
**D4 — `kMGPipeWiredTextureSubsystem` is still 0, and that is a BLOCKED flip rather than an
unfinished one. THIS IS THE ONE THING TO READ.**
Unlike the other three P4a families, the texture family gets no fresh apply entry points: the
catalogue is closed and a texture rides P3a's OWN `resource_create` / `resource_respecify` /
`resource_subdata` / `resource_destroy` rows. On a base without `w1` those four have P3a's
**buffer** bodies, and two of their properties make a texture record actively harmful rather than
merely ignored:
* `MGPipeApplierState::Resources` is ONE vector indexed by SLOT (D-B2 makes it three, one per
resource kind). Buffer, Texture and Renderbuffer slot spaces are **independent**, so a texture
create at slot 12 overwrites the buffer record at slot 12 and the next write to that buffer is
refused against the texture's extent — a dropped content write with no diagnostic beyond the
refusal counter;
* `SubDataBoxFault` validates every record as the buffer half of `MGPSubData`, so a texture
sub-data record is `Fatal{ProtocolCorruption}` on `record.Level != 0` alone.
This was **found, not argued**: the first verify-build unit run with the bit flipped went red with
`Fatal{ProtocolCorruption} resource_subdata {slot=12, gen=0, glName=8}: the buffer half carries a
mip level`, and it took `TextureTest.GetTexImageReadsALevelWhoseLowerLevelsWereNeverDefined` —
a pre-existing case, nothing to do with P4a — down with it. That is the applier's trip wire doing
exactly its job, and it is evidence that D.1's stated order (`wire` **before** `clientfb`) is not
merely tidy.
The package is therefore complete and gated but not switched on:
* `kMGPipeWiredTextureSubsystem = 0`, so `kMGPipeWiredSubsystems` does not carry the bit, the
validate point never calls `DrainTextureSubData`, the drain list never grows, and nothing this
file builds reaches an applier that cannot hold it;
* `MGPipeTextureRecordsReachTheApplier()` is that constant asked as a `constexpr` predicate and
guards the **four** `MGPipeApplyResource*` calls with `if constexpr`. `set_texture_params` is
deliberately NOT behind it — `MGPipeApplySetTextureParams` is one of P4a's own fifteen entry
points and is a stub at the tag, so sending it keeps that seam exercised;
* `MGPipeTextureEmitter::ArmForTest(Bool)` (beside `ResetForTest()`) is initialised from the
constant and is what the two suites flip, so the whole conversion — descriptors, params, the
sticky mask, the drain list, the sub-data record and its strides — is gated by tests that assert
on the **emitted records** rather than on any applier state. The flip cannot land untested.
**The integrator's edit after the rebase onto `p4a/wire` is one line**: change that `0` to
`kMGPipeSubsystemTextureResources`. §8 lists what to re-run.
**D5 — the drain list's membership flag lives on the CLIENT, not on `MipmapStorage`.**
D-D4 asks for "a `Bool m_onDrainList` beside the level's existing `m_isDirty`, inside
`#if MOBILEGL_PIPE_PUSH`". It is a per-slot `Vector<Uint32>` of packed `(uploadTarget, level)` keys
in the emitter instead, for D-D5's own inversion: the emission cursor is client state and
`MG_State` gains no member at all this way (D-D2 makes the same argument for the renderbuffer).
The cost is a linear scan of ≤ 96 shorts on the `glTexSubImage` path, which has just memcpy'd
texels. `TextureEmit.ABailedLevelStaysDirtyAndStaysOnTheDrainList` pins the behaviour either way.
**D6 — the descriptor is deduped on its own bytes rather than on a version.**
`glTexStorage2D` allocates level by level and every parameter setter that touches a descriptor
field publishes; an 88-byte `memcmp` against the last emitted descriptor is cheaper than the
emission it avoids and is what keeps `glRenderbufferStorage`'s three-setter sequence **one**
record rather than three (`TextureEmit.ARenderbufferRespecifyPublishesItsExtentWithoutAVersionCounter`
pins that). It is the "version-first skip before anything expensive" shape, with the descriptor
standing in for a version the frontend does not have.
**D7 — `MGPSurface::Kind` reuses `MGPipeKind` rather than minting a three-value enum.**
`MGPipeKind` already spells `Texture` and `Renderbuffer`, its `None` is 0, and a zero-initialised
`MGPSurface` is therefore already the empty attachment point the contract's own sentence requires.
A `static_assert` pins `None == 0`. If A wants a dedicated enumeration beside `MGPSurface` it is a
rename, not a re-encoding.
**D8 — `MGPFramebufferState::DrawBuffers[]` indexes THIS RECORD'S `Color[]`, and the four
default-framebuffer tokens narrow to 0.**
`None` → −1 and `Color0..Color31` → 0..31 are the field's documented convention read literally. A
default framebuffer keeps its one colour surface under `BackLeft`, this record carries it in
`Color[0]`, and `IsDefault` is what tells the server which framebuffer it is looking at. The
distinction the narrowing loses is FRONT vs BACK and LEFT vs RIGHT, which MobileGL's frontend never
gives a default framebuffer — `FramebufferObject`'s constructor seeds `BackLeft` and nothing writes
another. A phase that needs stereo has to widen the field, not re-encode this one.
**D9 — `MGPTextureParams::DepthStencilMode` is numbered, not a GLenum.**
The frontend keeps `GL_DEPTH_COMPONENT` / `GL_STENCIL_INDEX` (0x1902 / 0x1901) and the payload byte
cannot hold one. 0 is DEPTH_COMPONENT, which is also GL's initial value and therefore what a
zero-initialised record already says.
**D10 — `MGPTextureParams::BuiltinSampler` is IDENTITY-addressed on this branch.**
It is `MGPipeSlots().Acquire(MGPipeKind::SamplerCso, texture->GetSamplerObject()->GetLifetimeId())`
— the same key `~SamplerObject`'s death helper already resolves through, so the two agree by
construction. Minting a handle is client state; the CALL that fills the record
(`create_sampler_state`) is package C's. **The cross-package seam to check at integration** is
whether C's content-addressed cache (capacity 256) keys its slots on the `SamplerObject`'s lifetime
id. If it does, nothing changes. If it mints on a synthetic id, this line has to become a call into
C's cache, and `TextureEmit.TwoTexturesWithIdenticalSamplingShareOneBuiltinCso` — which SKIPs today
with that reason printed — is its gate.
**D11 — one SamplerCso slot per texture is not released on this branch, by construction.**
`~SamplerObject` still raises the bare `NotifyStateObjectDestroyed` at the tag; D-I1's table gives
package C the edit that turns it into `MGPipeEmitSamplerCsoDestroyAndFree`. Until `clientsp` lands,
every texture that ever published its params leaves one `SamplerCso` slot behind. It is an ordered
dependency, not a leak in this package: `clientfb` → `clientsp` is D.1's order, and
`TextureEmit.ADestroyedTextureReleasesItsResourceViewAndBuiltinSamplerSlots` says so in the case
body rather than asserting something it cannot yet prove.
---
## 6. Granted sites
Exactly one grant was taken.
| file:line | what |
|---|---|
| `MobileGL/MG_Test/State/ObjectLifetimeIdTest.cpp:34-40` | the five new includes |
| `MobileGL/MG_Test/State/ObjectLifetimeIdTest.cpp:161-227` | eight cases extending `ProbeLifetimeIdAcrossAddressReuse` / `ExpectDistinctIdsWhileBothAlive` to `TextureObject2D`, `FramebufferObject`, `SamplerObject` and `ProgramObject` |
**Grants NOT taken, and why:**
* `MG_Impl/GLImpl/Texture/GL_Texture.cpp` — **not needed, including the one anticipated exception.**
The generated-mip storage grow at `:528-539` calls `AllocateStorage` + `MarkStorageDirty(false)` +
`TruncateMipmapLevels` + `BumpContentVersion()`, and the first and third of those are hooked on
the OBJECT, so the respecify goes out from there. The same is true of both `glTexBuffer` entry
points: they end in `SetBufferRange` + `SetInternalFormat`, both of which publish. No storage path
was found that bypasses `TextureObjectBase` / `TextureObjectMipmap`.
* `MG_Impl/GLImpl/Framebuffer/GL_Framebuffer.cpp` — not needed;
`AllocateRenderbufferStorage_State` goes through `RenderbufferObject`'s own three setters.
* `MG_Test/Framebuffer/FramebufferTest.cpp`, `MG_Test/Texture/{TextureTest, TextureViewTest}.cpp` —
no payload edit broke a case (all three suites are green in all three builds), so nothing was
appended and ID-8's collision warning does not apply.
* `MG_Test/Buffer/BufferTest.cpp` — package D's read-and-confirm, not B's.
---
## 7. What was added, and what was not touched
43 ctest names added, 0 removed. 35 are the contract commit's; the 8 this package adds are the
`ObjectLifetimeIdTest` extension. The 22 emitter-side cases in `TextureEmit` / `FramebufferEmit`
land inside names the contract commit already registered.
Untouched, confirmed: everything under `MG_Backend/`, `MG_IntegrationTest/`, `.github/`,
`MG_State/GLState/{SamplerState, ProgramState}/**`, `MG_State/GLState/Core.{h,cpp}`, every
`MG_Pipe/` file, every `scripts/` file, every `generated/*.inc`, and
`MG_Impl/Pipe/{PipeFill.*, Tracker.h, SetHashSuppressor.h, SlotAllocator.*, CsoCache.h,
ResourceTracker.h, VertexInputEmit.h, SamplerEmit.h, ImageEmit.h, ProgramEmit.h}`.
---
## 8. Verification transcript
```
$ git log --format='%h %s' 08192d72..HEAD
f7de87b5 [Feat, Test] (Pipe): wire the framebuffer subsystem bit and pin the resolved read surface, …
a78eaf93 [Feat] (Pipe): push the bound framebuffers with a resolved read surface, …
51d1760f [Feat] (Pipe, State): mint a {slot, gen} handle for every texture and renderbuffer …
$ 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
$ python3 scripts/gen_pipe.py --check rc=0
$ python3 scripts/gen_pipe.py --self-test rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --check rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --self-test rc=0
$ python3 scripts/check_include_closure.py --mode both --compiler clang++ --self-test --require-all
include-closure: 4 probes, 0 skipped, 0 problem(s), 6 negative-control trip(s) rc=0
$ git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD rc=0 (the eleven byte-identical)
$ cmake --build build-linux -j 12 rc=0
$ cmake --build build-push -j 12 rc=0
$ cmake --build build-verify -j 12 rc=0
$ ctest --test-dir build-linux -L unit -j 12 100% 1665/1665
$ ctest --test-dir build-push -L unit -j 12 100% 1665/1665
$ ctest --test-dir build-verify -L unit -j 12 100% 1665/1665
$ ctest --test-dir build-push -R 'FramebufferEmit\.|TextureEmit\.' 100% 24/24 (1 SKIP, D10)
$ diff <(build-linux names) <(build-push names) (empty)
$ comm -23 ~/w7/p4a-before-ctest-names.txt <(build-linux names) 0 removed
$ comm -13 ~/w7/p4a-before-ctest-names.txt <(build-linux names) 43 added
$ ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8
100% tests passed, 0 tests failed out of 966
$ MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu -j 8 966/966
$ MOBILEGL_PIPE_PUSH=0x1ff ctest --test-dir build-push -L integration-gpu -j 8 966/966
$ GLIBC_TUNABLES=glibc.malloc.tcache_count=0 \
ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4
100% tests passed, 0 tests failed out of 844 Fatal{ lines: 0
$ MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/p4a-clientfb \
--lib ~/w7/p4a-clientfb/build-verify/libMobileGL.so --out ~/w7/retrace-out/p4a-clientfb -j 4
passed 79 / 79; failed: [] rc=0
$ grep -l 'Fatal{' ~/w7/retrace-out/p4a-clientfb/*.log (empty)
$ grep -L 'MGPipe verify:' ~/w7/retrace-out/p4a-clientfb/*.log (empty)
$ rm -rf ~/w7/retrace-out/p4a-clientfb
```
**A trap worth recording for the integrator, because it cost a whole retrace round.** The first
retrace reported `passed 2 / 79` with `ssim=None` on every case — the exact false red C.1 warns
about. `tools/trace_replay/fixtures` in this worktree had been pulled back to 131/133-byte **LFS
pointers**, with an mtime matching the "reset to the tag" the six sibling trees were given at 12:24;
`git update-index --assume-unchanged` was still set, so `git status` was clean and nothing looked
wrong. Restoring them from `~/w7/pipe/tools/trace_replay/fixtures` (803 MB) and re-running gave
79/79. **Every sibling tree reset at the same time is very likely in the same state.**
Two other findings, both gates working:
1. the `Fatal{ProtocolCorruption}` of §5 (D4), which is why the texture bit is not flipped;
2. `MG_Config::Features.PipePush` defaults to **0** and only `ConfigLoader` sets the phase mask, so
a unit case that does not arm it is green for the wrong reason. Both suites arm it explicitly
and restore it, and the arming is called out in the scope's comment.
---
## 9. What must be re-run after the rebase onto `p4a/wire`
The integrator's edit is **one line** — `kMGPipeWiredTextureSubsystem = 0` →
`= kMGPipeSubsystemTextureResources` in `MG_Impl/Pipe/TextureEmit.h` — and it must be made in the
same commit as the rebase, because `w1` is what makes it safe. Then, in this order:
1. **`ctest -L unit` in build-verify**, first and on its own. It is the cheapest place the two
defects of §5 (D4) surface: `TextureEmit`'s four drain cases and
`TextureTest.GetTexImageReadsALevelWhoseLowerLevelsWereNeverDefined` were the exact five that
went red before, and they are the named expected-failing set to re-state unchanged.
2. **`ctest -L integration-gpu` on build-push at the default mask AND at `0x1ff`.** The default arm
is the first place a texture record meets a real applier record table; the `0x1ff` arm proves
the A/B still isolates it.
3. **`ctest -L integration-verify` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`**, for the
two new death paths (`~TextureObjectBase`, `~RenderbufferObject`) reaching a live applier.
4. **The 79-case verify retrace**, which is the only thing that exercises the drain list on real
texture traffic (`rei`, `xaero-*`, `journeymap`, `modernui` are the atlas fixtures D-D5 names).
**Check the fixtures are not LFS pointers first.**
5. **G1**, because the flip changes a `constexpr` in a push-only header and must still move nothing
in the pull build.
Also re-check at integration, in this order of risk:
* **§5 (D10)** — whether package C's sampler CSO cache keys its slots on the `SamplerObject`'s
lifetime id. If not, `MGPipeTextureEmitter::EmitTextureParams`'s one `Acquire` becomes a call
into C's cache and `TwoTexturesWithIdenticalSamplingShareOneBuiltinCso` stops skipping.
* **§5 (D11)** — that `clientsp` really does replace `~SamplerObject`'s bare notice with the death
helper, or every texture keeps leaking one `SamplerCso` slot into G8b.
* **§5 (D2)** — that `w1`'s `Desc.Target` branch reads `MGPSubData::Target` in a way the packing
satisfies (it does if it tests either the whole `Uint16` or the low byte against
`kMGPipeResourceTargetBuffer`).
* **§5 (D1/D3)** — whether to fold the six MG_State entry points and the two step-1 death emitters
back into `PipeMutation.h` / `PipeFill.cpp` now that A's ownership window has closed.
@@ -0,0 +1,519 @@
# P4a package B — `clientfb`, rework v2
Branch `refs/heads/p4a/clientfb`. Rebased onto `refs/heads/feat/disaggregated` = **`9ea44389`** (c0 + c0b +
c0c + c0d), then three merges (see §1). Addresses `clientfb-review-v1.md` (M1–M4, nine minors) and the
integrator rulings ID-8, ID-12, ID-14, ID-17, ID-18, ID-19(b)(c), ID-21, ID-22.
**Read §7 first.** The gates are green everywhere except one arm, and that arm's failure is a *proved*
consequence of D4's flip landing without package D — not a defect in this package, and the integrator has
an ordering decision to make because of it.
---
## 1. Commits and merged heads
| commit | what |
|---|---|
| `8b910b8c` | merge `refs/heads/p4a/wire` @ **`70e742a3`** (the applier: the `MGPSubRegion` tail, the three acceptance `Bool`s, the per-object `FramebufferRecords` table, the metadata respecify) |
| `e12dab98` | merge `refs/heads/p4a/c0e` @ **`11446f35`** (`MGPipeFramebufferTarget::Named = 3`, the per-object record comment, `MGPSurface::TextureTarget`'s field set) |
| `8534abf7` | merge `refs/heads/p4a/clientsp` @ **`00a86d2a`** — **a fourth head, not in the base recipe; see §1.1** |
| `549ef30b` | `[Fix] (Pipe)` retire wire v3's local `kMGPipeFramebufferTargetNamed` for c0e's enumerator (merge seam) |
| `a390bb1a` | `[Fix] (Pipe, State)` the contract's birth hooks, the D4 flip, the region tail, acceptance-gated flag clears, the metadata respecify, the minors |
| `d013b7ec` | `[Fix] (GLImpl, Pipe)` the two granted files: M2's `set_texture_params` republish and ID-19(c)'s Named records |
| `4ec43194` | `[Test] (Pipe)` twelve new cases and the six that had to change |
| `d1215fbc` | `[Docs] (Pipe)` refresh the one comment the flip made stale — **HEAD** |
Three merges are the base recipe; the fourth is §1.1. **The integrator drops all four** when it rebases this
branch onto the pipe that already contains them, and `549ef30b` goes with them (it is a merge seam, and
ID-21 already assigns that retirement to wire's verification round).
**The heads move under this branch.** At the moment this round closed, `refs/heads/feat/disaggregated` had
advanced to `92dffb81` (from the `9ea44389` this branch is rebased on) and `refs/heads/p4a/wire` to
`712c9467` (from the `70e742a3` merged here); `p4a/esprytobj` is at `ef6beb28` and `p4a/gates` at
`ecf9cb45`. The four hashes in the table above are therefore snapshots of what this round was BUILT and
GATED against, not a claim about the current pipe.
### 1.1 Why `p4a/clientsp` had to be merged, and what it costs
ID-14/ID-17 and this rework's item (4) require `MGPTextureParams::BuiltinSampler` to come from **C's**
content-addressed cache — `MGPipeSamplerCsoCacheInstance().Acquire(params, payloadBytes)` /
`Release(handle)`, spelled in `clientsp-v2.md` §3. On the base recipe's tree
`MG_Impl/Pipe/SamplerEmit.h` is still the **76-line contract stub**: it declares no cache, so the call
does not compile, and c0b's `ForwardWhenWired` idiom cannot help (the cache is reached by a *free function
name*, which is non-dependent and is therefore looked up even in a discarded `if constexpr` arm). There is
no way to write the required call against the stub, so the head that declares it was merged.
The merge conflicted in four files — `MG_Test/Pipe/{CompositeResolver,ImageEmit,ProgramEmit,SamplerEmit}Test.cpp`
— because wire and clientsp both **append** at the same anchor. Resolved by **union**, verified exact:
re-run with `merge.conflictStyle=diff3 -X diff-algorithm=histogram` every conflict region has an **empty
base**, i.e. both sides are pure additions with nothing removed, so dropping the four marker lines is the
whole resolution. Checked afterwards: 0 duplicate `TEST(` names, 0 duplicate `#define`s, one
`MGL_*_TEST_LIST` per file, and G2 (pull == push name sets) is 0 diff lines.
**Consequence the integrator must decide:** ID-19's order is `B v2 -> C v2`. B's landing commit does not
compile before C's, so either the two land together, the order swaps, or B lands with D10 still
identity-addressed and takes the cache at C's verification round (the review's §3.4 option (a)). The code
here assumes they are one landing.
---
## 2. Item by item
### (1) c0b reconciliation — the two-TU deviation is gone
`MG_Impl/Pipe/TextureEmit.h`
* **Deleted** all eight free functions and both destructor call sites (`TextureEmit.h`, the block that was
`:986-1082`). MG_State now calls only what `MG_Pipe/PipeMutation.h` declares, and **no MG_State
translation unit includes an emitter header** — the `#include <MG_Impl/Pipe/TextureEmit.h>` is gone from
`TextureObject.cpp:22` and `RenderbufferObject.cpp:17`, and the second is replaced by
`#include <MG_Pipe/PipeMutation.h>` (`RenderbufferObject.cpp:12`).
* **Renamed to the contract's spellings**: `EmitTextureCreate` + `EmitTextureCreateFromBase` collapse into
one `EmitResourceCreate(ITextureObject&)` (`TextureEmit.h:520`); `EmitTextureRespecify` ->
`EmitResourceRespecify` (`:544`); `NoteLevelDirty(ITextureObject&, Uint32, Uint32)` (`:786`).
`EmitTextureParams`, `EmitRenderbufferCreate`, `EmitRenderbufferRespecify` already matched.
`MGPipeEmitTextureParams` was the **name collision** the review predicted; the inline definition is gone.
* **`EmitResourceCreate` reads only what `TextureObjectBase` itself implements.** It is called from that
class's constructor, so `GetStorageType()` and `GetUploadTargets()` (pure, no body on the base) would be
undefined behaviour; `GetTarget()`, `GetExternalIndex()` and `GetLifetimeId()` are `override`s **on the
base**, so they dispatch to the base's own bodies over members the mem-init list has already written.
The storage kind stays target-derived. Stated at `TextureEmit.h:512-519` and
`TextureObject.cpp:110-131`.
* **Publication latch**: `Entry::Published`, `TextureRecordIsPublished`, `RenderbufferRecordIsPublished`,
`NoteTextureRecordDestroyed`, `NoteRenderbufferRecordDestroyed`, `PublishedIn` and `Retire` are all
deleted. `MGPipeNoteHandlePublished` is called from `PublishCreate` (`TextureEmit.h:1002`) — **only when
the create was accepted**, because the death helper reads that latch and a latch taken on a refused
create would emit a `resource_destroy` for a record that does not exist. `MGPipeHandleIsPublished` drives
the self-healing create at `:566` and `:632`.
* **Call sites repointed**: `TextureObject.cpp:62` (one helper, not two), `:68` `MGPipeEmitTextureResourceRespecify`,
`:72` `MGPipeEmitTextureParams` (the contract's), `:76` `MGPipeNoteTextureLevelDirty` with `Uint32`s,
`:125-131` `MGPipeMintTextureHandle` **and** `MGPipeEmitTextureResourceCreate`;
`RenderbufferObject.cpp:42-48` the mint plus the create, `:54` one helper, `:148`
`MGPipeEmitRenderbufferResourceRespecify`.
**Declared deviation (the one thing c0b does not give B): the drain list has no clean arm.** The contract's
`MGPipeNoteTextureLevelDirty` carries no `dirty` flag. Rather than ask A to widen the signature or keep a
second B-owned entry point (which would have kept the two-TU coupling the rework exists to remove), the
clean arm is **retired**: a level that goes clean stays on the list until the next drain, where
`!mipmap->IsStorageDirty(...)` is the *first* test `EmitOneLevel` makes and returns "nothing owed", so the
entry is dropped from both lists there. Cost: one `IsStorageDirty` call per cleaned level per drain; the
list is bounded by the (texture, level) pairs dirtied since the last validate point; nothing clears a dirty
flag on this path, so no texels can be lost. `TextureObject.cpp:501` and `TextureObject2DCube.cpp:68`
become `if (dirty) PipeNoteLevelDirty(...)`; `TextureObject.h:235` loses the parameter. Pinned by
`TextureEmit.ALevelMarkedCleanIsCollectedAtTheNextDrain`.
### (2) c0c helper deletions and `MGPSurface::TextureTarget`
* Deleted `MGPipePackSubDataTarget` / `MGPipeSubDataResourceTargetOf` / `MGPipeSubDataUploadTargetOf` and
their `static_assert` (`TextureEmit.h`, was `:162-176`), and `kMGPipeDepthStencilModeDepth/Stencil`
(was `:182-183`). `MGPipeDepthStencilModeByte` stays (GLenum -> byte is frontend knowledge).
The one call site now widens to the contract's `Uint32` parameters (`TextureEmit.h:1003`).
* Deleted `kMGPipeSurfaceKindNone/Texture/Renderbuffer` and their `static_assert`
(`FramebufferEmit.h`, was `:73-77`).
* **`MGPSurface::TextureTarget` filled**: `static_cast<Uint16>(texture->GetTarget())` on the texture arm
(`FramebufferEmit.h:139`), `kMGPipeSurfaceNoTextureTarget` on the renderbuffer arm, on the empty-point
early return and on the two `SurfaceOf` early returns — through one `MGPipeEmptySurface()` helper
(`:113-118`) so a zero-initialised record cannot say `TextureTarget = 0` (which is `Texture1D`).
* **Added to the hash**: `MGPipeCopySurfaceForHash` copies it (`:196-201`). It is a `PipeFields.def` row, so
a field-wise copy that skipped it would suppress a record whose only moved field is the attachment's
texture target — the field three of the four cross-object masks read.
* **m6 folded in**: `MGPSurface::UploadTarget` is `TextureUploadTarget::Unknown` rather than `0` on every
non-texture point, the same rule for the same collision. `FramebufferEmitTest`'s
`Color[1].UploadTarget == 0u` assertion moved with it.
### (3) M1 — the region tail
`TextureEmit.h:1029-1033`: `MGPipeApplyResourceSubData(m_lastSubData, shadow, m_regions.empty() ? nullptr :
m_regions.data())`. Null stays correct for the whole-level shape, where `RegionCount` is 0.
New case `TextureEmit.TheApplierStoresTheRegionListTheEmitterBuiltAndNotAnEmptyOne` asserts on
`MGPipeApplier().TextureResources[slot].PendingUploads[...]` — **what the applier stored**, field by field
(`X`, `Y`, `W`, `H`, `SrcOffset`, `SrcRowStride`, `SrcSliceStride`) — rather than on `LastRegions()`, which
is the emitter's own staging vector and is why v1's four region cases could not see the omission.
### (4) M2 + ID-14/ID-17 — the built-in sampler and the thirteenth aggregate site
* **The hook** (`GL_Texture.cpp` grant, three call sites, §3): every `glTexParameter*` that writes
`GL_TEXTURE_MIN_LOD` / `MAX_LOD` / `LOD_BIAS` lands on the texture's built-in `SamplerObject` and on
nothing the texture's own params version watches. The three choke points now call
`MG_Pipe::MGPipeEmitTextureParams(*textureObject)` after their switch (so the error arms return without
emitting).
* **The version-first skip reads both counters** (`TextureEmit.h:660-673`): `GetTextureParamsVersion()`
**and** `SamplerObject::GetVersion()`, plus `ForceParamsResync` as a third input because an
`ImageBindableHint` transition moves neither. This is clientsp-v2 rule 4 and it is what makes the new
hook free when nothing moved.
* **The cache** (`:675-700`): `MGPipeSamplerCsoCacheInstance().Acquire(sampler->GetAllSamplerParameters(),
samplerBytes)`; the previous handle is `Release`d when the content moves it, and the duplicate reference
is handed straight back when the value did not move, so the entry holds **exactly one** reference.
`MGPipeSlots().Acquire(MGPipeKind::SamplerCso, ...)` is deleted (rule 1). `samplerBytes` is accumulated
into `SamplerCsoPayloadBytes()` rather than discarded (rule 3's accounting).
* **Texture death** (rule 3): the death helper is A's and does not forward here, so the reference is given
back at the only moment this package can see a texture die — `RetireIfRecycled` in `AcquireTexture`
(`:1050-1063`), when the allocator hands the slot out again. Bounded by live texture slots.
`ResetForTest` releases every held reference too, so a unit case cannot pin the cache for the process.
* **`SamplerResync` stays 0 and stays the server's** (D-E2): the failure it guards is an incomplete texture
sampling `(0,0,0,1)` after a driver re-mint, set by `RequireImageBindableStorage` /
`RecreateBackendTexture` on the twin. The client's one request is `ForceResync` after an
`ImageBindableHint` transition, and it is unchanged. The re-sync ID-14 needs is the **record itself**
going out again, not a byte.
Cases: `ALodWriteOnTheBuiltinSamplerRepublishesTheParams` (a write only the sampler object sees republishes;
an unchanged texture does not) and `ATexturesBuiltinSamplerHoldsOneCacheReferenceAndSwapsItWithTheContent`.
`EveryTexturesParamsNameItsBuiltinSamplerCso` now asserts `RecordIsPublished(...)` and
`RefCountOf(...) >= 1` and that **no** `SamplerCso` slot is keyed on the `SamplerObject`'s lifetime id.
`TwoTexturesWithIdenticalSamplingShareOneBuiltinCso` no longer skips (a `static_assert` forbids it).
**Declared:** the three `GL_Texture.cpp` call sites themselves are not pinned by a unit case — a
`MG_Test/Pipe` binary cannot drive `glTexParameterf` without a bound, context-registered texture, and
`MG_Test/Texture/TextureTest.cpp` (which can) is not in C.7's list for this package. The unit case drives
the exact call those sites make; the wiring rides the integration lane's texture family.
### (5) M3 — clear on acceptance, never on dispatch
`TextureEmit.h:1029-1064`. `accepted` comes from `MGPipeApplyResourceSubData`; `dispatched` is the
`if constexpr` itself, so a discarded call never clears either. A refused level **stays dirty and stays on
the drain list**, is counted (`RefusedSubDataCount()`) and is loud once (`MGLOG_E_ONCE` naming the
`{slot, gen}` and the level), because a permanently refused level would otherwise re-emit once per verb
for ever. The same rule is applied to the two calls that DEFINE the storage: `PublishCreate` takes the
latch only on acceptance, and `NoteRespecified` advances the descriptor mirror only on acceptance — a
refused respecify must not leave `LastDesc` claiming the applier holds it, or the next identical call is
deduped against a record that was never stored.
`ARefusedUploadLeavesTheLevelDirtyAndOnTheDrainList` constructs a real refusal
(`MGPipeApplierReleaseObjectRecords()`, i.e. the applier holds no record for the handle — the ordinary
shape of a texture born while the subsystem bit was clear) and asserts the flag survives, the drain entry
survives, and the emission was counted as refused.
**A second finding came out of writing it, and it is fixed here.** The self-heal was keyed on the
publication latch alone, and the latch answers *"did a create for this handle go out"* — which stays true
after `MGPipeApplierReleaseObjectRecords` has dropped every object record, the scope a served context's
teardown takes while the frontend objects live on in the share group. So a texture whose record the applier
had dropped would have had **every** later respecify refused, for ever, with no path back. The applier's
own refusal is now the second, authoritative signal: a refused respecify republishes the create and retries
once (`TextureEmit.h:600-621`, and the renderbuffer twin at `:645-657`). One retry, never a loop.
Pinned by the second half of the same case.
### (6) M4 — a mask change after the allocation is a metadata respecify
`NoteTextureBoundAs` / `NoteRenderbufferBoundAs` (`TextureEmit.h:475-521`) return early when the mask did
not actually move, and otherwise call `RepublishMask` (`:1084-1101`), which re-emits **`entry.LastDesc`
with the new mask and hint** — every storage-defining field byte-identical to what the applier holds, which
is exactly the shape wire applies as a metadata update: the descriptor is replaced, the serial advances, no
reallocation is acked and **no pending upload is dropped**. Gated on the family being live and on the
handle being published (before that, the create or the first respecify carries the mask anyway — both read
`entry.BindMask`).
`AnImmutableTexturesImageBindableHintReachesTheApplierAfterItsAllocation`: `glTexStorage`-shaped immutable
texture, a pending upload standing, then the image bind. Asserts `ImageBindableHint == 1` **on the
applier's record**, `BindMask`, that `Width` did not move, that the serial advanced, and that the pending
upload survived. `AnImageBoundTextureCarriesTheImageBindableHintForever` gained the reversed-order half
(allocate, then bind) that v1 could not fail, plus "a second note of the same bit emits nothing".
### (7) ID-19(c) — a record for every framebuffer handed over by name
`MGPipeFramebufferEmitter::EmitFramebufferByName(const FramebufferObject&)` (`FramebufferEmit.h:299-360`).
`Target` is `Named` **only when the object is bound to neither binding**; a bound object gets
`Draw`/`Read`/`Both` instead, because a record always writes `FramebufferRecords[Fbo.Slot]` and a Named
record on a bound object would leave the record saying "no binding" while `BoundFramebuffer` still resolves
through it. Suppressor: a **per-framebuffer** slot-indexed table with the generation checked
(`m_named`, `NamedEntryFor`), so two different objects' Named records in a row both go out; the two bound
latches are untouched, because they answer the different question "does the server's draw/read binding
already hold this record". `Reset()` clears the Named table (safe direction: this emitter cannot tell
`MGPipeApplierReset` from `ReleaseObjectRecords`).
**The GLImpl sites hooked — all in `MG_Impl/GLImpl/Framebuffer/GL_Framebuffer.cpp`, which is the only file
in the tree containing a DSA framebuffer entry point.** One `PipePublishFramebufferByName` helper
(`:648`), sixteen call sites:
| kind | entry point | site | where |
|---|---|---|---|
| consumer | `glBlitNamedFramebuffer` | `:672`, `:673` (both objects) | before `MGP_FILL(BlitNamedFramebuffer)` |
| consumer | `glClearNamedFramebufferfv` | `:688` | before `MGP_FILL` |
| consumer | `glClearNamedFramebufferfi` | `:702` | before `MGP_FILL` |
| consumer | `glClearNamedFramebufferiv` | `:716` | before `MGP_FILL` |
| consumer | `glClearNamedFramebufferuiv` | `:730` | before `MGP_FILL` |
| mutator | `glNamedFramebufferTexture` | `:1461` (detach), `:1490` (attach) | after the mutation |
| mutator | `glNamedFramebufferTexture1D/2D` (shared helper) | `:1516`, `:1546` | after the mutation |
| mutator | `glNamedFramebufferTextureLayer` | `:1603`, `:1708` | after the mutation |
| mutator | `glNamedFramebufferRenderbuffer` | `:1780`, `:1792` | after the mutation |
| mutator | `glNamedFramebufferDrawBuffers` | `:1994` | after the delegate |
| mutator | `glNamedFramebufferDrawBuffer` | `:2011` | after the delegate |
| mutator | `glNamedFramebufferReadBuffer` | `:2023` | after the delegate |
The five **consumers** publish before `MGP_FILL`, so the record precedes the verb that hands the object
over and a later bound-target record for the same object still wins. The ten **mutators** publish after
the frontend mutation because they have **no validate point at all** — `FillPoints.def` has no verb for
any of them, so there is no `MGP_FILL` to sit in front of; "the point at which the object is final for
this call" is the only reading of ID-19(c)'s "at their validate point" that exists for them. Inventing a
fill point would be a contract change (`FillPoints.def` is A's).
Not hooked, with reasons: `glNamedFramebufferTexture3D` is a stub that never resolves a framebuffer;
`glCheckNamedFramebufferStatus`, `glGetNamedFramebufferParameteriv`,
`glGetNamedFramebufferAttachmentParameteriv` are pure queries; `glInvalidateNamedFramebufferData/SubData`
validate and do nothing; `glNamedFramebufferParameteri` writes the no-attachment defaults, which the
record's `FillGeometry` reads only when there is no attachment — hooking it would be harmless and it is
declared rather than added, because it is not an entry point that hands the object to the server.
`GetNamedFramebufferObject_State` and `GetFramebufferObjectForNamedClear` were rejected as hook points:
they run **before** the mutation, so the record would describe the previous state.
Cases: `AFramebufferHandedOverByNameGetsANamedRecordWithoutMovingABinding` (the record exists in
`FramebufferRecordFor`, describes the named object, and neither binding moved) and
`ANamedRecordIsSuppressedPerObjectAndNeverAgainstABoundRecord`.
### (8) The nine minors
| # | verdict | where |
|---|---|---|
| m1 cube face -> `targets[0]` | **fixed** | `MGPipeResolveAttachmentUploadTarget` falls back only when the texture has **exactly one** upload target; anything else keeps `Unknown` (`FramebufferEmit.h:100-108`). Case `ALayeredCubeAttachmentDoesNotAssertAFaceItCannotKnow`. |
| m2 draw-buffer tokens >= 8 | **fixed** | `MGPipeDrawBufferIsInsideTheWireWidth` (`:160-172`) + the second refusal loop in `BuildFramebufferState` (`:436-452`). Case `ADrawBufferTokenAboveTheWireWidthIsRefusedNotTruncated`. |
| m3 dangling `Entry&` | **fixed** | the view owner is acquired **before** any `Entry&` is taken; every reference in `EmitResourceRespecify` is taken after the last call that can `resize()` the table (`TextureEmit.h:544-590`). |
| m4 unpublished entries never retired | **fixed** | `RetireIfRecycled` in both `Acquire*` (`TextureEmit.h:441-460`, `:1050-1063`): a generation change resets the whole `Entry` and releases the built-in sampler's cache reference. Case `ARecycledTextureSlotDoesNotInheritItsPredecessorsBindMask`. |
| m5 a Draw record's `ReadSurface` | **fixed, and by c0e rather than declared** | `MGPipeTypes.h` now states that ReadSurface is resolved from **that framebuffer's own** read buffer under every target, Named included. `BuildFramebufferState` lost its `readFbo` parameter (`FramebufferEmit.h:410-425`); the redundant draw emission on a `glReadBuffer` goes with it. Case renamed `EveryRecordsReadSurfaceComesFromItsOwnFramebuffersReadBuffer` and now asserts the draw record's hash does **not** move when the read framebuffer's read buffer does. |
| m6 `UploadTarget = 0` | **fixed** | see item (2). Case `EveryNonTexturePointCarriesTheUnknownSentinelsRatherThanZero`, which also proves the field is in the hash. |
| m7 bit 9 wired, bit 10 unwired | **dissolved** | the D4 flip. The constraint is restated at `TextureEmit.h:92-96` so it cannot be dropped. |
| m8 `SetInternalFormat`'s zero-extent respecify | **declared** | the first `resource_respecify` for a texture still carries `Width = Height = Levels = 0`. It is not byte-equal to the create (the create leaves `InternalFormat` 0), so it is a real respecify to a zero extent, which every applier body tolerates; the real `glTexStorage` respecify replaces it. Gating the publish on `storageDefined` would mean adding a member to `TextureObjectBase`, which resizes the pull build's object and breaks G1. |
| m9 no DSA-named path in the G6 case | **declared** | all four GL entry points funnel into `FramebufferObject::AttachTexture`, so a state-level unit case cannot distinguish them. Item (7) does now give the DSA paths their own coverage, one level up. |
### (9) D4 — the flip, and the named expected-failing set
`TextureEmit.h:98`: `kMGPipeWiredTextureSubsystem = kMGPipeSubsystemTextureResources`, with the
`0-or-its-own-bit` assert beside it. `ArmForTest` / `m_armed` are **deleted** with it and
`MGPipeTextureSubsystemEnabled()` is the config-bit test alone — `PipeFill.cpp`'s
`FamilyIsLive` never consulted that latch, so after the flip it could only lie. Both suites' scopes now
arm `MG_Config::Features.PipePush` (and reset the applier per case, since the emissions actually land).
**The named expected-failing set is EMPTY.** All five are green in `build-push`:
| case | |
|---|---|
| `TextureEmit.TheUnionBoxAndTheRegionListDescribeTheSameTexels` | pass |
| `TextureEmit.AScatteredUploadCarriesTheLevelShadowsStridesAndNotZero` | pass |
| `TextureEmit.AWholeLevelUploadCarriesZeroStrides` | pass |
| `TextureEmit.MoreThanKMaxDirtyRectsCollapsesToTheBoxWithRegionCountZero` | pass |
| `TextureTest.GetTexImageReadsALevelWhoseLowerLevelsWereNeverDefined` | pass |
---
## 3. The granted files, and every site in them
C.7 gives these to nobody; both are needed and both are granted under ID-8's rule ("the grant is one call
site per path and it is recorded as a deviation").
| file | why | sites |
|---|---|---|
| `MG_Impl/GLImpl/Texture/GL_Texture.cpp` | ID-18 M2. `SamplerObject::BumpVersion` is `MG_State/GLState/SamplerState`, which is package C's after the tag, so the hook cannot go there. | **three**, one per path: `TextureParameterObject_State` `:1365`, `TextureParameterObjectf_State` `:1467`, `TexParameterf_State` `:2181` — each after its switch, so the error arms return without emitting. `TexParameteri_State`, the four `TexParameter*v_State` families and the DSA `TextureParameter*` all funnel into these three. One include added (`MG_Pipe/PipeMutation.h`, a declaration only). |
| `MG_Impl/GLImpl/Framebuffer/GL_Framebuffer.cpp` | ID-19(c). Every DSA framebuffer entry point in the tree is in this one file. | **sixteen**, listed in §2 item (7), plus one helper and one include (`MG_Impl/Pipe/FramebufferEmit.h` — same layer; this file already includes `MG_Impl/Pipe/PipeFill.h`). |
Every added statement in both files is inside a `#if MOBILEGL_PIPE_PUSH` block, so the pull build's
preprocessed text and symbol set do not move (G1 confirms: 0/0/0/0).
---
## 4. Gate numbers — HEAD `d1215fbc`
| gate | result |
|---|---|
| builds | `build-linux` rc 0, `build-push` rc 0, `build-verify` rc 0 |
| **G1** `symbol_report --threshold 0` vs `~/w7/p4a-before-libMobileGL.so` | `.text` 10806323 -> 10806323 (+0, +0.000%); 27811 -> 27811 defined symbols; **0 added / 0 removed / 0 resized / 0 renamed** |
| `gen_pipe.py --check` | generated files are up to date; `git diff --stat MobileGL/MG_Pipe/generated` = **0 lines**; `--self-test` 7 negative-control trips, positive control OK |
| `gen_pipe_dirty_surface.py --check` | only the two known UNDECIDED rows (D6: `BindVertexArray <- NEW_VERTEX_ELEMENTS`, `UseProgram <- NEW_SHADER`), both still marked with the tool's reason |
| `gen_pipe_dirty_surface.py --self-test` | 27 negative controls, all tripped; positive controls OK |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all` | **rc 0**, 4 probes, 0 skipped, **0 problems**; self-test 6 negative-control trips (re-run for `TextureEmit.h`'s new `SamplerEmit.h` include and `GL_Framebuffer.cpp`'s) |
| **G5** `scripts/p3a_untouched_regions.sh 37da3c3a HEAD` | **rc 0** — byte-identical |
| `ctest -L unit` `build-linux` | **1756 / 1756** |
| `ctest -L unit` `build-push` | **1756 / 1756** |
| `ctest -L unit` `build-verify` | 1750 / 1756 — **six failures, all pre-existing on the merged base; see §6** |
| **G2** names pull == push | **0 diff lines** |
| **G14** vs `~/w7/p4a-before-ctest-names.txt` | **0 removed**, **+134 added** |
| emit suites (`TextureEmit|FramebufferEmit|SamplerEmit|ImageEmit|ProgramEmit|ResourceEmit|VertexInputEmit|CompositeResolver`) | **148 / 148** |
| `integration-gpu -R DirectGLES -j 8`, **default arm (0x1fff)** | 444 / 491 — **47 failures, one proved cause; see §5** |
| `integration-gpu -R DirectGLES -j 8`, **`MOBILEGL_PIPE_PUSH=0x1ff`** | **491 / 491** |
| `integration-gpu -R DirectGLES -j 8`, **`MOBILEGL_PIPE_PUSH=0`** | **491 / 491** |
| `integration-verify -j 4` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`, **0x1ff** | **844 / 844**, **0 `Fatal{` lines** |
| `integration-verify -j 4`, default arm | 735 / 844 — the same 47 scenarios under the Verify label, same cause; **0 `Fatal{` lines** |
| retrace, **0x1ff** (`git lfs checkout` first, 0 pointers left) | **79 / 79** |
| retrace, default arm | 0 / 79 — same cause |
Per-bit bisect of the integration-gpu arm, which is what isolates the cause
(`0x200` framebuffer, `0x400` textures, `0x800` samplers, `0x1000` programs):
| mask | result |
|---|---|
| `0x1ff` (P3a only) | 491 / 491 |
| `0x3ff` (+ framebuffer, bit 9) | **491 / 491** |
| `0x5ff` (+ textures, bit 10) | **444 / 491** |
| `0x9ff` (+ samplers, bit 11) | **491 / 491** |
| `0x11ff` (+ programs, bit 12) | **491 / 491** |
| `0xdff` (+ textures + samplers) | 444 / 491 |
| `0x1fff` (default) | 444 / 491 |
**Exactly bit 10, and exactly the same 47 every time.** The full list of 47 is at
`~/w7/p4a-clientfb-47.txt` while this round's logs stand; every one of them is a scenario that uploads
texels and reads them back (`SwizzleAccessRoutine`, `CopyImage*`, `PackedWordReadback`, `GuiBatch`,
`ClearTexImageUndefinedLevelZero`, `LayeredAttachment*`, `FormatlessImageBake`, ...), and the failure shape
is uniform: `textureGradOffset(...).w returned 0x0 instead of 0xffffffff at texel 0 (64 of 64 wrong)` —
the texels never reached the driver.
---
## 5. THE ONE THING THE INTEGRATOR HAS TO DECIDE: bit 10 needs package D, not just wire
**Negative control, and it is unambiguous.** On the default arm, with the emission left exactly as it is
and **only** the client-side dirty-flag clear removed (`EmitOneLevel`'s
`mipmap->MarkStorageDirty(uploadTarget, level, false)` put behind a probe environment variable):
| arm | result |
|---|---|
| default, client clear **present** (HEAD) | 444 / 491 |
| default, client clear **removed** | **491 / 491** |
So all 47 integration failures, the 109 integration-verify failures and the 0/79 retrace have **one cause**:
D-D5 step 1's inversion has landed its client half and this tree has no server half.
`DrainTextureSubData` clears the frontend's per-level dirty flag as soon as the applier accepts the record.
The texels then live only in `MGPipeResourceRecord::PendingUploads`, which is **package D's** to consume —
Espryt's texture arm reads the applier's pending set instead of the frontend flags. Neither `p4a/esprytobj`
nor `p4a/esprytdraw` is in this tree, so the base Espryt still reads `IsStorageDirty()`, finds it clear, and
uploads nothing. This is the inversion working exactly as designed with one half present, not a defect in
this package: the client half is required and correct, and it is destructive on its own.
**It is not fixable client-side.** The client cannot ask whether a server-side consumer exists, and keeping
the frontend flag set would double-upload once D lands.
**Recommendation, and it is the integrator's call:**
1. **Land B's D4 flip together with package D's texture arm** — the one line `TextureEmit.h:98` is the whole
switch, so it can equally be moved into D's commit and B lands with the constant at 0 and everything else
in place. That keeps every intermediate tree green and keeps a bisect meaningful, which is why it is the
recommendation.
2. Or land it here and run every gate between B and D at `0x1ff`, accepting that the default arm and the
retrace are red for that window.
Either way **D-K2 gains a row**, and it is stronger than the two it already has: *bit 10 requires the
server-side texture consumer*, not merely bit 11. Bits 9, 11 and 12 have no such dependency — the bisect
above shows each of them alone is 491/491, because their emissions are records the server may ignore, while
bit 10's emission **takes state away from the legacy path**. That asymmetry is worth recording in the brief
beside D-K2, because it is the only P4a subsystem bit that is not independently switchable.
---
## 6. The six `build-verify` unit failures are not this package's
| case | suite owner |
|---|---|
| `SamplerEmit.ARecordThatDoesNotDescribeItsOwnParametersIsRefusedNamingTheLength` | wire |
| `SamplerEmit.AUnitWindowPastTheMergedUnitSpaceIsRefusedRatherThanTruncated` | wire |
| `ImageEmit.AnImageWindowPastTheImageUnitSpaceIsRefusedRatherThanTruncated` | wire |
| `ProgramEmit.ACreateWithNoArtefactsAnOversizedBlockOrACorruptSlotIsRefusedNamingTheProgram` | wire |
| `ProgramEmit.TheDefaultUniformBlockLandsOnTheProgramsRecordAndTheSentinelIsRefused` | wire |
| `CompositeResolver.ASlotAtTheShaderCsoLimitIsRefusedWhileTheLastBandSlotIsNot` | wire |
All six are wire-authored **applier** refusal cases, verify lane only (`build-push` is 1756/1756), and none
is in either of B's two suites. They fail as `the gate fired without naming what it refused ... log: ` with
an **empty** child log: the forked child does die of the abort, and produces no log text in a
`MOBILEGL_PIPE_VERIFY` build.
**Control run.** `git checkout 8534abf7 -- <the eight library files B changed>` (the four conflicted test
files are untouched by B's four commits — `git diff --stat 8534abf7..HEAD` lists them nowhere), rebuild
`build-verify`, re-run the six: **0 / 6 passed, the same six, identically**. So they predate B's rework and
belong to the `wire v3` x `clientsp v2` seam on the verify lane. The integrator sees them on the integrated
tree whether or not B lands.
---
## 7. What the integrator must re-run, and in what order
1. **Decide §5 first.** Everything below is conditional on it. If the flip moves into D's commit, re-run the
default arm and the retrace there and expect 491/491 and 79/79; if it stays here, the window between B
and D is knowingly red on those two and must be gated at `0x1ff`.
2. **The integration order question in §1.1**: B's landing commit does not compile before `p4a/clientsp`.
3. On the integrated tree, the residual-record sweep ID-12 names: the 183 "no applier record" refusals must
go to zero. **Not answerable here** — the string does not occur once in this tree's integration logs,
because the arms that emit it are package D's and are not present. Report deferred to D's round.
4. `integration-verify` on the **DirectVulkan** lane for the per-kind leak test (ID-8): this tree's
`integration-verify` label runs the DirectGLES scenarios; `~TextureObjectBase` and `~RenderbufferObject`
reaching a live applier is exercised by `TextureEmit.ADestroyedTextureReleasesItsResourceViewAndBuiltinSamplerSlots`
and by `HandleRecycle`, both green, but the DirectVulkan arm of the leak test is the integrator's.
5. The **G9 white-box assertion** (ID-19/ID-22) and package F's `0x5ff` / `0x9ff` dependency-refusal arms:
`0x5ff` is 444/491 here for §5's reason and **not** for D-K2's "bit 10 requires bit 11", so F's scenario
cannot be read off this tree either.
6. The six of §6, once wire's verification round has looked at the verify-lane trip-wire logging.
7. `549ef30b` is a merge seam: drop it with the merges, or keep it if wire's verification round has not yet
retired `kMGPipeFramebufferTargetNamed` itself.
---
## 8. Deviations declared in this round
| # | deviation | reason |
|---|---|---|
| **D12** | the drain list has **no clean arm** | §2 item (1). The contract's hook carries no `dirty` flag; the collection moves to the next drain, where `IsStorageDirty` is already the first test. No texels can be lost by it. |
| **D13** | `p4a/clientsp` merged as a fourth head | §1.1. The ID-14/ID-17 call does not compile against the contract stub and `ForwardWhenWired` cannot reach a free function name. |
| **D14** | the three `GL_Texture.cpp` call sites are not pinned by a unit case | §2 item (4). A `MG_Test/Pipe` binary cannot drive `glTexParameterf`; the file that can is not in C.7's list for this package. |
| **D15** | the ten DSA **mutators** publish *after* the mutation rather than at a validate point | §2 item (7). They have no validate point — `FillPoints.def` has no verb for any of them, and that file is A's. |
| **D16** | m8 (`SetInternalFormat`'s zero-extent respecify) and m9 (no DSA-named path in the G6 case) declared rather than fixed | §2 item (8). |
| **D17** | the emitter's descriptor dedupe can suppress a respecify the applier no longer holds | The dedupe compares against B's mirror of the accepted descriptor. After `MGPipeApplierReleaseObjectRecords` the mirror is stale and a respecify that moves no field returns before reaching the applier, so the self-heal of §2 item (5) cannot fire for it. The refused **upload** is loud once per handle and the next real storage change heals it. Fixing it would mean asking the applier on every respecify, which is the roundtrip the dedupe exists to avoid. |
*Retired from v1:* D1 (the two-TU deviation — c0b), D2/D7/D9 (adopted into c0c), D3 (c0b's death helpers),
D4 (flipped), D10/D11 (ID-14/ID-17: the cache, no per-texture `SamplerCso` mint, nothing to leak).
D5, D6, D8 stand unchanged.
---
## Appendix — the 47 default-arm integration failures, by name
Identical on every mask containing bit 10 (`0x5ff`, `0xdff`, `0x1fff`); **all 47 pass** with the
client-side dirty-flag clear removed (§5's negative control), and all 47 pass at `0x1ff`.
Every one uploads texels and reads them back.
```
DirectGLES.ClearTexImageUndefinedLevelZeroScenario.AnOrdinaryLevelZeroTextureStillReadsBackCorrectly
DirectGLES.ClearTexImageUndefinedLevelZeroScenario.ReadBackALevelSeparatedFromLevelZeroByAGap
DirectGLES.CopyImageLayeredScenario.ArrayToArrayCopiesEverySlice
DirectGLES.CopyImageLayeredScenario.ArrayToArrayHonoursDifferentLayerOffsets
DirectGLES.CopyImageLayeredScenario.ArrayToVolumeCopiesEverySlice
DirectGLES.CopyImageLayeredScenario.VolumeToArrayCopiesEverySlice
DirectGLES.CopyImageLayeredScenario.VolumeToVolumeAtNonZeroMipLevel
DirectGLES.CopyImageLayeredScenario.VolumeToVolumeHonoursNonZeroZ
DirectGLES.CopyImageLevelRangeScenario.AValidLevelZeroCopyStillMovesPixels
DirectGLES.CopyImagePacked16Scenario.ArrayMipLevelLandsInFlatImageIntact
DirectGLES.CopyImagePacked16Scenario.FlatImageLandsInArrayMipLevelIntact
DirectGLES.CopyImagePacked16Scenario.RenderbufferLandsInArrayMipLevelIntact
DirectGLES.EmptyScissorScenario.AnExplicitlyEmptyScissorBoxClipsEveryFragment
DirectGLES.EmptyScissorScenario.IndexedZeroDimensionScissorBoxesClipEveryFragment
DirectGLES.FormatlessImageBakeScenario.CoreFormatBakedFromTheBoundUnitIsUnaffected
DirectGLES.FormatlessImageBakeScenario.R16uiBakedFromTheBoundUnitStillReachesTheDriver
DirectGLES.FormatlessImageBakeScenario.R8uiBakedFromTheBoundUnitStillReachesTheDriver
DirectGLES.FramebufferChurnScenario.RepeatedFramebufferReadbackStaysExact
DirectGLES.Glsl420DeclarationScenario.SamplerArrayElementsSampleConsecutiveTextureUnits
DirectGLES.GuiBatchScenario.Baseline
DirectGLES.GuiBatchScenario.BlendAndDepth
DirectGLES.GuiBatchScenario.FullFidelityWithRegrowth
DirectGLES.GuiBatchScenario.MeshesBlockLeftUnbound
DirectGLES.GuiBatchScenario.ShortIndices
DirectGLES.GuiBatchScenario.ThreeFramesWithoutRelayout
DirectGLES.GuiBatchScenario.TwoBuildersBaseVertex
DirectGLES.GuiBatchScenario.TwoBuildersShortIndicesBaseVertex
DirectGLES.GuiBatchScenario.TwoBuildersWideIndices
DirectGLES.IntegerBorderColorScenario.InsideTexelsAreUnaffectedByTheBorderColour
DirectGLES.LayeredAttachmentBarrierScenario.BlitBetweenNonZeroColorLayers
DirectGLES.LayeredAttachmentBarrierScenario.ReadPixelsOffRenderedNonZeroLayer
DirectGLES.LayeredAttachmentShapeScenario.NonLayeredThreeDSliceAttachmentWritesOnlyThatSlice
DirectGLES.NonCoreImageFormatScenario.NormalizedImageCarriesEveryLayerFaceOfACubeMapArray
DirectGLES.NoViewportArrayEmulation.ViewportArrayScenario.WithoutTheEmulationEveryIndexCollapsesOntoViewportZero
DirectGLES.PackedWordReadbackScenario.ACopiedRgb9E5WordSurvivesInAnR11fG11fB10fDestination
DirectGLES.PackedWordReadbackScenario.ACopyThroughARenderbufferReachesAnRgb9E5Destination
DirectGLES.PackedWordReadbackScenario.AnUploadedPackedWordReadsBackVerbatim
DirectGLES.PipelineFailureScenario.SamplerArrayInAStructDrawsWithoutKillingTheProcess
DirectGLES.PipelineFailureScenario.TheSameDrawRepeatsIdenticallyWithNoPoisonedPipelineCache
DirectGLES.ProgramPipelineScenario.ASamplerUnitRewrittenBetweenDrawsKeepsPaintingTheRightTexture
DirectGLES.SwizzleAccessRoutineScenario.EveryAccessRoutineFetchesTheSameTexelUnderTheIdentitySwizzle
DirectGLES.SwizzleAccessRoutineScenario.EveryAccessRoutineSeesAReversedSwizzle
DirectGLES.SwizzleAccessRoutineScenario.RepeatedProgramBuildsKeepFetchingTheSameTexel
DirectGLES.ViewportArrayScenario.AnIndexedScissorEnableClipsOnlyThatIndex
DirectGLES.WidenedPacked16.CopyImagePacked16Scenario.ArrayMipLevelLandsInFlatImageIntact
DirectGLES.WidenedPacked16.CopyImagePacked16Scenario.FlatImageLandsInArrayMipLevelIntact
DirectGLES.WidenedPacked16.CopyImagePacked16Scenario.RenderbufferLandsInArrayMipLevelIntact
```
The `integration-verify` default-arm residue (109 of 844) is the same scenarios under the
`DirectGLES.Verify.*` name plus their DirectVulkan twins; `0x1ff` is 844/844 with 0 `Fatal{` lines.
@@ -0,0 +1,470 @@
# P4a package C — `clientsp`. Adversarial review, v1
Target: `refs/heads/p4a/clientsp` = `ecd5b2e7`, four commits on `08192d72` (the tag `p4a/contract`).
11 files, +2426 / −52. Read-only review; no build, no worktree, nothing on the branch touched.
## Verdict — **REWORK**
The package is well built and the two hardest things in C.2 are right: the padding discipline (D1) is
correct at both the hash and the confirm, and the composite band is entered through exactly one door.
But a rework round is already mandatory (the c0b reconciliation, ID-13), and three defects in files C
owns must ride it, plus two cross-package under-fires that C's own subject matter surfaces and that
nobody else is positioned to notice:
* **C-M1** `MGPipeCompositeResolver::Reset()` permanently disarms the resolver's release path.
* **C-M2** a re-issued `create_shader_state` clears the applier's default uniform block (wire's W6) and
the emitter's `(Cso, Version)` latch is never invalidated, so the block is never re-sent.
* **C-M3** an LRU eviction of a sampler CSO silently invalidates every handle another record still
names — `MGPTextureParams::BuiltinSampler` above all, which wire says it deliberately does **not**
resolve. This is the seam ID-14 rules on, and ID-14 does not close it.
* **C-M4 / C-M5** (owner **A**, `Tracker.h`): `bind_sampler_states` cannot see `glBindSampler`, and the
whole program family is invisible to the dirty walk under a program pipeline.
None of these are visible on this branch — every applier entry point is a stub here — which is exactly
why they have to be written down before `wire` + `clientfb` + `esprytobj` are underneath them.
---
## 1. What was checked, and how
Every finding below was reached by opening the file, not by reading the report. The sources cross-read
were `INTEGRATOR-DECISIONS.md` (ID-8..ID-14), `BRIEF-P4A.md` D-F/D-G/D-H/D-I/D-J/D-K/D-L and C.2/C.7,
`contract-v2.md` §3 (the exact birth-hook declarations) and `wire-v1.md` §2.3/2.5/2.6/2.7/2.8/§4/§5 —
the last being what tells you what the applier actually stores and refuses, which several of C's
decisions have to be judged against and which C could not have read.
Not done, and stated as an absence: **no build and no test run.** The report's §5 transcript is
internally consistent (I re-derived the "38 added ctest names" as 13 contract + 25 C's from the four
files' `TEST(` macros and the pull skip lists, and it reconciles exactly), and the integrator re-runs
the whole gate on the integrated tree anyway. The LFS claim (D11) is **verified**: the fixtures in
`~/w7/p4a-clientsp/tools/trace_replay/fixtures` are 7–13 MB real archives and
`find … -size -1k | wc -l` is 0, so the 79/79 was read on real fixtures.
---
## 2. Findings in files C owns
### C-M1 [MAJOR] `MGPipeCompositeResolver::Reset()` permanently disarms the release path
`MG_Impl/Pipe/CompositeResolver.h:138-140`, `:104-107`, `:173-174`.
```cpp
void Reset() { for (Entry& entry : m_entries) entry.Live = false; } // :138-140
…
if (entry->Signature == signature && entry->Handle == handle) { // :104-107
++m_counters.Reuses;
return handle; // <-- returns WITHOUT restoring entry->Live
}
…
void ReleaseEntry(Entry& entry) { if (!entry.Live || …) return; … } // :173-174
```
**Failure scenario.** Bind pipeline P, draw — `Observe` mints an entry with `Live = true`. A
make-current arrives: `PipeFill.cpp:1908` calls `MGPipeProgramEmitterInstance().Reset()`, which calls
`MGPipeCompositeResolverInstance().Reset()` (`ProgramEmit.h:300`), and every entry goes `Live = false`.
The next draw has the same signature and the same handle, so `Observe` takes the *Reuses* branch and
returns before `entry->Live = true` — the entry is now stuck at `false` for the life of the process.
When the stage set really moves, `Observe` calls `ReleaseEntry`, which sees `!entry.Live` and returns
immediately: **no `delete_shader_state`, no `Free`, and the counter does not move**. The entry is then
overwritten with the new signature and handle, so the old composite's handle is lost from the resolver
entirely.
**Refutation attempted, and how far it gets.** Today nothing leaks: `ProgramPipelineObject` holds a
*one-slot* cache (`ProgramPipelineObject.h:149-159` — `SetCachedDrawProgram` overwrites
`m_drawProgram`), so the overwrite drops the last `SharedPtr` and `~ProgramObject` →
`MGPipeEmitShaderCsoDestroyAndFree` frees the slot. So the observable damage is zero *right now*. That
is precisely the argument the file's own header refuses to accept: *"the resolver still speaks the
release, because 'usually' is not a contract and a client that only reacted to destructors would leak a
slot the moment the frontend started holding a second reference"* (`CompositeResolver.h:31-35`). The
code does not do what the comment says it does, after the first make-current.
**Not caught by any case** — see C-m9.
**Fix**: set `entry->Live = true` in the reuse branch (or, better, do not clear `Live` in `Reset()` at
all — the memo's freshness is `Signature`/`Handle`, and `Live` is a *release obligation*, not
freshness; the two were conflated into one flag).
### C-M2 [MAJOR] a re-issued `create_shader_state` drops the server's global constants and nothing re-sends them
`MG_Impl/Pipe/ProgramEmit.h:195-245` (the re-issue) against `:164-168` (the latch), read against
`wire-v1.md` §4 **W6**: *"a re-issued `create_shader_state` clears the default uniform block."*
```cpp
// ProgramEmit.h:168
if (cso == m_constantsCso && version == m_constantsVersion) return bytes;
```
`AcquireShaderCso` re-issues the create whenever `GetLinkVersion()` moves (`:200-203`), and
`m_constantsCso` / `m_constantsVersion` are touched only by `EmitGlobalConstants` itself, by `Reset()`
and by `NoteRecordDestroyed` (which nothing calls).
**Failure scenario.** Program P is in use; `set_global_constants(H, V)` has gone out. The application
attaches a shader that will not compile and calls `glLinkProgram(P)`. The link **fails**;
`ProgramObject.cpp:357` bumps `m_linkVersion` regardless, and `ProgramObject.cpp:371` records that the
phase-B output (`globalUboScratch` included) is deliberately **not** cleared — which is right, because
GL keeps a program that is active for a stage running on its previous executable and uniforms after an
unsuccessful re-link. Next verb: bit 6 fires, `AcquireShaderCso` re-issues `create_shader_state` on
handle H, and the applier **clears the record's global constants** (W6). `GetUBOContentVersion()` did
not move, so bit 8 does not fire; and even when it is reached for another reason, `cso == H` and
`version == V` are both unchanged, so `EmitGlobalConstants` returns without emitting. The server now
draws P with a zeroed default uniform block while the client's scratch still holds the live values.
**Refutation attempted.** (a) *A successful relink is safe* — yes: `ProgramSpirvTask.cpp:352` clears and
re-sizes `globalUboScratch`, GL resets uniforms to 0 on a successful link, so the applier's cleared
block and the frontend's zeroed scratch agree, and the first `glUniform*` afterwards bumps the version
and re-emits. The bug is specific to the **re-issue without a content change**, of which the failed
relink is the reachable case. (b) *`RelinkStageSetScenario` would catch it* — it may, once E lands, but
by then the cause is three packages away. (c) *W6 landed after C's v1* — true, which is why this is a
rebase item rather than a defect of judgement.
**Fix**: one line in `AcquireShaderCso`, on the branch that actually emits — if
`m_constantsCso == handle`, reset `m_constantsCso = kMGPipeNullHandle` and
`m_constantsVersion = kMGPipeGlobalConstantsNeverUploaded`.
### C-M3 [MAJOR] LRU eviction invalidates handles other records still name, and the applier does not police them
`MG_Impl/Pipe/SamplerEmit.h:299-313` (`Evict`), `:252-258` (the LRU victim choice), `:167-170` (the
`static_assert` that is presented as making this safe), against `wire-v1.md` §2.3:
> `set_texture_params` … **not checked**: the CSO the record names is **not resolved**: the sampler bit
> may legitimately be clear while the texture bit is set, so an unresolvable `BuiltinSampler` is an
> ordering fact, not a corrupt one.
**Failure scenario.** ID-14 makes package B acquire `MGPTextureParams::BuiltinSampler` from this cache.
`set_texture_params` is emitted rarely — once per texture, then only when the texture's params move —
so a built-in sampler's entry is *touched* rarely and is therefore among the **first** LRU victims. Any
workload with more than 256 distinct live sampler values (a CTS sampler sweep; a scene with many
distinct filter/wrap/border combinations) evicts it. `Evict` emits `delete_sampler_state` and frees the
slot; the slot is re-handed out to a different value at `gen + 1`. The applier's
`MGPipeResourceRecord::Params.BuiltinSampler` still names `{slot, gen}` — and the applier **does not
resolve it**, so nothing refuses, nothing counts, nothing logs. Espryt's
`SyncBuiltinSamplerToBackend` then either misses (no twin at that generation) or, worse, finds the
slot's *new* occupant. Nothing re-emits `set_texture_params`, because the texture's params version did
not move: **an eviction is not a parameter change**, and D-E2's `SamplerResync` is not raised by it.
The same hazard applies, with a much smaller window, to a `MGPBoundView`/`bind_sampler_states` tail
already published: the record the applier holds is "the last set as received" and outlives the pass.
**Refutation attempted.** (a) *The `static_assert` closes it* (`SamplerEmit.h:167-170`): it closes only
the intra-pass case — 256 > 192 means one `EmitSamplerStates` pass cannot evict a handle that same pass
is about to name. It says nothing about a record published in an **earlier** pass, and the texture-params
record is exactly that. (b) *256 is never exceeded in practice*: correctness must not depend on cache
capacity, and this is the phase that runs the whole CTS. (c) *The applier refuses the stale gen loudly*
— it does not; wire says so in as many words. (d) *`~SamplerObject` covers it* — no: C deliberately gives
the content-addressed CSO no lifetime-id mapping (`SamplerEmit.h:161-166`), so
`MGPipeEmitSamplerCsoDestroyAndFree` resolves nothing and the LRU is the only death path, which is the
whole point of the design and also the whole problem.
**Fix, three shapes, integrator picks:** (i) an eviction hook that raises D-E2's `SamplerResync` for
every texture whose `BuiltinSampler` was the victim (needs a reverse map, or a global "CSO epoch" that
B's texture-params latch mixes in — cheapest and does not couple the two headers); (ii) pin entries a
live `set_texture_params` names, with the pin taken by B and dropped in the texture death helper (D5);
(iii) do not evict — replace LRU with "grow past 256 and log", which contradicts D-F1's capacity ruling
and therefore needs a brief amendment. **(i) is the smallest change that makes the failure impossible.**
---
## 3. Cross-package findings C's subject matter surfaces (owner: A — `Tracker.h` / `PipeFill.cpp`)
### C-M4 [MAJOR] `bind_sampler_states` cannot see `glBindSampler`
`PipeFill.cpp:1940-1942` gates `EmitSamplerStates` on `wants(MGPipeDirty::NewSamplers)`; bit 13's
shutter is `Mix(textureParams, ctx.GetSamplingResolutionGeneration())` (`Tracker.h`, the object-class
block). The only writers of `BumpSamplingResolutionGeneration` are `SamplerObject.cpp:65` and
`TextureObject.cpp:53` — both **parameter** changes. `glBindSampler` goes
`GL_Sampler.cpp:384 → TextureUnit::SetSamplerObject` → `TextureUnit.cpp:39`
`BumpTextureBindGeneration()`, which is **bit 12** (`NewSamplerViews`), not bit 13.
**Failure scenario.** `glBindSampler(3, samplerA)`; draw; `glBindSampler(3, samplerB)` with samplerB's
parameters differing from samplerA's; draw. Bit 12 fires both times (the view set is re-resolved,
correctly, because completeness depends on the effective sampler), bit 13 fires **neither** time. The
server's `BoundSamplerStates[3]` still names samplerA's CSO. Wrong filtering, no gate that sees it.
`Tracker.h`'s own rule is that over-firing is free and under-firing is fatal.
**Refutation attempted.** (a) *Something else bumps it* — grepped; there are exactly two writers, both
parameter paths. (b) *`GetTextureBindGeneration` is in bit 13 too* — it is not; it is in bit 12's mix
only. (c) *The legacy pull path saves it* — no: `bind_sampler_states` has no pulled twin;
`GetTextureUnitObject` is pulled, but `EmittedCallSuppliesTheWholeField(GetTextureUnitObject)` being
`false` means the field is still copied, so Espryt's *legacy* arm still works — the **push** arm is the
one that goes stale, and D-K3 says the legacy arm does not survive `MOBILEGL_PIPE_LEGACY_MEMOS=0`.
(d) *C's own case covers it* — `SamplerEmitTest.cpp:442` calls `Ctx().BumpTextureBindGeneration()` by
hand and then calls the emitter directly, which is bit **12**'s generation; the case documents the gap
rather than closing it.
**Fix (A's)**: either mix `GetTextureBindGeneration()` into bit 13's shutter, or gate `EmitSamplerStates`
on `wants(NewSamplers) || wants(NewSamplerViews)` in `PipeFill.cpp:1940`. Both are one line and both are
in files C may not touch.
### C-M5 [MAJOR] the program family is invisible to the dirty walk under a program pipeline
`Tracker.h` (bits 6/7/8): `const auto& program = ctx.GetCurrentProgram(); … if (program) { … }` — and
`Core.h:186` / `Core.cpp:611` make `GetCurrentProgram()` **null** whenever the application drove
`glUseProgram(0); glBindProgramPipeline(p)`. `Tracker.h` contains no reference to
`ProgramPipelineObject` at all (grepped).
**Failure scenario.** Bind pipeline P and draw: the *first* walk after a make-current is `!m_primed`, so
every bit fires once and the composite is emitted. Then `glUseProgramStages(P, …, newVs)` changes the
stage set; `GetProgramForDraw()` builds composite **B**. Bits 6/7/8 all still read `0 == 0`, so
`EmitShaderState` is never called again: **B never gets a `ShaderCso` handle, never gets a
`create_shader_state`, and `set_draw_program` keeps naming composite A**, whose `ProgramObject` the
one-slot pipeline cache has already dropped.
**Refutation attempted, and it does soften this.** `EmittedCallSuppliesTheWholeField(GetProgramForDraw)`
is `false` (`PipeFill.cpp:1383-1386`) and `DirtySurface.def:309-319` rules
`BindProgramPipelineObject` `kPulledEveryVerb` precisely because the field is *emitted-and-still-pulled*
— so the residual fill copies `m_programForDraw` at every verb and the **backend still receives the right
`SharedPtr`**. Rendering is therefore not wrong today. What *is* wrong is that D's re-keyed twin tables
resolve a program through its client-minted handle, and composite B has no handle at all
(`MGPipeSlots().FindByLifetimeId(ShaderCso, B)` misses), so D/E will see a program the handle protocol
never announced. That is a seam defect of exactly P3a's class, and it should be found now rather than in
E's verification round. Also note bit 8 never firing under SSO means `set_global_constants` is never
sent for a pipeline draw, and there the pull does **not** rescue anything.
**Fix (A's)**: mix the bound pipeline's identity and `ComputeDrawProgramSignature()` into bit 6 — the
signature is `{lifetimeId, GetLinkVersion()}` per stage (`ProgramPipelineObject.h:94-105`), i.e. exactly
the non-artefact fields the tracker is already allowed to read without joining, so the "must not force a
compile" constraint (`Tracker.h`) is preserved.
---
## 4. Minors
| # | where | what, and the refutation |
|---|---|---|
| **C-m1** | `ImageEmit.h:82-86`, `ProgramEmit.h:154`, `SamplerEmit.h:545-546` | All three key on `GetProgramForDraw()`. `Core.cpp:772-783` makes `GetProgramForDispatch()` a *different* object whenever a pipeline is bound (GL 4.6 §7.4 keeps compute exclusive). A compute-only pipeline gives `GetProgramForDraw() == null`, so `MaxImageUnit == -1`, the sticky window stays 0 and `set_shader_images` is **never emitted for the dispatch**; `EmitGlobalConstants` likewise never sends the compute program's default uniform block. *Refutation*: with a plain `glUseProgram` both getters return the same object, which is what every `ImageEmitTest` case does (`MakeComputeProgram` + `GL::UseProgram`), so the suite cannot see it. Narrow reach, but it is a hole with a name. |
| **C-m2** | `SamplerEmit.h:602-614` + `:192-213` | **No version-first skip in front of the CSO acquire.** Per firing of bit 13, per bound unit: `memset(100)` + sixteen assignments + `XXH64` over 100 bytes + a **linear** scan of up to 256 entries. D-F1 says *"One copy per mint attempt, never per draw, because the version-first skip runs first"*, and the file repeats it at `:95-96` — but `EmitSamplerStates` reaches `Acquire` unconditionally and only *then* asks the suppressor. *Refutation*: bit 13 is not per-draw, so this is per-batch rather than per-draw; and the fix is cheap and local — latch, per unit, `(sampler lifetime id, ctx.GetSamplingResolutionGeneration())`, which is exactly the pair that decides whether a sampler's 100 bytes can have moved. Recorded under ID-19's budget. |
| **C-m3** | `SamplerEmit.h:197-211` | The collision branch `Evict(i); break;` (a) can evict an entry the **record currently being built already names** — the `static_assert` at `:167-170` claims only the LRU victim can never be in the current pass, and this is a second eviction path it does not cover; and (b) stops the probe on the first hash match, so a *second* entry with the same hash whose bytes really do match is never found and a duplicate is minted. *Refutation*: both need a genuine 64-bit XXH64 collision, so the probability is not engineering-relevant. The finding is that the comment at `:155-159` states a property the code has a path around, and that path has no test (`Collisions` is only ever asserted `== 0`). |
| **C-m4** | `CompositeResolver.h:124-132`, `:98-101` | `Forget()` has **no caller** anywhere in the tree, and `m_entries` is keyed on `pipeline.GetExternalIndex()` — a GL name `glGenProgramPipelines` recycles. A deleted-and-recreated pipeline name inherits its predecessor's entry. *Refutation*: harmless, because `SlotAllocator.cpp:190-195` erases the lifetime-id mapping on `Free`, so the stale `ReleaseEntry` resolves nothing; and the vector is keyed by name so it cannot grow past the highest name ever used. It is still a dead public method and a key that is documented as recyclable everywhere else in the design. |
| **C-m5** | `SamplerEmit.h:412-483` | `MGPipeProgramOpaqueUnits` is a **one-entry** memo shared by the sampler and image emitters. A frame that alternates two programs re-walks `GetMaxUniformLocation()` locations on every switch. *Refutation*: the shared instance is the right call (two memos could disagree, which is the stated reason), and a two-entry memo would fix it without giving that up. Perf note only. |
| **C-m6** | `ProgramEmit.h:225-232` | `MOBILEGL_ASSERT(moduleCount <= 6, …)` compiles out at INFO — which D-J3 says is *"all three gate builds and every shipped build"* — and the loop then silently drops modules 7+. D-J3's own rule is a counted refusal, not an assertion. *Refutation*: `generatedSpirv` cannot exceed six stages today, so it is a guard against a future stage, and the truncation is the safe direction. Still the exact idiom D-J3 exists to forbid. |
| **C-m7** | `SamplerEmitTest.cpp:425-446` | `ARedundantRebindOfTheSameSamplerEmitsNothing` has **no `EmitterScope`**, so its `ASSERT_EQ(StateSetCount, 1u)` and `EXPECT_EQ(Mints, 1u)` depend on the preceding case's destructor having cleared the emitter. *Refutation*: it also passes run alone (fresh process ⇒ zero counters), and the gates do not shuffle. It is exactly the suite-order dependence D1 was. One line. |
| **C-m8** | `SamplerEmitTest.cpp:284-294` | `AHashCollisionDoesNotAliasTwoSamplerStates` **cannot go red for its name.** Deleting the `memcmp` confirm at `SamplerEmit.h:199` leaves it green: the two states it builds differ by one float ULP, so their hashes differ and the confirm is never consulted. The case honestly says so in its comment. *Refutation*: a real collision cannot be manufactured without a test hook into the cache. The honest close is a `#if` test seam that lets a case force two entries onto one hash — or renaming the case to what it proves. As it stands the memcmp branch, the `Collisions` counter and the collision-eviction path are **entirely uncovered**. |
| **C-m9** | `CompositeResolverTest.cpp:282-321` | Both "FreesTheSlotExactlyOnce" cases call `MGPipeSlots().AllocateComposite()` and then `MGPipeEmitShaderCsoDestroyAndFree()` twice — **the resolver is not in the picture at all**. `Releases` is asserted only `== 0` (`:239`). So the pinned "released exactly once" property is pinned at the *allocator*, and the resolver's own release path — the one C-M1 breaks — has no case. |
| **C-m10** | report §5 | ID-8 requires *"a leak test per new kind, run on the DirectVulkan lane too"*. §5's transcript has three `integration-gpu` arms and one `integration-verify` arm and **no DirectVulkan arm**. Contract-v2 §4.3 assigns the leak cases to package F, so this may be discharged elsewhere — the integrator must confirm F's G8b cases run on the DV lane rather than assume it. |
**Nits.** (n1) `SamplerEmit.h:310` `m_entries[index] = m_entries.back();` is a copy-**assignment**, which
does not carry padding; the cache's "the bytes stored are the bytes compared" invariant survives only
because every entry's padding was zeroed once by the `memcpy` at `:284` and `Vector` growth memmoves a
trivially-copyable type. True, but it deserves the same sentence `:271-278` gives the other half.
(n2) `MG_Test/SanityTest.cpp:3898` constructs `MakeShared<ProgramObject>(0u)`, which C's D5 discriminator
would classify as a pipeline composite; harmless (it never reaches the emitter) but it is a second
producer of external index 0 and the D5 argument says there is one. It is D's file — tell D.
---
## 5. The deviations, judged
| # | verdict |
|---|---|
| **D1** out-parameter canonicaliser + `memcpy` | **Correct and necessary.** `SamplerEmit.h:103-128` / `:284`. The reasoning is right (memberwise copy of a trivially copyable type leaves padding unspecified) and the bug it describes is real. `PaddingCannotChangeTheHash` pins the *canonicaliser* half convincingly; the *storage* half is weaker than it looks (see n1), but the code is right. Accept. |
| **D2** the wired constants are not the emission gate | **Closed by c0b** (`contract-v2.md` §4.1). C's finding was correct at the time. **The consequence is a rework item**: the header comments that assert the opposite are now false — see §6.7. |
| **D3** death helpers hardcode `published = false` | **Closed by c0b** (§2/M1, D17). The latch is A's, not the emitter's, and C's own `RecordIsPublished`/`NoteRecordDestroyed` are no longer what the death path asks. Rework item §6.5. |
| **D4** `TwoPipelinesWithTheSameSignatureKeepTheirOwnComposite` | **Accept, and the argument is right.** Verified: the composite is minted off its **own** lifetime id (`ProgramEmit.h:326-338`), `SlotAllocator.cpp:190-195` keys the map on that id, and `ProgramPipelineObject.h:161-163` gives each pipeline its own `m_drawProgram`. Sharing one handle would put one id in the map for two objects. The brief's name was wrong; the case is right and says so. |
| **D5** no `Core.{h,cpp}` hook; composite = `GetExternalIndex() == 0` | **Accept.** Verified there are exactly two production constructors of `ProgramObject(0u)` (`Core.cpp:661`, and `ProgramState.cpp:16` which passes a real GL name that is never 0). A `Bool` member would resize the pull object and break G1 outright. See n2 for the test-file third producer. |
| **D6** `ProgramObject.h` gains `GetSpirvReflection()` inside `#if MOBILEGL_PIPE_PUSH` | **Accept.** Needed (`MGPipeApplyCreateShaderState` takes the whole struct; wire makes a null `spirv` Fatal), minimal, and invisible to a pull build — G1's 0 resized confirms. |
| **D7** the image window is program-derived | **Accept with C-m1.** The reasoning against touching `TextureState` is right (B's file + a pull-build resize). The sticky union is the right hedge. The residue is the dispatch case. |
| **D8** the unit→target inversion is memoised per program | **Accept, and it is the right call.** O(units × locations) per verb was the alternative. First-writer-wins matches DirectGLES read forwards. One shared instance is right (C-m5 is about its size, not its sharing). |
| **D9** `static_assert(capacity > kMGPipeMaxTextureUnits)` | **Accept as far as it goes** — see C-M3 for what it does not cover, and C-m3 for the second eviction path it does not cover either. |
| **D10** nothing in `Reset()` touches an object record | **Correct for the sampler, image and program emitters** (verified against D-J4 and `PipeFill.cpp:1898-1911`). **Not correct for the composite resolver**, whose `Reset()` clears a release obligation rather than a memo — C-M1. |
| **D11** LFS pointers | **Verified restored.** Fixtures are real; 0 files under 1 KB. |
| **D12** `p4a-trees2.log` | Accepted as reported; nothing checkable now. |
| **D13** six extra test names | Accept (additions only; G14 is about removals). Re-counted: 25 C names + 13 contract = 38, matches. |
| **D14** cases assert on counters because the GL call already emitted | **Accept, and the suppression it describes is correct**, not a dropped emission: `EmitShaderImages` rebuilds the whole window from live context state and hands it to the suppressor, so a second call with unchanged content *should* send nothing — the record the applier holds is already that content. The only way it could drop a needed emission is if the first emission ran with a **smaller** window, and the window is monotone (`ImageEmit.h:86`), so a later call with a larger one produces a different hash and does emit. Correct. |
| **D15** the sentinel is pinned as a predicate | **Accept.** Driving `GetUBOContentVersion()` to `~0u` needs 2³² bumps. The live-path half is a conditional `if (… > 0u)` (`ProgramEmitTest.cpp:207`), which is weak, but `kVs` declares `uniform vec4 u_value` so the branch is taken. |
---
## 6. The c0b reconciliation list — exactly what the rebase onto `refs/heads/feat/disaggregated` must change
Contract-v2 §3.4 is a **compile-time** contract: the moment `kMGPipeWiredSamplerSubsystem` and
`kMGPipeWiredProgramSubsystem` are non-zero, `PipeFill.cpp`'s `if constexpr` seam instantiates and a
missing or misspelled entry point is a build error **in C's own commit**. C's branch predates the
declarations, so on rebase the build breaks until all three exist.
1. **`MGPipeSamplerEmitter::EmitSamplerCso(MG_State::GLState::SamplerObject&)` — does not exist.**
Add it. Its body is the family's handle rule, which for this kind is content addressing:
`MGPipeSamplerCsoCacheInstance().Acquire(sampler.GetAllSamplerParameters(), bytes)`. Called from
`MGPipeEmitSamplerCsoCreate` (`PipeFill.cpp:1058-1114`), i.e. from `SamplerObject`'s constructor —
note that minting a CSO at *construction* time content-addresses the **default** parameters and will
be superseded the moment the application sets one; that is correct (the cache dedupes) but C should
say so in the body, because it means one `create_sampler_state` per distinct default-valued sampler
and not one per object.
2. **`MGPipeSamplerEmitter::EmitSamplerView(MG_State::GLState::ITextureObject&)` — does not exist.**
Add it as a wrapper over `AcquireSamplerView` (`SamplerEmit.h:647`), resolving the texture handle the
way `EmitSamplerViews` already does at `:572`
(`MGPipeSlots().Acquire(MGPipeKind::Texture, texture.GetLifetimeId())`) and discarding the byte count.
3. **`MGPipeProgramEmitter::EmitShaderCso(MG_State::GLState::ProgramObject&)` — does not exist.**
Add it as a wrapper over `AcquireShaderCso` (`ProgramEmit.h:195`).
4. **The publication latch (contract-v2 §3.1) is called from nowhere.** Add, and nothing else:
* `MGPipeNoteHandlePublished(MGPipeKind::SamplerCso, cso)` after `SamplerEmit.h:288`;
* `MGPipeNoteHandleUnpublished(MGPipeKind::SamplerCso, …)` in `Evict` (`SamplerEmit.h:299-313`) **and**
in `ResetForTest` (`:231-235`) — the latter frees slots without a delete, so a stale latch would
make a future death helper emit a delete for a record that never existed;
* `MGPipeNoteHandlePublished(MGPipeKind::SamplerViewCso, handle)` after `SamplerEmit.h:681`;
* `MGPipeNoteHandlePublished(MGPipeKind::ShaderCso, handle)` after `ProgramEmit.h:237`.
5. **`RecordIsPublished` / `NoteRecordDestroyed` stop being the death path's authority** (D17). Keep them
— the view latch and the program latch are what the version-first skip needs — but rewrite their
comments (`SamplerEmit.h:215-218`, `:693-697`; `ProgramEmit.h:247-254`), which currently say the death
path asks them. `MGPipeProgramEmitter::NoteRecordDestroyed`'s bound-mirror clearing
(`ProgramEmit.h:271-277`) then has **no caller**: either state why the mirrors self-heal (the slot's
`Gen` moves on reuse, so the next `EmitShaderState` sees a different handle and re-binds) or delete
the three lines. Do not leave it as unreachable code with a live-looking comment.
6. **The sampler CSO has no lifetime-id mapping, and D must be told.** With C's design (right, per
contract-v2 §3.4's open box) `MGPipeEmitSamplerCsoDestroyAndFree(m_lifetimeId)` resolves nothing, so
`NotifyStateObjectDestroyed(SamplerCso, lifetimeId)` reaches D with **no handle behind it**. D must not
key a sampler twin on a `SamplerObject` lifetime id; the twin's life is `create_sampler_state` →
`delete_sampler_state` (LRU) and nothing else. Put that sentence in `SamplerEmit.h` and in the report.
7. **Two header comments are now false and must be rewritten**: `SamplerEmit.h:66-71` and
`ProgramEmit.h:50-54` both say *"It is NOT the emission gate"*. After c0b, `wants()` consults
`kMGPipeWiredSubsystems` (`contract-v2.md` §4.1) and the constants **are** the switch, in both the
validate point and the client paths. A comment that says the opposite is worse than no comment.
8. **No change expected, but verify**: `CompositeResolverTest.TheCompositeBandHasExactlyOneDoor` reads
`LiveCount(MGPipeKind::ShaderCso)` across a composite free; c0b deliberately kept `LiveCount` and
`FreeCount` summing both spaces so that case stays green (contract-v2 §4.3). It should still pass
unchanged.
---
## 7. ID-14 — the built-in sampler seam, answered
**The exact call B must make**, replacing `TextureEmit.h`'s
`MGPipeSlots().Acquire(MGPipeKind::SamplerCso, sampler->GetLifetimeId())` inside `EmitTextureParams`
(clientfb tree, `MG_Impl/Pipe/TextureEmit.h`, the block that starts *"THE BUILT-IN SAMPLER'S CSO SLOT IS
KEYED ON THE SamplerObject's OWN LIFETIME ID"*):
```cpp
Uint64 samplerBytes = 0;
const MGPipeHandle builtinSampler =
MGPipeSamplerCsoCacheInstance().Acquire(sampler->GetAllSamplerParameters(), samplerBytes);
```
Both names are in `MobileGL::MG_Pipe`, so no qualification is needed inside `TextureEmit.h`;
`ITextureObject::GetSamplerObject()` returns `const SharedPtr<SamplerObject>&`
(`TextureObject.h:34`) and `SamplerObject::GetAllSamplerParameters()` returns
`const SamplerParameters&` (`SamplerObject.h:64`). `Acquire` takes a **non-const `Uint64&`**, so B needs
a real lvalue; B should fold `samplerBytes` into whatever it returns as payload bytes rather than
discarding it, or the `csob-blob` accounting under-reports by 100 bytes per mint. B must **delete** its
own `MGPipeSlots().Acquire(SamplerCso, …)` line: leaving it would mint a second, record-less slot that
`~SamplerObject` then frees.
**Include-closure check — usable, no cycle.** `TextureEmit.h` must add
`#include <MG_Impl/Pipe/SamplerEmit.h>`. `SamplerEmit.h`'s own closure is `SetHashSuppressor.h`,
`SlotAllocator.h`, `Tracker.h`, `MGPipe.h`, `MGPipeHostSpan.h`, `PipeApply.h`, `Core.h`,
`ProgramObject.h`, `SamplerObject.h`, `TextureObject.h`, `TextureUnit.h`, `PipeStats.h`, `xxhash.h`.
The only files in the tree that include `TextureEmit.h` are `PipeFill.cpp:34` and
`TextureEmitTest.cpp:54` (grepped), so nothing in that closure reaches back. `ImageEmit.h:36` already
includes `SamplerEmit.h`, so the shape is precedented.
**Re-run `check_include_closure.py --mode both --compiler clang++ --self-test --require-all
--expect-probes 4` after the edit** (ID-14 says so, and c0b's `--expect-probes` is new).
**When the sampler object's parameters later change — who re-emits `set_texture_params`?**
For the texture's *own* built-in sampler: `glTexParameter*` writes through `TextureObject.cpp:53`, which
bumps both `GetTextureParamsVersion()` and `BumpSamplingResolutionGeneration()`; a `glSamplerParameter*`
on a `SamplerObject` goes through `SamplerObject.cpp:65`. Bit 13 fires, and **B's `EmitTextureParams` is
the only re-emitter** — it re-`Acquire`s, the content has moved, the cache returns a **different**
handle, and the new handle goes into the record. So the content-addressed handle changing with content
is self-healing *provided B's own params gate is keyed on `GetTextureParamsVersion()` and not on
something a sampler-parameter write leaves alone*: **the reviewer of B must check that**, because C's
side gives no signal.
**What is not covered, and is the real risk:** eviction — **C-M3**. A parameter change moves the handle
and B re-emits; an LRU eviction moves the handle's validity and nobody re-emits. ID-14's ruling
("B re-emits whenever the built-in sampler's parameters change") is necessary and not sufficient.
Hazard **H1** (wire): unchanged and consistent — with B taking the handle from C's cache the
`BuiltinSampler` is never null in a build where both families are wired, and the `0x9ff` arm (bit 10
without bit 11) stays a **contract dependency refusal**, package F's scenario.
---
## 8. Exit order, hygiene, ownership
* **Exit order (ID-8): clean.** All six new process singletons are `static T* p = new T();` and are never
destroyed — `MGPipeSamplerCsoCacheInstance` (`SamplerEmit.h:320-326`),
`MGPipeProgramOpaqueUnitsShared` (`:480-483`), `MGPipeSamplerEmitterInstance` (`:765-772`),
`MGPipeImageEmitterInstance` (`ImageEmit.h:167-172`), `MGPipeProgramEmitterInstance`
(`ProgramEmit.h:396-403`), `MGPipeCompositeResolverInstance` (`CompositeResolver.h:186-192`).
**No frontend `SharedPtr` is stored by any of them**, checked member by member: the cache's `Entry`
holds `SamplerParameters` by value (a POD of enums/floats/vec4s); the resolver's `Entry` holds
`Array<Uint64, N>` (`ProgramPipelineObject.h:94`), a `Uint`, a handle and a `Uint64`; the three
emitters hold `Array`s of wire PODs and `Vector`s of trivial latches. Confirmed against the task's
specific question: **the cache's entries do not hold `SharedPtr<SamplerObject>`.**
* **Hygiene: clean.** No `MGLOG_I`/`MGLOG_W`/`MGLOG_E`, no `TODO`/`FIXME`, no `printf`/`std::cout` and no
`pGLContext` anywhere in the four headers (grepped). `pGLContext` appears only in the test files, which
is where it belongs. G13's purity greps are unaffected (these are `MG_Impl`, the client side).
* **Ownership: clean.** The 11 changed files are all C's by C.7 — the four `MG_Impl/Pipe` headers,
`MG_State/GLState/{SamplerState,ProgramState}/**`, and the four `MG_Test/Pipe/*Test.cpp`. Nothing under
`MG_Backend/`, `scripts/`, `MG_Pipe/`, `.github/`, or A's `MG_Impl/Pipe` files. The C.7 grants
(`GL_Program.cpp`, `Core.{h,cpp}`) are genuinely unused — D5's argument for not needing the `Core.cpp`
hook holds up.
* **Shared logs / `RESOURCE_LOCK`: not needed.** Each of the four test `main()`s points
`MOBILEGL_LOG_FILE_PATH` at a **pid-unique** file and removes it (e.g. `SamplerEmitTest.cpp:452-456`),
so `-j 8` cannot make two suites share one log.
* **`EmittedCallSuppliesTheWholeField` (report §4): all six `false` verdicts confirmed.** The three that
matter were re-derived independently: `GetProgramForDraw`/`GetProgramForDispatch` are pointer-valued
and the emitted call carries a `{slot, gen}` (and `DirtySurface.def:309-319` depends on them staying
pulled — see C-M5); `GetTextureUnitObject` hands back a live `TextureUnit&` with one slot per target
while `set_sampler_views` carries the resolved single view, which is strictly less;
`GetMaxTouchedTextureUnit` is the `Count` argument and the suppressor is what swallows the redundant
re-bind. No row moves, so `PipeFill.cpp` needs no edit — correct.
---
## 9. The rework list, in order
1. **C-M1** — `CompositeResolver.h`: stop `Reset()` disarming the release path (restore `Live` in the
reuse branch, or split freshness from the release obligation). Add the case C-m9 says is missing: a
signature move must produce `Releases == 1` and must still do so **after** a `Reset()`.
2. **C-M2** — `ProgramEmit.h`: invalidate the global-constants latch whenever `AcquireShaderCso` actually
re-issues a create (wire's W6). Add a case: emit constants, force a link-version move, emit again,
assert the constants went out a second time.
3. **C-M3** — close the eviction/`BuiltinSampler` hazard. Preferred shape: a monotone "sampler-CSO epoch"
the cache bumps in `Evict`, which B's texture-params latch mixes in, so an eviction re-emits
`set_texture_params` through D-E2's existing `SamplerResync`. Whatever shape is picked, it needs a
case that evicts a handle a texture-params record names and proves the record is refreshed.
4. **The c0b reconciliation, §6 items 1–8** — three entry points, four latch calls, two false comments,
one sentence for D.
5. **§7** — hand B the exact call and the include; B deletes its own `SamplerCso` mint. Re-run the
include-closure gate with `--expect-probes 4`.
6. **Minors worth taking in the same round because they are one line each**: C-m6 (counted refusal
instead of a compiled-out assert), C-m7 (`EmitterScope` on the redundant-rebind case), C-m4 (delete
`Forget` or call it), n1 (one sentence on `Evict`'s copy-assign).
7. **Minors to declare and defer**: C-m2 (the per-unit acquire latch — real ID-19 budget item, record it
in `MEASUREMENTS.md` rather than leaving it silent), C-m5, C-m8 (either a test seam for the collision
branch or an honest rename), C-m1 (the dispatch-through-a-pipeline window).
8. **Not C's, hand to the integrator**: **C-M4** and **C-M5** are `Tracker.h` / `PipeFill.cpp`, which A
owns for the whole phase. Both are one-line fixes and both are under-fires, which `Tracker.h`'s own
text calls the fatal direction. They should land as a `c0d` on `p4a/contract` before `esprytdraw` is
verified, not after.
---
## 10. What the integrator must re-run on the integrated tree
1. **Before anything else** — `MGPTextureParams::BuiltinSampler` is non-null **and resolvable** on every
`set_texture_params`: `grep -c 'Fatal{' ` on an `integration-verify` run must stay 0, and B's texture
cases must show the handle coming from `MGPipeSamplerCsoCacheInstance()`. This is §7 and it is the
single highest-risk seam in the phase.
2. `ctest --test-dir build-push -R 'SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.'` — on
C's branch **no case ever reached a real applier**; with `wire` underneath, the `Start + Count`
Fatal, the `Parameters.Size` Fatal, the `link/spirv` non-null Fatal, the band's table split and the
verify build's program-archive round trip all come alive for the first time.
3. The whole of C's §5 transcript, in order: three builds, G1 (0/0/0/0 — P4a's admitted set is EMPTY),
`gen_pipe.py --check`/`--self-test`, the generated-file diff, `gen_pipe_dirty_surface.py`,
`check_include_closure.py --mode both --compiler clang++ --self-test --require-all --expect-probes 4`
(the new flag), `p3a_untouched_regions.sh 37da3c3a HEAD`, `ctest -L unit` ×3, the pull/push ctest-name
parity pair and the no-name-removed check, the three `integration-gpu` arms
(default / `0` / `0x1ff`), `integration-verify` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`
with `grep -c 'Fatal{'` = 0, and the retrace gate.
4. **A DirectVulkan arm for the death/leak cases** (ID-8) — confirm F's G8b cases really run there, or
say explicitly that they do not (C-m10).
5. **After `esprytobj` + `esprytdraw`**: `MOBILEGL_PIPE_PUSH=0x9ff` (samplers set, texture resources
clear) must be **refused at the contract dependency rule** and logged, never half-run — C emits
`MGPBoundView::Texture` and `MGPImageView::Res` as `Texture` handles unconditionally
(`SamplerEmit.h:572`, `ImageEmit.h:97-99`).
6. **A pipeline (SSO) scenario and a `glBindSampler` scenario on the integrated tree** — C-M4 and C-M5
are invisible to every unit suite in the phase, by construction, because the unit cases drive the
emitters directly. `ProgramPipelineScenario`'s sixteen cases and any scenario that rebinds a *different*
sampler object to a unit are the only things that can see them.
7. `retrace_gate.py`, **after** confirming `tools/trace_replay/fixtures` are not LFS pointers (D11) — the
false red is `passed 2 / 79` with `ssim=None`.
@@ -0,0 +1,491 @@
# P4a package C — `clientsp`. Focused re-review of the rework, v2
Target: `refs/heads/p4a/clientsp` = **`00a86d2a`** — the three rework commits `02475fbb` / `5f577d16` /
`00a86d2a` on top of the four v1 commits replayed onto `17db7598` (c0 + c0b + c0c).
Sources cross-read: `clientsp-review-v1.md`, `clientsp-v2.md`, `INTEGRATOR-DECISIONS.md`
(ID-14 / ID-17 / ID-18 / ID-22 / ID-25 / ID-26), `contract-v2.md` §3, `contract-v4.md` (c0d).
**Work done:** every file opened at HEAD, the three rework diffs read hunk by hunk, and — unlike v1 —
a **private worktree was built and run**: `/home/swung/w7/p4a-rereview-clientsp` at `00a86d2a`,
`build-push` (`MOBILEGL_PIPE_PUSH=ON`, integration tests off), `-j 8`, `CCACHE_BASEDIR=/home/swung/w7`.
The tree **builds rc 0** and `CompositeResolverTest` / `SamplerEmitTest` / `ProgramEmitTest` link and
pass, which independently confirms the report's §6 build rows for these three targets. The worktree
has been removed. **Not done:** C's full gate set (G1, the three ctest lanes, integration-gpu,
integration-verify, retrace) — the base moves at integration anyway and §5 below says what to re-run.
---
## Verdict — **REWORK (one item)**
Every v1 item is closed, and the two hardest ones are closed *well*: C-M2 is exactly the ruled
one-line invalidation with an honest case and two written-down corrections to the review's own
scenario, and C-M3 is ID-17 implemented as ruled — `Acquire` takes a reference, `Release` drops one,
the LRU skips pinned entries, over-capacity minting is counted, and the emitter's own bound set holds
its pins. The c0b reconciliation is complete and the ten minors are each taken or defensibly declared,
including one (**C-m7**) that is correctly **refuted**: the `EmitterScope` the v1 review said was
missing was already there in v1, and the diff proves it (the line is unchanged context at
`SamplerEmitTest.cpp:456`). The B-facing API in §3 of the report matches the code name for name,
line for line.
The rework nevertheless **over-corrects C-M1** and introduces a defect the v1 tree did not have:
* **C2-M1** — with `Live` no longer cleared by `Reset()`, the first `Observe` from **another context**
on a pipeline that happens to carry the same GL name releases the *first* context's **live**
composite: `delete_shader_state` goes out on the wire, the publication latch is cleared and the slot
is freed, while the frontend `ProgramObject` is still alive. **Demonstrated red on `00a86d2a`**, and
**green again** when v1's `Reset()` is restored — so it is this round's, not v1's.
The fix is small and local to `CompositeResolver.h` (§2 names it). If the integrator would rather not
spend a third round on C, it is an integrator-side edit in C's tree plus one case; but it cannot be
*declared*, because the file's own header (`CompositeResolver.h:130-142`) states the opposite property
as the reason `Reset()` does not release, and that sentence is now false.
---
## 1. What v1 asked for, and whether it happened
| v1 item | ruling | closed? | evidence |
|---|---|---|---|
| **C-M1** `Reset()` disarms the release path | fix + a case that drives release **through** the resolver after a `Reset` | **YES, but over-corrected — see C2-M1** | `Live` (`CompositeResolver.h:181`) is now the release obligation, cleared only by `ReleaseEntry` (`:195`); `Fresh` (`:183`) is the memo, cleared only by `Reset()` (`:143-145`); the reuse branch re-arms `Fresh` and leaves `Live` (`:105-113`). Case `ASignatureMoveAfterAMakeCurrentStillReleasesThroughTheResolver` (`CompositeResolverTest.cpp:346`). **I ran the stated negative control**: restoring `entry.Live = false` in `Reset()` turns it red on `Releases == 1`. The case does go red on the old code. |
| **C-M2** the `(Cso, Version)` latch survives a re-issue | invalidate on **every** re-issue | **YES** | `ProgramEmit.h:268-271`, on the branch that actually emitted, after `MGPipeApplyCreateShaderState`. Every re-issue reaches it (the early-out at `:209-211` is the only skip and it returns before the emit). `EmitGlobalConstants` acquires at `:172` **before** it consults the latch at `:176`, so an invalidation in the same call is seen. Accessors `:378-379`. Case `ProgramEmitTest.cpp:318`; deleting the four lines makes it red on `EXPECT_TRUE(MGPipeHandleIsNull(GlobalConstantsCso()))`. |
| **the failed-relink case** | — | **correctly re-derived, and the report is right** | `ProgramObject::Link()`'s prologue assigns `m_spirv = {}` (`ProgramObject.cpp:532`) and `GetUBOSize()` reads `Spirv().globalUboScratch.size()` (`ProgramObject.h:736`), so after a *failed* relink the size is 0 and `EmitGlobalConstants` early-outs at `:169`. v1's "the client's scratch still holds the live values" is true of GL and false of this frontend. **This is frontend behaviour, not a push/pull divergence** — the pull path reads the same two getters — so it is not C's to fix, and the fix is still required for the general re-issue. Report §1's correction 1 is also right: `BumpLinkObservableVersions` calls `MarkUBOContentDirty()` beside `++m_linkVersion` (`ProgramObject.cpp:357-358`), so the *behavioural* half is not the discriminator and the case says so. |
| **C-M3 / ID-17** reference counts | cache keeps a per-entry ref count; `Acquire` takes, `Release` drops, LRU evicts only unreferenced, over-capacity minting counted; B's Acquire/Release spelled for B | **YES, per ruling** | see §3 |
| **the c0b list, items 1–8** | three entry points, four latch calls, two comments, one sentence for D, one verify | **YES, all eight** | see §4 |
| **the ten minors + two nits** | fix or declare with a reason | **YES** | see §6 |
---
## 2. C2-M1 [MAJOR, introduced by this round] the resolver now emits `delete_shader_state` for another context's **live** composite
`MG_Impl/Pipe/CompositeResolver.h:102-115` (`Find` + the mismatch arm), `:143-145` (`Reset`),
`:186-191` (`Find`, keyed on the GL name alone), `:193-200` (`ReleaseEntry`), against its own
`:130-142` and `:164-175`.
```cpp
Entry* entry = Find(key); // key = pipeline.GetExternalIndex(), :101-102
if (entry != nullptr) {
if (entry->Signature == signature && entry->Handle == handle) { … return handle; }
ReleaseEntry(*entry); // :115 <-- now really runs after a Reset()
}
…
void Reset() { for (Entry& entry : m_entries) entry.Fresh = false; } // :143-145, Live untouched
```
**Failure scenario.** `GLContext` owns `m_programPipelines` **and its own name generator**
`m_programPipelineNames` (`MG_State/GLState/Core.h:658-659`), so pipeline GL name *N* can be live in
two contexts at once, naming two different objects. `MGPipeCompositeResolverInstance()` is a
**process** singleton and `Find` keys on nothing but that name. So:
1. Context A binds its pipeline *N*; `EmitShaderState` mints composite A's handle H<sub>A</sub>,
publishes `create_shader_state`, and `Observe` records `{name N, sig A, H_A, Live}`.
2. A make-current to context B: `PipeFill.cpp:2227-2229` runs
`MGPipeProgramEmitterInstance().Reset()` → the resolver's `Reset()`, which now clears **only**
`Fresh`.
3. Context B binds *its* pipeline *N* and draws. `Observe` finds the entry, the signature and the
handle both mismatch (two contexts hold two different composite `ProgramObject`s, so the handles
differ **even when the stage programs are share-group-shared and the signature is identical**),
and falls into `ReleaseEntry` — which, unlike in v1, is armed. It calls
`MGPipeEmitShaderCsoDestroyAndFree(A's composite lifetime id)`. Composite A is **alive**, so that
id still resolves: `EmitDeleteIfPublished` emits `delete_shader_state`, clears the publication
latch, `NotifyStateObjectDestroyed` fires and the slot goes back to the free list.
This is precisely what `:130-142` says must not happen (*"releasing them would emit a delete for a
live program"*) and what `:164-175`'s benign-recycling argument assumes cannot happen (*"that release
resolves NOTHING — the allocator erases the lifetime-id mapping on Free"* — true when the predecessor
is **dead**, false here).
**Demonstrated, not argued.** A scratch probe in the private worktree drove the resolver exactly as
`EmitShaderState` does — two `ProgramPipelineObject`s built with the same external index, two
composites, `Observe` / `Reset` / `Observe` — on the landed head:
```
CompositeResolver.ScratchProbe_CrossContextPipelineNameAliasing
Releases : 1 (expected 0)
MGPipeSlots().IsLive(ShaderCso, hA) : false (expected true)
MGPipeHandleIsPublished(ShaderCso, hA) : false (expected true)
-> delete_shader_state went out for a LIVE composite
[ FAILED ]
```
and with **v1's `Reset()` restored** (`entry.Live = false` put back), the probe is **green** and C's
own new case is the one that goes red. The two cases are in direct tension: with a single
`Live`/`Fresh` pair the resolver cannot tell *"my own entry after a make-current"* from *"another
context's entry"*, and exactly one of the two properties can hold at a time. That is the defect,
stated as sharply as it can be.
**Refutations attempted, and how far each gets.**
(a) *The reuse branch saves it — same signature, same handle.* No: the handle is minted off the
composite object's own lifetime id (`ProgramEmit.h:398-412`), and two contexts have two composite
objects, so `entry->Handle == handle` is false even when the signature matches exactly.
(b) *The old composite is dead by then.* No — that is the single-context case, where the pipeline's
one-slot cache drops the last `SharedPtr` before `Observe` runs. Across a make-current context A's
pipeline **and** its cached composite are alive; that is the stated reason `Reset()` does not release.
(c) *`MGPipeApplierReset` covers it.* It clears `DrawProgram` / `DispatchProgram` / `BoundShaderCso`
(`PipeApply.cpp`, the P4a working-state block) but deliberately **not** the object records — so the
record the delete destroys is exactly the one that was supposed to survive the switch.
(d) *MobileGL is single-context.* `MGPipeApplierReset`'s own comment describes *"a make-current BACK
to a context that is still alive"*, `FreshlyPrimed` exists for it, and v1's C-M1 scenario needs it too.
(e) *Unreachable anyway.* The opposite: **c0d makes it reachable.** Before c0d, bits 6/7/8 read
`GetCurrentProgram()`, null under SSO, so `EmitShaderState` — and therefore `Observe` — essentially
never ran for a bound pipeline (that was C-M5). c0d's `else if (pipeline)` arm
(`contract-v4.md` §2.2, §6 item 2) puts the composite resolver on the hot path *for the first time*.
This finding lands the moment C is rebased onto `e8502a61`.
(f) *It self-heals, so it is cosmetic.* It does self-heal — context A's next `EmitShaderState` misses
`FindByLifetimeId`, allocates a fresh band slot and re-issues `create_shader_state`, so pixels stay
right. What it costs is a **death notice and a backend twin destruction for a live frontend object**
(the D-I1 / P3a C-1 shape), a composite program **rebuild on the server per context switch** — which
for Espryt is the glslang + SPIR-V + spirv-opt rebuild `CompositeResolver.h:42-45` says the whole
signature design exists to avoid — and a window in which A's `ProgramObject` is alive with its band
slot already re-handed out at `gen + 1`. It is not cosmetic.
**Fix.** Give `Entry` a context key beside `PipelineName` and make `Find` require both — the
`GLContext*` the emission is running under, or a per-context serial. Then an entry from another
context is simply *not this pipeline's entry*: it is not found, not matched and not released, its
obligation stays owed to its own context, and both C's new case and this probe are green together.
`Observe` already has everything it needs at the call site (`ProgramEmit.h:116-120` is inside
`EmitShaderState(GLContext& ctx)`); the signature gains one argument. Add a case that pins it: two
pipeline objects with one external index, a `Reset()` between them, `Releases == 0` and the first
composite's slot still live.
**Do not fix it by re-clearing `Live` in `Reset()`** — that is v1's C-M1 back, as run 2 of the control
proves.
---
## 3. C-M3 / ID-17 — the reference count, checked against the ruling
Every clause of ID-17 is implemented and correct.
| ID-17 clause | where | verdict |
|---|---|---|
| the cache keeps a reference count per entry | `SamplerEmit.h:331` | ✔ |
| `Acquire` takes a ref (hit **and** mint) | `:354` / `:410` | ✔ — the mint counting as an acquire is right, and the comment says why |
| `Release` drops one | `:267-275` | ✔ (see C2-m2 for the one thing it should also do) |
| LRU evicts only unreferenced entries | `:361-374` | ✔ — the victim search starts at `m_entries.size()` as "none found" and skips `RefCount != 0`, so a fully pinned cache falls through correctly rather than picking index 0 |
| every entry pinned ⇒ mint beyond 256 and count it | `:376-381`, `Counters::OverCapacityMints` `:223` | ✔ |
| bound sampler states hold a ref while bound, released on unbind | `EmitSamplerStates` `:771-782`, `m_stateRefs` `:996` | ✔ — I walked the reconciliation for all five cases (same handle, moved handle, unit leaving the window, two units sharing one CSO, a unit with no sampler) and it is exactly one reference per binding in every one; `Release(null)` is a no-op so the out-of-window units are free |
| released at a make-current | `Reset()` `:952-959` | ✔ — and it is right that it goes there: `MGPipeApplierReset` clears `BoundSamplerStates` immediately before (`PipeFill.cpp:2224` then `:2227`), so no standing set names those CSOs afterwards |
| B's Acquire/Release spelled for B | report §3 | ✔ — matches the code exactly: `MGPipeSamplerCsoCacheInstance()` `:469`, `Acquire` `:244`, `Release` `:267`, `RefCountOf` `:279`, `RecordIsPublished` `:294`; `Acquire` really does take a **non-const `Uint64&`**, so B needs a real lvalue; both names are in `MobileGL::MG_Pipe`; the include is `<MG_Impl/Pipe/SamplerEmit.h>` and `ImageEmit.h:36` already precedents it |
**The ABA hazard is closed.** A handle a standing record names has `RefCount >= 1`; `Mint`'s victim
search cannot pick it; `Evict` is the only path that frees a `SamplerCso` slot
(`MGPipeEmitSamplerCsoDestroyAndFree` resolves nothing for a content-addressed CSO, confirmed at
`PipeFill.cpp:1265-1272` against `MGPipeSlots().Allocate(SamplerCso)` at `SamplerEmit.h:383`, which
takes no lifetime id). So a texture's params record can never name an evicted handle **provided B
owes exactly one Release per Acquire** — which is what report §3's four rules say, and which the
reviewer of B must check.
**The three cases are honest and the negative controls are real.**
`AReferencedCsoIsNeverTheLruVictim` (`SamplerEmitTest.cpp:526`) drives 512 distinct unreferenced
values through the 256-entry cache, asserts `Evictions > 0` (so the LRU really ran) and
`OverCapacityMints == 0`, and its bookkeeping is right — the two trailing `Release(pinned)` calls
balance the initial `Acquire` and the re-acquire that proves the hit.
`AFullyPinnedCacheMintsBeyondItsCapacityAndCountsIt` (`:559`) pins exactly the capacity and asserts
`Size() == 257 / Evictions == 0 / OverCapacityMints == 1`.
`ABoundSamplerStateHoldsItsCsoUntilTheUnitMoves` (`:494`) pins "one binding is one reference, not one
per pass", which is the clause that would otherwise leak pins for the life of the process.
`AHashCollisionDoesNotAliasTwoSamplerStates` (`:290`) now really can go red for its own name: the
forced-hash seam puts two different values on one hash and the case asserts the handles differ,
`Collisions == 1`, and — the part v1 said was unreachable — that the probe **keeps going**, so
re-asking for the first value is a `Hits == 1` and not a third mint.
---
## 4. The c0b reconciliation — all eight items, verified at the source
| # | claim | verified |
|---|---|---|
| 1 | `MGPipeSamplerEmitter::EmitSamplerCso(SamplerObject&)` | ✔ `SamplerEmit.h:888-892`; forwarded from `PipeFill.cpp:1097-1101`. Spelling exact. |
| 2 | `MGPipeSamplerEmitter::EmitSamplerView(ITextureObject&)` | ✔ `SamplerEmit.h:900-905`; `PipeFill.cpp:1103-1107`. Resolves the texture handle the same way `EmitSamplerViews` does (`:721` vs `:902-903`). |
| 3 | `MGPipeProgramEmitter::EmitShaderCso(ProgramObject&)` | ✔ `ProgramEmit.h:292-295`; `PipeFill.cpp:1109-1113`. |
| — | **compile-time contract really is armed** | ✔ Both wired constants are non-zero (`SamplerEmit.h:84`, `ProgramEmit.h:63`), so `ForwardWhenWired<kWired>` (`PipeFill.cpp:908`) instantiates all three forwards. My `build-push` **rc 0** is the proof; a misspelling would not have linked. |
| 4 | the four latch calls, and nothing else | ✔ `MGPipeNoteHandlePublished(SamplerCso)` `SamplerEmit.h:419` (immediately after `MGPipeApplyCreateSamplerState`), `NoteHandleUnpublished` in `Evict` `:450` **and** in `ResetForTest` `:313`, `NoteHandlePublished(SamplerViewCso)` `:855`, `NoteHandlePublished(ShaderCso)` `ProgramEmit.h:255`. Grepped: no fifth call site. Both headers now include `<MG_Pipe/PipeMutation.h>` directly (`SamplerEmit.h:47`, `ProgramEmit.h:44`). |
| 5 | `RecordIsPublished` / `NoteRecordDestroyed` comments rewritten; the bound-mirror clearing explained | ✔ `SamplerEmit.h:287-293`, `:907-916`, `:925-930`; `ProgramEmit.h:297-308`, `:318-327`. The "why it self-heals" the review asked for is at `ProgramEmit.h:322-327` and it is **correct**: `RecordGen == handle.Gen` refuses a stale latch and the three mirrors hold a generation that can never be handed out again. |
| 6 | the sentence for D | ✔ `SamplerEmit.h:201-205`, and repeated in report §3. It matches what `PipeFill.cpp:1265-1272` actually does. |
| 7 | the two false "it is NOT the emission gate" comments | ✔ rewritten at `SamplerEmit.h:67-83` and `ProgramEmit.h:55-62`, and they are now **accurate**: `wants()` really does consult `kMGPipeWiredSubsystems`, and `FamilyIsLive` (`PipeFill.cpp:885`) is the same pair one level in, as the birth-hook bodies at `:1097-1113` show. |
| 8 | `TheCompositeBandHasExactlyOneDoor` unchanged and green | ✔ unchanged in the diff; **I ran it** — green. |
**The three birth hooks having no call site is correctly declared, and the reasons hold.**
Grepped the whole tree: `MGPipeEmitSamplerCsoCreate` / `MGPipeEmitSamplerViewCreate` /
`MGPipeEmitShaderCsoCreate` are called from nothing outside `PipeFill.cpp` — and neither are
`MGPipeMintTextureHandle` / `MGPipeMintShaderCsoHandle`, which are B's and A's to wire. So **the
emitters are reachable only through the hooks and the validate point**, which is what §4 of the task
asked. D-H4 does put `create_shader_state` at the validate point; `TextureObject`'s constructor is B's
file; and the `SamplerObject` one-liner would make `DirectGLES.cpp:209-214`'s backend-side
`SamplerObject(0)` emit into the pipe from inside `MG_Backend`, which is a real objection. The offer
to add it on request is the right disposition.
---
## 5. The counted refusal in `5f577d16` — what is refused, and is it right
`ProgramEmit.h:233-240`:
```cpp
const SizeT moduleCount = spirv.generatedSpirv.size();
if (moduleCount > 6) ++m_moduleTruncations;
for (SizeT i = 0; i < moduleCount && i < 6; ++i) { … }
```
**What is refused:** the *tail* of a linked snapshot that carried more SPIR-V modules than
`MGPProgramDesc::Spirv[]` (six) can name. Nothing is refused today — `generatedSpirv` is indexed by
`GetLinkedShaderStages()` and `ShaderStage` has exactly six real stages — so this is a guard against a
seventh stage being added later.
**Is it right?** Yes, and it is the correct reading of D-J3. `MOBILEGL_ASSERT` is live only when
`MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG` (`Defines.h:104-115`), i.e. **off in all three
gate builds and every shipped build**, so the v1 code would have truncated silently in exactly the
builds that run. `TruncatedModuleCount()` (`:382`) is the visible artefact and `ResetCounters()`
zeroes it (`:369`). Truncation, not a drop of the whole descriptor, is the safe direction: `StageMask`
and `Spirv[]` come out of the same snapshot, so a truncated tail is a program the server refuses to
build rather than one it builds wrong.
One asymmetry the same round did **not** apply the same rule to: see C2-n1.
---
## 6. The ten minors and two nits — dispositions checked
| # | claimed | verified |
|---|---|---|
| **C-m1** dispatch-through-a-pipeline window | declared | ✔ defensible; the closure genuinely needs `Tracker.h`, and c0d §2.5 confirms only the tracker half is A's — the compute-pipeline half stays C's, correctly recorded |
| **C-m2** no version-first skip before the acquire | declared, ID-19 | ✔ declared — but the cost is **understated**, see C2-m3 |
| **C-m3** the collision branch's second eviction path | **taken** | ✔ `SamplerEmit.h:341-352`: counts and `continue`s. Both halves close, and the case now covers the branch |
| **C-m4** dead `Forget()`, recyclable key | **taken** | ✔ `Forget()` is gone; the key reason is at `:164-175`. But see C2-m1: `HandleFor()` was left behind |
| **C-m5** one-entry opaque-units memo | declared | ✔ perf only |
| **C-m6** compiled-out assert on the module count | **taken** | ✔ see §5 |
| **C-m7** missing `EmitterScope` | **refuted** | ✔ **the refutation is correct.** The `EmitterScope scope;` line is unchanged *context* in the rework diff at `SamplerEmitTest.cpp:456`, so it was present in v1; the v1 review was wrong. The case also now clears unit 2 on the way out, which matters because `EmitterScope::Clear()` resets the emitter *before* the cache, so a leaked binding could not have leaked a pin either way |
| **C-m8** the collision case cannot go red for its name | **taken** | ✔ `AcquireWithForcedHashForTest` `:256-262` + `SamplerEmitTest.cpp:290-327`. See C2-n3 for the one reservation |
| **C-m9** no case drives the resolver's own release | **taken** | ✔ and its negative control is real (I ran it) |
| **C-m10** no DirectVulkan arm | not C's | ✔ still the integrator's to confirm against F |
| **n1** `Evict`'s copy-assign | **taken** | ✔ `:452-458`, and the sentence is accurate |
| **n2** `SanityTest.cpp:3898` | recorded for D | ✔ |
### Hygiene, exit order, ownership — clean
* **No `MGLOG_*`, `TODO`, `FIXME`, `printf`, `std::cout`, `#if 0` or `pGLContext` in any of the four
headers** (grepped at HEAD). MGLOG discipline is vacuously satisfied — the headers log nothing.
* **No new static holder of a frontend `SharedPtr`.** The one new member is
`Array<MGPipeHandle, 192> m_stateRefs` (`SamplerEmit.h:996`) — a POD array of `{slot, gen}` pairs.
`Entry::RefCount` is a `Uint32`. `CompositeResolver::Entry` is unchanged in kind. All six singletons
are still `static T* p = new T();` and never destroyed (`SamplerEmit.h:473`, `:630`, `:1013`;
`ProgramEmit.h:475`; `ImageEmit.h:170`; `CompositeResolver.h:210`).
* **Ownership.** The rework touches six files, all C's: three `MG_Impl/Pipe` headers and their three
`MG_Test/Pipe` suites. `ImageEmit.h` is untouched by the rework. Nothing under `MG_Backend/`,
`MG_Pipe/`, `scripts/` or `.github/`.
* **No debug leftovers.** The only test-only surface is `AcquireWithForcedHashForTest` (C2-n3).
---
## 7. Findings of this round
### C2-M1 [MAJOR] — §2 above. Demonstrated red on `00a86d2a`, green on v1's `Reset()`.
### C2-m1 [MINOR] `HandleFor()` is dead, so `Fresh` has no live reader and `Reset()` is observably a no-op
`CompositeResolver.h:149-154`, `:183`, `:143-145`.
`Fresh` is written by `Observe` (`:111`, `:125`) and `Reset()` (`:144`) and **read in exactly one
place**: `HandleFor` (`:151`), which has **no caller anywhere in the tree** — grepped `MobileGL/**`,
production and tests alike. So the second half of the Live/Fresh split is unobservable scaffolding and
`MGPipeCompositeResolver::Reset()` now changes nothing any caller can see.
**Failure scenario.** None, today — this is dead weight, not a bug. It matters because it is *the same
class as C-m4*, which this very round deleted (`Forget()` had no caller, so out it went), and because
a reader of `:130-145` will believe `Reset()` does something. It also masks C2-M1: if `Fresh` had been
given a real reader, the question "what distinguishes my entry from another context's after a Reset"
would have had to be answered.
**Refutation attempted.** (a) *It is future API for B or D.* No — the resolver is entirely internal to
`ProgramEmit.h`; nothing else includes `CompositeResolver.h` except its own test. (b) *The new case
reads it.* It does not; the case reads `DrawCso()`, `Releases` and `IsLive`. (c) *Deleting `Fresh`
would re-break C-M1.* Also no — with `Live` no longer cleared, `Reset()` could be deleted outright and
every existing case stays green; the correct answer is a context key (§2), which gives `Fresh` a
purpose or removes the need for it.
**Disposition:** fold into the C2-M1 fix — either give `HandleFor` a caller or delete it, and say which
in the header.
### C2-m2 [MINOR] `Release` is silent on a handle it never handed out, and "a double release is a no-op" is true only when nobody else holds the entry
`SamplerEmit.h:263-275`.
```cpp
void Release(MGPipeHandle handle) {
if (MGPipeHandleIsNull(handle)) return;
for (Entry& entry : m_entries) {
if (entry.Cso != handle) continue;
if (entry.RefCount > 0) --entry.RefCount;
++m_counters.Releases;
return;
}
}
```
Two things the comment at `:263-266` promises that the code does not deliver.
1. **An unknown handle falls off the end of the loop and is counted nowhere.** `Releases` counts only
releases that *found* an entry, so a caller releasing a handle this cache never minted — a stale
handle from before a `ResetForTest`, a `Texture` handle passed by mistake, a handle whose entry was
already evicted — leaves no trace at all.
2. **A double release does not "not corrupt the count" when the entry is shared.** Entries are
content-addressed and shared by design: package B's texture params record and this file's own
`m_stateRefs` will routinely hold the *same* handle. `Release` is per-handle, not per-holder, so a
second release from B decrements the pin `bind_sampler_states` is holding. The entry becomes
`RefCount == 0` while a published `MGPTextureParams` **and** a standing `bind_sampler_states` set
still name it, the LRU may then take it, and we are back at C-M3 — silently, because the applier
does not resolve `BuiltinSampler` and nothing counts the extra release.
**Failure scenario.** B holds one ref for texture T's built-in sampler H; unit 3 is bound to a sampler
object with the same parameters, so `EmitSamplerStates` holds a second ref on H (`RefCount == 2`). B's
texture-death path releases H, and B's params-change path — which per report §3 rule 3 also releases
"the previous handle" — releases it again because its per-texture latch was not cleared. `RefCount`
is now 0 with unit 3 still bound. The next `Mint` under pressure evicts H, `delete_sampler_state` goes
out, and the applier's standing `BoundSamplerStates[3]` names a slot that has been re-handed out to a
different value. Wrong filtering, no refusal, no counter.
**Refutation attempted.** (a) *That needs a bug in B.* It does — and this API is being handed to
another package with a written four-rule contract, which is exactly when the callee should make a
contract violation visible rather than absorb it. (b) *An assert would do.* No: `MOBILEGL_ASSERT` is
off in every gate and shipped build (`Defines.h:104-115`) — the finding C-m6 just closed. (c) *The
over-capacity path makes it safe.* That path protects against too many pins, not too few.
**Fix (small):** two counters in the same counted-refusal idiom C-m6 adopted —
`Counters::UnknownReleases` incremented when the loop finds nothing, and
`Counters::UnderflowedReleases` incremented when `RefCount` is already 0 — plus one sentence in the
comment saying the count is per *handle*, not per *holder*, so a holder that releases twice steals
another holder's pin. No behaviour change, and B's review gains something to assert on.
### C2-m3 [MINOR] the refcount reconciliation's cost is understated, and c0d makes it land far more often
Report §1 describes the reconciliation as *"one extra pass over the 192-entry unit array"*, and C-m2's
deferral is budgeted against that sentence. The pass is 192 iterations, but each `cache.Release(held)`
on a **non-null** handle is a **linear scan of the whole cache** (`SamplerEmit.h:269-274`), sitting
beside the `Acquire` probe which is already a linear scan (`:339-357`). So a pass with *K* units
holding sampler CSOs costs `2 · K · O(cacheSize)` handle comparisons, not one extra array walk — up to
~98 000 iterations per firing at `K = 192` with a full cache, and unbounded above that because the
over-capacity path lets `m_entries` grow past 256.
And the firing rate moved under C's feet: **c0d mixes `GetTextureBindGeneration()` into bit 13's
shutter** (`contract-v4.md` §1.2, §6 item 1), so `EmitSamplerStates` now runs on **every texture bind
at any unit**, not only on a parameter change — the contract's own text says C's set-hash suppressor
is *"now load-bearing, not an optimisation"* and that C-m2 *"is worth more after this commit than
before it"*. The suppressor stops the *record* going out; it does not stop the acquire/release walk,
which happens first.
**Refutation attempted.** (a) *K is small.* In Minecraft-shaped workloads K is typically **0** — units
have no `SamplerObject` bound, so `m_states[unit]` is null, `Acquire` is not called and
`Release(null)` returns immediately. This is the honest limit of the finding and it is why it is a
minor and not a major. (b) *A CTS sampler sweep is not a perf lane.* True, but it is a correctness
lane whose wall-clock matters, and it is exactly the workload with large K **and** a large cache.
(c) *ID-19 already carries C-m2.* It does — with the wrong cost model.
**Disposition:** record the corrected model in `MEASUREMENTS.md` under ID-19 beside C-m2, and note
that the per-unit `(sampler lifetime id, GetSamplingResolutionGeneration())` latch C proposes removes
**both** scans, not one.
### C2-n1 [NIT] `Evict`'s `MOBILEGL_ASSERT` is presented as an ID-17 mechanism but is off in every build that runs
`SamplerEmit.h:435-436`. The v2 report's C-M3 table lists *"`Evict` asserts its victim is
unreferenced"* as one of the ruling's mechanisms; `Defines.h:104-115` compiles it out at INFO. It is a
**defensible** debug-only invariant check — the sole caller (`:374-375`) structurally guarantees
`RefCount == 0`, so unlike C-m6 there is no reachable condition being silently swallowed — but it is
the same idiom this round removed from `ProgramEmit.h`, and it is not a mechanism in the shipped
build. Say so in the report row, or make it a counter.
### C2-n2 [NIT] the cache never shrinks after an over-capacity peak
`SamplerEmit.h:361-381`. Once `m_entries.size() > 256`, every subsequent `Mint` evicts one
unreferenced entry and pushes one, so the size stays at its high-water mark for the life of the
process — along with that many `SamplerCso` slots in the allocator and that many `create_sampler_state`
records in the applier. Bounded by the peak simultaneous pin count, so this is memory retention rather
than a leak, and growing was the ruled-safe direction; worth one sentence beside `OverCapacityMints`
so the number is read as "how far the cache permanently grew", not "how often it grew".
### C2-n3 [NIT] `AcquireWithForcedHashForTest` is a public production method, and report §3's "full seam" listing is not full
`SamplerEmit.h:256-262`. It is guarded by nothing but its name and is callable from any translation
unit that includes the header — including package B's `TextureEmit.h`, which is about to. Misuse is
harmless (a value stored under a wrong hash simply mints a duplicate later), and a `#if` seam would
have been worse (the review named this as the honest option), so this is a nit and not a finding. But
report §3 presents a six-member listing as *"the full seam"* while the class has nine public members;
B should be told the three it must not call.
---
## 8. Per-item closure table
| item | ruling | v2 disposition | this review |
|---|---|---|---|
| C-M1 | fix + case through the resolver | Live/Fresh split + case + control | **closed, but over-corrected → C2-M1** |
| C-M2 | invalidate on every re-issue | `ProgramEmit.h:268-271` + case + control | **CLOSED, correct** |
| C-M3 | ID-17 ref counts | ref count + 3 cases + control | **CLOSED, correct** |
| C-M4 / C-M5 | not C's → c0d | not re-fixed | **correct — c0d owns them; C must not touch `Tracker.h`** |
| c0b item 1 | `EmitSamplerCso` | added `:888` | **CLOSED** (build proves the spelling) |
| c0b item 2 | `EmitSamplerView` | added `:900` | **CLOSED** |
| c0b item 3 | `EmitShaderCso` | added `ProgramEmit.h:292` | **CLOSED** |
| c0b item 4 | four latch calls | `:419`, `:450`, `:313`, `:855`, `ProgramEmit.h:255` | **CLOSED** (four sites + the `ResetForTest` one the review asked for) |
| c0b item 5 | comments rewritten, mirrors explained | done | **CLOSED** |
| c0b item 6 | the sentence for D | `:201-205` | **CLOSED** |
| c0b item 7 | two false comments | rewritten | **CLOSED, and now accurate** |
| c0b item 8 | one-door case still green | verified | **CLOSED — I ran it** |
| ID-14 §7 | B's exact call | report §3 | **CLOSED, matches the code** |
| C-m1 / C-m2 / C-m5 / C-m10 | declare | declared | **accepted** (C-m2's cost model corrected — C2-m3) |
| C-m3 / C-m4 / C-m6 / C-m8 / C-m9 / n1 | fix | fixed | **accepted** (C-m4 left `HandleFor` — C2-m1) |
| C-m7 | fix | **refuted** | **refutation upheld — the v1 review was wrong** |
| n2 | tell D | recorded | **accepted** |
---
## 9. What the integrator must re-run, in order
C's tree is at `17db7598`; the pipe is at **`e8502a61`** (c0d `9ea44389` + c0e). **Nothing C owns has
to change because of c0d or c0e** — `wants()`'s map, the emitter entry points and the two subsystem
constants are untouched, and c0e's `MGPipeFramebufferTarget::Named = 3` is not in C's reach. What
changes is *how often C's code is entered*, so the numbers do not carry over.
1. **Fix C2-M1 first** (§2), or record an explicit ruling that concurrent contexts are out of P4a's
scope **and correct `CompositeResolver.h:130-142`**, which currently claims the opposite property.
Whichever way, add the two-pipelines-one-name case.
2. **B's seam before anything else** (report §3 / ID-14 / ID-17): B takes `BuiltinSampler` from
`MGPipeSamplerCsoCacheInstance().Acquire(...)`, holds the reference, releases the previous handle on
re-acquire and at texture death, and **deletes** its own `MGPipeSlots().Acquire(SamplerCso, …)`.
With wire underneath, a null or stale `BuiltinSampler` is `Fatal{ProtocolCorruption}` on **every**
`set_texture_params`. B's review must also confirm B's params gate is keyed on
`GetTextureParamsVersion()`, and that B owes **exactly one** `Release` per `Acquire` (C2-m2 says
why a duplicate is silent).
3. **Rebase onto `e8502a61` and re-run C's whole §6 gate set** — three builds, G1 0/0/0/0,
`gen_pipe.py --check/--self-test`, the generated-file diff, `gen_pipe_dirty_surface.py`,
`check_include_closure.py --mode both --compiler clang++ --self-test --require-all
--expect-probes 4` (again after B adds its include), `p3a_untouched_regions.sh 37da3c3a HEAD`,
`ctest -L unit` ×3, the pull/push name-parity pair and the 0-removed check.
4. **The emit suites**, `build-push`,
`-R 'SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.'` — 34/34 at this head, plus
whatever the C2-M1 fix adds. With `wire` underneath these reach a real applier for the first time.
5. **`TrackerTest`** (A's, c0d's own cases) — not C's, but it is the shutter both of C's newly
hot paths hang off.
6. **The three `integration-gpu` arms (default / `0` / `0x1ff`) and the whole label, and
`integration-verify` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` with
`grep -c 'Fatal{'` = 0.** These are the rows c0d invalidates, and it is worth saying exactly why:
bit 13 now fires on **every texture bind**, so `EmitSamplerStates`' 192-unit walk *and* the new
refcount reconciliation run on batches where only a texture moved; and bits 6/7/8/14 now fire
**under a bound pipeline**, so `EmitShaderState` and the composite resolver are exercised for the
first time. C's own unit cases are indifferent to c0d by construction (they drive the emitters
directly); these arms are not.
7. **`ProgramPipelineScenario`'s sixteen cases and any scenario that rebinds a *different* sampler
object to a unit** — the only things that can see the paths c0d opened, and the only place C2-M1
could show up outside a unit case.
8. **A DirectVulkan arm for the death/leak cases** (ID-8, C-m10) — confirm F's G8b cases run there or
say plainly that they do not.
9. **After `esprytobj` + `esprytdraw`**: `MOBILEGL_PIPE_PUSH=0x5ff` / `0x9ff` must be **refused** at
D's texture-family `Resolve*SubsystemArm` (ID-15's fourth D-K2 row), never half-run — C emits
`MGPBoundView::Texture` (`SamplerEmit.h:721`) and `MGPImageView::Res` (`ImageEmit.h:97-99`) as
`Texture` handles unconditionally.
10. **`retrace_gate.py`** after confirming `tools/trace_replay/fixtures` are real files — the false
red is `passed 2 / 79` with `ssim=None`. Any fresh worktree needs `git lfs checkout` first
(ID-13); note that in C's tree `git lfs install` has never configured the smudge filter, so the
fixtures are the copied-in real files and `git status` must stay clean.
11. **`MEASUREMENTS.md` under ID-19**: C-m2's per-unit acquire latch **with the corrected cost model**
(C2-m3), and the one extra `set_global_constants` per link C found while writing the C-M2 case.
12. **The open question C named**: whether `MGPipeEmitSamplerCsoCreate` gets its one-line call site in
`SamplerObject`'s constructor. C's reasons for declining are good; if the answer is no, the
entry point stays instantiated-but-uncalled and that should be written into ID-26 rather than
left as a loose end.
@@ -0,0 +1,434 @@
# P4a package C — `clientsp`. Result, v1
Branch `refs/heads/p4a/clientsp`, four commits on top of `p4a/contract` = `08192d72`. **Not pushed.**
`git diff --stat 08192d72..HEAD`: **11 files, +2426 / −52.** Working tree clean.
| # | hash | message (exact, single line, no attribution) |
|---|---|---|
| c1 | `2700a058` | `[Feat] (Pipe): content-address sampler states, mint one sampler view per texture and push the three unit sets behind their own content hashes` |
| c2 | `384bff48` | `[Feat] (Pipe): publish a program's per-stage SPIR-V and reflection archive as a shader CSO and its default uniform block as global constants` |
| c3 | `7894f9bf` | `[Feat] (Pipe): resolve a program pipeline into one shader CSO out of the reserved composite band and release it exactly once` |
| c4 | `ecd5b2e7` | `[Test] (Pipe): wire the sampler and program subsystems and pin the padding-proof CSO identity, the program-resolved unit sets, the linked-snapshot stage mask and the composite band's single release` |
C.2's steps map one for one; c4's message is C's own (the brief prescribes none for step 4).
---
## 1. Verdict on the hard rules
| rule | result |
|---|---|
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` | **0 added / 0 removed / 0 renamed / 0 resized.** File bytes and `.text` byte-identical (19114360 / 10806323), 27811 → 27811 defined symbols. rc 0. |
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 (7 controls tripped) |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0 (27 controls, all tripped); the two UNDECIDED rows are the contract's D6 and are unchanged |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all` | rc 0, 4 probes, 0 skipped, 0 problems, 6 controls tripped |
| `p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, the eleven byte-identical |
| three builds (pull / push / verify) | all three, rc 0 |
| `ctest -L unit` in all three | **rc 0 in each**, no failures |
| ctest names pull == push | `diff` empty |
| no baseline name removed | `comm -23 ~/w7/p4a-before-ctest-names.txt <names>` empty; **38 added** (13 the contract's, 25 C's) |
| `ctest -L integration-gpu -j 8` on `build-push`, default arm | **966/966**, rc 0 |
| same, `MOBILEGL_PIPE_PUSH=0` | **966/966**, rc 0 |
| same, `MOBILEGL_PIPE_PUSH=0x1ff` (P4a's subsystems off) | **966/966**, rc 0 |
| `ctest -L integration-verify -j 4` on `build-verify` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` | **844/844**, rc 0, `grep -c 'Fatal{'` = **0** |
| `MOBILEGL_PIPE_VERIFY=1 retrace_gate.py … -j 4` | §5 |
| only C's files (+ granted) | yes — §4 |
| no push, no other worktree, no attribution lines | yes |
---
## 2. Per-file summary
### `MG_Impl/Pipe/SamplerEmit.h` (+714, the stub replaced)
Four things, in this order.
- **`MGPipeCanonicaliseSamplerParameters(src, out)`** — `memset` to zero, then sixteen field
assignments in `MGP_FIELDS_SamplerParameters`' order, `borderColorForm` included.
**It takes an OUT-PARAMETER and does not return a value** (§4 deviation D1).
`MGPipeHashSamplerParameters(canon)` is XXH64 over those 100 bytes;
`MGPipeHashOfSamplerParameters(src)` is the two in one step.
- **`MGPipeSamplerCsoCache`**, capacity 256: hash, probe, **memcmp-confirm**, LRU `Evict` that
emits `delete_sampler_state` and frees the slot, counters
`{Mints, Acquisitions, Hits, Collisions, Evictions}`, `RecordIsPublished(handle)` and a
test-only `ResetForTest()`. `MGPipeSamplerCsoCacheInstance()` is never destroyed and is
**package B's seam** for `MGPTextureParams::BuiltinSampler`.
- **`MGPipeSamplerUniformTextureTarget(GLenum)`** — DirectGLES' `SamplerUniformTextureTarget`
moved to the side of the boundary that now owns the question, and
**`MGPipeProgramOpaqueUnits`**, one inversion of the program's opaque-uniform table
(`unit → sampled target`, plus the highest image unit), memoised on
`(lifetimeId, linkVersion, backendStateVersion)`. `MGPipeProgramOpaqueUnitsShared()` is one
instance for the whole family, shared with `ImageEmit.h`.
- **`MGPipeSamplerEmitter`** — `EmitSamplerViews`, `EmitSamplerStates`, `AcquireSamplerView`,
`RecordIsPublished` / `NoteRecordDestroyed`, `Reset`, `ResetCounters`, and the
no-copy accessors a unit case reads. `kMGPipeWiredSamplerSubsystem` = `kMGPipeSubsystemSamplers`.
### `MG_Impl/Pipe/ImageEmit.h` (+120, the stub replaced)
`MGPipeShaderImageSetContentHash` and `MGPipeImageEmitter::EmitShaderImages`: the window, the
zero early-out taken **before** any hash, the per-unit `MGPImageView` build carrying the
application's format and access unrecast, `MGPipeEncodeImageAccess` (the three GL names folded
into one byte, with an assert on a fourth), the suppressor slot, `Reset` (the window is
per-context), and the accessors. It rides `kMGPipeWiredSamplerSubsystem`.
### `MG_Impl/Pipe/ProgramEmit.h` (+339, the stub replaced)
`kMGPipeGlobalConstantsNeverUploaded` + `MGPipeGlobalConstantsVersionIsEmittable`,
`MGPipeStageMaskOf` (off `GetLinkedShaderStages()`), and `MGPipeProgramEmitter`:
`EmitShaderState` (both joins, the composite observation, `bind_shader_state`,
`set_draw_program`, `set_dispatch_program`), `EmitGlobalConstants`, `AcquireShaderCso` (the
re-issue on the same handle), `AcquireShaderCsoHandle` (the one place the composite band can be
entered), the **two** latch tables (ordinary and band, never one wide one),
`RecordIsPublished` / `NoteRecordDestroyed`, `Reset`, `ResetCounters`, accessors.
`kMGPipeWiredProgramSubsystem` = `kMGPipeSubsystemPrograms`.
### `MG_Impl/Pipe/CompositeResolver.h` (+194, new)
`MGPipeProgramIsPipelineComposite(program)` (external index 0, Core.cpp:661's own invariant) and
`MGPipeCompositeResolver`: the signature-keyed memo, `Observe`, `Forget`, `Reset`, counters
`{Mints, Reuses, Releases}`. Entries hold a GL name, a signature of plain integers, a handle and
a lifetime id — **no frontend `SharedPtr`**, which is the exit-order rule.
`MGPipeCompositeResolverInstance()` is never destroyed.
**It is included BY `ProgramEmit.h`, not the other way round**, so the resolver is live in the
build that matters rather than only in a test.
### `MG_State/GLState/SamplerState/SamplerObject.cpp` (+17/−4)
The `#if MOBILEGL_PIPE_PUSH` destructor body's bare `NotifyStateObjectDestroyed(SamplerCso, …)`
becomes `MG_Pipe::MGPipeEmitSamplerCsoDestroyAndFree(m_lifetimeId)` — edited, never added
(G1). For a content-addressed CSO the helper correctly frees nothing (§3).
### `MG_State/GLState/ProgramState/ProgramObject.cpp` (+17/−4)
The same edit, `MGPipeEmitShaderCsoDestroyAndFree(m_lifetimeId)`, and it is the one line an
ordinary program and a pipeline composite share. `#include <MG_Pipe/PipeMutation.h>` added.
### `MG_State/GLState/ProgramState/ProgramObject.h` (+17)
One new accessor, **inside `#if MOBILEGL_PIPE_PUSH`**: `const SpirvArtifacts& GetSpirvReflection() const`
— the phase-B twin of `GetLinkReflection()`. `MGPipeApplyCreateShaderState` takes both whole
structs and the class had no public whole-struct SPIR-V accessor (§4 deviation D6).
### Tests
`MG_Test/Pipe/SamplerEmitTest.cpp` (+372, 10 cases), `ImageEmitTest.cpp` (+214, 5),
`ProgramEmitTest.cpp` (+259, 7), `CompositeResolverTest.cpp` (+215, 6). Each keeps the contract
commit's shape-pinning case verbatim, carries the pull-build SKIP list so `ctest -N` stays
name-for-name identical, and uses an RAII scope rather than a `TEST_F` (a fixture would file
every case under the fixture's name and out of the gates' `ctest -R` reach).
---
## 3. The identity rules, as implemented
### Sampler CSO — CONTENT-addressed, capacity 256
Key = XXH64 over a **zero-initialised canonical copy** built field by field, confirmed with a
`memcmp` over the same canonical bytes before any handle is reused. Slots come from
`MGPipeSlots().Allocate(SamplerCso)` **without a lifetime id**, deliberately: the CSO belongs to
a VALUE, not to a frontend object, so `~SamplerObject` must not free it — another live
`SamplerObject` may hold the same value. Its **only** death path is the cache's LRU eviction,
which is client-side and therefore backend-neutral from the first commit.
`static_assert(kMGPipeSamplerCsoCacheCapacity > kMGPipeMaxTextureUnits)` makes "a handle named
in the tail of the record being built now can never be the LRU victim" a build-time property:
one pass acquires at most 192 and touches every one of them.
### Sampler view — IDENTITY-addressed, one per `ITextureObject`
`MGPipeSlots().Acquire(SamplerViewCso, texture.GetLifetimeId())`, `create_sampler_view` re-issued
on the **same handle** whenever the restrictions move (`Gen` moves only on slot reuse).
The version-first skip latches `(GetShapeVersion(), GetTextureParamsVersion(), Gen, textureHandle)`
per slot. The shape version is the load-bearing half — it is what `BumpShapeVersion` moves, i.e.
exactly the inputs `MGPSamplerView` carries; the params version rides beside it belt-and-braces
(no field of the record depends on it, so a wrap of that `Uint16` can only cost a skipped
re-issue of an identical record). The four view restrictions are emitted from
`GetViewMinLevel/NumLevels/MinLayer/NumLayers`, which are `0` for an ordinary texture and written
by `glTextureView` for a view — so **zero unambiguously means "unrestricted"** and there is no
second spelling of that case to disagree with the first.
### Shader CSO — IDENTITY-addressed, one per `ProgramObject`
`Acquire(ShaderCso, program.GetLifetimeId())` for an ordinary program;
`AllocateComposite(lifetimeId)` for a composite. `create_shader_state` re-issued on the same
handle whenever `GetLinkVersion()` moves; the latch is `(RecordLive, RecordGen, LinkVersion)`.
All seven `MGPBlobRef`s declare `Seg = kMGHostSpanSegNone, Size = 0` (the one Blob rule) and the
artefacts ride beside the record through the entry point's companion pointers — **the codec is
never called on the monolith path**. `Offset` carries the staging address, diagnostics only.
### Composite — the band, and exactly one free
Minted off the composite `ProgramObject`'s **own** lifetime id out of
`[kMGPipeShaderCsoCompositeSlotBase, kMGPipeShaderCsoSlotLimit)` through the allocator's one
door. Two release paths, both through `MGPipeEmitShaderCsoDestroyAndFree`: the resolver's
signature-move release, and the composite's own `~ProgramObject`. Whichever runs second is a
proven no-op (`Free` refuses a slot that is not live at that generation and bumps no generation
of its own). Both orders are pinned.
**Two pipelines with the same signature do NOT share one handle** — see §4 deviation D4.
### The two unit sets and the image set
`set_sampler_views` is the **program-resolved** set (`Start = 0`,
`Count = GetMaxTouchedTextureUnit() + 1` clamped to 192); a unit the program does not sample, a
unit with nothing bound, an undefined default texture and a texture that
`SamplesAsIncompleteTexture` all carry the null view — which is the resolution DirectGLES
performs by leaving the native target unbound. `bind_sampler_states` is deliberately **not**
program-resolved (a sampler object is bound to a UNIT and applies to whatever it holds), which
is `BindCurrentUnitSamplers`' shape. All three hash field-wise over zero-initialised staging
arrays with `Start` and `Count` mixed in, and all three go through their `SetHashSuppressor` slot.
---
## 4. `EmittedCallSuppliesTheWholeField` — the decisions, and why none of them moved
All six P4a rows were placed in the **false** arm by the contract commit. C's implementation
confirms every one of them for its own families, so `PipeFill.cpp` (A's for the phase) needed no
edit and no field stopped being pulled:
| field | verdict | reason as implemented |
|---|---|---|
| `GetProgramForDraw` | **false** | pointer-valued. The emitted call carries a `{slot, gen}` HANDLE, not the `SharedPtr<ProgramObject>` the field returns — exactly `GetBoundVertexArray`'s reason. |
| `GetProgramForDispatch` | **false** | the same, and it is a second, independent slot. |
| `GetTextureUnitObject` | **false** | the field hands back a live `TextureUnit&` with one binding slot per target; `set_sampler_views` carries the RESOLVED single view per unit, which is strictly less. |
| `GetMaxTouchedTextureUnit` | **false** | the applier's `Count` can lag the frontend's mark by exactly the case the suppressor exists to swallow: a redundant re-bind moves `GetTextureBindGeneration()` and the mark, and the resolved set's hash does not move, so nothing is sent. |
| `GetImageTextureBinding` | **false** | the field is a live `ImageTextureBinding&` including its `SharedPtr`; the record carries a handle plus an access byte. And C's window is program-derived (§4 D7), so a unit outside it is not described at all. |
| `GetFramebufferBindingSlot` | **false** | package B's, untouched here. |
---
## 5. Verification transcript
```
$ git log --oneline -5
ecd5b2e7 [Test] (Pipe): wire the sampler and program subsystems and pin the padding-proof …
7894f9bf [Feat] (Pipe): resolve a program pipeline into one shader CSO out of the reserved …
384bff48 [Feat] (Pipe): publish a program's per-stage SPIR-V and reflection archive …
2700a058 [Feat] (Pipe): content-address sampler states, mint one sampler view per texture …
08192d72 [Feat] (Pipe): land the P4a contract - …
$ for d in build-linux build-push build-verify; do cmake --build $d -j 12; done all rc=0
$ 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
| before | ~/w7/p4a-before-libMobileGL.so | 19114360 | 10806323 |
| after | build-linux/libMobileGL.so | 19114360 | 10806323 |
.text 10806323 -> 10806323 (+0, +0.000%). 27811 -> 27811 defined symbols:
0 added, 0 removed, 0 resized, 0 renamed, 27072 unchanged. rc=0
$ python3 scripts/gen_pipe.py --check rc=0
gen_pipe: 71 calls (11 screen, 60 context), 72 verify payloads, 63 PipeInputs fields, 69 verbs
gen_pipe: inventory 477 rows: ... 0 UNMAPPED; generated files are up to date
$ python3 scripts/gen_pipe.py --self-test 7 negative-control trip(s), positive OK rc=0
$ git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --check rc=0
dirty-surface: 79 mutators, all mapped, no stale rows; 45 render-state answers derived
... 0 COARSE; 2 UNDECIDED (the contract's D6, unchanged); 26 prose answers
$ python3 scripts/gen_pipe_dirty_surface.py --self-test 27 negative controls, all tripped rc=0
$ python3 scripts/check_include_closure.py --mode both --compiler clang++ --self-test --require-all
include-closure: 4 probes, 0 skipped, 0 problem(s); self-test 6 negative-control trip(s) rc=0
$ 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
$ for d in build-linux build-push build-verify; do ctest --test-dir $d -L unit --no-tests=error -j 12; done
all rc=0, 0 failed
$ diff <(names build-linux) <(names build-push) (empty)
$ comm -23 ~/w7/p4a-before-ctest-names.txt <(names build-linux) (empty)
$ comm -13 ~/w7/p4a-before-ctest-names.txt <(names build-linux) 38 added
$ ctest --test-dir build-push -R 'SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.' \
--no-tests=error --output-on-failure 100% passed, 29/29 rc=0
$ ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8
100% tests passed, 0 tests failed out of 966 rc=0
$ MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu -j 8
100% tests passed, 0 tests failed out of 966 rc=0
$ MOBILEGL_PIPE_PUSH=0x1ff ctest --test-dir build-push -L integration-gpu -j 8
100% tests passed, 0 tests failed out of 966 rc=0
$ GLIBC_TUNABLES=glibc.malloc.tcache_count=0 \
ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4
100% tests passed, 0 tests failed out of 844 ; grep -c 'Fatal{' = 0 rc=0
```
```
$ MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/p4a-clientsp \
--lib ~/w7/p4a-clientsp/build-verify/libMobileGL.so --out ~/w7/retrace-out/p4a-clientsp -j 4
79 tests selected of 79
...
passed 79 / 79; failed: []
retrace_gate rc=0
$ grep -l 'Fatal{' ~/w7/retrace-out/p4a-clientsp/*.log (empty)
$ grep -L 'MGPipe verify:' ~/w7/retrace-out/p4a-clientsp/*.log (empty - all 79 armed)
$ rm -rf ~/w7/retrace-out/p4a-clientsp
```
**The first attempt of this run reported `passed 2 / 79` with `ssim=None` on every Minecraft
case.** That is the LFS-pointer false red, not a regression — see deviation D11.
---
## 6. Granted sites
**None used.** C.7 grants C `MG_Impl/GLImpl/Program/GL_Program.cpp` ("nothing today —
`create_shader_state` is emitted from the validate point"); that stayed true and the file is
untouched. `MG_State/GLState/Core.{h,cpp}`, which C.7 gives to C after the tag, is **also
untouched** (deviation D5).
Every file C edited is one C.7 names as C's: `MG_Impl/Pipe/{SamplerEmit,ImageEmit,ProgramEmit,
CompositeResolver}.h`, `MG_State/GLState/{SamplerState,ProgramState}/**`, and
`MG_Test/Pipe/{SamplerEmit,ImageEmit,ProgramEmit,CompositeResolver}Test.cpp`.
Nothing under `MG_Backend/`, `MG_IntegrationTest/`, `.github/`, `scripts/`, `MG_Pipe/`,
`MG_Impl/Pipe/{PipeFill,Tracker,SetHashSuppressor,SlotAllocator,CsoCache,ResourceTracker,
VertexInputEmit}`, or any of B's `MG_State` directories.
---
## 7. Deviations, each with its reason
**D1 — the canonicaliser takes an out-parameter, and the cache stores its bytes with `memcpy`.**
D-F1 says "hashed with XXH64 over the copy". A copy is not enough: a copy of a trivially
copyable type leaves the padding **unspecified**, so a canonicaliser that returned by value
would hand its caller three bytes of whatever the copy left there, and `Entry::Params = canon`
would leave the cache's own stored bytes with different padding from the probe's.
**This is not theoretical — it was the bug.** With member-wise assignment the first probe's
`memcmp` rejected the cache's own entry, counted a collision that never happened, evicted and
minted a fresh CSO: a 256-entry cache with a hit rate of zero, whose failure depends on heap
contents, so `TwoIdenticalSamplersShareOneCso` **passed run alone and failed run in a suite**.
Both are now `memset`/`memcpy` and `PaddingCannotChangeTheHash` covers the hash and the confirm.
**D2 — [FINDING] `kMGPipeWired*Subsystem` is NOT the emission gate, so c1–c3 are not inert.**
The validate point's `wants()` (`PipeFill.cpp`) asks `MGPipeSubsystemForDirty(bit)` and the
runtime `MOBILEGL_PIPE_PUSH` mask **and nothing else**; only the texture drain additionally
tests `kMGPipeWiredSubsystems`. So the moment an emitter has a body it runs at the phase default
mask `0x1fff`, whatever its family constant says. The tree is still behaviourally unchanged —
every applier entry point is a stub on this branch — but C.1's b1 wording ("the emission is
proven semantically free before anything is switched over") does not hold for the framebuffer,
sampler, image or program families as `PipeFill.cpp` is written, and **package B inherits the
same fact**. It surfaced as a real test symptom: a `glBindImageTexture` reaches the validate
point and emits the set, so a direct `EmitShaderImages` afterwards is correctly suppressed
(deviation D14). Recorded rather than fixed, because `PipeFill.cpp` is A's for the phase.
**D3 — [FINDING] the six death helpers hardcode `published = false`, so no wire delete can go
out from a frontend destructor.** `PipeFill.cpp:899-980` reads
`const Bool published = false; // the … emitter publishes nothing yet` for all six kinds, and
that file is A's for the entire phase (ID-9 D1: "never touch `PipeFill.cpp`"). C therefore
cannot make `delete_sampler_view` or `delete_shader_state` go out at object death.
**Impact is bounded and no slot leaks**: `NotifyAndFree` still frees the slot, so `HighWater`
and the leak cases are unaffected; what stays behind after `wire` lands is a `Live` applier
record on a freed slot, which no live handle can reach and which a create on the recycled slot
starts over. **The fix is one line per helper and C has already provided the other half**: both
emitters expose `RecordIsPublished(handle)` and `NoteRecordDestroyed(handle)` with P3a's exact
signature, so each body becomes
`const Bool published = emitter.RecordIsPublished(handle); if (published) { …ApplyDelete…; emitter.NoteRecordDestroyed(handle); }`.
`SamplerCso` needs no fix at all: it is content-addressed, has no per-object slot, and its
delete rides the cache's own LRU eviction.
**D4 — `TwoPipelinesWithTheSameSignatureShareOneComposite` is implemented and named
`TwoPipelinesWithTheSameSignatureKeepTheirOwnComposite`.** Sharing one handle between two
composites is not safely implementable and the property that is true is the opposite one. A
composite is an ordinary `ProgramObject` with its own lifetime id, and the death helper resolves
the handle **from** that id; two composites sharing one handle would put only one id in the
allocator's map, so the first `~ProgramObject` would free a slot the second still names — a
premature free that reappears later as slot theft, which is the class the reserved band exists
to prevent. The frontend does not share either: each `ProgramPipelineObject` carries its own
one-slot draw-program cache. The case asserts both handles are distinct, both are in the band
and both stay live; the reason is written into the case.
**D5 — no `Core.{h,cpp}` hook; the composite is identified by `GetExternalIndex() == 0`.**
C.2 grants `Core.{h,cpp}` for "the hook the composite resolver observes". None is needed:
`Core.cpp:661` constructs the composite as `MakeShared<ProgramObject>(0u)` **deliberately**, so
that it is not a named program, does not answer `glIsProgram` and consumes no name — and
`glCreateProgram` never returns 0. A `Bool` member on `ProgramObject` would resize the pull
build's object and break G1 outright. `CompositeResolverTest.ACompositeIsMintedFromTheReservedBand`
pins the discriminator against a really flattened pipeline.
**D6 — `ProgramObject.h` gains one push-guarded accessor.** `MGPipeApplyCreateShaderState` takes
`const SpirvArtifacts*`, and the class exposes only granular SPIR-V getters — no public
whole-struct accessor, and `reservedNumSamplesOffset` has no getter at all.
`GetSpirvReflection()` is the phase-B twin of the existing `GetLinkReflection()`, inside
`#if MOBILEGL_PIPE_PUSH` so a pull build's symbol set and this class's layout are untouched
(G1 confirms: 0 resized).
**D7 — the image-unit window is derived from the program, because the frontend has no
image-unit high-water mark.** D-G2 says `Count` is "the image-unit high-water mark + 1", and
D-G4 property 1 is the zero early-out. `g_imageUnitHighWaterMark` is **DirectGLES'**, written
from inside its own per-unit sync; `TextureState::NoteUnitTouched` is the TEXTURE-unit path and
`glBindImageTexture` does not reach it. Adding a counter to `TextureState` would edit package
B's file **and** resize the pull build's object. So the window is
`max(highest image unit the current program names + 1, the emitter's own sticky window)`, taken
from the shared opaque-unit inversion. A program with no image uniform gives 0 and the set is
not emitted at all — which is property 1's intent exactly ("one integer test for a feature it
does not use"), and it costs no 192-entry walk to reach. The window is sticky so a program that
stops naming a unit does not silently stop describing it.
`ImageEmit.AZeroHighWaterMarkEmitsNothingWithoutHashing` pins it **with an image really bound**.
**D8 — the unit→target resolution is INVERTED once per program, not searched per unit.**
DirectGLES asks it the other way round (`sampledTargetForUnit` walks every uniform location for
one unit) and gets away with it because it only asks on an aliasing conflict. Per unit per verb
that would be O(units × locations), which is the per-draw cost the phase's budget forbids.
`MGPipeProgramOpaqueUnits` walks the locations once and memoises on
`(lifetimeId, linkVersion, backendStateVersion)` — the third being the counter
`SetUniformSamplerOrImageUnitIndex` bumps, i.e. the one thing that moves a uniform's unit
without a relink. First writer wins on a shared unit, which is DirectGLES' arbitration read
forwards. **One instance shared by the sampler and image emitters**, so the two halves cannot
be resolved against two different readings of one program.
**D9 — the sampler CSO cache's capacity is a `static_assert`ed safety bound, not only a size.**
`static_assert(kMGPipeSamplerCsoCacheCapacity > kMGPipeMaxTextureUnits)`.
**D10 — nothing in C's `Reset()` paths touches an object record.** D-J4 is obeyed literally:
`MGPipeSamplerEmitter::Reset()` invalidates only the per-context opaque-unit memo,
`MGPipeImageEmitter::Reset()` only the window, `MGPipeProgramEmitter::Reset()` only the three
bound-handle mirrors and the global-constants key, and the CSO cache and the two record halves
(`RecordIsPublished`) are **not** reset — re-publishing a record the applier still holds would
move its `Serial` for nothing. The cache's `ResetForTest()` is named for what it is.
**D11 — the trace fixtures in this worktree were LFS pointers.** The integrator's 12:24 reset
to the tag pulled `tools/trace_replay/fixtures` back to 131/133-byte pointers, and the first
retrace run reported `passed 2 / 79` with `ssim=None` — the exact false red `MEASUREMENTS.md:413`
names. Restored from `~/w7/pipe/tools/trace_replay/fixtures` (7.7 MB → 803 MB) and re-hidden with
`git ls-files … | xargs git update-index --assume-unchanged`; `git status` clean, 0 files under
1 KB remain. **Every other P4a worktree that was reset at 12:24 is in the same state and must be
checked before its retrace verdict is believed.**
**D12 — `~/w7/p4a-trees2.log` never received `REBUILT clientsp`.** The file was created empty at
12:25 and no build, cmake or `wsl_tree.sh` process was ever running. Before the first build C
confirmed no build process was active in the shared trees and built `build-{linux,push,verify}`
itself; `build-linux` needed 2 targets, so the 11:32 build was already valid.
**D13 — six test names beyond C.2's list, additions only** (G14 is about removals):
`SamplerEmit.AHashCollisionDoesNotAliasTwoSamplerStates`,
`ImageEmit.TheApplicationsFormatAndAccessTravelUnrecast`,
`ProgramEmit.{TheDrawAndDispatchProgramsAreTwoIndependentSlots, AnUnchangedProgramEmitsNothingAtAll}`,
`CompositeResolver.{ASignatureThatHasNotMovedReusesOneComposite, DestructionThenEvictionFreesTheSlotExactlyOnce}`.
**D14 — cases assert on the emitter's counters, not on a direct call's return value**, wherever
a GL entry point in the fixture already reached the validate point and emitted (D2).
`SamplerEmitTest` also shares ONE process-wide `MobileGL::Initialize()` context rather than
`VertexInputEmitTest`'s per-case fresh `GLContext`, because half its cases need a really linked
program and glslang lives behind that call; each case uses GL names of its own.
**D15 — `ProgramEmit.TheNeverUploadedSentinelIsNeverEmitted` pins the PREDICATE.** Driving
`GetUBOContentVersion()` to `~0u` takes four billion `MarkUBOContentDirty` calls, which is not a
test. `MGPipeGlobalConstantsVersionIsEmittable` is what `EmitGlobalConstants` consults, so
pinning it pins the behaviour and deleting the guard is a compile error in the case; the case
additionally asserts that the live path's last record carries an emittable version.
---
## 8. What must be re-run after the rebase onto `wire` + `clientfb`
Ordered by risk, highest first.
1. **`MGPTextureParams::BuiltinSampler` must be non-null on every `set_texture_params`** — the
applier makes a null there `Fatal{ProtocolCorruption}`. Package B's `TextureEmit.h` gets that
handle from **C's seam**, `MGPipeSamplerCsoCacheInstance().Acquire(texture.GetSamplerObject()->GetAllSamplerParameters(), bytes)`
in `MG_Impl/Pipe/SamplerEmit.h`. If B minted it any other way, or not at all, every texture
will trip that Fatal the moment `wire` lands. **Check this before anything else.**
2. **Deviation D3's one-line fill-in** in each of the six `PipeFill.cpp` death helpers, then
re-run `ctest -R 'HandleRecycle'` and G8b's leak cases: `delete_sampler_view` and
`delete_shader_state` only start going out once `published` is asked rather than assumed.
3. `ctest --test-dir build-push -R 'SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.'`
— on this branch every applier entry point is a stub, so **no case has yet exercised a real
applier**: the `Start + Count` bounds gate, the record lifecycle, the refusal counters and the
verify build's program-archive round trip in `MGPipeApplyCreateShaderState` all come alive
with `wire`.
4. The full transcript of §5, in order — three builds, G1, the three generators, the closure
probe, `p3a_untouched_regions.sh`, unit ×3, the name parity pair, the three integration-gpu
arms, integration-verify under `GLIBC_TUNABLES`, and the retrace gate.
5. `MOBILEGL_PIPE_PUSH=0x9ff` (samplers set, texture resources clear) once package D's
`ResolveSamplerSubsystemArm` exists — C emits `MGPBoundView::Texture` and `MGPImageView::Res`
as `Texture` handles unconditionally, which is precisely the arm D-K2 says must be refused
and logged rather than half-run.
6. The retrace corpus, **after checking the fixtures are not LFS pointers** (D11).
@@ -0,0 +1,370 @@
# P4a package C — `clientsp`. Rework result, v2
Branch `refs/heads/p4a/clientsp`, head **`00a86d2a`**. **Not pushed.** Working tree clean.
Rebased onto `refs/heads/feat/disaggregated` = **`17db7598`** (c0 + c0b + c0c), then three
rework commits. `git diff --stat 17db7598..HEAD`: **11 files, +3027 / −52**; the rework alone
(`f5c3364c..HEAD`) is **6 files, +695 / −94**.
## 0. Commits
| # | hash | message (exact, single line, no attribution) |
|---|---|---|
| c1' | `2a076438` | `[Feat] (Pipe): content-address sampler states, mint one sampler view per texture and push the three unit sets behind their own content hashes` |
| c2' | `94daf8ed` | `[Feat] (Pipe): publish a program's per-stage SPIR-V and reflection archive as a shader CSO and its default uniform block as global constants` |
| c3' | `a23a07ad` | `[Feat] (Pipe): resolve a program pipeline into one shader CSO out of the reserved composite band and release it exactly once` |
| c4' | `f5c3364c` | `[Test] (Pipe): wire the sampler and program subsystems and pin the padding-proof CSO identity, the program-resolved unit sets, the linked-snapshot stage mask and the composite band's single release` |
| **c5** | **`02475fbb`** | `[Fix] (Pipe): give the sampler family the birth-hook entry points the contract declares, take the publication latch where its creates go out, and reference-count cache entries so an LRU eviction can never take a handle a standing record still names` |
| **c6** | **`5f577d16`** | `[Fix] (Pipe): give the program family its birth-hook entry point and publication latch, invalidate the global-constants key whenever a create_shader_state is re-issued, and count a truncated module tail instead of asserting it` |
| **c7** | **`00a86d2a`** | `[Fix] (Pipe): stop a make-current disarming the composite resolver's release path - the memo's freshness and the slot's release obligation were one flag, so after the first Reset no signature move ever spoke a delete` |
c1'..c4' are the v1 commits replayed; the rebase was **clean, no conflicts** (c0b/c0c touched
`PipeFill.cpp`, `SlotAllocator.*`, `PipeMutation.h`, `MGPipeTypes.h`, `PipeFields.def`,
`PipeCatalogueTest.cpp` and `check_include_closure.py`, none of which C owns or edits).
**The rework is grouped by file pair, so `f5c3364c` and `02475fbb` do not build.** That is not a
new fact: `f5c3364c` sets both wired constants and c0b's `if constexpr` seam then instantiates
forwards to entry points that did not exist, so the branch has not compiled since the rebase.
The tree builds again at **`5f577d16`** (both entry-point commits landed) and at `00a86d2a`.
Splitting the reconciliation out of the two defect fixes would have meant splitting hunks inside
one file; the integrator squashes or merges the branch anyway.
---
## 1. The three majors
### C-M1 — `MGPipeCompositeResolver::Reset()` disarmed the release path → FIXED (`00a86d2a`)
`Live` and the memo's freshness were one flag. `Reset()` cleared it, the reuse branch returned
before anything could restore it, and from the first make-current onwards `ReleaseEntry` saw
`!Live` and returned: no `delete_shader_state`, no `Free`, no counter, and the old composite's
handle overwritten out of the resolver.
Split into two flags, each with exactly one meaning:
* `CompositeResolver.h:181` `Bool Live` — **the release obligation**. Set when the entry takes
responsibility for a composite's slot, cleared **only** by `ReleaseEntry`.
* `CompositeResolver.h:183` `Bool Fresh` — the memo's "does this entry describe the current
context's pipeline of this name". `Reset()` (`:143-145`) clears **only** this; the reuse branch
re-arms it (`:105-113`) and `Observe`'s mint path sets both (`:125`). `HandleFor` (`:151`) now
asks for both, which is the only place `Fresh` is observable.
The reuse branch deliberately does **not** consult `Fresh` before deciding not to release: the
handle is minted off the composite `ProgramObject`'s own lifetime id, so an identical handle *is*
an identical object and there is nothing to release whatever the memo's freshness says. Making
`!Fresh` fall through to `ReleaseEntry` would have emitted a delete for a live composite.
**Case added** (C-m9's gap): `CompositeResolver.ASignatureMoveAfterAMakeCurrentStillReleases
ThroughTheResolver` (`CompositeResolverTest.cpp:346-403`). It drives the release **through the
resolver** — bind a real pipeline, emit, `MGPipeProgramEmitterInstance().Reset()` (the
make-current, which reaches the resolver's `Reset()`), emit again on the unchanged stage set (the
reuse branch), then `glUseProgramStages` a different fragment stage so the signature really moves
— and asserts `Releases == 1` and that the first composite's slot is no longer live. Both existing
"FreesTheSlotExactlyOnce" cases call the death helper directly and never touch the resolver; this
one does not. **Negative control: restoring `entry.Live = false` in `Reset()` turns it red.**
### C-M2 — the `(Cso, Version)` global-constants latch survived a re-issue → FIXED (`5f577d16`)
`ProgramEmit.h:259-271`: on the branch of `AcquireShaderCso` that actually re-issues
`create_shader_state`, `m_constantsCso` is reset to `kMGPipeNullHandle` and `m_constantsVersion`
to `kMGPipeGlobalConstantsNeverUploaded` whenever the re-issued handle is the one the constants
key names. Invalidated rather than re-emitted, because `AcquireShaderCso` has no business deciding
when the constants go out — the next `EmitGlobalConstants` sees an unlatched key and sends them.
Two accessors so a case can see it: `GlobalConstantsCso()` / `GlobalConstantsVersion()`
(`ProgramEmit.h:378-379`).
**Case added**: `ProgramEmit.AReIssuedCreateReSendsTheDefaultUniformBlock`
(`ProgramEmitTest.cpp:318-381`). **Negative control: deleting the four-line invalidation turns it
red.**
**Two corrections to the review's scenario, both written into the case's comment.**
1. *The behavioural half is not the discriminator.* `BumpLinkObservableVersions()`
(`ProgramObject.cpp:346-359`) calls `MarkUBOContentDirty()` beside `++m_linkVersion`, so the
`Version` half of the key moves on its own for the one re-issue trigger that exists today. The
case therefore pins the **mechanism** — after a re-issue the emitter must hold no key at all —
which is the property the contract needs and the half that goes red.
2. *A failed relink does not leave the block populated in this frontend.* `Link()`'s prologue
assigns `m_spirv = {}` (`ProgramObject.cpp:532`), so `globalUboScratch` is empty after **any**
link attempt and `EmitGlobalConstants` early-outs on `GetUBOSize() == 0`. The review's
"the client's scratch still holds the live values" is true of GL and not of this
implementation. The fix is still right and still required — it is what makes any future
re-issue trigger that does not happen to move the content version safe, of which a recycled
slot is one — but the reachable damage today is smaller than the review states.
*Noticed while writing the case, not fixed, recorded for ID-19:* `EmitGlobalConstants` reads
`GetUBOContentVersion()` (`ProgramEmit.h:164`) **before** `GetUBOSize()` (`:168`) joins phase B,
and that join bumps the counter — so the first emission after a link latches a version one behind
the bytes it sent and the next call re-sends identical bytes once. Over-emission, one record per
link, never under-emission. Left alone because reordering the two reads changes when the join
happens on a path the phase has not measured.
### C-M3 — LRU eviction could take a handle a standing record names → FIXED per ID-17 (`02475fbb`)
Reference-counted entries, exactly as ID-17 rules.
| what | where |
|---|---|
| `Uint32 RefCount` on the entry | `SamplerEmit.h:331` |
| `Acquire(params, payloadBytes)` returns a handle **and takes a reference** | `:244-248` → `AcquireCanonical` `:337-359` (`++RefCount` on a hit `:355`, `RefCount = 1` on a mint `:410`) |
| `Release(handle)` drops one; unknown handle or double release is a no-op, never an underflow | `:267-277` |
| LRU considers **unreferenced entries only** | `:367-374` |
| every entry pinned ⇒ mint beyond 256 and count it | `:376-381`, `Counters::OverCapacityMints` `:223` |
| `Evict` asserts its victim is unreferenced | `:434-437` |
| `RefCountOf(handle)` for diagnostics and cases | `:279-286` |
| the reference a **bound sampler state** holds while bound | `EmitSamplerStates` `:751-783`, `m_stateRefs` `:996` |
| that reference released at a make-current (working state, not a record) | `Reset()` `:944-960` |
| the `static_assert` restated | `:207-209` |
The `static_assert` is kept but no longer claims to be what makes eviction safe. Its message now
says what it really guarantees — a cache that could not hold one whole emission pass would
over-capacity-mint on **every** pass — and the header block at `:167-200` states plainly that
correctness against eviction is the reference count.
`EmitSamplerStates`' reconciliation is one extra pass over the 192-entry unit array: `Acquire` has
already taken a reference for every unit in the new set, so a unit whose handle did not move gives
that duplicate back, a unit whose handle moved gives back the one it used to hold, and a unit that
fell outside the window gives back its own. One binding is one reference, not one per pass.
**Three cases added** (`SamplerEmitTest.cpp`):
* `SamplerEmit.AReferencedCsoIsNeverTheLruVictim` (`:526-557`) — a pinned value survives a
miniature CTS sampler sweep (512 distinct unreferenced values through a 256-entry cache), the
LRU really runs (`Evictions > 0`), nothing over-capacity-mints, and re-acquiring the pinned
value is a **hit** and not a re-mint. **Negative control: dropping the `RefCount != 0` skip in
the victim choice turns it red.**
* `SamplerEmit.AFullyPinnedCacheMintsBeyondItsCapacityAndCountsIt` (`:559-586`) — 256 pinned
entries plus one more distinct value: `Size() == 257`, `Evictions == 0`, `OverCapacityMints == 1`.
* `SamplerEmit.ABoundSamplerStateHoldsItsCsoUntilTheUnitMoves` (`:494-524`) — the emitter half:
one binding is one reference across repeated passes, and the reference goes when the unit stops
naming the CSO (released is **not** evicted).
---
## 2. The c0b reconciliation (review §6, items 1–8)
| item | disposition |
|---|---|
| **1. `MGPipeSamplerEmitter::EmitSamplerCso(SamplerObject&)`** | **Added**, `SamplerEmit.h:888-892`. Body is the family's handle rule: `MGPipeSamplerCsoCacheInstance().Acquire(sampler.GetAllSamplerParameters(), bytes)`, then `Release` of the reference it just took — a birth is not a standing record, so pinning the default-parameter entry for the life of the process would buy no reader anything. The comment says what the review asked it to say: minting at construction content-addresses the **default** parameters and the cache dedupes, so it is one `create_sampler_state` per distinct default-valued sampler, not one per object. |
| **2. `MGPipeSamplerEmitter::EmitSamplerView(ITextureObject&)`** | **Added**, `SamplerEmit.h:900-905`. A wrapper over `AcquireSamplerView`, resolving the texture handle exactly as `EmitSamplerViews` does and discarding the byte count. |
| **3. `MGPipeProgramEmitter::EmitShaderCso(ProgramObject&)`** | **Added**, `ProgramEmit.h:292-295`. A wrapper over `AcquireShaderCso`. |
| **4. the publication latch, four call sites** | **All four**, and nothing else. `MGPipeNoteHandlePublished(SamplerCso, cso)` at `SamplerEmit.h:419` (immediately after `MGPipeApplyCreateSamplerState`); `MGPipeNoteHandleUnpublished(SamplerCso, …)` in `Evict` (`:450`) **and** in `ResetForTest` (`:313`); `MGPipeNoteHandlePublished(SamplerViewCso, handle)` at `:855`; `MGPipeNoteHandlePublished(ShaderCso, handle)` at `ProgramEmit.h:255`. Both headers now include `<MG_Pipe/PipeMutation.h>` explicitly (`SamplerEmit.h:47`, `ProgramEmit.h:44`) rather than relying on `CompositeResolver.h` pulling it in. |
| **5. `RecordIsPublished` / `NoteRecordDestroyed` stop being the death path's authority** | Kept, comments rewritten: `SamplerEmit.h:288-293` (the cache's), `:907-916` (the view latch's), `:925-930` (`NoteRecordDestroyed`), `ProgramEmit.h:301-308` and `:317-327`. Each says the death helpers read A's latch, and each says why it stays (the version-first skip is the same latch). The **program emitter's bound-mirror clearing keeps its three lines and gains the "why it self-heals" the review asked for**: the slot's `Gen` moves on reuse, so a stale record latch is refused by `RecordGen == handle.Gen` and the three mirrors hold a handle whose generation can never be handed out again, so the next `EmitShaderState` compares against a different handle and re-binds. Clearing them is the cheaper answer, not the load-bearing one. |
| **6. the sampler CSO has no lifetime-id mapping, and D must be told** | **Sentence in the header**, `SamplerEmit.h:201-205`, and §3 below. |
| **7. two now-false header comments** | **Rewritten.** `SamplerEmit.h:67-83` and `ProgramEmit.h:51-62` both now say the constant **is** part of the emission gate (four conditions in `wants()`, the same pair in `FamilyIsLive`) and is additionally a compile-time contract, and that the runtime A/B is still the mask. |
| **8. `CompositeResolver.TheCompositeBandHasExactlyOneDoor` still passes unchanged** | **Verified**, unchanged and green. |
**The three birth hooks still have no call site, deliberately, and this is the one place the
rework declines what the review implies.** The entry points exist and are instantiated (the build
proves it), but `MGPipeEmitSamplerCsoCreate` / `MGPipeEmitSamplerViewCreate` /
`MGPipeEmitShaderCsoCreate` are called by nothing, so no constructor emits. Reasons, per hook:
* **`MGPipeEmitShaderCsoCreate`** — D-H4 and C.7 put `create_shader_state` at the **validate
point** ("nothing today — `create_shader_state` is emitted from the validate point"). A
construction-time create would publish an empty archive for a program that has never linked and
would force a phase-B join at `glCreateProgram`. Adding it would be a design change, not a
reconciliation.
* **`MGPipeEmitSamplerViewCreate`** — its call site is `TextureObject`'s constructor, which is
**package B's file**, and D-F2 mints the view at first use behind the version-first skip.
* **`MGPipeEmitSamplerCsoCreate`** — the only honest call site is `SamplerObject`'s constructor
(C's file, one line). It is *safe* — the cache dedupes to one record for all default-valued
samplers and the entry point releases its reference — but it is not needed: every consumer of a
sampler CSO acquires it from the cache at the point of use. It would also make
`DirectGLES.cpp:209-214`'s backend-side `SamplerObject(0)` (D-F3's raw-depth-fetch sampler)
emit into the pipe from inside `MG_Backend` during backend init.
**Integrator's call.** If a live birth hook is wanted for this kind, it is one line in
`SamplerObject::SamplerObject` (`MG_State/GLState/SamplerState/SamplerObject.cpp:26`) and C will
add it on request; the entry point behind it is already correct.
---
## 3. THE EXACT API PACKAGE B MUST CALL — quote this
In `MG_Impl/Pipe/TextureEmit.h`, inside `EmitTextureParams`, replacing
`MGPipeSlots().Acquire(MGPipeKind::SamplerCso, sampler->GetLifetimeId())`:
```cpp
#include <MG_Impl/Pipe/SamplerEmit.h> // add to TextureEmit.h's include block
// ... in EmitTextureParams, where MGPTextureParams::BuiltinSampler is filled:
Uint64 samplerBytes = 0;
const MGPipeHandle builtinSampler =
MGPipeSamplerCsoCacheInstance().Acquire(sampler->GetAllSamplerParameters(), samplerBytes);
// ... and, when this texture's params record STOPS naming a previously acquired handle
// (a parameter change that re-acquires, or the texture's own death):
MGPipeSamplerCsoCacheInstance().Release(previousBuiltinSampler);
```
The full seam, all in `namespace MobileGL::MG_Pipe` (no qualification needed inside
`TextureEmit.h`), declared in `MG_Impl/Pipe/SamplerEmit.h`:
```cpp
MGPipeSamplerCsoCache& MGPipeSamplerCsoCacheInstance(); // :469
class MGPipeSamplerCsoCache {
MGPipeHandle Acquire(const SamplerParameters& params, Uint64& payloadBytes); // :244
void Release(MGPipeHandle handle); // :267
Uint32 RefCountOf(MGPipeHandle handle) const; // diagnostics / cases :279
Bool RecordIsPublished(MGPipeHandle handle) const; // :294
SizeT Size() const;
const Counters& GetCounters() const; // Mints/Acquisitions/Hits/Collisions/
// Evictions/Releases/OverCapacityMints
};
```
Types: `ITextureObject::GetSamplerObject()` returns `const SharedPtr<SamplerObject>&`
(`TextureObject.h:34`); `SamplerObject::GetAllSamplerParameters()` returns
`const SamplerParameters&` (`SamplerObject.h:64`). **`Acquire` takes a non-const `Uint64&`**, so B
needs a real lvalue; fold `samplerBytes` into whatever B returns as payload bytes rather than
discarding it, or the `csob-blob` accounting under-reports 100 bytes per mint.
**Four rules B must honour.**
1. **Delete B's own `MGPipeSlots().Acquire(MGPipeKind::SamplerCso, …)` line.** Leaving it mints a
second, record-less slot that `~SamplerObject` then frees.
2. **`Acquire` takes a reference; B owes exactly one `Release` for it.** The reference is what
stops the LRU taking a handle a published `MGPTextureParams` still names — the applier does not
resolve `BuiltinSampler`, and an eviction is not a parameter change, so nothing would refuse
and nothing would re-emit.
3. **Release the previous handle whenever B re-acquires** (the params moved, so the
content-addressed handle moved) **and when the texture's record stops standing**. If B has no
texture-death hook of its own — the texture death helper is A's and does not forward to the
emitter — the pin survives until B's per-texture latch on that slot is overwritten by the next
texture at that slot. That is bounded by the number of live texture slots, not unbounded, and
the over-capacity path handles it; but a real release at texture death is better and cheap if
B's latch already holds the handle.
4. **B's params gate must be keyed on `GetTextureParamsVersion()`**, not on something a
`glSamplerParameter*` write leaves alone — the review of B must check this. `glTexParameter*`
moves both `GetTextureParamsVersion()` and `BumpSamplingResolutionGeneration()`
(`TextureObject.cpp:53`); `glSamplerParameter*` goes through `SamplerObject.cpp:65`.
**Include closure re-run after the seam is added is B's**, but C re-ran the gate on this tree with
the new flag: `--mode both --compiler clang++ --self-test --require-all --expect-probes 4` → rc 0,
4 probes, 0 skipped, 0 problems, 6 negative controls tripped.
**And the sentence for D** (`SamplerEmit.h:201-205`): a content-addressed sampler CSO has **no
lifetime-id mapping**, so `NotifyStateObjectDestroyed(SamplerCso, lifetimeId)` arrives from
`~SamplerObject` with **no handle behind it, every time**. A backend must not key a sampler twin on
a `SamplerObject`'s lifetime id; the twin's life is `create_sampler_state` → the LRU's
`delete_sampler_state` and nothing else.
---
## 4. The ten minors and the two nits
| # | disposition |
|---|---|
| **C-m1** dispatch-through-a-pipeline window | **Declared, not taken.** Closing it means keying the image window and `EmitGlobalConstants` on `GetProgramForDispatch()` as well as `GetProgramForDraw()`, which changes what `set_shader_images` describes for an ordinary graphics draw too (the union of two programs' windows) and needs a dirty-bit shutter that can see the dispatch program — `Tracker.h`, A's file for the phase. Reach: compute through a **program pipeline** only, which no fixture in the phase exercises. Recorded for the integrator. |
| **C-m2** no version-first skip in front of the CSO acquire | **Declared, ID-19 budget item.** The refcount reconciliation adds one more pass over the unit array per firing of bit 13, so the cost the review measured grew rather than shrank. The latch that closes it is, per unit, `(sampler lifetime id, ctx.GetSamplingResolutionGeneration())` — and it is now **sound**, which it was not before: a bound CSO's handle cannot move under the reference count. Not taken in this round to keep the change surface auditable. **The integrator should record it in `MEASUREMENTS.md` under ID-19** — `docs/` is not C's file. |
| **C-m3** the collision branch's second eviction path | **TAKEN**, `SamplerEmit.h:337-359`. On a memcmp rejection the probe now **counts the collision and keeps going** instead of evicting and giving up. Both halves close at once: there is no second eviction path for the reference count to police, and a later entry with the same hash whose bytes really do match is found instead of a duplicate being minted. |
| **C-m4** dead `Forget()`, recyclable key | **TAKEN**: `Forget()` deleted. The key-recycling reason is written into the `Entry` comment (`CompositeResolver.h:164-175`) — a `ProgramPipelineObject` has **no lifetime id** (`ComputeDrawProgramSignature` reads the *stage* programs' ids), so `GetExternalIndex()` is the only available key; a recreated pipeline name inherits the entry, the first `Observe` finds a mismatched signature and releases it, and that release resolves nothing because the allocator erases the lifetime-id mapping on `Free`. It costs one redundant, idempotent death notice — the same shape the composite's own second release path already has. |
| **C-m5** one-entry `MGPipeProgramOpaqueUnits` memo | **Declared, not taken.** A two-entry memo would fix it without giving up the shared instance, and it is the same object C-m1 would have to widen; both belong in one change with a measurement behind it. Perf only. |
| **C-m6** compiled-out `MOBILEGL_ASSERT` on the module count | **TAKEN**, `ProgramEmit.h:233-240`. The assert is gone; `m_moduleTruncations` counts it and `TruncatedModuleCount()` (`:382`) reports it — D-J3's counted refusal, not an assertion that vanishes at INFO. |
| **C-m7** `ARedundantRebindOfTheSameSamplerEmitsNothing` has no `EmitterScope` | **REFUTED.** The case has had one since v1 — `SamplerEmitTest.cpp:459`, the first line of the body. Nothing to fix; a sentence was added saying why the scope is load-bearing. The case also now clears the sampler it bound to unit 2 on the way out, so it cannot leak state into the new reference-count cases. |
| **C-m8** the collision case cannot go red for its name | **TAKEN**, and closed with the `#if`-free test seam the review named as the honest option: `MGPipeSamplerCsoCache::AcquireWithForcedHashForTest(params, forcedHash, payloadBytes)` (`SamplerEmit.h:256-262`) puts two genuinely different values on one hash. `AHashCollisionDoesNotAliasTwoSamplerStates` (`SamplerEmitTest.cpp:290-328`) now asserts the two handles differ, `Collisions == 1`, `Mints == 2`, and — the part the old body could not reach — that the probe **keeps going past the rejected entry** so re-asking for the first value is a hit rather than a third mint. It keeps the one-ULP half as the ordinary-path control. **Negative control: deleting the `memcmp` confirm turns it red.** |
| **C-m9** no case drives the resolver's own release | **TAKEN** — see C-M1's new case. |
| **C-m10** no DirectVulkan arm for the leak cases | **Not C's.** contract-v2 §4.3 assigns the leak cases to package F. The integrator must confirm F's G8b cases run on the DV lane rather than assume it. Recorded, unchanged. |
| **n1** `Evict`'s copy-assignment does not carry padding | **TAKEN**, `SamplerEmit.h:452-458`: the sentence the review asked for, saying the assignment is safe only because every entry's padding was already zeroed by `Mint`'s `memcpy` and `Vector` growth memmoves a trivially copyable type. |
| **n2** `SanityTest.cpp:3898` is a second producer of external index 0 | **Not C's file** (D's). Recorded here so D is told; harmless, it never reaches the emitter, but it is a second producer of the value D5's discriminator reads. |
---
## 5. Negative controls (each patch applied, built, run, reverted)
| control | case | result |
|---|---|---|
| `Reset()` clears `Live` again | `CompositeResolver.ASignatureMoveAfterAMakeCurrentStillReleasesThroughTheResolver` | **red** |
| the constants-key invalidation deleted | `ProgramEmit.AReIssuedCreateReSendsTheDefaultUniformBlock` | **red** |
| the LRU stops skipping pinned entries | `SamplerEmit.AReferencedCsoIsNeverTheLruVictim` | **red** |
| the `memcmp` confirm deleted | `SamplerEmit.AHashCollisionDoesNotAliasTwoSamplerStates` | **red** |
All four reverted; tree clean, rebuild rc 0, all 34 emit cases green again.
---
## 6. Gate numbers (head `00a86d2a`, working tree clean)
| gate | result |
|---|---|
| three builds (pull `build-linux` / push `build-push` / verify `build-verify`), `-j 8`, `CCACHE_BASEDIR=/home/swung/w7` | rc 0 / rc 0 / rc 0 |
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` | **0 added / 0 removed / 0 resized / 0 renamed.** `.text` 10806323 → 10806323 (+0, +0.000%), 27811 → 27811 defined symbols. rc 0 |
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 (7 negative controls tripped); 71 calls, 72 verify payloads, 63 PipeInputs fields, 69 verbs, 477 inventory rows, 0 UNMAPPED |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0; 79 mutators all mapped, 0 COARSE, **2 UNDECIDED** (the contract's D6, unchanged) |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all --expect-probes 4` | rc 0, **4 probes**, 0 skipped, 0 problems, 6 negative controls tripped |
| `scripts/p3a_untouched_regions.sh 37da3c3a HEAD` | **rc 0**, the eleven byte-identical |
| `ctest -L unit -j 8`, `build-linux` | **100% passed, 0 failed out of 1668** |
| `ctest -L unit -j 8`, `build-push` | **100% passed, 0 failed out of 1668** |
| `ctest -L unit -j 8`, `build-verify` | **100% passed, 0 failed out of 1668** |
| ctest names pull == push | `diff` empty, **2634 == 2634** |
| no baseline name removed (`comm -23` vs `~/w7/p4a-before-ctest-names.txt`, sorted) | **0 removed**; **46 added** (2588 → 2634) = 13 c0 + 1 c0b + 2 c0c + 25 C v1 + **5 C v2** |
| the emit suites, `build-push`, `-R 'SamplerEmit\.\|ImageEmit\.\|ProgramEmit\.\|CompositeResolver\.'` | **100% passed, 34/34** (29 at v1 + 5 new) |
| `ctest --test-dir build-push -L integration-gpu -R DirectGLES -j 8`, default arm | **100% passed, 0 failed out of 491** |
| same, `MOBILEGL_PIPE_PUSH=0x1ff` | **100% passed, 0 failed out of 491** |
| `ctest --test-dir build-push -L integration-gpu -j 8` (whole label), default arm | **100% passed, 0 failed out of 966** |
| `ctest --test-dir build-verify -L integration-verify -j 4` under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` | **100% passed, 0 failed out of 844**; `grep -c 'Fatal{'` = **0** |
| `python3 ~/w7/retrace_gate.py --tree /home/swung/w7/p4a-clientsp --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p4a-clientsp-v2 -j 4` | **passed 79 / 79**, failed: `[]`, rc 0; 0 logs contain `Fatal{`; every case reported a real `ssim` (1.0 / 0.999x), never `None` |
**The LFS precondition, stated exactly.** `git lfs checkout` in this worktree prints
`Cannot checkout LFS objects, Git LFS is not installed` — `/usr/sbin/git-lfs` (3.7.1) exists but
`git lfs install` has never configured the smudge filter for this user. It does not matter here:
the fixtures are **already real files**, restored from `~/w7/pipe` by C's v1 (deviation D11) and
hidden with `--assume-unchanged`. Measured before the retrace: **94 files, 803 MB,
`find … -size -1k | wc -l` = 0**, `git status --porcelain` empty. The retrace's per-case
`ssim=1.0` confirms it read real archives rather than the `ssim=None` false red.
---
## 7. c0d, and the two cross-package under-fires (review step 7)
**c0d exists but is NOT on this branch's base.** `refs/heads/p4a/contract` is at **`9ea44389`**
(`[Fix, Test] (Pipe): widen the two shutters that cannot see their own subject rather than gate
their emitters on a second bit …`), which is exactly C-M4 and C-M5. `refs/heads/feat/disaggregated`
is still `17db7598`, and the instruction was to rebase onto that and not to wait. So:
* **C-M4** (`glBindSampler` moves bit 12's generation, not bit 13's, so `bind_sampler_states`
never fires for a sampler bind) and **C-M5** (bits 6/7/8 read `GetCurrentProgram()`, null for
the whole life of a bound separable pipeline, so a re-composited pipeline never gets a
`ShaderCso` handle) are **contract defects in `Tracker.h`, not C's**, and c0d has taken them.
* **Nothing was re-run against c0d**, because it is not on this branch's base. C's unit cases are
indifferent to it by construction — they drive the emitters directly and never go through the
dirty walk — but the `integration-gpu` arms are not: with the shutters widened,
`bind_sampler_states` and the whole program family fire in cases where they previously did not,
which is new emission traffic through C's code on the default and `0x1ff` arms.
* **The integrator must re-run, after rebasing this branch onto a `feat/disaggregated` that
carries c0d**: the three `integration-gpu` arms, `integration-verify`, and the emit suites; and
the sampler-bind and SSO scenarios named in review §10.6 (`ProgramPipelineScenario`'s sixteen
cases, and any scenario that rebinds a *different* sampler object to a unit) are the only things
that can see C-M4/C-M5 at all.
---
## 8. What the integrator must re-run
1. **§3 first, before anything else** — B's rework must take `BuiltinSampler` from
`MGPipeSamplerCsoCacheInstance().Acquire(...)`, hold the reference, and delete its own
`MGPipeSlots().Acquire(SamplerCso, …)`. With `wire` underneath, a null or a stale
`BuiltinSampler` is `Fatal{ProtocolCorruption}` on **every** `set_texture_params`. Check B's
texture cases show the handle coming from the cache, and that `grep -c 'Fatal{'` on an
`integration-verify` run stays 0.
2. **Rebase onto a `feat/disaggregated` that carries c0d (`9ea44389`)** and re-run §6 in full —
§7 says why the `integration-gpu` arms in particular are not carried over.
3. `ctest --test-dir build-push -R 'SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.'`
**with `wire` underneath**: on this branch every applier entry point is still a stub, so the
`Start + Count` bounds Fatal, the `Parameters.Size` Fatal, the `link`/`spirv` non-null Fatal,
the composite band's table split and the verify build's program-archive round trip all come
alive for the first time.
4. **A DirectVulkan arm for the death/leak cases** (ID-8, C-m10) — confirm F's G8b cases really
run there, or say explicitly that they do not.
5. **After `esprytobj` + `esprytdraw`**: `MOBILEGL_PIPE_PUSH=0x5ff` / `0x9ff` (bit 10 without bit
11) must be **refused at D's texture-family `Resolve*SubsystemArm`** and logged, never
half-run — C emits `MGPBoundView::Texture` and `MGPImageView::Res` as `Texture` handles
unconditionally (`SamplerEmit.h:721`, `ImageEmit.h:97-99`), and ID-15 makes bit 10 require
bit 11.
6. **The two open items C declined and named**: whether `MGPipeEmitSamplerCsoCreate` gets a call
site in `SamplerObject`'s constructor (§2, one line, C will add it on request), and
`MEASUREMENTS.md`'s ID-19 entry for C-m2 (the per-unit acquire latch) and for the one extra
`set_global_constants` per link noted in C-M2.
7. `retrace_gate.py` **after** confirming `tools/trace_replay/fixtures` are not LFS pointers —
the false red is `passed 2 / 79` with `ssim=None`.
@@ -0,0 +1,374 @@
# P4a package C — `clientsp`. Rework result, v3
Branch `refs/heads/p4a/clientsp`, head **`92dffb81`**. **Not pushed.** Working tree clean.
Rebased onto `refs/heads/feat/disaggregated` = **`712c9467`** (c0 + c0b + c0c + c0d + c0e + wire),
then four v3 commits. `git diff --stat 712c9467..HEAD`: **11 files, +3398 / −68**; the v3 work
alone (`820d1a60..HEAD`) is **6 files, +448 / −55**.
The v2 re-review's verdict was REWORK on **one major (C2-M1), three minors and three nits**. All
seven are closed; the rebase turned up **one further defect of its own** (§2.4), fixed in the same
round.
---
## 0. Commits
| # | hash | message (exact, single line, no attribution) |
|---|---|---|
| c1'' | `1534cf37` | `[Feat] (Pipe): content-address sampler states, mint one sampler view per texture and push the three unit sets behind their own content hashes` |
| c2'' | `5a3e9f08` | `[Feat] (Pipe): publish a program's per-stage SPIR-V and reflection archive as a shader CSO and its default uniform block as global constants` |
| c3'' | `bc2aad21` | `[Feat] (Pipe): resolve a program pipeline into one shader CSO out of the reserved composite band and release it exactly once` |
| c4'' | `ccde2906` | `[Test] (Pipe): wire the sampler and program subsystems and pin the padding-proof CSO identity, the program-resolved unit sets, the linked-snapshot stage mask and the composite band's single release` |
| c5' | `b2edca27` | `[Fix] (Pipe): give the sampler family the birth-hook entry points the contract declares, take the publication latch where its creates go out, and reference-count cache entries so an LRU eviction can never take a handle a standing record still names` |
| c6' | `f0f8cab6` | `[Fix] (Pipe): give the program family its birth-hook entry point and publication latch, invalidate the global-constants key whenever a create_shader_state is re-issued, and count a truncated module tail instead of asserting it` |
| c7' | `820d1a60` | `[Fix] (Pipe): stop a make-current disarming the composite resolver's release path - the memo's freshness and the slot's release obligation were one flag, so after the first Reset no signature move ever spoke a delete` |
| **c8** | **`ac09e5b3`** | `[Fix] (Pipe): key the composite resolver's memo on the context as well as the pipeline's GL name - the resolver is a process singleton while GL names are per context, so a make-current released the other context's live composite` |
| **c9** | **`d6e52f75`** | `[Fix] (Pipe): count the sampler cache's unaccountable releases and its referenced evictions rather than asserting them, and state what a shared reference count, an over-capacity cache and the per-unit reconciliation really cost` |
| **c10** | **`79b58198`** | `[Fix, Test] (Pipe): read a forked refusal drive's log from the offset it had instead of unlinking the file - once a case initialises the library the log is already open, so the child was writing into a deleted inode and the parent read nothing` |
| **c11** | **`92dffb81`** | `[Test] (Pipe): drive the sampler cache's two unaccountable-release counters - a handle it never handed out and a second release of a reference only one holder owed` |
c1''..c7'' are v1+v2 replayed. As at v2, **`ccde2906` and `b2edca27` do not build on their own**
(the wired constants and c0b's `if constexpr` seam are set one commit before the entry points
exist); the tree builds again at `f0f8cab6` and at every commit after it. The integrator squashes
or merges the branch anyway.
---
## 1. The rebase onto `712c9467`
Seven commits replayed; **four conflicted, all in `MobileGL/MG_Test/Pipe/`**, and all in the one
replayed commit `ccde2906`. The cause is that the pipe's `ae1a1c50` ("pin every P4a record's
lifecycle…", one of wire's twelve) filled **the same four stub files C owns** with the applier's
half of the same families: `CompositeResolverTest.cpp`, `ImageEmitTest.cpp`,
`ProgramEmitTest.cpp`, `SamplerEmitTest.cpp`. `MG_Impl/Pipe/*` and `MG_State/**` rebased clean —
c0d's `Tracker.h`, c0e's `Named` and wire's `PipeApply.*` are files C does not touch.
**How they were resolved.** Not by hand-picking hunks: both sides are *additions to the same
stub*, so the resolution is a three-way merge that replays each side's insertions at its own base
anchor. A script took `:1`/`:2`/`:3` from the index, computed both opcode lists against the base,
**asserted that no base range is touched by both sides**, and emitted the union in base order
(the applier block first, then C's `#if !MOBILEGL_PIPE_PUSH` pull-skip list and its `#else`
namespace, then `main()`). The overlap assertion passed on all four files. One duplicated
`#include <MG_Pipe/PipeApply.h>` in `CompositeResolverTest.cpp` was removed by hand.
**Nothing of wire's was lost.** Every `TEST(` name present in `712c9467`'s version of the four
files is present at HEAD: 4 / 5 / 7 / 8 wire cases, **0 lost**. The pull-skip `MGL_*_TEST_LIST`
macros carry only C's push-only cases, which is correct — wire's cases compile in both builds and
`GTEST_SKIP()` internally — and G2 (pull and push ctest name sets identical) holds at 2683 == 2683.
---
## 2. C2-M1 — the composite resolver's key
### 2.1 What changed
| what | where |
|---|---|
| `Entry` gains a context half | `CompositeResolver.h:230` `Uint64 ContextId`, beside `:231` `Uint PipelineName` |
| `Find` requires **both** halves | `:242-247` |
| `Observe` takes the context id | `:132-133` `Observe(Uint64 contextId, const ProgramPipelineObject&, const ProgramObject&, MGPipeHandle)` |
| the one production call site supplies it | `ProgramEmit.h:118-126`, inside `EmitShaderState(GLContext& ctx)`: `Observe(ctx.GetTextureContextId(), *pipeline, *drawProgram, drawCso)` |
| `Fresh` and `HandleFor()` deleted | (C2-m1) — see §2.3 |
| `Reset()` reclaims instead of invalidating | `:188-199`, counted by `Counters::Sweeps` `:120` |
| the file header states the key, the identity and the death path | `:42-69` |
The mismatch arm is now reachable only for **this** context's own entry: another context's
pipeline of the same name is not found, therefore not matched and not released, and its obligation
stays owed to the context that took it (`:147-151`).
### 2.2 The context identity, and why this one
**`GLContext::GetTextureContextId()`** (`Core.h:156-159` → `TextureState.h:135-141`,
`TextureState::AllocateContextId`, a process-wide atomic). It is not a new notion:
* it is already **the pipe's** context identity — `PipeFill.cpp:236-237` copies it into
`PipeInputs::m_textureContextId` at seven fill points (`FillPoints.def`, `kDraw` / `kDispatch` /
`kClear` / `kBlitOrCopy` / `kTextureOp` / `kReadback` / `kProgramOp`), and `Coverage.def:229`
describes it in exactly those words: *"a context identity the backend keys its own tables on"*;
* it is what the backend's own per-context memos key on today (`DirectGLES.cpp`'s
`g_observedUnitBindingsContextId`, `g_unitTextureSyncListContextId`, `g_imageSweepContextId`,
`g_unitSamplerWalkContextId`, `Managers.cpp`'s `m_syncedShapeContextId`).
**Deliberately NOT the `GLContext` address**, which is the other candidate in reach —
`MGB_CTX_IDENTITY` (`PipeInputsSwitch.h:21` / `PipeInputs.h:191`) and `MGPipeTracker::m_context`
(`Tracker.h:271`) both compare it. `Core.h:156-158` says why that would be wrong here, in its own
words: *"both restart at 0 in a new context, and a recreated context can land on the old heap
address"* — so an address key would put this same defect back one context destroy-and-recreate
later, with entries of a dead context inherited by its successor.
The id travels as a `Uint64` argument rather than a `const GLContext&` for two reasons: the
resolver keeps its "depends on nothing of the family's" include set (no `Core.h`), and a unit case
can drive two contexts in a process that only ever has one. The header says in capitals that the
argument is `GetTextureContextId()` **and nothing else**, and there is exactly one production
caller.
### 2.3 Where a destroyed context's entries are released — stated
**In `ProgramObject::~ProgramObject`, and nowhere else.** Destroying a `GLContext` drops
`m_programPipelines`, which drops each `ProgramPipelineObject`, which drops the composite it
cached in its one-slot draw-program cache; `~ProgramObject` then runs
`MG_Pipe::MGPipeEmitShaderCsoDestroyAndFree(m_lifetimeId)` (`ProgramObject.cpp:58`) — **D-H7's
second release path** — which emits `delete_shader_state`, drops the publication latch and frees
the band slot, **exactly once**.
The resolver never speaks a second release for such an entry, and could not: no future `Observe`
can carry a dead context id, and `MGPipeSlotAllocator::Free` has already erased the lifetime-id
mapping, so a release would resolve nothing. What the resolver does instead is **drop** the
stranded entry at the next `Reset()` — the make-current, i.e. the one moment
`PipeFill.cpp:2229`'s `FreshlyPrimed` arm tells the client a context boundary was crossed. An
entry is dropped when `!Live` or when `MGPipeSlots().IsLive(ShaderCso, entry.Handle)` is false,
which is precisely "the obligation was discharged elsewhere". This also restores the bound the
name-only key used to have: the vector is now bounded by the (context, pipeline name) pairs whose
composite slot is **actually live**, not by every pair the process ever used.
`Fresh` and `HandleFor()` go with it (**C2-m1**, disposition "give `HandleFor` a caller or delete
it, and say which in the header"): `Fresh` existed only because a name-only key could not tell
"my own entry after a make-current" from "another context's entry", and `HandleFor` was its only
reader and had no caller anywhere in the tree. Both are deleted and `Reset()`'s comment
(`:170-177`) and `Size()`'s (`:203-206`) say so, the latter adding why a `HandleFor(name)`
accessor must not come back.
### 2.4 The cases, and the mutations
Two new cases, both in `CompositeResolverTest.cpp` and both in the pull-skip list:
* **`CompositeResolver.TwoContextsHoldingOnePipelineNameKeepTheirOwnComposites`** (`:660`) — the
reviewer's probe, as a case. Two `ProgramPipelineObject`s built with **the same external index**,
two composites (`MakeShared<ProgramObject>(0u)`, external index 0, the shape `Core.cpp` builds),
two band handles with real `create_shader_state` records and publication latches, then
`Observe(A)` → `MGPipeProgramEmitterInstance().Reset()` (the make-current) → `Observe(B)`.
Asserts `Releases` unmoved, and that **A's slot is still live and still published**; then goes
back to A and asserts the unmoved signature is a `Reuses` and still releases nothing.
It is driven at the resolver because one test process has one `GLContext`; every value it
supplies is what the single production call site supplies.
* **`CompositeResolver.ADestroyedContextsEntryIsDroppedRatherThanReleasedASecondTime`** (`:716`) —
§2.3 as a case: `Observe`, then drop the composite's last `SharedPtr`, and assert the slot went
back exactly once with the latch, that the resolver spoke **no** release, and that the next
`Reset()` drops the stranded entry (`Sweeps + 1`, `Size()` back to where it was, `Releases`
unmoved).
| mutation | case that goes red | result |
|---|---|---|
| `Find` drops the `ContextId` half of the key (v2's key) | `TwoContextsHoldingOnePipelineNameKeepTheirOwnComposites` | **red**, and only that one (11/12) |
| `Reset()` stops reclaiming stranded entries | `ADestroyedContextsEntryIsDroppedRatherThanReleasedASecondTime` | **red**, and only that one (11/12) |
| `Release` stops counting a handle it never handed out | `SamplerEmit.AReleaseThisCacheNeverHandedOutIsCountedRatherThanAbsorbed` | **red**, and only that one (21/22) |
All three applied, built, run and reverted; the tree is clean and 12/12 + 22/22 green again.
---
## 3. The three minors and the three nits
| # | disposition |
|---|---|
| **C2-m1** `HandleFor()` dead, `Fresh` unobservable, `Reset()` a no-op | **TAKEN**, folded into the C2-M1 fix exactly as ruled: both deleted, `Reset()` given a real job (§2.3), and the header says which was chosen and why (`CompositeResolver.h:170-177`, `:203-206`). |
| **C2-m2** `Release` silent on an unknown handle; "a double release is a no-op" is only true when nobody else holds the entry | **TAKEN**, in the counted-refusal idiom C-m6 adopted. `Counters::UnknownReleases` (`SamplerEmit.h:240`) when the probe finds no entry, `Counters::UnderflowedReleases` (`:241`) when the count is already 0, both incremented in `Release` (`:305-320`). The comment above it (`:288-304`) now says in capitals that **the count is per HANDLE, not per holder**, that B's params record and this file's `bind_sampler_states` routinely name the same handle, and that a holder releasing twice therefore *steals another holder's pin* rather than harmlessly repeating itself. New case + mutation (§2.4). |
| **C2-m3** the reconciliation's cost is understated and c0d makes it land far more often | **TAKEN as a code correction**; the `MEASUREMENTS.md` half stays the integrator's (`docs/` is not C's file). `SamplerEmit.h:807-821` now states the real model: each `Release` of a non-null handle is a linear scan of the whole cache beside an `Acquire` probe that is another, so a pass with *K* units holding sampler CSOs costs `2 · K · O(cacheSize)` comparisons — **up to ~98 000 at K = 192 with a full cache, unbounded above that** because the over-capacity path lets the cache grow past 256 — that Minecraft-shaped K is typically 0 and a CTS sampler sweep is the workload with both a large K and a large cache, that **c0d's bit-13 shutter now mixes `GetTextureBindGeneration()` so it runs on every texture bind**, that the set-hash suppressor stops the record but not the two scans, and that C-m2's per-unit latch removes **both**. |
| **C2-n1** `Evict`'s `MOBILEGL_ASSERT` is presented as an ID-17 mechanism but is off in every build that runs | **TAKEN, made a counter** (the reviewer's second option). `Counters::ReferencedEvictions` (`:245`), incremented at `Evict` (`:483-484`); the comment says the sole caller structurally guarantees 0, that the eviction still proceeds (refusing would leave `Mint` without the room it asked for), and why an assert could not carry it. The new case asserts it is 0. |
| **C2-n2** the cache never shrinks after an over-capacity peak | **TAKEN**, one sentence beside `OverCapacityMints` (`:224-232`): read it as *how far the cache permanently grew*, not how often; the size stays at its high-water mark for the life of the process along with that many `SamplerCso` slots and that many applier records; bounded by the peak simultaneous pin count, so memory retention and not a leak. |
| **C2-n3** `AcquireWithForcedHashForTest` is a public production method and §3's "full seam" is not full | **TAKEN**, `:279-285`: the three members a consumer must **not** call are named — `AcquireWithForcedHashForTest`, `ResetForTest` and `ResetCounters` — and the sentence says the class is public because it is header-only, not because all nine members are for callers. B's seam, restated in §5 below, is the other six. |
---
## 4. The defect the rebase itself turned up (`79b58198`)
Not in any review; found by the gate, and it is C's to fix because it exists only where the two
halves meet. **`ctest -L unit` in `build-verify` failed 6 of 1716** immediately after the rebase —
all six of them *wire's* refusal cases, in the four merged files:
```
SamplerEmit.ARecordThatDoesNotDescribeItsOwnParametersIsRefusedNamingTheLength
SamplerEmit.AUnitWindowPastTheMergedUnitSpaceIsRefusedRatherThanTruncated
ImageEmit.AnImageWindowPastTheImageUnitSpaceIsRefusedRatherThanTruncated
ProgramEmit.ACreateWithNoArtefactsAnOversizedBlockOrACorruptSlotIsRefusedNamingTheProgram
ProgramEmit.TheDefaultUniformBlockLandsOnTheProgramsRecordAndTheSentinelIsRefused
CompositeResolver.ASlotAtTheShaderCsoLimitIsRefusedWhileTheLastBandSlotIsNot
```
**Root cause.** `ExpectRefusedNaming`'s poison/verify arm forks a child, expects `SIGABRT` and
then asserts the Fatal line was written to the log. `RunInChild` prepared for that by
`std::filesystem::remove(g_logPath)` before the fork — correct while the library's log file was
still closed, which it was in wire's own files. **C's `main()` calls `MobileGL::Initialize()`**
(its cases need a `GLContext`), and `Log.cpp:63-77` opens the log file with `std::fopen(path,"w")`
once and caches the `FILE*`. `fork()` duplicates it, so after the `remove()` the child wrote its
Fatal line into a **deleted inode** while the parent read a path that no longer existed: the child
aborted correctly (`DiedOfAbort` passed) and `child.Log` was empty, so only the assertion on *what*
it refused failed. It reproduced in `build-verify` only, because the push build's arm reads the log
in-process and never unlinks it; and only in the four files C owns, because they are the only ones
with both `MobileGL::Initialize()` and a forked drive.
**Fix** (all four files, identical): `RunInChild` remembers the log's end (`LogEnd()`,
`SamplerEmitTest.cpp:96`) instead of unlinking the path, and `ReadLog(from)` reads back only what
the child appended (`:133`). The comment at the call site says why the unlink cannot come back.
6/6 go green; `build-verify` unit is 100%.
This is worth the wire reviewer's eye as a **contract between the two halves of these files**: any
future forked drive in `MG_Test/Pipe` must assume the library's log is already open.
---
## 5. The B-facing API — unchanged from v2, with C2-n3's addition
Nothing about B's seam moved in v3. Restated so v2's §3 need not be re-read:
```cpp
#include <MG_Impl/Pipe/SamplerEmit.h> // add to TextureEmit.h's include block
Uint64 samplerBytes = 0;
const MGPipeHandle builtinSampler =
MGPipeSamplerCsoCacheInstance().Acquire(sampler->GetAllSamplerParameters(), samplerBytes);
// ... and, when this texture's params record STOPS naming a previously acquired handle:
MGPipeSamplerCsoCacheInstance().Release(previousBuiltinSampler);
```
The six members that are B's: `Acquire` (`SamplerEmit.h:281`), `Release` (`:305`), `RefCountOf`
(`:322`), `RecordIsPublished` (`:340`), `Size`, `GetCounters` — the counter set has grown to
`Mints / Acquisitions / Hits / Collisions / Evictions / Releases / OverCapacityMints /
UnknownReleases / UnderflowedReleases / ReferencedEvictions`. The three B must **not** call are
`AcquireWithForcedHashForTest`, `ResetForTest` and `ResetCounters` (C2-n3).
The four rules are unchanged, and **C2-m2 sharpens rule 2**: B owes *exactly* one `Release` per
`Acquire`, and a second one now shows up as `UnderflowedReleases` (or `UnknownReleases`) rather
than silently stealing `bind_sampler_states`' pin. B's review has a number to assert on.
---
## 6. Gate numbers (head `92dffb81`, working tree clean)
`CCACHE_BASEDIR=/home/swung/w7`, `-j 8`, `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` exported.
| gate | result |
|---|---|
| three builds (pull `build-linux` / push `build-push` / verify `build-verify`) | rc 0 / rc 0 / rc 0 |
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` | **0 added / 0 removed / 0 resized / 0 renamed**, rc 0. `.text` 10806323 → 10806323 (+0, +0.000%); 27811 → 27811 defined symbols, 27072 normalised names unchanged |
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 (7 negative controls tripped) |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0; **2 UNDECIDED** (the contract's D6, unchanged by c0d); 27 negative controls all tripped |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all --expect-probes 4` | rc 0, **4 probes**, 0 skipped, 0 problems, 6 negative controls tripped |
| `scripts/p3a_untouched_regions.sh 37da3c3a HEAD` | **rc 0**, the eleven byte-identical |
| `ctest -L unit -j 8`, `build-linux` | **100% passed, 0 failed out of 1717** |
| `ctest -L unit -j 8`, `build-push` | **100% passed, 0 failed out of 1717** |
| `ctest -L unit -j 8`, `build-verify` | **100% passed, 0 failed out of 1717** |
| ctest names pull == push | `diff` 0 lines, **2683 == 2683** |
| no baseline name removed (`LC_ALL=C comm -23` vs `~/w7/p4a-before-ctest-names.txt`) | **0 removed**; **+95** (2588 → 2683). Of those 95, 62 are the pipe's own between `37da3c3a` and `712c9467` (ID-28), so **33 are C's** |
| the emit suites, `-R 'SamplerEmit\.\|ImageEmit\.\|ProgramEmit\.\|CompositeResolver\.'` | **57/57** in `build-push`, `build-verify` **and** `build-linux` (all three 100%) |
| `TrackerWalk.*` (A's c0d cases, `build-push`) | **18/18** |
| `ctest --test-dir build-push -L integration-gpu -R DirectGLES -j 8`, **default arm** | **100% passed, 0 failed out of 491**; `grep -c 'Fatal{'` = **0** |
| same, **`MOBILEGL_PIPE_PUSH=0x1ff`** | **100% passed, 0 failed out of 491**; `grep -c 'Fatal{'` = **0** |
| `ctest --test-dir build-push -L integration-gpu -j 8` (whole label), default arm | **100% passed, 0 failed out of 966** |
| `ctest --test-dir build-verify -L integration-verify -j 4` | **100% passed, 0 failed out of 844**; `grep -c 'Fatal{'` = **0** |
| `python3 ~/w7/retrace_gate.py --tree /home/swung/w7/p4a-clientsp --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p4a-clientsp-v3 -j 4` | **passed 79 / 79**, failed `[]`, rc 0; **0** logs with `Fatal{`, **0** with `ssim=None` |
**Measurement points.** The three `integration-gpu` runs, `integration-verify` and the retrace were
measured at `79b58198`. The only change since is `92dffb81`, one unit case in
`MG_Test/Pipe/SamplerEmitTest.cpp`: `build-linux/libMobileGL.so` is **byte-identical** across it
(sha256 prefix `2625db7a19a54d3a` before and after) and G1, `p3a_untouched_regions`, unit ×3, the
emit suites, the name pair and all three static scripts **were** re-run at `92dffb81`. Nothing that
those five lanes exercise changed.
**The LFS precondition, stated exactly.** `git lfs checkout` in this worktree still prints
`Cannot checkout LFS objects, Git LFS is not installed` — `git-lfs` exists but `git lfs install`
has never configured the smudge filter for this user. It does not matter: the fixtures are the
real files restored by C's v1 (deviation D11) and hidden with `--assume-unchanged`. Measured
immediately before the retrace: **94 files, 803 MB, `find … -size -1k | wc -l` = 0**,
`git status --porcelain` empty. Every case reported a real `ssim` (1.0 / 0.999x), never `None`,
so the `passed 2 / 79` false red did not occur.
---
## 7. The c0d / c0e re-run list, and the deltas
The re-review's §9 said the numbers do not carry over from v2 because c0d changes *how often* C's
code is entered: bit 13's shutter now mixes `GetTextureBindGeneration()` (so `EmitSamplerStates`
runs on every texture bind at any unit), and the `else if (pipeline)` arm drives bits 6/7/8/14
under a bound separable pipeline (so `EmitShaderState` and the composite resolver are exercised for
the first time). With c0d **and** wire on the base, everything named was re-run:
| lane | v2 (base `17db7598`, stub applier) | v3 (base `712c9467`, real applier + c0d + c0e) | delta |
|---|---|---|---|
| emit suites, `build-push` | 34 / 34 | **57 / 57** | +23 = 20 wire applier cases + 3 of C's own |
| emit suites, `build-verify` | (not reported apart) | **57 / 57** | — |
| `TrackerWalk.*` | not run (c0d not on base) | **18 / 18** | new |
| `ctest -L unit` ×3 | 1668 | **1717** | +49 |
| ctest names pull == push | 2634 | **2683** | +49 |
| names added vs baseline | +46 | **+95** | +49 (62 pipe − 16 already counted + 3 C) |
| `integration-gpu -R DirectGLES`, default | 491 / 491 | **491 / 491**, 0 Fatal | unchanged |
| `integration-gpu -R DirectGLES`, `0x1ff` | 491 / 491 | **491 / 491**, 0 Fatal | unchanged |
| `integration-gpu`, whole label, default | 966 / 966 | **966 / 966** | unchanged |
| `integration-verify -j 4` | 844 / 844, 0 Fatal | **844 / 844**, 0 Fatal | unchanged |
| retrace | 79 / 79 | **79 / 79**, 0 Fatal, 0 `ssim=None` | unchanged |
| G1 | 0/0/0/0 | **0/0/0/0** | unchanged |
(The emit-suite arithmetic, checked at the source: the four stub files each carried one case at
`17db7598` and carry 4 / 5 / 7 / 8 at `712c9467`, so wire added **20**; C's own three are the two
composite-resolver ones and the sampler release-counter one. 34 + 20 + 3 = 57. The same 46 names
the pipe gained between the two bases plus C's 3 account for the +49 in the unit and name rows.)
**The scenarios the re-review named as the only things that can see the paths c0d opened**, all on
the default arm of `build-push`:
| scenario set | result |
|---|---|
| `-R 'ProgramPipeline'` (the sixteen SSO conformance cases and their siblings) | **22 / 22** |
| `-R 'ImageLoadStoreSso\|RelinkStageSet\|PostLinkAttach'` | **16 / 16** |
| `-R 'IntegerBorderColor\|SampledSetStaleness\|PixelStoreSweep'` (a different sampler object rebound to a unit) | **18 / 18** |
| `-R 'CsoContentAddressing\|ObjectSubsystemControl\|ResourceSubsystemControl'` | **10 / 10** |
**What this means, stated honestly.** On `712c9467` the applier is real but **Espryt is still v1**,
so there are no Espryt handle twins at all: the default arm's shape is *"the client emits, the
server pulls"* — every record C sends lands in `MGPipeApplier()` and is validated there (the
`Start + Count` bounds, the `Parameters.Size` gate, the `link`/`spirv` non-null gate, the composite
band's table split, the verify build's program-archive round trip **all ran for the first time**,
which is what the 6 refusal cases of §4 exercise), while the backend still reads the pulled
`PipeInputs` block for its drawing. So a green `integration-gpu` here proves *the records are
well-formed and nothing the client emits perturbs the pull path*; it cannot yet prove Espryt
consumes them. **No Fatal on any arm, 0 in `integration-verify`, and no refusal counter moved.**
---
## 8. What the integrator must re-run
1. **B's seam first** (§5, ID-14 / ID-17): B takes `BuiltinSampler` from
`MGPipeSamplerCsoCacheInstance().Acquire(...)`, holds the reference, releases the previous
handle on re-acquire and at texture death, and **deletes** its own
`MGPipeSlots().Acquire(SamplerCso, …)`. With wire underneath, a null or stale `BuiltinSampler`
is `Fatal{ProtocolCorruption}` on **every** `set_texture_params`. B's review should now also
check `UnknownReleases == 0 && UnderflowedReleases == 0` after its texture cases — C2-m2 made
that assertable.
2. **`check_include_closure.py … --expect-probes 4` again after B adds `#include
<MG_Impl/Pipe/SamplerEmit.h>` to `TextureEmit.h`** — the probe count moves.
3. **`MEASUREMENTS.md` under ID-19**, which is `docs/` and therefore not C's file: C-m2's per-unit
`(sampler lifetime id, GetSamplingResolutionGeneration())` acquire latch **with the corrected
cost model** (C2-m3 — `2 · K · O(cacheSize)`, not one array walk, and c0d's bit-13 shutter makes
it fire on every texture bind), and the one extra `set_global_constants` per link that C-M2's
case turned up.
4. **The wire reviewer should see §4** — the forked-drive/log-file contract between wire's cases
and C's `MobileGL::Initialize()`. The fix is in C's files; the rule belongs to both halves.
5. **A DirectVulkan arm for the death/leak cases** (ID-8, C-m10) — still F's, still to be confirmed
rather than assumed.
6. **After `esprytobj` + `esprytdraw`**: `MOBILEGL_PIPE_PUSH=0x5ff` / `0x9ff` must be **refused** at
D's texture-family `Resolve*SubsystemArm` (ID-15's fourth D-K2 row), never half-run — C emits
`MGPBoundView::Texture` (`SamplerEmit.h`) and `MGPImageView::Res` (`ImageEmit.h:97-99`) as
`Texture` handles unconditionally.
7. **The open question C named and still declines**: whether `MGPipeEmitSamplerCsoCreate` gets its
one-line call site in `SamplerObject`'s constructor. C's reasons for declining are in
clientsp-v2 §2 and are unchanged; if the answer is no, write it into ID-26 rather than leave it
as a loose end.
8. **`ProgramPipelineScenario` and the sampler-rebind scenarios on the integrated tree once Espryt
v2 lands** — §7 says why a green run here is necessary but not sufficient.
---
## 9. Per-item closure table
| item | ruling | v3 disposition |
|---|---|---|
| **C2-M1** | key `Entry` on (context identity, pipeline name) using the identity the pipe client already uses; say where a destroyed context's entries are released; add the probe as a case + a mutation | **CLOSED** — `GetTextureContextId()`; `~ProgramObject` (§2.3); 2 cases, 2 mutations |
| **C2-m1** | fold into C2-M1: give `HandleFor` a caller or delete it, and say which | **CLOSED** — deleted with `Fresh`, said in the header |
| **C2-m2** | two counters + one sentence | **CLOSED** — `UnknownReleases` / `UnderflowedReleases`, the per-handle-not-per-holder sentence, a case and a mutation |
| **C2-m3** | record the corrected cost model | **CLOSED in code**; the `MEASUREMENTS.md` half is the integrator's (§8.3) |
| **C2-n1** | say so in the report row, or make it a counter | **CLOSED** — made a counter (`ReferencedEvictions`) |
| **C2-n2** | one sentence beside `OverCapacityMints` | **CLOSED** |
| **C2-n3** | tell B the three it must not call | **CLOSED** — in the header and in §5 |
| rebase onto `712c9467` | resolve faithfully | **DONE** — §1, 0 of wire's 24 cases lost, overlap-checked union |
| the forked-drive log defect | not in any review | **FIXED** — §4, `79b58198` |
@@ -0,0 +1,405 @@
# P4a package A `c0` — adversarial review of the contract (`contract-review-v1`)
Reviewed commit `08192d72` (tag `p4a/contract`), parent/base `37da3c3a`, worktree
`/home/swung/w7/p4a-contract` (read-only; nothing was built there). Every finding below was checked by
opening the file at the commit — the whole `git diff 37da3c3a HEAD` (43 files, +3802/−145) plus the
surrounding unchanged code it lands into. No private worktree was needed: every question turned out to
be answerable by reading, and no experiment would have added evidence.
## Verdict
**ACCEPT WITH MAJORS — conditional.** The *payload* layer is right: every enum, constant, struct edit,
field-list row, generated table and entry-point signature I checked matches the B decision it claims,
`c0` is behaviourally inert in both the push and the verify build, and G1's 0/0/0/0 is credible. The
sixteen declared deviations are, with two exceptions, correctly reasoned.
What is **not** right is the *client-facing API surface*: `c0` landed the death half of the MG_State
coupling and none of the birth half, hard-coded the death helpers' answer to a literal `false` with no
hook any package can supply, left the one var-tail apply signature D-D3 needs without its tail, and — in
the one line three documents rest on — did not actually make `kMGPipeWired*Subsystem` gate emission.
**Packages B and C cannot write their emitters against this tag without editing three files C.7 gives A
for the entire phase**, which is precisely the `bb2a236d` merge shape section E claims was discharged
structurally.
Six **majors** and nine **minors** follow. None of them is an ABI change and none needs the tag re-cut
as such — M1, M2 and M3 are additions and a two-line predicate in A's own files — but **M1, M2 and M3
must land, and be announced to all five packages, before B and C write a line of emitter**, and M4/M5
before D, E and F write the twin tables and `PipeSlotPeek`. M6 is the integrator's.
---
## Findings
### M1 (major) — `c0` landed the DEATH half of the MG_State-facing client API and none of the BIRTH half, and the six death helpers answer a literal `false` with no hook a package can supply
`MobileGL/MG_Impl/Pipe/PipeFill.cpp:899-980` (the six helpers), each of which reads
```cpp
const Bool published = false; // the texture emitter publishes nothing yet
```
at `:902`, `:912`, `:935`, `:947` (implicit `return false`), `:961`, `:976`.
Compare P3a's, in the same file, `:833-841`:
```cpp
MGPipeVertexInputEmitter& emitter = MGPipeVertexInputEmitterInstance();
const Bool published = emitter.RecordIsPublished(handle);
if (published) { ... MGPipeApplyDeleteVertexElements(only); emitter.NoteRecordDestroyed(handle); }
```
The five new emit headers expose **only** `Emit*(GLContext&)` and `Reset()`
(`FramebufferEmit.h:138,146`, `TextureEmit.h:1272-1277` of the diff, `SamplerEmit.h`, `ImageEmit.h`,
`ProgramEmit.h`). There is no `RecordIsPublished`, no `NoteRecordDestroyed` and no destroy emitter, so
nothing B or C can add to *their own* header makes any of the six helpers emit a `delete_*`.
The birth side is missing outright. `MG_Pipe/PipeMutation.h` gains exactly the six death declarations
(`:181-201`); the only mint/emit declarations in the file are P3a's buffer ones
(`:115 MGPipeMintResourceHandle(BufferObject&)`, `:203 MGPipeEmitResourceCreate(BufferObject&)`, …).
There is no `MGPipeMintTextureHandle`, no `MGPipeEmitTextureResourceCreate/Respecify/SubData`, no
`MGPipeEmitTextureParams`, no sampler-CSO mint or emit. And that header is the *only* door:
`grep -rn 'MG_Impl/Pipe' MobileGL/MG_State/` is **empty**, and
`scripts/check_include_closure.py:110-112` pins `MobileGL/MG_Pipe/PipeMutation.h` as the
"mutation-header" probe precisely so it stays that way.
**Failure scenario.** D-D1 emits `resource_create` from `TextureObject.cpp:56`'s constructor and
`RenderbufferObject.cpp:28`'s; D-D2 emits `resource_respecify` from
`RenderbufferObject::{SetInternalFormat,AllocateStorage,SetSamples}`; D-E1/D-E3 emit
`set_texture_params` from `TextureObject.cpp:125-179`'s parameter mutators; D-F1 mints a sampler CSO
from `SamplerObject`. All four sites are in `MG_State`, and there is nothing declared for them to call.
B and C then have exactly three options, and all three are forbidden: edit `PipeMutation.h` (A's for
the phase, C.7), edit `PipeFill.cpp` (same, and E's risk table names it as the one file the whole
ownership rule exists to keep single-owner), or include `MG_Impl/Pipe/TextureEmit.h` from `MG_State`
(the closure probe's whole reason). Separately, even once the emitters have bodies, every death helper
still returns `false` and emits nothing, so the applier's records stay `Live` on slots the client has
already handed back — the P3a C-1 shape with the sign flipped, and `PipeSlotPeek`'s client-side leak
cases (G8b) cannot see it because the *slot* is returned correctly.
**Refutations attempted, all failed.**
- *"A's `w1`/`w2`/`w3` fill them in."* Their scope is the applier bodies (C.0), and A physically cannot
call `emitter.RecordIsPublished(handle)` before B and C define those methods — so the fix cannot land
before its consumers, and nothing in C.0 or D.1 schedules an A commit after them.
- *"Only the sub-data drain runs from the client, and that is at the validate point."* D-B1's own table
classifies texture storage, texture params, renderbuffer storage and sampler objects as
**record-only**, emitted "from the GL entry points that cause them" — the wording `TextureEmit.h`
itself uses ("THE THREE OBJECT CALLS ARE NOT EMITTED FROM HERE'S CALLER … they are emitted from
MG_State's own mutators"), which states the requirement and supplies nothing that satisfies it.
- *"C.7's explicit grant of `GL_Texture.cpp` to B covers it."* That grant is one anticipated respecify
call site at `GL_Texture.cpp:528-539`, and it is in `MG_Impl/GLImpl`, not `MG_State`; the constructor
and parameter emissions are not in it.
**Fix (A, on `p4a/contract` or as an announced amendment before B/C start).** (a) Add P4a's birth
declarations to `PipeMutation.h` in the `MGPipeMintResourceHandle` / `MGPipeEmitResourceCreate` shape,
one set per kind, with bodies in `PipeFill.cpp` that delegate to the family emitter — the same
"declaration here, definition there" split P3a used, so no file is touched twice later. (b) Give each of
the five emitter classes `Bool RecordIsPublished(MGPipeHandle) const`, `void NoteRecordDestroyed(MGPipeHandle)`
and its family's destroy emitter, and make the six helpers read the emitter instead of a literal.
### M2 (major) — `MGPipeApplyResourceSubData` has no region tail, so D-D3's texture sub-data record cannot be applied at all
`MG_Pipe/PipeApply.h:585`:
```cpp
void MGPipeApplyResourceSubData(const MGPSubData& record, const void* bytes);
```
and `MG_Pipe/MGPipeTypes.h:850`, in the record that call takes:
```cpp
Uint32 RegionCount; // MGPSubRegion[] in the variable tail
```
There is no second overload anywhere in the tree. Every *other* var-tail call got an explicit tail
parameter in this very commit (`PipeApply.h`, the three unit sets: `const MGPBoundView* tail`,
`const MGPipeHandle* tail`, `const MGPImageView* tail`), so the omission is not a house convention.
**Failure scenario.** D-D3 emits, per dirty `(owner, uploadTarget, level)`, one `ResourceSubData` with
`UnionBox` **and** `RegionCount` + `MGPSubRegion[]`, and D-D5 has the applier accumulate exactly
`(UnionBox, RegionCount, Regions[])` into `MGPipeResourceRecord::PendingUploads` — which `PipeApply.h`
declares (`struct PendingUpload { … Vector<MGPSubRegion> Regions; }`) and which nothing can ever fill,
because the regions never reach the applier. The consequences are the two the brief cares most about:
verify's **retain mode** (part of G4) has nothing to compare, and D-D6's box-vs-rect choice degrades to
"always the union box" — the +6 ms/frame Mali cliff that SSIM is blind to and that the two published
`TextureUpload*` counters exist to expose.
**Refutations attempted.** *"The buffer path proves one pointer is enough."* A buffer sub-data has one
range and encodes it in the box (`MGPipeSetSubDataBufferRange`); the whole point of the texture record
is that it carries a box **and** a disjoint rect list, "由 server 选上传形状". *"`w1` owns it."* Yes —
and that makes it a **post-tag signature change to a function C.6 explicitly tells B and C to assume**,
which C.0 says must not happen without telling the other five packages.
**Fix.** `void MGPipeApplyResourceSubData(const MGPSubData& record, const MGPSubRegion* regions, const void* bytes);`
now, with the buffer call sites passing `nullptr`; or, if A prefers to keep `w1`'s freedom, an explicit
amendment notice naming the new signature.
### M3 (major) — `kMGPipeWired*Subsystem` does not gate emission; six of the seven P4a emitters are live at `c0`, and three documents say otherwise
`MG_Impl/Pipe/PipeFill.cpp:1865-1869`:
```cpp
const auto wants = [&](MGPipeDirty bit) {
const Uint64 subsystem = MGPipeSubsystemForDirty(bit);
return subsystem != 0 && (pushMask & subsystem) != 0 &&
(dirty & MGPipeDirtyBit(bit)) != 0;
};
```
`kMGPipeWiredSubsystems` is **not** one of the three conditions. `ConfigLoader.cpp:257` now defaults
`pushMask` to `kMGPipeSubsystemsMigratedAtP4a` = `0x1fff`, so bits 9-12 are set. Of the seven new
emitters, six are gated by `wants()` alone (`:1924`, `:1927`, `:1937`, `:1940`, `:1943`, `:1946`); only
`DrainTextureSubData` also tests the wired mask (`:1933-1934`).
So `PipeFill.cpp:1920-1923` — *"all four family bits are absent from kMGPipeWiredSubsystems, so
`wants()` is false for every one of them and this whole block is dead"* — is **false**, and so is the
result file's §4.6 *"each family flips its own constant from `0` to its subsystem bit in the commit that
gives its emitters bodies"*. Today `EmitFramebufferState`, `EmitShaderState`, `EmitSamplerViews`,
`EmitSamplerStates`, `EmitShaderImages` and `EmitGlobalConstants` are **called** at every verb whose bit
fires. They are inert only because their bodies `return 0` — so `c0` is still behaviourally neutral, and
this is a wrong contract rather than a behaviour break.
**Failure scenario for a package.** B lands the framebuffer emitter's body in `b1` and flips
`kMGPipeWiredFramebufferSubsystem` in `b3`, believing (as the header comment, `PipeFill.cpp`'s comment
and the result file all tell it) that the constant is the switch. The emitter is live from `b1`, under
the shipped default mask, and every gate run in `b1`/`b2` measures an arm nobody thinks is on. The
mirror error is worse and will cost a debugging day: C gives `TextureEmit.h` a body, forgets the
constant, and sees **nothing** emitted — because the texture drain is the one emitter the constant
really does gate.
**Refutation attempted.** *"P3a had the same shape and it was fine."* It did, but P3a's emitter bodies
and its wired constant were in the same file and the same commit, so the window did not exist. P4a's
whole ownership design puts the body in B/C's header and the OR in A's file, which is what creates it.
**Fix.** Two lines, in A's own file, behaviour-preserving at `c0`: add
`(kMGPipeWiredSubsystems & subsystem) != 0` as a fourth condition of `wants()` (the P2/P3a bits are all
in that mask, so nothing existing changes), and correct the two comments. That makes the constant mean
what `PipeFill.cpp`, the five emit headers and the result file all already claim it means.
### M4 (major) — `MGPipeEmitSamplerViewCsoDestroyAndFree` skips the death notice, and its stated reason is wrong
`MG_Impl/Pipe/PipeFill.cpp:899-908`:
```cpp
// A sampler view has no frontend object of its own - it is minted off the texture's
// lifetime id - so there is no NotifyStateObjectDestroyed for kind SamplerViewCso to
// raise and step 2 is vacuous here. The slot still goes back, last.
if (!MGPipeHandleIsNull(handle)) MGPipeSlots().Free(MGPipeKind::SamplerViewCso, handle);
```
The reason is factually wrong. `MG_State/GLState/StateObjectDeathNotice.h:56-60` is
`NotifyStateObjectDestroyed(MG_Pipe::MGPipeKind kind, Uint64 lifetimeId)` — **one** entry point,
kind-parameterised, deliberately "one entry point for every kind rather than one ops table per kind"
(`:27-28`). `MGPipeHandles.h:34` has `SamplerViewCso`, and the helper's own first line resolves it:
`MGPipeSlots().FindByLifetimeId(MGPipeKind::SamplerViewCso, lifetimeId)` — i.e. the view *is* keyed in
that kind's `ByLifetimeId` map under the texture's id, so `NotifyStateObjectDestroyed(SamplerViewCso,
lifetimeId)` resolves exactly like the other five. Nothing about "no frontend object" prevents the
notice; that is what taking the lifetime id rather than the object was for.
**Failure scenario.** D and E will hold a backend twin per `SamplerViewCso` slot (`SlotTables.h`'s
`BackendSlotTable` shape; `SlotTables.h:38` says "All six re-keyed object classes raise
`NotifyStateObjectDestroyed()`"). With no notice the twin is never dropped: on Espryt it survives until
the slot happens to be recycled and `GetOrCreate(handle)` resets it on a generation change; on
DirectVulkan, which installs no other per-kind free path, it is never dropped at all. That is exactly
the C-1 leak, one kind later, and G8b cannot see it because `PipeSlotPeek` reads the **client**
allocator, where the slot was returned correctly.
**Refutation attempted.** *"It self-heals on reuse."* Only if the slot is reused, and only on a backend
whose handle-keyed `GetOrCreate` resets on a generation change — which is the same overload P3a's
contract review flagged (M2) for adopting a stale generation. D-I1 also states the three-step order is
"fixed and is not a package's choice"; a helper that drops step 2 with a wrong reason is how the rule
erodes.
**Fix.** Raise the notice (one line) and delete the claim; or, if the intent really is that no backend
may keep a `SamplerViewCso` twin, say *that* in `PipeMutation.h:196` and in `SlotTables.h`, because D
and E need the answer before they write the twin tables.
### M5 (major) — `HighWater(ShaderCso)` returns the band top once a composite exists, so G8b's ordinary-ShaderCso leak assertion can no longer go red
`MG_Impl/Pipe/SlotAllocator.cpp:221-231`:
```cpp
if (!state.BandSlots.empty()) {
return static_cast<Uint32>(kMGPipeShaderCsoCompositeSlotBase + state.BandSlots.size());
}
return static_cast<Uint32>(state.Slots.size());
```
The only consumer is `MG_IntegrationTest/Harness/PipeSlotPeek.cpp:37-40`, and the assertion shape G8b
copies is `HandleRecycleScenario.cpp:1080,1091` — `highWaterAfter == highWaterBefore` over `kChurn = 48`
rounds.
**Failure scenario.** `HandleRecycleScenario` runs the dedicated composite case and the ordinary
`ShaderCso` case in one process. From the first composite mint onward, `HighWater(ShaderCso)` is pinned
at `983040 + N`, and no amount of ordinary-slot growth moves it — so the ordinary case's high-water
assertion is vacuously true for the rest of the process. G8b asks for three assertions per kind; one of
them silently stops existing, for the one kind that has two independent release paths.
**Refutation attempted.** *"The live count still catches it."* It catches a *live* leak. The high-water
half exists to catch the other shape — slots freed but the dense table never shrinking, i.e. exactly the
1.3 KB-per-record growth C-1 produced — and D13's own argument for the change ("a leaked composite slot
moves it") is the mirror of what it costs.
**Fix.** Report the two spaces separately: `Uint32 HighWater(MGPipeKind)` keeps meaning the ordinary
space and a `CompositeHighWater()` (or a `HighWater(kind, Band)` overload) answers the band, with
`PipeSlotPeek` growing a seventh member for it. Package F owns `PipeSlotPeek`'s six new members and
needs this decided before it writes them.
### M6 (major, integrator's) — `check_include_closure.py` exits 0 when the compiler is missing, so G13's closure half is a false green
The result file's D16 records this as *"a tooling note for the integrator … not a tree defect"*. It is
a gate that cannot go red, which `ROADMAP.md:7` forbids: the brief's G13 spells
`--compiler clang++-20`, that binary does not exist in this WSL image, and the script prints
`::error::compiler not found` and **still exits 0** with 0 probes run. Every package that runs the gate
command verbatim gets a green it has not earned. `scripts/check_include_closure.py` is owned by nobody
in C.7, so this is the integrator's or F's.
**Fix.** `wsl_p4a_gate.sh` spells `clang++`; the script exits non-zero when the compiler is absent; and
the gate line checks the probe count is 4 rather than only the exit code.
---
### m1 (minor) — the `kMGPipeResourceTargetBuffer` drift `static_assert` is a tautology
`MG_Pipe/MGPipeTypes.h:185-188`: the constant is *defined as*
`static_cast<Uint8>(MGPipeResourceTarget::Buffer)` and then asserted equal to that same expression. It
can never fail. D-A3(a) wanted a guard against two independently written spellings drifting; either give
the constant its literal `0` (so the assert does work) or drop the assert and say the constant is
derived.
### m2 (minor) — `MGPipeApplierReleaseObjectRecords` clears three working handles and not the others
`MG_Pipe/PipeApply.cpp:693-720`. The comment says "the working handles they could name go too", and
`DrawProgram`, `DispatchProgram` and `BoundShaderCso` are nulled — but `DrawFramebuffer` /
`ReadFramebuffer`, whose `MGPSurface::Res` name texture and renderbuffer records just dropped, and the
three unit arrays, whose entries name sampler-view, sampler-CSO and texture handles, are left populated.
Teardown-only, so latent; but the stated rule is applied to half the fields it names, and D/E will read
this function as the definition of "what survives a release".
### m3 (minor) — the texture death helper discards the view helper's answer
`MG_Impl/Pipe/PipeFill.cpp:928`: `MGPipeEmitSamplerViewCsoDestroyAndFree(lifetimeId);` — return value
dropped, and `:930` returns the texture's own `published`. Once both emit, a texture whose
`ResourceDestroy` was suppressed but whose `DeleteSamplerView` went out reports `false` and the legacy
path runs for both.
### m4 (minor) — D5's destructor-ordering claim is not guaranteed
`MG_Impl/Pipe/PipeFill.cpp:316-317` of the diff: *"`~SamplerObject` runs immediately after
`~TextureObjectBase`'s body — a member's destructor follows its owner's body"*. `m_sampler` is a
`SharedPtr<SamplerObject>` (`TextureObject.cpp:57`, `m_sampler = MakeShared<SamplerObject>(0)`), so
anything that took a reference — a texture unit slot, a sampler-view resolution — delays it
arbitrarily. The **conclusion** (do not free the built-in sampler from the texture's lifetime id) is
right and important; the timing claim beside it is not, and D/E must not build an ordering on it.
### m5 (minor) — the archive's byte stream is not canonical
`ProgramArtifactsCodec.cpp`'s `ArchiveMap` and `ArchiveSet` write arms iterate an unordered container,
so two field-equal archives can encode to different bytes.
`ProgramArtifactsCodec.RoundTripsAFullyPopulatedArchive`'s `EXPECT_EQ(reencoded, bytes)` passes only
because a fresh map populated in the same order probes the same way — true today, not a property. Say in
`ProgramArtifactsCodec.h` that the bytes are not a content hash and must not be used as a cache key
(which matters the moment P5 or the program disk cache wants one).
### m6 (minor) — `PipeCatalogue.EveryUnmigratedEmulationIsNamedOnce` cannot fail for the reason it exists
`MG_Test/Pipe/PipeCatalogueTest.cpp`: the case declares a local `kNames[5]` literal and asserts
`std::size(kNames) == 5u` plus pairwise inequality. Nothing compares it to the tree. G13b's real check
is the grep, which lives in a gate script nobody has written yet. Not wrong — but the "red before"
property belongs to F's script, and D and E must plant exactly those five strings verbatim.
### m7 (minor) — `X(BindProgramPipelineObject, kPulledEveryVerb)` is now coupled to a `PipeFill.cpp` arm with nothing checking the coupling
`MG_Pipe/DirtySurface.def` (D7's row) is correct **only while**
`EmittedCallSuppliesTheWholeField(MGPipeInputField::GetProgramForDraw)` is false
(`MG_Impl/Pipe/PipeFill.cpp:1366-1372`). A later phase that flips that arm makes the row silently wrong,
and `--check` cannot see it. One sentence in the row's comment naming the arm it depends on.
### m8 (minor) — the five `TheEmitterIsOneNeverDestroyedProcessSingleton` cases do not test what they are named
They assert `&Instance() == &Instance()`, which a plain function-local static — the thing the rule
forbids — would satisfy identically. The property is real and enforced by construction
(`static X* p = new X();`); the case name promises an observation it does not make.
### m9 (minor) — `FreeCount(ShaderCso)` sums two spaces
`MG_Impl/Pipe/SlotAllocator.cpp:224-228` of the diff returns `FreeList.size() + BandFreeList.size()`, so
a test reading it cannot tell which space a slot returned to. Harmless today; worth a word in the header
beside `HighWater`'s new caveat.
---
## Judgement of the sixteen declared deviations
| # | judgement |
|---|---|
| **D1** five emit headers created by `c0` | **Correct and necessary.** C.0 asks for the wired constant to live in the family header *and* for no file to be touched twice; only creating the headers at `c0` satisfies both. But the *shape* they landed with is incomplete — see **M1** (no publication/destroy hook) and **M3** (the constant does not gate what the header says it gates). |
| **D2** `TexRect` as a thirteenth enumerator | **Correct, and the reason is right.** `TextureEnum.h:10-24` has `TextureRectangle` at `$BASE`, the table may carry no `default:`, and appending after `TexBuffer` preserves every number D-A3 fixes. The second assert (`Tex2D != TexRect`) is real work. The exhaustiveness walk is sound: `Unknown = -1` sits outside `[0, TextureTargetCount)` so the loop cannot trip on it, and both non-targets are listed rather than defaulted. |
| **D3** `kMGPipeResourceTargetBuffer` moved and narrowed to `Uint8` | **Correct.** `MG_Pipe` may not reach into `MG_Impl` and D-A2's predicate lives in `MGPipeTypes.h`. The narrowing is safe (`MGPResourceDesc::Target` is `Uint8`). See **m1**: the drift assert that came with it is vacuous. |
| **D4** no `using` alias in `ResourceTracker.h` | **Correct.** `using MGPipeBindBit = MGPipeBindBit;` is ill-formed, both files are `namespace MobileGL::MG_Pipe`, and `ResourceTracker.h` includes `MGPipeTypes.h`. All twelve enumerators moved verbatim with unchanged values and underlying type; package B's spellings are unchanged. |
| **D5** six helpers; the texture helper does not release the built-in sampler CSO | **The correction is right; one sub-reason is wrong.** `TextureObjectBase`'s constructor really does `MakeShared<SamplerObject>(0)` with its own lifetime id (`TextureObject.cpp:57`), so freeing it from the texture's id would resolve the wrong slot — D-I1's table is genuinely wrong and this fixes it. But the timing claim is unsound (**m4**), and the *view* half of the same deviation skips the death notice on a false premise (**M4**). |
| **D6** `MGP_DIRTY_SURFACE_UNDECIDED_LIST` is not empty | **Correct and honest.** Both rows carry the tool's own reason verbatim, both bit answers are stated and unchanged, and the two directions are both controlled (18 for a stale mark, new 21 for a mark that stops being needed). Widening the taint rule would have been the wrong trade and the file says why. |
| **D7** `BindProgramPipelineObject → kPulledEveryVerb` | **Correct.** The write set (`m_boundProgramPipeline`, `m_everBound`, the two name tables) and bit 6's read set (`m_currentProgram`, `m_lifetimeId`, `m_linkVersion`) are disjoint, the shutter's `GetCurrentProgram()` choice is deliberate, and `GetProgramForDraw` is in the false arm of `EmittedCallSuppliesTheWholeField` so it really is pulled at every verb. See **m7** for the coupling that is now unguarded. |
| **D8** six emitted rows, four deliberate absences | **Correct.** Each absence has a real reason (a selector no call carries; a backend's own keying question; two frontend shutters replaced by a server-owned `Serial` with a different owner), and the two sticky rows are genuinely storage-less. The rows are also `LC_ALL=C`-sorted, which is P3a's `m1` lesson applied. |
| **D9** seven validate-point emitters, not five | **Correct in shape, wrong in its inertness claim.** Seven bits plus a drain need seven call sites, and adding one after the tag would mean touching `PipeFill.cpp` again. The claim that the block is "dead" at `c0` is false — **M3**. The P4a-before-P2/P3a ordering is defensible (5.4 is code organisation, all `set_*` complete before the verb) and inert while every body returns 0. |
| **D10** the default flip is `ConfigLoader.cpp` only | **Correct, verified.** The root `CMakeLists.txt` carries only `option(MOBILEGL_PIPE_PUSH … OFF)` (`:28`) and no numeric default; the itest pins are at `MG_IntegrationTest/CMakeLists.txt:949, 1065, 1070, 1075, 1080, 1149, 1183, 1188, 1219`, which C.7 gives F. See the packages' list below for the consequence nobody has written down. |
| **D11** `TrackerTest.cpp` edited | **Correct.** `Tracker.h` is A's for the phase, the case that pins its map is A's, the name is unchanged (G14), and the added chain assertions (`P4a ⊇ P3a ⊇ P2`) plus the "no bit names the texture-resource subsystem" walk are real work, not padding. |
| **D12** `SixValueStructsHaveFieldLists` 71 → 72 | **Correct.** Name kept (G14), and the case grew the two things that matter: the `borderColorForm` / `borderColorI` / `maxAnisotropy` field naming and the three-padding-byte control written through a byte pointer. |
| **D13** the composite band gets its own dense table | **Right decision, incomplete reason.** The 236 MB/23 MB arithmetic is correct and the two-table split is the right answer; `EntryOf` is a single resolver so a caller cannot forget the band; `Free` routes band slots to `BandFreeList` and `AllocateComposite` pops from it, so the two spaces stay separate and dense; `Reset` clears both. What the reason does **not** say is the cost: making `HighWater` report the band top takes the ordinary `ShaderCso` high-water assertion away — **M5**. It also does not warn consumers that a composite handle passes the `kMGPipeMaxShaderCsoSlots` bound like any other, which is the point at which an applier that forgets the band allocates the 236 MB the allocator just avoided (see the packages' list). |
| **D14** visited-field count is a test, not a `static_assert` | **Correct.** `VisitFields` needs an instance and `LinkArtifacts` carries `std::string`, vectors, maps and a `std::set`, so no constant expression can walk it. `ProgramArtifactsVisitedFieldCount<T>()` plus the 57/8/14/11/20 pins is the honest substitute, and forcing `link.program = nullptr` on every successful decode is the right belt. |
| **D15** one hand-written codec arm | **Correct.** `TUniformInitializer` has no `VisitFields` table, it is a plain aggregate, the arm is flagged in the source, and a type with no table is a compile error in the `else` branch rather than a `memcpy`. The bound-before-allocate rule in `TakeCount` and the trailing-byte refusal are both real and both exercised. |
| **D16** `clang++-20` does not exist | **Correct, and under-rated.** The finding is right; calling it "a tooling note, not a tree defect" understates it — a gate that exits 0 with zero probes is a gate that cannot go red. **M6**. |
---
## What packages B, C, D, E and F must know that the result file does not say
1. **M1, M2, M3, M4, M5 above** — in particular: *do not start writing emitters against the tag's emit
headers until A has landed the birth declarations and the publication hook*, and do not believe
`kMGPipeWired*Subsystem` gates emission today.
2. **Every itest lane is still pinned at `MOBILEGL_PIPE_PUSH=0x1ff`**
(`MG_IntegrationTest/CMakeLists.txt:949, 1065, 1070, 1075, 1080, 1149, 1183, 1188, 1219`) — i.e. P4a's
four subsystems **off**. Until F moves them, B/C/D/E's `integration-gpu` and `integration-verify`
runs exercise the **legacy** arms and will not touch a single P4a emission. A package that reads a
green itest lane as evidence its emitter works is reading the T2 control.
3. **A composite `ShaderCso` handle passes every bound like an ordinary one.**
`kMGPipeMaxShaderCsoSlots == kMGPipeShaderCsoSlotLimit`, so slot 983040 is *in range*. Any applier
body, twin table or peek that indexes by slot must test `MGPipeIsCompositeShaderSlot(slot)` **first**
and use `MGPipeApplierState::CompositeShaderCsos` (or its own band table). Indexing
`ShaderCsos[983040]` grows a ~236 MB vector — the exact defect D13 removed from the allocator and now
the consumer's to avoid. There is no helper for this; write one.
4. **`HighWater(MGPipeKind::ShaderCso)` is not a table size** and is not the ordinary space's high-water
mark once a composite exists (`SlotAllocator.h`'s rewritten comment says the first half, not the
second). Size nothing off it.
5. **`MGPipeVerify(SamplerParameters)` exists but nothing reaches it yet.**
`MGPSamplerDesc::Parameters` is an `MGPBlobRef` (`MGPipeTypes.h:420-424`), not a value, so the new
field-wise comparator only bites when `w2`'s verify path calls it explicitly on the applier's
`MGPipeSamplerCsoRecord::Params`. Assuming "the payload-list row makes verify field-wise
automatically" gets you a byte comparison of a zero-size blob.
6. **Six accessors are deliberately not emitted rows** — `GetActiveTextureUnit`, `GetTextureContextId`,
`GetTextureBindGeneration`, `GetSamplingResolutionGeneration`, and the sticky `GetTextureObject` /
`GetProgramObject`. Those fields keep coming through the residual fill at every verb, so Espryt may
go on reading them; do not "clean them up".
7. **All six new emitted rows land in `EmittedCallSuppliesTheWholeField`'s FALSE arm**
(`PipeFill.cpp:1366-1372`), so *nothing stops being pulled in P4a*. A package that removes a pull
because "there is a Coverage.def row now" breaks the push build's mirrors.
8. **`MGPTextureParams` is 40 bytes with `BuiltinSampler` at +8, and a null `BuiltinSampler` is
`Fatal{ProtocolCorruption}` by contract — but nothing enforces it yet** (the applier is a stub). A
package that forgets to fill it passes every `c0` gate and detonates when `w1`/`w2` land.
9. **`MGPipeApplierReset` advances five new serials and clears the three unit arrays and the two
framebuffer records**; the emitters' `Reset()` is called from `PipeFill.cpp`'s `FreshlyPrimed` block.
Put **only latches** in `Reset()` — a re-publication path there would move a `Serial` for nothing,
and D-J4 forbids one.
10. **`kMGPipeWiredSamplerSubsystem` lives in `SamplerEmit.h` and covers `ImageEmit.h` too.**
`ImageEmit.h` defines no constant of its own; C flips one value for both files.
11. **`CompositeResolver.h` does not exist** — C creates it, header-only, inside `#if MOBILEGL_PIPE_PUSH`
— but `MG_Test/Pipe/CompositeResolverTest.cpp` already exists, is registered, and already owns the
suite name `CompositeResolver` and the case `TheCompositeBandHasExactlyOneDoor`.
12. **Run the closure gate as `--compiler clang++`, and check it reports 4 probes** — `clang++-20` is
absent and the script exits 0 anyway (**M6**).
13. **The five `MGPipeUnmigratedEmulation` names are fixed strings** —
`copy-image-shadow-mirror`, `generate-mipmap-storage`, `generate-mipmap-cpu-fallback`,
`get-tex-image-shadow`, `texture-remint-pull` — pinned as literals in `PipeCatalogueTest`, with no
in-tree check that the call sites match. D and E must spell them exactly.
14. **The six death helpers are currently unreferenced.** The five destructors still call
`NotifyStateObjectDestroyed` directly (`TextureObject.cpp:40`, `RenderbufferObject.cpp:40`,
`FramebufferObject.cpp:36`, `SamplerObject.cpp:39`, `ProgramObject.cpp:43`). B and C **replace** those
single lines — edit, never add a destructor (G1).
@@ -0,0 +1,576 @@
# P4a package A — `c0`, the contract. Result, v1
**Commit `08192d72`** on `refs/heads/p4a/contract`, branched from `feat/disaggregated@37da3c3a`.
**Tag `refs/tags/p4a/contract` → `08192d72`** (both refs exist and are the same object; ID-2's
"spell branch refs `refs/heads/...`" applies from here on). **Not pushed.**
Message, exactly as C.0 specifies, single line, no attribution:
> `[Feat] (Pipe): land the P4a contract - the resource target enum, the framebuffer target byte, the texture params' builtin sampler, the sampler-parameter field table, four subsystem bits, seven dirty arms and the program archive codec`
43 files, +3802 / −145. Working tree clean. `p4a/wire` continues from here; B/C/D/E/F branch from
the tag.
---
## 1. Verdict on the hard rules
| rule | result |
|---|---|
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0` | **0 added / 0 removed / 0 renamed / 0 resized.** The pull `.so` is byte-for-byte the same size as `$BASE`'s (19114360 file, 10806323 `.text`). P4a's admitted-resize set stays EMPTY. |
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 (7 controls tripped, positive control OK) |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` after regeneration | rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0 — **27 negative controls** (was 21), all tripped |
| `check_include_closure.py --mode both --self-test --require-all` | rc 0, 4 probes, 0 problems, 6 controls tripped |
| `p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, the eleven byte-identical |
| three builds compile (pull / push / verify) | all three |
| `ctest -L unit` in all three | **1635/1635 in each**, 0 failed |
| ctest names pull == push | `diff` empty |
| no name removed vs `~/w7/p4a-before-ctest-names.txt` | empty; 13 names added |
| only C.0's files | **no** — 6 deviations, §3 |
| one commit, exact message, no attribution, tagged, not pushed | yes |
---
## 2. Per-file summary
### `MG_Pipe/MGPipeTypes.h` (+247)
- **`enum class MGPipeResourceTarget : Uint8`** with `kMGPipeResourceTargetBuffer` moved in from
`ResourceTracker.h`, the drift `static_assert`, `kMGPipeResourceTargetUnmapped = 0x100`, the
`default:`-less `MGPipeResourceTargetForTextureTarget(TextureTarget)` table, and
`MGPipeEveryTextureTargetIsMapped()`'s `static_assert` (plus a second one pinning that
rectangle ≠ 2D).
- **`enum MGPipeBindBit : Uint16`** moved here verbatim (twelve enumerators + `kMGPipeBindNone`).
- **`MGPResourceDesc`**'s `Target`/`BindMask` comments re-pointed at the two new spellings.
- **`MGPTextureParams` 32 → 40**: `BuiltinSampler` at +8, `SamplerResync` at +26, `Pad0` at +27.
- **`MGPFramebufferState::Pad0` → `Uint8 Target`**, size unchanged at 304, plus
`enum class MGPipeFramebufferTarget : Uint8 {Draw, Read, Both, Count}` and the amended
`Complete` comment (it is `CheckCompleteness()`, never `glCheckFramebufferStatus`'s answer).
- **`kMGPipeMaxColorAttachments = 8`** + its `static_assert` against `kMGMaxDrawBuffers`.
- **`kMGPipeMaxTextureUnits = kMGPipeMaxImageUnits = 192`**.
- **`MGPipeResourceRespecifyNeedsAck` narrowed** to `Immutable != 0 && Target == Buffer`.
### `MG_Pipe/PipeFields.def` (+27)
`F(Target)` on `MGP_FIELDS_MGPFramebufferState`; `F(BuiltinSampler)` + `F(SamplerResync)` on
`MGP_FIELDS_MGPTextureParams`; new `MGP_FIELDS_SamplerParameters` (sixteen members) and
`P(SamplerParameters)` in `MGP_VERIFY_PAYLOAD_LIST` → **72 verified payloads**.
### `MG_Pipe/MGPipe.h` (+33)
Bits 9/10/11/12, `kMGPipeSubsystemsMigratedAtP4a = 0x1fff` with a `static_assert` tying it to the
four bits. `0x7f` and `0x1ff` untouched.
### `MG_Pipe/MGPipeHandles.h` (+11)
Comment only: `AllocateComposite` named as the one door into the composite band, with the
two-release-path note.
### `MG_Pipe/PipeApply.{h,cpp}` (+326 / +123)
Three bounds, three record types, `MGPipeResourceRecord`'s four new members, five new object
tables + the composite table, P4a's working state, `RefusedObjectCalls`, `Reset` /
`ReleaseObjectRecords` extended, **fifteen apply entry points with complete signatures and stub
bodies**, `MGPipeUnmigratedEmulation`. `MGPipeResourceOps` untouched (0 `MG_State` hits inside the
block).
### `MG_Pipe/Coverage.def` (+46)
Six P4a rows in `MGP_COVERAGE_EMITTED_LIST` and the paragraph explaining why those six and not
the other four (§4.7).
### `MG_Pipe/PipeMutation.h` (+60)
Six death-helper declarations with the three-step order written out.
### `MG_Pipe/DirtySurface.def` (+91)
Four new rows, `MarkProgramForDeletion → kExplicitDestroy`, updated reasons on the other two
destroy rows, the `Create*`/`Pop*` exclusion paragraph, and **two `MGP_DIRTY_SURFACE_UNDECIDED_LIST`
entries** (§3, D6).
### `scripts/gen_pipe_dirty_surface.py` (+56)
`MUTATOR_PREFIXES` gains `Use` and `Bind`; six new self-test controls (19, 20a–20d, 21).
### `MG_Impl/Pipe/Tracker.h` (+120)
`kMGPipeDirtyEmittedAtP4a`, seven `MGPipeSubsystemForDirty` arms, bit 11's shutter widened with a
second widened counter `m_readFramebufferBind`, the `SetDrawBuffer` trap recorded, header and bit
comments corrected.
### `MG_Impl/Pipe/SetHashSuppressor.h` (+25)
`SetFramebufferState` appended before `Count`; the three unit slots relabelled `P4a - wired` with
P3b/P4b named as the owner of the backend-debounce deletion.
### `MG_Impl/Pipe/SlotAllocator.{h,cpp}` (+42 / +129)
`AllocateComposite(lifetimeId)`, the band's own free list and slot table, the `EntryOf` resolver,
and `Free`/`IsLive`/`GenOfSlot`/`LifetimeIdOfSlot`/`FindByLifetimeId`/`HighWater`/`FreeCount`/`Reset`
routed through it (§3, D13).
### `MG_Impl/Pipe/PipeFill.{h,cpp}` (+365, `.cpp` only)
Five emit-header includes; six `SubsystemForEmitter` arms; seven pairing `static_assert`s (all
against `SubsystemForEmitter`, never a constant) + the "no dirty bit owns the texture-resource
subsystem" assert + the two texture-unit capacity pins; `kMGPipeWiredSubsystems` as an OR of four
per-family constants with four `0 || own-bit` asserts; six `EmittedCallSuppliesTheWholeField`
false arms; seven stub emitters and the validate-point ladder; the five emitters' `Reset()` on
`FreshlyPrimed`; **six death-helper bodies**.
### `MG_State/GLState/ProgramState/ProgramArtifactsCodec.{h,cpp}` (new, 76 + 303)
The archive serializer. `MG_State/GLState/ProgramState/ProgramArtifacts.h` (+21) gains the
"the serializer now exists" paragraph and its five stale "when one exists" notes updated.
### `MG_Util/Metrics/PipeStats.{h,cpp}` (+32 / +26)
Five `CallClass` members in the existing push block; a **new** push block at the tail of
`ByteClass` carrying `CsoBlobBytes`; both name tables, the short-name table and
`FormatWindowLine`'s new `emit[...]` bracket.
### Tests
`MG_Test/Util/PipeStatsTest.cpp` (+23, six names pinned), `MG_Test/Pipe/PipeCatalogueTest.cpp`
(+200), `MG_Test/Pipe/TrackerTest.cpp` (+42, §3 D11), six new `MG_Test/Pipe/*Test.cpp`
stubs (each with one real shape-pinning case), `MG_Test/Program/ProgramArtifactsCodecTest.cpp`
(+375), and both `CMakeLists.txt`s.
### Build/config
Root `CMakeLists.txt` (+6, `ProgramArtifactsCodec.cpp` inside `if (MOBILEGL_PIPE_PUSH)`),
`MobileGL/Config.h` (+19, the four new bits and their dependencies documented),
`MobileGL/ConfigLoader.cpp` (+12, the push default `kMGPipeSubsystemsMigratedAtP3a` →
`…AtP4a`).
---
## 3. Deviations from the brief, each with its reason
**D1 — five client emit headers are CREATED by `c0`.**
`MG_Impl/Pipe/{FramebufferEmit,TextureEmit,SamplerEmit,ImageEmit,ProgramEmit}.h` are not in C.0's
file table, and C.7 gives the first two to B and the rest to C. They have to exist at `c0`
anyway, because C.0 asks for two things that are only jointly satisfiable if they do: the
validate-point ladder lives in `PipeFill.cpp`, and `kMGPipeWiredSubsystems` is "an OR of four
per-family constants each **defined in its family's emit header**… **with no file touched
twice**". If the emitter bodies stayed in `PipeFill.cpp`, B and C would have to edit that file to
give them bodies — which is exactly what C.7/E forbid. So each header lands with (a) its family's
`kMGPipeWired*Subsystem = 0`, (b) a stub emitter class whose methods return 0, and (c) a
never-destroyed singleton accessor. **B and C replace the class bodies and the constant in their
own headers and never touch `PipeFill.cpp`.** This is the same shape as C.0's six stub test files.
`CompositeResolver.h` is *not* created: nothing at `c0` needs it, and it stays wholly C's.
**D2 — `MGPipeResourceTarget` has THIRTEEN enumerators, not twelve.**
`TexRect` is appended **after** `TexBuffer`, so every value D-A3 names keeps its number.
`MobileGL::TextureTarget::TextureRectangle` exists at `$BASE`, the mapping table may not carry a
`default:` arm, and folding rectangle onto `Tex2D` would erase a distinction the frontend keeps
and both backends switch on (`Managers.h:1246`, `UniformManager.cpp:132/170/1408`,
`VkTextureManager.cpp:2596`, `VkRenderPassManager.cpp:1041`) — while `Tex1D`, which Espryt lowers
to 2D in exactly the same place, still has an enumerator of its own. A second `static_assert` pins
`Tex2D != TexRect` so a later "simplification" is a build break.
**D3 — `kMGPipeResourceTargetBuffer` MOVED to `MGPipeTypes.h` (and narrowed `Uint16` → `Uint8`).**
D-A3(a) implies it stays in `ResourceTracker.h` with a cross-file `static_assert`, but D-A2's
narrowed predicate lives in `MGPipeTypes.h` and spells the constant, and `MG_Pipe` may not reach
into `MG_Impl`. The drift `static_assert` moved with it; `ResourceTracker.h` carries a comment
pointing at the new home. All three existing uses compile unchanged.
**D4 — no `using` alias for `MGPipeBindBit` in `ResourceTracker.h`.**
D-A4 asks for one. It is neither possible nor needed: both files are `namespace
MobileGL::MG_Pipe` and `ResourceTracker.h` includes `MGPipeTypes.h`, so `using MGPipeBindBit =
MGPipeBindBit;` is ill-formed and every existing spelling already resolves. A comment records the
move instead. Package B's code is unchanged either way.
**D5 — six death helpers, one per KIND, and the texture helper does not release the built-in
sampler CSO.**
D-I1's table has six rows but five distinct helper names; the phase mints six *kinds*
(`PipeSlotKind` grows six, G8 has six ABA arms), so there are six helpers, one per kind, all
taking `Uint64 lifetimeId`. The texture helper emits `ResourceDestroy` and then calls
`MGPipeEmitSamplerViewCsoDestroyAndFree(lifetimeId)` — legal because the view is minted off the
texture's own lifetime id (D-F2). It does **not** release the built-in sampler CSO from that same
id: `ITextureObject::m_sampler` is a real `SamplerObject` with its own lifetime id and its own
`#if MOBILEGL_PIPE_PUSH` destructor (`SamplerObject.cpp:30-40`), so freeing it from the texture's
id would resolve the wrong slot — possibly a live one belonging to another object. `~SamplerObject`
runs immediately after `~TextureObjectBase`'s body and takes
`MGPipeEmitSamplerCsoDestroyAndFree`, which is the same helper, the same three-step order, and
idempotent. The three wire calls D-I1's table attributes to a texture's death therefore all still
go out, from two destructors instead of one.
**D6 — `MGP_DIRTY_SURFACE_UNDECIDED_LIST` is NOT empty.**
D-K5 says it stays empty. With the widened prefix set it cannot: `--check` reports both new
bit-answer rows as UNDECIDED, and prints exactly why —
`UseProgram` reaches `DestroyProgramSlot()`, which writes `attachedShaders`, and `BindVertexArray`
reaches a call spelled `Bind(`, which resolves by name to `ImageTextureBinding::Bind` and writes
`Access`; neither is an `m_`-prefixed member, so the write analysis taints both bodies and refuses
to decide. The tool itself offers two options ("widen the analysis or list the row … with this
reason"). Widening the taint rule would weaken the one mechanism that catches a genuine under-fire
and has its own negative control (#9), so the two rows are **marked**, with the tool's own reason
written into the file. Control 18 fails if a mark outlives its reason; new control 21 fails if a
mark stops being needed. Both bit answers themselves are unchanged and correct.
**D7 — `X(BindProgramPipelineObject, kPulledEveryVerb)`, not `NEW_SHADER`.**
D-K5 lists it as `NEW_SHADER`. The derivation refutes that outright (not merely "undecided"): the
mutator writes `m_boundProgramPipeline`, `m_everBound`, `m_programPipelineNames`,
`m_programPipelines`, and bit 6's shutter reads `m_currentProgram` / `m_lifetimeId` /
`m_linkVersion` — disjoint on every path. Nor is that a shutter defect: bit 6 reads
`GetCurrentProgram()` and deliberately not `GetProgramForDraw()`, because the tracker must not
force a compile, and flattening a pipeline into its composite is that compile. What a bind moves
is `GetProgramForDraw`, which is pulled at every verb of every class that reads it, so
`kPulledEveryVerb` is the answer that holds on every path. Recorded verbatim in the row's comment.
**D8 — six `Coverage.def` emitted rows, and four deliberate absences.**
Added: `GetFramebufferBindingSlot → SetFramebufferState`, `GetImageTextureBinding →
SetShaderImages`, `GetTextureUnitObject → SetSamplerViews`, `GetMaxTouchedTextureUnit →
SetSamplerViews`, `GetProgramForDraw → SetDrawProgram`, `GetProgramForDispatch →
SetDispatchProgram`. Deliberately absent, for `GetPixelStoreParameters`' reason (a row is a claim
that the field is supplied, and for these it would be a half-truth): `GetActiveTextureUnit` (no
call carries the active-unit selector), `GetTextureContextId` (a backend's own keying question),
and `GetTextureBindGeneration` / `GetSamplingResolutionGeneration` (frontend *shutters*; what
replaces them server-side is the applier's `Serial`, a different value with a different owner).
`GetTextureObject` and `GetProgramObject` are **sticky** — forwarded, keyed by GL name, no storage
for an emitted call to supply.
**D9 — seven validate-point emitters, not five.**
`EmitFramebufferState`, `EmitShaderState`, `DrainTextureSubData`, `EmitSamplerViews`,
`EmitSamplerStates`, `EmitShaderImages`, `EmitGlobalConstants`. Seven dirty bits plus the texture
sub-data drain need call sites, and adding one after the tag would mean A touching `PipeFill.cpp`
again and telling five packages. The drain is the only one not gated by a dirty bit: its family's
calls dispatch at the GL call that causes them, so it is gated on the subsystem bit alone (and by
`kMGPipeWiredSubsystems`), and an empty drain list costs one test. The P4a block stands **before**
the P2/P3a block, which is ARCHITECTURE.md 5.4's recommended order; that document says in as many
words that the order is code organisation and not a contract, and every P4a emitter is a stub at
`c0`, so the move is inert here.
**D10 — the `0x1ff → 0x1fff` default is `ConfigLoader.cpp` only.**
C.0 and D-K1 say "the push default in `CMakeLists.txt` / `ConfigLoader.cpp:257`". The root
`CMakeLists.txt` carries no numeric push default — only `option(MOBILEGL_PIPE_PUSH … OFF)` — so
there is nothing there to move. The itest phase-mask pins (`0x1ff` → `0x1fff`, and
`0x80000000000001ff` → `0x8000000000001fff`) live in `MobileGL/MG_IntegrationTest/CMakeLists.txt`
at `:949, 1065, 1070, 1075, 1080, 1149, 1183, 1188, 1219`, which C.7 gives to **package F**; they
are untouched here and F owns them.
**D11 — `MG_Test/Pipe/TrackerTest.cpp` is edited.**
C.7 gives it to nobody. `TrackerWalk.OnlyTheFiveEmittedBitsNameASubsystem` compares
`MGPipeSubsystemForDirty` against `kMGPipeDirtyEmittedAtP3a` and goes red the instant `Tracker.h`'s
map grows — which is the gate working. `Tracker.h` is A's for the whole phase, so the case that
pins it is A's too. The test **name is unchanged** (G14). It now compares against
`kMGPipeDirtyEmittedAtP4a`, pins the three phase constants as a chain, pins each of the seven new
arms, and pins that no bit names `kMGPipeSubsystemTextureResources`.
**D12 — `PipeCatalogue.SixValueStructsHaveFieldLists` count 71 → 72.**
Inside A's own file, listed because the case name is now doubly stale and stays: it gained the
`SamplerParameters` verifier plus the padding control that writes garbage into the three trailing
bytes through a byte pointer.
**D13 — the ShaderCso composite band gets its own dense table, in the allocator AND the applier.**
`kMGPipeShaderCsoCompositeSlotBase` is 983040. A single composite in a slot-indexed vector
allocates ~983k `SlotState`s (~23 MB) in the allocator, and ~983k `MGPipeShaderCsoRecord`s
(~236 MB) in the applier — a 236 MB spike on the first program-pipeline draw, which would have
been a defect this commit introduced. Both sides therefore keep the band in a second table indexed
by `slot − base`: `KindState::{BandSlots, BandFreeList}` with a shared `EntryOf(kind, slot)`
resolver, and `MGPipeApplierState::CompositeShaderCsos` beside `ShaderCsos`. Both spaces stay dense
against their own high-water mark, which is the property the allocator exists to give the server.
`HighWater(MGPipeKind::ShaderCso)` still reports the band's top once a composite has been minted,
so a **leaked composite slot moves it** — otherwise G8b's dedicated composite leak case would be
green for ever and mean nothing. `kMGPipeMaxShaderCsoSlots` is still `kMGPipeShaderCsoSlotLimit`,
because a composite slot is a legal slot below that bound. **The server never learns a handle is a
composite**: the split is an indexing detail on the client side of the wire.
**D14 — the "visited field count" guard is a test assertion, not a `static_assert`.**
D-H2 asks for a `static_assert` on the visited field count. `VisitFields` needs an *instance*, and
`LinkArtifacts` carries strings, vectors, maps and a `std::set`, so no constant expression can walk
it. `ProgramArtifactsCodec.h` exposes `ProgramArtifactsVisitedFieldCount<T>()` and
`ProgramArtifactsCodec.TheTablesVisitEveryMemberExceptTheLiveProgram` pins 57 / 8 / 14 / 11 / 20.
`link.program` is additionally forced null on every successful decode.
**D15 — the codec has one hand-written arm.**
`glslang::TIntermediate::TUniformInitializer` (`LinkArtifacts::uniformInitialValues`) has no
`VisitFields` table in `ProgramArtifacts.h`, so the codec cannot reach it through the tables. It is
a plain aggregate (`std::string`, a `TBasicType`, four `int`s, `vector<long long>`,
`vector<double>`) — which is exactly what `ProgramTranslationCache.h`'s audit concluded — and the
codec carries an explicit arm for it, flagged in the source so that a field added there moves the
arm and the format version together. Everything else goes through the tables; a type with no table
is a `static_assert` failure, not a `memcpy`.
**D16 — `check_include_closure.py --compiler clang++-20` does not exist on this box.**
The binary is `clang++` (`/usr/sbin/clang++`); there is no `clang++-20`, and the script prints
`::error::compiler not found` and then still exits 0, which is a false green worth knowing about.
Run with `--compiler clang++`: 4 probes, 0 skipped, 0 problems, 6 controls tripped. A tooling
note for the integrator's `wsl_p4a_gate.sh`, not a tree defect.
---
## 4. The contract itself — what B, C, D, E and F compile against
### 4.1 `MG_Pipe/MGPipeTypes.h`
```cpp
enum class MGPipeResourceTarget : Uint8 {
Buffer = 0, Tex1D, Tex2D, Tex3D, Tex1DArray, Tex2DArray, TexCube, TexCubeArray,
Tex2DMS, Tex2DMSArray, Renderbuffer, TexBuffer, TexRect, Count,
};
inline constexpr Uint8 kMGPipeResourceTargetBuffer = 0; // moved from ResourceTracker.h
inline constexpr Uint32 kMGPipeResourceTargetUnmapped = 0x100u;
constexpr Uint32 MGPipeResourceTargetForTextureTarget(MobileGL::TextureTarget target); // no default: arm
constexpr Bool MGPipeEveryTextureTargetIsMapped();
enum MGPipeBindBit : Uint16 { // moved verbatim from ResourceTracker.h
kMGPipeBindNone = 0, kMGPipeBindVertex = 1u << 0, kMGPipeBindIndex = 1u << 1,
kMGPipeBindConstant = 1u << 2, kMGPipeBindShaderBuffer = 1u << 3, kMGPipeBindIndirect = 1u << 4,
kMGPipeBindSampler = 1u << 5, kMGPipeBindShaderImage = 1u << 6, kMGPipeBindRenderTarget = 1u << 7,
kMGPipeBindDepthStencil = 1u << 8, kMGPipeBindStreamOutput = 1u << 9, kMGPipeBindAtomic = 1u << 10,
kMGPipeBindElementArray = 1u << 11,
};
enum class MGPipeFramebufferTarget : Uint8 { Draw = 0, Read = 1, Both = 2, Count };
inline constexpr Uint32 kMGPipeMaxColorAttachments = 8; // == MobileGL::kMGMaxDrawBuffers
inline constexpr Uint32 kMGPipeMaxTextureUnits = 192; // == TextureState::MAX_TEXTURE_IMAGE_UNITS
inline constexpr Uint32 kMGPipeMaxImageUnits = 192;
struct MGPTextureParams { // 40 bytes (was 32)
MGPipeHandle Res; // 0
MGPipeHandle BuiltinSampler; // 8 kind SamplerCso; kMGPipeNullHandle is ILLEGAL
Uint16 BaseLevel, MaxLevel; // 16
Uint8 Swizzle[4]; // 20
Uint8 DepthStencilMode; // 24
Uint8 ForceResync; // 25
Uint8 SamplerResync; // 26 NEW
Uint8 Pad0; // 27
Float MinLod, MaxLod, LodBias; // 28
};
// MGPFramebufferState: ...Uint8 FixedSampleLocations, IsDefault, Complete; Uint8 Target; Uint32 Pad1;
// Target is MGPipeFramebufferTarget. Size unchanged at 304. Complete is
// FramebufferObject::CheckCompleteness(), NEVER glCheckFramebufferStatus's answer.
inline Bool MGPipeResourceRespecifyNeedsAck(const MGPResourceDesc& desc) {
return desc.Immutable != 0 && desc.Target == kMGPipeResourceTargetBuffer;
}
```
### 4.2 `MG_Pipe/MGPipe.h`
```cpp
inline constexpr Uint64 kMGPipeSubsystemFramebuffer = 1ull << 9;
inline constexpr Uint64 kMGPipeSubsystemTextureResources = 1ull << 10;
inline constexpr Uint64 kMGPipeSubsystemSamplers = 1ull << 11;
inline constexpr Uint64 kMGPipeSubsystemPrograms = 1ull << 12;
inline constexpr Uint64 kMGPipeSubsystemsMigratedAtP4a = 0x1fffull; // 0x7f and 0x1ff untouched
```
Dependencies (diagnosed at first use, never half-run, backend-side): **11 requires 10**,
**9 requires 10**, **10 requires 7**; bit 12 depends on nothing. The mirror pairs are all fine.
Push default is now `kMGPipeSubsystemsMigratedAtP4a` (`ConfigLoader.cpp:257`).
### 4.3 `MG_Pipe/PipeApply.h` — bounds, records, state
```cpp
inline constexpr Uint32 kMGPipeMaxSamplerCsoSlots = 1u << 16;
inline constexpr Uint32 kMGPipeMaxSamplerViewSlots = 1u << 20;
inline constexpr Uint32 kMGPipeMaxShaderCsoSlots = kMGPipeShaderCsoSlotLimit; // 1<<20
struct MGPipeSamplerCsoRecord { Uint32 Gen = 0; Bool Live = false; SamplerParameters Params{}; Uint64 Serial = 0; };
struct MGPipeSamplerViewRecord { Uint32 Gen = 0; Bool Live = false; MGPSamplerView View{}; Uint64 Serial = 0; };
struct MGPipeShaderCsoRecord {
Uint32 Gen = 0; Bool Live = false;
MGPProgramDesc Desc{};
Uint32 GlobalConstantsVersion = ~Uint32{0}; // the "never uploaded" sentinel
Vector<Uint8> GlobalConstants;
Uint64 GlobalConstantsSerial = 0;
Uint64 Serial = 0;
};
// MGPipeResourceRecord gains:
MGPTextureParams Params{}; Uint64 ParamsSerial = 0; MGPipeHandle ViewCso = kMGPipeNullHandle;
struct PendingUpload { Uint16 UploadTarget = 0; Uint16 Level = 0; MGPBox UnionBox{}; Vector<MGPSubRegion> Regions; };
Vector<PendingUpload> PendingUploads;
// MGPipeApplierState gains — OBJECT RECORDS (survive a make-current):
Vector<MGPipeResourceRecord> TextureResources, RenderbufferResources;
Vector<MGPipeSamplerCsoRecord> SamplerCsos;
Vector<MGPipeSamplerViewRecord> SamplerViewCsos;
Vector<MGPipeShaderCsoRecord> ShaderCsos;
Vector<MGPipeShaderCsoRecord> CompositeShaderCsos; // indexed by slot - kMGPipeShaderCsoCompositeSlotBase
Uint64 RefusedObjectCalls = 0;
// WORKING STATE (cleared by MGPipeApplierReset; serials ADVANCE, never zero):
MGPFramebufferState DrawFramebuffer{}, ReadFramebuffer{}; Uint64 FramebufferSerial = 0;
Array<MGPBoundView, kMGPipeMaxTextureUnits> BoundSamplerViews{}; Uint32 SamplerViewStart, SamplerViewCount; Uint64 SamplerViewsSerial;
Array<MGPipeHandle, kMGPipeMaxTextureUnits> BoundSamplerStates{}; Uint32 SamplerStateStart, SamplerStateCount; Uint64 SamplerStatesSerial;
Array<MGPImageView, kMGPipeMaxImageUnits> BoundShaderImages{}; Uint32 ShaderImageStart, ShaderImageCount; Uint64 ShaderImagesSerial;
MGPipeHandle DrawProgram, DispatchProgram, BoundShaderCso; Uint64 ProgramBindingSerial = 0;
```
### 4.4 `MG_Pipe/PipeApply.h` — the fifteen entry points (**stub bodies at `c0`**)
```cpp
void MGPipeApplySetFramebufferState(const MGPFramebufferState& state);
void MGPipeApplyCreateSamplerState(const MGPSamplerDesc& desc, const SamplerParameters* parameters);
void MGPipeApplyDeleteSamplerState(const MGPHandleOnly& handle);
void MGPipeApplyCreateSamplerView(const MGPSamplerView& view);
void MGPipeApplyDeleteSamplerView(const MGPHandleOnly& handle);
void MGPipeApplySetTextureParams(const MGPTextureParams& params);
void MGPipeApplySetSamplerViews(const MGPSamplerViews& hdr, const MGPBoundView* tail);
void MGPipeApplyBindSamplerStates(const MGPSamplerStates& hdr, const MGPipeHandle* tail);
void MGPipeApplySetShaderImages(const MGPShaderImages& hdr, const MGPImageView* tail);
void MGPipeApplyCreateShaderState(const MGPProgramDesc& desc,
const MG_State::GLState::LinkArtifacts* link,
const MG_State::GLState::SpirvArtifacts* spirv);
void MGPipeApplyBindShaderState(const MGPHandleOnly& handle);
void MGPipeApplyDeleteShaderState(const MGPHandleOnly& handle);
void MGPipeApplySetDrawProgram(const MGPHandleOnly& handle);
void MGPipeApplySetDispatchProgram(const MGPHandleOnly& handle);
void MGPipeApplySetGlobalConstants(const MGPGlobalConstants& record, const void* bytes);
void MGPipeUnmigratedEmulation(const char* name); // monolith body: (void)name;
```
`LinkArtifacts` / `SpirvArtifacts` are **forward-declared** in `PipeApply.h`; the header never
reaches a frontend one. `MGPipeResourceOps` is unchanged (nine members).
### 4.5 `MG_Pipe/PipeMutation.h` — the six death helpers
```cpp
Bool MGPipeEmitTextureDestroyAndFree(Uint64 lifetimeId); // ResourceDestroy, then the view helper
Bool MGPipeEmitRenderbufferDestroyAndFree(Uint64 lifetimeId); // ResourceDestroy
Bool MGPipeEmitFramebufferDestroyAndFree(Uint64 lifetimeId); // no wire call at all (D-I2)
Bool MGPipeEmitSamplerCsoDestroyAndFree(Uint64 lifetimeId); // DeleteSamplerState
Bool MGPipeEmitSamplerViewCsoDestroyAndFree(Uint64 lifetimeId); // DeleteSamplerView
Bool MGPipeEmitShaderCsoDestroyAndFree(Uint64 lifetimeId); // DeleteShaderState (composites too)
```
Order inside each, fixed: **wire delete → `NotifyStateObjectDestroyed(kind, lifetimeId)` → slot
free**. Each returns "did the delete go out". At `c0` all six answer `false` (the emitters publish
nothing yet), so the legacy path still runs and the tree is behaviourally unchanged. B and C
replace the bare `NotifyStateObjectDestroyed(...)` in the five existing `#if MOBILEGL_PIPE_PUSH`
destructor bodies with the matching helper call — **edit, never add a destructor** (G1).
### 4.6 `MG_Impl/Pipe/*`
```cpp
// SlotAllocator.h
MGPipeHandle MGPipeSlotAllocator::AllocateComposite(Uint64 lifetimeId); // the ONE door into the band
// SetHashSuppressor.h — the enum is now:
// SetVertexBuffers, SetSamplerViews, BindSamplerStates, SetShaderImages,
// SetShaderBuffers, SetStreamOutputTargets, SetVertexAttribDefaults, SetFramebufferState, Count
// Tracker.h
inline constexpr Uint32 kMGPipeDirtyEmittedAtP4a = kMGPipeDirtyEmittedAtP3a
| NewShader | NewShaderBindings | NewGlobalConstants
| NewFramebuffer | NewSamplerViews | NewSamplers | NewShaderImages; // (bit macros elided)
// bit 11's shutter is now
// Mix(Mix(anyFramebufferAttachmentGeneration, drawBindVersion), readBindVersion)
// the five emit headers, each header-only and inside #if MOBILEGL_PIPE_PUSH:
inline constexpr Uint64 kMGPipeWiredFramebufferSubsystem = 0; // FramebufferEmit.h
inline constexpr Uint64 kMGPipeWiredTextureSubsystem = 0; // TextureEmit.h
inline constexpr Uint64 kMGPipeWiredSamplerSubsystem = 0; // SamplerEmit.h (covers ImageEmit.h)
inline constexpr Uint64 kMGPipeWiredProgramSubsystem = 0; // ProgramEmit.h
class MGPipeFramebufferEmitter { Uint64 EmitFramebufferState(GLContext&); void Reset(); };
class MGPipeTextureEmitter { Uint64 DrainTextureSubData(GLContext&); void Reset(); };
class MGPipeSamplerEmitter { Uint64 EmitSamplerViews(GLContext&); Uint64 EmitSamplerStates(GLContext&); void Reset(); };
class MGPipeImageEmitter { Uint64 EmitShaderImages(GLContext&); void Reset(); };
class MGPipeProgramEmitter { Uint64 EmitShaderState(GLContext&); Uint64 EmitGlobalConstants(GLContext&); void Reset(); };
MGPipe{Framebuffer,Texture,Sampler,Image,Program}EmitterInstance(); // heap-constructed, leaked at exit
```
**B and C own these five headers from the tag on.** Each returns the bytes that went on the wire
(for the per-draw payload histogram) and each family flips its own constant from `0` to its
subsystem bit in the commit that gives its emitters bodies. `PipeFill.cpp` needs no edit for any
of that, and four `static_assert`s refuse a constant that is neither `0` nor its own bit.
### 4.7 `MG_Pipe/Coverage.def`, `PipeFill.cpp`
Six new `MGP_COVERAGE_EMITTED_LIST` rows (§3 D8) → new `MGPipeFieldEmitter` enumerators
`SetFramebufferState`, `SetShaderImages`, `SetSamplerViews`, `SetDrawProgram`,
`SetDispatchProgram`. All six rows are **shape-only**: they land in
`EmittedCallSuppliesTheWholeField`'s **false** arm, so nothing stops being pulled.
### 4.8 `MG_Util/Metrics/PipeStats`
`CallClass` (push-only): `FramebufferEmissions` `framebuffer-emissions` `fbe`,
`SamplerViewEmissions` `sampler-view-emissions` `sve`, `SamplerStateEmissions`
`sampler-state-emissions` `sse`, `ShaderImageEmissions` `shader-image-emissions` `sie`,
`ClientTextureUploadEmissions` `client-tex-upload-emissions` `ctu`.
`ByteClass` (new push-only block): `CsoBlobBytes` `cso-blob-bytes`, short **`csob-blob`** — not
`csob`, which the `cso[...]` bracket already uses for the CSO bind count.
The summary line gains `emit[fbe= sve= sse= sie= ctu=]`.
### 4.9 `ProgramArtifactsCodec`
```cpp
inline constexpr Uint32 kProgramArtifactsCodecVersion = 1;
void EncodeProgramArtifacts(const LinkArtifacts&, const SpirvArtifacts&, Vector<Uint8>& out);
Bool DecodeProgramArtifacts(const Uint8* bytes, SizeT size, LinkArtifacts&, SpirvArtifacts&);
template <class T> SizeT ProgramArtifactsVisitedFieldCount();
```
Header: version word, then a `MGL_LINKARTIFACTS_SIZE` echo (0 where the toolchain is not pinned).
Everything length-prefixed; every count checked against the bytes that remain **before** any
allocation; little-endian asserted. Refuses a truncated stream, a version mismatch, a size-echo
mismatch, a null pointer and **trailing bytes**, leaving both outputs default. `link.program` is
never visited and is null on return.
---
## 5. Verification transcript (on `08192d72`, working tree clean)
```
$ python3 scripts/symbol_report.py --before ~/w7/p4a-before-libMobileGL.so \
--after build-linux/libMobileGL.so --threshold 0
| before | ~/w7/p4a-before-libMobileGL.so | 19114360 | 10806323 |
| after | build-linux/libMobileGL.so | 19114360 | 10806323 |
### Removed (0) _none_ ### Added (0) _none_
### Resized (0) _none_ ### Renamed only (same size) (0) _none_
$ python3 scripts/gen_pipe.py --check
gen_pipe: 71 calls (11 screen, 60 context), 72 verify payloads, 63 PipeInputs fields
(7 sticky, 40 emitted by a P2 call), 69 verbs, 9 classes
gen_pipe: inventory 477 rows: ... 0 UNMAPPED
gen_pipe: generated files are up to date rc=0
$ python3 scripts/gen_pipe.py --self-test
gen_pipe: self-test: 7 negative-control trip(s), positive control OK rc=0
$ git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --check
dirty-surface: 79 mutators, all mapped, no stale rows; 45 render-state answers derived
dirty-surface: 10 other (mutator, bit) answers derived ...; 0 COARSE; 2 UNDECIDED
(listed in MGP_DIRTY_SURFACE_UNDECIDED_LIST); 26 prose answers rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --self-test
dirty-surface self-test: 27 negative controls, all tripped; positive controls OK rc=0
$ python3 scripts/check_include_closure.py --mode both --compiler clang++ --self-test --require-all
include-closure: self-test: 6 negative-control trip(s), parser checks OK
include-closure: 4 probes, 0 skipped, 0 problem(s) rc=0
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD
[p3a-untouched] the 11 ... functions are byte-identical between 37da3c3a and HEAD rc=0
$ cmake --build build-linux -j 16 && ctest --test-dir build-linux -L unit -j 12 100% 1635/1635
$ cmake --build build-push -j 16 && ctest --test-dir build-push -L unit -j 12 100% 1635/1635
$ cmake --build build-verify -j 16 && ctest --test-dir build-verify -L unit -j 12 100% 1635/1635
$ diff <(ctest --test-dir build-linux -N | ID-4 extractor) \
<(ctest --test-dir build-push -N | ID-4 extractor) (empty)
$ comm -23 ~/w7/p4a-before-ctest-names.txt <(build-linux names) (empty)
$ comm -13 ~/w7/p4a-before-ctest-names.txt <(build-linux names) 13 added:
CompositeResolver.TheCompositeBandHasExactlyOneDoor
{Framebuffer,Image,Program,Sampler,Texture}Emit.TheEmitterIsOneNeverDestroyedProcessSingleton
PipeCatalogue.EveryTextureTargetMapsToItsOwnResourceTarget
PipeCatalogue.EveryUnmigratedEmulationIsNamedOnce
PipeCatalogue.TextureParamsNameTheirBuiltinSamplerAndFramebufferStateNamesItsTarget
ProgramArtifactsCodec.{RoundTripsAFullyPopulatedArchive, ATruncatedStreamIsRefusedNotGuessed,
AVersionMismatchIsRefused, TheTablesVisitEveryMemberExceptTheLiveProgram}
$ 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
```
Two failures were found and fixed during the round, both of them gates doing their job:
`PipeCatalogue.SixValueStructsHaveFieldLists` (verified-payload count 71 → 72) and
`TrackerWalk.OnlyTheFiveEmittedBitsNameASubsystem` (the phase constant, §3 D11).
---
## 6. Left undone, and who owns it
- **Every apply body.** All fifteen entry points are stubs; `w1`/`w2`/`w3` fill them, on this
branch, **before** any client package runs against them.
- **Every emitter body**, and the four `kMGPipeWired*Subsystem` constants (all `0`). B and C, in
their own headers.
- **`CompositeResolver.h`** — not created. Wholly C's.
- **`Resolve<Family>SubsystemArm()`** and D-C3's `MaxColorAttachments > 8` refusal — backend-side
(`Managers.cpp`, beside `ResolveResourceSubsystemArm`), package D.
- **The five `MGPipeUnmigratedEmulation` call sites** in `MG_Backend/DirectGLES/` — D and E. The
five names are pinned here (`PipeCatalogue.EveryUnmigratedEmulationIsNamedOnce`):
`copy-image-shadow-mirror`, `generate-mipmap-storage`, `generate-mipmap-cpu-fallback`,
`get-tex-image-shadow`, `texture-remint-pull`.
- **`PipeSlotPeek`'s six new members**, `p4a_untouched_regions.sh`,
`p4a_descriptor_negative_control.sh`, the itest phase-mask moves (`0x1ff → 0x1fff`,
`0x80000000000001ff → 0x8000000000001fff`) and `MagmaPipeArms.h` — package F.
- **The libc++/NDK size pin** (`ProgramArtifacts.h:563-565`) — the integrator's, from an NDK
build's ctest properties. The codec's size echo is `0` under that branch until it lands, which
round-trips correctly within one build and starts biting the moment the pin exists.
- **`ROADMAP.md:100`'s citation of `:7`**, `ARCHITECTURE.md:134`'s texture-params row,
`ARCHITECTURE.md:63`'s sampler-view annotation and `SetHashSuppressor`'s doc corrections in
`docs/` — the integrator's (D.5). The in-tree comments are already correct.
- **`clang++-20`** does not exist in this WSL image; `wsl_p4a_gate.sh` should spell `clang++`
(§3 D16), and note that the script exits 0 when the compiler is missing.
@@ -0,0 +1,469 @@
# P4a package A — `c0b`, the contract-fix round. Result, v2
Two commits on `refs/heads/p4a/contract`, on top of `08192d72` (= the tag `refs/tags/p4a/contract`,
**which was NOT moved and still points at `08192d72`**):
| commit | message |
|---|---|
| **`32033d69`** | `[Fix] (Pipe): land the birth half of the P4a client API behind a publication latch both halves read, gate every emitter on its family's wired constant, raise the sampler view's death notice and count the shader composite band apart from the ordinary slots` |
| **`2cb44039`** | `[Fix] (Pipe): stop the include-closure gate going green on a compiler it could not find or on a probe count nobody asked for` |
`git diff --stat 08192d72 HEAD` — 6 files, **+642 / −41**:
```
MobileGL/MG_Impl/Pipe/PipeFill.cpp | 368 ++++++++++++++++-
MobileGL/MG_Impl/Pipe/SlotAllocator.cpp | 35 ++-
MobileGL/MG_Impl/Pipe/SlotAllocator.h | 40 ++-
MobileGL/MG_Pipe/PipeMutation.h | 145 +++++++++++
MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp | 62 +++++
scripts/check_include_closure.py | 33 ++-
```
Working tree clean, nothing pushed, no other worktree touched. **No file any in-flight package
owns was edited**: the five emit headers, `PipeApply.*`, `MG_State/**`, `MG_Backend/**`,
`MG_IntegrationTest/**` and `test.yml` are byte-identical to `08192d72`.
---
## 1. Verdict on the hard rules
| rule | result |
|---|---|
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0` | **0 added / 0 removed / 0 renamed / 0 resized.** `.text` 10806323 → 10806323 (+0). File 19114360 → 19114360. 27811 → 27811 defined symbols. |
| behaviour neutrality in push and verify | preserved — see §5's argument, three separate mechanisms |
| three builds compile (pull / push / verify) | all three |
| `ctest -L unit` ×3 | **1636 / 1636 in each**, 0 failed (1635 at `c0` + the one case §4.4 adds) |
| ctest names pull == push | `diff` empty, 2602 == 2602 |
| no name removed vs `~/w7/p4a-before-ctest-names.txt` | **empty**; 14 added (`c0`'s 13 + `PipeCatalogue.TheCompositeShaderBandIsCountedApartFromTheOrdinarySpace`) |
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0 |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all --expect-probes 4` | rc 0, 4 probes, 0 problems, 6 controls tripped |
| `p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, the eleven byte-identical |
| the tag was not moved | `refs/tags/p4a/contract` = `08192d72`; `refs/heads/p4a/contract` = `2cb44039` |
| two commits, single-line `[Fix] (Pipe)`, no attribution | yes |
---
## 2. Per-finding disposition
### M1 — the birth half, and the death helpers' literal `false` → **FIXED**, with one declared deviation
**(a) The birth half now exists.** `MG_Pipe/PipeMutation.h:225-358` declares thirteen hooks plus a
three-call publication latch, all inside the file's existing `#if MOBILEGL_PIPE_PUSH`, with the five
frontend classes forward-declared at `:95-106` beside `BufferObject`'s. Bodies are at
`MG_Impl/Pipe/PipeFill.cpp:1027-1114`. The exact declarations are §3.
**(b) The six death helpers read a latch instead of a literal.**
`PipeFill.cpp:1159-1175` adds `HandleOnly(kind, handle)` and
`EmitDeleteIfPublished(kind, handle, apply)`; the five kinds that have a wire delete now call it:
| helper | file:line | wire delete it now emits, when published |
|---|---|---|
| `MGPipeEmitSamplerViewCsoDestroyAndFree` | `PipeFill.cpp:1180-1181` | `MGPipeApplyDeleteSamplerView` |
| `MGPipeEmitTextureDestroyAndFree` | `:1199-1200` | `MGPipeApplyResourceDestroy` |
| `MGPipeEmitRenderbufferDestroyAndFree` | `:1235-1236` | `MGPipeApplyResourceDestroy` |
| `MGPipeEmitSamplerCsoDestroyAndFree` | `:1268-1269` | `MGPipeApplyDeleteSamplerState` |
| `MGPipeEmitShaderCsoDestroyAndFree` | `:1284-1285` | `MGPipeApplyDeleteShaderState` |
| `MGPipeEmitFramebufferDestroyAndFree` | `:1241-1263` | none, and now says **why the literal `false` is right for this kind**: nothing ever takes the latch for a kind with no create and no delete |
**[deviation D17] the latch is A's, not each emitter's `RecordIsPublished(handle)`.** The review's
fix (b) asks for `Bool RecordIsPublished(MGPipeHandle) const` on each of the five emitter classes.
That is an edit to the five emit headers, which **B and C are editing right now** — the one thing
this round may not do. It is also the wrong shape for P4a even without that constraint, and the
three reasons are in `PipeFill.cpp:1139-1146`:
- P3a had **one** kind behind **one** emitter, so the emitter could hold the latch. P4a has **six
kinds behind four emitters**, so a per-emitter latch means asking a different object per kind and
three of the four emitters answering for two kinds each.
- `SamplerViewCso` **has no frontend object and no emitter of its own** — it is minted off the
texture's lifetime id — so "ask its emitter" has no well-defined answer.
- The composite `ShaderCso` has **two independent release paths** (the pipeline cache's LRU
eviction and the composite `ProgramObject`'s destructor), and the second must be a proven no-op.
One latch keyed `{kind, slot, gen}`, cleared by the first delete, makes it one.
So: `MGPipeNoteHandlePublished(kind, handle)` / `MGPipeHandleIsPublished(kind, handle)` /
`MGPipeNoteHandleUnpublished(kind, handle)` (`PipeMutation.h:277-279`, `PipeFill.cpp:1027-1040`),
backed by a per-kind dense table plus **the composite band's own table**
(`PipeFill.cpp:958-1024`) — the client-side worked example of must-know item 3. **B and C call
`MGPipeNoteHandlePublished` when a create actually goes out and touch nothing else.**
### M2 — `MGPipeApplyResourceSubData`'s missing region tail → **NOT THIS ROUND**
Assigned to package `wire`'s rework, as instructed: `PipeApply.{h,cpp}` is being edited there now.
Untouched here.
### M3 — `wants()` did not consult `kMGPipeWiredSubsystems` → **FIXED**
`PipeFill.cpp:2184-2191` — the rule as landed is §4.1. The three comments that claimed the
property are now true rather than intended: `PipeFill.cpp:2241-2245` (the P4a segment's "this whole
block is dead"), and the drain gate's "the same pair `wants()` applies to every other emission"
(`:2252-2254`) is now literally the same pair. The `docs/` sentences are the integrator's.
### M4 — `MGPipeEmitSamplerViewCsoDestroyAndFree` skipped the death notice → **FIXED**
`PipeFill.cpp:1182-1193`. It now calls the same `NotifyAndFree(SamplerViewCso, lifetimeId, handle)`
the other five use, and the old reason is replaced by the refutation: the notice is
kind-parameterised, `MGPipeKind` has `SamplerViewCso`, and the helper's own first line already
resolves the view through that kind's `ByLifetimeId` map. "No frontend object of its own" is why it
takes a lifetime id, not a reason to drop step 2.
### M5 — `HighWater(ShaderCso)` made the ordinary leak assertion vacuous → **FIXED**
`SlotAllocator.h:86-119`, `SlotAllocator.cpp:224-254`. The two spaces are reported apart. **API
for package F** (`PipeSlotPeek`'s new members) is §4.3. A unit case proves the marks move
independently: §4.4.
### M6 — the closure gate could not go red → **FIXED, and the real defect was one step further in**
At `08192d72` the script **does** exit 1 when `--compiler X` is missing *in a mode that runs one* —
`--mode clang` and `--mode both` both reach `pick_compiler`, which already called `sys.exit(1)`.
Measured on this tree before the fix:
```
$ python3 scripts/check_include_closure.py --mode both --compiler clang++-20 --self-test --require-all
::error::compiler not found: clang++-20 rc=1
```
The hole is the **default mode**. `--mode text` never reaches `pick_compiler`, so an explicit
`--compiler` is accepted and silently ignored:
```
$ python3 scripts/check_include_closure.py --compiler clang++-20 --self-test --require-all
include-closure: 4 probes, 0 skipped, 0 problem(s) rc=0 # BEFORE
```
That is the false green D16 recorded, and it is the shape a gate line acquires the moment someone
drops `--mode both`. Two changes, `scripts/check_include_closure.py`:
1. `:608-614` — an explicit `--compiler` is resolved in **every** mode. Asking for a compiler that
is not there is an operator error whatever the mode, and it stops the run rather than
half-running it. `:630` reuses the resolved path so `--mode clang`/`both` are unchanged.
2. `:589-593`, `:699-704` — **`--expect-probes N`**: the run fails unless exactly N probes ran, so
the gate line can pin 4 rather than only the exit code. A `--probe` typo or a manifest edit is
exactly how a gate stops looking at anything.
Both arms verified red (§5). **The gate scripts spell `clang++`** — `/usr/sbin/clang++` exists,
`clang++-20` does not; the script's own usage block (`:47-56`) now spells `clang++` and
`--expect-probes 4`. **`.github/workflows/test.yml:774` still spells `--compiler clang++-20`** and
is package F's file, not A's: with this commit that line now goes **red** instead of green-and-empty,
which is the correct direction but F must move it to `--compiler clang++ --expect-probes 4` before
the lane can pass. `wsl_p4a_gate.sh` (the integrator's) already spells `clang++`.
### Minors
| minor | where it lives | disposition |
|---|---|---|
| **m1** vacuous `kMGPipeResourceTargetBuffer` drift assert | `MG_Pipe/MGPipeTypes.h` | **not taken — outside this round's file set.** For `wire` or an announced A amendment: give the constant its literal `0`, or drop the assert and say the constant is derived. |
| **m2** `MGPipeApplierReleaseObjectRecords` clears three of the working handles | `MG_Pipe/PipeApply.cpp` | **not taken — `wire` owns the file this round** |
| **m3** the texture death helper discarded the view helper's answer | `PipeFill.cpp:1224-1229` | **TAKEN.** `return published \|\| viewPublished;`, with the reason: a texture whose `ResourceDestroy` was suppressed but whose `DeleteSamplerView` went out has already spoken for this object, and `false` would run the legacy path for both halves. |
| **m4** the `~SamplerObject` ordering claim is not guaranteed | `PipeFill.cpp:1210-1223` | **TAKEN.** The conclusion is kept and the timing claim is deleted and replaced by its refutation (`m_sampler` is a `SharedPtr`; a unit slot or a view resolution delays it arbitrarily) plus an explicit "a package must not build an ordering on it". |
| **m5** the archive byte stream is not canonical | `ProgramArtifactsCodec.h` | **not taken — outside the file set.** Still worth one sentence in that header before P5 or the program disk cache wants a cache key. |
| **m6** `EveryUnmigratedEmulationIsNamedOnce` cannot fail for its reason | `PipeCatalogueTest.cpp` | **not taken.** The "red before" half genuinely belongs to F's grep script; adding a tree-side check here would duplicate it in the weaker direction. |
| **m7** `BindProgramPipelineObject`'s row is coupled to a `PipeFill.cpp` arm | `MG_Pipe/DirtySurface.def` | **not taken — outside the file set** (A's, but not this round's). One sentence in the row's comment naming `EmittedCallSuppliesTheWholeField(GetProgramForDraw)`. |
| **m8** the five singleton cases do not observe what they name | the five `*EmitTest.cpp` | **not taken — B and C own those files' contents now** |
| **m9** `FreeCount(ShaderCso)` sums two spaces | `SlotAllocator.h:115-119`, `.cpp:247-254` | **TAKEN, and more than asked**: the caveat is written down *and* `CompositeFreeCount()` answers the band, so a caller can tell which space a slot returned to instead of only being warned that it cannot. |
---
## 3. THE CONTRACT ADDITION — what B and C compile against
Everything in this section is new at `32033d69` and is what packages B and C must write their
emitters against. **Nothing calls any of it yet**; B and C add the call sites by **editing** the
existing `#if MOBILEGL_PIPE_PUSH` constructor / mutator / destructor bodies, never by adding one (G1).
### 3.1 The publication latch — `MG_Pipe/PipeMutation.h:255-279`
```cpp
void MGPipeNoteHandlePublished(MGPipeKind kind, MGPipeHandle handle);
Bool MGPipeHandleIsPublished(MGPipeKind kind, MGPipeHandle handle);
void MGPipeNoteHandleUnpublished(MGPipeKind kind, MGPipeHandle handle);
```
**The protocol, and it is not negotiable.** An emitter calls `MGPipeNoteHandlePublished(kind,
handle)` **when, and only when, a create for exactly that handle actually went on the wire**. The
six death helpers read `MGPipeHandleIsPublished` and clear the latch with the delete they emit; an
emitter that drops a record for its own reasons (an LRU eviction, a re-mint) calls
`MGPipeNoteHandleUnpublished`. Keyed `{kind, slot, gen}`, so a recycled slot never inherits its
predecessor's answer, and the `ShaderCso` composite band has a table of its own inside the latch.
Never destroyed (`PipeFill.cpp:1018-1024`), for `MGPipeSlots()`' exit-order reason.
### 3.2 The four mints — `PipeMutation.h:281-299`, bodies `PipeFill.cpp:1042-1056`
```cpp
void MGPipeMintTextureHandle(MG_State::GLState::ITextureObject& texture);
void MGPipeMintRenderbufferHandle(MG_State::GLState::RenderbufferObject& renderbuffer);
void MGPipeMintFramebufferHandle(MG_State::GLState::FramebufferObject& framebuffer);
void MGPipeMintShaderCsoHandle(MG_State::GLState::ProgramObject& program);
```
Pure allocator work — `MGPipeSlots().Acquire(kind, object.GetLifetimeId())` and nothing else — and
**unconditional in a push build**, for `MGPipeMintResourceHandle`'s reason: `MGPSurface::Res`,
`MGPBoundView::Texture` and `MGPImageView::Res` name a texture or renderbuffer handle out of
*other* families, so gating the mint on the family's own bit would make those emit null handles in
exactly the A/B arm that exists to isolate the families. Called from the object's constructor.
A program-pipeline **composite** is not a construction event and is not here: it is minted by C's
resolver through `MGPipeSlotAllocator::AllocateComposite`, the one door into the band.
### 3.3 The nine emissions — `PipeMutation.h:301-358`, bodies `PipeFill.cpp:1058-1114`
```cpp
// textures and renderbuffers - MG_Impl/Pipe/TextureEmit.h, package B
void MGPipeEmitTextureResourceCreate(MG_State::GLState::ITextureObject& texture);
void MGPipeEmitTextureResourceRespecify(MG_State::GLState::ITextureObject& texture);
void MGPipeEmitTextureParams(MG_State::GLState::ITextureObject& texture);
void MGPipeNoteTextureLevelDirty(MG_State::GLState::ITextureObject& storageOwner,
Uint32 uploadTarget, Uint32 level);
void MGPipeEmitRenderbufferResourceCreate(MG_State::GLState::RenderbufferObject& renderbuffer);
void MGPipeEmitRenderbufferResourceRespecify(MG_State::GLState::RenderbufferObject& renderbuffer);
// sampler CSOs and sampler views - MG_Impl/Pipe/SamplerEmit.h, package C
void MGPipeEmitSamplerCsoCreate(MG_State::GLState::SamplerObject& sampler);
void MGPipeEmitSamplerViewCreate(MG_State::GLState::ITextureObject& texture);
// programs - MG_Impl/Pipe/ProgramEmit.h, package C
void MGPipeEmitShaderCsoCreate(MG_State::GLState::ProgramObject& program);
```
Each body is the same three lines (`PipeFill.cpp:1058-1114`): the **gate**, then the **forward**.
### 3.4 THE ENTRY POINTS EACH EMIT HEADER MUST PROVIDE — implement exactly these
Public members of the family's existing emitter class, taking the frontend object by reference,
returning `void`. **The spelling is load-bearing**: `PipeFill.cpp` already calls them, and a family
that sets its wired constant without providing one is a compile error in that family's own commit.
| emitter class | entry point | called from |
|---|---|---|
| `MGPipeTextureEmitter` | `void EmitResourceCreate(MG_State::GLState::ITextureObject&)` | `MGPipeEmitTextureResourceCreate` |
| `MGPipeTextureEmitter` | `void EmitResourceRespecify(MG_State::GLState::ITextureObject&)` | `MGPipeEmitTextureResourceRespecify` |
| `MGPipeTextureEmitter` | `void EmitTextureParams(MG_State::GLState::ITextureObject&)` | `MGPipeEmitTextureParams` |
| `MGPipeTextureEmitter` | `void NoteLevelDirty(MG_State::GLState::ITextureObject& storageOwner, Uint32 uploadTarget, Uint32 level)` | `MGPipeNoteTextureLevelDirty` |
| `MGPipeTextureEmitter` | `void EmitRenderbufferCreate(MG_State::GLState::RenderbufferObject&)` | `MGPipeEmitRenderbufferResourceCreate` |
| `MGPipeTextureEmitter` | `void EmitRenderbufferRespecify(MG_State::GLState::RenderbufferObject&)` | `MGPipeEmitRenderbufferResourceRespecify` |
| `MGPipeSamplerEmitter` | `void EmitSamplerCso(MG_State::GLState::SamplerObject&)` | `MGPipeEmitSamplerCsoCreate` |
| `MGPipeSamplerEmitter` | `void EmitSamplerView(MG_State::GLState::ITextureObject&)` | `MGPipeEmitSamplerViewCreate` |
| `MGPipeProgramEmitter` | `void EmitShaderCso(MG_State::GLState::ProgramObject&)` | `MGPipeEmitShaderCsoCreate` |
`MGPipeFramebufferEmitter` and `MGPipeImageEmitter` need **nothing new**: a framebuffer's record
goes out at the validate point through the existing `EmitFramebufferState`, and the image units'
through `EmitShaderImages`. `MGPipeTextureEmitter::DrainTextureSubData` is unchanged and is still
the only validate-point call in the texture family.
**Each entry point owns its family's handle rule and its own publication.** `PipeFill.cpp` does
*not* resolve the handle for these — deliberately, because the three families disagree about
identity and the contract must not pick for them: a texture's view is identity-addressed off the
texture's lifetime id (D-F2), a sampler CSO is **content-addressed and shared** (D-F1), a program's
CSO is identity-addressed per `ProgramObject` and a composite comes out of the band (D-H7).
> **Open item for C, and it is a real tension in the brief, not a defect in this commit.** D-F1
> content-addresses sampler CSOs at capacity 256 with sharing, while D-I1 makes `~SamplerObject`
> call `MGPipeEmitSamplerCsoDestroyAndFree(m_lifetimeId)`, which resolves
> `FindByLifetimeId(SamplerCso, lifetimeId)`. Two samplers sharing one CSO cannot both own that
> slot's lifetime-id mapping. C must decide which sampler object (if any) owns the mapping, and the
> death helper is already safe when nothing resolves: a null handle emits no delete and frees no
> slot, and the death notice still goes out.
### 3.5 The seam, and why it exists — `PipeFill.cpp:889-937`
```cpp
template <Uint64 kWired, class Emitter, class Fn>
constexpr void ForwardWhenWired(Emitter& emitter, Fn&& call) {
if constexpr (kWired != 0) { call(emitter); } else { (void)emitter; (void)call; }
}
```
A owns `PipeFill.cpp` for the whole phase and B/C own the five emit headers, so the forwarding had
to be written **now**, against an emitter whose entry point does not exist **yet**. A plain call
would not compile against the stub and a runtime `if` would not link. Passing the family's wired
constant as a **template argument** makes the `if constexpr` condition value-dependent, so the
discarded statement is never instantiated while the constant is `0`; the moment a family sets it,
the statement instantiates and a missing or misspelled entry point is a **compile error in that
family's own commit**. `call` must be a **generic** lambda (`[&](auto& emitter) { … }`) — that is
what defers the body's name lookup — and every call site in `PipeFill.cpp` already is one.
The taken arm is otherwise never instantiated in this tree, so `PipeFill.cpp:917-937` adds a
**positive control**: a local probe emitter driven through the same template with `1ull` and with
`0ull`, and a `static_assert` that exactly one call happened. "Discarded when 0, called when set"
is a checked property of this build, not a claim in a comment.
---
## 4. The other three landed rules
### 4.1 `wants()` as landed — `MG_Impl/Pipe/PipeFill.cpp:2184-2191`
```cpp
const Uint64 pushMask = MG_Config::Features.PipePush;
const auto wants = [&](MGPipeDirty bit) {
const Uint64 subsystem = MGPipeSubsystemForDirty(bit);
return subsystem != 0 && (pushMask & subsystem) != 0 &&
(kMGPipeWiredSubsystems & subsystem) != 0 &&
(dirty & MGPipeDirtyBit(bit)) != 0;
};
```
**Four conditions**: the bit maps to a subsystem, the operator's mask has it, **this build wired
the family**, and the bit fired. The birth hooks' gate (`FamilyIsLive`, `PipeFill.cpp:885-887`) is
the same pair one level in, so the client paths and the validate point cannot disagree.
**Behaviour at `c0b` is unchanged, and it is checkable rather than argued.**
`MGPipeSubsystemForDirty` (`Tracker.h:156-200`) returns exactly eight distinct constants:
`RenderState`, `PixelPack`, `PatchState`, `VertexAttribDefaults`, `VertexInput` — all five present
in `kMGPipeWiredSubsystems` (`PipeFill.cpp:1601-1610`) — and `Programs`, `Framebuffer`, `Samplers`,
whose family constants are all `0` today and whose emitters are all stubs returning 0. So the new
condition removes nothing that emitted and adds nothing that did not.
**What this changes for B and C**: `kMGPipeWiredFramebufferSubsystem`,
`kMGPipeWiredTextureSubsystem`, `kMGPipeWiredSamplerSubsystem` and `kMGPipeWiredProgramSubsystem`
**are** the switch, exactly as their headers say. An emitter with a body and a constant still `0`
is called by nothing and emits nothing; flipping the constant switches the family on. Both
directions of the M3 failure scenario are now closed.
### 4.2 The sampler view's death notice
`PipeFill.cpp:1182-1193`, §2/M4. **For D and E**: a backend twin held per `SamplerViewCso` slot now
gets its `NotifyStateObjectDestroyed(MGPipeKind::SamplerViewCso, lifetimeId)`, like the other five
kinds, and the answer to `SlotTables.h:38`'s "all six re-keyed object classes raise
`NotifyStateObjectDestroyed()`" is now yes for all six.
### 4.3 The allocator's two spaces — API for package F
```cpp
Uint32 HighWater(MGPipeKind kind) const; // the ORDINARY space only, every kind
Uint32 CompositeHighWater() const; // one past the highest composite slot ever
// handed out; == the band base when none was
Uint32 LiveCount(MGPipeKind kind) const; // BOTH spaces for ShaderCso (unchanged)
Uint32 CompositeLiveCount() const; // the band's share of it
Uint32 FreeCount(MGPipeKind kind) const; // BOTH spaces for ShaderCso (unchanged)
Uint32 CompositeFreeCount() const; // the band's share of it
```
`SlotAllocator.h:86-119`; bodies `SlotAllocator.cpp:224-254`; `KindState::BandLiveCount` at
`SlotAllocator.h:148-150`, maintained at `.cpp:157-158`, `:201-202`, `:264`.
**`LiveCount` and `FreeCount` deliberately keep summing both spaces.** `CompositeResolverTest.
TheCompositeBandHasExactlyOneDoor` — which is package **C**'s file and must not be edited here —
reads `LiveCount(ShaderCso)` across a composite free and asserts it drops by one. Narrowing it
would have broken a case in a file this round may not touch, and the merged count is also the right
answer on its own terms: a live composite *is* a live `ShaderCso`. Only the **high-water** mark had
to split, because that is the one whose merged form is monotone-and-pinned.
**Package F, `PipeSlotPeek`**: the six new members G8b asks for want a **seventh**,
`PeekPipeCompositeSlotHighWater`, and the composite leak case asserts on that one; the ordinary
`ShaderCso` case keeps asserting on `PeekPipeSlotHighWater(ShaderCso)`, which is now a real
assertion again.
### 4.4 The unit case that proves the marks move — `MG_Test/Pipe/PipeCatalogueTest.cpp:783-843`
`PipeCatalogue.TheCompositeShaderBandIsCountedApartFromTheOrdinarySpace` pins both halves in one
allocator: a composite mint moves `CompositeHighWater()` and **leaves `HighWater(ShaderCso)` where
it was**; an ordinary mint with a composite outstanding moves `HighWater(ShaderCso)` and **leaves
`CompositeHighWater()` where it was**; freeing the composite returns it to the band's free list
(`CompositeFreeCount() == 1`, `FreeCount(ShaderCso) == 1`) and **neither high-water mark comes back
down**, which is what makes them leak witnesses. A visible `GTEST_SKIP` in a pull build, so
`ctest -N` stays name-for-name identical.
It lives in `PipeCatalogueTest.cpp` because that file is A's by C.7 and needs no
`MG_Test/Pipe/CMakeLists.txt` edit. `SlotAllocatorTest.cpp` is the thematic home and C.7 gives it
to **nobody**; a later round may move the case there.
---
## 5. Why the tree is still behaviourally neutral
Three independent mechanisms, each checkable:
1. **Nothing calls the birth hooks.** `git grep` for any of the thirteen names outside
`PipeMutation.h` and `PipeFill.cpp` is empty; B and C add the call sites.
2. **Every birth hook is gated twice** and both gates are false today:
`FamilyIsLive(subsystem, wired)` needs the operator's bit **and** a non-zero family constant, and
all four family constants are `0`. Even with the gate passed, the `if constexpr` seam discards
the forward.
3. **Nothing latches a publication**, so `MGPipeHandleIsPublished` answers `false` for every handle
and the five death helpers emit no wire delete — exactly as they did at `c0`, but now for a
reason a package can change rather than a literal it cannot.
And `wants()`' new condition removes nothing (§4.1). The pull build is untouched: every line added
to `PipeMutation.h` is inside its `#if MOBILEGL_PIPE_PUSH`, and `PipeFill.cpp` / `SlotAllocator.cpp`
are compiled only under it — which G1's 0/0/0/0 confirms.
---
## 6. Verification transcript (on `2cb44039`, working tree clean)
```
$ 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: before: ~/w7/p4a-before-libMobileGL.so (19114360 bytes on disk)
symbol-report: after : build-linux/libMobileGL.so (19114360 bytes on disk)
symbol-report: .text 10806323 -> 10806323 (+0, +0.000%)
symbol-report: 27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
### Removed (0) _none_ ### Added (0) _none_
### Resized (0) _none_ ### Renamed only (0) _none_ rc=0
$ cmake --build build-linux -j 12 && ctest --test-dir build-linux -L unit -j 12 100% 1636/1636
$ cmake --build build-push -j 12 && ctest --test-dir build-push -L unit -j 12 100% 1636/1636
$ cmake --build build-verify -j 12 && ctest --test-dir build-verify -L unit -j 12 100% 1636/1636
$ diff <(build-linux names) <(build-push names) (empty; 2602 == 2602)
$ comm -23 ~/w7/p4a-before-ctest-names.txt <(build-linux names) (empty)
$ comm -13 ~/w7/p4a-before-ctest-names.txt <(build-linux names) 14 added:
CompositeResolver.TheCompositeBandHasExactlyOneDoor
{Framebuffer,Image,Program,Sampler,Texture}Emit.TheEmitterIsOneNeverDestroyedProcessSingleton
PipeCatalogue.{EveryTextureTargetMapsToItsOwnResourceTarget, EveryUnmigratedEmulationIsNamedOnce,
TextureParamsNameTheirBuiltinSamplerAndFramebufferStateNamesItsTarget,
TheCompositeShaderBandIsCountedApartFromTheOrdinarySpace} <- c0b's one
ProgramArtifactsCodec.{RoundTripsAFullyPopulatedArchive, ATruncatedStreamIsRefusedNotGuessed,
AVersionMismatchIsRefused, TheTablesVisitEveryMemberExceptTheLiveProgram}
$ ctest --test-dir build-linux -R TheCompositeShaderBandIsCountedApartFromTheOrdinarySpace Skipped (pull)
$ ctest --test-dir build-push -R TheCompositeShaderBandIsCountedApartFromTheOrdinarySpace 1/1 passed
$ ctest --test-dir build-verify -R TheCompositeShaderBandIsCountedApartFromTheOrdinarySpace 1/1 passed
$ python3 scripts/gen_pipe.py --check rc=0
gen_pipe: 71 calls (11 screen, 60 context), 72 verify payloads, 63 PipeInputs fields,
69 verbs, 9 classes; inventory 477 rows, 0 UNMAPPED; generated files up to date
$ python3 scripts/gen_pipe.py --self-test rc=0
$ git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --check rc=0
dirty-surface: 79 mutators, all mapped; 0 COARSE; 2 UNDECIDED (listed); 26 prose answers
$ python3 scripts/gen_pipe_dirty_surface.py --self-test rc=0
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD rc=0
$ python3 scripts/check_include_closure.py --mode both --compiler clang++ \
--self-test --require-all --expect-probes 4
include-closure: self-test: 6 negative-control trip(s), parser checks OK
include-closure: 4 probes, 0 skipped, 0 problem(s) rc=0
# M6's two controls, both of which used to be green:
$ python3 scripts/check_include_closure.py --mode text --compiler clang++-20 --self-test
::error::compiler not found: clang++-20 rc=1 (was rc=0)
$ python3 scripts/check_include_closure.py --mode both --compiler clang++ --expect-probes 9
include-closure: 4 probes, 0 skipped, 1 problem(s)
::error::expected 9 probe(s), ran 4 rc=1 (new)
$ git rev-parse refs/tags/p4a/contract 08192d7266ace31cbba1641ed8078948687cbaaa (NOT moved)
$ git rev-parse refs/heads/p4a/contract 2cb44039b526abfd9875ea3b16fb57dda4296e26
$ git status --porcelain (empty)
```
---
## 7. What the other packages must be told
1. **B and C: implement §3.4's nine entry points verbatim, and call
`MGPipeNoteHandlePublished(kind, handle)` when a create actually goes out.** Nothing else
latches it, and without it your kind's destroy never goes out.
2. **`kMGPipeWired*Subsystem` now really is the switch** (§4.1). Emitter bodies are inert until the
constant is set, in *both* the validate point and the client paths.
3. **The wired constant is also a compile-time contract**: set it and every entry point §3.4 names
for your family must exist, spelled exactly, or the build fails in your commit.
4. **C: the D-F1/D-I1 sampler-CSO identity tension is open** (§3.4's box) and is C's to resolve.
5. **D and E: `SamplerViewCso` now raises `NotifyStateObjectDestroyed`** like the other five kinds
(§4.2) — write the twin drop.
6. **F: `PipeSlotPeek` needs a seventh member** for `CompositeHighWater()` (§4.3), and
`.github/workflows/test.yml:774` must move to `--compiler clang++ --expect-probes 4` or that
step is now red (§2/M6).
7. **`wire`: M2 (the `MGPSubRegion` tail on `MGPipeApplyResourceSubData`) and m2 are yours**, and
m1 (`MGPipeTypes.h`'s vacuous drift assert) is unclaimed.
@@ -0,0 +1,322 @@
# contract-v3 — c0c, the four seam encodings (P4a package A, ID-12)
**Branch** `refs/heads/p4a/contract` · **commit `17db7598`** · parent `2cb44039` (= `feat/disaggregated`)
· base `37da3c3a` · one commit, three files.
```
[Fix] (Pipe): state the four seam encodings the packages were each inventing - the sub-data
target packing, the depth-stencil aspect numbers, the surface kind constants and the texture
target the surface record grew where its padding was
MobileGL/MG_Pipe/MGPipeTypes.h | 118 +++++++++++++++++++++-
MobileGL/MG_Pipe/PipeFields.def | 6 +-
MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp | 148 ++++++++++++++++++++++++++++
3 files changed, 268 insertions(+), 4 deletions(-)
```
Nothing else moved. `MobileGL/MG_Pipe/generated` is untouched (`git diff --exit-code` rc 0):
the shadow comparator expands `MGP_FIELDS_MGPSurface` from `PipeFields.def` at compile time,
so the new row needs no regeneration — `gen_pipe.py` was still re-run and reports
`generated files are up to date`.
---
## 1. The exact declarations, for B/C/D/E to quote
All four blocks are in `MobileGL/MG_Pipe/MGPipeTypes.h`, namespace `MobileGL::MG_Pipe` — the
same namespace the in-flight packages' emit headers use, so a package that keeps its own copy
gets a redefinition error rather than a silent second authority.
### 1.1 `MGPSubData::Target` — the packing (ID-12 DV-3)
Placed immediately after `MGP_ASSERT_POD(MGPSubData, 72);`. The struct's comment block above it
now states the encoding and why the halves are that way round.
```cpp
constexpr inline Uint16 MGPipePackSubDataTarget(Uint32 resourceTarget, Uint32 uploadTarget) {
return static_cast<Uint16>((resourceTarget & 0xFFu) | ((uploadTarget & 0xFFu) << 8));
}
// Comparable against static_cast<Uint8>(MGPipeResourceTarget) / kMGPipeResourceTargetBuffer.
constexpr inline Uint8 MGPipeSubDataResourceTargetOf(Uint16 packed) {
return static_cast<Uint8>(packed & 0xFFu);
}
// Comparable against static_cast<Uint8>(MobileGL::TextureUploadTarget).
constexpr inline Uint8 MGPipeSubDataUploadTargetOf(Uint16 packed) {
return static_cast<Uint8>((packed >> 8) & 0xFFu);
}
static_assert(MGPipePackSubDataTarget(kMGPipeResourceTargetBuffer, 0u) ==
kMGPipeResourceTargetBuffer,
"a buffer sub-data record's Target must stay exactly "
"kMGPipeResourceTargetBuffer: the applier's SubDataNamesABuffer tests the "
"whole field == 0");
```
* low byte = `MGPipeResourceTarget`, high byte = `MobileGL::TextureUploadTarget`.
* **`Uint32` arguments, not the two enum types.** `MGPipeResourceTarget` is minted in this
header but the upload half is MG_State's, and no reader of the packed field ever needs that
type — the applier and both backends read the halves back as bytes through the two
accessors. It also lets `kMGPipeResourceTargetBuffer` be passed as it stands. **This is the
one signature difference from clientfb's copy**, whose second parameter was
`MobileGL::TextureUploadTarget`. A scoped enum does not convert implicitly, so B's call
sites need `static_cast<Uint32>(...)` on the upload argument once its own copy is deleted —
which the compiler points at, one site at a time (see §4).
* The comment block above the struct records **why**: the applier's `SubDataNamesABuffer` tests
the *whole* field `== 0` and `TextureUploadTarget::Texture1D` is 0, so a texture record
carrying the bare upload enumerator would be indistinguishable from a buffer record exactly
when its owner is a 1D texture, and that texture's upload would be dispatched into the buffer
path. With the resource target in the low byte a buffer record's `Target` stays exactly
`kMGPipeResourceTargetBuffer` (P3a's records unchanged — their upload byte is zero too) and a
texture record can never be zero, because no texture's `MGPipeResourceTarget` is.
* `MGPipeBuildSubDataRecord` (`MG_Impl/Pipe/ResourceTracker.h:212`,
`out.Target = kMGPipeResourceTargetBuffer`) is correct as it stands and was not touched.
### 1.2 `MGPTextureParams::DepthStencilMode` (ID-12 DV-2)
Placed immediately after `MGP_ASSERT_POD(MGPTextureParams, 40);`.
```cpp
inline constexpr Uint8 kMGPipeDepthStencilModeDepth = 0; // GL_DEPTH_COMPONENT
inline constexpr Uint8 kMGPipeDepthStencilModeStencil = 1; // GL_STENCIL_INDEX
```
The comment states that 0 is depth because `GL_DEPTH_COMPONENT` is the GL initial value of
`GL_DEPTH_STENCIL_TEXTURE_MODE` and a texture that never asks for the stencil aspect never
emits the call — a zeroed record must decode to what an untouched texture already has — and
that numbering by the enum's low byte (0x02 / 0x01) would have left zero meaning nothing. The
`GLenum -> byte` helper stays B's.
### 1.3 `MGPSurface::Kind` (ID-12 DV-4)
Placed immediately before `struct MGPSurface`.
```cpp
inline constexpr Uint8 kMGPipeSurfaceKindNone = static_cast<Uint8>(MGPipeKind::None);
inline constexpr Uint8 kMGPipeSurfaceKindTexture = static_cast<Uint8>(MGPipeKind::Texture);
inline constexpr Uint8 kMGPipeSurfaceKindRenderbuffer =
static_cast<Uint8>(MGPipeKind::Renderbuffer);
static_assert(kMGPipeSurfaceKindNone == 0,
"a zero-initialised MGPSurface must already be the empty attachment point");
```
Byte-identical in value to clientfb's copy (same reuse of `MGPipeKind`, same static_assert).
### 1.4 `MGPSurface::Pad0` -> `Uint16 TextureTarget` (ID-12 DV-5)
```cpp
inline constexpr Uint16 kMGPipeSurfaceNoTextureTarget = 0xFFFF;
static_assert(kMGPipeSurfaceNoTextureTarget ==
static_cast<Uint16>(MobileGL::TextureTarget::Unknown),
"kMGPipeSurfaceNoTextureTarget is TextureTarget::Unknown widened to the "
"field, and MG_State moved Unknown off -1");
struct MGPSurface {
MGPipeHandle Res;
Uint32 InternalFormat;
Uint8 Kind; // kMGPipeSurfaceKind{None,Texture,Renderbuffer}, above
Uint8 Layered;
Uint16 Level;
Uint32 Layer;
Uint16 UploadTarget; // static_cast<Uint16>(MobileGL::TextureUploadTarget)
Uint16 TextureTarget; // was Pad0
};
MGP_ASSERT_POD(MGPSurface, 24); // UNCHANGED
```
`TextureTarget` is `static_cast<Uint16>(MobileGL::TextureTarget)`, is
`kMGPipeSurfaceNoTextureTarget` on every non-texture point, and is **consulted only when
`Kind == kMGPipeSurfaceKindTexture`**. Its comment carries the reason it exists (the four
cross-object masks reduce to `(format, TEXTURE TARGET)` — `ShouldUseCaveatTextureFormat` and
`BackendTextureFormatAddsAlpha` — and no `TextureUploadTarget -> TextureTarget` inverse exists
in the tree, so `UploadTarget` cannot answer them) and the one sharp edge: a zero-initialised
record carries 0, which is `TextureTarget::Texture1D` and **not** the sentinel — harmless
because such a record is `Kind == None`, which is why gating on `Kind` is the reader's
contract.
`PipeFields.def`:
```
// P4a, ID-12 / esprytobj DV-5: Pad0 became Uint16 TextureTarget. Same trip wire as
// MGPFramebufferState's Target below - PADDING_MEMBER_RE only excludes a member still NAMED
// Pad<n>, so the rename without this row is a pipe-gates failure, and the row without the
// rename is one too. A meaning-carrying byte cannot enter this record silently.
#define MGP_FIELDS_MGPSurface(F) \
F(Res) F(InternalFormat) F(Kind) F(Layered) F(Level) F(Layer) F(UploadTarget) F(TextureTarget)
```
**Existing readers/writers of `MGPSurface::Pad0` on this branch: none.** `grep` over
`MG_Pipe`, `MG_Impl/Pipe`, `MG_Backend` and `MG_Test` finds `MGPSurface` only in
`PipeMutation.h` (a comment), `MGPipe.h` (a comment), `MGPipeCallbacks.h` (`MGPSurfaceInfo`, a
different struct), `generated/PipeVerify.inc` (the macro expansion) and
`FramebufferEmitTest.cpp` (a comment). c0/c0b's own code never named the padding member, so
nothing needed changing and everything still compiles — verified by the three full builds
below. The packages' own files are not on this branch.
---
## 2. The unit cases (A-owned)
Both added to `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp`, the contract-owned suite c0/c0b
already extend (c0b added `TheCompositeShaderBandIsCountedApartFromTheOrdinarySpace` there).
No CMake change: `PipeCatalogueTest` is registered by `MG_Test/Pipe/CMakeLists.txt` and
discovered with `LABELS unit`. Both run — not skipped — on all three lanes.
* **`PipeCatalogue.SubDataTargetPacksAResourceTargetAndAnUploadTarget`**
static_asserts that both halves fit their byte; round-trips **every** `MGPipeResourceTarget`
(0..`Count`-1, i.e. all 13) against five upload targets — `0`, `Texture2D`,
`CubeMapPositiveX`, `CubeMapNegativeZ` and `TextureUploadTargetCount - 1` — through
`MGPipeSubDataResourceTargetOf` / `…UploadTargetOf`, naming the offending pair on failure;
pins the buffer invariant at compile time *and* at runtime, including a zero-initialised
`MGPSubData` whose `Target` compares equal to `kMGPipeResourceTargetBuffer` whole-field;
pins the collision it prevents (`TextureUploadTarget::Texture1D == 0`, and no non-zero
resource target packs to the buffer value even with upload byte 0); and shows two cube faces
sharing one resource target but differing in the high byte.
* **`PipeCatalogue.SurfaceNamesItsKindItsTextureTargetAndItsDepthStencilAspect`**
the three surface-kind constants against `MGPipeKind` and `None == 0`; `sizeof(MGPSurface)
== 24` with `offsetof(UploadTarget) == 20`, `offsetof(TextureTarget) == 22`; the sentinel
against `TextureTarget::Unknown` and against every real target; **a zeroed `MGPSurface` has
`TextureTarget == 0`, documented in the case body as `TextureTarget::Texture1D` and not the
sentinel, with the reader's gate on `Kind` spelled out**; a renderbuffer point carrying the
sentinel; the `PipeFields.def` row proved live by making `MGPipeVerify(MGPSurface, …)` name
`"TextureTarget"`; and the two depth-stencil numbers, including
`MGPTextureParams{}.DepthStencilMode == kMGPipeDepthStencilModeDepth`.
---
## 3. Gates — every number
Run in `~/w7/p4a-contract`, `CCACHE_BASEDIR=/home/swung/w7`, `-j 8`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` exported for every ctest lane. All three build
dirs (`build-linux` pull, `build-push`, `build-verify`) already existed and were rebuilt
incrementally; 0 compiler errors, 0 new warnings attributable to this commit.
| gate | result |
|---|---|
| **(a) G1** `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` | **rc 0 — 0 added / 0 removed / 0 resized / 0 renamed.** `.text` 10806323 -> 10806323 (+0, +0.000%); `.data` 76840 -> 76840; `.bss` 1296872 -> 1296872; `.rodata` 1536538 -> 1536538; total 17226471 -> 17226471; file 19114360 -> 19114360 bytes. 27811 -> 27811 defined symbols, 27072 -> 27072 normalised names, **27072 unchanged (name, size and mangling all identical)**. The admitted set stays EMPTY. |
| **(b) unit, pull** `ctest --test-dir build-linux -L unit` | **rc 0, 100% passed, 0 failed out of 1638** |
| **(b) unit, push** `ctest --test-dir build-push -L unit` | **rc 0, 100% passed, 0 failed out of 1638** |
| unit, verify `ctest --test-dir build-verify -L unit` | **rc 0, 100% passed, 0 failed out of 1638** (extra lane, not required) |
| the two new cases, each lane | **2/2 passed** in build-linux, build-push and build-verify (neither is skipped in a pull build) |
| ctest names pull == push | `diff` empty, **1638 == 1638** |
| names vs `~/w7/p4a-before-ctest-names.txt` (whole suite, `LC_ALL=C`) | **0 removed**, 16 added, 2588 -> **2604**. The 16 = c0's 13 + c0b's 1 + **c0c's 2** (`PipeCatalogue.SubDataTargetPacksAResourceTargetAndAnUploadTarget`, `PipeCatalogue.SurfaceNamesItsKindItsTextureTargetAndItsDepthStencilAspect`). |
| **(c) G5** `p3a_untouched_regions.sh 37da3c3a HEAD` | **rc 0**, the eleven pool / deferred-release / ring / flush-drain functions byte-identical |
| **(d)** `check_include_closure.py --mode both --compiler clang++ --self-test --require-all --expect-probes 4` | **rc 0 — 4 probes, 0 skipped, 0 problems, 6 negative controls tripped.** value-header 66 (text) / 654 (clang) headers, artifacts-header 65 / 653, mutation-header 84 / 1, wire-header 2 / 42; 0 forbidden everywhere; all four self-contained under `-fsyntax-only` (`/usr/sbin/clang++`) |
| **(e)** `gen_pipe_dirty_surface.py --check` | **rc 0** — 79 mutators all mapped, no stale rows, 0 COARSE, **2 UNDECIDED** (the same `BindVertexArray <- NEW_VERTEX_ELEMENTS` and `UseProgram <- NEW_SHADER` c0 left listed), 26 prose answers. `--self-test` rc 0, 27 negative controls all tripped. This commit does not touch the dirty surface; the row set is unchanged from c0b. |
| `gen_pipe.py --check` | **rc 0**, generated files up to date; 71 calls, 72 verify payloads, 63 PipeInputs fields, 69 verbs, 477 inventory rows, 0 UNMAPPED |
| `gen_pipe.py --self-test` | **rc 0**, 7 negative controls tripped |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | **rc 0** |
### 3.1 The `PipeFields.def` trip wire, proved both ways
Because this commit is the second one in P4a to turn a `Pad<n>` into a meaning-carrying member,
both directions of `gen_pipe.py`'s guard were driven on a scratch edit and reverted (backed up
by file copy, **not** `git checkout` — a `git checkout` here reverts the whole uncommitted
change, which is how the first attempt at this control lost the edit and had to be re-applied):
* row removed, member kept -> **rc 1**,
`MGPSurface: member(s) with no F(...) in PipeFields.def: TextureTarget`
* member renamed back to `Pad0`, row kept -> **rc 1**,
`MGPSurface: F(...) name(s) that are not members: TextureTarget`
Tree restored and re-verified clean before the commit; the builds and the whole gate table
above were then re-run end to end against the restored tree, so every number in §3 is from the
exact bytes that were committed.
---
## 4. Rework list, per in-flight package
Every package's rework/verification round rebases onto `refs/heads/feat/disaggregated` once c0c
is integrated (ID-11). What each has to do:
### B — clientfb — **delete three helpers and five constants, fill one field**
`MobileGL/MG_Impl/Pipe/TextureEmit.h` and `FramebufferEmit.h` are in the **same namespace**
(`MobileGL::MG_Pipe`) as `MGPipeTypes.h`, so after the rebase the copies are redefinitions and
the build fails loudly. Delete, do not keep and do not rename:
* `TextureEmit.h` ~lines 148-185: `MGPipePackSubDataTarget`, `MGPipeSubDataResourceTargetOf`,
`MGPipeSubDataUploadTargetOf`, their `static_assert`, and
`kMGPipeDepthStencilModeDepth` / `kMGPipeDepthStencilModeStencil`.
**Keep** `MGPipeDepthStencilModeByte(GLenum)` — the GLenum decision is B's; it now reads the
contract's two constants. **Keep** `MGPipeTextureStorageKindForTarget`, untouched by c0c.
One signature note: the contract's `MGPipePackSubDataTarget` takes `Uint32 uploadTarget`, so
a call passing a `MobileGL::TextureUploadTarget` still compiles (implicit conversion is not
available for a scoped enum — **add `static_cast<Uint32>(...)` at each call site**, which is
the documented spelling).
* `FramebufferEmit.h` ~lines 70-80: `kMGPipeSurfaceKindNone`, `kMGPipeSurfaceKindTexture`,
`kMGPipeSurfaceKindRenderbuffer` and their `static_assert`.
**Keep** `MGPipeResolveAttachmentUploadTarget` — the resolution is B's.
* `MGPipeBuildSurface` gains the new field, one statement per field as its own comment
requires: texture arm `surface.TextureTarget = static_cast<Uint16>(texture->GetTarget())`
(whatever B's accessor for the attachment's `MobileGL::TextureTarget` is), renderbuffer arm
and the `IsEmpty()` early return `surface.TextureTarget = kMGPipeSurfaceNoTextureTarget`.
Note the empty arm returns a value-initialised `MGPSurface`, which carries **0, not the
sentinel** — set it explicitly, or state in the comment that `Kind == None` makes it
unreadable. B's own G7 scripted control (drop one member from the conversion and expect the
suite to go red naming it) should now cover `TextureTarget` too.
* B keeps emitting `MGPTextureParams::DepthStencilMode` through its helper; nothing else moves.
### C — clientsp — **nothing**, unless it reads `MGPSurface`
C owns Sampler/Image/Program emit. It does not build `MGPSurface` and does not emit
`resource_subdata`. If any C file kept a private copy of the depth-stencil constants (it should
not — that field is B's `MGPTextureParams`), delete it. Otherwise: no rework.
### D — esprytobj — **decode the high byte, move the four masks onto `TextureTarget`**
* `FindPipeTextureUpload(record, uploadTarget, level)` (`Managers.cpp` ~3745) and the consume
site `ConsumePipeTextureUpload` (~3757) match `pending.UploadTarget` against the value the
applier stored from `MGPSubData::Target`. That field is now **packed**: the applier's
`PendingUpload::UploadTarget` must be filled with `MGPipeSubDataUploadTargetOf(record.Target)`
(wire's side) and/or D must compare against the decoded byte rather than the whole field.
Whichever side does the decode, the comparison must be
`pending.UploadTarget == MGPipeSubDataUploadTargetOf(...)` — a bare
`static_cast<Uint16>(TextureUploadTarget)` match against the raw field is now wrong for every
texture whose resource target is non-zero, i.e. all of them.
* The long comment at `Managers.cpp` ~6033 ("THE UPLOAD-TARGET ENCODING is
`static_cast<Uint16>(TextureUploadTarget)`, which is what package B must emit into
`MGPSubData::Target`'s cube-face half; it is recorded as a deviation because the contract left
it unstated") is now stale — the contract states it, and it states the **packed** form. Rewrite
it to name `MGPipeSubDataUploadTargetOf` and drop the deviation note.
* DV-5's four cross-object masks (`IsSnormFallbackAttachment`, `IsUnormFallbackAttachment`,
`IsAlphaWidenedColorAttachment` and their sibling) can stop reading the frontend attachment
objects and read `MGPSurface::InternalFormat` + `MGPSurface::TextureTarget` instead, gated on
`Kind == kMGPipeSurfaceKindTexture`. `ShouldUseCaveatTextureFormat` /
`BackendTextureFormatAddsAlpha` stay byte-identical (D-N) — what changes is where their
`target` argument comes from, and it now comes from the record rather than from a guessed
inverse. Keep the G1 macro discipline (DV-9): these are value sites, not new lambdas.
* Where D compares a resource target out of `MGPSubData::Target` (the buffer-vs-texture branch),
either keep testing the whole field `== kMGPipeResourceTargetBuffer` — still correct — or use
`MGPipeSubDataResourceTargetOf`. Do not open-code `& 0xFF`.
### E — esprytdraw — **`SyncAttachmentObject` reads `TextureTarget`**
DV-7's blocker is gone. `SyncAttachmentObject` (`DirectGLES.cpp`) can resolve the texture and
renderbuffer twins from `MGPSurface::Res` now that the record carries the target the resolution
needs; gate on `Kind`, and treat `kMGPipeSurfaceNoTextureTarget` as "not a texture" rather than
as a target value. DV-1/DV-7/DV-8's other halves are unchanged C.7 boundary notes.
### wire — **nothing**
`SubDataNamesABuffer` matches `MGPSubData::Target` verbatim against
`kMGPipeResourceTargetBuffer` and the packing is designed to keep that exactly right (§1.1's
`static_assert`). The only thing wire *may* want, and it is D's call above, is to store
`MGPipeSubDataUploadTargetOf(record.Target)` into `PendingUpload::UploadTarget` so D's two match
sites compare a byte against a byte. W1's defaulted `const MGPSubRegion*` tail is untouched.
### F — gates — nothing here; `p4a_untouched_regions.sh` is still F's to add (esprytobj DV-12).
---
## 5. Deviations from ID-12
**None on substance.** Two notes:
1. ID-12 asks for "an A-owned unit test file under `MobileGL/MG_Test/Pipe/`". No new file was
created: `PipeCatalogueTest.cpp` is the contract-owned suite c0b already extended, it is
where D-E1's size pin and D-A3's target-table case live, and adding a file would have meant
editing `MG_Test/Pipe/CMakeLists.txt`, which c0 deliberately wrote so no later package has to
come back to it. Two cases were appended instead.
2. `MobileGL/MG_Pipe/generated` needed no regeneration (§0). `gen_pipe.py` was run in both
`--check` and write modes and reports the files up to date, and `git diff --exit-code` over
the directory is rc 0.
@@ -0,0 +1,333 @@
# P4a contract — c0d (Tracker.h): the two cross-package under-fires clientsp review v1 found
**Commit `9ea44389e7219f74794eccb8a32586ba9b6f806c`** on `refs/heads/p4a/contract`, parent
`17db7598` (= c0c = the pipe head at the time of writing). Two files, +269 / -6:
`MobileGL/MG_Impl/Pipe/Tracker.h` and `MobileGL/MG_Test/Pipe/TrackerTest.cpp`.
`PipeFill.cpp` is **not** touched: neither fix needed the `wants()` dirty-to-subsystem map to
move (see §1.3 and §2.4 for why that is the answer rather than a shortcut). `DirtySurface.def`
is **not** touched either, and §4 is the evidence that it did not need to be.
---
## 0. What the commit does, in one paragraph
Two shutters in `Tracker.h` could not see the state they exist to guard. `glBindSampler` moves
bit **12**'s generation and nothing else, so bit **13** — the bit `bind_sampler_states` is
emitted off — never fired for a sampler bind. And bits **6/7/8** (plus bit 14's program half)
read `GetCurrentProgram()`, which is null for the whole life of a bound separable program
pipeline, so after the first walk on a fresh context the entire program family latched `0` and
never moved again however the pipeline was restaged. Both are under-fires, which the file's own
rule calls the fatal direction; both are fixed by **widening the shutter**, which is where
over-firing is free. Four cases in `TrackerTest.cpp` pin them.
---
## 1. Fix 1 — `glBindSampler` now reaches `bind_sampler_states` (C-M4)
### 1.1 The defect, re-derived on this tree
`PipeFill.cpp:2262-2263` gates `EmitSamplerStates` on `wants(MGPipeDirty::NewSamplers)` — bit
13. Bit 13's shutter was `Mix(textureParams, ctx.GetSamplingResolutionGeneration())`.
`glBindSampler` is `GL_Sampler.cpp:360 BindSampler_State`, and it makes exactly two state calls:
* `MG_State::pGLContext->NoteTextureUnitTouched((Int)unit)` (`GL_Sampler.cpp:369`) →
`Core.h:139` → `TextureState.h:78 NoteUnitTouched`, whose `bindingChanged` defaults to `true`,
so it does `++m_textureBindGeneration` on **every** call — bit 12's counter;
* `textureUnit.SetSamplerObject(...)` (`GL_Sampler.cpp:372` / `:384`) →
`TextureUnit.cpp:28-39`, which calls `pGLContext->BumpTextureBindGeneration()` — bit 12's
counter again.
The only two writers of `BumpSamplingResolutionGeneration` in the tree are **parameter** paths
(`SamplerObject.cpp`, `TextureObject.cpp`). So the review's failure scenario holds exactly as
written: `glBindSampler(3, a); draw; glBindSampler(3, b); draw` fires bit 12 twice and bit 13
zero times, and the server's `BoundSamplerStates[3]` keeps naming `a`'s CSO. There is no pulled
twin to rescue it — `bind_sampler_states` has none, unlike the view set — and Espryt mixes
`SamplerStatesSerial` into a per-draw cache key (`DirectGLES.cpp`, the `SamplerViewsSerial` /
`SamplerStatesSerial` mix beside the `set_sampler_views` suppressor note), so the stale set is
also what its memo keys on.
### 1.2 The change
`Tracker.h:515-517` (comment `:496-514`):
```cpp
now[Index(MGPipeDirty::NewSamplers)] = MGPipeMixShutter(
MGPipeMixShutter(textureParams, ctx.GetSamplingResolutionGeneration()),
ctx.GetTextureBindGeneration());
```
### 1.3 Why the shutter and not `PipeFill.cpp`'s gate — the choice, stated
The review offered two one-line fixes: mix bit 12's generation into bit 13's shutter, or gate
`EmitSamplerStates` on `wants(NewSamplers) || wants(NewSamplerViews)`. **The shutter is the
correct one**, on the derivation of the three unit sets that the brief's D-G2 table gives:
* A **sampler-state set** entry is "the unit's sampler CSO, or the null handle when the unit has
no `SamplerObject` — the texture's built-in sampler then applies". So the set is a function of
*which sampler object is bound at each unit*, plus *which texture is bound there* whenever the
unit has no sampler object and the built-in sampler is what applies. `GetTextureBindGeneration`
is precisely the counter over which texture or sampler is bound at which unit: `Core.h:143-146`
defines it as bumped whenever a texture bind/unbind/delete changes which texture is bound at a
unit, and `TextureState.h:88-99` records that every texture **and sampler** bind entry point
routes through the `NoteUnitTouched` that bumps it. It is **an input to the set**, not another
bit's private business, so mixing it in is a correction to a shutter that was reading too
little — not a coupling of two bits.
* A **sampler bind** changes the sampler-state set and, correctly, also the view set (mipmap
completeness depends on the effective sampler), which is why bit 12 was already right. A
**texture bind** changes both too when the built-in sampler is in play. The asymmetry the
review noted — bit 12 firing, bit 13 not — was never a design, only a gap.
* The gate variant leaves the shutter itself still wrong, and three other consumers read it:
`gen_pipe_dirty_surface.py` derives `DirtySurface.def`'s bit answers **from the shutter**
(§4), the per-bit fire tallies (`m_fires`) are published as a measurement, and
`MGPipeSubsystemForDirty` makes the push bitmask "a true per-subsystem A/B rather than
approximately". A bit gated on another bit's shutter measures neither of those honestly.
Cost of the extra fires: bit 13 now also fires on every plain texture bind. That is bounded by
the emitter's own set-hash suppressor — `MGPipeSetHashSuppressorInstance().ShouldEmit(
BindSamplerStates, hash)` in `SamplerEmit.h`'s `EmitSamplerStates` — which `MGPipeTypes.h:614` makes
mandatory for every `kVarTail set_*` for exactly this traffic (MC 26.2 rebinds the same sampler
at every texture-unit switch). An over-fire costs the 192-entry walk and one XXH64, not a wire
record.
---
## 2. Fix 2 — the program family under a separable pipeline (C-M5)
### 2.1 The defect
`Tracker.h`'s old program block opened `const auto& program = ctx.GetCurrentProgram();` and did
everything under `if (program)`. `Core.cpp:609-631 GetProgramForDraw` shows what an application
that drives `glUseProgram(0); glBindProgramPipeline(P)` gets: `m_currentProgram` is null and the
draw program is the pipeline's composite. So bits 6, 7 and 8 all computed `0`, matched the `0`
they latched on the first (`!m_primed`) walk, and never fired again for the pipeline's whole
life. `Tracker.h` contained no reference to `ProgramPipelineObject` at all.
Rendering was not wrong, and the review is right about why: `GetProgramForDraw` is
emitted-and-still-pulled, the residual fill copies it at every verb, and that is exactly why
`DirtySurface.def:319` rules `BindProgramPipelineObject` `kPulledEveryVerb`. What breaks at P4a
is the **handle protocol**: `glUseProgramStages` makes `GetProgramForDraw` build composite B,
`EmitShaderState` is never called, so B gets no `ShaderCso` handle and no `create_shader_state`
while `set_draw_program` keeps naming composite A — a program D and E will see that the handle
protocol never announced. And bit 8 never firing means `set_global_constants` is never sent for
a pipeline draw at all, where the pull rescues nothing.
### 2.2 The change
`Tracker.h:361-421` adds an `else if` arm on the effective program source; the reasoning
paragraph is `:305-344`, and the file's own header summary is updated at `:30-40`.
```cpp
} else if (const auto& pipeline = ctx.GetBoundProgramPipeline(); pipeline) {
using Pipeline = MG_State::GLState::ProgramPipelineObject;
static_assert(sizeof(Pipeline::DrawProgramSignature) == 2 * Pipeline::kGraphicsStageCount * sizeof(Uint64), ...);
static_assert(sizeof(Pipeline::UniformMirrorVersions) == 2 * Pipeline::kGraphicsStageCount * sizeof(Uint64), ...);
Uint64 stageLinks = static_cast<Uint64>(ctx.GetBoundProgramPipelineName());
Uint64 stageState = 0;
Uint64 stageImages = 0;
for (SizeT stage = 0; stage < Pipeline::kGraphicsStageCount; ++stage) {
const auto& staged = pipeline->GetStageProgram(static_cast<ShaderStage>(stage));
if (!staged) continue;
stageLinks = Mix(Mix(stageLinks, staged->GetLifetimeId()), staged->GetLinkVersion());
stageState = Mix(Mix(Mix(stageState, staged->GetBackendStateVersion()),
Mix(staged->GetUBOContentVersion(), staged->GetBlockBindingVersion())),
staged->GetUniformWriteSetVersion());
stageImages = Mix(stageImages, staged->GetImageUnitVersion());
}
shader = stageLinks;
stageState = Mix(stageLinks, stageState);
bindings = Mix(stageState, stageImages);
constants = stageState;
programImages = Mix(stageLinks, stageImages);
}
```
### 2.3 Why these fields, and why the loop instead of the two helper functions
* **`{lifetimeId, linkVersion}` per graphics stage IS `ComputeDrawProgramSignature()`**
(`ProgramPipelineObject.h:94-105`), the key the composite cache is keyed on. Bit 6 therefore
fires **exactly** when `GetProgramForDraw` would hand back a different composite — exactly when
a new `ShaderCso` handle has to be minted. These are the same non-artefact fields the plain
program arm reads and the ones `Core.cpp:634-644` calls out as not passing through
`ProgramObject`'s join gate, so the tracker's "must not force a compile" rule is intact: no
join, no flatten, no `Link()`.
* **The four per-stage counters are `ComputeUniformMirrorVersions()`'s content**
(`:123-141`) — `backendStateVersion`, `uboContentVersion`, `blockBindingVersion`,
`uniformWriteSetVersion`. Under SSO per-program state is written to the **stage** programs and
only reaches the composite through `RefreshCompositeUniforms`, so those are the counters bits 7
and 8 have to watch. `GetImageUnitVersion` is read per stage as well, because D-G4 asks bit
14's shutter to keep reading all three **frontend** counters rather than any server-side epoch.
* **`stageLinks` is mixed into `bindings`, `constants` and `programImages`.** A composite
*rebuild* hands back a brand-new `ProgramObject` with an empty default uniform block and no
backend state at all (`SetCachedDrawProgram` clears the mirror versions with it), so a shutter
watching only the per-stage state counters would let a rebuilt composite inherit the bindings,
the constants and the image units of the one it replaced.
* **The pipeline NAME is mixed in** because two pipelines can carry the same stage set and each
caches its own composite object, so the signature alone would let a `glBindProgramPipeline`
between two such pipelines pass without a fire.
* **The two helper functions are not called, and that is a gate constraint rather than a
preference.** `gen_pipe_dirty_surface.py`'s `resolve_reader` follows an accessor only through
`return m_member;`-shaped bodies; both `Compute*` helpers build a **local** array and return
it, which it cannot place. Calling them made bits 6/7/8/14 `UNRESOLVED`, which cost
`X(UseProgram, NEW_SHADER)` its writer-taint reason and **broke self-test negative control 6b**
(`BumpTextureBindGeneration -> NEW_GLOBAL_CONSTANTS` must read UNDER-FIRING, and an unresolved
shutter turns that verdict into UNDECIDED). Measured, not guessed: with the helper calls,
`--self-test` printed *"negative control 6b did NOT trip"*. Reading the fields directly keeps
every one of those bits derivable — which is the only mechanism that can catch the **next**
under-fire here — and the two `static_asserts` are what tie the spelled-out pairs back to the
functions they mirror.
### 2.4 The residual hole, recorded rather than hidden
A pipeline **name recycled** by `glDeleteProgramPipelines` + `glGenProgramPipelines` back onto
the same stage programs at the same link versions, with no other program-family change between
the two draws, produces the same shutter value for a different composite object. A
`ProgramPipelineObject` has **no lifetime id and no wire object at all** —
`DirtySurface.def:348-353` says so where it rules `MarkProgramPipelineForDeletion`
`kUnpublishedDestroy` — so there is nothing else in `Tracker.h`'s reach to mix. Closing it needs
a generation counter on the frontend object, i.e. an `MG_State` change, which is out of this
commit's file scope. It is stated in the header comment at `Tracker.h:337-344`.
### 2.5 Bit 14 moved too
`programImages` feeds `NewShaderImages`'s shutter, so the same null-`GetCurrentProgram()` hole
made bit 14's program term constantly 0 under a pipeline. It is fixed by the same arm. This is
the same family as clientsp minor **C-m1** (the emitters keying on `GetProgramForDraw()`), but it
is only the tracker half; C-m1's compute-pipeline half is still C's.
---
## 3. The tests (A-owned, `MG_Test/Pipe/TrackerTest.cpp`)
Four cases, all in the existing `TrackerWalk` fixture, and all four added to
`MGL_TRACKER_TEST_LIST` (`:79-82`) so G2's "the pull and push ctest name sets are identical"
holds — they are visible SKIPs in a pull build.
| case | line | what it drives, and what it pins |
|---|---|---|
| `TrackerWalk.ASamplerBindAloneFiresTheSamplerStateBit` | `:635` | Makes the two calls `BindSampler_State` makes, in its order (`NoteTextureUnitTouched` then `SetSamplerObject`), rebinding unit 3 from sampler 1 to sampler 2 with **no parameter write anywhere**. Asserts `NEW_SAMPLERS` **and** `NEW_SAMPLER_VIEWS` fire, and that the next walk is 0 (the widened shutter does not fire forever). |
| `TrackerWalk.ARestagedProgramPipelineFiresTheProgramBits` | `:662` | Binds a pipeline with no program in use (asserting `GetCurrentProgram() == nullptr` as the premise), reaches steady state, then does what `glUseProgramStages` ends in — one `SetStageProgram`. Asserts bits 6, 7 and 8, then 0. |
| `TrackerWalk.ARelinkOfAStageProgramFiresTheProgramBits` | `:691` | Same setup with a stage already installed, then a real `ProgramObject::Link()` through the entry point `glLinkProgram` drives. The link *fails* (no shaders attached) on purpose: the link-observable versions are bumped in Link()'s **prologue**, before every early-out, which is the invalidation contract. Asserts bits 6, 7, 8, then 0. |
| `TrackerWalk.UseProgramZeroLeavesTheBoundPipelineDrivingTheProgramBits` | `:723` | The shape an application writes: a program in use over a bound pipeline, then `glUseProgram(0)`. Asserts bit 6 fires on the **handover** (the draw's program source changed), that it then settles, and that a subsequent stage change reaches bits 6/7/8 — i.e. the pipeline is the source now. |
All four pass in **all three** build dirs (`build-linux` pull, `build-push`, `build-verify`):
`4/4, 100%`, none skipped in the pull build (they are the `MGL_DECLARE_PULL_SKIP` stubs there and
report as passed).
---
## 4. Item (3): the two UNDECIDED dirty-surface rows stay marked
`MGP_DIRTY_SURFACE_UNDECIDED_LIST` still carries `X(UseProgram, NEW_SHADER)` and
`X(BindVertexArray, NEW_VERTEX_ELEMENTS)`, and **nothing this commit learned makes either
decidable**, because neither mark is about the shutter side:
```
UNDECIDED, no verdict: BindVertexArray <- NEW_VERTEX_ELEMENTS (the write analysis is not complete
for this mutator: Bind() writes 'Access', which it never declares ...)
UNDECIDED, no verdict: UseProgram <- NEW_SHADER (the write analysis is not complete for this
mutator: DestroyProgramSlot() writes 'attachedShaders', which it never declares ...)
```
Both reasons are **writer-side taints** — a call resolved by name into a body with an
unplaceable non-`m_` write — and they are properties of the scanner, not of the rows. Widening
bit 6's shutter cannot touch either. The reason strings after this commit are **byte-identical
to the ones c0 left**, `--check` still reports exactly 2 UNDECIDED, and self-test control 21
("the two P4a undecided marks are still needed") and control 18 ("a stale mark") both still trip.
So `DirtySurface.def` is unchanged: **no row moved, and no mark outlived its reason.**
One thing worth recording for whoever revisits this: the marks are one edit away from becoming
*shutter*-side (§2.3) — if a later change makes bit 6 read something `resolve_reader` cannot
place, the `UseProgram` mark silently changes meaning while staying green, and control 6b is what
notices, on a different bit.
---
## 5. Gates — every number
Run in `~/w7/p4a-contract`, `CCACHE_BASEDIR=/home/swung/w7`, `-j 8`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` for every ctest lane. All three build dirs already
existed and were rebuilt incrementally. **0 compiler errors, 0 warnings** attributable to this
commit (`grep -ci warning:` over the whole build log = 0).
| gate | result |
|---|---|
| **(a) G1** `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` | **rc 0 — 0 added / 0 removed / 0 resized / 0 renamed.** `.text` 10806323 → 10806323 (+0, +0.000%); `.data` 76840 → 76840; `.bss` 1296872 → 1296872; `.rodata` 1536538 → 1536538; total 17226471 → 17226471; file 19114360 → 19114360 bytes. 27811 → 27811 defined symbols, 27072 → 27072 normalised names, **27072 unchanged**. This is the check that says the fix is in push-only code: `Tracker.h` is inside `#if MOBILEGL_PIPE_PUSH`, so a pull-build symbol moving would mean it was placed wrongly. |
| **(b) unit, pull** `ctest --test-dir build-linux -L unit -j 8` | **rc 0, 100% passed, 0 failed out of 1642** |
| **(b) unit, push** `ctest --test-dir build-push -L unit -j 8` | **rc 0, 100% passed, 0 failed out of 1642** |
| **(b) unit, verify** `ctest --test-dir build-verify -L unit -j 8` | **rc 0, 100% passed, 0 failed out of 1642** |
| the four new cases, each lane | **4/4 passed** in build-linux, build-push and build-verify |
| ctest names pull == push | `diff` empty, **2608 == 2608** |
| names vs `~/w7/p4a-before-ctest-names.txt` (`LC_ALL=C` on both sort **and** `comm`) | **0 removed**, **20 added**, 2588 → 2608. The 20 = c0's 13 + c0b's 1 + c0c's 2 + **c0d's 4**. |
| **(c) G5** `p3a_untouched_regions.sh 37da3c3a HEAD` (re-run on the commit, not the dirty tree) | **rc 0**, the eleven pool / deferred-release / ring / flush-drain functions byte-identical |
| **(d)** `check_include_closure.py --mode both --compiler clang++ --self-test --require-all --expect-probes 4` | **rc 0 — 4 probes, 0 skipped, 0 problems, 6 negative controls tripped** |
| **(e)** `gen_pipe_dirty_surface.py --check` | **rc 0** — 79 mutators all mapped, no stale rows, 45 render-state answers derived, **10 other (mutator, bit) answers derived**, **0 COARSE**, **2 UNDECIDED** (both marked, both with their pre-existing writer-taint reason), 26 prose answers |
| `gen_pipe_dirty_surface.py --self-test` | **rc 0**, **27 negative controls, all tripped**; positive controls OK |
| `gen_pipe.py --check` | **rc 0**, generated files up to date; 71 calls, 72 verify payloads, 63 PipeInputs fields, 69 verbs, 477 inventory rows, 0 UNMAPPED |
| `gen_pipe.py --self-test` | **rc 0**, 7 negative controls tripped |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | **rc 0** |
### 5.1 `integration-gpu -R DirectGLES`, before **and** after
Both runs are the full 491-test selection, both under 30 s, so the before side was taken for
real rather than by subset: `git stash push` of the two files → `cmake --build build-push` →
run → `git stash pop` → rebuild → re-ran the push unit lane to confirm the restored binary
(**100%, 0 failed out of 1642**).
| | tests | passed | failed | skipped | wall |
|---|---|---|---|---|---|
| **before** (`17db7598`, same build dir) | 491 | **100%** | **0** | 63 | — |
| **after** (`9ea44389`) | 491 | **100%** | **0** | 63 | 27.4 s (216.85 s·proc) |
The **skipped-test name sets are identical** (`diff` of the two sorted name lists is empty),
which is the check that matters here — a fix that turned a real case into a skip would otherwise
read as "no regression". **No regression.**
---
## 6. What packages B / C / D / E must know — which bit now fires when
**For C (clientsp / sampler-image-program) — the two majors it handed up are closed at the
source, so C's rework must NOT re-fix them:**
1. `NEW_SAMPLERS` (bit 13) now also fires on **any texture or sampler bind at any unit**
(`GetTextureBindGeneration`), not only on a sampler/texture *parameter* change. So
`EmitSamplerStates` is now reached for `glBindSampler` — the case C-M4 named — and also for
plain `glBindTexture` traffic. **C's set-hash suppressor is now load-bearing, not an
optimisation**: without it MC 26.2's per-batch rebinds become a variable-length record per
batch. C-m2's version-first skip in front of the CSO acquire is
worth more after this commit than before it — the extra fires land exactly on that path.
The `SamplerEmitTest` case that bumps `BumpTextureBindGeneration()` by hand and then calls
the emitter directly, now documents a path that really is reachable.
2. `NEW_SHADER` / `NEW_SHADER_BINDINGS` / `NEW_GLOBAL_CONSTANTS` (bits 6/7/8) and the program
term of `NEW_SHADER_IMAGES` (bit 14) now fire under a bound pipeline, on: a
`glBindProgramPipeline` to a different name; any `glUseProgramStages` that changes a stage; a
relink of any stage program; a `glUniform*` / `glProgramUniform*` / block-binding write to a
stage program; and `glUseProgram(0)` handing the draw to the pipeline. So `ProgramEmit.h`'s
`EmitShaderState` is now reached for composites, and **the composite resolver is reached the
way `CompositeResolver.h` expects** — which is what makes C-M1 (the `Live`/`Reset` early-return)
and C-M2 (the never-invalidated `(Cso, Version)` latch) reachable in practice rather than in
theory. C's rework should assume both are now on the hot path.
3. Nothing C owns needs to change *because of* this commit. `wants()`'s map is untouched, the
emitter entry points are untouched, and the subsystem assignment (`kMGPipeSubsystemSamplers`,
`kMGPipeSubsystemPrograms`) is unchanged.
**For B (clientfb / framebuffer-texture):** bit 13 firing on texture binds means the sampler
family's emitters now run on batches where only a texture moved. B's built-in-sampler `Acquire`
through C's cache (ID-14 / ID-15) is therefore exercised more often; the ref-count ruling in
ID-17 is what keeps that safe.
**For D (wire) and E (esprytdraw / esprytobj):** the important consequence is a **negative** one
— a re-composited program pipeline now gets a `ShaderCso` handle and a `create_shader_state`
*before* `set_draw_program` names it, so D's re-keyed twin tables will not see a program the
handle protocol never announced (`MGPipeSlots().FindByLifetimeId(ShaderCso, B)` will hit). E can
rely on `SamplerStatesSerial` advancing on a sampler bind, which is what its per-draw memo at
`DirectGLES.cpp` (the `SamplerViewsSerial` / `SamplerStatesSerial` mix) keys on; before this
commit that serial stood still across a
`glBindSampler`. Fire rates go up for bits 13 and 6/7/8, so the P4a fire-rate measurements
recorded against c0c are not comparable to ones taken after c0d.
**Rebase note:** every package rebasing onto pipe after c0d integrates gets `Tracker.h` at
`9ea44389`. Nobody but A may edit that file; a package that finds itself wanting to is looking at
a contract defect and should say so rather than patch around it.
@@ -0,0 +1,310 @@
# P4a contract fix c0e — `MGPipeFramebufferTarget::Named` and the metadata respecify
Branch `p4a/c0e`, worktree `~/w7/p4a-c0e`, based on `refs/heads/feat/disaggregated` = **17db7598** (c0 + c0b + c0c).
**One commit: `11446f35`.**
```
[Fix] (Pipe): key the framebuffer record to the object it names - a fourth Target value for every
DSA entry point that hands a framebuffer over by name, and the metadata-only respecify the sticky
bind mask needs
```
Files: `MobileGL/MG_Pipe/MGPipeTypes.h`, `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp` (+160 / −15).
No other file touched — `Tracker.h` and `PipeFill.cpp` are c0d's and were never opened for writing.
`PipeFields.def` is unchanged: nothing was renamed and no member was added, so `gen_pipe` has nothing to
regenerate.
---
## 1. The declaration wire v3 / B v2 / D v2 quote
`MGPipeTypes.h`, the enum immediately above `kMGPipeMaxColorAttachments`:
```cpp
enum class MGPipeFramebufferTarget : Uint8 {
Draw = 0,
Read = 1,
Both = 2,
// Describes the framebuffer named by Fbo and changes no binding (ID-19). Emitted
// ahead of every DSA entry point that hands that framebuffer over by name.
Named = 3,
Count,
};
```
`Count == 4`. Wire's existing validate point (`PipeApply.cpp:2046`, `state.Target >= Count` refuses) therefore
starts accepting 3 with no edit at that line — **wire v3's declared local constant for 3 is now retired** and
`MGPipeFramebufferTarget::Named` is spelled directly.
`MGPFramebufferState` is **unchanged in layout**: `MGP_ASSERT_POD(MGPFramebufferState, 304)` still holds and
`Uint8 Target` is the same byte. `Named` cost nothing on the wire — it is a fourth value of a byte that already
existed, which is why the applier can be given a per-object table without a payload change.
`MGPResourceDesc` is likewise unchanged (`MGP_ASSERT_POD(MGPResourceDesc, 88)`). **No field was added anywhere.**
## 2. The exact comment text (quote verbatim; it is the contract)
### 2.1 Above `enum class MGPipeFramebufferTarget`
```
// P4a, D-C2/D-C3 and ID-19: THE RECORD DESCRIBES A FRAMEBUFFER OBJECT, and Target says
// whether it ALSO moves a binding.
//
// A `Named` record describes the framebuffer object it names (Fbo) and changes NO
// binding. `Draw` / `Read` / `Both` records describe the same object AND set the bound
// handle(s) of the target(s) they name.
//
// The applier therefore keeps records PER FRAMEBUFFER OBJECT, keyed by the handle's slot
// (the generation is checked on lookup and a stale one refuses; a framebuffer has no wire
// lifetime - D-I2, the catalogue has no framebuffer delete - so a successor's record
// simply OVERWRITES the slot), plus the two bound handles. And every DSA entry point that
// hands a framebuffer to the server BY NAME - BlitNamedFramebuffer, the four
// ClearNamedFramebuffer*, and the DSA attachment / draw-buffer / read-buffer setters at
// their validate point - is PRECEDED BY A Named RECORD, so that any framebuffer the
// server is about to receive by name already has one.
//
// That last rule is the phase's main correction, not a nicety. With only the two
// bound-target records, glClearNamedFramebufferfv(fbo) on an unbound fbo made the backend
// mint a fresh driver framebuffer with NO ATTACHMENTS, find no record for it, decline,
// and then issue the clear against it anyway - GL_INVALID_FRAMEBUFFER_OPERATION and
// nothing cleared, where the legacy arm cleared correctly. Writing such an object into
// the bound-target record instead would have been worse: the applier would then claim it
// is bound.
//
// GL has two independent framebuffer bindings and one record carries one Fbo, so a
// Draw/Read pair is two records and one object bound to both targets is one record with
// Both. The draw-buffer array belongs to the OBJECT the record names; it reaches the
// driver's bound draw framebuffer only for a record whose Target is Draw or Both -
// Espryt's own comment records the Minecraft 26.x OIT bug where a READ-only sync landed
// glDrawBuffers on the wrong framebuffer - and a Named record's draw buffers are applied
// when that object is next configured, never to whatever happens to be bound. ReadSurface
// is resolved from THAT framebuffer's own read buffer in EVERY record, Named included,
// which is what makes the read-buffer-shared-FBO defect class unrepresentable rather than
// merely fixed.
//
// Target IS A ContentHash INPUT (the hash covers the whole record), and the emitter's
// suppressor must be keyed by the framebuffer the record names, not by one global slot:
// two different objects' Named records in a row must both go out, and a Named record must
// never be suppressed against the same object's bound record or the reverse.
```
### 2.2 Above `struct MGPFramebufferState` — the field-by-field statement (item 3)
```
// ONE RECORD DESCRIBES ONE FRAMEBUFFER OBJECT - the one named by Fbo - and Target says
// whether it also moves a binding (P4a, D-C2 as corrected by ID-19; see
// MGPipeFramebufferTarget above for the failure that forced it).
//
// A Named record describes that object and changes NO binding. Draw / Read / Both records
// describe that object AND set the bound handle(s) of the target(s) they name. The applier
// keeps these records PER FRAMEBUFFER OBJECT, keyed by Fbo's slot (generation checked on
// lookup; a framebuffer has no wire lifetime - D-I2 - so a successor's record simply
// overwrites the slot), plus the two bound handles; every DSA entry point that hands a
// framebuffer to the server by name is preceded by a Named record.
//
// WHAT Target CHANGES, FIELD BY FIELD. NO FIELD IN THIS RECORD REFERS TO "the currently
// bound framebuffer" - every one of them describes the object named by Fbo - and that is
// the invariant a reader depends on:
//
// Fbo, Color[], Depth, Stencil, ReadSurface, Width/Height/Layers/Samples,
// FixedSampleLocations, IsDefault, Complete
// properties of the object named by Fbo, identical in meaning under every Target.
// In particular ReadSurface is resolved from THAT framebuffer's own read buffer -
// on a Named record too - never from whichever framebuffer is bound to GL_READ.
// DrawBuffers[]
// a property of the named object; it reaches the driver's bound draw framebuffer
// only when Target is Draw or Both. Under Named it is stored with the object and
// applied when that object is next configured.
// Target
// the only binding-specific field: Draw/Read/Both name the binding(s) this record
// also sets, Named names none. It is a ContentHash input.
// ContentHash
// per RECORD, not per object, and the emitter's suppressor is keyed by the
// framebuffer named: a Named record must never be suppressed against the same
// object's bound record, nor one object's Named record against another's.
```
**Answer to item (3), stated plainly: exactly one field's meaning is binding-specific, and it is `Target`
itself.** Every other member describes the object named by `Fbo` under every `Target`. Two of them needed
their in-struct comments amended because they read as bound-relative before:
```cpp
// The RESOLVED read surface, not an index, and it is THIS framebuffer's own read
// buffer under every Target - Named included. This is what structurally closes the
// read-buffer-shared-FBO defect class.
MGPSurface ReadSurface;
// attachment index, -1 = NONE. The named object's array; applied to the bound draw
// framebuffer only when Target is Draw or Both.
Int8 DrawBuffers[8];
...
// MGPipeFramebufferTarget, above (P4a, D-C2; was Pad0). Draw/Read/Both also set the
// named binding(s); Named sets none (ID-19). The ONLY binding-specific field.
Uint8 Target;
...
// ... (existing ContentHash comment) ...
// Target is one of its inputs, and the suppressor is keyed per framebuffer.
Uint64 ContentHash;
```
No field was added. `MGP_ASSERT_POD(MGPFramebufferState, 304)` unchanged, `MGP_FIELDS_MGPFramebufferState`
unchanged.
### 2.3 Beside `MGPipeResourceRespecifyNeedsAck` — the metadata respecify (item 4, ID-18 M4)
```
// P4a, ID-18 M4: A RESPECIFY WHOSE STORAGE-DEFINING FIELDS ALL EQUAL THE STORED
// DESCRIPTOR IS A METADATA UPDATE, NOT A REALLOCATION.
//
// MGPResourceDesc::BindMask and ImageBindableHint are STICKY facts the client discovers
// AFTER allocation - a texture first bound as a shader image, first used as a render
// target - and they ride resource_create and every resource_respecify. An IMMUTABLE
// texture never has a later respecify, so without a rule those two would reach the server
// only by accident, or never; with one, a mask change after allocation emits a
// resource_respecify that REPEATS the storage the resource already has.
//
// The applier and both twins must classify such a record as a metadata update:
// - NO reallocation acknowledgement. MGPipeResourceRespecifyNeedsAck above still
// answers the per-record question, but a metadata update allocates nothing, so a
// record it classifies as metadata is not acked even when that predicate says the
// call may require one.
// - NO PendingUploads clear - not the whole vector, and not the redefined level either.
// This REFINES the level-scoped clear: identical storage fields clear NOTHING. (The
// level-scoped rule exists because clearing the whole vector on a level-1 definition
// silently dropped level 0's accepted texels; a metadata update must drop neither.)
// - The stored descriptor's BindMask and ImageBindableHint ARE updated - BindMask is
// sticky and therefore ORed, never replaced - and the twin re-derives its storage
// flags from the new mask on its next sync, recreating backend storage only where the
// backend actually needs it. The record itself is not a request to recreate.
//
// THE STORAGE-DEFINING FIELD SET, named here so that neither side has to guess and a
// later field cannot join it by silence. It is every MGPResourceDesc member except the
// three metadata ones and the padding:
//
// Target, StorageKind, InternalFormat, Width, Height, Depth, ArrayLayers, Levels,
// Samples, FixedSampleLocations, Immutable, Usage, StorageFlags, HasDefinedContent,
// ViewOf, BufferForTexBuffer, BufOffset, BufSize.
//
// `Resource` is the identity the stored descriptor is looked up BY, not a comparand. The
// three fields that may differ on a metadata update are exactly BindMask,
// ImageBindableHint and GlNameForDiag (diagnostics only, never an identity, never a memo
// key). HasDefinedContent is storage-defining ON PURPOSE: glBufferData(size, NULL) at an
// unchanged size is an orphaning reallocation and has to keep clearing, rather than being
// mistaken for a mask change. A field added to MGPResourceDesc must be placed in one of
// the two lists in the same commit - PipeCatalogue pins the struct's size for that.
```
A back-pointer sits at the fields themselves so a reader who starts at `MGPResourceDesc` finds the rule:
```cpp
Uint8 HasDefinedContent; // false after a NULL-data respecify - STORAGE-DEFINING
Uint8 ImageBindableHint; // client-side everImageBound; pre-emptive allocation
Uint16 Pad0;
// ImageBindableHint and BindMask above are the two METADATA fields the rule exists
// for: a respecify that moves only them - every storage-defining field equal to the
// stored descriptor - is a metadata update, with no reallocation ack and no
// PendingUploads clear. The rule, the full storage-defining field set and the third
// field allowed to differ (GlNameForDiag) are stated beside
// MGPipeResourceRespecifyNeedsAck below (P4a, ID-18 M4), which is where the applier
// and both twins read them from.
```
Two judgement calls consumers should know about, because they decide behaviour:
- **`HasDefinedContent` is storage-defining.** It is not a shape field, but `glBufferData(size, NULL)` at an
unchanged size is an orphaning reallocation. Classifying it as metadata would have made orphaning stop
clearing pending uploads.
- **`GlNameForDiag` is not.** It is diagnostics-only by the phase's own rule (a GL name is never an identity,
never a memo key, never a content-hash input), so a record differing only in it classifies as metadata,
which is correct — it allocates nothing.
- **No predicate function was minted.** The rule needs the applier's *stored* descriptor as its second
operand and this header sees only one, so the contract states the field set in prose and the applier owns
the comparison. If the integrator wants one authority for the comparison, the natural home is wire v3's
applier, written against the list above verbatim; c0e deliberately did not front-run it while wire v3 was
in flight.
## 3. Unit test (item 5)
No new test name — the two existing A-owned catalogue cases were extended, so the name inventory is
unchanged (see §4). `MGP_ASSERT_POD` untouched in both directions.
`PipeCatalogue.TextureParamsNameTheirBuiltinSamplerAndFramebufferStateNamesItsTarget` now pins all five
values plus the byte:
```cpp
EXPECT_EQ(sizeof(MGPFramebufferState), 304u);
EXPECT_EQ(static_cast<Uint8>(MGPipeFramebufferTarget::Draw), 0u);
EXPECT_EQ(static_cast<Uint8>(MGPipeFramebufferTarget::Read), 1u);
EXPECT_EQ(static_cast<Uint8>(MGPipeFramebufferTarget::Both), 2u);
EXPECT_EQ(static_cast<Uint8>(MGPipeFramebufferTarget::Named), 3u);
EXPECT_EQ(static_cast<Uint8>(MGPipeFramebufferTarget::Count), 4u);
EXPECT_LE(static_cast<Uint32>(MGPipeFramebufferTarget::Count), 256u);
EXPECT_EQ(sizeof(MGPFramebufferState::Target), 1u);
```
`Named` is pinned **by value** on purpose: the applier's only validation is `Target >= Count`, so an
enumerator inserted ahead of `Named` would silently re-point every Named record the client emits at `Draw`
or `Read` — and a Draw record for a framebuffer that is not bound is the exact corruption `Named` exists to
prevent. `Count == 4` is pinned for the mirror failure: a wire that still refused 3 would drop every DSA
record on the floor.
`PipeCatalogue.ResourceRespecifyAcksOnlyImmutableStorage` gained the tripwire for the prose rule — the
thing that would make the field list lie is a member added to `MGPResourceDesc` and classified into neither
list:
```cpp
EXPECT_EQ(sizeof(MGPResourceDesc), 88u);
EXPECT_EQ(sizeof(MGPResourceDesc::BindMask), 2u);
EXPECT_EQ(sizeof(MGPResourceDesc::ImageBindableHint), 1u);
EXPECT_NE(offsetof(MGPResourceDesc, HasDefinedContent),
offsetof(MGPResourceDesc, ImageBindableHint));
```
## 4. Gates (every number)
| gate | result |
|---|---|
| `symbol_report --threshold 0`, before `~/w7/p4a-before-libMobileGL.so`, after `build-linux/libMobileGL.so` | rc 0 — **0 added / 0 removed / 0 resized / 0 renamed**, 27811 → 27811 defined symbols, 27072 unchanged; `.text` 10806323 → 10806323 (+0, +0.000%); file bytes 19114360 → 19114360 (identical) |
| `ctest -L unit` in `build-linux` (pull) | rc 0 — **100% passed, 0 failed out of 1638** |
| `ctest -L unit` in `build-push` (`-DMOBILEGL_PIPE_PUSH=ON`) | rc 0 — **100% passed, 0 failed out of 1638** |
| test-name inventory (full `ctest -N`, `LC_ALL=C`) | 2604 pull == 2604 push; vs `~/w7/p4a-before-ctest-names.txt`: **0 removed / +16 added** — identical to ID-20's post-c0c number, i.e. c0e adds no name (G14 additions-only trivially holds) |
| `scripts/p3a_untouched_regions.sh 37da3c3a HEAD` | **rc 0** — the 11 pool / deferred-release / ring / flush-drain functions byte-identical |
| `gen_pipe.py --check` | rc 0 — 71 calls (11 screen, 60 context), 72 verify payloads, 63 PipeInputs fields, 69 verbs, 9 classes; inventory 477 rows, 0 UNMAPPED; generated files up to date |
| `gen_pipe.py --self-test` | rc 0 — 7 negative-control trips, positive control OK |
| `gen_pipe_dirty_surface.py --check` | rc 0 — 2 UNDECIDED (the two D6 rows, unchanged), 0 COARSE |
| `gen_pipe_dirty_surface.py --self-test` | rc 0 — 27 negative controls, all tripped; positive controls OK |
| `check_include_closure.py --compiler clang++` | rc 0 — 4 probes, 0 skipped, 0 problems (value 66 / artifacts 65 / mutation 84 / wire 2 headers, 0 forbidden each) |
| `check_include_closure.py --mode both --compiler clang++` (extra) | rc 0 — 4 probes, 0 skipped, 0 problems; all four SELF-CONTAINED OK under `-fsyntax-only` |
Builds: `build-linux` rc 0 (994 targets), `build-push` rc 0 (1007 targets), both Release + Ninja + ccache,
`CCACHE_BASEDIR=/home/swung/w7`, `-j 8`, `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` exported for the
build and test lanes.
## 5. Notes for the integrator
1. **Wire v3's local constant for `Target == 3` can be deleted at the rebase.** `MGPipeFramebufferTarget::Named`
exists and `Count` is 4, so `state.Target >= Count` accepts 3 with no change at the validate point.
2. **What c0e did NOT do, because the files were not granted.** ID-19(a) also asks for the D-K2 fourth row
("bit 10 requires bit 11") and G9-as-white-box to be recorded in the brief/docs. `docs/` and
`BRIEF-P4A.md` are outside my grant (my files were `MGPipeTypes.h` + the A-owned catalogue test), and
ID-15's own correction puts the fourth row's *implementation* in package D's texture-family
`Resolve*SubsystemArm`. Both still need an owner; neither is a contract-header edit.
3. **The per-object table's key.** The comment says "keyed by the handle's slot, generation checked on
lookup, a stale generation refuses, a successor's record overwrites the slot". Wire v3 should read that
as: the slot is the index, `Gen` is a validity test on read, and there is no removal path — consistent
with D-I2 (no framebuffer delete call) and with `ReleaseObjectRecords` clearing the whole table plus both
bound handles (wire m1).
4. **B v2's suppressor is now under-specified by its current shape.** `EmitFramebufferState` feeds one
global `MGPipeSuppressorSlot::SetFramebufferState` slot with a combined draw/read hash. A Named record
for an arbitrary framebuffer cannot share that slot: two different objects' Named records in a row would
suppress each other. The contract comment states the requirement (suppression keyed by the framebuffer
named); the mechanism is B's.
5. **B v2's `ReadSurface` build changes.** Today `BuildFramebufferState(fbo, readSurfaceSource, target, out)`
passes the *read* framebuffer as the surface source for a Draw record. Under this contract `ReadSurface`
is always the record's own framebuffer's read buffer, so the second parameter collapses into the first.
## 6. Housekeeping
Worktree `~/w7/p4a-c0e` **left in place** on branch `p4a/c0e` at `11446f35` (integrator rebases onto c0d and
fast-forwards). Nothing pushed. My build/round logs under `~/w7` (`p4a-c0e-*.log`) and my script directory
`~/w7/c0e-scripts` are removed; the shared WSL scratchpad was not touched. The build directories themselves
(`~/w7/p4a-c0e/build-linux`, `build-push`) are left inside the worktree.
@@ -0,0 +1,225 @@
# contract v6 — c0f: the four P4a families require a registered consumer (ID-39)
**Commit `29d51ab9`** on `p4a/c0f`, worktree `~/w7/p4a-c0f`, branched from
`refs/heads/feat/disaggregated` = `17396216` (contract c0..c0e + wire + clientsp v3 + clientfb v2 +
esprytobj v2). One commit, seven files, +570/-11. Not pushed.
```
[Fix] (MG_Pipe, MG_Impl): gate the four P4a families on a backend having registered
MGPipeResourceOps - Magma emitted, the applier accepted, and the acceptance-cleared dirty flags
left its legacy path nothing to upload
```
---
## 1. The defect, restated from the code
P3a's buffers have always had **two** conjuncts in their client gate — `PipeFill.cpp:612`
`MGPipeResourceSubsystemEnabled()` is `bit 7 AND MGPipeGetResourceOps() != nullptr` — and the
comment at `PipeFill.cpp:656` (now ~:700) spells out why the second one is load-bearing.
P4a's four families had only **one and a half**: `FamilyIsLive(subsystem, wired)` was the
operator's `MOBILEGL_PIPE_PUSH` bit AND the family's `kMGPipeWired*Subsystem` constant, with no
per-backend half at all. DirectVulkan (Magma) registers no `MGPipeResourceOps`
(`Managers.cpp:2556` is DirectGLES-only) and has none of P4a's twins, so with
`kMGPipeWiredTextureSubsystem = 1`:
1. the client emitted `resource_create` / `resource_respecify` / `resource_subdata` /
`set_texture_params` for every texture;
2. the applier **accepted** every one of them (a non-buffer resource row is stored and returned —
`MGPipeApplyResourceCreate`'s own comment says so);
3. the emitter cleared the level's per-level dirty flags on that acceptance (D-D5 as amended by
ID-18 M3);
4. Magma's legacy pull path then read `IsStorageDirty` and found nothing to upload.
66 texture-upload-shaped DirectVulkan integration-gpu cases red on the push build at the default
mask, pull build 966/966 green. This is B's own finding (1) from ID-35, applied to Magma.
---
## 2. (a) The client gate — `MobileGL/MG_Impl/Pipe/PipeFill.{h,cpp}`
| file:line | what |
|---|---|
| `PipeFill.cpp:882` | `kMGPipeP4aFamilySubsystems` = `Framebuffer | TextureResources | Samplers | Programs` (bits 9/10/11/12). Deliberately **not** `kMGPipeSubsystemsMigratedAtP4a` (0x1fff, every bit through P4a) — the rule belongs to the four families this phase adds and to no earlier one. |
| `PipeFill.cpp:920` | `Bool P4aFamilyHasItsConsumer(Uint64 subsystem)` → `(subsystem & kMGPipeP4aFamilySubsystems) == 0 \|\| MGPipeGetResourceOps() != nullptr`. A P2/P3a bit answers `true` unconditionally, so nothing that emits today changes. |
| `PipeFill.cpp:933-935` | `FamilyIsLive` gains the conjunct. This is the predicate **every** P4a birth hook resolves through (`MGPipeEmitTextureResourceCreate/Respecify`, `MGPipeEmitTextureParams`, `MGPipeNoteTextureLevelDirty`, `MGPipeEmitRenderbufferResourceCreate/Respecify`, `MGPipeEmitSamplerCsoCreate`, `MGPipeEmitSamplerViewCreate`, `MGPipeEmitShaderCsoCreate` — nine hooks, ~:1105-1170). |
| `PipeFill.cpp:2257` | `wants()` gains it as a fifth condition, so the seven walk-side emissions (`EmitFramebufferState`, `EmitShaderState`, `EmitSamplerViews`, `EmitSamplerStates`, `EmitShaderImages`, `EmitGlobalConstants`) are inert too. |
| `PipeFill.cpp:2329` | the `DrainTextureSubData` gate — the one with no dirty bit over it — gains it. This is the path whose acceptance clears the level flags. |
| `PipeFill.cpp:2408` | the residual fill's `supplied` conjunction gains it: "supplied" means *a call went out carrying this field*, and with no consumer none did, so withholding the pull would leave the field unfilled at the verb that reads it. (Inert today — `EmittedCallSuppliesTheWholeField` answers `false` for every P4a field; it is forward protection for the first one admitted.) |
| `PipeFill.cpp:1097` / `PipeFill.h:63` | `Bool MGPipeP4aFamilyEmits(Uint64 subsystem, Uint64 wired)` — the gate exported as an observable, returning `FamilyIsLive(...)` itself rather than a second copy. `wired` is a parameter because the constant lives in the family's emit header, which `PipeFill.h` may not include. Unit gate only. |
**The emit headers were not touched.** `MGPipeTextureRecordsReachTheApplier()` and its siblings are
compile-time (`constexpr`) restatements of the wired constant, and
`MGPipeTextureSubsystemEnabled()` / `MGPipeFramebufferSubsystemEnabled()` are B/C's runtime
copies; every path they guard runs *behind* `FamilyIsLive`, or (`RepublishMask`) behind
`MGPipeHandleIsPublished`, which no longer answers true. The single exception is documented in
(b).
**Bits 7 and 8 are untouched.** `MGPipeResourceSubsystemEnabled` and the vertex-input rows read
exactly what they read before.
**The register/unregister window** is the same one P3a lives with (`UnregisterBufferBackendOps`
nulls the table at context teardown, the re-register happens at the next MakeCurrent) and is
closed the same way: an object born in the window latches `Published = false`, and the family's own
self-healing create on the next respecify (`TextureEmit.h:576` / `:709`) publishes it. Written into
the comment at `PipeFill.cpp:914`.
**Make-current does not flap the gate.** `MGPipeApplierReset` explicitly does *not* clear
`g_resourceOps` (`PipeApply.cpp:1121`, and `ResourceEmit.TheResourceOpTableIsUnregisteredUntilA
BackendInstallsOne` pins it); `MGPipeApplierReleaseObjectRecords` does not touch it either and has
no non-test caller in the monolith. So the client's gate and the applier's belt read the same
signal and cannot disagree across a frame.
---
## 3. (b) The applier belt — `MobileGL/MG_Pipe/PipeApply.{h,cpp}`
`PipeApply.cpp:1116` `Bool NoP4aConsumer()` — `g_resourceOps == nullptr` → `++RefusedNoConsumer`,
return true. **Silent by design**: `RefusedResourceCalls` / `RefusedVertexInputCalls` /
`RefusedObjectCalls` each mean "a record named something this applier should have had" and a
non-zero value there is a seam defect; a non-zero value *here* is the designed steady state of a
backend with no P4a twins, so an `MGLOG_E_ONCE` would put an ERROR line in every ordinary Magma
run. The counter is the observable.
**Counter**: `MGPipeApplierState::RefusedNoConsumer` at `PipeApply.h:553`, beside the other three,
zeroed by `MGPipeApplierReset` (`PipeApply.cpp:1152`) like them.
**Fifteen entry points**, each returning `accepted = false` / declining:
| line | entry point | note |
|---|---|---|
| 1590 | `MGPipeApplyResourceCreate` | non-buffer target only — the buffer row is P3a's and its consumer question was already answered by the frontend |
| 1626 | `MGPipeApplyResourceRespecify` | non-buffer target only |
| 1759 | `MGPipeApplyResourceSubData` | the texture half; **the call whose acceptance clears the level flags** |
| 2255 | `MGPipeApplySetFramebufferState` | in front of `RecordAt` — see below |
| 2369 | `MGPipeApplyCreateSamplerState` | |
| 2428 | `MGPipeApplyCreateSamplerView` | |
| 2477 | `MGPipeApplySetTextureParams` | first in the body (it resolves before it validates) |
| 2535 | `MGPipeApplySetSamplerViews` | in front of `ApplyUnitWindow` |
| 2545 | `MGPipeApplyBindSamplerStates` | in front of `ApplyUnitWindow` |
| 2560 | `MGPipeApplySetShaderImages` | in front of `ApplyUnitWindow` |
| 2633 | `MGPipeApplyCreateShaderState` | after the blob rule, the slot bound and the verify round trip |
| 2670 | `MGPipeApplyBindShaderState` | first — the null-handle unbind is behind it too |
| 2727 | `MGPipeApplySetDrawProgram` | first |
| 2742 | `MGPipeApplySetDispatchProgram` | first |
| 2763 | `MGPipeApplySetGlobalConstants` | first (its bounds come out of the resolved program) |
Placement rule, written at `PipeApply.cpp:1108`: **after the record's own shape checks and before
anything moves**, so a malformed record stays `Fatal{ProtocolCorruption}` on every backend — a
trip wire that fires only on some backends is a trip wire nobody can trust. Two documented
exceptions: the three unit-set calls (`ApplyUnitWindow` validates and writes in one step, so the
question has to be asked in front of it), and the five entry points whose first act is a
resolution (asking after would report the designed state as `RefusedObjectCalls`).
**The death paths are deliberately not belted** — `resource_destroy`, `delete_sampler_state`,
`delete_sampler_view`, `delete_shader_state` are idempotent cleanup that must keep working
whatever the registration did, and with no consumer they find no record anyway. Asserted, so a
later commit that adds them has to change that line.
**One known, bounded residue**: for the four create-shaped calls the bound check *is* `RecordAt`,
which grows the table to the slot on its way to answering, so a refused create can leave a zeroed
non-live row behind. It costs nothing where it matters: on a backend with no consumer the client's
gate emits none of these, and the one record that reaches this applier *without* passing that gate
— `set_framebuffer_state`, published by name from `GL_Framebuffer.cpp:650`'s
`PipePublishFramebufferByName`, which calls the framebuffer emitter directly at the fifteen DSA
sites — is declined in front of its `RecordAt`. That direct call is also the reason the belt is not
redundant with the gate.
---
## 4. (c) Tests
| test | file | what it pins |
|---|---|---|
| `TextureEmit.WithNoBackendConsumerTheFamilyGateIsFalseAndNothingReachesTheApplier` | `MG_Test/Pipe/TextureEmitTest.cpp` | the **client** half. All four `MGPipeP4aFamilyEmits` rows false, `kMGPipeSubsystemVertexInput` still true; the handle is still minted but `MGPipeHandleIsPublished` is false, `CreateCount`/`RespecifyCount`/`SubDataCount` 0, `DrainListSize` 0, `TextureResources` empty, **`texture->IsStorageDirty(...)` still true**, and `RefusedNoConsumer == 0` (the *gate*, not the belt, is what stopped it). Second half: with the consumer back, create published, drain list 1, `SubDataCount` 1, `RefusedSubDataCount` 0, flag cleared. |
| `ResourceEmit.EveryP4aFamilyEntryPointDeclinesWhenNoBackendRegisteredTheConsumer` | `MG_Test/Pipe/ResourceEmitTest.cpp` | the **applier** half. All fifteen entry points driven with no table: `RefusedNoConsumer == 15` (the number is the assertion — an entry point added later that forgets the belt fails this line), the other three refusal counters and `StaleFramebufferRecordLookups` all 0, nothing live in any of the five object tables, `FramebufferRecords` empty, the three unit windows 0, the three program bindings null. Then with a table: every one lands, the counter does not move, and the two death paths run uncounted. |
**Fixture change, and why.** The five P4a emit suites and `ResourceEmitTest`'s texture/renderbuffer
case drive the emitter/applier pair as they behave under a backend that *consumes* the records —
the shipped DirectGLES configuration — so they now install the same signal that backend installs:
an empty `static const MGPipeResourceOps` registered in `main()` of `TextureEmitTest.cpp` and
`FramebufferEmitTest.cpp`, and a scoped `ScopedResourceOps` in `ResourceEmitTest.cpp`'s
`TheThreeResourceKindsKeepTheirOwnSlotSpaceAndDoNotSeeEachOther`. The table is empty because none
of its hooks is on a non-buffer path (every non-buffer row is stored and returned, never
dispatched), so what the registration changes is the consumer question and nothing else; neither
file constructs a `BufferObject`. The two cases above take it away again
(`ScopedNoResourceOps` / the un-scoped arm). `SamplerEmitTest`, `ProgramEmitTest`, `ImageEmitTest`
and `CompositeResolverTest` needed nothing. `ResourceEmit.TheResourceOpTableIsUnregisteredUntilA
BackendInstallsOne` is unchanged and still asserts `nullptr` at entry.
### Mutations (run, not committed)
| # | mutation | result |
|---|---|---|
| M1 | `FamilyIsLive` drops `&& P4aFamilyHasItsConsumer(subsystem)` | `TextureEmit.WithNoBackendConsumer...` **RED** (1/1 failed). The 54-case DirectVulkan texture subset stayed **green** — because the belt then caught every record, which is exactly the belt's job. |
| M2 | `NoP4aConsumer()` never fires | `ResourceEmit.EveryP4aFamilyEntryPointDeclines...` **RED** (1/1 failed). |
| M3 | the walk-side conjuncts removed (`wants()` + the drain gate), `FamilyIsLive` kept | DirectVulkan **475/475 green** — reported honestly: with the birth hooks gated, the drain list is empty and the walk-side rows clear no client flag, so those two conjuncts are defence in depth (and the `supplied` one is forward protection), not independently lane-proved. Both are kept because ID-39 names them and because a family that later emits from the walk without a birth hook would otherwise be ungated. |
---
## 5. Gate numbers (all on `~/w7/p4a-c0f` @ `29d51ab9`)
| gate | result |
|---|---|
| builds | `build-linux` rc 0, `build-push` rc 0 |
| **G1 `symbol_report --threshold 0`** vs `~/w7/p4a-before-libMobileGL.so` | **0 added / 0 removed / 0 resized / 0 renamed**; `.text 10806323 -> 10806323 (+0, +0.000%)`; 27811 -> 27811 defined symbols |
| **G5 `scripts/p3a_untouched_regions.sh 37da3c3a HEAD`** | **rc 0** — "byte-identical between 37da3c3a and HEAD" |
| `gen_pipe.py --check` | rc 0 — "generated files are up to date" |
| `gen_pipe_dirty_surface.py --check` | rc 0 |
| `gen_pipe_dirty_surface.py --self-test` | rc 0 — 27 negative controls, all tripped |
| `check_include_closure.py --compiler clang++` | rc 0 — 4 probes, 0 skipped, 0 problems |
| `ctest -L unit` build-linux | **100%, 0 failed of 1762** (was 1761; +1, the ResourceEmit case is a visible SKIP in the pull build) |
| `ctest -L unit` build-push | **100%, 0 failed of 1763** (was 1761; +2) |
| **`ctest --test-dir build-push -L integration-gpu -R DirectVulkan -j 8`** | **100% tests passed, 0 failed out of 475** — was 409/475 (66 failed) on the same tree before the fix, measured here as the baseline |
| `ctest --test-dir build-push -L integration-gpu -R DirectGLES -j 8` | 98%, **8 failed of 491 — the gate's exact eight, unchanged** |
### The DirectGLES eight, unchanged and unchased
Identical set and identical count to `~/w7/p4ag-igpu-push.log` (which reported 74 = 66 DirectVulkan
+ 8 DirectGLES out of 966):
- six `DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.*` (Subprocess aborted) — the 0x1ff
itest pins, package F's;
- `DirectGLES.SampledSetStalenessScenario.AQueuedClearIsMaterialisedWhenASamplerObjectCompletesTheTexture`;
- `DirectGLES.IntegerBorderColorScenario.SamplerParameterIivBorderColourSurvivesToAnIntegerSampler`.
**No DirectGLES case was fixed or broken by c0f**, which is what the design predicts: DirectGLES
registers the table unconditionally at `RegisterBufferBackendOps`, so every predicate answers
exactly what it answered before.
---
## 6. What packages B / C / D / E must know
- **Nothing changes on Espryt.** DirectGLES registers `MGPipeResourceOps` at bring-up,
unconditionally, so `FamilyIsLive`, `wants()`, the drain gate and all fifteen applier entry
points behave exactly as they did at `17396216`. Every existing assumption, counter and lane
number holds.
- **On Magma the client now emits nothing for bits 9/10/11/12.** The legacy pull path runs
untouched, exactly as on a pull build. Do not write a scenario that expects a P4a record to
exist on DirectVulkan.
- **B**: `TextureEmit.h`/`FramebufferEmit.h` are unchanged. Your emitters are simply not called on
a backend without the table; `MGPipeHandleIsPublished` stays false there, so the death helpers
emit nothing and your self-healing creates (`:576` / `:709`) are what recover if a table appears
later. `RepublishMask`'s own `MGPipeTextureSubsystemEnabled()` is now a second, weaker gate — it
is harmless because the `MGPipeHandleIsPublished` test beside it already answers false.
- **B, and this one matters**: `GL_Framebuffer.cpp:650`'s `PipePublishFramebufferByName` is the
**only** P4a emission in the tree that does not pass through `PipeFill`. On a backend with no
consumer those Named records reach the applier and are declined by the belt (counted in
`RefusedNoConsumer`, silent). If you want them gated at the client instead, the gate to add is
`MGPipeGetResourceOps() != nullptr` in `MGPipeFramebufferSubsystemEnabled()` — your file, your
call; the belt makes it optional rather than required.
- **C**: `SamplerEmit.h` / `ImageEmit.h` / `ProgramEmit.h` unchanged; the CSO cache is never
reached on a backend with no consumer because the hooks that call it are gated upstream.
- **D / E**: the applier gains one member, `MGPipeApplierState::RefusedNoConsumer`
(`PipeApply.h:553`). It is **not** a seam-defect counter — do not fold it into the eight-family
"zero refusals" census on the integrated tree, which is about `RefusedResourceCalls`,
`RefusedVertexInputCalls`, `RefusedObjectCalls` and `StaleFramebufferRecordLookups`. On Espryt
it must read **0**; on Magma a non-zero value is the designed state (framebuffer Named records
only, per the point above).
- **F**: the P4a A/B arms are unaffected — the conjunct is per-backend, not per-mask, and every
subsystem-control and dependency-refusal scenario runs on DirectGLES.
- **New test-suite convention**: `TextureEmitTest` and `FramebufferEmitTest` register an empty
`MGPipeResourceOps` for the whole binary; a case added to either that wants the no-consumer arm
must scope it off (`ScopedNoResourceOps` exists in `TextureEmitTest.cpp`).
@@ -0,0 +1,217 @@
# contract v7 — c0g: D-K2's dependency table, on the client (S-3 / ID-41)
**Commit `29bd4d2c`** on `p4a/c0f`, worktree `~/w7/p4a-c0f`, rebased onto
`refs/heads/feat/disaggregated` = `588b2277` (contract c0..c0f + wire + clientsp v3 + clientfb v2
+ esprytobj v2/v3). One commit, four files, +392/-46. Not pushed.
```
[Fix, Test] (MG_Impl, Pipe): gate the four P4a families on D-K2's dependency bits as well -
Espryt refuses bit 10 without bit 11 or bit 7, but the client had already emitted and the
acceptance-cleared level flags left its legacy arm nothing to upload
```
---
## 1. The defect (S-3), restated from the code
Espryt's four `Resolve<Family>SubsystemArm()` functions (`Managers.cpp:3595` / `:3642` / `:3698` /
`:3735`) REFUSE a family whose D-K2 dependency bit is clear and run the legacy arm instead — the
shape `ResolveVertexInputSubsystemArm`'s bit-8-requires-bit-7 refusal set as the precedent, and the
one ID-15 extended with the fourth row.
That refusal is a **backstop** and it cannot restore a correct picture on its own, because the
client's emission was gated on the operator's mask **alone**: at `0x7ff` (bit 10 set, bit 11 clear)
the client emitted the whole texture family, the applier accepted it, the emitter cleared each
level's per-level dirty flag on that acceptance (D-D5 as amended by ID-18 M3) — and *then* the
server refused bit 10 and ran a legacy path with nothing left to upload. **438/491** on the
DirectGLES lane, the same 47 texture-upload failures ID-39 saw on Magma for the consumer-less
version of the identical mistake (c0f).
This is c0f's rule one signal over, so it is written with c0f's rule: with a dependency unmet the
client emits **NOTHING** for that family and the legacy pull path runs untouched — *nothing at all,
not less*.
---
## 2. The dependency table, as coded
`MobileGL/MG_Impl/Pipe/PipeFill.cpp:950-1055`, immediately under `kMGPipeP4aFamilySubsystems` and
`P4aFamilyHasItsConsumer()`, in the same anonymous namespace, with the D-K2 reasons as comments:
```cpp
struct P4aFamilyDependencyRow {
Uint64 Family; // exactly one bit, and it is one of kMGPipeP4aFamilySubsystems
Uint64 Requires; // the bits MOBILEGL_PIPE_PUSH must ALSO carry for it to be live
};
inline constexpr P4aFamilyDependencyRow kMGPipeP4aFamilyDependencies[] = {
{kMGPipeSubsystemFramebuffer, kMGPipeSubsystemTextureResources},
{kMGPipeSubsystemTextureResources, kMGPipeSubsystemResources | kMGPipeSubsystemSamplers},
{kMGPipeSubsystemSamplers, kMGPipeSubsystemTextureResources},
{kMGPipeSubsystemPrograms, 0},
};
```
| family | requires | why (the comment on the row) |
|---|---|---|
| bit 9 framebuffer | bit 10 | every `MGPSurface::Res` names a Texture or Renderbuffer handle and only bit 10 populates those two slot tables (`ResolveFramebufferSubsystemArm`) |
| bit 10 textures | bit 7 **and** bit 11 | a buffer texture's `MGPResourceDesc::BufferForTexBuffer` names a Buffer handle and only bit 7 puts twins in the resource slot table (D-D1); and `MGPTextureParams::BuiltinSampler` is a `SamplerCso` HANDLE, only bit 11 mints sampler CSOs, and the applier's verdict for a null one is `Fatal{ProtocolCorruption}` (D-K2's FOURTH row, ID-14/ID-15) |
| bit 11 samplers | bit 10 | every `MGPBoundView::Texture` and `MGPImageView::Res` names a Texture handle and only bit 10 populates that slot table (`ResolveSamplerSubsystemArm`); with the row above this is SYMMETRIC — bits 10 and 11 are one arm with two switches |
| bit 12 programs | — | a `ShaderCso` handle names no texture and no buffer. The empty row is written out so the table covers the four families exhaustively rather than by absence |
**The mirror pairs that stay fine**, stated in the code beside the table (Managers.cpp:2377-2381's
own argument: an unreachable branch that says something different is how the reachable one drifts):
- bit 10 set, bit 9 clear — FINE; the legacy FBO sync reaches the texture twin through
`SyncTextureObjectToBackend`, which dispatches to the handle arm by itself;
- bit 11 set, bit 9 clear — FINE, for the same reason: a sampler view names a texture, never a
framebuffer;
- bit 7 set, bit 10 clear — FINE, and it is P3a's shipped configuration;
- bit 12 with any or none of 9/10/11 — FINE, per the last row;
- bit 10 set, bit 11 clear (and its mirror) — **NOT** fine; it is the row above, and it is the one
sentence in the brief that P4a as built withdrew.
**The rows are NON-TRANSITIVE, on purpose.** Espryt's resolvers classify their arms from
`MOBILEGL_PIPE_PUSH` alone, so the table asks the question they ask — *is the dependency BIT set* —
and never *is the other family live*. At `0x7ff` that means the framebuffer family stays LIVE on
both sides while the texture family is dead on both sides, which is the state the two must agree
on; a client that withheld more than the server refuses would leave the server's handle arm live
with no records to read, and a client that withheld less is the defect above. The `0x7ff` arm below
confirms the choice empirically (485/491, no framebuffer-shaped fallout).
**Five `static_assert`s pin the table** rather than leaving it to a reader: every P4a family has a
row (coverage `==` `kMGPipeP4aFamilySubsystems`), each of the four rows' required mask is spelled
out again by name, no row may name its own family, and `kMGPipeSubsystemsMigratedAtP4a` (0x1fff)
must satisfy every dependency the table declares — so the shipped arm cannot be narrowed by any of
this, and the table can only ever narrow a hand-picked A/B mask.
The predicate consulted at the four sites:
```cpp
Bool P4aFamilyDependenciesAreSet(Uint64 subsystem, Uint64 pushMask) {
const Uint64 required = P4aFamilyDependencyBits(subsystem); // the table, folded
return (pushMask & required) == required;
}
```
The mask is a parameter, not a read, so the walk's single read of `MG_Config::Features.PipePush`
stays the one read a whole validate point resolves against.
---
## 3. The sites — the same four c0f joined
| file:line | site | what |
|---|---|---|
| `PipeFill.cpp:1068` | `FamilyIsLive(subsystem, wired)` | the fourth conjunct. This is the predicate every P4a birth hook resolves through (nine hooks, :1253-1304) |
| `PipeFill.cpp:2399` | `wants()` in the walk | a sixth condition beside c0f's fifth; the seven walk-side emissions are inert |
| `PipeFill.cpp:2474` | the `DrainTextureSubData` gate | the one with no dirty bit over it — **the path whose acceptance clears the level flags**, i.e. where S-3 actually bit |
| `PipeFill.cpp:2555` | the residual fill's `supplied` conjunction | "supplied" means a call went out carrying this field; at a mask with a dependency clear none did, so withholding the pull would leave the field unfilled at the verb that reads it |
| `PipeFill.h:46-71` | `MGPipeP4aFamilyEmits(subsystem, wired)` | the exported observable's contract, widened from three conjuncts to four; it still returns `FamilyIsLive` itself (`PipeFill.cpp:1232`), never a second copy |
Bits 7 and 8's existing rules are untouched — read only.
---
## 4. Tests (`MG_Test/Pipe/TextureEmitTest.cpp`, beside the c0f case)
| test | what it pins |
|---|---|
| `TextureEmit.WithTheSamplerBitClearTheTextureFamilyGateIsFalseAndNothingReachesTheApplier` | the **0x7ff shape** end to end: bit 10 set, bit 11 clear → gate false; the handle is still minted (the mint stays unconditional) but not published; `CreateCount`/`RespecifyCount` 0, `TextureResources` empty, `DrainListSize` 0, `SubDataCount` 0 after an explicit drain, **`IsStorageDirty` still true**, and `RefusedNoConsumer == 0` (the *gate*, not c0f's belt, is what stopped it). Second half: with bit 11 back, the same sequence lands and the flag clears |
| `TextureEmit.WithTheBufferResourceBitClearTheTextureFamilyGateIsFalseAndNothingReachesTheApplier` | the D-D1 half of the same row: bit 10 set, bit 7 clear, identical assertions |
| `TextureEmit.EveryDKTwoDependencyRowGatesItsOwnFamilyAndTheMirrorPairsStayLive` | the table itself, one row per family, through `MGPipeP4aFamilyEmits`: all four live when every dependency is met; bit 9 and bit 11 both false without bit 10; bit 10 false without bit 11 **while bit 9 stays true at that same mask** (the non-transitivity, asserted rather than assumed); bit 10 false without bit 7 while bit 11 stays true; bit 12 live entirely on its own; the mirror pairs (10+11 without 9 = the 0xdff arm; bit 7 alone) ; and `kMGPipeSubsystemVertexInput` still true with bit 7 clear — P2/P3a's rules are not narrowed |
All three names were added to the pull-build skip list `MGL_TEXTURE_EMIT_CLIENT_TEST_LIST` at the
top of the file, and **both builds compile** (ID-40's lesson): `ctest -N` gives 2732 names in
`build-linux` and 2732 in `build-push`, diff 0.
**Two fixtures had to arm bit 7**, and this is the one thing outside `PipeFill.*` the commit
touches. `TextureScope` (`TextureEmitTest.cpp`) armed bits 10|11 and `FramebufferScope`
(`FramebufferEmitTest.cpp`) armed bits 9|10|11 — both were arming a mask D-K2 forbids, which the
server would have refused and which the client now refuses too, so without bit 7 every case in both
suites would have gone green for the wrong reason (an emitter that emits nothing). Both now arm
`kMGPipeSubsystemResources` as well, with the row quoted in the comment. Neither file constructs a
`BufferObject`, so bit 7 changes nothing else in either suite (both suites: 37/37 and 22/22).
### Mutations (run, not committed)
| # | mutation | result |
|---|---|---|
| M1 | `FamilyIsLive` drops `&& P4aFamilyDependenciesAreSet(subsystem, pushMask)` | `TextureEmit` **3 failed of 37** — exactly the three new cases (`WithTheSamplerBitClear…`, `WithTheBufferResourceBitClear…`, `EveryDKTwoDependencyRow…`). Reverted: 37/37 |
| M2 | the texture row drops `kMGPipeSubsystemResources` (bit 7) | **does not compile**: `PipeFill.cpp:1020: static assertion failed … P4aFamilyDependencyBits(kMGPipeSubsystemTextureResources) == (kMGPipeSubsystemResources \| kMGPipeSubsystemSamplers)`. The row-by-row `static_assert`s are load-bearing, not decoration. Reverted, build rc 0 |
---
## 5. Gate numbers (all on `~/w7/p4a-c0f` @ `29bd4d2c`)
| gate | result |
|---|---|
| builds | `build-linux` rc 0, `build-push` rc 0 (**both compile** — ID-40's lesson) |
| **G1 `symbol_report --threshold 0`** vs `~/w7/p4a-before-libMobileGL.so` | **0 added / 0 removed / 0 resized / 0 renamed**; `.text 10806323 -> 10806323 (+0, +0.000%)`; `.data`/`.bss`/`.rodata` all +0; 27811 -> 27811 defined symbols |
| **G5 `scripts/p3a_untouched_regions.sh 37da3c3a HEAD`** | **rc 0** — "the 11 pool / deferred-release / ring / flush-drain functions are byte-identical between 37da3c3a and HEAD" |
| `scripts/gen_pipe.py --check` | rc 0 — inventory 477 rows, 0 UNMAPPED, "generated files are up to date" |
| `scripts/gen_pipe_dirty_surface.py --check` | rc 0 |
| `scripts/gen_pipe_dirty_surface.py --self-test` | rc 0 — 27 negative controls, all tripped |
| `scripts/check_include_closure.py --compiler clang++` | rc 0 — 4 probes, 0 skipped, 0 problems |
| **`ctest -L unit` build-linux** | **100%, 0 failed of 1766** |
| **`ctest -L unit` build-push** | **100%, 0 failed of 1766** |
| **G2 `ctest -N` pull vs push** | pull 2732, push 2732, **diff 0 lines** |
| G14 vs `~/w7/p4a-before-ctest-names.txt` | 0 removed, 144 added (+3 over the tree this branched from) |
---
## 6. The arms
Every DirectGLES arm is `ctest --test-dir build-push -L integration-gpu -R DirectGLES -j 8` with
`MOBILEGL_PIPE_PUSH` set as shown.
| arm | before c0g | **after c0g** | classification |
|---|---|---|---|
| `0x7ff` (bit 10 set, bit 11 clear — S-3's own mask) | **438/491** | **485/491** | the six pinned `.Handles` aborts only |
| `0x1fff` (the P4a default) | 485/491 | **485/491** | the same six |
| `0x3ff` (bit 9 set, 10/11/12 clear) | — | **485/491** | the same six |
| `0x5ff` (bit 10 set, 9/11 clear — ID-15's arm) | — | **485/491** | the same six |
| `0x9ff` (bit 11 set, bit 10 clear — G12's pair) | — | **485/491** | the same six |
| `0xdff` (bits 10+11 set, bit 9 clear — the mirror pair) | — | **485/491** | the same six |
| **DirectVulkan**, default mask | 475/475 | **475/475** | **0 failed** |
The failing set is **byte-for-byte identical across all six DirectGLES arms** (same six names, same
md5 of the sorted list, count 6 every time):
```
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
```
all `Subprocess aborted`, all `Fatal{PipeLegacyMemosDisabled}` — the **0x1ff itest pins, package
F's**, closed by F's pin move. **Nothing else fails at any arm**, on either backend.
Note the two DirectGLES sampler-seam failures of ID-39 are gone at every arm here: that is D's S-1
fix, already on `588b2277`, not c0g.
---
## 7. What the other packages must know
- **The client and the server now say the same thing about a mask.** Espryt's four
`Resolve<Family>SubsystemArm()` functions are unchanged and remain the backstop; the client's
table is their mirror, bit for bit and non-transitively. If a row is ever added or changed on one
side it must be changed on the other, and `PipeFill.cpp`'s `static_assert`s name each row so the
change cannot be silent.
- **F**: the `0x5ff` dependency-refusal scenario still asserts the refusal *line* and the legacy
arm running, and that is still true; what changes is that the surrounding lane at that mask is
now green too (485/491, the pins only) — esprytobj-v3's "read F-v2-m2 as 'the scenario', not
'the lane'" caveat is discharged. The suggested arms for F's dependency-refusal coverage are
`0x5ff` / `0x9ff` / `0x7ff` / `0xdff`, all measured above.
- **B / C**: no emit header was touched. A suite that arms a hand-picked `MOBILEGL_PIPE_PUSH`
must now arm a mask D-K2 permits — `TextureScope` and `FramebufferScope` were both fixed here,
and any new emit suite that arms bit 10 needs bits 7 and 11 with it.
- **D / E**: `RefusedNoConsumer` still reads 0 on Espryt and the dependency gate never touches it
— a dependency is refused by the client's gate, so no record reaches the belt at all.
- **The shipped arm is unchanged.** `kMGPipeSubsystemsMigratedAtP4a` = 0x1fff carries every
dependency the table declares (a `static_assert`), so the default mask, the pull build and every
P2/P3a bit behave exactly as they did at `588b2277`.
@@ -0,0 +1,530 @@
# P4a package E — `esprytdraw`. Adversarial review, v1
Reviewed: `refs/heads/p4a/esprytdraw` `98bdfa3e..0b00f7f0` (five commits) against the tag
`refs/tags/p4a/contract` (`08192d72`). One file, `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp`,
+893/−38. Read-only; no experiment worktree was needed (every question below was answerable by
reading the tree, the contract headers and package D's `Managers.{h,cpp}` in `~/w7/p4a-esprytobj`).
All line numbers are **HEAD (`0b00f7f0`) line numbers in `DirectGLES.cpp`** unless a path is given.
## Verdict: **REWORK** (three bounded code fixes in E's own file + one item to hand to D)
The package is strong: the arm shapes are right, the memo re-keying is argued rather than asserted,
the two byte-identical D-N regions and P2's `RenderStateImpl` sha reproduce exactly (I recomputed
them, §7), the macro/`#undef` hygiene is clean, and §0's `MGPipeApplierReset` finding is real and
load-bearing for D. What forces a rework round is three places where the handle arm **narrows what
reaches the driver** in the one direction the package's own DEV-3 argument forbids, plus two seam
checks that are silent and therefore cannot be policed by the check §8 itself mandates.
Everything ID-15 called out — the silent declines — is *specified* below rather than counted as a
rework item, because ID-15 assigns those flips to E's verification round. The decline table (§2) is
the deliverable for that round.
---
## 1. Findings by severity
### MAJOR-1 — the image sweep's membership can be smaller than the set of units the driver holds
`SyncImageTextureBindings`, **2519-2537**. The handle arm replaces
`for (unit = 0; unit < unitCount; ++unit)` with `for (unit = ShaderImageStart; unit < min(Start +
Count, unitCount); ++unit)` and then `return`s, so **no unit outside the received window is visited
at all**.
Failure scenario. The sweep exists for exactly one reason, written at 2544-2556 and 2601-2612: an
image unit is established *eagerly* by `glBindImageTexture` and is never revisited, so a texture
re-minted under it (`RecreateBackendTexture`) leaves the unit pointing at a **deleted driver texture
name**. Program P binds an image at unit 5 and dispatches; program Q, which declares only unit 0,
is then used. If `set_shader_images` is the *program-resolved* set — which is what E's own text calls
its sibling at 1828 ("the resolved per-unit view set") and what makes the ContentHash suppressor
worth having — Q's window is `[0,1)` and unit 5 is skipped by the sweep. A re-mint between the two
dispatches then leaves unit 5 bound to a dead name; on Adreno a stale image binding is a write
through a freed allocation, and on Mali the dispatch is rejected with `GL_INVALID_OPERATION`. The
pre-handle sweep bound *every* unit precisely so this could not happen. The same code is reached
unconditionally from `PrepareForCompute` (**5267**), which is the dispatch path where image units
matter most.
Refutation attempted, and why it fails. (a) *"D-J2 says the var-tail window IS the bound."* D-J2 and
`PipeApply.h:461-464` are a rule about **record retention** — entries outside the window are not
cleared *in the applier*. They say nothing about which **driver** units a re-issue sweep must visit;
the correct membership for that is "every unit the driver currently has an image on", which is
`g_imageUnitHighWaterMark` and is server-owned by construction. (b) *"The client emits Start = 0 and
Count = the image high-water mark + 1"* (the comment at 2525). That is an assumption about package C
that is written nowhere in the contract, is not listed among E's own seven assumptions in §3 of the
result, and is not checkable on this tree. (c) The decisive one: this is the **identical failure
direction** E refused to accept for `keys.maxTouchedUnit` in DEV-3 — "a window that is larger costs a
walk over provably-empty units, while one that is SMALLER silently drops [work] … which no gate on
this tree can see". DEV-3's reasoning applies verbatim here and was not applied.
Fix (E's file, ~2 lines): sweep `[min(Start, 0), max(Start + Count, g_imageUnitHighWaterMark))`
clamped to `unitCount` — i.e. union the record's window with the backend's own high-water mark — or
drop the record window here entirely and keep the record for the *values* only (which is `e3`'s real
deliverable). Add A8 to §3 naming C's `Start`/`Count` semantics for `set_shader_images` so the rebase
has something to reconcile against.
### MAJOR-2 — the sampler walk leaves a stale `glBindSampler` on every unit outside the window
`BindCurrentUnitSamplers`, **4357-4363**. On the record arm a unit in `[0, maxTouchedUnit]` but
outside `[SamplerStateStart, SamplerStateStart + SamplerStateCount)` is `continue`d: neither bound
nor unbound.
Failure scenario. The pre-handle arm's `else { SamplerImpl::UnbindSampler(unit); }` (**4390-4394**)
exists with its reason in the source: *"a sampler object left on the unit by an earlier draw keeps
being applied, and on a multisample texture — which takes no sampler object at all — the draw is
rejected outright."* Draw 1 binds sampler S to unit 3 (window `[0,4)`); draw 2 uses a program whose
resolved window is `[0,1)`; unit 3 keeps S bound. If unit 3 then holds a multisample texture the
draw is rejected by the driver; otherwise it silently samples with the wrong filter/wrap/compare.
This is the same defect class the `else` branch was added to close, reintroduced on the new arm.
Refutation attempted. Same three as MAJOR-1, and additionally: *"a `Start` above 0 is the client
saying it is describing a sub-range."* Even granting that, the units **below** `Start` are then
undescribed and keep whatever an earlier draw left, which is the same hole. The only shape that is
safe is "the window is always `[0, maxTouched+1]`", and if that is the contract it should be asserted
here rather than assumed.
Fix (E's file, ~3 lines): `UnbindSampler(unit)` for units outside the window instead of `continue`,
which is what the record's absence means for a *driver* binding; or refuse the arm when the window
does not cover `[0, maxTouchedUnit]` and fall through to the frontend walk (a full decline, per the
package's own §1 invariant).
### MAJOR-3 — two of the three seam checks are silent, so §8's mandated grep cannot see them
The framebuffer seam check logs (**2713-2717**, `"A framebuffer record does not describe the binding
it names"`). The other two do not:
* **image**, `ResolveShaderImageRecord` **2369**: `if (view.Res != HandleOf(boundTexture)) return
nullptr;` — the result's §4 calls this check *"not optional"*, and it is the one guarding the eager
`glBindImageTexture` funnel against binding one texture with another's level/layer/format. It
returns null in silence, which is indistinguishable from "the client half has not landed".
* **program**, `ResolveGlobalConstantsRecord` **3699**: `if (record->Desc.Cso != handle) return
nullptr;` — described in the source as *"the seam where a mis-keyed emission becomes visible
instead of becoming a wrong upload"*. It is not visible; it is a silent fallback to `MapUBO()`.
The package's own post-rebase item §8.2 says *"`grep 'does not describe the binding it names'` in the
itest and retrace logs must be empty; a hit means a client emission is mis-keyed and is a finding
against B/C"*. As built, that grep can only ever see the framebuffer seam. Two of the three seams are
unpoliceable, and a mis-keyed `set_shader_images` or `set_global_constants` from B/C would land as
"the arm did nothing", i.e. as a perf regression, not as a defect.
Refutation attempted: *"the checks still prevent the wrong pixels, which is their job."* True, and
that is why this is MAJOR and not CRITICAL — but a check whose whole purpose is to surface a
cross-package seam defect, in a phase whose integration plan is "each package gets a real-path
verification round on the integrated tree", must be observable. The framebuffer one shows the right
shape; the other two just need it.
Fix: one `MGLOG_E_ONCE` each with the same wording stem so one grep covers all three.
### MAJOR-4 (hand to D) — `InvalidateFramebufferHandleArmMemos()` is called *beside* the six call sites, not *inside* `InvalidateFramebufferBindingCache`
E adds the new call next to all six `FramebufferImpl::InvalidateFramebufferBindingCache()` sites in
`DirectGLES.cpp` (6402, 6920, 7022, 10979, 11426, 11962 — I verified all six are paired). But
`InvalidateFramebufferBindingCache` is defined in `Managers.cpp:7107` and has **three further
callers E cannot reach**: `MobileGL/MG_Test/SanityTest.cpp:2530` (`ScopedStateGuardMocks::
ResetShadows`), `:2778` and `:2799` (`ScopedBackendTwinMocks` ctor/dtor). Those three now clear the
pre-handle trio and leave `g_fboSyncedSerials` and `g_fboRecordsTrusted` stale across a GLES function
table swap — exactly the state a fixture installs mocks to control.
Harmless on E's tree (every arm declines). On the integrated tree with bit 9 set, a `SanityTest` case
that swaps the funcs table mid-test can be entered with `g_fboRecordsTrusted == true` and a memo
claiming a target is synced at the current serial, so `BindCurrentFBO` binds from a record while the
mock table is installed. Refutation attempted: *"`ScopedBackendTwinMocks` also clears on the way
out."* It clears the wrong half both times.
Fix belongs in D's file: call `InvalidateFramebufferHandleArmMemos()` from **inside**
`InvalidateFramebufferBindingCache` so no caller can forget. Until D lands, E should at minimum note
it in §3 as an eighth assumption. (E cannot fix this itself — `Managers.cpp` is D's for the phase.)
### MINOR-1 — the source claims the read buffer is applied "from the record's own `ReadSurface`"; it is not
**2801-2815**. The comment says *"the read buffer … is applied from the record's OWN ReadSurface.
That is what makes the read-buffer-shared-FBO defect class unrepresentable rather than merely
fixed"*. The code calls `backendObj->SyncReadBufferToBackend(currentFBO)` — the **frontend object**.
`MGPFramebufferState::ReadSurface` is read nowhere in the diff (I grepped the whole change: E reads
only `Fbo`, `IsDefault`, `Target`, `DrawBuffers[]` and `ContentHash`).
What the change actually achieves is real and worth having: the `lastUpdatedFBO` *pointer compare*
becomes a `record.Target == Both` **field test**, so the skip can no longer be produced by an
accident of loop order. That is "the defect class is now expressed as a field" — not
"unrepresentable". The distinction matters because the brief and ID-12 both lean on the structural
claim. Rewrite the comment, or read `ReadSurface` (which is the D-C1 endpoint anyway).
### MINOR-2 — ID-12's "E's `SyncAttachmentObject` reads `MGPSurface::TextureTarget`" is misassigned
ID-12 (DV-5) says *"B's rework fills it; D's rework moves the four cross-object masks onto it; **E's
`SyncAttachmentObject` reads it**"*. `SyncAttachmentObject` is `Managers.cpp:7142` (tag) /
`:7947` (esprytobj) — **package D's file**, which C.7 gives to D for the whole phase, and E's own
DEV-1 says so. E's diff contains no `MGPSurface` read at all. Package D's own source agrees the
ownership is confused: `~/w7/p4a-esprytobj/MobileGL/MG_Backend/DirectGLES/Managers.cpp:8603` says
*"the array itself retires with the frontend attachment objects, which is **E's**
`SyncAttachmentObject` work"*.
Integrator action: reassign the `MGPSurface::TextureTarget` reader to D explicitly, or grant E
`Managers.cpp`'s `SyncAttachmentObject` for one commit. As things stand nobody owns it and the c0c
field would land unread.
### MINOR-3 — `ForceBindCurrentFBO` stamps a record-keyed memo from a path that never consults the record
**4028-4035**. `StampSyncedFramebufferSerial(target, FramebufferSerial)` runs whenever bit 9 is set,
after `SyncAndBindFramebufferObject(fbo, target)` synced the **frontend object**. The memo it writes
means "this target reflects the applier's record as of this serial", and nothing here checked that
the record describes this binding.
Failure scenario I could construct, and its refutation: draw with FBO Y at serial S (record@S = Y,
memo stamped); `glBindFramebuffer(X)`; a DSA clear runs `ForceBindCurrentFBO(Draw)`, syncs X, and
re-stamps DRAW at S; `glBindFramebuffer(Y)`; next draw — the client suppresses the re-emission
(ContentHash unchanged), so the serial is still S, `FramebufferRecordMatchesBinding` passes (record Y
== binding Y) and `SyncedFramebufferSerialIsCurrent` skips Y's sync. **I could not make this go
wrong**: Y's driver FBO state was correct from the earlier sync at S, and any edit to Y would move
its ContentHash and hence the serial. What *is* wrong at that point is
`g_alphaWidenedDrawBufferMask`, which now describes X — but the pre-handle arm has the same hole, so
it is not a regression.
Recorded because it is a real invariant break with no demonstrable failure: the safe and cheaper
form is `g_fboSyncedSerials[target].valid = false` (one extra sync at worst) rather than a stamp that
claims something this path did not verify.
### MINOR-4 — the `PipeStats` gate cannot distinguish the two arms, so §8.1's "hit rate → 100%" is not measurable
**1869-1872** ticks `Gate::EsprytUnitBindingsEpoch` with `hit=true` when the records answer, and then
`return`s. The decline path falls through to the walk arm, which ticks **the same gate** with its own
`hit=true` (1887) / `hit=false` (1892). So a fully declining tree still reports a high hit rate on
that gate, and §8's *"`Gate::EsprytUnitBindingsEpoch` hit rate should go to 100%"* cannot separate
"the record arm engaged" from "the walk arm's memo hit". Tick `hit=false` on the record-arm decline
before falling through (or add a distinct gate) so the verification round has a real signal.
### MINOR-5 — the four local arm latches carry a D-K2 mirror sentence that ID-15 has since refuted
**221-250**. `EsprytDrawTextureResourceHandlesEnabled()` is `bit 10 && bit 7` and its comment states
the dependency directions "verbatim". ID-15 adds a **fourth** D-K2 row — **bit 10 requires bit 11** —
because `MGPTextureParams::BuiltinSampler` is a SamplerCso handle, only bit 11 mints sampler CSOs,
and a null there is Fatal. D's mirror in `esprytobj/Managers.h:631-636` still says the opposite out
loud (*"The mirror pairs (10 without 11, 10 without 9, 7 without 10) are all FINE and are said so out
loud"*), and D's rework has to change that sentence. E's four latches will be **deleted** at the
rebase (A4 / §8.7), so the missing row is not a runtime defect in E — but the comment must not be
copied forward, and the reviewer of the rebase should check that the deletion actually happened
rather than the latches being "kept and updated".
E's other three directions match D's mirror exactly: bit 11 → bit 10 (`EsprytDrawSamplerHandles`
238-246), bit 9 → bit 10 (`EsprytDrawFramebufferHandles` 230-236), bit 12 → nothing
(`EsprytDrawProgramHandles` 248-252). ✓
### Refuted — things I chased and could not turn into findings
* **`g_fboRecordsTrusted` staleness.** `BindCurrentFBO`'s handle arm trusts a latch set by the last
`SyncCurrentFBO`. I checked **all ten** `BindCurrentFBO` call sites (4091, 5323, 7256, 7257, 8010,
8105, 8708, 8754, 8770, 8783, 10359) and every one is preceded by `FramebufferImpl::
SyncCurrentFBO()` in the same function, with no GL entry point in between. `BindCurrentFBO` has no
caller outside `DirectGLES.cpp`. The claim holds.
* **Out-of-bounds `st.BoundSamplerStates[index]` at 4364** (no size check, unlike
`ResolveShaderImageRecord`'s at 2367). Refuted by contract: `PipeApply.h:461-464` — *"Start + Count
above the bound is `Fatal{ProtocolCorruption}`"* — and `kMGPipeMaxTextureUnits = 192` equals
`TextureState::MAX_TEXTURE_IMAGE_UNITS = 192`, so `maxTouchedUnit <= 191`. Safe. The asymmetry with
2367 is cosmetic.
* **`DrawBuffers` decode.** `record.DrawBuffers[i] >= 0` at **3739-3743** is correct: the field is
`Int8 DrawBuffers[8]; // attachment index, -1 = NONE` (`MGPipeTypes.h:556` region). Had it been
`Uint8` the broadcast count would have pinned at 8 on every draw. It is not.
* **Dangling `slot` pointers in the new `g_readFboTextureSyncList`.**
`FramebufferObject::GetAllAttachmentObjects()` returns `const FramebufferAttachmentObjectArray&`
(`MG_State/GLState/FramebufferState/FramebufferObject.h:131`), so `&textureObject` is stable, and
`PairingsIntact` is applied to the new list exactly as to the two existing ones. No finding.
* **Exit-order (ID-8).** The new statics are `Array<SyncedFramebufferSerialMemo,…>` (POD), four
`Bool`/`Uint64` scalars, and `Vector<UnitTextureSyncEntry>`; `UnitTextureSyncEntry` holds three
**raw** pointers, so no new static holder of a frontend `SharedPtr` is introduced. Observation only:
E's new D-F3 paragraph at **87-101** formally names the pre-existing
`g_rawDepthFetchSamplerState` file-static `SharedPtr<MG_State::GLState::SamplerObject>` as the
largest surviving `MG_State` usage under `MG_Backend/DirectGLES`. That *is* ID-8 "leak-at-exit
storage" by the letter of the rule; it is pre-existing at 37da3c3a and owned by P3b/P4b, but now
that it is written down the integrator should confirm P4a's `tcache_count=0` lanes still show zero
Fatal rather than letting the new comment imply it was audited.
* **The unit texture sync list keyed on a serial that can miss a frontend rebind.**
`keys.unitBindingsEpoch` becomes `Mix(SamplerViewsSerial, SamplerStatesSerial)`, which moves only
when the *resolved* set moves, while the list's **membership** is still the frontend binding walk
(DEV-4). I constructed: unit 5 empty → texture T bound to unit 5, program samples only unit 0, so
the resolved set and hence the serial do not move, `maxTouchedUnit` unchanged, `PairingsIntact`
sees no entry for unit 5 → the list is replayed without T. Refuted as harmless: T is not sampled by
this draw, and any later program that samples unit 5 moves the resolved set and rebuilds the list.
`PairingsIntact` (1938-1943) catches every *swap* on an existing entry, and
`g_unitTextureSyncListMaxUnit` is still frontend-derived (DEV-3), so the two escapes the walk arm
covered are both covered here. **Put it on the verification list anyway** (§5.4) — it is the one
place where the four "free" re-keyings are not obviously equivalent.
* **A missing-record partial run in `SyncCurrentFBOByRecord`.** The `!currentFBO` branch at
**2752-2756** `continue`s with `g_fboRecordsTrusted` already true and then `return true`, which
violates §1's "a decline is a full fallback". Refuted as unreachable: `FramebufferRecordMatchesBinding`
(2674-2681) maps `!bound` to `boundIsDefault = true`, so a non-default record with no bound FBO is
already rejected at 2713. Left as a decline-table flip (D4) rather than a finding.
---
## 2. The decline-site table, and the verification-round flip for each
Classification: **M** = "the client has not switched this family on" (the mask says so) — legitimate,
stays silent. **S** = seam defect once the bit is on and B/C have landed — must become LOUD.
**K** = a memo-key selection, not a behavioural decline — stays silent.
| # | site (`DirectGLES.cpp`) | condition | today | class | verification-round flip |
|---|---|---|---|---|---|
| F1 | 2800 | `EsprytDrawFramebufferHandlesEnabled()` false | silent | **M** | none; becomes `FramebufferSubsystemEnabled()` (D) |
| F2 | 2709-2711 | `DrawFramebuffer.Fbo` **or** `ReadFramebuffer.Fbo` null | **silent** | **S** | `MGLOG_E_ONCE` naming *which* target is unrecorded, then decline. A half-described applier (one target only) must be loud too — it is the shape a partially-landed emitter produces |
| F3 | 2713-2717 | seam: record vs binding mismatch | **loud** ✓ | S | keep verbatim; it is the wording §8.2 greps |
| F4 | 2752-2756 | non-default record, nothing bound | loud, but `continue`s | S | `g_fboRecordsTrusted = false; return false;` — a full fallback, per §1 |
| F5 | 3906 | `record.Fbo` null under `g_fboRecordsTrusted` | silent | — | unreachable (trust ⟹ both handles non-null); make it `MOBILEGL_ASSERT` or delete |
| F6 | 3910-3915 | twin missing for a trusted record | loud | S | keep; parity with the pre-handle arm at 3969-3971 (both bind nothing) |
| F7 | 3735 | as F5, in the fragColor derivation | silent | — | unreachable; same treatment |
| F8 | 2067-2071, 2211-2215 | `recordKeyed` false → version key | silent | **K** | none — both key shapes are correct and are held in separate fields |
| F9 | 4032 | `ForceBindCurrentFBO` stamps unconditionally | n/a | — | MINOR-3: invalidate instead of stamp |
| T1 | 1864 | `EsprytDrawSamplerHandlesEnabled()` false | silent | **M** | none; becomes `SamplerSubsystemEnabled()` (D) |
| T2 | 1852 | `SamplerViewCount == 0 && SamplerStateCount == 0` | **silent** | **S** | `MGLOG_E_ONCE` + tick the gate `hit=false` (MINOR-4) before falling through |
| I1 | 2363 | latch false | silent | **M** | none |
| I2 | 2365 | `ShaderImageCount == 0` | **silent** | **S** *(when the program declares images)* | loud-once; a program with images and no pushed set is a seam defect |
| I3 | 2366 | unit outside `[Start, Start+Count)` | silent | **M** for the eager funnel | none here — but see MAJOR-1 for the *sweep* |
| I4 | 2367 | `unit >= BoundShaderImages.size()` | silent | — | unreachable by `PipeApply.h:461-464`; keep as defence |
| I5 | 2369 | **image seam**: `view.Res != HandleOf(bound)` | **silent** | **S** | **MAJOR-3**: `MGLOG_E_ONCE` with the same wording stem as F3 |
| I6 | 2529 | `ShaderImageCount == 0` → full sweep | silent | **M** | safe direction; keep silent |
| I7 | 2532-2535 | sweep window narrower than the driver's | silent | — | **MAJOR-1** |
| S1 | 4354 | latch false | silent | **M** | none |
| S2 | 4356 | `SamplerStateCount == 0` | **silent** | **S** | loud-once, then the frontend walk |
| S3 | 4361-4363 | unit outside the window → `continue` | silent | — | **MAJOR-2** |
| S4 | 4369-4372 | twin missing at a live handle | silent | **M** | none — parity with `ResolveUnitSamplerBackend`'s null path, and deliberately not memoised as a miss |
| P1 | 3695 | latch false / `program == nullptr` | silent | **M** | none; becomes `ProgramSubsystemEnabled()` (D) |
| P2 | 3672 | `index >= table->size()` | silent | **S** | loud-once, and distinguish the composite band (an out-of-range composite index is a contract bug, not a missing record) |
| P3 | 3674 | `!record.Live \|\| record.Gen != handle.Gen` | silent | **S** | loud-once — this is ID-8's stale-generation refusal and it is currently indistinguishable from "no record" |
| P4 | 3698 | `record == nullptr` | silent | **S** | folded into P2/P3 |
| P5 | 3699 | **program seam**: `Desc.Cso != handle` | **silent** | **S** | **MAJOR-3**: `MGLOG_E_ONCE`, same stem as F3 |
| P6 | 3700 | `GlobalConstantsVersion == ~0u` | silent | **M**, then **S** | legitimate before the first upload; once bit 12 is on and `GetUBOSize() > 0 && HasGlobalUboBlock()`, a never-uploaded record at a draw is a seam defect → loud-once |
| P7 | 3701 | `GlobalConstants.size() < GetUBOSize()` | **silent** | **S** | a short block image is protocol corruption, not a missing record — this one should be `Fatal{ProtocolCorruption}`-shaped, or at minimum loud-once and never silently fall back to `MapUBO()` |
Also outside the table: the D-E3 read-attachment sync (**2078-2115**, called at **2231**) is
deliberately **ungated** (DEV-2), so it runs on the push build at mask 0 as well. Accepted as
declared — but it means the object A/B's `MOBILEGL_PIPE_PUSH=0` arm is no longer byte-equivalent to
the pull build's behaviour. G1 is unaffected (pull symbols 0/0/0/0 verified).
---
## 3. The seven assumptions, cross-checked against D's actual API
Read from `~/w7/p4a-esprytobj/MobileGL/MG_Backend/DirectGLES/Managers.{h,cpp}` (package D v1,
`9bb95335`), read-only.
| # | E's assumption | what D actually provides | reconciliation at the rebase |
|---|---|---|---|
| **A1** | registry forwards `HandleOf`/`FindByHandle` but **not** `GetOrCreate(MGPipeHandle)` | **Correct at c0.** D **adds** `BackendPtr* GetOrCreateByHandle(MG_Pipe::MGPipeHandle)` — `Managers.h:453` — returning a **pointer**, not the reference `GetOrCreate(StatePtr)` returns, and D says the pointer form is deliberate | Not the one-liner §3 predicts. `SyncCurrentFBOByRecord`'s `GetOrCreate(currentFBO)` (2779-2786) becomes `GetOrCreateByHandle(record.Fbo)` **plus a null check** — and once it takes the handle, the `slot.GetBoundObject()` resolve above it and the seam check can go, which is what A2 anticipates |
| **A2** | `BackendFramebufferObject::SyncToBackend(const SharedPtr<FramebufferObject>&, FramebufferTarget)` and `SyncReadBufferToBackend(const SharedPtr<FramebufferObject>&)` keep their signatures through `d4` | **Confirmed unchanged**: `esprytobj/Managers.h:1754` and `:1759` are textually the tag's `:1548` / `:1553`. D re-keys only the bodies (`m_syncedRecordHashes` / `m_syncedFrontendAttachmentVersions`, `Managers.cpp:8590-8608`) | Nothing to do. The `#else` half of A2 does not fire |
| **A3** | `SyncTextureParamsToBackend` / `SyncBuiltinSamplerToBackend` / `SyncMipmapsToBackend` / `IsDrawSyncClean` keep their frontend-object signatures through `d2` | **Confirmed**: `esprytobj/Managers.h:1501, 1514, 1515, 1550` == tag `:1350, 1363, 1364, 1399`. **But** D adds record-keyed members beside them — `:1709` *"the record's `ParamsSerial` at the last `SyncTextureParamsToBackend`"* and `:1715` *"the BuiltinSampler CSO record's `Serial` at the last `SyncBuiltinSamplerToBackend`"* | Signatures hold, so E's new read-FBO list compiles unchanged. **New**: once D's cheap gates key on record serials, `IsDrawSyncClean` for a **read-only** attachment answers from a `ParamsSerial` that nothing on the read path ever advanced — re-verify the new list still does work after `d2`, or it becomes a no-op |
| **A4** | D-K3's four `Resolve<Family>SubsystemArm()` latches do **not** exist at c0 | **Correct at c0; D has them.** `esprytobj/Managers.h:644-647` declares `ResolveFramebufferSubsystemArm` / `ResolveTextureResourceSubsystemArm` / `ResolveSamplerSubsystemArm` / `ResolveProgramSubsystemArm`, and `:649-663` wraps them as **`FramebufferSubsystemEnabled()`**, **`TextureResourceSubsystemEnabled()`**, **`SamplerSubsystemEnabled()`**, **`ProgramSubsystemEnabled()`** | Delete E's four (221-252) and call D's four **wrappers** (not the resolvers — the wrappers hold the `static const` latch). Note the **names differ** from E's guess. D's version adds the `MGLOG_E` refusal and `StopOnArmlessPipeSubsystem`. Carry ID-15's fourth row (bit 10 requires bit 11) — D's mirror comment at `Managers.h:631-636` still asserts the opposite and is D's rework item |
| **A5** | `SamplerPassMemo::rows` stays `Array<BackendSamplerObject*, 16>`, `g_boundSamplersCache` stays a raw-pointer shadow | **Confirmed**: `esprytobj/Managers.h:2158-2169`, `kMaxEntries = 16`, `Array<SamplerImpl::BackendSamplerObject*, kMaxEntries> rows{}` | Nothing. DEV-5 stands, and D's own arm-census at `Managers.h:627-628` lists these rows as a *legacy* memo, which is consistent |
| **A6** | `MGPImageView::Access` is a `Uint8` with no documented encoding at c0 | **Confirmed** — `MGPipeTypes.h`'s `MGPImageView` is `{Res, Unit, InternalFormat(Uint32), Layer(Uint32), Level(Uint16), Layered(Uint8), Access(Uint8)}` with no encoding note | Unchanged by esprytobj. Stays a C item (ID-12 did not rule it). §8.5 is the right home |
| **A7** | `MGPipeApplierReset` advances all P4a working-state serials | **Confirmed by reading `PipeApply.cpp`**: `++FramebufferSerial; ++SamplerViewsSerial; ++SamplerStatesSerial; ++ShaderImagesSerial; ++ProgramBindingSerial`, and the records/windows are zeroed in the same function. E's §0 is correct and should go to D before its rework, as the result recommends | Nothing here |
| **A8** *(new — the review adds it)* | *unstated*: that `set_shader_images` / `bind_sampler_states` windows cover every unit the **driver** holds, not just the program-resolved ones | The contract says only *"the record is the last set as received"* and *"Start + Count above the bound is `Fatal{ProtocolCorruption}`"* (`PipeApply.h:461-464`). Nothing pins the window's membership | MAJOR-1 / MAJOR-2. Either C documents it in `ImageEmit.h` / `SamplerEmit.h` and E asserts it, or E stops narrowing the driver-side sweep and walk |
The two extra API facts worth carrying: D's `HandleOf`/`FindByHandle` both return
null/`kMGPipeNullHandle` when `EsprytSlotTablesEnabled()` is false (`Managers.h:415-429`), so every
one of E's identity checks degrades to "decline" rather than to "false match" if bit 7 is ever clear
— that is a genuine safety property of the current code and should survive the rebase. And
`Managers.h:381-385` states a pointer-invalidation contract for handle-arm results ("invalidated by
the next `GetOrCreate`/`Find`/`CollectGarbage`"); E's `twinSlot ? *twinSlot :
GetOrCreate(currentFBO)` at 2794-2796 short-circuits correctly, and the `backendTexture` reference
held across `ResolveShaderImageRecord`'s `HandleOf` call at 2398 is safe because `HandleOf` neither
grows nor sweeps. Both should be re-checked after A1's rewrite, since `GetOrCreateByHandle` *can*
grow.
---
## 4. D-E3, and whether G9's mandated red-before is obtainable (R1 of the gates review)
**The closure itself is correct and is in the right place.** `SyncReadFramebufferTextureAttachments`
(**2078-2116**, called at **2231**) walks the READ framebuffer's texture attachments and gives each
`SyncTextureParamsToBackend` + `SyncBuiltinSamplerToBackend` + `SyncMipmapsToBackend`, dedupes a
framebuffer bound to both bindings with a pointer compare against the draw FBO, carries both key
shapes exactly like the draw list, and reuses `PairingsIntact`. DEV-1's ownership argument holds:
`SyncAttachmentObject` is `Managers.cpp:7142` and pushes `SyncMipmapsToBackend` **and nothing else**
(I read the whole body), while the list that pushes parameters reads the DRAW slot alone. Closing it
in `SyncNeccessaryTextures` is both inside E's ownership and closer to the cause.
**Completeness.** Attachment-only textures: covered (either framebuffer). Image-only textures: *not*
covered and correctly so — an image-only texture goes through `SyncTextureObjectToBackend(…, true)`
in `SyncImageTextureBinding` (2394), which is the params path for that family. `CopyImage`-endpoint
textures: *not* covered — `ResolveCopyImageEndpoint` (8418-8425) syncs the endpoint itself and does
not depend on this list. So the closure is complete for the gap D10 names.
**Is G9's red-before obtainable through public GL? No — the gates package's "no" stands, and I can
say exactly why.** I traced all four parameter families the comment at **2020-2024** names:
* `GL_DEPTH_STENCIL_TEXTURE_MODE` affects **texture fetch only**. For a texture that is only a READ
attachment it can be observed in exactly one place: MobileGL's own depth/stencil readback
emulation, which *samples* the attachment. That path **sets the mode itself** immediately before
sampling — `DirectGLES.cpp:9293` in `DepthStencilSamplingReadImpl`, and `:6954`, `:6967`, `:6987`
in the replicate-blit path — so the application's value is overwritten and cannot be observed.
* Swizzle, LOD clamp and border colour are likewise fetch-only. `glReadPixels`, `glBlitFramebuffer`
and `glCopyTexSubImage` read the attachment **image**, not through the sampler.
* The remaining route would be "the texture is later sampled, and a stale clean-stamp suppresses the
params push". Refuted by reading `IsDrawSyncClean` (`Managers.h:1399-1417`): it requires
`m_syncedTextureParamsVersion == t->GetTextureParamsVersion()` **and**
`m_syncedSamplerVersion == samplerObject->GetVersion()`, neither of which `SyncMipmapsToBackend`
advances. So the unit list pushes the parameters the first time the texture is sampled, and there
is no window in which the gap is visible.
Concretely: **no public-GL case goes red on the tag and green here.**
`AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver` as named cannot be written against the
GL surface. What *is* demonstrable, and what package F's G9 must become, is a **white-box** assertion:
an `MG_Test`/integration case that attaches a texture to the READ framebuffer only, sets
`GL_DEPTH_STENCIL_TEXTURE_MODE`/a swizzle, issues a `glReadPixels`, and asserts the **driver**
received the `glTexParameteri` — via a recording `GLESFunctionsTable` (the `ScopedBackendTwinMocks`
shape already in `SanityTest.cpp:2772+`) or by asserting on `BackendTextureObject`'s synced params
version. E's §8.3 should be rewritten to say that; as written it asks the integrator to run a green
against a red-before log that F cannot record. Flag to F and to the ROADMAP owner: `ROADMAP.md:20`'s
"落地前必须红" cannot be honoured for this item with a black-box test, and pretending otherwise
produces a vacuous green.
---
## 5. The other dimensions
**SyncCurrentFBO on the record (dimension 2).** Draw/Read/Both handled at 2757-2818; the `Both`
skip is now a field test (MINOR-1 on the comment). The `{0,1}` reserved-handle default path is
compared through `IsDefault` rather than `Fbo` (2764, and 2674-2681 says why) and resets the widened
and integer draw-buffer masks for the DRAW target only — matching the pre-handle arm at 2839-2849 and
`SyncAndBindFramebufferObject` at 3987-3999. `g_fboSynced{SlotVersions,ObjectVersions,Objects}` keep
their only readers on the pre-handle arm and are stamped only there; `g_fboSyncedBackendIdGenerations`
is *not* replaced — `g_attachmentBackendIdGeneration` and `g_backendContextGeneration` ride inside
`SyncedFramebufferSerialMemo` (2652-2664), which is the D-B3/D-O requirement and is right. The two
memo families never share a field, so a stale half can never be compared against a live one. One
behavioural divergence, benign and worth recording: with **nothing** bound, the pre-handle arm logs
`"No FBO is currently bound"` and skips (2834-2837), while the handle arm treats it as the default
framebuffer (2674-2677 maps `!bound` to default) and binds 0 — which is what `BindCurrentFBO`
(3943-3979) and `SyncAndBindFramebufferObject` (3987) already do, so the handle arm is the *more*
consistent of the two.
**The unit walks (dimension 3).** The epoch substitution is sound for three of its four consumers
(`ResolvedTextureBindingMemo`, `g_unitSamplerWalk*`, `SamplerPassMemo` — all program-resolved, which
is exactly what `set_sampler_views` covers) and approximately sound for the fourth
(`g_unitTextureSyncList`, whose membership is still the frontend walk — see §1 Refuted). No memo
fails to invalidate on a real change that I could construct. `maxTouchedUnit` is carried separately
in both the list key (1948, `g_unitTextureSyncListMaxUnit`) and the sampler-walk key
(`g_unitSamplerWalkMaxUnit`), so dropping it from the epoch loses nothing. The raw-depth-fetch
substitution stays server-side and is only re-*read* from the resolved view/CSO (87-101, `e4`); the
LOD-bias fallback and `EmulateTextureLodBias` are untouched, as §6 claims — I confirmed no diff hunk
reaches them.
**SyncCurrentProgram / the nine-clause rebuild (dimension 4).** `e4` touches only the fragColor
broadcast derivation (3727-3757) and the global-UBO source (4581-4656); the nine-clause condition and
`GetSyncedShaderCsoSerial()` are **not** re-keyed by this package — which is consistent with C.4 but
means dimension 4's "nine-clause rebuild condition reading `GetSyncedShaderCsoSerial()`" is *not* a
deliverable E landed. `FindShaderCsoRecord` (3658-3676) is the single composite-band reader, as
claimed, and `MGPipeIsCompositeShaderSlot` / `kMGPipeShaderCsoCompositeSlotBase` exist at
`MGPipeHandles.h:100-107`. Program deletion while bound is handled by P3 (`!record.Live ||
record.Gen != handle.Gen`), which is ID-8's stale-generation refusal — correct, but silent (table
row P3). Pipeline composites reach `ResolveGlobalConstantsRecord` through the same handle and are
indistinguishable to every other reader, which is D-H7 satisfied.
**G1 / G5 mechanism (dimension 7) — I re-verified, not just re-read.**
`awk '/^ namespace DepthStencilSamplingReadImpl \{/,…' | sha256sum` gives
`dfefc9964c82f23cb6b89292b2f155ebd2ac22ae442c18a959d38d5bc9063f53` at **both** `37da3c3a` and HEAD.
`RenderStateImpl` gives `d8fd1c48716056c536752fde09db3a9e5aa8494b70404798bfc15d11220efe27` at both,
== `~/w7/p4a-before-syncrenderstate.sha`. `git diff --stat 37da3c3a HEAD -- Utils.{h,cpp}
MultiDraw.cpp` is empty. `bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD` → rc 0. The pull-text
mechanism is macros, not duplicated functions, and every one is defined in **both** arms and
`#undef`ed: `MGB_IMAGE_{LAYERED,LAYER,LEVEL,FORMAT}` (2400-2408 / 2473-2476) and `MGB_UBO_BYTES`
(4596-4600 / 4656). `MGB_UNIT_BINDINGS_HANDLE_ARM` (1709-1770) is P3a's and is untouched. No macro
escapes its function. G1's 0/0/0/0 claim is mechanically credible; the integrator still re-runs
`symbol_report.py` on the integrated tree (§6).
**Emulations (dimension 8).** Four `MGPipeUnmigratedEmulation` sites, at 7534, 8185, 8480, 10106 —
`generate-mipmap-storage`, `generate-mipmap-cpu-fallback`, `copy-image-shadow-mirror`,
`get-tex-image-shadow`. Each is placed **after** the cheap declines, so the name means "this ran"
(7524-7534: after the `existingLevelCount == 0` return; 8172-8185: after the format and mipmap
declines; 8418-8480: after every shape decline; 10093-10106: after the channel-mapping and
zero-extent declines). D-M's fifth (`texture-remint-pull`) is not in this tree and is D's, as §6
says. Nothing in the D-M census is silently un-emulated: the fragColor broadcast, D24S8 dual-mode
sampling (byte-identical, verified), blit LOD/layered/multisample-replicate, draw-buffer `None`,
layered attachment shapes, the image format bake/widen/split, the LOD bias and the raw-depth-fetch
substitution are all still present and reachable. ✓
**Discipline (dimension 9).** Exit order: no new frontend-`SharedPtr` static (§1 Refuted). Logging:
five new `MGLOG_` lines — three `MGLOG_E_ONCE` for genuine seam/refusal conditions and one `MGLOG_D`
that mirrors the pre-handle arm's wording; nothing at `MGLOG_I`. No `TODO`/`FIXME`/`printf`/debug
leftovers in the diff (grepped). No new `MGB_CTX` read beyond the declared DEV-1/DEV-3/DEV-9 sites.
Working tree clean; `git status --porcelain` empty.
**Deviations judged.** DEV-1 ✓ (ownership argument correct, see §4). DEV-2 ✓ declared, with the A/B
caveat in §2. DEV-3 ✓ — and it is the reasoning MAJOR-1/MAJOR-2 ask to be applied consistently.
DEV-4 ✓ (structural, `Entry::stateRef` is empty on handle-keyed entries). DEV-5 ✓ (confirmed against
D's `Managers.h:2158-2169`). DEV-6 ✓ (confirmed: no encoding at c0 or c0c). DEV-7 ✓ but see MINOR-5.
DEV-8 ✓. DEV-9 ✓ (marked as monolith glue with a removal condition). DEV-10 ✓ (verified: the three
files are byte-untouched, and the `e5` message's second clause has no work behind it — accept, but
the integrator should know one of the five commit messages over-promises). DEV-11 ✓ (I reproduced
the shas by hand, same method). DEV-12 ✓. **DEV-13 is the one the integrator must act on before
anything else**: `refs/heads/p4a/esprytdraw` was never rebuilt by `wsl_tree.sh`, and re-running
`wsl_tree.sh p4a esprytdraw p4a/contract` would reset the branch and take all five commits.
`refs/heads/p4a/esprytdraw-backup` (`0b00f7f0`) is the net; do not delete it before the merge.
---
## 6. Rework list (bounded — all but the last are in E's own file)
1. **MAJOR-1** `SyncImageTextureBindings` 2527-2537: union the record window with
`g_imageUnitHighWaterMark` (or drop the window here and keep the record for the values only).
Add A8 to §3.
2. **MAJOR-2** `BindCurrentUnitSamplers` 4361-4363: `UnbindSampler(unit)` outside the window, or
decline the whole arm when the window does not cover `[0, maxTouchedUnit]`.
3. **MAJOR-3** add `MGLOG_E_ONCE` to the image seam (2369) and the program seam (3699), with the
same wording stem as 2715 so one grep covers all three.
4. **MINOR-1** correct the `ReadSurface` comment at 2801-2815 (or read the field).
5. **MINOR-3** `ForceBindCurrentFBO` 4028-4035: invalidate rather than stamp.
6. **MINOR-4** tick `Gate::EsprytUnitBindingsEpoch` `hit=false` on the record-arm decline at 1852.
7. **MINOR-5** delete the D-K2 mirror sentence at 221-229 (or add ID-15's fourth row) so the stale
claim is not carried into the rebase.
8. **MAJOR-4 → package D**: move `InvalidateFramebufferHandleArmMemos()` **inside**
`InvalidateFramebufferBindingCache` (`Managers.cpp:7107`); three `MG_Test/SanityTest.cpp` callers
(2530, 2778, 2799) currently clear only half the framebuffer memo state.
9. **→ integrator**: ID-12's DV-5 reader assignment ("E's `SyncAttachmentObject`") is wrong;
`SyncAttachmentObject` is `Managers.cpp` and E's diff reads no `MGPSurface` field. Reassign to D
or grant E the function for one commit, or the c0c `TextureTarget` field lands unread.
10. **→ package F / ROADMAP**: G9's `AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver`
cannot be written against public GL (§4). Re-specify it as a white-box assertion or drop the
red-before requirement for D-E3.
Not asked for and not required: the decline-table flips (§2). Those are ID-15's verification-round
work and should land there, not in this rework.
---
## 7. What the integrator must re-run on the integrated tree
0. **Before touching the tree**: do not run `wsl_tree.sh p4a esprytdraw p4a/contract` (DEV-13).
`git lfs checkout` in every worktree before any retrace (ID-13).
1. Rebase onto `refs/heads/feat/disaggregated` (c0 + c0b + c0c) + wire + clientfb + clientsp +
esprytobj, then take §3's reconciliations **first**: A1 (`GetOrCreateByHandle`, pointer + null
check), A4 (delete the four latches, call D's `FramebufferSubsystemEnabled()` /
`TextureResourceSubsystemEnabled()` / `SamplerSubsystemEnabled()` / `ProgramSubsystemEnabled()`),
A3's new record-keyed cheap gates.
2. **Apply the §2 flips**, then run with the default mask and assert **every** handle arm engages:
`SyncCurrentFBOByRecord` returns true, `UnitBindingsEpochFromRecords` answers,
`ResolveShaderImageRecord` returns non-null, `BindCurrentUnitSamplers` sets `walkedFromRecords`,
`ResolveGlobalConstantsRecord` answers. A silently all-declining tree passes every gate below and
means the package did nothing — and after the flips it is now *loud*, which is the point.
3. **Zero seam-check hits.** `grep 'does not describe the binding it names'` across the itest and
retrace logs must be empty for **all three** seams (framebuffer, image, program). A hit is a
finding against B/C, never a reason to relax the check.
4. **MAJOR-1/MAJOR-2 regression evidence**: with the client emitting, log
`(ShaderImageStart, ShaderImageCount)` against `g_imageUnitHighWaterMark` and
`(SamplerStateStart, SamplerStateCount)` against `maxTouchedUnit` for a Minecraft frame. If they
agree everywhere, DEV-3's `keys.maxTouchedUnit` can also move to the record (§8.4) and A8 can be
written down as a contract guarantee; if they do not, the fixes in §6.1-2 are load-bearing.
5. **The unit-list equivalence** (§1 Refuted, last item): compare `g_unitTextureSyncList` rebuild
counts between the walk arm (`MOBILEGL_PIPE_PUSH=0x1ff`) and the record arm (`0x1fff`) over one
frame. A large drop means the epoch is missing rebuilds the walk arm took.
6. **The full C.4 verification**: `symbol_report.py --threshold 0` (G1),
`p3a_untouched_regions.sh`, **`p4a_untouched_regions.sh`** — note `DepthStencilSamplingReadImpl`
is a **namespace**, so F's script needs the namespace shape for that row — `ctest -L unit` ×3,
`-L integration-gpu` on all three arms, the C.4 family regex, G13's two greps
(`pGLContext` = 1 pre-existing, `MGPipeUnmigratedEmulation` = 4 in `DirectGLES.cpp` + 1 in D's
`Managers.cpp`), and `retrace_gate.py` on `build-push` **and** `build-verify` (G3/G3b/G4 could not
run on E's tree — no `build-verify`).
7. **Named traces**: `photon-v1.3b` on llvmpipe desktop retrace is the canary for `e3`'s image-binding
semantics (and is the one that would catch MAJOR-1); `improved-transparency-minecraft-26.3` is the
draw-buffer-`None` net for `e1`.
8. **`MOBILEGL_PIPE_LEGACY_MEMOS=0`** configure+build (E did this once and removed the dir) plus the
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` exit-order lanes on both backends — the latter now
has a named item to confirm (`g_rawDepthFetchSamplerState`, §1 Refuted).
9. **Track H census input for `MEASUREMENTS.md`**: 7 memos re-keyed (3 direct, 4 transitive), 0
retired, 1 bypassed (`UnitSamplerLookupMemo`), 1 new (`g_readFboTextureSyncList`). Verified
against the source; the census is accurate as written.
@@ -0,0 +1,508 @@
# P4a package E — `esprytdraw`. Result, v1
Branch `refs/heads/p4a/esprytdraw`, five commits on top of the tag `refs/tags/p4a/contract`
(`08192d72`). **Not pushed.** Working tree clean. One file touched:
`MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp`, **+893 / −38**. `Utils.{h,cpp}` and
`MultiDraw.cpp` are **untouched** (§5, DEV-10).
A safety ref `refs/heads/p4a/esprytdraw-backup` points at HEAD; the integrator may delete it after
the merge.
| step | sha | message (exactly as C.4 specifies, single line, no attribution) |
|---|---|---|
| `e1` | `98bdfa3e37d737c5131280d55829671dff4d4970` | `[Refactor] (Espryt): resolve the current framebuffers from the pushed records and keep the shadowed default bind and the missing fast path exactly as they are` |
| `e2` | `c0dc679ea3099d4ff04736adf55d3339927de6ca` | `[Refactor] (Espryt): drive the per-draw texture sync from the pushed sampler-view set and give a read-only attachment its texture parameters` |
| `e3` | `f23fec0ea652bc19543cd93dfa982cd8abcb4398` | `[Refactor] (Espryt): bind shader images from the pushed set and leave the format recast and the split view where they are` |
| `e4` | `45810af0903a6c23c7f8975e8a82dd00e991b55d` | `[Refactor] (Espryt): bind samplers and the program's resources from the applier's resolved sets and keep the raw-depth-fetch substitution on the server` |
| `e5` | `0b00f7f0baae89dba37af66896bc7fd0062623e7` | `[Refactor] (Espryt): name every emulation that cannot survive a split and take the format decisions from the descriptor` |
---
## 0. The one finding the other Espryt packages need before they write a line
**`MGPipeApplierReset()` ADVANCES every P4a working-state serial unconditionally**
(`PipeApply.cpp:686-690`, `:716-720`: `++FramebufferSerial; ++SamplerViewsSerial; …;
++ProgramBindingSerial`). It is a make-current, not a teardown, and the design's own argument for
advancing rather than zeroing is correct — but the consequence is that **a P4a working-state serial
is NEVER the test for "has the client ever emitted this set"**. It is non-zero after the first
make-current on a tree where nothing emits at all.
This was found the expensive way. `e1`'s first landing gated the framebuffer handle arm on
`FramebufferSerial != 0`, took that arm with two all-zero records, skipped every framebuffer sync
and turned **55 of 491** `integration-gpu` cases red on the default (`0x1fff`) arm — a failure that
looks exactly like "the applier is a stub, which the brief says to expect", and would have been
classified as expected rather than as mine. It is not: the same tree at the tag is **491/491 green
on the default arm**, which is the control that separated the two (§7 records that run).
The tests that hold instead, and that every handle arm in this package uses:
* a **record's own handle** (`MGPFramebufferState::Fbo`, `MGPBoundView::View`, `MGPImageView::Res`)
— null means "no record";
* a var-tail set's **`Count`** (`SamplerViewCount`, `SamplerStateCount`, `ShaderImageCount`) — 0
means "this set has never arrived".
Package D's `esprytobj` will meet the same trap in `d4`'s `FramebufferSerial` compare and in `d2`'s
per-record gates. **Recommend the integrator hand this paragraph to D before its rework round.**
---
## 1. The controlling invariant of this package
**Every handle arm DECLINES to the pre-handle arm when the records that arm needs have not arrived,
and a decline is a full fallback rather than a partial run.** That is P3a's
`SyncVaoAttributeBuffersByHandle` discipline ("no live record is a miss, never a hit") applied to
five more families, and it is what makes this package landable ahead of `wire`, `clientfb`,
`clientsp` and `esprytobj`:
* **the default (`0x1fff`) arm is green on this tree, 491/491**, with no expected-failure set to
argue about — because with an empty applier every arm declines and the tree runs exactly the code
it ran at the tag;
* when B/C/`wire` land, each arm engages on its own record's arrival, independently of the others;
* a **seam check** sits in front of the two arms that could otherwise drive the driver from a record
that describes something else (§4, e1 and e3), so a mis-keyed emission declines loudly instead of
producing wrong pixels.
---
## 2. Per-step summary: every memo re-keyed, and every frontend read replaced (Track H census input)
### `e1` — the framebuffer sync and bind path (+347 / −18)
**Memos re-keyed**
| before | after (handle arm) |
|---|---|
| `g_fboSyncedSlotVersions[t]`, `g_fboSyncedObjectVersions[t]`, `g_fboSyncedObjects[t]` — three answers to "has the state the client would describe moved" (`Managers.h:1690-1710`) | **one** `Uint64`: `FramebufferImpl::g_fboSyncedSerials[t].serial` vs `MGPipeApplier().FramebufferSerial` |
| `g_fboSyncedBackendIdGenerations[t]` | **kept, per D-B3/D-O**: `g_attachmentBackendIdGeneration` answers "did *I* re-mint a driver texture id", which no client version can answer. Joined by `g_backendContextGeneration`, because driver FBO names die with the ES context |
| `g_broadcastMemo{Fbo, SlotVersion, ObjectVersion}` (`DirectGLES.cpp:3037-3057`) | `g_broadcastMemoContentHash` vs `DrawFramebuffer.ContentHash` — a **complete** key by D-C4's construction: the hash covers `Fbo` (so a recycled framebuffer handle cannot be suppressed against its predecessor) and `DrawBuffers[8]` (so an unchanged hash provably means the broadcast count did not move) |
The memo stays **per target**, because `ForceBindCurrentFBO` syncs one binding and must be able to
say so; what collapsed is the three-value question into one serial, not the two targets into one.
**Frontend reads replaced**
| read | site | replaced by |
|---|---|---|
| `GetFramebufferBindingSlotChecked(t).GetVersion()` ×2 | `SyncCurrentFBO`'s memo | the record's serial |
| `currentFBO->GetObjectVersion()` ×2 | same | same |
| `currentFBO.get()` as identity ×2 | same | `record.Fbo` through `FindByHandle` |
| `currentFBO == pDefaultFramebufferInfo->defaultFBO` ×2 | `SyncCurrentFBO`, `BindCurrentFBO` | `record.IsDefault` — one of the four identity comparisons `MGPipeHandles.h:69-71` names. Retained **only** as the consistency guard's comparand (§4) |
| `currentFBO.get() == lastUpdatedFBO` ("same FBO as draw") | `SyncCurrentFBO:2286` | `record.Target == Both`, and the read buffer is then applied from the record's **own** `ReadSurface`. The hazard `Managers.cpp:7424-7426` describes becomes unrepresentable rather than merely fixed |
| **the whole of `GetFramebufferBindingSlotChecked(t)`** | `BindCurrentFBO` | the record. This is the one of the five call sites that is **entirely retired** on the handle arm |
| `drawFBO->GetDrawBuffers()` walk | `SyncCurrentProgram`'s fragColor derivation | `record.DrawBuffers[8]` (`>= 0` is "not None") |
**Kept exactly as they are, and each says so in a comment**: `BindCurrentFBO` has **no fast path on
any version** (`KHR-GL32.packed_pixels`, D-O); the **default framebuffer is bound through the
shadow**, never raw (`readback-state-guards`, D-O); the widened/integer draw-buffer masks are reset
on the default-FBO path for the DRAW target only; `SyncAndBindFramebufferObject`'s default-FBO early
return is untouched.
**New invalidation**: `FramebufferImpl::InvalidateFramebufferHandleArmMemos()` is called beside all
**six** `InvalidateFramebufferBindingCache()` call sites in this file, and `InvalidateBroadcastMemo()`
clears the handle-arm broadcast keys too.
### `e2` — the per-draw texture sync (+265 / −4)
**Memos re-keyed**
| before | after (handle arm) |
|---|---|
| `CurrentUnitBindingsEpoch`'s derivation: `CaptureUnitBindings` / `UnitBindingsUnchanged` — a per-unit walk over every binding slot **and** the unit's sampler object, re-run whenever `GetTextureBindGeneration()` moves (26.2 moves it around every texture-unit switch) | `Mix(SamplerViewsSerial, SamplerStatesSerial)` — **two `Uint64` reads, no walk, no accessor call**. Sound because both sets go out through a `ContentHash` suppressor over every tail entry, so a serial moves iff the resolved set moved |
| `g_fboTextureSyncListSlotVersion` + `…ObjectVersion` | `g_fboTextureSyncListContentHash` vs `DrawFramebuffer.ContentHash`. **The identity half stays a pointer compare** and deliberately so — the list borrows the attachment's own `SharedPtr` slots, and "is the object I borrowed from the one bound now" has no handle in it until D re-keys the twin tables |
**Transitively re-keyed with no edit of their own** — every consumer of `keys.unitBindingsEpoch`,
which is now the records' serials on the handle arm: `g_unitTextureSyncList*` (the unit texture sync
list), `ResolvedTextureBindingMemo` (the per-program resolved texture bindings), `g_unitSamplerWalk*`
(the sampler walk), and `BackendProgramObjectImpl::SamplerPassMemo`. **Four memos re-keyed by one
substitution** — this is the single largest item in the census and it costs no edit at any of the
four sites.
**Behaviour deliverable — D-E3, `ROADMAP.md:20`'s 落地前必须红 item.** A new push-only list,
`g_readFboTextureSyncList`, walks the **READ** framebuffer's texture attachments and gives each one
`SyncTextureParamsToBackend` + `SyncBuiltinSamplerToBackend` + `SyncMipmapsToBackend`. Today a
read-only attachment reaches `SyncAttachmentObject`, which calls `SyncMipmapsToBackend` **and
nothing else** (`Managers.cpp:7161`), because the list that pushes parameters for an attachment reads
the DRAW slot alone (`DirectGLES.cpp:1944`). One object bound to both bindings is walked once (a
pointer compare against the draw framebuffer). The list carries **both** key shapes, exactly like
the draw list.
**Memos retired**: none. `UnitBindingsSnapshot` / `CaptureUnitBindings` / `UnitBindingsUnchanged` /
`PairingsIntact` are all **kept**; their deletion is the ~175-line backend debounce removal that
`ROADMAP.md:23` gives to P3b/P4b, and `ARCHITECTURE.md:369` keeps the pre-handle arm compiling
through P4a.
### `e3` — the image units (+93 / −6)
* `SyncImageTextureBinding` takes **`Level`, `Layer`, `Layered` and `InternalFormat`** from
`MGPImageView` when `ResolveShaderImageRecord` says the record names the same texture the unit
holds. Substituted through four `#define`/`#undef` pairs in the `MGB_UNIT_BINDINGS_HANDLE_ARM`
shape this file already uses, so the **pull build's preprocessed text is unchanged** (D-P).
* `SyncImageTextureBindings`' sweep membership: `min(192, MaxImageUnits)` → `[ShaderImageStart,
ShaderImageStart + ShaderImageCount)`, clamped to what ES exposes. That is D-J2's rule — *the
var-tail window IS the bound and entries outside it are not cleared*.
* **`Access` is deliberately not taken from the record** — see DEV-6.
* **D-G4's two invariants are kept and now say so in the source**: the
`g_imageUnitHighWaterMark == 0` early-out is asked before anything reads a record, and the sweep's
gate stays the **frontend** sampling-resolution generation and is explicitly *not* re-keyed onto a
server-owned serial, because a texture bound only to an image unit is re-minted **inside** the
sweep. The bind-format recast and the buffer split view are untouched.
### `e4` — the sampler walk and the program's resources (+159 / −13)
* **`BindCurrentUnitSamplers`' walk reads `MGPipeApplier().BoundSamplerStates[unit]`** instead of
`MGB_CTX->GetTextureUnitObject(unit).GetSamplerObject()`, and binds through `FindByHandle` — so on
that path `UnitSamplerLookupMemo` is **bypassed entirely**: the handle *is* the lookup, and
`SlotTables.h:556-561`'s recorded single-entry-memo thrash does not happen. A null handle unbinds;
a handle whose twin does not exist yet is left alone and **never cached as a miss**, for the reason
`ResolveUnitSamplerBackend` gives (the program pass creates the twin later in the same draw).
* **`BindCurrentProgramWithResources`' global UBO takes its version and its block image from the
`ShaderCso` record** — `GlobalConstantsVersion` and `GlobalConstants` replace
`GetUBOContentVersion()` and `MapUBO()`. `ResolveGlobalConstantsRecord` requires four things
before it will answer: a live record at the program's handle, the record's own `Desc.Cso` naming
that same handle (the seam check), a version that is not the `~0u` never-uploaded sentinel, and a
block image at least `GetUBOSize()` long.
* `FindShaderCsoRecord` is the **one** reader that knows the composite band exists
(`MGPipeIsCompositeShaderSlot` → `CompositeShaderCsos[slot − base]`), so D-H7's "the server never
learns it is a composite" stays true of every other reader.
* **The UBO ring is untouched** — the `{contentVersion, ringGeneration, frameSerial, offset}`
allocation key, the `glBufferSubData` fallback and the `ByteClass::StageUboGlobal` accounting are
all exactly what they were. Named UBOs (P4b) are untouched.
* **The raw-depth-fetch substitution stays on the server** and now carries the D-F3 paragraph naming
it as *the largest surviving `MG_State`-type usage under `MG_Backend/DirectGLES`* with its owner
(P3b/P4b) written down, so P13's include-graph gate meets a known item.
### `e5` — the named emulations (+32)
Four `MGPipeUnmigratedEmulation` call sites, each planted where the emulation **commits to running**
(after the cheap declines), so the name means "this ran" rather than "this was considered". §6 lists
them.
---
## 3. What this package assumes of package D, and where the rebase will touch it
Every assumption below is written into the source at the site that makes it.
| # | assumption | what changes at the rebase |
|---|---|---|
| **A1** | `StateBackendObjectRegistry` (`Managers.h:303-540`) forwards `HandleOf` and `FindByHandle` but **not** `GetOrCreate(MGPipeHandle)`. `e1` resolves the FBO twin with `FindByHandle(record.Fbo)` and falls back to `GetOrCreate(currentFBO)` | after `d1`, the fallback becomes `GetOrCreate(record.Fbo)` — one line, marked "MONOLITH GLUE" in the source |
| **A2** | `BackendFramebufferObject::SyncToBackend(const SharedPtr<FramebufferObject>&, FramebufferTarget)` and `SyncReadBufferToBackend(const SharedPtr<FramebufferObject>&)` keep their signatures through `d4`; only their bodies re-key onto `MGPFramebufferState` | if `d4` changes the signature, `SyncCurrentFBOByRecord`'s two call sites take the record instead of the object, and the "resolve the bound object" block above them disappears with the consistency guard (§4) |
| **A3** | `BackendTextureObject::{SyncTextureParamsToBackend, SyncBuiltinSamplerToBackend, SyncMipmapsToBackend, IsDrawSyncClean}` keep their frontend-object signatures through `d2` | the three sync lists' entries become `{handle, twin}` instead of `{slot, texture, twin}`, and DEV-4 (the unit list's membership) can then move to the record |
| **A4** | D-K3's four `Resolve<Family>SubsystemArm()` latches do **not** exist at `c0`; contract-v1 §6 gives them to D | the four local latches in this file (`EsprytDraw{TextureResource,Framebuffer,Sampler,Program}HandlesEnabled`) become calls to D's, which add the `MGLOG_E` naming both bits and the `Fatal{PipeLegacyMemosDisabled}` stop. **The dependency directions are already copied here** (11→10, 9→10, 10→7, 12→nothing) so a half-running mask is refused in the meantime |
| **A5** | `SamplerPassMemo::rows` stays `Array<BackendSamplerObject*, 16>` and `g_boundSamplersCache` stays a raw-pointer shadow (`Managers.h`, D's) | nothing here; see DEV-5 for why no handle belongs in either |
| **A6** | `MGPImageView::Access` is a `Uint8` with **no documented encoding** at `c0` | `e3` starts reading it once package C writes the encoding down; one `#define` in this file |
| **A7** | `MGPipeApplierReset` advances all P4a working-state serials (§0) | nothing here — every arm already uses handles and counts |
---
## 4. The two seam checks, and why they exist
Both were added in a self-review pass and squashed into their step (DEV-12). Both exist because this
package can be *landed* but not *exercised* against real records on its own tree, and the failure
mode they guard is silent wrong pixels rather than a red test.
**Framebuffer (`e1`).** `FramebufferRecordMatchesBinding(target, record)` requires the record's
`IsDefault` to agree with the bound object's defaultness and, for a non-default record, the
record's `Fbo` to equal `HandleOf(bound)`. A disagreement **declines the whole arm** — both targets,
not one — because the two records are emitted together and one being wrong says nothing good about
the other, and it logs once. `g_fboRecordsTrusted` carries that verdict to `BindCurrentFBO` (whose
whole value is that it does **not** read the binding slot) and to the fragColor broadcast derivation;
both run immediately after `SyncCurrentFBO` in `PrepareForDraw`, so the latch is fresh, and it starts
false and is cleared by every decline and by every binding-cache invalidation, so an unpaired bind
takes the pre-handle arm.
**Image units (`e3`).** `ResolveShaderImageRecord` returns the record only when `view.Res` equals
`HandleOf(the unit's bound texture)`. This one is not optional: `SyncImageTextureBinding` is also the
**eager** funnel `glBindImageTexture` itself runs, and at that moment the newest record describes the
*previous* draw — driving the driver from it would bind one texture with another's level, layer and
format.
Both checks are monolith glue and both disappear when D's twin API takes the record instead of the
object: at that point there is no second answer left to disagree with.
---
## 5. Deviations, each with its reason
**DEV-1 — the READ-attachment parameter gap is closed from `SyncNeccessaryTextures`, not from
`SyncAttachmentObject`.** C.4's `e2` says *"`SyncAttachmentObject` gains the parameter sync for
READ-only attachments"*, but `SyncAttachmentObject` is in `Managers.cpp`, which C.7 gives to **D**
for the whole phase. The gap's actual cause is in this package's file — `SyncNeccessaryTextures`'
attachment list reads `GetFramebufferBindingSlotChecked(Draw)` alone
(`scout-espryt-framebuffer.md` §2.6) — so closing it here is both within ownership and closer to the
cause. Same observable behaviour: an attachment of either framebuffer now gets
`SyncTextureParamsToBackend` + `SyncBuiltinSamplerToBackend`.
**DEV-2 — the READ-attachment sync is NOT gated on the framebuffer subsystem bit.** It is a
*deliverable* of the phase (`ROADMAP.md:20`, `ARCHITECTURE.md:100`), not an *arm* of it. Gating it
would make the object A/B measure the arm **plus** a behaviour change and would leave G9's mandatory
case red on every legacy lane. It is inside `#if MOBILEGL_PIPE_PUSH`, so G1 and the pull build are
untouched, and G9 runs on `build-push`.
**DEV-3 — `keys.maxTouchedUnit` stays `MGB_CTX->GetMaxTouchedTextureUnit()`.** D-G2 makes
`SamplerViewCount` the client's spelling of exactly this number, and an earlier revision of `e2` did
take it off the record. It was **reverted in self-review** because the two failure directions are not
alike: a window larger than the frontend mark costs a walk over provably-empty units, while one that
is *smaller* silently drops the sync of a texture a draw is about to sample — and no gate on this
tree can see the difference, because this tree emits no windows. The design assigns the high-water
mark to the **client** as the `count` argument and says nothing about re-deriving it server-side.
One accessor read per draw; the integrator can move it in one line on a tree where the two can be
compared (§8).
**DEV-4 — the unit texture sync list's MEMBERSHIP stays the frontend binding walk; only its
VALIDITY is record-keyed.** C.4's `e2` asks for the list to be "rebuilt from the applier's
SamplerViews set". It cannot be, yet, and the reason is structural rather than a matter of effort:
an entry is `{const SharedPtr<ITextureObject>* slot, ITextureObject* texture, BackendTextureObject*
backend}` and the three twin calls it replays all take the **frontend object**. `MGPBoundView`
carries a texture *handle* and a unit index but not the binding target, and a handle cannot be turned
back into a frontend object (`Entry::stateRef` is empty by design on handle-keyed entries,
`SlotTables.h:266-269`). The membership move is unlocked by D's `d2`, at which point the entries
become `{handle, twin}`; A3 records it.
**DEV-5 — `SamplerPassMemo`'s rows stay `BackendSamplerObject*`.** C.4's `e4` says they become
handles. Two reasons not to, and the second is the real one: the struct is in `Managers.h`, which is
D's file; and the rows are not an *identity* question at all — they are the memo's proof that **the
driver still holds the bindings this pass left**, compared against `g_boundSamplersCache`, which is a
server-owned driver shadow. A client handle in that array would answer a question nobody asked. The
identity half of this memo family *is* already handle-keyed, by P2:
`UnitSamplerLookupMemo::frontendHandle` (`DirectGLES.cpp:3522-3535`). What `e4` adds is that the
record path does not consult that memo at all.
**DEV-6 — `MGPImageView::Access` is not consumed.** The field is a `Uint8` and a GL access token
(`GL_READ_ONLY` = 0x88B8) is not, so the record carries an **encoding** — and neither
`MGPipeTypes.h:659-668` nor `PipeFields.def:123-124` writes one down at `c0`. Reading it here would
be inventing it. The frontend value answers, and it is the same value by construction.
**Recommend the integrator have package C document the encoding in `ImageEmit.h`**, after which this
is one `#define` in `SyncImageTextureBinding`.
**DEV-7 — four local family arm latches instead of D's `Resolve<Family>SubsystemArm()`.** A4. They
carry the dependency directions verbatim; they do **not** carry the refusal `MGLOG_E` or the
`Fatal{PipeLegacyMemosDisabled}` stop, because two writers of one diagnostic is how the two drift.
**DEV-8 — `SyncTextureObjectToBackend` does not gain an explicit handle parameter.** C.4's `e2` asks
for it. It is already handle-keyed *internally* on the handle arm — `Find(obj)` on a
`BackendSlotTable` is `FindByHandle(HandleOf(obj))` (`SlotTables.h:364-368`) — so an explicit
parameter would only skip a memoised lifetime-id probe, and no caller has a handle to pass until
DEV-4 is unlocked. Adding the overload now would be ~60 duplicated lines with no caller.
**DEV-9 — two consistency guards on the handle arms.** §4. They add frontend reads that a fully
migrated path would not need, which is the opposite direction from the phase's goal; they are marked
in the source as monolith glue with the condition for their removal.
**DEV-10 — `Utils.{h,cpp}` and `MultiDraw.cpp` are untouched.** C.4's `e5` asks for "the
`Utils.{h,cpp}` readers that take a descriptor instead of a frontend object". A grep for `MG_State`,
`ITextureObject`, `FramebufferObject`, `SamplerObject` and `ProgramObject` across all three files
finds **no such reader**: `Utils.h`'s format decisions
(`ShouldUseCaveatTextureFormat`, `GetImageBindableStorageWidening`, `GetImageBindableBufferSplitFormat`,
`GenerateTextureFormatInfo`) already take `TextureInternalFormat` + `TextureTarget` **values**, and
`MultiDraw.cpp`'s only frontend reads are `BufferObject` (P3a's family, and the index host mirror is
P8's). The one Utils function D-N names, `ShouldUseCaveatTextureFormat`, is on the byte-identical
list and stays byte-identical. `e5`'s message therefore lands with only its first clause realised;
the second clause has no work behind it in these files.
**DEV-11 — D-N was checked by hand.** `scripts/p4a_untouched_regions.sh` is package F's and does not
exist yet. §6 gives the sha evidence for the two D-N functions that live in package E's files, taken
the same way the script takes them (an `awk` range for the namespace, a `git diff --stat` for the
file).
**DEV-13 — `~/w7/p4a-trees2.log` never said `REBUILT esprytdraw`, and this package built anyway.**
The task said to wait for that line before the first build. The file was created at 12:25 and was
**still zero bytes** when this round ended, with no `cmake`, `ninja`, `wsl_tree.sh` or
`wsl_integrate.sh` process running at any point. What was checked instead, before touching anything:
`HEAD == refs/tags/p4a/contract` (`08192d72`), a clean working tree, `build-linux` and `build-push`
present with libraries dated after the tree was created, and `ninja -n` in both reporting nothing to
do but a CMake re-run — i.e. the tree was already in the state the line would have announced. **If
the integrator's rebuild script is still pending, it must not be run against this worktree**: a
`wsl_tree.sh p4a esprytdraw p4a/contract` would reset `refs/heads/p4a/esprytdraw` and take the five
commits with it. `refs/heads/p4a/esprytdraw-backup` (`0b00f7f0`) exists for exactly that accident and
should be deleted after the merge.
**DEV-12 — the series was produced with one autosquashed fixup.** The self-review (§4, DEV-3) found
two issues after `e5` had landed; the fix was committed as `--fixup=<e2>` and folded in with
`git rebase --autosquash`, so `e2`..`e5` carry different shas than their first landing and the branch
is exactly the five commits C.4 asks for, with the five messages verbatim. Every commit was
re-verified afterwards (§7).
---
## 6. Emulations: dispositions and the `MGPipeUnmigratedEmulation` sites
Four of D-M's five names are planted in this package's file; the fifth (`texture-remint-pull`,
`Managers.cpp:4769`) is **package D's** — contract-v1 §6 splits the five between D and E, and
`PipeCatalogueTest.EveryUnmigratedEmulationIsNamedOnce` pins all five names.
`grep -rc 'MGPipeUnmigratedEmulation' MobileGL/MG_Backend/DirectGLES/` → `DirectGLES.cpp:4`.
| name | site (this file, at `0b00f7f0`) | planted where |
|---|---|---|
| `"generate-mipmap-storage"` | `EnsureGenerateMipmapStorageAllocated` | after the `existingLevelCount == 0` decline, before the level shadows are read |
| `"generate-mipmap-cpu-fallback"` | `GenerateThreeChannelFloatMipmapOnCpu` | after the format and mipmap-texture declines |
| `"copy-image-shadow-mirror"` | `MirrorCopyImageIntoDestinationShadow` (under `CanMirrorCopyImageShadow`) | after every shape decline, immediately before the shadow rows are copied |
| `"get-tex-image-shadow"` | `GetTexImageViaShadowConversion` | after the channel-mapping and zero-extent declines |
**Emulations that stay where they are, per D-M, and what changed about them:**
| emulation | owner | in this package |
|---|---|---|
| fragColor MRT broadcast (`BroadcastLegacyFragColor`) | server | unchanged as a rewrite; its **input** (`g_fragColorBroadcastCount`) is now derived from the framebuffer record's `DrawBuffers[8]`, keyed on its `ContentHash`, at the same point in the draw as before. Deleting the workaround and `g_broadcastMemo*` is P3b/P4b's |
| D24S8 dual-mode sampling (`DepthStencilSamplingReadImpl`) | server | **byte-identical**, §6.1 |
| blit LOD / layered blit, the multisample replicate path | server | untouched |
| draw-buffer `None` → `GL_NONE`, "apply draw buffers only for the DRAW target" | server (`Managers.cpp`, D's) | untouched here; the record's `Target` is what makes the second rule a field test rather than call-site discipline |
| layered attachment shapes, `SupportsLayeredImageBinding`'s rule | server | untouched; `e3` feeds it `record->Layered` / `record->Layer` and it still asks the **backend** target and still forces `layer` to 0 for a non-layerable one |
| image format bake / widen / split / array remap | server | untouched; `e3` feeds the recast the application's format from the record |
| texture LOD bias (`EmulateTextureLodBias` + the per-draw `glUniform1f`) | server | untouched |
| raw-depth-fetch sampler substitution | server, P3b/P4b to nativise | untouched, and now carries the D-F3 paragraph naming it as the largest surviving `MG_State`-type usage under `MG_Backend/DirectGLES` |
### 6.1 Byte-identical evidence
| item | evidence |
|---|---|
| **D-N, in package E's files**: `DepthStencilSamplingReadImpl` | it is a **namespace**, not a function (`DirectGLES.cpp:8437-8898`), so it is hashed the way P2's G5 hashes `RenderStateImpl`: `awk '/^ namespace DepthStencilSamplingReadImpl \{/,/^ \} \/\/ namespace DepthStencilSamplingReadImpl/' \| sha256sum` → `dfefc996…c9063f53` at `37da3c3a` **and** at HEAD. Package F's `p4a_untouched_regions.sh` will need the namespace shape for this one row |
| **D-N**: `ShouldUseCaveatTextureFormat` (`Utils.cpp:245`) | `git diff --stat 37da3c3a..HEAD -- Utils.cpp Utils.h MultiDraw.cpp` is **empty** — the whole file is untouched |
| **P3a's eleven** (G5) | `bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD` → **rc 0** at every one of the five commits |
| **P2's G5** (`RenderStateImpl` namespace) | `d8fd1c48716056c536752fde09db3a9e5aa8494b70404798bfc15d11220efe27` == `~/w7/p4a-before-syncrenderstate.sha`, at every one of the five commits |
Package E's other D-N obligations (`StageBlocksIntoUnpackRing`, `UnpackRingAvailable`,
`UnpackRingAllocate`, `RecomputeBackendColorSlots`) all live in `Managers.cpp`, which this package
never opens.
---
## 7. Verification transcript
All commands in `~/w7/p4a-esprytdraw` with `CCACHE_BASEDIR=/home/swung/w7`.
### 7.1 Per commit (all five)
```
$ for c in 98bdfa3e c0dc679e f23fec0e 45810af0 0b00f7f0; do git checkout --detach $c; ... done
98bdfa3e build-linux OK build-push OK unit(push) OK
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (0)
p3a-untouched rc=0 RenderStateImpl sha d8fd1c48716056c5
c0dc679e … identical …
f23fec0e … identical …
45810af0 … identical …
0b00f7f0 … identical …
```
### 7.2 On the finished branch (`0b00f7f0`)
```
$ python3 scripts/symbol_report.py --before ~/w7/p4a-before-libMobileGL.so \
--after build-linux/libMobileGL.so --threshold 0
| before | ~/w7/p4a-before-libMobileGL.so | 19114360 | 10806323 |
| after | build-linux/libMobileGL.so | 19114360 | 10806323 |
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (same size) (0) <- G1
$ 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
$ awk '/^ namespace RenderStateImpl \{/,/^ \} \/\/ namespace RenderStateImpl/' \
MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp | sha256sum
d8fd1c48716056c536752fde09db3a9e5aa8494b70404798bfc15d11220efe27 == p4a-before-syncrenderstate.sha
$ cmake --build build-linux -j 12 && ctest --test-dir build-linux -L unit -j 12
100% tests passed, 0 tests failed out of 1635
$ cmake --build build-push -j 12 && ctest --test-dir build-push -L unit -j 12
100% tests passed, 0 tests failed out of 1635
# the legacy arms, and the default arm
$ MOBILEGL_PIPE_PUSH=0x1ff ctest --test-dir build-push -L integration-gpu -j 8 -R DirectGLES
100% tests passed, 0 tests failed out of 491 rc=0
$ MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu -j 8 -R DirectGLES
100% tests passed, 0 tests failed out of 491 rc=0
$ (default = 0x1fff) ctest --test-dir build-push -L integration-gpu -j 8 -R DirectGLES
100% tests passed, 0 tests failed out of 491 rc=0
# C.4's family subset, all three arms
$ ctest --test-dir build-push -L integration-gpu -j 4 -R '<C.4's 41-name regex>'
default 100% 497/497 | 0x1ff 100% 497/497 | 0 100% 497/497
$ grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$'
MobileGL/MG_Backend/MGPipe/PipeInputs.h:1 # pre-existing at $BASE, unchanged <- G13
$ grep -rc 'MGPipeUnmigratedEmulation' MobileGL/MG_Backend/DirectGLES/
MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:4 # + D's one in Managers.cpp = 5 <- G13b
# both compile-time arms, since none of the three standing build dirs has it off
$ cmake -S . -B build-nolegacy … -DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_PIPE_LEGACY_MEMOS=OFF
configure rc=0 ; ninja -C build-nolegacy MobileGL → rc=0 (dir removed afterwards)
```
**The default-arm control that made §0's finding attributable**: with the working tree stashed, the
same build dirs at the tag ran `default → 100% 491/491`. That is what says "55 red" was this
package's and not the stub applier's.
### 7.3 Not run here, and why
* **G3 / G3b / G4** (`retrace_gate.py`, the verify lane) — `build-verify` does not exist in this
worktree (`wsl_tree.sh p4a esprytdraw p4a/contract` was created without the `verify` argument, per
C's tree-creation list). They belong to the integrated tree.
* **G6 / G7** (`*EmitTest`, `p4a_descriptor_negative_control.sh`) — packages B/C/F.
* **G8 / G8b / G9 / G12** (`HandleRecycleScenario`, `TextureParamsWithoutASamplerViewScenario`,
`ObjectSubsystemControlScenario`) — package F's scenarios; none exists on this tree, so **D-E3's
closure is implemented but not yet demonstrated** (§8).
* **G5's script** — package F's (DEV-11).
---
## 8. Post-rebase verification list
For the integrator, after rebasing this branch onto `wire` + `clientfb` + `clientsp` + `esprytobj`.
The first three are the ones that can only be answered on the integrated tree.
0. **Re-read §3's assumptions against `contract-v2`.** This branch is based on the **tag**
`refs/tags/p4a/contract` (`08192d72`), as ID-2 requires, but `refs/heads/p4a/contract` has since
moved to `2cb44039` (the contract rework). Anything the rework settled that §3 lists as an
assumption — most likely **A6** (`MGPImageView::Access`'s encoding) and **A4**
(`Resolve<Family>SubsystemArm()`'s home) — is a one-line change here rather than a design
question, and should be taken before the rest of this list.
1. **The arms actually engage.** With the default mask, confirm each handle arm is taken rather than
declining: `SyncCurrentFBOByRecord` returns true, `UnitBindingsEpochFromRecords` answers,
`ResolveShaderImageRecord` returns non-null, `BindCurrentUnitSamplers` walks from records, and
`ResolveGlobalConstantsRecord` answers. A silent all-declining tree passes every gate below and
means this package did nothing. Recommend one temporary `MGLOG_D` per arm for the round, or the
`PipeStats` gate counters (`Gate::EsprytUnitBindingsEpoch` hit rate should go to 100%).
2. **Neither seam check fires.** `grep 'does not describe the binding it names'` in the itest and
retrace logs must be empty; a hit means a client emission is mis-keyed and is a **finding against
B/C**, not a reason to relax the check.
3. **G9** — `ctest --test-dir build-push -R 'TextureParamsWithoutASamplerView'`, and specifically
`AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver` **green**, against package F's
recorded red-before log. This is the one deliverable of this package that has no gate on its own
tree.
4. **DEV-3, reconsidered with evidence**: on a tree that emits, compare
`MGB_CTX->GetMaxTouchedTextureUnit()` against `SamplerViewCount - 1` for a frame; if they agree
everywhere, `keys.maxTouchedUnit` can take the record in one line.
5. **DEV-6, reconsidered**: once package C documents `MGPImageView::Access`'s encoding, `e3` reads it
(one `#define`), and `ImageEmitTest.AnAccessModeChangeAloneStillEmitsTheSet` becomes the gate on
both sides.
6. **DEV-4 / A3**: once `d2` has re-keyed the twin's sync calls onto the record, move the unit
texture sync list's membership to `BoundSamplerViews` and drop the frontend binding walk.
7. **A1 / A2 / A4**: replace the `GetOrCreate(currentFBO)` fallback with `GetOrCreate(record.Fbo)`,
the four local arm latches with D's `Resolve<Family>SubsystemArm()`, and (if `d4` changed them)
the two `SyncToBackend` call signatures. Then re-run §7.2 whole.
8. **The full C.4 verification**: G1, `p3a_untouched_regions.sh`, **`p4a_untouched_regions.sh`**
(F's, including this file's two rows — note `DepthStencilSamplingReadImpl` is a **namespace**,
§6.1), `ctest -L unit` ×3, `-L integration-gpu` on all three arms, the C.4 family regex, G13's
greps, and `retrace_gate.py` on `build-push` and `build-verify`.
9. **Named traces**: `photon-v1.3b` on **llvmpipe desktop retrace** is G3b's canary for exactly the
image-binding semantics `e3` moves, and `improved-transparency-minecraft-26.3` is the draw-buffer
`None` net for `e1`. Neither can run here.
10. **The Track H census** (§2) is the input the phase owes `MEASUREMENTS.md`: **7 memos re-keyed**
(3 directly, 4 transitively through the epoch substitution), **0 retired** (the pre-handle arms
stay through P4a per `ARCHITECTURE.md:369`), **1 memo bypassed** on its record path
(`UnitSamplerLookupMemo`), **1 new** (`g_readFboTextureSyncList`, D-E3), and the frontend reads
listed per step.
---
## 9. Intermediate logs
Deleted, per ID-5 ("package logs `~/w7/p4a-<slug>-*.log` are deleted by their owner when the round
ends"): the five `~/w7/p4a-esprytdraw-*.log` tree-creation and first-build logs are gone, and so is
every `/tmp/p4ae-*` build, ctest and arm log this round produced. `~/w7/p4a-esprytdraw` itself holds
only `build-linux` and `build-push` (the `build-nolegacy` dir of §7.2 was removed after its one
compile). Nothing was written under `~/w7/notes/` except this file. The scratchpad's
`wsl/p4a-esprytdraw-*.sh` command scripts remain in the shared `wsl` directory, which ID-7 says
never to delete.
@@ -0,0 +1,437 @@
# P4a package E — `esprytdraw`. Rework result, v2
Branch `refs/heads/p4a/esprytdraw`, **HEAD `9b8441a6`**, rebased onto `refs/heads/feat/disaggregated`
(`17db7598` = c0 + c0b + c0c; **no c0d existed when this round started**, so `Tracker.h`'s two
under-fires are not reconciled here — see §6). One file, `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp`,
**+1214 / −38** against `17db7598`. Nothing was pushed. `~/w7/p4a-esprytdraw-backup` (`0b00f7f0`,
DEV-13's net) was not touched.
All line numbers below are **HEAD (`9b8441a6`) line numbers in `DirectGLES.cpp`**.
---
## 1. The rebase, and the commit series
`git rebase refs/heads/feat/disaggregated` replayed all five original commits with **no conflicts**
(c0b/c0c touch `MG_Impl/Pipe`, `MG_Pipe` and `scripts/` only, and this package owns one backend
file). The five rebased commits are `ff07f5fa 08945879 7b79a1f2 e588cd55 d6127608`, and
`git diff 0b00f7f0 d6127608 -- DirectGLES.cpp` is **empty** — the rebase moved the base and nothing
else.
The rework is five further commits on top:
| # | hash | message |
|---|---|---|
| r1 | **`ba93dfda`** | `[Refactor] (Espryt): read the applier's framebuffer records through one accessor, carry D-K2's fourth row into the temporary latches and tick the declining epoch arm as a miss` |
| r2 | **`011c8d50`** | `[Fix] (Espryt): sweep every image unit the driver holds rather than only the pushed window, and say the seam line when a record names another texture at the validate point` |
| r3 | **`1aee17ca`** | `[Fix] (Espryt): unbind the sampler on every touched unit the pushed window does not describe instead of leaving an earlier draw's object on it` |
| r4 | **`f8002a5e`** | `[Fix] (Espryt): make a half-described framebuffer applier and a mis-keyed program record say the seam line, and refuse a short global-constant block instead of falling back to the frontend block` |
| r5 | **`9b8441a6`** | `[Refactor] (Espryt): index every decline site with the flip it takes at the verification round, and invalidate rather than stamp the forced framebuffer bind` |
Working tree clean at HEAD; `git status --porcelain` empty.
---
## 2. Every review item, and what happened to it
### MAJOR-1 — the image sweep's membership — **FIXED** (`2618-2673`, commit `011c8d50`)
`SyncImageTextureBindings`' handle arm no longer walks `[Start, Start + Count)`. It walks
```
[0, min(max(ShaderImageStart + ShaderImageCount, g_imageUnitHighWaterMark), unitCount))
```
— the record's window **unioned** with the backend's own high-water mark, starting at 0 because a
unit *below* `Start` is as undescribed as one above `Start + Count`. The reasoning is written at the
site (`2618-2656`): D-J2 and `PipeApply.h:461-464` are a rule about **record retention**, not about
which **driver** units a re-issue sweep must visit; the membership this loop needs is "every unit the
driver has an image on", which is `g_imageUnitHighWaterMark` — server-owned and monotonic, because
`SyncImageTextureBinding` is the only path to `glBindImageTexture` and raises the mark on every unit
it hands a texture. DEV-3's own argument, applied here rather than contradicted.
What the record still buys is real and is what `e3` was actually for: the four field **values**
(`Layered`/`Layer`/`Level`/`InternalFormat`) still come off it inside `SyncImageTextureBinding`, and
the walk now stops at the high-water mark instead of at the device's `MaxImageUnits`. The units in
`[end, unitCount)` the pre-handle arm additionally visits have never been given a texture through the
only funnel that can give one, so re-binding 0 on them is a provable no-op — that is the one
remaining behavioural difference from the pre-handle sweep and it is stated in the source.
**A8 added** (§4) and named in the source at `2637-2650`.
### MAJOR-2 — the sampler walk's stale binding — **FIXED** (`4656-4683`, commit `1aee17ca`)
`BindCurrentUnitSamplers`' record arm: a unit in `[0, maxTouchedUnit]` outside
`[SamplerStateStart, SamplerStateStart + SamplerStateCount)` now runs
`SamplerImpl::UnbindSampler(unit)` (`4682`) instead of `continue`. That is the pre-handle arm's
`else { UnbindSampler(unit); }` restored on the new arm, with its reason carried to the new site:
for a **driver** binding, "no record" means "no sampler object", and a sampler left on a unit by an
earlier draw keeps being applied — on a multisample texture the draw is rejected outright. The
alternative the review offered (decline the whole arm when the window does not cover
`[0, maxTouchedUnit]`) was **not** taken: unbinding is the cheaper of the two and is exactly what the
frontend walk does for the same units, so the two arms stay at parity instead of diverging on a
window shape nothing yet pins.
### MAJOR-3 — the two silent seams — **FIXED** (image `2454-2462`, program `3922-3936`; the log lines at `2458` and `3929`, commits `011c8d50` / `f8002a5e`)
All three seams now log the same stem, **`"does not describe the binding it names"`**, so the one
grep §8.2 mandates covers all three:
* framebuffer, `SyncCurrentFBOByRecord` `2895-2896` (unchanged wording — it is the stem);
* **image**, `ResolveShaderImageRecord` `2454-2462`;
* **program**, `ResolveGlobalConstantsRecord` `3922-3936`.
**One thing the review's fix as written would have broken, and how it is handled.** The image seam
cannot log unconditionally. `SyncImageTextureBinding` is *also* the eager funnel `glBindImageTexture`
runs, and at that moment the newest record legitimately describes the **previous** draw — this
package's own §4 says so. An unconditional `MGLOG_E_ONCE` there would fire on the first ordinary
frame of every application and the mandated grep would be worthless. So the seam is loud **only at
the validate point**: `g_imageRecordSeamIsAuthoritative` (`2433`, with its reason at `2423-2432`) is set around the
draw/dispatch sweep's loop and only there (`2665` / `2669`), which are the only two call sites where the set for
*this* draw has been applied. The program seam has no such funnel — its only caller is the global-UBO
upload at the draw validate point — so it is unconditional. Both facts are written at their sites.
### MAJOR-4 — `InvalidateFramebufferHandleArmMemos` — **HANDED TO D, recorded here as A9** (`2776-2790`)
Not fixable in this package (`Managers.cpp` is D's for the phase). Recorded in full at the site E
*can* reach — the function's own definition — naming the three `MG_Test/SanityTest.cpp` callers
(`2530`, `2778`, `2799`) that clear the pre-handle trio and leave `g_fboSyncedSerials` /
`g_fboRecordsTrusted` stale across a GLES function-table swap, and naming the fix: call it from
**inside** `InvalidateFramebufferBindingCache`. On D's rework list.
### The two SILENT decline sites that become loud NOW (ID-19)
**F2 — `SyncCurrentFBOByRecord`, the half-described applier** (`2863-2890`, commit `f8002a5e`).
The site is split into the two cases it was conflating:
* **neither** target recorded — the transitional state of a tree whose client half has not landed,
which is *every* draw on this tree — stays silent and declines; the round flips it;
* **exactly one** recorded — loud, with the stem, naming which target has no record and the
`{slot, gen}` of the one that does (`2882-2888`, the log at `2882`). No correct emitter can produce it: an emitter
walks `{Draw, Read}` together and a `Target = Both` record writes both, so it is exactly the shape
a partially landed emitter produces, and it is invisible in a pixel test because the arm just
declines.
That split is why **the default arm is still 491/491 on this tree** (§5): with no client, both
records are null, which is the silent case. No test names to list as expected-failing.
**P7 — `ResolveGlobalConstantsRecord`, the short block image** (`3943-3977`, commit `f8002a5e`).
This is protocol corruption, not a missing record: the upload copies `GetUBOSize()` bytes out of
`GlobalConstants`, so a shorter block image is a read past the end of the applier's own buffer.
**A judgement the integrator should confirm.** ID-19 says it "must not fall back to `MapUBO()`". The
verdict implemented is the one the contract already spells for every trip wire it owns
(`PipeApply.cpp:22-40`, *"the verdict of every trip wire in this file, in one place"*): under
`MOBILEGL_PIPE_POISON || MOBILEGL_PIPE_VERIFY` it is `MGLOG_F("MGPipe: Fatal{ProtocolCorruption} …")`
(`3959`) + `std::abort()` — so the **gate lanes never reach `MapUBO()` at all**, and G4's `Fatal{` grep finds
it — while any other push build logs the same line at error level, once, and declines. I did not put
an unconditional `abort()` on a shipped game's draw path over a client-side bug, and inventing a
second trip-wire verdict in a backend file would contradict the contract's own one-place rule. If the
integrator wants the stop on every arm it is one `#if` away and the comment at `3943-3956` says so.
The `#if` arm was compile-checked (§5).
### MINOR-1 — the `ReadSurface` claim — **FIXED (comment corrected)** (`2972-2984`)
The comment no longer says the read buffer is applied "from the record's own `ReadSurface`" (it is
not; this package reads `Fbo`, `IsDefault`, `Target`, `DrawBuffers[]` and `ContentHash` and nothing
else). It now says what the change actually buys: the `lastUpdatedFBO` **pointer compare** became a
`record.Target == Both` **field test**, so the read-buffer-shared-FBO defect class can no longer be
produced by an accident of loop order — the defect **expressed as a field**, not made
unrepresentable. Reading `ReadSurface` is the D-C1 endpoint and belongs with A1's rewrite.
### MINOR-2 — ID-12's DV-5 reader assignment — **DECLARED, for the integrator**
Confirmed against this tree: E's diff contains **no `MGPSurface` read at all**, and
`SyncAttachmentObject` is `Managers.cpp` (D's). Nothing to do here; the c0c `TextureTarget` field
lands unread unless the integrator reassigns the reader to D (esprytobj's own source at
`Managers.cpp:8603` already believes it is E's, so the confusion is two-sided).
### MINOR-3 — `ForceBindCurrentFBO` stamping a record-keyed memo — **FIXED** (`4306-4326`)
`StampSyncedFramebufferSerial(target, …)` → `InvalidateSyncedFramebufferSerial(target)` (`4325`), a
new one-line helper beside the stamp (`2797-2801`). The stamp claimed "this target reflects the applier's
record as of this serial" from a path that syncs the **frontend** object out of the binding slot and
never consults the record. Like the review, I could not turn it into a wrong-pixel scenario; it is an
invariant break with no demonstrable failure, and the honest form costs at most one extra sync.
### MINOR-4 — the `PipeStats` gate cannot separate the arms — **FIXED** (`1938-1948`)
`CurrentUnitBindingsEpoch` now ticks `Gate::EsprytUnitBindingsEpoch` with `hit=false` on the
record-arm decline before falling through. Because the walk arm below ticks the *same* gate, every
declining call now contributes at least one miss, so §8.1's *"hit rate should go to 100%"* means
exactly one thing: the record arm answered every time. A distinct gate would have been cleaner but
`PipeStats::Gate` is not this package's file.
### MINOR-5 — the refuted D-K2 mirror sentence — **FIXED, and the fourth row added** (`222-250`)
The comment no longer claims the directions are the brief's three; it states ID-15's correction out
loud (*"D-K2 HAS FOUR ROWS, NOT THREE"*) and `EsprytDrawTextureResourceHandlesEnabled()` now also
requires bit 11 (`242`). The row is spelled as a **raw bit test**, not as a call to the sampler
latch, because the two `static const` latches would otherwise initialise each other. Net effect: the
texture-resource and sampler latches become the same predicate (bits 7 ∧ 10 ∧ 11), which is what the
mutual dependency means. No arm this round tests is affected (`0x1fff`, `0x1ff`, `0` all unchanged).
The four latches are still deleted at the rebase (A4); the comment now names D's **actual wrapper
names** so that deletion is mechanical.
### Also fixed, found this round and not in the review
**G13's `pGLContext` grep had a second hit, in this file** (`315-319`, commit `ba93dfda`). The v1
report's §7.2 recorded `grep -rc 'pGLContext' MobileGL/MG_Backend` as `PipeInputs.h:1`, but the D-F3
paragraph v1 added at `302-316` **spelled the token in a comment**, and G13's grep is a bare-token
grep — so the sentence claiming the purity gates were unaffected was itself the second hit. The
sentence now says the same thing without spelling it. G13 is back to **1** (§5).
---
## 3. The decline-site index
Every row of the review's §2 table has a `// P4a decline-site <id>: <M|S|K> - …` comment at its site,
each naming the flip it takes at the verification round. `grep -n "P4a decline-site"
MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp` returns **30 lines** (29 table rows; F8 has two sites
and carries the marker at both).
| id | line | class | state now | flip at the verification round |
|---|---|---|---|---|
| F1 | 3008 | M | silent | none; becomes D's `FramebufferSubsystemEnabled()` |
| F2 | 2867 | S | **half-described = LOUD now**; both-null silent | flip the both-null case |
| F3 | 2891 | S | loud | keep verbatim — it is the stem |
| F4 | 2947 | S | loud, `continue`s | `g_fboRecordsTrusted = false; return false;` |
| F5 | 4185 | — | silent | unreachable; `MOBILEGL_ASSERT` or delete |
| F6 | 4191 | S | loud | keep (parity with the pre-handle arm: both bind nothing) |
| F7 | 4010 | — | silent | unreachable; same treatment as F5 |
| F8 | 2121, 2270 | K | silent | none — a memo-key selection, not a decline |
| F9 | 4314 | — | **fixed** (MINOR-3) | none |
| T1 | 1905 | M | silent | none; becomes D's `SamplerSubsystemEnabled()` |
| T2 | 1888 | S | silent (+ gate miss ticked) | `MGLOG_E_ONCE` then decline |
| I1 | 2437 | M | silent | none |
| I2 | 2441 | S | silent | loud-once **when the program declares images** |
| I3 | 2445 | M | silent | none |
| I4 | 2450 | — | silent | unreachable by `PipeApply.h:461-464`; keep as defence |
| I5 | 2454 | S | **LOUD now** at the validate point | none (see MAJOR-3 on the eager funnel) |
| I6 | 2653 | M | silent | none — the safe (wider) direction |
| I7 | 2656 | — | **fixed** (MAJOR-1) | none; only A8's measurement |
| S1 | 4646 | M | silent | none |
| S2 | 4650 | S | silent | loud-once, then the frontend walk |
| S3 | 4656 | — | **fixed** (MAJOR-2) | none; only A8's measurement |
| S4 | 4685 | M | silent | none — deliberately not memoised as a miss |
| P1 | 3913 | M | silent | none; becomes D's `ProgramSubsystemEnabled()` |
| P2 | 3882 | S | silent | loud-once, **distinguishing the composite band** |
| P3 | 3888 | S | silent | loud-once — ID-8's stale-generation refusal |
| P4 | 3919 | S | silent | folded into P2/P3 |
| P5 | 3922 | S | **LOUD now** | none |
| P6 | 3937 | M→S | silent | loud-once once bit 12 is on **and** `GetUBOSize() > 0 && HasGlobalUboBlock()` |
| P7 | 3943 | S | **LOUD now** (Fatal-shaped on poison/verify) | confirm the verdict (§2) |
---
## 4. The assumptions, reconciled against D's actual API
Read from `~/w7/p4a-esprytobj/MobileGL/MG_Backend/DirectGLES/Managers.{h,cpp}` (package D v1,
`9bb95335`), read-only. What follows is what the **source now says**, so the rebase is mechanical.
| # | reconciliation, as now written in the file |
|---|---|
| **A1** | `2928-2949`. D adds `BackendPtr* GetOrCreateByHandle(MGPipeHandle)` (`Managers.h:453`) returning a **pointer**, so the fallback is `GetOrCreateByHandle(record.Fbo)` **plus a null check**, not the one-liner v1 predicted; the `slot.GetBoundObject()` resolve above it and `FramebufferRecordMatchesBinding` go with it. The source also carries the **pointer-invalidation** warning (`Managers.h:381-385`): the current `twinSlot ? *twinSlot : GetOrCreate(currentFBO)` short-circuits safely, but `GetOrCreateByHandle` **can grow the table**, so the two must not share one expression after the rewrite. |
| **A2** | Nothing to do; confirmed unchanged in D (`Managers.h:1754`/`:1759` are textually the tag's). The `#else` half of A2 does not fire. |
| **A3** | Signatures hold, so the new read-FBO list compiles unchanged. **The open question is D's new record-keyed cheap gates** (`Managers.h:1709`, `:1715`): once `d2` keys `IsDrawSyncClean` on a record `ParamsSerial`, a **read-only** attachment's serial is one nothing on the read path ever advances — at which point `g_readFboTextureSyncList` may do no work at all. **I expect it still does work**, because `IsDrawSyncClean` requires *both* `m_syncedTextureParamsVersion == GetTextureParamsVersion()` and `m_syncedSamplerVersion == samplerObject->GetVersion()`, and neither is advanced by the read path either — so the first sync for a read-only attachment is still a miss and still pushes. **What the verification round must check** is stated in §6.5: instrument the new list's per-frame push count on the integrated tree at `d2` or later; a count of **zero** means D's re-keying turned D-E3's closure into a no-op and the closure has to move into D's gate instead. |
| **A4** | `202-250`. D's four are **wrappers**, and the names differ from v1's guess: `FramebufferSubsystemEnabled()`, `TextureResourceSubsystemEnabled()`, `SamplerSubsystemEnabled()`, `ProgramSubsystemEnabled()` (`Managers.h:649-663`), which hold the `static const` latch — the `Resolve<Family>SubsystemArm()` resolvers beside them are never the thing to call. The source now names all four and says the local latches are **deleted**, not "kept and updated". ID-15's fourth row is carried (MINOR-5). |
| **A5** | Confirmed against `Managers.h:2158-2169`; nothing to do. DEV-5 stands. |
| **A6** | Unchanged by c0b/c0c — `MGPImageView::Access` still has no documented encoding, so `e3` still does not read it (DEV-6). Stays a C item. |
| **A7** | Confirmed by reading `PipeApply.cpp`; §0's `MGPipeApplierReset` finding stands and is D's input. |
| **A8** *(new, the review's)* | Written into the source at **both** sites it binds: `2637-2650` (images) and `4671-4676` (samplers). Nothing in the contract pins the emitted window's membership to "every unit the driver holds"; until package C documents it in `ImageEmit.h` / `SamplerEmit.h`, MAJOR-1's union and MAJOR-2's unbind are load-bearing. §6.4 is the measurement that would let them be relaxed. |
| **A9** *(new, the review's MAJOR-4)* | Written at `2776-2790`. D's fix, recorded at the site E can reach. |
### The ID-19 framebuffer-record redesign — what I assumed
ID-19 makes the applier's framebuffer state a **per-object table keyed by the framebuffer handle**,
with `BoundFramebuffer[Draw|Read]` holding the bound handles, and says wire v3 keeps
`DrawFramebuffer` / `ReadFramebuffer` as **accessors of those names** resolving through the bound
handle "so E's `SyncCurrentFBOByRecord` keeps its shape".
To make that literally true, **every one of this file's reads of those two names now goes through
one function**, `BoundFramebufferRecord(FramebufferTarget)` at **`284-287`** (declared and argued at
`271-287`, commit `ba93dfda`). The seven call sites are the two F8 memo keys (`2127`, `2273`), the
two identity reads and the per-target loop in `SyncCurrentFBOByRecord` (`2863`, `2864`, `2905`), the
fragColor broadcast derivation (`4009`) and `BindCurrentFBO` (`4179`).
**What I assumed, explicitly:**
1. The names `DrawFramebuffer` and `ReadFramebuffer` survive wire v3 and still answer "the record
describing the framebuffer bound to this target". If they land as **member functions** rather than
members, this file's rebase is *one pair of parentheses inside `BoundFramebufferRecord`* and
nothing else moves.
2. If the accessor can answer "there is no record at the bound handle" (a slot whose generation has
moved, or a binding whose framebuffer never got a record), it answers with a **null `Fbo`** — which
is already exactly what every caller here treats as a decline (F2/F5/F7/F8). If wire v3 chooses a
different "absent" encoding (a null pointer return, say), `BoundFramebufferRecord`'s signature
changes from `const MGPFramebufferState&` to a pointer and the four call sites take a null check;
still one function plus four one-line edits.
3. A `Named` record (`MGPipeFramebufferTarget::Named = 3`) never reaches these six reads, because
they always ask *by target* and a `Named` write does not touch the bound handles. Nothing in this
file interprets `record.Target` except the `Both` skip at `2982-2983`, which compares against
`Both` explicitly and so is unaffected by the new enumerator.
4. D's side of ID-19 (`PushedFramebufferRecord(target, fbo)` → `FramebufferRecordFor(handle)`) is in
`Managers.cpp` and does not appear here; the local accessor is deliberately named
`BoundFramebufferRecord` so it cannot be confused with D's.
---
## 5. Gates — every number
All in `~/w7/p4a-esprytdraw`, `CCACHE_BASEDIR=/home/swung/w7`, `-j 8`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` exported, at **HEAD `9b8441a6`** unless said otherwise.
```
build-linux (pull, PUSH=OFF) rc 0
build-push (PUSH=ON) rc 0 0 warnings in DirectGLES.cpp on either arm
G1 symbol_report.py --threshold 0 --before ~/w7/p4a-before-libMobileGL.so
--after build-linux/libMobileGL.so
file bytes 19114360 -> 19114360 ; .text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed, 27072 unchanged
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (0) <- 0/0/0/0
scripts/p3a_untouched_regions.sh 37da3c3a HEAD rc 0
(the 11 pool / deferred-release / ring / flush-drain functions byte-identical)
RenderStateImpl namespace sha256
d8fd1c48716056c536752fde09db3a9e5aa8494b70404798bfc15d11220efe27
== ~/w7/p4a-before-syncrenderstate.sha and == the sha at 37da3c3a UNCHANGED
D-N, the two in this package's files:
DepthStencilSamplingReadImpl (a NAMESPACE, not a function)
dfefc9964c82f23cb6b89292b2f155ebd2ac22ae442c18a959d38d5bc9063f53 at 37da3c3a AND at HEAD
ShouldUseCaveatTextureFormat: git diff --stat 37da3c3a HEAD -- Utils.h Utils.cpp MultiDraw.cpp
is EMPTY (the whole files are untouched)
ctest --test-dir build-linux -L unit -j 8 100% passed, 0 failed out of 1638
ctest --test-dir build-push -L unit -j 8 100% passed, 0 failed out of 1638
(1638, not v1's 1635: c0c added three PipeCatalogueTest cases)
ctest --test-dir build-push -L integration-gpu -R DirectGLES -j 8
default (0x1fff) 100% passed, 0 failed out of 491
MOBILEGL_PIPE_PUSH=0x1ff 100% passed, 0 failed out of 491
MOBILEGL_PIPE_PUSH=0 100% passed, 0 failed out of 491
C.4's 41-name family regex, -L integration-gpu --no-tests=error -j 4
default 100% 497/497 | 0x1ff 100% 497/497 | 0 100% 497/497
G13 grep -rc 'pGLContext' MobileGL/MG_Backend -> PipeInputs.h:1 (ONE file)
G13b grep -rc 'MGPipeUnmigratedEmulation' .../DirectGLES -> DirectGLES.cpp:4 (+ D's 1 = 5)
MOBILEGL_PIPE_PUSH=ON, MOBILEGL_PIPE_LEGACY_MEMOS=OFF
cmake configure rc 0 ; ninja -C build-nolegacy MobileGL rc 0 (dir removed afterwards)
MOBILEGL_PIPE_VERIFY=1 (the P7 trip wire's Fatal arm)
clang++ -fsyntax-only on DirectGLES.cpp with the build-push flags + -DMOBILEGL_PIPE_VERIFY=1
rc 0, no diagnostics (the abort arm compiles)
Per commit (ba93dfda 011c8d50 1aee17ca f8002a5e 9b8441a6), all five:
-fsyntax-only on both arms rc 0, no diagnostics in DirectGLES.cpp
RenderStateImpl sha d8fd1c48716056c5… (unchanged)
DepthStencilSamplingReadImpl sha dfefc9964c82f23c… (unchanged)
Utils.{h,cpp} / MultiDraw.cpp diff 0 lines
p3a_untouched_regions.sh 37da3c3a <c> rc 0
Hygiene: no TODO/FIXME/printf/std::cout in the diff; git status --porcelain empty;
tools/trace_replay/fixtures/*.tgz are real files, 0 LFS pointers (ID-13) — no retrace
was run, so `git lfs checkout` was not needed, but the tree is clean for one.
```
**The default arm shows no new failures.** The prompt anticipated that the two newly-loud sites might
red the default arm where a record is half-described; they do not, and the reason is structural
rather than luck: F2's loud branch fires only when **exactly one** of the two framebuffer records
exists, and on this tree neither does (the both-null case is still the silent decline, per §2), while
P5/P7 sit behind `FindShaderCsoRecord`, which returns null on a tree with no `ShaderCsos` at all. So
there is **no expected-failing set to name** for E v2. The first tree on which either can fire is the
integrated one.
### Not run here, and why
* **G3 / G3b / G4** (`retrace_gate.py`, the verify lane) — this worktree has no `build-verify`
(DEV-13: it was created without the `verify` argument), and the round's instructions did not add
one. They belong to the integrated tree, together with the two named traces (§6.7).
* **G5's `p4a_untouched_regions.sh`, G6, G7, G8/G8b/G9/G12** — packages B/C/F; none exists on this
tree. D-E3's closure is still **implemented but not demonstrated**.
* **`ctest -L unit` ×3** — the third arm in C.3's list is `build-verify`; two arms were run.
---
## 6. The verification-round checklist (E, on the integrated tree)
0. **Do not run `wsl_tree.sh p4a esprytdraw p4a/contract`** (DEV-13) — it would reset the branch and
drop all ten commits. `refs/heads/p4a/esprytdraw-backup` (`0b00f7f0`) is v1's net; this rework is
only on `refs/heads/p4a/esprytdraw`. `git lfs checkout` in the worktree before any retrace.
1. **Take §4's reconciliations first**, in this order: A4 (delete `202-250`, call D's four
**wrappers**), A1 (`GetOrCreateByHandle` + null check at `2946`, then drop the resolve above it
and `FramebufferRecordMatchesBinding` with it), the ID-19 accessor question (§4 — expected to be
zero or one edit inside `BoundFramebufferRecord` at `284`), then A3.
**c0d is not in this branch**: it did not exist when this round started, so `Tracker.h`'s two
under-fires (ID-17) are unreconciled here and the rebase must pick them up.
2. **Apply the §3 flips**, then run the default mask and assert **every** arm engages:
`SyncCurrentFBOByRecord` returns true, `UnitBindingsEpochFromRecords` answers,
`ResolveShaderImageRecord` returns non-null, `BindCurrentUnitSamplers` sets `walkedFromRecords`,
`ResolveGlobalConstantsRecord` answers. `Gate::EsprytUnitBindingsEpoch`'s hit rate going to
**100%** now means exactly that (MINOR-4).
3. **Zero seam hits.** `grep 'does not describe the binding it names'` across the itest and retrace
logs must be empty for **all three** seams. A hit is a finding against B/C, never a reason to
relax a check. Also `grep 'Fatal{ProtocolCorruption}'` for P7 on the verify lane.
4. **A8's measurement, which is what makes MAJOR-1/MAJOR-2 relaxable or permanent.** With the client
emitting, log `(ShaderImageStart, ShaderImageCount)` against `g_imageUnitHighWaterMark` and
`(SamplerStateStart, SamplerStateCount)` against `keys.maxTouchedUnit` for one Minecraft frame.
If they agree everywhere, C can document the membership in `ImageEmit.h` / `SamplerEmit.h`, the
two fixes become assertions, and DEV-3's `keys.maxTouchedUnit` can also move to the record. If
they do not, both fixes are load-bearing and must stay.
5. **A3 / D-E3: does the new read-FBO list still do work after `d2`?** Count
`g_readFboTextureSyncList`'s pushes per frame. **Zero means D's record-keyed cheap gates turned
the closure into a no-op** and the closure must move into D's gate. This is the one item where my
expectation (§4, A3: it still works, because neither of `IsDrawSyncClean`'s two version compares
is advanced by the read path) has to be **measured, not argued**.
6. **The unit-list equivalence** (the review's §1 "Refuted", last item): compare
`g_unitTextureSyncList` rebuild counts between `MOBILEGL_PIPE_PUSH=0x1ff` (walk arm) and `0x1fff`
(record arm) over one frame. A large drop means the epoch substitution is missing rebuilds.
7. **Named traces**: `photon-v1.3b` on llvmpipe desktop retrace is the canary for `e3`'s image
semantics and is the trace that would have caught MAJOR-1; `improved-transparency-minecraft-26.3`
is the draw-buffer-`None` net for `e1`.
8. **The full C.4 verification**: G1, `p3a_untouched_regions.sh`, `p4a_untouched_regions.sh` (F's —
it needs the **namespace** shape for the `DepthStencilSamplingReadImpl` row), `ctest -L unit` ×3,
`-L integration-gpu` on all three arms, the C.4 family regex, G13's two greps, and
`retrace_gate.py` on `build-push` **and** `build-verify`, plus the `LEGACY_MEMOS=OFF` compile and
the `tcache_count=0` exit-order lanes on both backends — the latter now has a named item to
confirm, `g_rawDepthFetchSamplerState` (the file-static `SharedPtr<SamplerObject>` at `61` (formally named by the D-F3 paragraph at `302-320`),
pre-existing at `37da3c3a`, owned by P3b/P4b).
9. **Carried to other packages, unchanged from the review**: MAJOR-4/A9 → **D**; ID-12's DV-5 reader
reassignment → **integrator**; G9-as-white-box → **F / ROADMAP** (it cannot be written against
public GL; the readback emulation sets `GL_DEPTH_STENCIL_TEXTURE_MODE` itself and
`IsDrawSyncClean` pushes the parameters on the first sample).
10. **Track H census** (unchanged and re-verified): 7 memos re-keyed (3 direct, 4 transitive),
0 retired, 1 bypassed (`UnitSamplerLookupMemo`), 1 new (`g_readFboTextureSyncList`).
---
## 7. Deviations of this round
* **DEV-14 — the image seam is loud only at the validate point.** MAJOR-3 as written asks for an
unconditional `MGLOG_E_ONCE`; that would fire on the eager `glBindImageTexture` funnel, where a
mismatch is *expected*, and would make the mandated grep useless. Implemented as a latch set around
the sweep. Reason and mechanism at `2423-2433`.
* **DEV-15 — P7's verdict is the contract's trip-wire verdict, not an unconditional abort.** §2.
Flagged for the integrator; one `#if` to change.
* **DEV-16 — MAJOR-2 takes the unbind, not the arm-refusal.** §2. Unbinding keeps the two arms at
parity; refusing the arm would diverge on a window shape nothing yet pins.
* **DEV-17 — the four local latches gained a bit rather than losing the comment.** MINOR-5 offered
either; adding ID-15's fourth row makes the temporary latches agree with what D's rework will do,
which is the whole reason the directions were copied here. No arm under test changes.
* **DEV-18 — the six applier reads were funnelled through one accessor.** Not asked for; it is what
makes ID-19's table redesign a zero-to-one-line rebase for this file (§4).
* **DEV-13 still stands** and is repeated in §6.0 because it is the one item that can silently
destroy this branch.
---
## 8. Logs
Deleted per ID-5: `/tmp/p4ae/` (this round's edit scripts, build, ctest and configure logs) and the
`build-nolegacy` directory. `~/w7/p4a-esprytdraw` holds only `build-linux` and `build-push`.
Nothing was written under `~/w7/` except this file. The shared scratchpad `wsl` directory was not
touched (ID-7).
@@ -0,0 +1,690 @@
# P4a package E — `esprytdraw`. Verification round, v3
**Branch** `refs/heads/p4a/esprytdraw`, worktree `~/w7/p4a-esprytdraw`, **HEAD `0cd0d1ec`**,
rebased onto `refs/heads/feat/disaggregated` = **`ee31944b`**. One file,
`MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp`. Nothing was pushed.
This is the round that runs on the first tree where every record this package reads is REAL
(contract c0..c0e, wire v3's applier, clientsp v3, clientfb v2, esprytobj v2). It started on
`17396216`; the integrator moved the pipe to `ee31944b` mid-round (`29d51ab9`, which closes
SD-2 below), so **every number in this report was re-taken on `ee31944b`** and every red one has
a control run of `~/w7/pipe` at the same commit, on the same box, in the same session.
**The verdict, in three lines.**
1. **The arms engage and the flips are taken.** Every decline site that can now speak, does; the
eight-family refusal census is **0 on seven of the ten shapes** (§6.1), and the three
residuals are seam defects against B/C/D with named evidence and patches.
2. **On both itest lanes, E changes nothing.** Default arm 483/491 with E and 483/491 without,
**failing sets byte-identical**; `0x7ff` 438/491 both; DirectVulkan **475/475** both;
`integration-verify` 842/844 both, **zero `Fatal{`**.
3. **On the retrace, E found one real regression of its own - in `e3`, from v2, not from this
round's flips - and this round root-caused it, patched it and verified the patch.**
`create-indirect.DirectGLES` was `FAIL ssim=0.887403` against the control's `PASS 0.999961`;
the cause is a **client-side dirty shutter that cannot see an image re-bind**
(`Tracker.h:518`), the four-line fix is in §SD-0, and with it applied E's retrace is
**62/79 with a failing set identical to the control's**. The patch is in another package's
file and is therefore reported, not committed.
Two findings are larger than this package and are handed up: the tree's own **62/79** at the
default retrace mask, seventeen shader-pack traces wrong with **no refusal behind them** (§7),
and the sampler-record residual that costs two scenarios a correct picture (§SD-1).
---
## 1. The rebase, and the commit series
`git rebase refs/heads/feat/disaggregated` replayed all ten v2 commits **clean** - no conflict,
one file - both onto `17396216` and again onto `ee31944b`. D's replay touched none of the lines
this package touches. Four new commits on top:
| commit | what |
|---|---|
| `ea3d664c` | **A4 + the ID-19 accessor.** The four temporary family latches (`EsprytDraw*HandlesEnabled`) deleted; all 12 consults now call D's public wrappers `FramebufferSubsystemEnabled()` / `TextureResourceSubsystemEnabled()` / `SamplerSubsystemEnabled()` / `ProgramSubsystemEnabled()`. `BoundFramebufferRecord` takes wire v3's landed shape. |
| `90f0c35a` | **A1 + ID-27 + F2/F4/F5/F7.** The framebuffer twin resolved by handle; the `Both` test replaced by the applier's bound handles; the undescribed-binding declines made loud. |
| `3d6fcc4c` | **The remaining flips** - T2, I2, S2, P2, P3, P4, P6 - and the M/K sites' comments updated to record that the round left them silent deliberately. |
| `0cd0d1ec` | **The one flip the first real-path run corrected**: T2 and S2 scoped to a draw that actually touches a texture unit. |
The final diff against pipe is `1371 +/38 -`, one file.
### The `git lfs checkout` trap, recorded because it cost two runs
The task said "`git lfs checkout` first". On this box that is **wrong and destructive**: LFS
content is not local (`Skipped checkout … content not local`), so the checkout **replaced every
real trace fixture with its 130-byte pointer** and the first retrace came back 1/79 with
`0s ssim=None` on 78 of them. The working recipe is `wsl_tree.sh`'s: copy from
`~/w7/pipe/tools/trace_replay/fixtures/` and re-apply `git update-index --assume-unchanged`.
**And `git reset --hard` undoes it again** - `--assume-unchanged` does not survive one - which
is how it happened a second time while the commit series was being rebuilt. Anyone re-running a
retrace on a package tree must re-copy the fixtures immediately before it.
---
## 2. ID-27 — the `Both` question is now asked of the applier's own fact
`DirectGLES.cpp:2983` (v2) tested `record.Target == MGPipeFramebufferTarget::Both` to decide
whether one framebuffer is bound to both bindings and the DRAW pass's attachment work need not
be repeated. Since ID-19(c) the stored `Target` is the **last emission's** target, and B v2
emits `Named` records at sixteen DSA sites, so:
* a framebuffer genuinely bound to both bindings can carry `Target == Named`, and
* a framebuffer bound to neither can carry a stale `Target == Both`.
Replaced by `BoundFramebuffer[Draw] == BoundFramebuffer[Read]` - the applier's own fact, a
`{slot, gen}` comparison, with both handles already proved non-null by F2 three lines up. The
old test degraded to a *redundant* read-buffer sync rather than to a wrong picture (the
`!= Both` path takes the full `SyncToBackend`, which is correct and merely repeats work), which
is exactly why no lane caught it and the wire review had to read the emitter. `grep 'record.Target'
DirectGLES.cpp` is now **empty**, and so is `grep '.Target =='`.
---
## 3. The seven assumptions, reconciled against D's and wire's ACTUAL landed code
| # | what the integrated tree actually says | what E did |
|---|---|---|
| **A1** | `BackendPtr* GetOrCreateByHandle(MGPipeHandle)` at `Managers.h:453` returns a **pointer** and declines three ways (legacy arm, slot past the sanity bound, generation behind the live entry's), silently, "for its release-build voice at the per-kind resolver". | The twin is now resolved **by handle only** - the `FindByHandle`-else-`GetOrCreate(currentFBO)` pair is gone, so no twin on this arm can be minted against the bound frontend *address*. The null return is a **loud whole-arm decline** naming the handle and `LiveGenAt(slot)`. |
| **A1, two corrections to the review's sketch** | `slot.GetBoundObject()` **stays**: A2's `#else` never fired, so `SyncToBackend(SharedPtr<FramebufferObject>, target)` still takes the frontend object as its argument. `FramebufferRecordMatchesBinding` (F3) **stays**: §2's "keep verbatim; it is the wording §8.2 greps" governs, and with the twin now resolved from the record and configured from the bound object, that identity check is the only thing between a mis-keyed record and one framebuffer's attachments written into another's twin. | recorded at the site |
| **A2** | Confirmed unchanged: `Managers.h:1769`/`:1774` still take `const SharedPtr<FramebufferObject>&`. | nothing |
| **A3** | **The feared no-op does not exist, and this is settled by code rather than by a counter.** D added `m_syncedResourceSerial` / `m_syncedParamsSerial` **beside** the legacy members and re-keyed the *sync functions*; `IsDrawSyncClean` (`Managers.h:1565-1583`) still compares the FRONTEND's `GetTextureParamsVersion()` twice, `GetContentVersion()`, and `samplerObject->GetVersion()`, and returns **false outright when the texture has no sampler object at all**. Nothing on the read path advances any of those, so a read-only attachment's first sync is still a miss and `g_readFboTextureSyncList` still pushes. | nothing; D-E3's closure stays where it is |
| **A4** | D's four wrappers exist with the predicted names at `Managers.h:650-665`, holding the `static const` latch; the resolvers carry the refusals, **including D-K2's fourth row** (`ResolveTextureResourceSubsystemArm`, bit 10 requires bit 11, with both mirror pairs said out loud). | E's four latches **deleted**; no dependency direction is restated in this file any more. |
| **A5** | Confirmed. | nothing |
| **A6** | `MGPImageView::Access` now HAS an encoding - `MGPipeEncodeImageAccess` in C's `ImageEmit.h` - but nothing in the contract documents it as read-back-able, and `e3` still does not read it. | unchanged; still a C documentation item |
| **A7** | Confirmed. | nothing |
| **A8** *(the one that had to be measured)* | **Image half: MAJOR-1's union is PERMANENT, and C's own source says so.** `ImageEmit.h:63-80` derives the window from "the highest image unit the CURRENT PROGRAM names … unioned with a sticky mark of every unit this emitter has already described" - explicitly *not* every unit the driver holds. The five I2 hits in §6 are that gap, observed. **Sampler half: C's window is `[0, GetMaxTouchedTextureUnit()]`** (`SamplerEmit.h:822-825`), the same bound E's walk uses, so MAJOR-2's unbind is *expected* unreachable - but it is capped at `kMGPipeMaxTextureUnits` and gated by a content-hash suppressor, so it may only become an assertion once **C documents the membership in `SamplerEmit.h`**. Until then both stay load-bearing. |
| **A9** | D landed `InvalidateFramebufferHandleArmMemos` inside `InvalidateFramebufferBindingCache`. | closed |
**The ID-19 accessor question, answered.** Wire v3 landed `DrawFramebuffer()` / `ReadFramebuffer()`
as member **functions** returning a **nullable pointer** - i.e. *both* halves of v2's DEV-18
prediction. Because every read in this file goes through `BoundFramebufferRecord`, the rebase
was that one function plus a null check at each of its four call sites, and nothing else moved.
---
## 4. The flip table, as executed
`grep -c 'P4a decline-site' DirectGLES.cpp` = **30** (29 rows, F8 twice), unchanged.
| id | class | v2 state | **flip taken this round** |
|---|---|---|---|
| F1 | M | silent | none; **is** `FramebufferSubsystemEnabled()` now |
| F2 | S | half-described loud, both-null silent | **both-null now LOUD** - names both bound handles and `StaleFramebufferRecordLookups`, so "no record was written" and "the slot's generation moved" are told apart without a third message |
| F3 | S | loud | **kept verbatim** (the stem §8.2 greps); only the dereference changed. Deliberately kept against the review's A1 sketch - see §3 |
| F4 | S | loud, `continue` | **`g_fboRecordsTrusted = false; return false`** + the record's handle in the message |
| F5 | — | silent | **`MOBILEGL_ASSERT` + a kept null check** (not deleted: a release build must not deref null if the ordering ever changes) |
| F6 | S | loud | kept - parity with the pre-handle arm |
| F7 | — | silent | same treatment as F5 |
| F8 ×2 | K | silent | none; gained wire v3's null check, which is not a decline |
| F9 | — | fixed in v2 | none |
| **NEW** | S | — | **A1's third decline**: `GetOrCreateByHandle` returning null is a loud whole-arm decline naming the handle and `LiveGenAt(slot)` |
| T1 | M | silent | none; **is** `SamplerSubsystemEnabled()` now |
| T2 | S | silent | **loud-once, then decline — scoped to `maxTouchedUnit >= 0`** (see §6.1a) |
| I1 | M | silent | none |
| I2 | S | silent | **loud-once at the validate point when the unit holds an image texture** - a strictly narrower and more informative condition than the review's "when the program declares images", and the flip that found SD-4 |
| I3 | M | silent | none, and **deliberately not folded into I2**: A8 says nothing pins the window's membership, so a unit *outside* it is not evidence the way an *empty* set is |
| I4 | — | silent | kept as defence; **not** an assertion (that bound is the applier's, not this file's latch) |
| I5 | S | loud | none |
| I6 | M | silent | none - I2 speaks once from inside the sweep instead, where the unit can be named |
| I7 | — | fixed in v2 | none |
| S1 | M | silent | none |
| S2 | S | silent | **loud-once, then the frontend walk — scoped to `maxTouchedUnit >= 0`** |
| S3 | — | fixed in v2 | none |
| S4 | M | silent | none |
| P1 | M | silent | none; **is** `ProgramSubsystemEnabled()` now |
| P2 | S | silent | **loud-once, telling the two bands apart** - an out-of-range ordinary slot says "no `create_shader_state` arrived" (client seam), an out-of-range composite index says the band base or the decode is wrong (contract bug) |
| P3 | S | silent | **loud-once**, naming *dead* vs *live-but-differently-generationed* - ID-8's stale-generation refusal |
| P4 | S | silent | **folded into P2/P3**: stays silent because both causes have just spoken with the band and the generation named |
| P5 | S | loud | none |
| P6 | M→S | silent | **loud-once**, and the review's condition is not retested here because the **only caller already guarantees it** (`GetUBOSize() > 0 && backendProgram.HasGlobalUboBlock()`, the global-UBO upload) |
| P7 | S | loud (Fatal-shaped) | verdict confirmed - **0 `Fatal{ProtocolCorruption}` on the verify lane** |
### 4.1 Every arm engages
The default-arm run is not merely green, it is green *through the new arms*: with F2, F4, T2,
S2, I2, P2, P3, P6 all wired to speak on a decline, the census in §6 shows **zero** hits for
every framebuffer, program and sampler-window site over 491 scenarios. A declining arm cannot
be silent any more, so "no message" now means "the arm ran".
---
## 5. The lanes — every number
All on `~/w7/p4a-esprytdraw` at **`0cd0d1ec`** on **`ee31944b`**, `CCACHE_BASEDIR=/home/swung/w7`,
`-j 8`, `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`. The box was shared (load ~45 on 28 cores)
with the gate run and package D's round throughout. Every red number below has a **control run
on `~/w7/pipe` at the same commit, on the same box, in the same session**, and every one of
them matches.
```
build-linux (pull) rc 0 build-push rc 0 build-verify rc 0
build-nolegacy (MOBILEGL_PIPE_LEGACY_MEMOS=OFF, PUSH=ON) configure rc 0 build rc 0
0 warnings in DirectGLES.cpp on any of the four
G1 symbol_report.py --threshold 0, before ~/w7/p4a-before-libMobileGL.so
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 RESIZED, 0 renamed
G2 pull-vs-push ctest name diff 0 lines
G14 vs the P4a before-set 0 removed, +141 added, 2729 total
G5 scripts/p3a_untouched_regions.sh 37da3c3a HEAD rc 0 (P3a's eleven byte-identical)
G5 ~/w7/p4a-gates/scripts/p4a_untouched_regions.sh rc 0 (the seventeen)
DepthStencilSamplingReadImpl 822ca3b0ece4e662f9b462945f2697f6b14547d841d926ae94c2b35139f16e53
ShouldUseCaveatTextureFormat 266710e0fdc19756f31e27dcee536149c99fc9fe583752042135b3a9cde26366
== the two shas D's report prints; these are the two D-N rows that live in E's file
RenderStateImpl sha d8fd1c48716056c53675 == ~/w7/p4a-before-syncrenderstate.sha
pGLContext in MG_Backend MG_Backend/MGPipe/PipeInputs.h:1 == pipe's, unchanged
MGPipeUnmigratedEmulation in DirectGLES.cpp 4
record.Target / .Target == tests in DirectGLES.cpp 0 (ID-27)
ctest -L unit build-linux 1763/1763 build-push 1763/1763 build-verify 1763/1763
emitter/CSO suites (build-push) 168/168
```
### 5.1 `-R DirectGLES -L integration-gpu`, six arms, with the control beside each
| mask | E (`0cd0d1ec`) | pipe without E (`ee31944b`) | verdict |
|---|---|---|---|
| **default `0x1fff`** | **483/491**, 8 failed | **483/491**, 8 failed | **failing sets byte-identical** |
| `0x1ff` | 485/491, 6 failed | — | the six armless `.Handles` aborts |
| `0` | 485/491, 6 failed | — | same six |
| `0x3ff` | 485/491, 6 failed | — | same six |
| `0x7ff` | 438/491, **53 failed** | **438/491, 53 failed** | **identical** — SD-5, a D-side half-run |
| `0xfff` | 483/491, 8 failed | — | same eight as the default |
| C.4 family regex (default) | **495/497**, 2 failed | — | the 2 are SD-1's pair |
| **`-R DirectVulkan`** | **475/475** | **475/475** | **unchanged, and clean** |
The eight default-arm failures are **six + two**:
* six `DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.*` **(Subprocess aborted)** —
category (a), F's, expected until F lands. **Positively identified this round rather than
assumed**: their logs carry exactly one line, `Fatal{PipeLegacyMemosDisabled, "MOBILEGL_PIPE_PUSH
leaves kMGPipeSubsystemSamplers (bit 11) clear (or refuses it) and MOBILEGL_PIPE_LEGACY_MEMOS
…"}` — the itest's 0x1ff pin meeting D's armless stop.
* `IntegerBorderColorScenario.SamplerParameterIivBorderColourSurvivesToAnIntegerSampler` and
`SampledSetStalenessScenario.AQueuedClearIsMaterialisedWhenASamplerObjectCompletesTheTexture`
— category (b): **a NAMED REFUSAL**, seam defect **SD-1**, §6.2.
### 5.2 `-L integration-verify` (build-verify, `tcache_count=0`)
```
842/844 passed, 2 failed, 0 Timeout, 0 Subprocess aborted, 0 Not Run
Fatal{ lines: 0
the 2 = DirectGLES.Verify.{IntegerBorderColor…, SampledSetStaleness…} = SD-1, again
```
Zero `Fatal{` is P7's verdict confirmed and the exit-order lane clean on both backends.
---
## 6. The census, and the seam defects
### 6.0 The census could not be taken the obvious way, and the first attempt was a false ZERO
`MOBILEGL_LOG_ENABLE_CONSOLE` is **0** (`MobileGL/Defines.h:71`), so the library's log has
exactly one sink: the file named by `MOBILEGL_LOG_FILE_PATH`. Grepping `ctest -V` output -
which *does* capture every test's stdout - therefore returns **zero of everything, always**, and
looks exactly like a clean census. Setting one `MOBILEGL_LOG_FILE_PATH` for the whole run does
not work either: `Log.cpp:71` opens it with `"w"`, so 491 processes truncate each other and only
the last survives.
**The recipe that works, and that the integrator and package D should both use.** Move
`build-push/MobileGL/MG_IntegrationTest/MobileGLIntegrationTest` aside to `….real` and put a
four-line shell shim in its place that gives each process its own log file, **named after its
`--gtest_filter`** so a residual can be traced back to its scenario, and that leaves an
already-set `MOBILEGL_LOG_FILE_PATH` alone so the four scenarios that manage their own
(`PoisonOmission`, `PointSizeDemotion`, `StorageBufferRegrow`, `PrimitivesGeneratedNoXfb`) are
unaffected.
**One trap inside the trap:** any `cmake --build` after installing the shim RE-LINKS over it,
after which a naive re-install sees `….real` already present and shims the *stale* binary. Delete
both and rebuild. One census run was thrown away to this.
**Positive control, so the zeros below mean something**: the same harness at
`MOBILEGL_PIPE_PUSH=0x9ff` on one scenario produces
`ERROR]: MGPipe: kMGPipeSubsystemSamplers (bit 11) is set but kMGPipeSubsystemTextureResources
(bit 10) is clear …` - D's dependency refusal, captured.
### 6.1 The census — all TEN shapes, not eight
ID-34's N-2 corrected the census from six shapes to eight. **It is still short by two, and by
its own method**: `grep 'applier record' Managers.cpp` cannot see `:7584` and `:7895`, because
there the phrase straddles a string-literal line break (`"… has no applier "` / `"record …"`).
Both are the **built-in sampler CSO** family, and one of them fires on this tree.
`-R DirectGLES -L integration-gpu`, 491 scenarios, 477 processes that logged:
| # | shape (`Managers.cpp`) | **default `0x1fff`** | `0x1ff` |
|---|---|---|---|
| 1 | `:6310` texture … storage and uploads cannot be driven | **0** | 0 |
| 2 | `:7564` texture … built-in sampler cannot be pushed | **0** | 0 |
| 3 | `:7778` texture … parameters cannot be pushed | **0** | 0 |
| 4 | `:8866` framebuffer … its read buffer cannot be pushed | **0** | 0 |
| 5 | `:9083` framebuffer … cannot be synced from the pushed record | **0** | 0 |
| 6 | `:11925` program … no shader-CSO applier record | **0** | 0 |
| 7 | `:12174` sampler … its parameters cannot be pushed | **2** → **SD-1** | 0 |
| 8 | `:12418` renderbuffer … storage cannot be allocated | **0** | 0 |
| **9** | `:7584` built-in sampler CSO … declining the built-in sampler push | **3** → **SD-3** | 0 |
| **10** | `:7895` built-in sampler CSO … border colour cannot be pushed | **0** | 0 |
| — | E's three seam lines (`does not describe the binding it names`) | **5** → **SD-4** | 0 |
| — | `Fatal{ProtocolCorruption}` | **0** | 0 |
| — | `Fatal{PipeLegacyMemosDisabled}` | 6 (= the six armless aborts) | 6 |
`0x1ff` is zero for every row by construction (all four E families take their M sites), and is
recorded because it is the arm the six aborts are pinned to.
### 6.1a The flip the run corrected — T2 and S2, 333 false positives
Before `0cd0d1ec`, T2 fired in **172** of 477 processes and S2 in **161**, and every single S2
line said `units 0..-1`. `maxTouchedUnit < 0` is "this draw touches no texture unit at all", for
which an empty sampler-view / sampler-state window is not a seam defect but **the only correct
emission**. Both are now scoped to `maxTouchedUnit >= 0` and both are **0**. This is the one
place where the review's table, written before C landed, asked for a rule the real path
disproved; the site comments say so and say how it was measured. The MINOR-4 gate tick still
counts *every* decline, loud or not, so nothing became uncountable.
---
## SD-0 — **E's own regression, found and root-caused: `create-indirect` on DirectGLES**
This is the one defect the round found *in this package's own consequences*, and the only
difference between E's retrace and the control's.
```
retrace, default mask, 79 cases
~/w7/pipe at ee31944b, WITHOUT E 62 / 79
~/w7/p4a-esprytdraw at 0cd0d1ec 61 / 79
the single difference:
MobileGLTraceReplay.minecraft-1.21.1-neoforge-create-indirect-in-world.DirectGLES
E FAIL ssim=0.887403 pipe PASS ssim=0.999961 (deterministic, 4/4 runs each)
```
**Bisected to the commit**, by rebuilding at six points across E's fourteen commits (the pre-wire-v3 ones
carry a mechanical accessor fix so they compile; it is behaviour-preserving - a null answer
becomes a zeroed record, which is what a null `Fbo` already was):
```
ee31944b base PASS 0.999961
78967961 e1 framebuffer records PASS 0.999961
6c63e017 e2 texture sync lists PASS 0.999961
1e1a042f e3 SHADER IMAGES FROM THE PUSHED SET FAIL 0.887403 <-- first bad
9aca1457 e4 FAIL 0.887403
15ab31dc … through 0cd0d1ec FAIL 0.887403
```
**Bisected to the field**, with each of `e3`'s four record-sourced fields put behind its own
switch:
```
drop record->Layered FAIL drop record->Level PASS <-- this one
drop record->Layer FAIL drop record->InternalFormat FAIL
```
**Root cause, and it is NOT in `DirectGLES.cpp`.** `MGPipeDirty::NewShaderImages`'s shutter is
`Mix(Mix(textureContent, textureParams), programImages)` (`Tracker.h:518-519`), and
`ImageEmit.h:20-25` states that as an invariant: *"all three FRONTEND counters"*. **None of the
three moves when `glBindImageTexture` re-binds a texture that is already on that unit and
changes only `level`** (or `layer`, `layered`, `format`, `access`). So `wants(NewShaderImages)`
is false, `EmitShaderImages` never runs, the applier keeps the PREVIOUS bind's `Level`, and
`e3` - the first code anywhere to read that field off the record - paints the wrong mip.
The set-hash suppressor cannot save it: the emitter is never called, so no hash is ever taken.
Flywheel/Create does exactly this, which is why one trace in 79 finds it.
**Ruled out along the way** (each rebuilt and re-run): trusting the record at the eager
`glBindImageTexture` funnel rather than only at the validate point (`FAIL` either way, so
DEV-14's latch is not implicated); ID-27's bound-handle comparison (`FAIL` with the old
`record.Target == Both` restored); A1's `GetOrCreateByHandle` (`FAIL` with `FindByHandle` +
`GetOrCreate(currentFBO)` restored).
**The patch, written and VERIFIED, for the owner of `MG_Impl/Pipe/Tracker.h`** (C / the
contract - not E's file under C.7, so it is *not* committed on this branch):
```c++
// Tracker.h, in Update(), replacing lines 518-519
now[Index(MGPipeDirty::NewShaderImages)] = MGPipeMixShutter(
MGPipeMixShutter(MGPipeMixShutter(textureContent, textureParams), programImages),
ctx.GetTextureBindGeneration());
```
`glBindImageTexture` already calls `NoteTextureUnitTouched` (`GL_Texture.cpp:6741`), so that
generation moves on every image bind and nothing new has to be counted - which matters, because
`ImageEmit.h:69` records that adding a counter to `TextureState` would resize the pull build's
object and G1 forbids it. It is also the shape `NewSamplers` already uses two lines above, with
Tracker.h's own argument for it: *"MIXING THE GENERATION IN IS THE FIX RATHER THAN A SECOND GATE
ON THE EMITTER"*. Measured with the patch applied to this tree:
```
create-indirect.DirectGLES PASS ssim=0.999961 (was FAIL 0.887403)
DirectGLES integration-gpu unchanged
DirectVulkan integration-gpu unchanged
full retrace see §7
```
`ImageEmit.h`'s invariant-2 paragraph must be reworded in the same commit: it currently says the
shutter is three frontend counters *and gives that as the reason the sweep's gate is sound*. It
becomes four, and the added one is still a frontend counter, so the property it protects
survives - but the sentence as written is now the documentation of a bug.
---
## SD-1 (category (b)) — the sampler family refuses, and it is the tree's only wrong picture on the DirectGLES itest lanes
**Refusal**, twice, one per scenario:
```
ERROR]: MGPipe: sampler 1 has no applier record on the handle arm, so its parameters
cannot be pushed (handle {8, 0}) IntegerBorderColorScenario…IntegerSampler
(handle {6, 0}) SampledSetStalenessScenario…CompletesTheTexture
```
**Reading side**: `Managers.cpp:12174`, `BackendSamplerObject::SyncToBackend` - D's file. It
resolves the sampler CSO record for the handle and declines when there is none; it does **not**
fall back to the frontend, by design.
**Emitting side**: package **C** (`clientsp`, `SamplerEmit.h`). No `create_sampler_state` has
been applied for the sampler object the draw binds. The generation in both handles is **0**
while the slots differ (6 and 8): the handle was *acquired* (the slot exists) but never
*described*.
**The failure is visible, not silent**, which is what makes it the most important residual:
`IntegerBorderColorScenario.SamplerParameterIivBorderColourSurvivesToAnIntegerSampler` reads
back `component 0 = 0 instead of 255`, `1 = 0 instead of -1`, `2 = 0 instead of 7` and
`3 = 1065353216 instead of 3` on **64 of 64 texels**. `1065353216` is `0x3F800000` - **`1.0f`
reinterpreted as an integer** - so the integer border colour was not merely lost, the FLOAT form
was applied in its place. That is `SamplerParameters::borderColorForm` (the field F's G7
negative control targets) not reaching the driver because the record it rides on was never
created.
**Not E's**: identical on `~/w7/pipe` without this package, on both the gpu and the verify lane.
**Patch, for package C.** The refusal is at the *first* `SyncToBackend` of a sampler object
whose CSO record was never emitted, so the fix is birth-side, not per-draw: every path that
acquires a `SamplerCso` slot for a `SamplerObject` must emit `create_sampler_state` before any
handle naming it can reach the applier - the "mint-and-create in one step" shape
`TextureEmit.h:943-949` already has. Two things to check first, in this order:
1. `glSamplerParameterIiv` / `glSamplerParameterIuiv` are the entry points both failing
scenarios use. If `SamplerEmit.h`'s parameter hooks cover the `f`/`i` forms but not the
integer `Iiv`/`Iuiv` forms, the object is never marked dirty and never emitted - which fits
`Gen == 0` exactly.
2. `SampledSetStalenessScenario` binds a sampler object to *complete* an incomplete texture,
i.e. the sampler is created and bound with **no parameter call at all**. If the emission
hangs off a parameter hook rather than off the object's birth, that case can never emit.
Both point at one rule: **emit on acquire, not on first parameter.**
---
## SD-2 (category (c)) — bit 10 cost the DirectVulkan lane 66 tests, and it was fixed under this round
Recorded because this round found it independently and its bisect is worth keeping.
On `17396216` (the tree this round started on), on `~/w7/pipe`'s own `build-push`, **without E**:
```
MOBILEGL_PIPE_PUSH=0 475/475 =0x3ff 475/475 =0x1000 475/475
=0x1ff 475/475 =0x7ff 409/475 =0x11ff 475/475
=0x1fff 409/475 =0xfff 409/475
```
Exactly **bit 10** (`kMGPipeSubsystemTextureResources`), deterministic
(`DirectVulkan.EmptyScissorScenario.AnExplicitlyEmptyScissorBoxClipsEveryFragment` reproduces
serially and single-process), and identical with and without E. The integrator's `29d51ab9`
("gate the four P4a families on a backend having registered `MGPipeResourceOps` - Magma emitted,
the applier accepted, and the acceptance-cleared dirty flags left its legacy path nothing to
upload") landed while this round was running and **closes it**: on `ee31944b` the lane is
**475/475 with and without E**.
Two things from this round's own investigation are worth keeping in the record, because they
would have sent the next person down the same two dead ends:
* a **negative control that refuted the obvious single-line culprit**: putting only
`TextureEmit.h`'s `mipmap->MarkStorageDirty(uploadTarget, level, false)` (the sub-data
acceptance clear) behind a switch left the lane at **66 failed either way**. The clear that
mattered was on a different path, which is why `29d51ab9` had to gate the whole family
rather than one call;
* the reading side, for the record: `VkTextureManager::UploadDirtyMipLevels`
(`VkTextureManager.cpp:2873`, and `:1828`) skips any level whose `IsStorageDirty` is false,
and no `MG_Backend/DirectVulkan` file reads `MGPipeApplier().TextureResources` or
`PendingUploads` - so Magma could only ever lose by the emission, never gain by it.
---
## SD-3 (category (b)) — the built-in sampler CSO family refuses, in the two shapes the census cannot see
```
ERROR]: MGPipe: texture N's built-in sampler CSO {slot, gen} has no applier record
- declining the built-in sampler push x3
DepthStencilReadbackMatrixScenario.ReadbackLeavesNoGLStateBehind
UnboundImageDescriptorScenario.ABufferTextureWithNoAttachedBufferDoesNotLoseTheDraw
```
Both scenarios **pass**, so this is a silent fallback rather than a wrong picture - which is
exactly why it has to be reported: the record for a texture's `MGPTextureParams::BuiltinSampler`
handle was never applied, and D's twin declines the push instead of using it. Same owner and
almost certainly the same root cause as SD-1 (C never emitted `create_sampler_state` for a
sampler CSO whose handle it had already acquired); the difference is only which side holds the
handle - here the texture record's built-in sampler rather than a bound `SamplerObject`.
**Owed by D's report (documentation) and C (code).** D: add `:7584` and `:7895` to the census in
`esprytobj-v3.md` §4/§5 and say that the stem `no applier record on the handle arm` matches only
**seven of ten**. The integrator's residual check must grep **four** patterns, not two:
`no applier record on the handle arm`, `no shader-CSO applier record`,
`declining the built-in sampler push`, `border colour cannot be pushed`.
---
## SD-4 (category (b), found by E's own I2 flip) — `set_shader_images` is never emitted for a buffer-texture image
```
ERROR]: An image record does not describe the binding it names: image unit 0 holds a
texture at a draw and no set_shader_images has ever been applied; running the
pre-handle image bind. x5
BufferTextureScenario.AnImageStoreIntoABufferTextureIsVisibleToTheCpu
ImageTargetKindScenario.LoadsTextureBuffer
ImageTargetKindScenario.StoresTextureBuffer
NonCoreImageFormatScenario.ASplitBufferImageStillSamplesWholeTexels
NonCoreImageFormatScenario.BufferImageAddressesTheApplicationsOwnTexels
```
All five pass, because E declines to the pre-handle bind - the fallback MAJOR-1's union exists
to protect. **The discriminator is the buffer flavour and nothing else**:
`ImageTargetKindScenario` runs one shader template over `uimage1D`, `uimage1DArray`,
`uimage2D`, … and `uimageBuffer`, and **only the `Buffer` kind appears here**.
**Emitting side**: `ImageEmit.h:81-90`. The window is
`resolution.MaxImageUnit < 0 ? 0 : MaxImageUnit + 1`, and `count == 0` takes the zero early-out
before any hash - so **no `set_shader_images` is ever applied for the life of the process**.
`MaxImageUnit` comes from `SamplerEmit.h:635-642`, which counts a uniform location only when
`GetUniformSamplerOrImageUnitIndex(location) >= 0 && GetUniformTypeFacts(location).isImage`.
For an `imageBuffer` uniform one of those two answers wrongly; the unit index is the likelier -
ES forbids `glUniform1i` on an image uniform, so it can only come from `layout(binding=)` at
link, and `ProgramLinkTask.cpp:57` sets `isImage` straight from glslang's `type->isImage()`.
**Reading side**: `DirectGLES.cpp`'s I2, the flip this round installed, which is the only reason
this is visible at all.
**Patch, for package C**, in preference order:
1. Fix the reflection so an `imageBuffer` / `uimageBuffer` / `iimageBuffer` uniform contributes
its unit to `MaxImageUnit`. If the gap is in `uniformSamplerOrImageUnitIndex` rather than in
`isImage`, that is `MG_State`'s file and outside P4a's set - the integrator has to grant it,
and it is then a **pre-existing frontend reflection gap that P4a's client emitter is the
first code to depend on**, worth saying in the phase's docs.
2. Failing that, union the emitted window with the units the CONTEXT actually holds an image
binding on - the same union E's sweep already takes server-side (MAJOR-1), which would make
the two sides agree by construction.
Until one of them lands, **A8's image half is settled: MAJOR-1's union in
`SyncImageTextureBindings` is permanent and may not become an assertion.**
---
## SD-5 (category (c), pre-existing) — `0x7ff` half-runs the framebuffer family against a refused texture family
53 DirectGLES scenarios fail at `MOBILEGL_PIPE_PUSH=0x7ff`, **identically with and without E**,
where every other arm this round ran is 6 or 8. The shape is D's:
`ResolveTextureResourceSubsystemArm` refuses bit 10 because bit 11 is clear (D-K2's fourth row,
correctly), so the texture family runs the LEGACY arm - but
`ResolveFramebufferSubsystemArm` tests **the raw mask bit 10**, not the texture family's
resolved verdict, so the framebuffer family ARMS. That is precisely the half-run D-K2 exists to
forbid, one level up: the dependency is expressed against the BIT and the bit lies whenever the
depended-on family refused itself.
**Patch, for package D** (`Managers.cpp`, `ResolveFramebufferSubsystemArm`): make the row read
the arm rather than the bit -
```c++
// bit 9 requires the TEXTURE-RESOURCE ARM, not merely bit 10: bit 10 can be set and still
// refused (bit 10 requires bit 11), and a refused family runs its legacy arm, which is
// exactly the state MGPSurface::Res cannot be resolved against.
refused = !TextureResourceSubsystemEnabled(); // logs its own reason
```
with the existing `PipeSubsystemDependencyMissing` line kept for the plain bit-10-clear case so
the message still names both bits. `0x7ff` is not a shipped mask, so this is not urgent - but it
is a lane that reports 53 failures to anyone who sweeps the masks, and F's dependency-refusal
scenario is the natural place to pin it.
---
## 7. The retrace, and what it says about the tree rather than about E
`python3 ~/w7/retrace_gate.py --tree ~/w7/p4a-esprytdraw --lib build-push/libMobileGL.so
--out ~/w7/retrace-out/p4a-esprytdraw-v3 -j 4`, default mask, 79 cases.
```
~/w7/pipe ee31944b, WITHOUT E 62 / 79 17 failed, all DirectGLES
~/w7/p4a-esprytdraw 0cd0d1ec 61 / 79 18 failed, all DirectGLES
~/w7/p4a-esprytdraw 0cd0d1ec + SD-0's Tracker patch 62 / 79 17 failed - THE SAME SEVENTEEN,
set-identical to the control
```
So the whole of E's retrace delta is **one case**, `create-indirect.DirectGLES`, and SD-0's
four-line patch closes it exactly.
**79/79 was not obtainable, and is not obtainable without this package.** The integrated tree is
at 62/79 at the default mask, and the seventeen are identical in name and in SSIM to six decimal
places between the two trees:
```
improved-transparency-minecraft-26.3.DirectGLES 0.994435
minecraft-1.21.11-main-menu.DirectGLES 0.936674
minecraft-1.21.4-fabric-iris-bliss-in-world.DirectGLES 0.856432
minecraft-1.21.4-fabric-iris-bsl-esc-menu-854.DirectGLES 0.922890
minecraft-1.21.4-fabric-iris-bsl-in-world.DirectGLES 0.851414
minecraft-1.21.4-fabric-iris-chocapic-v6-lite-in-world 0.855946
minecraft-1.21.4-fabric-iris-complementary-reimagined 0.815194
minecraft-1.21.4-fabric-iris-complementary-unbound 0.806136
minecraft-1.21.4-fabric-iris-derivative-main-d24.4.14 0.761700
minecraft-1.21.4-fabric-iris-iterationt-in-world 0.985983
minecraft-1.21.4-fabric-iris-iterationt-nodsa-in-world 0.985049
minecraft-1.21.4-fabric-iris-makeup-ultrafast-in-world 0.981368
minecraft-1.21.4-fabric-iris-nostalgia-in-world 0.845284
minecraft-1.21.4-fabric-iris-photon-v1.1-in-world 0.824615
minecraft-1.21.4-fabric-iris-photon-v1.3b-in-world 0.970720
minecraft-1.21.4-fabric-iris-sundial-lite-in-world 0.812143
minecraft-1.21.4-fabric-iris-super-duper-vanilla-in-world 0.610444
```
**Fifteen of the seventeen are Iris shader packs**, plus `improved-transparency-26.3` and one
main menu; every DirectVulkan half passes, and every non-Iris in-world and inventory trace
passes. Nobody had run a retrace at the DEFAULT mask on an integrated P4a tree before this
round - B's 79/79 was at `0x1ff`, and D's arms were `189/6/6` on the itest lane only - so **this
is the first measurement of it, and it is an integrator-level finding independent of E**:
seventeen shader-pack traces are wrong on the DirectGLES handle arm, at SSIM 0.61 to 0.99, with
**zero named refusals and zero seam lines** anywhere in the census. That is category (c): a
silent difference in the client emission or the applier, not a declined arm. E's decline sites
cannot speak about it because none of them is declining, and the fact that the failures cluster
so exactly on shader packs (many programs, many framebuffer switches, many image and sampler
units per frame) is the strongest lead the round can hand over.
The SD-0 patch is **reverted** on the branch (`Tracker.h` is not E's file); the working tree is
clean.
---
## 8. The verification-round checklist (v2 §6), item by item
| item | result |
|---|---|
| 6.0 do not run `wsl_tree.sh`; `git lfs checkout` first | **the `git lfs checkout` instruction is WRONG on this box** - see §1. The branch was never reset; `refs/heads/p4a/esprytdraw-backup` untouched |
| 6.1 take §4's reconciliations first | done, in the order given; §3 |
| 6.2 apply the flips, assert every arm engages | done; §4, §4.1 - and one flip was corrected by the run itself (§6.1a) |
| 6.3 zero seam hits, and `Fatal{ProtocolCorruption}` on verify | **5 image-seam hits (SD-4, a finding against C, not a reason to relax the check)**, 0 framebuffer, 0 program, **0 `Fatal{ProtocolCorruption}`** |
| 6.4 A8's measurement | **answered, and it is the image half that matters**: `ImageEmit.h`'s own text says the window is the program's named units unioned with a sticky mark, not the driver's set, and SD-4 is that gap observed. MAJOR-1's union is **permanent**. The sampler half's window is `[0, GetMaxTouchedTextureUnit()]`, the same bound E walks, so MAJOR-2 is *expected* unreachable but stays load-bearing until C documents the membership in `SamplerEmit.h` (it is capped at `kMGPipeMaxTextureUnits` and gated by a suppressor) |
| 6.5 A3 / D-E3: does the read-FBO list still do work? | **yes, and settled by code rather than by a counter**: `IsDrawSyncClean` was NOT re-keyed onto the record's `ParamsSerial` - it still compares the frontend's params version twice, the content version, and the sampler object's version, and **returns false outright when the texture has no sampler object**. Nothing on the read path advances any of them. D-E3's closure stays in E |
| 6.6 unit-list equivalence between `0x1ff` and `0x1fff` | the two arms' *failing sets* differ only by the two SD-1 scenarios, and every family census row is 0 on both, so no rebuild class is missing; the per-frame rebuild COUNT is not instrumented on either arm and stays an optimisation-list item |
| 6.7 named traces | `photon-v1.3b` and `improved-transparency-26.3` both run, both fail **identically with and without E** (§7); the canary that actually fired was `create-indirect`, and it caught a real one (SD-0) |
| 6.8 the full C.4 verification | §5. `p4a_untouched_regions.sh` run from F's tree, rc 0, and the two D-N rows that live in E's file carry D's own shas. `g_rawDepthFetchSamplerState` confirmed still the only file-static `SharedPtr<SamplerObject>` in this file, pre-existing at `37da3c3a`, untouched (P3b/P4b's) |
| 6.9 carried to other packages | A9 closed by D; ID-12's DV-5 still the integrator's; G9-as-white-box landed in D |
| 6.10 Track H census | unchanged: 7 memos re-keyed, 0 retired, 1 bypassed, 1 new |
---
## 9. What the integrator must re-run, and what is owed by whom
**Before the push**
1. **SD-0 → the owner of `MG_Impl/Pipe/Tracker.h` (C / contract).** The four-line shutter patch
in §SD-0, plus the `ImageEmit.h` invariant-2 rewording. **Verified on this tree**: it turns
`create-indirect.DirectGLES` from `FAIL 0.887403` into `PASS 0.999961` and leaves both itest
lanes unchanged. Until it lands, E's tree is one retrace case behind pipe's, and **that case
is the only difference between them**.
2. **SD-1 → package C.** Two scenarios red on the gpu AND verify lanes, with a named refusal and
a demonstrable wrong picture (`0x3F800000` where an integer border colour belongs). This is
the residual ID-12's rule is about.
3. **SD-4 → package C** (possibly reaching into `MG_State`'s reflection under an integrator
grant). Five scenarios silently on the pre-handle arm.
4. **SD-3 → package D's report and package C's code.** The census is short by two shapes; the
residual check needs four grep patterns.
5. **SD-5 → package D**, when convenient. `0x7ff` is not a shipped mask.
**Re-runs the integrator owes after any of the above lands**
* the DirectGLES `-L integration-gpu` default arm and the census (the recipe is §6.0 - **the
obvious `ctest -V` census is a false zero and must not be used**);
* the **full retrace at the default mask**, which nobody had run on an integrated P4a tree
before this round and which is at **62/79 without E** (§7). Those seventeen are a
category-(c) finding with no refusal behind them and they are **not this package's**; they
need an owner before the phase closes.
**Not owed by anyone, recorded as settled**
* the DirectVulkan lane: **475/475, with and without E**, at every mask this round swept, once
`29d51ab9` landed;
* the six armless `.Handles` aborts: F's, and now positively identified by their
`Fatal{PipeLegacyMemosDisabled}` line rather than assumed;
* ID-27: `record.Target` has no reader left in this file.
---
## 10. Deviations of this round
* **DEV-19 — F3 was KEPT against the review's A1 sketch.** The A1 cell says the seam check "can
go" once the twin resolve takes the handle; §2's table says "keep verbatim; it is the wording
§8.2 greps". The table wins, and the reason is stronger than precedence: with the twin now
resolved from the record and configured **from the bound frontend object**,
`FramebufferRecordMatchesBinding` is the only thing between a mis-keyed record and one
framebuffer's attachments being written into another's twin. Removing it would delete the
check that makes A1 safe.
* **DEV-20 — F5 and F7 became assertions PLUS a kept null check**, not assertions alone and not
deletions: `MOBILEGL_ASSERT` is inert in a release build, and a dereference of a nullable
accessor is not something to leave to an ordering argument.
* **DEV-21 — I2's condition is narrower than the review's.** "When the program declares images"
is not testable at that site; "the validate-point latch is set AND this unit holds an image
texture" is, is strictly stronger, and names the unit. The latch was extended to cover the
pre-handle sweep as well, because I2 fires precisely when the record arm is NOT taken and a
latch covering only the record arm would make the flip unreachable.
* **DEV-22 — T2 and S2 are scoped to `maxTouchedUnit >= 0`**, against the review's table, on the
evidence of the first real-path run (§6.1a). 333 of 333 hits of the unnarrowed rule were draws
that touch no texture unit.
* **DEV-23 — P6 does not re-test the review's condition** because its only caller already
guarantees it; re-testing would have been a second reader of one rule.
* **DEV-18 (v2) paid for itself**: wire v3 landed the accessors as member functions returning a
nullable pointer - both halves of what v2 predicted - and the rebase was one function plus
four null checks.
---
## 11. Logs
Everything this round wrote lives in `~/w7/p4ae3/` and is **deleted** at the end of the round per
ID-5: the edit scripts, the four `build-*.log`s, the arm logs, the per-process `mglogs/`, the
census extracts, the bisect logs and the retrace logs. `~/w7/p4a-esprytdraw` keeps only
`build-linux`, `build-push` and `build-verify` (`build-nolegacy` was deleted with the logs; it
is a compile gate, rebuilt in one command). The shared scratchpad `wsl`
directory was not touched (ID-7). Nothing was pushed; `~/w7/pipe` and the other `p4a-*` trees
were read-only except for the control ctest runs inside `~/w7/pipe/build-push` and
`~/w7/pipe/build-verify`, which write no tracked file.
@@ -0,0 +1,375 @@
# P4a package D — `p4a/esprytobj` adversarial review, v1
Reviewed: `refs/heads/p4a/esprytobj` `7aa598fa..9bb95335` (six commits) against the tag `p4a/contract`
(`08192d72`). Worktree read-only; experiments in `~/w7/p4a-review-esprytobj` (detached, removed at the
end of this round). Sources read in full: the whole `git diff 08192d72 HEAD` (Managers.cpp +1208 /
Managers.h +360 / SanityTest.cpp +196) plus the surrounding bodies of every function it touches, plus
`SlotTables.h`'s handle overloads, `p4a/wire@3c07c8c3`'s `PipeApply.{h,cpp}`, `p4a/clientfb@8946061e`'s
`TextureEmit.h` / `FramebufferEmit.h` / `TextureObject.cpp` and `p4a/esprytdraw@0b00f7f0`'s
`DirectGLES.cpp` (only to refute findings, never to grade them).
## Verdict: **REWORK**
One critical, four majors, ten minors. The critical and two of the majors are behavioural and are
invisible on this tree by construction (no records exist yet), so none of them could have been caught
by the package's own verification — which is exactly why they have to be fixed before the real-path
round rather than found by it.
What the package got right is worth stating first, because it is most of it: the refusal discipline is
genuine (every handle arm declines with a named `MGLOG_E_ONCE` and returns; I could not find one
silent fall-back that would make a lane pass), the four arm resolvers and the three dependency
refusals are D-K2/D-K3 verbatim, the death-notice arm is idempotent by construction, the G5 set is
byte-identical (recomputed independently), the macro hygiene is complete, and the purity greps are
clean.
---
## 1. Critical
### C-1 — the handle arm silently stops configuring every framebuffer that is not the currently bound one, which is all five DSA / blit entry points
`MobileGL/MG_Backend/DirectGLES/Managers.cpp:8216-8228` (`FramebufferImpl::PushedFramebufferRecord`)
and `:8450-8473` (the decline inside `BackendFramebufferObject::SyncToBackend`).
`PushedFramebufferRecord(asTarget, fbo)` answers only `MGPipeApplier().DrawFramebuffer` /
`.ReadFramebuffer` — the applier's **working state for the two bound targets** — and returns null when
`record.Fbo != fbo`. `SyncToBackend` then does:
```
GLenum glFBOTarget = ...;
Bind(asTarget); // :8432 - the driver FBO is bound FIRST
...
pushedRecord = PushedFramebufferRecord(asTarget, fbo); // :8450
if (pushedRecord == nullptr) { MGLOG_E_ONCE(...); return; } // :8451-8457
```
**Failure scenario.** `glClearNamedFramebufferfv(fbo, ...)` with bit 9 set:
`ClearNamedFramebufferfv` (`DirectGLES.cpp:7960`) →
`SyncAndBindFramebufferObject(framebuffer, Draw, forceSync=true)` (`DirectGLES.cpp:3262-3294`) →
`registry.GetOrCreate(framebuffer)` mints a **fresh** twin with no attachments →
`InvalidateSyncedState()` → `SyncToBackend(framebuffer, Draw)` → `Bind(Draw)` → the record names the
*application's* bound FBO, not this one → refusal → `return` → back in the caller,
`backendObj->Bind(target)` → `glClearBufferfv` is issued against a driver framebuffer with **no
attachments at all**. Result: `GL_INVALID_FRAMEBUFFER_OPERATION` and nothing cleared. On the legacy
arm the same call configures the FBO from the frontend and clears correctly. The same holds for
`BlitNamedFramebuffer` (`DirectGLES.cpp:6474-6475`, both targets) and the other three
`ClearNamedFramebuffer*` (`:7980`, `:7997`, `:8017`).
This is not the benign case the report describes. §2-d4 says a mismatch "is answered with null rather
than with the other framebuffer's attachments" — true, and the alternative it rejects would indeed be
worse — but the caller's response to null is to do *nothing at all*, and doing nothing to a
framebuffer that is about to be cleared or blitted into is a third outcome the report does not
consider.
**Refutations attempted, all four failed.**
1. *Does package B emit a record for a DSA-named framebuffer?* No.
`p4a/clientfb:MG_Impl/Pipe/FramebufferEmit.h:219 EmitFramebufferState(GLContext& ctx)` builds only
from the two bound slots (`:237-244`, `drawFbo`/`readFbo`), which is D-C2 as written ("once per
bound target that moved"). A named-but-unbound framebuffer never gets a record, and it must not:
writing one into `DrawFramebuffer` would make the applier claim it is bound.
2. *Does package E fix the call site?* No. `p4a/esprytdraw@0b00f7f0`'s `SyncAndBindFramebufferObject`
(`DirectGLES.cpp:3982-4013`) is unchanged in this respect and still calls
`backendObj->SyncToBackend(framebuffer, target)`. E's e1 rework is confined to `SyncCurrentFBO` /
`BindCurrentFBO` / `ForceBindCurrentFBO`.
3. *Does `ForceBindCurrentFBO` repair it afterwards?* It re-syncs the **application's** framebuffer,
not the named one, and the clear/blit has already been issued by then.
4. *Is the path dead?* No — `ClearThenReadPixelsScenario`, `OrientationScenario` and
`FramebufferTest.NamedFramebufferDrawBuffersDoNotModifyDefaultFramebuffer` all drive it, and the
Minecraft/Iris traces drive it every frame.
**What the fix has to decide** (this is a contract question, not a one-line patch): either (a) the
applier grows a per-object framebuffer record beside the two working-state ones so a named FBO can be
addressed by handle — which is a real change to D-B2/D-I2 and A's file; or (b) Espryt keeps a named
arm for the not-currently-bound case and says so out loud (it is still a decline on the handle arm,
just not a silent one); or (c) B emits a third, explicitly-not-bound record kind. What is not
acceptable is the present state, where the only visible symptom is one `MGLOG_E_ONCE` line and a
framebuffer that quietly never gets attachments. **This is the finding the integrator most needs
before the real-path round**, because on the integrated tree it will present as "the 183 went to
zero, but the DSA scenarios are red" and look like a seam defect in B.
---
## 2. Major
### M-1 — the server's own re-dirty of the frontend model is invisible to the handle arm's upload loop
`Managers.cpp:6046-6049` (`MGB_LEVEL_NEEDS_UPLOAD`) **replaces** `IsStorageDirty` on the handle arm
rather than OR-ing with it:
```
(pushedStorage != nullptr
? FindPipeTextureUpload(*pushedStorage, (Uint16)tgt, (Uint16)lvl) != nullptr
: (obj)->IsStorageDirty(tgt, lvl))
```
D-D5's inversion covers the **client's** own emission-time clear. It does not cover the fact that the
**server** still writes into the frontend dirty model from three places, two of which are live:
`RequireImageBindableStorage` (`Managers.cpp:5127`,
`mipmapObject->MarkStorageDirty(uploadTarget, level, true)` — the very re-dirty this package planted
`MGPipeUnmigratedEmulation("texture-remint-pull")` next to) and
`GenerateThreeChannelFloatMipmapOnCpu` (`DirectGLES.cpp:7406`).
**Failure scenario.** First `glBindImageTexture` on a texture that was already uploaded:
`SyncTextureObjectToBackend` (`DirectGLES.cpp:1529`) → `RequireImageBindableStorage` sets
`m_imageBindableStorageRequired`, clears `m_isInitialized`, re-dirties every defined level in the
**frontend** and sets `m_forceTextureParamsResync`; execution falls straight into
`SyncMipmapsToBackend` in the same verb. On the handle arm the applier's pending set is empty (the
client cleared and emitted those levels long ago), so `levelDirty == false` for every level,
`pData == nullptr`, and the widened image-carrier storage is allocated **empty**. The dispatch/draw
that triggered the bind reads zeroes. This is precisely the bug `Managers.cpp:5091-5101`'s comment
says "survived so long", re-introduced on the new arm.
**Refutation attempted (partially successful, and it is what keeps this out of §1).**
`TextureObjectWithOneMipmap::MarkStorageDirty` in `p4a/clientfb` (`TextureState/TextureObject.cpp:493-503`)
calls `PipeNoteLevelDirty(uploadTarget, mipmapLevel, dirty)` →
`MGPipeNoteTextureLevelDirty` (`TextureEmit.h:1012-1021`) → `emitter.NoteLevelDirty(...)`, so the
server's re-dirty **does** reach the client's drain list and the levels are emitted at the **next**
validate point. So the damage is bounded to the verb that triggers it and self-heals one verb later
(the applier bumps `Serial`, the gate at `Managers.cpp:6120-6123` misses, and the levels upload). It
is still deterministic wrong content for that verb, and for a one-dispatch-then-readback scenario that
is the whole result. `GenerateThreeChannelFloatMipmapOnCpu` has the same shape with a milder outcome.
**Fix**: on the handle arm the question is "does this level owe an upload", and the honest answer is
the union of the two sources for as long as the server keeps writing the client's flag —
`pending != nullptr || (obj)->IsStorageDirty(tgt, lvl)` — with `MGB_LEVEL_UPLOAD_DONE` clearing the
frontend flag too **only** for levels it did not consume from the pending set (so the D-D5 rule "the
server never clears the client's flag" keeps holding for records the client owns). Whatever the
shape, the three server-side re-dirty sites must be enumerated in the code beside it.
### M-2 — `MGPipeResourceRecord::Desc` is never read by the texture twin: the storage is still allocated entirely from the frontend
Grep across `Managers.cpp`: `pushedStorage->Desc` has **zero** readers (`pushedStorage` is used at
`:6047`, `:6055`, `:6097-6122`, `:6140`, `:6200`, `:6702`, `:7183-7193`, and never for `Desc`). Inside
`SyncMipmapsToBackend`, `currentTextureInfo` (`Managers.cpp:6236-6244`), `needsRegeneration`
(`:6251`, and again at `:7044`), `canAppendMipmaps` (`:6266-6277`) and every `glTexImage*` argument still
come from `stateTextureObject->GetFormat()/GetBaseSize()/GetSamples()/HasFixedSampleLocations()` and
`textureMipmapObject->GetMipmapLevelCount()`.
C.3's `d2` is explicit — "`m_prevTextureInfo` probe re-keyed onto the resource record's `Serial` **and
`Desc`**" — and the commit message says "drive texture storage, parameters and uploads from the pushed
descriptors". Only the parameters and the uploads moved. The renderbuffer twin one function over does
read its `Desc` (`MGB_RBO_FORMAT/WIDTH/HEIGHT/SAMPLES`, `:11694-11701`), so the asymmetry is not a
capability gap.
**Why it matters even though no lane can see it.** `SyncTextureParamsToBackend` already answers
`MGB_TEXPARAM_FORMAT` from `Desc.InternalFormat` (`:7479-7481`) while `SyncMipmapsToBackend` allocates
from `GetFormat()`. That is two authorities for one value inside one twin — the exact coupling P4a
exists to remove — and in monolith they agree, so G4/G12 cannot expose it. It is also what
`BackendTextureFormatAddsAlpha(MGB_TEXPARAM_FORMAT, ...)` at `:7651` silently depends on.
**Refutation attempted.** Is `Serial` enough? No: `Serial` gates *whether* to run, not *what* to
allocate. Is `Desc` missing the fields? No: `MGPResourceDesc` carries InternalFormat / Width / Height
/ Depth / Levels / Samples / FixedSampleLocations / Immutable, and B fills them (`TextureEmit.h`'s
respecify path).
**Not in §5's twelve deviations**, which is the part that makes it a major rather than a scope note:
D-N/D-P force a lot of shapes on this package and every one of them is documented; this one is not.
### M-3 — `SyncAttachmentObject` is in **D's** file, so DV-7's hand-off to E is a mis-attribution, and §7-13's claim about G9 is wrong
`SyncAttachmentObject` is `Managers.cpp:7947` — `MG_Backend/DirectGLES/Managers.cpp`, which C.7 gives
to **D** exclusively. DV-7 says "resolving them from `MGPSurface::Res` instead is package E's
`SyncAttachmentObject` work", and §7 item 13 says G9's red-before case
`AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver` "is closed on the **E** side
(`SyncAttachmentObject` gains the parameter sync for READ-only attachments)". E cannot touch that
function without violating C.7, and it did not: `p4a/esprytdraw@0b00f7f0` changes `DirectGLES.cpp`
only (`git diff --stat`: 1 file, +893/-38).
**Refutation attempted, and it saves the deliverable but not the attribution.** E closed D-E3 by a
different route — a new `SyncReadFramebufferTextureAttachments` in `DirectGLES.cpp` (E's diff
`:208-282`, `:356-358`) that walks `MGPipeApplier().ReadFramebuffer` and calls
`SyncTextureParamsToBackend` / `SyncBuiltinSamplerToBackend` for the read attachments. So G9's case
does get closed. But the consequence for the rework stands: **with ID-12 minting
`MGPSurface::TextureTarget`, the attachment-walk re-key from `MGPSurface::Res` is D's work, not E's**,
and so are the four cross-object masks (below). The integrator should not schedule it on E.
### M-4 — the adoption helper d1 is named for has no call site anywhere in the phase
`AdoptTwinByHandle` (`Managers.cpp:3544-3568`), the anonymous-namespace template the report calls "the
release-build VOICE for the two silent refusals, shared by the five kinds", is never instantiated.
`StateBackendObjectRegistry::GetOrCreateByHandle` (`Managers.h:453`) and `ReleaseByHandle`
(`Managers.h:476`) likewise have no caller for any of the five re-keyed kinds. Grep over the whole
tree returns only the definitions, P3a's pre-existing buffer-family copies
(`Managers.cpp:2157`, `:2472`) and `SanityTest.cpp`. Package E adds none either: grep for
`AdoptTwinByHandle|GetOrCreateByHandle|ReleaseByHandle|LiveGenAt` over
`p4a/esprytdraw:DirectGLES.cpp` returns nothing.
So in this package the five twins are still minted through `GetOrCreate(StatePtr)` off the frontend
lifetime id, and every d2-d5 site resolves with `HandleOf(stateObject.get())` — a *lookup*, not an
adoption. DV-1 records half of this honestly (the resolution sites are E's) but not that the helper
itself is dead on arrival on both branches.
**Consequence, and it is not cosmetic**: that helper holds the only release-build diagnostic for the
two refusals `SlotTables.h` performs under a compiled-out `MOBILEGL_ASSERT`. Dead code cannot be
wrong-and-noticed; its bound (`Registry::SlotTable::kMaxHandleSlot`) and its wording will first be
exercised at P5. Either give it its first caller in D's rework (the five `HandleOf` sites are where an
adoption would go once the handle arrives in a payload) or move it, with its comment, to the package
that does — and say which in the report.
---
## 3. Minor
| # | site | what |
|---|---|---|
| m-1 | `Managers.cpp:6761-6765`, `:6724` | `MGPSubRegion::SrcOffset` and `MGPSubData::SourceIsVerbatimLevelShadow` are **never read** (zero grep hits). `regionPtr` re-derives the byte offset from `dirtyRegion.lo` and the strides, and `subRectEligible` is still the pre-P4a `uploadData == mipData` pointer comparison rather than D-D6's `SourceIsVerbatimLevelShadow` test. Correct in monolith, both are carried contract fields the server is supposed to consume, and D-D3's "carried, never inferred" applies to `SrcOffset` in the same sentence as the strides. |
| m-2 | `Managers.cpp:6742-6755` | only `Regions.front()`'s `SrcRowStride`/`SrcSliceStride` are consulted; a record whose regions disagree silently uses the first. D-D3 says the pitch is the level's, so add the assert rather than the loop. |
| m-3 | `Managers.cpp:7718` | `const auto borderColorForm = MGB_TEXPARAM_BORDER_FORM;` is evaluated unconditionally and, when `pushedBorder == nullptr`, reads `stateTextureObject->GetBorderColorForm()` **on the handle arm**. The value is unused (`borderColorReadable`, declared `:7541`, gates the block at `:7721`), so this is not a silent fall-back — but it is a live frontend read on a switched-over path and a future edit will use it. |
| m-4 | `Managers.cpp:8277-8299` | the read-buffer decode takes the FIRST `Color[i]` whose `{Res, Level, Layer}` equals `ReadSurface`. The same image legally attached to two colour points resolves to the lower index; `Kind` and `Layered` are not compared. The refusal branch says "refusing to guess", which the match itself partly does. |
| m-5 | report §5 DV-9 | the claim "the pull build's preprocessed text — and therefore its object code — is unchanged" is **false as worded**. Measured (clang++ `-E -P` with the pull `compile_commands.json` flags at both revs, diff categorised): **38 differing lines — 23 `line = N` constants** inside `ErrorLopper::Loop` lambda captures shifted by the insertions, **13 pure added-parenthesis** differences from the macro expansion, **2 whitespace re-flows** (the border-colour `if`). Zero semantic differences, and `symbol_report --fail-on-symbol-set-change --fail-on-added-bytes 0` is the real gate and passes — so the *conclusion* holds. Reword DV-9 to claim what is true. |
| m-6 | `Managers.cpp:7303`, `:7563`, `:11499`, `:11743` | the four `#if !MOBILEGL_PIPE_LEGACY_MEMOS` "unreachable but loud" bodies were compiled in **no build this round**: `build-linux` and `build-push` both pass `-DMOBILEGL_PIPE_LEGACY_MEMOS=1` (verified in both `compile_commands.json`), and `build-verify` does not exist in this tree. A syntax error in them would not have been caught. P3a's twin at `:4164` has the same property, so this is inherited — but P4a quadruples it. One `cmake -DMOBILEGL_PIPE_LEGACY_MEMOS=OFF` compile-only configure closes it. |
| m-7 | `Managers.cpp:217` / `:236` | the `#if MOBILEGL_PIPE_PUSH` around the `SamplerViewCso` case (`:218`) sits **inside** the guard at `:182` that already opens the whole dispatcher. Redundant; delete the inner pair. |
| m-8 | `SanityTest.cpp` (the `auto& stale = table.GetOrCreate(first); EXPECT_EQ(stale, nullptr)` pair) | the first assertion cannot go red for its stated reason: an **adopted** backward generation also yields a null `BackendPtr&`, because `SlotTables.h`'s `GetOrCreate(handle)` does `entry.backend.reset()` before stamping. Only the following `EXPECT_NE(table.FindByHandle(second), nullptr)` distinguishes refusal from adoption. Keep both; fix the message so a reader does not trust the wrong one. |
| m-9 | `SanityTest.cpp` `ADeathNoticeForEveryP4aKindIsIdempotent` | the successor-acquire proof (slot really came back, generation moved) exists only for `SamplerViewCso`. The five object kinds get "second and third delivery is a no-op" but no ABA leg. ID-8's third case ("notice for a slot re-minted at a new generation") is therefore covered for one of six kinds. |
| m-10 | report §6.4 | "Three refusals, one per switched-over texture path" under-quotes: re-running the same standalone scenario, the default arm emits **six** distinct named shapes (3 texture, 2 framebuffer, 1 program). The classification claim ("no case fails for any other reason") is what matters and it holds — but `grep -c 'no applier record'` counts only the texture wording, so the number 3 is an artefact of the grep, not of the run. |
---
## 4. What I verified mechanically (and it all passes)
| check | result |
|---|---|
| **G5** — the four D-N functions in this package's files | Recomputed with my own mask-first extractor (comments and string/char literals blanked, definition = the one `name (` whose closing paren is followed by `{`, brace-matched in the masked text, **hashed from the original text**, exactly one definition per name). `08192d72` and `9bb95335` give byte-identical shas and they equal §4's four values: `d75537bc…` `StageBlocksIntoUnpackRing`, `a0c9994d…` `UnpackRingAvailable`, `f56d432f…` `UnpackRingAllocate`, `39a37249…` `RecomputeBackendColorSlots`. |
| `ShouldUseCaveatTextureFormat` / `BackendTextureFormatAddsAlpha` untouched | Both are in `Utils.cpp:245` / `:270`; `git diff --stat 08192d72 HEAD` touches three files and `Utils.cpp` is not one of them. |
| **DV-9 macro hygiene** | All fourteen macros are `#undef`'d immediately after their function (`:7212-7213`, `:7776-7783`, `:11830-11833`). `grep -rn 'MGB_LEVEL_\|MGB_TEXPARAM\|MGB_RBO_' MobileGL --include=*.h` → **no hits**: nothing leaks into `Managers.h` or any other header. |
| **DV-9 pull-text identity** | See m-5: 38 differing lines, all provably non-semantic. |
| **Purity (G13)** | `grep -rc pGLContext MobileGL/MG_Backend` → only `MG_Backend/MGPipe/PipeInputs.h:1`. `awk '/struct MGPipeResourceOps \{/,/^ \};/' MG_Pipe/PipeApply.h \| grep -c MG_State` → `0`. |
| **Logging discipline** | Diff adds 22 `MGLOG_E_ONCE`, 2 `MGLOG_E` (both arm-resolver refusals, once per process by construction), 12 `MGLOG_D`, and **zero** `MGLOG_I`. No leftover debug, no `printf`, no commented-out code. |
| **Exit order (ID-8)** | The only new namespace-scope object is `SamplerViewImpl::g_backendSamplerViews`, a `BackendSlotTable` whose `Entry::stateRef` is a `weak_ptr` and is never written on the handle overload (nothing instantiates `GetOrCreate(StatePtr)` for it), so it is not a holder of frontend `SharedPtr`s. No new `std::atexit`; `EnsureProcessTeardownSentinel()` is still armed by the first insertion of a driver-id-owning table. The four arm latches are function-local `static const Bool` in `inline` functions — trivially destructible, one guard variable, no exit registration. |
| **Death-notice idempotence** | Argument checked against the mechanism, not the prose: `MGPipeSlotAllocator::Free` erases the lifetimeId→slot map, `BackendSlotTable::OnFrontendObjectDestroyed` returns false on the null handle, and `ReleaseTwinAt` refuses a `Gen` mismatch. The `SamplerViewCso` arm (`Managers.cpp:228`) is a plain `OnFrontendObjectDestroyed` and cannot free another kind's slot because the allocator resolves `(kind, lifetimeId)`. `ADeathNoticeForEveryP4aKindIsIdempotent` drives the real `GetStateObjectDeathOps()->OnDestroyed`, not a stub, which is the right call. |
| **The legacy arm is unchanged** | Ran the full `MOBILEGL_PIPE_PUSH=0 ctest -L integration-gpu -j 8 -R DirectGLES`: **99% passed, 6 failed out of 491**, and the six are exactly the `DirectGLES.HandleRecycle.Handles.*` aborts — §6.3's central safety claim reproduced independently. |
| **The default arm** | Ran the full default-arm lane: **189 failed out of 491, 62% passed** — the report's number reproduced exactly. `-R HandleRecycle` on the default arm gives exactly the same six aborts and nothing else. Standalone repro of the two shapes confirmed verbatim: at `0x1ff`+`LEGACY_MEMOS=0`, `exit=134` and `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"}`; at `0x1fff` the abort is gone and only named refusals remain. **The `~/w7/p4a-esprytobj-lanes*.log` files no longer exist** (deleted per ID-5), so §6.3/§6.4's failure *sets* could not be diffed against their logs — see §6. |
| **No silent fall-back** | Walked every `#if MOBILEGL_PIPE_PUSH` arm's decline path: `SyncMipmapsToBackend` `:6102-6108`, `ResolvePushedBuiltinSampler` `:7225`/`:7237`/`:7249`, `SyncTextureParamsToBackend` `:7439`, `SyncToBackend`(fbo) `:8452`/`:8466`, `SyncReadBufferToBackend` `:8271`/`:8290`, `SamplerObject::SyncToBackend` `:11486`, `RBO::SyncToBackend` `:11730`, program `:11237`. Every one names the handle and returns (the program one deliberately leaves its memo rather than stamping 0, which is the right direction). The only frontend read left under a handle arm that I could not justify is m-3's dead one — and M-2's, which is a design gap rather than a fall-back. |
---
## 5. The twelve deviations, judged against ID-12
| DV | verdict |
|---|---|
| **DV-1** | Accepted as the C.7 boundary note ID-12 rules, **with M-4's correction**: the note explains why the resolution sites are E's, but not that the adoption helper and the two new registry methods end up with no caller on either branch. |
| **DV-2** | As ruled. c0c mints `kMGPipeDepthStencilModeDepth/Stencil`; D's rework replaces the bare `!= 0` in `MGB_TEXPARAM_DS_MODE` (`Managers.cpp:7498-7500`) with the named constant. The chosen direction (zero decodes to `GL_DEPTH_COMPONENT`) is right for the reason given and I could not fault it. |
| **DV-3** | KNOWN rework per ID-12; not re-found. **I verified the scope**: the packed field is compared in exactly five places (listed in §7) and **nothing else in D compares `MGPSubData::Target`** (`Desc.Target` is never read anywhere in `Managers.cpp`; `MGPFramebufferState::Target` at `:8463-8473` is a different field). Wire confirms the hazard: `PipeApply.cpp:756` stores `entry.UploadTarget = record.Target` — the **whole packed field** — while D matches `static_cast<Uint16>(TextureUploadTarget)`, so today every texture upload would be dropped, silently, on the handle arm. |
| **DV-4** | As ruled and the cheapest of the four: D never reads `Kind`, and `SyncReadBufferToBackend`'s emptiness test is `MGPipeHandleIsNull(record->ReadSurface.Res)` (`:8277`), which D-C1 fixes independently of the enum. c0c's constants make the code clearer but no rework is *required* here. |
| **DV-5** | As ruled, **but the ownership in the report is wrong** (M-3). All four masks are in **D's** file — `IsSnormFallbackAttachment` `Managers.cpp:8051`, `IsUnormFallbackAttachment` `:8067`, `IsAlphaWidenedColorAttachment` `:8098`, `IsIntegerColorAttachment` `:8149` — so moving them onto `MGPSurface::TextureTarget` is D's rework, not "contract + integrator, until then D leaves them alone". The analysis behind the deviation (no `TextureUploadTarget → TextureTarget` inverse exists; inventing one would feed a D-N-pinned function a guessed input) is correct and is why the field is the right answer. |
| **DV-6** | Accepted as argued, and I confirmed both halves: `DecodePushedDrawBuffers` (`:8237-8247`) is total for `Color0..7` and `-1 → None`, and the D-O row survives — the apply is still gated on `asTarget == FramebufferTarget::Draw` (`:8499`), as is the snorm/unorm/widened/integer mask block (`:8535`), so a `Target = Both` record synced as READ still cannot land `glDrawBuffers` on the wrong framebuffer. |
| **DV-7** | Accepted as a boundary note, **with M-3's correction to who owns it**. |
| **DV-8** | Accepted; D-H3 is unambiguous and the code matches it (`:11582` stamps identity + serial only). The step message does read the other way and the deviation says so. |
| **DV-9** | Accepted as G1-forced, **with m-5's rewording** and m-6's gap. The measurement behind it (lambda `$_N` renumbering; +9 / -2 bytes) is the right kind of evidence and I did not try to re-derive it. |
| **DV-10** | Fine. |
| **DV-11** | Fine structurally — every `#if !MOBILEGL_PIPE_LEGACY_MEMOS` body is inside a push arm — with m-6 (never compiled) and one asymmetry worth a line in the rework: `SyncMipmapsToBackend` and the framebuffer pair express the arm choice as `if (pushedStorage == nullptr)` / `if (FramebufferSubsystemEnabled())` rather than `#if/#else`, so **their** pre-handle text is not removed under `LEGACY_MEMOS=0` and gets no "loud unreachable" body. Unreachability still holds (all four resolvers pass `legacyArmSurvivesLegacyMemos=false`), so this is a consistency note, not a defect. |
| **DV-12** | Fine; §4's one-off equivalent copies the parent script's shape faithfully and I reproduced its four shas with an independently written extractor. |
---
## 6. What I could not check, and why
- **§6.3/§6.4's failure *sets*.** `~/w7/p4a-esprytobj-lanes*.log` are gone (ID-5 says the owner deletes
them at the end of the round, so this is compliant, not a lapse). I reproduced the default arm's
**count** (189/491) and the six aborts exactly, and I confirmed on a representative scenario that
the only `[ERROR]: MGPipe` lines are named refusals — but the per-case classification of all 183
rests on the report's own log, which no longer exists. **Keep the logs until the review closes** in
future rounds; §6.4's whole argument is a log-line attribution.
- **The `0x1ff` lane.** Only the `0` lane was re-run in full (6/491, the six aborts and nothing else).
§6.3 says both outer lanes see the identical set *because* the ctest `ENVIRONMENT` property replaces
the job env, which the `0` run confirms as far as it goes; the `0x1ff` run would prove the same
property from the other side and costs four minutes.
- **`build-verify`** does not exist in this tree, so G4's retain-mode comparison — the *only* gate that
can check a consume-and-clear set (D-D5) — has not been run anywhere in the phase yet.
---
## 7. Rework list for D's verification round
**Blocking (must be done before the real-path round):**
1. **C-1** — decide and implement the not-currently-bound framebuffer case. Sites:
`Managers.cpp:8213-8225` and `:8459-8479`; the five callers are `DirectGLES.cpp:6474`, `:6475`,
`:7960`, `:7980`, `:7997`, `:8017` via `SyncAndBindFramebufferObject`. Coordinate with A/B if the
answer is a new record; raise it as a contract deviation if it is not.
2. **M-1** — make the handle arm's per-level dirty question cover the server's own re-dirty
(`Managers.cpp:6046-6049` and `:6053-6060`), and enumerate the three server-side `MarkStorageDirty`
sites in the comment beside it (`Managers.cpp:5127`, `DirectGLES.cpp:7406`, `DirectGLES.cpp:6735`).
3. **ID-12 DV-3** — decode the HIGH BYTE. The cheapest correct patch is **two lines**, in the two
helpers rather than at the three call sites, so the `static_cast<Uint16>(TextureUploadTarget)`
spelling stays where it reads naturally:
- `Managers.cpp:3752` (in `FindPipeTextureUpload`, `:3745`): `pending.UploadTarget == uploadTarget`
→ `MGPipeSubDataUploadTargetOf(pending.UploadTarget) == uploadTarget`;
- `Managers.cpp:3768` (in `ConsumePipeTextureUpload`, `:3757`): `pending.UploadTarget !=
uploadTarget` → the same decode.
The three call sites that pass the bare enumerator are `Managers.cpp:6047-6048`
(`MGB_LEVEL_NEEDS_UPLOAD`), `:6056` (`MGB_LEVEL_UPLOAD_DONE`) and `:6702-6705` (the staging block's
`pendingUpload`) and need no edit under that patch — but they must be re-read against c0c's final
helper signature (`Uint32` arguments). **Nothing else in D compares `MGPSubData::Target`** —
verified by grep; `Desc.Target` is never read and `MGPFramebufferState::Target` is a different
field.
4. **ID-12 DV-5** — move the four cross-object masks onto `MGPSurface::TextureTarget`:
`Managers.cpp:8051` `IsSnormFallbackAttachment`, `:8067` `IsUnormFallbackAttachment`, `:8098`
`IsAlphaWidenedColorAttachment`, `:8149` `IsIntegerColorAttachment`. All four are D's file (M-3);
`ShouldUseCaveatTextureFormat` / `BackendTextureFormatAddsAlpha` stay byte-identical and only their
*inputs* change. Consult `TextureTarget` only when `Kind == Texture`, treat `0xFFFF` as "unknown"
and decline rather than guess.
5. **ID-12 DV-2/DV-4** — swap `MGB_TEXPARAM_DS_MODE`'s `!= 0` (`:7498-7500`) for
`kMGPipeDepthStencilModeStencil`; optionally tighten `SyncReadBufferToBackend`'s emptiness test with
`kMGPipeSurfaceKindNone`.
6. **M-2** — either drive `SyncMipmapsToBackend`'s shape from `pushedStorage->Desc` (the brief's d2),
or record it as an explicit, argued deviation with an owner. Silence is the one option that is not
available, because no monolith lane can expose it.
**Non-blocking but owed in the same round:**
7. **M-3** — correct DV-7 and §7-13 in `esprytobj-v1.md`; tell the integrator that the attachment-walk
re-key is D's, not E's, and that E closed D-E3 through `SyncReadFramebufferTextureAttachments`.
8. **M-4** — give `AdoptTwinByHandle` / `GetOrCreateByHandle` / `ReleaseByHandle` a first caller, or
move them to the package that will have one, and say which in the report.
9. m-1, m-2 — consume `SrcOffset`; assert the per-region stride invariant.
10. m-3 — hoist `MGB_TEXPARAM_BORDER_FORM` inside the `borderColorReadable` guard.
11. m-5 — reword DV-9 to the measured truth (23 `__LINE__` constants + 13 parenthesis-only + 2
re-flows; symbol-set and byte-size unchanged).
12. m-6 — add one `cmake -DMOBILEGL_PIPE_LEGACY_MEMOS=OFF -DMOBILEGL_PIPE_PUSH=...` **compile-only**
configure to the package's verification block so the four "loud unreachable" bodies are at least
compiled once.
13. m-7 — drop the redundant nested `#if`.
14. m-8, m-9 — fix the over-claiming assertion message; add the successor-acquire leg to the five
object kinds in `ADeathNoticeForEveryP4aKindIsIdempotent`.
15. m-10 — restate §6.4's refusal census with all six shapes.
16. Keep `~/w7/p4a-esprytobj-lanes*.log` until the review of the round closes.
---
## 8. What the integrator must re-run on the integrated tree
Beyond §7 of `esprytobj-v1.md`, which is otherwise sound:
1. **The DSA / named-framebuffer set, explicitly**, because C-1 is the one failure that will look like a
B-side seam defect:
`ctest --test-dir build-push -L integration-gpu -R 'ClearThenReadPixels|Orientation|FramebufferChurn|DepthStencilReadback'`
plus `ctest --test-dir build-push -R 'FramebufferTest.NamedFramebuffer'`. If C-1 is fixed, these go
green with the rest; if the fix is a decline-with-a-name, they will still be red and the integrator
needs to know that *before* reading the number.
2. **The image-bindable remint set**, for M-1, one dispatch and one readback apiece:
`ctest --test-dir build-push -L integration-gpu -R 'ImageLoadStoreSso|FormatlessImageBake|ImageSizeAfterRespec|ImageTargetKind|SampledSetStaleness'`,
and confirm `TextureParamsWithoutASamplerViewScenario.AnImageUnitOnlyTexturesSwizzleSurvivesARequireImageBindableStorageRemint`
is green **and** that a content assertion exists beside the swizzle one — today's case checks the
swizzle, which M-1 does not break.
3. **G4's retain-mode comparison** (`build-verify`, `-L integration-verify`) — it has not run anywhere
in this phase and it is the only mechanism that can check a consume-and-clear set. D-D5's whole
safety argument is unverified until it does.
4. **The residual-refusal check, per shape, not per count.** With `MOBILEGL_LOG_FILE_PATH` set, the
integrated tree must show **zero** of all six shapes, not three:
`no applier record on the handle arm, so its {parameters,built-in sampler,storage and uploads}`,
`has no {draw,read}-target applier record`, and `has no shader-CSO applier record`. A residual of
any one of them is a seam defect (P3a's lesson), and the framebuffer two are the ones C-1 will
masquerade as.
5. `MOBILEGL_PIPE_PUSH=0x9ff` once F's `ObjectSubsystemControlScenario` exists — D's half (the
bit-11-requires-bit-10 `MGLOG_E` and the legacy fall-back, `ResolveSamplerSubsystemArm`,
`Managers.cpp:3647-3665`) is in and correct.
6. The six itest phase pins `0x1ff → 0x1fff` (`MG_IntegrationTest/CMakeLists.txt:949, 1065, 1075, 1149,
1183, 1188, 1219`) and `0x80000000000001ff → 0x8000000000001fff` (`:1070, 1080`) — F's, and until
they move the six `.Handles` aborts are red on the integrated tree. I reproduced them and their
`Fatal` verbatim; the attribution in §6.3 is correct and needs no re-argument.
7. `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` on the unit and integration runs (ID-18/21), and the
ID-8 leak/idempotence half on the **DirectVulkan** lane — which lives in F's `HandleRecycleScenario`
`…ReturnTheirSlots` cases (G8b), not in D's `SanityTest.cpp`. Confirm F wrote one for
`SamplerViewCso`, the kind with no frontend object: nothing in D or E can test it there.
@@ -0,0 +1,483 @@
# P4a package D — `p4a/esprytobj` rework v2, focused re-review
Reviewed: `refs/heads/p4a/esprytobj` `cce81d19..ef6beb28` (the seven rework commits) against
`esprytobj-review-v1.md`, `INTEGRATOR-DECISIONS.md` ID-12 / ID-15 / ID-18 / ID-19 / ID-23 / ID-27 /
ID-28, `wire-v3.md` + `wire-review-v2.md`, `contract-v3/v5.md`, `gates-review-v1.md` R1,
`gates-review-v2.md`, `esprytdraw-v2.md`. Read in full: the whole `git diff cce81d19 HEAD`
(Managers.cpp +892 / Managers.h +98 / SanityTest.cpp +218) plus the surrounding bodies of every
function it touches, `PipeApply.{h,cpp}`'s `FramebufferRecordFor` / `AccumulatePendingUpload` /
`SubDataTextureFault`, `SlotTables.h`'s handle overloads, and — only to refute findings —
`p4a/clientfb`'s `TextureEmit.h` and E's `DirectGLES.cpp` call sites.
Experiments in a private worktree `~/w7/p4a-rereview-esprytobj` (**removed at the end of this
round**). Every number in §4 was measured **on the rebased tree** — D's thirteen commits replayed
onto the real pipe head `712c9467` — not on the temporary merged base.
## Verdict: **ACCEPT WITH MINORS**
The critical and all four majors are closed, and closed the right way rather than papered over.
ID-12, ID-15's fourth row, ID-18's M4, ID-19(d), E's item (4) and the R1/G9 probe are all in and I
could break none of them. Nine minors below; **two of them are owed before the verification round**
(N-1's log wording, N-2's census under-count, because the integrator's residual-refusal check is
written from that census and would miss two of the eight shapes). Nothing blocks the merge.
**The one thing the integrator must not do is run ID-32's rebase command as written** — it fails,
and §5 gives the recipe that works and builds.
---
## 1. Per-item closure table
| v1 item / ruling | verdict | where |
|---|---|---|
| **CRITICAL** (C-1) framebuffer record keyed by the bound target | **CLOSED** | `PushedFramebufferRecord(fbo)` = `MGPipeApplier().FramebufferRecordFor(fbo)` (`Managers.cpp:8803`, decl `Managers.h:1879`). The `asTarget` parameter and the `record.Fbo == fbo` test are gone; both DSA entry families reach it through `SyncToBackend` unchanged. `FramebufferRecordFor` (`PipeApply.cpp:2235`) is silent for the null handle and for an undescribed slot and **loud + counted** (`StaleFramebufferRecordLookups`, `MGLOG_E_ONCE`) on a stale generation — exactly what `Managers.h:1888-1898` claims |
| … refusal BEFORE the bind | **CLOSED in the twin**, but see **N-1** | the record block is `:9054-9091`, `Bind(asTarget)` is `:9092`. The claim the refusal line makes about the *resulting driver state* is false at every call site |
| … the record's `Target` no longer compared to `asTarget` | **CLOSED** | the old `expected`/`Both` block is deleted. What stays gated on `asTarget` is what reaches the driver's bound target: `glDrawBuffers` (`:9151`), the four masks (`:9159-9192`), `glReadBuffer` (`:9220`) |
| **ID-27** — any remaining `record.Target == Both`-style test in D | **NONE** | `grep -n 'Target *[=!]=' Managers.cpp` at HEAD: 20 hits, every one of them `glTarget`/`fbTarget`/`uploadTarget`/`glTextureTarget`/`asTarget`/`surface.TextureTarget`/`color.UploadTarget`. `MGPipeFramebufferTarget` appears **only** at `:8814-8815`, as the `BoundFramebuffer` index. D has nothing of E's MAJOR-1 shape |
| **M-1** server re-dirty arms the applier's `PendingUploads` | **CLOSED** | `RearmPipeTextureLevelUpload` (`:3834`, decl `Managers.h:717`), called from `RequireImageBindableStorage` (`:5277`). Entry is whole-level, `RegionCount 0`, **merged** with an existing entry, loud refusal at `kMGPipeMaxPendingUploads` (256). The three server-side `MarkStorageDirty` sites are enumerated at `:3836-3856` and the third is correctly identified as the *clear* half |
| … keyed with the PACKED target so the consume site finds it | **YES, verified end to end** | the write is `entry.UploadTarget = packedTarget` (`:3888`) built with `MGPipePackSubDataTarget(MGPipeResourceTargetForTextureTarget(GetTarget()), uploadTarget)` (`:5279`); `FindPipeTextureUpload` (`:3799`), `ConsumePipeTextureUpload` (`:3821`) and the re-arm's own scan (`:3872`) all decode with `MGPipeSubDataUploadTargetOf`. Same key, both directions. See **N-7** for the one asymmetry against wire |
| … consumed exactly once | **YES** | `ConsumePipeTextureUpload` swap-and-pops the first match and returns; at most one entry can exist per `(uploadHalf, level)` because `RearmPipeTextureLevelUpload` and wire's `AccumulatePendingUpload` both merge before inserting |
| … does the re-arm actually re-open the gate? | **YES** | the serial gate is `m_isInitialized && m_syncedResourceSerial == Serial && PendingUploads.empty()` (`:6353-6357`). `RequireImageBindableStorage` clears `m_isInitialized` **and** fills the set, so the gate misses on both counts. No recursion: the function early-returns on `m_imageBindableStorageRequired` |
| **M-2** storage from `Desc` | **CLOSED** | seven `MGB_STORAGE_*` macros (`:6244-6270`), applied at `currentTextureInfo`/the storage-kind switch, `mipmapCount`, `IsImmutable` at both allocator branches, the two multisample allocations, and all sixteen `GetFormat()` reads |
| … every `StorageKind` incl. buffer textures / multisample / cube / array | **YES** | buffer texture: `Desc.BufferForTexBuffer` + `EnsureBufferResourceForHandle` + the `BufOffset`/`BufSize` window with `kMGPipeWholeBuffer` resolved live (`:7324-7360`, `:7421-7443`); multisample: `MGB_STORAGE_SAMPLES` / `MGB_STORAGE_FIXED_SAMPLE_LOCATIONS` at `glTexStorage2D/3DMultisample`; cube/array: the base extent is `Desc.{Width,Height,Depth}` and **B fills those three from `GetBaseSize()` verbatim** (`p4a/clientfb:TextureEmit.h:185-188`), deriving `ArrayLayers` *in addition* rather than instead — so §5-item-7's feared seam does not exist. I checked it so the integrator need not |
| … metadata respecify re-derives flags without reallocation | **CLOSED, with N-4** | `:6335-6339`: `ImageBindableHint != 0 \|\| (BindMask & kMGPipeBindShaderImage)` and `!m_imageBindableStorageRequired` → `RequireImageBindableStorage`. Idempotent, no reallocation from the mask alone (the reallocation is the *widening*, which is what the flag means on this backend) |
| … `HasDefinedContent` honoured | **NOT READ, and not declared** — see **N-8** | it is storage-defining per c0e; the buffer family reads it (`:1911`, `:1956`, `:2846`), the texture arm never does and `:6230-6237`'s "what the descriptor does NOT answer" does not list it |
| **M-3** `SyncAttachmentObject` from `MGPSurface` | **CLOSED** | `PushedSurfaceForAttachment` (`:8605`) + `SyncAttachmentSurface` (`:8631`); call site `:9299-9322`. Res → twin by **adoption**, and `Layered`/`Level`/`Layer`/`UploadTarget`/`TextureTarget` off the surface |
| … `TextureTarget` for the four masks, D-N functions byte-identical | **CLOSED, shas recomputed** | `PushedSurfaceTextureTarget` (`:8539`) gates on `Kind == kMGPipeSurfaceKindTexture` and refuses `kMGPipeSurfaceNoTextureTarget` loudly. `ShouldUseCaveatTextureFormat` / `BackendTextureFormatAddsAlpha` and the two renderbuffer siblings are untouched — `p4a_untouched_regions.sh 37da3c3a HEAD` rc 0 on the rebased tree, and all six printed shas equal `esprytobj-v2.md` §4 **exactly** (`791b54a3… 1d6f15c9… 19e614af… 3ae7e347… 822ca3b0… 266710e0…`) |
| … `kMGPipeSurfaceNoTextureTarget` never fed to the masks on a renderbuffer point | **YES** | the renderbuffer arms of all four take the `Kind == Renderbuffer` branch and call the renderbuffer siblings, which take no target; `IsIntegerColorSurface` reads the format alone. `PushedSurfaceTextureTarget` is only reachable under `Kind == Texture` |
| … E's READ-only attachment parameter sync still reachable | **YES** | E's `SyncReadFramebufferTextureAttachments` lives in `DirectGLES.cpp` and calls `SyncTextureParamsToBackend` / `SyncBuiltinSamplerToBackend`; neither those two entry points nor their signatures changed, and nothing in this round touches E's file (`git diff --stat`: three files, `DirectGLES.cpp` not among them) |
| **M-4** `AdoptTwinByHandle` wired; `ReleaseByHandle` gone | **CLOSED in letter** — see **N-3** | two callers, `:8657` (texture) and `:8723` (renderbuffer). `StateBackendObjectRegistry::ReleaseByHandle` removed, the decision written where the method was (`Managers.h:470-481`); `SlotTable::ReleaseByHandle` untouched and still driven by `SanityTest.cpp` |
| **ID-12** `MGPipeSubDataUploadTargetOf` at find + consume, no bare comparison | **CLOSED** | see M-1's row. `MGPResourceDesc::Target` still has zero readers; `MGPFramebufferState::Target` is no longer compared anywhere |
| **ID-12** DV-2 / DV-4 | **CLOSED** | `MGB_TEXPARAM_DS_MODE` reads `kMGPipeDepthStencilModeStencil` (`:7835-7839`); the read-surface emptiness test keeps `MGPipeHandleIsNull(Res)` as the authority and **cross-checks** `Kind` against it, refusing when they disagree (`:8877-8886`) |
| **ID-15** bit 10 requires bit 11, in the precedent's voice | **CLOSED** | `ResolveTextureResourceSubsystemArm` `:3651-3664`, through the shared `PipeSubsystemDependencyMissing` (`:3521`), guarded `if (!refused)` so the bit-7 row cannot pre-empt it. `ResolveSamplerSubsystemArm`'s "the mirror pair … is FINE" sentence is corrected in place (`:3692-3699`); the mirror-pair table in `esprytobj-v2.md` §2(7) matches the source |
| … the exact `MGLOG_E` sentence F's matcher expects | **MATCHES** | one `MGLOG_E` line, `"MGPipe: %s - REFUSING the dependent bit and running the legacy arm. Set both bits, or clear both"` with `what` naming both bits in set-then-needed order. `gates-review-v2.md` §2.6 fed D's four real `what` strings through F's matcher: the two dependency rows match in both the 0x9ff and 0x5ff columns and all four near-misses are rejected. Nothing changed in that sentence after `b6169dba`, so F's measurement still applies at `ef6beb28` |
| **E's item (4)** `InvalidateFramebufferHandleArmMemos` inside `InvalidateFramebufferBindingCache` | **CLOSED as a declared two-line handshake (DV-13)** | the call is `Managers.cpp:8270-8278`, inside the function, beside the pre-handle trio it clears; the declaration and the whole argument are at `Managers.h:1996-2015`, gated by `#define MOBILEGL_ESPRYT_FBO_HANDLE_ARM_MEMOS_LINKED 0` (`:2011`). Can E's memo miss an invalidation once it is on? **No** — the three `SanityTest.cpp` callers (`:2530`, `:2778`, `:2799`) all go through `FramebufferImpl::InvalidateFramebufferBindingCache`, as do the six in `DirectGLES.cpp`, so being inside it is exactly the "forgetting is impossible" property E asked for. Half-done handshake does not link: the constant has no other reader and the declaration no other definition |
| **G9 white-box probe (R1)** | **CLOSED**, green on four arms, red under mutation — see **N-9** for the residual | `SanityTest.cpp:3184`. Covers deferred-to-first-view as R1 demanded: the reading is taken while the texture is attachment-only, and the probe asserts *before* the sync that no sampler-view twin exists — the assertion the public scenario cannot make |
| ten minors m-1..m-10 | **all closed or declared**, individually re-checked (§3 of `esprytobj-v2.md` matches the source at every line I spot-checked) | m-1 fixed + DV-14 declared (`PendingUpload` really is `{UploadTarget, Level, UnionBox, Regions}` — `PipeApply.h`; `SourceIsVerbatimLevelShadow` is genuinely unreachable); m-2 `:6975-7001`; m-3 `:8063`; m-4 `:8888-8912`; m-5 reworded; m-6 run (I re-ran it, §4); m-7 the nested `#if` is gone and the dispatcher's own guard at `:182` really does open the whole function; m-8 `:4194-4208`; m-9 `:4337-4352`; m-10 restated — **but the restatement is still short by two, N-2** |
| DV-9 wording | **CORRECTED** | the false sentence is withdrawn and the claim is narrowed to the property D-P actually requires. I verified that property directly and independently (§4): pull build at `712c9467` vs pull build at D's rebased head, `+0` bytes of `.text`, `0 added / 0 removed / 0 resized / 0 renamed`, identical file size |
| G1 0/0/0/0 mechanism (macros, not locals/lambdas) intact | **YES** | 20 push-arm `#define MGB_*` and 20 matching `#undef`s; every one takes the receiver it would have been spelled on, so the pull expansion is the pre-P4a expression in one pair of parentheses. `MGB_RECT_SRC_PTR` is a macro for the stated `$_N`-renumbering reason and the pull arm is literally `(rectShadowPtr(rect))` |
| macro leak into headers | **NONE** | `grep -rn 'MGB_LEVEL_\|MGB_TEXPARAM\|MGB_RBO_\|MGB_STORAGE_\|MGB_RECT_' MobileGL --include=*.h` → no hits |
| purity greps (G13) | **CLEAN** | `pGLContext` → `MG_Backend/MGPipe/PipeInputs.h:1` only; `MGPipeResourceOps` ∌ `MG_State` (0) |
| exit-order rule (ID-8) | **HELD** | the diff adds **no** namespace-scope object in `Managers.cpp` — the seven new file-scope symbols are all `static` *functions*. `SanityTest.cpp` adds `g_texParamCalls` (a raw pointer) and `g_texParamBoundTexture` (a `GLuint`): trivially destructible, no guard variable, no `std::atexit`, and neither holds a frontend `SharedPtr` |
| logging discipline | **CLEAN** | the diff adds **17** `MGLOG_E_ONCE`, **0** bare `MGLOG_E`, **0** `MGLOG_I`. No `printf`, no commented-out code |
| DirectVulkan lane 475/475 — what runs there | **REPRODUCED**, and the attribution is right | 475 `DirectVulkan.*` integration-gpu cases, run under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`. D changes only `MG_Backend/DirectGLES`, so what this lane actually exercises of D's work is the **shared** half: `MGPipeSlotAllocator`, the death-notice dispatcher (`Managers.cpp:182-250`, which the SamplerViewCso arm's `#if` removal touched) and process-teardown ordering, on the backend that installs **no** death ops. That is precisely ID-8's leak/idempotence half, and 0 failures is the right reading |
| the default arm 189 = 183 + 6 | **REPRODUCED EXACTLY**, classification confirmed by mechanism | §4 |
---
## 2. Findings
Nine, none blocking. Each has a file:line, a failure scenario and the refutation I tried.
### N-1 (minor, but it ships in a log line) — "left unbound rather than bound-and-unconfigured" is false at every caller
`Managers.cpp:9083-9087` (the refusal text), and `esprytobj-v2.md` §2(1)'s claim that on a missing
record "the driver's binding is where the caller left it rather than pointing at a freshly minted,
attachment-less driver FBO".
`SyncToBackend` returning without binding does not decide the driver's binding, because **every**
caller binds immediately afterwards:
* `DirectGLES.cpp:3292-3293` — `SyncAndBindFramebufferObject` is `backendObj->SyncToBackend(...)`
then `backendObj->Bind(target)`, unconditional, `void` return. That is the path all five DSA entry
points take (`:6474`, `:6475`, `:7960`, `:7980`, `:7997`, `:8017`).
* `DirectGLES.cpp:3206-3256` — `BindCurrentFBO` binds the current FBO's twin independently of
whether `SyncCurrentFBO` (`:2310`) synced it.
**Failure scenario.** On the integrated tree B fails to emit a `Named` record for one DSA-cleared
framebuffer. The twin refuses and returns; `SyncAndBindFramebufferObject` then calls `Bind(Draw)`,
which mints and binds the driver FBO exactly as before, and `glClearBufferfv` lands on a framebuffer
with no attachments — the identical outcome to v1. The integrator reads the log line, believes
nothing was bound, and looks for the wrong symptom.
**Refutation attempted, and it fails three ways.** (a) Does `Bind` early-out when nothing was
synced? No — it binds `m_backendFBOId`, minting it if needed. (b) Does any caller check a return
value? `SyncToBackend` returns `void`. (c) Does the reorder buy anything at the *bound*-FBO path?
No: `SyncCurrentFBO` never binds, and `BindCurrentFBO` binds regardless.
**What the reorder does buy** is real but smaller and worth saying instead: the twin no longer
*mints and binds* a driver FBO as a side effect of a refusal, so the refusal itself has no driver
effect. **Fix**: reword the message to "…so it is not configured; the caller's own bind still
targets it" (or similar), and correct §2(1). One string, and it is the string F's residual grep and
the integrator's eye will both land on.
### N-2 (minor, owed before the verification round) — the refusal census names six of **eight** shapes, and I observed seven in a single run
`esprytobj-v2.md` §4 ("six distinct shapes and no seventh") and §5 item 2 ("the integrated tree must
show **zero** of all six shapes").
`grep -n 'applier record' Managers.cpp` at HEAD gives **eight** distinct `MGLOG_E_ONCE` refusals:
```
:6310 texture %u ... its storage and uploads cannot be driven from the pushed descriptor
:7564 texture %u ... its built-in sampler cannot be pushed
:7778 texture %u ... its parameters cannot be pushed
:8866 framebuffer %u ... its read buffer cannot be pushed
:9083 framebuffer %u ... it cannot be synced from the pushed record and is left unbound ...
:11925 program %u has no shader-CSO applier record ... its synced serial cannot be stamped
:12174 sampler %u ... its parameters cannot be pushed <- NOT IN THE CENSUS
:12418 renderbuffer %u ... its storage cannot be allocated from the pushed descriptor <- NOT IN THE CENSUS
```
**Demonstrated, not argued.** One standalone run of `*IntegerBorderColor*` on the default arm with
`MOBILEGL_LOG_FILE_PATH` set produced exactly **seven** `ERROR]: MGPipe` lines — the six the report
names **plus** `MGPipe: sampler N has no applier record on the handle arm, so its parameters cannot
be pushed`. (The renderbuffer one needs a scenario with a renderbuffer attachment; it is the eighth
by inspection.) v1's m-10 corrected "three" to "six"; six is still short.
**Failure scenario.** ID-12's rule is that a residual of *any* named refusal on the integrated tree
is a seam defect. The verification round greps the six, the sampler-CSO and renderbuffer families
still refuse because C's or B's records never arrive for them, and the round reports "zero
residuals" over a tree where two families are running the legacy arm.
**Refutation attempted.** Could the sampler line be another package's? No — `Managers.cpp:12174` is
in `BackendSamplerObject::SyncToBackend`, D's file, added by D's v1 commit `107658f7` ("take the
sampler parameters … from the applier"). Could it be unreachable on an integrated tree? No: it is
the sampler family's only decline, and it fires the moment a sampler object is synced with no
`create_sampler_state` applied — which is exactly what a C-side seam looks like.
**Fix**: list all eight in §4 and §5-item-2. The common stem `no applier record on the handle arm`
matches seven of the eight; only `:11925` ("no shader-CSO applier record") needs its own pattern.
### N-3 (minor) — `AdoptTwinByHandle` now has callers, but neither can reach either of its refusals
`Managers.cpp:8657` and `:8723`, against the helper at `:3550-3574`.
Both call sites are preceded by a cross-check that the record's `Res` equals
`registry.HandleOf(frontendObject)` (`:8642-8655`, `:8709-8722`) and return `false` when it does
not. `HandleOf` (`Managers.h:420`) resolves through `MGPipeSlots().FindByLifetimeId`, i.e. the
**live** handle. So by the time `AdoptTwinByHandle` runs, `handle.Slot` is a slot the registry itself
minted (below `kMaxHandleSlot`) and `handle.Gen` equals `LiveGenAt(handle.Slot)` — neither the
slot-bound refusal nor the backward-generation refusal can fire, and `GetOrCreateByHandle` can never
take its `entry.backend.reset()` path either.
**Failure scenario.** M-4's actual argument was "dead code cannot be wrong-and-noticed; its bound and
its wording will first be exercised at P5". That argument is unchanged: the helper is now *called*
but its distinguishing behaviour is still never *exercised* outside `SanityTest.cpp`. A typo in
either bound would still ship.
**Refutation attempted, and it half succeeds.** `HandleOf` memoises (`SlotTables.h`,
`m_memoLifetimeId`/`m_memoHandle`), so a stale memo could in principle return a generation behind the
live entry and make the refusal reachable. I could not construct a sequence that does it — a live
object's handle does not change generation — so I record this as "essentially unreachable" rather
than "provably unreachable". Either way the letter of M-4 is closed and its substance is not; say so
in the report rather than leaving the integrator to infer it.
### N-4 (minor) — the metadata respecify routes the *prevention* case through the remint-pull emulation marker
`Managers.cpp:6335-6339` calling `RequireImageBindableStorage` (`:5203`), whose first statement is
`MG_Pipe::MGPipeUnmigratedEmulation("texture-remint-pull")` (`:5235`).
`MGPResourceDesc::ImageBindableHint` exists as *mitigation 1, the prevention half* — the comment at
`:5223-5231` says so in as many words: a texture that has ever been image-bound "is allocated in the
carrier from the start and never reaches this path". D's rework makes the hint's arrival the trigger
for entering that path.
**Failure scenario.** `glBindImageTexture` on a texture whose storage is not yet defined: B's sticky
mask gains `kMGPipeBindShaderImage`, emits the mask-only respecify (ID-18 M4), D calls
`RequireImageBindableStorage`, the marker fires, and the level loop then finds nothing to re-arm.
Under split (P9) that marker is the arm that aborts/counts, so the case the hint was invented to
prevent is counted as an unmigrated emulation. In monolith `MGPipeUnmigratedEmulation` is
`{ (void)name; }` (`PipeApply.cpp:2717`), so nothing is observable today — this is a P9-facing
accuracy defect, which is why it is a minor and not a major.
**Refutation attempted.** (a) Is the marker about something wider than the replay? No — its own
comment scopes it to "the server is reaching BACK into the client's own dirty model to ask for texels
it does not hold". (b) Is the no-levels case unreachable? No: B fills
`desc.ImageBindableHint = (bindMask & kMGPipeBindShaderImage) != 0`
(`p4a/clientfb:TextureEmit.h:230`, `:520`, `:982`) from the sticky mask on every respecify, including
one that precedes any level definition.
**Fix**: move the marker to where a level is actually re-armed (inside the loop, or behind a
"replayed at least one level" flag). Two lines, and it keeps the marker honest for P9.
### N-5 (minor, consistency) — `SrcOffset` is consumed raw while its sibling stride got a loud refusal in the same commit
`Managers.cpp:7091-7096` (`MGB_RECT_SRC_PTR`), used at `:7123`, `:7218`, `:7262`.
The macro adds `Regions[idx].SrcOffset` to `uploadData` and hands the result to `glTexSubImage*` as
the client pointer for `(w·bpp × h × d)` bytes. The same commit added a loud refusal when the
regions' *strides* disagree (`:6975-7001`), on the argument that "a record whose regions disagree is
corrupt". `SrcOffset` gets no equivalent — and the block two lines above computes the same number
independently (`rectShadowPtr`, `:7074-7079`), so the cross-check is free.
**Refutation attempted, and it is strong enough to keep this a minor.** (a) Wire validates
region-inside-box and box-encodability (`PipeApply.cpp:743-770`) but explicitly does *not* validate
the box against the level extent, and says so. (b) B derives `SrcOffset` from the same box origin and
level pitch the shadow path uses (`clientfb:TextureEmit.h:394-396`), so in monolith the two agree by
construction. (c) The pre-existing `rectShadowPtr` derivation is exactly as untrusted, so this is not
a new exposure. It is an asymmetry in the package's own discipline, not a live defect.
**Also**: the first of the three use sites is unreachable. `dirtyRectCount` is forced to `0` whenever
`UnpackRingAvailable()` (`:7069-7071`), and the staging-block loop at `:7119` requires
`ringUsable && dirtyRectCount >= 2`. Pre-existing shape, not D's — but `esprytobj-v2.md` §3-m-1 cites
three live sites where there are two.
### N-6 (minor) — an empty surface is accepted silently while every other record-vs-frontend disagreement is loud
`Managers.cpp:8634-8640` (the `Kind == kMGPipeSurfaceKindNone || MGPipeHandleIsNull(Res)` arm of
`SyncAttachmentSurface`), against the detach at `:9289-9291`.
The detach is decided by the **frontend** (`attachmentObject.IsEmpty()`); the attach is decided by
the **record**. When the record says a point is empty and the frontend still holds an attachment,
neither fires: no detach (frontend not empty), no attach (surface empty), `return true` — and the
caller then stamps `m_syncedFrontendAttachmentVersions[i]`, so the point is marked synced with the
*previous* owner's image still attached. The comment claims "the caller has already detached it where
that is what an empty point means", which is only true when the two sides agree.
**Refutation attempted, and it explains why this is a minor.** (a) Would the point even be visited?
Yes — a moved `ContentHash` re-arms every version to `~0` (`:9256-9260`), so a record-only change
forces the whole walk. (b) Can the two disagree in monolith? Only through a frontend that keeps a
detached attachment object non-empty, which I could not find. (c) Is the *converse* loud? Yes:
`Kind == Texture` with a null frontend texture, and a `Res`/`HandleOf` mismatch, are both
`MGLOG_E_ONCE`. So the hole is exactly one direction wide. One `else if (!attachmentObject.IsEmpty())`
with the same voice closes it.
### N-7 (minor) — D keys on the high byte, wire keys on the whole packed field
`Managers.cpp:3799` / `:3821` / `:3872` versus `PipeApply.cpp:814` (`AccumulatePendingUpload`:
`if (entry.UploadTarget != record.Target || entry.Level != record.Level) continue;`).
Wire treats two entries with the same upload half and different resource-target bytes as **distinct**;
D treats them as the **same**. They agree today only because a texture's
`MGPipeResourceTargetForTextureTarget(GetTarget())` is constant for the object's life.
**Failure scenario.** If that ever stopped holding, wire would store two entries and D's consume
would erase the first match and leave the second in the set for ever — a full re-upload of that level
on every sync, silently, for the life of the texture.
**Refutation attempted, and it holds today.** A texture emits sub-data only through
`MGPipeBuildSubRegion`/the texture emitter, whose resource-target byte comes from the object's own
target; texture views own their own resource. So this is a latent divergence, not a live one. **Fix**:
either compare the packed field (which is what `RearmPipeTextureLevelUpload` already writes, so
nothing else changes) or assert the low byte matches, at the two comparison sites.
### N-8 (minor) — `Desc.HasDefinedContent` is neither read nor listed among what the descriptor does not answer
`Managers.cpp:6230-6237` enumerates what the descriptor answers and what it does not; c0e made
`HasDefinedContent` storage-defining (`MGPipeTypes.h:301`), the buffer family reads it three times,
and the texture arm reads it nowhere.
**Refutation attempted, and it succeeds on behaviour.** For a texture the per-level pending set is
the authority on content (D-D5), and a level the shadow has not defined is skipped by the per-level
loops; `HasDefinedContent` would add nothing. So this is a **documentation** gap in an enumeration
whose whole purpose is to be exhaustive — one line at `:6237`.
### N-9 (minor) — the G9 probe covers deferral *inside* the function, not *above* it
`SanityTest.cpp:3184`, and `gates-review-v1.md` R1's second half ("distinguish 'not applied yet' from
'applied late'").
The probe calls `twin->SyncTextureParamsToBackend(texture)` directly. The negative control the report
describes — requiring `FindSamplerViewForHandle(...) != nullptr` inside the swizzle block — is
therefore the only deferral shape it can see. A regression that gates the *call* on a sampler view
existing (in `SyncNeccessaryTextures`, or in E's per-unit walk) leaves this case green.
**Refutation attempted, and it is why this is a minor.** R1 asked for a *backend-side probe* taking
its reading while the texture is attachment-only, and that is exactly what this is; the caller-level
shape is a scenario's job and the scenario is F's. Worth one sentence in the case's comment and in
F v3's G9 note, so the next reader does not over-trust it.
---
## 3. What I tried to break and could not
* **Can a `Named` record reach a target-gated apply?** No. `glDrawBuffers` and the four masks are
under `asTarget == Draw` (`:9151`, `:9159`), `glReadBuffer` under `asTarget == Read` (`:9220`), and
`asTarget` is the caller's binding intent, not the record's `Target`. The D-O row survives.
* **Can the metadata respecify recurse?** No. `RequireImageBindableStorage` early-returns on
`m_imageBindableStorageRequired` and calls nothing that re-enters `SyncMipmapsToBackend`.
* **Can `pushedStorage` dangle across the re-arm?** No. The re-arm `push_back`s into
`record.PendingUploads`, which does not move `TextureResources`; only a create/respecify for a new
slot grows the outer vector, and nothing on this path emits one.
* **Can the re-arm break wire's own invariants?** No. It either replaces `UnionBox` and clears
`Regions` (box-only, which is legal and is what `AccumulatePendingUpload` itself falls back to) or
inserts a region-less entry. The one nit is that it *replaces* rather than unions the box; the
replacement is a whole-level box, which contains any box built from the same level's extent, and
`UnionOfBoxes` is `static` in `PipeApply.cpp` so D could not call it anyway.
* **Can `dirtyRects[r]` and `Regions[r]` fall out of step?** No. On the handle arm `dirtyRects` is
*built from* `Regions` (`:7043-7060`), index for index, so `MGB_RECT_SRC_PTR(r, rect)` is
consistent by construction.
* **Does the sampler-view / death-notice `#if` removal (m-7) change any arm?** No. The dispatcher's
own `#if MOBILEGL_PIPE_PUSH` at `:182` opens the whole `OnFrontendStateObjectDestroyed` body;
the removed inner pair was strictly nested inside it.
---
## 4. What I measured — all of it on the rebased tree (base `712c9467`, D head `d86b32e9`)
```
build-push (PUSH=ON) rc 0
build-linux (pull, PUSH=OFF) rc 0
ctest -L unit build-push 100% passed, 0 failed out of 1686
ctest -L unit build-linux 100% passed, 0 failed out of 1686
G1, ISOLATING D (pull build at 712c9467 -> pull build at D's head):
symbol_report.py --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0 rc 0
file bytes 19114360 -> 19114360 ; .text 10806323 -> 10806323 (+0, +0.000%)
.data/.bss/.rodata all +0 ; Total 17226471 -> 17226471 (+0)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
27072 normalised names, 27072 unchanged
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (0)
p4a_untouched_regions.sh 37da3c3a HEAD (F's script, from ~/w7/p4a-gates) rc 0
17 pool / ring / unpack-staging / attachment-permutation /
depth-stencil-sampling / format-caveat regions byte-identical
791b54a3.. StageBlocksIntoUnpackRing 1d6f15c9.. UnpackRingAvailable
19e614af.. UnpackRingAllocate 3ae7e347.. RecomputeBackendColorSlots
822ca3b0.. DepthStencilSamplingReadImpl 266710e0.. ShouldUseCaveatTextureFormat
== esprytobj-v2.md §4, sha for sha
ctest -L integration-gpu -j 8 -R DirectGLES, build-push:
default (0x1fff) 62% passed, 189 failed out of 491 (6 aborts, 183 named)
MOBILEGL_PIPE_PUSH=0x1ff 99% passed, 6 failed out of 491 (6 aborts)
MOBILEGL_PIPE_PUSH=0 99% passed, 6 failed out of 491 (6 aborts)
comm -3 (0 vs 0x1ff) EMPTY -> the two failing SETS are identical
comm -13 (0x1ff not in default) EMPTY -> the default arm is a strict superset
ctest -L integration-gpu -j 8 -R DirectVulkan 100% passed, 0 failed out of 475
G9 probe DirectGLESTextureSync.AnAttachmentOnlyTexturesParametersReachTheDriverWithNoSamplerView
push @ 0, push @ 0x1ff, push @ 0x1fff, and the pull build: PASSED (4/4)
DirectGLESSlotTable.* 20/20 passed
m-6, re-run as a SINGLE TU rather than a whole configure: the build-push compile command for
Managers.cpp with -DMOBILEGL_PIPE_LEGACY_MEMOS=1 rewritten to =0, -fsyntax-only:
rc 0, 0 errors, 0 warnings
(six `#if !MOBILEGL_PIPE_LEGACY_MEMOS` bodies now live in the file: :333 :4281 :7642 :7902
:12187 :12431 — the four P4a added plus two inherited)
greps: MGB_* in any header no hits
pGLContext in MG_Backend PipeInputs.h:1 only
MGPipeResourceOps ∌ MG_State 0
diff adds MGLOG_E_ONCE 17 / MGLOG_E 0 / MGLOG_I 0
```
**The 189 = 183 + 6 classification.** Confirmed by mechanism rather than by a log I no longer have:
the six are the ctest `ENVIRONMENT`-pinned `.Handles` aborts, they are present in all three arms'
failing sets and are the *only* overlap (`comm`), and `comm -13` shows the default arm adds nothing
that fails for a pre-existing reason. The census run's log carried **zero** `FATAL]: MGPipe` lines —
the only two `FATAL` lines are ambient EGL entry-point loads under llvmpipe
(`eglSwapBuffersWithDamageEXT`, `eglUnlockSurfaceKHR`), which the integrator should expect and not
mistake for a pipe fault.
**Not re-derived**: DV-9's 38-line preprocessed-text count (the report withdraws the claim it
supported; the property that matters is measured above), and the retrace corpus (meaningless with no
records, as §5-item-13 says).
---
## 5. The rebase onto `712c9467` — **ID-32's command does not work**
ID-32 and the brief both say:
```
git rebase --onto refs/heads/feat/disaggregated cce81d19 # "replays only the seven rework commits"
```
Ran it. It **conflicts on the first commit**:
```
Rebasing (1/7)
CONFLICT (content): Merge conflict in MobileGL/MG_Backend/DirectGLES/Managers.cpp (4 hunks)
CONFLICT (content): Merge conflict in MobileGL/MG_Backend/DirectGLES/Managers.h (2 hunks)
error: could not apply ac6757e6...
```
**Why**, and it is not a resolvable conflict — it is the wrong range. `cce81d19..HEAD` is the seven
rework commits *only*, and those seven are built on D's **v1 six** (`b1983e2c..8338c18f`), which sit
*below* the two merges and are **not on pipe**: `git diff cce81d19 712c9467 -- Managers.{cpp,h}` is
`-1208 / -360` lines, exactly D's v1 additions. Replaying the seven onto a tree that has none of v1
asks git to re-apply `PushedFramebufferRecord`'s *edit* to a file that has no
`PushedFramebufferRecord`. Resolving the conflicts by hand would silently drop the whole v1
deliverable.
`git rebase --onto refs/heads/feat/disaggregated 9ea44389` is also wrong: it linearises the merged
branch, so after replaying D's six v1 commits cleanly it tries to replay **wire's twelve** on top of
pipe's already-rebased copies of them and conflicts in `PipeApply.{h,cpp}` (wire's rebase onto
`e8502a61` changed their patch-ids, so `git` cannot skip them).
### The recipe that works — verified, zero conflicts, builds, and reproduces every number
```
git checkout --detach 712c9467
git cherry-pick 9ea44389..8338c18f # D's six v1 commits -> clean, 6/6
git cherry-pick cce81d19..ef6beb28 # D's seven rework -> clean, 7/7
```
Thirteen commits, **no conflicts at any step**, and
```
git diff HEAD ef6beb28 -- MobileGL/MG_Backend/DirectGLES/ MobileGL/MG_Test/SanityTest.cpp
```
is **empty** — D's three files are byte-identical to the pre-rebase tree. `cce81d19` is excluded by
the range (its retirement is already `712c9467`); its patch-id and `712c9467`'s differ, so `git`
would *not* have skipped it automatically — leaving it out of the range is what drops it, and that is
the point of starting the second range at `cce81d19` rather than at `815dd6d3`.
Resulting head `d86b32e9`. Both builds rc 0, unit 1686 × 2, G1 0/0/0/0 against `712c9467`'s own pull
build, D-N rc 0, three integration arms at 189/6/6, DirectVulkan 475/475 — §4.
**The pipe head moved during this review** and the recipe survives it. `refs/heads/feat/disaggregated`
is now **`92dffb81`** (C v3 / `p4a/clientsp` fast-forwarded in: eleven commits, `1534cf37..92dffb81`),
with `712c9467` still an ancestor. `git diff 712c9467 92dffb81 -- Managers.cpp Managers.h
SanityTest.cpp` is **empty** — nothing C landed touches any file D owns — so both cherry-pick ranges
apply unchanged onto `92dffb81` and every number in §4 stands. Substitute whatever
`refs/heads/feat/disaggregated` is at integration time for `712c9467` in the recipe; the two ranges
(`9ea44389..8338c18f` and `cce81d19..ef6beb28`) are what matters and they are fixed.
---
## 6. D's verification-round checklist, corrected
`esprytobj-v2.md` §5 is sound; these are the amendments this review adds. Order is still ID-24's
(C v3 → B v2 → **D v2** → E verification → **D verification** → F v3).
1. **Item 2 is short by two shapes (N-2).** The residual-refusal check must cover **eight**:
the six §4 lists, plus `MGPipe: sampler %u has no applier record …its parameters cannot be pushed`
(`Managers.cpp:12174`) and `MGPipe: renderbuffer %u has no applier record …its storage cannot be
allocated from the pushed descriptor` (`:12418`). Grep the stem
`no applier record on the handle arm` (catches seven) **and** `no shader-CSO applier record`
(catches `:11925`). A residual sampler shape points at C's cache seam, a residual renderbuffer
shape at B's renderbuffer descriptor — neither is what the framebuffer shapes would tell you.
2. **Item 3 stays, but read it with N-1 in mind**: if a DSA case is red *and* the framebuffer refusal
is in the log, the driver still had the unconfigured FBO bound. That is B's missing `Named` record,
not a residue of the CRITICAL fix.
3. **Item 7 (the storage-shape seam) is already closed** — I compared `TextureEmit.h:183-241` against
`Managers.cpp:6244-6270` this round: B fills `Width/Height/Depth` from `GetBaseSize()` verbatim and
derives `ArrayLayers` *in addition*, so `MGB_STORAGE_BASE_SIZE` and the frontend agree exactly and
`needsRegeneration` cannot churn on it. Ten minutes saved; spend them on item 6 instead.
4. **Add: assert `MGPipeApplier().StaleFramebufferRecordLookups == 0`** — already item 3's tail, but
also worth asserting after the *image-bindable remint* set, because the re-arm and the framebuffer
table are the two places D writes/reads applier state outside a record apply.
5. **Add (N-4)**: when B's `ImageBindableHint` lands, confirm that a texture whose mask-only respecify
arrives *before* any level is defined does not trip `MGPipeUnmigratedEmulation`. Today it does, and
it is inert; P9 will not be.
6. **Add (N-9)**: when F v3 writes G9's scenario half, note in the white-box case's comment that it
covers in-function deferral only.
7. `MOBILEGL_ESPRYT_FBO_HANDLE_ARM_MEMOS_LINKED` → 1 (`Managers.h:2011`) after E drops the `static`
— unchanged, and the gate is that the flip does not link without E's half.
8. The **0x5ff** arm is expected **GREEN**, not red — `gates-review-v2.md` F-v2-m2 already corrected
the gates side, and D's row is in and matches F's matcher. A red there is a real finding about D's
resolver.
---
## 7. What I could not check
* **The 183's per-case classification.** `~/w7/p4a-esprytobj-lanes*.log` are gone (ID-5-compliant). I
reproduced the count, the six-abort overlap and the superset property mechanically, and sampled the
shapes from a fresh standalone run — which is how N-2 surfaced. The same recommendation as v1
stands: **keep the lane logs until the review of the round closes**.
* **Anything behind a record.** With no client on this tree the handle arms mostly decline; the
CRITICAL's fix, M-1's replay, M-2's descriptor allocation, M-3's attachment walk and the four masks
are all first *executed* on the integrated tree. §6 is where they get their first real reading.
* **G4's retain-mode comparison** — still has not run anywhere in this phase, and DV-15 makes it the
one lane that can tell a legitimate server-side re-arm from a lost emission.
---
Private worktree `~/w7/p4a-rereview-esprytobj` removed and `git worktree prune` run; the
`~/w7/rr-obj-*.log` files and `/tmp/rr-obj-*` scratch removed with it.
@@ -0,0 +1,571 @@
# 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 |
@@ -0,0 +1,666 @@
# P4a package D — `p4a/esprytobj`, rework v2
Branch `refs/heads/p4a/esprytobj`, worktree `/home/swung/w7/p4a-esprytobj`, **HEAD `ef6beb28`**,
**not pushed**. Files touched by the rework: `MG_Backend/DirectGLES/{Managers.h, Managers.cpp}` and
`MG_Test/SanityTest.cpp` — the same three v1 touched, nothing else. Every line number below is a
line number **at HEAD**.
---
## 0. The base: what was rebased, what was merged, and the one commit the integrator must drop
```
git rebase refs/heads/feat/disaggregated # 9ea44389 = c0 + c0b + c0c + c0d, clean, six commits replayed
git merge --no-edit refs/heads/p4a/wire # 70e742a3 -> merge af5dca4c
git merge --no-edit refs/heads/p4a/c0e # 11446f35 -> merge 815dd6d3
```
**Merged heads: `refs/heads/p4a/wire` = `70e742a3` and `refs/heads/p4a/c0e` = `11446f35`.**
`p4a/clientfb` and `p4a/clientsp` were NOT merged (their v2 rounds are in flight; D's verification
round on the integrated tree follows theirs). The rebase replayed all six v1 commits with no
conflicts: `7aa598fa c1d6b41c 49ff8d91 7e400454 a69819e4 9bb95335` →
`b1983e2c b8d0ef1b 42f1379f 308c80cb 107658f7 8338c18f`.
### `cce81d19` — a TEMPORARY BASE COMMIT, and the integrator drops it with the two merges
`[Fix] (Pipe): TEMPORARY BASE COMMIT the integrator drops with the two merges - retire wire v3's
stand-in Named framebuffer target constant, which c0e's enumerator makes a firing static_assert`
wire v3 left `kMGPipeFramebufferTargetNamed = 3` in `PipeApply.h` behind
`static_assert(MGPipeFramebufferTarget::Count == 3)` as the trip wire that makes retiring it
impossible to forget (wire-v3.md §7.2). c0e makes `Count` 4, so **the merged base does not
compile** until that constant is retired. The commit performs exactly the retirement wire-v3.md
§7.2 specifies — delete the constant and its assert, spell
`static_cast<Uint8>(MGPipeFramebufferTarget::Named)` at its six readers (`PipeApply.h:595`, `:965`,
`PipeApply.cpp` target gate and comment, `FramebufferEmitTest.cpp` ×3) — and nothing else. It is
`PipeApply.{h,cpp}` and a wire test file, all package A's, so it is **not** part of D's deliverable:
ID-24 assigns that edit to the integrator in the wire tree after wire's rebase. If the integrator's
own version is textually identical the patch-id matches and the rebase skips it; otherwise drop it.
---
## 1. The seven rework commits
| # | hash | items closed |
|---|---|---|
| r1 | `ac6757e6` | **CRITICAL / ID-19(d)**, E's item (4) |
| r2 | `a8c8824e` | **ID-12 DV-3** (the packed decode), DV-2, DV-4, **ID-15** (D-K2's fourth row), m-4 |
| r3 | `b6169dba` | **M-2** (storage from `Desc` + the metadata respecify), **M-1** (the server's own re-dirty) |
| r4 | `244224bc` | **M-3** (`SyncAttachmentObject` + the four masks from `MGPSurface`), **M-4** |
| r5 | `972384c2` | m-1, m-2, m-3, m-7 |
| r6 | `15787e7e` | **the G9 white-box probe (R1)**, m-8, m-9 |
| r7 | `ef6beb28` | three `#undef`s for macros never defined, and one stale ownership comment (both found by my own audit) |
Full messages:
```
ac6757e6 [Fix] (Espryt): resolve the framebuffer record by the handle it names and refuse before
binding, so a DSA blit or clear configures the framebuffer it is about to write instead
of one that never got its attachments
a8c8824e [Fix] (Espryt): decode the sub-data target's upload half through the contract's accessor,
read the depth-stencil aspect and surface-kind constants c0c minted, and refuse bit 10
without bit 11
b6169dba [Fix] (Espryt): allocate texture storage from the pushed descriptor, honour a
metadata-only respecify's sticky mask, and arm the server's own re-dirty in the applier's
pending set instead of a model the handle arm never reads
244224bc [Refactor] (Espryt): resolve framebuffer attachments and the four cross-object masks from
the record's surfaces, adopting each twin by the handle the record carries, and drop the
registry release helper nothing calls
972384c2 [Fix] (Espryt): consume the carried region offset, refuse a record whose regions disagree
about the level pitch, stop reading the frontend border form on the handle arm, and drop a
nested guard that repeats its parent
15787e7e [Test] (Espryt): assert an attachment-only texture's parameters reach the driver with no
sampler view, prove every P4a kind's slot returns at a moved generation, and stop one
refusal message claiming what it cannot tell
ef6beb28 [Fix] (Espryt): drop three #undefs for macros that were never defined and correct the
attachment-version note that still called the record-driven walk another package's work
```
---
## 2. Item by item
### (1) CRITICAL / ID-19(d) — the record is keyed by the framebuffer handle, and the refusal happens BEFORE the bind
`Managers.cpp:8803` `PushedFramebufferRecord(MGPipeHandle fbo)` is now one call —
`MG_Pipe::MGPipeApplier().FramebufferRecordFor(fbo)`. The `asTarget` parameter and the
`record.Fbo == fbo` test are **gone**: the table is keyed by the handle, so a record that comes back
is that framebuffer's by construction and it comes back whether the object is bound to Draw, to
Read, to both or to neither. Declared at `Managers.h:1879`.
**The bound-target question is now a different function**: `PushedFramebufferIsBoundTo(target, fbo)`
(`Managers.cpp:8812`, declared `Managers.h:1886`) = one compare against
`MGPipeApplier().BoundFramebuffer[Draw|Read]`, exactly ID-19(d). It is the only correct spelling now
that a `Named` record describes an object without claiming any binding for it.
**`SyncToBackend` no longer binds and returns.** The record resolution block moved ABOVE
`Bind(asTarget)` (`Managers.cpp:9054-9091`, the `Bind` at `:9092`): on a missing record the twin logs
one `MGLOG_E_ONCE` naming the handle and returns with **nothing bound**, so the driver's binding is
where the caller left it rather than pointing at a freshly minted, attachment-less driver FBO. The
record's own `Target` is no longer compared against `asTarget` (a `Named` record legitimately names
no binding); what stays gated on `asTarget` is what reaches the DRIVER's bound target — `glDrawBuffers`
and the four cross-object masks stay Draw-only, `glReadBuffer` stays Read-only, and the OIT
argument the old comparison protected is unchanged because the object is bound as `asTarget` at that
point.
**Every DSA entry point is covered without touching E's file.** `BlitNamedFramebuffer`
(`DirectGLES.cpp:6474`, `:6475`) and the four `ClearNamedFramebuffer*` (`:7960`, `:7980`, `:7997`,
`:8017`) all reach the twin through `SyncAndBindFramebufferObject` →
`BackendFramebufferObject::SyncToBackend(framebuffer, target)`, which now resolves **that**
framebuffer's record by its own handle. No `DirectGLES.cpp` edit was needed and none was made.
`SyncReadBufferToBackend` (`Managers.cpp:8838`) asks the same question the same way and its refusal
line dropped the word "read-target": the record is the OBJECT's, and `ReadSurface` is resolved from
that framebuffer's own read buffer under every `Target`, `Named` included (c0e's comment).
The per-target memo `m_syncedRecordHashes` **stays per target** and `Managers.h:1836-1849` now says
why: there is one record for the framebuffer, but syncing it as Draw and syncing it as Read do
different work, so "I have already applied this record" is a per-target claim.
### (2) M-1 — the server's own re-dirty arms the applier's pending set
**Wire exposes no helper**, so the re-arm is written twin-side against the applier's own record —
`MGPipeApplier()` returns a non-const `MGPipeApplierState&` and `PendingUploads` is server-side state
by design (D-D5), so this is the applier's set, not a second twin-side one.
`RearmPipeTextureLevelUpload(res, packedTarget, level, wholeLevel)` at `Managers.cpp:3834`
(declared `Managers.h:717`), called from `RequireImageBindableStorage` (`Managers.cpp:5203`) at `Managers.cpp:5277`.
- The entry is **whole-level with no regions** (`RegionCount 0` = "the union box is the whole story",
D-D3), because a replay owes every texel of the level.
- It **merges** with an entry the client already emitted rather than duplicating it (a whole-level box
subsumes any scatter behind it), and it decodes the packed target with `MGPipeSubDataUploadTargetOf`
so its key is indistinguishable from a client-emitted one.
- It writes a **packed** `MGPSubData::Target` (`MGPipePackSubDataTarget(MGPipeResourceTargetForTextureTarget(
texture->GetTarget()), uploadTarget)`), for the same reason.
- At the applier's `kMGPipeMaxPendingUploads` bound it returns false with a named `MGLOG_E_ONCE`: a
dropped replay is the bug this exists to stop, so it must not be silent.
- Both models are written (the frontend's `MarkStorageDirty` stays): the legacy arm reads it and the
client's own `NoteLevelDirty` hook rides on it.
**The alternative the review offered (OR the frontend flag into the per-level question) was not
taken** and the reason is at the definition: it puts two authorities back on the handle arm and
forces D-D5's "the server never clears the client's flag" to grow an exception for the levels the OR
consumed.
**The three server-side `MarkStorageDirty` sites are enumerated in the comment** at
`Managers.cpp:3836-3856`: `Managers.cpp:5203` (`RequireImageBindableStorage`, live, this helper's
caller); `DirectGLES.cpp:7406` (`GenerateThreeChannelFloatMipmapOnCpu` — package E's file, and E's
verification round calls this helper there or states why not); `DirectGLES.cpp:6735` — which is the
**clear** half (`MarkStorageDirty(..., false)`), so nothing is owed and there is nothing to re-arm.
### (3) M-2 — the storage shape comes from `pushedStorage->Desc`
Seven push-only macros at `Managers.cpp:6244-6263`, `#undef`'d with the pair above at `:7543-7552`:
`MGB_STORAGE_FORMAT`, `MGB_STORAGE_BASE_SIZE`, `MGB_STORAGE_LEVELS`, `MGB_STORAGE_SAMPLES`,
`MGB_STORAGE_FIXED_SAMPLE_LOCATIONS`, `MGB_STORAGE_IMMUTABLE`, `MGB_STORAGE_KIND`. Each takes the
object it would otherwise have been spelled on, so the PULL expansion is the pre-P4a expression with
one pair of parentheses round the receiver — DV-9's discipline, and G1 stayed 0/0/0/0 through the
commit. Applied at:
- `currentTextureInfo` and the storage-kind switch (`:6468-6477`) — the allocation memo
`needsRegeneration` and `canAppendMipmaps` read;
- the mipmap branch's `mipmapCount` (`:6481`, `:6858`) ← `Desc.Levels`;
- `IsImmutable()` at both allocator branches (`:6502`, `:6668`);
- the multisample allocation's sample count and fixed sample locations (`:6617`, `:6635`, `:6642`);
- all 16 `GetFormat()` reads in the mipmap and buffer branches ← `Desc.InternalFormat`.
**Buffer-texture fields** (`:7324-7360`, `:7425-7443`): `Desc.BufferForTexBuffer` names the backing
store (refused loudly when null on the handle arm), the twin resolves it with P3a's
`EnsureBufferResourceForHandle(buffer, pushedTexBuffer)`, the `bufferExternalIndex` memo key becomes
the handle's slot rather than a GL name, and the window comes from `Desc.BufOffset` / `Desc.BufSize`
with `kMGPipeWholeBuffer` resolved live against the buffer's own size (which is what the sentinel is
documented to mean). Written as `#if MOBILEGL_PIPE_PUSH` arms rather than macros because the branch
is structurally divergent; the pull text is byte-identical.
**What the descriptor does NOT answer**, stated at `:6230-6237`: the PER-LEVEL extent and the level
bytes. `MGPResourceDesc` carries one base extent; the per-level sizes are derived and the texels ride
on sub-data. A level `Desc.Levels` claims and the shadow has not defined reads back `{0,0,0}` and the
per-level loops skip it, which is the arm they already take for a sparse chain.
**The metadata respecify (ID-18 M4)** is honoured at `Managers.cpp:6316-6339`: when
`Desc.ImageBindableHint != 0 || (Desc.BindMask & kMGPipeBindShaderImage)` and the twin has not yet
required image-bindable storage, `RequireImageBindableStorage` is called. That IS the "re-derive the
BindMask-driven flags and recreate only where the backend needs the flag at creation" path — the
image carrier may be channel-widened, which is a different allocation and not a different binding —
and it is idempotent, clears `m_isInitialized`, re-arms every defined level in both dirty models
(M-1), and forces the parameter resync the widening's swizzle needs. Arriving on the CREATE instead,
which is the common case once B publishes the hint, costs nothing: `m_isInitialized` is already false
and there are no levels to replay. No reallocation is triggered by the mask alone.
### (4) M-3 — `SyncAttachmentObject` and the four cross-object masks read `MGPSurface`
**The four masks** are answered from the record at `Managers.cpp:8519-8601`:
`IsSnormFallbackSurface` (`:8550`), `IsUnormFallbackSurface`, `IsAlphaWidenedColorSurface`,
`IsIntegerColorSurface`, over `PushedSurfaceTextureTarget` (`:8539`) which gates on
`Kind == kMGPipeSurfaceKindTexture` and refuses `kMGPipeSurfaceNoTextureTarget` loudly rather than
guessing. `ShouldUseCaveatTextureFormat` / `BackendTextureFormatAddsAlpha` and their renderbuffer
siblings are **untouched** (two are on D-N's byte-identical list, verified below); only what they are
ASKED changed. The one call site — `SyncToBackend`'s draw-buffer mask block — takes a push-only early
branch at `:9163-9192` that resolves `record->Color[index]` from the decoded draw-buffer index and
`continue`s, so the frontend `GetAttachment` below is not even bound on the handle arm.
**The attachment walk**: `PushedSurfaceForAttachment(record, point)` (`:8605`) maps Color0..Color7 →
`Color[i]`, Depth → `Depth`, Stencil → `Stencil`, and answers null for points the record cannot
describe. `SyncAttachmentSurface(glFBOTarget, surface, attachmentObject, glBackendAttachment)`
(`:8631`) is the handle arm of `SyncAttachmentObject`; the call site is `:9290-9322`.
What moves: the TWIN RESOLUTION (`AdoptTwinByHandle(g_backendTextureObjects, surface.Res, "texture")`
and the renderbuffer equivalent — an adoption by the handle the record carried, not a lookup by the
frontend object's address) and the ATTACH SHAPE (`Layered`, `Level`, `Layer`, `UploadTarget`,
`TextureTarget`). What does not move, and is argued at the definition: the twins'
`SyncMipmapsToBackend` / `SyncToBackend` still take the frontend object — they read the level shadow
for the texels, which no record carries, and they have their own handle arms that drive the storage
from the descriptor. The frontend object is also **cross-checked**: a record whose `Res` does not name
the same twin the frontend attachment does is a seam defect and is refused loudly rather than resolved
in favour of either side. A point the record does not describe with a live attachment on it is loud;
an empty one is silently fine (D-C3 refuses bit 9 on a driver reporting more than 8 colour points, so
Color8..31 cannot legally hold one).
**E's READ-only attachment parameter sync stays reachable.** E closed D-E3 through a new
`SyncReadFramebufferTextureAttachments` in `DirectGLES.cpp` that walks the applier's read framebuffer
and calls `SyncTextureParamsToBackend` / `SyncBuiltinSamplerToBackend` per attachment. Nothing here
touches that function, the two twin entry points it calls, or their signatures; the attachment walk
changed here is `BackendFramebufferObject::SyncToBackend`'s, which E's list does not go through.
### (5) M-4 — the adoption helper is wired, one registry method is removed
- `AdoptTwinByHandle` now has **two callers** (`Managers.cpp:8657`, `:8723` — the texture and the
renderbuffer registry, from `SyncAttachmentSurface`), which is where a handle actually arrives in a
payload. Its comment (`:3529-3552`) says so and names the other three kinds' resolution sites as
package E's, so their first adoption is E's to write through the same template.
- `StateBackendObjectRegistry::GetOrCreateByHandle` and `LiveGenAt` are reached through it.
- **`StateBackendObjectRegistry::ReleaseByHandle` is REMOVED** (`Managers.h:470-481` now carries the
decision instead of the method). Its own precondition — "a kind whose announcement is its own
destroy CALL" — holds for the BUFFER family and for none of the five kinds this registry serves:
every one of them dies through `DestroyByLifetimeId`, because P4a adds no server-side destroy arm
for a texture, a renderbuffer, a framebuffer, a sampler CSO or a shader CSO. The one-line wrapper
comes back in the commit that gives it a caller. `SlotTable::ReleaseByHandle` underneath is
untouched and is what `SanityTest.cpp` drives directly.
### (6) ID-12 — the HIGH byte is decoded, and every other `Target` comparison is audited
`FindPipeTextureUpload` (`Managers.cpp:3799`) and `ConsumePipeTextureUpload` (`:3821`) both compare
`MGPipeSubDataUploadTargetOf(pending.UploadTarget)` against the passed half; the re-arm helper does
the same at `:3872`. The three call sites that pass the bare `static_cast<Uint16>(TextureUploadTarget)`
needed no edit. `Managers.h:703-707` states the convention where the two functions are declared.
**Audit**, `grep -n '\.Target\|->Target\|\.UploadTarget'` over `Managers.cpp` at HEAD — eight hits
and every one of them accounted for:
| line | what |
|---|---|
| `:3792`, `:12379` | comments |
| `:3799`, `:3821`, `:3872` | the three decoded comparisons (find, consume, re-arm) |
| `:3888` | the re-arm's WRITE of a packed `MGPSubData::Target` |
| `:8673` | `MGPSurface::UploadTarget` — a different field, a bare `TextureUploadTarget`, no packing |
| `:8902` | the same field, compared surface-to-surface in the read-buffer decode (m-4) |
`MGPResourceDesc::Target` is still **never read** — M-2 reads `Desc.StorageKind`, not `Desc.Target`,
so the storage-kind switch does not go through the resource-target enum at all.
`MGPFramebufferState::Target` is a different field again and, per item (1), is no longer compared.
**DV-2** (`Managers.cpp:7840`): `MGB_TEXPARAM_DS_MODE`'s bare `!= 0` became
`== MG_Pipe::kMGPipeDepthStencilModeStencil`. **DV-4** (`:8877`): the read-surface emptiness test keeps
`MGPipeHandleIsNull(Res)` as the authority (D-C1) and **cross-checks** `Kind` against it, refusing
loudly when the two disagree instead of silently picking a winner.
### (7) ID-15 — the texture family's resolver refuses bit 10 without bit 11
`ResolveTextureResourceSubsystemArm` (`Managers.cpp:3624-3667`) gained a second
`PipeSubsystemDependencyMissing` row after the bit-7 one: **bit 10 requires bit 11**, refusing the bit
and running the legacy arm, in the same voice as the bit-8-without-bit-7 precedent at
`ResolveVertexInputSubsystemArm` (`Managers.cpp:2409-2431`) — same "the handle arm resolves through a
slot table only the other bit populates" shape, same `MGLOG_E`, same fall-back. The reason is stated
at the site: `MGPTextureParams::BuiltinSampler` is a SamplerCso handle, only bit 11 mints sampler CSOs
(c0b's four unconditional mints exclude it), and the applier's verdict for a null one is
`Fatal{ProtocolCorruption}`.
**The mirror pairs, as the source now states them:**
| pair | verdict |
|---|---|
| bit 7 set, bit 10 clear | **fine** — P3a's shipped configuration (unchanged) |
| bit 10 set, bit 7 clear | refused (v1, unchanged) |
| bit 11 set, bit 10 clear | refused (v1, unchanged) |
| **bit 10 set, bit 11 clear** | **refused now** — D-K2's fourth row |
| bit 8 set, bit 7 clear | refused (P3a, unchanged) |
| bit 7 set, bit 8 clear | **fine** (unchanged) |
| bit 12 (programs) | depends on nothing (unchanged) |
`ResolveSamplerSubsystemArm`'s comment said "the mirror pair (bit 10 set, bit 11 clear) is FINE";
that sentence is corrected in place (`Managers.cpp:3692-3699`) — the dependency is now SYMMETRIC, bits
10 and 11 are one arm with two switches, and the only two masks that reach the texture handle arm are
"both set" and "neither set". The two latches are raw bit tests on the mask, never calls to each
other, so they cannot initialise each other.
### (8) E's item (4) — `InvalidateFramebufferHandleArmMemos` inside `InvalidateFramebufferBindingCache`
The call is written at `Managers.cpp:8270-8278`, inside `InvalidateFramebufferBindingCache`, beside
the pre-handle trio it clears. **It is gated**, and this is a declared deviation the integrator must
see:
`InvalidateFramebufferHandleArmMemos` is **`static`** in `DirectGLES.cpp` (E v2, `:2789`) and owns E's
storage (`g_fboSyncedSerials`, `g_fboRecordsTrusted`). An internal-linkage function cannot be called
from `Managers.cpp`, and E is not merged into this base, so there is no definition here to link
against at all. The handshake is two lines and neither side can do it silently:
- `Managers.h:1996-2015` declares the entry point behind
`#define MOBILEGL_ESPRYT_FBO_HANDLE_ARM_MEMOS_LINKED 0`, with the whole argument at the declaration;
- **E's verification round drops the `static` keyword** (one token);
- **D's verification round flips that constant to 1** (one line, in D's own file).
The constant has no other reader and the declaration has no other definition, so a half-done
handshake does not build. **The three `SanityTest.cpp` callers E named are covered the moment it is
on**: `ScopedStateGuardMocks::ResetShadows` (`SanityTest.cpp:2530`) and `ScopedBackendTwinMocks`'
constructor and destructor (`:2778`, `:2799`) all go through
`FramebufferImpl::InvalidateFramebufferBindingCache()`, which is exactly why the call belongs inside
it rather than at nine call sites.
### (9) The G9 white-box probe (gates review R1)
`SanityTest.cpp:3184` —
`DirectGLESTextureSync.AnAttachmentOnlyTexturesParametersReachTheDriverWithNoSamplerView`.
It covers the half `TextureParamsWithoutASamplerViewScenario` cannot: that scenario's observation is a
SAMPLE, the sample creates the sampler view, and a backend that merely DEFERS the apply to the first
view is green there. This one takes its reading while the texture is still attachment-only.
- A complete 8×8 texture is specified and then released from every unit
(`BindTexture(GL_TEXTURE_2D, 0)`), so nothing in the test ever binds it for sampling and nothing
mints a sampler view for it.
- `SetSwizzleParam(Red, Green)` — not any texture's default, so a driver that never hears about it is
distinguishable from one that does.
- On the handle arm the probe writes the applier records itself (`MGPipeApplyResourceCreate`, a
`SamplerCso` through `MGPipeApplyCreateSamplerState` because a null `BuiltinSampler` is
`Fatal{ProtocolCorruption}`, then `MGPipeApplySetTextureParams`) — which is what makes it a
white-box test: no client emitter exists on this tree, and the subject is Espryt's behaviour GIVEN a
record.
- It asserts, before the sync, that **no sampler-view twin exists for the texture** — the assertion
the public scenario cannot make, because making it there would create the view.
- Then it drives `twin->SyncTextureParamsToBackend(texture)` and asserts a
`glTexParameteri(GL_TEXTURE_SWIZZLE_R, GL_GREEN)` reached the mocked driver.
**Green here on all four arms** (push build at masks `0`, `0x1ff`, `0x1fff`, and the pull build).
**Red on the tag's behaviour** — negative control run and restored: mutating the swizzle block to
require `FindSamplerViewForHandle(...) != nullptr` (the deferral reinstated) makes the case fail with
its own message, and the tree was restored, rebuilt and re-run green
(`git status --porcelain` clean afterwards).
### (10) The ten minors
| # | disposition |
|---|---|
| m-1 | **Fixed, partly.** `MGPSubRegion::SrcOffset` is CONSUMED at all three per-rect sites through `MGB_RECT_SRC_PTR(idx, rect)` (`Managers.cpp:7091`, used at `:7123`, `:7218`, `:7262`), a macro rather than a second lambda for DV-9's measured reason. Every such site is inside `subRectEligible`, which requires `uploadData == mipData`, so the base the offset is relative to is the level shadow itself. **The union-box path still derives its pointer** and cannot do otherwise: `MGPBox` carries no offset, only `MGPSubRegion` does. **`MGPSubData::SourceIsVerbatimLevelShadow` is NOT readable by this package and is DECLARED**: the applier's `MGPipeResourceRecord::PendingUpload` stores `{UploadTarget, Level, UnionBox, Regions}` and does not carry it (`PipeApply.h:283-289`), so `subRectEligible` keeps the `uploadData == mipData` pointer comparison. Carrying it is a wire change; owner = package A at its verification round. |
| m-2 | **Fixed.** `Managers.cpp:6975-7001`: every region's `SrcRowStride`/`SrcSliceStride` is compared against the first; on disagreement the carried pair is DROPPED (the level's extent × bpp is used, which is what the legacy arm computes) and one named `MGLOG_E_ONCE` says so. The assert the review asked for, not a per-region stride loop: a pitch is the level's. |
| m-3 | **Fixed.** `Managers.cpp:8058-8065`: `borderColorForm` is `borderColorReadable ? MGB_TEXPARAM_BORDER_FORM : m_cacheBorderColorForm`, so there is no live frontend read left on the switched-over path, and the value a skipped block sees cannot make the condition true. |
| m-4 | **Fixed.** `Managers.cpp:8888-8912`: the read-buffer decode compares `Res`, `Kind`, `Layered`, `Level`, `Layer` and `UploadTarget`. `InternalFormat` and `TextureTarget` are properties of the RESOURCE rather than of the point and are deliberately left out. |
| m-5 | **DV-9 reworded** — see §3 below. |
| m-6 | **Run.** `cmake -DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_PIPE_LEGACY_MEMOS=OFF` compile-only configure, numbers in §4. |
| m-7 | **Fixed.** `Managers.cpp:217`: the nested `#if MOBILEGL_PIPE_PUSH` around the `SamplerViewCso` case is gone; the dispatcher's own guard at `:182` already opens it. |
| m-8 | **Fixed.** `SanityTest.cpp:4194-4208`: the message no longer claims what the assertion cannot tell, and a comment says which of the two assertions separates a refusal from an adoption (and why the first is kept: a non-null there would be a third and worse outcome). |
| m-9 | **Fixed.** `SanityTest.cpp:4337-4352`: `KindCase` carries the pre-death handle and every one of the five object kinds now gets the ABA leg — the slot came back, and at a MOVED generation, which is what a double free would break by skipping one. |
| m-10 | **Restated.** §4's refusal census names all six shapes; the count is per shape, not per grep. |
---
## 3. Deviations, updated
**DV-9 — REWORDED (m-5).** The sentence "the pull build's preprocessed text — and therefore its
object code — is unchanged" is **withdrawn**. The review measured it and it is false as worded: at
v1 the pull build's preprocessed text differed in 38 non-semantic lines (23 `line = N` constants in
`ErrorLopper::Loop` lambda captures shifted by the insertions, 13 pure added-parenthesis differences
from the macro expansions, 2 whitespace re-flows) with zero semantic differences. **That count is the
reviewer's, at v1, and this round did not re-derive it** — it can only have grown, because the round
added nine more macros (seven storage, one rect pointer, and DV-2's re-spelling), each of which adds
parentheses to the pull expansion by construction.
What the deviation should have claimed, and what IS verified here, is the CONCLUSION: the pull build's
**symbol set and byte size do not move**, which is the property D-P actually requires and which
`symbol_report --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` measures directly —
**0 added / 0 removed / 0 resized / 0 renamed and +0 bytes of `.text` at every one of the eight
commits of this round** (§4). The macro-over-lambda choice stands for the same measured reason it was
made: a lambda inserted into `SyncMipmapsToBackend` renumbers every `$_N` in it.
**DV-1 — closed by M-4.** The adoption helper and `GetOrCreateByHandle` have callers;
`ReleaseByHandle` is removed rather than left dead.
**DV-5 / DV-7 — closed by M-3.** Both are D's work and both are done. The v1 report's §7 item 13
("closed on the E side") and DV-7's "package E's `SyncAttachmentObject` work" are **wrong** and are
corrected here: `SyncAttachmentObject` is `Managers.cpp`, which C.7 gives to D. E closed D-E3 by a
different route (`SyncReadFramebufferTextureAttachments` in `DirectGLES.cpp`), which is untouched.
The stale comment in v1's source that said the array "retires with the frontend attachment objects,
which is E's `SyncAttachmentObject` work" is rewritten at `Managers.cpp:9250-9256` — see §7.
**DV-2 / DV-3 / DV-4 — retired**: c0c's constants and accessors are read.
**DV-6, DV-8, DV-10, DV-11, DV-12 — unchanged** and accepted as v1 argued them. DV-11's asymmetry note
(the `if (pushedStorage == nullptr)` / `if (FramebufferSubsystemEnabled())` arms get no "loud
unreachable" body) still stands and m-6's compile now exercises the four that do have one.
**NEW DV-13 — the handle-arm framebuffer memo hook is gated.** See item (8). One line each side, both
named at the declaration.
**NEW DV-14 — `MGPSubData::SourceIsVerbatimLevelShadow` is unreachable from this package.** See m-1.
The applier does not carry it into `PendingUpload`; owner = package A.
**NEW DV-15 — the re-arm helper writes the applier's own `PendingUploads`.** `MGPipeApplier()` is
non-const and the set is server-side state by design (D-D5), so this is not a twin-side shadow. G4's
retain-mode comparator compares the EMITTED shape against the tracker's retained one; a server-side
re-arm is a legitimate difference there and the verify lane must be read with that in mind
(`RequireImageBindableStorage` is the only site that produces it).
---
## 4. Gates — every number, at HEAD `ef6beb28`
All in `/home/swung/w7/p4a-esprytobj` with `CCACHE_BASEDIR=/home/swung/w7`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` exported, `-j 8`.
```
build-linux (pull, PUSH=OFF) rc 0
build-push (PUSH=ON) rc 0
G1 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 rc 0
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
RE-RUN AT EVERY COMMIT OF THIS ROUND, base repair included, each rebuilt clean and measured:
cce81d19 ac6757e6 a8c8824e b6169dba 244224bc 972384c2 15787e7e ef6beb28
all eight: .text 10806323 -> 10806323 (+0), 27811 -> 27811 symbols,
0 added / 0 removed / 0 resized / 0 renamed, 27072 normalised names unchanged
ctest --test-dir build-linux -L unit 100% passed, 0 failed out of 1686 rc 0
ctest --test-dir build-push -L unit 100% passed, 0 failed out of 1686 rc 0
(1685 after r5, 1686 from r6's new case on)
bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD rc 0
the 11 pool / deferred-release / ring / flush-drain functions are
byte-identical between 37da3c3a and HEAD
G13 grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$'
MobileGL/MG_Backend/MGPipe/PipeInputs.h:1 <- ONE file, unchanged
awk '/struct MGPipeResourceOps \{/,/^ \};/' MG_Pipe/PipeApply.h | grep -c MG_State
0
grep -rn 'MGB_LEVEL_|MGB_TEXPARAM|MGB_RBO_|MGB_STORAGE_|MGB_RECT_' MobileGL --include=*.h
(no hits - no macro leaks into a header)
```
### D-N: the four functions in this package's files
Run with **package F's `scripts/p4a_untouched_regions.sh`** (it exists in `~/w7/p4a-gates` and not on
this tree; invoked from this worktree so its `git show` reads this tree's refs — it was NOT copied in
or committed here, `scripts/` is F's):
```
bash /home/swung/w7/p4a-gates/scripts/p4a_untouched_regions.sh 37da3c3a HEAD rc 0
[p4a-untouched] the 17 pool / ring / unpack-staging / attachment-permutation /
[p4a-untouched] depth-stencil-sampling / format-caveat regions are byte-identical
791b54a35a19b58c82a5b9143cf48aa9ee815c755ecc1d4fa8dae709eeaa20bf StageBlocksIntoUnpackRing
1d6f15c983bbf7e26bcb6bdfdc0f9bd940367d928b35480717ef22a4f663ef12 UnpackRingAvailable
19e614afbed5c0af01517f5ad75926d42f60eae7e23385190989dd47d0132f4f UnpackRingAllocate
3ae7e3472c4a730d24549ee8b51b87eacf284dec1266b498cd5f3e056f787188 RecomputeBackendColorSlots
822ca3b0ece4e662f9b462945f2697f6b14547d841d926ae94c2b35139f16e53 DepthStencilSamplingReadImpl
266710e0fdc19756f31e27dcee536149c99fc9fe583752042135b3a9cde26366 ShouldUseCaveatTextureFormat
```
**These four shas are NOT v1's** (`d75537bc… a0c9994d… f56d432f… 39a37249…`) and that is a change of
EXTRACTOR, not of content: v1 used a one-off equivalent because F's script did not exist, F's script
hashes the region differently, and both say the same thing — **rc 0, byte-identical between
`37da3c3a` and HEAD**. v1's report printed no sha for P3a's eleven, so there is nothing to compare
them against there; what IS a cross-check is that `p3a_untouched_regions.sh` and F's superset print
the SAME eleven shas on this tree, so the two extractors agree everywhere they overlap.
### Integration-gpu, three arms, `-R DirectGLES`
```
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8 -R DirectGLES
default (0x1fff) 62% passed, 189 failed out of 491 rc 8
MOBILEGL_PIPE_PUSH=0x1ff 99% passed, 6 failed out of 491 rc 8
MOBILEGL_PIPE_PUSH=0 99% passed, 6 failed out of 491 rc 8
```
**The 0x1ff and 0 failing SETS are identical, and are exactly the six `.Handles` aborts** (diffed
with `comm`, zero differing lines):
```
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.ABufferAtARecycledAddressDoesNotInheritItsPredecessorsContents
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AFramebufferAtARecycledAddressDoesNotInheritItsPredecessorsTwin
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.ATextureAtARecycledAddressDoesNotInheritItsPredecessorsTwin
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexBufferSet
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexInput
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.DestroyedVertexArraysReturnTheirVertexElementsSlots
(Subprocess aborted)
```
They are the ctest `ENVIRONMENT`-pinned `MGL_ITEST_HANDLES_ARM_KNOBS = "MOBILEGL_PIPE_LEGACY_MEMOS=0"
"MOBILEGL_PIPE_PUSH=0x1ff"` arm (`MG_IntegrationTest/CMakeLists.txt:949`), which replaces the job env
— so both outer lanes see them — and under that pair all four P4a families classify as `NoArm` and
`StopOnArmlessPipeSubsystem` aborts, which is what D-K3 rules must happen. **Package F's pin move
`0x1ff → 0x1fff` at `:949, 1065, 1075, 1149, 1183, 1188, 1219` and `0x80000000000001ff →
0x8000000000001fff` at `:1070, 1080` is what closes them.** Unchanged from v1, reproduced.
### The default arm: 189 = 183 + 6, classified BY SHAPE
- **6** = the same six aborts above, `comm`-verified to be present in all three arms' failing sets and
the only overlap. **Zero of the other 183 abort** (`grep -c 'Subprocess aborted'` over the 183 = 0).
- **183** = the named-refusal set. `comm -13` (0x1ff failures not in the default set) is EMPTY, so the
default arm is a strict superset and nothing that passes at 0x1ff was newly broken.
The census, taken with `MOBILEGL_LOG_FILE_PATH` over 17 standalone runs sampled across the failing
suites — **six distinct shapes and no seventh**, which is m-10's correction to v1's "three":
```
MGPipe: texture N has no applier record on the handle arm, so its parameters cannot be pushed (handle {N, N})
MGPipe: texture N has no applier record on the handle arm, so its built-in sampler cannot be pushed (handle {N, N})
MGPipe: texture N has no applier record on the handle arm, so its storage and uploads cannot be driven from the pushed descriptor (handle {N, N})
MGPipe: framebuffer N has no applier record on the handle arm, so it cannot be synced from the pushed record and is left unbound rather than bound-and-unconfigured (handle {N, N})
MGPipe: framebuffer N has no applier record on the handle arm, so its read buffer cannot be pushed (handle {N, N})
MGPipe: program N has no shader-CSO applier record on the handle arm, so its synced serial cannot be stamped (handle {N, N})
```
**Zero `FATAL]: MGPipe` lines** across the sample. The non-MGPipe `ERROR` lines in those runs are the
DOWNSTREAM consequences of the declines and nothing else: `ReadPixels: bound READ FBO is not
complete` and `BlitFramebuffer: the depth/stencil aspect was dropped` (a framebuffer that got no
attachments because its record does not exist), one `glCopyImageSubData failed` (a texture with no
storage for the same reason), and `NormalizePixelFormat: unhandled internalFormat:
GL_STENCIL_INDEX8`, which is **ambient** — the control below shows it in the PASSING run of the same
case.
**Control**, `IntegerBorderColorScenario.InsideTexelsAreUnaffectedByTheBorderColour` standalone:
```
MOBILEGL_PIPE_PUSH=0x1ff -> [ OK ], 0 'ERROR]: MGPipe' lines, 2 NormalizePixelFormat lines
default -> [ FAILED ], the six shapes above, 2 NormalizePixelFormat lines
```
**The framebuffer refusal's wording changed this round** (item (1): "…is left unbound rather than
bound-and-unconfigured"), so a grep written against v1's text will miss it. The stem
`no applier record on the handle arm` still matches all five of the first-family shapes.
### The DirectVulkan lane (ID-8's death/leak half)
```
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 8 -R DirectVulkan
100% passed, 0 failed out of 475 rc 0
```
Under `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`. Zero failures, so the exit-order and
death-notice rules hold on the backend that installs no death ops.
### m-6: the `MOBILEGL_PIPE_LEGACY_MEMOS=OFF` compile-only configure
The four `#if !MOBILEGL_PIPE_LEGACY_MEMOS` "unreachable but loud" bodies this package added
(`Managers.cpp` texture params, built-in sampler, sampler twin, renderbuffer twin) were compiled in
NO build of the v1 round — `build-linux` and `build-push` both pass
`-DMOBILEGL_PIPE_LEGACY_MEMOS=1`. They are compiled now:
```
cmake -S . -B ~/w7/dobj-nolegacy -G Ninja -DCMAKE_BUILD_TYPE=Release
-DCMAKE_C_COMPILER=/usr/sbin/clang -DCMAKE_CXX_COMPILER=/usr/sbin/clang++
-DMOBILEGL_PIPE_PUSH=ON -DMOBILEGL_PIPE_LEGACY_MEMOS=OFF configure rc 0
cmake --build ~/w7/dobj-nolegacy --parallel 8 --target MobileGL_s build rc 0
0 lines matching 'error:'; Managers.cpp compiled in this configuration
```
**The compiler has to be spelled.** A bare configure picks GCC on this box and GCC fails in
`MG_Impl/GLXImpl/GLXImpl.cpp:178` (`-Wchanges-meaning` on a member named `Display`) — a pre-existing,
unrelated toolchain difference, not a P4a defect; both gate builds use `/usr/sbin/clang++`, which is
what the line above passes. The build directory was removed afterwards.
---
## 5. What the verification round must do, in order
This is D's checklist for the round that runs on the integrated tree AFTER `C v2` and `B v2` land
(ID-24's order: c0e → wire → C v2 → B v2 → **D v2** → E verification → **D verification** → F v3).
1. **`MOBILEGL_ESPRYT_FBO_HANDLE_ARM_MEMOS_LINKED` → 1** (`Managers.h:2011`), once E's verification
round has dropped the `static` on `InvalidateFramebufferHandleArmMemos`. One line. Re-run
`ctest -L unit` and the `-R HandleRecycle` integration set: the three `SanityTest.cpp` fixtures
that clear the pre-handle trio now clear the handle-arm memos too.
2. **The residual-refusal check, PER SHAPE and not per count.** With `MOBILEGL_LOG_FILE_PATH` set, the
integrated tree must show **zero** of all six shapes in §4. A residual of any one of them is a seam
defect (P3a's lesson), not a leftover. The framebuffer two are the ones the CRITICAL fix would
masquerade as if B did not emit `Named` records.
3. **The DSA / named-framebuffer set, explicitly**, because that is what the CRITICAL fix buys and it
cannot be observed on this tree:
`ctest --test-dir build-push -L integration-gpu -R 'ClearThenReadPixels|Orientation|FramebufferChurn|DepthStencilReadback'`
plus `ctest --test-dir build-push -R 'FramebufferTest.NamedFramebuffer'`. Also assert
`MGPipeApplier().StaleFramebufferRecordLookups == 0` — wire made that the framebuffer family's own
seam counter and 0 is the expected value.
4. **B's `Named` records at all five DSA entry points plus the DSA setters** (ID-19(c), wire-v3 §5
B.1/B.2). If B emits none, item (1)'s fix produces the framebuffer refusal instead of a wrong
picture — which is the intended failure mode, and the integrator needs to read it as B's gap.
5. **The image-bindable remint set, for M-1**, one dispatch and one readback apiece:
`ctest --test-dir build-push -L integration-gpu -R 'ImageLoadStoreSso|FormatlessImageBake|ImageSizeAfterRespec|ImageTargetKind|SampledSetStaleness'`,
and confirm a CONTENT assertion exists beside the swizzle one in
`TextureParamsWithoutASamplerViewScenario.AnImageUnitOnlyTexturesSwizzleSurvivesARequireImageBindableStorageRemint`
— today's case checks the swizzle, which M-1 does not break.
6. **The metadata respecify end to end (M-2 / ID-18 M4)**: B publishes a mask-only respecify on an
IMMUTABLE texture; the applier must classify it as metadata (no ack, no pending-upload clear) and
the twin must widen the carrier and replay the levels. The observable is that the first
`glBindImageTexture` after an upload reads the texels rather than zeroes.
7. **The storage-shape seam (M-2)**: B's `MGPipeTextureExtentOf` clamps `Width/Height/Depth` at 0 and
derives `ArrayLayers` separately; this package reads `Width/Height/Depth` as the base extent and
`Levels` as the level count. Ten minutes on `TextureEmit.h:183-241` against
`Managers.cpp:6224-6263` closes it; a disagreement shows up as `needsRegeneration` firing every
sync (a re-allocation per draw) rather than as a wrong picture.
8. **The attachment seam (M-3)**: the cross-checks at `Managers.cpp:8643`, `:8649`, `:8710` and `:8717` refuse
when the record's `Res` and the frontend attachment's handle disagree. It must never fire; if it
does, B's `MGPSurface::Res` fill and the twin's `HandleOf` disagree about which object is attached.
Also confirm B fills `MGPSurface::TextureTarget` (c0c) — `kMGPipeSurfaceNoTextureTarget` on a
texture point is loud here and turns all four masks off.
9. **G4's retain-mode comparison** (`build-verify`, `-L integration-verify`) — it has not run anywhere
in this phase and it is the only mechanism that can check a consume-and-clear set. Read it with
DV-15 in mind: `RequireImageBindableStorage`'s server-side re-arm is a legitimate difference
between the emitted set and the applier's.
10. `MOBILEGL_PIPE_PUSH=0x5ff ctest --test-dir build-push -R 'ObjectSubsystemControl'` — F's
dependency-refusal scenario for D-K2's fourth row (item (7)). D's half is in and correct; the
expected log line names both bits and the legacy arm runs.
11. `MOBILEGL_PIPE_PUSH=0x9ff` — the bit-11-without-bit-10 arm, unchanged from v1.
12. The six itest phase pins `0x1ff → 0x1fff` and the two `0x80000000000001ff → 0x8000000000001fff`
(package F). Until they move, the six `.Handles` aborts are red on the integrated tree.
13. `python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib build-push/libMobileGL.so ...` after
`git lfs checkout` — not run this round (with empty records the corpus can only reproduce the
refusal set, so the number would mean nothing), and it is the first real reading once records
exist.
14. `GLIBC_TUNABLES=glibc.malloc.tcache_count=0` on the unit, integration and verify runs, and the
ID-8 leak/idempotence half on the DirectVulkan lane — 475/475 here, and F's
`HandleRecycleScenario.…ReturnTheirSlots` cases (G8b) are where `SamplerViewCso`, the kind with no
frontend object, has to be covered; nothing in D or E can test it there.
---
## 6. Open items handed on
| item | owner |
|---|---|
| `InvalidateFramebufferHandleArmMemos`: drop the `static` (one token) | package E, its verification round |
| `MGPSubData::SourceIsVerbatimLevelShadow` is not carried into `MGPipeResourceRecord::PendingUpload`, so D-D6's test is unreachable and `subRectEligible` keeps the pointer comparison (DV-14) | package A (wire), its verification round |
| `MGPipeApplyResourceRespecify`'s per-level pointer with a byte-identical descriptor keeps the level it redefines (wire's own W11) — worth ten lines on B's `AllocateStorage` path | package B / the integrator |
| the itest phase-mask pins `0x1ff → 0x1fff` | package F |
| the four remaining `MGPipeUnmigratedEmulation` sites in `DirectGLES.cpp` | package E |
| G4's retain-mode comparison has still not run anywhere in this phase | the integrator |
---
## 7. Corrections to `esprytobj-v1.md`
- **§7 item 13 is wrong**: G9's red-before case is not "closed on the E side (`SyncAttachmentObject`
gains the parameter sync for READ-only attachments)". `SyncAttachmentObject` is `Managers.cpp`,
which C.7 gives to D. E closed D-E3 through a NEW function in its own file
(`SyncReadFramebufferTextureAttachments`), and G9 itself is now a white-box assertion (ID-19) which
this round supplies at `SanityTest.cpp:3184`.
- **DV-7 is wrong for the same reason** and DV-5's "owner: the contract (package A) + the integrator.
Until then this package leaves the four masks reading the frontend" is superseded: c0c minted the
field and this round moved all four masks onto it.
- **DV-9's wording** is corrected in §3 above (m-5).
- **§6.4's "three refusals"** is corrected to six shapes in §4 above (m-10); the classification claim
("no case fails for any other reason") holds and is re-verified over a 17-case sample.
- The source comment that said the per-attachment version array "retires with the frontend attachment
objects, which is E's `SyncAttachmentObject` work" was stale on both counts and is **rewritten**
(`Managers.cpp:9250-9256`, commit `ef6beb28`): the walk resolves each attachment from the record
now, so the versions say only "this point may have moved since I last looked", and they retire with
the frontend attachment array itself, which is a later phase's and not package E's.
@@ -0,0 +1,479 @@
# P4a package D — `p4a/esprytobj3`, the VERIFICATION ROUND on the integrated tree
Branch `refs/heads/p4a/esprytobj3`, worktree `/home/swung/w7/p4a-esprytobj3`, base
`refs/heads/feat/disaggregated` = **`17396216`** (contract c0..c0e + wire + clientsp v3 + clientfb v2 +
esprytobj v2's thirteen replayed commits). **HEAD `56453191`**, three commits, **not pushed**.
Files touched: `MG_Backend/DirectGLES/{Managers.h, Managers.cpp}` and `MG_Test/SanityTest.cpp` — the
same three, nothing else. `DirectGLES.cpp` is package E's and is **byte-identical to the base**
(one temporary experiment, run and reverted — §4.1).
**Headline.** The default arm reaches **485 / 491** on the DirectGLES lane, the six failures are the
armless `.Handles` aborts that package F's pin move closes, and the eight-family refusal census over
the whole lane is **ZERO for all eight**. Four seam defects were found; two are fixed here, one needs
one line from package E (written out verbatim in §4.1, and proved to close the seam), and one is a
**phase-level defect the integrator must rule on: at the default mask the DirectVulkan backend has no
texture-upload consumer, so 66 of its 475 integration cases and 40 of 40 of its retrace cases are
red** (§4.2).
---
## 1. The three commits
| # | hash | what |
|---|---|---|
| v1 | `84c0edbd` | `[Fix] (Espryt): close the nine re-review minors - the framebuffer refusal now claims only what it can, the adoption refusals have a reachable caller, the carried region offsets and the sub-data resource byte are cross-checked, the remint-pull marker fires only when a level is owed, and a record-empty point the frontend still holds is refused` |
| v2 | `aec41e7d` | `[Fix] (Espryt): take the sampler CSO record from the handle the caller carries - a content-addressed record can never be named by the twins own identity handle, so every bound sampler objects parameters were refused on the integrated tree` |
| v3 | `56453191` | `[Fix] (Espryt): stop calling a texture that was never glTexParameter-ed a malformed record - ParamsSerial 0 means no set_texture_params was ever applied, so there is no built-in sampler to push` |
The integrator fast-forwards `p4a/esprytobj3` (its parent IS `17396216`; no rebase, no cherry-pick,
no conflict — the ID-34 recipe was for the pre-integration replay and is spent).
---
## 2. N-1, N-2 and the seven minors
### N-1 — the refusal line said something it cannot know (`Managers.cpp:9244`)
The message and the block comment above it are rewritten. What the reorder actually buys is stated
instead: **the refusal itself has no driver effect** — the twin no longer mints and binds a driver
FBO as a side effect of declining — and the comment now names the two callers that bind anyway
(`SyncAndBindFramebufferObject` = `SyncToBackend` then an unconditional `Bind(target)`,
`DirectGLES.cpp:3292-3293`, the path all five DSA entry points take; and `BindCurrentFBO`, which binds
whether or not `SyncCurrentFBO` synced). New text:
```
MGPipe: framebuffer %u has no applier record on the handle arm, so it is not configured here;
nothing is bound by this refusal, but the caller's own bind still targets it (handle {%u, %u})
```
The common stem `no applier record on the handle arm` is preserved, so every grep written against
the family keeps matching. Package F's dependency-refusal matcher is unaffected (it matches the
`REFUSING the dependent bit` sentence, which did not change).
### N-2 — the census is EIGHT families, and it was run as eight
`esprytobj-v2.md` §4 named six; the review found two more. All eight, at HEAD:
| # | site (at HEAD) | sentence (stem) |
|---|---|---|
| 1 | `Managers.cpp:6381` | `texture %u … its storage and uploads cannot be driven from the pushed descriptor` |
| 2 | `Managers.cpp:7675` | `texture %u … its built-in sampler cannot be pushed` |
| 3 | `Managers.cpp:7906` | `texture %u … its parameters cannot be pushed` |
| 4 | `Managers.cpp:9021` | `framebuffer %u … its read buffer cannot be pushed` |
| 5 | `Managers.cpp:9244` | `framebuffer %u … it is not configured here` (N-1's new wording) |
| 6 | `Managers.cpp:12086` | `program %u has no shader-CSO applier record …` |
| 7 | `Managers.cpp:12354` | `sampler %u … its parameters cannot be pushed` |
| 8 | `Managers.cpp:12630` | `renderbuffer %u … its storage cannot be allocated from the pushed descriptor` |
Seven share the stem `no applier record on the handle arm`; `#6` needs its own pattern
(`no shader-CSO applier record`). §3.2 has the measured counts.
### The seven minors
| # | disposition |
|---|---|
| **N-3** `AdoptTwinByHandle`'s refusals unreachable | **Fixed by splitting the helper.** `PipeTwinHandleIsAdoptable(registry, handle, kindName)` (`Managers.cpp:3562`) now carries the two loud refusals and `AdoptTwinByHandle` (`:3588`) is `PipeTwinHandleIsAdoptable` + `GetOrCreateByHandle`. Both call sites (`SyncAttachmentSurface`, texture and renderbuffer arms) call the predicate **before** consulting the frontend, because the record's handle is the untrusted input and `HandleOf(frontendObject)` is the corroboration — v2 asked them the other way round, which made the slot bound and the backward-generation refusal unreachable by construction. Asking first is also side-effect free, which matters for the same reason N-1 does: `GetOrCreateByHandle` can reset an incumbent twin and a handle the predicate rejects must not reach it. |
| **N-4** the remint-pull marker on the *prevention* path | **Fixed.** `MGPipeUnmigratedEmulation("texture-remint-pull")` moved out of `RequireImageBindableStorage`'s prologue and into the level loop, behind a `markedRemintPull` latch so it is raised **once per transition, only when a level is actually owed** (`Managers.cpp:5302`, `:5327`). A mask-only respecify that arrives before any level is defined — exactly what `ImageBindableHint` exists to make happen — no longer counts (and, under P9, no longer aborts on) the emulation it prevents. Still one `MGPipeUnmigratedEmulation` occurrence in the file, so E's G13b census (`DirectGLES.cpp:4` + D's 1 = 5) is unchanged. |
| **N-5** raw `SrcOffset` | **Fixed, symmetrically with the strides.** `Managers.cpp:7103-7131`: every region's `SrcOffset` is compared against the number `rectShadowPtr` derives from its own origin and the level's two pitches; on disagreement the carried offsets are **dropped** (every use site falls back to the derived pointer, which is what the legacy arm sends) and one named `MGLOG_E_ONCE` says so. `MGB_RECT_SRC_PTR` consults the same `pendingOffsetsAgree`. The comment also **corrects v2's m-1**: there are three use sites and the FIRST is unreachable (`dirtyRectCount` is forced to 0 whenever `UnpackRingAvailable()`, and the staging loop requires `ringUsable && dirtyRectCount >= 2`); that shape is pre-existing, so the count is corrected rather than the loop deleted underneath it. |
| **N-6** the silent empty-surface arm | **Made loud.** `Managers.cpp:8763-8782`: `SyncAttachmentSurface`'s empty arm now refuses when the record says the point is empty and `!attachmentObject.IsEmpty()`. That was the one direction in which neither the frontend-decided detach nor the record-decided attach fired, and the caller then stamped the point's synced version with the previous owner's image still on the driver. Every other record-vs-frontend disagreement in that function was already loud. No false-positive risk: B's `MGPipeBuildSurface` returns the empty surface **only** when `attachment.IsEmpty()` (`FramebufferEmit.h:115-118`), i.e. exactly the case this refusal excludes — and it fired **zero** times across the whole lane (§3.2). |
| **N-7** high byte vs packed key | **Resolved in D's favour, with the reason, plus a cross-check.** `Managers.cpp:3800-3826` states it: D's question is per `(uploadTarget, level)` because that is the granularity its upload loop iterates and the only key its callers hold, while wire's `AccumulatePendingUpload` keys on the whole packed field because that is what arrived. Widening D's key would require its callers to invent a resource target; instead the low byte is **cross-checked** at all three match sites (find, consume, re-arm) against `record.Desc.Target`, which B fills from exactly the expression the sub-data's low byte comes from (`TextureEmit.h:223` / `:517` against `:1037`). A disagreement is one named line. This is also **`MGPResourceDesc::Target`'s first reader** in the package (v2 §2(6) recorded it as having none). It fired zero times. |
| **N-8** `HasDefinedContent` unread and unlisted | **Stated, with the argument, at `Managers.cpp:6298-6310`.** It is deliberately not read on the texture arm: a buffer's content is ONE fact about the resource (and the buffer family reads it three times), a texture's is per `(uploadTarget, level)` and its authority is the pending set, which survives a bail. A whole-resource "content is undefined" would say nothing the per-level loops do not already answer by finding no level to upload, and acting on it would mean throwing away levels the set still owes. It stays a respecify CLASSIFIER (it is storage-defining, so wire refuses to call such a respecify metadata-only) and nothing more on this arm. |
| **N-9** the G9 probe covers in-function deferral only | **Recorded in the case's own comment** (`SanityTest.cpp:3185-3191`): the probe drives `SyncTextureParamsToBackend` directly, so a regression that gates the CALL on a sampler view (in `SyncNeccessaryTextures`, or in E's per-unit walk) leaves it green; the caller-level half is F's G9 scenario. |
`MOBILEGL_ESPRYT_FBO_HANDLE_ARM_MEMOS_LINKED` (`Managers.h:2011`) **stays 0**: package E is not on
the integrated tree at all — `InvalidateFramebufferHandleArmMemos` does not exist in
`DirectGLES.cpp` at `17396216` (`grep`: zero hits). The flip is one line and belongs in the round
that follows E's integration; flipping it now does not link, which is the property the handshake was
designed to have.
---
## 3. THE FIRST REAL-PATH RUN
`ctest --test-dir build-push -L integration-gpu -j 8 --no-tests=error -R DirectGLES`, under
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0`, at HEAD.
| mask | result | note |
|---|---|---|
| **default `0x1fff`** | **485 / 491** | the six armless `.Handles` aborts, and nothing else |
| `0x1ff` | 485 / 491 | same six |
| `0` | 485 / 491 | same six |
| `0x3ff` | 485 / 491 | same six |
| `0x7ff` | **438 / 491** | the six + **47**: bit 10 set with bit 11 clear — §4.3 |
| `0xfff` | 485 / 491 | same six |
| DirectVulkan, default | **409 / 475** | **§4.2 — a phase-level defect, not D's** |
| DirectVulkan, `0x1ff` / `0x3ff` | 475 / 475 | |
| DirectVulkan, `0x5ff` | 409 / 475 | isolates the cause to bit 10 |
For reference, the same six masks on the **base** `17396216` (measured first, before any edit of
mine) were `483 / 485 / 485 / 485 / 438 / 483`: the default and `0xfff` arms each had **two extra
failures**, `SampledSetStalenessScenario.AQueuedClearIsMaterialisedWhenASamplerObjectCompletesTheTexture`
and `IntegerBorderColorScenario.SamplerParameterIivBorderColourSurvivesToAnIntegerSampler`. Those two
are seam defect **S-1** and are closed by `aec41e7d`.
### 3.1 Classification of every default-arm failure
**(a) six armless `.Handles` aborts — package F's, expected until F lands.** Identical set at every
mask, in `build-push` and `build-verify` alike:
```
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)
```
Now proved from the log rather than by mechanism: each aborts with exactly one
```
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"}
```
which is the ctest `ENVIRONMENT` pin `MGL_ITEST_HANDLES_ARM_KNOBS = "MOBILEGL_PIPE_LEGACY_MEMOS=0"
"MOBILEGL_PIPE_PUSH=0x1ff"` (`MG_IntegrationTest/CMakeLists.txt:949`) doing exactly what D-K3 says it
must. F's pin move `0x1ff → 0x1fff` at `:949, 1065, 1075, 1149, 1183, 1188, 1219` and
`0x80000000000001ff → 0x8000000000001fff` at `:1070, 1080` closes all six.
**(b) NAMED REFUSALS of the eight families — ZERO.** §3.2.
**(c) a wrong picture with no refusal — none on the DirectGLES lane.** One exists on the
DirectVulkan lane and it is §4.2.
**(d) anything else — none.**
### 3.2 The eight-family census, and how it was taken
The console log sink is compiled out of these builds, so ctest's captured output carries no `MGLOG`
lines at all (I checked: `grep -c 'MGPipe' LastTest.log` = 0 over 491 tests). The library opens
`MOBILEGL_LOG_FILE_PATH` with `fopen(path, "w")`, so a `-j 8` lane sharing one path clobbers itself.
The census therefore runs **one ctest invocation per test name, `-P 8`, each with its own log file**
(`~/w7/notes/tools/wsl_p4a_refusal_census.sh`, left durable — E's round, F's round and the final
review all owe this measurement).
Default arm, 491 names, **477 logs** (the 14 without one are ctest `ENVIRONMENT`-pinned scenario
variants — `CsoContentAddressing.{On,Off}`, `PointSizeDemotion.*`, `UnlocatedIoBlocks.*`,
`ResourceSubsystemControl.{On,Off}`, `MapPersistentRoundtrips.*` — whose own property replaces
`MOBILEGL_LOG_FILE_PATH`; all 14 pass in the lane).
```
[0 lines / 0 tests] texture ... its storage and uploads cannot be driven from the pushed descriptor
[0 lines / 0 tests] texture ... its built-in sampler cannot be pushed
[0 lines / 0 tests] texture ... its parameters cannot be pushed
[0 lines / 0 tests] framebuffer ... its read buffer cannot be pushed
[0 lines / 0 tests] framebuffer ... it is not configured here
[0 lines / 0 tests] program ... no shader-CSO applier record
[0 lines / 0 tests] sampler ... its parameters cannot be pushed
[0 lines / 0 tests] renderbuffer ... its storage cannot be allocated from the pushed descriptor
stem 'no applier record on the handle arm' : 0
stem 'no shader-CSO applier record' : 0
```
**Every `ERROR]: MGPipe` / `FATAL]: MGPipe` line in the entire 477-log corpus, deduped:**
```
6 FATAL]: MGPipe: Fatal{PipeLegacyMemosDisabled, ...} <- (a), F's pins
2 ERROR]: MGPipe: sampler N was synced without its unit's SamplerCso handle, so the
content-addressed record cannot be named and the object's own parameters
are used - the caller must pass MGPipeApplier().BoundSamplerStates[unit]
```
and nothing else. The 960 `FATAL]` lines the raw count reports are 477 × 2 ambient EGL
entry-point loads under llvmpipe (`eglSwapBuffersWithDamageEXT`, `eglUnlockSurfaceKHR`) plus those
six — the same ambient pair the re-review warned about.
The two remaining `ERROR` lines are **S-1's residual half**, which is package E's one-line call site
(§4.1) and is loud by design until E carries it.
**Counters, read off the same corpus:**
* `StaleFramebufferRecordLookups` — **0**. The counter is incremented only beside
`PipeApply.cpp:2258`'s `MGLOG_E_ONCE("MGPipe: the framebuffer record at slot %u is generation %u
and the lookup named generation %u…")`, and that sentence does not occur once. (Checklist item 3's
assertion, taken over 477 tests rather than one scenario.)
* `RefusedResourceCalls` / `RefusedObjectCalls` — the applier's refusal paths are all loud; none of
their sentences occurs. Wire's rule that `RefusedObjectCalls` stays 0 across every framebuffer call
holds.
* D's own new cross-checks (`Res` vs `HandleOf`, `PushedSurfaceTextureTarget`'s
`kMGPipeSurfaceNoTextureTarget`, the region stride and offset disagreements, the sub-data low-byte
mismatch, N-6's record-empty point) — **all zero**. Every one of them is a seam assertion that has
now been exercised against real records and stayed silent.
---
## 4. The seam defects
### 4.1 S-1 (FIXED here + one line owed by package E) — the sampler family could never find its record
**Evidence.** On the base, two scenarios failed and both logged
`MGPipe: sampler 1 has no applier record on the handle arm, so its parameters cannot be pushed
(handle {8, 0})` / `(handle {6, 0})`. `IntegerBorderColorScenario.SamplerParameterIivBorderColour…`
failed as `glSamplerParameterIiv component 3 returned 1065353216 instead of 3` — `0x3F800000`, i.e.
the FLOAT border colour: the driver sampler had never been programmed at all.
**The mismatch.** Reading side: `BackendSamplerObject::SyncToBackend` resolved the record with
`g_backendSamplerObjects.HandleOf(stateSamplerObject.get())` — the twin registry's own handle, minted
by `SlotTables.h:232` as `MGPipeSlots().Acquire(MGPipeKind::SamplerCso, stateObj->GetLifetimeId())`,
i.e. **identity-addressed**. Emitting side: C's cache allocates sampler CSOs **by content**,
`MGPipeSlots().Allocate(MGPipeKind::SamplerCso)` (`SamplerEmit.h:426`), and `create_sampler_state`
is only ever emitted at those handles. The two are different slots in the same kind band, so the
lookup could not hit — for any sampler object, ever. (`MGPipeEmitSamplerCsoCreate` exists in the
contract and in `PipeFill.cpp:1097` but has **no caller**: clientsp-v3 §8.7 declined the
constructor-time call site. Wiring it would not have helped, because `EmitSamplerCso` also acquires
from the content-addressed cache.) D's own comment three lines below the broken lookup already said
the record is content-addressed — the defect is that the handle did not follow.
**Fix, D's half (`aec41e7d`).** `SyncToBackend` takes the CSO handle from the caller:
```cpp
#if MOBILEGL_PIPE_PUSH
void SyncToBackend(const SharedPtr<MG_State::GLState::SamplerObject>& stateSamplerObject,
MG_Pipe::MGPipeHandle pushedCso = MG_Pipe::kMGPipeNullHandle);
#else
void SyncToBackend(const SharedPtr<MG_State::GLState::SamplerObject>& stateSamplerObject);
#endif
```
(push-only spelling: a defaulted parameter is still part of the signature, and widening it
unconditionally renames the symbol in the PULL build, whose admitted-change set is EMPTY.) With a
handle: resolve, serial-gate, refuse loudly if the record is missing — that is now a true seam
defect. Without one, two shapes, told apart by whether the object is in the twin registry:
* **not registered** → a sampler this backend minted for itself (`GetRawDepthFetchSampler`,
`DirectGLES.cpp:207-218`), which the client has never seen and for which no record can ever exist.
The object is the authority. Silent, permanent, correct.
* **registered** → an application sampler whose caller did not carry the handle: **one named line**,
and the object's own parameters are used, which in monolith are the very values the client
content-addressed — so the picture is right while the gap is visible rather than silent.
Both scenarios go green with that, and the census's two remaining `ERROR` lines are exactly this
named gap.
**The line package E owes (`DirectGLES.cpp:4021`).** Proved: applied in the tree, built, run,
**reverted** (`git status` clean, `git diff` against the base for that file is empty, rebuilt). With
it, both scenarios pass **and the sampler ERROR line disappears entirely** — the record path resolves
end to end. The call site is NOT inside a `#if MOBILEGL_PIPE_PUSH` block, so the patch needs the
guard:
```cpp
#if MOBILEGL_PIPE_PUSH
backendSampler->SyncToBackend(
samplerObject,
static_cast<SizeT>(unit) < MG_Pipe::MGPipeApplier().BoundSamplerStates.size()
? MG_Pipe::MGPipeApplier().BoundSamplerStates[static_cast<SizeT>(unit)]
: MG_Pipe::kMGPipeNullHandle);
#else
backendSampler->SyncToBackend(samplerObject);
#endif
```
`GetRawDepthFetchSampler`'s call at `:217` stays one-argument and must: it has no unit and no record.
### 4.2 S-2 (NOT D's — the integrator must rule) — bit 10 breaks the DirectVulkan backend
**Evidence, three independent measurements:**
| lane | default `0x1fff` | `0x3ff` | `0x5ff` (adds bit 10) |
|---|---|---|---|
| integration-gpu `-R DirectVulkan` | **409 / 475** | 475 / 475 | 409 / 475 |
| `integration-verify` (whole label) | 778 / 844, and **all 66 failures are `DirectVulkan.Verify.*`** | — | — |
| retrace (`retrace_gate.py`) | **39 / 79** — DirectGLES **39 / 39**, DirectVulkan **0 / 40** | `minecraft-1.21.4-main-menu.DirectVulkan` **PASSES**, ssim 0.997 | — |
The failing set is the texture-upload shape clientfb-v2's appendix lists (`SwizzleAccessRoutine`,
`CopyImage*`, `ImageTargetKind.Loads*`, `NonCoreImageFormat`, `FormatlessImageBake`,
`PackedWordReadback`, `FramebufferChurn`): the texels never reach the driver.
**Cause**, and it is exactly ID-35 §5's ruling extended one backend further. Bit 10's client half is
**destructive**: `DrainTextureSubData` clears the frontend per-level dirty flag as soon as the
applier accepts the record, so the texels live only in `MGPipeResourceRecord::PendingUploads`, which
only a P4a server-side consumer reads. D wrote that consumer for **DirectGLES only**;
`MG_Backend/DirectVulkan` still asks `IsStorageDirty()`, finds it clear and uploads nothing.
`MG_Config::Features.PipePush` is a process-wide config bit with no backend dimension, and
`FamilyIsLive` (`PipeFill.cpp:885`) is `(Features.PipePush & subsystem) != 0 && (wired & subsystem) != 0`
— it cannot ask which backend is running.
**The patch the owning packages need** (D cannot write it; `MG_Impl/Pipe` is B's and `MG_Pipe` is A's):
1. **Contract (A)** — a predicate on the same shape as the existing precedent
`MGPipeResourceOpsHaveSubDataResident()` (`PipeMutation.h:119`, already used by
`BufferObject.cpp:439/494` to decide exactly this kind of "may I stop keeping the host copy"
question): e.g. `Bool MGPipeTextureSubDataHasAServerConsumer()`, answered by something the backend
registers at bring-up.
2. **clientfb (B)** — gate the acceptance-driven `mipmap->MarkStorageDirty(uploadTarget, level, false)`
in `TextureEmit.h`'s `EmitOneLevel` on that predicate. Everything else about bit 10 stays; only the
destructive half becomes conditional. B's own §5 negative control already showed that removing
just that clear takes the default arm to 491/491.
3. **Interim, if the integrator prefers no contract change in P4a**: ship the default mask at
`0x3ff` (or run the DirectVulkan lane and the retrace at `0x3ff`) and record bit 10 as
DirectGLES-only for the phase. D-K2 should then carry the row explicitly: **bit 10 requires a
server-side texture consumer in the running backend**, which is a stronger statement than the
"bit 10 requires bit 11" row and is the only P4a bit that is not independently switchable.
This is the one thing on the tree that is a *wrong picture with no refusal* — DirectVulkan emits no
refusal because it has no P4a handle arm at all to refuse from.
### 4.3 S-3 (NOT D's) — D-K2's fourth row refuses server-side, but the client half is already spent
At `0x7ff` (bit 10 set, bit 11 clear) D's `ResolveTextureResourceSubsystemArm` refuses bit 10 and
falls back to the legacy arm exactly as ID-15 specifies — and the lane is **438 / 491**, the same 47
texture-upload failures. The refusal cannot restore a correct picture, because the CLIENT's emission
is gated on the operator's mask alone and has already cleared the frontend dirty flags by the time
the server declines. The same applies to F's `0x5ff` arm.
**Patch:** the client half of the fourth row. `FamilyIsLive(kMGPipeSubsystemTextureResources, …)` in
`MG_Impl/Pipe/PipeFill.cpp:885` (A's file, the contract owns the enum-coupled block) must also
require `kMGPipeSubsystemSamplers`, so that a mask with bit 10 and without bit 11 emits nothing
rather than emitting and being refused. D's server-side row stays as it is — it is the backstop, and
it is what stops the applier's `Fatal{ProtocolCorruption}` on a null `BuiltinSampler`.
**Note for package F:** its `0x5ff` scenario asserts the refusal *line* and the legacy arm running,
which is still true and still green in principle; but the surrounding lane at that mask is not, and
F's gates-review-v2 F-v2-m2 wording ("the 0x5ff arm goes GREEN") should be read as "the scenario",
not "the lane".
### 4.4 S-4 (FIXED here, mine) — `ParamsSerial == 0` was being read as a malformed record
Three cases logged `MGPipe: texture N's set_texture_params names the null handle as its built-in
sampler CSO; every texture owns a sampler object, so this record is malformed` — a ninth named
refusal shape, outside the eight:
`DepthStencilReadbackMatrixScenario.ReadbackLeavesNoGLStateBehind` (and its
`ForcedDepthStencilEmulation` variant) and
`UnboundImageDescriptorScenario.ABufferTextureWithNoAttachedBufferDoesNotLoseTheDraw`. All three
*passed*, so it was a decline with no visible consequence — and it was D's own misreading, not a
client defect: B never emits a null `BuiltinSampler` (`TextureEmit.h:618-626` drops the record
instead). The null was the value-initialised `MGPTextureParams` of a record for a texture the
application has **never given a parameter to**, so no `set_texture_params` had ever been applied.
`ParamsSerial` is the applier's own "have I ever stored one here". `56453191` reads it first and
declines silently in that state — which is the conclusion `SyncTextureParamsToBackend`'s own gate
already reaches (`m_syncedParamsSerial` starts at 0 too, so its compare skips).
---
## 5. The gate's "HandleRecycle (verify): 6 failed of 70", classified
```
ctest --test-dir build-verify -R HandleRecycle -> 64 / 70 (6 Subprocess aborted)
ctest --test-dir build-push -R HandleRecycle -> 50 / 56 (the SAME 6)
```
They are **the `.Handles` 0x1ff pins of §3.1(a), byte for byte the same six names**, not an ABA
defect and nothing verify-specific: the same six fail identically in `build-push`, at every mask, and
each dies of `Fatal{PipeLegacyMemosDisabled}`. The ABA controls the round added at v2
(`SanityTest.cpp` m-9: every one of the five kinds gets the "slot came back at a MOVED generation"
leg) are in `-L unit` and are **green in all three builds**. Nothing here is D's and nothing needs a
fix; package F's pin move closes all six.
---
## 6. Lanes, gates and every number, at HEAD `56453191`
```
builds build-linux rc 0, build-push rc 0, build-verify rc 0
G1 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 rc 0
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
27072 normalised names, 27072 unchanged
ctest -L unit build-push 100% passed, 0 failed out of 1761
ctest -L unit build-linux 100% passed, 0 failed out of 1761
ctest -L unit build-verify 100% passed, 0 failed out of 1761
G2 names pull == push 2727 == 2727, 0 diff lines (LC_ALL=C)
G14 vs ~/w7/p4a-before-ctest-names.txt 0 removed, +139 added (== ID-38's post-merge
number: this round adds no test names)
G5 scripts/p3a_untouched_regions.sh 37da3c3a HEAD rc 0
D-N scripts/p4a_untouched_regions.sh 37da3c3a HEAD (F's script, from ~/w7/p4a-gates) rc 0
791b54a35a19b58c82a5b9143cf48aa9ee815c755ecc1d4fa8dae709eeaa20bf StageBlocksIntoUnpackRing
1d6f15c983bbf7e26bcb6bdfdc0f9bd940367d928b35480717ef22a4f663ef12 UnpackRingAvailable
19e614afbed5c0af01517f5ad75926d42f60eae7e23385190989dd47d0132f4f UnpackRingAllocate
3ae7e3472c4a730d24549ee8b51b87eacf284dec1266b498cd5f3e056f787188 RecomputeBackendColorSlots
822ca3b0ece4e662f9b462945f2697f6b14547d841d926ae94c2b35139f16e53 DepthStencilSamplingReadImpl
266710e0fdc19756f31e27dcee536149c99fc9fe583752042135b3a9cde26366 ShouldUseCaveatTextureFormat
== esprytobj-v2.md §4 and esprytobj-review-v2.md §4, sha for sha
G13 grep -rc 'pGLContext' MobileGL/MG_Backend -> MG_Backend/MGPipe/PipeInputs.h:1 (one file)
MGPipeResourceOps block ∌ MG_State -> 0
MGB_* in any header -> no hits
integration-gpu -R DirectGLES (six masks) 485 / 485 / 485 / 485 / 438 / 485 of 491
integration-gpu -R DirectVulkan (default) 409 / 475 <- S-2
integration-verify -j 4, default, tcache_count=0 778 / 844, ZERO `Fatal{` lines
all 66 failures are DirectVulkan.Verify.* <- S-2
retrace, default (79 cases, -j 4) 39 / 79 = DirectGLES 39/39, DirectVulkan 0/40 <- S-2
retrace, 0x3ff, minecraft-1.21.4-main-menu.DirectVulkan PASS, ssim 0.997 (the A/B for S-2)
the DSA / named-framebuffer set (checklist item 3)
-R 'ClearThenReadPixels|Orientation|FramebufferChurn|DepthStencilReadback' 93 / 94
the one failure is DirectVulkan.FramebufferChurnScenario (S-2); DirectGLES 100%
-R 'FramebufferTest.NamedFramebuffer' 3 / 3
StaleFramebufferRecordLookups == 0 over the whole 477-log census
the image-bindable remint set (checklist item 5)
-R 'ImageLoadStoreSso|FormatlessImageBake|ImageSizeAfterRespec|ImageTargetKind|
SampledSetStaleness|TextureParamsWithoutASamplerView' 59 / 76
all 17 failures are DirectVulkan (S-2); DirectGLES 100%
the P4a family suites
-R 'DirectGLESTextureSync|DirectGLESSlotTable|TextureEmit|FramebufferEmit|SamplerEmit|
ImageEmit|ProgramEmit|ResourceEmit' 152 / 152
G9 white-box probe DirectGLESTextureSync.AnAttachmentOnlyTexturesParametersReachTheDriverWith
NoSamplerView push @ 0, @ 0x1ff, @ 0x1fff, and the pull build 4 / 4 PASSED
```
**ID-8's leak/death half on the DirectVulkan lane**: `integration-verify` ran under
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` with **zero `Fatal{` lines** in the ctest output and in
`LastTest.log`; the DirectVulkan failures are all S-2 pixel comparisons, none is a death-path,
exit-order or idempotence failure, and none aborts. At `0x3ff` the DirectVulkan lane is 475/475.
**G4's retain-mode texture-dirty-rect comparison (checklist item 9): it does not exist to run.**
`MG_Config::Features.PipeTexelRetainMb` is written by `ConfigLoader.cpp:278` from
`MOBILEGL_PIPE_TEXEL_RETAIN_MB` and has **no reader anywhere in the tree** (`grep -rn PipeTexelRetainMb`
→ the declaration and the loader, nothing else). So the consume-and-clear gate the review kept
carrying forward as "still has not run anywhere in this phase" cannot run in P4a as built. What the
verify lane DOES check is the field-by-field record comparison, and that is clean. This should be
recorded against G4 rather than carried again.
---
## 7. What the integrator must re-run, and what is owed
1. **Rule on S-2 (§4.2) before the push.** It is the only thing on the tree that renders wrongly, and
it renders wrongly on a whole backend. Cheapest interim = default mask `0x3ff`, or gate B's
dirty-flag clear on a backend predicate.
2. **S-3 (§4.3)**: the client half of D-K2's fourth row, in `PipeFill.cpp:885`. One condition.
3. **Package E owes one line** (§4.1, written out verbatim, guard included). After it lands the
census's last two `ERROR` lines go to zero. E also then drops the `static` on
`InvalidateFramebufferHandleArmMemos`, after which **one line in D's file**
(`Managers.h:2011`, `MOBILEGL_ESPRYT_FBO_HANDLE_ARM_MEMOS_LINKED` → 1) closes DV-13; that flip does
not link without E's half, which is the point.
4. **Package F**: the six itest pins `0x1ff → 0x1fff` (and the two `0x8000000000000...ff`), which is
the whole of the default arm's remaining 6/491. F's `ObjectSubsystemControl` scenario does not
exist on this tree yet, so the `0x5ff` / `0x9ff` dependency arms could not be run here; read F's
`0x5ff` expectation as "the scenario", not "the lane" (§4.3).
5. **Re-run after E and F land**: the six-mask DirectGLES lane, the eight-family census
(`~/w7/notes/tools/wsl_p4a_refusal_census.sh default`, ~4 minutes), `integration-verify`, and the
retrace. Only the retrace and the DirectVulkan lane are affected by S-2.
6. **Checklist items 6 and 7 of `esprytobj-v2.md` §5** are closed by measurement rather than by
inspection: the metadata respecify runs end to end on this tree (the image-bindable set is 100% on
DirectGLES, `TextureParamsWithoutASamplerViewScenario` included) and the storage-shape seam was
already closed by the re-review's own comparison of `TextureEmit.h:183-241` against
`Managers.cpp`'s `MGB_STORAGE_*`.
7. **Not re-derived here**: DV-9's preprocessed-line count (withdrawn at v2; the property that
matters, G1's 0/0/0/0 with `.text` +0, is measured above), the device A/B and the bench.
## 8. Deviations added by this round
| # | deviation | reason |
|---|---|---|
| **DV-16** | `BackendSamplerObject::SyncToBackend`'s second parameter exists only in the PUSH build (`#if`/`#else` on both the declaration and the definition) | a defaulted parameter is part of the signature, so an unconditional widening renames the symbol in the pull build and P4a's admitted-change set is EMPTY (D-P / G1). |
| **DV-17** | the twin falls back to the frontend object's parameters when no CSO handle is carried, LOUDLY for a registered sampler and silently for a backend-private one | §4.1. The silent arm is permanent and correct (`GetRawDepthFetchSampler`'s object is server-owned and can never have a record); the loud arm is the E-side gap and disappears with §4.1's one line. |
| **DV-18** | `MGPResourceDesc::Target` now has exactly one reader, and it is a cross-check rather than a decision | N-7. D still keys the pending-upload match on the upload half; the low byte is compared, never acted on. |
@@ -0,0 +1,444 @@
# P4a seam audit (fable research agent), 2026-09-08
**Tree audited:** `~/w7/pipe` = `feat/disaggregated` @ **`41b79050`** (E's verification round landed: the
S-1 call-site line + SD-0's `Tracker.h` bind-generation mix), i.e. c0..c0g + wire + B + C + D + E. Read-only;
no tree was edited. Runs: the Iris retrace set on `41b79050`, on E's pre-landing lib `2e03b82a` (D's
landing without E's last commit), and a three-point bisect of D's landing commits in a private worktree
`~/w7/fable-bisect` (results in §B). Retrace outputs under `~/w7/retrace-out/fable-*`.
**Method of the sweeps (§A):** the P4a record catalogue (`PipeCalls.def`, `PipeFields.def`, `MGPipeTypes.h`)
was walked field by field against (i) the emitter that fills the field (`MG_Impl/Pipe/*Emit.h`), (ii) the
dirty bit / birth hook that triggers the emitter (`PipeFill.cpp:2457-2517`, `Tracker.h:283-524`), (iii) the
frontend setter that changes the field's source (`grep` over `MG_State` for every `MGP_NOTE_AGGREGATE`,
`Bump*Generation`, `NoteUnitTouched`, `++m_*Version` site; `DirtySurface.def` rows), and (iv) every server
reader of the field (`grep 'st\.\|MGPipeApplier()' DirectGLES.cpp`; `grep 'surface\.\|pushedRecord->\|record->'
Managers.cpp`). Handle minting was checked per kind on both sides (`MGPipeSlots().Acquire/Allocate/AllocateFor`
vs `TwinRegistry`/`BackendSlotTable::Acquire`, `SlotTables.h:232`). Every client-side clear/evict/release was
listed with its consumer guarantee, every process singleton in `MG_Impl/Pipe` with its per-context state,
every serial with the memo that reads it. The retrace's MobileGL log (`<case>/DirectGLES/output/mobilegl.log`,
the file sink - `ctest -V`/stdout is a false zero, E §6.0) was censused for refusal and seam lines on every run.
---
## 0. Verdict in brief
* **Proven remaining seams: 4 that need a fix before P4a closes (F-1, F-2, F-3, F-4), 3 recorded (F-5,
F-6, F-7).** All four are instances of the classes the seven contract fixes already hit - three of them
class 6 (a setter that changes a record field moves no shutter the emitter reads) and one class 2 (an
identity-keyed twin table looked up by a content-addressed handle, S-1's twin one loop over). None
produces a wrong picture on the current itest/retrace corpus, which is exactly why they survived; each has
a public-GL sequence that does, and none of the 80 scenarios or 79 traces contains that sequence.
* **Iris (17 shader-pack retrace failures at ee31944b): S-1, the D half, and they were NOT silent.** A
three-point bisect of D's landing reproduces E's 17 exactly at `ee31944b` and at `a632e26e` (3/20, the
same SSIMs to six decimals) and goes 20/20 at **`1e8cdc59`** (S-1's server half); `588b2277` (S-4) and E's
`41b79050` line are not needed. The path is the **raw-depth-fetch sampler** (`DirectGLES.cpp:207-278`): a
backend-minted `SamplerObject` that no client ever describes, which v2's `SyncToBackend` looked up by its
identity handle and refused - every failing trace's `mobilegl.log` carries `MGPipe: sampler N has no
applier record on the handle arm, so its parameters cannot be pushed` (17 of 17; the three passing
controls carry none) - so its NEAREST/no-compare parameters never reached the driver sampler bound over
every `sampler2D` depth read, which is what a shader pack does all frame. E §7's "zero named refusals
and zero seam lines" was asserted from the itest census; the retrace census was never taken (the trace
harness writes `output/mobilegl.log`, not `retrace.log`). On `41b79050` and on `2e03b82a` all 20 pass
with zero refusal/seam lines. c0g is inert at `0x1fff`.
* **Why the brief missed them:** D-K4's sentence "the shutters are already computed, latched and counted
today - P4a only emits for them" is the root of c0d, SD-0, F-1, F-2 and F-3 alike: the P2/P3a shutters
were built for value-class blocks and coarse aggregates, and the P4a records carry *derived* fields
(program-resolved unit sets, per-program windows, inlined attachment formats) that no existing shutter
covers and that `DirtySurface.def` cannot see (it maps mutators to bits, never record fields to
mutators). The brief never tabulated record field -> source setter -> shutter, never tabulated the
handle rule per kind on BOTH sides (D-F1 content vs D-I1's per-object death row vs D's identity twin
registries), and stated the dependency/mirror rules as facts about masks rather than about emissions.
---
## A. The sweeps, class by class
Confidence scale: **proven** = code-proven on both sides and refuted every alternative I tried;
**mechanism** = code-proven chain, not yet demonstrated by a run; **latent** = correct today only because
the reader is absent or reads the frontend.
### A.1 Class 1 - an encoding stated nowhere (c0c's class)
Mechanism: every `Uint8/Uint16/Int8` field of the P4a payloads in `MGPipeTypes.h` (grep'd: 31 such
fields) classified as (a) spelled by a `kMGPipe*` constant in the contract, (b) a `static_cast` of one
frontend enum used identically by both sides, (c) an encoding invented in a package header.
| field | where the encoding lives | reader | status |
|---|---|---|---|
| `MGPSubData::Target`, `MGPSurface::Kind`, `DepthStencilMode`, `MGPSurface::TextureTarget` (0xFFFF), `MGPipeFramebufferTarget` | contract (c0c/c0e) | D/E | closed |
| **`MGPImageView::Access`** | `ImageEmit.h:146-159` only (`MGPipeEncodeImageAccess`, 0/1/2); `MGPipeTypes.h:797` has no constant | **none** - E reads the frontend's `imageBinding.Access` on purpose (`DirectGLES.cpp:2492-2500`: "reading it here before that encoding is written down would be inventing it") | **F-6a, latent** |
| `MGPSamplerView::Target` (`Uint8`, `MGPipeTypes.h:441`) | `SamplerEmit.h:900` `static_cast<Uint8>(texture.GetTarget())`, no comment in the contract | D's sampler-view twin (no field decode found) | F-6b, latent (same enum both sides) |
| `MGPFramebufferState::DrawBuffers[8]` (`Int8`, -1 = None, four default-FB tokens -> 0) | `FramebufferEmit.h:146-163` (B's narrowing) | **none** - D's mask loop indexes the record's surfaces by the FRONTEND token `stateDrawBuffers[i]` (`Managers.cpp:9322-9330`), never by `DrawBuffers[]` | F-6c, latent |
| `MGPSurface::UploadTarget` empty-point spelling | `FramebufferEmit.h:102-113` (B's m6: `TextureUploadTarget::Unknown`) | D's `SyncAttachmentSurface` | latent, consistent by shared enum |
| `MGPResourceDesc::StorageKind`, `Swizzle[4]`, `MGPImageView::InternalFormat`, `BindMask` | shared enum casts / contract constants | D | fine |
**F-6 (latent, low):** three encodings are written in a package header rather than the contract and have
no server reader today. Each is the c0c shape one reader away: the first server that decodes `Access`
will write its own table. The fix is documentation-only now (`MGPipeTypes.h` constants for `Access`, a
comment on `MGPSamplerView::Target` and on the `DrawBuffers` narrowing).
### A.2 Class 2 - a handle minted by IDENTITY on one side and by CONTENT on the other (ID-14/17, S-1)
Mechanism: per kind, the client mint (`MGPipeSlots().AllocateFor(kind, lifetimeId)` = identity;
`Allocate(kind)` with no lifetime id = content) against every server lookup of a handle of that kind.
| kind | client | server lookup | status |
|---|---|---|---|
| Texture, Renderbuffer, Framebuffer, SamplerViewCso, ShaderCso (+ composite band) | identity (`TextureEmit.h:616`, `SamplerEmit.h:881`, `FramebufferEmit.h:256`, `ProgramEmit.h:406-419`) | `TwinRegistry`/`BackendSlotTable` identity (`SlotTables.h:232`), records by handle | consistent |
| SamplerCso (built-in sampler in `MGPTextureParams`) | **content** (`SamplerEmit.h:426`) | record by the carried handle (`Managers.cpp:7710`) | fixed (ID-14/17, S-4) |
| SamplerCso (`BoundSamplerStates[unit]`) in `BackendSamplerObject::SyncToBackend` | content | record by the handle the caller carries (`Managers.cpp:12352`) | fixed (S-1 + E's `41b79050` line) |
| the raw-depth-fetch sampler (`DirectGLES.cpp:207-278`, a backend-minted `SamplerObject`, never described by any client) | **no record can exist** | v2: identity `HandleOf(object)` -> "no applier record" refusal on every depth read; `1e8cdc59`: unregistered -> the object is the authority (`Managers.cpp:12361-12372`) | fixed by `1e8cdc59` - **this is the Iris failure (§B)** |
| **SamplerCso in `BindCurrentUnitSamplers`' record arm** | content | **`g_backendSamplerObjects.FindByHandle(sampler)` (`DirectGLES.cpp:4847`)** - a registry keyed by the SamplerObject's lifetime id (`Managers.cpp:12546`, `Managers.h:2533`) | **F-4, proven** |
**F-4 (class 2, proven, latent today).** `st.BoundSamplerStates[index]` is a content-addressed CSO handle
(allocated by the cache with no lifetime id); `g_backendSamplerObjects` mints its slots off
`SamplerObject::GetLifetimeId()`. One allocator, two disjoint slot families: the lookup can never find a
twin, so the S4 branch ("a live handle whose twin does not exist yet is left alone") is taken on **every**
draw for every bound sampler, and E's rationale for S4 - "the program pass creates the twin later in the
same draw" - is wrong: the twin the program pass creates (`DirectGLES.cpp:5296-5311`,
`GetOrCreate(samplerObject)`) sits at the *identity* slot and will never sit at the CSO slot. The record
arm's only live effect is the unbind of null/out-of-window units; every sampler-object bind on the handle
arm is still performed by the pre-handle program pass. This is S-1's confusion one loop over, and
`SamplerEmit.h:201-205` already states the rule D's registry violates ("a backend must NOT key a sampler
twin on a SamplerObject's lifetime id; the twin's life is create_sampler_state -> delete_sampler_state").
*Consequence today:* none visible (the program pass binds). *Failure scenario:* the moment the program pass'
sampler bind is memoised away or retired (P3b/P4b's "175-line debounce removal" names exactly that region),
every `glBindSampler` stops reaching the driver with no refusal. *Lane:* none can see it; a white-box case
("after BindCurrentUnitSamplers' record arm, unit N's driver sampler == the CSO's twin, walkedFromRecords
bound > 0") is red today. *Fix (D):* key the sampler twin table by CSO handle (create the twin at
`create_sampler_state` / on first lookup by handle), and correct E's S4 comment.
### A.3 Class 3 - a record keyed by BINDING while consumers address by OBJECT (ID-19's class)
Mechanism: every applier table vs every reader's key. Framebuffer: per object + two bound handles (wire v3),
DSA readers by handle (`Managers.cpp:8964-8971`) - closed. The three unit sets: keyed by unit, consumed by
unit (`DirectGLES.cpp:2447-2455`, `4831-4835`) - consistent. `set_texture_params`: per texture. Program:
per CSO. **No new instance.** One monolith-only note: D's mask loop reads the *frontend* draw-buffer tokens
to address the record's surfaces (F-6c) - a binding-side input over an object-keyed record; harmless while
the frontend is in-process.
### A.4 Class 4 - a process-wide singleton keyed by a per-context name (C2-M1's class)
Mechanism: every `*Instance()` in `MG_Impl/Pipe` (10: Tracker, CsoCache, SamplerCsoCache,
ProgramOpaqueUnitsShared, SetHashSuppressor, five emitters, CompositeResolver, ResourceTracker) vs the
per-context state it holds and what `FreshlyPrimed` resets (`PipeFill.cpp:2414-2440`).
* Tracker: context pointer check + `Reset()`; SetHashSuppressor: `InvalidateAll()`; the five emitters:
bound-latch halves only (`SamplerEmit.h:1015-1022` releases the bound-set refs, `ImageEmit.h:133` window,
`FramebufferEmit.h:404-414` incl. the Named latch, `ProgramEmit.h:363-372`); CompositeResolver keyed on
`(GetTextureContextId(), pipeline name)` (`ProgramEmit.h:118-126`, C v3) - all correct.
* `MGPipeProgramOpaqueUnits` memo keyed on `(lifetimeId, linkVersion, backendStateVersion)` - lifetime ids
are process-unique; fine.
* The texture drain list `m_drain` is process-wide, not "per-context" as D-D4 says; it is keyed on
handles of share-group objects and the applier is one per process, so it is correct in monolith and is
a P5 item (one drain per client context).
* `FramebufferRecords` survive a make-current although an FBO is per-context (`PipeApply.h:485`); keyed by
process-unique handles, so two contexts' FBOs cannot collide. Fine.
**No new instance.**
### A.5 Class 5 - a destructive client-side change with no consumer/dependency guarantee (c0f/c0g, ID-17)
Mechanism: every client-side clear/evict/release/latch and what guarantees a consumer: (1) the level dirty
clear `MarkStorageDirty(false)` (`TextureEmit.h:1097`) - gated on acceptance AND on
`FamilyIsLive` = bit + wired + consumer + D-K2 deps (`PipeFill.cpp:1064-1069`, `2470-2475`); (2) sampler CSO
LRU eviction - reference-counted (ID-17); (3) composite release - through the one helper; (4) the drain
list clear - only for accepted levels; (5) `DrainKeys` rebuild; (6) the bound-set reference release on
Reset; (7) every emitter latch.
* **F-7 (class 5/7, minor):** `EmitTextureParams` sets its version latch (`TextureEmit.h:637-643`) BEFORE
`MGPipeApplySetTextureParams` (void; refuses when the texture has no record or a null
`BuiltinSampler`, `PipeApply.cpp` set_texture_params:14/22). A texture born in the
register/unregister window (no create, `PipeFill.cpp` c0f note) that receives `glTexParameter*` before
any respecify has its params refused and latched; the later self-healing create republishes the
resource but not the params, so `ParamsSerial` stays 0 and the built-in sampler is never pushed (the S-4
path, `Managers.cpp:7690-7696`) - the driver keeps its defaults against the application's filters.
Narrow (needs the teardown window); the fix is to latch only on acceptance (the D-D5 rule applied to
params) - the same shape as wire's n2 for framebuffer records (`FramebufferEmit.h:311-318` latches after a
void `Emit`). The kVarTail sets are moot: `ApplyUnitWindow`'s only refusals are Fatal.
* **F-5 (recorded = E's SD-5, still open):** both sides express D-K2 against the *bit*, non-transitively
(`PipeFill.cpp` c0g: "IT IS THE RUNTIME BIT THAT IS TESTED, NOT THE OTHER FAMILY'S LIVENESS";
`Managers.cpp:3598-3610`). At `0x7ff` the framebuffer family is live on both sides while the texture
family refuses itself; the surfaces name texture handles that never get twins and D's adoption refusal
makes E's F4 decline the whole arm - loud, correct picture, a lane that reports 53 fails to whoever
sweeps masks. Not a shipped mask. The brief rule: a family's dependency is the *resolved liveness* of the
family it depends on (transitive closure), stated once and mirrored.
* The structural residue that stays after c0f/c0g: the client's gate is *family*-level, the server's
declines are *per object* (no record / stale generation -> legacy read of a dirty flag the client has
cleared). Zero such declines on the itest census (ID-41) and on the 40 retrace logs I censused, so no
reachable instance; it is the rule a P4b brief must state (a per-object server decline may never fall
back to a flag the client owns).
### A.6 Class 6 - a tracker shutter that does not move on a change that alters a record field (c0d, SD-0)
Mechanism: the record field -> source setter -> shutter table, built for every P4a emission and checked
against the bump sites (`o`-grep: `MGP_NOTE_AGGREGATE(TextureContent|TextureParams|FramebufferAttachment)`,
`NoteUnitTouched`, `BumpSamplingResolutionGeneration`, `++m_imageUnitVersion`, `UseProgram`).
| emission (bit) | shutter (`Tracker.h`) | record inputs NOT in the shutter | finding |
|---|---|---|---|
| `set_framebuffer_state` (11) | attachment aggregate ⊕ draw bind ⊕ read bind (:487-493) | **the attachments' `InternalFormat`/`TextureTarget`/`Width`/`Height`/`Samples`/`Complete`** (`FramebufferEmit.h:115-144, 589-617`) - a texture or renderbuffer *respecify* moves `TextureContent`/`TextureParams` (`TextureObject.cpp:178-184`, `:410-412`) or nothing (renderbuffers, D-D2), never `FramebufferAttachment` | **F-3** |
| `set_sampler_views` (12) | textureContent ⊕ textureBind (:494-495) | **the current program** (`SamplerEmit.h:742-767`: `GetProgramForDraw()` -> `SamplerTarget[unit]`), the sampler uniform's unit (`glUniform1i`, bit 7), the effective sampler's parameters and the texture's (`SamplesAsIncompleteTexture`, textureParams/sampling generation - bit 13's inputs) | **F-1** |
| `bind_sampler_states` (13) | textureParams ⊕ samplingResolution ⊕ textureBind (:515-517) | none (program-independent walk; `glDeleteSamplers` bumps via `TextureUnit.cpp:39`) | ok |
| `set_shader_images` (14) | textureContent ⊕ textureParams ⊕ **`program->GetImageUnitVersion()`** ⊕ textureBind (:518-520) | **the program's identity**: the plain-program arm mixes a per-program counter that is equal for two programs with the same number of image-unit assignments (`ProgramObject.h:826-848`); the pipeline arm mixes `stageLinks` (:420), the plain arm does not | **F-2** |
| `create/bind_shader_state`, `set_draw/dispatch_program` (6/7) | lifetime ⊕ link (:353); bindings without identity (:354-358) but the emitter runs on 6\|7 | ok |
| `set_global_constants` (8) | lifetime ⊕ UBO content (:359) | ok |
| `set_texture_params` (hook) | version-first latch on (params, sampler) versions + ForceResync (`TextureEmit.h:635-643`) | ok |
| `resource_respecify` / renderbuffer | emitted from the storage entry points (`PipePublishDescriptor`) | ok |
**F-1 (class 6, proven shutter gap; wrong picture deferred to the first server reader).**
`EmitSamplerViews` resolves the set for *the program bound at the validate point* and is called only when
bit 12 fires (`PipeFill.cpp:2477`); `EmitShaderState` neither invalidates the `SetSamplerViews` suppressor
slot nor calls the sampler emitter (`ProgramEmit.h:105-158`). `glUseProgram` moves nothing bit 12 reads
(`Core.cpp:393-395` -> `m_programState`; no `BumpTextureBindGeneration` on that path). Sequence:
`glBindTexture` x N; `glUseProgram(P1)`; draw; `glUseProgram(P2)` where P2 samples a unit/target P1 did not
(or `glUniform1i(sampler, otherUnit)`); draw -> `BoundSamplerViews` still describes P1's set. Same for a
`glTexParameteri(MIN_FILTER)` that flips `SamplesAsIncompleteTexture` (bit 13 fires, bit 12 does not) - the
entry stays null. *Reader today:* only E's epoch (`DirectGLES.cpp:1835-1871`); no code on either side reads
a `BoundSamplerViews` entry (`grep BoundSamplerViews` over `MG_Backend`: none). So the record is
write-only in P4a and the gap is invisible to every lane; the first server that binds from the set
(P3b/P4b's debounce removal, P7's Magma views) renders the previous program's units. *Fix (A,
`Tracker.h:494`):* mix the same program identity the emitter's memo is keyed on (`GetCurrentProgram()`'s
lifetime id ⊕ link version ⊕ backendStateVersion, or `stageLinks` under a pipeline) and `textureParams`
into bit 12 - the c0d/SD-0 shape; the suppressor absorbs the extra fires. Unit case: "a program switch
alone re-emits the view set" (red today on `SamplerEmitTest`/`TrackerTest`).
**F-1b (class 7, mechanism-proven, narrow, wrong picture with no refusal).** E's e2 replaced the
program-independent per-slot walk epoch (`UnitBindingsUnchanged`, every binding slot + sampler of every
touched unit) with the two record serials (`DirectGLES.cpp:1868-1871`) and keys the program-independent
`g_unitTextureSyncList` on it (`:2148-2200`). The serials move only when the *program-resolved* set's hash
moved. A `glBindTexture(target, T)` onto a slot that was EMPTY (no entry for `PairingsIntact` to compare)
on an already-touched unit (`Count` unchanged) while the current program does not sample that unit/target
moves neither serial; a following `glUseProgram(P2)` that samples it fires no bit 12 (F-1); the list is
never rebuilt, T is never `SyncTextureObjectToBackend`'d, and `ResolveAndBindUnitTextures` finds no twin
(`DirectGLES.cpp` ~4630 `Find()` null -> `fullyResolved=false; continue`) and then *clears* the native
target -> P2 samples an unbound unit, no refusal, and `fullyResolved=false` cannot self-heal because the
list memo still hits. Rescued only by a `maxTouched` move, any `glTexParameter*` anywhere
(`samplingGeneration` in the key) or a replacement on a populated slot. *Lane:* none
(`SampledSetStalenessScenario` binds before it switches). *Fix:* E's key should mix the frontend
`GetTextureBindGeneration()` (one accessor read; over-fires only on binds) beside the serials, or the serial
must move on the F-1 fix plus a bind-generation input - the record epoch is a *narrower* shutter than the
walk it replaced, which is the direction `Tracker.h:42-48` forbids.
**F-2 (class 6, proven, degrades loudly-ish).** Plain-program arm: `programImages =
program->GetImageUnitVersion()` (`Tracker.h:360`) - a per-program counter incremented only in
`SetUniformSamplerOrImageUnitIndex` for image uniforms (`ProgramObject.h:846-848`); two programs commonly
carry equal values, so a `glUseProgram` between them (no bind/content/params change) fires no bit 14 and
`set_shader_images`' window stays the previous program's (`ImageEmit.h:82-87`). E's I3 then takes the
pre-handle bind for the units outside the window (MAJOR-1's union, silent by E's table) - correct picture,
a permanent silent fallback, exactly A8's "the image half is permanent". *Fix (A, one line):* mix the
program's lifetime id into `programImages` in the plain arm, as the pipeline arm already mixes
`stageLinks` (`Tracker.h:420`).
**F-3 (class 6, proven divergence between the two arms, uncaught by any lane).** The framebuffer record
inlines each attachment's `InternalFormat` (and `TextureTarget`, extent, samples, `Complete`) at emission -
D-C1's "inline, so the four cross-object masks fall out at push time with no lookup". Nothing bit 11 reads
moves when an *attached* texture is respecified: `TextureObjectBase::SetInternalFormat` bumps
`TextureParams` + shape (`TextureObject.cpp:178-184`), `AllocateStorage`/`BumpContentVersion` bump
`TextureContent` (`:410-412`); no path notifies a framebuffer (`grep FramebufferAttachment|BumpAttachmentVersion
TextureObject*.cpp`: none); a renderbuffer re-storage bumps nothing (D-D2 closed only the *resource*
record). On the server the four masks are answered from the stale surface on the handle arm
(`Managers.cpp:8678-8723`, consumed at `:9328-9353`) while the legacy arm reads the frontend attachment at
the same sync (`:9356-9372`). Both arms DO re-run `SyncToBackend` after the respecify - the re-mint bumps
`g_attachmentBackendIdGeneration`, which both memos carry (`DirectGLES.cpp:2852-2857`, the pre-handle
quartet) - so the legacy arm comes out fresh and the handle arm frozen. Sequence (public GL, both arms
otherwise identical): `glTexImage2D(tex, RGB8)`; `glFramebufferTexture2D(fbo, tex)`; draw;
`glTexImage2D(tex, RGBA8, same size)` (no re-attach); draw; `glReadPixels` -> alpha-widened mask still set:
`IsAlphaWidenedFallbackReadAttachment` forces opaque alpha on the handle arm and not on the legacy arm
(`DirectGLES.cpp:10865`); the mirror (RGBA8 -> RGB8) reads the driver's widened alpha instead of 1.0. The
same for `RGBA8 -> RGBA8_SNORM` (clamp mask, `:11084/11705`) on caveat drivers and for
`glRenderbufferStorage(newFormat)` on an attached renderbuffer. `Width/Height/Layers/Samples/Complete` have
no reader (grep) and only go stale. *Lane:* none - `SnormAttachment`, `ThreeChannelAttachment`,
`RenderbufferBlendFormat` all storage-then-attach; `ImageSizeAfterRespec` respecifies an image texture, not
an attachment. *Fix:* either (D) answer the four masks from the *resource* record's `Desc.InternalFormat`
(`TextureResources[surface.Res.Slot]`, which `resource_respecify` keeps fresh) instead of the inlined copy -
an applier-internal lookup, no frontend - or (A) mix the texture aggregates into bit 11, which fires the
304-byte hash on every texture upload. The first is the right one: the inlining "so no lookup is needed"
is the seam. One scenario pins it (respecify-while-attached, both directions, readback alpha).
Refuted along the way: `SetReadBuffer`/`SetDrawBuffer`/default-size setters all bump the attachment
aggregate (`FramebufferObject.cpp:205-241`); `glDeleteTextures`/`glDeleteSamplers` bump the bind generation
(`TextureState.cpp:142`, `TextureUnit.cpp:39`); `glBindImageTexture` reaches `NoteTextureUnitTouched`
(`GL_Texture.cpp:6742`); `glBindSampler` too (`GL_Sampler.cpp:370`); `DirtySurface.def`'s
`BindProgramPipelineObject = kPulledEveryVerb` prose predates c0d (the shutter now reads the pipeline) but
the pull still holds on every path - stale reasoning, not a defect.
### A.7 Class 7 - a serial that is not an "emitted" test; memo keys too coarse (E §0, ID-27)
Mechanism: every `Serial` in `PipeApply.h` vs every memo in `DirectGLES.cpp`/`Managers.cpp` that reads it.
`FramebufferSerial` (one per family, advanced on Reset; E's memo adds backend-id and context generations -
correct, coarse = recorded perf item); `ParamsSerial` 0 = never applied (S-4, correct now);
`SamplerCso.Serial` + handle as the key (`Managers.cpp:7720-7731` - the handle is in the key because
content addressing can re-point a texture at a CSO with a smaller serial: correct);
`SamplerViews/SamplerStatesSerial` as E's epoch (**F-1b**: moves less often than the walk it replaced);
`ShaderImagesSerial` (not used as a memo). **F-1b is the one new instance.**
### A.8 Class 8 - a clear that is too wide (wire C1)
`PendingUploads` erase per `(uploadTarget, level)` with the cube face in the key (wire v3 + F's case);
`MGPipeApplierReset` clears working state only; `ReleaseObjectRecords` clears all (teardown);
`SamplerEmitter::Reset` releases the bound-set refs only; `FramebufferEmitter::Reset` drops the Named latch
(over-fire, argued). **No new instance.**
### A.9 Class 9/10 - gates that cannot go red; name sets
G7 trips and exits 0 on the integrated tree (gates-v3 §5); G9 is white-box; G2 2846 == 2846. Two gates that
still cannot go red: (i) E's S4/"walkedFromRecords" arm is counted as engaged while it binds nothing (F-4)
- the MINOR-4 gate tick measures an arm that does no work; (ii) E §6.6's "unit-list equivalence between
0x1ff and 0x1fff" was argued from failing sets, and the per-frame rebuild count is not instrumented - F-1b
lives exactly there. The retrace-time refusal census that E §7 asserted ("zero named refusals") was never
taken on trace runs (the trace harness writes `output/mobilegl.log`; `retrace.log` has no MobileGL lines);
I took it: zero on 40 runs (§B).
---
## B. The seventeen Iris retrace failures
Reference: E v3 §7 - 62/79 at the default mask on `ee31944b` without E, 17 failures, 15 Iris packs +
`improved-transparency-26.3` + `1.21.11-main-menu`, SSIM 0.61-0.99.
**Run 1 - current head `41b79050`** (pipe's `build-push`, stamp `GIT@41b7905`; E landed incl. the S-1
line and SD-0): `retrace_gate.py --only '(iris|improved-transparency|main-menu).*DirectGLES'` = 20 cases
(the 17 + `1.17-main-menu-854`, `1.21.4-main-menu`, `iris-mellow`): **20/20 PASS**, SSIM 0.9935-1.0
(`~/w7/retrace-out/fable-audit/`). Log census over the 20 `mobilegl.log`s: **0** lines matching any of the
ten refusal shapes, the three E seam stems or `Fatal{`; the only ERROR/WARN lines are the pre-existing
`NormalizePixelFormat GL_STENCIL_INDEX8` pair, the capability-query and stub warnings and the residual
`SetVertexAttribDefaults` note.
**Run 2 - control `2e03b82a`** (E's branch head before `41b79050`: D's landing `a632e26e`/`1e8cdc59`/
`588b2277` + c0g present, E's S-1 call-site line and SD-0 patch ABSENT; lib `~/w7/p4a-esprytdraw/build-push`,
stamp `GIT@2e03b82`): **20/20 PASS**, SSIMs identical to run 1 to six decimals. Census: identical, and in
particular **zero** occurrences of D's S-1 fallback line for a *registered* sampler (`"sampler N was
synced without its unit's SamplerCso handle"`, `Managers.cpp:12379-12385`) - so no application
`glBindSampler` sampler is synced in these 20 traces, and E's call-site line (`41b79050`) is not what fixed
them. SD-0 is likewise excluded (present in run 1 only; E measured it as `create-indirect` alone). c0g
changes nothing at `0x1fff` (every dependency set; the `TextureScope` fixture edits are test-only).
**So the 17 were fixed by D's landing on `ee31944b`, i.e. by one of `a632e26e` (nine re-review minors),
`1e8cdc59` (S-1's server half) or `588b2277` (S-4).** S-4 cannot change a picture by mechanism: the
pre-fix path returned without pushing the built-in sampler for a texture that was never `glTexParameter`'d,
and `SamplerParameters`' defaults are GL's (`MGPipeValueTypes.h:462-486`: NEAREST_MIPMAP_LINEAR/LINEAR/
REPEAT/LEQUAL/None), so "no push" and "push defaults" are the same driver state; D's own report calls
it a decline with no visible consequence. `a632e26e`'s picture-relevant hunks (N-5 `SrcOffset`
cross-check, N-6 record-empty point) fire on no run. The bisect below settles it.
**Bisect** (private worktree `~/w7/fable-bisect`, same configure line as `wsl_tree.sh`, `build-push`, fixtures
copied from pipe with `--assume-unchanged`, the same 20 cases; log `~/w7/fable-bisect.log`, outputs
`~/w7/retrace-out/fable-bisect-<rev>/`):
| rev | content | result (20 cases) | `mobilegl.log` census |
|---|---|---|---|
| `ee31944b` | E's base (before D's landing) | **3/20 - the 17 fail, SSIMs identical to E §7 to six decimals** (0.610443849 super-duper-vanilla ... 0.994435418 improved-transparency) | 17 x `MGPipe: sampler N has no applier record on the handle arm, so its parameters cannot be pushed (handle {N, N})` + 17 x the S-4 line; every failing case carries the sampler refusal, the three passing controls carry none |
| `a632e26e` | + nine re-review minors | **3/20, identical** | identical |
| `1e8cdc59` | + S-1 (server half: the record is taken from the handle the caller carries; an unregistered, backend-minted sampler is its own authority) | **20/20** | the sampler refusal is gone |
**Narrative.** The 17 are **S-1**, through a path nobody named: `GetRawDepthFetchSampler()`
(`DirectGLES.cpp:207-278`) constructs a frontend `SamplerObject` inside the backend (NEAREST/NEAREST/no
mips/compare None) and syncs it through `BackendSamplerObject::SyncToBackend` before binding it over every
`sampler2D` unit that reads a depth texture (`:5290-5293`). No client ever emits a `create_sampler_state`
for that object. D v2 resolved the record by `g_backendSamplerObjects.HandleOf(object)` - the twin's
identity handle - found nothing, logged the refusal and returned without a push, so the driver sampler
object over every depth read kept GL defaults (NEAREST_MIPMAP_LINEAR on a single-level depth texture is
incomplete: every depth fetch reads 0). Shader packs read depth in every composite pass; vanilla in-world
traces have no `sampler2D` depth reads, which is why the failures clustered on Iris (plus 26.3's
improved-transparency and the 1.21.11 menu, which do). `1e8cdc59` sends an unregistered object down the
"the object IS the authority" branch (`Managers.cpp:12361-12372`), silently and correctly; E's line at
`41b79050` covers the *registered* (application) samplers, which these traces do not use.
Two corrections to E v3 §7 follow: the failures were **category (b) - a loud named refusal in every
failing log** - not category (c), and the "zero refusals" sentence was true of the itest census only; the
retrace census (`<case>/DirectGLES/output/mobilegl.log`, one file per run, no shim needed) had never been
taken. The integrator's post-merge should add it: `grep -c 'no applier record\|does not describe\|declining
the built-in\|cannot be pushed' retrace-out/*/*/DirectGLES/output/mobilegl.log` must be all-zero.
**Classification of the 17 on the current head:** all 17 = "fixed by `1e8cdc59`, loud refusal at
`ee31944b`, no refusal, no seam line and SSIM >= 0.9935 on `41b79050`"; none is E's.
---
## C. Root causes in the brief, and what a P4b/P5 brief must state up front
1. **No record-field -> source-setter -> shutter table.** D-K4's "the shutters are already computed,
latched and counted today - P4a only emits for them" treated the P2/P3a shutters as complete for records
they were never designed for. Every class-6 seam - c0d (bit 13 without the bind generation, bits 6/7/8
under SSO), SD-0 (image re-bind), F-1, F-2, F-3 - is a record field with a source the shutter does not
read. `DirtySurface.def` cannot catch this class: it maps *mutators* to bits and cannot see that a
*derived* field (a program-resolved set, an inlined attachment format, a per-program window) depends on a
mutator whose row is `kPulledEveryVerb`/UNDECIDED (`UseProgram`) or maps to another family's aggregate
(`SetInternalFormat` -> `TextureParams`). The rule to state: **every field of every emitted record names
the frontend counter that moves when its source changes, and that counter is in the emitting bit's
shutter or the emission is unconditional at the setter.** The table is the deliverable of the contract
package, checked by a unit case per row (set the source, assert the bit fires).
2. **No handle-rule table per kind, for both sides.** D-F1 (content-addressed sampler CSO) and D-E1
("BuiltinSampler is a SamplerCso handle") never said who mints it; D-I1's death table gave `SamplerCso`
a per-object helper emitting `DeleteSamplerState`, contradicting D-F1's LRU-only death; D's twin
registries (`TwinRegistry`, `SlotTables.h`) mint by lifetime id for every kind with no rule saying a
content-addressed kind may not be looked up that way. ID-14/17, S-1 (both the bound-sampler and the
raw-depth-fetch instances, §B) and F-4 are one confusion, found one call site at a time. Rule:
**per kind: identity or content, who mints, who frees, and every server table that may key on it -
stated in the contract, with a static check that a content-addressed kind has no lifetime-id twin table.**
3. **"Fine" mirror pairs and gates stated about masks, not emissions.** D-K2's "bit 10 without 11 is fine"
and D-B1's "a push build with P4a's bits clear registers nothing new" described the server's arms and
never asked what the *client* had already cleared (c0f, c0g, S-3). Rule: **a family is live on the client
iff its consumer is registered and every family it depends on is live (transitive), and no client-side
state is cleared before the applier's acceptance - and the same predicate is evaluated on both sides.**
F-5 shows the non-transitive table still disagrees with itself at `0x7ff`.
4. **Records keyed by binding.** D-C2 ruled "emitted once per bound target" for a record whose consumers
address objects by name (ID-19). Rule: **object records are keyed by the object's handle; binding is a
separate, per-context fact.**
5. **Per-context rule for singletons.** D-H7 keyed the composite resolver on a GL name without saying names
are per context (C2-M1). Rule: every process singleton lists its per-context state and the context id it
keys on; `FreshlyPrimed` resets exactly that list.
6. **Serials.** D-J4 said "advance, never zero" but not "a serial is never an emitted test" (E §0) nor "a
record-serial epoch must not be narrower than the shutter it replaces" (F-1b).
7. **Evidence rules.** "Zero refusals" was asserted from `ctest -V` (a false zero, E §6.0) and never taken
on trace runs; a record with no reader (`BoundSamplerViews` entries, `MGPSamplerView`, `DrawBuffers[]`,
`Width/Height/Complete`, `Access`) cannot be verified by any lane. Rule: **the census recipe (file
sink, per-process log) is in the brief, is run on itest AND retrace, and every emitted field has at least
one reader or a white-box comparator by the phase's close.**
---
## D. Ranked list for the integrator
**Before P4a closes**
| # | finding | owner file | what | why now |
|---|---|---|---|---|
| 1 | **F-3** framebuffer masks from a stale inlined format | D `Managers.cpp:8678-8723` (answer the four masks from the resource record's `Desc.InternalFormat`, keep `TextureTarget` from the surface) + one scenario (respecify-while-attached, alpha readback both directions) | the only proven arm-divergence on a public-GL sequence; visible on every GLES driver through the alpha-widened mask | wrong picture, no refusal, no lane |
| 2 | **F-1 + F-1b** bit 12 blind to the program; E's epoch narrower than the walk | A `Tracker.h:494` (mix the program identity and `textureParams` into bit 12) + E `DirectGLES.cpp:1868` (mix `GetTextureBindGeneration()` into the record epoch) + a unit case ("program switch alone re-emits the view set") | F-1b is a wrong picture with no refusal on a plain sequence; F-1 is the design's stated invariant for a program-resolved set | the record is write-only today, so the first reader in P3b/P4b would inherit it |
| 3 | **F-4** sampler twins keyed by identity, looked up by content | D `Managers.cpp:12546` / `SlotTables.h` (key `g_backendSamplerObjects` by CSO handle; twin per `create_sampler_state`) + E `DirectGLES.cpp:4840-4850` comment + a white-box case | the record arm's sampler bind is a permanent silent no-op; the P3b/P4b debounce removal retires the pass that hides it | S-1's class, proven |
| 4 | **F-2** bit 14 plain arm blind to the program | A `Tracker.h:360` (mix the lifetime id, as :420 does) | one line; closes A8's "permanent union" for the program-switch half | silent fallback |
**Recorded for later (P4b/P5 brief items, not gates)**
* F-5 (= SD-5): transitive dependency on both sides; F pins `0x7ff` as loud-decline, not as a lane.
* F-6a/b/c: `Access`, `MGPSamplerView::Target`, the `DrawBuffers` default-token narrowing and
`UploadTarget` Unknown - contract constants and comments before any server reads them.
* F-7: latch-on-acceptance for `set_texture_params` and the framebuffer bound latches (wire n2).
* Records with no reader today: `BoundSamplerViews` entries, `MGPSamplerView` (the twin table exists, no
field is consumed), `DrawBuffers[]`, `Width/Height/Layers/Samples/Complete`, `Access` - each is a
verification hole until P4b gives it a reader or a white-box comparator; G4 retain mode (ID-41).
* SD-4 (imageBuffer units absent from `MaxImageUnit`, `SamplerEmit.h:640`) is still open (C / MG_State
reflection); E's I2 keeps it loud.
* `DirtySurface.def`'s `BindProgramPipelineObject` prose predates c0d; the `d`-tables' "per-context drain
list" wording (D-D4) vs the process-wide `m_drain`.
* Perf items already recorded: `FramebufferSerial` coarse memo; the two sampler cache scans per pass.
**Not defects, refuted:** `SetReadBuffer`/`SetDrawBuffer`/default-size setters (bump the aggregate);
`glDeleteTextures`/`glDeleteSamplers` (bump the bind generation); the ten singletons' reset lists; the
applier's refusal set for well-formed records (Fatal only, so latch-before-acceptance is moot for the unit
sets); the sampler-view twin table (identity on both sides); the framebuffer-record table across a
make-current (process-unique handles).
---
## E. Runs and artefacts
* `~/w7/retrace-out/fable-audit/` (20 cases, lib `41b79050`), `~/w7/retrace-out/fable-audit-2e03b82a/`
(20 cases, lib `2e03b82a`), `~/w7/retrace-out/fable-bisect-<rev>/` (bisect), logs `~/w7/fable-bisect*.log`.
* The bisect worktree `~/w7/fable-bisect` was removed after the run (`git worktree remove --force`; its
three retrace outputs and logs are kept under `~/w7/retrace-out/fable-bisect-*` and
`~/w7/fable-bisect*.log`). No tree under `~/w7/p4a-*` or `~/w7/pipe` was written to; the retrace
harness writes only under `--out`.
* Scripts in the shared scratchpad `wsl/fable-audit-*.sh`, `wsl/fable-bisect*.sh` (mine; delete freely).
@@ -0,0 +1,441 @@
# P4a fable fix round - fablefix-v1 (2026-09-08)
**Branch** `refs/heads/p4a/fablefix`, worktree `~/w7/p4a-fablefix`, base `refs/heads/feat/disaggregated` =
`4678519f` (the complete P4a tree: contract c0..c0g, wire, clientsp v3, clientfb v2, esprytobj v2/v3,
esprytdraw v3 + patches, gates v3). **HEAD `6035c9d7`**, seven commits, **not pushed**, working tree clean.
Integrator grant across package boundaries for this round (ID-45): the files touched are A's `Tracker.h` /
`PipeMutation.h` / `DirtySurface.def` / `scripts/gen_pipe_dirty_surface.py`, B's `TextureObject.cpp` /
`RenderbufferObject.cpp`, D's `Managers.{h,cpp}`, E's `DirectGLES.cpp`, and F's
`MG_IntegrationTest/CMakeLists.txt` (two added lines - one scenario file, one harness TU; section 4). No F
scenario file was edited; the new scenarios live in `Scenarios/P4aSeamAuditScenario.cpp` with their own peek
TU `Harness/P4aSeamPeek.{h,cpp}` (F's `PipeApplyPeek.cpp` is untouched). The census tool
`~/w7/notes/tools/wsl_p4a_refusal_census.sh` is edited in place (not a tree file).
## 0. Verdict in brief
* All four proven seams (F-3, F-1/F-1b, F-2, F-4) and E's SD-4 are fixed, each in its own commit with a
scenario that was RED on the unfixed tree and is GREEN after (section 2 has the red/green transcript per
case; every red was taken on `4678519f` + the tests with the eight behavioural files stashed).
* **SD-4 is not a reflection gap - it is F-2.** A probe (2.5) shows `EmitShaderImages` never ran with the
buffer-image program current: bit 14's plain arm mixed the per-program image-unit COUNTER alone, 0 against
no program and 0 against the program, so the null -> program transition moved nothing. The 2D/3D kinds
were rescued by an unrelated frontend generation moving between the bind and the dispatch; a buffer
texture moves none, which is why only that kind reached E's I2 line. F-2's fix closes it: the five itest
cases E named no longer carry the line (census 0 lines / 0 tests on the final tree).
* **F-1b's wrong picture reproduces** exactly as the audit described (black quad, 144/144 pixels, Espryt at
`0x1fff`; Magma and the legacy arms green) once the sequence has a verb between the bind and the switch
and the first program is in use before the first verb. The F-1 fix alone closes it; E's epoch is NOT
widened with the bind generation (3.2).
* **F-3 was wrong on BOTH arms**, and the audit's "the legacy arm comes out fresh" held only for a respecify
that re-mints the driver id. A same-carrier redefinition (`GL_SRGB8` -> `GL_SRGB8_ALPHA8` on a driver that
widens the first) regenerates mutable storage on the same id, which moves nothing the pre-handle FBO memo
reads either. Commit 1 fixes the handle arm at the SETTER (the framebuffer aggregate); commit 6 fixes the
pre-handle arm for textures (an in-place regeneration takes the generation a re-mint takes); commit 7
compiles that bump under `MOBILEGL_PIPE_PUSH` because G1 (pull library byte-identical to the P4a baseline)
caught it as 0/0/2/0 - so every arm of a push build has the fix, the pull build keeps the pre-P4a hole and
the texture cases decline by name there. A renderbuffer re-storage on the pre-handle arm is D-D2's
documented hole and its case asserts on the handle arm only (2.1, 3.4).
* Gates on `6035c9d7`: G1 0/0/0/0 (`.text` 10806323 -> 10806323), both untouched-region scripts rc 0 (+
self-test, 8 controls), gen_pipe `--check` up to date, dirty-surface `--check` and `--self-test` rc 0 (27
controls), include closure rc 0 (4 probes, both invocations), unit 1772 x 3, G2 2863 == 2863, G14 0 removed
/ +275, integration-gpu **1091/1091 at 0x1fff, 0x1ff, 0 and on the pull build** (DirectVulkan lane
546/546), verify 896/896 with 0 Fatal, retrace 79/79, retrace census 0 on all thirteen needles over 79
logs, itest default-arm census 0 lines / 0 tests on all ten rows and three stems (section 6).
## 1. Commits (branch `p4a/fablefix`, from `4678519f`)
| # | hash | what |
|---|---|---|
| 1 | `dcc31e95` | F-3 (handle arm): the framebuffer aggregate moves from `TextureObjectBase::PipePublishDescriptor` / `RenderbufferObject::PipePublishDescriptor`; + the scenario file with the three F-3 cases, its peek TU, two CMake lines, two `TrackerAggregates` unit cases |
| 2 | `0d01405c` | F-1 / F-1b: bit 12 mixes `opaqueUnits` (lifetime id x link version x backend state version; `stageLinks` x per-stage backend state under a pipeline) and the params aggregate; `DirtySurface.def`'s UseProgram row gains NEW_SAMPLER_VIEWS (+ mark); `gen_pipe_dirty_surface.py` control 21 reads the mark list; two `TrackerWalk` unit cases; the F-1 scenario |
| 3 | `e4579ee8` | F-2 / SD-4: bit 14's plain arm mixes `shader` (lifetime id x link version) into `programImages`; UseProgram row gains NEW_SHADER_IMAGES (+ mark); one `TrackerWalk` unit case; the F-2/SD-4 scenario |
| 4 | `ccb7b6b3` | F-4: `SamplerImpl::ResolveSamplerCsoTwin` (Managers.{h,cpp}); the record arm and the program pass bind it (DirectGLES.cpp); `SyncToBackend` accepts a CSO twin (null object + handle); the F-4 scenario |
| 5 | `72b4c91a` | docs: the record-field -> setter -> shutter table at Tracker.h's shutter block; the bit-11 note |
| 6 | `419f9941` | F-3 (pre-handle arm): an attachable object's storage redefined IN PLACE bumps `g_attachmentBackendIdGeneration` (texture twin's regeneration of mutable storage, renderbuffer twin's re-allocation); the renderbuffer case asserts on the handle arm only. Found by the F-3 scenarios on the 0x1ff / 0 / pull lanes of gate 1 |
| 7 | `6035c9d7` | commit 6's two bumps compiled under `MOBILEGL_PIPE_PUSH`; the two texture cases decline by name on the pull build. Found by G1 on gate 2 (`SyncMipmapsToBackend` +16, `BackendRenderbufferObject::SyncToBackend` +13 = 0/0/2/0, rc 1) |
Seven single-line `[Type] (Scope): description` messages; no attribution trailer (`git log --format=%B
4678519f..HEAD | grep -ciE 'co-authored|claude|assistant'` = 0). Commits 6 and 7 are what the gates found
in the round's own work and are kept as their own commits rather than folded into 1, so the history says
who found what.
## 2. Seam by seam: root cause, change, scenario, red/green
The RED column is the run on `4678519f` + the new tests with every behavioural change stashed
(`git stash push -- <8 fix files>`, build-push, `ctest -R 'P4aSeamAudit|Tracker(Aggregates|Walk)'`, stash
pop); the GREEN column is the staged commit's own run and the final tree's (every lane, section 6).
### 2.1 F-3 - an attached object's storage redefinition never reached the framebuffer record (commits 1, 6, 7)
**Root cause, handle arm.** `set_framebuffer_state` inlines each attachment's `InternalFormat`,
`TextureTarget`, extent, `Samples` and `Complete` at emission (D-C1, `FramebufferEmit.h`
`MGPipeBuildSurface`). The setters that change those - `TextureObjectBase::SetInternalFormat` /
`SetSamples` / `SetFixedSampleLocations`, `TextureObjectWithOneMipmap::AllocateStorage` /
`TruncateMipmapLevels`, the cube, view and buffer-texture variants, and
`RenderbufferObject::SetInternalFormat` / `AllocateStorage` / `SetSamples` - bump the two TEXTURE aggregates
(or, for a renderbuffer, nothing at all) and never the attachment aggregate bit 11 reads. So
`glTexImage2D(RGB-class); attach; draw; glTexImage2D(RGBA-class); draw` left the framebuffer record on the
first format while the resource record moved, and Espryt's handle arm computed its four cross-object masks
(`Managers.cpp` `IsSnormFallbackSurface` / `IsUnormFallbackSurface` / `IsAlphaWidenedColorSurface` /
`IsIntegerColorSurface`, consumed in `BackendFramebufferObject::SyncToBackend`'s Draw-target block) from
the stale surface.
**Root cause, pre-handle arm** (gate 1 on commit 5: the same three cases red at `0x1ff`, `0` and on the pull
build, alpha 1.0 / red 0.25). The FBO twin's memo re-enters `SyncToBackend` on a frontend framebuffer
version or on `g_attachmentBackendIdGeneration`, which `RecreateBackendTexture` bumps when a respecify
RE-MINTS the driver id. A redefinition that keeps the id - `BackendTextureObject::SyncMipmapsToBackend`'s
`needsRegeneration` path regenerating MUTABLE storage in place, `BackendRenderbufferObject::SyncToBackend`
re-allocating behind the same name - moved neither, so the masks of the storage the object was attached
with stayed. The audit's reading that the legacy arm "re-reads the frontend" was true of the re-minting
case only.
**What changed.**
* Commit 1: `MobileGL/MG_State/GLState/TextureState/TextureObject.cpp` `TextureObjectBase::PipePublishDescriptor()`
(push-only, the one funnel every storage-defining entry point takes - the comment at `AllocateStorage`
already said so) now also does `MGP_NOTE_AGGREGATE(FramebufferAttachment)`;
`MobileGL/MG_State/GLState/RenderbufferState/RenderbufferObject.cpp` `PipePublishDescriptor()` - the same
bump, the D-D2 paragraph rewritten (its "widening the shutter would fire the framebuffer emission on an
unrelated renderbuffer write" was the seam); `MobileGL/MG_Pipe/PipeMutation.h` - the
`FramebufferAttachment` enumerator's comment names the new bump sites. `Tracker.h` bit 11's shutter is
unchanged (it already reads the attachment aggregate); its "a renderbuffer respecify is still invisible
here, and deliberately so" paragraph is replaced in commit 5.
* Commit 6: `MobileGL/MG_Backend/DirectGLES/Managers.cpp` - in `SyncMipmapsToBackend`'s
`if (needsRegeneration)` block, `if (m_isInitialized && !m_backendStorageImmutable)
++FramebufferImpl::g_attachmentBackendIdGeneration;` (a first definition is not a redefinition; a
redefinition that went through `RecreateBackendTexture` has already bumped); in
`BackendRenderbufferObject::SyncToBackend` before `Bind()` / the allocation, `if (m_isInitialized) ++...`.
`Managers.h`: the generation's comment now says it counts "did I change something under an attachment
point that no frontend version can tell the framebuffer about", of which the re-mint is one case.
* Commit 7: both bumps inside `#if MOBILEGL_PIPE_PUSH` (3.4 says why); the two texture cases gate their
alpha / DST_ALPHA assertion on `PeekEsprytFramebufferHandleArmIsLive` RETURNING true (it returns true
exactly where it could look, which for a case that already skipped off Espryt means "a push build") and
decline by name on the pull build, printing the value they read.
* Unit: `TrackerAggregates.ATextureStorageDefinitionMovesTheFramebufferAggregateToo` (both aggregates move,
the other four do not) and `...ARenderbufferStorageDefinitionMovesTheFramebufferAggregate` (`ExpectOnly`);
pull skip twins added, G2 stays 0.
**Why the setter and not the shutter.** The task offered "mix the generation that texture/renderbuffer
respecify moves" into bit 11. For textures that would be the content + params aggregates, which fire on
every `glTexSubImage2D` and every `glTexParameter` - MC 26.3 does 185 uploads a frame - and each fire costs
the two 304-byte record builds and hashes in `EmitFramebufferState`; and for renderbuffers there is no
generation at all to mix. Bumping the aggregate the emitter's bit already reads from the one storage funnel
fires bit 11 exactly when an inlined field can have moved, costs nothing per frame, adds no counter to
either object (G1), and is the literal reading of the rule: the setter of a record field moves a shutter the
emitter reads. The dirty-surface derivation is unchanged by it (the aggregate hop is credited to callers
through `MGPipeNoteAggregate`'s switch; no row names these object setters): `--check` rc 0, `--self-test`
all tripped at every stage.
**Scenario** (`P4aSeamAuditScenario`, DirectGLES only - the masks are Espryt's substitution machinery, the
same reason `SnormAttachment` / `ThreeChannelAttachment` skip on Magma): the format pair is `GL_SRGB8` <->
`GL_SRGB8_ALPHA8`, because on llvmpipe `GL_SRGB8` is only renderable through Espryt's three-channel
widening (`GL_RGB8` is native there and would not carry the mask).
| case | sequence | RED on 4678519f (push 0x1fff) | RED on commit 5 at 0x1ff / 0 / pull | GREEN on 6035c9d7 |
|---|---|---|---|---|
| `ATextureRespecifiedWhileAttachedReachesTheFramebufferRecord` | SRGB8 tex, attach, draw a=0.25, respecify SRGB8_ALPHA8 while attached, draw a=0.25, read alpha | `:328` alpha 1.0 != 0.25 (the stale widened mask kept masking alpha off) | alpha 1.0 (in-place regeneration, memo never re-entered) | 0x1fff / 0x1ff / 0 pass asserting; pull passes declining by name, "alpha read 1" |
| `ARenderbufferRestoragedWhileAttachedReachesTheFramebufferRecord` | the same with `glRenderbufferStorage` | `:389` alpha 1.0 | alpha 1.0 | 0x1fff passes asserting; 0x1ff / 0 / pull pass declining by name (D-D2 hole, pre-P4a code) |
| `ATextureRespecifiedToThreeChannelsWhileAttachedReachesTheFramebufferRecord` | SRGB8_ALPHA8 -> SRGB8 while attached, then GL_DST_ALPHA blend of white must read 1.0 | `:462` red 0.25 (the stale not-widened mask let the draw write 0.25 into the carrier) | red 0.25 | 0x1fff / 0x1ff / 0 pass asserting; pull passes declining, "red read 0.25098" |
A decline is a printed `[ P4aSeamAudit ] ... DECLINED ...` line plus `RecordProperty("p4a_seam_white_box",
"declined")`, the shape `TextureParamsWithoutASamplerViewScenario.cpp` argues for; the public half (the draw
lands, green channel 1.0) is asserted on every arm.
### 2.2 F-1 / F-1b - the view set did not follow the program, and E's epoch could not see it (commit 2)
**Root cause.** `EmitSamplerViews` resolves the set for `GetProgramForDraw()` and memoises the resolution
on (lifetime id, link version, backend state version); bit 12's shutter was `Mix(textureContent,
bindGeneration)` - no program input, no params input. `glUseProgram(P2)` moved nothing, so
`BoundSamplerViews` stayed P1's; and E's `UnitBindingsEpochFromRecords` (the two set serials) then never
rebuilt `g_unitTextureSyncList`, so a texture bound to an EMPTY slot of an already-touched unit under P1 was
never `SyncTextureObjectToBackend`'d for P2 - `ResolveAndBindUnitTextures` found no twin and cleared the
native target (probe, 2.5: `resolve unit=1 name=2 twin=0`).
**What changed** (`MobileGL/MG_Impl/Pipe/Tracker.h`): a new walk local `opaqueUnits` = the emitter's memo
key - `Mix(shader, program->GetBackendStateVersion())` on the plain arm, `Mix(stageLinks, stageOpaque)`
under a pipeline where `stageOpaque` mixes each stage program's backend state version (the sampler-unit
assignments reach the composite through the uniform mirror) - and bit 12 = `Mix(Mix(Mix(textureContent,
textureParams), bindGeneration), opaqueUnits)`. The params aggregate is the second F-1 input:
`SamplesAsIncompleteTexture` reads the effective sampler's filters, so a `glTexParameteri(MIN_FILTER)` that
completes a texture fired bit 13 and left the view entry null. `DirtySurface.def`: `X(UseProgram,
NEW_SHADER|NEW_SAMPLER_VIEWS)` with the matching undecided mark (the same taint as bit 6's -
`DestroyProgramSlot` writes a non-`m_` member); `gen_pipe_dirty_surface.py` control 21 now reads the mark
list instead of counting two, so a row that gains a bit is counted (`marked_pairs` must each appear as an
"UNDECIDED answer <bit> for <mutator>" line and the count must match). Unit:
`TrackerWalk.AProgramSwitchAloneFiresTheSamplerViewBit`,
`TrackerWalk.ATextureParameterAloneFiresTheSamplerViewBit`.
**Scenario** `ATextureBoundToAnEmptySlotUnderOneProgramIsSampledByTheNext` (both backends): P1 samples
unit 0 (red), unit 1 is touched through its 3D slot; P1 in use BEFORE the first verb; draw; bind green to
unit 1's EMPTY 2D slot; draw with P1 again (the bind's own bit-12 fire resolves under P1 and suppresses);
switch to P2 (samples unit 1); draw; read back. RED on `4678519f`: `:551` "region should be all green, but
144 of 144 pixels are not; first offender is black" on DirectGLES (Magma green). GREEN after commit 2 on
every lane. Two earlier drafts of this case were green before the fix and are recorded because they say
what the seam needs: with the switch inside the same verb gap as the bind, the bind's fire resolves under
P2; with no program in use at the first verb, the first set is `[null, null]` and P1's later `[red, null]`
is a different set that moves the serial (probe: `views program=0 ... emit=1` then `views program=1 ...
emit=1`).
### 2.3 F-2 / SD-4 - the image window did not follow the program (commit 3)
**Root cause.** Bit 14's plain arm mixed `program->GetImageUnitVersion()` alone - a counter that only
`SetUniformSamplerOrImageUnitIndex` moves for an image uniform, so it is 0 for every program that takes its
image units from `layout(binding)` and 0 against no program. A `glUseProgram` between two such programs, or
from no program to one, moved nothing, and `set_shader_images` kept the previous window. That is also E's
SD-4: the probe shows `EmitShaderImages` running only with `program=0` for `LoadsTextureBuffer` (no `OPQ`
line at all - the resolver was never asked about the buffer-image program) while `LoadsTexture2D` got one
`program=1 maxImageUnit=0 count=1` emission - rescued by a frontend generation the image-bindable re-mint of
a 2D texture moves between the bind and the dispatch and a buffer texture, which has no storage of its own,
does not. The reflection is fine (`isImage=1 unit=0 type=0x9063` for the image kinds that were asked).
**What changed** (`Tracker.h`): `programImages = Mix(shader, program->GetImageUnitVersion())` on the plain
arm - the identity the pipeline arm already mixed as `stageLinks`; `ImageEmit.h`'s invariant paragraph is
untouched (the shutter still reads only frontend counters). `DirtySurface.def`: UseProgram row + mark gain
NEW_SHADER_IMAGES. Unit: `TrackerWalk.AProgramSwitchBetweenEqualImageUnitCountersFiresTheShaderImageBit`.
**Scenario** `AProgramSwitchWithEqualImageUnitCountersMovesTheImageWindow` (both backends; white-box half
declined by name where Espryt's sampler family is not on its handle arm): two BUFFER-image compute programs,
P1 naming unit 0, P2 naming units 0 and 1, both images bound before any dispatch; after P1's dispatch the
applier's window must be Count 1, after P2's Count 2; the public half checks both stores landed (7 and 9).
RED on `4678519f`: `:607` Count 0 != 1 and `:620` Count 0 != 2. GREEN after commit 3. The five itest cases E
named (`ImageTargetKind.Loads/StoresTextureBuffer`, `BufferTexture.AnImageStoreIntoABufferTextureIsVisibleToTheCpu`,
the two `NonCoreImageFormat` buffer cases) no longer carry the I2 line: the default-arm census on the final
tree reads 0 lines / 0 tests for every row (section 6), with all eleven `NonCoreImageFormat` /
`ImageTargetKind` names present in the 545-name list it censused.
### 2.4 F-4 - the record arm's sampler bind could never hit (commit 4)
**Root cause.** `BindCurrentUnitSamplers`' record arm did `g_backendSamplerObjects.FindByHandle(
st.BoundSamplerStates[unit])`: a CONTENT-addressed handle (`MGPipeSlots().Allocate(SamplerCso)` in C's
cache) asked of a table whose every twin was minted off a `SamplerObject`'s lifetime id. One allocator, two
disjoint slot families - a miss on every draw, read by E's S4 comment as a within-draw ordering fact. The
picture stayed right because the pre-handle program pass bound the identity twin (synced from the same
record since S-1); the record arm's only live effect was the unbind of null and out-of-window units. The
audit's white-box reading confirmed it on this tree: `unit 0 driver sampler 1, bind_sampler_states handle
{6, 0} inside window yes, CSO twin 0, identity twin 1`.
**What changed.**
* `Managers.h` / `Managers.cpp` (`SamplerImpl`): `BackendSamplerObject* ResolveSamplerCsoTwin(MGPipeHandle
cso)` - record first (`PipeSamplerCsoRecordForHandle`; no record is a loud named refusal in the sampler
family's census shape), then `g_backendSamplerObjects.GetOrCreateByHandle(cso)` (the same slot table: one
allocator serves both handle families of the kind, so a content slot and an identity slot never coincide;
a generation behind the live entry is refused loudly), then `SyncToBackend(nullptr, cso)`, serial-gated.
`SyncToBackend`'s null-object prologue admits a null object beside a live handle (push-only text; the pull
build's three lines are unchanged token for token), the two log lines name the handle instead of a GL
name, the legacy body returns on a null object it can never receive.
* `DirectGLES.cpp`: the record arm binds `ResolveSamplerCsoTwin(handle)` (S4 retired); the program pass's
sampler override binds the SAME CSO twin for a unit inside the received window and takes the pre-handle
path (identity twin, handle carried to `SyncToBackend`) otherwise, so the two arms cannot ping-pong a unit
between two driver samplers.
* Death: a CSO twin lives until its slot is recycled (the client's LRU eviction frees the slot and the next
handout arrives with a moved generation, which `GetOrCreate(handle)` answers by resetting the twin) -
bounded by the cache's capacity, never by draw count; there is no `delete_sampler_state` hook in the ops
table to retire it earlier, and none is added (recorded in the header comment).
**Scenario** `ABoundSamplerObjectIsDrivenThroughItsCsoTwinOnTheHandleArm` (both backends): a
`CLAMP_TO_BORDER` white-border sampler object bound over a `REPEAT` red texture, sampled at (1.5, 1.5) - the
public half (white wins) passes on every arm; the white-box half (Espryt handle arm only, via
`P4aSeamPeek`) requires the unit's driver sampler == the twin at the CSO handle, and no identity twin for
the object. RED on `4678519f`: `:706` CSO twin 0, `:710` driver sampler != CSO twin, `:713` identity twin 1.
GREEN after commit 4.
### 2.5 The two probes (temporary `MGLOG_E` lines, never committed)
* SD-4 (`SamplerEmit.h` `For()` + `ImageEmit.h`): `LoadsTextureBuffer` -> 19 x `IMG program=0 link=0
maxImageUnit=-1 ... count=0`, no `OPQ` line; `LoadsTexture2D` -> `OPQ program=1 loc=0 unit=0 isImage=1
isTexture=0 isOpaque=1 type=0x9063` then `IMG program=1 link=1 maxImageUnit=0 programWindow=1 count=1`.
* F-1b (`DirectGLES.cpp` sync list / resolve + `SamplerEmit.h` emitters), on the draft that was green:
`views program=0 count=2 ... emit=1 u0={0,0} u1={0,0}` at the clear, then at the P1 draw after the bind
`views program=1 count=2 ... emit=1 u0={15,0} u1={0,0}` -> `syncList ... epoch=3042.../1476...` rebuilt ->
`syncTex name=2`. With P1 in use before the clear the first set is already `u0={15,0}`, the bind's
re-resolution is suppressed, and the P2 draw hits the list memo: black.
## 3. Judgement calls
### 3.1 F-3 at the setter (2.1, "why the setter and not the shutter").
### 3.2 E's record epoch is NOT widened with `GetTextureBindGeneration()`
The audit's F-1b fix offered two shapes: mix the bind generation into E's epoch, or make the serial move on
the F-1 fix. The first would re-run the program-independent list rebuild on every redundant re-bind (26.2
re-binds a sampler around every texture-unit switch), which is exactly the walk E's e2 removed. With F-1
fixed the two serials move whenever the PROGRAM-RESOLVED set moves - a program switch, a relink, a
sampler-uniform re-assignment, a bind onto a slot the program samples, a completeness flip - and that is
the set of events after which a not-yet-synced texture can be SAMPLED. A texture bound to a slot no program
samples stays unsynced until something samples it, at which point the set moves; the read-attachment path,
the copy-image endpoints and the image sweep have their own sync lists. So the record epoch is narrower
than the walk only for textures nothing can read, and the scenario that pins the audit's sequence is green
through the F-1 fix alone. Recorded, not changed.
### 3.3 The scenario file ships its own peek TU (a second CMake line)
Two of the four seams are correct pictures over a permanent silent fallback (F-2/SD-4: the server's
window/high-water union; F-4: the program pass) and have no public-GL observable, so their cases are
white-box. `PipeApplyPeek.cpp` is F's (gates v3) and this round may not edit it; a scenario TU cannot include
`Managers.h` beside the GL prototype headers (PipeSlotPeek.h's rule). So `Harness/P4aSeamPeek.{h,cpp}` is a
new TU of its own - the task said one added CMake line for the scenario; this is two, one per new source
file, in the same list. Its four entry points (`PeekEsprytSamplerHandleArmIsLive`,
`PeekEsprytFramebufferHandleArmIsLive`, `PeekPipeShaderImageWindow`, `PeekEsprytUnitSampler`) all return
false where they cannot look (pull build, Android, a backend that is not Espryt) and a false teaches the
caller nothing.
### 3.4 What was NOT changed, and why
* **The pull build's in-place-regeneration hole (F-3's pre-handle half on pre-P4a code).** Commit 6's two
bumps are Espryt code the pull build shares, and G1 caught them as two resized functions (+32 bytes
`.text`). The charter's G1 is 0/0/0/0 and its meaning is that P4a lands nothing in the pull library, so
commit 7 brackets them with `#if MOBILEGL_PIPE_PUSH`. The pull build therefore still answers alpha 1.0 /
red 0.25 to the two texture cases (they say so by name, every run). The right vehicle is a separate
`[Fix] (Espryt)` commit on dev of exactly those two `if` statements (no P4a dependency; the three F-3
cases are its regression test once the `#if` is dropped and `p4a-before-libMobileGL.so` re-baselined) -
an integrator decision, not this round's.
* **A renderbuffer re-storaged while attached, pre-handle arm.** On the 0x1ff / 0 / pull lanes the
renderbuffer twin is only reached from inside the FBO walk the memo skips, the frontend setters bump no
version (D-D2) and no framebuffer version sees them, so the commit-6 bump inside `SyncToBackend` is never
reached before the memo decides; the resource record is what closes it, and the case asserts on the
handle arm only. Pre-P4a code, D-D2's documented hole; fixing it on the legacy arm means teaching the FBO
memo a renderbuffer version that does not exist today. Not this round's.
* `ImageEmit.h`'s invariant-2 paragraph ("all three FRONTEND counters"): still true - `programImages` is a
frontend identity, not a server epoch - so the sentence stands.
* `DirtySurface.def`'s `BindProgramPipelineObject` prose predates c0d (recorded by the audit): prose answer,
no derivation checks it, not this round's.
* No `delete_sampler_state` ops hook for the CSO twin (2.4).
* The two `.Handles`-style census shapes in `Managers.cpp` are not reworded (the tool is fixed instead,
section 5).
## 4. Deviations from the charter
* Seven commits rather than five: 6 and 7 are the gates' own findings on the round's work (2.1).
* Two CMake lines rather than one (3.3).
* F-3 fixed at `PipePublishDescriptor` rather than in `Tracker.h`'s shutter (3.1); `Tracker.h` gains the
comment and the table only.
* `scripts/gen_pipe_dirty_surface.py` control 21 rewritten to read the undecided-mark list (the hard-coded
"two marks" made the self-test red the moment UseProgram gained a second bit); `DirtySurface.def`'s prose
for the list updated to match ("Control 21 is what proves every marked row still needs its mark").
* The two F-3 texture cases assert on push builds only (3.4, first bullet); the renderbuffer case on the
handle arm only.
## 5. The census tool
`~/w7/notes/tools/wsl_p4a_refusal_census.sh` gains the two built-in-sampler-CSO shapes whose "has no
applier record" straddles a string-literal line break in `Managers.cpp` (`ResolvePushedBuiltinSampler`,
"declining the built-in sampler push"; the border-colour block of `SyncTextureParamsToBackend`, "so its
border colour cannot be pushed") - matched on the half of the LOG line unique to each - plus a stem line
for the pair ("built-in sampler CSO (two shapes)") and a "TEN SHAPES" comment. `Managers.cpp`'s D-N regions
are untouched (the two sentences are not in them either, but the tool fix was preferred as asked). `bash -n`
clean; the default-arm run on the final tree is in section 6.
## 6. Gates on `6035c9d7`
Run by one detached script after the commit (`fablefix-gate.sh`; builds `-j 8`, `CCACHE_BASEDIR=/home/swung/w7`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0`). The same script ran on `72b4c91a` (gate 1: the F-3 reds on
the legacy lanes) and on `419f9941` (gate 2: G1 0/0/2/0, everything else identical to the numbers below).
| gate | result |
|---|---|
| builds | build-linux / build-push / build-verify rc 0, 0 warnings each |
| G1 `symbol_report --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` vs `p4a-before-libMobileGL.so` | rc 0: `.text` 10806323 -> 10806323 (+0), 27811 -> 27811 symbols: **0 added, 0 removed, 0 resized, 0 renamed** |
| `scripts/p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, byte-identical |
| `scripts/p4a_untouched_regions.sh 37da3c3a HEAD` | rc 0, depth-stencil-sampling / format-caveat regions byte-identical |
| `scripts/p4a_untouched_regions.sh --self-test` | rc 0, 8 negative controls all tripped and named |
| `scripts/gen_pipe.py --check` | up to date |
| `scripts/gen_pipe_dirty_surface.py --check` | rc 0 |
| `scripts/gen_pipe_dirty_surface.py --self-test` | rc 0, 27 negative controls all tripped, positive controls OK (control 21 now "every P4a undecided mark - 4 of them - is still needed") |
| `scripts/check_include_closure.py --compiler clang++` | rc 0, 4 probes, 0 skipped, 0 problems |
| `check_include_closure.py --mode text --self-test --require-all --expect-probes 4` | rc 0 |
| unit `-L unit` | build-linux 1772/1772, build-push 1772/1772, build-verify 1772/1772 |
| G2 pull-vs-push ctest names | 0 diff lines (2863 == 2863) |
| G14 names vs `p4a-before-ctest-names.txt` | 0 removed, 275 added |
| integration-gpu, build-push, `MOBILEGL_PIPE_PUSH` default (0x1fff) | 1091/1091 |
| integration-gpu, build-push, 0x1ff | 1091/1091 |
| integration-gpu, build-push, 0 | 1091/1091 |
| DirectVulkan lane (`-R ^DirectVulkan`, build-push) | 546/546 |
| integration-gpu, build-linux (pull) | 1091/1091 |
| integration-verify, build-verify, `-j 4` | 896/896, `Fatal{` lines 0 |
| retrace (`retrace_gate.py --lib build-push/libMobileGL.so -j 4`, fixtures re-copied, 0 LFS pointers) | rc 0, **79 / 79**, failed [] |
| retrace refusal census over 79 `mobilegl.log`s | 0 for every needle: the ten shapes ("storage and uploads cannot be driven", "built-in sampler cannot be pushed", "parameters cannot be pushed", "read buffer cannot be pushed", "it is not configured here", "no shader-CSO applier record", "sampler ... has no applier record", "storage cannot be allocated", "declining the built-in sampler push", "border colour cannot be pushed"), "does not describe the binding it names", `Fatal{`, "cannot be adopted on the handle arm"; the deduped `MGPipe:` ERROR/FATAL list is empty |
| itest default-arm census (`wsl_p4a_refusal_census.sh default`, 545 names, 525 logs) | 0 lines / 0 tests on all ten rows; stems "no applier record on the handle arm" 0, "no shader-CSO applier record" 0, "built-in sampler CSO (two shapes)" 0; FATAL lines 1050 = the 2 ambient EGL loads x 525 logs, none real |
| the new scenarios (12 cases: 6 DirectGLES + 6 DirectVulkan) at 0x1fff | 12/12; the three F-3 cases 3/3 at 0x1fff, 0x1ff, 0 and on pull (declines by name as in 2.1) |
Baseline for the integration lanes was 1079/1079; the twelve added are the six new cases on both backends.
## 7. The shutter table
Carried in `Tracker.h` at the shutter block (commit 5, before `// ---- the object-class bits 9..17 ----`)
and reproduced here for the P4b brief:
```
THE RECORD-FIELD -> SETTER -> SHUTTER TABLE FOR THE SEVEN P4a BITS.
THE RULE (P4a fable seam audit, section C.1): every field of every emitted
record names the frontend setter that changes it, and that setter moves a
counter the emitting bit's shutter reads - or the emission is unconditional at
the setter (the resource_* family, set_texture_params). A record field whose
setter moves no shutter input is a stale record with nothing to refuse: c0d
(bit 13 without the bind generation), SD-0 (an image re-bind), F-1 (the
program behind the view set), F-2 (the program behind the image window) and
F-3 (an attached object's storage) were all this one class. DirtySurface.def
cannot catch it - it maps MUTATORS to bits and cannot see that a DERIVED field
depends on a mutator whose row is another family's - so the table lives here,
beside the shutters, and a row is added whenever a record gains a field.
bit 6 create/bind_shader_state, set_draw/dispatch_program (ProgramEmit.h)
fields: Cso, StageMask, GlobalUboSize, the artefact blob refs, the two
bound handles
setters: glUseProgram (m_currentProgram), glLinkProgram (link version),
glBindProgramPipeline / glUseProgramStages (pipeline name +
per-stage {lifetime id, link version})
shutter: lifetime id x link version, or stageLinks under a pipeline
bit 7 the program's bindings (image units, block bindings, uniform write set)
setters: glUniform1i on an opaque uniform (backend state version, image
unit version), glUniformBlockBinding / glShaderStorageBlockBinding
(block binding version), any glUniform* (uniform write set)
shutter: the four per-program counters, x stageLinks under a pipeline
bit 8 set_global_constants: ShaderCso, Version, the default-block image
setters: any glUniform* on the default block (UBO content version),
glUseProgram (lifetime id)
shutter: lifetime id x UBO content version, or stageState
bit 11 set_framebuffer_state: Fbo, Color[8]/Depth/Stencil/ReadSurface
(Res, Kind, InternalFormat, TextureTarget, Layered, Level, Layer,
UploadTarget), DrawBuffers[8], Width/Height/Layers/Samples/
FixedSampleLocations, IsDefault, Complete, Target
setters: glFramebufferTexture*/glFramebufferRenderbuffer, glDrawBuffer(s),
glReadBuffer, glFramebufferParameteri (the attachment
aggregate); glBindFramebuffer (the two binding slot versions);
AND a storage redefinition of an ATTACHED texture or
renderbuffer - glTexImage*/glTexStorage*/glTexBuffer/
glTextureView/glRenderbufferStorage* - because InternalFormat,
TextureTarget, the extent, Samples and Complete are INLINED at
emission (D-C1): those bump the attachment aggregate from the
object's PipePublishDescriptor (F-3)
shutter: attachment aggregate x draw bind version x read bind version
bit 12 set_sampler_views: per unit {View, Texture}
setters: glBindTexture / glActiveTexture (bind generation), a texture's
or a sampler object's parameters (SamplesAsIncompleteTexture -
the params aggregate), an upload that defines a level (content
aggregate), the default texture's image appearing (bind
generation, TextureObject.cpp); AND the program in use -
glUseProgram, a relink, glUniform1i on a sampler uniform (which
unit a uniform's TYPE resolves) - F-1
shutter: content x params x bind generation x opaqueUnits
bit 13 bind_sampler_states: per unit the sampler CSO handle
setters: glBindSampler (bind generation, c0d), glSamplerParameter* /
glTexParameter* (params aggregate + sampling resolution),
glDeleteSamplers (bind generation)
shutter: params x sampling resolution x bind generation
bit 14 set_shader_images: per unit {Res, InternalFormat, Layer, Level,
Layered, Access} over the program's image-unit window
setters: glBindImageTexture (bind generation, SD-0), a texture's
content/params, glUniform1i on an image uniform (image unit
version); AND the program in use - glUseProgram, a relink -
F-2
shutter: content x params x bind generation x programImages
(lifetime id x link version x image unit version)
```
## 8. Logs
Every `~/w7/fablefix-*` log, `~/w7/fablefix-logs/`, `~/w7/fablefix-stage/` and `~/w7/fablefix-census/` are
deleted at the end of the round; `~/w7/retrace-out/p4a-fablefix` keeps only `summary.txt` / `summary.json`.
The worktree `~/w7/p4a-fablefix` stays (branch `p4a/fablefix`, HEAD `6035c9d7`, clean; fixtures are the
copies from `~/w7/pipe` under `assume-unchanged`). The shared scratchpad `wsl` directory is untouched except
for this round's own `fablefix-*` scripts.
@@ -0,0 +1,484 @@
# P4a final whole-diff review — v1
Reviewer: final whole-diff review (fable). Tree reviewed: `~/w7/pipe` at `a38bdab4` = code head
`6035c9d7` (+ the tools-only `MOBILEGL_TRACE_SKIP_INSTALL` commit). Phase diff read in full:
`git diff 37da3c3a 6035c9d7` (81 files, every hunk, including the tests, the harness, the scripts and
the workflow). Experiments ran in the throwaway worktree `~/w7/p4a-finalreview` (@ `6035c9d7`,
`build-push` / `build-linux`, base tree `~/w7/p4a-finalreview-base` @ `37da3c3a`) after
`~/w7/p4a-bench.done` appeared; the worktrees are removed at the end of this round (§9). Nothing was
committed to `pipe`.
Reading order, as instructed: `INTEGRATOR-DECISIONS.md` (ID-1..49), `BRIEF-P4A.md` A/D/E/F,
`fable-seam-audit.md`, `fablefix-v1.md`, then contract-v7, wire-v3 + review-v2, clientfb-v2 +
review-v2, clientsp-v3 + review-v2, esprytobj-v3 + review-v2, esprytdraw-v3, gates-v3, and the three
docs. Findings below were refuted against the code before being written; the refutation attempted is
stated under each.
---
## 0. Verdict
**REWORK** — two critical defects in the texture-resource family's CLIENT half (package B's
`TextureEmit.h`), both structural, both invisible to every gate that shipped, both with a small and
well-bounded fix:
* **C-1** — `TextureEmit.h` never passes wire's `MGPRespecifiedLevel`, so every per-level
`glTexImage*D` / `glCopyTexImage2D` / `glGenerateMipmap` grow clears the applier's WHOLE
pending-upload set. A level accepted at one verb and defined-around at the next is uploaded by nobody;
the client's flag is already clear (D-D5 step 1). Silent, no counter, no log line.
* **C-2** — a dead-but-not-recycled texture handle still resolves to the freed `ITextureObject*` inside
the emitter, and the drain list is not emptied at death. `glTexImage2D` → `glDeleteTextures` → next
verb walks freed memory (virtual `GetStorageType()` on it), and keeps walking it once per verb until the
slot is recycled.
Both were confirmed by probes in the review worktree (§2), and C-1's shape was documented as B's
obligation by wire-v3 §5 item 5 and never checked by clientfb-review-v2. Everything else in the phase
is CLOSE-quality: the contract as landed is consistent (one encoding per field, six death helpers in one
fixed order, c0f/c0g complete and non-transitive on both sides, the shutter table complete after the
fable round), the applier is a per-object table with loud stale-generation refusals, Espryt's handle arms
refuse loudly at every one of the 27 decline sites I re-walked, the exit-order rule holds, no debug or
temporary-base artefact leaked, and every gate I mutated went red for the reason it exists (§4) except
the one declared limitation in §4.3.
The rework is one package (B) plus one contract signature (A), ≈ 6 files + 2 tests, and does not
reopen D/E/F. After it lands: re-run the list in §8. The recorded items (§5) and the D.5 docs checklist
(§6) are unchanged by the rework.
---
## 1. Findings
### CRITICAL
#### C-1 — the client never passes the level scope; a per-level respecify drops every pending upload
**Where.** `MobileGL/MG_Impl/Pipe/TextureEmit.h:955-960`:
```cpp
static Bool ApplyRespecify(const MGPResourceDesc& desc) {
if constexpr (MGPipeTextureRecordsReachTheApplier()) {
return MGPipeApplyResourceRespecify(desc, nullptr); // third parameter defaulted: level == nullptr
}
```
`MGPipeApplyResourceRespecify(desc, initialBytes, const MGPRespecifiedLevel* level)`
(`MG_Pipe/PipeApply.cpp:1612-1613`) then takes the whole-resource arm at `:1684-1685`:
`else if (level == nullptr) { record->PendingUploads.clear(); }`. The non-test tree contains exactly
three mentions of `MGPRespecifiedLevel`: `PipeApply.h`, `PipeApply.cpp`, and a comment in
`Managers.cpp`. No emitter constructs one. The hook the frontend calls
(`MG_State/.../TextureObject.cpp:68-69` `PipePublishDescriptor()` → `MGPipeEmitTextureResourceRespecify(*this)`,
`PipeMutation.h:320`) carries no level at all, although every caller of it — `AllocateStorage`
(`TextureObject.cpp:527`, `TextureObject2DCube.cpp:68`) — is per `(uploadTarget, level)`.
**Why the descriptor moves on a level-1 definition** (so the metadata-only arm does not save it):
`TextureEmit.h:239` `desc.Levels = mipmap->GetMipmapLevelCount()`, and `GetMipmapLevelCount()` is
`m_textureStorage.GetLevelCount()` (`TextureObject.cpp:471-473`), which grows as levels are defined.
`RespecifyRedefinesNoStorage` (`PipeApply.cpp:558-568`) compares `Levels`, so the call is classified as a
redefinition and the clear runs.
**Failure scenario** (any of these, application-side, all legal GL):
1. `glTexImage2D(L0, data)` → any verb that does not reach the texture (a draw with another texture, a
`glClear`, `glReadPixels`, `glGetTexImage` on another texture, `glBindImageTexture` — every
`MGP_FILL` point drains) → `glTexImage2D(L1, data)` → draw sampling the texture.
At the first verb the drain emits L0, the applier accepts it, the client clears L0's flag
(`TextureEmit.h:1097`). Espryt does not sync the texture (bound nowhere / not sampled), so the
applier's entry is the only owner of those texels. The L1 definition respecifies with `level ==
nullptr` → `PendingUploads.clear()`. At the sampled draw the handle arm allocates from the descriptor
(`MGB_STORAGE_*`, `Managers.cpp:6315-6333`) and uploads only what `FindPipeTextureUpload` returns
(`MGB_LEVEL_NEEDS_UPLOAD`, `:6262-6265` — no frontend fallback on the handle arm): L1 only. Level 0
is allocated undefined. No refusal, no counter, no line.
2. The same with `glGenerateMipmap`: `GL_Texture.cpp:6782-6783` runs
`EnsureGeneratedMipmapStorageAllocated` (one `AllocateStorage` → one respecify per level, `:505-550`)
BEFORE `GenerateMipmap_Backend` (`MGP_FILL(GenerateMipmap)` at `:1675`). A texture whose level 0 was
accepted-but-unconsumed loses it inside the generate; the driver builds the chain from garbage.
3. Cube maps: six faces of level 0 defined across verbs — each face's `AllocateStorage` respecifies and
clears the other faces' pending uploads.
4. Texture views: `TextureObjectView::AllocateStorage` forwards to the owner (`TextureObjectView.cpp:272`),
so a per-level definition through a view clears the OWNER's set.
**Evidence.**
* Applier+client probe (worktree, `TextureEmitTest` with the real frontend `AllocateStorage` /
`MarkStorageDirtyRegion` and `DrainTextureSubData`): `FinalReviewALevelDefinedAfterAnEmittedButUnconsumedUploadKeepsThatUpload`
→ **RED**: after the level-1 definition, level 0 is no longer pending and its client flag is CLEAR;
after the next drain only level 1 is pending (`~/w7/p4a-finalreview-exp.log`).
* End-to-end (worktree itest `FinalReviewC1Scenario`, DirectGLES, llvmpipe): **cases 1 and 4 read a
100 % black level 0 on the handle arm (`0x1fff`) and red on the legacy arm (`0x1ff`); the three
controls are red on both** (§2.1).
**Refutation attempted.**
* "Espryt's incomplete-texture bail keeps the level pending until the chain is complete": the bail at
`Managers.cpp:6480` is `!IsComplete() && !HasAnyDefinedMipmapLevel(...)` — it only bails when NO level is
defined. So when the texture IS reached, L0 is consumed at the first sync and the hazard closes; the
hazard needs the texture to be unreached between the two definitions. That is the ordinary loader
shape (progress bars, one-level-per-tick uploaders, atlas stitchers that upload level 0 and mip later).
* "The client re-dirties": nothing in MG_Impl re-marks a level; the only re-dirty is
`RearmPipeTextureLevelUpload` on a backend bail, which needs the set to still hold the entry.
* "glTexStorage / glBufferData are whole-resource anyway": yes, and those are the calls that SHOULD pass
`nullptr` (wire-v3 §5 item 5 lists them). The bug is that everything passes `nullptr`.
* "The applier could infer the scope": it cannot — a `Levels` move from 1 to 2 and a level-0
redefinition at a new format both change the descriptor; only the caller knows which level moved.
**Why no gate saw it.** `TextureEmitTest.cpp:1567-1645` and `:1647-…` (wire's C1 cases and gates'
MINOR-1 cube case) drive `MGPipeApplyResourceRespecify(..., &levelZero)` DIRECTLY — they prove the applier's
arm and assume B passes the pointer (`:1584-1591` even says so in prose). No unit case drives
`AllocateStorage` twice around a drain. clientfb-review-v2 verified M1 (the region tail) at
`TextureEmit.h:1068-1069` and did not verify wire-v3 §5 item 5. No itest or retrace fixture defines two
levels of one texture around a verb without sampling it in between (the itest textures are drawn
right after their upload; MC defines every level with NULL data in one burst and sub-images later).
**Fix path** (B + A, one commit, ≈ 6 files):
`PipeMutation.h:320` `MGPipeEmitTextureResourceRespecify(ITextureObject&, const MGPRespecifiedLevel* = nullptr)`;
`TextureObject.h:235` / `TextureObject.cpp:68` `PipePublishDescriptor(TextureUploadTarget, Uint level)`
called from `AllocateStorage` with the level and from `TruncateMipmapLevels` / the view / immutable
paths with none; `PipeFill.cpp:1258` forwards; `TextureEmit.h:955` builds the key with
`MGPipePackSubDataTarget(MGPipeResourceTargetForTextureTarget(target), uploadTarget)` — the SAME packed
`Target` the drain uses at `:1037-1039` (wire-v3 §5 item 5's exact requirement), and `RepublishMask`
keeps `nullptr`. Tests: the applier+client probe above becomes a permanent `TextureEmitTest` case; the
itest in §2.1 (cases 1 and 4 with their controls) becomes a lane.
#### C-2 — a dead texture handle resolves to freed memory in the drain; the drain list survives the death
**Where.** `TextureEmit.h:446-453`:
```cpp
ITextureObject* ResolveTexture(MGPipeHandle handle) const {
... if (entry.Texture == nullptr || entry.Gen != handle.Gen) return nullptr;
if (MGPipeSlots().GenOfSlot(MGPipeKind::Texture, handle.Slot) != handle.Gen) return nullptr;
return entry.Texture;
```
`MGPipeSlotAllocator::Free` (`SlotAllocator.cpp:184-207`) sets `Live = false` and pushes the slot on the
free list; the generation moves only in `AllocateFor` (`:90` `++entry.Gen`) at the NEXT acquire. So
between the death and the recycle, `GenOfSlot == handle.Gen`, `entry.Texture` is the freed object, and
`ResolveTexture` hands it back. The death helper (`PipeFill.cpp:1391-1395`
`MGPipeEmitTextureDestroyAndFree`) does not forward to the emitter — `TextureEmit.h:927-929` says so in
its own words ("the death helper is A's ... and does not forward to this emitter") — and
`RetireIfRecycled` (`:931-935`) clears the entry only at re-acquire. Nothing removes the slot's
`DrainKeys` / `m_drain` entries at death.
**Failure scenario.** `glGenTextures; glTexImage2D(data)` (or `glTexSubImage2D`) — the level is on the
drain list — `glDeleteTextures` (the last reference; the frontend destructor runs the helper) — any verb.
`DrainTextureSubData` → `EmitOneLevel` (`:998-1005`) → `ResolveTexture` returns the dangling pointer →
`AsMipmapTexture(texture)` calls virtual `GetStorageType()` (`TextureObject.h:342-346`) on freed memory →
`IsStorageDirty` reads freed `MipmapStorage`. If the allocator has not scribbled the block the read
succeeds, a `resource_subdata` is emitted for a record the wire delete has already dropped, the applier
refuses it (a counted no-op, `:1082-1083`), `EmitOneLevel` returns false and the entry STAYS on the list
(`:1090-1095`, "retried at the next validate point") — so the freed object is dereferenced once per verb
until a new texture recycles the slot. In a process with many texture creates this is short; in one
that deletes a temporary texture and then draws for a long time it is a per-draw UAF read plus one
`MGLOG_E_ONCE` line. `MALLOC_PERTURB_` / ASan / a reused block turns it into a crash.
**Evidence.**
* Emitter probe (worktree, `TextureEmitTest`): `FinalReviewADeadTexturesHandleStillResolvesAndTheDrainWalksIt`
→ `IsLive == false` passes, `ResolveTexture(handle) == 0x5a88f04261f0` (expected `nullptr`), and
`DrainListSize()` stays 1 after the death (`~/w7/p4a-finalreview-exp2.log`).
* End-to-end (worktree itest, case 6 of `FinalReviewC1Scenario`, 8 create-upload-delete-draw rounds,
plain and under `MALLOC_PERTURB_=165`, both arms): **SIGABRT `pure virtual method called` on the
handle arm in the first round, with and without the perturb; the legacy arm passes** (§2.1). This is
a hard crash on `glTexImage2D; glDeleteTextures; <any verb>` at the shipping default mask.
**Refutation attempted.**
* "The `GenOfSlot` compare is the guard": it guards a RECYCLED slot, not a dead one — the design comment
at `:442-445` ("the entry exists only between the create the constructor emits and the destroy the
destructor emits") describes an invariant no code establishes.
* "The applier refuses, so nothing reaches the server": true for the server — the client-side deref is
the hole, and the refusal path is what keeps the entry alive.
* "No lane saw it, so the sequence is rare": no itest or retrace deletes a texture with a level still on
the drain list (every itest draws first). CTS negative tests and `packed_pixels` (upload, check
errors, delete, next case draws) do exactly this; G15 has not run yet.
* The renderbuffer table has the same stale-`Gen` entry but no drain and no pointer, so no deref; the
framebuffer `NamedEntry` table resolves the live object at the DSA call; sampler CSOs are
content-addressed with reference counts; sampler views and shader CSOs are re-acquired from live
objects at the validate point. Only the texture drain defers by handle.
**Fix path** (B + A, same commit as C-1): the texture death helper — or the emitter's own hook from
`NotifyAndFree`'s notice — nulls `entry.Texture`, drops `entry.DrainKeys` and the slot's entries from
`m_drain`; `ResolveTexture` tests `MGPipeSlots().IsLive(kind, handle)` rather than `GenOfSlot`. The
emitter probe above becomes a permanent case; the itest case 6 (with `MALLOC_PERTURB_` in its lane
environment) becomes the negative control.
### MAJOR
#### M-A — no producer of `kMGPipeBindSampler` / `kMGPipeBindShaderImage`; `ImageBindableHint` is dead
`MGPipeTypes.h:256-259` says "P4a is that producer: a texture sets kMGPipeBindSampler,
kMGPipeBindShaderImage, kMGPipeBindRenderTarget and kMGPipeBindDepthStencil". The only caller of
`NoteTextureBoundAs` (`TextureEmit.h:474`) in the non-test tree is `FramebufferEmit.h:577`, with
RenderTarget / DepthStencil. `SamplerEmit.h` and `ImageEmit.h` never call it. Consequences:
* `desc.ImageBindableHint = (BindMask & kMGPipeBindShaderImage) != 0` (`TextureEmit.h:230`, `:520`,
`:982`) is always 0; the ShaderImage-transition `ForceParamsResync` at `:486` is dead.
* Espryt's `pushedWantsImageBindableStorage` (`Managers.cpp:6408`, read from `Desc.BindMask`) never
fires from the record; the widening still comes from the legacy trigger
(`SyncTextureObjectToBackend(texture, /*imageBindable=*/true)`), so the PICTURE is right — but D-A4 /
D-M's mitigation (the hint arriving BEFORE the first image bind so the level is not re-uploaded) is not
delivered, and `ROADMAP.md:85` open question 2 (the remint pull rate that decides
`MOBILEGL_PIPE_TEXEL_RETAIN_MB`) cannot be answered from this tree — nothing counts a remint.
* The metadata-respecify arm (ID-18 M4, `RepublishMask` `:975-986`) has exactly one live trigger
(framebuffer attachment) and none of the two the ruling was written for.
Refutation attempted: `ResourceTracker.h:97` returns `kMGPipeBindSampler` for `BufferTarget::Texture`
— that is the BUFFER family (a TBO's backing store), not a texture. clientsp-review-v2 §"sampler views"
checks the view's `Target`/`Res` and not the mask.
Fix (C, ≈ 2 lines + 1 unit case): `ImageEmit.h`'s window walk notes each image-bound texture as
`kMGPipeBindShaderImage`; `SamplerEmit.h`'s view acquisition notes `kMGPipeBindSampler`;
`ImageEmitTest`: "a texture bound to an image unit carries `ImageBindableHint = 1` on its next
descriptor". Not blocking on its own — recorded as MAJOR because a design ruling (D-A4) is silently
undelivered and a ROADMAP number depends on it.
### MINOR
* **m-1 F-7 (recorded by the audit, still open): set_texture_params latches BEFORE acceptance.**
`TextureEmit.h:641-643` sets `HasParamsLatch / ParamsVersion / SamplerVersion` and `:676` clears
`ForceParamsResync` before the void `MGPipeApplySetTextureParams(params)` at `:679`. A refused record
(no applier record — the SD-1/SD-3 shape) leaves the latch advanced; the params are not re-sent until
the next `glTexParameter*` moves the version. `PublishCreate` (`:941-953`) and `NoteRespecified`
(`:962-968`) got the acceptance rule; params did not. Owner B; make `MGPipeApplySetTextureParams`
return `Bool` (A) and latch on true.
* **m-2 `Config.h:336-340`** lists 0x200→0x400, 0x400→0x80, 0x800→0x400 and omits the fourth row
`kMGPipeP4aFamilyDependencies` actually enforces (`PipeFill.cpp:961-…`: bit 10 also requires bit 11).
The scenario `ASamplerBitWithoutTheTextureBitIsRefusedAndNamed` pins the code; the comment misleads a
reader of the mask.
* **m-3 `MGPipeTypes.h:1107-1108`** says the stored `BindMask` "is sticky and therefore ORed, never
replaced"; `PipeApply.cpp:1644` replaces the descriptor whole. Equivalent today only because the
client's `entry.BindMask` is itself sticky; fix the comment (or OR in the applier).
* **m-4 F-6 (audit class 1, recorded): encodings stated in package headers, not the contract.**
`MGPipeEncodeImageAccess` lives in `ImageEmit.h`; `MGPSamplerView::Target`'s meaning and the
`DrawBuffers` narrowing are stated at their emitters. Espryt reads them back with its own copies.
Owner: contract, P4b.
* **m-5 `DirectGLES.cpp:8687-8754`** (`GenerateThreeChannelFloatMipmapOnCpu`, called at `:8780`):
marks frontend levels dirty from inside the backend without `RearmPipeTextureLevelUpload`; on the
handle arm the CPU-built levels reach the driver only at the NEXT verb's drain (self-heals, one verb
late). The storage grow beside it (`EnsureGenerateMipmapStorageAllocated`, `:8038` / `:8777`) is
fine — and note it is a SECOND per-level `AllocateStorage` → respecify path inside the backend that
C-1's fix must pass the level through as well.
* **m-6** G9's dirty-surface check is blind to the two P4a bits on the `UseProgram` row when row AND
mark are dropped together (declared in `DirtySurface.def:300-306`; measured in §4.3). The behaviour
is pinned by `TrackerTest.cpp:833-849` and the F-1/F-2 itests, not by the gate.
* **m-7 pull-build text change**: `DirectGLES.cpp:4137/4174` adds a `Bool broadcastCountResolved`
local and an `if` on the pull path (the only non-`#if` code change the preprocess diff of
`Managers.cpp` / `DirectGLES.cpp` / `TextureObject.cpp` shows; everything else is macro parentheses,
`__LINE__` immediates and one `static_assert` string). Benign; the per-symbol size comparison in §3
is the evidence.
* **m-8** the review worktree's `include/ska` submodule prints `fatal: not a git repository` on every
`git status` — a `wsl_tree.sh`-shaped tree does not get the nested-worktree `.git` pointer right
for `include/ska`; `git commit -a` fails silently there (it cost this review one false gate reading,
§4.1). Tooling note for `~/w7/notes/tools/`.
---
## 2. Experiments (review worktree, after the bench)
### 2.1 `FinalReviewC1Scenario` (DirectGLES, llvmpipe, itest binary run directly with the lane's env)
| case | sequence | `0x1fff` handle arm | `0x1ff` legacy arm |
|---|---|---|---|
| 1 PerLevelDefinitionAcrossAnUnrelatedDraw | L0(red); draw(other); L1(red); draw(T) magnified | **BLACK** rgba(0,0,0,0), 11625/11625 px — **FAIL** | red — pass |
| 2 ConsecutiveDefinitionsNoVerbBetween (control) | L0; L1; draw(T) | red — pass | red — pass |
| 3 LevelZeroConsumedBeforeLevelOne (control) | L0; draw(T); L1; draw(T) | red — pass | red — pass |
| 4 GenerateMipmapAcrossAnUnrelatedDraw | L0(red); draw(other); glGenerateMipmap; draw(T) | **BLACK** 11625/11625 px — **FAIL** | red — pass |
| 5 GenerateMipmapImmediately (control) | L0(red); glGenerateMipmap; draw(T) | red — pass | red — pass |
| 6 ADirtyTextureDeletedBeforeAnyVerbIsWalkedByTheNextDrain | 8 × (L0(red); delete; draw(other)) | **SIGABRT** in round 1: `pure virtual method called` / `terminate called without an active exception` (rc 134) | white, 8/8 rounds — pass |
| 6 under `MALLOC_PERTURB_=165` | same | **SIGABRT**, same message | pass |
Notes. 128×96 pbuffer, llvmpipe (LLVM 22.1.6), `MOBILEGL_BACKEND_TYPE=DirectGLES`,
`__EGL_VENDOR_LIBRARY_FILENAMES=…/50_mesa.json`, the itest binary run directly with `--gtest_filter`;
logs `~/w7/p4a-finalreview/.finrev-logs/c1-{handles,legacy,perturb,perturb-legacy}.{log,mglog}`.
The three controls (2, 3, 5) are green on the handle arm, so the mip path and the consumed-first path
are fine and the two black pictures are exactly the accepted-but-unconsumed window C-1 describes.
Case 6's `pure virtual method called` is the dangling-vtable signature of a virtual call on an object
whose destructor has run — `AsMipmapTexture` → `GetStorageType()` from `EmitOneLevel` — and it fires on
the FIRST round without any allocator help; the library log carries no `was refused` line because the
process dies inside that first drain. The legacy arm (no drain, no handle table) passes all six.
### 2.2 First-attempt probes (same worktree, 21:43–22:00, logs `~/w7/p4a-finalreview-exp*.log`)
* `TextureEmit.FinalReviewALevelDefinedAfterAnEmittedButUnconsumedUploadKeepsThatUpload` — RED (C-1 at the
emitter+applier level, driven through the real `AllocateStorage`).
* `TextureEmit.FinalReviewADeadTexturesHandleStillResolvesAndTheDrainWalksIt` — RED (C-2 at the emitter
level).
---
## 3. G1 / G5 mechanics
* **G5** as landed: `p4a_untouched_regions.sh 37da3c3a HEAD` rc 0; `--self-test` 8/8 controls tripped.
Mutation (§4.1): a `(void)0;` statement committed inside `RingAvailable` → rc 1, the row's sha moves
and the region is named. (A comment-only mutation also moves the sha by the script's own rule at
`:63-72`; my first two tries read rc 0 only because `git commit -a` failed on the broken submodule —
m-8.)
* **G1 spot-check at TU granularity** (pull configuration, `compile_commands.json` of both
`build-linux` trees, `clang++ -E -P` and `nm -S -C` on the objects):
- `Managers.cpp.o`: 1410 defined symbols at base and at tree, **0** differing (size, type, name)
rows; `DirectGLES.cpp.o`: 1004 and 1004, **0** differing. The symbol SET and every symbol's SIZE
are unchanged in the pull configuration of the two files the phase touched most.
- Preprocessed bodies: `BackendSamplerObject::SyncToBackend` **identical** (the widened signature is
`#if MOBILEGL_PIPE_PUSH`-guarded at `Managers.h:2552-2564`, so the pull symbol keeps its name);
`SyncMipmapsToBackend` and `SyncBuiltinSamplerToBackend` differ only in `__LINE__` immediates
inside `ErrorLopper::Loop` lambdas and in the extra parentheses the `MGB_*` macros add (no codegen
effect — the nm rows above are the proof); the `TextureObject.cpp` TU (first attempt) differs only
in a `static_assert` string. The one pull-path CODE change found is m-7.
* D-N regions: the 17 rows are the same 17 the brief lists (15 Managers.cpp functions,
`DepthStencilSamplingReadImpl` namespace, `ShouldUseCaveatTextureFormat`), `FlushPendingRangesFrom`
consulted against the pinned sha unconditionally (D-N/2, declared in the script header).
---
## 4. Gates — can each go red?
### 4.1 Mutations this round (worktree; every edit restored, tree back at `6035c9d7`, `git status` clean of tracked changes)
| gate | mutation | result |
|---|---|---|
| G5 `p4a_untouched_regions.sh` | `(void)0;` inside `RingAvailable`, committed | **rc 1**, `RingAvailable` named, sha row moves |
| G9 `gen_pipe_dirty_surface.py --check` | `SetBlendFunc` row drops `NEW_PIPELINE_STATE` | **rc 1** "MISSING publisher NEW_PIPELINE_STATE for SetBlendFunc" |
| G9 same | `UseProgram` row drops `NEW_SAMPLER_VIEWS|NEW_SHADER_IMAGES`, marks kept | **rc 1** "STALE undecided mark" ×2 |
| G9 same (first attempt) | row AND undecided marks dropped | **rc 0** — blind (m-6, declared) |
| G7 `p4a_descriptor_negative_control.sh build-push` | its own two field drops | **rc 0**: `Layered` (FramebufferEmit.h, 3 assignments neutralised) tripped, `borderColorForm` (SamplerEmit.h) tripped, both suites green again after restore; tree clean |
### 4.2 Mutations from the first attempt (same worktree, `~/w7/p4a-finalreview-exp.log`)
| gate | mutation | result |
|---|---|---|
| P4aSeamAudit F-3 | delete `MGP_NOTE_AGGREGATE(FramebufferAttachment)` at `TextureObject.cpp:83` | `ATextureRespecifiedWhileAttachedReachesTheFramebufferRecord` **red** |
| G9 white-box | delete `SyncReadFramebufferTextureAttachments(...)` at `DirectGLES.cpp:2309` | `AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver` **red** (6402 ≠ 6401) |
| G12 / D-K2 | `PipeSubsystemDependencyMissing` returns false | `ObjectSubsystemControl.Refused.…ASamplerBitWithoutTheTextureBitIsRefusedAndNamed` **red**, names 0x9ff and the two bits |
### 4.3 Standing observations on the gates
* `.github/workflows/test.yml:9-12` still carries the **TEMPORARY** `feat/disaggregated` trigger — left
in place as instructed; the integrator removes it at the `dev` merge. `BASELINE: "37da3c3a"` at
`:1599`; `--expect-probes 4` at `:802` pinned with `check_include_closure.py`'s PROBES list.
* G2 (pull == push test names): not re-taken here (the review's pull tree has no test binaries);
gates-v3 §6 row 2 is the standing evidence.
* The subdata-refusal line (`resource_subdata for texture {…} level N was refused`,
`TextureEmit.h:1092`) is not one of the ten census shapes esprytdraw §6.1 greps, and no itest reads
`RefusedSubDataCount`. Add it to the post-merge census (it is C-2's tell).
* `ctest` re-runs on the final tree this round (`build-push`, llvmpipe/lavapipe):
`-R 'ObjectSubsystemControl|TextureParamsWithoutASamplerView|TextureUploadShape|P4aSeamAudit|HandleRecycle'`
**181/181**; `-L unit -R 'TextureEmit|FramebufferEmit|SamplerEmit|ImageEmit|ProgramEmit|Tracker|CompositeResolver|PipeCatalogue|ResourceEmit|Sanity|ProgramArtifacts'`
**304/304**. Green — and, as §1 shows, green over both criticals: none of the 181 defines a level
around a verb or deletes a texture with a level on the drain list.
---
## 5. Recorded for later (owner, phase)
| # | item | owner | phase |
|---|---|---|---|
| R-1 | M-A producers for `kMGPipeBindSampler` / `kMGPipeBindShaderImage` + the remint counter `ROADMAP.md:85` asks for | C | before D.5 docs if cheap, else P3b/P4b |
| R-2 | m-1 F-7: `MGPipeApplySetTextureParams` returns `Bool`; latch on acceptance | A + B | with the C-1/C-2 rework (same files) |
| R-3 | m-4 F-6: image-access / sampler-view target / draw-buffer encodings stated once in the contract | contract | P4b |
| R-4 | m-6: G9 derivation for `UseProgram` / `BindVertexArray` (the `attachedShaders` / `Access` undeclared-member taint) | A | P4b |
| R-5 | SD-5: `0x7ff` half-run — c0g's table now refuses it on the client; the server's table (`ResolveTextureResourceSubsystemArm`) is the same four rows; keep both lists in one place | D | P4b |
| R-6 | `g_rawDepthFetchSamplerState` (a frontend `SamplerObject` inside `MG_Backend`, synced through the "object is the authority" branch `Managers.cpp:12361-12372`) — the one place the handle arm reads a frontend object on purpose (S-1, audit §B) | D | P3b/P4b (`ROADMAP.md:23`) |
| R-7 | m-5: `GenerateThreeChannelFloatMipmapOnCpu` rearm | D | P4b |
| R-8 | `ProgramArtifacts.h:563-565` NDK/libc++ size pin still inert (brief D.5 chore) | integrator | D.5 |
| R-9 | Post-merge census must include the retrace logs (`grep -c 'no applier record\|does not describe\|declining the built-in\|cannot be pushed\|was refused' retrace-out/*/*/DirectGLES/output/mobilegl.log`) — audit §B's correction plus C-2's line | integrator | D.3 re-run |
| R-10 | `HandleRecycle.AbaControl` for the six P4a kinds is inert on both backends (no `PipeHandleAbaControl` consumer over the object slot tables; the cases say so and assert the correct pixels) — a real control needs one `if` in `GetOrCreateByHandle` | D | P4b |
| R-11 | `TextureUploadShapeScenario` recorded, not gated (D-D4) — becomes a gate with the Mali delta | F | P3b/P4b |
| R-12 | m-8 tooling: nested-worktree `include/ska` `.git` pointer in `wsl_tree.sh`-shaped trees | tools | now |
---
## 6. D.5 docs checklist (state at `6035c9d7` / `a38bdab4`)
All D.5 placeholders are still unfilled; `scripts/check_doc_citations.py docs/Disaggregated/*.md` must
be run after each.
| doc line | brief asks | state |
|---|---|---|
| `README.md:3` | status → P4a landed + hash; next P3b/P4b, P5 | not updated |
| `ROADMAP.md:3` | — | still "P3a 已落地 … 下一步 P4a" |
| `ROADMAP.md:20` | ✅ + the real numbers (15 calls, 6 kinds, memos retired, two red-before logs, CTS blocks, T3) | not marked |
| `ROADMAP.md:23` | what P4a left to P3b/P4b (D-Q table) | not updated |
| `ROADMAP.md:67` | 39-day checkpoint: actual elapsed days per package | "P4a > 39 天 | 同上" unfilled |
| `ROADMAP.md:85` (Q2) | texture-remint pull rate | not updated — and NOT MEASURABLE on this tree (M-A) |
| `ROADMAP.md:91` (Q8) | one reflection archive, Espryt half | not updated |
| `ROADMAP.md:100` (Q17) | `create-indirect` state at exit + fix the `:7`→`:98` citation | not updated (SD-0 fixed it; say so) |
| `ARCHITECTURE.md:63` | [deviation] D-F2 identity-addressed sampler views for Espryt | not updated |
| `ARCHITECTURE.md:100` | read-attachment-only parameter gap closed, scenario red-first | not updated |
| `ARCHITECTURE.md:134` | [deviation] D-E1 `MGPTextureParams` 40 bytes + built-in sampler CSO | not updated |
| `ARCHITECTURE.md:136` | `MGPFramebufferState::Target`, `Complete` = `CheckCompleteness()` (D-C3); add `Named` (ID-27/D-I2) | not updated |
| `ARCHITECTURE.md:212` | `CompositeResolver` file + two release paths | not updated |
| `ARCHITECTURE.md:249-254` | drain list is P4a's, cursor is P3b/P4b's, `TextureUploadShapeScenario` built/gated | not updated |
| `ARCHITECTURE.md:261` | `ProgramArtifactsCodec.{h,cpp}`, verify-only | not updated |
| `ARCHITECTURE.md:294-295` | `kNeedsAck` narrowed to the buffer target (D-A2) | not updated |
| `ARCHITECTURE.md:318/:321` | P4a's six byte-identical rows beside P3a's eleven (now 17 rows in `p4a_untouched_regions.sh`) | not updated |
| `ARCHITECTURE.md:323` | `g_rawDepthFetchSamplerState` still a frontend object inside the backend | not updated |
| `ARCHITECTURE.md:369` | `MOBILEGL_PIPE_LEGACY_MEMOS` P4a arm + the +1 day | the only P4a mention in the file; the day is not recorded |
| `ARCHITECTURE.md:598` | push default `0x1fff`, bits 9-12, three dependency refusals (there are four: add 10→11) | not updated |
| `MEASUREMENTS.md` | new numbered P4a section (D.4.2 table with the acc/draw caveat above it, D.4.3 headline numbers, T1/T2/T3 + `mc_state_toggle`, six counters, four suppressors, per-bit fire rates, two red-before logs, Track H census, CTS blocks, peak-RSS hedge) | no P4a section; DriverBench rows exist in `~/w7/p4a-bench.log` (e.g. magma `mc_pass_switch` pull 518785.6 / push 513177.1 / native 475307.8) — transcribe with the two-device A/B |
| `MEASUREMENTS.md:465` | reading (5) discharged: CSO blob byte class numbers | not updated |
| `MEASUREMENTS.md:519` | `g_uploadRing` reset asymmetry still open + `ScopedDefaultUnpackState::s_synced` (D-O) beside it | not updated |
| `ProgramArtifacts.h:563-565` | NDK size pin (chore) | inert |
Two additions the brief did not foresee: (a) the C-1/C-2 rework and the `MGPRespecifiedLevel` rule
belong in `ARCHITECTURE.md:249-254`'s texture paragraph ("the client passes the level it redefines;
whole-resource calls pass none"); (b) `ARCHITECTURE.md:598` should list the FOUR dependency rows.
---
## 7. Public-GL sequences still uncovered by the retrace / itest lanes (audit classes extended), ranked
1. **Per-level definition around a verb** (C-1): `glTexImage2D(L0)`; verb; `glTexImage2D(L1)` — also the
`glCopyTexImage2D`, `glCompressedTexImage2D`, cube-face and texture-view forms. No fixture, no itest.
2. **Upload-then-generate around a verb** (C-1/4): `glTexImage2D(L0)`; verb; `glGenerateMipmap`.
3. **Dirty-then-delete** (C-2): a level on the drain list when the last reference drops. CTS negative
tests and `packed_pixels` do this constantly; G15 is the first place it will run.
4. **Image-unit-only textures across program switches** (M-A/F-2): bound with `glBindImageTexture`,
never sampled, program changes the window — F-2's itest covers the window; nothing measures the
remint.
5. **Sampler-object binding churn** (`glBindSampler` on registered samplers across many units) — SD-1's
two scenarios are the only coverage of the registered-sampler CSO path; no retrace fixture binds
application samplers (audit §B: zero occurrences in the 20 traces).
6. **Framebuffer death while bound / recycled name with a Named record pending** — HandleRecycle covers
the bound case; DSA-configured-then-deleted-then-recycled (Named record on a slot whose Gen moved)
is only covered by `FramebufferRecordFor`'s loud refusal, not by a scenario.
7. **Level-scoped respecify of a cube face while the other faces are pending** — gates' MINOR-1 unit case
pins the applier; no GL-level case.
8. **Texture views over a mutable owner redefined per level** (class of 1).
9. **`glTexParameter*` refused-then-repeated** (m-1): the latch-before-acceptance shape has no lane
because the refusal needs a texture without an applier record (S-1/SD-3 shape), which the fixes
removed; a `MOBILEGL_PIPE_PUSH` mask that arms bit 10 without a consumer (`NoConsumer` lane) is the
place to add it.
10. The `0x7ff` / `0x5ff` half-masks with a REGISTERED sampler bound (SD-5 was measured without one).
---
## 8. What the integrator must re-run
After the C-1/C-2 rework lands (B + A; and R-2 if taken with it):
1. `-L unit` on pull, push and verify; the two probe cases from §2.2 and the two itest cases from §2.1
(cases 1, 4, 6) added as permanent tests, with case 6's lane carrying `MALLOC_PERTURB_=165`.
2. `ctest -L integration-gpu` on `build-push` at `0x1fff`, `0x1ff`, `0x9ff`, `0x5ff`, consumer /
no-consumer, plus `-L integration-verify` — the 1079/1079 answer gates-v3 §6 names.
3. The full retrace at the default mask (79 cases) AND the retrace-log census of R-9 (the ten shapes +
`was refused` must all be zero).
4. `p4a_untouched_regions.sh 37da3c3a HEAD` + `--self-test`; `p4a_descriptor_negative_control.sh`;
`gen_pipe_dirty_surface.py --check`; the include-closure step.
5. G1 symbol report (`symbol_report.py --fail-on-symbol-set-change --fail-on-added-bytes 0`) — the
rework touches `PipeMutation.h` / `TextureObject.h` / `TextureObject.cpp`, all of which must stay
`#if MOBILEGL_PIPE_PUSH`-guarded on the pull side.
6. The device A/B and DriverBench rows are unaffected by the rework's mechanism but the two-device
Release A/B must be re-taken on the rework head before the numbers go into `MEASUREMENTS.md`.
7. Remove the TEMPORARY trigger at `test.yml:9-12` in the `dev` merge commit; D.5 docs (§6);
`check_doc_citations.py`; G15 scheduled after the verdict.
---
## 9. Artefacts and cleanup
* Kept beside this report in `~/w7/notes/p4a/p4a-results/final-review-v1-logs/`: the probe
scenario `FinalReviewC1Scenario.cpp` (drop-in for `MG_IntegrationTest/Scenarios/`, add one line to
the CMake list), the two unit probes `finrev-repro.py` / `finrev-repro2.py` (they splice a `TEST`
into `TextureEmitTest.cpp`), the itest run logs `c1-{handles,legacy,perturb,perturb-legacy}.log`,
the gate-mutation outputs `g5-*.err` / `g9-*.out` / `g7.log`, the ctest subset logs, the four
`nm -S` symbol tables of §3, and the first attempt's `p4a-finalreview-exp*.log`.
* Removed: the worktrees `~/w7/p4a-finalreview` and `~/w7/p4a-finalreview-base` (`git worktree
remove --force` + `prune` from `~/w7/pipe`), their build dirs, `~/w7/finrev-g1/` (42 MB of `.i`)
and the first attempt's `~/w7/p4a-finalreview-*.log`. `pipe` itself was never checked out, edited or
committed to (HEAD `a38bdab4`, no tracked change).
@@ -0,0 +1,28 @@
# MobileGL symbol report
| side | path | file bytes | .text |
|---|---|---|---|
| before | `/home/swung/w7/p4a-before-libMobileGL.so` | 19114360 | 10806323 |
| after | `build-linux/libMobileGL.so` | 19114360 | 10806323 |
`.text` 10806323 -> 10806323 (+0, +0.000%). 27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed, 27072 unchanged.
### Removed (0)
_none_
### Added (0)
_none_
### Resized (0)
_none_
### Renamed only (same size) (0)
_none_
@@ -0,0 +1,328 @@
# P4a final-review fix round - finalfix-v1 (2026-09-09)
**Branch** `refs/heads/p4a/finalfix`, worktree `~/w7/p4a-finalfix`, base `refs/heads/feat/disaggregated` =
`a38bdab4` (= the gated P4a code head `6035c9d7` + the tools-only harness commit). **HEAD `8c458cd5`**, five
commits, **not pushed**, working tree clean. Charter: `final-review-v1.md` C-1 / C-2 / M-A / the minors and
INTEGRATOR-DECISIONS ID-52 (B is past two reworks, so the round is fable's with an integrator grant across
B's files, the contract, the applier, Espryt and one new scenario file). Every fix has a scenario that was
RED on the unfixed tree and is GREEN with the fix, taken on this tree (section 2); the full gate on the head
is in section 4.
## 0. Verdict in brief
* **C-1 fixed.** The storage entry points state WHICH storage a respecify replaces (one level, a chain cut,
the whole resource); the emitter builds wire's `MGPRespecifiedLevel` with the drain's own packed target
and passes it; a per-level respecify is never deduped on the descriptor; the applier drops a named level
whether or not the descriptor moved (a refinement of wire's W11 clause, section 3). The review's two
llvmpipe scenarios read a 100 % black level 0 before and red after; the three controls are red on every
arm.
* **C-2 fixed.** The six death helpers forward to the emitters between the wire delete and the slot free
(ID-8's order): the texture emitter drops the dead handle's drain entries, its raw pointer, the built-in
sampler's cache reference and its latches; the renderbuffer, framebuffer, sampler-view and shader-CSO
memos are retired the same way; `ResolveTexture` refuses a dead slot loudly on `IsLive`. `glTexImage2D;
glDeleteTextures; draw` was SIGABRT (`pure virtual method called`) / SegFault under `MALLOC_PERTURB_` and
is green on both backends, for every P4a kind and for a recycled slot.
* **M-A fixed.** `kMGPipeBindSampler` is produced by the sampler-view resolution and
`kMGPipeBindShaderImage` by `glBindImageTexture`'s state setter (so the hint precedes the first sync) and
by the image walk; both through a new contract door because neither caller may include `TextureEmit.h`.
`ImageBindableHint` reaches the applier as ID-18 M4's metadata respecify (pinned end to end, kept
upload included), and ROADMAP open question 2 is measurable: **PipeStats `tex-remint-pulls`, `trp=` on
the summary line** - one per texture Espryt had already allocated and had to re-mint image-bindable.
* **Minors:** m-1/F-7 done (`MGPipeApplySetTextureParams` returns `Bool`, the emitter latches on
acceptance), m-2 (Config.h's fourth row), m-3 (the "ORed" comment). Going loud on m-1 surfaced one real
residual in the retrace census - the context's default textures are born before the backend registers
its consumer, so their first `glTexParameter*` was refused and silently latched away - fixed by healing
the record from the params path (commit 5). m-4, m-5, m-6, m-7, m-8 declared (section 5).
* Gate on `8c458cd5` (section 4): G1 0/0/0/0, G5 rc 0 x 4, purity rc 0 x 5, unit **1785 x 3**, G2
2902 == 2902, G14 0 removed / +314, integration-gpu **1117/1117 at 0x1fff, 0x1ff, 0, 0x9ff, 0x5ff, pull
and `ESPRYT_DISABLE_INVALIDATE_FLUSH=1`** (DirectVulkan 559/559), verify **920/920 zero Fatal**, retrace
**79/79**, retrace refusal census **0 on 16 needles**, itest eight-family census **0 lines / 0 tests on
13 rows**, every negative control tripped.
## 1. Commits (branch `p4a/finalfix`, from `a38bdab4`)
| # | hash | what |
|---|---|---|
| 1 | `173f1dd2` | C-1: the level scope of a texture respecify (contract hook + enum, PipeFill forward, TextureObject{,2DCube} call sites, the emitter's three-scope body, the applier's precedence, W11's test clause, 3 unit cases, the scenario file + peek TU + 5 itest cases) |
| 2 | `a690032f` | C-2: the death path forwards to every emitter; loud dead-slot refusal; gen-stamped mask producers; 6 unit cases (texture x4, framebuffer, program), 6 itest cases + the `MALLOC_PERTURB_=165` lanes |
| 3 | `9f60aadc` | M-A: the two bind-bit producers through `MGPipeNoteTextureBoundAs` / `MGPipeNoteTextureImageBound`; `tex-remint-pulls`; 2 unit cases (sampler, image), 1 itest case, 2 peeks |
| 4 | `c2c6a655` | m-1/F-7 (`Bool` from set_texture_params, latch on acceptance, `RefusedParamCount`), m-2 (Config.h), m-3 (MGPipeTypes.h); 1 unit case |
| 5 | `8c458cd5` | the retrace census's residual once m-1 went loud: set_texture_params heals a record the applier never received (create, storage if any, params); the F-7 case reshaped around a refusal on the merits; 1 unit case |
Five single-line `[Type] (Scope): description` messages, no attribution trailer. Each commit was compiled
and run with ONLY its own tests (the shared test files were trimmed per commit before `git add` and the
trimmed suites run: TextureEmit 41/45/45/46/47 on both builds, the itest lane 10/24/26/26/26), so every
intermediate commit is green on its own.
## 2. Finding by finding: root cause, change, scenario, red/green
### 2.1 C-1 - the client never passed the level a respecify redefines
**Root cause.** `TextureEmit.h`'s `ApplyRespecify` called `MGPipeApplyResourceRespecify(desc, nullptr)` at
every texture respecify; the applier's whole-resource arm then cleared the record's entire pending-upload
set. `AllocateStorage` is per `(uploadTarget, level)` and the descriptor carries only the base extent and
the level count, so a level the applier had ACCEPTED at one verb (client flag already clear, D-D5 step 1)
and that the next verb's `glTexImage2D(level 1)` or `glGenerateMipmap` grow defined AROUND was owed by
nobody. wire-v3 §5 item 5 required B to pass the key; no review checked it.
**What changed.**
* `MG_Pipe/PipeMutation.h:334-352` - `enum class MGPipeTextureRespecifyScope { WholeResource, OneLevel,
LevelsFrom }` and `MGPipeEmitTextureResourceRespecify(ITextureObject&, scope, Uint32 uploadTarget,
Uint32 level)`; every caller states its scope, "whole resource" is said, never defaulted.
* `MG_Impl/Pipe/PipeFill.cpp:1258` - the forward.
* `MG_State/GLState/TextureState/TextureObject.h:239-240`, `TextureObject.cpp:87-104` -
`PipePublishLevelDescriptor(uploadTarget, level)` / `PipePublishTruncatedDescriptor(uploadTarget,
levelCount)` beside the whole-resource `PipePublishDescriptor()`; `AllocateStorage` (`:517`) and
`TruncateMipmapLevels` (`:527`) call them; the cube twins at `TextureObject2DCube.cpp:39/:47` (the face
rides in `uploadTarget`). The view forwards to its owner's `AllocateStorage`, so a per-level definition
through a view keys the OWNER's level; the backend's own generate-mipmap grow
(`DirectGLES.cpp:8074`) goes through the same `AllocateStorage` and is level-scoped for free.
* `MG_Impl/Pipe/TextureEmit.h:626-720` - `EmitResourceRespecify(texture, scope, uploadTarget, level)`:
`OneLevel` builds one key `{MGPipePackSubDataTarget(resourceTarget, uploadTarget), level}` - the SAME
packed `MGPSubData::Target` the drain writes at the sub-data emission - and is NEVER deduped on the
descriptor (a non-base level redefined at a new size moves no descriptor field, and the applier's box
against the old level would be uploaded past the end of the new one); `LevelsFrom` spells the cut as one
call per removed level `[level, LastDesc.Levels)` (the applier's key is one level; a cut at 0 is the
whole resource; a cut that removes nothing the applier could hold is deduped like the whole-resource
form); `WholeResource` keeps the byte dedupe. `RespecifyOnce` (`:1124`) carries the refusal self-heal;
`ApplyRespecify(desc, level)` (`:1107`) takes the key; `RepublishMask` passes `nullptr` deliberately
(wire-v3 §5 item 6) and says so; the renderbuffer twin passes `nullptr` (no levels).
* `MG_Pipe/PipeApply.cpp:1691-1703` - precedence: a **named level is dropped whether or not the
descriptor moved**; a null level with identical storage fields is the metadata update that drops
nothing; a null level with moved fields clears all. `PipeApply.h:787` and `MGPipeTypes.h:1103-1108`
state the rule; the W11 test clause is rewritten to the same rule (section 3).
**Scenario and proof** (`MG_IntegrationTest/Scenarios/P4aFinalFixScenario.cpp`, DirectGLES-asserted,
skipped by name on DirectVulkan where no P4a consumer exists; `MG_Test/Pipe/TextureEmitTest.cpp`).
| case | before (a38bdab4 + the tests) | after (173f1dd2) |
|---|---|---|
| `PerLevelDefinitionAcrossAnUnrelatedDraw` (`L0(red); draw(other); L1; draw(T)`) | **black, 11625/11625 px** | red |
| `GenerateMipmapAcrossAnUnrelatedDraw` (`L0(red); draw(other); glGenerateMipmap; draw(T)`) | **black, 11625/11625 px** | red |
| controls `ConsecutiveDefinitionsNoVerbBetween`, `LevelZeroConsumedBeforeLevelOne`, `GenerateMipmapImmediately` | red | red |
| unit `ALevelDefinedAfterAnEmittedButUnconsumedUploadKeepsThatUpload` (`:1300`, the review's probe through the real `AllocateStorage`) | **Failed** (level 0 not pending, flag CLEAR) | Passed: both levels stand after the next drain |
| unit `AChainTruncationKeepsTheSurvivingLevelsPendingUploads` (`:1346`) | **Failed** (the cut took level 0's upload) | Passed: level 0 kept, level 2 gone |
| unit `ARedefinitionOfANonBaseLevelAtANewSizeDropsOnlyThatLevelsPendingUpload` (`:1377`) | **Failed** (deduped: the 8x8 box survived onto a 4x4 level) | Passed: level 1 gone, level 0 kept, serial moved |
The five itest cases run at 0x1fff, 0x1ff, 0 and on the pull build (26/26 each arm at the head).
### 2.2 C-2 - a dead handle resolved to freed memory in the drain
**Root cause.** `ResolveTexture` guarded with `GenOfSlot == handle.Gen`, but the allocator moves a slot's
generation only at the NEXT hand-out; between a death and a recycle the dead handle compared equal, the
emitter still held the freed `ITextureObject*`, and nothing removed the slot's drain entries - the six
death helpers freed the slot and told no emitter. `EmitOneLevel` then called virtual `GetStorageType()`
on the freed object from the next validate point.
**What changed.**
* `MG_Impl/Pipe/PipeFill.cpp:1405/1429/1467/1493/1525` - the sampler-view, texture, renderbuffer,
framebuffer and shader-CSO helpers forward to their emitter AFTER the wire delete and BEFORE
`NotifyAndFree` (ID-8: delete, notice, free). The sampler CSO forwards to nothing, stated: content-
addressed, no per-object entry (ID-17). Unconditional in a push build, like the mints (the entries exist
whether or not the family bit is set; the 0x1ff / 0 arms run the same path).
* `MG_Impl/Pipe/TextureEmit.h:457-513` - `ResolveTexture` refuses on `!MGPipeSlots().IsLive(...)`,
counted (`DeadResolveCount()`, `:974`) and `MGLOG_E_ONCE` - reaching it means a death path skipped the
emitter; `NoteTextureDied(handle)` (`:487`) drops the handle's `m_drain` entries and `DrainKeys`,
releases the built-in sampler's cache reference (at the death now, no longer first at the recycle),
resets the entry; `NoteRenderbufferDied` (`:509`); `MaskOf` refuses a stale generation; the two mask
producers stamp the generation they write under (`:423-425`, `:434-435`, `:545-546`, `:564-565`) so a
texture born while the family bit was clear has an entry a gen-keyed reader can see. `RetireIfRecycled`
stays as the belt.
* `MG_Impl/Pipe/FramebufferEmit.h:400-410` - `NoteFramebufferDied` (the per-object Named latch) and
`NamedRecordIsLatched` for the case. `SamplerEmit.h` / `ProgramEmit.h`'s existing
`NoteRecordDestroyed` ("no production caller today") now have one; comments say so.
* `MG_IntegrationTest/CMakeLists.txt` - `DirectGLES.MallocPerturb.` / `DirectVulkan.MallocPerturb.`
registrations of the dirty-then-delete case with `MALLOC_PERTURB_=165` (the review's §8 item 1).
**Scenario and proof** (both backends, every arm).
| case | before | after (a690032f) |
|---|---|---|
| `ADirtyTextureDeletedBeforeAnyVerbIsWalkedByTheNextDrain` (8 x `glTexImage2D; glDeleteTextures; draw(other)`) | **SIGABRT `pure virtual method called`** (DirectGLES); **SegFault** under `MALLOC_PERTURB_=165` | white 8/8 on both backends, both lanes |
| `ATextureRecycledOntoTheDeadSlotDoesNotInheritItsDrainEntry` (ABA) | pass (the recycle's Gen already refused it) | pass |
| `ARenderbufferAndItsFramebufferDeletedAfterAClearLeaveTheNextDrawIntact`, `ASamplerObjectDeletedWhileBoundLeavesTheNextDrawIntact`, `AProgramDeletedWhileInUseLeavesTheNextDrawIntact`, `AFramebufferDeletedAfterADsaClearLeavesItsAttachmentIntact` | pass | pass |
| unit `ADeadTexturesHandleResolvesToNothingAndLeavesTheDrainList` (`:1410`, the review's probe) | **SegFault** (the freed pointer resolved) | Passed: null, drain list 0, `DeadResolveCount` 0 |
| unit `ATextureRecycledOntoADeadSlotDoesNotInheritTheDrainEntry` (`:1458`) | **Failed** (drain list still 1 after the death) | Passed: 0 after the death, the successor's own level goes out |
| unit `ADeadRenderbuffersEntryIsRetiredWithItsSlot` (`:1484`) | **Failed** (the dead handle still read its sticky mask) | Passed |
| unit `ADeadTexturesSamplerViewLatchIsRetiredAtItsDeath` (`:1440`), `FramebufferEmit.ADeadFramebuffersNamedRecordLatchIsRetired` (`:782`), `ProgramEmit.ADeadProgramsRecordLatchIsRetiredAtItsDeath` (`:781`) | (added with the fix; the stale latches read as published between death and recycle on the unfixed tree) | Passed |
| `ARecycledTextureSlotDoesNotInheritItsPredecessorsBindMask` gains: the cache reference is back at the DEATH and the dead handle reads mask 0 | - | Passed |
### 2.3 M-A - no producer of `kMGPipeBindSampler` / `kMGPipeBindShaderImage`
**Root cause.** `NoteTextureBoundAs` had one caller (the framebuffer emitter, the two attachment bits).
`SamplerEmit.h` and `ImageEmit.h` are included BY `TextureEmit.h` and could not include it back;
`TextureState.h` is `MG_State` and may include no emit header. Nothing set either bit, `ImageBindableHint`
was always 0, the metadata respecify had no live trigger, and the remint pull was neither prevented nor
counted.
**What changed.**
* `MG_Pipe/PipeMutation.h:379/384`, `MG_Impl/Pipe/PipeFill.cpp:1293-1307` - `MGPipeNoteTextureBoundAs(
MGPipeHandle, Uint32 bindBit)` and `MGPipeNoteTextureImageBound(ITextureObject&)`, the birth hooks'
shape (declared in the one door, defined beside the other hooks, forwarded through
`ForwardWhenWired<kMGPipeWiredTextureSubsystem>`); not gated on `FamilyIsLive` because the mask is
client state and the emission it causes is gated inside the emitter.
* `MG_Impl/Pipe/SamplerEmit.h:774` - the sampler-view resolution notes SAMPLER on every texture it names
in an emitted `MGPBoundView` (D-A4's letter). `MG_Impl/Pipe/ImageEmit.h:106` - the image walk notes
SHADER_IMAGE. `MG_State/GLState/TextureState/TextureState.h:43` - `ImageTextureBinding::Bind` notes
SHADER_IMAGE at `glBindImageTexture` itself (push-only), so the hint reaches the applier BEFORE the
texture's first sync - the prevention half's whole point.
* `MG_Util/Metrics/PipeStats.h:166`, `PipeStats.cpp:178/459`, `MG_Backend/DirectGLES/Managers.cpp:5260,
5338-5340` - `CallClass::TextureRemintPulls` ("tex-remint-pulls", `trp=` on the summary line, push-
only so the pull enum is unchanged), counted in `RequireImageBindableStorage` once per transition that
replays a level of storage the backend ALREADY HELD (`hadBackendStorage`); a texture reaching the
transition uninitialised is allocated image-bindable up front and pulls nothing. **This is the counter
for ROADMAP.md:85 (open question 2):** read `trp=` off the periodic `MGPipe stats:` line
(`MOBILEGL_PIPE_STATS=1`) on the MC / Iris fixtures.
* `Harness/P4aFinalFixPeek.{h,cpp}` - `PeekPipeTextureResourceRecord` (by GL name),
`PeekPipeStatsTextureRemintPulls`, `PeekPipeStatsTextureUploadEmissions` (arm the counters in-process).
**Scenario and proof.**
| case | before | after (9f60aadc) |
|---|---|---|
| unit `SamplerEmit.AResolvedSamplerViewMarksItsTextureAsSamplerBound` (`SamplerEmitTest.cpp:1098`) | **Failed** (mask 0) | Passed; a texture no sampler uniform resolves keeps mask 0 |
| unit `ImageEmit.AnImageBoundTextureIsMarkedShaderImageBoundAtTheBind` (`ImageEmitTest.cpp:528`) | **Failed** (mask 0 after the bind and after the walk) | Passed at the bind and in the emitted set |
| `AnImageBindAfterAllocationReachesTheApplierAsAMetadataRespecify` (DirectGLES; `glTexStorage2D` + red, draw, blue subimage drained by an unrelated draw, `glBindImageTexture`) | **Failed**: `ImageBindableHint 0`, `BindMask & (1<<6) == 0`, serial 5 vs 5 unmoved | Passed: hint 1, bit set, serial moved, picture blue, **`trp` +1** for the texture allocated before its hint and **+0** for a second texture image-bound before its first sync; then the KEPT half on that second texture: a DSA attachment's RENDER_TARGET bit (a Named record, no sync in between) reaches the record as a metadata respecify with the blue upload still standing beside it, and the next draw is blue |
A note on the case's shape: Espryt syncs a texture eagerly inside `glBindImageTexture` and the widening
re-mints its storage, replaying every level from the shadow, so on the first texture the standing upload
is CONSUMED by that regeneration whatever the metadata respecify did - which is why the "kept" property is
proved on the second texture (image-bindable already, a new bit, no remint in the way), with Espryt's own
upload count telling a consumed upload from a dropped one.
### 2.4 The minors
* **m-1 / F-7 (c2c6a655).** `MG_Pipe/PipeApply.{h,cpp}:1010/2482` - `MGPipeApplySetTextureParams`
returns `Bool` (false on no consumer, no record, null built-in sampler; true on store).
`TextureEmit.h:739-837` - the latch (`HasParamsLatch` / `ParamsVersion` / `SamplerVersion` /
`ForceParamsResync`) is written only after acceptance; a refusal is counted (`RefusedParamCount()`,
`:966`) and logged once. Unit `ARefusedParamsRecordDoesNotAdvanceTheLatch` (`TextureEmitTest.cpp:1511`):
with the pre-fix latch order the refused record advanced the latch and the record never learned the LOD
write (`ParamCount` +1 not +2, `ParamsSerial` unmoved, `LodBias` 0 vs 0.5) - **RED**; with the fix
**GREEN**. The case was reshaped twice during the round (its first shape never emitted the refused
record - `MakeTexture2D`'s format setter had already latched - and its second shape lost its premise to
commit 5's heal); the final shape drives the emitter directly under `ScopedNoResourceOps`, where the
applier's belt refuses both the parameters and the healing create, and its red/green was re-taken with
the latch-order toggle (transcript in `finalfix-v1-logs/`).
* **The residual m-1 uncovered (8c458cd5).** With the refusal loud, the retrace census found 2 lines
(`set_texture_params for texture 0 {slot=2, gen=0} was refused`): the context's default textures are
constructed (`TextureState.cpp:68`) before the backend registers `MGPipeResourceOps`
(`Managers.cpp:2556`), so their create never went out, and an application's first `glTexParameter*` on
texture 0 found no record - silently latched away before m-1. `TextureEmit.h:805-831` heals the record
from the params path the way `EmitResourceRespecify` heals it: a create with no storage for the
identity, the storage itself if the texture has any (a respecify against the create's descriptor is
never deduped), then the parameters; `Entry&` is re-fetched across the respecify (the table can grow).
Unit `ATextureBornBeforeTheConsumerRegisteredGetsItsRecordFromItsFirstParamsPublication` (`:1548`):
**RED** (refused, no record healed) / **GREEN** (record with its 8x8 storage, `ParamsSerial` 1, the LOD
bias; and a storage-less texture heals to an identity-only record). The retrace census is 0 on the head.
* **m-2 (c2c6a655).** `Config.h:336-341` - `0x400 ... requires 0x80 AND 0x800`, naming
`kMGPipeP4aFamilyDependencies` and ID-15.
* **m-3 (c2c6a655).** `MGPipeTypes.h:1110-1114` - the applier replaces the descriptor WHOLE with the one
the client sent; the mask in it is the client's sticky OR, so no bit can be lost; "ORed, never replaced"
is gone.
## 3. Judgement calls and deviations from the charter
* **The applier's precedence (C-1).** wire's W11 clause read "a metadata update drops nothing, whatever
`level` says". The client's only metadata caller (the mask republish) passes `nullptr`, and a
per-level caller cannot be deduped on the descriptor (a non-base level's extent is not in it), so a
named level with identical storage fields is now that level's redefinition and drops exactly that key.
`ARespecifyThatRedefinesNoStorageCarriesTheStickyMaskAndKeepsThePendingUploads` keeps its null-level
half and gains the named-level half (its immutable store has two levels now so level 1 exists for the
validator). Contract grant; stated in `PipeApply.h:787`, `PipeApply.cpp:1680-1690`, `MGPipeTypes.h`.
* **A per-level respecify is never deduped.** One applier call per `glTexImage*D` / generated-mip grow
instead of a byte compare; the sub-data that follows moves the serial anyway, and on the handle arm an
unchanged descriptor with a moved serial costs Espryt one bind and an empty level loop
(`Managers.cpp:6470-6520`: `needsRegeneration` compares the descriptor, not the serial).
* **`LevelsFrom` as N calls.** The contract's key is one level; a chain cut is spelled as one call per
removed level rather than a new contract type. Belt-and-braces in practice: every frontend path that
cuts a chain has already redefined or is about to redefine the surviving base
(`DiscardMipmapChainOnBaseRespecification`, `glTexStorage*`'s loop), but the unit case pins the rule.
* **Files outside the listed grant** (ID-52's charter names the mechanisms, the grant list names B, the
contract, the applier, Espryt and one scenario file): C's `SamplerEmit.h` / `ImageEmit.h` /
`ProgramEmit.h` (the D-A4 placements and the death forward; 1 + 8 + 14 lines), B's `FramebufferEmit.h`
(the death forward), A's `PipeStats.{h,cpp}` (the counter; push-only), `MG_State/.../TextureState.h`
(B's directory; the eager image-bind note), C's `SamplerEmitTest.cpp` / `ImageEmitTest.cpp` /
`ProgramEmitTest.cpp` and B's `FramebufferEmitTest.cpp` (one case each, with pull twins), and F's
`MG_IntegrationTest/CMakeLists.txt` (two source lines + the two `MallocPerturb` registrations the
review's §8 asked for). Every one is additive.
* **A second harness TU** (`Harness/P4aFinalFixPeek.{h,cpp}`, fablefix's precedent): a scenario TU cannot
include `PipeApply.h` beside the GL prototype headers and F's `PipeApplyPeek.cpp` is not mine to edit.
* **Five commits, not four**: the heal is the census's finding on the round's own m-1 work and is kept as
its own commit (with the F-7 reshape it necessitated) so the history says who found what.
* **The C-1 / M-A itest cases assert on DirectGLES only** (skipped by name on DirectVulkan, which
registers no P4a consumer - the handle arm is inert there by design); the C-2 cases run on both
backends (ID-8: the death path is backend-neutral and the DirectVulkan lane must see it).
## 4. Gates on `8c458cd5` (one detached script, `-j 8`, `CCACHE_BASEDIR=/home/swung/w7`, `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`)
| gate | result |
|---|---|
| builds | build-linux / build-push / build-verify rc 0, **0 warnings** each |
| G1 `symbol_report --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` vs `~/w7/p4a-before-libMobileGL.so` | rc 0: `.text` 10806323 -> 10806323 (+0); 27811 -> 27811 symbols: **0 added, 0 removed, 0 resized, 0 renamed** |
| `RenderStateImpl` sha | d8fd1c48716056c53675 == before |
| `scripts/p3a_untouched_regions.sh 37da3c3a HEAD` / `--self-test` | rc 0 byte-identical / rc 0 |
| `scripts/p4a_untouched_regions.sh 37da3c3a HEAD` / `--self-test` | rc 0 byte-identical / rc 0, 8 controls tripped and named |
| `gen_pipe.py --check` | up to date, rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0, 27 negative controls tripped, positive OK |
| `check_include_closure.py --compiler clang++` / text self-test | rc 0, 4 probes, 0 problems / rc 0 |
| gate C (`pGLContext` in MG_Backend) / G13 | only `PipeInputs.h` (as before) / `PipeApply.h` :37 :40 :832 :1040 :1041 - forward declarations and prose, outside the ops block (ID-39's class) |
| unit `-L unit` | **1785 / 1785 / 1785** (linux / push / verify) |
| G2 pull == push ctest names | **2902 == 2902**, 0 diff lines |
| G14 vs `p4a-before-ctest-names.txt` | 0 removed, **+314** (was +275: 13 unit twins + 13 itest cases x 2 backends = 39) |
| emitter/CSO unit suites (push) | 185/185 |
| HandleRecycle (verify) / verify controls | 180/180 / 4/4 |
| integration-gpu, build-push, 0x1fff (default) | **1117/1117** (1091 + 26) |
| integration-gpu, build-push, 0x1ff / 0 / 0x9ff / 0x5ff | **1117/1117** each |
| DirectVulkan lane, 0x1fff | 559/559 |
| integration-gpu, `MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1` | 1117/1117 |
| integration-gpu, build-linux (pull) | 1117/1117 |
| family regex / G9 `TextureParamsWithoutASamplerView` / `TextureUploadShape` (recorded) | 497/497 / 8/8 / 3/3 |
| the new lane `P4aFinalFix` at 0x1fff / 0x1ff / 0 / pull | 26/26 each |
| `g7_negative_control.sh` / `p3a_vertex_input_negative_control.sh` / `p4a_descriptor_negative_control.sh` | rc 0 tripped / rc 0 (IsBgra) / rc 0 (both controls named) |
| CsoContentAddressing + ResourceSubsystemControl + ObjectSubsystemControl / the 0x9ff arm | 24/24 / 14/14 |
| controls (PoisonOmitted/VerifyCorrupted/HandleRecycle, verify) | 184/184 |
| integration-verify, build-verify, `-j 4` | **920/920, `Fatal{` lines 0** |
| retrace (`retrace_gate.py --tree ~/w7/p4a-finalfix --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p4a-finalfix -j 4`, fixtures re-copied from `~/w7/pipe`, 0 LFS pointers) | rc 0, **79 / 79**, failed [] |
| retrace refusal census over the 79 `mobilegl.log`s | **0** for every one of 16 needles: the ten shapes, "does not describe the binding it names", `Fatal{`, "cannot be adopted on the handle arm", **"was refused"** (C-2's and m-1's tells), "is dead but the emitter still holds", "no applier record"; the deduped `MGPipe:` ERROR/FATAL list is **empty** (it held 2 lines on `c2c6a655`, closed by `8c458cd5`) |
| itest eight-family census (`wsl_p4a_refusal_census.sh default`, 558 names, 538 logs) | **0 lines / 0 tests on all 13 rows** (the ten shapes + the three this round's tells), stems 0 / 0 / 0 |
## 5. Declared, with reasons
* **m-4 / F-6** (`MGPipeEncodeImageAccess`, `MGPSamplerView::Target`, `DrawBuffers` narrowing stated in
package headers): contract work for P4b (R-3); no behaviour to fix this round.
* **m-5** (`GenerateThreeChannelFloatMipmapOnCpu` marks levels dirty without `RearmPipeTextureLevelUpload`,
self-heals one verb late): a server-side D-M emulation site on E's file; the rearm belongs with R-7's
audit of the two backend re-dirty sites, not in a client-side round. Its storage grow beside it goes
through `AllocateStorage` and is level-scoped by C-1 for free.
* **m-6** (G9 blind when a `UseProgram` row and its mark drop together): derivation work, R-4, P4b.
* **m-7** (`DirectGLES.cpp:4137/4174` pull-path `broadcastCountResolved`): benign; G1 0/0/0/0 stands.
* **m-8** (nested-worktree `include/ska` pointer): this worktree, made with the plain `git worktree add
-b` the charter spelled, shows a clean `git status` in `include/ska`; every commit here used explicit
`git add` + `git commit -F`, never `-a`, and each was verified with `git log`/`show --stat`. Two tooling
notes of this round for `notes/tools`: (1) `$(...)` inside a double-quoted `wsl.exe -d Arch -- bash -c
"..."` string is expanded by the Windows Git Bash BEFORE the string reaches WSL (it reported the FCL
repo's `dev` head and dirty count as if they were the worktree's); (2) a Bash-tool heredoc containing
backticks fails to parse - write the `.py` with the Write tool instead.
* **§8 items 6-7** (the two-device Release A/B re-take on the fixed head - C-1 dropped uploads and biased
the push arm - `test.yml:9-12`'s TEMPORARY trigger, D.5 docs and `check_doc_citations.py`) are the
integrator's. For D.5: `ARCHITECTURE.md:249-254`'s texture paragraph should carry the C-1 rule ("the
client passes the level it redefines; a chain cut names its removed levels; whole-resource calls pass
none; a named level is dropped whatever the descriptor says"), `ARCHITECTURE.md:598` the four
dependency rows, and `ROADMAP.md:85` the counter name (`tex-remint-pulls`, `trp=`).
* The census tool `notes/tools/wsl_p4a_refusal_census.sh` already lists this round's three tells
(rows 11-13 in the head's census run); it was not edited by this round.
## 6. Logs
Kept in `~/w7/notes/p4a/p4a-results/finalfix-v1-logs/`: the RED run on the unfixed tree
(`p4a-finalfix-red.log`, `p4a-finalfix-red-itest.log` with the black-pixel counts, the `pure virtual
method called` abort and the M-A assertion values), the GREEN run after each fix (`p4a-finalfix-green-
{c1,c2,ma,minors}.log` + `-{c1,c2,ma,ma2,minors}-itest.log`), the F-7 / heal red-green transcripts
(`p4a-finalfix-f7.log`, `p4a-finalfix-heal.log`), and the gate on `8c458cd5` (`p4a-finalfix-gate.log`,
`-gate-symbols.md`, `-gate-retrace-summary.txt`, `-gate-census.log`, `-gate-iverify.log`). Every other
`~/w7/p4a-finalfix-*` log, `~/w7/finalfix-stage/`, the census output directory and the retrace output
directories (summary.txt / summary.json kept) were deleted at the end of the round. The worktree
`~/w7/p4a-finalfix` stays (branch `p4a/finalfix`, HEAD `8c458cd5`, clean; fixtures are the copies from
`~/w7/pipe` under `assume-unchanged`). The shared scratchpad `wsl` directory is untouched except for this
round's own `finalfix-*` scripts.
@@ -0,0 +1,563 @@
# P4a package F — `gates`. Adversarial review, v1
Reviewed: `refs/heads/p4a/gates` `0bc9aafa..303a9dc8` (4 commits) in
`/home/swung/w7/p4a-gates`, against `BRIEF-P4A.md` (A.2 G5/G7/G8/G8b/G9/G10–G12, B's D-I/D-K/D-L/D-N,
C.5, C.7, D.2, D.3, E), `INTEGRATOR-DECISIONS.md` ID-1..11, `contract-v1.md`,
`contract-review-v1.md`, `contract-v2.md`, `wire-v1.md` and the package report `gates-v1.md` with
its four D.2 artefacts.
Experiments were run in a private detached worktree `/home/swung/w7/p4a-review-gates` @ `303a9dc8`
(no build; git + python + bash only). Nothing in `p4a-gates` was written to, and the private
worktree has been removed. §3's tail-boundary probe is reproducible in a fresh one:
`git worktree add --detach <dir> 303a9dc8`, insert a comment before the last statement of
`RecomputeBackendColorSlots`, inside `namespace DepthStencilSamplingReadImpl`'s closing brace and
before `ShouldUseCaveatTextureFormat`'s `return`, commit, then
`bash scripts/p4a_untouched_regions.sh 303a9dc8 HEAD`.
---
## Verdict
**ACCEPT WITH MAJORS — rework required before integration.**
The G5 gate is the strongest thing in the package: I attacked it four ways and it survived all four
(§3). The scenario work is honest about what it cannot assert and its skips are real skips. But:
* **G7 cannot report success at all.** Two independent defects each make exit 0 unreachable, and a
third makes its central safety claim (`repair()` on every path including a mid-way interrupt)
false. All three are unexercised today because the script exits at step 0 on the contract tree —
i.e. the package's own green measurement is exactly the path that hides them. **F-M1, F-M2, F-M3.**
* **G8b's composite case reads a counter that c0b redefined**, and `contract-v2.md` §4.3 / §7.6
assigns F the fix by name. As it stands the case will pass, will not skip, and will be blind to
the band it exists for. **F-M4.**
* **R2's flip can be forgotten after all**, through a file-layout accident in the conjunction probe.
**F-M5.**
* **G12's refusal assertion — the one P4a control that is not vacuous today — matches a lowercase
`"sampler"` anywhere in the whole log**, so it is not clear it can go red for its stated reason.
**F-M6.**
Six majors, twelve minors, three deviations judged acceptable, two judged under-declared. Nothing
here is an architectural objection: the shapes are right and every fix is local.
---
## 1. Hard-rule spot checks I re-ran
| what | result |
|---|---|
| `p4a_untouched_regions.sh 37da3c3a HEAD` | **rc 0**, 17 shas, matching the report's list byte for byte |
| `p4a_untouched_regions.sh --self-test` | **rc 0**, 3 positive + 4 negative controls, each named |
| exit contract: no args / bad `<ref-a>` / bad `<ref-b>` / 3 args / `--self-test extra` | **2 / 2 / 2 / 2 / 2** — correct, nothing degrades to 1 |
| tail-boundary probe (new, §3) | **rc 1**, all three files' regions named |
| working tree clean, no attribution, single-line `[Type] (Scope):` messages | yes |
| only F's files + the one granted `MagmaPipeArms.h` | yes |
| each commit's `CMakeLists.txt` names only scenario sources that exist in that commit | verified for all four |
| D.2 artefacts | present and say what the report says they say: G9's four cases **Passed** on DirectGLES, the DirectVulkan four Skipped; every ObjectSubsystem entry Skipped; the TextureUploadShape lane Passed |
I did not re-measure G1 / G2 / G14 / the 1072-case `integration-gpu` run (they need the package's
build dirs, which are not mine to touch). What I *did* check is the thing the integrator cannot
re-derive from a number: whether the new CI filters actually reach every new entry — §6, they do.
---
## 2. The rulings
### R1 — G9 as a D10 regression net: **partial, and the gap should be written into esprytobj's brief**
The four cases are structurally correct for what they claim
(`/home/swung/w7/p4a-gates/MobileGL/MG_IntegrationTest/Scenarios/TextureParamsWithoutASamplerViewScenario.cpp:286`,
`:337`, `:460`, `:506`): each puts a texture through exactly one reachability path, moves a
parameter through the DSA entry points so no setup step ever binds it to a unit
(`:231-238`), runs a frame, and only then samples (`:243-257`). The mechanism F documents for why
they are green today is correct and I re-derived it: the sample is the only observable, and the
sample is also what repairs the state.
**Would they go red if Espryt stopped applying params to an attachment-only texture?** It depends
on the shape of the regression, and only one of the two plausible shapes is caught:
* **Caught.** A P4a path that emits `set_texture_params` for the attachment-only texture and marks
the frontend params version *synced* while the backend drops the record (no sampler view ⇒ no
apply) — the observation at `:243` then finds `IsDrawSyncClean` true, skips the sync, and the
wrong colour comes back. This is the likeliest P4a-introduced shape precisely because P4a is what
moves the clean-marking, so the net is real.
* **Not caught.** A path that merely *defers* the apply to the first sampler view. The observation
creates that view, the params are applied at that moment, and the case is green. The same
self-repair that makes the red unobtainable today makes this regression unobservable.
So the four cases stand as a regression net, but they are not a complete one, and the ruling's
phrasing ("red if Espryt stopped applying params to an attachment-only texture") is only half
satisfied. **Recommendation for the esprytobj verification round: specify the backend-side probe to
take its reading while the texture is still attachment-only *and* to distinguish "not applied yet"
from "applied late"** — otherwise the genuine red will reproduce the same blind spot at a lower
level. Nothing about this is package F's to fix.
Two further R1 notes. The scenario deliberately takes **no lane** and runs in the ambient
registrations at the build default mask — correct, and it only works because the contract moved the
push default to `0x1fff` (`contract-review-v1.md` D10, verified there). And the DirectVulkan four
skip in `SetUp` naming the backend (`:162`), which the D.2 log confirms.
### R2 — the flip is one `if`, but it can be forgotten. **Verify: PARTIAL**
**The one `if` is real.** `ObjectAbaControlIsWiredHere()`
(`.../Scenarios/HandleRecycleScenario.cpp:257-266`) is
`MGITEST_HANDLE_ABA_OBJECTS_<backend> AND ThisBackendsObjectRekeyHasLanded()`, both build markers
from `CONFIGURE_DEPENDS` content probes
(`.../MG_IntegrationTest/CMakeLists.txt:531-563`). No test source has to be edited: the moment a
backend source reads `Features.PipeHandleAbaControl` over a P4a slot table, the probe finds it and
all six cases flip. `ExpectPixelsFor` gates on `arm == Arm::AbaControl && armExpectsCorruption`
(`:341`), so the flip cannot leak onto the Handles or Legacy arms; the framebuffer and renderbuffer
cases re-check `m_arm == Arm::AbaControl` explicitly (`:1234`, `:1489`). The lane that can carry the
flip exists and pins the shipping mask: `DirectVulkan.HandleRecycle.AbaControlHandles.`
(`CMakeLists.txt:1067-1070`, `0x1fff` + the knob). I confirmed the probe does **not** arm today —
`MagmaPipeArms.h` names `PipeHandleAbaControl` (`:222`, `:227`) but no P4a subsystem constant, and
no DirectGLES source names either.
**But it can be forgotten — F-M5.** The conjunction requires both regexes **in one file**
(`CMakeLists.txt:425-446`). If package D wires the knob in `Managers.cpp` while the P4a subsystem
constants live in `SlotTables.h`, the marker never arms, the six cases keep printing `wired=0` and
asserting the correct pixels, and **nothing fails, warns, or records that the expected flip did not
happen**. `RecordProperty("aba_control_wired", 0)` (`HandleRecycleScenario.cpp:500`) is recorded,
never checked; there is no TODO the gate itself checks.
The fix is cheap and strictly safer: make the conjunction **directory-wide** (regex A anywhere under
the backend directory AND regex B anywhere under it), keeping "one source" only in the message.
Today that is still false for both backends — DirectVulkan has the knob and no P4a constant,
DirectGLES has neither — so it costs nothing now and removes the layout dependency later.
`MagmaPipeAbaControlCoversKind` (`MagmaPipeArms.h:237`) does **not** discharge R2: nothing calls it
(F-m5).
---
## 3. G5 — `scripts/p4a_untouched_regions.sh`
**The region set is exactly D-N's, nothing missing and nothing extra.** 17 rows (`:116-133`) =
P3a's eleven in `Managers.cpp` + P4a's six across three files; `EXPECTED_FUNCTION_COUNT=17` is
asserted (`:135`, `:541`) and `SELF_TEST_FUNCTIONS` (`:159`) is exactly D-N's four, with the count
pinned (`:609-612`).
**I attacked the extraction four ways.** Three found nothing; one found a hole in the *self-test*,
not in the code:
1. **Tail boundary.** The self-test's `perturb` inserts at the very first byte after the opening
brace (`:383-387`), so every negative control would still trip even if `find_definition` returned
an extent that stopped one character in. Nothing in the self-test proves a region reaches its
closing brace. **Refuted empirically for the current tree:** I committed a comment immediately
before the last statement of `RecomputeBackendColorSlots` (`Managers.cpp`), inside
`namespace DepthStencilSamplingReadImpl`'s closing brace (`DirectGLES.cpp:8578`) and before
`ShouldUseCaveatTextureFormat`'s `return` (`Utils.cpp`), and the gate returned **rc 1** naming
`RecomputeBackendColorSlots` first and the other two as "also moved". The extents are right,
including the namespace kind. Recorded as **F-m2** because the *self-test* still cannot catch an
extent regression.
2. **Duplicated preprocessor arms.** Handled the way the parent handles it: the two spellings of the
flush ladder are two named rows (`FlushPendingRangesNow` in the `#else`, `FlushPendingRangesFrom`
in the `#if MOBILEGL_PIPE_PUSH`), each found exactly once. A P4a arm that re-spells one of the
seventeen *under the same name* is found twice and is exit 2 with a message that names the shape
(`:345-358`) — the designed finding, not a limitation. Not a defect.
3. **Comments and literals.** `mask()` blanks comments, strings, chars and raw strings
length-preservingly, and it carries the C++14 digit-separator special case (`:218-224`) that
would otherwise blank forward to a distant apostrophe. Hashing is from the **original** text
(`:360-362`), so a comment change is a difference — deliberate and correct for a "byte-identical"
claim. Not a defect.
4. **Call sites vs definitions.** `find_function` requires the closing paren to be followed (past
`const`/`noexcept`/`override`/`final`) by `{` (`:264-268`); `RecomputeBackendColorSlots`'s own
call site at `Managers.cpp:7580` is correctly not matched. A trailing-return-type definition
would yield zero hits and exit 2 — loud, not silent. Not a defect.
**Deviations D-N/1 (namespace kind) and D-N/2 (pin consulted unconditionally): both correct and
both well argued.** `DepthStencilSamplingReadImpl` really is a namespace
(`DirectGLES.cpp:8117-8578`), the parent's extractor really would find zero and exit 2 forever, and
`find_namespace` (`:279-300`) will not match a *use* of the namespace. The unconditional pin is the
stronger reading of D-N and the two readings agree on this tree (measured: `37fc94ff…`).
### F-m1 (minor) — the one-ref listing is not in the fixed order, so a captured baseline diffs spuriously
`scripts/p4a_untouched_regions.sh:90-91` promises "stdout is always the sha list … in the fixed
order above — so a baseline capture is a plain redirect". It is not, in the one-argument mode:
`extract_baseline` strips the pinned rows from the spec and appends them **last** (`:463-489`),
while `extract_ref` (`:446-452`) emits in spec order.
Measured: `p4a_untouched_regions.sh 37da3c3a` puts `FlushPendingRangesFrom` at row 17;
`p4a_untouched_regions.sh 37da3c3a HEAD` puts it at row 11. A baseline captured the documented way
and later `diff`ed against the two-ref stdout shows **seven** spurious differences.
The gate itself is unaffected (`compare_lists` looks rows up by name), so this is minor — but the
documented capture workflow is the one that breaks. Fix: emit `$out.sha` through the `REGIONS`
order, or `sort` both sides in the doc.
### F-m2 (minor) — no control proves a region's closing boundary
Above. Fix: a fifth control that perturbs immediately *before* the closing brace, or pin each
region's line count beside its sha in the self-test.
### F-m3 (minor, inherited) — the hash starts at the line carrying the name
`:274` — `begin = text.rfind('\n', 0, m.start()) + 1`. A return type, attribute or template header on
an *earlier* line of a multi-line signature is outside the hash. Inherited from the parent verbatim,
so not a P4a regression; worth one line in the script header so the next reader knows the claim's
exact extent.
---
## 4. G7 — `scripts/p4a_descriptor_negative_control.sh`
The design is right (regex not line numbers; RHS replaced not deleted; both controls always run;
exit 2 outranks exit 1; logs under the build dir; `repair()` before the verdict is reported). Three
defects nonetheless make it unusable as written, and none of them is visible on the contract tree,
because there the script exits at step 0 before any of them runs.
### F-M1 (major) — the `borderColorForm` control cannot compile, so its half can never answer
`:233-234` replaces the right-hand side with the literal `0`:
```python
pattern = re.compile(r'(\.' + re.escape(field) + r'\s*=\s*)([^;,\n]+)([;,])')
patched, count = pattern.subn(r'\g<1>0 /* G7 NEGATIVE CONTROL: was \g<2> */\g<3>', text)
```
`borderColorForm` is a **scoped** enum — `MG_Pipe/MGPipeValueTypes.h:456`
`enum class BorderColorForm : Uint8 { … };`, field at `:485` — present in F's own tree, so this was
knowable at c0. `= 0` does not convert. Verified twice: on package C's real header (the assignment
is `canon.borderColorForm = src.borderColorForm;` at
`/home/swung/w7/p4a-clientsp/MobileGL/MG_Impl/Pipe/SamplerEmit.h:127`, in an `inline` function body,
so every including TU fails), and on a standalone `g++ -fsyntax-only` reduction:
```
error: cannot convert 'int' to 'BorderColorForm' in assignment
```
The script then takes the "the patched header did not compile" path (`:252-261`), reports
`could-not-run`, and `WORST=2` — with the summary at `:342-343` telling the reader that exit 2 is
"the expected answer on the P4a contract tree", which on an integrated B+C tree is exactly the wrong
diagnosis.
**Fix (one character each):** replace the RHS with `{}` instead of `0` — `= {}` is valid for the
scoped enum *and* for `MGPSurface::Layered` (`Uint8`, `MG_Pipe/MGPipeTypes.h:501`), so one
replacement string covers both controls. Verified compiling.
### F-M2 (major) — the patcher's stdout is captured as part of the verdict, so exit 0 is unreachable
`run_control` is invoked in a command substitution (`:325` `verdict=$(run_control …)`), and the
patcher's success message goes to the function's **stdout** (`:240`
`print('[p4a-g7] neutralised %d assignment(s) to .%s' …)`), not stderr like every other message in
the file. So on a tree where a control really trips, `$verdict` is
```
[p4a-g7] neutralised 1 assignment(s) to .Layered
tripped
```
and the `case "$verdict" in tripped) ;;` at `:328-332` falls through to `*)`, setting `WORST=1`.
Reproduced in isolation: the two-line verdict "FELL THROUGH TO * -> WORST=1 (false 'did not
answer')". **The script reports "a control did not answer" for a control that answered
perfectly, and can never exit 0.**
**Fix:** redirect that `print` to `sys.stderr` (or `>&2` on the whole `python3` call), or take only
the last line of the verdict.
### F-M3 (major) — `repair()` cannot run from the traps: the state lives in a subshell
`:117-119` declare `PATCHED_HEADER` / `PATCHED_BACKUP`; `:152-154` install `repair` on `EXIT`, `INT`
and `TERM`; `:222` sets `PATCHED_HEADER` **inside `run_control`**, which `:325` runs in a command
substitution. Bash resets a script's traps inside a command-substitution subshell, and the subshell's
assignments never reach the parent — so:
* the subshell has no traps to fire, and
* the parent's traps fire with `PATCHED_HEADER` empty and `repair()` returns 0 immediately.
Measured (`/tmp` reduction, SIGINT to the process group two seconds into a long "build"): the
parent's `repair` printed *"NO-OP (PATCHED empty)"* and the patched file **survived the interrupt**.
The header's own claim at `:57-69` — *"a Ctrl-C during a rebuild cannot leave a hard-wired field in
the tree … repair() runs from the EXIT trap as well"* — is therefore false, and it is false for
exactly the `p3a-g7 m3` reason it cites. The handled paths are all covered by the explicit
`repair` calls (`:244`, `:258`, `:289`), so the exposure is signals and hard errors only — but that
is the case the traps exist for.
**Fix:** stop capturing the verdict through a subshell. Have `run_control` write its verdict to a
variable (`printf -v` or a global) or to a file under `$LOG_DIR`, and call it plainly.
### F-m10 (minor) — a pull build dir reports `did-not-trip`, not `could-not-run`
The emission suites compile their cases only under `MOBILEGL_PIPE_PUSH`
(`MG_Test/Pipe/FramebufferEmitTest.cpp`, `SamplerEmitTest.cpp`), so in a pull build every case is a
visible skip, ctest is green before and after the patch, and `:271` records `did-not-trip` — a
finding *about the suite* that is really a finding about the build directory. The usage text
requires a push build dir (`:54-55`) but nothing verifies it. Fix: check
`MOBILEGL_PIPE_PUSH` in `$BUILD_DIR/CMakeCache.txt`, or require at least one non-skipped case in the
"before" run.
### F-m8 (minor) — the `Layered` control perturbs two mechanisms, not one
On package B's tree the regex matches **three** assignments
(`/home/swung/w7/p4a-clientfb/MobileGL/MG_Impl/Pipe/FramebufferEmit.h:110`, `:119`, `:168`), and
`:168` is inside `MGPipeCopySurfaceForHash` — the **ContentHash** staging copy. Patching it also
removes `Layered` from the framebuffer content hash. The control still trips (`FramebufferEmitTest.
cpp:351-352` compares `surface.Layered` against the frontend attachment and streams
`"MGPSurface::Layered at colour point N"`, so the block-scoped grep at `:272-273` finds the name),
but the script's own claim of a single-field drop (`:21-27`) is inaccurate. Either exclude the hash
copy or say that two mechanisms are perturbed.
### The G7 assumption about B/C's headers — otherwise robust
Checked against the packages' real trees. `grep -qE "\.<field>[[:space:]]*="` matches in both;
both assignments are single-line, `;`-terminated and contain no comma, so the `[^;,\n]+` capture is
safe; the ctest regexes `FramebufferEmit\.` / `SamplerEmit\.` each select only their own suite (9 and
11 cases); and both suites' failure text carries the literal field name inside the gtest failure
block, which is what the awk-block grep needs. **The assumption is robust; only the replacement
value is wrong (F-M1).**
---
## 5. G8 / G8b — `HandleRecycleScenario`
**The four new ABA cases construct real ABA through public GL.** Renderbuffer (`:1420`), sampler
object (`:1524`), sampler view (`:1632`), program (`:1724`): each deletes, re-creates, checks the GL
name actually came back and `GTEST_SKIP`s *"inconclusive, not proven"* otherwise. The observables are
well chosen and each is defended against a false green — the renderbuffer's is the **storage extent**
(4×4 dead under an 8×8 replacement) because a renderbuffer cannot be sampled; the sampler's is the
**border colour** at a constant UV outside `[0,1]` with `CLAMP_TO_BORDER`, which is the parameter with
the fewest other paths to the driver; the sampler view's keeps a live sampler object across the
window so the *texture* half is the only thing that moved, which is what makes it a different
question from the texture case; the program's colour is baked into the shader source, not a uniform,
so a re-set uniform cannot hide the inheritance. All four correctly detach/unbind/`glUseProgram(0)`
before deleting, so the frontend object really dies inside the case.
**The two existing cases are now real controls.** The texture case takes
`ObjectAbaExpectation("texture")` (`:1118`). The framebuffer case adds the dead attachment's red
warm-up clear and reads **both** attachments (`:1214-1247`), which is the right upgrade: "the
replacement's attachment never became green" was half a verdict.
**The seven leak cases sample peak-live inside the round.** `AssertChurnReturnsEverySlot`
(`:630-708`) takes an `observe()` the round must call while the object is alive (`:655-658`), resets
`peakLive` after two warm-ups (`:661`), takes the baseline, runs `kChurn = 48`, and asserts
`liveAfter == liveBefore`, `highWaterAfter == highWaterBefore` and
`peakLive - liveBefore <= maxInFlight` (`:699-717`). The "nothing was ever minted" skip (`:688-697`)
is P4a's real addition and is what stops six of the seven being `0 == 0` greens. Each churn round
varies the object's content where the kind is content-addressed (the sampler's LOD bias, the
program's and the composite's fragment source) — correct, and non-obvious.
**They do run on the DirectVulkan lane.** `DirectVulkan.HandleRecycle.Handles.` exists
(`CMakeLists.txt`, `MGL_ITEST_VULKAN_HANDLE_HANDLES_ENVIRONMENT` at `0x1fff`), the leak cases gate
only on `m_arm == Arm::Handles`, and the D.2 verbose log shows all seven reaching the "nothing
minted" skip there. Once B and C land, the client mints slots regardless of backend and the cases
arm on Magma — which is the P3a C-1 shape and ID-8's requirement. **Satisfied.**
### F-M4 (major) — the composite leak case reads a counter c0b redefined, and c0b assigns F the fix
`Harness/PipeSlotPeek.cpp:50-54` reads `MGPipeSlots().HighWater(Translate(kind))` and
`PipeSlotPeek.h:47-55` states as fact that *"LiveCount counts both and HighWater is one past the
highest slot handed out in either"*. That was c0's semantics. c0b split them
(`contract-v2.md` §4.3): `HighWater(kind)` is now **the ordinary space only**, and the band is
`CompositeHighWater()` / `CompositeLiveCount()` / `CompositeFreeCount()`.
`contract-v2.md` §4.3 and §7 item 6 name the consequence for this package explicitly:
> **Package F, `PipeSlotPeek`**: the six new members G8b asks for want a **seventh**,
> `PeekPipeCompositeSlotHighWater`, and the composite leak case asserts on that one
F was written against c0 and does not have it. **Failure scenario on the integrated tree:**
`EvictedPipelineCompositesReturnTheirShaderCsoSlots` (`.../HandleRecycleScenario.cpp:2060`) churns
composites; the two stage programs it also creates are ordinary `ShaderCso`s, so the "nothing
minted" skip does **not** fire and the case does not skip; `highWaterAfter == highWaterBefore` and
`liveAfter == liveBefore` are then statements about the ordinary space; a slot that never comes back
to the **band** — the double-free-refusal case the band exists to police (`SlotAllocator.cpp:117-119`,
D-H7) — moves neither. The case reports green having never looked at the thing it is for. This is
M5's failure mode reintroduced one level up, and the report's §3.3 note that "this case is one of
[M5's] consumers" is true but not acted on.
**Fix:** add `PeekPipeCompositeSlotHighWater` (and, for the live/peak assertions to mean anything
about the band, `PeekPipeCompositeSlotLiveCount`), point the composite case at them, and correct
`PipeSlotPeek.h:47-55`'s now-false statement.
### F-m5..m6, m12 (minor)
* **F-m4 (the skip reason is false).** `:636` tells the reader *"The Legacy and AbaControl lanes
run `MOBILEGL_PIPE_PUSH=0`, where there is no allocator to leak from."* Measured against the lane
table: `DirectGLES/DirectVulkan.HandleRecycle.Legacy.` and
`DirectVulkan.HandleRecycle.AbaControl.` do set `MOBILEGL_PIPE_PUSH=0`
(`CMakeLists.txt:1057-1066`), but `DirectVulkan.HandleRecycle.AbaControlHandles.`
(`:1067-1070`) runs `${MGL_ITEST_HANDLES_ARM_KNOBS}` = `0x1fff` **with a live allocator**, and the
seven cases decline there anyway. Not a correctness bug (the Handles lanes cover it), but the
stated reason is false and one lane's coverage is left on the table. Fix the sentence, or gate on
the mask rather than on the arm.
* **F-m5.** `MagmaPipeAbaControlCoversKind` (`MagmaPipeArms.h:237-258`) has **no caller**. It cannot
make anything red or green, so it will rot silently; and it uses `default:` where
`PipeSlotPeek.cpp:28-41` deliberately refuses one for exactly the "a kind added without a decision"
reason. Either call it (from the DirectVulkan side of the scenario, or from a unit case pinning the
two covered kinds) or reduce it to the comment it effectively is.
* **F-m6.** `:2083` reads "TWO in flight" beside `/*maxInFlight=*/3u` at `:2087`. 3 is the right
number (two stage programs + the composite); the prose is stale.
* **F-m12.** The framebuffer ABA corruption assertion is `EXPECT_NE(deadIsNotRed, 0)` (`:1238`),
which is weaker than the `sawStale` predicate the same case computes and prints at `:1224` (dead
attachment now *all green*). A garbage dead attachment satisfies the assertion. Use `sawStale`.
---
## 6. The itest CMake, and `test.yml`
**Pins.** All nine C.5 pins raised, each re-read rather than pattern-replaced; the CSO Off lanes
moved `0x80000000000001ff → 0x8000000000001fff` (mask with the phase, control at bit 63). Grepping
the final file, the only surviving `0x7f` env pins are `ResourceSubsystemControl`'s Off lane
(`:1255`) and `LargeArenaAdoption`'s Off lane (`:1323`) — exactly C.5's `:1154`/`:1222` — and the
only surviving `0x1ff` env pin is the **new** `ObjectSubsystemControl` Off lane (`:1382`), which is
the named P4a control. `0x9ff` appears once, in the refusal lane (`:1387`). Correct, and the three
comment blocks were rewritten rather than left stale.
**`mgl_itest_join_environment`** is used for all four new environments, each with
`${MGL_ITEST_COMMON_ENV}` last. **The two-symbol probe** (`:425-446`) is well motivated and its
false-positive risk is real but not live: I confirmed `MagmaPipeArms.h` names the knob but no P4a
subsystem constant, so DirectVulkan does not arm today. Its false-*negative* risk is F-M5 above.
**`RESOURCE_LOCK`.** Not needed and correctly omitted: the three ObjectSubsystem lanes and the
TextureUploadShape lane each have a private `MOBILEGL_LOG_FILE_PATH` **and** a `TEST_FILTER` naming
one case, which is the stronger form of the guarantee the four existing locks (`:769`, `:886`,
`:922`, `:933`) provide.
**No test name removed or renamed**; the two pre-existing HandleRecycle cases keep their names and
every existing lane keeps its `TEST_PREFIX`. The new lanes are registered outside the
`if (MOBILEGL_PIPE_PUSH)` guard, so the pull/push name sets stay identical (G2) — this is the
structural check; the counts (2707 / +119) are the integrator's to re-take on the finished tree.
**`test.yml`.** `BASELINE 44c2b5cf → 37da3c3a` with a justification that is correct and that I
re-verified (`p3a_untouched_regions.sh 37da3c3a HEAD` rc 0; `FlushPendingRangesFrom` still hashes to
its `3e298c9a` pin). Two new `pipe-gates` rows under the same
`feat/disaggregated`-or-`workflow_dispatch` guard as the P3a rows, which stay. The push-build
control step's `-R` alternation reaches **every** new entry: `ObjectSubsystem` selects the three
`DirectGLES.ObjectSubsystemControl.{On,Off,Refused}.` lanes and the two ambient entries;
`TextureUploadShape` selects the lane and the ambient entries; `TextureParamsWithoutASamplerView`
selects the ambient four (the scenario has no lane by design); `HandleRecycle` already selects the
eleven new cases across six lanes. `ResourceSubsystem` genuinely does not match
`ObjectSubsystemControl`. **The TEMPORARY trigger lines are untouched** (verified at the top of the
file).
### F-m9 (minor) — the c0b hardening of the closure gate is not applied
`contract-v2.md` §7 item 6 also tells F that `.github/workflows/test.yml:774` must become
`--compiler clang++ --expect-probes 4`. The line is now at **`:793`** and still reads
`--mode both --compiler clang++-20 --self-test --require-all`.
On the **compiler** half, ID-11 is right and contract-v2 over-states the risk: the job installs
`clang-20` via apt (`:790`), and Debian/Ubuntu's `clang-N` package ships `/usr/bin/clang++-N`, so
`clang++-20` resolves in CI (contract-v2's "compiler not found" evidence was taken on the WSL box,
where it genuinely does not exist). The line is **consistent with what CI has**; no change is
required there and changing it to bare `clang++` would be a small regression in specificity.
The **`--expect-probes 4`** half is still owed: without it a `--probe` typo or a manifest edit makes
the gate run zero probes and exit 0, which is the second half of M6 and the reason the flag was
added. One word, F's file, and it could not have been written at c0 — so it is a rebase item rather
than an omission.
---
## 7. `TextureUploadShape` (recorded, not gated), and the D.2 artefacts
The scenario is well built for a recorded lane: it asserts `emissions > 0` first so the shape
numbers cannot be zeros that mean nothing (`:311-318`), then the server bracket's own arithmetic
(`box + rect == emit`, `jobs >= emit`), then the two-sided agreement only when both sides exist, and
finally the pixels so a recorded shape cannot be the shape of a workload that drew nothing. The
recorded baseline (`emit=6 box=6 rect=0 jobs=6`, 40 scattered rects collapsed to one box per frame
on llvmpipe) is a real number and is the right thing for P3b/P4b to be written against.
### F-m7 (minor) — "the counter is absent" and "the counter read zero" are the same branch
`:331` `if (clientEmissions > 0)`. `CounterOrAbsent` returns a negative for a missing field, so an
absent `ctu=` and a present `ctu=0` both fall into the else branch and print *"no P4a client emitter
has landed on this tree, so this run records the SERVER shape only. That is the expected reading on
the contract tree"* (`:337-346`). Once package B lands, a client emitter that stops emitting reads
exactly like no emitter at all, and the case passes. The report's own re-run list says "once B
lands, the `ctu == emit` assertion is live" — it will **not** be live under that condition. Fix:
branch on `clientEmissions >= 0` for "the counter exists" and require `> 0` once it does.
### The D.2 artefacts — what was red before, and where it is recorded
* `p4a-texparams-before.log` — G9's four cases, **all Passed** on `DirectGLES` (`#2066`–`#2069`),
the DirectVulkan four Skipped. This is the artefact `ROADMAP.md:20` asks for and it records the
**absence** of the mandatory red, not the red. R1 accepts that; it must be carried into
`MEASUREMENTS.md` with §3.4's mechanism, or the next reader will read a green as a pass.
* `p4a-object-subsystem-before.log` — every `ObjectSubsystemControl` entry Skipped (ambient, and all
three lanes), the `TextureUploadShape` lane Passed. Consistent with the report.
* `p4a-handlerecycle-before.log` / `-verbose.log` — 180/180, the per-kind arms and the leak cases'
live/high-water numbers, which is the "重键前红" evidence per kind in the only form this tree can
produce (skips with stated reasons, plus the texture leak case genuinely asserting).
All four are in `~/w7/notes/p4a/p4a-results/` as ID-5 requires.
---
## 8. Hygiene, and deviations judged
**Hygiene: clean.** No attribution lines; four single-line `[Type] (Scope): description` messages;
working tree clean; no trailing whitespace in the new scripts; only F's files plus the granted
`MagmaPipeArms.h`; each commit's CMake source list matches its own tree. One triviality:
`scripts/p4a_*.sh` are `100755` while the sibling `scripts/p3a_untouched_regions.sh` is `100644`
(**F-m11**); both are invoked as `bash <script>`, so it is cosmetic.
| deviation | judgement |
|---|---|
| **F-1** four commits, not three | **Accepted** — ruling R3, and the reasoning is right: `ObjectSubsystemControl` and `TextureUploadShape` belong to neither of C.5's two `[Test]` messages, and the three exact messages are present in order |
| **F-2** the six ABA arms assert correct pixels and say so | **Accepted** under R2, with F-M5 to fix. The alternative really would be a permanently red always-on lane |
| **F-3** G9's red-before could not be produced | **Accepted** under R1; the mechanism is correctly derived. See R1 for the half the regression net does not cover |
| **D-N/1** namespace region kind | **Accepted** — verified necessary and verified correct, including the closing boundary |
| **D-N/2** pin consulted unconditionally | **Accepted** — the stronger reading of D-N, and both readings agree here |
| **F-4** `MagmaPipeAbaControlCoversKind` instead of changing `…DefeatsIdentity` | **Accepted in principle, under-delivered** — see F-m5: nothing calls it |
| **F-5** `build-bench` absent | **Accepted** — nothing in the package touches `MG_Benchmark/` |
| **F-6** `p4a-trees2.log` never said `REBUILT gates` | **Accepted** — the pull `.so` being byte-identical to `$BASE`'s is the check that would have caught a stale tree |
| **(undeclared)** C.5's two `~/w7/notes/tools` rows — `wsl_p4a_gate.sh` and the `p4a_ab*.sh` / `wsl_p4a_bench.sh` / `ab_reduce3.py` family | **Under-declared.** ID-3 reassigns them to the integrator and they exist, timestamped before F's round began. Correct outcome, but the report is silent on two rows of its own file table; a reader checking C.5 against the report finds a hole. Should be one line in `gates-v1.md` §8 |
| **(undeclared)** the c0 → c0b delta | **Under-declared.** The report names M5 as an in-flight dependency (§3.3) but does not say that `contract-v2.md` §4.3/§7.6 assigns F two concrete follow-ups. F-M4 and F-m9 |
---
## 9. Rework list
**Blocking (must land before integration):**
1. **F-M1** `scripts/p4a_descriptor_negative_control.sh:234` — replace the RHS with `{}` rather than
`0`, so the scoped-enum control compiles. Re-verify on an integrated B+C tree.
2. **F-M2** `:240` — send the patcher's success message to stderr (or take only the last line of
`$verdict` at `:325`), so a tripped control is not scored as `did-not-trip`.
3. **F-M3** `:325` / `:117-154` — stop running `run_control` in a command substitution; keep the
patched-header state in the parent so `repair()` on `EXIT`/`INT`/`TERM` is not a no-op. Prove it
with a SIGINT during a rebuild.
4. **F-M4** `Harness/PipeSlotPeek.{h,cpp}` — add `PeekPipeCompositeSlotHighWater` (and a composite
live count), point `EvictedPipelineCompositesReturnTheirShaderCsoSlots`
(`HandleRecycleScenario.cpp:2060`) at them, and correct `PipeSlotPeek.h:47-55`. This is
`contract-v2.md` §7 item 6, first half.
5. **F-M5** `MG_IntegrationTest/CMakeLists.txt:425-446` — make the ABA conjunction directory-wide so
arming does not depend on package D's file layout.
6. **F-M6** `ObjectSubsystemControlScenario.cpp:476-482` — tighten the refusal assertion: require one
**line** of the log to name both bits, at error severity, rather than a lowercase `"sampler"`
substring anywhere in the file. As written the assertion goes green on any log that happens to
contain the word, which is most of them once the sampler path logs anything.
**Non-blocking (declared minors are fine to carry, but these are cheap):**
7. **F-m9** `test.yml:793` — add `--expect-probes 4` (keep `clang++-20`, which CI has).
`contract-v2.md` §7 item 6, second half.
8. **F-m1** one-ref listing order; **F-m2** a closing-boundary control; **F-m3** one line in the
script header about the hash's start.
9. **F-m4** `HandleRecycleScenario.cpp:636` — fix the false skip reason (and consider gating on the
mask so `AbaControlHandles` is covered).
10. **F-m5** call `MagmaPipeAbaControlCoversKind` or delete it; **F-m6** "TWO in flight" → three;
**F-m12** use `sawStale` in the framebuffer corruption assertion.
11. **F-m7** `TextureUploadShapeScenario.cpp:331` — separate "absent" from "zero".
12. **F-m10 (G7)** verify `$BUILD_DIR` is a push build; **F-m8** narrow or document the `Layered`
triple patch.
13. **F-m11** exec bits; and one line in `gates-v1.md` §8 declaring the two `~/w7/notes/tools` rows
ID-3 reassigned.
---
## 10. What the integrator must re-run on the finished tree
F's own list in `gates-v1.md` §9 is right and I would keep every row of it. Add:
| what | why |
|---|---|
| `bash scripts/p4a_descriptor_negative_control.sh build-push` **after the F-M1/M2/M3 rework**, on an integrated B+C tree | it has never once reached the "tripped" path. Expect **exit 0** naming `Layered` and `borderColorForm`; anything else, including exit 2 with the "expected on the contract tree" wording, is now a real finding |
| `ctest --test-dir build-verify -R 'EvictedPipelineComposites'` after F-M4, with the composite band's numbers printed | today it will pass while never reading the band |
| grep the configure output for `MGITEST_HANDLE_ABA_OBJECTS_DirectGLES` **and** `MGITEST_HANDLE_REKEY_OBJECTS_DirectGLES` after D lands | F-M5: if the first is absent while the second is present, the six ABA controls silently did not flip. The configure log is the only place this shows |
| `MOBILEGL_PIPE_PUSH=0x9ff ctest -R 'ObjectSubsystemControl'` with the lane log kept | after F-M6, confirm the refusal line really is what turned it green — read the log, do not trust the substring |
| `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` **and** `--self-test` after D and E | unchanged from F's list; this is the gate D and E can break, and it is in good order |
| the pull-build `-L integration-gpu` run (F's list already asks for it) | plus the pull/push name diff, which is the only unverified half of G2 in this review |
| `python3 scripts/check_include_closure.py --mode both --compiler clang++-20 --self-test --require-all --expect-probes 4` locally is expected to fail on the compiler (the box has no `clang++-20`); run the CI job instead | ID-9 D16 / ID-11; do not "fix" `test.yml:793` to bare `clang++` on the strength of a local failure |
@@ -0,0 +1,523 @@
# P4a package F — `gates`. Focused re-review of rework v2
Reviewed: `refs/heads/p4a/gates` = **`ecf9cb45`** (`/home/swung/w7/p4a-gates`, read-only for this
round) — the four v1 commits rebased onto `2cb44039` plus the four rework commits `e85ba86a` /
`77f31f90` / `2e18d35d` / `ecf9cb45` — against `gates-review-v1.md` (F-M1..F-M6, R1/R2/R3, twelve
minors), `gates-v2.md`, `INTEGRATOR-DECISIONS.md` ID-15 / ID-16 / ID-19 / ID-27 / ID-28 / ID-29,
`contract-v2.md` §4.3/§7.6, `contract-v3.md`, `contract-v5.md`.
Every experiment ran in two private detached worktrees, `/home/swung/w7/p4a-rereview-gates`
(@ `ecf9cb45`, its own `build-push`) and `/home/swung/w7/p4a-rr-rebase` (the rebase probe). Nothing
in `p4a-gates` was written to; both worktrees and their build dirs are removed. `CCACHE_BASEDIR=
/home/swung/w7`, `-j 8`, `GLIBC_TUNABLES=glibc.malloc.tcache_count=0`. No device work, no retrace,
so no `git lfs checkout` was needed.
---
## Verdict
**ACCEPT WITH MINORS — merge is not blocked.**
All six majors are closed, and I re-proved five of them myself rather than reading the report's
transcript: G7 reaches `tripped` and exits **0** (§2.1); a SIGINT mid-rebuild leaves the tree
**empty under `git status --porcelain`** and the script dies **by SIGINT** (§2.3); commit 8's *other*
detection path — a child that returned ≥128 while bash never reached the trap — stops the run and
prints the interruption wording at exit 2 (§2.3); one leaked composite band slot makes
`EvictedPipelineCompositesReturnTheirShaderCsoSlots` fail **all three** assertions on **all three**
live-allocator lanes while every ordinary-space case stays untouched (§2.4); and the ABA conjunction
is directory-wide with no false positive on any tree in flight (§2.5). G5 is stronger than it was
(17 rows, **8** negative controls, the one-ref listing now byte-identical to the two-ref one) and
still green against the integrated pipe head. The rebase onto `712c9467` is **conflict-free, 8/8
commits, zero file overlap** (§4).
Four minors, none blocking; two of them are corrections to the report rather than to the code, and
one of those matters to the integrator's sequencing because **the §4 red-window warning is now
false** — esprytobj already carries the bit-10-requires-bit-11 row, so the 0x5ff arm goes GREEN at
integration, not red.
---
## 1. Per-item closure table
| item | v1 ask | landed | verified how | verdict |
|---|---|---|---|---|
| **F-M1** | `= {}` not `= 0`, so the scoped-enum control compiles | `p4a_descriptor_negative_control.sh:331` | script half: end-to-end run reached "the patched header still compiles" and `tripped` for **both** fields (§2.1). Compile half: the patcher's output on a real `SamplerParameters::borderColorForm` copy is `canon.borderColorForm = {} /* … */;` — accepted; `= 0` is `cannot convert 'int' to 'BorderColorForm'` | **CLOSED** |
| **F-M2** | the verdict cannot be polluted | global `CONTROL_VERDICT` (`:250`), plain call (`:455`), patcher writes to `sys.stderr` (`:339`), rows collected into an array first (`:445-452`), `</dev/null` on every child | exit **0** reached with a deliberately noisy stub builder writing to stdout during every step. Under v1's code this run scored `did-not-trip` | **CLOSED** |
| **F-M3** | `repair()` must run from the traps | state lives in this shell (`:220-232`, `:455`) | SIGINT to the process group with the patch demonstrably in the tree → trap fired, restore + rebuild + re-run, `git status --porcelain` **empty**, no `G7 NEGATIVE CONTROL` marker anywhere, exit **by SIGINT** (§2.3) | **CLOSED** |
| **commit 8** | *(found by F-M3's proof run)* stop carrying on past an interrupt | `INTERRUPTED` latch, `child_was_signalled`, `break`, separate summary wording | second path exercised on its own: child returns 130, script never got the signal → repair, `break`, `(INTERRUPTED - the remaining control(s) did not run)`, exit **2** (§2.3) | **CLOSED** |
| **F-M4** | read the band's own counters | `PipeSlotPeek.h:97-99` + `.cpp:57-73`; `SlotSpace` at `HandleRecycleScenario.cpp:217-247`, `:707`, `:2200`; `maxInFlight=1` | leak-one-composite reproduced independently (§2.4): 3 failed / 8, `live 2 -> 50 (peak 50), high water 983042 -> 983090 (floor 983040)`, all three assertions, on `DirectGLES.HandleRecycle.Handles.`, `DirectVulkan.HandleRecycle.Handles.` and `DirectVulkan.HandleRecycle.AbaControlHandles.`. Positive control (mint and free) **passes rather than skips**. The three peeks are 1:1 with c0b's API and that API is unchanged on `712c9467` | **CLOSED** |
| **F-M5** | directory-wide conjunction | `mgl_itest_probe_for_two_symbols`, `CMakeLists.txt:411-463`, `:580-595` | read + grepped four trees for both halves (§2.5). No false positive anywhere in flight; residual holes are narrow and named | **CLOSED** |
| **F-M6** | match the refusal as a LINE | `ObjectSubsystemControlScenario.cpp:181-220`, `:561-577` | the `/ERROR]` spelling is exactly what `MG_Util/Debug/Log.cpp:89-103` writes (`"/" + levelTag + "]: "`, `MGLOG_E` ⇒ `"ERROR"`); simulated against `p4a-esprytobj`'s **exact** sentences: matches both arms, rejects the framebuffer refusal, the bit-10-requires-bit-7 refusal, the same sentence demoted to WARN, and a line naming both bits without `REFUS` (§2.6) | **CLOSED** (one direction minor, F-v2-m1) |
| **ID-15 0x5ff arm** | write the arm now, SKIP visibly until D lands | case at `:614-692`, lane at `CMakeLists.txt:1446-1451`, `:1479-1487` | ran it: `***Skipped` with the full named reason quoted in §2.7. Expected refusal text checked against `p4a-esprytobj`'s HEAD — it **matches**, and the bit-7 check ahead of it does not pre-empt under 0x5ff | **CLOSED**, but see **F-v2-m2** |
| **F-m1** | fixed listing order | `:515-522`, `reorder_sha_list` `:529-541` | `p4a_untouched_regions.sh 37da3c3a` vs `… 37da3c3a 37da3c3a` — `diff` **empty** | CLOSED |
| **F-m2** | a control for the closing boundary | `perturb(..., where)` `:374-415`, `:642-680` | `--self-test` rc 0, **8** negative controls, head and tail per region, each named | CLOSED |
| **F-m3** | state the hash's extent | header `:74-82` | read; it also says the tail controls are what make the end covered | CLOSED |
| **F-m4** | the false skip reason / cover `AbaControlHandles` | `LanePinnedALiveAllocator()` `:194-202`, gate `:716-726` | measured: that lane now runs — it is one of the three that went red in §2.4 | CLOSED |
| **F-m5** | call `MagmaPipeAbaControlCoversKind` or delete it | exhaustive `constexpr` per-kind predicate + three `static_assert`s (`MagmaPipeArms.h:245-288`) | grepped: the *inner* predicate is pinned in every Magma build; the *wrapper* is still uncalled | CLOSED in substance — **F-v2-m3** for the wrapper |
| **F-m6** | "TWO in flight" is stale | folded into F-M4; the band's answer is 1 (`:2201-2203`) | read; matches the measured peak of 1 in the no-leak control | CLOSED |
| **F-m7** | separate "absent" from "zero" | `TextureUploadShapeScenario.cpp:326-383` + probe `CMakeLists.txt:622-633` | read: `clientEmitterExists` decides, `ctu == 0` is asserted when it does not, `ctu > 0 && ctu == emit` when it does. Verified the probe finds nothing on `712c9467` either, so the assertion stays on its zero arm through this integration | CLOSED |
| **F-m8** | narrow or document the `Layered` triple patch | header `:28-33` | read; narrowed in prose with the reason regexes may not name another package's helper | CLOSED |
| **F-m9** | `--expect-probes 4` | `test.yml:793-802` | ran it: `--expect-probes 4` **rc 0** ("4 probes, 0 skipped, 0 problems"), `--expect-probes 5` **rc 1** (`expected 5 probe(s), ran 4`). `clang++-20` kept with the reason | CLOSED |
| **F-m10** | verify the build directory | `:129-156`, reads PUSH **and** VERIFY | ran it against a synthetic pull cache (`PUSH:BOOL=OFF`, `VERIFY:BOOL=OFF`) → **rc 2**, naming both cache lines | CLOSED |
| **F-m11** | exec bits | `100644` | `ls -l`: both `p4a_*.sh` are `-rw-r--r--`, matching `p3a_untouched_regions.sh` and `g7_negative_control.sh` | CLOSED |
| **F-m12** | use `sawStale` | `HandleRecycleScenario.cpp:1328-1347` | read: `EXPECT_TRUE(sawStale)`, and the message names the third answer and prints the count | CLOSED |
| **F-m13** | declare the two `~/w7/notes/tools` rows | `gates-v2.md` §5 | read; ID-3 reassigns them and the report now says so. Correct | CLOSED |
| **R1** | not F's to fix | carried to D's round | ID-16 assigns it; nothing F can write through public GL closes it. ID-19 then made G9 white-box — that is **F v3's**, §6 | CARRIED |
| **R2** | the flip must not be forgettable | F-M5's fix | see §2.5 | CLOSED |
| **R3** | four commits fine | eight now, four of them rework | messages are eight single-line `[Type] (Scope): description`, C.5's three exact texts still present in order | CLOSED |
---
## 2. What I re-ran, and what it showed
### 2.1 G7 reaches "tripped" and exits 0 — and does the contract-tree thing on the contract tree
Two runs, one real and one instrumented:
* **On the clean tree with the real `build-push`** (configured Release/Ninja/clang from
`p4a-gates/build-push`'s own cache, `MOBILEGL_PIPE_PUSH=ON`): **rc 2**, both controls
`could-not-run`, each naming its header, its field, its owning package and the contract-stub
reason, and the summary saying exit 2 is the expected answer here. Confirmed independently that
`MG_Impl/Pipe/{FramebufferEmit,SamplerEmit}.h` assign nothing at `ecf9cb45` **and** at `712c9467`
(`grep -c '\.Layered[[:space:]]*=' = 0`, `.borderColorForm` likewise), so exit 2 stays the right
answer across this integration.
* **On a scaffolded tree** — the two headers given the one field copy each that B and C will carry,
committed so the tree was clean at the start, with `cmake`/`ctest` replaced by stubs on `PATH`
that make a suite red **iff** its header carries the control marker — the script produced:
```
[p4a-g7] [FramebufferEmit-Layered] the patched header still compiles, …
[p4a-g7] [FramebufferEmit-Layered] negative control tripped, naming Layered, and the tree is green again
[p4a-g7] [SamplerEmit-borderColorForm] negative control tripped, naming borderColorForm, …
[p4a-g7] ---- G7 (P4a descriptor emission) ----
Layered (MobileGL/MG_Impl/Pipe/FramebufferEmit.h): tripped
borderColorForm (MobileGL/MG_Impl/Pipe/SamplerEmit.h): tripped
[p4a-g7] both controls tripped and named their field; exit 0
G7_RC=0
```
`git status --porcelain` empty afterwards, both field copies restored.
**What the stub does and does not prove, stated plainly.** It replaces the *builder and the runner*,
not the script: every line of `run_control`, the verdict propagation, the repair, the traps and the
summary are the shipped ones. What it cannot prove is that a real `FramebufferEmitTest` goes red
with the field dropped — that is B's and C's contract and is the integrator's row. It **does** prove
what F-M1/F-M2 were about: that exit 0 is now reachable at all, which under v1's code it was not,
for two independent reasons.
The patcher's replacement value is the one thing the stub cannot vouch for, so I checked it
separately: `SamplerParameters::borderColorForm` is `BorderColorForm` at
`MG_Pipe/MGPipeValueTypes.h:485`, `enum class BorderColorForm : Uint8` at `:456`, and `MGPSurface::
Layered` is a `Uint8` at `MG_Pipe/MGPipeTypes.h:545`. `= {}` is valid for both; `= 0` is valid for
neither the scoped enum in an assignment. F-M1's one character is right.
### 2.2 — *(merged into 2.1)*
### 2.3 The interrupt, both ways
The launcher matters, exactly as `gates-v2.md` §3.2 warns. I launched through Python with
`os.setsid()` and `signal.signal(SIGINT, SIG_DFL)` in `preexec_fn`, waited until the patched line was
visible in the working tree, and then `killpg(SIGINT)`:
```
===== mid-way: the patch IS in the tree =====
M MobileGL/MG_Impl/Pipe/FramebufferEmit.h
75: dst.Layered = {} /* G7 NEGATIVE CONTROL: was src.Layered */;
===== sending SIGINT to the process group =====
[p4a-g7] [FramebufferEmit-Layered] rebuilding with the dropped field
[p4a-g7] restored MobileGL/MG_Impl/Pipe/FramebufferEmit.h; rebuilding from it
[p4a-g7] the tree is restored, rebuilt and green again
SCRIPT_EXIT_RC=-2 (killed by signal 2, i.e. 130 as a shell reports it)
===== tree AFTER the interrupt ===== (nothing tracked)
===== leftover control marker anywhere in MG_Impl/Pipe? ===== (none)
```
**One observation the integrator needs and the report does not say.** On this path the script dies
inside the `INT` trap's `kill -INT $$` (`:225`), so the `(INTERRUPTED - the remaining control(s) did
not run)` summary and the "the run was INTERRUPTED …; exit 2" wording at `:465` / `:477-479` are
**never printed**. That wording belongs to commit 8's *other* detection path, which I exercised on
its own by making the stub builder return 130 without signalling the script:
```
[p4a-g7] [FramebufferEmit-Layered] INTERRUPTED during the rebuild (exit 130). Repairing the tree and stopping:
[p4a-g7] ---- G7 (P4a descriptor emission) ----
Layered (…/FramebufferEmit.h): could-not-run
(INTERRUPTED - the remaining control(s) did not run)
[p4a-g7] the run was INTERRUPTED (exit 130); exit 2. …
G7_RC=2
```
Tree clean, second control not run. Both halves of commit 8 work; they simply produce different
exits (130 by signal, or 2 with the wording), and `gates-v2.md` §7 row 1 tells the integrator to
treat "exit 2 with the interruption wording" as a real finding without saying that a terminal Ctrl-C
usually produces the signal exit instead. One sentence.
### 2.4 The composite leak case really reads the band
I did not reuse the package's scaffold. In my own worktree I added two scaffold entry points to
`Harness/PipeSlotPeek.cpp` that mint and free **one band slot per churn round through the
allocator's only door**, `MGPipeSlots().AllocateComposite(lifetimeId)` / `.Free(ShaderCso, handle)`,
and called them from the composite round in `HandleRecycleScenario.cpp` — mint before `observe()`,
free after it unless `MGL_RR_LEAK_COMPOSITE` is set. Three runs of
`ctest -R EvictedPipelineComposites` (8 entries):
| tree | result |
|---|---|
| no scaffold (`ecf9cb45` as it is) | 8/8 **Skipped**, the "the client minted no ShaderCso (pipeline composites) [composite band] slot at all" reason |
| scaffold, **no** leak | the three live-allocator lanes **Passed** (they no longer skip — the band moved and came back); the five others skip |
| scaffold **+ one leaked band slot per round** | **3 failed of 8**, on `DirectGLES.HandleRecycle.Handles.`, `DirectVulkan.HandleRecycle.Handles.` and `DirectVulkan.HandleRecycle.AbaControlHandles.` |
The red is the one the case claims, and all three assertions fire:
```
[ HandleRecycle ] backend=DirectGLES ShaderCso (pipeline composites) [composite band]
live 2 -> 50 (peak 50), high water 983042 -> 983090 (floor 983040) over 48 create/draw/destroy rounds
HandleRecycleScenario.cpp:793: Failure … 48 slots never came back
HandleRecycleScenario.cpp:804: Failure … the … slot space grew with the churn
HandleRecycleScenario.cpp:809: Failure more than 1 churned … object(s) were live at once
```
The numbers reproduce `gates-v2.md` §3.3 exactly. The middle row is the one the report does not
have and that I think matters most: with a mint that *does* come back, the case **passes rather
than skips**, which is what says `ReadSpaceHighWaterFloor` (`:240-246`) is not swallowing the
assertions at the band base.
**And the split is real.** Running the whole `HandleRecycle` family with the band leaking, the only
failures are the three composite entries; every ordinary-space leak case — texture, renderbuffer,
framebuffer, sampler, sampler view, ordinary program — is unmoved. That is c0b's `HighWater(kind)`
= ordinary-only, measured rather than argued, and it is exactly the blindness F-M4 was about,
inverted.
**Consistency with c0b on `712c9467`.** `PeekPipeCompositeSlotLiveCount` / `…HighWater` /
`…BandBase` (`PipeSlotPeek.cpp:57-73`) map 1:1 onto `MGPipeSlotAllocator::CompositeLiveCount()`,
`CompositeHighWater()` and `kMGPipeShaderCsoCompositeSlotBase`, and I re-read all three at
`712c9467`: `SlotAllocator.h:108`, `:114`, `MGPipeHandles.h:100`, unchanged by c0c, c0d, c0e or
wire. `PipeSlotPeek.h:52-61` now states c0b's split correctly and `:82-90` explains why HighWater is
returned absolute rather than base-relative — which is the right call and is what makes the third
member necessary.
### 2.5 The ABA-flip probe: can the flip still be forgotten?
`mgl_itest_probe_for_two_symbols` (`CMakeLists.txt:438-463`) now answers "both regexes matched
somewhere under the backend directory" and prints `<file A> + <file B>`. The layout dependency v1
found is gone.
**Can it still be forgotten?** I looked for the three ways:
* **A new file** — no. The glob is `file(GLOB_RECURSE … CONFIGURE_DEPENDS "*.h" "*.hpp" "*.cpp"
"*.c")` and every file found is also appended to `CMAKE_CONFIGURE_DEPENDS` (`:444`), so both a new
file and an edit to an existing one re-run the configure.
* **A renamed scenario** — irrelevant: the probe is over the backend directory, not over the test
sources, and the marker is consumed by name (`MGITEST_HANDLE_ABA_OBJECTS_<backend>`) in
`HandleRecycleScenario.cpp:329-337`.
* **A file the glob does not name** — the one residual. `.inc` / `.def` / `.hh` / `.ipp` under
`MG_Backend/**` would be invisible. Measured: there are **no** non-`{h,hpp,cpp,c}` files under
`MG_Backend` in any of the four trees in flight (`p4a-gates`, `pipe@712c9467`, `p4a-esprytobj`,
`p4a-esprytdraw`), so it costs nothing today. Not raised as a finding; noted so the next reader
does not have to re-derive it.
**And the false positive the change trades against is not live.** I grepped all four trees:
`MG_Backend/DirectVulkan` matches `PipeHandleAbaControl` in exactly one file (`MagmaPipeArms.h`) and
matches `kMGPipeSubsystem{Framebuffer,TextureResources,Samplers,Programs}` in **none** — including
after F's own edit to `MagmaPipeArms.h`, which was my first worry, since `file(STRINGS … REGEX)`
matches comments and the new `static_assert` block names all six P4a *kinds*. It names
`MG_Pipe::MGPipeKind::Texture` and friends, never the four subsystem constants, so the conjunction
stays false. `MG_Backend/DirectGLES` matches neither today; it will match the constants once
esprytobj/esprytdraw land (`Managers.cpp`, `DirectGLES.cpp` — measured), and still not the knob. So
the six controls keep asserting the correct pixels through this integration, which is right.
### 2.6 The 0x9ff refusal matches Espryt's line, not a substring
`FindTheRefusalLine` (`ObjectSubsystemControlScenario.cpp:190-209`) requires one line that carries
`/ERROR]`, carries `REFUS`/`refus`, and names both bits. Two checks:
* **The severity token is right.** `MG_Util/Debug/Log.cpp` builds the header as
`"[" + time + "] [" + os + " " + thread + "/" + levelTag + "]: "` and `Log.h:81` defines
`MGLOG_E` with `levelTag = "ERROR"`, so `/ERROR]` is the literal spelling and nothing else in the
record can produce it.
* **The text is Espryt v2's, not v1's.** `p4a/esprytobj` is now at `b6169dba`; the shared helper is
`PipeSubsystemDependencyMissing` (`Managers.cpp:3523-3529`), `MGLOG_E("MGPipe: %s - REFUSING the
dependent bit and running the legacy arm. Set both bits, or clear both", what)`. I fed the four
real `what` strings through the matcher:
| line | 0x9ff case | 0x5ff case |
|---|---|---|
| sampler family: bit 11 set, bit 10 clear (`:3691-3695`) | match | match |
| texture family: bit 10 set, bit 11 clear (`:3652-3657`) | match | match |
| framebuffer: bit 9 set, bit 10 clear (`:3582-3586`) | no | no |
| texture family: bit 10 set, bit 7 clear (`:3627-3631`) | no | no |
| the same sentence demoted to `MGLOG_W` | no | no |
| an ERROR line naming both bits but not saying it refused | no | no |
So the assertion goes green on the real refusal and red on every near-miss I could construct.
That is a real gate. The one thing it does not check is the **direction** — F-v2-m1.
### 2.7 ID-15's 0x5ff arm
Ran `ctest -R 'ObjectSubsystemControl.RefusedTexture' -V`: `***Skipped`, from
`ObjectSubsystemControlScenario.cpp:634`, with the reason naming the marker, the four constants,
D-K2's fourth row, ID-15, package D's file, and the fact that the library did come up under 0x5ff.
Exactly the "SKIPs by name" ID-16 asked for.
**The expected refusal text is right**, and the arm will go **green** rather than red at
integration — see F-v2-m2.
---
## 3. Findings
Each has a file:line, a failure scenario and the refutation I tried. None is blocking.
### F-v2-m1 (minor, new) — the refusal matcher does not check the DIRECTION of the dependency
`MobileGL/MG_IntegrationTest/Scenarios/ObjectSubsystemControlScenario.cpp:190-209`, used at `:562`
and `:668`.
`FindTheRefusalLine(log, bitThatWasSet, bitThatWasNeeded)` applies `LineNamesTheBit` to each list and
ANDs the two results. That conjunction is **symmetric**: swapping the two arguments — which is
precisely what `:665-668` says makes the 0x5ff case different from the 0x9ff one ("the same line
shape … with the two bits' roles swapped") — cannot change the answer. Measured in §2.6: every row
of that table is identical in both columns.
**Failure scenario.** Package D's texture-family resolver refuses correctly under 0x5ff but prints
the mirror sentence. This is one copy-paste away: `Managers.cpp:3652` and `:3691` are forty lines
apart in the same file, share one helper and differ only in the `what` string, and the file's own
comment at `:3632-3633` calls the new row "the exact mirror" of the old one. The 0x5ff lane then
goes green on a refusal that told the operator the wrong dependency, which is exactly the class of
"the log says something plausible" defect F-M6 closed one level up.
**Refutation I tried, and it half succeeds.** For the wrong sentence to be in the 0x5ff lane's log,
`ResolveSamplerSubsystemArm` would have to run its refusal, and it only does so when bit 11 is set
(`:3687-3696`); 0x5ff leaves bit 11 clear, so on esprytobj's HEAD that line cannot appear. The
finding is therefore **not exploitable against today's Espryt** — it is an assertion that does not
check what its own comment says it checks, and that would stop being safe the moment the two
refusals are ever emitted from one place or one of them is made unconditional.
**Fix (small).** Require the ordering as well as the presence: find each spelling's offset in the
line and require the SET bit's offset to be smaller than the NEEDED bit's — Espryt's sentence is
`"<A> … is set but <B> … is clear"`, so the order is the direction. Two lines in
`LineNamesTheBit`'s caller.
### F-v2-m2 (minor, new, and it changes the integrator's sequencing) — §4's red window no longer exists
`gates-v2.md` §4 (and §7's third row) tell the integrator:
> **the moment esprytobj is integrated, this entry stops skipping and goes RED until package D's
> rework adds the bit-10-requires-bit-11 row** … Either sequence D's rework before F, or expect that
> red
That was true of `p4a/esprytobj` v1. It is not true now. `p4a/esprytobj` is at **`b6169dba`**, and
its commit **`a8c8824e`** — "*…and refuse bit 10 without bit 11*" — carries the row:
`ResolveTextureResourceSubsystemArm`, `Managers.cpp:3652-3657`,
`PipeSubsystemDependencyMissing(mask, kMGPipeSubsystemSamplers, "kMGPipeSubsystemTextureResources
(bit 10) is set but kMGPipeSubsystemSamplers (bit 11) is clear; …")`. So at integration the
`RefusedTexture` lane arms **and passes**.
**Failure scenario if the sentence stands.** The integrator either re-orders the phase to avoid a
red that is not there, or — worse — reads a genuine red on that lane as "expected, see §4" and ships
a resolver that refuses for the wrong reason or not at all.
**Refutation I tried.** (a) Could the bit-10-requires-**bit-7** refusal at `:3627-3631` fire first
and short-circuit the bit-11 one? No: `0x5ff = 0x1ff | 0x400` and `0x1ff` already carries bit 7
(`0x80`), so that check passes and `if (!refused)` at `:3651` lets the bit-11 check run. (b) Could
the arming marker fail to set? No: `MGITEST_HANDLE_REKEY_OBJECTS_DirectGLES` probes
`MG_Backend/DirectGLES` for the four constants and `Managers.cpp` names them (grepped). (c) Could
the sentence not match? No — §2.6's table.
**Fix.** One line in `gates-v2.md` §4 / §7 and in the integrator's re-run list: the 0x5ff arm is
expected **green** once esprytobj v2 is in; a red there is a real finding about D's resolver.
### F-v2-m3 (minor, residual of F-m5) — the wrapper is still uncalled
`MobileGL/MG_Backend/DirectVulkan/Renderer/MagmaPipeArms.h:292-294`. `MagmaPipeAbaControlCoversKind`
has no caller anywhere in the tree (grepped `MobileGL/**`); only `MagmaPipeAbaControlKindIsRekeyedHere`
is referenced, by the three `static_assert`s at `:273-288`.
**Failure scenario.** The rot v1 described, one level up: the wrapper's `&&` could be inverted or
one operand dropped and nothing would say so, because it is not `constexpr` (it reads
`MG_Config::Features`) and no assert can pin it.
**Refutation, and it mostly succeeds.** The substance of F-m5 *is* closed: the per-kind table — the
part that could be silently wrong about which kinds are covered — is now exhaustive with no
`default:` and pinned in both directions by asserts that compile in every Magma build, which is a
better answer than the token caller v1 asked for. The wrapper is three lines whose entire body is
the conjunction of two things that are each pinned or trivial. Judged: **carry**, or delete the
wrapper and let the two pinned pieces stand alone. Not worth a rework round.
### F-v2-m4 (trivial, new) — `REPAIR_RC` is write-only
`scripts/p4a_descriptor_negative_control.sh:179`, `:188`, `:193`, `:199`. It is set to 2 on three
failure paths inside `repair()` and never read anywhere. The header's claim at `:90` — "*a repair
that itself fails downgrades the verdict to 2*" — is true, but it is delivered by `run_control`'s
`if ! repair; then … CONTROL_VERDICT=could-not-run` at `:407-413`, not by this variable. A reader
tracing the claim finds a dead one. Delete it, or read it after the loop so a trap-time repair
failure also reaches the exit code.
### Nothing new elsewhere
* **Hygiene: clean.** Eight single-line `[Type] (Scope): description` messages, no bodies, no
`Co-Authored-By` and no other attribution (grepped for it and for tool names). Only F's nine files
plus the granted `MagmaPipeArms.h` and the two scripts. No trailing whitespace in either script.
Both `scripts/p4a_*.sh` are `100644`.
* **No scaffold leftovers.** `tmp/gatesF-g7proof` does not resolve; no commit reachable from any ref
mentions the scaffold; the only file in the tree containing the word `SCAFFOLD` is the
pre-existing `MG_Util/SelfTest/DriverBugProbes.cpp`. `p4a/gates` is the only branch containing
`ecf9cb45`.
* **`test.yml`.** The rework's only change to it is the include-closure step; `git diff HEAD~5
ecf9cb45 -- .github/workflows/test.yml` is that hunk and nothing else. The **TEMPORARY** trigger
lines at the top (`:9`) are untouched and **`BASELINE` is still `37da3c3a`** (`:1599`), with both
P3a and P4a region gates reading it.
* **The itest CMake.** The rework adds exactly one `TEST_PREFIX` and one `TEST_FILTER`
(`DirectGLES.ObjectSubsystemControl.RefusedTexture.` / the 0x5ff case) and renames nothing —
`git diff HEAD~5 ecf9cb45` over that file shows two `+` lines and no `-` line among them. Re-derived
the pin audit on the whole file: every `MOBILEGL_PIPE_PUSH=` env pin is `0x1fff` except
`ResourceSubsystemControl`'s Off lane and `LargeArenaAdoption`'s Off lane (`0x7f`, `:1304`,
`:1372`), `ObjectSubsystemControl`'s Off lane (`0x1ff`, `:1438`), the two refusal lanes
(`0x9ff` `:1443`, `0x5ff` `:1448`), the CSO Off lanes (`0x8000000000001fff`) and the three
`MOBILEGL_PIPE_PUSH=0` arm lanes. Exactly C.5's shape.
* **G14, re-derived.** `ctest --test-dir build-push -N` on my own build of `ecf9cb45`: **2711**
names; against `~/w7/p4a-before-ctest-names.txt` (37da3c3a, 2588 names, `LC_ALL=C`) —
**0 removed, +123 added**, of which 109 carry a `DirectGLES.`/`DirectVulkan.` prefix (F's itest
entries) and 14 are the contract's unit cases (`PipeCatalogue` ×4, `ProgramArtifactsCodec` ×4, the
five `*Emit.TheEmitterIsOneNeverDestroyedProcessSingleton`, `CompositeResolver.TheCompositeBandHas
ExactlyOneDoor`). The report's 2711 / 0 / +123 are correct.
*(A caution for whoever re-takes this: extracting names with `awk '{print $3}'` truncates the five
`Shapes/DemoteFloat64EsslTest…` parameterised names at their first space and manufactures a
spurious 5 removed / 5 added. Use `sed -n 's/^ *Test *#[0-9]*: //p'` and `LC_ALL=C`.)*
* **G5, re-derived.** `p4a_untouched_regions.sh 37da3c3a ecf9cb45` **rc 0**, 17 rows;
`--self-test` **rc 0**, 3 positive + **8** negative controls, every one tripped and named; the
exit contract is `2/2/2/2/2` for no args / bad `<ref-a>` / bad `<ref-b>` / 3 args /
`--self-test extra`; `p3a_untouched_regions.sh` is still rc 0 both ways at this head.
---
## 4. The rebase report — `ecf9cb45` onto `feat/disaggregated` = `712c9467`
Run in a throwaway worktree (`git worktree add --detach … ecf9cb45`, then
`git rebase refs/heads/feat/disaggregated`). **`REBASE_RC=0`, 8/8 commits, no conflict, nothing to
resolve.** Head `01c0ea21`, the eight commits in order on top of `712c9467`.
The reason is structural rather than lucky: `git diff --name-only 2cb44039 refs/heads/feat/
disaggregated` and the same for F are **disjoint** — pipe moved `MG_Impl/Pipe/Tracker.h`,
`MG_Pipe/{MGPipeTypes.h, PipeApply.{h,cpp}, PipeFields.def}` and eight `MG_Test/Pipe/*Test.cpp`
(14 files, +4982/−116); F owns `MG_IntegrationTest/**`, `MagmaPipeArms.h`, `scripts/p4a_*.sh` and
`test.yml`. `comm -12` over the two lists is empty.
**ID-28's three named questions, answered on the rebased tree:**
| question | answer |
|---|---|
| `PeekPipeCompositeSlot*` vs c0b's `CompositeHighWater` API | Unchanged. `SlotAllocator.h:108` `CompositeHighWater()`, `:114` `CompositeLiveCount()`, `MGPipeHandles.h:100` `kMGPipeShaderCsoCompositeSlotBase` all present at `712c9467` with the same signatures; the three peeks are verbatim wrappers. c0c/c0d/c0e/wire did not touch `SlotAllocator.*` or the band constants |
| the itest CMake pins | Untouched by pipe — `MG_IntegrationTest/**` is not in pipe's changed-file list. The lanes' `0x1fff` / `0x1ff` / `0x9ff` / `0x5ff` / `0x7f` pins are still the phase constants they name |
| the negative-control scripts' targets after c0c renamed `MGPSurface::Pad0` → `TextureTarget` and wire changed `PipeApply`'s signatures | **Both scripts survive.** G7 targets `MGPSurface::Layered` (`MGPipeTypes.h:545` on the rebased tree — c0c renamed the *other* two bytes, `Pad0` → `Uint16 TextureTarget` at `:566`, and says so in the comment at `:549-551`) and `SamplerParameters::borderColorForm` (`MGPipeValueTypes.h:485`, untouched). Neither script names `PipeApply` at all. G5's seventeen rows are backend function/namespace names in `Managers.cpp`, `DirectGLES.cpp` and `Utils.cpp`, none of which pipe touched: **`p4a_untouched_regions.sh 37da3c3a 712c9467` is rc 0 with the same 17 shas, byte-identical to the `37da3c3a → ecf9cb45` listing** |
**The rebase is not just textually clean — I built and ran it.** Configured and built the rebased
worktree (Release/clang/Ninja, `MOBILEGL_PIPE_PUSH=ON`, integration tests on): **BUILD_RC=0**, and
| on `ecf9cb45` rebased onto `712c9467` | result |
|---|---|
| `ctest -L unit` | **1684/1684**, 0 failed — the same 1684 ID-28 records for pipe's post-merge |
| `ctest -R 'HandleRecycle\|ObjectSubsystemControl\|TextureUploadShape\|TextureParamsWithoutASamplerView'` | **165/165**, 0 failed |
| `p4a_untouched_regions.sh 37da3c3a HEAD` / `--self-test` | **rc 0** / **rc 0** |
| `p4a_descriptor_negative_control.sh build-push` | **rc 2**, both `could-not-run` — still the right answer, the emit headers are still the contract's stubs |
| `ctest -N` | **2759** (2711 + the 48 names wire's real emission cases add) |
So `PipeSlotPeek.cpp` still compiles against c0b's allocator on the integrated tree, the four new
lanes still register, and no probe flipped.
**What still moves at integration, and it is not nothing.** Wire's rework put real cases into seven
`MG_Test/Pipe/*EmitTest.cpp` suites, so (a) G7's "`N` matching test(s) before the patch" line changes
(and, better, the suites are now real, so the two controls will have something to make red as soon
as B and C land); (b) the unit counts, the `ctest -N` totals and the G14 delta all move without
anything F owns changing. That is `gates-v2.md` §7's last row and it is right. G7's verdict on the
rebased tree is still **rc 2, both `could-not-run`** — the emit headers are still the contract's
stubs at `712c9467`, which I checked directly.
I also confirmed that none of the itest **probes** flips at this integration: `MG_Impl/Pipe` on the
rebased tree still emits neither `FramebufferEmissions` nor `ClientTextureUploadEmissions`, and
`MG_Backend/**` still names none of the four subsystem constants — so `ObjectSubsystemControl`'s
emission case, `TextureUploadShape`'s client half, the six `HandleRecycle` P4a cases' Handles arm
and both refusal lanes keep the arming they have today. No surprise reds land with wire.
**Caveat.** F integrates **last** (ID-29: after D v2), so `feat/disaggregated` will have moved again
by then; this rebase says the shape is clean, not that the one at integration time will be. Section
6's numbers must be re-taken there regardless.
---
## 5. On ID-19's G9 — correctly absent from v2
ID-19 makes G9 a **WHITE-BOX** assertion and assigns it to "gates v3 / F's verification round";
ID-16, which specified *this* round, does not mention it. v2 does not contain it, and that is right,
not an omission. `gates-v2.md` §5's "Not fixed, and why" says the same thing about R1's residual gap
and points at D — also right: the gap is that the four public-GL cases catch *emitted-but-not-applied*
and cannot catch *deferred-to-first-view*, because the sample that observes the parameter is what
pushes it (`TextureParamsWithoutASamplerViewScenario.cpp:243-257`, and the mechanism v1 §3.4
derived, which I re-read and still agree with).
---
## 6. What F v3 must contain
1. **G9 as a white-box assertion (ID-19, brief section F).** The shape the gap dictates: the four
existing public-GL cases stay as the end-to-end control, and each gains a reading taken **while
the texture is still attachment-only — before the observing sample repairs the state**, through a
new isolated harness translation unit (`MG_IntegrationTest/Harness/PipeApplyPeek.{h,cpp}`, for
`PipeSlotPeek`'s stated reason: the `MG_Pipe` headers and the GL headers are not meant to meet in
one TU). It needs **both** sides of the seam, because one alone reproduces the blind spot at a
lower level:
* **the applier's own params record** for that texture handle — that a `set_texture_params`
record exists at the serial the client emitted, and that the field the case moved (Swizzle /
`DepthStencilMode`) is in it;
* **Espryt's applied state** for that texture's backend twin — that the driver-side value is that
value **now**, not after the first sampler view is created;
* and that **no sampler view exists for that texture yet**, which is what turns "applied" into
"applied without one" and is the whole claim.
Assertion shape: after the frame and *before* any sampling, (a) record present at the emitted
serial, (b) twin's applied value equals it, (c) no sampler view for that handle. A peek that
cannot look must `GTEST_SKIP` by name, exactly like `PipeSlotPeek` (pull build, Android hidden
visibility), and it must arm on **package D's applier/backend state**, not on the emitter markers
B and C set — they are different questions and a shared marker would re-create F-M5's shape.
2. **F-v2-m1** — make the refusal matcher check the direction (offset ordering), so the 0x5ff and
0x9ff arms really are different assertions.
3. **F-v2-m2** — correct §4/§7: the 0x5ff arm is expected **green** once esprytobj v2 is in, and a
red there is a finding about D's resolver.
4. **F-v2-m4** — delete or read `REPAIR_RC`.
5. **F-v2-m3** (optional) — call or delete `MagmaPipeAbaControlCoversKind`.
6. **The rebase and section 6, re-taken on the pipe of the day** — G1, the three `-L unit` runs, the
pull/push name diff, the G14 delta, `-L integration-gpu` on both builds. The emission suites now
carry real cases, so every one of those numbers moves for reasons outside this package.
7. **One sentence** on the interrupt: a terminal Ctrl-C exits **by SIGINT (130)** and prints no
summary; the `(INTERRUPTED …)` wording at exit 2 belongs to the signalled-child path. Both are
correct behaviour; §7's first row currently implies only the second exists.
Carried, unchanged: R1's second shape is D's verification round; wire's cube-face case is wire's.
---
## 7. What the integrator must re-run (delta to `gates-v2.md` §7)
`gates-v2.md` §7 stands. Amend two rows and add one:
| row | amendment |
|---|---|
| `ctest -R 'ObjectSubsystemControl.RefusedTexture'` as soon as esprytobj is integrated | **Expect GREEN, not red.** esprytobj `a8c8824e` already carries D-K2's fourth row; the sentence it emits matches the assertion (verified). A red here is a real finding (F-v2-m2) |
| the G7 row | A terminal Ctrl-C exits **130 with no summary**; exit 2 *with* the interruption wording means a child died on a signal the script itself never received. Both mean "nothing here is a verdict about the controls" |
| **new** | `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` at every integration step, not only after D and E: it is rc 0 against `712c9467` today with the same 17 shas, which is the cheapest possible check that a merge did not quietly touch Espryt's protected regions |
---
## 8. Method note
`p4a_descriptor_negative_control.sh`'s "tripped" path was exercised with `cmake` and `ctest`
replaced by stubs on `PATH`, against a scaffolded pair of emit headers, in a private worktree. The
script itself was the shipped one and every line of its control flow ran; what was stubbed is the
builder and the runner. The composite-band experiment used a **real** build of the integration test
(`build-push`, Release/clang/Ninja, `MOBILEGL_PIPE_PUSH=ON`, llvmpipe) with a scaffold that mints and
frees band slots through `AllocateComposite` / `Free`. The SIGINT proof was launched through Python
with the disposition reset to `SIG_DFL` in a new session, which is the only way to measure the
script rather than the launcher (`gates-v2.md` §3.2, confirmed).
Both private worktrees, their build directories and all scratch files under `~/w7` have been
removed.
@@ -0,0 +1,459 @@
# P4a package F — `gates`. Result, v1
Four commits on `refs/heads/p4a/gates`, branched from the tag `refs/tags/p4a/contract` = `08192d72`.
**Not pushed.** Working tree clean. 11 files, **+3831 / −57**.
| # | hash | message (exactly as C.5 gives it, single line, no attribution) |
|---|---|---|
| 1 | `0bc9aafa` | `[Test] (Pipe): reproduce the texture, framebuffer, renderbuffer, sampler, view and program handle ABA through public GL and prove the pre-rekey guards are what stops it` |
| 2 | `4f006f3c` | `[Test] (Espryt): assert a glTexParameter on a texture that only ever was an attachment, an image binding or a copy endpoint reaches the driver` |
| 3 | `70868f93` | `[Test] (Pipe): switch P4a's four object subsystems off against the shipping mask and record the texture upload shape the two counters make visible` |
| 4 | `303a9dc8` | `[CI] (Pipe): gate that the unpack ring, the attachment permutation, the depth-stencil sampling core and the format caveat did not move` |
**Commit 3's message is not in C.5** — C.5 names three. `ObjectSubsystemControlScenario` (G12) and
`TextureUploadShapeScenario` (D-D4) are in C.5's file table but belong to none of the three messages,
and putting them under either of the two `[Test]` messages would have made the message describe
something else. **Declared deviation F-1**, below. Every commit builds on its own: the CMake source
list and the lane registrations were staged so that no commit names a scenario file that does not
exist in it (verified by walking each commit's `CMakeLists.txt` against its own tree).
---
## 1. Verdict on the hard rules
| rule | result |
|---|---|
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0` | **0 added / 0 removed / 0 renamed / 0 resized**, rc 0. The pull `.so` is byte-for-byte the same size as `$BASE`'s: 19114360 file, 10806323 `.text`. None of this package's files reaches the library. |
| every ctest name at the tag still exists (**G14**) | `comm -23 ~/w7/p4a-before-ctest-names.txt <names at HEAD>` **empty**; **+119 added** |
| ctest names pull == push (**G2**) | `diff` empty, **2707** names in each |
| `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` | **rc 0**, seventeen regions |
| `bash scripts/p4a_untouched_regions.sh --self-test` | **rc 0**, 3 positive + **4 negative** controls, each tripped and named |
| `bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD` | **rc 0** (and `--self-test` rc 0) |
| `bash scripts/p4a_descriptor_negative_control.sh build-push` | **rc 2**, naming both absent field copies — the contract tree's correct answer |
| `ctest --test-dir build-verify -R 'HandleRecycle\|Leak'` | **180/180 passed, 0 failed**; every non-assertion is a named SKIP |
| `ctest --test-dir build-push -R 'ObjectSubsystemControl\|TextureParamsWithoutASamplerView\|TextureUploadShape'` | **18/18 passed, 0 failed** (8 + 10 across two runs); named SKIPs only |
| `ctest -L unit`, three builds | **1635 / 1635 / 1635**, 0 failed |
| `ctest --test-dir build-push -L integration-gpu -j 6` | **1072/1072 passed, 0 failed** |
| only this package's files | yes — `MG_IntegrationTest/**`, `.github/workflows/test.yml`, `scripts/p4a_*.sh`, and F's one granted DirectVulkan file `Renderer/MagmaPipeArms.h` |
| no push, no other worktree, no attribution lines | yes |
**Not run here, and why:** the retrace sweeps, the verify retrace and the device work are D.3/D.4's
and need `~/w7/pipe`, which package agents never touch (ID-3). `build-bench` does not exist in this
worktree (`wsl_tree.sh` creates `build-linux`, `build-push`, `build-verify`), so C.5's
`cmake --build build-bench && ctest -L benchmark` line could not run; **nothing in this package
touches `MG_Benchmark/`**, so there is nothing for it to have broken — the integrator's own bench
tree covers it.
---
## 2. Per-file summary
| action | file | what |
|---|---|---|
| MODIFY | `MG_IntegrationTest/Harness/PipeSlotPeek.{h,cpp}` | `PipeSlotKind` gains `Texture, Renderbuffer, Framebuffer, SamplerCso, SamplerViewCso, ShaderCso`. `Translate` is now an exhaustive switch with **no `default:`** — a kind added without a decision is a `-Wswitch` warning rather than a row that silently counts `VertexElementsCso` and reports "did not leak" about a kind it never looked at. `ShaderCso` covers ordinary programs **and** band composites, because that is what the allocator has. |
| MODIFY | `MG_IntegrationTest/Scenarios/HandleRecycleScenario.cpp` | +1057 lines. Four new ABA cases (renderbuffer, sampler object, sampler view, program); the two existing texture/framebuffer cases become real controls; seven `…ReturnTheir…Slots` leak cases; three new gates (`ThisBackendsObjectRekeyHasLanded`, `ObjectAbaControlIsWiredHere`, `SkipUnlessTheObjectHandlePathIsAssertableHere`) and one shared assertion block (`AssertChurnReturnsEverySlot`). |
| MODIFY | `MG_Backend/DirectVulkan/Renderer/MagmaPipeArms.h` | The **only** DirectVulkan file P4a touches. `MagmaPipeAbaControlDefeatsIdentity` keeps its body; beside it, `MagmaPipeAbaControlCoversKind(MGPipeKind)` states **per kind** what the knob defeats — true for `VertexElementsCso` and `Buffer` (the only two kinds `MagmaPipeIdentityTables` mints), false for P4a's six, with the one change that flips it written out. Inside the file's existing `#if MOBILEGL_PIPE_PUSH`, so the pull build is untouched (G1 0/0/0/0 confirms). |
| CREATE | `MG_IntegrationTest/Scenarios/TextureParamsWithoutASamplerViewScenario.cpp` | G9. D-E3's four cases, DirectGLES only, every setup step through the DSA entry points so no case ever binds its texture to a unit before the observation. |
| CREATE | `MG_IntegrationTest/Scenarios/TextureUploadShapeScenario.cpp` | D-D4, recorded not gated. |
| CREATE | `MG_IntegrationTest/Scenarios/ObjectSubsystemControlScenario.cpp` | G12. `0x1fff` vs `0x1ff`, plus the `0x9ff` dependency refusal. |
| MODIFY | `MG_IntegrationTest/CMakeLists.txt` | +280 lines: three sources, one new probe function, five new capability markers, every `0x1ff` phase pin raised, four new lanes. §4. |
| CREATE | `scripts/p4a_untouched_regions.sh` | G5, seventeen regions across three files. §5. |
| CREATE | `scripts/p4a_descriptor_negative_control.sh` | G7, two field drops. §6. |
| MODIFY | `.github/workflows/test.yml` | `BASELINE` → `37da3c3a`, two new `pipe-gates` rows, three new `-R` alternatives on the push-build control step. §7. |
---
## 3. What each scenario asserts, and how it skips on an unimplemented tree
Every arm that needs a subsystem this tree does not have **SKIPs with a named reason**. No
registration is withheld, no arm vanishes, and no arm asserts something that cannot exist yet
(ID-2). The decision is the BUILD's, through content probes with `CONFIGURE_DEPENDS`, never a
hand-maintained list.
### 3.1 `HandleRecycleScenario` — the six ABA cases (G8)
**On a complete tree** each case builds an ABA through public GL — an object is created, drawn with
for `kWarmupFrames`, unbound, deleted, and immediately replaced at the same GL name with a
byte-identical configuration and different contents — and asserts the pixels come from the
replacement. On the `AbaControl` arm, where the knob defeats the identity half of the memo key, the
**corruption is the assertion**.
| case | what a stale key would produce | observable |
|---|---|---|
| texture (existing, now a control) | the dead texture's texels | sampled colour |
| framebuffer (existing, now a control) | the clear lands in the DEAD framebuffer | **both** attachments read back: FRESH = (replacement green, dead red), STALE = dead turned green. P4a added the dead attachment's red warm-up clear so the corruption has a place to be visible, not just an absence |
| renderbuffer | the dead 4×4 storage under an 8×8 replacement | 8×8 readback all green, plus the framebuffer's completeness |
| sampler object | the dead sampler's border colour | `GL_CLAMP_TO_BORDER` sampled at a constant UV outside [0,1] — one colour for the whole viewport, and the border colour is the parameter with the fewest other paths to the driver |
| sampler view | the dead texture through a LIVE sampler object | a bound sampler object is what makes this a different question from the texture case: the view's key names the texture, and the sampler half deliberately does not move |
| program | the dead program's fragment output | the colour is baked into the source, not a uniform — a uniform would be re-set on the replacement and hide the inheritance |
**On this tree** the six SKIP on the `Handles` arm with *"subsystem not implemented on this tree: …
no source under `MobileGL/MG_Backend/<backend>` names any of
`kMGPipeSubsystem{Framebuffer, TextureResources, Samplers, Programs}`"* — and they PASS on the
`Legacy` arm (asserting today's address/`weak_ptr` guards, which is exactly what "the replacement has
to be at least as strong" means).
### 3.2 The `AbaControl` arm for the six kinds — a finding, not an omission
`armExpectsCorruption` is `ObjectAbaControlIsWiredHere()`, which is
`knob-consumer-for-this-backend AND object-re-key-for-this-backend`. **Both are false on every
backend today, and the reason is structural rather than temporal**:
* `MOBILEGL_PIPE_HANDLE_ABA_CONTROL` has exactly one consumer in the tree,
`MagmaPipeAbaControlDefeatsIdentity`, and its consumers are Magma's **vertex-input** keys;
* `MagmaPipeIdentityTables` mints `{slot, gen}` for **two** kinds, `VertexElementsCso` and `Buffer`.
A texture, a framebuffer, a sampler, a view and a program are still reached from their frontend
objects on that backend, and moving them onto handles is **P7's** (`ROADMAP.md:24`, D-Q);
* on DirectGLES the knob has no consumer at all, which is why the `AbaControl` lanes are
DirectVulkan-only in the first place.
So **D.2's expectation that the six kinds' `.AbaControl` arms PASS by asserting the corruption cannot
be met on this tree, and no package in P4a owns the file that would change that** (the Espryt knob
consumer would live in `MG_Backend/DirectGLES/SlotTables.h`/`Managers.cpp`, which C.7 gives to
package D; the Magma one is P7). Rather than a lane that asserts a corruption nothing can produce —
a hard red on an always-on `integration-gpu` lane, the exact failure this file's own header records
having had once — the arm **asserts the correct pixels and says, on stdout and in
`RecordProperty("aba_control_wired", 0)`, that it is not a control for that kind yet**. One `if` in
a backend's `GetOrCreate`/`FindByHandle`, the shape `MagmaPipeClaimSlotMemos` already has, flips all
six. **Declared deviation F-2.**
### 3.3 `HandleRecycleScenario` — the seven leak cases (G8b)
Shape: two warm-up rounds, then `kChurn = 48` create/draw/destroy rounds, asserting
`liveAfter == liveBefore`, `highWaterAfter == highWaterBefore` and
`peakLive − liveBefore <= maxInFlight`. `peakLive` is sampled **inside** the round through an
`observe()` callback the round must call while its object is still alive — sampled after the destroy
the third assertion would be vacuous, and it is the one that catches a death path that works but runs
at the wrong time.
Three ways a case declines to assert, all of them named:
1. not the `Handles` arm → the other lanes run `MOBILEGL_PIPE_PUSH=0`, where there is no allocator;
2. `PeekPipeSlot*` returns false → "could not look" is not "did not leak";
3. **nothing of that kind was ever minted** (`highWater == 0 && peakLive == 0 && liveAfter == 0`) →
*"the client minted no `<kind>` slot at all over 50 rounds"*. This third one is P4a's addition and
it is what stops six of the seven cases from being `0 == 0` greens before the emitters land.
**Measured on the contract tree, DirectGLES `Handles` lane** (the numbers are in
`p4a-handlerecycle-before-verbose.log`):
| case | reading | verdict |
|---|---|---|
| `DestroyedVertexArraysReturnTheirVertexElementsSlots` (P3a's) | live 1→1 (peak 1), hw 3→3 | pass |
| `DestroyedTexturesReturnTheirTextureSlots` | live 3→3 (peak 4), hw 5→5 | pass — **the client already mints and frees Texture slots at `c0`** |
| `DestroyedRenderbuffersReturnTheirRenderbufferSlots` | live 0→0 (peak 1), hw 2→2 | pass |
| `DestroyedFramebuffersReturnTheirFramebufferSlots` | live 0→0 (peak 1), hw 2→2 | pass |
| `DestroyedSamplersReturnTheirSamplerCsoSlots` | live 0→0 (peak 1), hw 2→2 | pass |
| `DestroyedProgramsReturnTheirShaderCsoSlots` | live 1→1 (peak 1), hw 2→2 | pass |
| `EvictedPipelineCompositesReturnTheirShaderCsoSlots` | live 1→1 (peak 1), hw 2→2 | pass, **partially armed** — see below |
| `DestroyedTexturesReturnTheirSamplerViewSlots` | live 0→0 (peak 0), hw 0→0 | **SKIP**, "the client minted no SamplerViewCso slot at all" |
On the DirectVulkan `Handles` lane every one of the seven SKIPs on the same "nothing minted" rule,
which is the honest reading for a backend whose object kinds are P7's — and it is exactly where the
cases have to run once they arm, because P3a's C-1 was a **Magma** leak (ID-8).
**The composite case is only partially armed today.** `ShaderCso` is minted (so the "nothing minted"
skip does not fire and the case is not vacuous about the *kind*), but no slot comes out of the
composite band yet: `CompositeResolver` is package C's. The case therefore asserts today that
pipeline churn leaks no `ShaderCso`, and asserts the two-release-path property — LRU eviction **and**
the composite `ProgramObject`'s destructor, the pair D-H7 calls out — when C lands. It also depends
on contract review v1's **M5** (`HighWater(ShaderCso)` returning the band top makes the high-water
assertion vacuous); the fix is in flight on `c0b` and this case is one of its consumers.
### 3.4 `TextureParamsWithoutASamplerViewScenario` (G9) — **the mandatory red could not be produced, and the reason is a finding**
The four cases put a texture through exactly one reachability path, move a parameter while it is
reachable only that way (through `glCreateTextures` / `glTextureStorage2D` / `glTextureSubImage2D` /
`glTextureParameteri`, so no setup step ever binds it to a sampler unit), and sample it once at the
end.
**All four are GREEN on `08192d72`** — including
`AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver`, which D-E3 says must be RED.
`p4a-texparams-before.log` is the run. The mechanism, re-opened at the base ref:
* a texture parameter's only public-GL observable is a **sample** — nothing about an attachment, an
image binding or a copy endpoint reads a swizzle or an aspect mode;
* a sample puts the texture on `SyncNeccessaryTextures`' **unit** list, and that walk calls
`SyncTextureParamsToBackend` for every entry whose `IsDrawSyncClean` is false
(`DirectGLES.cpp:1896-1898`);
* `IsDrawSyncClean` is false **whenever the frontend parameter version has moved** since the last
sync (`Managers.h:1399-1416`: `m_syncedTextureParamsVersion != paramsVersion`).
So the D-E3 gap is real — between the parameter change and the next sampler binding the driver
really is not told — and it is closed by the only thing that can see it. **No public-GL integration
scenario on a monolith tree can produce ROADMAP.md:20's `落地前必须红` artefact for this case.**
Producing it needs an observation of the *driver's* texture object taken while the texture is still
read-attachment-only, i.e. a probe inside `MG_Backend/DirectGLES` — package D's files (C.7), not
this package's.
What the scenario is instead, stated in its own header so nobody reads a green as more than it is:
a **regression net around D10**. It goes red if any of the four reachability paths is ever made to
depend on the texture having a sampler **view** — which is the coupling P4a's resource-addressed
`set_texture_params` removes and a later phase could reintroduce. **The integrator's ruling is
needed** (§9). **Declared deviation F-3.**
### 3.5 `ObjectSubsystemControlScenario` (G12)
Workload: a user framebuffer with a texture attachment (bit 9), a texture with parameters and a
sub-region upload per iteration (bit 10), an explicit sampler object on the unit (bit 11), a program
with a default-uniform write (bit 12) — all four families, four times, in one counted window.
* **On (`0x1fff`)**: `fbe + sve + sse + sie + ctu > 0`, and `fbe > 0` on its own so a large upload
count cannot hide a framebuffer family that never emitted.
* **Off (`0x1ff`)**: every one of those five is **zero** — the dead-switch reading.
* **Both**: the pixels do not move.
* **Refused (`0x9ff`)**: the library's own log must **name both bits** (the constant's name or its
hex mask, so the assertion does not pin the wording), and the run must still draw what every other
lane draws — a refusal runs the LEGACY arm, so the pixels are the one thing it may not change.
**On this tree** the on/off case SKIPs on `MGITEST_PIPE_OBJECT_EMITTER_PRESENT` (no `MG_Impl/Pipe`
source emits `FramebufferEmissions`, so the counters are structurally zero in *both* arms and their
difference is not observable). The refusal case SKIPs on `MGITEST_HANDLE_REKEY_OBJECTS_DirectGLES`:
D-K2's refusal lives in `ResolveSamplersSubsystemArm()`, package D's file, and a backend that does
not honour P4a's mask cannot refuse a dependency inside it. **That skip was added after measurement**
— the first cut of the case FAILED on the contract tree, which is precisely the "fail on an
unimplemented subsystem" ID-2 forbids.
### 3.6 `TextureUploadShapeScenario` (D-D4, recorded)
Asserts only what is assertable before the shape policy is finished: the numbers could be read at
all, the server bracket's own arithmetic (`box + rect == emit`, `jobs >= emit`), and that the two
sides agree **when both are non-zero**. Everything else is `RecordProperty` + stdout.
**Recorded on the contract tree**, 3 frames × (40 scattered 2×2 rects + one 64×8 contiguous band):
```
[ TextureUploadShape ] backend=DirectGLES frames=3 scattered_rects_per_frame=40
server[emit=6 box=6 rect=0 jobs=6] client[ctu=0]
```
Six emissions (3 frames × 2 textures), **all six took the union-box shape**, 6 driver jobs — i.e.
Espryt collapsed 40 scattered rects into one box on every frame, on llvmpipe. The client side reads
zero and the case says so rather than reporting a divergence against an emitter that does not exist.
This is the P3b/P4b gate's baseline.
---
## 4. `MG_IntegrationTest/CMakeLists.txt`
**Every phase pin was re-read, not pattern-replaced.** Raised to the P4a constant:
`MGL_ITEST_HANDLES_ARM_KNOBS` (`0x1ff`→`0x1fff`), the two CSO **On** lanes, the CSO **Off** lanes'
`0x80000000000001ff`→`0x8000000000001fff` (the mask moves with the phase, the control is bit 63),
`ResourceSubsystemControl`'s On lane, both `MapPersistentRoundtrips` lanes and
`LargeArenaAdoption`'s On lane. **Left alone**: the two `0x7f` pins
(`ResourceSubsystemControl`'s Off lane and `LargeArenaAdoption`'s Off lane) — `0x7f` is P2's constant
and those lanes' named A/B control. The three comment blocks that explained the old masks were
rewritten to explain the new ones; a stale comment beside a moved pin is how the next phase gets it
wrong. **Measured: those lanes are green at the raised mask** — `CsoContentAddressing |
ResourceSubsystem | MapPersistentRoundtrip` is 28/28 on `build-push` and 36/36 on `build-verify`.
**New probes** (all inside the existing `if (MOBILEGL_PIPE_PUSH)`, all content probes over a
directory rather than filename globs, all `CONFIGURE_DEPENDS`):
| marker | probe | gates |
|---|---|---|
| `MGITEST_HANDLE_REKEY_OBJECTS_<backend>` | `kMGPipeSubsystem(Framebuffer\|TextureResources\|Samplers\|Programs)` under that backend | the six ABA cases' `Handles` arm; the refusal case |
| `MGITEST_HANDLE_ABA_OBJECTS_<backend>` | **conjunction**: `PipeHandleAbaControl` **and** a P4a subsystem constant, in ONE source | whether the six expect the corruption |
| `MGITEST_PIPE_OBJECT_EMITTER_PRESENT` | `FramebufferEmissions` under `MG_Impl/Pipe` | `ObjectSubsystemControl`'s emission case |
The conjunction needed a new helper, `mgl_itest_probe_for_two_symbols`. A single-regex probe for
`PipeHandleAbaControl` would hit `MagmaPipeArms.h` **today** and arm six controls on a backend where
the knob cannot reach any of their kinds; a single-regex probe for the subsystem constants will be
true for any backend that honours the mask, long before anyone wires the knob. What the arm needs is
one source that does both.
**New lanes** (all `DirectGLES`, all registered in every build so G2's name-for-name comparison
holds, each with a private `MOBILEGL_LOG_FILE_PATH` and a `TEST_FILTER` naming ONE case because the
library opens its log `fopen(path, "w")` and two readers in a lane race under `-j`):
`ObjectSubsystemControl.{On,Off,Refused}.` and `TextureUploadShape.`. Every environment goes through
`mgl_itest_join_environment(... ${MGL_ITEST_COMMON_ENV})`, so the `;` separators are escaped and the
EGL vendor / ICD pinning is not lost to the property that replaces the job environment.
**No `RESOURCE_LOCK` was needed**: it exists for lanes where a whole scenario shares one log and one
case reads it; each of the four new lanes selects a single case, which is the stronger form of the
same guarantee. `TextureParamsWithoutASamplerViewScenario` gets **no lane at all** — it reads no log
and no counter, and its claim is about the shipping configuration, so the ambient registrations are
exactly its arms.
---
## 5. `scripts/p4a_untouched_regions.sh` — exit contract and self-test
```
p4a_untouched_regions.sh <ref-a> <ref-b> compare the seventeen at two git refs
p4a_untouched_regions.sh <ref> print the seventeen shas at one ref
p4a_untouched_regions.sh --self-test prove the comparison can go red
```
stdout is always the `<sha256> <region>` list in the fixed order (a baseline capture is a plain
redirect); everything else is stderr. **0** identical / **1** at least one moved, first one named /
**2** could not run (bad ref, missing file, a name not defined exactly once, a self-test control that
did not trip). Both arguments are git refs, so an uncommitted edit is invisible by design.
The seventeen: P3a's eleven in `Managers.cpp` (which P4a must not touch either) plus P4a's six —
`StageBlocksIntoUnpackRing`, `UnpackRingAvailable`, `UnpackRingAllocate`,
`RecomputeBackendColorSlots` (`Managers.cpp`), `DepthStencilSamplingReadImpl` (`DirectGLES.cpp`) and
`ShouldUseCaveatTextureFormat` (`Utils.cpp`). Both preprocessor arms of the duplicated flush ladder
are hashed, exactly as in the parent (`FlushPendingRangesNow` in the `#else`,
`FlushPendingRangesFrom` in the `#if MOBILEGL_PIPE_PUSH`), so a push arm that re-spells the ladder is
a finding rather than an invisible drift.
**Self-test evidence, verbatim:**
```
[p4a-untouched] positive control: 17 regions extracted from the working tree
[p4a-untouched] positive control: an untouched copy compares equal
[p4a-untouched] positive control: an edit outside the seventeen regions is invisible, in all three files
[p4a-untouched] negative control 1: a perturbed ClearBufferPool body is reported, and named
[p4a-untouched] negative control 2: a perturbed FlushPendingRangesNow body is reported, and named
[p4a-untouched] negative control 3: a perturbed RecomputeBackendColorSlots body is reported, and named
[p4a-untouched] negative control 4: a perturbed StageBlocksIntoUnpackRing body is reported, and named
[p4a-untouched] self-test passed: 4 negative controls, all tripped and all named
```
The four are D-N's four, and they are four different shapes on purpose: the small no-overload body,
one of a PAIR of identically shaped ladders in two preprocessor arms, a `Class::method(` with a
multi-line signature and a call site of its own, and a `static` in an anonymous namespace between two
other protected bodies. The count is asserted (`!= 4` is exit 2), so a control cannot be dropped
silently.
**The seventeen shas at `37da3c3a` == at `HEAD`** (rc 0). For the record:
```
ba79b92d… IsPoolable 6563286e… EnrollIntoPool dc9d3066… AcquireFromPool
12656cfd… TrimBufferPool c44a1274… ClearBufferPool 15259e54… ProcessDeferredBufferReleases
2daaa525… CreateRingStorage 6221df2e… RingAvailable 709b6f41… RingAllocate
c6557002… FlushPendingRangesNow 37fc94ff… FlushPendingRangesFrom (the PINNED sha, unchanged)
791b54a3… StageBlocksIntoUnpackRing 1d6f15c9… UnpackRingAvailable 19e614af… UnpackRingAllocate
3ae7e347… RecomputeBackendColorSlots 822ca3b0… DepthStencilSamplingReadImpl
266710e0… ShouldUseCaveatTextureFormat
```
**Two declared deviations from D-N, both written into the script's header:**
* **D-N/1 — a region KIND.** `DepthStencilSamplingReadImpl` is a **namespace**
(`DirectGLES.cpp:8117-8578`), not a function. D-N's table names it as though it were one, and the
parent's extractor — which finds the one `<name> (` whose closing paren is followed by `{` — finds
**zero** definitions of it and would exit 2 forever. Rows now carry `function` or `namespace`;
hashing the whole namespace block is also the stronger reading of "the D24S8 sampling-emulation
CORE".
* **D-N/2 — the pin is consulted unconditionally.** The parent falls back to
`PINNED_SHA_FlushPendingRangesFrom` only when `<ref-a>` does not define the function; at P4a's base
ref it **does**, so the fallback would never fire and the pin D-N names would stop being the
baseline. This script always compares against the pin and says so on stderr if `<ref-a>` defines it
differently. **Measured: they agree** (`37fc94ff…` at `37da3c3a` is the sha pinned at `3e298c9a`),
so the two readings are the same answer on this tree.
---
## 6. `scripts/p4a_descriptor_negative_control.sh` — exit contract
```
p4a_descriptor_negative_control.sh <build-dir>
```
**0** both controls tripped **and named their field**; **1** a control did not answer (a suite stayed
green with its field dropped, or went red without ever naming it — both are findings about the TEST,
and both leave the tree restored, rebuilt and re-run); **2** a control could not run. **Exit 2
outranks exit 1**: "could not run" is never reported as "did not answer".
The two breaks: `MGPSurface::Layered` stops being copied in `FramebufferEmit.h`, and
`SamplerParameters::borderColorForm` in `SamplerEmit.h`. Each is patched by **regex over any
`.<field> = <expr>[;,]`**, because both headers belong to other packages (C.7: B and C) and their
spelling is theirs; the right-hand side is *replaced*, not deleted, so the record still has the
field, still asserts its size, and the break stays one the compiler cannot see.
**Restore is not enough; the rebuild is part of the contract.** Every exit after a patch goes through
`repair()` — restore from a byte-for-byte copy taken before the patch (never from git, so a dirty
tree gets its own state back), rebuild, re-run the suite — and `repair()` also runs from the `EXIT`,
`INT` and `TERM` traps, so a Ctrl-C during a rebuild cannot leave a hard-wired field in the tree. A
failed repair downgrades the verdict to 2. Both controls always run even when the first could not,
because "one emitter has landed and the other has not" is a different tree from "neither has". Logs
and backups live in `<build-dir>/p4a-g7-logs/`, never in the repository.
**On this tree it exits 2 and says why**, which is the required answer:
```
[p4a-g7] MobileGL/MG_Impl/Pipe/FramebufferEmit.h exists but assigns no .Layered.
[p4a-g7] On the P4a CONTRACT tree that is the expected answer: the contract commit creates all five
[p4a-g7] emit headers with STUB emitters (contract-v1 D1) that return 0 payload bytes and copy
[p4a-g7] nothing, and package B (clientfb) fills the body in. …
[p4a-g7] ---- G7 (P4a descriptor emission) ----
Layered (MobileGL/MG_Impl/Pipe/FramebufferEmit.h): could-not-run
borderColorForm (MobileGL/MG_Impl/Pipe/SamplerEmit.h): could-not-run
```
No patch was applied and no rebuild was needed, so nothing was left behind — verified by
`git status` after the run.
---
## 7. `.github/workflows/test.yml`
* `BASELINE: "44c2b5cf"` → **`"37da3c3a"`**, with the comment rewritten to say why the narrowing is
safe: P3a's eleven were byte-identical against `44c2b5cf` at P3a's exit, so `37da3c3a` carries the
same bodies (verified here: `p3a_untouched_regions.sh 37da3c3a HEAD` rc 0, and
`FlushPendingRangesFrom` still hashes to its `3e298c9a` pin). Both gates now answer "did anything
on the list move during **P4a**".
* **Two new `pipe-gates` rows**, `p4a_untouched_regions.sh "${BASELINE}" HEAD` and its
`--self-test`, under the **same** `feat/disaggregated`-or-`workflow_dispatch` guard the P3a rows
carry. The P3a rows stay and keep running: neither gate can be silenced by editing the other's
list.
* The push-build control step gains three `-R` alternatives — `ObjectSubsystem`,
`TextureParamsWithoutASamplerView`, `TextureUploadShape` — each the shortest string that selects
only what it means to. **`ResourceSubsystem` does not match `ObjectSubsystemControl`**: the two
families are named apart on purpose, and a filter that merged them would hide one behind the other.
That step (in `integration-verify`) is the **only** CI job that unpacks a push build, which is why
the new entries have to be there and not in the pull `integration` job.
* **The TEMPORARY trigger lines at the top of the file are untouched.**
---
## 8. Deviations, declared
| # | deviation | why |
|---|---|---|
| **F-1** | **four commits, not three.** C.5 gives three messages; `ObjectSubsystemControlScenario` and `TextureUploadShapeScenario` are in C.5's file table but under none of them | putting them under one of the two `[Test]` messages would have made the message describe something it does not. The three exact messages are present, in C.5's order, with the fourth between the second and the last |
| **F-2** | **the six ABA cases' `AbaControl` arm asserts the CORRECT pixels and says it is not a control yet**, instead of asserting the corruption | no backend keys P4a's six kinds on `{slot, gen}` *and* reads `Features.PipeHandleAbaControl`; Magma's object paths are P7 and the Espryt knob consumer is package D's file. A lane asserting a corruption nothing can produce is a permanent red on an always-on `integration-gpu` lane. §3.2 |
| **F-3** | **G9's mandatory red-before was not produced**; all four cases are green on `08192d72` | mechanically impossible through public GL on a monolith tree: the only observable of a texture parameter is a sample, and the sample repairs the state it was meant to catch. §3.4 |
| **D-N/1** | the byte-identity script gains a region **kind**; `DepthStencilSamplingReadImpl` is a namespace | D-N names it as a function; the parent's extractor finds zero definitions and exits 2 forever. §5 |
| **D-N/2** | the pinned baseline is consulted **unconditionally** | D-N says that row is compared against the `3e298c9a` pin, and the parent's fallback would never fire at P4a's base ref. Both readings agree here. §5 |
| **F-4** | `MagmaPipeArms.h` gains `MagmaPipeAbaControlCoversKind` rather than changing `MagmaPipeAbaControlDefeatsIdentity`'s behaviour | C.5 asks for the knob to defeat "P4a's memo keys on the Magma side too"; there are none to defeat. The per-kind function states that as code rather than as a comment, and is where the answer changes when a consumer appears |
| **F-5** | `build-bench` does not exist in this worktree, so C.5's benchmark verification line did not run | `wsl_tree.sh` creates three build dirs; nothing in this package touches `MG_Benchmark/` |
| **F-6** | `~/w7/p4a-trees2.log` never contained `REBUILT gates` | the file was 0 bytes with no build process running when work started, and the tree's own build dirs and per-tree logs were complete. Building proceeded from there; all three builds reconfigured and relinked cleanly, and the pull `.so` is byte-identical to `$BASE`'s, which is the check that would have caught a stale tree |
---
## 9. What the integrator must decide, and re-run on the finished tree
**Two rulings are needed before the phase verdict:**
1. **G9's missing red-before artefact (F-3).** ROADMAP.md:20 requires it by hand. The options, in the
order I would rank them: (a) accept the scenario as a regression net and record in
`MEASUREMENTS.md` that the artefact is unobtainable through public GL, with §3.4's mechanism as
the reason — this is the honest reading and it costs nothing that is real; (b) ask **package D**
(which owns `Managers.cpp`/`DirectGLES.cpp`) for an Espryt-internal probe or a one-off
instrumented run taken *before* its own change, which would produce a genuine red-before but
inside a file this package may not touch; (c) drop the requirement, recorded.
2. **The six ABA controls' arm (F-2).** Either accept that they arm when a backend wires the knob
over its P4a object slot tables — the probe is already in place and the change is one `if` — or
grant package D (or E) that one `if` explicitly, in which case the six flip to expecting the
corruption with no change to this package.
**Re-runs the integrator owes on the integrated tree** (this package integrates LAST, so all of them
run against the finished code):
| what | why it must be re-run here |
|---|---|
| `ctest --test-dir build-verify -R 'HandleRecycle'` | the six ABA cases' `Handles` arm and the seven leak cases **arm themselves** when D and E land. The leak cases are the phase's only defence against P3a's C-1 shape, on both backends |
| `ctest --test-dir build-push -R 'ObjectSubsystemControl'` and `MOBILEGL_PIPE_PUSH=0x9ff ctest -R 'ObjectSubsystemControl'` | both cases SKIP today; the On/Off A/B arms when B and C land, the refusal when D lands. The refusal lane already pins `0x9ff` itself, so D.3's separate `0x9ff` invocation is a second reading of the same thing rather than the only one |
| `ctest --test-dir build-push -R 'TextureUploadShape'` | ~~the client half (`ctu=`) is zero today; once B lands, the `ctu == emit` assertion is live~~ **DONE, P3b/P4b wave 2-D (R-11).** The client emitter landed (`MG_Impl/Pipe/TextureEmit.h`'s `EmitOneLevel`), the `ctu == emit` comparison is live, and the scenario is now a GATE against a gold row rather than a record. The workload gained a third texture written through a `glTextureView`, so the numbers are not comparable to the P4a baseline `emit=6 box=6 rect=0 jobs=6`: the row measured on `cf7ca59f` is **`emit=9 box=9 rect=0 jobs=9`, client emitter 9**, identical on monolith / inproc / spawn / tcp. See `notes/p34b/espryt-d2.md` |
| `bash scripts/p4a_descriptor_negative_control.sh build-push` | exits 2 today because both emit headers are the contract's stubs. It becomes a real G7 control the moment B and C fill them in, and it is **not** a CI lane (it rebuilds the library up to four times) |
| `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` | this is the gate D and E can break. It is rc 0 here because nothing on the list has been touched yet |
| `ctest --test-dir build-push -R 'TextureParamsWithoutASamplerView'` | green here; after `esprytobj` it is the regression net that says the parameter sync did not move onto the sampler view |
| the full `-L integration-gpu` on the **pull** build | run here on the push build only (1072/1072). G2 wants both, and the pull build's ambient entries include the three new scenarios' skips |
**Artefacts kept** in `~/w7/notes/p4a/p4a-results/`: `p4a-handlerecycle-before.log` (180/180, the six
kinds' arms per lane), `p4a-handlerecycle-before-verbose.log` (the leak cases' live/high-water
numbers and every skip reason in full), `p4a-texparams-before.log` (G9's four cases, all green — the
D.2 evidence, such as it is), `p4a-object-subsystem-before.log` (G12 and the upload shape).
Everything else this package wrote under `~/w7` has been deleted.
@@ -0,0 +1,380 @@
# P4a package F — `gates`. Rework result, v2
`refs/heads/p4a/gates` = **`ecf9cb45`**, rebased onto `refs/heads/feat/disaggregated` = `2cb44039`
(c0 + c0b; no c0c had landed there when this round started, so `2cb44039` is the head ID-16 names).
Working tree clean, **nothing pushed**, no other worktree written to.
**`feat/disaggregated` moved WHILE this round ran** and is now `712c9467` — c0c plus the wire
package's rework (`Tracker.h`, `MGPipeTypes.h`, `PipeApply.{h,cpp}`, `PipeFields.def`, and real
cases in seven `MG_Test/Pipe/*EmitTest.cpp` suites; 14 files, +4982/-116). **This package was not
rebased onto it**, and every number below is measured on `2cb44039` + the eight commits. The delta
touches **none** of F's files — `MG_IntegrationTest/**`, `MagmaPipeArms.h`, `scripts/p4a_*.sh`,
`.github/workflows/test.yml` — so the rebase is textually clean; it is the integrator's to take,
along with a re-run of section 6 (the emission suites now carry real cases, which moves this
package's ctest counts even though nothing it owns changed).
Answers `gates-review-v1.md`'s six majors, the cheap minors, and `INTEGRATOR-DECISIONS.md` **ID-16**
(which is this round's specification) plus **ID-15**'s new D-K2 row.
---
## 1. Commits
The four v1 commits are unchanged in content and keep C.5's exact messages; the rebase gave them new
hashes. Four rework commits sit on top.
| # | hash | was | message |
|---|---|---|---|
| 1 | `5cdcce59` | `0bc9aafa` | `[Test] (Pipe): reproduce the texture, framebuffer, renderbuffer, sampler, view and program handle ABA through public GL and prove the pre-rekey guards are what stops it` |
| 2 | `f6ab550f` | `4f006f3c` | `[Test] (Espryt): assert a glTexParameter on a texture that only ever was an attachment, an image binding or a copy endpoint reaches the driver` |
| 3 | `7789584b` | `70868f93` | `[Test] (Pipe): switch P4a's four object subsystems off against the shipping mask and record the texture upload shape the two counters make visible` |
| 4 | `84ed7177` | `303a9dc8` | `[CI] (Pipe): gate that the unpack ring, the attachment permutation, the depth-stencil sampling core and the format caveat did not move` |
| 5 | `e85ba86a` | — | `[Fix] (Test): make G7's descriptor negative control able to report success - a patch that compiles into a scoped enum, a verdict its own patcher cannot pollute, and repair state the signal traps can see` |
| 6 | `77f31f90` | — | `[Fix, Test] (Pipe): read the shader composite band's own counters in the composite leak case, arm the ABA flip from anywhere under a backend, match Espryt's exact refusal line and pin the bit-10-requires-bit-11 arm` |
| 7 | `2e18d35d` | — | `[Fix, CI] (Pipe): order the byte-identity listing, prove every protected region reaches its closing brace, and pin the include-closure probe count` |
| 8 | `ecf9cb45` | — | `[Fix] (Test): stop G7's descriptor control carrying on past a Ctrl-C - latch the interrupt from the trap and from a signalled child, and report it as an interruption rather than as the contract tree's verdict` |
Commit 8 is not on the review's list. It is a defect **the F-M3 proof run found in the fixed
script** — section 3.2 — and it is reported as a finding rather than folded away.
The rebase was clean (c0b touched `PipeMutation.h`, `PipeFill.*`, `SlotAllocator.*`,
`PipeCatalogueTest.cpp` and `check_include_closure.py`; this package touches none of them). Files
this round changed: `MG_IntegrationTest/{CMakeLists.txt, Harness/PipeSlotPeek.{h,cpp},
Scenarios/{HandleRecycle,ObjectSubsystemControl,TextureUploadShape}Scenario.cpp}`,
`MG_Backend/DirectVulkan/Renderer/MagmaPipeArms.h` (F's one granted DirectVulkan file),
`scripts/p4a_{untouched_regions,descriptor_negative_control}.sh`, `.github/workflows/test.yml`.
---
## 2. The six majors
### F-M1 — the control patch now compiles. `scripts/p4a_descriptor_negative_control.sh:331`
The replacement value is `{}`, not `0`:
```python
patched, count = pattern.subn(r'\g<1>{} /* G7 NEGATIVE CONTROL: was \g<2> */\g<3>', text)
```
`= {}` is valid for `SamplerParameters::borderColorForm` (the scoped `enum class BorderColorForm :
Uint8`) **and** for `MGPSurface::Layered` (`Uint8`), in an assignment and in a designated
initializer, so one string covers both controls and neither has to know its field's type. The
reasoning is written into the header at `:48-61`, together with the caveat that `{}` is the type's
zero — so a suite every case of which expects the field's zero would legitimately report
`did-not-trip`, and both suites' own headers already require a red **by field name**.
**Proved, not argued** — see 3.1: on a scaffolded tree the `borderColorForm` control compiled, went
red naming the field, and the run exited **0**.
### F-M2 — the verdict cannot be polluted. `:250`, `:339`, `:452-457`
`run_control` no longer echoes its verdict: it sets the global `CONTROL_VERDICT` (`:250`) and the
driver reads it after a **plain call** (`:455`). The patcher's success line goes to `sys.stderr`
(`:339`), which is the literal ask, but the fix that matters is that the verdict no longer travels
through a stream anything else can write to. The rows are also collected into an array first
(`:445-452`) and every child gets `</dev/null`, so a `cmake` or `ctest` that read stdin could not
eat the second control's row out of the loop's heredoc.
### F-M3 — `repair()` really runs from the traps. `:220-232`, `:455`
`PATCHED_HEADER` is set in **this** shell (`run_control` is no longer invoked in `$(...)`), so the
`EXIT`/`INT`/`TERM` traps see it. Measured end to end — 3.2: a SIGINT sent to the process group
mid-rebuild, with the patch demonstrably in the tree, ran the trap's `repair`, restored and rebuilt,
re-raised, and the script died **130** leaving `git status --porcelain` **empty**.
### F-M4 — the composite leak case reads the band. `Harness/PipeSlotPeek.{h,cpp}`, `HandleRecycleScenario.cpp:2200`
`PipeSlotPeek.h:97-99` gains the members `contract-v2.md` 4.3/7.6 asks for, and the now-false
paragraph about a merged high-water mark (old `:47-55`) is replaced by `:47-61`, which states c0b's
split:
```cpp
bool PeekPipeCompositeSlotLiveCount(unsigned* outLive); // CompositeLiveCount()
bool PeekPipeCompositeSlotHighWater(unsigned* outHighWater); // CompositeHighWater(), VERBATIM
bool PeekPipeCompositeSlotBandBase(unsigned* outBandBase); // kMGPipeShaderCsoCompositeSlotBase
```
`PeekPipeCompositeSlotHighWater` returns the allocator's number **unmodified** — an absolute slot
index that starts at the band base, not a base-relative delta. A peek whose name says HighWater and
whose value is a delta is the same class of quietly-redefined counter this member exists to correct,
so the base is a third member instead (`:91-96`, bodies `.cpp:57-73`) and the scenario reads the two
against it.
`AssertChurnReturnsEverySlot` now takes a `SlotSpace` (`HandleRecycleScenario.cpp:217-247`, `:707`),
stated at every one of the seven call sites — six `SlotSpace::Ordinary`, and
`EvictedPipelineCompositesReturnTheirShaderCsoSlots` `SlotSpace::CompositeBand` (`:2200`). Three
consequences:
* the three assertions (`live`, `high water`, `peak in flight`) are about the **band** for that case;
* the "nothing was ever minted" skip compares against the space's **floor** (`:734-741`, `:782`) —
0 for the ordinary space, the band base for the band — so a band that never moved from 983040 is
a named skip and not a silent pass;
* `maxInFlight` for the composite case is **1**, not 3: a round creates three `ShaderCso`s but only
one of them is a band slot (`:2192-2202`). F-m6's stale "TWO in flight" prose is gone with it.
Today, on both lanes, the case prints its band numbers and skips:
```
[ HandleRecycle ] backend=DirectGLES ShaderCso (pipeline composites) [composite band]
live 0 -> 0 (peak 0), high water 983040 -> 983040 (floor 983040) over 48 rounds
... Skipped: the client minted no ShaderCso (pipeline composites) [composite band] slot at all
```
**It can go red** — 3.3.
### F-M5 — the ABA-flip probe is directory-wide. `MG_IntegrationTest/CMakeLists.txt:411-460`, `:571-595`
`mgl_itest_probe_for_two_symbols` now answers "**both regexes matched somewhere under the
directory**" and reports `<file matching A> + <file matching B>`, instead of requiring one file to
carry both. The layout dependency the review found — package D wiring the knob in `Managers.cpp`
while the P4a subsystem constants live in `SlotTables.h`, the marker never arming, six controls
silently keeping the old expectation — is gone.
It costs nothing today, verified by grep on this tree: `MobileGL/MG_Backend/DirectVulkan` matches
`PipeHandleAbaControl` (only `MagmaPipeArms.h`) and matches
`kMGPipeSubsystem{Framebuffer,TextureResources,Samplers,Programs}` **nowhere**;
`MG_Backend/DirectGLES` matches neither. So `MGITEST_HANDLE_ABA_OBJECTS_*` is still unset for both
backends and the six controls still assert the correct pixels and say so.
### F-M6 — the refusal is matched as a LINE. `ObjectSubsystemControlScenario.cpp:150-215`, `:556-575`
`FindTheRefusalLine(log, bitThatWasSet, bitThatWasNeeded)` (`:190-215`) scans the log line by line
and requires **one line** that is all of:
* at **ERROR** severity — the library writes `[<time>] [<os> <thread>/<TAG>]: <message>`, one record
per line (`MG_Util/Debug/Log.cpp:89-103`), and D-K2 asks for an `MGLOG_E`;
* carrying `REFUS`/`refus`, so a line that merely mentions the two bits is not the decision;
* naming the bit that was set **and** the bit it needed, on that same line. Three spellings each —
the constant's name, `(bit 11)` / `(bit 10)`, `0x800` / `0x400` (`:207-215`).
That is Espryt's exact sentence. `p4a-esprytobj`'s `Managers.cpp` emits it from the helper the three
dependent families share (`PipeSubsystemDependencyMissing`, ~`:3523`, used by
`ResolveSamplerSubsystemArm` ~`:3659`):
> `MGPipe: kMGPipeSubsystemSamplers (bit 11) is set but kMGPipeSubsystemTextureResources (bit 10) is
> clear; every MGPBoundView::Texture and MGPImageView::Res names a Texture handle and only bit 10
> populates that slot table - REFUSING the dependent bit and running the legacy arm. Set both bits,
> or clear both`
The matched line is printed and `RecordProperty`'d on the **pass** as well (`:570-575`), so a green
refusal lane shows the sentence it went green on. The old form — a lowercase `"sampler"` anywhere in
the whole file — is gone.
---
## 3. The proofs
Run on a **throwaway commit** `8266916a` on a private branch `tmp/gatesF-g7proof`, which gave the
tree the two things it does not have yet: a `.Layered =` copy in `FramebufferEmit.h` and a
`.borderColorForm =` copy in `SamplerEmit.h` with one comparison case per emission suite, and one
deliberately leaked composite band slot per churn round. **The branch has been deleted and no
scaffold commit is reachable from anything** (`git log --oneline --all | grep -c SCAFFOLD` = 0);
`p4a/gates` never carried it.
### 3.1 G7 reaches "tripped" and exits 0
```
[p4a-g7] [FramebufferEmit-Layered] the patched header still compiles, so the record still has the field and its size
[p4a-g7] [FramebufferEmit-Layered] negative control tripped, naming Layered, and the tree is green again
[p4a-g7] [SamplerEmit-borderColorForm] the patched header still compiles, ...
[p4a-g7] [SamplerEmit-borderColorForm] negative control tripped, naming borderColorForm, and the tree is green again
[p4a-g7] ---- G7 (P4a descriptor emission) ----
Layered (MobileGL/MG_Impl/Pipe/FramebufferEmit.h): tripped
borderColorForm (MobileGL/MG_Impl/Pipe/SamplerEmit.h): tripped
[p4a-g7] both controls tripped and named their field; exit 0
G7_RC=0
```
`git status --porcelain` empty afterwards, and both headers still carry their field copies. Re-run
after commit 8's hardening: **still exit 0, both tripped**. This is the first time the script has
ever reached that path — F-M1 and F-M2 together.
### 3.2 A SIGINT mid-rebuild leaves the tree clean
```
===== mid-way: the patch IS in the tree =====
M MobileGL/MG_Impl/Pipe/FramebufferEmit.h
69: dst.Layered = {} /* G7 NEGATIVE CONTROL: was src.Layered */;
===== sending SIGINT to the process group =====
SCRIPT_EXIT_RC=130
[p4a-g7] [FramebufferEmit-Layered] rebuilding with the dropped field
[p4a-g7] restored MobileGL/MG_Impl/Pipe/FramebufferEmit.h; rebuilding build-push from it
[p4a-g7] the tree is restored, rebuilt and green again
===== tree AFTER the interrupt ===== (empty)
===== leftover control marker anywhere? ===== (none)
```
**A methodology note the integrator needs.** The first attempt at this proof was invalid and looked
like a pass. A command started with `&` from a **non-interactive** shell has `SIGINT` set to
`SIG_IGN`, and a disposition inherited as ignored **cannot be trapped** — so the script could never
run its `INT` trap however it was written, `ninja` (which installs its own handler) took the signal
instead, and the tree was repaired through the explicit build-failure path. Repaired, but the run
then carried on into the second control and signed off with the summary it prints on an untouched
contract tree. The proof above launches the script through `python3` with the disposition reset to
`SIG_DFL`, which is what a terminal's Ctrl-C gives it. **Anyone re-running this must do the same or
they will measure the launcher, not the script.**
That first attempt is also what found commit 8's defect, now fixed two ways (`:220-232`, `:353-360`,
`:380-389`, `:462-470`, `:476-483`): the traps latch `INTERRUPTED`, every child's exit status is
additionally checked for "killed by a signal", the driver **breaks** rather than running the next
control, and the summary says `(INTERRUPTED - the remaining control(s) did not run)` instead of the
contract-tree wording.
### 3.3 The composite leak case can go red
With one band slot leaked per round, on the scaffold:
```
[ HandleRecycle ] backend=DirectGLES ShaderCso (pipeline composites) [composite band]
live 2 -> 50 (peak 50), high water 983042 -> 983090 (floor 983040) over 48 rounds
HandleRecycleScenario.cpp:793: Failure - 48 ... slots never came back
HandleRecycleScenario.cpp:804: Failure - the ... slot space grew with the churn
HandleRecycleScenario.cpp:809: Failure - more than 1 churned ... object(s) were live at once
```
**Failed on all three lanes that pin a live allocator** — `DirectGLES.HandleRecycle.Handles.`,
`DirectVulkan.HandleRecycle.Handles.` and `DirectVulkan.HandleRecycle.AbaControlHandles.` — and
correctly **skipped** on the `Legacy` / `AbaControl` lanes (`MOBILEGL_PIPE_PUSH=0`) and on the
ambient entries. 3 failed out of 8. All three assertions fire, which is what says the case is wired
to the band and not to the ordinary space.
That third lane is also **F-m4's proof**: it used to decline on `arm == Handles` while telling the
reader it had no allocator, which was false.
---
## 4. ID-15 — the 0x5ff arm
`ObjectSubsystemControlScenario.ATextureBitWithoutTheSamplerBitIsRefusedAndNamed` (`:589-693`), lane
`DirectGLES.ObjectSubsystemControl.RefusedTexture.` pinning `MOBILEGL_PIPE_PUSH=0x5ff`
(`CMakeLists.txt:1446-1451`, `:1478-1487`). Same two assertions as the 0x9ff arm with the bits'
roles swapped: one ERROR line naming both bits and saying it refused, and the same pixels every
other lane draws.
**On this tree it is a named SKIP, and it is visible as one:**
```
DirectGLES.ObjectSubsystemControl.RefusedTexture....ATextureBitWithoutTheSamplerBitIsRefusedAndNamed
***Skipped
subsystem not implemented on this tree: no source under MobileGL/MG_Backend/DirectGLES names any
of kMGPipeSubsystem{Framebuffer, TextureResources, Samplers, Programs}, so this backend does not
honour P4a's mask and cannot refuse a dependency inside it. D-K2's fourth row (bit 10 requires
bit 11, ID-15) lives in the texture family's Resolve*SubsystemArm ...; this control arms itself
when that lands. The lane itself is not wasted: the library came up under 0x5ff ...
```
> **[CORRECTED by gates-v3.md sections 2 and 3.1 - review finding F-v2-m2. Do not act on the
> paragraph below.]** The red window this section predicts DOES NOT EXIST. `p4a/esprytobj` v2
> already carries D-K2's fourth row (`Managers.cpp`, `ResolveTextureResourceSubsystemArm`
> refuses bit 10 without bit 11), so at integration the arm ARMS and its refusal assertion
> PASSES - measured on the integrated tree at `29d51ab9`, matching Espryt's exact sentence.
> What IS red there is the lane's OTHER assertion, the pixels, and that is a real finding about
> the CLIENT: at 0x5ff the emitter still emits the texture family (`ctu=5`) while Espryt refuses
> the bit and runs its legacy arm, so the dirty flags are cleared on an acceptance nobody
> consumes and the sampled texture is black. See gates-v3.md section 3.1.
**The integrator must know what that gate implies.** It is the same marker the 0x9ff case uses -
"does any source under this backend name a P4a subsystem constant". `p4a/esprytobj` v1 already sets
it, and its `ResolveTextureResourceSubsystemArm` (`Managers.cpp` ~`:3618`) refuses only bit 10
without bit **7**. So **the moment esprytobj is integrated, this entry stops skipping and goes RED
until package D's rework adds the bit-10-requires-bit-11 row.** That is exactly the pin ID-15 asks F
to provide, and it is deliberate — but it is a red that appears at integration time and not at F's,
and it must not be read as a regression in this package.
The lane marker vocabulary is now `on / off / refused / refused-texture`; an unrecognised value is
still a `FAIL()`, and the on/off case declines **both** refusal lanes.
---
## 5. The minors
| id | what changed |
|---|---|
| **F-m1** | `p4a_untouched_regions.sh:522`, `:527-543` — `reorder_sha_list` puts the baseline listing back into `REGIONS` order after the pinned rows are appended. **Measured: `p4a_untouched_regions.sh 37da3c3a` and `... 37da3c3a HEAD` now produce byte-identical sha lists** (`diff` empty; it was seven spurious differences). |
| **F-m2** | `:366-411` (`perturb(... where)`) and `:646-679` — every self-test region is now perturbed at its **head** and again at its **tail**, immediately before the closing brace. **8 negative controls, all tripped, all named**; the pin is `!= 8`. This is the control that proves an extent reaches its closing brace, which no head-only control can. |
| **F-m3** | `:74-82` — one paragraph stating the hash's exact extent: it starts at the line carrying the name, so a return type, attribute or template header on an earlier line of a multi-line signature is outside it; the end IS covered, and the tail controls are why. |
| **F-m4** | `HandleRecycleScenario.cpp:194-212`, `:707-733` — the leak cases gate on `LanePinnedALiveAllocator()` (the lane's own non-zero `MOBILEGL_PIPE_PUSH`) instead of on `arm == Handles`. The false sentence is gone and `DirectVulkan.HandleRecycle.AbaControlHandles.` is now covered — see 3.3. |
| **F-m5** | `MagmaPipeArms.h:229-290` — the per-kind answer is now `constexpr MagmaPipeAbaControlKindIsRekeyedHere(kind)` (`:245`), **exhaustive with no `default:`** (a new `MGPipeKind` is a `-Wswitch` warning, and there is no arm for it to read `true` from), **pinned by three `static_assert`s** in the same file (`:273-290`) saying the two minted kinds are covered and P4a's six are not. It can no longer rot with no caller: the asserts compile in every Magma build. `MagmaPipeAbaControlCoversKind` is that predicate AND the knob. |
| **F-m6** | folded into F-M4: the composite case's prose and its `maxInFlight` now agree, and both say **1** (the band's answer), not two or three. |
| **F-m7** | `TextureUploadShapeScenario.cpp:326-378` plus a new probe `MGITEST_PIPE_CLIENT_TEXTURE_UPLOAD_EMITTER_PRESENT` (`CMakeLists.txt:614-632`, over `MG_Impl/Pipe` for `ClientTextureUploadEmissions`). `ctu=` is published in **every** push build, so "absent" and "zero" were never distinguishable from the number; the build now answers it. With no emitter the case **asserts `ctu == 0`** (a non-zero one would mean the probe is looking at the wrong symbol); with an emitter it asserts `ctu > 0` **and** `ctu == emit`. |
| **F-m8** | `p4a_descriptor_negative_control.sh:28-33` — the header now says the `Layered` control perturbs two mechanisms on a tree that has the framebuffer emitter (the record and the ContentHash staging copy), rather than claiming a single-field drop. Narrowed in prose, not in the regex: excluding the hash copy means hard-coding another package's helper name. |
| **F-m9** | `.github/workflows/test.yml:793-802` — `--expect-probes 4` added; `clang++-20` kept, with the reason (the step above installs `clang-20`; the bare `clang++` spelling exists only because the WSL box has no `clang++-20`). **Verified both ways locally: `--expect-probes 4` rc 0, `--expect-probes 5` rc 1.** |
| **F-m10** | `p4a_descriptor_negative_control.sh:129-155` — the build directory is checked, reading **both** `MOBILEGL_PIPE_PUSH` and `MOBILEGL_PIPE_VERIFY` from `CMakeCache.txt`, because `MOBILEGL_PIPE_VERIFY=ON` forces push on for the configure without writing it back (root `CMakeLists.txt:470-472`) and refusing a verify directory would be the wrong answer. **Measured: `... build-linux` now exits 2 naming the cache lines, instead of scoring two `did-not-trip`s.** |
| **F-m11** | `scripts/p4a_*.sh` are `100644`, matching `scripts/p3a_untouched_regions.sh` and the two older negative controls. |
| **F-m12** | `HandleRecycleScenario.cpp:1319-1347` — the framebuffer ABA corruption assertion is `EXPECT_TRUE(sawStale)`, the predicate the case already computes and prints, not `EXPECT_NE(deadIsNotRed, 0)` which a garbage attachment satisfies. The message names the third answer explicitly. |
| **F-m13** | declared here: `~/w7/notes/tools/wsl_p4a_gate.sh` and the `p4a_ab.sh` / `p4a_ab_1ff.sh` / `wsl_p4a_bench.sh` / `ab_reduce3.py` family are C.5 rows that **ID-3 reassigns to the integrator**. They exist, timestamped before this package's round began, and this package did not write them. `gates-v1.md` section 8 was silent about them; this row is the correction. |
**Not fixed, and why.** R1's gap (`TextureParamsWithoutASamplerView` catches emitted-but-not-applied,
not deferred-to-first-view) is not this package's — ID-16 assigns the backend-side probe to package
D's verification round, and nothing F can write through public GL closes it (v1's section 3.4 still
holds).
---
## 6. Gate numbers, all at `ecf9cb45`, working tree clean
| gate | result |
|---|---|
| **G1** `symbol_report.py --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0` | **0 added / 0 removed / 0 resized / 0 renamed**, rc 0. `.text` 10806323 -> 10806323 (+0). File 19114360 -> 19114360. `.data` / `.bss` / `.rodata` all +0. 27811 -> 27811 defined symbols |
| `ctest -L unit` x 3 | `build-linux` **1636**, `build-push` **1636**, `build-verify` **1636** — 100%, 0 failed in each |
| **G2** ctest names pull == push | `diff` empty, **2711 == 2711** |
| **G14** vs `~/w7/p4a-before-ctest-names.txt` (37da3c3a) | **0 removed**, **+123 added** (v1's +119, plus c0b's one unit case, plus this round's three `ATextureBitWithoutTheSamplerBitIsRefusedAndNamed` entries) |
| `p4a_untouched_regions.sh 37da3c3a HEAD` | **rc 0**, 17 rows |
| `p4a_untouched_regions.sh --self-test` | **rc 0**, 3 positive + **8 negative** controls, each tripped and named |
| `p4a_untouched_regions.sh 37da3c3a` vs the two-ref listing | **byte-identical** (F-m1) |
| `p3a_untouched_regions.sh 37da3c3a HEAD` / `--self-test` | **rc 0** / **rc 0** |
| `check_include_closure.py --mode text --self-test --require-all --expect-probes 4` | **rc 0** ("4 probes, 0 skipped, 0 problems"); with `--expect-probes 5`, **rc 1** |
| `scripts/g7_negative_control.sh build-push` (P2) | **rc 0**, tripped naming `SetColorMask`, tree green again |
| `scripts/p3a_vertex_input_negative_control.sh build-push` (P3a) | **rc 0**, tripped naming `IsBgra`, tree green again |
| `scripts/p4a_descriptor_negative_control.sh build-push` (P4a) | **rc 2**, both `could-not-run` — the contract tree's correct answer, both emit headers are the contract's stubs. **rc 0 on a scaffolded B+C-shaped tree** (3.1) |
| `scripts/p4a_descriptor_negative_control.sh build-linux` | **rc 2**, refused as a non-push build directory (F-m10) |
| `ctest --test-dir build-push -R 'HandleRecycle'` | **144/144**, 0 failed |
| `ctest --test-dir build-push -R 'ObjectSubsystemControl\|TextureParamsWithoutASamplerView\|TextureUploadShape'` | **21/21**, 0 failed |
| `ctest --test-dir build-verify -R 'HandleRecycle'` | **180/180**, 0 failed |
| `ctest --test-dir build-verify -R 'ObjectSubsystemControl\|TextureParamsWithoutASamplerView\|TextureUploadShape'` | **37/37**, 0 failed |
| `ctest --test-dir build-linux -R 'HandleRecycle\|ObjectSubsystemControl\|TextureParamsWithoutASamplerView\|TextureUploadShape'` (PULL) | **165/165**, 0 failed |
| `ctest -L integration-gpu` push / pull | **1075/1075** and **1075/1075**, 0 failed — G2's unverified half in the v1 review is now measured on both builds |
| working tree, attribution, message shape | clean; no `Co-Authored-By`; eight single-line `[Type] (Scope): description` messages |
Every one of the new and changed scenarios runs on **both** lanes: the `HandleRecycle`,
`ObjectSubsystemControl`, `TextureParamsWithoutASamplerView` and `TextureUploadShape` families all
appear under `DirectGLES.` and `DirectVulkan.` prefixes in the counts above (the `RefusedTexture`
lane is DirectGLES-only by design, like its 0x9ff sibling; the scenario's ambient entries exist on
both).
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` was exported for every build and every ctest run above.
`CCACHE_BASEDIR=/home/swung/w7`, `-j 8` for builds. No retrace was run, so no `git lfs checkout` was
needed; D.3/D.4's retrace and device work stay the integrator's (ID-3).
**The recorded `TextureUploadShape` baseline is unchanged by this round:**
`server[emit=6 box=6 rect=0 jobs=6] client[ctu=0]`, 3 frames x (40 scattered 2x2 rects + one 64x8
band), DirectGLES on llvmpipe.
---
## 7. What the integrator must re-run on the integrated tree
`gates-v1.md` section 9's list stands in full. It is amended and extended by:
| what | why |
|---|---|
| `bash scripts/p4a_descriptor_negative_control.sh build-push` on an integrated B+C tree | **Expect exit 0 naming `Layered` and `borderColorForm`.** It has now been shown to reach that path (3.1), so exit 2 with the contract-tree wording is a real finding here — and so is exit 2 with the *interruption* wording, which means the run was killed and reported nothing about the controls |
| `ctest --test-dir build-verify -R 'EvictedPipelineComposites'` after C lands, and **read the printed band line** | The case reads `CompositeHighWater` / `CompositeLiveCount` now; the line is `... [composite band] live A -> B (peak P), high water H1 -> H2 (floor 983040)`. A high water still equal to the floor means C's composite resolver is not minting through `AllocateComposite` and the case is skipping, not passing |
| `ctest -R 'ObjectSubsystemControl.RefusedTexture'` **as soon as esprytobj is integrated** | **[CORRECTED by gates-v3.md sections 2 and 3.1 - review finding F-v2-m2.]** The REFUSAL assertion is expected GREEN: esprytobj v2 carries D-K2's fourth row and the sentence matches (measured on 29d51ab9). The lane is nonetheless RED there on its OTHER assertion, the pixels, because the client still emits the texture family at 0x5ff while Espryt refuses the bit - a real finding about the client gate, not a sequencing artefact |
| `MOBILEGL_PIPE_PUSH=0x9ff ctest -R 'ObjectSubsystemControl'` and the 0x5ff lane, **with the lane log kept** | The refusal assertion is now a single ERROR line naming both bits and saying it refused; the matched line is printed and recorded, so confirm it is Espryt's sentence rather than trusting the exit status |
| grep the **configure output** for `MOBILEGL_PIPE_HANDLE_ABA_CONTROL steers <backend>` after D lands | F-M5: the probe is directory-wide now, so the message names the two files that supplied the two halves. If it is absent while `is keyed on {slot, gen} for P4a's object families` is present, the knob has no consumer and the six ABA controls are still not controls |
| `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` **and** `--self-test` after D and E | Unchanged, and the self-test is stronger: **8** negative controls, and a TAIL control that does not trip while its head twin does means the extraction stops before the closing brace |
| the CI `pipe-gates` include-closure step | `--expect-probes 4` is now pinned; it must change in the same commit as any change to `check_include_closure.py`'s `PROBES` list. **Do not** "fix" `clang++-20` to bare `clang++` on the strength of a local failure (ID-9 D16 / ID-11) |
| `ctest -L integration-gpu` on both builds | Measured here at **1075/1075** each; the counts move as B..E land |
| a SIGINT test of the G7 script, if it is ever re-verified | **Launch it with SIGINT deliverable** (3.2). A `&` from a non-interactive shell makes the trap unreachable and the test measures nothing |
| **rebase `p4a/gates` onto whatever `feat/disaggregated` is at integration time, and re-take section 6** | It was `2cb44039` when this round rebased and `712c9467` by the time it finished (c0c + wire's rework). The delta touches none of F's files, so the rebase is textually clean, but the seven `MG_Test/Pipe/*EmitTest.cpp` suites now carry real cases: the unit count, the `-N` name counts and the G7 script's "N matching test(s)" line all move without anything F owns changing. Re-take G1, the three `-L unit` runs, the pull/push name diff and the G14 delta on the rebased tree |
**Carried forward for the esprytobj round (ID-16, R1):** the backend-side probe must take its
reading while the texture is still attachment-only *and* distinguish "not applied yet" from "applied
late". `TextureParamsWithoutASamplerView` catches the first shape and not the second, and no
public-GL case can, because the sample that observes the parameter is also what repairs it.
**Artefacts** stay where v1 left them in `~/w7/notes/p4a/p4a-results/`
(`p4a-handlerecycle-before.log`, `p4a-handlerecycle-before-verbose.log`, `p4a-texparams-before.log`,
`p4a-object-subsystem-before.log`). They are the pre-rework readings; sections 3 and 6 above are the
post-rework ones. Everything else this package wrote under `~/w7` has been deleted.
@@ -0,0 +1,395 @@
# P4a package F — `gates`. Rework result, v3 (verification round, integrates LAST)
Branch `refs/heads/p4a/gates`, head **`4678519f`**, **fifteen** commits on
`refs/heads/feat/disaggregated` = **`41b79050`** (contract c0..c0f, wire, clientsp v3, clientfb v2,
esprytobj v2, **package D's verification round and package E's**). Eight commits are v2's, rebased;
**seven are new in v3**. Nothing pushed. Working tree clean.
**The base moved twice under this round** and every number below is from the third and final
rebase. F started on `29d51ab9`, moved to `29bd4d2c` (D's verification round), and finished on
`41b79050` (E's). All three rebases were clean; §2.
---
## 0. The headline
**Everything is green.** On `4678519f`:
| | |
|---|---|
| `ctest -L integration-gpu` push, default `0x1fff` | **1079/1079** |
| the same at `0x1ff` / at `0` / pull build | **1079/1079** / **1079/1079** / **1079/1079** |
| DirectVulkan lane / DirectGLES lane | **540/540** / **539/539** |
| `ctest -L integration-verify` | **884/884**, **zero Fatal** |
| `ctest -L unit` × 3 builds | **1767 / 1767 / 1767** |
| G1 symbols | **0 added / 0 removed / 0 resized / 0 renamed** |
| G2 pull vs push names | **2846 == 2846, diff empty** |
| G14 vs `37da3c3a` | **0 removed / +258** |
| G5 `p4a_untouched_regions.sh` two-ref / `--self-test` | **rc 0, 17 rows** / **rc 0, 8 negative controls** |
| G7 `p4a_descriptor_negative_control.sh build-push` | **rc 0**, both controls tripped and named |
Two things in that table are new this phase and worth reading twice:
* **`HandleRecycle.Handles` is 36/36.** ID-38/ID-39's six armless `.Handles` aborts are closed, and
the itest CMake's `0x1fff` phase pin — F's — is what closed them.
* **The G7 descriptor negative control reaches its real path for the first time** and exits 0
naming `Layered` and `borderColorForm`. `gates-v2.md` §7's first row is satisfied.
**Four defects F's gates found on the two intermediate bases, all now fixed** (§4.5). Three were
fixed by the integrator's own D/E verification commits, arriving independently and with the same
diagnosis; one was F's own case and F fixed it. They are recorded because F's lanes are what will
keep them fixed, and because a reader of the intermediate gate runs would otherwise not understand
why the numbers moved. Nothing is owed.
---
## 1. Commits
| # | hash | what |
|---|---|---|
| 1..8 | `246434bb` … `9a0a7f76` | v2's eight, rebased (§2) |
| 9 | `e62abff6` | **F-v2-m3**: `MagmaPipeAbaControlCoversKind` deleted |
| 10 | `b938c83b` | **F-v2-m4**: `REPAIR_RC` is read, in two places |
| 11 | `f9c0e7ec` | **F-v2-m1**: the refusal matcher reads the sentence's DIRECTION; **F-v2-m2**'s wording |
| 12 | `972dd811` | **G9's white-box half** (ID-19/ID-31): `Harness/PipeApplyPeek.{h,cpp}` + the four cases |
| 13 | `7107d0f4` | c0f's belt pinned in a lane, on both backends (ID-40, "if cheap") |
| 14 | `4614abb9` | **wire MINOR-1** (ID-27, integrator grant): the cube-face erase-key case |
| 15 | `4678519f` | the SamplerCso leak case corrected against C's content-addressed cache (§3.4) |
No `Co-Authored-By`, no other attribution, fifteen single-line `[Type] (Scope): description`
messages (grepped for `co-authored|claude|assistant|generated`: 0 hits).
**Files v3 touched**: `MG_Backend/DirectVulkan/Renderer/MagmaPipeArms.h` (granted; v2 already owned
it), `MG_IntegrationTest/CMakeLists.txt`, `MG_IntegrationTest/Harness/PipeApplyPeek.{h,cpp}` (new),
`MG_IntegrationTest/Scenarios/{ObjectSubsystemControlScenario,
TextureParamsWithoutASamplerViewScenario, HandleRecycleScenario}.cpp`,
`MG_Test/Pipe/TextureEmitTest.cpp` (ID-27's grant — one case added, nothing else in the file
changed), `scripts/p4a_descriptor_negative_control.sh`.
**`.github/workflows/test.yml` was not touched by v3 at all.** The TEMPORARY trigger at `:9` and
`BASELINE: "37da3c3a"` at `:1599` are v2's, unmodified.
---
## 2. The three rebases
| from | onto | result |
|---|---|---|
| `ecf9cb45` (v2's head) | **`29d51ab9`** (c0..c0f) | `REBASE_RC=0`, **8/8**, no conflict → `8d40c55a` |
| `796e6bfa` | **`29bd4d2c`** (+ D's verification round, six commits) | `REBASE_RC=0`, **15/15**, no conflict → `1c58d48a` |
| `1c58d48a` | **`41b79050`** (+ E's verification round, ten commits) | `REBASE_RC=0`, **15/15**, no conflict → `4678519f` |
Nothing new against the re-review's §4 prediction. The file sets stay disjoint: pipe moved
`MG_Pipe/**`, `MG_Impl/Pipe/**`, `MG_Backend/DirectGLES/**` and `MG_Test/**`; F owns
`MG_IntegrationTest/**`, `MagmaPipeArms.h`, `scripts/p4a_*.sh` and `test.yml`. The only overlap is
`MG_Test/Pipe/TextureEmitTest.cpp`, which F touches for the first time this round under ID-27's
grant and after every rebase.
Three things the re-review said to check on the rebased tree:
* **`PeekPipeCompositeSlot*` still resolves** — `SlotAllocator.h`'s `CompositeHighWater()` /
`CompositeLiveCount()` and `kMGPipeShaderCsoCompositeSlotBase` are unchanged; `PipeSlotPeek.cpp`
compiles and its cases run.
* **The itest CMake pins are still F's** — every `MOBILEGL_PIPE_PUSH=` there is `0x1fff` except the
documented off / refusal / `0` lanes and the two new consumer lanes (also `0x1fff`).
* **The G7 script's targets survive** — `MGPSurface::Layered` and
`SamplerParameters::borderColorForm` both exist, and the script now reaches its real path (§5).
**F-v2-m2's correction, for the integrator.** `gates-v2.md` §4 and its §7 row told you to expect
the `RefusedTexture` lane RED until package D's rework. **That window does not exist**: esprytobj
v2 carries D-K2's fourth row, the arm arms, and its refusal assertion passes — the matcher finds
Espryt's exact sentence, quoted in §4.1. Both places in `gates-v2.md` now carry a `[CORRECTED …]`
marker pointing here.
---
## 3. What was added, and how each piece was proven
### 3.1 G9's white-box half (ID-19 / ID-31) — and the artefact ROADMAP.md:20 asks for
**`MG_IntegrationTest/Harness/PipeApplyPeek.{h,cpp}`** (new, 110 + 188 lines), a separate
translation unit for `PipeSlotPeek`'s stated reason and more so: it includes Espryt's own
`Managers.h`, which may not meet a scenario's GL headers. Four entry points, each returning `false`
and touching nothing where it cannot look (a pull build has no applier; Android resolves no
internal symbol; a backend that is not Espryt has no twin):
* `PeekPipeTextureParamsRecord(glName, out)` — scans `MGPipeApplier().TextureResources` for a live
record whose `Desc.GlNameForDiag` is that GL name (a **diagnostic** field used as a diagnostic
search key, never as an identity) and returns `{Slot, Gen, ParamsSerial, Swizzle[4] as GL enums,
DepthStencilMode as a GL enum}`. Purely server-side: it consults neither the client emitter nor
the twin registry, so it arms on **D's applier state** and not on the markers B and C set — which
ID-31 is explicit about, and which is how F-M5's shape is avoided.
* `PeekEsprytAppliedTextureParams(glName, glTarget, out)` — reads the value back **from the driver**
through the twin's own ES name (`g_backendTextureObjects.Find(...)->GetBackendTextureId()`, then
`g_GLESFuncs.glGetTexParameteriv`). The binding on the **already-active** unit is saved and
restored byte for byte and no unit is switched, so Espryt's `g_boundTexturesCache` still
describes reality afterwards. Binding through the twin's own `Bind()` would have updated that
shadow and changed what the scenario measures next; this does not.
* `PeekEsprytHasSamplerViewForTexture(glName, out)` —
`SamplerViewImpl::FindSamplerViewForHandle(HandleOfSamplerViewForTexture(object))`, i.e. Espryt's
own table asked the way Espryt asks it. It deliberately does **not** read the record's `ViewCso`,
which is the client's statement about the same fact and would make one side of the seam vouch
for the other.
* `PeekPipeApplierRefusedNoConsumer(out)` — c0f's counter, for §3.2.
**`TextureParamsWithoutASamplerViewScenario.cpp`**: each of the four cases now calls
`TakeTheWhiteBoxReadingBeforeAnySample(...)` at the point where its texture is reachable only its
own way and **before** the observing sample, asserting all three parts ID-31 names: (a) a record at
a non-zero `ParamsSerial` carrying the field the case moved; (b) the driver's value equals it
**now**; (c) **no sampler view exists for that texture yet**.
**A reading that cannot be taken is DECLINED BY NAME and the case continues.** This is a deliberate
departure from the `GTEST_SKIP` the review sketched, and the file header carries the argument:
these four cases are dual-purpose — they are also the end-to-end regression net around D10, and
that net is the *only* thing measuring D10 on exactly the arms where the peek cannot look (the pull
build; the `0x1ff` and `0` lanes; Magma). Skipping the case there would delete the one verdict
those lanes carry in order to report the absence of a second one. Every decline is printed and
`RecordProperty`'d, so a lane that silently stopped taking the reading is visible in the log rather
than in a count.
The header also carries **esprytobj re-review N-9**, as asked: D's unit probe drives
`SyncTextureParamsToBackend` directly and so sees only a deferral *inside* that function; these
readings run through the real per-frame paths and also see one introduced *above* it —
`SyncNeccessaryTextures`, the attachment walk, E's per-unit walk. Neither half covers both alone.
**Proof 1 — the artefact, and it was a measurement rather than a mutation.** On the base before E
landed, `AReadAttachmentOnlyTexturesDepthStencilModeReachesTheDriver` was red on **exactly one
assertion, the white-box one**, while its public-GL assertion was **green in the same run**:
```
[ TextureParamsWithoutASamplerView ] white-box: texture 1 -> applier handle {15, 1}
paramsSerial 5, Espryt ES name 1, sampler view: none, GL_DEPTH_STENCIL_TEXTURE_MODE applied
before any sample
...:437: Failure applied.DepthStencilMode which is 6402 (GL_DEPTH_COMPONENT)
expected 6401 (GL_STENCIL_INDEX)
```
The applier's record carried `GL_STENCIL_INDEX`, Espryt held no sampler view for the texture, and
the driver was still at the GL default — and the sample at the end of the case repairs it, which is
precisely why the end-to-end half passed. **That pair is R1's gap, measured, and it is the
"落地前必须红" artefact ROADMAP.md:20 asks for**: no public-GL case on a monolith tree can produce
it, and this is the first time it has been produced.
**Proof 2 — it closed with package E, predicted then observed.** Before E landed, a throwaway
worktree = F's head + `git merge refs/heads/p4a/esprytdraw` gave **4/4 green** (measured twice, on
`29d51ab9` and on `29bd4d2c`). E's `SyncReadFramebufferTextureAttachments` is the read-side sync
list that closes D-E3's gap. E is now integrated at `41b79050` and the case is green on the real
tree, with no change to F.
**Proof 3 — mutation**, applied in place, restored, never committed, and re-taken on the final base:
gating Espryt's `SyncTextureParamsToBackend` on `FindSamplerViewForHandle(...) != nullptr` — the
sampler-view coupling ARCHITECTURE.md:100 (D10) exists to remove — makes **all four cases red**,
with **10** `ESPRYT HAS NOT APPLIED …` white-box assertion failures **and 4** of the cases'
public-GL messages. Restored, rebuilt, re-run: **6/6 green**, `git status --porcelain` empty.
### 3.2 c0f's belt, pinned in a lane (ID-40)
New case `ObjectSubsystemControlScenario.TheAppliersNoConsumerBeltNeverFiresBehindTheClientsGate`
and two new lanes at the **phase default** `0x1fff`:
* **`DirectVulkan.ObjectSubsystemControl.NoConsumer.`** — the backend *without* a consumer, and the
first DirectVulkan entry in this family. A non-zero `RefusedNoConsumer` delta there means the
client's gate leaked and only the belt stopped a dirty flag being cleared: ID-39's bug caught one
layer later, and invisible in these pixels *because* the belt does its job (the 66 red cases were
in another suite entirely).
* **`DirectGLES.ObjectSubsystemControl.Consumer.`** — the control, so that a green cannot also mean
"nothing is ever emitted anywhere", which is what a gate that had become accidentally
always-false would look like.
Read as a **delta** across the workload: the counter is process-global and `MGPipeApplierReset`
zeroes it, so a value that went *down* is read as "the applier was reset, everything since is
`after`". Both lanes pass, delta **0**, and both draw the same green every other lane draws. The
CMake comment says why the block's "DirectGLES only" rule does not apply to these two.
### 3.3 wire MINOR-1 — the cube-face erase key (ID-27, integrator grant)
`MG_Test/Pipe/TextureEmitTest.cpp`: **one case added, nothing else in the file changed**.
`TextureEmit.ARespecifyOfOneCubeFaceKeepsTheOtherFacesUploadOfTheSameLevel` puts two cube faces of
**the same level** into `PendingUploads` — the ordinary shape of building a cube map, six
`glTexImage2D` calls at level 0 — and then respecifies one of them with a moved `InternalFormat`
(a real storage redefinition, not ID-18 M4's metadata update, which drops nothing and would make
the case vacuous the other way).
**The SECOND-added face is the one redefined, and that choice is the whole mutation sensitivity.**
The erase walks the vector in order and `break`s at the first match, so a level-only key still
removes exactly one entry — and if the redefined face were first it would remove the *right* one by
insertion-order accident. Measured: the first draft redefined `+X` and was **green** under the
mutation. It now redefines `-X` and asserts the survivor's identity, not only the count.
**Proof**, in place and restored, re-taken on the final base: deleting the
`it->UploadTarget != level->UploadTarget ||` half of the key at `MG_Pipe/PipeApply.cpp:1690` makes
**the new case red and `ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers` stay green** — which
is exactly the review's point, that the existing case cannot see this half. Restored, rebuilt,
green, `git status` clean.
### 3.4 The SamplerCso leak case was measuring C's cache, and is fixed
`DestroyedSamplersReturnTheirSamplerCsoSlots` went red the moment package C's emitter was in the
base — *"48 SamplerCso objects were created, drawn with and destroyed and 14 slots never came
back"*, live 7 → 21, high water 9 → 23. It is **F's own case and F's own defect**, not C's:
`SamplerCso` is minted by a **content-addressed cache** (D-F1, ID-17's reference-count ruling), so
destroying the frontend sampler releases its reference and leaves the entry in the cache,
unreferenced, until LRU eviction at capacity 256. The case's churn cycles the LOD bias
`round % 16` — **16 distinct contents** — and 14 is those minus the two the warm-up had already
interned. A flat "every slot comes back" assertion there measures the cache's capacity policy and
calls it P3a's C-1 leak.
The fix (`4678519f`) is not a weaker assertion but a **warmer cache**:
`AssertChurnReturnsEverySlot` gains a `warmUpRounds` parameter (default 2, unchanged for the other
six kinds) and the sampler case passes `16 + 2`, so the baseline is taken with every distinct
content already interned. The three assertions then say something *stronger* than they can for a
per-object kind — **a warm content-addressed cache must not grow at all under churn** — and an
unbounded leak, which is what C-1 is about, still moves every one of them.
---
## 4. The four minors, closed — and the four defects the gates caught in passing
### 4.1 F-v2-m1 — the refusal matcher now reads the direction
`ObjectSubsystemControlScenario.cpp:196-266`: `LineNamesTheBit` and its symmetric conjunction are
gone, replaced by `EarliestSpellingOffset` plus an **ordering** test in `FindTheRefusalLine`. A line
matches only when, in this order:
`<set-bit spelling>` … `" is set but "` … `<needed-bit spelling>` … `" is clear"`
and it also carries the helper's own decision clause verbatim —
`"REFUSING the dependent bit and running the legacy arm"` — instead of the old loose `REFUS`/`refus`
substring. The **earliest** offset is taken per bit on purpose: Espryt's bit-10-requires-bit-11
sentence says *"only bit 11 mints sampler CSOs"* in its reason, and a later occurrence must not be
able to satisfy an ordering the first does not.
Both lanes find their own sentence and print it. The 0x5ff one, read out of the lane's log:
```
[Linux MobileGLIntegra/ERROR]: MGPipe: kMGPipeSubsystemTextureResources (bit 10) is set but
kMGPipeSubsystemSamplers (bit 11) is clear; MGPTextureParams::BuiltinSampler is a SamplerCso
handle, only bit 11 mints sampler CSOs, and the applier's verdict for a null one is
Fatal{ProtocolCorruption} - REFUSING the dependent bit and running the legacy arm. Set both
bits, or clear both
```
Swapping a caller's two arguments now breaks the chain, which is what the two cases claimed to be
doing and could not.
### 4.2 F-v2-m2 — the 0x5ff arm's wording, and the sentence it asserts
The scenario's comment block (`:681-694`) now says the arm **arms and passes** at integration and
that a red on the refusal assertion is a real finding about D's resolver; the call site (`:742-752`)
quotes Espryt's sentence verbatim, read out of `Managers.cpp`'s
`ResolveTextureResourceSubsystemArm`. `gates-v2.md` §4 and its §7 row carry `[CORRECTED …]` markers.
The lane is **green** on the final base, on both of its assertions.
### 4.3 F-v2-m3 — the wrapper is gone
`MagmaPipeArms.h`: `MagmaPipeAbaControlCoversKind` deleted, with the reason in its place. The knob
has exactly two consumers (`VulkanRenderer.cpp:3653`, `VertexInputStateFactory.cpp:67`) and each
holds one kind — `VertexElementsCso` — by construction, so the conjunction was not a variable at
either site and no build evaluated it; it is not `constexpr` (it reads `MG_Config::Features`) so no
assert could reach it either. The two pieces stand alone and each is pinned by something that runs:
the `constexpr` per-kind table with its three `static_assert`s, and the knob its consumers read.
`grep -r MagmaPipeAbaControlCoversKind MobileGL/`: 0 hits. G1 is unchanged.
### 4.4 F-v2-m4 — `REPAIR_RC` is read
`scripts/p4a_descriptor_negative_control.sh`: the flag is documented as sticky (`:184-188`), read
after the control loop (`:499-504`, forcing `WORST=2`), and read by the **EXIT trap** (`on_exit`,
`:242-250`), which `exit 2`s over whatever status an early exit had chosen. That last one is the
path the review asked for: a repair that fails while the script is on its way out through an early
`exit` can no longer leave a corrupted build directory behind a 0 or a 1. `bash -n` clean.
### 4.5 Four defects the gates caught, and where each was fixed
All four were red on one of the two intermediate bases and are green on `41b79050`. Three were
fixed by the integrator's D/E verification commits, independently and with the same diagnosis.
| what F measured, and where | fixed by |
|---|---|
| **At `MOBILEGL_PIPE_PUSH=0x5ff` the client emitted the texture family while Espryt refused bit 10 and ran its legacy arm.** The lane's own log carried `emit[fbe=0 sve=0 sse=0 sie=0 ctu=5]` on the very run that carried the refusal line; the applier accepted, the client cleared the level's dirty flags on that acceptance, and the legacy upload path found nothing to upload — the sampled texture was **black** (11625/11625 pixels). ID-39's failure mode with the consumer signal replaced by the dependency. The mirror at 0x9ff was benign (`sve=2 sse=2`, nothing carrying texels, pixels green). Measured on `29d51ab9` | **`29bd4d2c`** — "gate the four P4a families on D-K2's dependency bits as well", in `PipeFill.cpp`: the site and shape F's diagnosis named. `DirectGLES.ObjectSubsystemControl.RefusedTexture.` is now the pin, and its `emit[…]` bracket is the only place this shape is visible |
| **G2 was broken by one name.** `TextureEmit.WithNoBackendConsumerTheFamilyGateIsFalseAndNothingReachesTheApplier` (c0f's own unit case) sat inside `TextureEmitTest.cpp`'s push-only half and was never added to `MGL_TEXTURE_EMIT_CLIENT_TEST_LIST`, so pull named 2842 and push 2843. Measured on `29d51ab9` | **`245daca0`** + **`ee31944b`** — the pull-build skip twin. G2 is now **2846 == 2846, zero diff** |
| **The built-in-sampler seam was a four-case seam, not ID-39's two.** F's `HandleRecycle.Handles.…ASamplerAtARecycledAddressDoesNotInheritItsPredecessorsParameters` was red with `expected=FRESH observed=NEITHER`, first offender **blue** — the texture's own colour, i.e. a plain sampler object's `GL_CLAMP_TO_BORDER` + float `GL_TEXTURE_BORDER_COLOR` never reached the driver at all, in the **warm-up** frames, before any recycling. Not confined to the integer-sampler path ID-39 named. Measured on `29d51ab9`, and still red with E's branch merged at that point | **`1e8cdc59`** (D) and **`41b79050`** (E) — "the twin resolved a content-addressed record by an identity handle". All four sampler-shaped cases are green now |
| **D-E3's read-attachment gap, measured white-box** — §3.1. Red on `29d51ab9` and on `29bd4d2c`, green on both merged-with-E worktrees, green on `41b79050` | **`41b79050`**'s branch — E's `SyncReadFramebufferTextureAttachments` |
---
## 5. Section 6, re-taken on `4678519f`
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` exported for every build and every run;
`CCACHE_BASEDIR=/home/swung/w7`, `-j 8`, Release/clang/Ninja, llvmpipe + lavapipe.
| gate | result |
|---|---|
| three builds | `build-linux` / `build-push` / `build-verify` **rc 0** |
| **G1** `symbol_report.py --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0` | **0 added / 0 removed / 0 resized / 0 renamed**. `.text` 10806323 → 10806323 (+0). 27811 → 27811 defined symbols |
| `ctest -L unit` × 3 | `build-linux` **1767**, `build-push` **1767**, `build-verify` **1767** — 100%, 0 failed in each |
| **G2** pull vs push names | **2846 == 2846, diff empty** |
| **G14** vs `~/w7/p4a-before-ctest-names.txt` (37da3c3a, `LC_ALL=C`) | **0 removed**, **+258 added**. F v3's own share is **+3**: the two consumer lanes and the cube-face unit case |
| **G5** `p4a_untouched_regions.sh 37da3c3a HEAD` | **rc 0**, **17 rows** |
| **G5** `--self-test` | **rc 0**, 3 positive + **8** negative controls, all tripped and all named |
| `p3a_untouched_regions.sh 37da3c3a HEAD` / `--self-test` | **rc 0** / **rc 0** |
| `check_include_closure.py --mode text --self-test --require-all --expect-probes 4` | **rc 0**; `--expect-probes 5` **rc 1** |
| **G7** `scripts/g7_negative_control.sh build-push` (P2) | **rc 0** |
| **G7** `scripts/p3a_vertex_input_negative_control.sh build-push` (P3a) | **rc 0** |
| **G7** `scripts/p4a_descriptor_negative_control.sh build-push` (P4a) | **rc 0 — `Layered` tripped, `borderColorForm` tripped**, "both controls tripped and named their field; exit 0" |
| `scripts/p4a_descriptor_negative_control.sh build-linux` | **rc 2**, refused as a non-push build directory (F-m10) |
| **G7 SIGINT**, delivered to the process group mid-rebuild from a new session with the child's disposition reset to `SIG_DFL` | the script **died by SIGINT** (`returncode -2`, i.e. 130), the repair ran and printed *"restored …; rebuilding build-push from it"*, and **`git status --porcelain` was empty**. No summary is printed on that path, which is correct: exit 2 *with* the interruption wording is the signalled-**child** path, not this one |
| `ctest --test-dir build-push -L integration-gpu -j 8 --no-tests=error` (default `0x1fff`) | **1079/1079** |
| the same at `MOBILEGL_PIPE_PUSH=0x1ff` / at `0` | **1079/1079** / **1079/1079** |
| `ctest --test-dir build-linux -L integration-gpu` (PULL) | **1079/1079** |
| **DirectVulkan lane** `-R '^DirectVulkan'` | **540/540** (c0f holds; it was 475/475 before F's lanes added names) |
| DirectGLES lane `-R '^DirectGLES'` | **539/539** |
| `ctest --test-dir build-verify -L integration-verify -j 4` | **884/884**, **zero `Fatal` lines** |
| `ctest -R HandleRecycle` push / verify / pull | **144/144** / **180/180** / **144/144** |
| `HandleRecycle.Handles` push | **36/36** — ID-38/ID-39's six armless `.Handles` aborts are closed by the itest CMake's `0x1fff` phase pin |
| `ctest -R ObjectSubsystemControl` push | **14/14** (both refusal lanes, both consumer lanes) |
| `ctest -R 'TextureParamsWithoutASamplerView\|TextureUploadShape'` push | **11/11** |
| the four families, pull / verify | **169/169** / **223/223** |
| `ctest -N` totals | push **2846**, verify **3730** |
| working tree / attribution / message shape | clean; no `Co-Authored-By`; fifteen single-line messages |
**Recorded, not gated.** `TextureUploadShape` on DirectGLES/llvmpipe now reads
`server[emit=6 box=6 rect=0 jobs=6] client[ctu=6]`. The client half was `ctu=0` at v2 (no emitter
on that base) and now agrees with the server's count — which is exactly what F-m7's build probe was
added to make readable, and it is the first tree on which the two numbers can be compared at all.
Re-confirmed and worth restating: **a ctest `ENVIRONMENT` property overrides the job env**, so the
`HandleRecycle.Handles`, refusal and consumer lanes keep their own `MOBILEGL_PIPE_PUSH` whatever
outer arm the gate runs. That is why the `0x1ff` and `0` arms above do not move those lanes, and it
is deliberate.
---
## 6. What the integrator must re-run on the final tree
`gates-v2.md` §7 stands as amended there. On top of it:
| what | why |
|---|---|
| `ctest -L integration-gpu` on both builds and at the three masks | **1079/1079 everywhere** is the answer today. Anything less is a regression, not a known red: F leaves none |
| `diff <(ctest --test-dir build-linux -N) <(ctest --test-dir build-push -N)` | G2 must stay empty. Extract names with `sed -n 's/^ *Test *#[0-9]*: //p'` and `LC_ALL=C sort`; `awk '{print $3}'` truncates the five parameterised `Shapes/DemoteFloat64EsslTest…` names and manufactures a spurious 5 removed / 5 added |
| `bash scripts/p4a_descriptor_negative_control.sh build-push` | **rc 0 naming `Layered` and `borderColorForm`** is now the answer, not rc 2. rc 2 with the contract-tree wording means an emit header went back to a stub; rc 2 with the *interruption* wording means the run was killed and reported nothing about the controls |
| `bash scripts/p4a_untouched_regions.sh 37da3c3a HEAD` **and** `--self-test`, at **every** integration step | 17 rows / 8 negative controls. The cheapest check that a merge did not quietly touch Espryt's protected regions |
| the `0x9ff` and `0x5ff` lanes **with the lane logs kept** | The matcher pins the DIRECTION and the decision clause, so the two lanes accept disjoint sentences. Read the printed `refusal line:` **and** the `emit[…]` bracket in the same log — the bracket is what caught the client/server disagreement in §4.5, and it is the only place that shape is visible |
| `ctest -R 'ObjectSubsystemControl.(Consumer\|NoConsumer)'` | Both must pass with `refused_no_consumer_delta` **0**. A non-zero on the NoConsumer lane is the gate/belt disagreement c0f closed, reappearing |
| `ctest -R HandleRecycle` on all three builds, reading the printed `[ HandleRecycle ] … live A -> B (peak P), high water H1 -> H2` lines | The SamplerCso case now takes its baseline with the content cache warm (§3.4). A `live` that grows there again **is** a real leak, because every content is already interned |
| `ctest -R 'TextureParamsWithoutASamplerView'` **and read the case's stdout** | Each case prints one `white-box:` line naming the applier handle, the params serial, Espryt's ES name and "sampler view: none". A `white-box reading DECLINED` line on the push build's DirectGLES lanes means the peek stopped being able to look, which a green count will not tell you |
| `ctest --test-dir build-verify -R 'EvictedPipelineComposites'`, reading the band line | Unchanged from `gates-v2.md` §7: a high water still equal to the floor (983040) means C's composite resolver is not minting through `AllocateComposite` and the case is skipping, not passing |
| grep the configure output for `MOBILEGL_PIPE_HANDLE_ABA_CONTROL steers <backend>` | Unchanged. F-M5's probe is directory-wide |
| the CI `pipe-gates` include-closure step | `--expect-probes 4` is pinned and must change in the same commit as `check_include_closure.py`'s `PROBES` list. Do **not** "fix" `clang++-20` to bare `clang++` on the strength of a local failure (ID-9 D16 / ID-11) |
| a SIGINT test of the G7 script, if re-verified | Launch it with SIGINT deliverable **to the process group**, from a new session, with the child's disposition reset to `SIG_DFL`. A `&` from a non-interactive shell makes the trap unreachable and the test measures nothing |
| **G1, the three `-L unit` runs, the pull/push name diff and the G14 delta, re-taken** | They move with whatever lands after this head |
**Not re-run here, and still the integrator's (ID-3):** D.3/D.4's retrace sweeps, the device A/B,
DriverBench, the APKs and the docs pass.
---
## 7. Method note
Every mutation in this report was applied to the working tree, measured, restored, rebuilt and
re-run green, with `git status --porcelain` empty afterwards — the same discipline the two shipped
negative-control scripts use, and the check is stated in each subsection. Nothing was committed.
Both mutation proofs were re-taken after the final rebase, on the head this report names. The
E-merge measurements used throwaway `git worktree`s whose submodules were symlinked at the gates
tree's checkouts; they were removed and pruned, as have been every log and helper this round wrote
under `~/w7`.
@@ -0,0 +1,364 @@
# P4a package A — `w1`-`w4`, adversarial review of the applier bodies (`wire-review-v1`)
Reviewed `86835b50` / `bc9abfbd` / `0f990633` / `3c07c8c3` on `refs/heads/p4a/wire`, parent `08192d72`
(tag `p4a/contract`), worktree `/home/swung/w7/p4a-wire` (**not modified**). Everything below was checked by
opening the file at `3c07c8c3`; the brief, `contract-v1.md`, `contract-review-v1.md` and `contract-v2.md` were
re-read at their landed text. No private worktree was needed: every claim I re-derived is a source or a
structural one.
## Verdict
**REWORK** — one critical defect, small and fully specified, plus five minors of which two were explicitly
assigned to this package by the integrator and not taken.
The package is otherwise very good, and better than P3a's `wire` was at the same point. The three-table split
is right and is argued at the place it matters; the two verdicts (counted no-op vs `Fatal{ProtocolCorruption}`)
are applied consistently and the boundary between them is drawn where the brief draws it; the sub-data split
into a buffer half and a texture half is the right call and its "deliberately NOT checked" list is the most
useful comment in the file; `ApplyUnitWindow` is one body for three sets with the overflow written in `Uint64`;
the composite band split is correct at both ends and is coherent with `c0b`'s `CompositeHighWater` split (no
w4 case reads `HighWater`, only `LiveCount(ShaderCso)`, which `c0b` deliberately left summing both spaces —
§4.3 of `contract-v2`); and the verify-only codec pin is live code with a gate, in the right place in the body,
under the right guard, with the `Fatal{PipeVerifyDiffer` marker G4 greps for. Behaviour neutrality is
structural and I verified it independently: all four `kMGPipeWired*Subsystem` constants are still `0`
(`FramebufferEmit.h:40`, `TextureEmit.h:36`, `SamplerEmit.h:41`, `ProgramEmit.h:46`) and the only mentions of
the fifteen entry points outside `MG_Pipe/PipeApply.{h,cpp}` and `MG_Test/Pipe/*EmitTest.cpp` are two prose
comments (`MG_Impl/Pipe/ProgramEmit.h:33`, `MG_State/GLState/ProgramState/ProgramArtifactsCodec.h:26`).
What forces a rework round is **C1**: `resource_respecify` clears the *whole* pending-upload set, which throws
away accepted uploads for levels and cube faces the respecify never redefined — after the client has already
cleared those levels' dirty flags. That is the exact class of loss D-D5's server-side set exists to prevent,
it is reachable on a canonical mip-building sequence, and it is invisible to every gate P4a has. It is
declared as deviation **W7**, whose stated justification is factually wrong about the frontend.
Nothing here needs the tag re-cut. C1's fix is ~15 lines in A's own file plus one case; the minors are
one-liners. G1, G13 and the closure gate hold and hold structurally (`PipeApply.{h,cpp}` are push-only
translation units, so the pull build cannot move).
---
## Findings
### C1 (critical) — `resource_respecify` drops the pending uploads of every level, not of the level it redefines, and the client has already cleared those levels' dirty flags
`MG_Pipe/PipeApply.cpp:1478-1485` (the clear and its comment), `PipeApply.h:220-238` (the set and its
contract), `MG_State/GLState/TextureState/TextureObject.h:245` and `:252` (the frontend's per-level
granularity), `MG_State/GLState/TextureState/MipmapStorage.h:53,118` (`m_isDirty` is a per-level vector),
brief D-D1 (respecify is emitted from `TexImage{1,2,3}D_State` — i.e. per GL call, per level) and D-D5.
```cpp
// PipeApply.cpp:1485
record->PendingUploads.clear();
```
The pending set is keyed `(UploadTarget, Level)` and holds every emission the applier has accepted and the
backend has not yet consumed. A respecify wipes all of them.
**Why the deviation's argument does not carry.** W7 says *"nothing is lost because the frontend entry points
that respecify a texture re-mark the levels they define (`AllocateStorage` then `MarkStorageDirty`)"*. Both
frontend entry points are **per (uploadTarget, level)**:
```cpp
// TextureObject.h:245, :252
virtual void AllocateStorage(TextureUploadTarget uploadTarget, Uint mipmapLevel, MipmapInput input) = 0;
virtual void MarkStorageDirty(TextureUploadTarget uploadTarget, Uint mipmapLevel, Bool dirty = true) = 0;
```
so a `glTexImage2D(level = 1)` on a mutable texture re-marks **level 1 and nothing else**, while the applier's
clear drops the pending entries for levels 0, 2, 3 … and for the other five cube faces. Those levels' client
dirty flags were cleared at *their* emission (D-D5 step 1), so nothing anywhere still owes them.
**Failure scenario**, and it is the canonical one:
1. `glTexImage2D(level 0, data)` → respecify (GL-call time), `MarkStorageDirty(0)`.
2. `glDrawArrays` → the drain emits `resource_subdata(level 0)`; the applier accumulates it; the client
clears its level-0 dirty flag.
3. Espryt **bails** — the texture is not mipmap-complete for its min filter, which is the
`Managers.cpp:5734-5738` early return D-D5 names by name — so the applier's entry survives, exactly as
designed.
4. `glTexImage2D(level 1, data)` → respecify → **`PendingUploads.clear()` destroys level 0's entry.**
5. `glDrawArrays` → the drain emits level 1 only. Level 0's texels never reach the driver, in any build,
with no counter, no log line and no gate that can see it. The same happens for
`glTexImage2D(0); draw; glGenerateMipmap(...)` — the generated-mip storage grow at `GL_Texture.cpp:528-539`
is a respecify emission C.7 explicitly grants to B — where the whole generated chain is then built from
whatever the driver had in level 0.
**Refutations attempted, and why each fails.**
- *"Both respecifies happen before the drain, so nothing is pending yet."* True only when no verb separates
them. The loss needs one intervening verb, which is what step 2 is, and streaming a mip chain while drawing
is the ordinary shape.
- *"Espryt consumes the entry at the sync between the two calls."* Sometimes. The arms where it does not are
precisely the bail arms the server-side set was introduced for (D-D5's own words), and the
incomplete-texture bail persists **until more levels are defined** — i.e. until the very call that wipes the
set.
- *"A respecify invalidates the level's coordinate system, so keeping a box would upload past the end of a
shrunken store."* True **for the level being redefined**, which is why the clear is right for that key and
for a whole-resource redefinition (`glTexStorage*`, which defines every level at once). It is not an
argument for dropping the other keys.
- *"The verify lane's retain mode would catch it."* It cannot: retain mode compares the *emitted*
`(UnionBox, RegionCount, Regions[])` against the tracker's pre-clear set. The emission happened and matched;
what was lost happened afterwards, inside the applier.
- *"It is latent — nothing consumes the set in this tree."* Same answer P3a's wire review gave to the same
objection: these are the record semantics B's drain and D's consume loop are being written against right
now, and D.1's order exists so that no package after `contract` runs against a wrong applier.
**Fix.** The clear has to be scoped, and `MGPResourceDesc` names no level, so the scope has to arrive with the
call. The cheapest form is the one W1 already established as legitimate in this file — a trailing defaulted
parameter that the buffer call sites do not pass:
```cpp
// PipeApply.h
struct MGPRespecifiedLevel { Uint16 UploadTarget, Level; };
void MGPipeApplyResourceRespecify(const MGPResourceDesc& desc, const void* initialBytes,
const MGPRespecifiedLevel* level = nullptr);
```
`nullptr` = "this respecify redefines the whole resource" (every `glBufferData`/`glBufferStorage`, every
`glTexStorage*`, every `TextureView`) → clear all, as today. Non-null → erase only the matching
`(UploadTarget, Level)` entry and keep the rest. B passes the pair it just allocated, which it has in hand at
every `AllocateStorage` call site. If the integrator would rather not touch the signature a second time, the
fallback is to clear nothing on a respecify and put the shrink clamp on the consume side (D) — but that moves
"the applier owns extent" (D-J1) onto the backend and needs saying out loud in the brief.
Either way the case is `TextureEmit.ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers`, with the mutation
(delete the scoping) added to the harness, and `TextureEmit.ARespecifyDropsThePendingUploadsAgainstTheStorageItReplaces`
narrowed to the whole-resource arm it actually proves.
---
### m1 (minor) — `MGPipeApplierReleaseObjectRecords` still clears three of the working handles it says it clears (contract review `m2`, assigned to `wire`, not taken and not declared)
`MG_Pipe/PipeApply.cpp:1117-1133`. The comment says *"P4a's five object tables go with them, **and the working
handles they could name go too**"*, and then nulls `DrawProgram`, `DispatchProgram` and `BoundShaderCso` only.
`DrawFramebuffer` / `ReadFramebuffer` — whose eleven `MGPSurface::Res` name texture and renderbuffer records
this function has just dropped — and `BoundSamplerViews` / `BoundSamplerStates` / `BoundShaderImages` — whose
entries name sampler-view, sampler-CSO and texture handles it has just dropped — are left populated.
Latent in the monolith (the function is wired to nothing, `PipeApply.h:556-563`), and teardown-only under
split, which is why this is a minor and not more. What makes it a rework item rather than a note is that
`contract-v2.md` §7 item 7 assigned it to this package in as many words (*"`wire`: M2 … and m2 are yours"*),
the report does not mention it, and D and E will read this function as the definition of what survives a
release. Two lines, or one honest sentence saying why the framebuffer records and the three sets deliberately
outlive the object records they name.
### m2 (minor) — `PipeApply.h`'s `RefusedObjectCalls` comment still promises a framebuffer refusal that W4 correctly says cannot exist
`MG_Pipe/PipeApply.h:422-428`: *"every **framebuffer**, sampler, sampler-view, program and texture-params call
this applier refused"*. `MGPipeApplySetFramebufferState` (`PipeApply.cpp:1953-1959`) resolves no record and can
never touch the counter — which is right, and W4's reasoning from D-I2 is right. But the header is A's own
file, this package owns it, and the fix is deleting one word. Leaving the contradiction in the header and the
correction in a report is the wrong way round: `MG_Test`, D and E read the header. (The brief's D-J3 has the
same five-family list; the integrator amends it at D.5.)
### m3 (minor) — the texture half of `resource_subdata` accepts any non-zero `Target`, including the `Renderbuffer` enumerator, and nothing pins the upload-target value space
`MG_Pipe/PipeApply.cpp:504-511` (`SubDataNamesABuffer`), `:834-837` (the texture half resolves in
`TextureResources`), `MGPipeTypes.h:844` (`Uint16 Target`), brief D-D3 (*"the owner's upload target
(`MGPipeResourceTarget` from D-A3, plus the cube-face upload target …)"*).
`MGPipeResourceTarget::Renderbuffer` is `10` and is therefore a perfectly plausible `MGPSubData::Target`; a
record carrying it is routed to `TextureResources` and, if a live texture holds that slot in the texture slot
space, accumulates a pending upload onto **that texture**. Unreachable from a correct client (renderbuffers
have no sub-data path), which is why it is a minor — but the applier's own argument for `ResourceTableForTarget`
returning null on an unknown enumerator ("acting on the wrong table would … act outside its own storage") is
exactly the argument for refusing this one. The value space of `MGPSubData::Target` is also undocumented on the
record: B is about to encode cube faces into it and nothing says which numbers are free. One `static_assert`
or one sentence beside `MGPSubData` plus a `Target != Renderbuffer` arm closes both.
### m4 (minor) — no acceptance signal reaches the emitter, so D-D5's "clear only for levels the applier accepted" degrades to "clear for levels I emitted"
`MG_Pipe/PipeApply.h:628` / `PipeApply.cpp:1502-1516` return `void`; `ApplyTextureUpload` has two silent exits
(a refused resolve at `:837`, a validator fault at `:849-858`) and neither is observable from the call site.
`RefusedResourceCalls` cannot substitute: the validator's `Fatal{ProtocolCorruption}` path does **not**
increment it, so in a shipped push build a refused upload and an accumulated one are indistinguishable to B's
drain loop, which is about to clear the level's dirty flag on the strength of having emitted.
I could not build a reachable loss out of it and that is why it is a minor rather than a major: the texture
family's create gate and consume gate are the same bit (D-B1 registers no op table, so there is no
register/unregister window of the kind `PipeFill.cpp:653-679` documents for buffers), so the resolve failure
only happens at teardown, where the texels do not matter. But D-D5 step 1 says *"only for levels whose record
the applier **accepted**"*, the signature is open in this very round, and it will not be open again: return
`Bool` (true when the record was stored/accumulated) from `MGPipeApplyResourceSubData` in the same edit that
fixes C1, and let B gate its clear on it.
### m5 (minor) — the three buffer-only entry points police their kind with an inert assertion where `resource_destroy` uses a Fatal
`MG_Pipe/PipeApply.cpp:1524` (`flush_range`), `:1553` (`readback`), `:1639` (`map_persistent`), `:1660-1663`
(`unmap_persistent`). All four resolve through `ResolveResource`, i.e. against `g_applier.Resources` — correct,
because these calls exist only for buffers — but `MGPFlushRange` / `MGPReadback` carry no kind at all, and
`unmap_persistent`'s `MOBILEGL_ASSERT(handle.Kind == Buffer)` compiles out at INFO, which is what every gate
build is. A mistyped record therefore aliases whatever buffer holds that slot instead of being refused, which
is the failure mode `resource_destroy`'s `ResourceTableForKind` Fatal exists to stop. W3's fix is complete for
the four calls the brief names (create / respecify / subdata / destroy); this is the tail of the same question
and one `Fatal` in `unmap_persistent` closes the only half that has the discriminator to close it.
### n1..n4 (nits, no rework required)
- **n1** `SubDataTextureFault` (`PipeApply.cpp:672-709`) checks region *containment* but not *disjointness*,
and `AccumulatePendingUpload` (`:751`) concatenates lists across emissions, so the accumulated list can hold
overlapping rects that the frontend's own model (pairwise disjoint behind one level,
`MipmapStorage.h:62-75`) never produces. Harmless — D's N-rect staging uploads the same texels twice — but
say it in the header beside `PendingUpload`, because D will read "the frontend's model" and assume disjoint.
- **n2** "the record describes no texels at all" (`:843`) tests the union box and `RegionCount`, so a record
with `RegionCount = 1` and an all-zero region passes and creates an entry describing nothing.
- **n3** a texture record's `MGPTextureParams::BuiltinSampler` is never swept when the CSO it names is deleted
(`MGPipeApplyDeleteSamplerState`, `:2035-2053`), by the same deliberate non-resolution as `set_texture_params`
— correct, but §5 of the report tells D what to read and does not tell it that this handle can be dead.
- **n4** contract review `m1` (the tautological `kMGPipeResourceTargetBuffer` assert, `MGPipeTypes.h:185-188`)
was offered to `wire` and is still unclaimed. Optional.
---
## Judgement on the eight deviations
| # | verdict |
|---|---|
| **W1** — trailing defaulted `const MGPSubRegion* regions` | **Accept.** It breaks nothing: `gen_pipe.py` never parses `PipeApply.h`, and the generated wire path (`generated/PipeWire.inc`, `MGPipeApplyWireRecord`, `gen_pipe.py:672-685`) is a bounds-checking skeleton that returns "not applied" and calls no `MGPipeApply*` function, so there is no thunk to break and `PipeCalls.def` is untouched. It **does** close M2 fully: `AccumulatePendingUpload` (`PipeApply.cpp:751,762`) fills `PendingUpload::Regions` from the tail, so D-D3's rect list, D-D5's pending set and verify's retain-mode comparison are all reachable, and the region-containment gate is the invariant M2 said nothing could check. The one cost is that a caller who forgets the tail gets `nullptr` instead of a compile error; the record's own `RegionCount != 0 && regions == nullptr` Fatal (`:682`) catches the case where it matters, so the hole is closed by the validator rather than by the type system. Acceptable, and the amendment notice the report gives B/C/D is the right form. |
| **W2** — four new bounds constants | **Accept.** Each is argued at its declaration, each is a number that arrives in a payload, none is allocated by being named. I checked the one that could be wrong: `kMGPipeMaxPendingUploads = 256` is above the 192 distinct `(cube face, level)` keys a legal texture can produce, so no legal record can ever hit that Fatal. |
| **W3** — the folded dispatch-guard defect | **Accept the fold** (the branch was rewritten before any push, the four commits and four exact messages are intact, and the defect was found by the package's own gate, which is the system working). **Complete for the four calls the brief names** — verified at `:1452`, `:1496`, `:1509-1515`, `:1624`, and negatively by `ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable`, which also drives the same five calls on a buffer to prove the spy is armed. The tail of the question is m5. |
| **W4** — no refusal counted for `set_framebuffer_state` | **Accept the behaviour, reject the paperwork.** D-I2 gives a framebuffer a handle and no wire lifetime, so there is nothing to resolve and nothing to refuse; not resolving `MGPSurface::Res` is likewise right (D-I3: the keep-alives are the frontend's `SharedPtr`s and enforcement is P5's). But the correction belongs in `PipeApply.h`, not only in the report — m2. |
| **W5** — the create/re-issue serial rule | **Accept.** It follows the contract header and D-J2 verbatim (`a create is not a mutation`, `Serial` 0 so a fresh twin agrees without either side publishing), it names the divergence from `create_vertex_elements` honestly, and the three implementations are consistent with one another (`:2020-2025`, `:2075-2080`, `:2259-2273`). |
| **W6** — a re-issued `create_shader_state` clears the default uniform block | **Accept.** A relink replaces the layout the image was sized to; `~0u` is the sentinel that means "never uploaded"; `++GlobalConstantsSerial` announces the clearing so a twin cannot match what it staged before the relink. Well reasoned and correctly implemented. |
| **W7** — a respecify clears `PendingUploads` | **Reject as written — this is C1.** The clear is right for a whole-resource redefinition and wrong for the per-level one, and the frontend fact the deviation rests on is the opposite of the fact. |
| **W8** — `p4a-trees2.log` never said `REBUILT wire` | **Accept as a process note.** Three complete build logs plus a no-op `cmake --build` returning rc 0 across all three trees before the first edit is adequate evidence that the tree was current; the missing line is the orchestration script's and is worth fixing before the next package waits on it. Not a code matter. |
---
## H1 — is `BuiltinSampler == null` under `0x5ff` a real lane, and whose fix is it?
**It is a real lane.** `0x5ff` = bits 0-8 (P3a's `0x1ff`) plus bit 10 (texture resources). D-K2's table has
three rows — 11→10, 9→10, 10→7 — and `0x5ff` violates none of them, so no refusal fires and the arm runs. Bit
10 carries `set_texture_params` (D-K1), whose record must name a `SamplerCso` handle
(`MGPTextureParams::BuiltinSampler`, D-E1), and `contract-v2` §3.2's four unconditional mints are
`Texture / Renderbuffer / Framebuffer / ShaderCso` — **the sampler CSO is deliberately not among them**,
because it is content-addressed and shared (D-F1) and §3.4 leaves its identity rule to package C. So on that
arm the only thing that can mint the handle sits behind bit 11, the record carries `kMGPipeNullHandle`, and
`PipeApply.cpp:2128-2134` aborts the process in a verify or poison lane and drops every texture's parameters
in a shipped one. The applier is implementing D-E1 exactly as written and is not the defect.
**Assignment: the contract's — add a fourth row to D-K2, "bit 10 (texture resources) requires bit 11
(samplers)", refused in `ResolveTextureResourcesSubsystemArm()` with one `MGLOG_E` naming both bits and a
fallback to the legacy arm** (package D implements it, `ObjectSubsystemControlScenario` gets the mirror of
`ASamplerBitWithoutTheTextureBitIsRefusedAndNamed` at `0x5ff`, and the integrator corrects the brief's
sentence *"the mirror pairs (bit 10 without 11 …) are all fine"* at D.5).
The alternative — have the client mint the built-in sampler's CSO handle unconditionally in a push build, the
§3.2 shape — is worse on two counts. The handle of a **content-addressed** CSO is the cache's answer, so
minting it unconditionally means running the sampler cache's hash-and-confirm in the arm that exists to
exclude the sampler family, which costs the A/B its meaning anyway; and it makes the texture emitter (B) reach
into the sampler emitter (C), across the one package boundary C.7 was drawn to keep. §3.2's argument covers
identity-addressed handles minted at construction, which this is not. The cost of the D-K2 row is that bits 10
and 11 become one arm — real, but bit 11 already required bit 10, the recorded arms are pull / `0x1ff` /
`0x1fff` (D.4.2) and not per-bit sweeps, and a stated coupling beats a lane that aborts.
Either way the answer must be written down before B and C emit, because today the tree has an arm that
`ROADMAP.md:7` would call a gate that cannot go green.
---
## What I checked and found correct (so a later round does not re-derive it)
- **Per-target framebuffer storage.** `Target != Read` writes draw, `Target != Draw` writes read, `Both` writes
both and bumps the pair's one serial once (`:1960-1970`, pinned at `FramebufferEmitTest.cpp:242-249`). The
`{0,1}` default framebuffer needs nothing here: `Fbo` is stored verbatim and never resolved. `Target >= Count`
and every `DrawBuffers[i] ∉ [-1, 8)` are Fatal with the identity in the line (`:1930-1951`).
- **The three tables and the destroy dispatch.** `ResourceTableForTarget` (descriptor) and `ResourceTableForKind`
(handle kind) both return null on an unknown value and both callers Fatal (`:1415-1422`, `:1595-1602`); slot 7
is three live objects at once and `ResourceEmit.TheThreeResourceKindsKeepTheirOwnSlotSpaceAndDoNotSeeEachOther`
proves it end to end including the destroy.
- **The sub-data validator.** Level < 32, encodable box, `RegionCount <= 256`, non-null tail, every region
encodable **and inside the union box**, "no texels at all", non-null bytes — and the three deliberate
non-checks are argued rather than omitted. The containment rule is the right one and the reason given for it
(the server picks the shape from the pair) is the reason.
- **`set_texture_params`.** On the texture's own record, `ParamsSerial` moves and `Serial` does not, both resync
bytes are carried and never cleared, the named CSO is deliberately not resolved (an ordering fact, not a
corrupt one) — all as D-E1/D-E2 require.
- **Sampler CSO / view records.** The blob rule (0 or exactly `sizeof(SamplerParameters)`), the by-value store
including `borderColorForm`, the fresh-vs-re-issue rule, the delete that does **not** sweep the unit window,
the silent back-pointer write, and the delete that clears the back-pointer only if the texture still names
this view (`:2100-2106`) — that last guard is right and is the one thing in the family a mutation harness
would need a new case for (see "test gaps").
- **`ApplyUnitWindow`.** `Uint64{start} + Uint64{count} > destination.size()` cannot overflow; entries land at
`start + i` and nowhere else; nothing outside the window is cleared; the `Unit` field is stored and not
policed, with `MGPVertexBuffer::BindingIndex`'s precedent cited; a refused set moves no serial and touches no
entry; an empty set is applied and still moves the serial. `SamplerEmit.AUnitWindowPastTheMergedUnitSpaceIsRefusedRatherThanTruncated`
pins the acceptance boundary (`Start + Count == 192`) as well as the refusal, which is the shape the house
asks for.
- **The composite band.** `MGPipeIsCompositeShaderSlot` is `[base, limit)` (`MGPipeHandles.h:103-105`), so a slot
at or above the limit falls to the ordinary table and is refused by its `base` bound rather than indexing the
band's; both tables grow only to their own high-water mark; no `MGPipeShaderCsoRecord` outside the band can
reach a band slot. `CompositeResolver.ASlotAtTheShaderCsoLimitIsRefusedWhileTheLastBandSlotIsNot` pins both
sides.
- **Serials only advance.** All five working serials `++` in `MGPipeApplierReset` *and* in
`MGPipeApplierReleaseObjectRecords` (`:1099-1103`, `:1129-1133`); the per-record serials restart with the
record, which is safe because `Gen` moves with it.
- **Reset semantics.** Working state cleared, object records untouched — including `Params`, `ParamsSerial`,
`ViewCso` and `PendingUploads`, which ride on a resource record; four cases pin it, one per family.
- **Exit order.** No new static, no new singleton, no frontend `SharedPtr` anywhere: the only global is P3a's
`g_applier = *new MGPipeApplierState{}` (`:396`), unchanged. The six test TUs' `String g_logPath` is test-only.
- **G1 / G13 / closure.** `PipeApply.{h,cpp}` compile only under `MOBILEGL_PIPE_PUSH`, so the pull build cannot
move; `MGPipeResourceOps` is unchanged at nine members with no frontend type; the verify-only
`#include <MG_State/GLState/ProgramState/ProgramArtifactsCodec.h>` sits inside `#if MOBILEGL_PIPE_VERIFY`
(`:19-27`) and no closure probe names `PipeApply.*` or forbids `MG_State` inside `MG_Pipe`
(`scripts/check_include_closure.py:73-137`) — so that include is unguarded by design and the contract header
is the only thing holding it, which is worth knowing at P13 but is c0's decision, not this package's.
- **The codec pin.** Runs after the bounds gate and before the store, all four faults are real faults, and the
`decodedLink.program != nullptr` arm is the right paranoia. The tag is `Fatal{PipeVerifyDiffer}`, which is
what G4 greps.
- **Hygiene.** Four commits, four exact single-line messages, empty bodies, no attribution, not pushed; two
production files and seven test files, all A's by C.7; every test file is a visible SKIP in a pull build.
## Tests (w4) — 33 cases
Not vacuous. Every case I opened asserts a specific field or counter, most assert an acceptance boundary
*and* its refusal in the same body, and the refusal helper (`ExpectRefusedNaming`) checks the log line's text
in a push build and `SIGABRT` plus the text in a forked child under verify/poison — I confirmed the needle
matches both spellings of `MGP_TRIP_WIRE_TAG` (`PipeApply.cpp:42-52`). The counter discipline is pinned in both
directions: a counted refusal moves `RefusedObjectCalls`, a `Fatal` must **not**
(`TextureEmitTest.cpp:324-325`, `ResourceEmitTest.cpp:1422-1423`), which is the distinction the whole file
rests on. The mutation evidence is credible: I traced M11, M13-M16, M20, M26, M28 and M40 to bodies that do
fail if the named line is removed, and M16's SegFault is exactly what deleting the null-tail gate produces at
`:686`. The report's note that grepping ctest output for `(Failed)` under-reports the two process-killing
mutations is correct and worth carrying into the house recipe.
Gaps, all small and none blocking:
- no case covers the *guard* in `MGPipeApplyDeleteSamplerView` (clear the back-pointer **only if the texture
still names this view**) — a mutation that drops the condition survives, because the re-issue case re-issues
on the same handle;
- `TextureEmit.ATexturesParametersLandOnItsOwnRecordAndMoveOnlyTheirOwnSerial:296-299` says "a BUFFER of the
same slot is not a texture" without ever creating that buffer, so it proves the refusal but not the
non-aliasing (the real proof is in `ResourceEmit`, so this is a comment fix);
- C1's fix needs `TextureEmit.ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers`.
---
## Exact rework list
1. **C1** — scope `resource_respecify`'s pending-upload clear to the level the respecify redefines
(`PipeApply.cpp:1485`), via a trailing defaulted `const MGPRespecifiedLevel*` (null = whole resource) or the
integrator's chosen alternative; add
`TextureEmit.ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers` and its mutation, and narrow
`ARespecifyDropsThePendingUploadsAgainstTheStorageItReplaces` to the whole-resource arm. Rewrite deviation
W7 with the per-level frontend fact (`TextureObject.h:245,252`) instead of the current claim.
2. **m4** — in the same edit, make `MGPipeApplyResourceSubData` return `Bool` ("stored / accumulated"), and say
in `PipeApply.h` that B's dirty-flag clear is gated on it (D-D5 step 1). Announce both signature changes to
B, C, D, E in the v2 report's "what the others must know".
3. **m1** — either clear `DrawFramebuffer` / `ReadFramebuffer` and the three unit windows in
`MGPipeApplierReleaseObjectRecords` (`PipeApply.cpp:1117-1133`), or replace the comment's claim with the
reason they survive. Contract review `m2` is discharged either way, and the report must say which.
4. **m2** — delete "framebuffer" from `PipeApply.h:422-428`'s refusal list and state there, once, that
`set_framebuffer_state` resolves no record and can only ever fault.
5. **m3** — refuse `MGPSubData::Target == MGPipeResourceTarget::Renderbuffer` in the texture half, and pin the
upload-target value space (which numbers cube faces may use) in one sentence beside `MGPSubData`.
6. **m5** — make `MGPipeApplyUnmapPersistent`'s kind check a `Fatal{ProtocolCorruption}` like
`resource_destroy`'s, and note beside `flush_range` / `readback` / `map_persistent` that their records carry
no kind and are buffer-only by catalogue.
7. **n1/n3** — two sentences in `PipeApply.h`: the accumulated rect list may overlap across emissions (D's
staging must tolerate it), and a texture record's `BuiltinSampler` may name a CSO whose record is gone.
8. **H1** — not this package's. Report it to the integrator as written above (recommended: D-K2 gains
"bit 10 requires bit 11"), and keep the applier's Fatal exactly as it is.
Optional, and declared minors do not block: contract review `m1` (the tautological `static_assert` at
`MGPipeTypes.h:185-188`), still unclaimed.
@@ -0,0 +1,392 @@
# P4a package A — `wire`, adversarial review of rounds v2 + v3 (`wire-review-v2`)
Scope: the **eight** commits after the rebase point on `refs/heads/p4a/wire`
(`7b5b3957 fb709418 52a16a1e be0e032a 22a3e265` = v2, `aff381c7 282325d5 70e742a3` = v3), HEAD `70e742a3`,
against ID-8 / ID-12 / ID-15 / ID-17 / ID-18 M3+M4 / ID-19(b) / ID-21 / ID-22, `wire-review-v1.md`
(C1, m1-m5), `wire-v2.md`, `wire-v3.md`, `esprytobj-review-v1.md` (C-1), `clientfb-review-v1.md` (M3/M4),
`esprytdraw-v2.md` and c0e (**now integrated**: pipe = `e8502a61`, ID-25).
Read-only in `/home/swung/w7/p4a-wire`. Every experiment ran in a private detached worktree
`~/w7/p4a-review-wire2` at `70e742a3` (`build-push`, `-j 8`, `CCACHE_BASEDIR=/home/swung/w7`), which is
**removed** (`git worktree prune` run, log deleted, `p4a-wire` clean, its three build dirs untouched).
---
## Verdict
**ACCEPT WITH MAJORS** — one major, four minors, two nits. Nothing here blocks the merge: every line of
applier behaviour this round changed is correct on the code I read, and the three items the round was launched
for (C1's level scoping, ID-19(b)'s per-object table, ID-18 M3/M4) are implemented as specified and gated by
tests that I re-killed with mutations of my own. The major is a **package-boundary contract gap** — wire changed
what the stored `Target` byte MEANS and told nobody, and package E has a live consumer of it — plus the memo key
E must now use. Both are exactly the class of silent hand-off defect ID-19 exists to close, and neither is
visible to any gate P4a owns.
### What I re-measured rather than took on trust
| claim | result |
|---|---|
| `ctest -L unit` = 1680 in all three builds | **1680 / 1680 / 1680** (`ctest -N`, `LC_ALL=C`) |
| name sets `build-linux` == `build-push`, 2646 | **2646 == 2646, 0 differing lines** |
| applier suites = 130 | **130** |
| MU1 (Named arm moves the draw binding) | **rc 8, 1/74** — `FramebufferEmit.ANamedRecordDescribes…` |
| MU4 (metadata arm disarmed) | **rc 8, 1/74** — `TextureEmit.ARespecifyThatRedefinesNoStorage…` |
| MU8 (C1's per-level scoping disarmed) | **rc 8, 1/74** — `TextureEmit.ARespecifyOfOneLevelKeeps…` |
| baseline clean | **74/74, rc 0** |
| **MX3 (mine)** — stale-generation test disarmed (`record.Gen != fbo.Gen` → `false`) | **rc 8, 1/74** — `AFramebufferHandleWhoseGenerationHasMovedOn…` |
| **MX2 (mine)** — the `Level` half of the level-scoped erase key deleted | **rc 8, 1/74** — `ARespecifyOfOneLevelKeeps…` |
| **MX1 (mine)** — the `UploadTarget` half of the same key deleted | **rc 0, 74/74 — GREEN** (MINOR-1) |
`git diff -- MobileGL/MG_Pipe/generated` rc 0; `gen_pipe.py` contains **no** reference to `PipeApply.h`
(its only hit is the string it *emits*, `gen_pipe.py:672`), so §3's default-tail / acceptance-return
source-compatibility claim survives v3 intact. No `[[nodiscard]]`; the four P3a call sites
(`PipeFill.cpp:645, 678, 691, 705`) discard the `Bool` and compile.
---
## Findings
### MAJOR-1 — the stored record's `Target` byte silently changed meaning, and `wire-v3.md` §5's package-E section does not say so (the one consumer is `DirectGLES.cpp:2983`)
**Where.** `PipeApply.h:397-401` (`MGPipeFramebufferRecord`) + `:383-396` (its comment) + `:957-975`
(`MGPipeApplySetFramebufferState`'s contract) + `wire-v3.md` §5 "Package E".
Consumer: `/home/swung/w7/p4a-esprytdraw/MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:2982-2987`.
Before ID-19(b) the applier held **two records, one per binding**, so `record.Target` read out of the
read-binding record was a live statement about the current binding pair: `Target == Both` meant "the object on
the read binding is the same object the draw pass just synced". After ID-19(b) the table is **per object**
(`PipeApply.cpp:2207-2211`, the record is written at `FramebufferRecords[state.Fbo.Slot]` whatever the target
is), so the stored `Target` is a property of **the last emission that named that object, from any target
including `Named`** — not of the object and not of the bindings. c0e's own comment
(`MGPipeTypes.h:596-600`, "the draw-buffer array … reaches the driver's bound draw framebuffer only for a
record whose Target is Draw or Both") reads as an invitation to keep asking the binding question of the field.
E does exactly that:
```cpp
// DirectGLES.cpp:2982
if (target == FramebufferTarget::Read &&
record.Target == static_cast<Uint8>(MG_Pipe::MGPipeFramebufferTarget::Both)) {
backendObj->SyncReadBufferToBackend(currentFBO); // skip the draw pass's work
```
**Failure scenario.** FBO X is bound to both bindings, so its record says `Both`. A DSA call on X —
`glClearNamedFramebufferfv(X, …)`, `glBlitNamedFramebuffer(…, X, …)`, or any of the DSA attachment /
draw-buffer / read-buffer setters ID-19(c) puts a `Named` record in front of — overwrites the record at X's
slot with `Target = Named` (bindings untouched, which is correct). On the next draw the read pass no longer
matches `Both`, falls through to a full `SyncToBackend(currentFBO, Read)` and re-does the whole attachment and
draw-buffer walk the draw pass has just done, every frame that issues such a call. The wrong-direction case —
a stale `Both` on an object that is no longer bound to both, which would make the read pass **skip a
framebuffer that was never synced** — is the one that corrupts, and it is what the field-test shape now
permits in principle.
**Refutation I tried, and it holds for the corrupting direction only.** I read B v2's emitter
(`~/w7/p4a-clientfb/MobileGL/MG_Impl/Pipe/FramebufferEmit.h:219-260`): `EmitFramebufferState` walks **both**
bindings at every validate and rebuilds a `Both`/`Draw`/`Read` record from the current pair, suppressed on the
`(drawHash, readHash)` pair, and `Target` is a `ContentHash` input (`:193`). So any binding change re-emits
both records with the right `Target`, and the stale-`Both` corruption is **not reachable while B keeps that
shape**. What survives the refutation is (a) the `Named` false-negative above — cost, not corruption, but
per-frame cost on exactly the DSA traffic ID-19 added — and (b) that a correctness property now rests on an
undocumented emitter habit rather than on the applier's contract. Wire answers the binding question exactly
and cheaply — `BoundFramebuffer[Draw] == BoundFramebuffer[Read]` (ID-19(d)) — and `wire-v3.md` §5's E section
says only "a reference becomes a pointer", listing the seven `BoundFramebufferRecord` call sites and the
`SyncCurrentFBOByRecord` null test while omitting the one site that reads a field whose meaning moved.
Two further inaccuracies in the same §5-E section, found by reading E at `9b8441a6`: the quoted half-described
test `if (MGPipeHandleIsNull(st.DrawFramebuffer.Fbo) || …) return false;` **no longer exists** — E v2 replaced
it (ID-23 F2) with `drawUnrecorded`/`readUnrecorded` plus a loud one-sided branch at `DirectGLES.cpp:2865-2894`
— and the line reference `:2765` now points at `g_fboSyncedSerials`. The section is written against E v1.
**Fix (wire's half is two sentences).** In `PipeApply.h` beside `MGPipeFramebufferRecord`: *"`State.Target` is
the target of the LAST EMISSION that named this framebuffer, `Named` included; it is not a statement about the
object's current bindings. The binding question is `BoundFramebuffer[t] == fbo` (ID-19(d)) and nothing else."*
In `wire-v3.md` §5-E: add `DirectGLES.cpp:2983` to E's change list with that expression, and re-derive the
quoted shapes from E v2.
---
### MINOR-1 — the `UploadTarget` half of the level-scoped erase key is ungated: a mutation that deletes it is GREEN, and the case that claims to pin it does not
**Where.** `PipeApply.cpp:1646-1652` (the erase loop); `MG_Test/Pipe/TextureEmitTest.cpp:473-545`
(`ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers`), specifically `:503-511`.
The key is `(UploadTarget, Level)` and the code is right:
```cpp
// PipeApply.cpp:1648
if (it->UploadTarget != level->UploadTarget || it->Level != level->Level) continue;
```
The case's own comment at `:503-504` says the second face exists *"so that the level number alone cannot be
what matched"*. **It can.** I applied MX1 — delete the `UploadTarget` clause, leaving
`if (it->Level != level->Level) continue;` — rebuilt and ran the seven emit suites: **rc 0, 74/74**. The
symmetric mutation MX2 (delete the `Level` clause) is red. So exactly half of the key is gated.
**Why the case misses it.** Trace it: the second-face respecify at `:507` is fed `levelDesc(1, 0x8058u)`, which
is **byte-identical to the descriptor the previous respecify stored** — so it is classified metadata-only
(`RespecifyRedefinesNoStorage` true) and takes the third arm, erasing nothing at all, contrary to the comment.
The only real per-level erases in the case name `(kTex2D, 1)`, and `(kTex2D, 1)` is the only entry with
`Level == 1`, so the `Level` half alone decides both of them.
**Failure scenario the gate should hold.** A cube map: `glTexSubImage2D` on face 0 level 1 and on face 1 level 1
both pending behind Espryt's incomplete-texture bail, then `glTexImage2D(GL_TEXTURE_CUBE_MAP_POSITIVE_X, 1, …)`
redefines face 0 level 1 only. With a `Level`-only key the loop erases the **first** entry with `Level == 1`,
which is whichever face was accumulated first — face 1's texels are dropped for good (its client dirty flag was
cleared at its own emission, D-D5 step 1). That is C1's bug one axis over.
**Refutation I tried.** The shipped code has the full key, so this is a *test* gap and not a live defect. But
the level-scoped erase is the thing C1's whole rework exists to make right, MU8 is the round's own proof that
the arm is load-bearing, and half of its key has no mutation behind it — which is the condition under which a
later refactor of `AccumulatePendingUpload`'s keying would land green.
**Fix.** In the same case, make the second-face respecify a real redefinition (move one storage-defining field,
e.g. `levelDesc(1, 0x8051u)`) that names `{secondFace, 0}`, and assert `(kTex2D, 0)` survives while
`(secondFace, 0)` goes. Add it to the mutation table as MU10 = MX1.
---
### MINOR-2 — `FramebufferSerial` is one number for the whole family and a `Named` write moves it, so E's per-target memo is invalidated by DSA traffic on framebuffers that are not bound; the table has no per-record serial to key on instead
**Where.** `PipeApply.h:600-603` (`Uint64 FramebufferSerial`), `PipeApply.cpp:2229` (`++` on every applied
record, `Named` included); consumer `DirectGLES.cpp:2758-2765` (`SyncedFramebufferSerialMemo`, `serial`) and
`:2903` (`if (SyncedFramebufferSerialIsCurrent(target, st.FramebufferSerial)) continue;`).
Before ID-19(b) the serial moved only when a **bound** framebuffer was described, so a per-target memo keyed on
it was about as sharp as the four `g_fboSynced*` arrays it retires. Now every `Named` record — one ahead of
each `BlitNamedFramebuffer`, each of the four `ClearNamedFramebuffer*`, and each DSA attachment / draw-buffer /
read-buffer setter (ID-19(c)) — moves the same number, invalidating **both** targets' memos and forcing a full
attachment re-sync of the currently bound draw and read framebuffers on the next draw, for a write that touched
neither.
**Refutation.** Over-invalidation is always safe: the memo is stamped after the sync, so a spurious miss costs
a redundant `SyncToBackend`, never a wrong frame. And P4a is behaviour-neutral today (all four
`kMGPipeWired*Subsystem` are 0 on this tree), so nothing regresses now, and ID-6 records performance rather
than gating it. That is why this is a minor and not a major. It is still a real coarsening introduced by this
round, on the draw path, and the applier is the only place that can undo it.
**What E should key on, and what wire owes it.** The exact question is *"has the record describing the
framebuffer bound to target t changed, or has the binding changed"*. That is
`(BoundFramebuffer[t], <that record's own serial>)`. Wire supplies the first half and not the second:
`MGPipeFramebufferRecord` (`PipeApply.h:397-401`) carries `Gen`, `Live`, `State` and no serial. Three lines fix
it — a `Uint64 Serial` in the record, `++record->Serial` beside `PipeApply.cpp:2229`, and an accessor (or
simply returning the record struct rather than `&record.State` from a second entry point). Until then E's
honest key is `(BoundFramebuffer[t], st.FramebufferSerial)`, which at least stops a *binding* change being
missed but does not stop the over-invalidation.
---
### MINOR-3 — the `kMGPipeFramebufferTargetNamed` retirement recipe in `wire-v3.md` §7.2 is one site short, and c0e has already landed
**Where.** `wire-v3.md` §7 item 2 names "six readers": `PipeApply.cpp:2153`, `FramebufferEmitTest.cpp:276`,
`:443`, `:454`, and prose at `PipeApply.h:595` / `:965`. A full grep of the tree finds **nine** occurrences:
those six plus the declaration `PipeApply.h:173`, its `static_assert` `:174-176`, and **a ninth the recipe
misses — the prose mention at `PipeApply.cpp:2148`**.
This is now live rather than hypothetical: c0e is integrated (ID-25, pipe = `e8502a61`,
`MGPipeFramebufferTarget::Named = 3`, `Count` = 4), so the `static_assert` at `PipeApply.h:174` **fires on the
merged tree** and `PipeApply.h` is included by `Managers.cpp`, `DirectGLES.cpp`, `VulkanRenderer.h` and
fourteen test TUs — the whole tree fails to compile until the retirement lands. ID-24 already schedules that
edit ("the Named-constant retirement edit done by the integrator in the wire tree after its rebase,
unit-tested, one commit"), so the ordering is handled; only the recipe's completeness is not. The trip wire
itself is **well designed and I would keep it** — it is the reason the local constant cannot be forgotten.
**Refutation.** A prose mention left behind compiles fine, so the miss costs a stale comment, not a build. It
is a minor only because the recipe presents itself as exhaustive ("One constant, six sites, no behaviour
change") and the integrator is being asked to execute it verbatim under time pressure.
---
### MINOR-4 — `resource_create`'s reserved-slot refusal is the one refusal class with no observable at all in a shipped build, and the header's contract says there are only two
**Where.** `PipeApply.cpp:1524-1527` (`MOBILEGL_ASSERT` + `return false`); contract text `PipeApply.h:777-789`.
The header states the acceptance-return rationale as *"a dead or stale handle is a counted no-op and a corrupt
record is a `Fatal` that deliberately moves no counter"* — two classes. `resource_create` with
`Slot < kMGPipeFirstAllocatableSlot` is a third: `MOBILEGL_ASSERT` compiles out at INFO (which every gate build
and every shipped build is), nothing is counted, nothing is logged, and before M3 the call was a completely
silent drop. The other two create refusals (`:1533` no resource target, `:1550` slot past
`kMGPipeMaxResourceSlots`) are `MGP_TRIP_WIRE_REPORT` and therefore at least an `MGLOG_E`.
**Refutation.** M3 is precisely the cure: the emitter now sees `false` and must not advance its dedupe or clear
a level's flags, and `TextureEmit.TheCreateAndRespecifyCallsAnswerWhetherTheRecordWasAccepted` (`:757`) pins
it. So the hole M3 was written to close is closed. What remains is that the header's two-class taxonomy is
incomplete where it is used to justify the return — one clause, not a code change.
---
### NIT-1 — `kMGPipeMaxFramebufferSlots` is a unilateral bound with no counterpart in the allocator
`PipeApply.h:156` sets it at `1u << 16`; `MG_Impl/Pipe/SlotAllocator.h` has no per-kind ceiling for
`MGPipeKind::Framebuffer` (only the `ShaderCso` composite band is policed), so nothing on the client side
prevents a handle above the cap. The verdict on one is correct and **loud, not UB**:
`MGP_TRIP_WIRE_REPORT` → `abort()` under `MOBILEGL_PIPE_VERIFY`/`POISON`, `MGLOG_E` + return under push, with
nothing stored, no serial moved, and `AFramebufferRecordThatNamesNoUsableHandleIsRefusedRatherThanStored`
(`:528`) asserting the table did **not** resize. Unreachable in practice — the client frees a framebuffer's
slot at death (`PipeFill.cpp:1260-1261`, `NotifyAndFree(MGPipeKind::Framebuffer, …)`), so the high-water mark
tracks *peak live* FBOs, not lifetime creations, and 65 536 simultaneously live FBOs is not a thing. Identical
in shape to the `VertexElements` and `SamplerCso` bounds v1 accepted. Recorded so F can assert
`HighWater(Framebuffer) < kMGPipeMaxFramebufferSlots` if it wants a gate.
### NIT-2 — contract review `m1` (the tautological `static_assert`, `MGPipeTypes.h:185-188`) is still unclaimed
v2 declined it because c0c was in flight on that file; c0c, c0d and c0e have all landed since and it is still
there. Not wire's file; the integrator's to fold or drop.
---
## What I checked and found correct (so a later round does not re-derive it)
**C1's fix (dimension 1).** The three arms at `PipeApply.cpp:1640-1653` are ordered `metadataOnly` →
`level == nullptr` (whole-resource `PendingUploads.clear()`) → the keyed erase, and the precedence is right:
M4's rule *refines* C1's rather than contradicting it (a call that replaces no storage replaces no level's
coordinate system), and it is the arm that must win, because the mask republish B v2 will emit is exactly the
call that would otherwise eat texels standing behind Espryt's incomplete-texture bail. Both are pinned —
`ARespecifyThatRedefinesNoStorage…` (`TextureEmitTest.cpp:687`) drives the metadata arm **with a level pointer**
and carries its own negative control (move `Width`/`Height` and the same call drops the level), and MU4/MU8 are
red on the right cases. A cube-face respecify erases by the full packed key and leaves the other five faces
standing — correct in code, half-gated (MINOR-1). Keys are unique by `AccumulatePendingUpload`'s construction
(`:813-824` looks for the pair before appending), so `erase(it); break;` is right and no iterator survives it.
**The packed decode (dimension 1).** v2's local `SubDataResourceTargetOf` is gone; `PipeApply.cpp:1698` and
`:1711` go through `MGPipeSubDataResourceTargetOf` / `MGPipeSubDataUploadTargetOf`, `TextureEmitTest.cpp:505`
through `MGPipePackSubDataTarget`. A grep for `0x00FF` / `0xFF00` / `& 0xFF` / `>> 8` across
`PipeApply.{h,cpp}` and the two test files returns **one hit, and it is inside a comment** (`:520`).
`SubDataNamesABuffer` (`:512`) still matches the **whole** field, which is ID-12 as written and is what c0c's
own `static_assert` (`MGPipeTypes.h:962`) keeps exact. `MGPRespecifiedLevel::UploadTarget` is `Uint16` holding
the same packed value `PendingUpload::UploadTarget` stores verbatim — types line up, and the header
(`PipeApply.h:763-775`) states the pairing to B in as many words.
**ID-19(b) (dimension 2).** Table slot-indexed by the handle with the generation checked on lookup
(`PipeApply.cpp:2235-2264`); the three nulls are separated correctly and only the third is loud
(`++StaleFramebufferRecordLookups` + `MGLOG_E_ONCE`, counted **apart** from `RefusedObjectCalls`, `mutable` so
E keeps its `const auto&`); the accessors are defined in the `.cpp` so `MGLOG` stays out of the header's
include closure; `RecordAt` deliberately does **not** apply `kMGPipeFirstAllocatableSlot`, which is what lets
the reserved default framebuffer `{0,1}` be a real record at slot 0 while `MGPipeHandleIsNull` (`Slot == 0 &&
Gen == 0`, `MGPipeHandles.h:75`) still refuses `{0,0}` — both pinned as positive/negative controls at
`FramebufferEmitTest.cpp:528`. Draw/Read/Both set the bound handle(s) and `Named` sets neither
(`:2214-2221`, MU1 red). `Reset` clears `BoundFramebuffer` only and keeps the table (`:1183`, MU7); the
argument — a DSA-only framebuffer has no re-emission trigger, since `InvalidateAll` re-sends the two bound
records — is sound, and the slots come from one process-global allocator so nothing aliases across a switch.
`ReleaseObjectRecords` clears the table **and** the two bound handles **and** the three unit windows
(`:1211-1245`, m1 discharged by fixing, MU6). `ReadSurface` is stored verbatim under every target, which is
what c0e (ID-25) rules and what §5-B.1 tells B to fill.
**M3 (dimension 3).** `Bool` on `Create` (`:1524`) / `Respecify` (`:1576`) / `SubData` (`:1678`); every refusal
path returns `false` (create: reserved slot, null table, slot past the bound; respecify: null table, no live
record at that generation; subdata: the resource-target gate and `AccumulatePendingUpload`'s overflow), every
accepted path returns `true` including a metadata update and including an unregistered `MGPipeResourceOps`
(right: the op table is a property of the build, not of the record). `ResolveResourceIn` still moves
`RefusedResourceCalls` on the stale-generation path — asserted at `TextureEmitTest.cpp:775`.
**M4 (dimension 4), and W10 is now the contract's own ruling.** `RespecifyRedefinesNoStorage`
(`PipeApply.cpp:558-585`) compares field by field (not `memcmp` — `MGPResourceDesc` carries `Pad0`/`Pad1`) and
excludes exactly `BindMask`, `ImageBindableHint`, `GlNameForDiag` and the padding. ID-25 records c0e's ruling
as *"metadata = BindMask, ImageBindableHint, GlNameForDiag; **HasDefinedContent is storage-defining**"* — the
implementation matches the contract **exactly**, including the field ID-21's narrower list omitted. A metadata
respecify therefore cannot flip defined content: `HasDefinedContent` differing makes the call a redefinition.
I chased the one way that could have gone wrong — whether B's builder moves `HasDefinedContent` independently
of the storage fields, which would silently reclassify every mask republish as a redefinition — and it does
not: `TextureEmit.h:272-275` derives it from `mipmap->GetMipmapLevelCount() > 0`, in lockstep with
`desc.Levels` (`:261`), and `Immutable` from `texture.IsImmutable()` (`:268`); `Usage`/`StorageFlags` are never
written for a texture. A respecify that changes only `Levels`, or only `Samples`, is **not** metadata (both are
compared at `:568-570`), and the C1 case now feeds the level counts a real mip build produces so it exercises
the per-level arm rather than the metadata one. `MGPipeResourceRespecifyNeedsAck` is false by construction for
every metadata record because the buffer target is excluded outright (`:559`) — the right shape, since a
second suppression rule is one the transport would have to learn.
**m2 / m3 / m5 (dimension 5).** `RefusedObjectCalls`' comment (`PipeApply.h:507-535`) now names four families,
states positively that `set_framebuffer_state` resolves no record and can only fault, and — new in v3 — that
ID-19(b) does not change that, because the per-object table is written by that call and never looked up by it,
the lookup refusal being counted apart. Three test cases assert `RefusedObjectCalls == 0` across the family.
The `Renderbuffer` enumerator and everything `>= MGPipeResourceTarget::Count` are refused in the texture half
(`:1699-1712`) with **both** halves in the line. `unmap_persistent`'s kind check (`:1876-1882`) is
`Fatal{ProtocolCorruption}`, uncounted — the same verdict `resource_destroy` gives at `:1804-1810`, asked of a
narrower question (Buffer only vs any of the three kinds), which is right for a donation that is buffer-only.
**Exit order and hygiene (dimension 7).** `g_applier` is `MGPipeApplierState& g_applier = *new
MGPipeApplierState{};` (`PipeApply.cpp:396`) — the deliberate never-destroyed singleton P3a ID-18/21 asks for.
`FramebufferRecords` rides inside it and holds only PODs (`MGPFramebufferState`'s surfaces carry `MGPipeHandle`,
never a `SharedPtr`), so this round adds **no** new static holder of frontend `SharedPtr`s and no new
destructor reaching into pipe state. `MGLOG_E_ONCE` is used once, on a genuine seam defect — correct level, and
`MGLOG_D` would have been wrong there. `MGPipeApplierReleaseObjectRecords` still has no production caller
(tests only), as the header says.
**Integration lanes (dimension 6).** The nine mutations are honest — I re-ran three at random and all three
killed exactly the named case, and my two extra mutations behaved as the design predicts (MX2 red, MX3 red).
No DirectVulkan lane applies to this round: the seven emit suites are backend-agnostic unit tests, all four
`kMGPipeWired*Subsystem` are 0, `PipeApply.{h,cpp}` are push-only TUs, and G1 is 0/0/0/0 — the "leak test per
new kind on the DirectVulkan lane" that ID-8 requires belongs to the packages that mint (B and C), not here.
---
## The deviations, judged
| # | verdict |
|---|---|
| **W1–W6, W8** | **Stand.** v1's review accepted them and nothing in v2/v3 disturbed them. |
| **W7′** | **Superseded by W11's third arm, correctly.** The metadata arm precedes the scope arm and refines it; the scope argument is unchanged. |
| **W9** (`MGPipeApplyResourceSubData` returns `Bool`) | **Accept.** Source-compatible, `gen_pipe.py` re-verified as never parsing this header, no `[[nodiscard]]`, P3a's call sites unchanged. Extended cleanly to `Create`/`Respecify` in v3. |
| **W10** (a buffer is never metadata-only; the comparison is wider than ID-21's list) | **Accept, and it is no longer a deviation.** ID-25 records c0e ruling `HasDefinedContent` storage-defining and metadata = exactly the three fields wire excludes, so the implementation and the contract now agree field for field. Both reasons wire gives are right independently: the asymmetry argument (comparing too much costs one dropped upload on a call B does not emit; comparing too little uploads past the end of a new level) picks the safe direction, and excluding the buffer target is what makes "no reallocation ack" true by construction rather than by a second rule. I verified the claim the deviation rests on — that none of the extra fields moves on a mask republish — against B's actual builder (`TextureEmit.h:243-285`); it holds. |
| **W11** (identical storage fields clear nothing, whatever the level pointer says — and its sharp edge) | **Accept as written, and the sharp edge is benign in the direction that matters.** A per-level respecify whose descriptor does not move keeps the level it names. Wire calls this unreachable on B's memcmp dedupe; I add the stronger argument it did not make: even if B did emit one, nothing is lost — the descriptor is unchanged, so that level's coordinate system is unchanged, and the surviving box is re-uploaded from the client's **current** shadow, i.e. correct content over a possibly larger region. The failure W11 warns about would need a redefinition that moves no descriptor field at all, which `HasDefinedContent`, `Levels`, `Immutable` and the extent between them make impossible on B's builder. Honest, well-flagged, and the ten minutes of B-review it asks for is the right ask. |
---
## Rework list
Small, and none of it blocks the merge.
1. **MAJOR-1.** Add the two sentences to `PipeApply.h` beside `MGPipeFramebufferRecord` (`:397`): the stored
`State.Target` is the last emission's target, `Named` included, and is **not** a binding fact; the binding
question is `BoundFramebuffer[t] == fbo`. Amend `wire-v3.md` §5-E to list `DirectGLES.cpp:2983` with that
replacement expression, and re-derive its quoted E shapes from E v2 (`9b8441a6`) — the half-described test
it quotes no longer exists and `:2765` is now `g_fboSyncedSerials`.
2. **MINOR-1.** Make the second-face respecify in `TextureEmitTest.cpp:503-511` a real redefinition of
`{secondFace, 0}` and assert `(kTex2D, 0)` survives; add MX1 (delete the `UploadTarget` clause at
`PipeApply.cpp:1648`) to the mutation table as MU10 and show it red. Fix the comment at `:503-504`, which
currently claims a property the suite does not hold.
3. **MINOR-2.** Either add `Uint64 Serial` to `MGPipeFramebufferRecord` with `++` beside
`PipeApply.cpp:2229` and an accessor, so E can key per bound record — three lines, and it is the applier's
to give — or state in `PipeApply.h:600-603` that the family serial is deliberately coarse and that DSA
traffic on unbound framebuffers invalidates a bound target's memo, so E's verification round records the
cost rather than discovering it.
4. **MINOR-3.** Add `PipeApply.cpp:2148` to §7.2's retirement site list (nine occurrences, not six).
5. **MINOR-4.** One clause in `PipeApply.h:777-789`: the reserved-slot create refusal is neither counted nor a
Fatal, and the return is its only observable.
---
## The integrator's post-merge re-run list
1. **The full five-part gate of D.3** on the merged head, plus `symbol_report --threshold 0` (P4a's admitted
set is empty) and `p3a_untouched_regions.sh 37da3c3a HEAD`. Nothing in this review substitutes for it; what
I did re-measure on wire's own tree (unit 1680 × 3, names 2646 == 2646 with 0 differing lines, applier
suites 130, generated-dir diff rc 0) matches `wire-v3.md` §6 exactly.
2. **The Named-constant retirement is merge-blocking, not a later round.** c0e is integrated (`e8502a61`,
`Count` = 4), so the `static_assert` at `PipeApply.h:174` fires the moment wire is rebased, and
`PipeApply.h` is in the include closure of `Managers.cpp`, `DirectGLES.cpp`, `VulkanRenderer.h` and
fourteen test TUs — the tree does not compile until it is done. ID-24 already schedules it as one commit in
the wire tree; use the **nine**-site list from MINOR-3, not §7.2's six, and re-run the seven emit suites
(130) plus `-L unit` afterwards.
3. **After B v2 lands**, the three ten-minute reads `wire-v3.md` §7.3 names — all five DSA entry points plus
the DSA setters emit a `Named` record; the suppressor is per framebuffer and not one global slot (B v2 at
`8534abf7` is still **one** slot, `MGPipeSuppressorSlot::SetFramebufferState`, on the `(drawHash, readHash)`
pair — that is the shape §5-B.2 asks B to change); the mask republish moves **only** `BindMask` /
`ImageBindableHint`. Add a fourth: B must keep re-emitting **both** bound records at every validate — the
refutation of MAJOR-1's corrupting direction rests on it, so it is now a load-bearing property and should be
stated in B's own header rather than left as a habit.
4. **After D v2 lands**: `PushedFramebufferRecord` must lose its `asTarget` parameter and its
`record.Fbo == fbo` test (`~/w7/p4a-esprytobj/…/Managers.cpp:8216-8227` still has both) or C-1 is only half
fixed; D's teardown must not read a binding after `MGPipeApplierReleaseObjectRecords`.
5. **At E's verification round**: `DirectGLES.cpp:2983` becomes
`st.BoundFramebuffer[Draw] == st.BoundFramebuffer[Read]` (MAJOR-1); the seven `BoundFramebufferRecord` call
sites (`:2127, :2273, :2863, :2864, :2905, :4009, :4179`) take `const auto*` and null-check;
`FramebufferRecordMatchesBinding` and the one-sided loud branch at `:2865-2894` take pointers;
`StaleFramebufferRecordLookups` must read **0** on every scenario — a non-zero value is the seam defect
ID-19 was written to make visible, not traffic.
6. **D-K2's fourth row** ("bit 10 requires bit 11", ID-15's H1) is still owed by D and F; the applier's `Fatal`
on a null `BuiltinSampler` is unchanged and correct, and the `0x5ff` lane still aborts until that row exists.
7. **Docs**: the brief's D-C2 (record "per bound target") and D-J4 (framebuffer records as working state) are
both amended by ID-19(b) and by this round; D.5 should carry the correction beside c0e's.
8. **LFS**: `git lfs install --local` in each worktree would stop ID-13's trap recurring after every WSL
restart — `/usr/bin/git-lfs` exists but no worktree has `filter.lfs.smudge`, which is why wire restored 92
fixture blobs by copy this round.
@@ -0,0 +1,491 @@
# P4a package A — `w1`..`w4`, the applier bodies. Result, v1
Branch `refs/heads/p4a/wire`, worktree `/home/swung/w7/p4a-wire`, on top of the tag
`refs/tags/p4a/contract` = `08192d72`. **Four commits, two production files and seven test
files, +3147 / −49. Not pushed. Nothing else touched.**
| commit | message (single line, empty body, no attribution) |
|---|---|
| `86835b50` | `[Feat] (Pipe): apply the framebuffer record per bound target and the texture and renderbuffer resource calls into their own slot-indexed records` |
| `bc9abfbd` | `[Feat] (Pipe): apply sampler states, sampler views and the three unit sets into the server's own working state` |
| `0f990633` | `[Feat] (Pipe): apply the shader CSO's artefacts and the default uniform block without ever re-linking on the server` |
| `3c07c8c3` | `[Test] (Pipe): pin every P4a record's lifecycle, its bounds gate and what a make-current does and does not clear` |
```
MobileGL/MG_Pipe/PipeApply.cpp | 1016 ++++++++++++++++++--
MobileGL/MG_Pipe/PipeApply.h | 46 +-
MobileGL/MG_Test/Pipe/CompositeResolverTest.cpp | 237 +++++
MobileGL/MG_Test/Pipe/FramebufferEmitTest.cpp | 249 +++++
MobileGL/MG_Test/Pipe/ImageEmitTest.cpp | 248 +++++
MobileGL/MG_Test/Pipe/ProgramEmitTest.cpp | 397 ++++++++
MobileGL/MG_Test/Pipe/ResourceEmitTest.cpp | 148 +++
MobileGL/MG_Test/Pipe/SamplerEmitTest.cpp | 444 +++++++++
MobileGL/MG_Test/Pipe/TextureEmitTest.cpp | 411 ++++++++
```
**Behaviour neutrality holds and is structural.** Nothing in this package registers a consumer
of any record: the four subsystem bits are absent from `kMGPipeWiredSubsystems`, every client
emitter beside them is still a stub, `MGPipeResourceOps` is unchanged at nine members, and no
backend reads the new state. `grep` over `MobileGL/` for the fifteen entry points returns hits
only in `MG_Pipe/PipeApply.{h,cpp}` and in `MG_Test/Pipe/*EmitTest.cpp`. The pull build is
byte-identical to `$BASE`'s (G1 0/0/0/0).
---
## 1. Verdict on the hard rules (after `3c07c8c3`; re-run unchanged after every commit)
| rule | result |
|---|---|
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` | rc 0, **0 added / 0 removed / 0 renamed / 0 resized** after each of the four commits |
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 (7 controls tripped) |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | rc 0 |
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0, 27 negative controls, all tripped |
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all` | rc 0, 4 probes, 0 problems, 6 controls tripped |
| `p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, the eleven byte-identical |
| three builds compile (pull / push / verify) | all three, after every commit |
| `ctest -L unit` in all three | **1668 / 1668 in each**, 0 failed (1635 at the tag, +33) |
| ctest names pull == push | `diff` empty |
| no name removed vs `~/w7/p4a-before-ctest-names.txt` | empty; 46 added (the contract's 13 + this package's 33) |
| only A's files | yes — `MG_Pipe/PipeApply.{h,cpp}` and the seven `MG_Test/Pipe/*Test.cpp` C.7 gives A |
| four commits, exact messages, no attribution, not pushed, no other worktree | yes |
| `grep -rc 'pGLContext' MG_Backend` | only `MGPipe/PipeInputs.h:1`, pre-existing |
---
## 2. Per-entry-point behaviour: record, serial, bounds, refusal
The two verdicts are P3a's and the difference between them is the whole discipline:
* **a call naming a record this applier does not have is a DEFINED NO-OP that is COUNTED.**
One legal sequence produces it (teardown → `MGPipeApplierReleaseObjectRecords` → `~Object` →
death notices naming records already dropped), so it cannot be a wire; `MOBILEGL_ASSERT` is
inert at INFO, so it cannot be only an assertion. `RefusedResourceCalls` takes the resource
family (buffers, textures **and** renderbuffers — they are resource calls);
`RefusedObjectCalls` takes the five object families (framebuffer, sampler, sampler view,
program, texture params).
* **a record that would make the server index or allocate outside its own storage is
`Fatal{ProtocolCorruption}`** with the record's identity in the line, and it is **not**
counted as a refusal.
### 2.1 `set_framebuffer_state`
| | |
|---|---|
| storage | `DrawFramebuffer` / `ReadFramebuffer`, working state. `Target != Read` writes the draw record, `Target != Draw` writes the read record, so `Both` writes both. |
| serial | `FramebufferSerial`, one for the pair, `++` once per applied record (**a `Both` record is one record and bumps once**). |
| bounds | `Target >= MGPipeFramebufferTarget::Count` → Fatal. Every `DrawBuffers[i]` outside `[-1, kMGPipeMaxColorAttachments)` → Fatal (an index into the record's own `Color[]`). |
| refusal | **none, ever.** A framebuffer has a handle but no wire lifetime (D-I2), so there is no record to resolve; and the surfaces' `Res` handles are deliberately **not** resolved, because an attachment pins its texture through the frontend's own `SharedPtr` in monolith and a refusal here would enforce a lifetime rule monolith cannot need (D-I3). This entry point never touches `RefusedObjectCalls`. |
### 2.2 `resource_create` / `resource_respecify` / `resource_subdata` / `resource_destroy`
The four P3a entry points now **branch on the descriptor's `Target`** (on the handle's `Kind`
for the destroy, which carries no descriptor). The three tables are `Resources`,
`TextureResources`, `RenderbufferResources`; the record **type** is shared and the bound
(`kMGPipeMaxResourceSlots`) is shared, only the table is per kind.
| | |
|---|---|
| table selection | `Target == Buffer` → `Resources`; `Target == Renderbuffer` → `RenderbufferResources`; every other enumerator below `Count` → `TextureResources`; `>= Count` → Fatal. Destroy: `Kind` ∈ {Buffer, Texture, Renderbuffer}, anything else → Fatal. |
| create | starts the record over, `Gen` from the handle, `Live = true`, `Serial` stays **0**. Dispatches to `MGPipeResourceOps::Create` **only for a buffer**. |
| respecify | replaces `Desc` whole, `++Serial`, **clears `PendingUploads`** (§2.4), dispatches **only for a buffer**. |
| destroy | drops the record whole, keeps `Gen`, dispatches **only for a buffer** (the op table is the buffer family's). |
| bounds | `slot >= kMGPipeMaxResourceSlots` → Fatal naming the bound; the table is never grown by a corrupt slot. |
| refusal | `RefusedResourceCalls`, through `ResolveResourceIn`. |
### 2.3 `set_texture_params`
| | |
|---|---|
| storage | `MGPipeResourceRecord::Params` on the **texture** record, addressed by resource and independent of any binding. |
| serial | `ParamsSerial`, `++` per applied call. `Serial` (the storage serial) does **not** move — a parameter push is not a storage mutation. |
| bounds | `params.BuiltinSampler == kMGPipeNullHandle` → **Fatal** (§5, hazard H1). |
| not checked | the CSO the record names is **not resolved**: the sampler bit may legitimately be clear while the texture bit is set, so an unresolvable `BuiltinSampler` is an ordering fact, not a corrupt one. |
| refusal | `RefusedObjectCalls`. |
### 2.4 The sub-data validator, per target
`SubDataBoxFault` was **split in two** rather than widened; every statement it made is a
statement about the buffer convention and every one of them is false for a texture.
**Buffer half (`Target == kMGPipeResourceTargetBuffer`, unchanged from P3a):** offset above
`0x7FFFFFFF` → Fatal; `Level != 0` → Fatal; `RegionCount != 0` → Fatal; `Blob.Size != 0 &&
Blob.Size != MGPipeSubDataBufferSize(record)` → Fatal; then `BufferRangeFault` against
`Desc.Width`; then a non-empty write with `bytes == nullptr` → Fatal. Dispatches to
`MGPipeResourceOps::SubData` / `SubDataResident`.
**Texture half (every other `Target`):**
| rule | verdict |
|---|---|
| `Level >= kMGPipeMaxTextureLevels` (32) | Fatal |
| the union box has a negative origin, or `origin + extent > 0x7FFFFFFF` on any axis | Fatal |
| `RegionCount > kMGPipeMaxPendingUploadRegions` (256) | Fatal |
| `RegionCount != 0 && regions == nullptr` | Fatal |
| a region with a negative origin or an unencodable extent | Fatal |
| **a region not inside the union box** | Fatal |
| an empty box **and** zero regions ("no texels at all") | Fatal |
| `bytes == nullptr` | Fatal |
| more distinct `(UploadTarget, Level)` keys than `kMGPipeMaxPendingUploads` (256) | Fatal |
The region-containment rule is the one that matters: the union box **is** the union of the
regions, the server picks the upload shape from the pair, so a region outside the box means the
box misses its texels and the region writes where the box never said it would.
**Deliberately NOT checked, so a later reader does not add them back as an oversight:** (a) the
level against `Desc.Levels` — a mutable texture defines its levels one `glTexImage2D` at a
time, so the descriptor's level count is not an upper bound at every instant and a gate on it
would refuse a legal upload; (b) the box against the descriptor's extents — the record
addresses the **level's** coordinate system and a view remaps that space, so the arithmetic is
the storage owner's; (c) the blob — **no field of a texture record describes its own byte
length**, so the one Blob rule has nothing to cross-check and is inert here by construction.
**Pending-upload accumulation (D-D5).** Keyed `(UploadTarget, Level)` on the texture's record.
Boxes union; rect lists concatenate; and the moment either side says "box only", or the list
would outgrow `kMGPipeMaxPendingUploadRegions`, the entry becomes **box only** — never a
dropped region, because the box still covers every texel the dropped list named. That is the
frontend's own model one level up (`MipmapStorage` answers "0 rects" for everything it cannot
describe that way). An entry is never created empty, which is why an empty `Regions` after the
first contribution unambiguously means box-only. `++Serial` on acceptance, and the acceptance
is what the client reads before clearing its own dirty flag.
### 2.5 `create_sampler_state` / `delete_sampler_state`
| | |
|---|---|
| storage | `SamplerCsos[slot]`, `Params` by value **including `borderColorForm`**. |
| serial | a **fresh or recycled identity** starts over with `Serial = 0` (a create is not a mutation, and a fresh twin starting at 0 agrees without either side publishing); a **re-issue on a live identity** keeps the record and `++Serial`. |
| bounds | `Parameters.Size != 0 && != sizeof(SamplerParameters)` → Fatal; `parameters == nullptr` → Fatal; `slot >= kMGPipeMaxSamplerCsoSlots` → Fatal. |
| delete | drops the record whole, keeps `Gen`. **Does not sweep `BoundSamplerStates`** — that window is "the last set as received" and the client re-emits it at the next verb. |
| refusal | `RefusedObjectCalls`. |
### 2.6 `create_sampler_view` / `delete_sampler_view`
| | |
|---|---|
| storage | `SamplerViewCsos[slot]`, `View` verbatim, plus **the texture's `ViewCso` back-pointer**. |
| serial | the same fresh-vs-re-issue rule as the sampler CSO. A re-issue **does not rebind** anything. |
| bounds | `slot >= kMGPipeMaxSamplerViewSlots` → Fatal. `View.Target`, `MinLevel`/`NumLevels`/`MinLayer`/`NumLayers` are **not policed** (`MGPVertexBuffer::BindingIndex`'s precedent: the applier cannot justify that contract). |
| back-pointer | written through a **silent** `FindIn` (no refusal counted) — a view arriving before or without its texture record is legal in a mixed-bit lane. The delete clears it **only if the texture still names this view**. |
| refusal | `RefusedObjectCalls` on the delete. |
### 2.7 The three `kVarTail` unit sets
One shared body (`ApplyUnitWindow`), because they differ only in what an entry is.
| | |
|---|---|
| bounds | `Start + Count > 192` → **Fatal** (`kMGPipeMaxTextureUnits` for the two sampler sets, `kMGPipeMaxImageUnits` for the images; the two constants are equal and a case pins that). `Count != 0 && tail == nullptr` → Fatal. |
| storage | entries land at `Start + i` and **nowhere else**; `Start`/`Count` stored; **entries outside the window are not cleared** — the record is "the last set as received", and a set that names four units has said nothing about the other 188. |
| serials | `SamplerViewsSerial` / `SamplerStatesSerial` / `ShaderImagesSerial`, `++` per applied set, independently. |
| refusal | **none** — a set is working state and resolves no record. A **null handle in any tail entry is legal** everywhere (a unit the program does not resolve, a unit with no sampler object, an unbound unit) and the entry's own `Unit` field is deliberately unpoliced: the destination is `Start + i`, which the window already bounds. |
| empty set | applied, not refused, and it still moves the serial — a program with no images publishes one. |
### 2.8 `create_shader_state`, the two bindings, `bind_shader_state`, `set_global_constants`
| | |
|---|---|
| table | `MGPipeIsCompositeShaderSlot(slot)` routes to `CompositeShaderCsos[slot − base]`, bounded by the band's width; every other slot to `ShaderCsos[slot]`, bounded by **the band's base** (an ordinary program can never be handed a band slot, so a non-composite slot at or above the base is out of range by definition). A slot at or above `kMGPipeShaderCsoSlotLimit` → Fatal naming `kMGPipeMaxShaderCsoSlots`. **The server never learns a handle is a composite**; the split is two functions and nothing else branches on it. |
| create | fresh/recycled → record starts over, `Serial = 0`; re-issue on a live identity → `++Serial` **and the default uniform block is dropped** (image cleared, version back to the `~0u` sentinel, `++GlobalConstantsSerial`), because a relink replaces the layout the block was sized to. `Desc` stored; the artefacts are **not** stored (in monolith the backend reads the frontend's own archive). |
| create bounds | `link == nullptr || spirv == nullptr` → Fatal ("declares no blobs and carries no artefacts"); `GlobalUboSize > kMGPipeMaxGlobalConstantsBytes` (16 MiB) → Fatal. |
| bind / draw / dispatch | one `ProgramBindingSerial` for the three, `++` per applied call. A **null** handle is legal in all three and means "nothing bound" (and still bumps); a **dead** handle leaves the previous binding untouched and is counted. |
| delete | drops the record whole, keeps `Gen`, and **clears every one of the three bindings that named it** (unlike the unit sets: these are single handles resolved against the record just dropped), bumping `ProgramBindingSerial` only if one was actually cleared. The **second** delete — a composite's other release path — is a counted refusal and moves nothing. |
| `set_global_constants` | on the **program's** record. `Version == ~0u` → Fatal (the backends' never-uploaded sentinel); `Blob.Size != 0 && != Desc.GlobalUboSize` → Fatal; `GlobalUboSize != 0 && bytes == nullptr` → Fatal. Stores `GlobalUboSize` bytes, sets `GlobalConstantsVersion`, `++GlobalConstantsSerial`. `Serial` does not move — a block upload is not a relink. The allocation is bounded **at the create**, so this call can only ever allocate what the create already declared. |
### 2.9 `MGPipeApplierReset` / `MGPipeApplierReleaseObjectRecords`
Unchanged from the contract commit and re-pinned by four cases: the reset clears the two
framebuffer records, the three unit sets and the three program handles and **advances** all five
P4a serials; it does **not** touch texture/renderbuffer resources, sampler CSOs, sampler views
or shader CSOs — nor the `Params`, `ParamsSerial`, `ViewCso` and `PendingUploads` that ride on a
resource record. `ReleaseObjectRecords` is the only teardown scope and advances the serials
again for the same reason.
---
## 3. The verify-only codec round trip (D-H3)
`PipeApply.cpp` includes `<MG_State/GLState/ProgramState/ProgramArtifactsCodec.h>` **inside
`#if MOBILEGL_PIPE_VERIFY`** — the only place the codec is called, and the coupling the
contract header already anticipated ("the verify build is the only place the codec runs, and it
runs from `PipeApply.cpp`"). `PipeApply.h` keeps its two forward declarations and reaches no
frontend header; the include-closure gate's four probes are unaffected (none of them names
`PipeApply.*`).
`PinProgramArchiveRoundTrip(desc, link, spirv)` runs **before the record is stored**, so a lane
that aborts aborts on the record that was wrong:
1. `EncodeProgramArtifacts(link, spirv, encoded)` — empty output for a program that has
artefacts is a fault;
2. `DecodeProgramArtifacts(...)` returning false is a fault;
3. re-encoding the decoded pair and comparing the bytes — a mismatch is a fault (the codec's own
suite reads the members back explicitly; what this adds is that it runs over **every real
program the verify lane links** rather than over one hand-built instance);
4. `decodedLink.program != nullptr` is a fault — the live glslang `TProgram` is the one member
the tables omit, and a decode that reconstructed one would be carrying the compiler front end
across the boundary that exists to keep it on the client side.
The verdict is `MGP_TRIP_WIRE_REPORT` with `MGP_TRIP_WIRE_TAG("PipeVerifyDiffer")`, so a verify
or poison build writes `Fatal{PipeVerifyDiffer} program-archive create_shader_state {slot=…,
gen=…}: …` and aborts — the marker G4 greps the retrace logs for. **Zero cost in push and
pull**: the include, the function and the call site are all inside the verify guard.
Mutation **M41** (making the decode fail) is what proves the pin is live code rather than a
comment.
---
## 4. Deviations, each with its reason
**W1 — `MGPipeApplyResourceSubData` gained a trailing defaulted parameter,
`const MGPSubRegion* regions = nullptr`.** The contract's signature has no tail parameter, and
D-D5 is unimplementable without one: `ResourceSubData` has carried `kVarTail` since P2, the
applier's pending-upload set is `(UnionBox, RegionCount, Regions[])`, and the verify lane's
retain mode compares all three. The parameter is **trailing and defaulted**, so P3a's one call
site (`MG_Impl/Pipe/PipeFill.cpp:705`), every existing case and every other package compile
unchanged. **Package B must pass the tail** when it emits a texture upload; a record that
declares `RegionCount != 0` and passes no tail is refused. This is the only signature change in
the package.
**W2 — four new bounds constants in `PipeApply.h`.** `kMGPipeMaxTextureLevels = 32`,
`kMGPipeMaxPendingUploads = 256`, `kMGPipeMaxPendingUploadRegions = 256`,
`kMGPipeMaxGlobalConstantsBytes = 16 MiB`. Every one of them is a number that arrives inside a
payload and decides how much the applier allocates or how far it indexes; the slot bounds' own
argument ("never allocated by being named; a slot at or above the bound is
`Fatal{ProtocolCorruption}` and never a resize") applies to each unchanged. They are additive
and inside A's own file.
**W3 — `resource_destroy` dispatches to the backend only for a buffer**, and the same is true
of `resource_create` and `resource_respecify`. D-B1 says every non-buffer target "stores and
returns"; the destroy's guard was missing in the first draft of `w1` and
`ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` found it. The fix is
folded into `86835b50` where it belongs (the branch was rewritten before anything was pushed,
so the four-commit shape and the four exact messages are intact).
**W4 — `set_framebuffer_state` counts no refusal.** The contract's header text lists
"framebuffer" among the families `RefusedObjectCalls` covers. It cannot: D-I2 gives the
framebuffer a handle and no wire lifetime, so this call resolves no record and there is nothing
to refuse. Its only verdict is `Fatal{ProtocolCorruption}` on a malformed record. Recorded here
rather than by weakening D-I3 into a surface-handle refusal, which the brief forbids in as many
words.
**W5 — the P4a records' create/re-issue serial rule differs from
`create_vertex_elements`'s, deliberately.** P3a's vertex-elements record bumps
`ContentSerial` on *every* create including the first ("Serial 0 means never created"). The
three P4a record types follow the **contract header's** rule instead: a fresh or recycled
identity leaves `Serial` at 0 so a fresh backend twin agrees without either side publishing, and
only a re-issue on a live identity counts up. Both statements are in the tree; this package
implements the one written on the P4a records.
**W6 — a re-issued `create_shader_state` clears the default uniform block.** Not stated by the
brief either way. A relink replaces the block's layout, so an image sized to the old one is a
hazard for the consumer and the `~0u` sentinel is exactly the value that says "nothing has been
uploaded for this program". `++GlobalConstantsSerial` announces the clearing so a twin cannot
match what it uploaded before the relink.
**W7 — a respecify clears the record's `PendingUploads`.** Not stated by the brief. The pending
entries are boxes and rects in the coordinate system of a level the respecify has just
redefined; keeping one across a shrink would have Espryt upload past the end of the new store,
and nothing is lost because the frontend entry points that respecify a texture re-mark the
levels they define (`AllocateStorage` then `MarkStorageDirty`).
**W8 — `~/w7/p4a-trees2.log` never contained `REBUILT wire`, and is empty.** The rebuild
nevertheless happened and finished: `~/w7/p4a-wire-submodule.log` (11:24:24) and
`~/w7/p4a-wire-build-{linux,push,verify}-build.log` (11:24:48 / 11:25:12 / 11:25:34) each end on
the last link of a complete build (980, 991, 991 targets), no builder was still running, and a
no-op `cmake --build` over all three returned rc 0 before any edit was made. The package
proceeded on that evidence. **The summary line the orchestration script was to append is the
thing that is missing, not the work** — worth knowing before the next package waits on it.
Those four logs were deleted with the round's own (ID-5); the timestamps and byte counts above
are the record.
---
## 5. What B, C, D, E and F must know
**H1 — `MGPTextureParams::BuiltinSampler` may never be null, and bit 10 can be set while bit 11
is clear.** The contract makes a null built-in sampler `Fatal{ProtocolCorruption}` and this
package implements it. But D-K2's dependency table has **no** "bit 10 requires bit 11", and
says the mirror pair is fine — so a `MOBILEGL_PIPE_PUSH=0x5ff` lane (texture resources on,
samplers off) would emit `set_texture_params` while the sampler CSO family is switched off. If
B/C mint the built-in sampler's handle only from the sampler emitter, that lane aborts on the
first `glTexParameter`. **Either** the handle is minted whenever the texture family emits
(the allocator, not the CSO cache, is what mints it), **or** the integrator adds "bit 10
requires bit 11" to D-K2. This is the one cross-package hazard the package found and cannot fix
from inside `MG_Pipe`.
**Blob size rules, exactly.**
| record | rule |
|---|---|
| `MGPSubData` (buffer) | `Blob.Size` is 0, or exactly `MGPipeSubDataBufferSize(record)`. Anything else is Fatal. |
| `MGPSubData` (texture) | **inert.** No field describes the blob's byte length, so any value is accepted; the destination is bounded by the box and the regions. Leave it 0. |
| `MGPSamplerDesc::Parameters` | 0, or exactly `sizeof(SamplerParameters)` (100). Anything else is Fatal. The value itself travels through the companion pointer, which may never be null. |
| `MGPProgramDesc::Spirv[6]` + `Reflection` | **inert**, all seven. Nothing in the descriptor describes their lengths. Leave them 0 and pass the two artefact pointers; **both** non-null or the record is Fatal. |
| `MGPGlobalConstants::Blob` | 0, or exactly the program's `Desc.GlobalUboSize` as the create declared it. Anything else is Fatal. |
**Unit-set window semantics, exactly.** `Start + Count <= 192` or Fatal. Entries land at
`Start + i`; **entries outside the window are never cleared**, so an emitter that wants a unit
unbound must include it in the window carrying a null handle. `Count == 0` is legal and still
moves the serial. A null handle in any entry is legal. The entry's own `Unit` field is stored
verbatim and never compared against `Start + i` — if the emitter lets the two disagree, nothing
here will say so.
**Serial semantics for D and E.** All five P4a working serials (`FramebufferSerial`,
`SamplerViewsSerial`, `SamplerStatesSerial`, `ShaderImagesSerial`, `ProgramBindingSerial`) are
`MGGen`-class: they **only ever advance**, including across `MGPipeApplierReset` and
`MGPipeApplierReleaseObjectRecords`, so no value can ever recur and a twin may safely memoise
one. The per-record serials (`Serial`, `ParamsSerial`, `GlobalConstantsSerial`) restart with the
record, which is safe because the handle's `Gen` moves with it. **Every serial moves before
anything downstream is told.**
**What D reads, per kind.** `TextureResources[slot]` / `RenderbufferResources[slot]` for the
descriptor, the parameters (`Params` + `ParamsSerial`), the view handle (`ViewCso`) and the
pending uploads; `SamplerCsos[slot].Params`; `SamplerViewCsos[slot].View`;
`ShaderCsos[slot]` **or** `CompositeShaderCsos[slot − kMGPipeShaderCsoCompositeSlotBase]` — a
consumer that resolves a `ShaderCso` handle must use the same band split the applier does, and
`MGPipeIsCompositeShaderSlot` is the one predicate for it. **Espryt consumes and clears a
`PendingUploads` entry only where it actually uploads**; a bail must leave it intact, which is
the whole point of the set being server-side.
**For F.** The package adds **33** ctest names — `ResourceEmit.` +3, `FramebufferEmit.` +4,
`TextureEmit.` +6, `SamplerEmit.` +7, `ImageEmit.` +4, `ProgramEmit.` +6,
`CompositeResolver.` +3 — for 46 added against `~/w7/p4a-before-ctest-names.txt` in total (the
contract's 13 plus these 33). None is removed and every one of them is a visible SKIP in a pull
build, so `ctest -N` stays name-for-name identical between the pull and push trees.
The six suites' `main()` points `MOBILEGL_LOG_FILE_PATH` at a per-pid temp file, because the
refusal cases read the trip wire's line back out of it.
---
## 6. Verification transcript (on `3c07c8c3`, working tree clean)
```
$ 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
### Removed (0) _none_ ### Added (0) _none_
### Resized (0) _none_ ### Renamed only (same size) (0) _none_ rc=0
$ python3 scripts/gen_pipe.py --check
gen_pipe: inventory 477 rows: ... 0 UNMAPPED
gen_pipe: generated files are up to date rc=0
$ python3 scripts/gen_pipe.py --self-test
gen_pipe: self-test: 7 negative-control trip(s), positive control OK rc=0
$ git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --check rc=0
$ python3 scripts/gen_pipe_dirty_surface.py --self-test
dirty-surface self-test: 27 negative controls, all tripped rc=0
$ python3 scripts/check_include_closure.py --mode both --compiler clang++ \
--self-test --require-all
include-closure: self-test: 6 negative-control trip(s), parser checks OK
include-closure: 4 probes, 0 skipped, 0 problem(s) rc=0
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD
[p3a-untouched] the 11 ... functions are byte-identical rc=0
$ cmake --build build-linux -j 12 ok
$ cmake --build build-push -j 12 ok
$ cmake --build build-verify -j 12 ok
$ ctest --test-dir build-linux -L unit -j 12 100% 1668/1668, 0 failed
$ ctest --test-dir build-push -L unit -j 12 100% 1668/1668, 0 failed
$ ctest --test-dir build-verify -L unit -j 12 100% 1668/1668, 0 failed
$ diff <(build-linux names) <(build-push names) (empty)
$ comm -23 ~/w7/p4a-before-ctest-names.txt <(build-linux names) (empty)
$ comm -13 ~/w7/p4a-before-ctest-names.txt <(build-linux names) 46 added
$ grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$'
MobileGL/MG_Backend/MGPipe/PipeInputs.h:1 # pre-existing, unchanged
```
Two failures were found during the round and both were the gates doing their job:
`ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` (deviation W3, a real
defect in `w1`'s first draft) and one flake of `LogLevel.ProductionBuildKeepsErrorAndWarn` under
`-j 12` (green on re-run and on every subsequent full run; a pre-existing shared-temp-file race
in a suite this package does not touch).
---
## 7. Mutation evidence
**41 mutations, 41 red, measured.** Each was applied to `MobileGL/MG_Pipe/PipeApply.cpp` in
this worktree, the tree rebuilt, the family's suite run, and the file restored from the commit
(the working tree was verified clean before and after; no other worktree was created). The rule
the brief asks for — *for each entry point a case that fails if its body is deleted* — is
therefore measured rather than claimed.
| # | mutation | first case to go red |
|---|---|---|
| M1 | `set_framebuffer_state`: the draw store removed | `FramebufferEmit.ADrawRecordAndAReadRecordAreKeptApartAndBothWritesBoth` |
| M2 | `set_framebuffer_state`: the read store removed | the same |
| M3 | `set_framebuffer_state`: the serial bump removed | the same |
| M4 | `set_framebuffer_state`: the target gate removed | `FramebufferEmit.ATargetOutsideTheThreeBindingsIsRefusedNamingTheRecord` |
| M5 | `set_framebuffer_state`: the draw-buffer gate removed | `FramebufferEmit.ADrawBufferEntryOutsideTheRecordsOwnArrayIsRefusedRatherThanRead` |
| M6 | `resource_create`: every target routed to the buffer table | `ResourceEmit.TheThreeResourceKindsKeepTheirOwnSlotSpaceAndDoNotSeeEachOther` |
| M7 | `resource_destroy`: every kind routed to the buffer table | the same |
| M8 | `resource_destroy`: the texture dispatch guard removed | `ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` |
| M9 | `set_texture_params`: the store removed | `TextureEmit.ATexturesParametersLandOnItsOwnRecordAndMoveOnlyTheirOwnSerial` |
| M10 | `set_texture_params`: the serial bump removed | the same |
| M11 | `set_texture_params`: the null-sampler gate removed | `TextureEmit.ARecordWithNoBuiltinSamplerCsoIsRefusedNamingTheTexture` |
| M12 | `set_texture_params`: the resolver replaced by a silent find (the refusal stops being counted) | `TextureEmit.ATexturesParametersLandOnItsOwnRecordAndMoveOnlyTheirOwnSerial` |
| M13 | sub-data: the region-containment gate removed | `TextureEmit.TheSubDataValidatorRefusesALevelABoxAndARegionTheRecordCannotDescribe` |
| M14 | sub-data: the level bound removed | the same |
| M15 | sub-data: the encodable-box gate removed | the same |
| M16 | sub-data: the missing-tail gate removed | the same (**SegFault**, §7.1) |
| M17 | pending uploads: the box union removed | `TextureEmit.AnAccumulatedUploadUnionsItsBoxesAndCollapsesToTheBoxWhenARectListCannotDescribeIt` |
| M18 | pending uploads: the box-only collapse removed | the same |
| M19 | pending uploads: the accumulation removed | the same |
| M20 | respecify: the pending-upload clear removed | `TextureEmit.ARespecifyDropsThePendingUploadsAgainstTheStorageItReplaces` |
| M21 | `create_sampler_state`: the parameter store removed | `SamplerEmit.ACreateStoresTheParametersByValueAndAReissueOnALiveIdentityCountsUp` |
| M22 | `create_sampler_state`: the re-issue serial bump removed | the same |
| M23 | `create_sampler_state`: the blob-length gate removed | `SamplerEmit.ARecordThatDoesNotDescribeItsOwnParametersIsRefusedNamingTheLength` |
| M24 | `delete_sampler_state`: the record drop removed | `SamplerEmit.ADeleteDropsTheRecordAndAStaleNoticeIsCountedRatherThanSilentlyDropped` |
| M25 | `create_sampler_view`: the back-pointer write removed | `SamplerEmit.AViewIsReissuedOnTheSameHandleAndKeepsItsTexturesBackPointerInStep` |
| M26 | `delete_sampler_view`: the back-pointer clear removed | the same |
| M27 | the unit sets: the entry copy loop removed | `SamplerEmit.TheTwoUnitSetsLandInTheirWindowAndLeaveEverythingOutsideItAlone` |
| M28 | the unit sets: the window gate removed | `SamplerEmit.AUnitWindowPastTheMergedUnitSpaceIsRefusedRatherThanTruncated` |
| M29 | `set_sampler_views`: the serial bump removed | `SamplerEmit.TheTwoUnitSetsLandInTheirWindowAndLeaveEverythingOutsideItAlone` |
| M30 | `set_shader_images`: the serial bump removed | `ImageEmit.TheImageSetLandsInItsWindowWithEveryFieldTheShaderWasBuiltAgainst` |
| M31 | `create_shader_state`: the descriptor store removed | `ProgramEmit.ACreateStoresTheDescriptorAndARelinkCountsUpAndDropsTheBlockKeyedToTheOldLayout` |
| M32 | `create_shader_state`: the relink block clear removed | the same |
| M33 | `create_shader_state`: the artefact gate removed | `ProgramEmit.ACreateWithNoArtefactsAnOversizedBlockOrACorruptSlotIsRefusedNamingTheProgram` |
| M34 | `bind_shader_state`: the store removed | `ProgramEmit.TheThreeBindingsFollowTheirOwnHandleAndADeadOneLeavesThePreviousBindingStanding` |
| M35 | `set_draw_program`: the store removed | the same |
| M36 | `set_dispatch_program`: the store removed | the same |
| M37 | `delete_shader_state`: the binding sweep removed | `ProgramEmit.ADeleteDropsTheRecordAndClearsEveryBindingThatNamedIt` |
| M38 | `set_global_constants`: the image store removed | `ProgramEmit.ACreateStoresTheDescriptorAndARelinkCountsUpAndDropsTheBlockKeyedToTheOldLayout` |
| M39 | `set_global_constants`: the sentinel gate removed | `ProgramEmit.TheDefaultUniformBlockLandsOnTheProgramsRecordAndTheSentinelIsRefused` |
| M40 | the composite band routed into the ordinary table | `CompositeResolver.ACompositeRecordLandsInTheBandsOwnTableAndNeverGrowsTheOrdinaryOne` |
| M41 | **verify build**: the archive decode made to fail | three `ProgramEmit.*` cases, `Subprocess aborted` |
M1-M40 ran in `build-push`; **M41 ran in `build-verify`**, and it is the one that proves the
codec round trip is live code with a gate rather than a comment: with the decode failing, every
`ProgramEmit` case that creates a shader state dies on `Fatal{PipeVerifyDiffer}`.
### 7.1 A note on reading a mutation harness
Two of the forty-one (M16 and M41) kill the test **process** rather than failing an assertion —
M16 dereferences the tail it no longer refuses, M41 aborts inside the verify trip wire — so
`ctest` reports `***Exception: SegFault` and `Subprocess aborted` instead of `(Failed)`. A
harness that greps for `(Failed)` reads both as SURVIVED. They were re-run with the exit code as
the verdict (`rc=8` in both cases) and are red. **Worth knowing for anyone repeating this:
grepping ctest output for `(Failed)` silently under-reports exactly the mutations that matter
most.**
---
## 8. Left undone, and who owns it
- **Every emitter body** and the four `kMGPipeWired*Subsystem` constants — B and C, in their own
headers. Nothing consumes a record until they land.
- **`CompositeResolver.h`** — still not created; wholly C's. This package's
`CompositeResolverTest` cases are the applier's half of the band and are disjoint from C's.
- **`Resolve<Family>SubsystemArm()`**, D-C3's `MaxColorAttachments > 8` refusal, and the D-K2
dependency refusals — backend-side, package D. **H1 above is an input to that work.**
- **The five `MGPipeUnmigratedEmulation` call sites** — D and E.
- **`p4a_untouched_regions.sh`**, `p4a_descriptor_negative_control.sh`, the itest phase-mask
moves and `MagmaPipeArms.h` — package F.
- **The retain-mode comparison of the emitted `(UnionBox, RegionCount, Regions[])`** against the
tracker's pre-clear set (part of G4): the applier's half exists — the pending set is
accumulated and never recomputed — and the tracker's half is the client packages'.
@@ -0,0 +1,348 @@
# P4a package A — `wire`, rework round. Result, v2
Rework of `wire-review-v1` (verdict REWORK: **C1** plus minors **m1**–**m5**), accepted by the integrator as
**ID-15**. Worktree `/home/swung/w7/p4a-wire`, branch `refs/heads/p4a/wire`, **not pushed**.
## 0. Rebase
`p4a/wire` was rebased onto `refs/heads/feat/disaggregated` = **`2cb44039`** (c0 `08192d72` + c0b
`32033d69`/`2cb44039`). **No `c0c` had landed** on `feat/disaggregated` or on `refs/heads/p4a/contract` when this
round started (both were at `2cb44039`), so the base is c0 + c0b and `MGPipeSubDataUploadTargetOf` /
`MGPipeSubDataResourceTargetOf` / `MGPipePackSubDataTarget` are **not available** — see m3 for what this package
did instead and what c0c retires.
The rebase was **clean, four commits, no conflicts** (c0b's `PipeFill.{h,cpp}`, `PipeMutation.h`,
`SlotAllocator.*` do not overlap `PipeApply.{h,cpp}`, which is wire's after the tag). The four v1 commits are now:
| v1 | after rebase | message (unchanged) |
|---|---|---|
| `86835b50` | `686ad38c` | `[Feat] (Pipe): apply the framebuffer record per bound target and the texture and renderbuffer resource calls into their own slot-indexed records` |
| `bc9abfbd` | `e5038c3d` | `[Feat] (Pipe): apply sampler states, sampler views and the three unit sets into the server's own working state` |
| `0f990633` | `59bceb4c` | `[Feat] (Pipe): apply the shader CSO's artefacts and the default uniform block without ever re-linking on the server` |
| `3c07c8c3` | `529cb262` | `[Test] (Pipe): pin every P4a record's lifecycle, its bounds gate and what a make-current does and does not clear` |
## 1. The five new commits
**HEAD = `6f263284`.** Only `MG_Pipe/PipeApply.{h,cpp}` and three `MG_Test/Pipe/*EmitTest.cpp` are touched;
no other file in the tree moved, and nothing outside package A's own C.7 set was opened.
| # | hash | items | message |
|---|---|---|---|
| 1 | `3c5b2d01` | **C1**, **m4**, **m3** (+ n1) | `[Fix] (Pipe): scope a respecify's pending-upload clear to the level it redefines, answer the emitter whether a sub-data record was accepted, and refuse a resource target that names no texture` |
| 2 | `026d2c48` | **m1** | `[Fix] (Pipe): release the framebuffer records and the three unit windows with the object records whose handles they hold` |
| 3 | `9f75fbbb` | **m5** | `[Fix] (Pipe): give unmap_persistent's kind check the verdict resource_destroy's has, and say why the other three buffer-only calls have nothing to check` |
| 4 | `aaad9691` | **m2**, **n3** | `[Docs] (Pipe): correct the refusal counter's family list - set_framebuffer_state resolves no record and can only fault - and warn that a texture's built-in sampler handle may outlive its CSO` |
| 5 | `6f263284` | the four new cases + the narrowing | `[Test] (Pipe): pin a respecify's per-level scope, the sub-data acceptance signal, the upload targets that name no texture and what a release of the object records clears` |
The three concerns folded into commit 1 all live on the same call path (the respecify's clear, the sub-data
dispatcher and the sub-data return type share hunks in both files); n1's sentence is adjacent to C1's in
`PipeApply.h` and rides with it. Everything else is one item per commit.
---
## 2. Review item by review item
### C1 — the respecify's pending-upload clear is now scoped to the level it redefines
**Fixed exactly as the review specifies**, with the trailing defaulted pointer.
- `PipeApply.h:641-653` — new `struct MGPRespecifiedLevel { Uint16 UploadTarget, Level; }`. It is an
**applier-side argument, not a wire record**: not in `PipeFields.def`, no payload, no `MGP_ASSERT_POD`. Its
`UploadTarget` is `MGPSubData::Target` **verbatim** — the whole packed field — because that is what
`MGPipeResourceRecord::PendingUpload::UploadTarget` holds (`AccumulatePendingUpload` stores `record.Target`),
so the two keys are the same value or they match nothing. This is stated at the declaration.
- `PipeApply.h:655-680` — `MGPipeApplyResourceRespecify(const MGPResourceDesc&, const void*, const
MGPRespecifiedLevel* level = nullptr)`. Trailing and defaulted, M2/W1's shape: `gen_pipe.py` never parses this
header, the generated wire path calls no `MGPipeApply*`, `PipeCalls.def` is untouched, and P3a's one call site
(`MG_Impl/Pipe/PipeFill.cpp:691`) plus every existing case compile unchanged. **`git diff -- MobileGL/MG_Pipe/generated`
is empty and `gen_pipe.py --check` is rc 0**, so the wire path did not move.
- `PipeApply.cpp:1510-1511` (signature), `1531-1562` (the argued clear). `nullptr` → clear all, exactly as
before, for `glBufferData` / `glBufferStorage` / `glTexStorage*` / a texture view. Non-null → erase the single
matching `(UploadTarget, Level)` and keep the rest; the keys are unique by `AccumulatePendingUpload`'s
construction, so it erases at most one entry and stops.
- `PipeApply.h:241-247` — the pending set's own comment now says the keys are independent and why.
**Deviation W7 is withdrawn and replaced** — see §3.
**The case.** `TextureEmit.ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers`
(`MG_Test/Pipe/TextureEmitTest.cpp:473`) drives the canonical sequence the review names: define level 0, accept
its upload, add a second **cube face** of level 0 (keyed the packed way, `(1 << 8) | Tex2D`, so that the level
number alone cannot be what matched), then respecify level 1 — and asserts **both** level-0 entries survive with
their boxes intact. It then proves the other half: the key the respecify **does** name is dropped.
`TextureEmit.ARespecifyDropsThePendingUploadsAgainstTheStorageItReplaces` (`:445`) is **narrowed to the
whole-resource arm it actually proves** — it now accumulates two levels and passes a null scope, and its comment
says so and points at its twin.
**The mutation** (§4, MU1): restoring the old code — the unconditional `PendingUploads.clear()` — makes exactly
that case fail, and nothing else.
### m4 — the acceptance signal (implemented, not declared)
`MGPipeApplyResourceSubData` now returns `Bool`.
- `PipeApply.h:692-709` — the contract: **true** when the record was stored (the buffer half landed its range,
or the texture half accumulated the shape), **false** when it was refused, and the paragraph says in as many
words that B's dirty-flag clear is gated on it (D-D5 step 1) and why neither refusal path is otherwise visible
(a dead handle is a counted no-op; a corrupt record is a Fatal that deliberately moves **no** counter).
- `PipeApply.cpp:811` `ApplyBufferWrite` and `:863` `ApplyTextureUpload` both return `Bool`; `:1579`
`MGPipeApplyResourceSubData` forwards it.
- **An unregistered or partial op table still returns true** (`PipeApply.cpp:839-843`, argued there): whether a
backend registered `MGPipeResourceOps`, and whether it implements the optional resident hook, is a property of
the **build**, not of the record. An emitter that read "not accepted" off an unregistered table would re-send
a write the applier has already taken responsibility for.
- `MGPipeApplyBufferSubDataResident` keeps its `void` return — it is not on D-D5's dirty-flag path and no
package asked for it.
Case: `TextureEmit.TheSubDataCallAnswersWhetherTheRecordWasAcceptedSoTheClientCanClearItsFlag`
(`TextureEmitTest.cpp:531`) — an accepted texture upload answers true, a **stale generation** (the refusal that
is *not* a Fatal, so the only one the return can carry) answers false and moves `RefusedResourceCalls`, and the
buffer half answers on the same terms with no backend table registered. Mutation MU2.
### m3 — the texture half no longer accepts a resource target that names no texture
`PipeApply.cpp:1591-1608`. After the buffer branch, the record's **resource-target half** must name a texture:
`Buffer`, `Renderbuffer` and anything at or above `MGPipeResourceTarget::Count` are
`Fatal{ProtocolCorruption}` — *"the record's resource target names no texture to upload into
(target=%u, resource target=%u)"* — rather than an accumulation onto whatever texture holds that slot. It is the
mirror of `ResourceTableForTarget`'s null-on-unknown and its argument, and it is a Fatal and not a counted
refusal for the reason `resource_destroy`'s dispatch Fatal is.
**The value-space pin, and where it went.** ID-12 rules `MGPSubData::Target` **packed** (low byte
`MGPipeResourceTarget`, high byte `TextureUploadTarget`) and says wire matches the field verbatim, which the
buffer test still does (`SubDataNamesABuffer`, `PipeApply.cpp:511-513`, whole field `== 0`). The new gate needs
the low byte, so `PipeApply.cpp:515-530` carries `SubDataResourceTargetOf` — **the local decode, with the
encoding written out beside it**, because c0c is not on this base. It is one function to retire the day c0c
lands; §5 says so. **The sentence beside `MGPSubData` in `MGPipeTypes.h` is DECLARED, not written**: that file
is the contract's and c0c is in flight on exactly it (it mints the three pack/unpack helpers, which *are* the
value-space pin). Writing a comment there would collide with c0c for no gain. The pin therefore lives at
`PipeApply.h:700-707` and `PipeApply.cpp:515-530`, both of which name ID-12.
A side effect worth naming: the gate also closes the hole DV-3 opened at the *other* end — a record with the
low byte `Buffer` and a non-zero upload-target half used to fall through the whole-field buffer test into
`TextureResources`. It is now refused.
Case: `TextureEmit.ASubDataRecordWhoseResourceTargetNamesNoTextureIsRefusedRatherThanRouted`
(`TextureEmitTest.cpp:580`) — all three arms (Renderbuffer, `Count`, packed-Buffer), each naming the refusal,
each proving nothing was accumulated, no serial moved and `RefusedObjectCalls`/`RefusedResourceCalls` did not
move. Mutation MU3.
### m1 — `MGPipeApplierReleaseObjectRecords` now releases everything that names an object record
`PipeApply.cpp:1160-1180`. It clears `DrawFramebuffer`, `ReadFramebuffer` and all three unit windows
(`BoundSamplerViews`/`Start`/`Count`, `BoundSamplerStates`/…, `BoundShaderImages`/…) alongside the three
program handles it already cleared. The argument is written there: a window left standing after the tables are
emptied is a set of handles into empty tables, which the next resolve either refuses and counts (a teardown-time
refusal storm nothing asked for) or — on a slot the next context re-mints — resolves onto somebody else's
record. **Contract review m2 is discharged by fixing, not by declaring.**
Case: `FramebufferEmit.AReleaseOfTheObjectRecordsAlsoClearsTheWorkingHandlesThatCouldNameThem`
(`FramebufferEmitTest.cpp:348`) — a framebuffer record whose `Color[0].Res` names a texture, plus one entry in
each of the three sets at a non-zero `Start`, then the release, then eleven assertions. Mutation MU4.
### m2 — the header no longer promises a framebuffer refusal
`PipeApply.h:445-465`. "framebuffer" is out of `RefusedObjectCalls`' family list (now four families, "one
counter rather than four"), and a paragraph states positively that `set_framebuffer_state` **resolves no
record** (D-I2: a handle and no wire lifetime), that `MGPSurface::Res` is deliberately left unresolved (D-I3),
that its only verdict is `Fatal{ProtocolCorruption}` on a malformed record, and that **the counter must stay at
0 across every framebuffer call in every build**. That last sentence is the assertable form of W4, in the file
`MG_Test`, D and E read.
### m5 — `unmap_persistent`'s kind check is a Fatal
`PipeApply.cpp:1762-1780`. `MOBILEGL_ASSERT` is replaced by `Fatal{ProtocolCorruption}` — *"the persistent
donation is the buffer family's and the handle names another kind (%u)"* — with the reason written out: the
assert compiles out at INFO, which is what all three gate builds and every shipped build are, so a mistyped
record used to walk into `ResolveResource` and alias whatever **buffer** holds that slot. No counter moves; it
is the corrupt-record verdict, exactly as `resource_destroy`'s.
`PipeApply.cpp:1618-1626` carries the note the review asks for beside the other three: `resource_flush_range`,
`resource_readback` and `map_persistent` are buffer-only **by catalogue and not by check** — `MGPFlushRange` and
`MGPReadback` carry no kind at all and `map_persistent`'s `MGPHandleOnly` is not asked for one — so there is
nothing there to compare, and if a later phase gives one of them a kind the gate belongs beside that field.
Case: `ResourceEmit.AResourceTargetOrKindTheCatalogueDoesNotNameIsRefusedRatherThanRouted`
(`ResourceEmitTest.cpp:1423-1434`) gains the arm, with a **live buffer at the same slot** so the aliasing it
prevents is actually reachable. Mutation MU5.
### n1, n3 — the two sentences
- **n1**: `PipeApply.h:248-255`, beside `PendingUpload` — the accumulated rect list **may overlap across
emissions** (the lists concatenate and the gate only checks containment in the union box), so D's N-rect
staging uploads those texels twice; that is a cost, never a correctness problem, and nothing downstream may
read "the frontend's model" as "disjoint" once the shapes have been accumulated.
- **n3**: `PipeApply.h:216-223`, beside `Params` — a texture record's `BuiltinSampler` **may name a CSO whose
record is gone** (`set_texture_params` deliberately does not resolve it; `delete_sampler_state` does not sweep
the textures that name it), so a consumer must treat it as it treats any stale handle.
### n2, n4 — declared, not taken
- **n2** (`RegionCount == 1` with an all-zero region passes the "no texels at all" test and creates an entry
describing nothing): **not taken**, deliberately. The record is legal by every rule the applier owns — the
region is inside the box and the box is encodable — and the only way to refuse it is a rule about region
*content*, which is the storage owner's arithmetic (the "deliberately NOT checked" list's item (b)). It costs
one empty staging job on a shape no emitter produces. Left as the review left it: a nit.
- **n4** (contract review m1, the tautological `static_assert` at `MGPipeTypes.h:185-188`): **not claimed.**
`MGPipeTypes.h` is the contract's file and **c0c is in flight on it**; a one-line deletion from this branch
would conflict with c0c for no behavioural gain. It stays unclaimed and is the integrator's to fold into c0c
or to drop.
### H1 — not this package's, and the applier is unchanged
ID-15 rules it: **D-K2 gains a fourth row, "bit 10 requires bit 11"**, refused at the contract dependency rule,
with package D's mirror in the texture family's `Resolve*SubsystemArm` and package F's `0x5ff`-shaped
dependency-refusal scenario. Client-side minting is rejected. **This package changed nothing**: the null
`BuiltinSampler` is still `Fatal{ProtocolCorruption}` and
`TextureEmit.ARecordWithNoBuiltinSamplerCsoIsRefusedNamingTheTexture` still pins it.
---
## 3. Deviations after the rework
W1, W2, W3, W4, W5, W6 and W8 stand exactly as v1 recorded them and as the review accepted them. **W7 is
withdrawn** — it was C1 — and is replaced by:
**W7' — a respecify's pending-upload clear is scoped by a trailing defaulted `const MGPRespecifiedLevel*`, and
the applier's second signature change.** Null means whole-resource and clears everything (`glBufferData`,
`glBufferStorage`, `glTexStorage*`, a texture view); non-null names one `(uploadTarget, level)` and clears only
that. The frontend fact is the opposite of v1's claim: `AllocateStorage` and `MarkStorageDirty`
(`MG_State/GLState/TextureState/TextureObject.h:245,252`) are **per `(uploadTarget, level)`**, so a
`glTexImage2D(level = 1)` re-marks level 1 and nothing else, and every other level's dirty flag was cleared at
its own emission — a blanket clear loses those texels with no counter, no log line and no gate that can see it.
**W9 — `MGPipeApplyResourceSubData` returns `Bool` instead of `void`.** m4, implemented rather than declared.
Source-compatible (P3a's call site at `PipeFill.cpp:705` discards it), and the answer is D-D5 step 1's
"accepted".
---
## 4. Mutation evidence for this round
Five mutations, five red, measured in `build-push` at HEAD, each applied to
`MobileGL/MG_Pipe/PipeApply.cpp`, the tree rebuilt, the family's suite run, the file restored from the commit.
**The verdict is `ctest`'s exit code**, not a grep for `(Failed)` — v1's §7.1 lesson.
| # | mutation | verdict |
|---|---|---|
| MU1 | **C1 restored to the old code**: `if (level == nullptr)` → `if (true)`, i.e. the unconditional `PendingUploads.clear()` | `rc=8`, 1/10 failed — `TextureEmit.ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers` and only it |
| MU2 | **m4**: `ApplyTextureUpload`'s refused-resolve returns `true` | `rc=8`, 1/10 — `TextureEmit.TheSubDataCallAnswersWhetherTheRecordWasAcceptedSoTheClientCanClearItsFlag` |
| MU3 | **m3**: the resource-target gate disarmed | `rc=8`, 1/10 — `TextureEmit.ASubDataRecordWhoseResourceTargetNamesNoTextureIsRefusedRatherThanRouted` |
| MU4 | **m1**: the eleven working-handle clears deleted from `MGPipeApplierReleaseObjectRecords` | `rc=8`, 1/6 — `FramebufferEmit.AReleaseOfTheObjectRecordsAlsoClearsTheWorkingHandlesThatCouldNameThem` |
| MU5 | **m5**: `unmap_persistent`'s kind Fatal disarmed | `rc=8`, 1/29 — `ResourceEmit.AResourceTargetOrKindTheCatalogueDoesNotNameIsRefusedRatherThanRouted` |
MU1 is the review's requirement stated exactly: the new case is red on the old code and green on the new. Each
mutation kills **one** case, which is also evidence the four new cases are not duplicating an existing one.
After the sweep the tree was restored, rebuilt and re-run: `git status --porcelain` empty, 1673/1673.
---
## 5. What B, C, D, E and F must know (delta on v1's §5)
1. **`MGPipeApplyResourceRespecify` has a third parameter.** `const MGPRespecifiedLevel* level = nullptr`.
**Package B must pass it at every per-level respecify** — every `glTexImage{1,2,3}D` on a mutable texture, and
the generated-mip storage grow at `GL_Texture.cpp:528-539` — with `UploadTarget` set to **the same packed
`MGPSubData::Target` value that level's sub-data emission uses** and `Level` to the level index. It has both
halves in hand at the `AllocateStorage` call site. Passing `nullptr` (or the wrong pair) does not fail
loudly — it silently returns to C1's behaviour for that call, so this is the one line of B's texture path a
reviewer should read twice. `glTexStorage*`, `glBufferData`, `glBufferStorage` and texture views pass
`nullptr`, which is the default, so B's immutable paths and every P3a buffer path need no edit.
2. **`MGPipeApplyResourceSubData` returns `Bool`.** B's drain must clear the level's
`m_isDirty`/`m_dirtyRects`/`m_dirtyRegions` **only when it is true** (D-D5 step 1). Discarding it compiles.
3. **A texture sub-data record's resource-target half is now policed.** `Buffer` (with a non-zero upload-target
half), `Renderbuffer` and anything `>= MGPipeResourceTarget::Count` are Fatal. B's packing must put the
**resource** target in the low byte, per ID-12.
4. **`MGPipeApplierReleaseObjectRecords` now clears the framebuffer records and the three unit windows.** D and
E must not read this function as "the object records go and the bindings stay"; after it, nothing is bound.
5. **`unmap_persistent` on a non-buffer kind is Fatal.** D's death paths must not route another kind's retire
through it.
6. **`RefusedObjectCalls` covers four families, not five.** `set_framebuffer_state` can only ever Fatal; a
framebuffer call that moved this counter would be a defect. F may assert it stays 0 across the framebuffer
family.
7. **The accumulated rect list may contain overlaps** (n1). D's staging must tolerate duplicate texels.
8. **A texture record's `BuiltinSampler` may name a dead CSO** (n3).
9. **`SubDataResourceTargetOf` (`PipeApply.cpp:515-530`) is a local decode that c0c retires.** When c0c lands
`MGPipeSubDataResourceTargetOf` in `MGPipeTypes.h`, this one function forwards to it or goes away; the
applier's behaviour does not change either way.
---
## 6. Gate transcript (HEAD `6f263284`, working tree clean)
Run in `/home/swung/w7/p4a-wire` with `CCACHE_BASEDIR=/home/swung/w7`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0`, `--parallel 8` / `-j 8`.
```
build-linux / build-push / build-verify rc=0 / rc=0 / rc=0
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
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (0) rc=0
ctest --test-dir build-linux -L unit 100% passed, 0 failed out of 1673 rc=0
ctest --test-dir build-push -L unit 100% passed, 0 failed out of 1673 rc=0
ctest --test-dir build-verify -L unit 100% passed, 0 failed out of 1673 rc=0
ctest --test-dir build-push -R 'ResourceEmit\.|FramebufferEmit\.|TextureEmit\.|
SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.|HandleRecycle'
100% passed, 0 failed out of 125 rc=0
bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD
the 11 pool / deferred-release / ring / flush-drain functions are
byte-identical between 37da3c3a and HEAD rc=0
python3 scripts/check_include_closure.py --mode both --compiler clang++
--self-test --require-all
4 probes, 0 skipped, 0 problem(s); self-test 6 negative-control trips rc=0
python3 scripts/gen_pipe.py --check rc=0
python3 scripts/gen_pipe.py --self-test 7 negative-control trips rc=0
python3 scripts/gen_pipe_dirty_surface.py --check rc=0
python3 scripts/gen_pipe_dirty_surface.py --self-test 27 negative controls rc=0
git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
```
**ctest name sets** (`LC_ALL=C` sort, `ctest -N`):
```
build-linux vs build-push identical, 0 differing lines (G2)
vs ~/w7/p4a-before-ctest-names.txt 0 removed, 51 added
```
51 = the contract's 13 + wire v1's 33 + c0b's 1 + **this round's 4**. Every new case is a visible SKIP in a pull
build, so the pull and push name sets stay identical name for name. The four:
| suite | case |
|---|---|
| `TextureEmit` | `ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers` |
| `TextureEmit` | `TheSubDataCallAnswersWhetherTheRecordWasAcceptedSoTheClientCanClearItsFlag` |
| `TextureEmit` | `ASubDataRecordWhoseResourceTargetNamesNoTextureIsRefusedRatherThanRouted` |
| `FramebufferEmit` | `AReleaseOfTheObjectRecordsAlsoClearsTheWorkingHandlesThatCouldNameThem` |
Unit count moved 1668 (v1's base, c0 only) → **1673**: c0b's one test plus these four.
**Not run this round, and why**: the integration/verify/retrace/APK lanes and the device arms. This package is
behaviour-neutral (all four `kMGPipeWired*Subsystem` are still 0, nothing consumes a P4a record on this tree),
G1 is 0/0/0/0, and the review confirmed structurally that `PipeApply.{h,cpp}` are push-only translation units so
the pull build cannot move. The `git lfs checkout` of ID-13 was therefore not needed either — no retrace ran.
---
## 7. What the integrator must re-run on the integrated tree
1. **The full five-part gate of D.3**, unchanged — nothing here is a substitute for it.
2. **`symbol_report --threshold 0` after the merge** (P4a's admitted set is EMPTY, so 0/0/0/0 again), and
`p3a_untouched_regions.sh 37da3c3a HEAD` on the merged head.
3. **When c0c lands**: re-run `check_include_closure.py` and the unit lanes, and decide whether
`SubDataResourceTargetOf` (`PipeApply.cpp:515-530`) forwards to `MGPipeSubDataResourceTargetOf` or is
deleted. Behaviour does not change either way; this is hygiene, and it is one function.
4. **After package B lands**: the seam that C1 exposed is now B's to hold up — a per-level respecify that
forgets its `MGPRespecifiedLevel*` is silently the old bug. Worth a targeted read of B's `AllocateStorage`
emission path, and worth checking that B gates its dirty-flag clear on the new `Bool`. Neither is visible to
any gate P4a has; both are visible to a reviewer in ten lines.
5. **After D lands**: `MGPipeApplierReleaseObjectRecords` now clears the bindings as well as the records —
check D's teardown path does not read a binding after it.
6. **D-K2's fourth row** (ID-15's H1 ruling) is still owed by the contract and by D/F. The applier's Fatal on a
null `BuiltinSampler` is unchanged and correct; the `0x5ff` lane still aborts until that row exists.
7. **The brief's D-J3** still lists five refusal families including framebuffer; the header no longer does.
ID-15/D.5 amends the brief.
@@ -0,0 +1,409 @@
# P4a package A — `wire`, round v3. Result
The round ID-21 launched: rebase onto c0c, retire v2's local packed-target decode, **ID-19(b)** (the per-object
framebuffer table), **ID-18 M3** (acceptance returns on create and respecify) and **ID-18 M4** (the metadata
respecify). Worktree `/home/swung/w7/p4a-wire`, branch `refs/heads/p4a/wire`, **not pushed**.
**HEAD = `70e742a3`**, three new commits on top of the nine rebased ones. Only
`MobileGL/MG_Pipe/PipeApply.{h,cpp}` and two `MG_Test/Pipe/*EmitTest.cpp` are touched; nothing outside package
A's own C.7 set was opened.
---
## 0. Rebase onto `refs/heads/feat/disaggregated` = `17db7598` (c0 + c0b + **c0c**)
Clean, nine commits, **no conflicts** (c0c touches `MGPipeTypes.h`, `PipeFields.def` and
`PipeCatalogueTest.cpp`; wire owns `PipeApply.{h,cpp}` and three of the emit test files). The mapping:
| v2 | after rebase | |
|---|---|---|
| `86835b50`/`686ad38c` | `395cb841` | w1: the framebuffer + resource records |
| `bc9abfbd`/`e5038c3d` | `ed635ea5` | w2: samplers, views, unit sets |
| `0f990633`/`59bceb4c` | `0ce08d03` | w3: shader CSOs, the default uniform block |
| `3c07c8c3`/`529cb262` | `b2a53c90` | v1's test commit |
| `3c5b2d01` | `7b5b3957` | C1 + m4 + m3 |
| `026d2c48` | `fb709418` | m1 |
| `9f75fbbb` | `52a16a1e` | m5 |
| `aaad9691` | `be0e032a` | m2 + n1 + n3 |
| `6f263284` | `22a3e265` | v2's test commit |
**LFS note (ID-13).** The 92 `tools/trace_replay/fixtures/*` blobs were 132-byte POINTERS in this tree *before*
this round (mtime 12:24, the WSL restart), and `git lfs checkout` fails here — `/usr/bin/git-lfs` exists but the
repo has no `filter.lfs.smudge` configured. They are `assume-unchanged` (`git ls-files -v` → `h`), so I restored
all 92 by copying from `~/w7/base` and the working tree stayed clean (`git status --porcelain` empty,
0 pointers left). No retrace ran this round and none was needed — see §6.
## 1. The three new commits
| # | hash | items | message |
|---|---|---|---|
| 1 | `aff381c7` | **ID-19(b)** | `[Feat] (Pipe): key the framebuffer record by the framebuffer handle and resolve the two bindings through it, so a framebuffer that is named but bound to neither can still be described` |
| 2 | `282325d5` | **c0c retirement**, **ID-18 M3**, **ID-18 M4** | `[Fix] (Pipe): read a sub-data record's target halves through the contract's own accessors, answer the emitter whether a create or a respecify was accepted, and apply a respecify that restates the stored storage as a metadata update rather than a redefinition` |
| 3 | `70e742a3` | the five new cases | `[Test] (Pipe): pin what a Named framebuffer record does and does not move, the stale-generation refusal on the per-object table, the two handles it will not store, and that a respecify which redefines no storage carries the mask without eating the texels` |
`aff381c7` was verified independently (build rc 0, the seven emit suites 69/69) before `282325d5` was applied, so
the history bisects. The three items in commit 2 are one commit because they share hunks: the decode retirement
and the metadata predicate are adjacent blocks in the same anonymous namespace, and the acceptance return and the
metadata arm are the same two function bodies.
---
## 2. Item by item
### (1) c0c's accessors — v2's local decode is gone
- **`PipeApply.cpp:515-524`** — v2's `SubDataResourceTargetOf` (the local `& 0x00FF`) is **deleted**. The comment
that replaces it says the encoding is the contract's, names the three helpers, and states that nothing in this
file open-codes a half any more.
- **`PipeApply.cpp:1698`** — the m3 gate now reads `MGPipeSubDataResourceTargetOf(record.Target)` and compares
`Uint8` against `Uint8`.
- **`PipeApply.cpp:1701-1710`** — the refusal line gained the **upload half**, through
`MGPipeSubDataUploadTargetOf`: *"the record's resource target names no texture to upload into (target=%u,
resource target=%u, upload target=%u)"*. A reader no longer has to do the arithmetic the encoding exists to
stop anyone doing by hand, and the second half is what says whether an emitter packed the pair the wrong way
round. The existing case's needle stops before the parenthesis and is unaffected.
- **`TextureEmitTest.cpp:490`** — the case's hand-packed `(1u << 8) | kTex2D` is now
`MGPipePackSubDataTarget(kTex2D, 1u)`.
**Unchanged, deliberately:** `SubDataNamesABuffer` still matches the **whole field** against
`kMGPipeResourceTargetBuffer` (ID-12, and c0c's own `static_assert` is what keeps that exact), and
`MGPipeResourceRecord::PendingUpload::UploadTarget` still stores `MGPSubData::Target` **verbatim**. ID-12 gives
the high-byte decode to package D at its two match sites, and `MGPRespecifiedLevel::UploadTarget` is documented
to B as "the same packed value that level's sub-data emission uses" — changing the stored key here would silently
break that pairing. contract-v3 §4 leaves the choice to D; wire stays as ID-12 wrote it.
### (2) ID-19(b) — the framebuffer record is per object
**New in `PipeApply.h`:**
| where | what |
|---|---|
| `:156` | `kMGPipeMaxFramebufferSlots = 1u << 16` — the bounds gate the five object tables already carry |
| `:173` | `kMGPipeFramebufferTargetNamed = 3`, the **declared local** ID-21 asked for, with… |
| `:177-179` | …a `static_assert(static_cast<Uint8>(MGPipeFramebufferTarget::Count) == kMGPipeFramebufferTargetNamed)`. The day c0e lands, `Count` becomes 4 and **this fires**: the retirement cannot be forgotten |
| `:182-186` | `kMGPipeFramebufferBindingCount = 2` + a `static_assert` that `Draw == 0 && Read == 1` |
| `:397-401` | `struct MGPipeFramebufferRecord { Uint32 Gen; Bool Live; MGPFramebufferState State; }` |
| `:504` | `Vector<MGPipeFramebufferRecord> FramebufferRecords` — **beside the five object tables**, not in the working-state block |
| `:597` | `Array<MGPipeHandle, kMGPipeFramebufferBindingCount> BoundFramebuffer{}` (replaces the two `MGPFramebufferState` members) |
| `:614` | `mutable Uint64 StaleFramebufferRecordLookups = 0` |
| `:663-665` | `FramebufferRecordFor(MGPipeHandle) const`, `DrawFramebuffer() const`, `ReadFramebuffer() const`, all returning `const MGPFramebufferState*` |
**Bodies in `PipeApply.cpp`:**
- **`:2144` `MGPipeApplySetFramebufferState`.** The target gate is now `state.Target > kMGPipeFramebufferTargetNamed`
(so **3 is admitted**). Two new refusals, both `Fatal{ProtocolCorruption}` and neither counted: the **null
handle** (`{0,0}` is what "nothing is bound" reads as, so a record installed there would be answered to every
caller asking about an empty binding) and a **slot at or above the bound**. Then: the record is written at
`FramebufferRecords[state.Fbo.Slot]` **whatever the target is**; Draw/Both sets `BoundFramebuffer[Draw]`,
Read/Both sets `BoundFramebuffer[Read]`, **Named sets neither**; `++FramebufferSerial` on every applied record,
Named included.
- **`:2235` `MGPipeApplierState::FramebufferRecordFor`.** Null for a null handle (silent — that is an unbound
binding, not an error), null for a slot with no record (silent — that is every framebuffer before its first
emission), and for a **stale generation**: `++StaleFramebufferRecordLookups` and one `MGLOG_E_ONCE` naming both
generations, then null. Loud, because the only way to reach it is an emitter defect and the consequence on the
handle arm is a blit or clear into another framebuffer's attachments. Defined in the `.cpp`, not inline in the
header, so the header's include closure does not grow a logger.
- **`:2266`/`:2270` `DrawFramebuffer()` / `ReadFramebuffer()`** = `FramebufferRecordFor(BoundFramebuffer[t])`.
- **`:1176` `MGPipeApplierReset`** clears **`BoundFramebuffer` only** and keeps the table. A make-current is a
binding change; the record is an object record. Dropping the table there would lose the record of every
framebuffer that is addressed only BY NAME, because the client's re-emission on a fresh context is driven by
`MGPipeSetHashSuppressor::InvalidateAll`, which re-sends the two BOUND records and nothing else.
- **`:1222`/`:1236` `MGPipeApplierReleaseObjectRecords`** clears the table **and** the bound handles (m1
extended). Here there is nothing to outlive: the context is going away, its framebuffers are container objects
that go with it, and a table left standing would answer a lookup from the next context on a re-minted slot.
I checked c0e's in-flight `MGPipeTypes.h` in `~/w7/p4a-c0e` (uncommitted, branch still at `17db7598`) and wrote
to match it: `Named = 3`, "describes the framebuffer object it names and changes NO binding", per-object table
keyed by the handle's slot with the generation checked on lookup, a successor's record overwriting the slot.
**Nothing was cherry-picked.**
### (3) ID-18 M3 — acceptance returns on create and respecify
`Bool MGPipeApplyResourceCreate` (`PipeApply.h:800`, `.cpp:1524`) and `Bool MGPipeApplyResourceRespecify`
(`:848` / `:1576`). Contract at `PipeApply.h:786-799`, written once for all three calls: the emitter cannot see
either refusal from its call site, because a dead or stale handle is a counted no-op and a corrupt record is a
`Fatal` that deliberately moves no counter.
- **create** returns false for the reserved slot 0, a target that names no resource kind, and a slot past
`kMGPipeMaxResourceSlots`; true otherwise, dispatch or no dispatch.
- **respecify** returns false for a target that names no resource kind and for a handle with no live record at
that generation; true otherwise, **metadata updates included** — the record did move.
- Source-compatible: `PipeFill.cpp`'s P3a call sites discard the value, nothing is `[[nodiscard]]`, and
`gen_pipe.py` never parses this header (wire review W1) — `git diff -- MobileGL/MG_Pipe/generated` is rc 0 and
`gen_pipe.py --check` is rc 0.
### (4) ID-18 M4 — the metadata respecify
`RespecifyRedefinesNoStorage(stored, next)` (`PipeApply.cpp:558`), asked **before** the descriptor is replaced
(`:1595`), and its three consequences:
- `record->Desc = desc` — BindMask and ImageBindableHint take their new values (that is the whole call);
- `++record->Serial` — the entire publication; the twin re-derives its storage flags from the new mask at its
next sync and decides for itself whether the backend needs a recreate;
- `:1640` — the **third arm of the pending-upload clear**: a metadata update drops **nothing**, whatever `level`
says. This refines C1 rather than contradicting it: C1's rule drops the uploads against the storage a call
REPLACES, and a call that replaces no storage replaces no level's coordinate system.
- `MGPipeResourceRespecifyNeedsAck` is false for every such record **by construction** (`:1660-1670`), not by a
second suppression rule — see the deviation below.
**The comparison is field by field, not a memcmp** (`MGPResourceDesc` carries `Pad0`/`Pad1` and neither side is
guaranteed to have written them — the padding coin flip clientsp's sampler cache already paid for once).
### (5) The tests
Five new cases; three existing ones extended to the new shape. Every case is a visible SKIP in a pull build, so
`ctest -N` stays name-for-name identical between the pull and the push trees.
| suite | case | pins |
|---|---|---|
| `FramebufferEmit` | `ANamedRecordDescribesTheFramebufferItNamesWithoutMovingEitherBinding` (`:431`) | the Named record is found **by handle** with its attachments; **neither** binding moved (two *different* framebuffers are bound first, so it is an assertion about values and not about null); the serial moved anyway; the same object can then be bound |
| `FramebufferEmit` | `AFramebufferHandleWhoseGenerationHasMovedOnIsRefusedRatherThanAnswered` (`:488`) | stale gen → null **and** `StaleFramebufferRecordLookups + 1`, in both directions across a recycle; the null handle and an undescribed slot are **not** counted; `RefusedObjectCalls` stays 0 |
| `FramebufferEmit` | `AFramebufferRecordThatNamesNoUsableHandleIsRefusedRatherThanStored` (`:528`) | the default framebuffer `{0,1}` is the positive control; the null handle and a slot at the bound are refused by name; nothing stored, no serial, no resize |
| `TextureEmit` | `ARespecifyThatRedefinesNoStorageCarriesTheStickyMaskAndKeepsThePendingUploads` (`:687`) | the immutable `glTexStorage2D` → `glTexSubImage2D` → `glBindImageTexture` order; mask and hint land, the pending upload survives, the serial moves, `NeedsAck` is false; **with a level pointer too**; and the negative control — move one storage field and the same call drops the level |
| `TextureEmit` | `TheCreateAndRespecifyCallsAnswerWhetherTheRecordWasAccepted` (`:757`) | true on both, false on the reserved slot and on a stale generation (with `RefusedResourceCalls + 1`), and the buffer half on the same terms with no backend table registered |
Extended: `ADrawRecordAndAReadRecordAreKeptApartAndBothWritesBoth` (`:216` — Draw moves Draw only, Both moves
both, **and the two earlier framebuffers keep their own records**); `AMakeCurrentClearsBothRecordsAnd…` (`:334` —
both accessors null, both handles null, **the record survives**); `AReleaseOfTheObjectRecordsAlsoClears…`
(`:371` — `FramebufferRecords` is **empty** afterwards). `ATargetOutsideTheThreeBindings…` (`:270`) now drives
`kMGPipeFramebufferTargetNamed + 1`, because 3 is legal.
`ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers` (C1's case, `:473`) was **rewritten to stay a gate**: it
now gives each respecify the descriptor the call it models would carry (`Levels` 1 → 2 as a mip build adds
level 1 — package B's `desc.Levels = mipmap->GetMipmapLevelCount()`, which is also why B's own memcmp dedupe
emits that respecify at all; and a new `InternalFormat` for the redefinition of level 1). Fed the *same*
descriptor three times, as v2 wrote it, it would have been exercising the metadata arm instead of the per-level
one. MU8 below proves C1's gate survived the restructure.
---
## 3. Deviations
**W10 — a BUFFER respecify is never classified as metadata-only, and the comparison is wider than the brief's
list.** ID-21 names the storage-defining set as InternalFormat / Width / Height / Depth / ArrayLayers / Levels /
Samples / FixedSampleLocations / StorageKind / Target / the buffer-texture fields. The implementation compares
**everything except** `BindMask`, `ImageBindableHint`, `GlNameForDiag` and the two padding words — so also
`Immutable`, `HasDefinedContent`, `Usage`, `StorageFlags` and `ViewOf` — and refuses the buffer target outright.
Two reasons, both written at `PipeApply.cpp:526-557`:
1. **Direction of the asymmetry.** Comparing too much can only mis-classify a metadata update as a redefinition,
whose cost is one level's pending upload dropped by a call B does not emit. Comparing too little
mis-classifies a REDEFINITION as metadata and keeps boxes in a coordinate system that no longer exists —
an upload past the end of the new level. None of the extra fields moves on a mask republish (B re-publishes
the same descriptor with a new mask), so the wider set costs M4 nothing.
2. **`glBufferData` at an unchanged size is the canonical ORPHANING idiom** — a real reallocation whose whole
point is that the old store is gone — and `glBufferStorage` is the one entry point allowed a synchronous ack.
Excluding the buffer target is what makes ID-18 M4's *"no reallocation ack
(`MGPipeResourceRespecifyNeedsAck` false)"* true **by construction** rather than by a second suppression rule
the transport would later have to learn: the predicate is already false for every non-buffer target. ID-18 M4
is a statement about a texture's (and a renderbuffer's) sticky mask, and a buffer has no pending upload for
the arm to protect.
**W11 — "identical storage fields clear nothing, whatever the level pointer says" is implemented literally, and
here is its one sharp edge.** A per-level respecify whose descriptor happens not to move would now keep the very
level it redefines. On the tree as built that is unreachable: B publishes `desc.Levels` from
`MipmapStorage::GetMipmapLevelCount()`, so the glTexImage\*D that defines a new level moves the descriptor, and
B's 88-byte memcmp dedupe means a respecify whose descriptor did **not** move is never emitted at all. The case
at `TextureEmitTest.cpp:687` pins the ruling as written (a metadata update with a non-null level drops nothing)
and the case at `:473` pins the other arm on the descriptors a real mip build produces. **If B's rework ever
emits a per-level respecify with a byte-identical descriptor, that level's pending upload survives the
redefinition** — worth ten lines of a reviewer's attention on B's `AllocateStorage` path, and invisible to every
gate P4a has.
W1–W6, W8 and W9 stand as v1/v2 recorded them and as the reviews accepted them. **W7′ is superseded by W11's
third arm** (the scope argument is unchanged; the metadata arm now precedes it).
---
## 4. Mutation evidence — nine mutations, nine red, each killing exactly one case
Measured in `build-push` at HEAD; each applied to `MobileGL/MG_Pipe/PipeApply.cpp`, the tree rebuilt, the seven
emit suites run (74 tests), the file restored from the commit. **The verdict is `ctest`'s exit code**, not a grep.
| # | mutation | verdict |
|---|---|---|
| MU1 | the Named arm also moves the draw binding (`Target == Draw \|\| Both` → `Target != Read`) | rc 8, 1/74 — `FramebufferEmit.ANamedRecordDescribesTheFramebufferItNamesWithoutMovingEitherBinding` |
| MU2 | the stale-generation test disarmed | rc 8, 1/74 — `FramebufferEmit.AFramebufferHandleWhoseGenerationHasMovedOnIsRefusedRatherThanAnswered` |
| MU3 | the null-framebuffer-handle refusal disarmed | rc 8, 1/74 — `FramebufferEmit.AFramebufferRecordThatNamesNoUsableHandleIsRefusedRatherThanStored` |
| MU4 | the metadata-respecify arm disarmed | rc 8, 1/74 — `TextureEmit.ARespecifyThatRedefinesNoStorageCarriesTheStickyMaskAndKeepsThePendingUploads` |
| MU5 | a refused respecify answers accepted | rc 8, 1/74 — `TextureEmit.TheCreateAndRespecifyCallsAnswerWhetherTheRecordWasAccepted` |
| MU6 | the teardown no longer drops the framebuffer records | rc 8, 1/74 — `FramebufferEmit.AReleaseOfTheObjectRecordsAlsoClearsTheWorkingHandlesThatCouldNameThem` |
| MU7 | a make-current drops the framebuffer records | rc 8, 1/74 — `FramebufferEmit.AMakeCurrentClearsBothRecordsAndAdvancesTheSerialRatherThanZeroingIt` |
| MU8 | **C1's** per-level scoping disarmed (the whole-resource clear again) | rc 8, 1/74 — `TextureEmit.ARespecifyOfOneLevelKeepsThePendingUploadsOfTheOthers` |
| MU9 | `resource_create` always answers accepted (the reserved-slot arm) | rc 8, 1/74 — `TextureEmit.TheCreateAndRespecifyCallsAnswerWhetherTheRecordWasAccepted` |
After each sweep the tree was restored, rebuilt and re-run: `git status --porcelain` empty, 74/74.
---
## 5. The exact applier API the other packages must call
### Package B — clientfb
1. **Emit a `Named` record at every DSA entry point that hands a framebuffer to Espryt by name** (ID-19(c)):
`BlitNamedFramebuffer`, the four `ClearNamedFramebuffer*`, and the DSA attachment / draw-buffer / read-buffer
setters at their validate point. `state.Target = static_cast<Uint8>(MGPipeFramebufferTarget::Named)` once c0e
lands; **until then `MG_Pipe::kMGPipeFramebufferTargetNamed`** (`PipeApply.h:173`, which B already includes).
The record's every other field describes the framebuffer named by `Fbo` exactly as a bound record does,
`ReadSurface` included. The rule is *"any framebuffer Espryt is about to receive by name has a record"*.
2. **The suppressor must be keyed by the framebuffer the record names, not by one global slot.** Two different
objects' Named records in a row must both go out, and a Named record must never be suppressed against the
same object's bound record or the reverse. (c0e's comment says this too; the applier cannot see the
difference, so it is B's to hold up.)
3. **`state.Fbo` may never be the null handle** — it is now `Fatal{ProtocolCorruption}`. `kMGPipeDefaultFramebuffer`
`{0,1}` for the default framebuffer, a minted `{slot, gen}` otherwise, which is what `HandleFor` already does.
4. **`MGPipeApplyResourceCreate` and `MGPipeApplyResourceRespecify` now return `Bool`.** Together with
`MGPipeApplyResourceSubData` (v2), that is D-D5 step 1's complete signal: **clear a level's
`m_isDirty`/`m_dirtyRects`/`m_dirtyRegions`, and advance the per-entry descriptor dedupe, only on true.**
Discarding compiles.
5. **`MGPipeApplyResourceRespecify`'s third parameter is still `const MGPRespecifiedLevel* level = nullptr`**
and B must pass it at every per-level respecify, with `UploadTarget` set to **the same packed
`MGPSubData::Target` value that level's sub-data emission uses** (build it with c0c's
`MGPipePackSubDataTarget`) and `Level` to the level index. `glTexStorage*`, `glBufferData`,
`glBufferStorage` and texture views pass `nullptr`.
6. **The mask republish (M4) passes `nullptr` for the level and changes only `BindMask` /
`ImageBindableHint`.** If any other descriptor field moves in the same emission the applier reads it as a
redefinition and drops that level's pending upload — see W11.
7. The refusal line for a mis-packed sub-data target now names **both halves**, so a wrong-way-round packing is
readable straight out of the log.
### Package D — esprytobj
`FramebufferImpl::PushedFramebufferRecord` (`Managers.cpp:8216-8226`) is now one call:
```cpp
const MG_Pipe::MGPFramebufferState* PushedFramebufferRecord(MG_Pipe::MGPipeHandle fbo) {
return MG_Pipe::MGPipeApplier().FramebufferRecordFor(fbo); // null = no record / stale gen
}
```
The `asTarget` parameter and the `record.Fbo == fbo` test **go**: the table is keyed by the handle, so a record
that comes back is that framebuffer's by construction, and it comes back whether the object is bound to Draw, to
Read, to both or to neither. That is C-1's fix: `SyncToBackend(fbo, Draw)` for a DSA-named framebuffer now finds
its attachments instead of declining and clearing into an unattached driver FBO.
Where D genuinely needs the **binding** question (rather than the description), it is one array compare:
`MG_Pipe::MGPipeApplier().BoundFramebuffer[static_cast<SizeT>(asTarget == FramebufferTarget::Read
? MG_Pipe::MGPipeFramebufferTarget::Read : MG_Pipe::MGPipeFramebufferTarget::Draw)] == fbo` (ID-19(d)).
Also for D: `MGPipeApplier().StaleFramebufferRecordLookups` is the counter to assert 0 in a scenario;
`MGPipeApplierReleaseObjectRecords` now empties `FramebufferRecords` as well as the bindings.
### Package E — esprytdraw
E's v2 already routed all six reads through one function, and that function is the only thing that changes.
`DirectGLES.cpp:284-287`:
```cpp
static const MG_Pipe::MGPFramebufferState* BoundFramebufferRecord(FramebufferTarget target) {
const auto& st = MG_Pipe::MGPipeApplier();
return target == FramebufferTarget::Draw ? st.DrawFramebuffer() : st.ReadFramebuffer();
}
```
— a reference becomes a **pointer**, and `const auto& st` stays const (both accessors are `const`; the stale
counter is `mutable` precisely so E keeps its shape). The seven call sites (`:2127`, `:2273`, `:2863`, `:2864`,
`:2905`, `:4009`, `:4179`) take `const auto*` and null-check. In `SyncCurrentFBOByRecord` (`:2765`) the
half-described test
```cpp
if (MGPipeHandleIsNull(st.DrawFramebuffer.Fbo) || MGPipeHandleIsNull(st.ReadFramebuffer.Fbo)) return false;
```
becomes `if (st.DrawFramebuffer() == nullptr || st.ReadFramebuffer() == nullptr) return false;` — the same
question, and it now also covers "the bound handle's record has a stale generation", which used to be
unrepresentable. `st.FramebufferSerial` is unchanged and still advances on every applied record.
### Package F — gates
`RefusedObjectCalls` must still be **0 across every framebuffer call in every build**; the framebuffer family's
own refusal counter is the separate `StaleFramebufferRecordLookups`, and **0 is the expected value there too** on
an integrated tree — a non-zero one is a seam defect, not traffic.
---
## 6. Gate transcript (HEAD `70e742a3`, working tree clean)
Run in `/home/swung/w7/p4a-wire` with `CCACHE_BASEDIR=/home/swung/w7`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0`, `-j 8` / `--parallel 8`.
```
build-linux / build-push / build-verify rc=0 / rc=0 / rc=0
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 rc=0
.text 10806323 -> 10806323 (+0, +0.000%)
27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
27072 -> 27072 normalised names, 27072 unchanged
### Removed (0) ### Added (0) ### Resized (0) ### Renamed only (0)
ctest --test-dir build-linux -L unit 100% passed, 0 failed out of 1680 rc=0
ctest --test-dir build-push -L unit 100% passed, 0 failed out of 1680 rc=0
ctest --test-dir build-verify -L unit 100% passed, 0 failed out of 1680 rc=0
ctest --test-dir build-push -R 'ResourceEmit\.|FramebufferEmit\.|TextureEmit\.|
SamplerEmit\.|ImageEmit\.|ProgramEmit\.|CompositeResolver\.|HandleRecycle'
100% passed, 0 failed out of 130 rc=0
bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD rc=0
the 11 pool / deferred-release / ring / flush-drain functions are
byte-identical between 37da3c3a and HEAD
python3 scripts/check_include_closure.py --mode both --compiler clang++
--self-test --require-all rc=0
4 probes, 0 skipped, 0 problem(s); self-test 6 negative-control trips
python3 scripts/gen_pipe.py --check rc=0
477 inventory rows, 0 UNMAPPED; generated files are up to date
python3 scripts/gen_pipe.py --self-test 7 negative-control trips rc=0
python3 scripts/gen_pipe_dirty_surface.py --check rc=0
0 COARSE, 2 UNDECIDED (c0's BindVertexArray / UseProgram rows, unchanged)
python3 scripts/gen_pipe_dirty_surface.py --self-test 27 negative controls rc=0
git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
```
**ctest name sets** (`LC_ALL=C`, `ctest -N`):
```
build-linux vs build-push 2646 == 2646, 0 differing lines (G2)
vs ~/w7/p4a-before-ctest-names.txt 0 removed, 58 added, 2588 -> 2646
```
58 = c0's 13 + c0b's 1 + **c0c's 2** + wire v1's 33 + v2's 4 + **v3's 5**. Unit count 1673 (v2, on c0+c0b) →
**1680** = c0c's 2 + this round's 5.
**Not run this round, and why**: the integration / verify-scenario / retrace / APK lanes and the device arms.
This package is still behaviour-neutral — all four `kMGPipeWired*Subsystem` are 0 on this tree, nothing consumes
a P4a record, `PipeApply.{h,cpp}` are push-only translation units and G1 is 0/0/0/0. No retrace ran, so the LFS
restore in §0 was hygiene for the next round rather than a prerequisite for this one.
---
## 7. What the integrator must re-run
1. **The full five-part gate of D.3** on the merged head — nothing here substitutes for it — plus
`symbol_report --threshold 0` (P4a's admitted set is EMPTY) and `p3a_untouched_regions.sh 37da3c3a HEAD`.
2. **When c0e lands**: the `static_assert` at `PipeApply.h:177` **fires** (its `Count` becomes 4). That is the
trip wire, not a regression. Retiring it is wire's verification round: delete
`kMGPipeFramebufferTargetNamed` and its assert (`PipeApply.h:173-176`) and spell
`static_cast<Uint8>(MGPipeFramebufferTarget::Named)` at its six readers — `PipeApply.cpp:2153` (the target
gate), `FramebufferEmitTest.cpp:276`, `:443`, `:454`, and the two prose mentions at `PipeApply.h:595`/`:965`.
One constant, six sites, no behaviour change.
3. **After B lands**, three reads worth ten minutes each: (a) does B emit a Named record at **all five** DSA
entry points plus the DSA setters, and is its suppressor keyed per framebuffer (§5 B.1/B.2)? (b) does B gate
its dirty-flag clear on the three acceptance returns? (c) does the mask republish move **only** BindMask /
ImageBindableHint (W11)? None of the three is visible to any gate P4a has.
4. **After D lands**: `PushedFramebufferRecord` must lose its `asTarget` parameter and its `record.Fbo == fbo`
test, or C-1 is only half fixed — a Named record would still be refused for not being the bound one. And D's
teardown path must not read a binding after `MGPipeApplierReleaseObjectRecords`.
5. **After E's verification round**: `StaleFramebufferRecordLookups` should be **0** on the integrated tree's
scenarios. A non-zero value is the seam defect ID-19 was written to make visible, not traffic.
6. **D-K2's fourth row** (ID-15's H1) is still owed by D and F; the applier's `Fatal` on a null `BuiltinSampler`
is unchanged and correct, and the `0x5ff` lane still aborts until that row exists.
7. **The brief's D-C2** still describes the record as per bound target and **D-J4** still lists the framebuffer
records as working state; both are amended by ID-19(b) and by this round. D.5 should carry the correction
alongside c0e's.
8. **LFS**: this tree's fixtures were restored by copy from `~/w7/base` because `git lfs checkout` reports
*"Git LFS is not installed"* here — `/usr/bin/git-lfs` exists but the repo has no `filter.lfs.smudge`. A
`git lfs install --local` in each worktree would stop ID-13's trap recurring after every WSL restart.
+955
View File
@@ -0,0 +1,955 @@
# P4a docs specification — everything `docs/Disaggregated/` says about handle wave 2
Scout report. Tree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`
(branch `feat/disaggregated`, P3a landed at `fde5fda3`, docs at `37da3c3a`). Read-only; nothing edited.
Every claim below carries the path and line I opened. Chinese is quoted **verbatim** wherever the wording is
the requirement; English around it is my reading.
Conventions carried forward from P3a: `ID-n` are the rulings in `~/w7/notes/p3a/INTEGRATOR-DECISIONS.md`;
`Gn` are the gate ids of `~/w7/notes/p3a/BRIEF-P3A.md` §A.2. Paths written `MobileGL/...` are relative to the
repo root; `ARCHITECTURE.md`, `ROADMAP.md`, `MEASUREMENTS.md`, `README.md` are in `docs/Disaggregated/`.
---
## 0. Where P4a sits
- `README.md:3`: "**P0、P0.5、P1、P2、P3a 已落地**(`feat/disaggregated@fde5fda3`,基线 `dev@9eae9858`)。第 43 天
GO/NO-GO 判定为**继续**。P3a(handle wave 1:Espryt 的 buffer 与 VAO)已交付,**下一步 P4a**(handle wave 2:
FBO / 纹理 / sampler / program 的身份与描述符)。"
- `ROADMAP.md:9` — the two tracks. The monolith track is
"**monolith 跑道** P0 → P0.5 → P1 → P2 → P3a → P4a → P3b/P4b → P7 → P8 → P13,每段可独立交付、可随时中止且
monolith 严格好于起点". P4a's dependency is P3a; P5 (transport) depends on P4a (`ROADMAP.md:21`), and so does
P3b/P4b (`ROADMAP.md:23`).
- `ROADMAP.md:32` — the running day total: "P3a 61 → **P4a 87** → P5 99 …". P4a's own estimate is **26–34 days**
(`ROADMAP.md:20`, column 2).
- `ID-24` (P3a closed): "Next: P4a (handle wave 2: FBO / texture / sampler / program)."
---
## 1. The P4a row of the phase table, cell by cell
`ROADMAP.md:20` in full. **All five cells verbatim** (this table row is the contract; nothing below adds a
deliverable to it):
> | **P4a** handle wave 2(Espryt):FBO / 纹理 / sampler / program 身份与描述符 | 26–34 | `set_framebuffer_state`(解析后的 `ReadSurface`、内联格式、`ContentHash`、`{0,1}`);sampler CSO(含 `borderColorForm`);sampler view + `set_texture_params`;`set_sampler_views`/`bind_sampler_states`/`set_shader_images`;shader CSO(SPIR-V + 归档);`set_draw/dispatch_program`;`set_global_constants`;`CompositeResolver`;纹理/renderbuffer 的 `resource_*`。emulation 在 split 下显式 Fatal 直到 P8 | 全套门;framebuffer/纹理/program 族场景;**新增"只作 attachment / image 单元 / CopyImage 端点的纹理其 `glTexParameter` 生效"场景(落地前必须红)**;两台设备 `KHR-GL46.direct_state_access.framebuffers*` 与整个 `packed_pixels` 块(~3300 例,句柄复用压力测试)。**再基线检查点 1b:超过 39 天** | P3a |
### 1.1 Deliverables, decoded (column 3)
Eleven items. Each maps onto a call that **already exists in the catalogue** — `PipeCalls.def` is closed
(`MGP_CALL_LIST_DOCUMENTED_COUNT 71`, `MobileGL/MG_Pipe/PipeCalls.def:75`) and
`MobileGL/MG_Pipe/PipeCalls.def:26-29` forbids reordering: "RECORD NUMBERING NEVER CHURNS … The wire opcode is
the 1-based position in this list, so reordering is a protocol break." P4a therefore **wires** calls; it does
not add rows. (P3a's precedent: it changed one flag word on an existing row, `ID-8`/BRIEF C.0.)
| # | deliverable | catalogue row | payload |
|---|---|---|---|
| 1 | `set_framebuffer_state` | `PipeCalls.def:113` `X(SetFramebufferState, MGPFramebufferState, kCtxState, kNone)` | `MGPFramebufferState` 304 B |
| 2 | sampler CSO incl. `borderColorForm` | `:104` `CreateSamplerState`, `:105` `DeleteSamplerState` (`kCtxCso, kNone`) | `MGPSamplerDesc` 32 B |
| 3 | sampler view | `:106` `CreateSamplerView`, `:107` `DeleteSamplerView` | `MGPSamplerView` 36 B |
| 4 | `set_texture_params` | `:133` `X(SetTextureParams, MGPTextureParams, kCtxObject, kNone)` | `MGPTextureParams` 32 B |
| 5 | `set_sampler_views` | `:117` `kCtxState, kVarTail` | `MGPSamplerViews` 16 B + `MGPBoundView[]` 24 B |
| 6 | `bind_sampler_states` | `:118` `kCtxState, kVarTail` | `MGPSamplerStates` 16 B + `MGPipeHandle[]` |
| 7 | `set_shader_images` | `:119` `kCtxState, kVarTail` | `MGPShaderImages` 16 B + `MGPImageView[]` 24 B |
| 8 | shader CSO (SPIR-V + archive) | `:108` `CreateShaderState` (`kHasBlob`), `:109` `BindShaderState`, `:110` `DeleteShaderState` | `MGPProgramDesc` 192 B |
| 9 | `set_draw/dispatch_program` | `:126` `SetDrawProgram`, `:127` `SetDispatchProgram`, both `MGPHandleOnly` | 16 B |
| 10 | `set_global_constants` | `:122` `X(SetGlobalConstants, MGPGlobalConstants, kCtxState, kHasBlob)` | `MGPGlobalConstants` 40 B |
| 11 | texture/renderbuffer `resource_*` | `:81-85` `ResourceCreate/Respecify/Destroy/MapPersistent/UnmapPersistent` (kScreen) + `:134-141` the `kCtxObject` transfers | `MGPResourceDesc` 88 B, `MGPSubData` 72 B, `MGPMipPlan` 16 B, `MGPCopyRegion` 64 B, `MGPReadbackInfo` 64 B |
`CompositeResolver` is not a call: it is a **client-side component** in the build layout,
`ARCHITECTURE.md:562` — `MobileGL/MG_Impl/Pipe/ Tracker、SlotAllocator、CsoCache、HostResolve、CompositeResolver [P2+]`.
It does not exist in the tree today (`grep -rn CompositeResolver` hits only `ARCHITECTURE.md:562` and
`ROADMAP.md:20`); `MobileGL/MG_Impl/Pipe/` currently holds `CsoCache.h`, `PipeFill.{h,cpp}`, `ResourceTracker.h`,
`SetHashSuppressor.h`, `SlotAllocator.{h,cpp}`, `Tracker.h`, `VertexInputEmit.h`. Its contract is §5.6 below.
**"emulation 在 split 下显式 Fatal 直到 P8"** — the last clause of column 3. The emulations P4a's families
reach (client vertex arrays, max-index scan, `*IndirectCount`, CopyImage mirror, generate-mipmap storage) are
P8's work (`ROADMAP.md:25`: `MG_Impl/Pipe/HostResolve.cpp`, `Server/IndexHostMirror`, "CopyImage 镜像搬到
client", "`generate_mipmap` 计划 + CPU 回退纹素"). Until then, a split build that reaches one must **abort
loudly, not silently degrade**. In monolith the same code paths keep running as today (the Fatal is a
split-only arm), so this costs P4a a named `Fatal{...}` per unmigrated emulation site and nothing else.
### 1.2 The acceptance gate (column 4), decoded
Four clauses. Read literally.
**(a) 全套门** — the five-part gate of `ARCHITECTURE.md:507-517` (§13.2), run once at the phase exit
(`ROADMAP.md:7`: "每阶段出口跑一次五部分门"). Concretely, P3a's realisation of it is `MEASUREMENTS.md:328-381`
(§16) and the G-ids of `BRIEF-P3A.md:155-172`, all of which carry over:
| part | what | P4a shape |
|---|---|---|
| 1 interface purity | three builds pull/push/verify green; **A** include-closure; **B** `nm --undefined-only libMobileGLServer.so \| grep -E 'MG_State::GLState::\|glslang'` empty; **C** `grep -c pGLContext MG_Backend/ == 0`; plus **G1** pull symbols 0/0/0/0 and **G5** byte-identical regions | `ARCHITECTURE.md:511`; P3a's realisation `MEASUREMENTS.md:330-341`. G13 additionally: "no `MG_State::GLState` type appears in any `MGPipeResourceOps` signature" (`BRIEF-P3A.md:170`) — P4a's new op tables inherit that rule |
| 2 semantic shadow compare | `MOBILEGL_PIPE_VERIFY=1`: `integration-verify` zero `Fatal{`, every retrace case **armed**, zero divergence | `ARCHITECTURE.md:512`; P3a: 842/842 and 79/79 armed (`MEASUREMENTS.md:347-348`). §512 names the **保留模式** (retain mode) that P4a's texture path needs: "消费即清的组(纹理 dirty rect)发射后无法重算,verify 时 tracker 保留清除前的集合并比对发射出去的 `(UnionBox, RegionCount, Regions[])`" |
| 3 behaviour A/B | **G2** pull/push ctest names identical; **G14** 0 removed; `integration-gpu` green on {pull, push, `PUSH=0`, the previous phase's mask, named kill-switch arms}; 79 retrace cases at their own SSIM thresholds; **CTS within 0.5 pp** | `ARCHITECTURE.md:513`, `MEASUREMENTS.md:352-367`. The subsystem-off arm for P4a is `MOBILEGL_PIPE_PUSH=0x1ff` (P3a's default), exactly as P3a used `0x7f` (**G12**, `MEASUREMENTS.md:359`) |
| 4 monolith performance | **RECORDED, NOT GATED** — see §4 below | `ARCHITECTURE.md:514`, `MEASUREMENTS.md:324`, `ID-6` |
| 5 coverage + poison + handle discipline | G6 `gen_pipe.py --check`/`--self-test` 0 UNMAPPED; `gen_pipe_dirty_surface.py --check`/`--self-test`; per-verb poison; G7 setter-consistency; `ResidualValueBlock` `offsetof` asserts | `ARCHITECTURE.md:515`, `MEASUREMENTS.md:373-379` |
**(b) framebuffer / 纹理 / program 族场景** — the scenario families. The tree's existing homes:
`MobileGL/MG_IntegrationTest/Scenarios/` (P3a's buffer/VAO family list is enumerated at `MEASUREMENTS.md:361`
and is the template for naming the P4a family list in the brief).
**(c) THE NEW SCENARIO, and its red-before requirement.** Verbatim:
> **新增"只作 attachment / image 单元 / CopyImage 端点的纹理其 `glTexParameter` 生效"场景(落地前必须红)**
This is the acceptance case for the D10 split between `set_texture_params` and the sampler view. The design
statement it tests is `ARCHITECTURE.md:100`:
> `SetTextureParams` 按资源寻址、与 sampler view 分开(D10):只作 FBO attachment / image 单元 /
> `glCopyImageSubData` 端点的纹理没有 sampler view,但 Espryt 对 attachment 也同步纹理参数,且
> `RequireImageBindableStorage` 需要在前端参数版本不动时强制重同步。
and the payload comment `MobileGL/MG_Pipe/MGPipeTypes.h:289-292`:
> "= pipe_sampler_view, and ONLY the view restrictions. Everything a `glTexParameter` writes lives on
> `set_texture_params` instead, because a texture that is only an FBO attachment, only an image binding or only
> a `glCopyImageSubData` endpoint has no sampler view to hang it on (section 4.4.3)."
"落地前必须红" is the same discipline as `ROADMAP.md:7`'s "**每个门必须能因它存在的理由变红**" and the same
shape P3a discharged for the buffer class at `MEASUREMENTS.md:383-399` (§17: the `.Handles` arm **visibly
SKIPs** with a stated reason on the contract tree, `.Legacy` passes, `.AbaControl` passes *by asserting the
corruption*; "**`.Handles` 可见地 skip** 并写明缺什么,而不是一条消失的测试"). Record the red-before evidence on
the contract tree before the consumer package lands (`BRIEF-P3A.md:1420-1431` D.2 is the procedure).
**(d) DEVICE CTS, both devices.** Verbatim: "两台设备 `KHR-GL46.direct_state_access.framebuffers*` 与整个
`packed_pixels` 块(~3300 例,句柄复用压力测试)". Two named blocks, and the second is explicitly a
**handle-reuse stress test** — that is why the block runs whole rather than sampled. Supporting rules:
- `ROADMAP.md:34`: "**CTS 周转单独计价**:`gl44to46` 约 56,271 例。逐阶段只跑该阶段可能影响的具名块
(**P4a `packed_pixels`**、P3b/P4b `texture_*`/`shader_image_*`、P9 `transform_feedback*`);完整 caselist 只在
五个架构边界(P0.5、P3a、**P4a**、P3b/P4b、P13)与每次合并 `dev` 之前跑,放 CI 不放关键路径。若周转仍主导排期,
加宽估时而不是削弱门。" — so P4a owes **both** the named blocks *and* a full ~56,271-case run, the latter off
the critical path at the `dev` merge (P3a's handling: `MEASUREMENTS.md:381`, **G15**).
- Report shape is fixed (`ARCHITECTURE.md:513`, `BRIEF-P3A.md:172`): rows = GL version/extension, columns =
status counts, rate = Pass/(Pass+Fail), **NS not in the denominator**; per-backend conformance within
**0.5 pp** of the `$BASE` reading. The two devices are Adreno 830 `35d0befa` and Mali `3B159D009VZ00000`
(`ROADMAP.md:50`).
- P3a also carried a caselist rider that lands in the same run: `MEASUREMENTS.md:381` — "`MOBILEGL_PIPE_POISON_OMIT`
的清扫(§14 那 8 条静态过近似填充行)搭同一次 caselist 运行". Those 8 over-approximated `FillPoints.def` rows
(`MEASUREMENTS.md:294`) are still open and three of them are P4a's own subject matter (`kTextureOp`/`kDispatch`
+ `IsCapabilityEnabled`, `kBlitOrCopy`/`kTextureOp` + the shader-blit viewport/vertex bindings).
**(e) 再基线检查点 1b:超过 39 天.** `ROADMAP.md:67` — the trigger table row "| P4a > 39 天 | 同上 |", where
"同上" = `ROADMAP.md:66`'s action, "'窄句柄化'的前提错了,P4a 开始前重定基线" (for 1b: re-baseline before the
next phase). `ROADMAP.md:70`: "任一触发,先跑 `inproc` 的证伪数字再决定是否继续." Precedent for the accounting:
P3a's checkpoint 1 was 27 days and came in at **1** actual calendar day (`ROADMAP.md:40`, `MEASUREMENTS.md:417`),
recorded per package. P4a must record elapsed days per package the same way.
### 1.3 Every other mention of P4a in the docs
1. `README.md:3` — next phase, named as "handle wave 2:FBO / 纹理 / sampler / program 的身份与描述符".
2. `ROADMAP.md:9` — position in the monolith track.
3. `ROADMAP.md:21` — **P5 depends on P4a**. P5's column-5 cell is literally `P4a`.
4. `ROADMAP.md:23` — **P3b/P4b depends on P4a** (column 5 = `P4a`).
5. `ROADMAP.md:32` — cumulative day count, P4a ends at day 87.
6. `ROADMAP.md:34` — the CTS rule above (`packed_pixels` named block; P4a one of the five full-caselist boundaries).
7. `ROADMAP.md:67` — re-baseline checkpoint 1b.
8. `ARCHITECTURE.md:369` (§9.6) — "对策:**编译期** `MOBILEGL_PIPE_LEGACY_MEMOS`(默认 ON)在 **P3a/P4a 期间**
保留 registry / `TwinLookupMemo` 实现活在同一个 `PipeInputs` 接口之下,随 pull 路径在 P13 退役(各阶段 +1 天维护)."
→ **P4a keeps the pre-handle arm compiling**, and budgets +1 day for maintaining it.
9. `MEASUREMENTS.md:465` reading (5) — "`CreateVertexElements` 每帧字节数:统计行没有这一类(`vtxc` 是 client
数组),**未测**,**留给 P4a 给汇总行加类**." → P4a owes a new byte class on the `MGPipe stats:` summary line.
10. `MEASUREMENTS.md:503` (DriverBench) — "**不钉上限、也不强制上限**(规则 (a));数字发布出来,**让 P4a 自己
决定要不要钉**." → P4a decides whether P3a's per-draw cost gets a ceiling. See §4.
11. `MEASUREMENTS.md:326` (§15) — "一次回归要写下数字与怀疑的成因并**带进 P4a 的排期**."
12. `MobileGL/MG_Impl/Pipe/SetHashSuppressor.h:45-52` — the suppressor slot enum labels
`SetSamplerViews`/`BindSamplerStates` as **P3b** and `SetShaderImages`/`SetShaderBuffers`/
`SetStreamOutputTargets` as **P4b**, while `ROADMAP.md:20` gives the three *calls* to P4a. **This is not a
contradiction but it is a trap**: P4a lands the calls and their `ContentHash` fields; the *suppressor
wiring* for those slots is P3b/P4b's ("**同时**在 Tracker 落地集合 hash 抑制器", `ROADMAP.md:23`). A P4a
package that wires a suppressor slot is doing P3b/P4b's work; one that omits `ContentHash` from the record
breaks `ARCHITECTURE.md:147`. Say which in the brief.
---
## 2. What ARCHITECTURE.md says about these calls, payloads and paths
### 2.1 The exact structs and `static_assert`s (`MobileGL/MG_Pipe/MGPipeTypes.h`)
Every payload is "平坦 POD、显式 padding、`static_assert` 平凡可复制与**精确尺寸**;**永不含指针**"
(`ARCHITECTURE.md:118`). `MGP_ASSERT_POD(T, Size)` is defined at `MGPipeTypes.h:44`. Sizes are identical on
arm64 and x86-64 (`MEASUREMENTS.md:86`).
**`MGPSurface` — 24 B, `MGPipeTypes.h:343-353`** (`= pipe_surface`; `:341-342`: "internalFormat is INLINE so the
four cross-object masks fall out at push time with no lookup"):
```cpp
struct MGPSurface {
MGPipeHandle Res;
Uint32 InternalFormat;
Uint8 Kind; // Texture | Renderbuffer | None
Uint8 Layered;
Uint16 Level;
Uint32 Layer;
Uint16 UploadTarget;
Uint16 Pad0;
};
MGP_ASSERT_POD(MGPSurface, 24);
```
**`MGPFramebufferState` — 304 B, `MGPipeTypes.h:355-372`**:
```cpp
struct MGPFramebufferState {
MGPipeHandle Fbo; // kMGPipeDefaultFramebuffer for the default framebuffer
MGPSurface Color[8];
MGPSurface Depth, Stencil;
MGPSurface ReadSurface; // the RESOLVED read surface, not an index
Int8 DrawBuffers[8]; // attachment index, -1 = NONE
Uint16 Width, Height, Layers, Samples;
Uint8 FixedSampleLocations, IsDefault, Complete, Pad0;
Uint32 Pad1;
Uint64 ContentHash;
};
MGP_ASSERT_POD(MGPFramebufferState, 304);
```
The three doc statements this row carries, all of which the P4a row's parenthetical
(解析后的 `ReadSurface`、内联格式、`ContentHash`、`{0,1}`)names one-for-one:
- **Resolved ReadSurface.** `ARCHITECTURE.md:136`: "**client 解析后的 `ReadSurface`**(按结构消灭
read-buffer-shared-FBO 缺陷类)". Header, `MGPipeTypes.h:359-360`: "The RESOLVED read surface, not an index.
This is what structurally closes the read-buffer-shared-FBO defect class." (That defect class is the one my
memory file `read-buffer-shared-FBO` records as landed on `dev@bc2d698b`; P4a makes it unrepresentable.)
- **Inline formats.** `ARCHITECTURE.md:136`: "`MGPSurface::InternalFormat` 内联(四个跨对象 mask 推送时零查表)".
- **ContentHash, two jobs.** `ARCHITECTURE.md:136`: "`ContentHash` 既是 server 的 render-pass memo 键也是
client 的发射抑制器". Header, `MGPipeTypes.h:366-369`: "Two jobs …: the server's render-pass memo key, and the
CLIENT's emission suppressor — an unchanged hash means this record is not sent at all. The same pattern is
mandatory for every kVarTail set_* below, or 26.2's redundant glBindSampler traffic reappears as a
variable-length record per batch."
- **`{0,1}`.** `ARCHITECTURE.md:39`: "保留句柄:`{0,0}` = null;**`{0,1}` of `Framebuffer` = 默认帧缓冲**(退役
Espryt 四处 `pDefaultFramebufferInfo->defaultFBO` 身份比较)". In the tree:
`MobileGL/MG_Pipe/MGPipeHandles.h:70-71` `kMGPipeNullHandle{0,0}` / `kMGPipeDefaultFramebuffer{0,1}`, with the
comment at `:66-69` naming the four identity comparisons that retire. Related: the default framebuffer's
geometry stops being written by the swapchain — `ARCHITECTURE.md:281` (`OnSurfaceChanged`) and
`ARCHITECTURE.md:574`: "`pDefaultFramebufferInfo` 由保留句柄 `{0,1}` + `OnSurfaceChanged` 取代" — which is
one of the four process globals `inproc` needs gone.
**`MGPSamplerDesc` — 32 B, `MGPipeTypes.h:283-287`**, with the `borderColorForm` requirement stated twice.
`ARCHITECTURE.md:133`: "`SamplerParameters` 逐字节过线**含 `borderColorForm`**(三种 border color 表示永远都被
数值填满,没有它后端无法在 `Iiv`/`fv` 或 `VkBorderColor` 家族间选择)". Header `:279-282` says the same in
English and adds "Carried as a blob until P0.5 gives it a value header" — **P0.5 has landed**, so the blob is
the P0.5-extracted `SamplerParameters` of `MobileGL/MG_Pipe/MGPipeValueTypes.h` (which also holds
`BorderColorForm`, per `ARCHITECTURE.md:262`'s extraction list).
```cpp
struct MGPSamplerDesc { MGPipeHandle Cso; MGPBlobRef Parameters; }; // 32
```
**`MGPSamplerView` — 36 B, `MGPipeTypes.h:293-304`** and **`MGPTextureParams` — 32 B, `:307-318`**:
```cpp
struct MGPSamplerView {
MGPipeHandle Cso; MGPipeHandle Texture;
Uint32 InternalFormat; // aliasing format for glTextureView
Uint8 Target; Uint8 Pad0[3];
Uint16 MinLevel, NumLevels, MinLayer, NumLayers;
Uint16 Samples; Uint8 FixedSampleLocations; Uint8 Pad1;
}; // MGP_ASSERT_POD(..., 36)
struct MGPTextureParams { // "Per texture OBJECT, independent of any view."
MGPipeHandle Res;
Uint16 BaseLevel, MaxLevel;
Uint8 Swizzle[4];
Uint8 DepthStencilMode;
Uint8 ForceResync; // mirrors m_forceTextureParamsResync
Uint8 Pad0[2];
Float MinLod, MaxLod, LodBias;
}; // MGP_ASSERT_POD(..., 32)
```
`ARCHITECTURE.md:134`: "view 只带视图限制(min/num level、min/num layer、别名格式);纹理参数(base/max level、
swizzle、depth-stencil mode、LOD 钳、`ForceResync`)挂在纹理对象上". `ForceResync` exists for
`RequireImageBindableStorage` (`ARCHITECTURE.md:100`; header `:312-313`: "the widened-channel carrier needs a
swizzle override that the frontend params version does not move for") — i.e. it is the one field that must move
**without** a frontend version bump, and the new red-before scenario is precisely its habitat.
**The three `kVarTail` set headers — all 16 B, all `Start/Count/ContentHash`** (`MGPipeTypes.h:440-468`):
```cpp
struct MGPBoundView { MGPipeHandle View; MGPipeHandle Texture; Uint32 Unit; Uint32 Pad0; }; // 24
struct MGPSamplerViews { Uint32 Start, Count; Uint64 ContentHash; }; // 16
struct MGPSamplerStates { Uint32 Start, Count; Uint64 ContentHash; }; // 16 (tail: MGPipeHandle[Count])
struct MGPImageView { MGPipeHandle Res; Uint32 Unit; Uint32 InternalFormat; Uint32 Layer;
Uint16 Level; Uint8 Layered; Uint8 Access; }; // 24
struct MGPShaderImages { Uint32 Start, Count; Uint64 ContentHash; }; // 16
```
**No stage dimension**, and this is a design ruling not an omission — `ARCHITECTURE.md:99`:
> `SetSamplerViews` / `BindSamplerStates` **没有 stage 维度**:MobileGL 的纹理单元空间是合并的
> (`TextureState::m_textureUnits` 是 192 个单元的一个数组,每 stage 32 只是广告数字),同一单元可被两个 stage
> 采样;stage 只在目标 API 需要时由 server 从反射归档推导。
Repeated at `MGPipeTypes.h:429-431` and again as an explicit non-migration at `PipeCalls.def:182-183` ("the
stage dimension of set_sampler_views … MobileGL's texture unit space is merged, not per stage").
**`MGPProgramDesc` — 192 B, `MGPipeTypes.h:323-335`**:
```cpp
struct MGPProgramDesc {
MGPipeHandle Cso;
Uint32 StageMask; // == GetLinkedShaderStages()
Uint32 GlobalUboSize;
Uint32 ReservedNumSamplesOffset;
Uint8 SpirvStatus; Uint8 NativeFloat64; Uint8 PointSizeDemoted; Uint8 EnableSpirvValidation;
MGPBlobRef Spirv[6]; // per stage
MGPBlobRef Reflection;
}; // MGP_ASSERT_POD(..., 192)
```
`ARCHITECTURE.md:135`: "逐 stage SPIR-V blob ×6 + 反射归档 blob + `StageMask`/`GlobalUboSize`/
`ReservedNumSamplesOffset` + 四个状态字节,§7".
**`MGPGlobalConstants` — 40 B, `MGPipeTypes.h:507-513`** — "Covers the DEFAULT UNIFORM BLOCK only (D6)":
```cpp
struct MGPGlobalConstants { MGPipeHandle ShaderCso; Uint32 Version; Uint32 Pad0; MGPBlobRef Blob; };
```
`ARCHITECTURE.md:143`: "`(ShaderCso, Version)` 键控,每 program 每帧至多一次". `ARCHITECTURE.md:102`:
"`SetGlobalConstants` 只覆盖默认 uniform block(D6):`globalUboScratch` 是 link phase B 的 CPU 数组,没有 GL
name、没有 `BufferObject`."
**`MGPResourceDesc` — 88 B, `MGPipeTypes.h:150-176`** — already carried by P3a for buffers; P4a adds the texture
and renderbuffer discriminants. `ARCHITECTURE.md:130`:
> buffer / 全部纹理 target / renderbuffer 一个判别式 create/respecify 形状;`BindMask` 的 `ELEMENT_ARRAY` 位是
> 索引镜像的开关;`ImageBindableHint` 预防性分配 image-bindable 存储;`ViewOf` 是纹理视图的存储属主(server 侧
> keep-alive);`BufferForTexBuffer/BufOffset/BufSize` 实时解析(`kMGPipeWholeBuffer = ~0`)。**Renderbuffer 保持
> 独立类**(自己的 format-capability target、`ComponentSizes`、twin)
Texture-relevant members, from the header: `Target` ("Buffer | Tex1D..TexCubeArray | Tex2DMS.. | Renderbuffer |
TexBuffer", `:152`), `StorageKind` (`== TextureStorageType`), `InternalFormat` ("already resolved to an
uncompressed fallback by the client", `:158`), `Width/Height/Depth`, `ArrayLayers/Levels/Samples`,
`FixedSampleLocations/Immutable`, `HasDefinedContent`, `ImageBindableHint` ("client-side everImageBound;
pre-emptive allocation", `:165`), `GlNameForDiag` (**diagnostics only** — `:167-169`: "A GL name is NEVER an
identity, never a memo key and never part of a content hash"), `ViewOf`, `BufferForTexBuffer`,
`BufOffset/BufSize`, `kMGPipeWholeBuffer = ~0ull` (`:177`).
**`kNeedsAck` does not extend to textures.** `ARCHITECTURE.md:294`: "纹理分配的 OOM 在 monolith 里就已推迟到
sync 时刻(`glTexImage*`/`glTexStorage*` 只 `MarkStorageDirty`,Espryt 惰性分配;连 `glRenderbufferStorage*` 也在
`SyncToBackend` 里惰性做),拆分不改变可观察行为,**这批不同步 ack**." And `:295`: "**唯一允许同步 ack 的入口是
`glBufferStorage`**". The per-record predicate is `MGPipeResourceRespecifyNeedsAck(desc) == (desc.Immutable != 0)`
(`MGPipeTypes.h:680`) — P4a must not widen it. `MEASUREMENTS.md:83` is the corpus evidence: 0 OOM-probe idioms
in 41 fixtures.
**Transfer payloads P4a's texture path needs** (`MGPipeTypes.h`): `MGPSubRegion` 40 (`:607-614`), `MGPSubData` 72
(`:636-648`), `MGPSubDataComplete` 24 (`:686-691`), `MGPCopyRegion` 64 (`:708-716`), `MGPMipPlan` 16 (`:741-745`),
`MGPReadbackInfo` 64 (`:748-756`, "read_pixels and get_texture_image share one shape; both answer into a reply
slot", `Res` null for read_pixels).
**The blob rule** — one rule, stated on `MGPVertexElements` (`MGPipeTypes.h:254-265`) and repeated on `MGPSubData`
(`:624-635`): `Blob.Size` is the record's own statement; a **non-zero** size disagreeing with what the other
fields describe is `Fatal{ProtocolCorruption}` and the call is refused; a **zero** size means "this record does
not declare its blob", which is what a monolith emission is, and is not a fault. Every new P4a `kHasBlob` record
(`CreateShaderState`, `SetGlobalConstants`) obeys it. `ID-8b` restates it as an integration invariant: "one Blob
rule (0 = not declared)".
**Slot bounds.** `MobileGL/MG_Pipe/PipeApply.h:112-113`: `kMGPipeMaxResourceSlots = 1u << 20`,
`kMGPipeMaxVertexElementsSlots = 1u << 16`; `:97-111` explains that a slot at or above the bound is
`Fatal{ProtocolCorruption}` **and never a resize**, because the applier's tables are grown *by* the slot index.
P4a adds record tables per new kind and must set each bound the same way, with the same reasoning about the
record's own size. Related trap from P3a's final review (`MEASUREMENTS.md:507`): the client-minted
`VertexElementsCso` slot had **no backend-neutral death path**, so Magma leaked a slot per VAO and `Fatal`d past
65536 slots. **Every kind P4a mints needs a death path that does not depend on which backend is loaded.**
**Composite band.** `MGPipeHandles.h:83-96`: `kMGPipeShaderCsoSlotLimit = 1u<<20`,
`kMGPipeShaderCsoCompositeSlotBase = limit - (limit>>4)` (the top 1/16), `MGPipeIsCompositeShaderSlot(slot)`,
plus `static_assert` that the band does not swallow ordinary program slots. Doc: `ARCHITECTURE.md:39` "…
`ShaderCso` slot 空间的高 1/16 保留给 program pipeline 合成体".
### 2.2 The texture path (`ARCHITECTURE.md` §6, `:247-256`)
Seven statements, all binding on P4a's `resource_*` half:
1. **`glTexSubImage*` does not reach the backend table at all** (`:249`). "全部纹理上传由 Espryt 在 sync 时刻按
**累积**区域做,那里跑 `MipmapStorage` 的 96-rect 级联合并与 `summedArea*4 >= unionArea*3` 的 union-box 回退,
并在 unpack ring 可用时刻意塌成一个 box——Mali 按**作业数**给上传计价,~100 个精灵 rect 对一个 union box 实测
+6 ms/frame。逐 `glTexSubImage` 发一条记录会精确复现那个形状。" This is the explicit exception to §5.1's
"GL-call-time push" rule: `ARCHITECTURE.md:157` — "**只有今天就在 GL 调用时刻分发的资源 op 在 GL 调用时刻推送**
——即 `BufferBackendOps` 的七个 hook。**纹理 subdata 不在此列**(§6)."
2. **Accumulate client-side, emit one record at the next validate/flush point** (`:250`): "client 在自己的
`MipmapStorage` rect 模型里累积,在**下一个 validate / flush 点**把合并后的形状作为**一条**
`ResourceSubData` 发出。`MOBILEGL_PIPE_STATS` 单列逐帧发射次数与上传作业数
(`TextureUploadEmissions/Box/Rect/Jobs`)."
3. **Union box AND region list both travel; the server picks** (`:251`): "**同时携带 union box 与 region 列表,
由 server 选上传形状**:决策留在付 GPU 代价的那一侧。实测:vanilla 世界同样 185 次发射,Espryt 的整 box 路径
每帧 635 KB 纹素、Magma 的 rect 路径 40 KB,16×." The measured baseline is `MEASUREMENTS.md:52-53` and the
reading at `:66`. Payload comment `MGPipeTypes.h:616-618` says the same, plus "Mali prices texture upload by
JOB COUNT".
4. **Strides carried, not inferred** (`:252`): "`MGPSubRegion` 显式携带 `SrcRowStride/SrcSliceStride`,
`MGPSubData::SourceIsVerbatimLevelShadow` 显式携带原来由 `uploadData == mipData` 指针比较回答的问题 … Espryt
的上传路径改为从描述符取步长,`UNPACK_ROW_LENGTH` 从 `SrcRowStride/bpp` 设。形状照抄已存在的
`UnpackStagingBlock`(ring 路径本来就紧密重打包、不发 `glPixelStorei`)." Note this is also the **one item
moved out of the Espryt do-not-touch list**: `ARCHITECTURE.md:321` — "从'不动'里移出的一项:Espryt 的 sub-rect
上传判定与跨步计算(§6,从描述符取步长)."
5. **Dirty-ownership inversion** (`:253`): "client 保留 rect 模型、维护一份发射游标、发射后清自己的标志,server
从不碰 client 的标志。安全,因为 `MG_Impl` 里没有任何 `IsStorageDirty/GetStorageDirtyRects/
GetStorageDirtyRegion` 调用点(前端从不读自己的 dirty 状态)。逐 level 'server 权威位'与纹理 ack 协议因此不必
存在。" (`ROADMAP.md:23` puts "dirty 归属反转(按存储属主键控的发射游标)" in the **P3b/P4b** row — so the
*cursor* is P3b/P4b; P4a lands the descriptors it keys on. Say which in the brief.)
6. **The cursor's key** (`:254`): "`(storageOwnerHandle, ownerUploadTarget, ownerLevel)`:`TextureObjectView`
把 dirty 查询/清除全部转发给属主并做索引重映射,view 与属主共用同一份 dirty 状态。门:通过 view 上传、经属主
采样(及反向),跨 draw 边界各一次."
7. **Two backend shadow writers, and what stays client-side** (`:255-256`): CPU-fallback mip generation
(RGB16F/RGB32F) → `OnTextureWriteback`; `glCopyImageSubData` destination mirror → "CopyImage 镜像搬到 client".
"Unpack PBO 完全在 client 解析;压缩纹理永不到达后端;`glCopyTexSubImage*` 与 `glClearTexImage` 整体留在
client(今天就是纯前端操作:借一次 `ReadPixels` 进 CPU scratch 再写 shadow),拆分后恰好是一次阻塞 ReadPixels
round trip,脏区按普通 subdata 下发."
**Verify's retain mode** is the gate for (3): `ARCHITECTURE.md:512` — "**保留模式**:消费即清的组(纹理 dirty
rect)发射后无法重算,verify 时 tracker 保留清除前的集合并比对发射出去的 `(UnionBox, RegionCount, Regions[])`."
And the shape gold standard: `ARCHITECTURE.md:513` — "**`TextureUploadShapeScenario`** 把逐纹理逐帧的上传形状
(box vs N region、作业数)录金标比对——+6 ms 悬崖由形状相等把关,SSIM 对它完全不敏感." (`ROADMAP.md:23` lists
`TextureUploadShapeScenario` in the **P3b/P4b** gate cell with "形状金标,Mali 帧时增量必须发布"; P4a's texture
`resource_*` is what makes it meaningful, so expect to build it in P4a and gate on it in P3b/P4b — resolve this
in the brief.)
### 2.3 Sampler-view resolution stays on the client (`ARCHITECTURE.md` §5.5, `:204-206`)
> GL 是每 unit 每 target 各一个绑定;shader 看见哪一个取决于 sampler uniform 类型、mipmap 完备性
> (`IsMipmapCompleteForFilter`、`SamplesAsIncompleteTexture`)与 `IsUndefinedDefaultTexture`。gallium 的"每槽一个
> view"就是解析后的形态,解析留在 client 并带自己的 memo(~40 行搬迁)。**两处后端特定后处理留在 server**、作用于
> 已解析集合:Espryt 的 raw-depth-fetch sampler 替换、Magma 的 feedback-loop 检测。
Espryt's raw-depth-fetch sampler is a live `SharedPtr<SamplerObject>` today:
`MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:61` (`static SharedPtr<MG_State::GLState::SamplerObject>
g_rawDepthFetchSamplerState`), constructed at `:208-217`. `ARCHITECTURE.md:323` puts its nativisation in the
same bucket as Magma's placeholder textures: "Espryt 的小号同类:`g_rawDepthFetchSamplerState` → 后端原生
sampler." (`ROADMAP.md:23` assigns "raw-depth-fetch sampler 原生化" to **P3b/P4b**.) It is a **purity-gate
blocker**: a `MG_State::GLState::SamplerObject` inside `MG_Backend` is exactly what gate B greps for.
### 2.4 Lifetime, ordering and the composite resolver (`ARCHITECTURE.md` §5.6, `:208-212`)
- `:210` — "resource_create 在前端对象构造时发,存储由 `resource_respecify` 惰性定义;`resource_destroy` 在析构时
发。**三条顺序约束由 payload 表达**:view 先于存储属主销毁(`ViewOf` + server keep-alive)、**FBO attachment
钉住纹理(surface handle 隐含 keep-alive)**、buffer texture 钉住 buffer(`BufferForTexBuffer`,范围实时解析)."
Two of the three are P4a's.
- `:211` — share group: one screen, one context, one flow; `eglMakeCurrent` is a flow ownership transfer emitted
under the existing `EGLOperationMutex`.
- `:212` — **the composite resolver**, in full:
> program pipeline 合成体:`GLContext::GetProgramForDraw()` 今天就完全在前端合成(join、签名查 cache、
> `Link(true)`)。tracker 拿到 `SharedPtr<ProgramObject>` 推**一个** handle,slot 从 `ShaderCso` 保留高位段分配,
> pipeline cache 淘汰时释放 slot、`gen++`、发 `delete_shader_state`。合成体从不过线,server 不需要任何"解析后的
> draw program"钩子;副带收益是阻塞的 `JoinLinkAndSpirv()` 离开 server 的 draw path。
Coverage backs this: `MobileGL/MG_Pipe/Coverage.def:100` `X(GetProgramForDraw, SetDrawProgram)` and `:101`
`X(GetProgramObject, CreateShaderState)`; `GetProgramObject` is one of the seven **sticky** fields
(`Coverage.def:147`, "keyed by GL name: an object lookup, not verb state").
### 2.5 Ordering invariant and the emission suppressor (`ARCHITECTURE.md` §5.4)
`:196`, the D-B3 norm, verbatim:
> **一条 verb 的全部 `set_*`/`bind_*` 必须在该 verb 之前完成;server 在 verb 处、从它此刻持有的全部已推送状态
> 惰性特化 shader 与 pipeline。除"资源 create 先于对它的 bind"外,`set_*` 之间没有顺序要求。**
The recommended order (framebuffer → program → texture/sampler/image/buffer/global constants → render
state/dynamic → vertex elements/buffers/index/attrib defaults → patch/XFB → verb) is "只是代码组织,不是契约".
`:196` also names what lazy specialisation retires: "退役 Espryt 的 fragColor 重推导 workaround、`g_broadcastMemo*`
与 `ImageUnitFormatsStillMatch` 的机制是惰性特化,不是调用顺序" — (`ROADMAP.md:23` schedules the actual deletions
of "fragColor 重推导 workaround 与 `g_broadcastMemo*`" in **P3b/P4b**). The live site:
`MobileGL/MG_Backend/DirectGLES/Managers.h:2030` `Bool ImageUnitFormatsStillMatch() const;` with 20 lines of
rationale at `:2010-2029` (format-less image uniforms are compiled against the *binding*).
`:200`, the four merge rules, including the fourth that P4a's three var-tail sets live or die by:
> **集合 hash 抑制器**——每条 `kVarTail` `set_*` 在 client 算已解析集合的 xxHash,未变不发。最后一条是从后端搬到
> client 的 ~175 行去抖(`UnitBindingsSnapshot`/`PairingsIntact`/`g_fboTextureSyncList` 族)的载体:
> `GetTextureBindGeneration()` 在冗余重绑时也 bump(MC 26.2 每次纹理单元切换都重绑同一个 sampler),没有抑制器
> 每个 batch 都会重发一条几百字节的变长记录并冲掉 server 的两个 memo。
Also `:200` first three rules: 整块结构优于逐字段; high-water marks (`GetTouchedBindPointCount`,
`GetMaxTouchedUnit`) stay in the tracker walk and are directly the `count` argument; only the program-resolved
set is emitted (`uniformSamplerOrImageUnitIndex`).
### 2.6 Dirty bits P4a's families hang off (`ARCHITECTURE.md` §5.2, `:161-172`)
| bit | class | shutter |
|---|---|---|
| `NEW_SHADER`, `NEW_SHADER_BINDINGS`, `NEW_GLOBAL_CONSTANTS` | value | link / image-unit / backend-state / block-binding / uniform-write-set / UBO-content versions (`:165`) |
| `NEW_FRAMEBUFFER` | object | **`FramebufferState::m_anyAttachmentGeneration`**(new) + object/slot version → recompute `ContentHash` (`:168`) |
| `NEW_SAMPLER_VIEWS`, `NEW_SAMPLERS`, `NEW_SHADER_IMAGES` | object | **`TextureState::m_anyTextureContentGeneration` + `m_anyTextureParamsGeneration`**(new) + bind/sampling-resolution generation → walk the `GetMaxTouchedUnit()` prefix, recompute the set hash (`:169`) |
`:172` — the five aggregate generations all sit on existing bump points (~20 lines) and turn the object-class
shutter from "每 validate 走查 192 单元 / 84×4 绑定点 / 32 属性 / 40 attachment" into one `Uint64` compare;
"对象类不能靠轮询逐对象版本(没有聚合能回答'有没有哪张已绑定纹理动了',这正是 Magma 不得不用有损
`sampledContentSum` 的原因)".
Completeness is a **gate**, `:174`: `scripts/gen_pipe_dirty_surface.py` enumerates every mutator in
`MG_Impl/GLImpl` → the aggregate generation it must bump; unmapped, or a row naming a mutator that no longer
exists, fails. P3a widened the scan root to `MG_State/GLState` (**G9**, `BRIEF-P3A.md:166`; result
`MEASUREMENTS.md:376`: 75 mutators all mapped, 0 COARSE / 0 UNDECIDED, plus 21 self-test negative controls).
P4a's new generations land in that table or the gate goes red.
`:176` — the three wrapping `Uint16`s are widened **at the tracker boundary** (`m_lastPushed[]` is the tracker's
own field, `MG_State` is not changed); wrapping is locally harmless (one extra push, never a missed one) and is
swallowed by the set-hash suppressor.
### 2.7 Shader state (`ARCHITECTURE.md` §7, `:258-265`)
- `:260` — "**`CreateShaderState` 的 payload 是逐 stage SPIR-V + 反射归档(`LinkArtifacts` + `SpirvArtifacts`
全结构体),不是源码**。'server 从源码重新 link'这条路显式关闭:链接真 `ProgramObject` 就链接 glslang。glslang
全在 client,SPIRV-Cross(`TranspileSpirvToEssl`)全在 server,文件级切割。没有 `MOBILEGL_IPC_PROGRAM` 开关、
没有 server 侧 compile pool." (`ARCHITECTURE.md:608` repeats the non-knob: "显式不设立:`MOBILEGL_IPC_PROGRAM`
(没有 relink 档)".)
- `:261` — the archive mechanism: `Visit()` + a `sizeof` trip wire
(`static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE)`), one field table serving both directions.
**The must-cover list, verbatim**: "必须覆盖四个 `ResourceReflection`(各带 `TypeFacts`)、
`uniformSamplerOrImageUnitIndex`、`uniformBlockBinding`、`shaderStorageBlockBinding`(按名字)、
`explicitOpaqueUniformBindings`、`xfbVaryings/xfbStrides/xfbPackedStride/xfbNeedsScatteredCapture`、
`computeLocalSize`、GS/TCS/TES 事实、`usesReservedNumSamples`、`uniformOffsets`。`XfbVarying` 带两套拼写
(GL 名字 + block 实例/成员/元素)."
- `:262` — **P0.5 is the hard precondition and it has landed**: the five reflection types live in
`MG_State/GLState/ProgramState/ProgramArtifacts.h`. "没有这一步,P7 的 `nm -D | grep glslang` 判据不可达."
- `:263` — **server-side lazy specialisation (D-B2)**, and the eight extra inputs a backend program still
depends on: "draw FBO 的 snorm/unorm clamp mask、fragColor 广播数、storage-block 绑定签名、atomic counter 集、
活的 image 格式、patch 参数;Magma 另加 FragCoord-Y-flip 的 default-FB 高度与 XFB 布局",
"`create_shader_state` 发布**制品**,server 在 verb 时刻从已推送状态特化".
- `:264` — **link failure needs no synchronous return**: "今天只是一行 `MGLOG_E` 加 bind program 0 的空 draw,
`GL_LINK_STATUS` 永不撤回,同步查询由 client 从 `ProgramObject` 回答。`OnLog` 逐字复现——由此要求日志按严重级
分级(§8.3)." The log grading rule is `:283`/`:297`: ≤WARN lossy, ≥ERROR lossless + rate limited, because "后端
link 失败只以一行 ERROR 呈现".
- `:198` — the async win P4a unlocks: "`create_shader_state` 从编译池的终止 continuation 发出(不是从 draw),
SPIR-V 在首个用到它的 draw 之前到达 server——monolith 拿不到的异步收益."
- `:265` — Magma's two internal shaders baked to in-tree SPIR-V is **P7**, not P4a.
### 2.8 The reverse-channel callbacks a texture / FBO needs
`ARCHITECTURE.md:269-286` (§8.1), and the tree: `MobileGL/MG_Pipe/MGPipeCallbacks.h:27-51`, ten function
pointers with `kMGPipeCallbackCount = 10` and a `static_assert` on the struct size (`:55-57`). Of the ten, the
ones P4a's families produce or consume:
| callback | header | why P4a |
|---|---|---|
| `OnGpuWritten(res, rangeCount, ranges)` | `MGPipeCallbacks.h:31` | ARCHITECTURE `:276`: replaces 6 `MarkGpuWritten`; the client builds a conservative pending set per draw/dispatch emission — a **narrowing** channel |
| `OnTextureWriteback(res, box, bytes)` | `:33` | `:278` "CPU 回退生成 mip 的纹素(唯一生产者)" |
| `OnTexturePullRequest(res, target, firstLevel, levelCount, pullSerial)` | `:37-38` | §8.4, the only new stall class |
| `OnMipLevelsGenerated(res, base, count)` | `:41` | `:280` shape only, never bytes: monolith's `EnsureGenerateMipmapStorageAllocated` also only allocates and `MarkStorageDirty(false)` |
| `OnSurfaceChanged(info)` | `:44` | `:281` retires the swapchain→`pDefaultFramebufferInfo` layering inversion; pairs with handle `{0,1}` |
| `OnGlError(code)` | `:29` | `:275` **must be ordered w.r.t. the command stream** or `glGetError` answers wrong |
| `OnCapsInvalidated()` | `:45` | `:282` two `InvalidateCompileEnv` sites |
| `OnLog(level, text)` | `:47` | `:283`, and §7's link-failure requirement |
| forward terminator `ResourceSubDataComplete` | `PipeCalls.def:136`, `MGPipeTypes.h:686-691` | §8.4 item 4 |
**§8.4 — the only new stall class (D-B6), `ARCHITECTURE.md:299-308`.** Three causes a server that keeps no
texels must ask for a level back: "`RequireImageBindableStorage` 的 re-dirty、整格式再生、view 源重铸". Four
mitigations, all four at once:
1. Prevention: `everImageBound` → `ImageBindableHint` on every `ResourceCreate/Respecify`.
2. Async: the server marks the twin not-ready and the client re-sends at its next publish; **the blocked thread
is `mgl-srv-apply`, not the application thread**.
3. Bounded retention, default off: `MOBILEGL_PIPE_TEXEL_RETAIN_MB = 0` — "`MipmapStorage` 保有每 level 完整 CPU
影子,拉取总能被服务,缓存买的是延迟不是正确性".
4. **Explicit terminator**: `ResourceSubDataComplete(res, target, firstLevel, levelCount, pullSerial)`, "**可携带
零个 region**"; on zero regions the server continues with allocated-but-empty storage (monolith's own
behaviour) and logs `MGLOG_W`. "没有终止符 apply 线程会永久 park."
Gate (`:308`): "`TextureRemintPullScenario`(含无解用例,**且在终止符落地前必须是红的**);拉取次数逐 trace 用例
发布。本设计从不声称'零 round trip',它测量并公布." — a second red-before scenario in P4a's blast radius, and
its rate is `ROADMAP.md:85`'s open question 2 ("真实语料上纹理重铸拉取的发生率… 若 MC/Iris fixture 上非平凡,保留
LRU 从默认 0 升为强制并拿真预算").
**§8.2 — ordering is a correctness requirement**, `ARCHITECTURE.md:290`: "每一次 `WritebackFromBackend` 后面都
紧跟 `BumpBufferMutationEpoch()` … 写回的 epoch bump 必须在任何后续读该 handle 的命令之前被 server 应用。
**反向通道需要与正向通道相同的有序保证。**"
**§8.1's remaining-95-sites paragraph, `:286`** — the rules P4a inherits: `MarkStorageDirty` is mostly
server-local bookkeeping (zero messages); backend-invented frontend objects (Magma placeholder textures,
swapchain default-FB placeholder) become server-native; `SetBackendResource` is deleted **except** that
`D-K (P3a)` did not delete it (see §5 traps); "`SetBackendStateMemo`(前端 VAO 里存后端堆裸指针)直接删除;
`SetBackendHashMemo/AuxMemo` → server 侧 per-slot 字段".
### 2.9 The Track H census rows P4a pays (`ARCHITECTURE.md` §9.5, `:363-365`)
The census's single fact, verbatim (`:365`):
> 统一事实:每个进入 memo 键的版本计数器要么是回绕 `Uint16`,要么根本不会被它害怕的那个 mutation bump;身份比较
> 是堵回绕洞的补丁。`{slot, gen}` + 显式 destroy 让 **11 条直接删除** … **2 条** server 删除但去抖搬到 client
> (§5.4),**7 条重键**成更便宜的比较(`StampSyncedFBO` 四元组 → `ContentHash` + server 私有
> `attachmentRemintEpoch`;`ResolvedTextureBindingMemo` 9 键 → `(shaderCso.slot, viewSetSerial)`;
> `SetupDrawSnapshot` 的 ~14 探测字段与两个有损求和 → 三个 handle + 两个 server 纪元 + dirty mask;
> `VertexInputStateFactory::ComputeHash` 里的 lifetimeId → `gen` **混进** server 侧每个 content hash),
> **1 条**(D18)原样不动。
Ledger to date: **P2** paid all 11 direct deletions plus 2 of the 7 re-keys (`MEASUREMENTS.md:425`); **P3a** paid
the last direct deletion (`ConvertedVertexStreamKey`'s `sourcePin`), retired 5 more twin members *on the handle
arm only*, and paid 4 re-keys including **`ResolvedDrawBuffers`** (`MEASUREMENTS.md:429-431`, `ROADMAP.md:19`).
**Which memos remain, and whose row they are.** `ROADMAP.md:23`, the **P3b/P4b** cell, verbatim:
> memo 重键(`ResolvedDrawBuffers`、`ResolvedTextureBindingMemo`、`SamplerPassMemo`、image sweep、program
> registry…);server 删 `g_unitTextureSyncList`/`g_fboTextureSyncList`/`DirectGLES.cpp` 的 ~115 行 unit-bindings
> epoch 推导,**同时**在 Tracker 落地集合 hash 抑制器;dirty 归属反转(按存储属主键控的发射游标);
> `MGPSubRegion` 跨步描述符改造;XFB scatter 搬到 client;删 fragColor 重推导 workaround 与 `g_broadcastMemo*`;
> raw-depth-fetch sampler 原生化;回读 / pack state
`ResolvedDrawBuffers` in that list **is already done** (P3a, `MEASUREMENTS.md:431`: "`configVersion` →
`{elementsHandle, elementsSerial, buffersSerial}`,`Entry` 与 `iboFrontend` 各加一个 `MGPipeHandle`"). So the
P4a/P3b/P4b boundary is: **P4a lands identity + descriptors; P3b/P4b lands the deepening re-keys.** The sites
the later phase will touch, located for you now (so P4a can decide what to leave reachable):
| census row | site in the tree |
|---|---|
| `ResolvedTextureBindingMemo` (9 keys → `(shaderCso.slot, viewSetSerial)`) | the unit/FBO texture sync lists, `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:1814-1830` (`g_unitTextureSyncList` + 6 key statics; `g_fboTextureSyncList` + 5) and the two memo-hit tests at `:1879-1885` and `:1950-1955` |
| `SamplerPassMemo` | `MobileGL/MG_Backend/DirectGLES/Managers.h:1913-1924` (the struct, `kMaxEntries = 16`, keyed on contextId / unitBindingsEpoch / samplingGeneration / backendStateVersion / textureContextGeneration + a row snapshot), accessor `:2001`, member `:2117`; its invalidation contract is documented at `:1895-1912` |
| image sweep / `ImageUnitFormatsStillMatch` | `Managers.h:2030-2032` + `ComputeImageUnitFormatSignature()`; rationale `:2010-2029` |
| program registry | `Managers.h:2130` `extern TwinRegistry<ProgramObject, BackendProgramObjectImpl, MGPipeKind::ShaderCso>` |
| `StampSyncedFBO` 四元组 | the FBO trio is named in the code at `DirectGLES.cpp:1936` ("heap address (pointer + slot version together, the StampSyncedFBO trio)"); registry `Managers.h:1612` |
| `SetupDrawSnapshot` ~14 probe fields | Magma, **P7** (`ROADMAP.md:24`) |
| D18 container discipline | untouched, `ARCHITECTURE.md:318` |
**The six P2 registries are the six kinds.** `MobileGL/MG_Backend/DirectGLES/Managers.h`:
`:1181` VertexArrayObject→`MGPipeKind::VertexElementsCso`, `:1521` ITextureObject→`Texture`,
`:1612` FramebufferObject→`Framebuffer`, `:2130` ProgramObject→`ShaderCso`, `:2230` SamplerObject→`SamplerCso`,
`:2257` RenderbufferObject→`Renderbuffer`. P3a added the **seventh** table, the first one keyed by a
client-minted handle that travels with the call:
`Managers.h:691` `BackendSlotTable<BufferObject, GLESBufferResource, MGPipeKind::Buffer>` (`ROADMAP.md:19`).
**P4a's job is to do to the remaining five (Texture, Renderbuffer, Framebuffer, SamplerCso, ShaderCso) what P3a
did to Buffer.** The template, its dispatch and the P2/P3a switch live at `Managers.h:303-553`
(`StateBackendObjectRegistry`, `GetOrCreate` routing to `m_slotTable` when `EsprytSlotTablesEnabled()`,
`TwinRegistry` alias that drops the kind parameter in the pull build so the mangled name is the pre-P2 one).
**The recorded P3+ debt this phase inherits**, `MobileGL/MG_Backend/DirectGLES/SlotTables.h:70-77`, verbatim:
> P3+ DEBT, recorded rather than hidden: this header is under `MG_Backend/` and it MINTS handles
> (`MGPipeSlots().Acquire` below) off a frontend `SharedPtr`'s `GetLifetimeId()`. `MGPipeHandles.h:13-16` says a
> handle is minted by the CLIENT and never by the server … This is monolith glue: the minting and the
> lifetimeId → handle resolution both belong on the client, and the backend should receive the handle in the
> verb payload. It is NOT part of "Track H done" and `check_include_closure.py` does not probe `MG_Backend`
> headers, so nothing catches it automatically.
For Buffer, P3a closed exactly that (client mints, the handle rides the call). **Each kind P4a converts closes
one more slice of this debt, and nothing automated will notice if it does not** — make it an explicit review item.
`SlotTables.h:36-68` also states the death protocol the five new kinds must obey: all six re-keyed object
classes raise `MG_State::GLState::NotifyStateObjectDestroyed()` from their destructor, consumed in
`Managers.cpp`, `OnFrontendObjectDestroyed()` drops the twin in **every** holder of the kind and returns the slot;
there is **no** draw-path tick, no creation tick and no sweep on this arm; every table links itself into a
per-table-type list so one notice resolves the handle once, drops the twin in each holder by handle, and frees
the slot last.
### 2.10 The emulation ownership table (`ARCHITECTURE.md` §5.7, `:216-245`)
The rule, `:216`: "**驱动表达不了的变换在 tracker 里 lowering,硬件/驱动强加的变换在 driver 里 lowering。**
只有三个'读前端字节的纯 CPU 变换'下放到 client."
| emulation | owner | what crosses |
|---|---|---|
| client 顶点数组 `(first+count-1)*stride+elementSize` | **client** | bytes via `MGHostSpan`, never a pointer |
| 最大索引扫描 `TryComputeMaxIndexFromHostBytes` (the only unbounded application-pointer read) | **client** | `MGPDrawInfo::MinIndex/MaxIndex`, flag-gated, `~0` = unknown |
| client 索引数组 | **client** | `MGHostSpan` in the var tail |
| `*IndirectCount` count resolution | **client** | resolved `MGPDrawRange[]` |
| primitive-restart rewrite (whole EBO, `kMaxRestartRewriteBytes` = 64 MiB) | **server** | zero wire traffic — reads the index host mirror (§10.3) |
| multi-draw five-tier + flatten (`ResolveTierForBatch`) | **server** | same |
| viewport-array N-pass replay | **server** | nothing new — 16 sets already in the render state |
| fp64 vertex narrowing | **server** | raw bytes; `IsLong` and `Type` travel separately |
| **image-bindable storage widen/split** | **server** | forward `ImageBindableHint`; reverse = texture pull + terminator |
| **generate-mipmap frontend storage** | **split**: client allocates level storage, server generates | `MGPMipPlan`; `OnMipLevelsGenerated` carries shape not bytes |
| **CopyImage shadow mirror** | **client** | only "copy succeeded" — deletes a whole server→client byte channel |
| XFB CPU primitive accounting | **client** | `XfbCpuCapturedVertices` (flag-gated) + `EndStreamOutput`'s `MGPXfbAccounting` |
| XFB scatter read-modify-write | **client** | §8.5 |
| **压缩纹理 / pixel unpack 规整** | **client** | nothing |
The **stale-index discipline is a per-site table, not a blanket rule** (`:235-243`): "client 侧扫描/解析之前要做的
reconcile 必须逐字复现 monolith 的集合" — client vertex arrays: nothing; max-index scan from an EBO:
`SyncPersistentMappedRange()` **+** `SyncGpuWrites()`; max-index scan from a client pointer: nothing;
`*IndirectCount`: **only** `SyncPersistentMappedRange()`, never `SyncGpuWrites()` ("monolith 今天就只做这一个,
加了会给 Create/Flywheel 的每 batch 平白加一次 publish-and-wait"); server-side restart/flatten: reads the
mirror, GPU-writer visibility decided server-locally from `OnGpuWritten`'s narrowed set. Shape of the first two
client reconciles (`:245`): "publish → 等 `appliedSeq` → 排空事件 → 再碰 shadow", gated by
`ClientArrayAfterComputeWriteScenario` (removing the wait must show missing geometry) and by
`roundtrips-per-frame == 0` on the `create-indirect` fixture — both **P8**.
Explicit non-migrations that bind P4a (`ARCHITECTURE.md:104`, `PipeCalls.def:169-183`):
`GetIntegeri_v`/`GetInteger64i_v`/`GetProgramiv`; `ShaderStorageBlockBinding` (folded into the reflection
archive); **`set_pixel_unpack_state` does not exist** ("前端已在 `glTexImage` 时解析压缩格式、强制默认 unpack");
the compressed-format concept; `pipe_transfer`; the stage dimension of `set_sampler_views`.
`MGPPixelPackState` is PACK only (`:140`, D5), and `Coverage.def:170-180` explains why
`GetPixelStoreParameters` is deliberately **absent** from the emitted list: `PipeInputs::m_pixelStore[2]` holds
both halves, so claiming it supplied would blind both the poison and the verify comparator to the unpack half.
### 2.11 The purity gates
`ARCHITECTURE.md:511` (part 1 of the five-part gate), verbatim:
> **接口纯度三道门**(只跑非 verify 构建):**A 门 include 图**——disaggregated 配置编译 `MG_Backend` 时把
> `MG_State/GLState` 从 include 搜索路径移除(`nm --undefined-only` 对"只 include 不调用"是瞎的,而
> `RenderState.h → FramebufferObject.h → TextureObject.h` 正是这种耦合),依赖 P0.5;**B 门符号**——
> `nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空;**C 门未声明**——
> `grep -c 'pGLContext' MG_Backend/` == 0。外加 debug 断言"每个后端 memo 键都是 `{slot, gen}`,永不是裸前端
> 指针",由 `HandleRecycleScenario` 支撑(重键前必须在至少一个后端上是红的)。
Note the A-gate example is **literally P4a's include chain** (`RenderState.h → FramebufferObject.h →
TextureObject.h`). Realisations: G13 (`BRIEF-P3A.md:170`) adds "no `MG_State::GLState` type appears in any
`MGPipeResourceOps` signature" and `check_include_closure.py --mode both --compiler clang++-20 --self-test
--require-all`; P3a's readings at `MEASUREMENTS.md:335-337` (A: 4 probes, 0 skip, 0 problem; C: empty; G13:
`PipeApply.h`'s ops block free of `MG_State`). P13 is where the three gates finally turn green on non-verify
builds (`ARCHITECTURE.md:377`, `ROADMAP.md:30`).
Two byte-level equalities survive everything (`ARCHITECTURE.md:517`):
`MOBILEGL_BUILD_DISAGGREGATED=OFF` ⇒ `nm --defined-only libMobileGL.so | grep MG_Remote` empty and no added
link libraries; `nm -D libMobileGL.so | grep mobilegl_server_main` hits in RelWithDebInfo.
### 2.12 The switch and its bits
`ARCHITECTURE.md:598` — `MOBILEGL_PIPE_PUSH`: pull build `0`, **push build `0x1ff`**
(`kMGPipeSubsystemsMigratedAtP3a`, `MobileGL/MG_Pipe/MGPipe.h:95`, read at `MobileGL/ConfigLoader.cpp:257`).
Bits are allocated in ROADMAP order and **never reused**: `0x01` render state, `0x02` pixel pack, `0x04` patch,
`0x08` vertex attrib defaults, `0x10` residual, `0x20` Espryt slots, `0x40` Magma vertex input, `0x80` resources
(P3a), `0x100` vertex input (P3a); "**位 9..62 留给后续阶段**" — P4a's subsystems take bits 9 and up. Bit 63 is
not a subsystem but the behaviour control `kMGPipeBehaviourNoCsoContentAddressing` (`MGPipe.h:90`).
Precedent for a bit that **requires** another (P3a's bit 8 requires bit 7): `0x17f` prints one ERROR naming the
refusal and falls back to the legacy arm (`Managers.cpp:2312`, `ARCHITECTURE.md:374`, `:598`). P4a's sampler
views plausibly require the texture-resource bit for the same reason (attribute→resource-slot resolution's
analogue), and the arm classification must be **diagnose at bring-up, stop at first lookup** — `SlotTables.h`'s
`ClassifyEsprytSlotArm` / `CurrentEsprytSlotArmVerdict` and the long comment explaining why the stop cannot live
at bring-up (a forked pre-flight child dying on a signal makes the whole lane SKIP green, "which is what
`ROADMAP.md:7` forbids").
Also `ARCHITECTURE.md:590`: `MOBILEGL_PIPE_LEGACY_MEMOS` default ON for P2..P13; `MOBILEGL_PIPE_PUSH=OFF` forces
it back ON with a `message(STATUS)` (`CMakeLists.txt:476-479`) "因为 pull 构建里 pre-handle 臂就是唯一的实现".
And `MOBILEGL_PIPE_HANDLE_ABA_CONTROL` (`:599`) is negative control C: "故意打掉句柄身份,让 `HandleRecycle` 的
ABA 臂重现旧的 A-B-A 污染。**它变绿即为控制失效**" — P4a extends `HandleRecycleScenario` with its own kinds the
way P3a added a buffer case (`ROADMAP.md:19`, `MEASUREMENTS.md:341`).
---
## 3. What later phases expect P4a to leave in place
**P3b / P4b** (`ROADMAP.md:23`, depends on P4a). Deliverables quoted in §2.9 above. Its gate cell, verbatim:
> ~25 个纹理场景、21 个 program 场景 + `MG_Test/ShaderTranspiler`;两台设备 `KHR-GL46.texture_*`/
> `internalformat.texture2d.*`/`shader_image_*`/`packed_pixels` 在 pull 基线 0.5 pp 内;每一个 Iris trace;
> **`TextureUploadShapeScenario`**(形状金标,Mali 帧时增量必须发布);view/owner 发射游标别名场景;verify 保留
> 模式下 subdata 形状逐项相等;XFB 场景 + `capture_special_interleaved_test`
So P4a must leave behind: descriptors and handles that a per-storage-owner emission cursor can key on
(`(storageOwnerHandle, ownerUploadTarget, ownerLevel)`); the `ContentHash` fields the suppressor will latch;
sampler-view/sampler/image sets resolved on the client so the backend memos can be re-keyed onto
`(shaderCso.slot, viewSetSerial)`; and the verify **retain mode** comparison for subdata shape.
**P5** (`ROADMAP.md:21`, depends on P4a): `MG_Remote/Client` emit tables; `Server/PipeApplier` + `ServerLoop`;
one `Init.cpp` hook installing `BackendObject_Remote`; `MGPCaps` snapshot; blocking `read_pixels`; client-side
conservative `MarkGpuWritten`; client-side block-granular persistent-map push; `InProcessTransport` through the
**same G3 codec** as spawn; trace-replay `SPLIT` suffix. Its acceptance includes "未迁移字段读 =
`Fatal{UnmigratedPipeInput}`" and the day-99 first IPC frame. Implication for P4a: every payload it fills must
be transport-ready (flat POD, blob rule, declared counts) because P5 encodes them without re-deciding shapes.
**P7 — Magma** (`ROADMAP.md:24`, depends on P0.5/P2, **parallel** with P5/P6/P8, not on P4a): the other 10
subsystems, `SetupDrawSnapshot` probe fields collapsed to a dirty mask, **placeholder textures nativised
(~120 lines deleted)**, named-UBO host payload (D-B8, `kCapNeedsHostUboBytes`), blit/depth-mipmap internal
shaders baked, `VertexInputStateFactory` raw-pointer writeback deleted, D18 discipline preserved. Gate includes
`nm -D libMobileGLServer.so | grep glslang` empty. Two P4a-adjacent consequences: the content-addressed
vertex-elements CSO table (1024 entries) is P7's, not P4a's (`ARCHITECTURE.md:65`, D-G1); and P4a's shader CSO
must be shaped so Magma's `ProgramFactory` can consume the same archive later (`ROADMAP.md:91`, open question 8:
"一份反射归档能否服务三个消费者").
**P8** (`ROADMAP.md:25`, depends on P6 and P3b/P4b): `MG_Impl/Pipe/HostResolve.cpp`, `MGHostSpan` split fill,
`Server/IndexHostMirror`, **CopyImage 镜像搬到 client**, `draw_vbo` absorbing the multi-draw family,
viewport-array replay validation, **`generate_mipmap` 计划 + CPU 回退纹素**, G3 chunked path, no-present fence
tick + a no-present split case, `kCapDriverOrderedXfbCapture`. **This is the phase that retires P4a's
"emulation 在 split 下显式 Fatal"** — so each Fatal P4a plants must name the emulation and be greppable, and its
gate is "`'^DirectGLES\.Split\.'` 与 `'^DirectGLES\.'` 逐名相同" plus 40-trace split SSIM ≥ 0.99. Also
`ARCHITECTURE.md:391-396` (§10.3): the index host mirror is built out of the `ResourceCreate/Respecify/SubData`
stream P3a/P4a already send — "零额外线上流量、零 round trip" — and is "本设计里唯一的'数据副本'".
**P9** (`ROADMAP.md:26`) consumes the reverse channel P4a produces: `OnTextureWriteback`, `OnMipLevelsGenerated`,
the four texture-pull mitigations + terminator, `OnGlError` ordered + the `glBufferStorage` ack,
`OnCapsInvalidated`, `OnSurfaceChanged`. Its gate: "`TextureRemintPullScenario` 绿且含无解用例(终止符前表现为
apply 线程挂死/超时)".
**P13** (`ROADMAP.md:30`) is where P4a's parked debt actually dies: delete `SnapshotFromGLContext()`'s non-verify
branch, `MGB_CTX`, `MOBILEGL_PIPE_PUSH`, `MOBILEGL_PIPE_LEGACY_MEMOS`; keep `MOBILEGL_PIPE_VERIFY`; delete
`set_residual_value_state`; shrink `MG_Backend`'s `MG_State` includes to `MGPipeValueTypes.h`; **retune surviving
cache capacities with the counters alive** — the named list includes `syncedTextureMemo 8`, i.e. a P4a-owned
cache. Open question 14 (`ROADMAP.md:97`): "推送模型改变哪些按拉取模式调过的缓存命中率。幸存者容量在 P13 重调."
---
## 4. Commit / CI discipline, and the rulings that bind P4a
### 4.1 The per-commit discipline (`ROADMAP.md:7`), verbatim
> 默认 ALL target 必须完整构建;禁止提交热路径插桩(CI grep 门);**每个门必须能因它存在的理由变红**;Windows 机器
> 不是正确性门;设备对比走 reboot-clean + 同热窗口配对 A/B,CPU 定频按项目协议;每阶段出口跑一次五部分门;
> 每阶段性能判据是**逐线程 CPU 时间**。
Also `ROADMAP.md:100`, the no-drive-by rule: "**拆分不借机顺手修 `dev` 的 bug**". P3a honoured it twice — the
`g_uploadRing` reset asymmetry (`MEASUREMENTS.md:519`) and `create-indirect` (`ROADMAP.md:100`); P4a inherits
both the rule and those two open items.
### 4.2 CI (`ARCHITECTURE.md:578`)
`pipe-gates` (`.github/workflows/test.yml:1538`): `gen_pipe.py` regenerate + diff; the stdio-instrumentation grep
gate over `MG_Backend`/`MG_State`; `gen_pipe_dirty_surface.py --check` + `--self-test` (a gate since P2,
`test.yml:1601-1604`); `check_doc_citations.py` (warning level, `--strict` once the docs are final). Separate job
`flatc-check` (`test.yml:304`). Already landed: `include-graph-check` (P0.5), `monolith-symbol-report`,
`build-linux-verify` / `integration-verify` / `retrace-verify` (P1). Generated `.inc` files are **committed to
the tree** and the build never depends on python (`ARCHITECTURE.md:73`, `:431`).
Test-wiring traps, `ARCHITECTURE.md:577`: ctest `ENVIRONMENT` is **replace, not append**; `;` must be escaped;
**the property overrides the job env** — use `mgl_itest_join_environment(... ${MGL_ITEST_COMMON_ENV})`;
`add_trace_replay_test` needs the `SPLIT` suffix (otherwise it collides with the same case+backend) and
`-DTRACE_TRANSPORT=` for `run_trace_case.cmake`.
Commit-message style (my memory, `commit-style`): `[Type] (Scope): description`, single line, never a
`Co-Authored-By`. Milestone flow (`milestone-merge-flow`): commit + push + merge to `dev` + open the next item
without asking.
### 4.3 The user's 2026-09-08 rule — performance is recorded, never gated
`MEASUREMENTS.md:324`, the rule **verbatim in the user's own words** (§15 exists because it was written nowhere
in `docs/Disaggregated/`):
> (a) advance the roadmap as fast as possible without a large performance regression; performance is RECORDED
> against the pull baseline, never a blocking gate in P3a; correctness gates stay.
Its consequences, `MEASUREMENTS.md:326`: part **4** of the five-part gate (`ARCHITECTURE.md:514`) and
`ROADMAP.md:19`'s "MC 26.3 在 Adreno 上 p99 不变" become **measure-and-publish obligations**, not pass/fail;
parts 1, 2, 3, 5 stay hard gates; "一次回归要写下数字与怀疑的成因并带进 P4a 的排期——**唯一不可谈判的是数字必须
真的采到**:没测到的回归不算记录在案。" Same ruling as `ID-6`. `ARCHITECTURE.md:514` carries it too: "**口径
(2026-09-08 起)**:这一条对着 pull 臂**记录**而不阻塞 … 专门的优化阶段排在路线图之后."
**The baseline of record is `MEASUREMENTS.md` §20** (`:436-503`), not §10. §10's numbers are **-O0** and carry an
erratum (`ID-17`; `ROADMAP.md:18`, `:57`). §20's protocol, verbatim at `:438`: reboot-clean, same thermal window,
`tools/device_bench/pin_device.sh` (big cores 1.96 / little 1.55 GHz, GPU maxed, 40 °C gate, `check` before and
after every run, a DRIFT run voided and repeated), two arms back to back, one device at a time, p50/p99 over the
tail 200 frames of `benchmark.json`'s `frameCpuTimesMs[]` computed host-side. Arms in P3a were three: pull APK /
same push APK with `--env MOBILEGL_PIPE_PUSH=0x7f` (the previous phase's boundary) / push APK at the default
mask. **P4a's analogue: pull / `0x1ff` (P3a) / P4a's default mask.**
Numbers P4a is measured against (`MEASUREMENTS.md:444-461`, `:493-501`, `ID-19`, `ID-24`):
- Device p50, `--benchmark-no-finish`: P2's Release boundary **+6–12%** on both devices and both backends; P3a
added ~0 on 26.3 and sodium but **+17–19 points on rd12** (Espryt +30%, Magma +27% total).
- **MC 26.3 p99 on Adreno: pull 25.457 → P3a 26.322 ms (+3.4%)** — the number `ROADMAP.md:19` names, still in
the 21–26 ms band of the adoption baseline at `MEASUREMENTS.md:87` (p99 163→21 ms, 40→115 fps, ~400 MB).
- DriverBench `mc_vanilla_draw` ns/draw at `c20e2f2b`: **T1** (push `0x1ff` − pull) = Espryt **+1048** (+20.5%) /
Magma **+611** (+3.6%); **T2** (`0x7f` − pull) = +349 / +189; **P3a itself = +699 / +422**. Blend-toggle
+5.2% / +2.8%; pass switch ≈ 0; CSO content addressing ≈ 0.
- `MEASUREMENTS.md:503`: "**不钉上限、也不强制上限**(规则 (a));数字发布出来,**让 P4a 自己决定要不要钉**."
The optimisation candidates P3a handed forward (`:501`): per-draw suppression of unchanged vertex-input sets,
and in-place applier record updates.
Reading discipline that must sit **above** the numbers, `MEASUREMENTS.md:440`: `CallClass::AccessorCalls` is a
**static** count at ~10 hot entry points (`MobileGL/MG_Util/Metrics/PipeStats.cpp:16-100`, "那份站点清单本身就是
契约"), so a change that only **moves** a read gets a lower `acc/draw` without doing less work; lead with the six
memo gates' hit/miss and the CPU time series, and re-check the tally constants before quoting `acc/draw`.
DriverBench mechanics (`:503`): its own `build-bench` (the gate builds set `-DMOBILEGL_BUILD_BENCHMARK=OFF`), and
**`DRIVERBENCH_EGL_LIB` must `dlopen` a provider explicitly — never shadow via `LD_LIBRARY_PATH`**, because on a
glvnd system a bare `libEGL.so.1` resolves to Mesa/llvmpipe and silently swaps the GPU for a software rasteriser
underneath the benchmark.
### 4.4 P3a-era rulings that bind P4a
- **ID-6** — performance recorded, not gated; parts 1/2/3/5 stay hard gates. (Same as §4.3.)
- **ID-11 / ID-13 / ID-15, the G5 shape.** G5 is now **eleven** functions, in two ladders, and the ruling is
`MEASUREMENTS.md:509` verbatim:
> **ID-15(取代 ID-13 里"定义在任何 `#if` 之外"那句)。** `Managers.cpp` 把三层 flush 排水梯各带一份、每个预
> 处理臂一份,任一构建只编译其中之一:`#if MOBILEGL_PIPE_PUSH` 下的 `FlushPendingRangesFrom` 是 **push** 构建
> 跑的(legacy 调用点与 `Ops_H_Readback` 都到它),`#else` 里与 `5cb826b0` 逐字节相同的 `FlushPendingRangesNow`
> 是 **pull** 构建跑的;push 构建根本不编译 `FlushPendingRangesNow`。转发函数不可行:G5 的提取器不认预处理,
> 一个转发的 `FlushPendingRangesNow` 会让同名出现两个定义、门直接退出 2(门跑不了)而不是比对。因此**两个名字
> 都是 G5 行**:十一个函数,pull 梯对着 P3a 基线比、push 梯对着钉在 `3e298c9a` 的 sha 比;两条梯都不许漂,也不
> 许彼此漂而门不响。
The ten from P3a: `IsPoolable`, `EnrollIntoPool`, `AcquireFromPool`, `TrimBufferPool`, `ClearBufferPool`,
`ProcessDeferredBufferReleases`, `CreateRingStorage`, `RingAvailable`, `RingAllocate`,
`FlushPendingRangesNow` (`BRIEF-P3A.md:162`, `ID-11`); the eleventh is `FlushPendingRangesFrom` (`ID-8f`).
Sites: `Managers.cpp:1051` (`FlushPendingRangesFrom`, callers `:1721`, `:2044`, `:2766`, `:2904`) and
`:1316` (`FlushPendingRangesNow`, callers `:1723`, `:2906`) per `MEASUREMENTS.md:521`. **P4a must not touch
any of the eleven**, and if it adds an untouched region of its own (the Espryt do-not-touch list at
`ARCHITECTURE.md:318` is the candidate pool: the three rings, the pool, seven fallback-repack paths,
`m_backendColorSlots`, the three scratch FBOs and their driver-side shadows, `PackState`, all driver binding
shadows, the Adreno disabled-attribute SIGSEGV workaround, the Mali XFB-capture-loss workaround,
`ScopedDefaultUnpackState`, the SPIRV-Cross session and post-emission ESSL rewrite, the driver POST self-test
family), it extends the same script (`scripts/p3a_untouched_regions.sh` → its P4a sibling) with its own
negative controls — P3a's had two (`ClearBufferPool`, `FlushPendingRangesNow`, `MEASUREMENTS.md:379`).
A shared template over an accessor interface is **rejected**: it resizes pull symbols and breaks G1
(`ID-13`, `MEASUREMENTS.md:521`).
- **ID-17 — Release APKs only.** The P2-era A/B APKs were unoptimised: the P3a pull APK's `libMobileGL.so` is
15.5 MB with a 9.4 MB `.text`; the P2 A/B's was 43.2 MB / 21.8 MB `.text`, same clang 18.0.4 — a 2.3× `.text`
is a Debug-flavour `-O0` build, and it replays 26.3 on the Oppo at **42 ms/frame CPU where Release takes 9.7**.
So `MEASUREMENTS.md` §10's absolutes and its +8–18% deltas are `-O0` readings. `wsl_build_trace_apks.sh` prints
the lib size "so an -O0 APK can never pass unnoticed again (Release .text ~9.4 MB)". **P4a's device A/B is
Release-only**, and the baseline of record is §20's table.
- **ID-18 — the exit-order rule.** `exit()` → `PipeInputs::~PipeInputs` (a namespace-scope holder of a
`SharedPtr<VertexArrayObject>`) → `~VertexArrayObject` → `~BufferObject` →
`MGPipeEmitResourceDestroyAndFree` → `MGPipeSlotAllocator::FindByLifetimeId` **on a hash table already freed**
by `~MGPipeSlotAllocator` (`MGPipeSlots()` is a Meyers singleton constructed at the first buffer, so it dies
first). The fix, landed as `d54ec57a` / `6515c8e6` / `fde5fda3` (`ID-21`, `MEASUREMENTS.md:515`): the MGPipe
singletons (`MGPipeSlots()`, `MGPipeResourceTrackerInstance()`, `g_applier`, and four more) are
**never-destroyed** (heap-constructed, intentionally leaked at exit), and **leak-at-exit storage** is used for
the four static `PipeInputs` holders (`gPipeInputs`, `g_snapshot`, `g_readScratch`, `probe`) that hold frontend
`SharedPtr`s — "树里只有它们持有前端对象,于是没有任何前端析构函数会从 exit handler 里跑;这是
`Init.cpp`/`GlobalObjects.cpp` 已有的规则". **Every new static P4a introduces that holds a frontend
`SharedPtr`, and every new MGPipe singleton, follows this rule.** Native reproduction key:
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0`; with it armed, P3a's finished tree ran `integration-verify`
844/844 and push `integration-gpu` 966/966 (`ID-21`).
- **The pin / tapper traps** (`MEASUREMENTS.md:469`, `ID-23`, and my memory files): Oppo ColorOS's install
confirmation is `topResumedActivity=…InstallGuideActivity` — `mCurrentFocus` shows a systemui window, so
grepping for it never matches, and not tapping it hangs the harness to timeout; **tapping during a streamed
install drops the device off adb for seconds and voids all three repeats**; the Xiaomi cannot reboot+pin
immediately after ~32 runs (thermal clamp: big cores pin at 1689600, or the GPU reads 1050 MHz) — wait for
`cpuss-0-0` < 42 °C; **a crash resets the GPU pwrlevel range to 2..5**, so every row after a crash carries a
DRIFT verdict on both arms. `ID-23`: Xiaomi rd12 on Magma aborts on **every** arm including pull (scudo map
error inside a calloc from `libMobileGL`) — pre-existing, excluded from the table, task chip open.
- **ID-16 / ID-22 — CI reds that are not code signals.** Artifact-download failures (`digest-mismatch`,
"Artifact download failed after 5 retries") on `retrace`/`retrace verify` matrix entries, and the
"Delete intermediate Linux retrace artifacts" step dying on a GitHub HTTP 504, are housekeeping/flake, not
signal. Only real retrace reds **after a successful download** matter.
- **ID-14 — the `BufferTest.cpp` fixture waiver**, and its shape is a warning for P4a: under a push build the
backend installs both `BufferBackendOps` and `MGPipeResourceOps` at bring-up, so a fixture that scoped only
the former let 26 of 86 dispatch cases route into the pipe (`MEASUREMENTS.md:523`: "这是**合并缝**的典型形态——
两个分支各自绿、合起来红"). **Any P4a unit fixture that scopes one op table must scope the new one too.**
- **ID-2 / ID-4 / ID-5 / ID-7 process rulings** carry over unchanged: integration order contract → wire →
client → espryt → gates; agents on opus, one adversarial review per package, at most two rework rounds;
durable locations `~/w7/notes/p4a/`; UNC editing works, `mkdir` does not — create directories from a WSL
script, run builds through a `.sh` with LF endings via `wsl.exe -d Arch -- bash /mnt/c/...`, and launch
anything over ~8 minutes with `setsid nohup … &` polled through its log.
---
## 5. Traps and open questions a P4a brief must resolve
1. **Suppressor-slot ownership** — `SetHashSuppressor.h:45-52` labels sampler-view/sampler-state slots P3b and
image/buffer/SO slots P4b, while `ROADMAP.md:20` gives the calls to P4a. Decide: P4a emits with `ContentHash`
populated, P3b/P4b latches the suppressor. (§1.3 item 12.)
2. **`TextureUploadShapeScenario` and the emission cursor** are in the **P3b/P4b** cells but are only meaningful
once P4a's texture `resource_*` exists. Decide where each lands. (§2.2.)
3. **`ResolvedDrawBuffers` is already paid** (P3a) despite appearing in P3b/P4b's memo list; do not re-scope it.
4. **The `SlotTables.h:70-77` P3+ debt** (backend minting handles off a frontend lifetime id) is closed *per
kind*, and nothing automated catches a kind that skips it.
5. **Every client-minted kind needs a backend-neutral death path** — P3a's final review found the
`VertexElementsCso` leak (Magma installs no death ops → one leaked slot + ~1.3 KB record per VAO, `Fatal`
past 65536 slots, `MEASUREMENTS.md:507`). `MG_IntegrationTest/Harness/PipeSlotPeek.{h,cpp}` (`:513`) is the
"see through the GL API" seam that made the leak testable.
6. **Peak RSS is still unmeasurable**: `~/w7/retrace_gate.py` takes only `--tree --lib --out -j --only` and has
no `rss`/`maxrss`/`getrusage` (`MEASUREMENTS.md:527`). The number was wanted precisely to watch a slot table
leak. P4a adds five more tables — either instrument the tool or state the hedge (unconditional destroy
emission + `HandleRecycleScenario` arms).
7. **Still unmeasured from P3a, inherited**: per-dirty-bit fire rates (`FireCount`/`WalkCount` implemented but
not in `FormatWindowLine`), the 24-bucket per-draw payload histogram (teardown-JSON only, and the trace app
never reaches teardown), and the `CreateVertexElements` bytes/frame class (`MEASUREMENTS.md:525`, `:465`(5),
`:288`, `:290`) — the last is explicitly "留给 P4a".
8. **`create-indirect` on device** stays excluded from the A/B and blocked on a `dev` fix
(`ROADMAP.md:100`, open question 17); G3b is recorded as "desktop green, device partial", never as a pass.
9. **The `--only` regex trap**: `retrace_gate.py --only` takes a **regex**, not a comma list; P3a's named sweep
silently selected 0 cases (`MEASUREMENTS.md:367`, `ID-15`). Spell it
`--only 'a\|b\|c'`.
10. **LFS fixtures**: a fresh package worktree has `tools/trace_replay/fixtures` as 131/133-byte LFS pointers, and
retrace against pointers reports `passed 2 / 79` with `ssim=None` — a **false red** that reads exactly like a
total regression (`MEASUREMENTS.md:413`).
11. **Open questions in `ROADMAP.md` that touch P4a**: 2 (texture-remint pull rate on real corpora — P4a's
`MOBILEGL_PIPE_TEXEL_RETAIN_MB` decision), 6 (D-B8 named-UBO host payload shape; Magma repacks 331 KB/frame
on 26.3, Espryt 0), 7 (`MG_Util`'s cut line — server needs SPIRV-Cross, ESSL transpile cache, format
handlers, POST probes; client needs glslang phase A/B and reflection), 8 (one reflection archive for three
consumers), 9 (viewport-array replay inside one `draw_vbo`; `EndViewportRoutingPasses` calls
`InvalidateSyncedRenderState`), 13 (can baked internal shaders express uniform locations and UBO layout
without a live `ProgramObject`), 14 (which pull-tuned cache hit rates the push model changes).
@@ -0,0 +1,815 @@
# Scout — Espryt's framebuffer / renderbuffer / texture surface that P4a converts
Tree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch `feat/disaggregated`
@ `37da3c3a` (P3a docs commit). Every line number below was opened in this tree. Paths are repo-relative
from `MobileGL/` unless stated.
Files that carry essentially all of it:
| file | lines | what P4a touches |
|---|---|---|
| `MG_Backend/DirectGLES/DirectGLES.cpp` | 11142 | `SyncCurrentFBO`, `BindCurrentFBO`, `ForceBindCurrentFBO`, `SyncAndBindFramebufferObject`, the two texture sync lists + the unit-bindings epoch, image units, readbacks, blits, CopyImage, GenerateMipmap, the scoped state guards |
| `MG_Backend/DirectGLES/Managers.cpp` | 10698 | `BackendFramebufferObject`, `BackendTextureObject`, `BackendRenderbufferObject`, `ScratchFBOImpl`, `PixelStoreImpl`, the unpack ring staging, the death-notice consumer |
| `MG_Backend/DirectGLES/Managers.h` | 2260 | the twin classes' members and the `TwinRegistry` alias / `StateBackendObjectRegistry` two-arm template |
| `MG_Backend/DirectGLES/SlotTables.h` | 577 | `BackendSlotTable` — the `{slot,gen}` table, both `GetOrCreate` overloads, `ReleaseByHandle`, the holder list |
| `MG_Backend/DirectGLES/Utils.cpp/.h` | 2405 / 543 | format caveat/widening predicates, `ReadbackImpl` client-store walks |
| `MG_Pipe/MGPipeTypes.h`, `MG_Pipe/PipeCalls.def` | — | the payloads P4a must fill (§7) |
---
## 0. The contract P4a is filling in (already written, all stubs today)
`MG_Pipe/PipeCalls.def` rows that P4a owns (none are new; only their emitters/appliers are):
- `:113` `X(SetFramebufferState, MGPFramebufferState, kCtxState, kNone)`
- `:118` `X(SetSamplerViews, MGPSamplerViews, kCtxState, kVarTail)`
- `:119` `X(BindSamplerStates, MGPSamplerStates, kCtxState, kVarTail)`
- `:120` `X(SetShaderImages, MGPShaderImages, kCtxState, kVarTail)`
- `:133` `X(SetTextureParams, MGPTextureParams, kCtxObject, kNone)`
- `:140` `X(GenerateMipmap, MGPMipPlan, kCtxObject, kNone)`
- `:141` `X(GetTextureImage, MGPReadbackInfo, kCtxObject, kReplySlot)`
- `:139` `X(ResourceCopyRegion, MGPCopyRegion, kCtxObject, kNone)`
- `:142/:143` `X(Blit, MGPBlit, kCtxVerb, kNone)`, `X(Clear, MGPClear, kCtxVerb, kNone)`
- `:144` `X(ReadPixels, MGPReadbackInfo, kCtxVerb, kReplySlot)`
- CSO create/delete: `:105-108` `CreateSamplerState` / `DeleteSamplerState` / `CreateSamplerView` / `DeleteSamplerView`.
Payload shapes (`MG_Pipe/MGPipeTypes.h`), with the fields that decide P4a's work:
- `MGPResourceDesc` `:150-175`, 88 B. **One create/respecify shape for buffers, every texture target and
renderbuffers** — `Target`, `StorageKind` (== `TextureStorageType`), `BindMask`, `InternalFormat`,
`Width/Height/Depth`, `ArrayLayers/Levels/Samples`, `FixedSampleLocations`, `Immutable`,
`HasDefinedContent`, **`ImageBindableHint` (`:166`, "client-side everImageBound; pre-emptive
allocation")**, `ViewOf` (`:173`, texture-view storage owner), `BufferForTexBuffer` + `BufOffset/BufSize`
(`:174-175`) for a buffer texture. So texture creation reuses P3a's `resource_create/respecify`.
- `MGPSurface` `:342-352`, 24 B: `Res`, `InternalFormat` **inline** (so the cross-object masks fall out with
no lookup), `Kind` (Texture|Renderbuffer|None), `Layered`, `Level`, `Layer`, `UploadTarget`.
- `MGPFramebufferState` `:354-371`, 304 B: `Fbo` (`kMGPipeDefaultFramebuffer` for the default FBO),
`Color[8]`, `Depth`, `Stencil`, **`ReadSurface` — "the RESOLVED read surface, not an index. This is what
structurally closes the read-buffer-shared-FBO defect class" (`:359-361`)**, `DrawBuffers[8]` as
`Int8` attachment indices with **-1 = NONE**, `Width/Height/Layers/Samples`,
`FixedSampleLocations/IsDefault/Complete`, and `ContentHash` (`:369`) doing two jobs: the server's
render-pass memo key and the **client-side emission suppressor**.
*Note for the implementer:* `Color[8]` and `DrawBuffers[8]` are **8**, while the frontend today carries
`FramebufferObject::MAX_DRAW_BUFFERS` draw buffers and `Color0..Color31` attachment points
(`Managers.h:1579-1581` computes `MAX_COLOR_ATTACHMENT_SLOTS` as `Color31-Color0+1` = 32). The
attachment-relocation table (§1.4) is 32 wide. This is a real width mismatch P4a has to rule on.
- `MGPSamplerView` `:288-303`, 36 B: "ONLY the view restrictions. Everything a `glTexParameter` writes lives
on `set_texture_params` instead, **because a texture that is only an FBO attachment, only an image binding
or only a `glCopyImageSubData` endpoint has no sampler view to hang it on**" (`:288-291`). Carries
`InternalFormat` (aliasing format for `glTextureView`), `Target`, `MinLevel/NumLevels/MinLayer/NumLayers`,
`Samples`, `FixedSampleLocations`.
- `MGPTextureParams` `:306-318`, 32 B: `Res`, `BaseLevel/MaxLevel`, `Swizzle[4]`, `DepthStencilMode`,
**`ForceResync` — "Mirrors `m_forceTextureParamsResync`" (`:312-313`)**, `MinLod/MaxLod/LodBias`.
- `MGPBoundView` `:428-434` / `MGPSamplerViews` `:436-440`; `MGPImageView` `:443-452` /
`MGPShaderImages` `:454-458`; `MGPSamplerStates` `:442-446`.
- `MGPCopyRegion` `:708-716` (64 B), `MGPBlit` `:718-727` (56 B), `MGPClear` `:729-739` (48 B),
`MGPMipPlan` `:741-745` (16 B), `MGPReadbackInfo` `:748-756` (64 B, `Res` null for `read_pixels`:
"the bound read surface answers").
`MGPTextureParams` has **no border colour and no filter/wrap/compare/anisotropy**; those live in
`MGPSamplerDesc` (`:283-287`, a blob of `SamplerParameters`) — but Espryt today pushes filters/wrap/LOD/
anisotropy **onto the texture object** through `SyncBuiltinSamplerToBackend` (§2.4). That mapping
(built-in sampler → sampler CSO, or → an extra params field) is P4a's second contract ruling.
---
## 1. How Espryt resolves the current draw/read framebuffer today
### 1.1 The FBO twin and its table
`FramebufferImpl::BackendFramebufferObject` — `Managers.h:1537-1610`.
Members (all of them are the server-side state P4a must relocate):
| member | line | meaning |
|---|---|---|
| `m_backendFBOId` | `Managers.h:1561` | driver FBO name, `glGenFramebuffers` in the ctor (`Managers.cpp:7015`) |
| `m_contextGeneration` | `:1562` | ES context generation the id belongs to; dtor only deletes when it matches (`Managers.cpp:7035`) |
| `m_frontendDrawBuffers[MAX_DRAW_BUFFERS]` | `:1570-1571` | the app's draw-buffer array verbatim (holes / reversals allowed) |
| `m_backendDrawBuffers[MAX_DRAW_BUFFERS]` | `:1577` | the ES-legal compacted array actually handed to `glDrawBuffers` |
| `m_backendColorSlots[32]` | `:1593` | **the permutation**: where frontend `COLOR_ATTACHMENTn` physically lives as a backend `COLOR_ATTACHMENTm` |
| `m_frontendReadBuffer` / `m_backendReadBuffer` | `:1600-1601` | read-buffer memo |
| `m_syncedFrontendAttachmentVersions` | `:1604` | per-attachment-point memo, keyed on FRONTEND attachment versions |
| `m_syncedBackendIdGeneration` | `:1609` | `g_attachmentBackendIdGeneration` at the last attachment walk |
Table: `extern TwinRegistry<FramebufferObject, BackendFramebufferObject, MGPipeKind::Framebuffer>
g_backendFramebufferObjects;` — declared `Managers.h:1612-1613`, defined `Managers.cpp:7754-7755`.
`TwinRegistry` is the alias at `Managers.h:547-553` that swallows the kind in the pull build;
`StateBackendObjectRegistry` (`Managers.h:303-540`) dispatches to `m_slotTable`
(`BackendSlotTable`, `Managers.h:538`) when `EsprytSlotTablesEnabled()` (`SlotTables.h:132-135`),
otherwise to the legacy `UnorderedMap<StateObject*, Entry>` (`Managers.h:319`).
The other two tables of this family:
- `TextureImpl::g_backendTextureObjects` — `Managers.h:1521-1522`, defined `Managers.cpp:7001`.
- `RenderbufferImpl::g_backendRenderbufferObjects` — `Managers.h:2257-2258`, defined `Managers.cpp:10695-10696`.
- (`SamplerImpl::g_backendSamplerObjects` — `Managers.h:2230-2231`, defined `Managers.cpp:10583`.)
All four still **mint** their handle inside `MG_Backend` off a frontend `GetLifetimeId()`
(`SlotTables.h:231-232`) — that is the debt `SlotTables.h:70-77` records against itself and that
P4a discharges for these kinds, exactly as P3a's seventh table (`BufferImpl::BackendBufferResourceTable`,
`Managers.h:690-692`) already does with `GetOrCreate(MGPipeHandle)` (`SlotTables.h:278-326`) and
`ReleaseByHandle` (`SlotTables.h:350-361`).
### 1.2 The frontend binding slot read
`GetFramebufferBindingSlotChecked(FramebufferTarget)` — `DirectGLES.cpp:173-193`. On the handle arm it is a
plain `MGB_CTX->GetFramebufferBindingSlot(target)` (`:176`); on the legacy arm it goes through the raw
pointer cache `g_fbSlotCache` / `g_fbSlotCacheContext` (`:156-157`, `:179-188`), which the comment at
`:159-172` explains was a **poison/verify bypass** and is therefore kept only for the pull control.
Five call sites: `:1944`, `:2242`, `:3080`, `:3210`, `:3300`.
### 1.3 `SyncCurrentFBO` — `DirectGLES.cpp:2229-2315`
Sequence, verbatim:
1. `:2233-2235` — three `CollectGarbageIfNeeded()` ticks (framebuffer, texture, renderbuffer). These are
no-ops on the handle arm (`Managers.h:477-491`).
2. `:2237` — walks `{Draw, Read}` in that order; `lastUpdatedFBO` carries the draw object forward.
3. **The four-part memo**, `:2254-2266`:
`slotVersion` (`slot.GetVersion()`), `objectVersion` (`currentFBO->GetObjectVersion()`), the raw
`currentPtr` (identity only), and `g_attachmentBackendIdGeneration`. All four stamped together by
`StampSyncedFBO` (`:2221-2227`) into `g_fboSyncedSlotVersions` / `g_fboSyncedObjectVersions` /
`g_fboSyncedObjects` / `g_fboSyncedBackendIdGenerations` (declared `Managers.h:1690-1710`,
defined `Managers.cpp:7756-7762`). The comment at `:2245-2253` records the bug that fixed:
leaving the slot version to `ForceBindCurrentFBO` alone made the early-out never fire and a
Minecraft-shaped frame re-ran the whole attachment walk on all 5495 draws.
4. `:2268-2271` — no FBO bound at all → `MGLOG_E_ONCE`, continue.
5. **Default-framebuffer branch** `:2273-2284`: nothing to sync *except* resetting
`g_alphaWidenedDrawBufferMask` / `g_integerColorDrawBufferMask` to 0 for the DRAW target, then stamp.
6. **Same-FBO-as-draw skip** `:2286-2302`: when the READ target names the object already synced as DRAW,
the attachment/draw-buffer work is skipped but `SyncReadBufferToBackend` is still called
(`:2295-2298`), through a `Find` on the twin table. This is the `read-buffer shared FBO` fix
(`draw_buffers_1`); `MGPFramebufferState::ReadSurface` is the structural replacement.
7. `:2304-2310` — resolve-or-create the twin, materialise it if empty, `SyncToBackend(currentFBO, target)`.
### 1.4 `BackendFramebufferObject::SyncToBackend` — `Managers.cpp:7521-7737`
- `:7533` `Bind(asTarget)` first.
- Draw buffers `:7537-7585`: memcmp against `m_frontendDrawBuffers`; **applied only when
`asTarget == Draw`** (`:7551`) — the comment `:7544-7550` records the Minecraft 26.x OIT bug where a
READ-only sync would land `glDrawBuffers` on the wrong framebuffer and falsely stamp the memo.
`FramebufferAttachmentType::None` → `GL_NONE` (`:7558-7560`) — **that is the "draw-buffer None"
handling**; default-framebuffer FRONT/BACK tokens pass through unremapped (`:7564-7569`);
everything else is forced to `GL_COLOR_ATTACHMENT0 + i` (`:7571`), and `nEffectiveBuffers` is the
highest non-None index + 1 (`:7573`).
- `RecomputeBackendColorSlots` — `Managers.cpp:7432-7519`. Three passes: draw-buffer slot `s` pins
attachment `a` to backend point `s` (`:7453-7474`); survivors keep identity (`:7479-7486`); displaced
attachments are parked on the lowest free point (`:7492-7504`). Returns "moved", and each moved
attachment has its version memo forced to `~0` (`:7515-7516`). When anything moved the read-buffer memo
is dropped (`:7580-7582`). `GetBackendAttachmentType` (`:7739-7752`) is the single reader.
- Draw-target-only mask recompute `:7587-7619`: `snormClampOutputMask`, `unormClampOutputMask`,
`g_alphaWidenedDrawBufferMask`, `g_integerColorDrawBufferMask` (globals declared `Managers.h:1650`,
`:1659`, defined `Managers.cpp:7308-7309`; the shader-side masks go into
`PrgramImpl::g_snormFallbackClampOutputMask` / `g_unormFallbackClampOutputMask`).
- Read buffer `:7623-7625` → `SyncReadBufferToBackend` (`Managers.cpp:7410-7430`), which binds as READ
first (`:7427`) then `glReadBuffer`.
- **Attachment walk** `:7627-7724`: re-arm every point when `m_syncedBackendIdGeneration !=
g_attachmentBackendIdGeneration` (`:7632-7636`); per point compare
`m_syncedFrontendAttachmentVersions[i] != attachmentVersions[i]` (`:7650`); an empty colour point below
`MaxColorAttachments` is explicitly detached with `glFramebufferRenderbuffer(..., 0)` (`:7659-7666`) —
the comment `:7651-7658` says removing that detach breaks the permutation invariant.
- **Re-entrancy** `:7726-7736`: the walk itself can re-mint a texture id, so `SyncToBackend` recurses until
`g_attachmentBackendIdGeneration` is quiescent.
`SyncAttachmentObject` — `Managers.cpp:7142-7216`: the attachment id/layer/level resolution.
- Texture branch `:7145-7194`: find-or-create the texture twin, **`SyncMipmapsToBackend` only**
(`:7161` — see §2.6, the parameter gap), then three shapes:
layered → `glFramebufferTexture(target, att, id, level)` (`:7162-7165`);
3D / 2DArray / 1DArray / CubeMapArray / 2DMSArray → `glFramebufferTextureLayer(..., level, layer)`
(`:7166-7177`); otherwise bind + `glFramebufferTexture2D` with the cube-face target
(`:7178-7194`, the cube-face bind rule at `:7184-7190`).
- Renderbuffer branch `:7195-7214`: find-or-create, `SyncToBackend`, `Bind()`,
`glFramebufferRenderbuffer`.
- An empty attachment returns `true` and issues nothing (`:7215`).
Read-side helpers on the frontend READ binding: `GetReadColorAttachment` (`Managers.cpp:7280-7291`),
`IsFixedPointFallbackReadAttachment` (`:7385-7408`), `IsAlphaWidenedFallbackReadAttachment` (`:7377-7383`),
`IsAlphaWidenedColorAttachment` (`:7293-7306`), `ComputeAlphaWidenedDrawBufferMask` (`:7357-7372`),
`IsIntegerColorAttachment` (`:7344-7355`), `IsSnormFallbackAttachment` / `IsUnormFallbackAttachment`
(`:7246-7276`).
### 1.5 Binding: `BindCurrentFBO` / `ForceBindCurrentFBO` / `SyncAndBindFramebufferObject`
- `BindCurrentFBO(target)` — `DirectGLES.cpp:3206-3260`. **No fast path on the slot version** — the
comment `:3211-3216` records `KHR-GL32.packed_pixels` reading out of the previous subtest's framebuffer.
Handle arm: a plain `Find` (`:3229-3232`); legacy arm: the 64-slot `g_fboTwinLookupMemo`
(`DirectGLES.cpp:140-141`, used `:3237-3243`). Default FBO → `BindFramebufferId(..., 0)` **through the
shadow** (`:3253-3259`) — *"a raw bind here would leave the shadow claiming the previous user FBO,
false-skipping its next re-bind"*. **This is the default-FBO-bind trap from the readback-state-guards
work**; its siblings are `SyncAndBindFramebufferObject`'s early return (`:3267-3280`) and
`NoteFramebufferIdDeleted` (`Managers.cpp:7096-7105`).
- `SyncAndBindFramebufferObject(fbo, target, forceSync)` — `DirectGLES.cpp:3262-3294`; used by the DSA
clears and `BlitNamedFramebuffer`. `forceSync` → `InvalidateSyncedState()` (`Managers.cpp:7119-7140`).
- `ForceBindCurrentFBO(target)` — `DirectGLES.cpp:3296-3308`: sync+bind then stamp all four memo arrays by
hand.
Driver-binding shadow: `g_driverFBOBindings` / `g_driverFBOBindingKnown` (`Managers.cpp:7051-7056`),
`BindFramebufferId` (`:7058-7079`), `CurrentFramebufferBinding` (`:7081-7094`, the one `glGetIntegerv`
cold pin), `NoteFramebufferIdDeleted` (`:7096-7105`), `InvalidateFramebufferBindingCache`
(`:7107-7117` — also clears the three synced-FBO arrays; called from `DirectGLES.cpp:5597`, `:6112`,
`:6211`, `:10133`, `:10577`, `:11110`).
Call sites that drive the pair (`SyncCurrentFBO` then `BindCurrentFBO`): `PrepareForDraw`
(`DirectGLES.cpp:3359` + `:3363`), `Clear` (`:4511` + `:4518`), `BlitFramebuffer` (`:6433`, `:6442-6443`),
`CopyTexImage2D` (`:7176` + `:7187`), `CopyTexSubImage2D` (`:7270` + `:7282`), `ClearBufferfi/fv/iv/uiv`
(`:7866/7912/7925/7941` + `:7869/7915/7931/7944`), the four `ClearNamedFramebuffer*`
(`:7969`, `:7986`, `:8006`, `:8026` via `ForceBindCurrentFBO`), `ReadPixels` (`:9510` + `:9513`),
`GetTexImage` (`:9681`), the multisample-resolve fallback (`:6507-6508`).
### 1.6 The fragColor MRT broadcast
`PrgramImpl` `DirectGLES.cpp:3037-3057`: the memo `g_broadcastMemoFbo` / `g_broadcastMemoSlotVersion` /
`g_broadcastMemoObjectVersion` / `g_broadcastMemoValid` / `g_broadcastMemoCount`, **keyed exactly like
`SyncCurrentFBO`'s trio** and cleared by `InvalidateBroadcastMemo()` (`:3055-3057`, called from
`DestroyEGLContext` `:11113`). Derivation `DirectGLES.cpp:3079-3102`: walk `drawFBO->GetDrawBuffers()`,
`enabledDrawBuffers = i+1` for every non-`None` slot, `g_fragColorBroadcastCount = max(count,1)`.
It is **read from the frontend, deliberately not from the backend FBO sync** (`:3076-3078`), because a
program compiled against a stale count would not be relinked until the following draw. It then enters the
program-staleness condition at `:3154` (`twin->GetFragColorBroadcastCount() != g_fragColorBroadcastCount`),
i.e. **the draw-buffer array is a shader-compilation input**. P4a must keep that ordering when the FBO
state becomes a pushed `MGPFramebufferState`.
### 1.7 The other emulations that live in this surface
- **Alpha-widened three-channel attachments** (`Managers.h:1642-1659`): the stored alpha is pinned at 1.0
— clears write 1.0 (`SubstituteWidenedClearAlpha`, `Managers.h:1670-1680`, used
`DirectGLES.cpp:7917-7920`, `:7933-7936`, `:7946-7949`, and for DSA at `:7961-7963` via
`IsWidenedNamedDrawBuffer` `:7894-7907`), draws get their alpha write mask forced off
(`RenderStateImpl::SyncRenderState(forColorClear)`, contract at `DirectGLES.h:209-226`, the applied
mask memo `g_syncedColorMaskAlphaWidenMask` at `DirectGLES.cpp:2346`), and readback overwrites alpha
(`IsAlphaWidenedFallbackReadAttachment` → `forceOpaqueAlpha`, `DirectGLES.cpp:9533-9543`).
`g_integerColorDrawBufferMask` exists because `glClearBufferfv` on an integer buffer is
`INVALID_OPERATION` (`Managers.h:1652-1658`).
- **SNORM / UNORM caveat formats**: `IsSnormFallbackAttachment` / `IsUnormFallbackAttachment`
(`Managers.cpp:7246-7276`) → the two shader clamp masks; readback clamp
`applyFixedPointReadClamp` (`DirectGLES.cpp:9542`, the clamp itself `:9204-9231`).
- **Layered attachment shapes**: `attachmentObject.IsLayered()` (5 reads),
`GetTextureLayer()` (1), `GetTextureLevel()` (6), `GetTextureUploadTarget()` (4) — the three-way branch
at `Managers.cpp:7162-7194`; the layered-blit substitute at `DirectGLES.cpp:6265-6421`.
- **Blit LOD / layered blit**: `BlitFramebuffer` `DirectGLES.cpp:6423-…`; the non-zero destination array
layer is served by `glCopyImageSubData` (`:6288`, `:6354-6413`) because a driver may ignore the layer
(`:6387`). The multisample replicate path builds its own programs (`:5889-5910`, `:6105-6191`) and the
aspect split is at `:6218-6258`. `EmulateTextureLodBias` (`Utils.cpp:1749-1830`, `Utils.h:527-536`)
is the shader-side LOD-bias emulation, invoked `Managers.cpp:9855`, gated by
`ShouldAvoidExplicitLodBiasOnAngleLlvmpipe()` (`Managers.cpp:94-97`).
- **D24S8 dual-mode sampling**: `GL_DEPTH_STENCIL_TEXTURE_MODE` is forwarded per texture
(`Managers.cpp:6956-6977`; cache `m_cacheDepthStencilTextureMode`, `Managers.h:1501`), and the *second*
half — one D24S8 sampled through its own name as `STENCIL_INDEX` and through a `glTextureView` as
`DEPTH_COMPONENT` in one pass (Better Clouds) — is why `GL_ARB_texture_view` is only advertised behind
a host extension **and** `MG_Config::Features.EsprytEnableTextureView`
(`BackendObject_DirectGLES.cpp:1177-1203`; the known break is `SyncTextureViewToBackend` normalising the
view's ES internalformat independently of the storage, `:1189-1196`).
The depth/stencil **readback** emulation is `DepthStencilSamplingReadImpl`
(`DirectGLES.cpp:8117-8578`, entered from `:8617` and `:8721`), with `ScopedDepthBlitState` at `:6985`.
---
## 2. The texture object twin
### 2.1 The class
`TextureImpl::BackendTextureObject` — `Managers.h:1341-1517`. Public surface `:1343-1417`; the members
that are the real server state:
| member | line | note |
|---|---|---|
| `m_backendTextureId` | `1422` | driver name |
| `m_bufferImageSplitViewId` | `1441` | second buffer-texture name for `glBindImageTexture` (the rg32f→r32f split) |
| `m_viewSourceBackendTextureId` | `1447` | for a `glTextureView`: the ES name it was made a view OF |
| `m_contextGeneration` | `1455` | |
| `m_isInitialized`, `m_imageBindableStorageRequired`, `m_backendStorageImmutable` | `1456-1458` | |
| `m_bufferTextureUnsupportedReported` | `1463` | one-shot report latch |
| `m_prevTextureInfo` (`StateTextureBasicInfo`, `Managers.h:1320-1338`) | `1464` | format/w/h/d/levels/bufferExternalIndex/samples/fixedSampleLocations |
| `m_syncedContentVersion` | `1468` | |
| `m_syncedShapeContextId`, `m_syncedShapeGeneration`, `m_syncedShapeParamsVersion` | `1481-1483` | the cheap-gate trio |
| `m_cacheSamplerParameters`, `m_cacheLodRange` | `1484-1485` | |
| `m_cacheBorderColor` / `I` / `UI` / `Form` | `1490-1493` | **all four**, because none alone identifies the driver's border colour |
| `m_cacheSwizzleParams` | `1494-1495` | |
| `m_cacheDepthStencilTextureMode` | `1501` | |
| `m_syncedSamplerVersion`, `m_syncedTextureParamsVersion` | `1502-1503` | |
| `m_forceTextureParamsResync`, `m_forceSamplerResync` | `1507`, `1516` | the two re-mint overrides (`MGPTextureParams::ForceResync` mirrors the first) |
`IsDrawSyncClean(t, contextId, samplingGeneration)` — `Managers.h:1399-1417`: the aggregate gate that is
*exactly* the conjunction of the three per-draw sync calls' own early-outs (documented `:1383-1394`; it
must never be more permissive).
Unit binding shadow: `g_boundTexturesCache[192][TextureTargetCount]` (`Managers.h:1530-1532`, defined
`Managers.cpp:6998-7000`), `g_activeTextureUnit` (`Managers.cpp:6997`), `ActivateTextureUnit`
(`Managers.cpp:6980-6986`), `UnbindTexture` (`:6988-6995`), `Bind(target, unit=TempTextureUnit=0)`
(`Managers.cpp:4729-4743`, `TempTextureUnit` at `Managers.h:1340`).
### 2.2 `SyncTextureObjectToBackend` — `DirectGLES.cpp:1501-1577`
Find-or-create (`:1507-1512`), then a **by-value SharedPtr copy** of the twin
(`:1514-1526`) because the sync can re-enter (a texture view syncs its storage texture first) — on the
slot arm the copy is kept only to hold the twin alive. Then, in order:
`RequireImageBindableStorage` if asked (`:1528-1530`), `SyncTextureParamsToBackend` (`:1531`),
`SyncBuiltinSamplerToBackend` (`:1532`), `SyncMipmapsToBackend` (`:1533`), and — if the storage sync
re-minted the name — **both parameter pushes again** (`:1541-1544`, `NeedsParameterResync()`
`Managers.h:1397`). Handle arm re-resolves once (`:1546-1566`); legacy arm re-resolves and repairs
(`:1568-1576`).
### 2.3 The per-draw work lists and the unit-bindings epoch
`DirectGLES.cpp:1579-1990` is the block P4a rewrites. In order:
- **The identity snapshot.** `UnitBindingsSnapshot` on the push arm holds **lifetime ids, not weak_ptrs**
(`:1594-1622`; `LifetimeIdOf` `:1624-1630`), with the legacy weak_ptr fields kept under
`MOBILEGL_PIPE_LEGACY_MEMOS` (`:1616-1621`) and the arm chosen at **runtime** via
`MGB_UNIT_BINDINGS_HANDLE_ARM` (`:1632-1636`, `#undef` at `:1694`). Pull-build copy of the same two
functions at `:1696-1727`. `CaptureUnitBindings` `:1638-1664`, `UnitBindingsUnchanged` `:1666-1693`.
The design note at `:1579-1593` says explicitly what the snapshot does **not** cover (completeness
flips, high-water mark, context identity, ES context generation, the program keys).
**This is the ~115-line derivation the task names.**
- **`CurrentUnitBindingsEpoch(maxTouchedUnit)`** — `:1746-1773`, over
`g_observedUnitBindings` / `…ContextId` / `…Generation` / `…MaxUnit` / `g_unitBindingsEpoch`
(`:1730-1734`). Gate: `(contextId, bindGeneration, maxTouchedUnit)`; on a miss it re-walks and bumps
the epoch only when the bindings really moved. Stats gate `Gate::EsprytUnitBindingsEpoch` (`:1757`, `:1762`).
- **`UnitTextureSyncEntry`** — `:1801-1805`: `{const SharedPtr<ITextureObject>* slot,
ITextureObject* texture, BackendTextureObject* backend}`. **Entries borrow, never own**
(rationale `:1783-1800`), and `PairingsIntact` (`:1808-1813`) is the structural net under the keys
(a DSA by-name slot swap that never reached the bind generation would otherwise drive texture A's twin
from texture B's state).
- **`g_unitTextureSyncList`** + keys `:1814-1820`
(`Valid`, `ContextId`, `MaxUnit`, `ContextGeneration`, `Epoch`, `SamplingGeneration`).
- **`g_fboTextureSyncList`** + keys `:1825-1830`
(`Fbo`, `SlotVersion`, `ObjectVersion`, `ContextId`, `ContextGeneration`).
- **`DrawTextureSyncKeys`** `:1839-1844` and `CaptureDrawTextureSyncKeys()` `:1846-1858`
(`contextId`, `maxTouchedUnit`, `samplingGeneration`, `unitBindingsEpoch`).
- **`SyncNeccessaryTextures(keys)`** `:1860-1988`.
Unit list hit path `:1879-1901` (per entry: `IsDrawSyncClean` then the three syncs);
rebuild `:1902-1930` (skips `IsUndefinedDefaultTexture`, `:1918`).
**FBO list `:1944-1987` walks the DRAW slot only** (`:1944`), over
`currentFBO->GetAllAttachmentObjects()` with `attachment.IsTexture()` (`:1970-1976`); a null draw FBO
clears the list (`:1984-1987`). Stats gate `Gate::EsprytTextureSyncList` (`:1889`, `:1904`).
No-arg wrapper `:1990` used by every non-draw entry point.
### 2.4 `SyncTextureParamsToBackend` / `SyncBuiltinSamplerToBackend`
- `SyncBuiltinSamplerToBackend` — `Managers.cpp:6671-6780`. Gate `m_syncedSamplerVersion == version &&
!m_forceSamplerResync` (`:6684`). Multisample targets: cache and return without any GL
(`:6706-6709`). Then min/mag filter (`:6732-6744`, via `ResolveBackendMinFilter`), wrap S/T
(`:6749-6750`), wrap R only when `SupportsWrapR` (`:6751-6755`), compare func/mode (`:6756-6757`),
min/max LOD (`:6758-6765`), max anisotropy behind `SupportsTextureFilterAnisotropy` (`:6766-6775`).
**All of it via `glTexParameter*` on the texture object, after `Bind(target)` at `:6711`.**
- `SyncTextureParamsToBackend` — `Managers.cpp:6782-6978`. Gate
`m_syncedTextureParamsVersion == version && !m_forceTextureParamsResync` (`:6794`);
multisample refresh-but-skip at `:6821-6825`; `Bind(target)` `:6827`; base/max level `:6837-6847`;
swizzle with the alpha-widening substitution `:6852-6864` and the image-widening substitution
`:6865-6879`; border colour (all three forms + form, `:~6900-6954`); `GL_DEPTH_STENCIL_TEXTURE_MODE`
`:6956-6977`.
Both `Bind()` on `TempTextureUnit` (unit 0), which is why `BindCurrentTextures` has to re-establish the
real unit bindings afterwards (`DirectGLES.cpp:3687-3693`).
### 2.5 `SyncMipmapsToBackend` — `Managers.cpp:5672-…`
- Texture-view short-circuit `:5683-5686` → `SyncTextureViewToBackend`.
- **Cheap gate** `:5700-5707`: `m_isInitialized && shapeContextId && ctx live && shapeContextId ==
GetTextureContextId() && shapeGeneration == GetSamplingResolutionGeneration() && contentVersion ==
GetContentVersion() && shapeParamsVersion == GetTextureParamsVersion() && StorageType == Mipmap`.
- `IsComplete() || HasAnyDefinedMipmapLevel()` bail `:5734-5738`.
- **Second fast path** `:5751-5778`: content version unchanged + a `StateTextureBasicInfo` probe equal to
`m_prevTextureInfo` → re-stamp the cheap gate and return without the scratch bind.
- `Bind(target)` `:5780`; `currentTextureInfo` built `:5785-5792`.
- `TextureStorageType::Mipmap` `:5794-6503`:
- `needsRegeneration` `:5800`; immutable storage forces `RecreateBackendTexture()` `:5801-5804`.
- `imageWidening` = `GetImageBindableStorageWidening(format)` only when `m_imageBindableStorageRequired`
(`:5810-5813`).
- **`canAppendMipmaps`** `:5815-5827` (append-only level growth) → the `glTexImage2D/3D` append loop
`:5833-5910`.
- Full regeneration `:5912-…`: `ApplyImageBindableStorageWidening` `:5920`; multisample clamp
`:5923-5931`.
- **The per-level upload loop** `:6184-6500` — see §2.7.
- `TextureStorageType::Buffer` `:6504-…`: **calls `BufferImpl::EnsureBufferResource(buffer)` at
`:6520`** (the one place a texture sync pulls a buffer twin — and therefore the one texture path that
reaches `SyncPersistentMappedRange`, see §5), then `CallTexBuffer` / `CallTexBufferRange`
(`:6589-6598`), and mints/points `m_bufferImageSplitViewId` for the image split (`:6606-6630`,
rationale `:6533-6549`).
`SyncTextureViewToBackend` — `Managers.cpp:5579-5670`: syncs the storage owner first (`:5600-5601`,
by-value SharedPtr for the same rehash reason), short-circuits when
`m_viewSourceBackendTextureId == storageBackendTextureId` (`:5613-5616`), otherwise
`RecreateBackendTexture()` (`:5620`, which also bumps `g_attachmentBackendIdGeneration`) and calls
`ResolveTextureViewEntryPoint()` (`:5630-5634`). `StampViewSyncKeys` `:5569-5577`.
### 2.6 Where an attachment-only / image-unit / CopyImage texture gets — or misses — its parameters
**This is the exact answer the task asks for.**
| how the texture is reached | code path | gets `SyncTextureParamsToBackend` + `SyncBuiltinSamplerToBackend`? |
|---|---|---|
| bound to a sampler unit ≤ high-water mark | `SyncNeccessaryTextures` unit list, `DirectGLES.cpp:1898-1900` (hit) / `:1919-1920` → `SyncTextureObjectToBackend` (miss) | **yes** |
| attachment of the **DRAW** framebuffer | `SyncNeccessaryTextures` FBO list, `DirectGLES.cpp:1963-1965` (hit) / `:1974-1975` (rebuild) | **yes** |
| attachment of the **READ** framebuffer only | `SyncCurrentFBO` `:2304-2310` → `SyncToBackend` → `SyncAttachmentObject` `Managers.cpp:7142-7194`, which calls **`SyncMipmapsToBackend` at `:7161` and nothing else** | **NO** — storage is synced, parameters are not. `SyncNeccessaryTextures`'s attachment list reads only `GetFramebufferBindingSlotChecked(FramebufferTarget::Draw)` (`DirectGLES.cpp:1944`) |
| bound to an image unit | `SyncImageTextureBinding` → `SyncTextureObjectToBackend(imageBinding.Texture, /*imageBindable=*/true)` (`DirectGLES.cpp:2071`) | **yes**, and `RequireImageBindableStorage` additionally forces `m_forceTextureParamsResync = true` (`Managers.cpp:4787`) so the swizzle override lands |
| a `glCopyImageSubData` endpoint | `MakeGLESCopyImageEndpoint` → `SyncTextureObjectToBackend(endpoint.Texture)` (`DirectGLES.cpp:7588`); renderbuffer endpoint → `SyncRenderbufferObjectToBackend` (`:7547-7562`, `:7567`) | **yes** |
| `GenerateMipmap` target | `DirectGLES.cpp:7433` / `:7436` → `SyncTextureObjectToBackend` | **yes** |
| `GetTexImage` source | `DirectGLES.cpp:9678` `SyncNeccessaryTextures()` — i.e. only if it is unit-bound or a DRAW attachment; then a bare `Find` at `:9693` | **only incidentally** |
So today parameters ride on the *unit binding* and on the *draw* attachment set. `MGPTextureParams`
(`MGPipeTypes.h:306-318`) is per-`Res` and independent of any view, which is the fix — but the
implementer must not assume the current behaviour is complete: the READ-attachment-only case is a
pre-existing gap that P4a either preserves (bug-for-bug) or closes deliberately, and the choice must be
written down. The corresponding negative control is easy: a texture attached only as READ with a
non-default swizzle / `DEPTH_STENCIL_TEXTURE_MODE`, read back with `glReadPixels`.
### 2.7 Upload shapes — whole box vs rect vs jobs, and the PBO unpack ring
Per dirty (uploadTarget, level) in `Managers.cpp:6185-6499`:
1. Conversion fallbacks first, each of which takes the level **off** the sub-rect path by pointing
`uploadData` at a fresh buffer: `PrepareFallbackUpload` (`:6215-6217`),
`PreparePackedNormUpload` (`:6218-6220`), `PrepareImageWidenedUpload` (`:6225-6227`, defined `:5442`).
2. `subRectEligible` — `:6241-6246`: `uploadData == mipData` (unconverted) **and** a non-empty dirty
region that does not cover the whole level **and** whole-texel byte size **and** the backend upload
size equals the shadow texel size. `bpp = byteSize / texelCount` (`:6247`).
3. Union box (`GetStorageDirtyRegion`, `:6237`) vs **scatter rects** (`GetStorageDirtyRects`, `:6271-6273`,
bounded by `MipmapStorage::kMaxDirtyRects`). **`dirtyRectCount` is forced to 0 whenever the unpack ring
is available** (`:6280-6282`) — the comment records the measured +6 ms/frame Mali cliff from ~100
one-rect jobs; "One box, one job".
4. **Unpack-ring staging plan**, decided once for the level (`:6290-6353`): three shapes matching the
three branches — N rects (`:6310-6322`), one box (`:6323-6331`), whole level verbatim (`:6332-6353`).
`StageBlocksIntoUnpackRing` (`Managers.cpp:4947-5001`, `UnpackStagingBlock` `:4935-4945`) repacks
**tightly**, which is why the ring path issues no `glPixelStorei` at all — the surrounding
`ScopedDefaultUnpackState` already holds ROW_LENGTH/IMAGE_HEIGHT at 0 (`:6296-6302`).
`UnpackRingPixelOffset` `:5003-5006`.
5. `ringStaged` → `BindPixelUnpackBufferId(UnpackRingBufferId())` `:6357-6359`, restored to 0 at
`:6492-6497`.
6. **Stats** `:6360-6395`: `ByteClass::StageTexture`, `CallClass::TextureUploadEmissions`,
`TextureUploadRectEmissions` / `TextureUploadBoxEmissions`, `TextureUploadJobs` (rects → N jobs,
box → 1). *"the box/rect split is counted separately from the bytes on purpose: SSIM is blind to it"*.
7. The dispatch `:6396-6491`: 2D/CubeMap `glTexSubImage2D` in three shapes (`:6399-6431`),
3D/2DArray/CubeMapArray `glTexSubImage3D` in three shapes (`:6438-6485`).
The ring itself is `BufferImpl`'s: `g_unpackRing` (`Managers.cpp:866-872`), `kUnpackRingInitialBytes`
4 MiB / `kUnpackRingMaxBytes` 64 MiB / alignment 64 (`:803-810`), `UnpackRingAvailable`
(`:3466-3469`, honours `MG_Config::Features.EsprytDisableUnpackRing`), `UnpackRingAllocate` (`:3471-3476`),
`UnpackRingMappedPtr`/`BufferId`/`MaxBytes` (`:3478-3480`), `UnpackRingOnPresent` (`:3482`),
`ResetRingForNewContext` (`:2577`). `ScopedDefaultUnpackState` `Managers.cpp:4851-4880`.
Widening helpers: `GetWidenableClientComponentCount` / `IsIntegerWidenableFormat` /
`PrepareChannelWidenedUpload` / `PreparePackedIntWidenedUpload` (`Managers.h:1292-1318`);
`ShouldUseCaveatTextureFormat`, `BackendTextureFormatAddsAlpha`, `GetImageBindableStorageWidening`
(`Utils.h:63`, `:69`, `:130-161`; `Utils.cpp:245`, `:270`, `:280-…`).
Target mapping: `MapToBackendTextureTarget` (`Managers.h:1243-1253`), `GetBackendUploadSize`
(`:1273-1278` — 1D arrays move layers from y to z).
### 2.8 Image units and the format recast
`SyncImageTextureBinding(unit)` — `DirectGLES.cpp:2057-2135`: high-water mark `g_imageUnitHighWaterMark`
(`:2055`), `TrackWritableImageBufferUnit` (`:2062`, counter at `:2040-2047`), unbind path `:2066-2069`,
`SyncTextureObjectToBackend(tex, true)` `:2071`, layered/layer resolution via
`SupportsLayeredImageBinding` (`:2072-2074`, rationale `:1992-1999`), the buffer split view
(`:2120-2124`), and the **bind-format recast** (`:2126-2132`, rationale `:2075-2083`: a `GL_RG32F` bind
is `INVALID_VALUE` on 19/26 non-core formats on Adreno and 25 on both Malis).
`SyncImageTextureBindings()` `:2169-2179`; the per-draw gate
`SyncImageTextureBindingsForDraw(keys)` `:2202-2214`, keyed on `(contextId, samplingGeneration,
g_backendContextGeneration)` with the deliberate note (`:2195-2201`) that the key is the frontend
sampling-resolution generation and **not** the backend re-mint counter.
`MarkWritableImageBufferTexturesGpuWritten()` `:2149-2167`.
### 2.9 Re-mint and the FBO coupling
`RecreateBackendTexture()` — `Managers.cpp:4790-4840`: `ScratchFBOImpl::NoteTextureIdDeleted`
(`:4792`), **`++FramebufferImpl::g_attachmentBackendIdGeneration`** (`:4797`), delete under the matching
context generation (`:4798-4800`), scrub `g_boundTexturesCache` (`:4801-4807`), regen (`:4810`), reset
`m_isInitialized` / `m_backendStorageImmutable` / `m_prevTextureInfo` (`:4818-4820`), reset **every**
parameter cache and set both force flags (`:4829-4839`).
`RequireImageBindableStorage` — `Managers.cpp:4752-4788`: sticky, clears `m_isInitialized`,
**re-marks every already-uploaded level dirty** (`:4769-4779`), sets `m_forceTextureParamsResync`
(`:4787`). `g_attachmentBackendIdGeneration` is defined at `Managers.cpp:7763`.
Destructor `Managers.cpp:4693-4727` (note the `/sdcard/MG/exp_leak_texture_deletes` experiment latch at
`:4711-4718` — an existing temp-experiment hook in the destructor).
### 2.10 CopyImage
`CopyImageSubData` — `DirectGLES.cpp:7696-…`; endpoint resolution `MakeGLESCopyImageEndpoint`
`:7564-7603` (renderbuffer at `:7566-7573`, texture at `:7587-7602`, with the explicit *no* axis remap
for 1D arrays at `:7592-7598`); `GLESCopyImageEndpoint` at `:7530-7542`;
`GetCopyImageEndpointFormat` `:7605-7608`; `CanMirrorCopyImageShadow` `:7613-7617` and the CPU-shadow
mirror below it (`:7619-…`, `:7790` "the CPU shadow is what glGetTexImage answers from, so it has to
follow the same move"). The layered-blit substitute reuses `glCopyImageSubData` at
`DirectGLES.cpp:6288`, `:6406`.
### 2.11 GenerateMipmap
`GenerateMipmap(target)` — `DirectGLES.cpp:7417-7462`.
`EnsureGenerateMipmapStorageAllocated` (`:6707-6752`) for R11F_G11F_B10F / depth-only / RGB16F / RGB32F;
`GenerateThreeChannelFloatMipmapOnCpu` (`:7432-7435`, filtered on the CPU so dirty levels ride down with
the sync); `GenerateDepthTexture2DMipmap` (`:7439`), `GenerateColorTexture2DMipmap` (`:7444`);
`ScopedDetachedTextureFramebufferAttachments` (`:7453`) then `ScopedCompleteFramebufferBinding` (`:7455`)
then `glGenerateMipmap` (`:7460`).
---
## 3. The renderbuffer twin
`RenderbufferImpl::BackendRenderbufferObject` — `Managers.h:2235-2255`. Members:
`m_backendRBOId`, `m_contextGeneration`, `m_isInitialized`, `m_cacheInternalFormat`, `m_cacheWidth`,
`m_cacheHeight`, `m_cacheSamples` (`:2248-2254`).
- ctor `Managers.cpp:10585-10597` (`glGenRenderbuffers`, stamps `g_backendContextGeneration`).
- dtor `Managers.cpp:10599-10612`; no binding shadow exists (`:10606-10607` — `Bind()` always issues).
- `Bind()` `Managers.cpp:10614-10619` — unconditional `glBindRenderbuffer`.
- `SyncToBackend` `Managers.cpp:10621-10693`: **storage respecify is memoised on the four-field cache**
(`:10634-10640`); otherwise `Bind()`, `GenerateRenderbufferFormatInfo` (`:10650`),
`ClampSamplesToBackendSupport` for the multisample form (`:10664-10668`) or
`glRenderbufferStorage` (`:10670-10671`), and an explicit `GL_OUT_OF_MEMORY` probe that reports
`ErrorCode::OutOfMemory` to the application (`:10673-10683`) — the deferred-allocation model means the
error lands on whatever entry point triggered the sync (`:10652-10658`).
- Table `Managers.cpp:10695-10696`. Reached from `SyncAttachmentObject` (`Managers.cpp:7195-7213`),
from `SyncRenderbufferObjectToBackend` (`DirectGLES.cpp:7547-7562`, used by CopyImage), and ticked by
`SyncCurrentFBO` (`DirectGLES.cpp:2235`).
- **Lifetime id / death**: `RenderbufferObject` raises `NotifyStateObjectDestroyed`; the consumer arm is
`Managers.cpp:208-210`.
Frontend members read: `GetInternalFormat` (7 sites), `GetExternalIndex` (4), `GetWidth`, `GetHeight`,
`GetSamples` (2 each).
---
## 4. Readback paths, and what a server without the frontend address space needs
### 4.1 `ReadPixels` — `DirectGLES.cpp:9488-9636`
`IsLegacyNativeReadPixelsFormat` / `…Type` / `IsSupportedDepthStencilReadPixelsPair`
(`:9455-9486`) decide `useNativeReadback`; `GetReadbackChannelMapping` + `GetReadbackDstPixelSize`
decide `convertible` (`:9497-9499`). Then:
`SyncNeccessaryTextures()` `:9507`, `SyncCurrentFBO()` `:9510`, `BindCurrentFBO(Read)` `:9513`,
`ScopedPackState packParamsScope(PackStateFromContext())` `:9516`,
`glCheckFramebufferStatus(GL_READ_FRAMEBUFFER)` `:9518-9524`.
`packSwapBytes` `:9530`, `forceOpaqueAlpha = IsAlphaWidenedFallbackReadAttachment()` `:9533`,
`nativeFastPair` `:9537-9539`; conversion path `:9540-9550`; depth/stencil helpers `:9555-9560+`;
the pack-PBO resolution `GLuint packBufferId` `:9575-9585` (**via
`BufferImpl::EnsureBufferResource(pixelPackBufferObject)` at `:9577`**), `ScopedPixelPackBuffer` `:9589`,
`glReadPixels` `:9593`, the retry-on-error via conversion `:9594-9617`, and the
**PBO → frontend shadow writeback** `:9618-9634` (`WritebackFromBackend` `:9626` +
`BumpBufferMutationEpoch()` `:9628`).
### 4.2 `GetTexImage` — `DirectGLES.cpp:9655-…`
`IsNativeGetTexImagePair` `:9640-9653`; `SyncNeccessaryTextures()` `:9678`; `SyncCurrentFBO()` `:9681`;
resolves the texture off the **active unit's binding slot** (`:9683-9691`) and does a bare
`g_backendTextureObjects.Find` (`:9693-9702`) — it does **not** create a twin, it bails.
Then the cross-FBO resolve barrier note (`:9704-9709`), widening probes at `:9810`, `:9818`,
the temp-FBO + `ReadPixelsViaFormatConversion` route (`:9933`, `:9956`), the pack-PBO resolution
`:10001-10011` and the PBO writeback `:10029-10043`.
**The shadow fallback**: `GetTexImageViaShadowConversion` — `DirectGLES.cpp:9244-9300+`. Valid *only*
while the CPU shadow is authoritative, which holds for non-renderable formats (`:9246-9247`). Reads
`textureMipmapObject->MapMipmapData(uploadTarget, level)` (`:9268`), takes the raw-packed shortcut when
`IsRawPackedPixelTransfer` (`:9277-9287`, so an RGB9_E5 shared exponent is not canonicalised), else
`DecodeShadowDataToWideRGBA` (`:9292-9297`) then `ReadbackImpl::StoreWideRowsToClient`.
`ReadPixelsViaFormatConversion` — `DirectGLES.cpp:9015-9242`; the fixed-point read clamp `:9204-9231`.
`ReadbackImpl` client-store walks: `Utils.cpp:1973-2404`, `StoreWideRowsToClient` `Utils.cpp:2362`,
`StorePackedWordsToClient` `Utils.cpp:2387` (declarations `Utils.h:188-246`); the PBO writeback inside
the shared row walk is `Utils.cpp:2343-2352`.
`StoreReadbackRowsToClient` (depth/stencil destination walk) — `DirectGLES.cpp:8040-8073`, PBO writeback
`:8062`, epoch bump `:8068`.
### 4.3 The scoped driver-state guards (the readback-state-guards architecture)
`DirectGLES.cpp:6545-6644` and `:6795-6900+`:
`ScopedFramebufferBinding` `:6555-6573` (saves/restores through `CurrentFramebufferBinding` +
`BindFramebufferId`, never `glGetIntegerv`), `ScopedPackState` `:6576-6588`, `PackStateFromContext`
`:6592-6596`, `ScopedPixelPackBuffer` `:6601-6607` (always returns the binding to 0),
`ScopedScissorDisable` `:6612-6626` (reads the render-state shadow), `TempFBOBinder` `:6631-6644`,
`ScopedCompleteFramebufferBinding` `:6795-6803`,
`ScopedDetachedTextureFramebufferAttachments` `:6805-…` — **the one direct-iteration site over a twin
table**: push arm uses `g_backendFramebufferObjects.ForEachLive` (`:6877-6884`), legacy arm walks
`begin()/end()` and must test `stateRef.expired()` by hand (`:6885-6895`), pull arm keeps the pre-P2 walk
verbatim (`:6896-6899`). `SlotTables.h:61-68` says the per-entry `weak_ptr` survives **only** for this
caller. `ScopedDepthBlitState` `:6985`.
`PixelStoreImpl` (PACK shadow): `Managers.h:1792-1806`, `Managers.cpp:8004-8054`
(`ApplyPackState` `:8019`).
`ScratchFBOImpl`: `Managers.h:1734-1781`, `Managers.cpp:7767-8002`
(`EnsureId` `:7833`, `EnsureColorAttachment2D` `:7847`, `EnsureCompleteTinyFramebufferId` `:7960`,
`NoteTextureIdDeleted` `:7984`).
### 4.4 What a server without the frontend address space needs
Enumerated so the implementer does not have to re-derive it:
1. **A destination that is not a client pointer.** Every readback today writes either into the
application's `void* pixels` or into a frontend `BufferObject`'s CPU shadow via
`WritebackFromBackend` (four sites, §5). `MGPReadbackInfo` (`MGPipeTypes.h:748-756`) already carries
`DstOffset`/`DstSize` and is `kReplySlot`, so the reply slot is the destination — but the
**pack-PBO** case is different: the driver writes into the *backend* buffer store and the frontend
shadow then has to be refreshed. That refresh is `WritebackFromBackend` + `BumpBufferMutationEpoch`,
both frontend calls, and is P4a's hardest readback item.
2. **PACK pixel-store parameters as payload.** `PackStateFromContext` (`DirectGLES.cpp:6592-6596`) and
the row walks read `MGB_CTX->GetPixelStoreParameters(false)` directly
(`DirectGLES.cpp:9530`, `:8042`, `Utils.cpp:~2300`). `SetPixelPackState`/`MGPPixelPackState` exists
in the catalogue (`PipeCalls.def:126`) — P4a has to actually push it, including the four ES-less
fields (`IMAGE_HEIGHT`, `SKIP_IMAGES`, `SWAP_BYTES`, `LSB_FIRST`; `Managers.h:1788-1791` says they are
honoured on the CPU from frontend state).
3. **The resolved read surface**, not the read-buffer enum: `MGPFramebufferState::ReadSurface`.
The three helpers `IsFixedPointFallbackReadAttachment`, `IsAlphaWidenedFallbackReadAttachment`,
`GetReadColorAttachment` (`Managers.cpp:7280-7408`) all currently walk
`MGB_CTX->GetFramebufferBindingSlot(Read)`; with the inline `InternalFormat` on `MGPSurface`
(`MGPipeTypes.h:344`) they become pure functions of the pushed record.
4. **The texture CPU shadow.** `GetTexImageViaShadowConversion` reads `MapMipmapData`
(`DirectGLES.cpp:9268`) and the CopyImage mirror writes it (`DirectGLES.cpp:~7790`,
`MarkStorageDirty`). A split server has no shadow. Either the shadow stays client-side and the server
answers only from the driver, or a mirror is added — this is the texture analogue of P8's index host
mirror and should be recorded, not solved, in P4a.
5. **Error reporting.** `BackendRenderbufferObject::SyncToBackend` calls `MGB_CTX->RecordError`
(`Managers.cpp:10677-10682`); `GenerateMipmap` calls `RecordGLError` (`DirectGLES.cpp:7461`). Both
need the reverse channel.
---
## 5. `SyncPersistentMappedRange` / `SyncGpuWrites` sites still touching textures
Full census in `MG_Backend/DirectGLES` (the grep is exhaustive):
| site | file:line | texture-related? |
|---|---|---|
| `drawBuffer->SyncPersistentMappedRange()` (indirect) | `DirectGLES.cpp:301`, `:5117-5118`, `:5219-5220` | no (indirect buffers) |
| `indexBuffer->SyncPersistentMappedRange(); SyncGpuWrites()` | `DirectGLES.cpp:4863-4864`, `MultiDraw.cpp:511-512` | no |
| `bufferObject->SyncPersistentMappedRange()` inside the ensure path | `Managers.cpp:2799`, `:2976` (D-N note `:2703-2718`) | **reached from the texture path**: `SyncMipmapsToBackend`'s buffer-texture branch calls `BufferImpl::EnsureBufferResource(buffer)` at `Managers.cpp:6520` |
| `bufferObject->SyncGpuWrites()` | `Managers.cpp:4424`, `:4549` (fp64 narrowing; ID-15 M-3 is the RULED P3a deviation) | no |
| `MarkBufferGpuWritten` / `MarkGpuWritten` for writable image **buffer textures** | `DirectGLES.cpp:2162-2164` (from `MarkWritableImageBufferTexturesGpuWritten`, `:2149-2167`) | **yes — the only texture-driven GPU-write announcement** |
| SSBO / atomic-counter marks | `DirectGLES.cpp:506-510`, `:556-558` | no |
| `WritebackFromBackend` (pack PBO) | `DirectGLES.cpp:8062`, `:9626`, `:10036`, `Utils.cpp:2343` | **yes — these are the readback writebacks**, each paired with `BumpBufferMutationEpoch()` (`:8068`, `:9628`, `:10038`, `Utils.cpp:2351`) |
| `WritebackFromBackend` (XFB capture) | `DirectGLES.cpp:1017`, `:1125` | no |
| `Ops_ReadbackFromGpu` | `Managers.cpp:1726-1761`, tracked wrapper `:1828-1829`, table row `:2300` | no |
So for P4a: **one** texture-owned `SyncPersistentMappedRange` reach (the buffer-texture backing store, via
`EnsureBufferResource`), **one** texture-owned GPU-write mark (writable image buffer textures), and
**four** readback writebacks that are texture/framebuffer-triggered but land on buffers.
`MarkBufferGpuWritten` is `Managers.cpp:2491-2520` (declared `Managers.h:753-763`); the
`BufferImpl::CurrentBufferMutationEpoch` / `BumpBufferMutationEpoch` contract is documented at length in
`Managers.h:558-593` — note it explicitly lists *"every pack-PBO `WritebackFromBackend` site
(glReadPixels/glGetTexImage)"* (`Managers.h:579`) as a bumping path.
---
## 6. Tests and traces
### 6.1 Unit tests (label `unit`)
- **`MG_Test/SanityTest.cpp`** (4378 lines) — the slot-table suite `DirectGLESSlotTable`:
`ARecycledSlotIsANewHandleAndTheStaleOneResolvesToNothing` `:3316`,
`RepeatedLookupsOfALiveObjectKeepOneHandle` `:3358`,
`ANegativeLookupIsNotCachedAcrossAnotherHoldersAcquire` `:3387`,
`FindNeverMutatesTheTable` `:3416`,
`AWholeTableSavesResetsAndRestores` `:3450`,
`TwoTablesOfTheSameKindShareOneSlotAndKeepTheirOwnTwin` `:3491`,
`OneDeathNoticeDropsTheTwinInEveryHolderOfTheKind` `:3537`,
`AnnouncedDeathKeepsObjectChurnFromAccumulatingWithoutASweep` `:3596`,
`GetOrCreateToleratesANullStateObject` `:3635`,
`AnAnnouncedDeathReturnsTheSlotWithoutASweep` `:3662`,
`EveryReKeyedObjectClassAnnouncesItsOwnDeath` `:3711`,
`TheHandleArmInstallsTheDeathNoticeConsumer` `:3777`,
`TheTwinRegistryCasesInThisBinaryRunOnTheHandleArm` `:3795`,
**`EverySwitchedOverKindResolvesItsTwinThroughTheHandleArm` `:3878`** — drives Texture, Framebuffer,
Renderbuffer, SamplerCso, ShaderCso, VertexElementsCso through
`ExpectTheHandleArmDrivesThisKind` (`:3888-3899`) and then the seventh (Buffer) table by hand
(`:3908-3958`). **This is the case P4a extends** for the kinds it converts to `GetOrCreate(handle)`.
`ASavedCopyOfARealRegistryDropsTheTwinOnTheSameNotice` `:3963`,
`AnArmlessKnobCombinationStopsInsteadOfSkippingTheLane` `:4004`,
`TheArmlessCasesLeaveTheLogPathAndTheConfigAsTheyFoundThem` `:4061`.
Fixture `ScopedDirectGLESTextureBindings` `:218-260` — **the second live holder of kind Texture**
(saves `g_backendTextureObjects` by value at `:224`, resets with `= {}` at `:228`, restores at `:242`),
used at `:353`, `:404`, `:2699`, `:3065`. `EsprytSlotArmEnvironment` `:90-103`.
- **`MG_Test/Framebuffer/FramebufferTest.cpp`** — 60+ `FramebufferTest.*` cases; the ones P4a's
framebuffer record must keep green: `NamedFramebufferTextureAttachesWithoutChangingBindings` `:244`,
`FramebufferTextureBumpsAttachmentVersionOnlyOnce` `:289`,
`ReadPixelsAllowsPersistentMappedPixelPackBuffer` `:310`,
`NamedFramebufferDrawBuffersDoNotModifyDefaultFramebuffer` `:446`,
`DefaultFramebufferProvidesTextureAttachmentsForFrontAndBackAliases` `:492`,
`FramebufferTexture3DAttachesSliceWithLayerTracking` `:825`,
`ThreeChannelColorAttachmentsAreCompleteThroughTheWidenedSubstitution` `:961`,
`TwoAttachmentCompositeFramebufferMatchesIrisComplementaryPass` `:972`,
**`WidenedDrawBufferIsIdentifiedPerDrawBufferSlotNotPerAttachmentPoint` `:1194`**,
`DrawIntoAWidenedDrawBufferReachesTheDriverWithAlphaWritesMaskedOff` `:1227`,
`ClearIntoAWidenedDrawBufferKeepsAlphaWritableAndSubstitutesOne` `:1263`,
plus the `PackedReadbackEncodeTest.*` block `:645-769` (pure readback encoders) and
`ReadPixelsRejectsIntegerFormatMismatchWithReadBuffer` `:785`.
- **`MG_Test/Texture/TextureTest.cpp`** — 192 cases. Directly load-bearing for P4a:
`DepthStencilTextureModeIsBackendVisibleThroughTheParamsVersion` `:2609`,
`ShadowReadbackRefusesALayoutItCannotProduceInsteadOfOverrunningTheBuffer` `:1017`,
`ShadowReadbackRefusesAPackStateItCannotHonour` `:1058`,
`GetTexImageReadsALevelWhoseLowerLevelsWereNeverDefined` `:1971`,
`GetTexImageOfOneCubeFacePacksIntoAOneFacePixelPackBuffer` `:2096`,
`CopyImageSubDataRejectsALevelTheTextureDoesNotHave` `:2531`,
`TextureStorage2DMultisampleTracksNamedObjectState` `:1921`,
the border-colour trio `:610`, `:656`, `:698`, and the compressed-upload/PBO block `:2657-2812`.
`MG_Test/Texture/TextureViewTest.cpp`, `MG_Test/Texture/VkClearManagerTest.cpp`.
- `MG_Test/Backend/DirectGLES/` holds only `BaseInstanceInjectionTest.cpp`,
`EsslShaderPassTest.cpp`, `ViewportIndexRoutingTest.cpp` — **there is no backend-side framebuffer or
texture unit test today**; P4a's emitter tests belong in `MG_Test/Pipe/` beside
`ResourceEmitTest.cpp` and `VertexInputEmitTest.cpp` (the P3a shape), which is also where the
`PipeCatalogueTest.cpp` size pins live.
### 6.2 Integration scenarios (label `integration-gpu` / `integration-verify`)
Registered in `MG_IntegrationTest/CMakeLists.txt`; the framebuffer/texture/renderbuffer set with its
case names:
- **`HandleRecycleScenario`** (`:979-1015+`, four+ pinned lanes): `TheReproducerRecyclesEveryName`,
`AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexInput`,
`ABufferAtARecycledAddressDoesNotInheritItsPredecessorsContents`,
**`ATextureAtARecycledAddressDoesNotInheritItsPredecessorsTwin`** (`Scenarios/HandleRecycleScenario.cpp:869`),
**`AFramebufferAtARecycledAddressDoesNotInheritItsPredecessorsTwin`** (`:920`),
`DestroyedVertexArraysReturnTheirVertexElementsSlots`.
P4a's G8 analogue: add a renderbuffer case and a sampler case here.
- `LayeredAttachmentShapeScenario` (8 cases: `LayeredThreeDColorAttachmentReachesEverySlice`,
`NonLayeredThreeDSliceAttachmentWritesOnlyThatSlice`,
`LayeredCubeMapArrayColorAttachmentReachesEveryLayerFace`,
`LayeredCubeMapArrayDepthAttachmentGatesEveryLayerFace`,
`LayeredCubeMapArrayDepthStencilAttachmentGatesEveryLayerFace`,
`LayeredCubeMapClearMaterialisedBySamplingReachesEveryFace`,
`LayeredOneDArrayClearMaterialisedBySamplingReachesEveryLayer`,
`CubeMapFaceReadbackAnswersTheFaceItWasAskedFor`) — **the direct gate on `MGPSurface`'s
`Layered`/`Level`/`Layer`/`UploadTarget`.**
- `LayeredTextureReadbackScenario` (2), `LayeredAttachmentBarrierScenario`.
- `ThreeChannelAttachmentScenario` (`ThreeChannelColorAttachmentsReportComplete`,
`WidenedAttachmentReadsBackOpaqueWhileItsNeighbourKeepsItsAlpha`,
`DstAlphaBlendingSeesOneInAWidenedAttachment`) — the alpha-widening triple.
- `SnormAttachmentScenario`, `RenderbufferBlendFormatScenario` (3 cases — the only renderbuffer-specific
scenario), `DepthStencilReadbackScenario` + `…MatrixScenario` + `…AttachmentShapeScenario`
(one lane, `TEST_FILTER "DepthStencilReadback*Scenario.*"` at `:639`),
`PackedWordReadbackScenario`, `PixelStoreSweepScenario`,
`ClearThenReadPixelsScenario` (5 cases, incl. `ABlitIntoTheDefaultFramebufferSurvivesAnEarlierClear`
and `AMultisampleResolveBlitIntoTheDefaultFramebufferKeepsItsOrientation`),
`ClearTexImageUndefinedLevelZeroScenario`,
`CopyImageLevelRangeScenario` / `CopyImageLayeredScenario` / `CopyImagePacked16Scenario` (own lane `:806`),
`TextureViewScenario` (8 cases, incl. `BetterCloudsCoveragePipeline` and `CoherencyIsBidirectional`),
`BufferTextureScenario`, `ImageSizeAfterRespecScenario`
(`ADrawSeesTheNewSizeOfARespecifiedImageTexture` — the `RecreateBackendTexture` /
`g_attachmentBackendIdGeneration` gate), `SampledSetStalenessScenario` (2 cases — the
sampling-resolution-generation gate), `ImageTargetKindScenario`, `ImageLoadStoreSsoScenario`,
`NonCoreImageFormatScenario`, `FormatlessImageBakeScenario`, `ImageFormatQualifierScenario`,
`UnboundImageDescriptorScenario`, `IntegerBorderColorScenario` (carries a known ASan
stack-buffer-overflow, ID-21 follow-up), `FragmentOutputArrayIndexScenario`,
`OrientationScenario`, `FragCoordOriginScenario`, `IterationRP*Scenario` ×3, `GuiBatchScenario`.
- `ResourceSubsystemControlScenario.ClearingTheP3aBitsStopsTheEmissionsAndNotThePixels` — the G12
template P4a copies for its own bits; `CsoContentAddressingScenario`; `PipeVerifyArmingScenario`.
### 6.3 Traces most sensitive to this surface
From `tools/trace_replay/trace_cases.json` (40 cases; 79 desktop arms):
- **`improved-transparency-minecraft-26.3`** — the OIT scratch-clear-FBO / draw-buffers-`None` /
read-buffer bug family lives here (`Managers.cpp:7544-7550`). First trace to break on a draw-buffer or
read-buffer regression.
- **`minecraft-1.21.4-fabric-iris-*-in-world`** (17 shader packs: bsl, complementary-reimagined,
complementary-unbound, sundial-lite, iterationt, iterationrp, photon-v1.1/v1.3b, mellow, nostalgia,
bliss, chocapic-v6-lite, super-duper-vanilla, makeup-ultrafast, derivative-main, …) — heavy MRT,
attachment relocation and `glDrawBuffers` permutations; `TwoAttachmentCompositeFramebufferMatchesIrisComplementaryPass`
is the unit-test shadow of this. `iterationrp` has no DirectGLES arm (79 = 40×2 − 1).
- **`minecraft-1.21.4-rd12-odinlite-in-world`** — the VAO/buffer-heavy fixture that cost P3a +30%/+27%
(ID-19/ID-24); also the one that aborts on Xiaomi/Magma pre-existing (ID-23). Texture-upload traffic
is the other half of its frame.
- **`minecraft-1.21.4-fabric-sodium-in-world`** — sub-ms frames, the per-call overhead canary.
- **`minecraft-1.21.1-neoforge-create-instancing-in-world`** (2-frame fixture, not a benchmark) and
**`create-indirect`** (pre-existing `dev` red, BRIEF-P3A.md's first caveat — keep it in the desktop
SSIM corpus, out of the device A/B).
- `minecraft-1.21.4-fabric-{rei,xaero-minimap,xaero-world-map,journeymap,modernui}-*` and
`…-normal-world` — GUI/atlas-heavy, i.e. the `glTexSubImage` union-box vs scatter-rect shape and the
unpack ring; a shape regression there is invisible to SSIM and shows only in
`TextureUploadBoxEmissions` / `TextureUploadRectEmissions` / `TextureUploadJobs`
(`Managers.cpp:6385-6394`).
- `minecraft-1.17-main-menu-854`, `minecraft-1.21.4-fabric-iris-bsl-esc-menu-854`, `OpenRA` — default
framebuffer / blit-to-default paths.
---
## 7. Working notes for the P4a implementer
1. **Seven→ten tables.** P3a converted only the Buffer kind to a call-carried handle
(`Managers.h:690-692`). Framebuffer, Texture, Renderbuffer (and Sampler) still mint inside
`MG_Backend` through `TwinRegistry::GetOrCreate(StatePtr)` (`Managers.h:326-372`) and still depend on
the shared death notice (`Managers.cpp:199-245`). The buffer family's shape — client mints →
`GetOrCreate(handle)` → `ResourceDestroy` retires → **client** frees the slot (`SlotTables.h:337-361`,
`Managers.cpp:233-243`) — is the template. Note the `GetOrCreate(handle)` asymmetry: forward
generations recycle, **backward generations are refused** (`SlotTables.h:301-321`).
2. **`ForEachLive` is the blocker for dropping `Entry::stateRef` on Framebuffer.**
`ScopedDetachedTextureFramebufferAttachments` (`DirectGLES.cpp:6805-6899`) is the only
direct-iteration site and it needs the frontend `FramebufferObject` to read its attachment array. A
handle-keyed FBO table has no `stateRef` (`SlotTables.h:266-269`), so that walk has to be re-expressed
over the applier's `MGPFramebufferState` records before the FBO table can lose its `StatePtr`.
3. **The `Color[8]` / `DrawBuffers[8]` vs 32 mismatch** (§0) has to be ruled on before any emitter is
written; `MAX_COLOR_ATTACHMENT_SLOTS` is 32 at `Managers.h:1579-1581` and `RecomputeBackendColorSlots`
is 32-wide (`Managers.cpp:7443-7448`).
4. **`ContentHash` suppression on `SetFramebufferState`** must not swallow the `fragColorBroadcastCount`
input (§1.6): the broadcast count is read from the frontend *before* the FBO sync precisely so a
program relinks in the same draw. If the FBO record is suppressed, the broadcast count must still be
derivable — either it becomes a field of the record or it stays a separate emission.
5. **`ForceResync` on `MGPTextureParams`** (`MGPipeTypes.h:312-313`) is already the wire spelling of
`m_forceTextureParamsResync`; there is **no** wire spelling of `m_forceSamplerResync`
(`Managers.h:1508-1516`), and the failure mode it guards is not mis-filtering but an *incomplete*
texture that samples `(0,0,0,1)`. That gap is P4a's third contract ruling.
6. **G5-style byte-identity.** P3a's G5 protects eleven buffer-pool/ring functions
(ID-11/ID-13/ID-15). The P4a analogue candidates, if the phase wants one, are the unpack-ring
staging (`StageBlocksIntoUnpackRing`, `Managers.cpp:4947-5001`), `RecomputeBackendColorSlots`
(`Managers.cpp:7432-7519`) and `ScratchFBOImpl`'s attachment shadow (`Managers.cpp:7767-8002`) —
all three are dense, well-tested and have nothing to gain from being rewritten.
7. **Exit order (ID-18/ID-21).** `EnsureProcessTeardownSentinel` / `InProcessTeardown`
(`Managers.cpp:171-180`) gate every twin destructor (`:3556`, `:4693`, `:7026`, `:8085`, `:10432`,
`:10600`), and `OnFrontendStateObjectDestroyed` drops notices during teardown (`:200`). Any new
MGPipe singleton P4a adds must be heap-constructed and intentionally leaked, like the four
`fde5fda3` made never-destroyed.
@@ -0,0 +1,810 @@
# P4a scout — Espryt's sampler / image / program surface
Tree read: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg` at
`feat/disaggregated@37da3c3a` (P3a closed, ID-24). Every line number below was opened in that tree.
Paths are repo-relative under `MobileGL/` unless written out in full.
House shape assumed from `~/w7/notes/p3a/BRIEF-P3A.md` §A/§C and `INTEGRATOR-DECISIONS.md` ID-1..24:
a phase is 4-5 packages (contract → wire → client → backend → gates), the contract commit is tagged
and frozen, G1 (pull build symbol-identical, admitted-resize set EMPTY) is the hardest gate, and every
backend edit lives inside `#if MOBILEGL_PIPE_PUSH`.
---
## 0. The one-paragraph orientation
P3a converted **one** family (buffers) to a handle-addressed op table and **one** CSO (vertex
elements) to an applier record. P4a's sampler/program half is structurally *easier* in one way and
*harder* in three:
* **Easier**: the payloads already exist and are already in the verify comparator's list.
`MGPSamplerDesc` (`MG_Pipe/MGPipeTypes.h:283-287`), `MGPSamplerView` (`:293-304`),
`MGPTextureParams` (`:307-318`), `MGPProgramDesc` (`:323-335`), `MGPBoundView`/`MGPSamplerViews`
(`:432-444`), `MGPSamplerStates` (`:447-451`), `MGPImageView`/`MGPShaderImages` (`:453-468`),
`MGPGlobalConstants` (`:507-513`). All twelve are already in `MGP_VERIFY_PAYLOAD_LIST`
(`MG_Pipe/PipeFields.def:314-336`) with their `MGP_FIELDS_*` tables (`:74-88`, `:108-134`).
The catalogue rows exist too and are `kNone`/`kHasBlob`/`kVarTail` today
(`MG_Pipe/PipeCalls.def:104-110`, `:117-119`, `:127`, `:134-135`).
* **Harder 1**: sampler state has **two** carriers in MobileGL (a `SamplerObject` bound to a unit,
and a `SamplerObject` *owned by every texture object*), and Espryt pushes them through **two
different driver entry-point families** (`glSamplerParameter*` vs `glTexParameter*`), with two
independent caches. §1.
* **Harder 2**: the shader CSO's wire form is SPIR-V + the whole `LinkArtifacts`+`SpirvArtifacts`
archive (`ARCHITECTURE.md:259-266`), but the archive **has no serializer yet** — only the field
tables. §3.9.
* **Harder 3**: three of the four things Espryt's program twin is keyed on are **not program state
at all** (draw-FBO clamp masks, fragColor broadcast count, live image-unit formats, patch
parameters). That is the `st_variant`-style lazy specialisation `ARCHITECTURE.md:264` names, and
it is what stops `create_shader_state` from being self-contained. §3.4.
---
## 1. Samplers
### 1.1 `SamplerParameters` and `BorderColorForm` — the value type
`MG_Pipe/MGPipeValueTypes.h:462-486`. 15 members, `sizeof == 100`, trivially copyable
(`:615` static_assert; pinned again in `MG_Test/Pipe/PipeCatalogueTest.cpp:131` and `:138`):
```
wrapS/wrapT/wrapR SamplerWrapMode (enum class, 4 B each) default Repeat
minFilter SamplerFilterMode default Nearest
magFilter SamplerFilterMode default Linear
mipmapMode SamplerMipmapMode default Linear
minLod/maxLod Float -1000 / +1000
lodBias Float 0
maxAnisotropy Float 1
compareFunc SamplerCompareFunc LessEqual (NOT Never - table 23.18)
compareMode SamplerCompareMode None
borderColor FloatVec4 (0,0,0,0)
borderColorI IntVec4
borderColorUI UintVec4
borderColorForm BorderColorForm : Uint8 Float
```
`BorderColorForm` is declared at `:449-460` with the rationale verbatim: all three representations
are *always* numerically populated, so the value alone cannot say which driver entry point to use.
`MGPipeTypes.h:279-282` says the struct "crosses byte for byte INCLUDING borderColorForm".
> **TRAP (P4a must fix in the contract commit).** `SamplerParameters` has **3 bytes of trailing
> padding** (96 bytes of members + 1 byte `borderColorForm` = 97, padded to 100). There is **no
> `MGP_FIELDS_SamplerParameters`** in `PipeFields.def` (grep: only `RenderStateParameters` at `:233`
> and `PixelStoreParameters` at `:253` of the value structs), and `SamplerParameters` is **not** in
> `MGP_VERIFY_PAYLOAD_LIST`. `MGPSamplerDesc::Parameters` is an `MGPBlobRef`, so under
> `MOBILEGL_PIPE_VERIFY` the blob is compared as bytes and the padding false-differs; and any
> content hash taken over those 100 bytes hashes uninitialised padding, which would mint a fresh
> sampler CSO per call. This is exactly the shape the P3a brief's G7 negative control exists for on
> the vertex side. Add the field table + the verify-list row, and hash/compare field-wise.
### 1.2 The `SamplerCso` slot table (P2)
`MG_Backend/DirectGLES/Managers.h:2228-2229`:
```cpp
extern TwinRegistry<MG_State::GLState::SamplerObject, BackendSamplerObject, MG_Pipe::MGPipeKind::SamplerCso>
g_backendSamplerObjects;
```
defined at `Managers.cpp:10583`. `TwinRegistry` is the alias at `Managers.h:1188-1195` that swallows
the kind parameter in the pull build (G1); the push arm holds a
`BackendSlotTable<SamplerObject, BackendSamplerObject, SamplerCso>` member at `Managers.h:538`, and
`StateBackendObjectRegistry::GetOrCreate` dispatches to it at `Managers.h:325-332` when
`EsprytSlotTablesEnabled()` (`SlotTables.h:132-135`).
The handle-keyed overloads P4a needs already exist and are **unused for this kind**:
`BackendSlotTable::GetOrCreate(MGPipeHandle)` (`SlotTables.h:278-326` — forward Gen = recycle+reset,
**backward Gen = refuse**, `kMaxHandleSlot = 1<<20` at `:148`), `FindByHandle` (`:376-382`),
`ReleaseByHandle` (`:350-361`), `LiveGenAt` (`:331-335`).
**Death today is the shared notice, not a call.** `Managers.cpp:199-247`
`OnFrontendStateObjectDestroyed` switches on kind; `MGPipeKind::SamplerCso` →
`SamplerImpl::g_backendSamplerObjects.DestroyByLifetimeId(lifetimeId)` (`Managers.cpp:211-213`),
which forwards to `BackendSlotTable::OnFrontendObjectDestroyed` (`Managers.h:442-446`,
`SlotTables.h:416-430`). The raiser is `SamplerObject`'s push-only destructor
(`MG_State/GLState/SamplerState/SamplerObject.h:18-24` — declared only under `MOBILEGL_PIPE_PUSH`
so the pull build keeps its implicit dtor, G1). The ops table is installed at `Managers.cpp:247-250`
+ `:326`. **P4a decision owed**: does `SamplerCso` follow buffers (its own `DeleteSamplerState` call,
client frees the slot — the `default:` comment at `Managers.cpp:236-246` spells the ordering rule) or
does it keep the shared notice? The catalogue already has `DeleteSamplerState`
(`PipeCalls.def:105`), and the P3a `VertexElementsCso` case (`Managers.cpp:225-236`) is the
precedent for the **hybrid**: the client speaks the whole death *and* the backend keeps a notice
consumer for the driver object, with a documented double-release that is a no-op.
### 1.3 `BackendSamplerObject` — the twin
Declared `Managers.h:2205-2223`, defined `Managers.cpp:10416-10584`.
| member | line | note |
|---|---|---|
| `m_backendSamplerId` | `Managers.h:2218` | `glGenSamplers` in ctor `Managers.cpp:10417-10429` |
| `m_contextGeneration` | `:2219` | vs `g_backendContextGeneration`; dtor refuses to delete a foreign name |
| `m_isInitialized` | `:2220` | |
| `m_cacheSamplerParameters` | `:2221` | the whole 100-byte struct, as the last-pushed shadow |
| `m_syncedSamplerVersion` | `:2222` | `Uint16`, vs `SamplerObject::GetVersion()` |
`SyncToBackend` (`Managers.cpp:10451-10556`): version early-out at `:10461-10465`; then a
per-field diff against `m_cacheSamplerParameters`:
* min-filter + mipmap-mode fused, through `ResolveBackendMinFilter(params, ShouldAvoidSamplerMipmapMinFilterOnAngleLlvmpipe())`
(`Managers.cpp:10482-10490`; the resolver is `Managers.cpp:100-117` and collapses the four
`*_MIPMAP_*` filters to `GL_NEAREST`/`GL_LINEAR` on ANGLE-on-llvmpipe);
* mag filter `:10491-10497`;
* `SYNC_SAMPLER_PARAM_IF_CHANGED` macro (`:10475-10480`) for wrapS/T/R, compareFunc, compareMode
(`:10498-10502`);
* minLod / maxLod `:10503-10510`;
* maxAnisotropy behind `g_GLESCapabilities.SupportsTextureFilterAnisotropy`, cache updated even when
the call is skipped `:10511-10517`;
* **border colour**, `:10518-10553`: gated on `SupportsTextureBorderClamp`, branches on
`borderColorForm` to `glSamplerParameterIiv` / `Iuiv` / `fv`, with the entry-point null checks;
the redundancy filter compares **all four** (float, int, uint, form) `:10518-10521`.
* **`lodBias` is never pushed here.** ES has no `GL_TEXTURE_LOD_BIAS`; it is folded into the shader
as a uniform — see §3.5.
`Bind(unit)` (`:10558-10566`) dedups against `g_boundSamplersCache[unit]` and calls `glBindSampler`.
`UnbindSampler(unit)` (`:10575-10581`) is the symmetric zero-bind. Destructor
(`:10431-10449`) scrubs **every** row of `g_boundSamplersCache` that names `this` before deleting —
the recycled-heap-address defence that `{slot,gen}` is supposed to retire.
### 1.4 The unit shadow
`Array<BackendSamplerObject*, TextureState::MAX_TEXTURE_IMAGE_UNITS> g_boundSamplersCache`
— declared `Managers.h:2226-2227`, defined `Managers.cpp:10582`. `MAX_TEXTURE_IMAGE_UNITS` is **192**
(`MGPipeTypes.h:429-431` states it: "one Array of MAX_TEXTURE_IMAGE_UNITS = 192", merged unit space,
no stage dimension — which is why `PipeCalls.def:194-196` deliberately drops the stage dimension of
`set_sampler_views`).
This shadow is a **raw twin pointer per unit** and is read by three memos as a proof-of-driver-state
(§1.5, §1.6). Under a split it cannot be a pointer; it becomes the applier's own per-unit
`MGPipeHandle` array. That is the single largest mechanical change on the sampler side.
### 1.5 Per-unit sampler walk — `BindCurrentUnitSamplers`
`MG_Backend/DirectGLES/DirectGLES.cpp:3593-3626`, called last from `BindCurrentTextures`
(`DirectGLES.cpp:3752`).
Two memos stack here:
1. **`UnitSamplerLookupMemo`** (`DirectGLES.cpp:3522-3535`), one row per unit (192 rows). Push arm
stores `MGPipeHandle frontendHandle` (`:3525`); legacy arm stores a `WeakPtr<SamplerObject>`
under `MOBILEGL_PIPE_LEGACY_MEMOS` (`:3528-3530`). `ResolveUnitSamplerBackend`
(`:3537-3572`): push arm probes `g_backendSamplerObjects.HandleOf(sampler)` then `FindByHandle`
(`:3543-3556`); legacy arm uses `OwnerEquals` + `Find` (`:3558-3568`). **A miss is never cached**
(`:3550-3553`) because the program pass creates the twin later in the same draw.
`SlotTables.h:556-561` records that this caller *thrashes* the table's single-entry
lifetime-id memo (a different sampler per unit) — a known, unpaid perf item.
2. **The walk memo** (`DirectGLES.cpp:3588-3593`): `g_unitSamplerWalkContextId`,
`…Epoch`, `…MaxUnit`, `…ContextGeneration`, `…Valid`, plus
`g_unitSamplerWalkRows` — a **full 192-entry copy of `g_boundSamplersCache`**. The replay gate
(`:3597-3604`) is keys-equal **AND** `memcmp` of the first `maxTouchedUnit+1` rows. The
invalidation argument is written out at `:3575-3587`.
The walk itself (`:3605-3616`): for every unit ≤ `maxTouchedUnit`, take
`MGB_CTX->GetTextureUnitObject(unit).GetSamplerObject()`; bind its twin, or `UnbindSampler(unit)`.
### 1.6 `SamplerPassMemo` — the program-side sampler pass
Declared `Managers.h:1913-1924` (with the six-bullet invalidation enumeration at `:1895-1912`),
member at `Managers.h:2117`, accessor `Managers.h:2001`.
```cpp
struct SamplerPassMemo { // Managers.h:1913
static constexpr SizeT kMaxEntries = 16; // :1914
Bool valid; Uint8 count;
Uint64 contextId, unitBindingsEpoch, samplingGeneration;
Uint32 backendStateVersion; Uint textureContextGeneration;
Array<Uint8, 16> units; // :1922
Array<BackendSamplerObject*, 16> rows; // :1923 - driver-state proof
};
```
Consumed in `BindCurrentProgramWithResources` at `DirectGLES.cpp:3922-4038`: the clean test is the
five keys (`:3936-3941`) plus a per-entry row compare against `g_boundSamplersCache`
(`:3942-3950`). A pass touching >16 units, or an out-of-range unit, simply never memoises
(`:3956-3966`). Reset on relink at `Managers.cpp:9258`.
The pass body (`:3954-4030`) does five things per `SamplerUniformBinding`:
1. resolve the frontend unit — `currentProgram->GetUniformSamplerOrImageUnitIndex(frontendLocation)`
(`:3958-3960`);
2. `glUniform1i(backendLocation, unit)` if it moved (`:3971-3974`);
3. the **LOD-bias uniform** (`:3982-4000`) — sampler-object bias wins, else the *texture's own*
sampler's bias, looked up through `SamplerUniformTextureTarget(uniformType)`
(`DirectGLES.cpp:3553`ff mapping table, i.e. `DirectGLES.cpp` right after
`NeedsRawDepthFetchSampler`);
4. the **raw-depth-fetch substitution** (`:4001-4010`);
5. otherwise `SyncToBackend` + `Bind(unit)` on the unit's sampler object, creating the twin if
`ResolveUnitSamplerBackend` missed (`:4011-4026`), or `UnbindSampler(unit)` (`:4027-4029`).
**This is the only site in Espryt that ever creates a `BackendSamplerObject`**
(`DirectGLES.cpp:4014-4020`) — there is no eager `glGenSamplers` at `glGenSamplers` time.
`create_sampler_state` under P4a inverts that: the CSO is minted and emitted at the frontend call,
and the draw path only binds. Say so in the brief; it changes when `glGenSamplers` runs on the
driver and therefore what `MGLOG_E_ONCE("Failed to generate sampler object.")` at
`Managers.cpp:10424` can report.
### 1.7 The raw-depth-fetch sampler
`DirectGLES.cpp:61-62` (two file-static `SharedPtr`s), `:207-219` `GetRawDepthFetchSampler()`,
`:221-235` `NeedsRawDepthFetchSampler()`.
It **constructs a frontend `MG_State::GLState::SamplerObject(0)`** inside the backend
(`:209-214`) purely to reuse `BackendSamplerObject::SyncToBackend`'s signature — nearest/nearest,
no mipmaps, compare mode off, compare func Always. `ARCHITECTURE.md:322` names it explicitly:
> Espryt 的小号同类:`g_rawDepthFetchSamplerState` → 后端原生 sampler。
so P4a is expected to replace it with a backend-native sampler (a `glGenSamplers` id + a literal
parameter push), not to route it through a CSO. `NeedsRawDepthFetchSampler` reads
`IsDepthFormatInternalFormat(textureFormat)` and three sampler params (compareMode, minFilter,
mipmapMode, magFilter) — under a split those come from the **resolved sampler view + the sampler
CSO's parameters**, both of which the applier will hold. `ARCHITECTURE.md:206` already assigns this
post-processing to the **server**, acting on the already-resolved set:
> 两处后端特定后处理留在 server、作用于已解析集合:Espryt 的 raw-depth-fetch sampler 替换、Magma 的 feedback-loop 检测。
### 1.8 Texture-object sampling state — the *second* carrier
Every `ITextureObject` owns a `SamplerObject` (`GetSamplerObject()`), and Espryt pushes it with
`glTexParameter*` in `BackendTextureObject::SyncBuiltinSamplerToBackend`
(`Managers.cpp:6671-6781`):
* version gate on `samplerObject->GetVersion()` **plus** `m_forceSamplerResync`
(`:6683-6690`; the flag's rationale is `Managers.h:1508-1519` — a driver re-mint loses every
pushed parameter, and an incomplete texture samples (0,0,0,1));
* multisample targets take **no** parameters at all — the cache is stamped and the function returns
(`:6706-6710`);
* min/mag filter through the same `ResolveBackendMinFilter`, but with `IsAngleLlvmpipeRenderer()`
rather than the sampler-object predicate (`:6732-6744`) — **an asymmetry to preserve**;
* `SYNC_TEX_SAMPLER_PARAM_IF_CHANGED` (`:6719-6731`) for wrapS/T, wrapR **only when
`SupportsWrapR(targetInternal)`** (`:6752-6757`), compareFunc, compareMode;
* minLod/maxLod/maxAnisotropy `:6758-6776`;
* **no border colour here.** The texture's border colour is pushed from
`SyncTextureParamsToBackend` instead (`Managers.cpp:6911-6954`), reading
`stateTextureObject->GetBorderColorForm()/GetBorderColor()/…I()/…UI()` and comparing against four
separate members `m_cacheBorderColor{,I,UI,Form}` (`Managers.h:1488-1493`). That split matters:
the border colour is *sampler* state per GL 4.6 table 23.18 (`MGPipeValueTypes.h:478-483`) but
Espryt pushes it on the **texture params** version, not the sampler version.
So a P4a `MGPSamplerDesc` covers the *sampler object* half; the texture's own sampling state is
`set_texture_params` (`MGPTextureParams`, `MGPipeTypes.h:307-318`) **plus** a second sampler CSO or
an inline parameter block — and today `MGPTextureParams` carries `BaseLevel/MaxLevel/Swizzle/
DepthStencilMode/ForceResync/MinLod/MaxLod/LodBias` and **no filter, no wrap, no border colour, no
compare mode**. That is a real gap between the payload and what
`SyncBuiltinSamplerToBackend` + the border block actually push. Resolve it in the contract commit —
either widen `MGPTextureParams` (it is 32 B today, `MGP_ASSERT_POD` at `:318`) or give every
texture object an implicit sampler CSO.
### 1.9 Seamless cube maps — a non-item, state it so nobody looks for it
`GL_TEXTURE_CUBE_MAP_SEAMLESS` is **not** sampler state in this codebase. It is
`RenderStateParameters::TextureCubeMapSeamlessEnabled` (`MGPipeValueTypes.h:305`, packed into the
alignment hole so `sizeof(RenderStateParameters)` stays 1168 — `:292-303`), lives in the **P1
pipeline chunk** (`MG_Pipe/MGPipeRenderStateSpans.h:64-67`), and therefore already crosses as part
of `create_render_state`/`bind_render_state` since P2. `PipeApply.cpp:72` and `:370` carry it in the
capability list. **`grep -rn CubeMapSeamless MG_Backend/` returns nothing** — no backend reads it
(ES 3.0+ cube sampling is unconditionally seamless), and the frontend answers `glIsEnabled` from
`RenderState.cpp:340` / `:420`. Nothing for P4a to do.
### 1.10 Complete list of sampler-state reads from backend code
| site | file:line | reads |
|---|---|---|
| `DirectGLES.cpp:227` | raw-depth probe | `samplerObject->GetAllSamplerParameters()` (compareMode, minFilter, mipmapMode, magFilter) |
| `DirectGLES.cpp:3607` | unit walk | `GetTextureUnitObject(unit).GetSamplerObject()` |
| `DirectGLES.cpp:3986` | LOD bias | `samplerObject->GetLodBias()` |
| `DirectGLES.cpp:3993-3995` | LOD bias fallback | `boundTexture->GetSamplerObject()->GetLodBias()` |
| `DirectGLES.cpp:4004-4008` | raw-depth gate | unit sampler, else `texture2D->GetSamplerObject()`; `texture2D->GetFormat()` |
| `DirectGLES.cpp:3468-3474` | completeness | `textureUnit.GetSamplerObject()` else `textureObject->GetSamplerObject()`, then `MG_State::GLState::SamplesAsIncompleteTexture` (`MG_State/GLState/TextureState/TextureObject.cpp:489-512`) |
| `Managers.cpp:6705` | texture built-in sampler | `samplerObject->GetAllSamplerParameters()` |
| `Managers.cpp:6683` | version gate | `samplerObject->GetVersion()` |
| `Managers.cpp:10473` | sampler object | `stateSamplerObject->GetAllSamplerParameters()` |
| `Managers.cpp:10461`,`:10471`,`:10502` | ids/versions | `GetVersion()`, `GetExternalIndex()` |
| `Managers.cpp:6925`,`:6932`,`:6937`,`:6942` | border | `GetBorderColorForm/I/UI/…` on the **texture object** |
| `Managers.cpp:4838` | reset | `m_cacheSamplerParameters = SamplerParameters{}` (on backend texture re-mint) |
`DirectVulkan` uses the same helpers (`MG_Backend/DirectVulkan/Renderer/UniformManager.cpp:515`,
`:828`, `:857`, `:1676`) — a reminder that `SamplesAsIncompleteTexture`/`IsUndefinedDefaultTexture`
resolution is shared and, per `ARCHITECTURE.md:206`, moves **client-side** in P4a
("~40 行搬迁"), leaving only the two backend-specific post-processings on the server.
---
## 2. Images (`set_shader_images`' counterpart)
### 2.1 The payload that exists
`MGPImageView` (`MGPipeTypes.h:453-462`): `Res, Unit, InternalFormat, Layer, Level:Uint16,
Layered:Uint8, Access:Uint8` (24 B). `MGPShaderImages` (`:464-468`): `Start, Count, ContentHash`
var-tail header. Fields tables `PipeFields.def:117-121`.
Catalogue row `PipeCalls.def:119` — `kCtxState, kVarTail`.
Coverage row `Coverage.def:85` maps `GetImageTextureBinding → SetShaderImages`.
Dirty bit `MGPipeDirty::NewShaderImages` (`MG_Impl/Pipe/Tracker.h:79`), computed at
`Tracker.h:311-312` as `mix(mix(textureContent, textureParams), programImageUnitVersion)` — already
live, just not emitted (`kMGPipeDirtyEmittedAtP3a` at `Tracker.h:104-107` stops at bit 10).
### 2.2 The single funnel: `SyncImageTextureBinding`
`DirectGLES.cpp:2057-2135`. Everything about an image unit passes through here — the file says so at
`:2019-2021` ("`glBindImageTextures` is a frontend loop over `glBindImageTexture`, and the whole-sweep
`SyncImageTextureBindings` goes through it too"). It:
* maintains `g_writableImageBufferUnits[192]` + `g_writableImageBufferUnitCount`
(`:2029-2031`, tracker `:2038-2054`, predicate `:2033-2036`);
* maintains `g_imageUnitHighWaterMark` (`:2055`, bumped `:2063-2065`);
* unbinds with `glBindImageTexture(unit, 0, 0, GL_FALSE, 0, GL_READ_ONLY, GL_RGBA8)` `:2066-2069`;
* calls `SyncTextureObjectToBackend(texture, /*imageBindableStorageRequired=*/true)` `:2071` —
**this is the call that forces immutable storage and can re-mint the ES texture name**;
* normalises `layered`/`layer` through `SupportsLayeredImageBinding` (`:1992-2013`, and note the
rule: it asks the **backend** target after `MapToBackendTextureTarget`, and `layer` is forced to 0
for a non-layerable target — Adreno took a stray layer index literally);
* rewrites the bind **format**: buffer textures take the *split* view
(`GetImageBindableBufferSplitFormat`, `backendTexture->GetBufferImageSplitViewId()`,
`:2126-2138`), everything else takes the *widening*
(`GetImageBindableStorageWidening`, `:2139-2145`);
* finally `glBindImageTexture(unit, bindTextureId, Level, layered, layer, Access, bindFormat)` `:2133`.
`MarkWritableImageBufferTexturesGpuWritten` (`DirectGLES.cpp:2147-2171`) is the GPU-write
announcement for buffer textures on writable image units; under push it already routes through
`BufferImpl::MarkBufferGpuWritten` (`:2166-2169`), i.e. the P3a reverse channel.
`SyncImageTextureBindings` (`:2173-2185`) sweeps `min(192, MaxImageUnits)` units.
### 2.3 The image sweep memo
`DirectGLES.cpp:2190-2193` (`g_imageSweepContextId`, `g_imageSweepSamplingGeneration`,
`g_imageSweepBackendContextGeneration`, `g_imageSweepValid`), gate
`SyncImageTextureBindingsForDraw` at `:2202-2214`. Two properties P4a must keep:
* the `g_imageUnitHighWaterMark == 0` early-out (`:2203`) is what makes every Minecraft draw pay one
integer test;
* the gate key is deliberately the **frontend** sampling-resolution generation and **not** a
backend re-mint counter, because a texture bound *only* to an image unit is re-minted *inside* the
sweep (`:2195-2201`). A server-side epoch would be bumped after the gate had already declined.
Called from the draw path at `DirectGLES.cpp:3355`.
### 2.4 The photon canary — image binding semantics
Memory `flywheel-indirect-lessons` item 5 (and item 2) applies directly, and its mechanism is in
this tree:
* `RebindImageUniformsToFrontendUnits` (`Managers.cpp:602-651`) rewrites every image uniform
declaration's `layout(binding = N)` to the **frontend-tracked unit**
(`GetUniformLocation` → `GetUniformSamplerOrImageUnitIndex`, `:627-635`), because glslang
auto-assigns a binding when desktop GL source omits one while the app picks the unit with
`glUniform1i` (illegal on ES image uniforms). Called at `Managers.cpp:9800`, and the ordering
constraints against `BakeImageFormatQualifiers` / `RemapImageArrayElementUnits` /
`SplitReadWriteImageUniforms` / `RemoveLayoutBinding` are spelled out at `:9801-9851`.
* `IsImageUniformType` (`Managers.h:1826-1867`) is the **33-entry** contiguous block
`GL_IMAGE_1D`..`GL_UNSIGNED_INT_IMAGE_2D_MULTISAMPLE_ARRAY`; the header records that the earlier
15-entry list caused two bugs (a non-baked non-core format losing the stage, and an image uniform
assigned with `glUniform1i`).
* `CacheResourceLocations` skips image uniforms entirely (`Managers.cpp:10316-10321`).
**The canary itself** (from the memory note, still the rule): real-device Flywheel testing does NOT
cover Iris packs; `photon-v1.3b` on llvmpipe retrace is what catches an image/SSBO binding-semantics
regression. `MEASUREMENTS`/roadmap caveat: photon is broken on Adreno (memory
`photon-broken-on-adreno`) — run it on llvmpipe, not on the phone. P4a moves the image-unit
resolution to `set_shader_images` records and the *format bake* stays server-side (the format the
shader was built against is live `glBindImageTexture` state, §3.4), so this is precisely the change
the canary exists for. **Recommend the brief pin `photon-v1.3b` desktop retrace as a named G3b
case for P4a.**
### 2.5 Format-less image bake (the fourth staleness key)
`ImageFormatBakeInputs` (`Managers.h:2170-2199`) + `CollectImageFormatBakeInputs`
(`Managers.cpp:8327-8390`): walks the program's uniform reflection
(`GetMaxUniformLocation`/`GetUniformName`/`GetUniformType`/`GetUniformTypeFacts`, `:8346-8351`),
resolves each format-less image's unit (`GetUniformSamplerOrImageUnitIndex`, `:8377`), reads the
**live** bound format (`BoundImageUnitFormat`, `Managers.cpp:8155-8161`) and mixes a signature
(`MixImageUnitFormat`, `:8163`). Stored on the twin as `m_formatlessImageUnits` +
`m_imageUnitFormatSignature` (`Managers.h:2118-2119`, written `Managers.cpp:9287-9288`) and
re-checked per draw by `ImageUnitFormatsStillMatch()` (`Managers.cpp:8544-8547`, declared
`Managers.h:2030`), consumed in the rebuild condition at `DirectGLES.cpp:3164`.
`FormatlessImageBakeScenario` and `NonCoreImageFormatScenario` are its itests.
---
## 3. Programs
### 3.1 The `ShaderCso` slot table and the composite band
`Managers.h:2130-2131` / `Managers.cpp:8065`:
`TwinRegistry<ProgramObject, BackendProgramObjectImpl, MGPipeKind::ShaderCso> g_backendProgramObjects`.
Slot space: `MGPipeHandles.h:84-92` reserves the **top 1/16** of the `ShaderCso` space
(`kMGPipeShaderCsoSlotLimit = 1<<20`, `kMGPipeShaderCsoCompositeSlotBase = limit - limit/16`) for
**program-pipeline composites**, with `MGPipeIsCompositeShaderSlot(slot)` at `:90-92`. That band is
allocated and asserted but **nothing mints into it yet** — P4a's composite resolver does.
Resolution today, `PrgramImpl::SyncCurrentProgram` at `DirectGLES.cpp:3104-3128`: push arm
`g_backendProgramObjects.Find` → `GetOrCreate` (`:3106-3113`); legacy arm goes through
`g_programTwinLookupMemo` (`DirectGLES.cpp:134-135`, an 8-entry `TwinLookupMemo` declared at
`DirectGLES.cpp:93`), `:3115-3127`. A per-draw stash `g_currentDrawFrontendProgram` /
`g_currentDrawBackendProgram` is written at `:3202-3203` and read at `DirectGLES.cpp:3775-3778`
and `:4046-4052`.
### 3.2 The rebuild condition — nine clauses, and where each one comes from
`DirectGLES.cpp:3148-3200`. `twin->SyncToBackend(currentProgram)` runs when **any** of:
| clause | line | source of truth |
|---|---|---|
| no backend program id | 3148 | |
| `GetSyncedLinkVersion() != GetLinkVersion()` | 3150 | program state |
| `GetSyncedImageUnitVersion() != GetImageUnitVersion()` | 3151 | program state |
| snorm clamp mask ≠ `g_snormFallbackClampOutputMask` | 3152 | **draw FBO** |
| unorm clamp mask ≠ `g_unormFallbackClampOutputMask` | 3153 | **draw FBO** |
| `GetFragColorBroadcastCount() != g_fragColorBroadcastCount` | 3154 | **draw FBO**, memoised at `:3078-3101` |
| SSBO binding signature ≠ `ComputeShaderStorageBlockBindingSignature(*program)` | 3155-3156 | program state |
| `!ImageUnitFormatsStillMatch()` | 3164 | **live image-unit state** |
| patch-vertices/outer/inner mismatch (bitwise compare, NaN-safe — `:3183-3186`) | 3188-3196 | **context state** (`MGB_CTX->GetPatchVertices()` etc.) |
The comment at `:3187-3199` explains why the `gl_PerVertex` member set needs **no** clause on this
backend (it mirrors the neighbouring stages' emitted ESSL) while DirectVulkan does.
`GetSyncedLinkVersion()` call sites: `DirectGLES.cpp:3150`, `:4110`, `:7857`; written once at
`Managers.cpp:10234`; declared `Managers.h:2004`.
### 3.3 The `BackendProgramObjectImpl` surface
Class `Managers.h:1873-2122`. Public accessors that P4a's `MGPProgramDesc`/applier must reproduce
or replace: `GetIndirectParamsBinding` (`:1959`), `GetBackendProgramId` (`:1960`),
`IsBackendProgramUsable` (`:1964`), `GetBackendGlobalUBOId` (`:1965`),
`GetSnormFallbackClampOutputMask`/`GetUnormFallbackClampOutputMask` (`:1966-1967`),
`GetFragColorBroadcastCount` (`:1968`), `GetShaderStorageBlockBindingSignature` (`:1973`),
`GetAtomicCounterBindings` + `GetAtomicCounterEsslBindingTop` (`:1979-1980`),
`GetPassthroughTessControl{PatchVertices,OuterLevel,InnerLevel}` (`:1986-1998`),
`HasGlobalUboBlock` / `GetUniformBlockBackendIndices` / `GetSamplerUniformBindings` (`:1997-1999`),
`GetLastUploadedGlobalUboVersion`/`Set…` (`:2000-2001`), `GetGlobalUboBackendBlockSize` (`:1999`),
`GetGlobalUboRingAllocation` (`:2000`), `GetSamplerPassMemo` (`:2001`),
`ReadsDrawID`/`ReadsBaseVertex`/`RoutesViewportIndex` (`:1946-1958`),
`SetBaseInstance`/`SetBaseInstanceWordIndex`/`SetDrawID`/`SetBaseVertex`/`SetViewportPassMask`
(`:1939-1952`). Private state at `:2066-2121`.
`SamplerUniformBinding` (`Managers.h:1880-1891`): `frontendLocation, backendLocation, uniformType,
lastAssignedUnit, lodBiasLocation, lastAssignedLodBias`. Built once per link in
`CacheResourceLocations` (`Managers.cpp:10264-10345`), which also does the array-element
subscripting fix (`SubscriptUniformNameForElement`, `Managers.cpp:10245-10256` — reflection names an
array after its first element at every location it spans, so `goku[7]` needed its own
`glGetUniformLocation`).
### 3.4 `SyncToBackend` — what it reads from the `ProgramObject`
`Managers.cpp:9230-10240`. The complete read set with line numbers (the P4a archive must supply
every one of these, or the call must carry it):
```
9241 GetExternalIndex 9248 GetLinkStatus / GetSpirvStatus
9268 GetShaderStorageBlockBindingOverrides (-> SpvcSession::SetShaderStorageBlockBinding)
9335 GetLinkedShaderStages 9336 GetGeneratedSpirv 9347 PointSizeDemoted
9357 GetLinkedShaderSnapshot 9366 GetSpirvValidationEnabled
9375 GetTransformFeedbackVaryings 10017 GetTransformFeedbackVaryingCount
10067 GetTransformFeedbackBufferMode 10217 GetUBOSize
10234 GetLinkVersion 10235 GetImageUnitVersion
10290 GetActiveUniformBlocksCount 10295 GetUniformBlockName
10310 GetMaxUniformLocation 10312 GetUniformName 10314 GetUniformType
8119 GetShaderStorageBlockBindingOverrides (signature)
8346-8351 GetMaxUniformLocation/GetUniformName/GetUniformType/GetUniformTypeFacts
8377 GetUniformSamplerOrImageUnitIndex 8506/8513 GetUniformLocation / UniformLocationsAliasSameUniform
622/627 (RebindImageUniformsToFrontendUnits) GetUniformLocation / GetUniformSamplerOrImageUnitIndex
```
`ARCHITECTURE.md:264` names the **eight extra inputs** the backend program depends on beyond the
artefacts, and the list above matches: draw-FBO snorm/unorm clamp masks, fragColor broadcast count,
storage-block binding signature, atomic-counter set, live image formats, patch parameters (+ Magma's
default-FB height and XFB layout). `create_shader_state` publishes the **artefacts**; the server
specialises at verb time. That is the design; nothing in this tree contradicts it.
### 3.5 Sampler/LOD-bias/UBO/atomic-counter binding at draw time
`BindCurrentProgramWithResources` (`DirectGLES.cpp:3765-4041`), in order:
1. `backendProgram.Use()` (`:3781`; the impl is `Managers.cpp:10347-10390`, with the
`m_rebindAfterRelink` rule — a relink replaces the executable behind an unchanged GL name);
2. **global UBO / default uniform block** (`:3786-3856`): `GetUBOSize()`, `GetUBOContentVersion()`,
`MapUBO()`; preferred path is the shared persistent-mapped **UBO ring**
(`UboRingAvailable/UboRingAllocate/UboRingMappedPtr/UboRingBufferId`, `:3805-3831`) with a
per-program `UboRingAllocation` keyed `{contentVersion, ringGeneration, frameSerial, offset}`
(`Managers.h:2003`, `BufferImpl::UboRingAllocation`), and a `glBufferSubData` fallback
(`:3833-3852`). Bytes are accounted to `PipeStats::ByteClass::StageUboGlobal`
(`MG_Util/Metrics/PipeStats.h:55-57`). **This is `set_global_constants`'
(`MGPGlobalConstants{ShaderCso, Version, Blob}`, `MGPipeTypes.h:507-513`, "covers the DEFAULT
UNIFORM BLOCK only (D6)") counterpart** — the ring is on `ARCHITECTURE.md:315`'s
do-not-touch list, so the P4a shape is: the client emits the block image + version, the server
keeps the ring exactly as-is;
3. **named UBOs** (`:3857-3910`): `blockBackendIndices` from the link cache,
`currentProgram->GetUniformBlockBinding(i)`, `MGB_CTX->GetBufferBindingPoint(Uniform, binding)`,
then the P3a buffer clean-probe (`GetBufferResource`/`IsBufferDrawClean`/`EnsureBufferResource`,
`:3884-3894`) and `BindBufferBaseCached`/`BindBufferRangeCached`. This is
`set_shader_buffers(Uniform)` — **P4b, not P4a** (dirty bits 15-17, `Managers.h:717-723` says so
explicitly);
4. **atomic counters** (`:3912-3921`) via `SyncAtomicCounterBuffers(bindings, esslBindingTop)`;
5. the sampler pass (§1.6).
### 3.6 The SPIR-V → ESSL transpile: what is per-program and what is per-context
* **`SpvcSession` is per STAGE, per transpile, and stack-allocated**:
`MG_Util/ShaderTranspiler/SpvcSession.h:89-105` (move-only, non-copyable), constructed at
`Managers.cpp:9019-9020` inside `TranspileSpirvToEssl`. Nothing persists it. Its mutators that
carry program state: `SetShaderStorageBlockBinding` (`SpvcSession.h:120`, called
`Managers.cpp:9037-9039`), `SetAtomicCounterBlockBindings` (`SpvcSession.h:135`, called
`Managers.cpp:9060-9061`, and **both halves are memo state** — the top is key, the returned
bindings are payload, `:9051-9059`), `SetVertexAttribLocation` (`:109`),
`DropDefaultFragmentOutputColorIndex` (`:154`), `RelaxReadWriteExclusiveStorageBuffers` (`:175`),
`ReflectTransformFeedbackCaptures` (`:189`), `StripTransformFeedbackDecorations` (`:201`),
`SetEntryPoint` (`:202`), `SetSpecializationConstants` (`:210`).
* **The L2 ESSL translation cache is per PROCESS**: `GetEsslTranslationCache()`
(`MG_Util/ShaderTranspiler/TranslationCache.h:698`), consulted at `Managers.cpp:9664-9720`.
Key inputs `EsslTranslationKeyInputs` (`TranslationCache.h:635-689`) mix **driver capability bits**
(`viewportIndexLoweringArmed`, `supportsNoperspectiveInterpolation`,
`supportsExtendedImageFormats`, the four sample-count limits) with **per-program/per-context**
inputs (`xfbCaptureBlockNames`, `glFormatByUniformName`, `storageBlockBindingOverrides`,
the two block-rename maps, the two location-strip flags, `atomicCounterEsslBindingTop`,
`esslVersion`, `enableSpirvValidation`). Payload `EsslTranslationResult` (`:618-632`) carries the
ESSL **plus** `flattenedXfbBlockNames` **plus** `atomicCounterGlBindings` — the header records
why dropping either is a silent-wrong-output bug. `Managers.cpp:8556-8558` states the invariant:
*every* read inside `TranspileSpirvToEssl` must appear in `BuildEsslTranslationKey`.
`MG_Test/ShaderTranspiler/TranslationCacheTest.cpp` is its unit test.
* **`InvalidateCompileEnv()` is a forwarded (F-class) `PipeInputs` accessor**
(`MG_Backend/MGPipe/PipeInputs.h:573`), i.e. already a reverse call rather than a state read.
`ARCHITECTURE.md:258-260`: glslang stays entirely on the **client**, SPIRV-Cross
(`TranspileSpirvToEssl`) entirely on the **server**, file-level cut. No `MOBILEGL_IPC_PROGRAM`
switch, no server-side compile pool.
### 3.7 What a shader CSO on the wire must carry
`MGPipeTypes.h:320-335`:
```cpp
struct MGPProgramDesc { // 192 B
MGPipeHandle Cso;
Uint32 StageMask; // == GetLinkedShaderStages()
Uint32 GlobalUboSize;
Uint32 ReservedNumSamplesOffset;
Uint8 SpirvStatus, NativeFloat64, PointSizeDemoted, EnableSpirvValidation;
MGPBlobRef Spirv[6]; // per stage
MGPBlobRef Reflection; // the whole LinkArtifacts + SpirvArtifacts archive
};
```
`ARCHITECTURE.md:259` enumerates what the archive **must** cover: the four `ResourceReflection`
vectors (each with its `TypeFacts`), `uniformSamplerOrImageUnitIndex`, `uniformBlockBinding`,
`shaderStorageBlockBinding` (by name), `explicitOpaqueUniformBindings`,
`xfbVaryings/xfbStrides/xfbPackedStride/xfbNeedsScatteredCapture`, `computeLocalSize`, the GS/TCS/TES
facts, `usesReservedNumSamples`, `uniformOffsets`; and `XfbVarying` carries two spellings (GL name
+ block instance/member/element).
### 3.8 `ProgramArtifacts.h` — the archive as it stands
`MG_State/GLState/ProgramState/ProgramArtifacts.h`, 576 lines, extracted at P0.5. Purity is asserted
by `check_include_closure.py`'s `artifacts-header` probe (`:16-19`), and the header notes that it is
glslang-free **by symbol**, not textually (`:10-15`).
* `TypeFacts` (`:31-59`, 20 fields, POD, `sizeof == 44` pinned at `:552`);
* `ResourceReflection` (`:63-86`, 14 fields, `sizeof == 128` on libstdc++);
* `XfbVarying` (`:95-121`, 11 fields, `sizeof == 128`);
* `LinkArtifacts` (`:160-345`, **58 members**, `sizeof == 1056`), including the live
`SharedPtr<glslang::TProgram> program` at `:165` that is **null for every archived instance by
construction** and is the one member `VisitFields` deliberately omits (`:471-474`);
* `SpirvArtifacts` (`:365-402`, 8 fields, `sizeof == 88`): `generatedSpirv`,
`enableSpirvValidation`, `uniformOffsets`, `globalUboScratch`, `reservedNumSamplesOffset`,
`spirvStatus`, `nativeFloat64`, `pointSizeDemoted`.
* **The visitor tables**: `VisitFields(TypeFacts)` `:408-434`, `(ResourceReflection)` `:436-453`,
`(XfbVarying)` `:455-469`, `(LinkArtifacts)` `:471-535` (57 fields), `(SpirvArtifacts)` `:537-547`.
Contract at `:404-407`: `v(const char* name, Field&)`, `Field` const when `Self` is const, so **one
table serves both directions**.
* **Trip wires** `:549-575`: `sizeof` static_asserts, pinned **per STL** — libstdc++ numbers are in
the tree, the libc++/NDK branch at `:565-566` is **inert until the integrator pins it**
(`MGL_ARTIFACT_SIZES_LIBCXX_PINNED`). `MG_Test/Program/ProgramArtifactsTest.cpp` records every
`sizeof` as a ctest property on every platform.
> **The serializer does not exist.** Grep finds no writer/reader over these tables — only the tables
> and the size asserts. Every `VisitFields` comment says "(and its serializer when one exists)".
> **P4a's contract package owns writing it**, and the NDK `sizeof` pin at `:565-566` is a
> gate the integrator must close in the same phase, or an Android build silently has no trip wire.
### 3.9 Program-pipeline composites (`ProgramPipelineScenario`)
`GLContext::GetProgramForDraw()` (`MG_State/GLState/Core.h:190`, `Core.cpp:609`) already flattens a
pipeline into one hidden composite `ProgramObject` **entirely in the frontend**, which is why
`ARCHITECTURE.md:212` says the tracker pushes **one** handle out of the composite band and the
server never learns it is a composite. Two signatures decide the work
(`MG_State/GLState/ProgramState/ProgramPipelineObject.h`):
* `ComputeDrawProgramSignature` (`:97-107`) — `{lifetimeId, GetLinkVersion()}` per graphics stage;
the header (`:75-85`) records that keying on `GetBackendStateVersion()` instead made the SSO
conformance loop rebuild the composite (glslang + SPIR-V + spirv-opt) **on every draw**;
* `ComputeUniformMirrorVersions` (`:125-141`) — the per-stage refresh gate, mixing
`backendStateVersion<<32 | uboContentVersion` and `blockBindingVersion<<32 | uniformWriteSetVersion`.
`DirectGLES.cpp:3157-3163` records the accident this removed: `glUniform1i` on an image uniform used
to bump the composite's cache key and therefore produce a whole new twin.
`ProgramPipelineScenario.cpp:1-28` lists the sixteen conformance cases (compute_shader.*,
shader_image_load_store.advanced-sso-*, shader_storage_buffer_object.basic-syntaxSSO /
basic-noBindingLayout) that depend on the flattening. `MG_Test/Program/ProgramPipelineCompositeTest.cpp`
is the unit-level pin.
### 3.10 The "CompositeResolver"
**It does not exist in the tree.** `grep -rn CompositeResolver MobileGL/` returns nothing; the only
two mentions are `docs/Disaggregated/ARCHITECTURE.md:562` (the P2+ file list for `MG_Impl/Pipe/`,
which today holds `CsoCache.h, PipeFill.cpp, PipeFill.h, ResourceTracker.h, SetHashSuppressor.h,
SlotAllocator.{h,cpp}, Tracker.h, VertexInputEmit.h`) and `ROADMAP.md:20` (P4a's own row).
From `ARCHITECTURE.md:212` and `MGPipeHandles.h:84-92`, what it composes is **program + program**:
the pipeline's per-stage `ProgramObject`s → one `ShaderCso` handle out of the reserved top-1/16 band,
with the pipeline cache's eviction releasing the slot, bumping `gen` and emitting
`delete_shader_state`. It is **not** a framebuffer/sampler composer — those are separate
(`set_framebuffer_state`, `bind_sampler_states`). Its side benefit, stated at `:212`: the blocking
`JoinLinkAndSpirv()` leaves the server's draw path. Model it on `MG_Impl/Pipe/CsoCache.h`
(`kMGPipeCsoCacheCapacity = 64` at `:53`, `Acquire` at `:74`, `Counters` at `:57-69`, LRU eviction,
and the `kMGPipeBehaviourNoCsoContentAddressing` negative control at `:30-37`).
---
## 4. Emulations that touch programs — which stay frontend-side
`ARCHITECTURE.md:216` is the rule: *驱动表达不了的变换在 tracker 里 lowering,硬件/驱动强加的变换在
driver 里 lowering*, and the per-emulation table is `:221-243`.
| emulation | code | verdict |
|---|---|---|
| **fragColor broadcast** | `PrgramImpl::BroadcastLegacyFragColor` (`Utils.h:260`, `Utils.cpp:506`), called `Managers.cpp:9854`; the count is `g_fragColorBroadcastCount` (`Managers.h:2129`) memoised from the draw FBO's `GetDrawBuffers()` at `DirectGLES.cpp:3078-3101`, snapshotted onto the twin at `Managers.cpp:9261` | **SERVER.** It is a post-emission ESSL rewrite (`ARCHITECTURE.md:315` do-not-touch: "SPIRV-Cross 会话与 post-emission ESSL 重写"), keyed on framebuffer state the server already holds after `set_framebuffer_state`. |
| **noperspective** | `ShaderCompiler::EmulateNoPerspectiveForEssl`, `Managers.cpp:8789-8792`, armed on `!g_GLESCapabilities.SupportsNoperspectiveInterpolation` (`:8788`); the arming bit is L2 key material (`TranslationCache.h:661`) | **SERVER.** Driver-capability-armed SPIR-V pass; the client cannot know the arming. |
| **fp64 demotion** | `DemoteFloat64Pass`, decided **per program at link** and recorded as `SpirvArtifacts::nativeFloat64` (`ProgramArtifacts.h:378-390`); read by `BackendObject.h:496`, `Managers.cpp:3522`/`:3924`, DirectVulkan `VertexInputStateFactory.cpp:253`/`:494`, and by the frontend uniform path `GL_Program.cpp:1319`/`:1643`/`:1784` | **CLIENT (already).** The demotion happens before the archive exists; the flag rides in `MGPProgramDesc::NativeFloat64` (`MGPipeTypes.h:329`) so the server knows the layout. The **vertex-side** fp64 narrowing is server-side (`ARCHITECTURE.md:233`), and ID-15's M-3 ruled the P3a `SyncGpuWrites` gap on that stream a deviation — **P4a inherits that open item**. `DoublePrecisionScenario` is the gate. |
| **XFB scatter** | `XfbImpl` in `DirectGLES.cpp:895-1230`: `XfbCaptureTarget` `:895`, `scattered/scatterProgram/scatterCapacityVertices` `:922-924`, `g_scatterBufferId` `:930`, `ReadbackCapturedRanges` `:987`, `BindScatterCaptureBuffer` `:1032`, `ScatterCapturedRecords` `:1068-1140`, armed at `StartPendingTransformFeedback` `:1210` off `program->NeedsScatteredTransformFeedbackCapture()` (`ProgramObject.h:1227` → `xfbNeedsScatteredCapture`) | **CLIENT** — `ARCHITECTURE.md:239` and §8.5. The read-modify-write moves to the client. Note `Managers.h:576-580`: `ReadbackCapturedRanges` and the scatter path are two of the backend-initiated shadow writebacks that bump the buffer-mutation epoch **without** an op — P3a's epoch contract already names them, and a P4a move must not orphan those bumps. |
| **texture LOD bias** | `EmulateTextureLodBias` (`Utils.h:536`, called `Managers.cpp:9855`) + the per-draw `glUniform1f` at `DirectGLES.cpp:3982-4000` | **SERVER** (post-emission rewrite), but the *value* is sampler state and must arrive with the sampler CSO / sampler view. `MGPTextureParams::LodBias` exists (`MGPipeTypes.h:317`) but `SamplerParameters::lodBias` (`MGPipeValueTypes.h:470`) is the one the pass reads. |
| **image format bake / widen / split / array remap** | §2.5, plus `BakeImageFormatQualifiers` (`Utils.h:313`), `RemapImageArrayElementUnits` (`:365`), `SplitReadWriteImageUniforms` (`:519`), `RemoveLayoutBinding` (`:314`) | **SERVER.** `ARCHITECTURE.md:235`: image-bindable 存储加宽/拆分 → server. |
| **pass-through TCS synthesis** | `AttachPassthroughTessControlStage` (`Managers.h:2041-2044`), `BuildPassthroughTessControlEssl` (`Utils.h:408`) | **SERVER**, keyed on `set_patch_state` (already P2). |
Everything in this table except fp64-demotion and XFB scatter stays on the server, which is why the
shader CSO's payload is SPIR-V + archive and **not** ESSL.
---
## 5. Tests
### 5.1 Integration scenarios that already exercise this surface
All rows are in `MG_IntegrationTest/CMakeLists.txt:56-135`.
*Samplers / border colour*: `IntegerBorderColorScenario` (`:127`) — the `borderColorForm` scenario;
its header (`Scenarios/IntegerBorderColorScenario.cpp:9-33`) documents the exact Espryt failure
(1132396544 = the bits of 255.0f read through an integer sampler) and the Vulkan
`VK_EXT_custom_border_color` requirement. **ID-21 records a pre-existing ASan stack-buffer-overflow
in this scenario** — a test bug, and P4a will be running it a lot.
Also `SampledSetStalenessScenario` (`:65`), `TextureViewScenario` (`:114`),
`ClearTexImageUndefinedLevelZeroScenario` (`:128`).
*Images*: `ImageLoadStoreSsoScenario` (`:88`), `ImageTargetKindScenario` (`:89`),
`ImageFormatQualifierScenario` (`:90`), `NonCoreImageFormatScenario` (`:91`),
`ImageSizeAfterRespecScenario` (`:92`), `FormatlessImageBakeScenario` (`:100`),
`UnboundImageDescriptorScenario` (`:126`), `AtomicCounterScenario` (`:119`).
*Programs*: `ProgramPipelineScenario` (`:87`), `PostLinkAttachScenario` (`:99`),
`RelinkStageSetScenario` (`:124`), `AsyncCompileScenario` (`:61`, with two pinned-config lanes at
`:679-753`), `PipelineFailureScenario` (`:68`), `SpirvShaderBinaryScenario` (`:123`),
`UniformInitializerScenario` (`:82`), `Glsl420DeclarationScenario` (`:94`),
`IoBlockNameCollisionScenario` (`:95`), `UnlocatedIoBlockScenario` (`:96`, plus a location-strip
pinned-on lane at `:647-670`), `PointSizeDemotionScenario` (`:109`, pinned lanes `:814-834`),
`SsboDeclarationFormScenario` (`:93`), `SsboArrayLengthScenario` (`:80`),
`SsboArrayDynamicIndexScenario` (`:121`), `DoublePrecisionScenario` (`:81`),
`ViewportArrayScenario` (`:79` + negative control `:768`), the five XFB scenarios (`:104-108`),
`TessellationDrawModeScenario`/`GeometryDrawModeScenario` (`:97-98`).
*The P2/P3a machinery scenarios P4a extends*: `HandleRecycleScenario` (`:133`, six pinned arms at
`:979-1024`), `CsoContentAddressingScenario` (`:134`, four lanes `:1086-1113`),
`ResourceSubsystemControlScenario` (`:135`, two lanes `:1160-1169`),
`PipeVerifyArmingScenario` (`:131`), `PoisonOmissionScenario` (`:132`).
`HandleRecycleScenario` today covers exactly two kinds — buffer
(`ABufferAtARecycledAddressDoesNotInheritItsPredecessorsContents`, header `:14`) and VAO
(`AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexInput`, `:568`). **P4a's G8
analogue is: add a texture case, a sampler case and a program case, each with `.Handles`/`.Legacy`/
`.AbaControl` arms**, and record the red-before evidence on the contract tree exactly as P3a did.
### 5.2 Unit tests
`MG_Test/Pipe/`: `PipeCatalogueTest.cpp` (payload sizes — `sizeof(SamplerParameters)==100` at
`:131`, trivially-copyable at `:138`), `CsoCacheTest.cpp`, `TrackerTest.cpp`, `SlotAllocatorTest.cpp`,
`PipeInputsTest.cpp`, `RenderStateSpansTest.cpp`, and P3a's two emitter tests
`ResourceEmitTest.cpp` / `VertexInputEmitTest.cpp` (the shape P4a's `SamplerEmitTest` /
`ProgramEmitTest` / `ImageEmitTest` should copy; note ID-14 — `ResourceEmitTest`'s `ApplierGuard`
is the fixture-scoping pattern, and `MG_Test/Buffer/BufferTest.cpp` needed the same treatment).
`MG_Test/ShaderTranspiler/`: `SpirvPassTest.cpp`, `TranslationCacheTest.cpp`,
`WidenImageFormatsTest.cpp`, `FlattenAtomicCounterBlockTest.cpp`, `FlattenXfbInterfaceBlocksTest.cpp`,
`UniquifyIoBlockNamesTest.cpp`, `StripIoBlockLocationsTest.cpp`, `LowerViewportIndexTest.cpp`,
`DemoteFloat64Test.cpp`, `DemotePointSizeTest.cpp`, `LegalizeResourceArrayIndexTest.cpp`,
`ClampMultisampleFetchTest.cpp`, `GlslangCaptureTest.cpp`, `DeriveNumSubgroupsTest.cpp`,
`EmulateSubgroupsTest.cpp`, `FixIterationRP*Test.cpp`, `FlattenFloat64StorageBlockTest.cpp`.
`EmulateNoPerspectiveForEssl` is tested from `MG_Test/Program/ProgramUtilTest.cpp:1344`, `:1385`,
`:1439`, `:1465` (not from the ShaderTranspiler directory).
`MG_Test/Program/`: `ProgramArtifactsTest.cpp` (**the archive's size-and-field pin — P4a's serializer
test belongs beside it**), `ProgramPipelineCompositeTest.cpp`, `ProgramInterfaceTest.cpp`,
`ProgramTest.cpp`, `ProgramUtilTest.cpp`, `AsyncLinkTest.cpp`, `AsyncSpirvPhaseTest.cpp`
(reads `GetLinkVersion()` at `:695`/`:701`), `AsyncCompileTest.cpp`, `AsyncTeardownTest.cpp`,
`OptimisticStatusTest.cpp`, `ParallelShaderCompileTest.cpp`, `ShaderCompileAdoptionTest.cpp`,
`TessellationLinkTest.cpp`, `XfbBlockVaryingTest.cpp`, `XfbFrontendOrderInvarianceTest.cpp`.
### 5.3 `PipeInputs` accessors for programs
`MG_Backend/MGPipe/PipeInputs.h`. O-class storage: `m_programForDispatch`, `m_programForDraw`,
`m_transformFeedbackProgram` (`:683-685`), listed in `MGP_INPUT_STORAGE_LIST` at `:108-109`, `:122`,
with accessors at `:534-548`. F-class (forwarded, sticky, no poison check — the declared exception
at `:558-568`): `GetProgramObject(Uint index)` `:570`, `ValidateProgramName(Uint index)` `:574`,
plus `GetTextureObject` `:571` and `InvalidateCompileEnv` `:573`.
`Coverage.def:99-101` maps `GetProgramForDispatch→SetDispatchProgram`,
`GetProgramForDraw→SetDrawProgram`, `GetProgramObject→CreateShaderState`, and `:127`/`:146-149`
records `GetProgramObject`/`ValidateProgramName` as client-resolved name lookups.
`gPipeInputs` is **leak-at-exit storage** (`PipeInputs.h:688-700`, ID-18/ID-21): its O-class
`SharedPtr`s reach `~BufferObject` → the slot allocator at exit. P4a adds **more** frontend
`SharedPtr` members if it is careless — sampler/program handles must be `MGPipeHandle`, not
`SharedPtr`, or the exit-order closure has to be re-litigated.
---
## 6. Traps and open items for the P4a brief
1. **`SamplerParameters` has 3 bytes of trailing padding and no field table.** §1.1. Contract commit
must add `MGP_FIELDS_SamplerParameters` + the `MGP_VERIFY_PAYLOAD_LIST` row, and the sampler CSO's
content hash must be field-wise. A memcmp-based hash mints a fresh CSO per call.
2. **`MGPTextureParams` cannot express what `SyncBuiltinSamplerToBackend` pushes.** §1.8 — no filter,
wrap, compare mode or border colour. Decide in the contract: widen the payload (it is 32 B with
an `MGP_ASSERT_POD`) or give each texture an implicit sampler CSO.
3. **The archive has no serializer, and the libc++/NDK `sizeof` pin is inert.**
`ProgramArtifacts.h:565-566`. Both are contract-package work; the NDK pin must land in the same
phase or the Android build has no trip wire on a 58-member struct.
4. **`g_boundSamplersCache` is a raw twin pointer per unit and is load-bearing for three memos.**
§1.4-1.6. It becomes a per-unit handle array in the applier; the `memcmp` replay proofs
(`DirectGLES.cpp:3597-3604`, `:3942-3950`) have to be re-derived against that.
5. **The sampler twin is created lazily, only from the program pass** (`DirectGLES.cpp:4014-4020`).
`create_sampler_state` inverts the timing of `glGenSamplers`.
6. **Three of the program twin's nine staleness keys are not program state.** §3.2/§3.4. The
`st_variant` specialisation is the design (`ARCHITECTURE.md:264`); a brief that treats
`create_shader_state` as self-contained will produce a per-draw rebuild.
7. **`g_rawDepthFetchSamplerState` constructs a frontend `SamplerObject` inside `MG_Backend`**
(`DirectGLES.cpp:209`). `ARCHITECTURE.md:322` names its removal as P4a work. The purity gate G13
(`grep -rc pGLContext MG_Backend` empty) does not catch it — it is a type use, not `pGLContext`.
8. **The image sweep's gate must stay keyed on the frontend generation** (`DirectGLES.cpp:2195-2201`)
— a server-side epoch is bumped too late by construction.
9. **`SlotTables.h` still mints handles from inside `MG_Backend`** for the six P2 kinds
(`:70-77` records the debt; `GetOrCreate(StatePtr)` at `:209-252` calls
`MGPipeSlots().Acquire`). P3a discharged it for `Buffer` only. P4a discharges it for
`Texture`, `Framebuffer`, `SamplerCso`, `ShaderCso` — four of the remaining five — and should say
whether `Renderbuffer` follows in the same phase (its `resource_*` conversion is in the
`ROADMAP.md:20` cell) or is left for later.
10. **`ForEachLive` needs `Entry::stateRef`, and a handle-keyed entry has none** (`SlotTables.h:266-269`,
`:443-463`). The one direct-iteration site is `ScopedDetachedTextureFramebufferAttachments`, which
walks **texture** twins (`SlotTables.h:61-64`) — i.e. exactly a kind P4a converts. That iteration
has to be re-expressed before the texture table goes handle-keyed, or it silently walks nothing.
11. **The photon canary.** §2.4 — pin `photon-v1.3b` (llvmpipe retrace, **not** Adreno) as a named
P4a case; it is the only thing that has ever caught an image-binding-semantics regression.
12. **`ProgramPipelineObject`'s composite band is allocated but unused** (`MGPipeHandles.h:84-92`).
The composite resolver mints into it, and the pipeline cache's eviction is what frees the slot,
bumps `gen` and emits `delete_shader_state` (`ARCHITECTURE.md:212`).
13. **Inherited from P3a**: ID-15 M-3 (the fp64 stream's dropped `SyncGpuWrites`) is still a ruled
deviation; ID-21's `IntegerBorderColorScenario` ASan stack-buffer-overflow is still open and sits
squarely in P4a's sampler test set; ID-19's per-draw vertex-input emission cost (+699/+422
ns/draw) is on the optimisation list and P4a's per-unit sampler/image emission is the same shape
of risk on VAO/texture-heavy frames (rd12 was +30%/+27%).
14. **Subsystem bits.** `MGPipe.h:72-95` has bits 0-8 used and
`kMGPipeSubsystemsMigratedAtP3a = 0x1ff`. P4a needs its own bits (framebuffer / texture+sampler /
program are three natural ones) and a `kMGPipeSubsystemsMigratedAtP4a`, plus the arm-resolution
treatment at `Managers.cpp:2352-2400` (`ClassifyPipeSubsystemArm`, `StopOnArmlessPipeSubsystem`)
— including the **dependency refusal** pattern (bit 8 requires bit 7, `Managers.cpp:2395-2400`):
a program/sampler bit will require the texture bit for the same reason.
15. **Dirty bits.** `Tracker.h:70-83` already computes `NewShader`, `NewShaderBindings`,
`NewGlobalConstants`, `NewFramebuffer`, `NewSamplerViews`, `NewSamplers`, `NewShaderImages`
(values at `:246-262` and `:305-312`) — P4a only has to **emit** them and extend
`kMGPipeDirtyEmittedAtP3a` (`:104-107`) into a `…AtP4a`. `MGPipeSubsystemForDirty` (`:128`ff)
is where each new bit's gate goes.
16. **Registration.** `MGPipeSetResourceOps` is installed from `BufferImpl::RegisterBufferBackendOps`
(`Managers.cpp:2529-2551`, called `BackendObject_DirectGLES.cpp:849` and
`DirectGLES.cpp:10568`) — ID-8's accepted deviation. P4a's new op tables should get their own
registration entry point rather than piling onto the buffer one.
@@ -0,0 +1,933 @@
# Scout — the frontend (MG_State/GLState + MG_Impl/GLImpl) as P4a's client emission must read it
Tree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg` @ `37da3c3a`
(feat/disaggregated, P3a closed). Every path below is relative to `MobileGL/` unless it starts
with `docs/`. Every line number was opened in this tree; where a file is large I name the exact
range I read.
Read alongside: `~/w7/notes/p3a/INTEGRATOR-DECISIONS.md` (ID-1..24). The rulings that bind P4a
directly are ID-11/ID-13 (G5 byte-identical functions — none of them are in P4a's files),
ID-12/ID-8b (**the applier keeps object records across make-current; only
`MGPipeApplierReleaseObjectRecords` drops them; the client therefore needs no re-publication on
`FreshlyPrimed`, but must say so as a rule**), ID-18/ID-21 (**leak-at-exit storage: every MGPipe
process singleton is heap-constructed and never destroyed; a new P4a singleton MUST follow**),
and ID-19 (P3a already costs +699/+422 ns/draw; P4a's per-verb emission budget is tight).
---
## 0. The one-paragraph shape
P4a's kinds are **Framebuffer, Texture, Renderbuffer, SamplerCso/SamplerViewCso, ShaderCso**
(`MG_Pipe/MGPipeHandles.h:24-40`). Unlike P3a's buffers, **five of the six already raise a death
notice** and **all six already have a lifetime id**; what none of them has is a client-minted
handle, a client emitter, or an applier record. The frontend versions the emitters need already
exist and are already read by the tracker's shutters (`MG_Impl/Pipe/Tracker.h:303-312`) — bits
11..14 (`NewFramebuffer`, `NewSamplerViews`, `NewSamplers`, `NewShaderImages`) plus bits 6..8
(`NewShader`, `NewShaderBindings`, `NewGlobalConstants`) are **computed, latched and counted
today and emitted by nobody**. P4a is therefore mostly "wire the emitters onto shutters that
already fire", plus four genuinely new pieces of frontend work: the resolved `ReadSurface`, the
framebuffer `Complete` bit, the texture region list on the wire, and the program archive blob.
---
## 1. The object classes: ids, versions, constructors, destructors
### 1.1 Summary table (the hook points)
| kind | class + header | lifetime id | ctor | dtor / death | already raises |
|---|---|---|---|---|---|
| Framebuffer | `FramebufferObject`, `MG_State/GLState/FramebufferState/FramebufferObject.h:105-191` | `m_lifetimeId` `:176`, `GetLifetimeId()` `:165`, allocator `FramebufferObject.cpp:20-24` | `FramebufferObject.cpp:126-135` | `FramebufferObject.cpp:27-37` (`#if MOBILEGL_PIPE_PUSH` only) | `NotifyStateObjectDestroyed(MGPipeKind::Framebuffer, …)` `:36` |
| Texture | `TextureObjectBase : ITextureObject`, `TextureState/TextureObject.h:117-234` | `m_lifetimeId` `:205`, `GetLifetimeId()` decl `:84` / def `TextureObject.cpp:334-336`, allocator `TextureObject.cpp:19,26-28` | `TextureObject.cpp:56-...` | `TextureObject.cpp:31-41` — **virtual, declared on the BASE** so 2D/3D/cube/buffer/view all announce once (`TextureObject.h:120-128`) | `MGPipeKind::Texture` `TextureObject.cpp:40` |
| Renderbuffer | `RenderbufferObject`, `RenderbufferState/RenderbufferObject.h:23-71` | `m_lifetimeId` `:64`, `GetLifetimeId()` `:58`, allocator `RenderbufferObject.cpp:21,24-26` | `RenderbufferObject.cpp:28` | `RenderbufferObject.cpp:31-41` | `MGPipeKind::Renderbuffer` `:40` |
| Sampler | `SamplerObject`, `SamplerState/SamplerObject.h:16-79` | `m_lifetimeId` `:76`, `GetLifetimeId()` `:63`, allocator `SamplerObject.cpp:20-24` | `SamplerObject.cpp:26-27` | `SamplerObject.cpp:30-40` | `MGPipeKind::SamplerCso` `:39` |
| Program | `ProgramObject`, `ProgramState/ProgramObject.h:25-...` | `m_lifetimeId` `:1353`, `GetLifetimeId()` `:1262`, allocator `ProgramObject.cpp:26-30` | inline `ProgramObject.h:55` | `ProgramObject.cpp:32-45` (`CancelLink()` then the notice) | `MGPipeKind::ShaderCso` `ProgramObject.cpp:43` |
| Shader | `ShaderObject`, `ProgramState/ShaderObject.h:24`, dtor `:52` | **NONE** | — | no notice | — |
| ProgramPipeline | `ProgramPipelineObject`, `ProgramState/ProgramPipelineObject.h:19-170` | **NONE** | — | no notice | — (composites are ordinary `ProgramObject`s, §9.4) |
| Buffer (P3a, the model) | `BufferState/BufferObject.cpp` | `g_nextBufferLifetimeId` `:20`, `AllocateLifetimeId` `:23-25` | `:35-47` — **mints the handle unconditionally, emits create only if the subsystem is on** | `:49-65` — `MGPipeEmitResourceDestroyAndFree` returns the latch, and the legacy `OnDestroy` runs only when it says false | emits `resource_destroy` itself (no notice) |
| VAO (P3a, the CSO model) | `VertexArrayState/VertexArrayObject.cpp:41-62` | | | `MGPipeEmitVertexElementsDestroyAndFree(m_lifetimeId)` — **backend-neutral, client-side**, emit → notice → free slot, in that fixed order | |
### 1.2 The two death shapes, and which one each P4a kind takes
`MG_State/GLState/StateObjectDeathNotice.h` (whole file, 62 lines) is the P2 mechanism: one
`StateObjectDeathOps{ void(*OnDestroyed)(MGPipeKind, Uint64 lifetimeId) }` (`:39-43`), a plain
non-atomic global `g_stateObjectDeathOps` (`:45`, written at backend bring-up, read from
destructors — both on the context thread), `SetStateObjectDeathOps` `:47`, and
`NotifyStateObjectDestroyed` `:55-59`. Declares nothing at all in a pull build (`:12`, `:62`).
**The P3a ruling P4a inherits (ID-15 C-1, `MG_Pipe/PipeMutation.h:127-141`):** a death path that
lives only in a backend's death-ops table **is no path at all under a backend that installs
none** — Magma installs none — so every VAO leaked its slot and its ~1.3 KB applier record and
Fatal'd past 65536 slots. The fix was `MGPipeEmitVertexElementsDestroyAndFree`, a **client-side**
helper taking the lifetime id (the object is already gone) that emits `delete_*`, raises the
notice, and frees the slot in that fixed order (`PipeMutation.h:136-141`,
`MG_Impl/Pipe/PipeFill.cpp:801-...`).
**Therefore: for all five P4a kinds the notice at the destructor is NOT sufficient.** Each
destructor must call a client helper of the same shape. The five call sites are the five `#if
MOBILEGL_PIPE_PUSH` destructor bodies listed in 1.1 — they already exist, so P4a edits five
existing lines rather than adding five destructors (which would resize the pull build's symbol
set and break G1).
### 1.3 The per-object version counters P4a's shutters and records need
**Framebuffer** (`FramebufferObject.h`):
- `m_attachmentVersions` `:178`, one `Uint16` per attachment point (`FramebufferAttachmentTypeCount`
= 41 entries, `:24-71`), read whole via `GetAllFramebufferAttachmentVersions()` `:152-154`.
- `m_objectVersion` `:190`, `GetObjectVersion()` `:156` — bumped by `BumpAttachmentVersion`
(`FramebufferObject.cpp:231-235`), by `SetReadBuffer` (`:205-210`) and by the five
`Set Default*` setters (macro `:216-229`). **`SetDrawBuffer` bumps only through
`BumpAttachmentVersion(buffer)` (`:195-199`) — i.e. it versions the *new* attachment slot, not
the draw-buffer array**, which is a real quirk: `glDrawBuffers` writing `NONE` over `COLOR0`
bumps `m_attachmentVersions[None]`, not `[Color0]`.
- `m_drawBuffers` `:180` (`Array<FramebufferAttachmentType, MAX_DRAW_BUFFERS=kMGMaxDrawBuffers>`,
`:107,113`), `m_readBuffer` `:181`, defaults seeded in the ctor `:126-135`
(`BackLeft` for name 0, `Color0` otherwise).
- `FramebufferAttachmentObject` `:74-103` is the attachment struct: `SharedPtr<ITextureObject>`
**or** `SharedPtr<RenderbufferObject>` (`:96-97`), `m_textureUploadTarget` `:98`, `m_textureLevel`
`:99`, `m_textureLayer` `:100`, `m_layered` `:101`, `m_isValid` `:102`. `IsComplete()`
`FramebufferObject.cpp:89-99`, `GetSize()` `:101-119` (resolves `Unknown` upload target to
`GetUploadTargets()[0]`).
- **`FramebufferState`** `FramebufferState/FramebufferState.h:15-45`: `m_framebufferObjects`
(`UnorderedMap<Uint, SharedPtr<…>>`) `:41`, `m_bindingSlots[Draw|Read]` `:43-44`,
`NoteAttachmentChanged`/`GetAnyAttachmentGeneration` `:33-34` under `#if MOBILEGL_PIPE_PUSH`
`:28-40`. `MarkFramebufferObjectForDeletion` `FramebufferState.cpp:59-72` rebinds any slot
holding the victim to FBO 0 and erases the map entry.
**Texture** (`TextureState/TextureObject.h`): `ITextureObject` `:23-115` is the interface (39
pure virtuals); `TextureObjectBase` `:117-234` the storage-free base; `TextureObjectMipmap`
`:236-303` adds the level API; `TextureObjectWithOneMipmap` `:344-378` holds
`MipmapUploadTargetArray<1> m_textureStorage` `:377`. Concrete leaves: `TextureObject1D/2D/3D.h`,
`TextureObject2DCube.h`, `TextureObjectBuffer.h`, `TextureObjectView.h`.
Three independent counters, all on the base:
- `m_textureParamsVersion` (Uint16) `:213`, `GetTextureParamsVersion()` `:158` — the
glTexParameter family.
- `m_shapeVersion` (Uint64, **starts at 1**) `:217`, `GetShapeVersion()` `:160`, bumped **only**
by `BumpShapeVersion()` (`:202`, def `TextureObject.cpp:44-54`), which also calls
`pGLContext->BumpSamplingResolutionGeneration()` `:53`. Invalidates the completeness memo
`m_completeMemoShapeVersion[2]` / `m_completeMemoValue[2]` `:220-221`, read by
`IsMipmapCompleteForFilterCached` `TextureObject.cpp:298-307`.
- `m_contentVersion` (Uint64, **starts at 1**) `:224`, `GetContentVersion()` `:159`, bumped by
`MarkStorageDirty(dirty=true)` (`TextureObject.cpp:379-386`), `MarkStorageDirtyRegion`
(`:392-398`) and `BumpContentVersion()` (`:309-312`).
- Other state the descriptor needs: `m_internalFormat` `:207`, `m_sampler` `:208` (**every texture
owns a `SamplerObject(0)`**, `TextureObject.cpp:58`), `m_swizzleParams` `:209`, `m_levelRange`
`:211` (`{0,1000}`), `m_immutableLevels` `:212`, `m_depthStencilTextureMode` `:225`,
`m_viewMinLevel/NumLevels/MinLayer/NumLayers` `:228-231`, `m_samples` `:232`,
`m_fixedSampleLocations` `:233`.
- Views: `TextureObjectView.h:44-135`, `m_storageOwner` `:134`, `GetViewStorageOwner()` override
`:49`; the base returns a static null `TextureObject.cpp:338-343`. `IsTextureView()`
`TextureObject.h:102`. A view is composed onto the ROOT at creation, so one hop always reaches
storage (`:90-101`) — that is exactly `MGPResourceDesc::ViewOf`.
- Texture buffers: `TextureObjectBuffer.h:16-48` — `m_bufferBindingSlot` `:46`,
`m_bufferRangeOffset` `:47`, `m_bufferRangeSize` `:48` with `kWholeBuffer = ~0` `:28`,
`GetBufferRangeSizeInBytes()` `:35-41` **resolves live against the buffer's current size** —
which is exactly the `kMGPipeWholeBuffer` / "resolved live" contract of
`MGPipeTypes.h:173-177`.
- `TextureState` `TextureState/TextureState.h:39-173`: `MAX_TEXTURE_IMAGE_UNITS = 192` `:42`,
`MAX_PER_STAGE_TEXTURE_IMAGE_UNITS = 32` `:47`; `m_textureUnits` `:166`,
`m_imageTextureBindings` `:167`, `m_textureObjects` `:169`, `m_defaultTextureObjects` `:172`
(name 0, one per target, immortal). `ImageTextureBinding` `:18-37` = `{Texture, Level, Layered,
Layer, Access, Format, Version}` with `Bind()` `:27-36` bumping `Version`.
- `TextureUnit` `TextureState/TextureUnit.h:15-26`: `m_slots[TextureTargetCount]` `:24` +
`m_sampler` `:25`; `SetSamplerObject` `TextureUnit.cpp:28-40` bumps
`pGLContext->BumpTextureBindGeneration()` `:39`.
**Renderbuffer** — **the outlier: no version at all.** `RenderbufferObject.h:63-70` has
`m_externalIndex`, `m_lifetimeId`, `m_internalFormat`, `m_width`, `m_height`, `m_samples`,
`m_allocated`, `m_componentSizes` and nothing else. `SetInternalFormat`
(`RenderbufferObject.cpp:96-99`), `AllocateStorage` (`:101-105`) and `SetSamples` (`:107-109`)
write the members and **bump nothing and notify nothing**. See §5.2 — this is a real P4a hole.
**Sampler** — `m_version` (Uint16) `SamplerObject.h:77`, `GetVersion()` `:58`;
`BumpVersion()` `:73` (def `SamplerObject.cpp:43-54`) is the **only** writer, called by all 14
setters (`:56-...`), each of which early-outs on an unchanged value. It does three things:
`++m_version`, `pGLContext->BumpSamplingResolutionGeneration()` (`:50`), and
`MGP_NOTE_AGGREGATE(TextureParams)` (`:53`). `m_samplerParameters` `:78` is the whole
`SamplerParameters` POD that `MGPSamplerDesc::Parameters` ships byte-for-byte
(`MGPipeTypes.h:283-287`; `docs/Disaggregated/ARCHITECTURE.md:4.1` insists `borderColorForm`
travels with it). `SamplerState` `SamplerState.h:17-31` is just a map + `IndexGenerator`.
**Program** — five counters, all read by the tracker (`Tracker.h:251-260`):
- `m_linkVersion` (mutable Uint32) `ProgramObject.h:1418`, `GetLinkVersion()` `:793` — bumped
**only** by `BumpLinkObservableVersions()` (decl `:1340`), called at Link()'s prologue and at
both publish sites (`ProgramObject.cpp:72`, `:119`).
- `m_backendStateVersion` (mutable) `:1399`, `GetBackendStateVersion()` `:790`.
- `m_blockBindingVersion` `:1401`, `GetBlockBindingVersion()` `:1013`, bumped by
`SetUniformBlockBinding` `:1020-1027` (and the storage-block setter).
- `m_imageUnitVersion` `:1394`, `GetImageUnitVersion()` `:855`, bumped inside
`SetUniformSamplerOrImageUnitIndex` **only for image uniforms** `:847-849`.
- `m_uniformWriteSetVersion` `:1393`, `GetUniformWriteSetVersion()` `:601`.
- `m_uboContentVersion` (mutable) `:1417`, `GetUBOContentVersion()` `:740`,
`MarkUBOContentDirty()` `:741-743` — **`~0u` is reserved as the backends' "never uploaded"
sentinel and the wrap skips it**.
- `m_artifacts` `:1426` and `m_spirv` `:1429` are private and reachable only through
`Artifacts()` / `Spirv()`, which join `m_pendingLink` `:1434` / `m_pendingSpirv` `:1438`
(invariant I5, `:1264-1275`).
---
## 2. The mutation entry points, per family
Frontend GL entry points live in `MG_Impl/GLImpl/<Family>/GL_<Family>.cpp` in a **two-layer
shape**: a `Foo_State(...)` function that mutates `MG_State` and validates, and a public `Foo(...)`
that calls it then dispatches through `MG_Backend::gBackendFunctionsTable.GL.Foo` behind an
`MGP_FILL(Verb)`. P4a's emission sites are the `_State` bodies (mutation) and, for the verbs,
the `MGP_FILL` point.
### 2.1 Framebuffer — `MG_Impl/GLImpl/Framebuffer/GL_Framebuffer.cpp` (182 KB), decls
`GL_Framebuffer.h:16-96`
- Attach: `FramebufferTexture{,1D,2D,3D,Layer}` `GL_Framebuffer.h:44-49`,
`NamedFramebufferTexture{,1D,2D,3D,Layer}` `:50-55`, `FramebufferRenderbuffer` `:34`,
`NamedFramebufferRenderbuffer` `:35-36`. All land in `FramebufferObject::AttachTexture`
(`FramebufferObject.cpp:137-142`) / `AttachRenderbuffer` (`:144-148`) / `Detach` (`:150-153`),
each ending in `BumpAttachmentVersion` (`:231-235`) → `++m_attachmentVersions[type]`,
`++m_objectVersion`, `MGP_NOTE_AGGREGATE(FramebufferAttachment)`.
- Draw/read buffers: `DrawBuffer` / `DrawBuffers` / `ReadBuffer` `:78-80` and their `Named*`
forms `:56-58`. Implementations: `DrawBuffersForFramebuffer_State`
`GL_Framebuffer.cpp:1719-1830`, `DrawBuffers_State` `:1831-1836`, `DrawBuffer_State`
`:1838-1848`, `ReadBufferForFramebuffer_State` `:1850-1899` (ends at `fbo->SetReadBuffer(attType)`
`:1898`), `ReadBuffer_State` `:1901-1906`, `NamedFramebufferDrawBuffers_State` `:1908-1916`.
- Default geometry (`ARB_framebuffer_no_attachments`): `FramebufferParameteri` `:71`,
`NamedFramebufferParameteri` `:73` → the five setters `FramebufferObject.h:146-150`, defined by
the macro at `FramebufferObject.cpp:216-229`.
- Renderbuffer storage: `RenderbufferStorage` / `RenderbufferStorageMultisample` `:23-25`,
`NamedRenderbufferStorage{,Multisample}` `:30-32`; bodies
`RenderbufferStorageMultisample_State` `GL_Framebuffer.cpp:817-842`,
`AllocateRenderbufferStorage_State` `:844-858`, `RenderbufferStorage_State` `:860-866`.
**None of them notify anything** (§5.2).
- `BindFramebuffer` `:85`, `BindRenderbuffer` `:38`, `DeleteFramebuffers` `:81`,
`DeleteRenderbuffers` `:37`, `Blit{,Named}Framebuffer` `:75-77,83-84`, `Invalidate*` `:61-66`,
`CheckFramebufferStatus` `:82` / `CheckNamedFramebufferStatus` `:69`, `ReadPixels`/`ReadnPixels`
`:16-18`, `ClearBuffer*` `:19-22` / `ClearNamedFramebuffer*` `:59-60,67-68`.
- `DefaultFramebufferInfo` `GL_Framebuffer.h:87-96` holds the default FBO plus its three synthetic
attachments; `pDefaultFramebufferInfo->defaultFBO` is the identity every "is this the default"
test compares against (`GL_Framebuffer.cpp:1834`, `:1844`, `:1904`). This is exactly the four
comparisons `MGPipeHandles.h:67-73` retires into `kMGPipeDefaultFramebuffer{0,1}`.
### 2.2 Texture — `MG_Impl/GLImpl/Texture/GL_Texture.cpp` (426 KB), decls `GL_Texture.h`
Storage / respecify (each → `MGPResourceDesc` create-or-respecify):
- `TexImage3D_State` `:2352`, `TexImage2D_State` `:2524`, `TexImage1D_State` `:2678` — each
`AllocateStorage(...)` (`:2473`, `:2621`, `:2734`), optional `UpdateMipmapSubData` (`:2515`,
`:2668`, `:2754`), then `MarkStorageDirty(..., true)` (`:2518`, `:2674`, `:2758`).
- `TexImage2DMultisample_State` `:2308`, `TexImage3DMultisample_State` `:2264`.
- `CompressedTexImage{1,2,3}D_State` `:4984`, `:4904`, `:4830` (`AllocateStorage` `:4895`/`:4975`,
`MarkStorageDirty` `:4901`/`:4981`).
- `TexStorage{1,2,3}D` `:6002`, `:6027`, `:6052` — allocate every level with
`MarkStorageDirty(..., false)` (`:5554`, `:5628`, `:5698`) then `TruncateMipmapLevels`
(`:5564`, `:5644`, `:5714`). `TexStorage{2,3}DMultisample` `:6110`, `:6121`, shared validator
`TexStorageMultisample_State` `:6098`.
- DSA `TextureStorage*` / `TextureSubImage*` / `CompressedTextureSubImage*` — `GL_Texture.h:41-60`.
- `TextureView` `:5838` (decl `GL_Texture.h:83`) → `TextureState::CreateTextureViewObject`
(`TextureState.h:55-58`).
- `TextureBuffer` / `TextureBufferRange` `GL_Texture.h:73-74`.
- The generated-mip storage grow: `GL_Texture.cpp:528-539` (`AllocateStorage`,
`MarkStorageDirty(false)`, `TruncateMipmapLevels`, then **`BumpContentVersion()` `:539`** —
the level SET grew without any CPU byte being dirty).
Sub-image (each → `MGPSubData` + regions):
- `TexSubImage3D_State` `:1725` → `MarkStorageDirtyRegion(target, level, {x,y,z}, {w,h,d})`
`:1820-1821`.
- `TexSubImage2D_State` `:1825` → `MarkStorageDirtyRegion(..., {x,y,0}, {w,h,1})` `:1940`.
- `TexSubImage1D_State` `:1945` → `:2007`.
- `CompressedTexSubImage{1,2,3}D_State` `:4818`, `:4658`, `:4489`.
- `ClearTexImage` `:1102` / `ClearTexSubImage` `:1118` → `MarkStorageDirty(..., true)` `:1006`,
`:1097`.
- Copy family: `CopyTexImage2D_State` `:4389` / `_Backend` `:4467`, `CopyTexSubImage2D_Backend`
`:4028`, `CopyTexSubImage3D_State` `:3986`, `CopyTexSubImage1D_State` `:4372`,
`CopyTexImage1D_State` `:4474`, DSA `CopyTextureSubImage{1,2,3}D` `GL_Texture.h:133-136`.
- `CopyImageSubData` `GL_Texture.h:143`, validator `ValidateCopyImageSubData_State`
`GL_Texture.cpp:4263`, backend hop `CopyImageSubData_Backend` `:4034` (verb
`CopyImageSubData`, class `kBlitOrCopy`, `MG_Pipe/FillPoints.def:113`) — the payload is
`MGPCopyRegion` (`MGPipeTypes.h:708-716`).
Parameters (each → `MGPTextureParams`, or the sampler-owned half):
- `TexParameter{f,i,fv,iv,Iiv,Iuiv}_State` `GL_Texture.cpp:2012`, `:2110`, `:2126`, `:2163`,
`:2194`, `:2224`; DSA `TextureParameter*` `GL_Texture.h:62-67`.
- They land on `TextureObjectBase::Set*`, each of which bumps `m_textureParamsVersion` and fires
`MGP_NOTE_AGGREGATE(TextureParams)`: `SetInternalFormat` `TextureObject.cpp:98-119` (also
`BumpShapeVersion` `:116` and a `BumpTextureBindGeneration` for the default-texture
Unknown↔defined transition `:108-113`), `SetBorderColor` `:136-145`, `SetBorderColorI`
`:151-160`, `SetBorderColorUI` `:166-175`, `SetSwizzleParam` `:202-225`, `SetSwizzleParamRGBA`
`:227-233`, `SetBaseLevel` `:239-252` (+`BumpShapeVersion` `:251`), `SetMaxLevel` `:254-264`
(+`:263`), `SetImmutableLevels` `:274-284`, `SetSamples` `:318-322`, `SetFixedSampleLocations`
`:328-332`, `SetDepthStencilTextureMode` **inline in the header** `TextureObject.h:188-193`.
- **TEXTURE_BORDER_COLOR / MIN_FILTER / WRAP_* are NOT texture-object state**: they live on the
texture's own `SamplerObject` (`TextureObject.cpp:125-179`), so a `glTexParameteri(GL_TEXTURE_
MIN_FILTER)` runs `SamplerObject::BumpVersion` and fires `MGP_NOTE_AGGREGATE(TextureParams)`
through *that* path.
Mipmap generation: `GenerateMipmap` `GL_Texture.cpp:6690-6709` (`EnsureGeneratedMipmapStorage
Allocated` `:6707` then `GenerateMipmap_Backend` `:1623`), `GenerateTextureMipmap` `:6711-6720`
(binds temporarily, `WithTemporarilyBoundNamedTexture`), guard `ValidateGenerateMipmapTexture`
`:6675-6688`, auto-gen hook `MaybeAutoGenerateMipmap` `:1628`. Verb `GenerateMipmap`, class
`kTextureOp` (`FillPoints.def:114`), payload `MGPMipPlan` (`MGPipeTypes.h:741-745`).
Binds: `BindTexture_State` `:4995`, `BindTextureUnit` `:6296`, `BindTextures` `:6395`,
`BindImageTexture` `:6612-6670`, `BindImageTextures` `:6418`. **`BindImageTexture` is the one
that is already a verb** (`FillPoints.def:122`, class `kTextureOp`): it writes
`GetImageTextureBinding(unit).Bind(...)` `:6665-6666`, calls `NoteTextureUnitTouched(unit)`
`:6667`, then `MGP_FILL(BindImageTexture)` `:6668` and dispatches `:6669`.
`glBindTexture`/`glBindSampler` are **not** verbs — they route through
`TextureState::NoteUnitTouched` (`TextureState.h:78-100`) only.
Readback: `GetTexImage_State` `:5251` / `_Backend` `:5079`, `GetCompressedTexImage_State` `:3801`,
`GetTextureSubImage` `GL_Texture.h:75-76`, `CopyTextureImageToClientOrPBO_State`
`GL_Texture.cpp:5375`.
### 2.3 Sampler — `MG_Impl/GLImpl/Sampler/GL_Sampler.cpp` (27 KB), decls `GL_Sampler.h:14-29`
`SamplerParameter{f,i,fv,iv,Iiv,Iuiv}` `:15-20`, `BindSampler` `:29`, `BindSamplers` `:28`,
`GenSamplers` `:25`, `CreateSamplers` `:27`, `DeleteSamplers` `:26`, the six `Get*` queries.
All setters funnel to `SamplerObject::Set*` → `BumpVersion()` (§1.3). `glDeleteSamplers` goes
through `GLContext::MarkSamplerObjectForDeletion` (`Core.cpp:1228-1240`), which **unbinds the
sampler from all 192 units first** (`:1232-1237`) so `TextureUnit::SetSamplerObject`
(`TextureUnit.cpp:28-40`) bumps the bind generation.
### 2.4 Program / pipeline — `MG_Impl/GLImpl/Program/GL_Program.cpp` (188 KB) +
`GL_ProgramPipeline.cpp` (12.7 KB) + `ProgramInterface.cpp` (49 KB)
- `UseProgram_State` `GL_Program.cpp:1451-1481` (public `UseProgram` `:2530`) → refuses while XFB
is active-and-unpaused `:1457-1464`, refuses an unlinked program `:1473-1479`, then
`pGLContext->UseProgram(program)` `:1480` → `ProgramState::UseProgram` (`Core.cpp:393-395`).
- `LinkProgram_State` `:1395` (public `:2522`), `DeleteProgram_State` `:606` (public `:2434`).
- **The one uniform funnel: `Uniform_State<ItemCount,T>` `GL_Program.cpp:1483-1561`.** Every
`glUniform*` and `glProgramUniform*` reaches it once per LOCATION (`:1495-1496`). Non-opaque
arm: `MarkUniformWrittenAtLocation` `:1499` → `BufferUniformWrite` if SPIR-V is pending
`:1516-1519` → `MapUBO()`/`GetUBOOffset` `:1520-1532` → **bytes-equal dedupe `:1542`** →
`Memcpy` `:1543` → `MarkUBOContentDirty()` `:1544`. Opaque arm `:1545-1560`:
`SetUniformSamplerOrImageUnitIndex(location, unit)` `:1559`, which bumps
`m_imageUnitVersion` only for image uniforms (`ProgramObject.h:847-849`).
Wrappers: `Uniformv_State` `:1563-1587` (reads `GetProgramForUniform()` `:1567`),
`ProgramUniformv_State` `:1590`. Public entry points from `:2534` (`Uniform1f`), `:2553`
(`Uniform1i`), `:2999` (`ProgramUniform1i`), etc.
- `glUniformBlockBinding` → `ProgramObject::SetUniformBlockBinding` `ProgramObject.h:1020-1027`
(bumps `m_backendStateVersion` **and** `m_blockBindingVersion`).
- `glShaderStorageBlockBinding` is a **verb** (`FillPoints.def:124`, class `kProgramOp` — the
class exists solely because it syncs Espryt's render state and textures, `:150-151`, `:323-334`).
- Pipelines: `GL_ProgramPipeline.cpp`; frontend state `Core.h:200-215`
(`GenProgramPipelineNames` `:204`, `CreateProgramPipelineObject` `:205`,
`BindProgramPipelineObject` `:208` → `Core.cpp:1391`, `MaterializeProgramPipelineObject` `:211`,
`MarkProgramPipelineForDeletion` `:212`, `GetBoundProgramPipeline` `:215` → `Core.cpp:1429`,
`m_boundProgramPipeline` `Core.h:660`).
### 2.5 Pixel store — `glPixelStore{i,f}`
`GLContext::SetPixelStoreParam` `Core.cpp:1134-1136` → `RenderState::SetPixelStoreParam`
`RenderState/RenderState.cpp:828-856` (a 16-arm macro switch, Pack ×8 + Unpack ×8).
`GetPixelStoreParameters(Bool isUnpack)` `RenderState.cpp:885-887`. Storage:
`m_pixelStorePackParameters` / `m_pixelStoreUnpackParameters` `RenderState.h:180-181` — **deliberately
outside `RenderStateParameters m_parameters` `:177`, so they are NOT part of the CSO byte range,
and the setter bumps NO version** (`SetPixelStoreParam` never calls `BumpVersions()` `:159-162`).
---
## 3. Which mutation sites already carry a `MGP_NOTE_MUTATION` / `MGP_NOTE_AGGREGATE`
Macros: `MG_Pipe/PipeMutation.h:155-158` (push) / `:160-161` (pull no-ops).
`MGPipeAggregate` enum `:56-74`. Dispatch: `MG_Impl/Pipe/PipeFill.cpp:529-552`
(`MGPipeNoteAggregate`) and `:509` (`MGPipeNoteFrontendMutation`).
**Complete census of the P4a-relevant sites** (grep over `MG_State/` + `MG_Impl/`):
`MGP_NOTE_AGGREGATE(FramebufferAttachment)` — 3 sites, all in
`FramebufferState/FramebufferObject.cpp`: `:209` (`SetReadBuffer`), `:221` (the five default-geometry
setters via macro), `:234` (`BumpAttachmentVersion`, i.e. every attach/detach/draw-buffer write).
`MGP_NOTE_AGGREGATE(TextureParams)` — 13 sites: `TextureObject.cpp:118, 144, 159, 174, 224, 232,
250, 262, 283, 321, 331`; `TextureObject.h:192` (`SetDepthStencilTextureMode`);
`SamplerState/SamplerObject.cpp:53` (`BumpVersion`, the choke point for **all** sampler params).
`MGP_NOTE_AGGREGATE(TextureContent)` — 5 sites: `TextureObject.cpp:311` (`BumpContentVersion`),
`:383` (`MarkStorageDirty`), `:395` (`MarkStorageDirtyRegion`);
`TextureState/TextureObject2DCube.cpp:53, 65` (the cube overrides).
`MGP_NOTE_MUTATION(...)` — **only four sites in the whole tree, all in
`TextureState/TextureState.h`**: `:85` `GetMaxTouchedTextureUnit`, `:98` and `:111`
`GetTextureBindGeneration`, `:133` `GetSamplingResolutionGeneration`. (P3a widened
`gen_pipe_dirty_surface.py`'s scan root to `MG_State/GLState` precisely to bring these inside the
gate — `MG_Pipe/DirtySurface.def:150-153`.)
**Nothing at all fires for**: any `RenderbufferObject` mutation, any `ProgramObject` version bump,
`glUseProgram`, `glBindProgramPipeline`, `glBindImageTexture`'s `ImageTextureBinding::Bind`
(only `NoteUnitTouched` runs), and `SetPixelStoreParam`.
---
## 4. The dirty bits P4a inherits — already computed, emitted by nobody
`MG_Impl/Pipe/Tracker.h`. Enum `MGPipeDirty` `:57-84`; names `:106-125`;
`MGPipeSubsystemForDirty` `:130-154` (**returns 0 for every bit past 10** `:149-153`);
`MGPipeMixShutter` `:170-173`; `MGPipeWidenedCounter` `:186-204`.
Shutters computed in `MGPipeTracker::Update` `:215-361`:
| bit | name | shutter, verbatim | line |
|---|---|---|---|
| 6 | `NewShader` | `Mix(program->GetLifetimeId(), program->GetLinkVersion())` | `:252`, stored `:261` |
| 7 | `NewShaderBindings` | `Mix(Mix(Mix(ImageUnitVersion, BackendStateVersion), BlockBindingVersion), UniformWriteSetVersion)` | `:253-257`, `:262` |
| 8 | `NewGlobalConstants` | `Mix(LifetimeId, UBOContentVersion)` | `:258`, `:263` |
| 11 | `NewFramebuffer` | `Mix(ctx.GetAnyFramebufferAttachmentGeneration(), m_framebufferBind.Observe(ctx.GetFramebufferBindingSlot(Draw).GetVersion()))` | `:303-306` |
| 12 | `NewSamplerViews` | `Mix(textureContent, ctx.GetTextureBindGeneration())` | `:307-308` |
| 13 | `NewSamplers` | `Mix(textureParams, ctx.GetSamplingResolutionGeneration())` | `:309-310` |
| 14 | `NewShaderImages` | `Mix(Mix(textureContent, textureParams), program->GetImageUnitVersion())` | `:311-312` |
`textureContent` / `textureParams` are read at `:266-267`. The program is read from
`ctx.GetCurrentProgram()` `:246` **and deliberately not `GetProgramForDraw()`** — "the tracker must
not force a compile just to answer did the shader move" `:242-245`. **P4a must respect that**: the
emitter, which needs the artifacts, is the thing that joins.
Also: `m_primed` / `FreshlyPrimed()` `:349-350`, `:417-420`; `Reset()` `:378-392` (called from
`Update` whenever `m_context` moves `:219-222`); the fire tallies `:353-359`.
`kMGPipeDirtyEmittedAtP2` `:96-99` and `kMGPipeDirtyEmittedAtP3a` `:102-104` — **P4a adds a
`kMGPipeDirtyEmittedAtP4a` constant rather than editing either** (the rule is stated at `:93-95`).
Subsystem bits: `MG_Pipe/MGPipe.h:72-95`; `kMGPipeSubsystemResources = 1<<7` `:84`,
`kMGPipeSubsystemVertexInput = 1<<8` `:85`, `kMGPipeSubsystemsMigratedAtP3a = 0x1ff` `:95`.
Bit 63 is the CSO content-addressing negative control `:90`. **Bits 9+ are free for P4a.**
---
## 5. The dirty-surface rows P4a's kinds already carry, and the two holes
`MG_Pipe/DirtySurface.def`. Legend `:101-143` (`kImmediate`, `kReverseChannel`, `kNoBackendRead`,
`kExplicitDestroy`, `kUnpublishedDestroy`, `kPulledEveryVerb`, `kPulledPartialShutter|BIT`).
Gate: `scripts/gen_pipe_dirty_surface.py --check` / `--self-test`, scan root now **both**
`MG_Impl/GLImpl` and `MG_State/GLState`, and a `MGP_NOTE_MUTATION` site counts as a publish
mechanism whose "mutator" is the enclosing function (`:16-28`, `:145-155`).
Rows P4a touches:
- `X(BumpTextureBindGeneration, NEW_SAMPLER_VIEWS)` `:248`
- `X(BumpSamplingResolutionGeneration, NEW_SAMPLERS)` `:256` (added at P3a by the widened root)
- `X(NoteUnitTouched, kPulledPartialShutter|NEW_SAMPLER_VIEWS)` `:271` — the bind generation moves
only on the `bindingChanged` arm; `GetMaxTouchedTextureUnit` has **no shutter at all** `:265-266`
- `X(SetPixelStoreParam, kPulledPartialShutter|NEW_PIXEL_PACK)` `:237` with the reasoning at
`:224-236`: the setter writes BOTH halves, only the pack half has a bit, so
`glPixelStorei(GL_UNPACK_ALIGNMENT, 8)` **moves nothing at all**
- `X(SetActiveTextureUnit, kImmediate)` `:164`
- Deaths `:299-307`: `MarkFramebufferObjectForDeletion`, `MarkRenderbufferObjectForDeletion`,
`MarkSamplerObjectForDeletion`, `MarkTextureObjectForDeletion` are all `kExplicitDestroy`;
**`MarkProgramForDeletion`, `MarkProgramPipelineForDeletion`, `MarkShaderForDeletion` are
`kUnpublishedDestroy` `:301-302, :305`** — a recorded hole ("programs, program pipelines and
shaders have no per-object handle on the wire at all in P2", `:113-124`). **P4a closes the
program row and must decide explicitly what to do with pipeline and shader** (a pipeline has no
wire object; a composite does — see §9.4).
- `MGP_DIRTY_SURFACE_UNDECIDED_LIST` `:332` is **empty**; every bit answer above is derived and
checked in both directions.
### 5.1 Hole A — `glUseProgram` has no row and no publisher
`GLContext::UseProgram` (`Core.cpp:393-395`) writes `ProgramState::m_currentProgram`
(`ProgramState.h:100`). The scanner sees `pGLContext->UseProgram(...)` from
`GL_Program.cpp:1467`/`:1480`, so a row is owed. Bit 6's shutter mixes lifetimeId ⊕ linkVersion
(`Tracker.h:252`), so a switch between two programs DOES move it — the row's honest answer is
`NEW_SHADER`, but **it is not there today**, meaning the `--check` gate will fail the moment the
scan is re-run against a `UseProgram` call site it now recognises. Verify before writing the brief.
### 5.2 Hole B — a renderbuffer respecify publishes nothing
`RenderbufferObject::{SetInternalFormat, AllocateStorage, SetSamples}`
(`RenderbufferObject.cpp:96-109`) bump no version and raise no notice, and
`AllocateRenderbufferStorage_State` (`GL_Framebuffer.cpp:844-858`) adds nothing. Bit 11's shutter
(`Tracker.h:303-306`) is `anyAttachmentGeneration ⊕ drawFboBindVersion` — neither moves when an
**already-attached** renderbuffer is re-storaged. So
`glBindRenderbuffer; glRenderbufferStorage(newsize)` on a renderbuffer that is already an FBO
attachment is invisible to the framebuffer bit. P4a needs either (a) a version + aggregate on
`RenderbufferObject` (matching `TextureObjectBase::BumpShapeVersion`, which does exactly this and
routes through `BumpSamplingResolutionGeneration`), or (b) `resource_respecify` emitted straight
from the storage entry points the way `BufferObject::NotifyRespecify` does
(`BufferObject.cpp:67-79`) — option (b) matches ARCHITECTURE's rule that renderbuffers share
`MGPResourceDesc` (`docs/Disaggregated/ARCHITECTURE.md` §4.1 table).
---
## 6. The pixel-store shadows — two of them, on opposite sides
### 6.1 Frontend: unpack is fully resolved client-side, pack is not
Every texture upload calls
`MG_Util::PixelStoreProcessor::ProcessTexturePixelsDataUnpack(pixels,
pGLContext->GetPixelStoreParameters(true), …)` before touching the level shadow — call sites
`GL_Texture.cpp:905, 1780-1782, 1902, 1991-1992, 2502-2503, 2655-2656, 2749-2750, 6195-6196`
(decl `MG_Util/Texture/PixelStoreProcessor.h:16`, def `PixelStoreProcessor.cpp:858`). The result
is a **tightly packed** buffer copied row by row into the level shadow
(`GL_Texture.cpp:1803-1817`). This is why `docs/Disaggregated/ARCHITECTURE.md:` §3.2's "explicitly
not migrated" list contains `set_pixel_unpack_state` ("前端已在 `glTexImage` 时解析压缩格式、强制默
认 unpack") and why `MGPPixelPackState` is PACK-only (`MGPipeTypes.h:531-542`).
**Consequence for P4a: `MGPSubData`'s bytes are already tight; `MGPSubRegion::SrcRowStride /
SrcSliceStride` (`MGPipeTypes.h:611-612`) describe the LEVEL SHADOW's pitch, not the
application's.**
Pack, by contrast, is read live at readback: `GL_Texture.cpp:5356`, `:5411`,
`DirectGLES.cpp:6593`, `:8043`, `:9530`, `:9909`.
### 6.2 Espryt: two process-wide driver shadows, asymmetrically invalidated — the pollution risk
- **UNPACK**: `ScopedDefaultUnpackState`, `MG_Backend/DirectGLES/Managers.cpp:4851-4918`. Shadow
statics `s_synced, s_alignment, s_rowLength, s_skipRows, s_skipPixels, s_imageHeight,
s_skipImages` at `:4911-4917` — **`static inline` class members, i.e. one set per PROCESS, not
per context**. `EnsureShadowSynced()` `:4874-4891` pins the driver to GL defaults exactly once
and sets `s_synced = true` `:4878`. **`s_synced` is written at `:4878` and read at `:4875` and
nowhere else in the file — there is no invalidation path at all.** The class comment `:4842-4850`
states the invariant it depends on: "The backend unpack state is set ONLY by MobileGL's own
save/restore helpers … so the shadow stays accurate". Any glPixelStorei on an `UNPACK_*` from
outside those helpers, or a driver context whose unpack state is not the pinned default,
desynchronises it permanently. The known outside writer is the ring path's
`glPixelStorei(GL_UNPACK_ROW_LENGTH, texelSize.x())` at `Managers.cpp:6400` (guarded by
`!ringStaged`, comment `:6297`).
- **PACK**: `PixelStoreImpl`, declared `MG_Backend/DirectGLES/Managers.h:1783-1806`
(`struct PackState{Alignment,RowLength,SkipRows,SkipPixels}` `:1793-1802`), defined
`Managers.cpp:8004-8054` — file-scope `g_packState` / `g_packStateKnown` `:8006-8007`,
`PinPackState` `:8009-8016`, `ApplyPackState` `:8019-8040`, `CurrentPackState` `:8042-8049`,
`InvalidatePackStateCache` `:8051-8053`. **This one IS invalidated**, at MakeCurrent
(`DirectGLES.cpp:10578`) and at context destroy (`:11112`). `ScopedPackState` RAII
`DirectGLES.cpp:6577-6588`, `PackStateFromContext` `:6592-6593`; users at `:7092, 8477, 8588,
8683, 9103, 9432`.
- Header note `Managers.h:1789-1791`: `PACK_IMAGE_HEIGHT / SKIP_IMAGES / SWAP_BYTES / LSB_FIRST`
have **no ES equivalent** and are honoured on the CPU from frontend context state — i.e. the
boundary must keep carrying the full `PixelStoreParameters` (28 B, `MGPipeTypes.h:538-542`),
not the four ES-expressible fields.
**P4a's stake**: once texture upload is emitted by handle, Espryt's upload path stops being the
thing that reads the frontend's unpack state (ARCHITECTURE.md:252 says it "改为从描述符取步长,
`UNPACK_ROW_LENGTH` 从 `SrcRowStride/bpp` 设"), so the P4a emitter has to carry the strides that
`ScopedDefaultUnpackState`'s pin currently makes unnecessary — and the asymmetric invalidation
above becomes a correctness dependency rather than a performance one.
---
## 7. `ReadSurface` resolution and framebuffer completeness
`MGPFramebufferState` (`MG_Pipe/MGPipeTypes.h:355-372`, 304 B) demands three things the client
must resolve **before** the record goes out:
- `MGPSurface ReadSurface` `:361` — "The RESOLVED read surface, not an index. This is what
structurally closes the read-buffer-shared-FBO defect class."
- `Uint8 Complete` `:364`.
- `Uint64 ContentHash` `:370` — both the server's render-pass memo key and the client's emission
suppressor.
`MGPSurface` itself `:343-353` (24 B): `{Res, InternalFormat, Kind(Texture|Renderbuffer|None),
Layered, Level, Layer, UploadTarget}` — **`InternalFormat` is inline so four cross-object masks
fall out with zero lookups** (`:341-342`).
**Where the client gets each piece:**
- Bound FBO: `ctx.GetFramebufferBindingSlot(FramebufferTarget::Draw|Read)`
(`Core.h:547`, `FramebufferState.cpp:49-57`); default-FBO identity is
`FramebufferImpl::pDefaultFramebufferInfo->defaultFBO` (`GL_Framebuffer.h:89, 95`).
- Attachments: `fbo->GetAllAttachmentObjects()` (`FramebufferObject.h:131`,
`FramebufferObject.cpp:159-161`) or per point `GetAttachment(type)` `:155-157`;
then `IsTexture()`/`IsRenderbuffer()`/`GetTexture()`/`GetRenderbuffer()`/`GetTextureLevel()`/
`GetTextureLayer()`/`IsLayered()`/`GetTextureUploadTarget()`
(`FramebufferObject.cpp:53-87`), format from `ITextureObject::GetFormat()` or
`RenderbufferObject::GetInternalFormat()`.
- **The read surface**: `fbo->GetReadBuffer()` (`FramebufferObject.h:137`) then
`fbo->GetAttachment(readBuffer)` — this is the exact two-step every consumer already does:
frontend `GL_Framebuffer.cpp:2373, 2921, 2992`, `Framebuffer/Validators.cpp:185`,
`Getter/GL_Getter.cpp:343, 2114`, `Texture/GL_Texture.cpp:4445`; Espryt
`Managers.cpp:7286, 7391, 7398, 7415`; Magma `VkRenderPassManager.cpp:618`,
`VulkanRenderer.cpp:1806, 1823, 8755, 9243, 10261-10264`.
**The defect class it closes** is visible in Espryt's
`BackendFramebufferObject::SyncReadBufferToBackend` (`Managers.cpp:7410-7430`), whose comment at
`:7424-7426` says it must `Bind(FramebufferTarget::Read)` first "When this is reached from
`SyncCurrentFBO`'s 'same FBO as draw' skip path" — the shared-FBO case where the read-buffer
sync was skipped. With the surface pre-resolved on the client, that whole hazard is
unrepresentable.
- **`Complete`**: `FramebufferObject::CheckCompleteness()` `FramebufferObject.cpp:163-193` — walks
the 41 attachment slots, skips `!IsValid()`, requires equal `GetSize()` and per-attachment
`IsComplete()`, and requires at least one valid attachment. The *GL-visible* status is more
than that: `CheckFramebufferStatus_State` `GL_Framebuffer.cpp:2265-2296` adds
`HasDefinedAttachment` (to pick `INCOMPLETE_ATTACHMENT` vs `MISSING_ATTACHMENT` `:2284-2286`),
`HasNonRenderableColorAttachment` → `UNSUPPORTED` `:2288-2290`, and
`ActiveBackendRejectsDistinctDepthStencil() && HasUnsupportedDistinctDepthStencilAttachments`
`:2291-2294` (**this one reads the backend**, so it cannot be part of a purely-client answer —
see the risk note in §14). `CheckNamedFramebufferStatus_State` `:2298-...` is the same body.
The TODO block at `:2279-2282` records that DRAW_BUFFER / READ_BUFFER / MULTISAMPLE /
LAYER_TARGETS incompleteness is not implemented.
- `Width/Height/Layers/Samples/FixedSampleLocations` for a no-attachment FBO come from
`GetDefaultWidth/Height/Layers/Samples/FixedSampleLocations` (`FramebufferObject.h:141-145`).
- `DrawBuffers[8]` from `GetDrawBuffers()` `:135` (an array of `FramebufferAttachmentType`, so the
client converts to the `Int8` attachment index / `-1` the payload wants, `MGPipeTypes.h:362`).
---
## 8. Texture sub-data accumulation — the union box and the region list already exist
`MG_State/GLState/TextureState/MipmapStorage.h` is where a P4a `MGPSubData` + `MGPSubRegion[]`
is built from; the frontend structure and the payload were designed against each other.
- `struct MipmapDirtyRegion` `:26-39` — `{IntVec3 lo, hi}` half-open, `Empty()` `:29`,
`CoversWholeLevel(levelSize)` `:30-33`, `TexelCount()` `:34-38`. Cleared (all zero) while clean
`:20-25`.
- Union box per level: `m_dirtyRegions` `:119`; `MarkDirtyRegion(level, offset, size)` `:58`
unions and sets the flag; `GetDirtyRegion(level)` `:60` reads it, meaningful only while
`IsDirty(level)` `:54`.
- **Behind it, the disjoint rect list**: `kMaxDirtyRects = 96` `:75`, `m_dirtyRects` `:127`
(per-level `Vector<MipmapDirtyRegion>`), `GetDirtyRects(level, out, maxRects)` `:82`,
`InsertDirtyRect` `:114`. The design notes `:62-81` are load-bearing for the wire format:
the union box "stays the source of truth (every write funnels through
`MarkDirty`/`MarkDirtyRegion` into BOTH representations), backends OPT IN to the list purely as
an upload-size refinement"; **`GetDirtyRects` returning 0 means "upload the union box instead"
and covers every reason at once** — tracking unavailable, a single rect, more rects than
`maxRects`, or a summed area close enough to the box's that one big upload wins `:76-81`.
96 slots because a 16-slot list forced far-apart merges to >90% of the box's area on
Minecraft's ~100 sprites/frame `:68-74`. An EMPTY list is the resting state and always means
"the union box is the whole story" `:120-126`.
- Other level state the descriptor and the blob need: `m_texelSizes` `:116`, `m_data` `:117`
(the level shadow), `m_isDirty` `:118`, `m_compressedData`/`m_compressedFormats` `:128-129`
(kept **beside**, not instead of, the uncompressed shadow — rationale `:84-92`),
`m_requestedCompressedFormats` `:130` (`:99-109`).
- The `ITextureObject` face of all of this: `MarkStorageDirty` `TextureObject.h:252`,
`MarkStorageDirtyRegion` `:257-262` (**base fallback degrades to whole-level**),
`GetStorageDirtyRegion` `:264-267` (**base fallback returns the whole level**),
`GetStorageDirtyRects` `:274-281` (**base fallback returns 0**), `IsStorageDirty` `:253`,
`MapMipmapData` `:251`, `GetMipmapTexelSize` `:243`, `GetMipmapByteSize` `:244`,
`GetMipmapLevelCount` `:242`. Concrete impls
`TextureObject.cpp:379-410` (`TextureObjectWithOneMipmap`), cube overrides
`TextureObject2DCube.cpp:53, 65`.
- The payload side: `MGPSubRegion` `MGPipeTypes.h:607-614` (`X,Y,Z,W,H,D,SrcOffset,SrcRowStride,
SrcSliceStride`; **strides CARRIED, not inferred from a pointer comparison** `:603-606`),
`MGPSubData` `:636-648` (`Res, Target, Level, SourceIsVerbatimLevelShadow, UnionBox,
RegionCount, Blob`). "Carries the union box AND the region list so the SERVER picks the upload
shape — the decision belongs on the side that pays the GPU cost. Mali prices texture upload by
JOB COUNT: ~100 sprite rects against one union box measured +6 ms/frame" `:616-618`.
The blob rule `:624-635`: a non-zero `Blob.Size` that is not exactly the record's own byte size
is `Fatal{ProtocolCorruption}`; **zero means "not declared"**, which is what a monolith emission
is. `MGPSubDataComplete` `:686-691` is the forward terminator for a server-initiated pull.
- Espryt's existing consumer, whose shape `MGPSubRegion` copies: `UnpackStagingBlock`
`Managers.cpp:4934-4942` (`src, rowBytes, rows, slices, srcRowStride, srcSliceStride, offset`),
with the ring-staging contract at `:4920-4933` and `:6297`.
---
## 9. Program artifacts, reflection, per-stage SPIR-V, the link version
`MG_State/GLState/ProgramState/ProgramArtifacts.h` (35 KB, 576 lines) is the P0.5 extraction that
makes `MGPProgramDesc`'s reflection blob possible — it includes only `<Includes.h>` (`:10`), never
`ShaderObject.h` or `SpvcSession.h`.
- `kInvalidUniformOffset = ~0u` `:26`.
- `struct TypeFacts` `:31-59` — 20 flattened predicates (13 `Bool` + 7 4-byte scalars),
**POD of exactly 44 bytes**, asserted `:551-552`.
- `struct ResourceReflection` `:63-86` — one flattened `glslang::TObjectReflection`
(`name, glDefineType, offset, size, index, counterIndex, arrayStride, topLevelArraySize,
topLevelArrayStride, binding, location, stages, arraySize, TypeFacts type`); aliased as
`UniformReflection`/`BlockReflection`/`PipeInputReflection`/`PipeOutputReflection` `:88-91`.
- `struct XfbVarying` `:95-120` — `{name, type, size, bufferIndex, offsetBytes, byteSize,
packedOffsetBytes, blockInstanceName, blockName, blockMemberIndex, blockMemberElement}`.
- `struct LinkArtifacts` `:160-343` — the whole link output in one movable block; `program`
(`SharedPtr<glslang::TProgram>`) is **live only between LinkProgram() and the end of
DoReflection** and is null for an L1-memo-served link `:161-165`; then the four owned
reflection vectors `:168-171`, `lastStageIsFragment` `:177`, `computeLocalSize` `:178`, …,
ending at `xfbVaryingNameMaxLength` / `xfbNeedsScatteredCapture` / `xfbPackedStride` `:340-342`.
Indexed by **TProgram index**, deliberately `:155-158`.
- `struct SpirvArtifacts` `:359-399` — `generatedSpirv` (`Vector<Vector<unsigned>>`, **one module
per entry of the linked-shader snapshot, in that order**) `:360`, `enableSpirvValidation` `:361`,
`uniformOffsets` `:364`, `globalUboScratch` `:365`, `reservedNumSamplesOffset` `:370`,
`spirvStatus` `:377`, `nativeFloat64` `:386`, `pointSizeDemoted` `:398`.
- **The archive**: `VisitFields(Self&, Visitor)` free templates `:401-547`, one per type, the same
table serving serializer (const) and deserializer (non-const) `:403-406`. This is the
ready-made writer for `MGPProgramDesc::Reflection`.
- **Trip wires** `:549-575`: `sizeof(TypeFacts)==44`; per-STL pins under `__GLIBCXX__`
`MGL_RESOURCEREFLECTION_SIZE 128`, `MGL_XFBVARYING_SIZE 128`, `MGL_LINKARTIFACTS_SIZE 1056`,
`MGL_SPIRVARTIFACTS_SIZE 88` `:558-562`; the libc++ (NDK) branch is **inert until the integrator
pins it** `:563-565` — that pin is a P4a chore if the archive crosses on device.
`MGPProgramDesc` (`MG_Pipe/MGPipeTypes.h:323-335`, 192 B): `{Cso, StageMask (== the linked stage
set), GlobalUboSize, ReservedNumSamplesOffset, SpirvStatus, NativeFloat64, PointSizeDemoted,
EnableSpirvValidation, MGPBlobRef Spirv[6], MGPBlobRef Reflection}`.
### 9.1 The "as last linked" rule the emitter must obey
`ProgramObject::GetLinkedShaderSnapshot()` `ProgramObject.h:106` returns
`Vector<LinkedShaderRef>` (`:99-103`, `{shader, source, node}`), rebuilt in Link()'s prologue.
`HasLinkedShaderStage(stage)` `:115-120`. **The header states it twice** (`:92-98`, `:121-133`):
`glAttachShader`/`glCompileShader` take effect only at the next link and neither moves
`m_linkVersion`, so **anything keyed on the link generation must consume this snapshot, never the
live attach list** (`GetAttachedShaders()` `:89-90`), and the SPIR-V module list is sized and
indexed by the snapshot, not by the attach list. `StageMask` therefore comes from the snapshot.
### 9.2 The join gate
`Artifacts()`/`Spirv()` join through `EnsureLinkJoined()` (inline `ProgramObject.h:1275`, blocking
half `ProgramObject.cpp:50-83`) and `EnsureSpirvJoined()` (`ProgramObject.cpp:89-122`).
`JoinPendingLink` moves the node out FIRST to avoid re-entry `:55-60`, moves the artifacts
`:66`, and calls `BumpLinkObservableVersions()` `:72` (the *second* bump; the first was at
enqueue `:67-71`). `GLContext::GetProgramForDraw` `Core.cpp:609-628` is join site J1 and calls
`currentProgram->JoinLinkAndSpirv()` `:627` — **both phases, and the comment `:622-626` explains
why phase A alone reopens the hazard**. `GetProgramForDispatch` `Core.cpp:763-...`,
`GetProgramForUniform` `:786-...`.
**P4a's emitter must be the joiner.** ARCHITECTURE.md:198 says `create_shader_state` is emitted
"从编译池的终止 continuation" — i.e. from the compile pool's terminal continuation, not from the
draw — which is the monolith-unreachable async win. That is a design decision for the brief, not
a fact about this tree: today nothing emits it at all.
### 9.3 What the server still specialises (do NOT try to push it)
`docs/Disaggregated/ARCHITECTURE.md:263` lists the eight extra inputs a backend program depends on
(draw-FBO snorm/unorm clamp mask, fragColor broadcast count, storage-block binding signature,
atomic-counter set, live image formats, patch params; Magma adds default-FB height for FragCoord
Y-flip and the XFB layout): `create_shader_state` publishes the **artifacts**, the server
specialises at verb time.
### 9.4 Program pipelines and the composite band
`GLContext::GetProgramForDraw` `Core.cpp:630-...`: when no program is current it takes the bound
pipeline `:631`, **joins every graphics stage program** `:642-645`, computes
`pipeline->ComputeDrawProgramSignature()` `:647` (`ProgramPipelineObject.h:94-98`, an
`Array<Uint64, kGraphicsStageCount*2>` of per-stage lifetimeId+linkVersion), checks
`GetCachedDrawProgram(signature)` `:648-651` (`ProgramPipelineObject.h:149`) and otherwise
**flattens the pipeline into a fresh `MakeShared<ProgramObject>(0u)`** `:661` — deliberately
unnamed (`:658-660`), graphics stages only (`:663-668`: a composite carrying a compute module
SIGSEGVs inside `vkCreateGraphicsPipelines` on Adreno 830).
`RefreshCompositeUniforms` `:649` / `SetMirroredUniformVersions` `:606`
(`ProgramPipelineObject.h:123-148`).
**A composite is an ordinary `ProgramObject` with its own lifetime id**, so it fits the ShaderCso
slot space — and `MGPipeHandles.h:83-97` already reserves the top 1/16 of that space for exactly
these (`kMGPipeShaderCsoSlotLimit = 1<<20` `:88`, `kMGPipeShaderCsoCompositeSlotBase` `:89-90`,
`MGPipeIsCompositeShaderSlot` `:92-94`), and `SlotAllocator.cpp:19-23` refuses the band from the
ordinary allocator. `ProgramPipelineObject` itself has **no lifetime id and no wire object**
(`:19-170`; the only identity is `m_everBound` `:170` / `GetEverBound` `:51`).
`ShaderObject` (`ProgramState/ShaderObject.h:24`, dtor `:52`) has **no lifetime id** — consistent
with `kUnpublishedDestroy` and with the design (shaders never cross).
---
## 10. `PipeInputs` — what already exists for these kinds, and what fills it
`MG_Backend/MGPipe/PipeInputs.h` (736 lines). Storage list
`MGP_INPUT_STORAGE_LIST` `:73-129`; the block `struct PipeInputs` `:158-687`; three storage
classes V/O/F documented `:144-153`; `sizeof(PipeInputs) < 20 KB` asserted `:714`; the
field-count identity `:709-712`.
**P4a-relevant accessors and their storage:**
| accessor | decl | storage member | class |
|---|---|---|---|
| `GetFramebufferBindingSlot(FramebufferTarget)` | `:508-517` | `m_framebufferBindingSlot[kFramebufferTargetCount]` `:681` | O (raw ptr into the live context) |
| `GetImageTextureBinding(Int unit)` ×2 | `:518-533` | `m_imageTextureBindingBase` `:682` | O |
| `GetTextureUnitObject(Int unit)` | `:549-...` | `m_textureUnitBase` `:686` | O |
| `GetProgramForDraw()` | `:539-543` | `m_programForDraw` `:684` | O (`SharedPtr`) |
| `GetProgramForDispatch()` | `:534-538` | `m_programForDispatch` `:683` | O |
| `GetTransformFeedbackProgram()` | `:544-548` | `m_transformFeedbackProgram` `:685` | O |
| `GetActiveTextureUnit()` | `:199-203` | `m_activeTextureUnit` `:629` | V |
| `GetMaxTouchedTextureUnit()` | `:313-317` | `m_maxTouchedTextureUnit` `:647` | V |
| `GetTextureBindGeneration()` | `:398-401` | `m_textureBindGeneration` `:662` | V |
| `GetSamplingResolutionGeneration()` | — | `m_samplingResolutionGeneration` `:661` | V |
| `GetTextureContextId()` | `:403-...` | `m_textureContextId` `:663` | V |
| `GetPixelStoreParameters` | — | `m_pixelStore` (`[0]`=pack, `[1]`=unpack) `:103` | V |
| `GetClampReadColor()` | `:244-248` | `m_clampReadColor` `:635` | V |
| **forwarded (F, sticky)** | `:558-577` | none | `GetProgramObject(Uint)` `:570`, `GetTextureObject(Uint)` `:571`, `ValidateProgramName` `:574`, `GetBufferBindingPointCount` `:569`, `HasOpenTransformFeedbackSpan` `:572`, `InvalidateCompileEnv` `:573`, `RecordError` `:577` |
`kMGPipeForwardedFieldCount = 7` `:135`, asserted equal to the sticky count `:136-137`. The F
accessors carry **no** `MGP_INPUT_CHECK` / `MGP_INPUT_VERIFY_READ` and the reason is stated
`:563-568`.
The two friend doors: `MGPipeFillAccess` `:611` (client filler) and `MGPipeApplyAccess` `:618`
(the applier scattering render-state chunks straight into `m_renderState`).
`gPipeInputs` `:706` — **`inline PipeInputs& gPipeInputs = *new PipeInputs();`**, leak-at-exit,
with the full ID-18 rationale at `:692-705` (its O-class members are `SharedPtr`s to FRONTEND
objects; destroying the block at exit runs `~VertexArrayObject` → `~BufferObject` →
`MGPipeApplyResourceDestroy` → the backend's twin tables). **Any P4a `SharedPtr<ProgramObject>` /
`SharedPtr<ITextureObject>` added here inherits that rule verbatim.**
### 10.1 `FillPoints.def` rows that fill them
`MG_Pipe/FillPoints.def`. Verb list `:79-148` (69 verbs, **must be exactly the member set of
`MG_Backend::GLFunctionsTable` in declaration order** `:17-22`, enforced by `gen_pipe.py`);
class list `:152-153` (nine classes); the may-read table `MGP_FILL_FIELD_LIST` `:158-338`.
P4a's fields, by class:
- `GetFramebufferBindingSlot`: `kDraw` `:200`, `kDispatch` `:219`, `kClear` `:232`,
`kBlitOrCopy` `:247`, `kTextureOp` `:291`, `kReadback` `:296`, `kProgramOp` `:328`.
- `GetTextureUnitObject`: `kDraw` `:165`, `kDispatch` `:213`, `kClear` `:240`, `kBlitOrCopy` `:256`,
`kTextureOp` `:278`, `kReadback` `:298`, `kProgramOp` `:329`.
- `GetImageTextureBinding`: `:170, 218, 245, 261, 279, 308, 334`.
- `GetTextureContextId` / `GetTextureBindGeneration` / `GetSamplingResolutionGeneration` /
`GetMaxTouchedTextureUnit`: the same seven classes (`:166-169, 214-217, 241-244, 257-260,
280-283, 304-307, 330-333`).
- `GetActiveTextureUnit`: `kBlitOrCopy` `:255`, `kTextureOp` `:277`, `kReadback` `:297`.
- `GetProgramForDraw`: `kDraw` `:161`. `GetProgramForDispatch`: `kDispatch` `:209`.
- `GetPixelStoreParameters`: `kReadback` ONLY `:294`.
- `GetClampReadColor`: `kReadback` `:299`.
- The eight statically over-approximated rows are **all KEPT** with reasons `:30-70`; three of
them are P4a-adjacent (`kTextureOp/kDispatch + IsCapabilityEnabled` because Magma's
`GenerateMipmap` and `PrepareStorageImageTextures` materialise a queued clear that reads
`GL_FRAMEBUFFER_SRGB` `:43-49`; `kTextureOp + GetBufferBindingPoint` / `GetFramebufferBindingSlot`
for the depth-mipmap shader path `:284-292`). **`P3a STATUS` `:65-70` says the omission sweep
rides the full gl44to46 caselist run and every row stays until it lands** — so P4a must not
retire one on desktop evidence either.
### 10.2 `Coverage.def` rows P4a's calls will claim
`MG_Pipe/Coverage.def`. Accessor→call map `:29-132`; sticky list `:144-151`; delta list `:156-158`;
**emitted list `:198-232`** (what a call now SUPPLIES, so the residual fill loop may skip it).
Existing accessor rows for P4a's kinds: `GetFramebufferBindingSlot → SetFramebufferState` `:84`,
`GetImageTextureBinding → SetShaderImages` `:85`, `GetActiveTextureUnit → SetSamplerViews` `:30`,
`GetMaxTouchedTextureUnit → SetSamplerViews` `:88`, `GetSamplingResolutionGeneration →
SetSamplerViews` `:109`, `GetTextureBindGeneration → SetSamplerViews` `:112`,
`GetTextureContextId → SetSamplerViews` `:113`, `GetTextureObject → SetSamplerViews` `:114`,
`GetTextureUnitObject → SetSamplerViews` `:115`, `GetProgramForDraw → SetDrawProgram` `:100`,
`GetProgramForDispatch → SetDispatchProgram` `:99`, `GetProgramObject → CreateShaderState` `:101`,
`GetPixelStoreParameters → SetPixelPackState` `:94`.
**None of them is in the EMITTED list yet.** The two standing warnings for P4a:
- `GetPixelStoreParameters` is **deliberately absent from EMITTED** `:173-181` — the field is
`m_pixelStore[2]` and `set_pixel_pack_state` carries the pack half only, so a row there would be
a half-truth that neither the poison nor the verify comparator could see. **P4a must not add it.**
- P3a's own row (`GetBoundVertexArray → BindVertexElements` `:202`) is "shape-only" and the note
`:191-197` says the decision of whether an emitted call supplies the WHOLE field lives in
`PipeFill.cpp`'s `EmittedCallSuppliesTheWholeField` (`:1116`), **deliberately rather than
silently by the row's presence**. Same discipline applies to every P4a row.
---
## 11. The payloads P4a fills (all already declared, `MG_Pipe/MGPipeTypes.h`)
`MGPResourceDesc` `:150-176` (88 B) — one create/respecify shape for buffers, **every texture
target** and renderbuffers: `Target` `:152`, `StorageKind` (== `TextureStorageType`) `:153`,
`BindMask` `:157` (the `ELEMENT_ARRAY` bit is the index-mirror switch `:154-156`),
`InternalFormat` "already resolved to an uncompressed fallback by the client" `:158`,
`Width/Height/Depth` `:159`, `ArrayLayers/Levels/Samples` `:160`,
`FixedSampleLocations/Immutable` `:161`, `Usage`/`StorageFlags` `:162-163`,
`HasDefinedContent` `:164`, `ImageBindableHint` `:165`, `GlNameForDiag` (**diagnostics only** —
a GL name is never an identity `:167-170`), `ViewOf` `:172`, `BufferForTexBuffer` `:173`,
`BufOffset/BufSize` with `kMGPipeWholeBuffer = ~0` `:174, 177`.
`MGPipeResourceRespecifyNeedsAck(desc)` `:680-682` — `desc.Immutable != 0` (rationale `:668-679`).
Other P4a payloads: `MGPSamplerDesc` `:283-287` (32 B); `MGPSamplerView` `:293-304` (36 B, view
restrictions only — rationale `:289-292`: an attachment-only / image-only / CopyImageSubData-only
texture has no sampler view to hang params on); `MGPTextureParams` `:307-318` (32 B, per texture
OBJECT, with `ForceResync` `:314` mirroring Espryt's `m_forceTextureParamsResync`);
`MGPSurface` `:343-353`; `MGPFramebufferState` `:355-372`; `MGPSamplerViews` `:440-444`,
`MGPSamplerStates` `:447-451`, `MGPImageView` `:453-462`, `MGPShaderImages` `:464-468` (all
`{Start, Count, ContentHash}` var-tail headers); `MGPProgramDesc` `:323-335`;
`MGPGlobalConstants` `:507-513`; `MGPSubData`/`MGPSubRegion` `:607-648`; `MGPCopyRegion`
`:708-716`; `MGPMipPlan` `:741-745`; `MGPReadbackInfo` `:748-756`; `MGPClear` `:729-739`;
`MGPBlit` `:718-725`.
Catalogue rows (`MG_Pipe/PipeCalls.def`, `MGP_CALL_LIST_DOCUMENTED_COUNT 71` `:75`):
`CreateSamplerState/DeleteSamplerState` `:104-105`, `CreateSamplerView/DeleteSamplerView`
`:106-107`, `CreateShaderState/BindShaderState/DeleteShaderState` `:108-110`,
`SetFramebufferState` `:113`, `SetSamplerViews` `:117`, `BindSamplerStates` `:118`,
`SetShaderImages` `:119`, `SetGlobalConstants` `:122`, `SetDrawProgram`/`SetDispatchProgram`
`:126-127`, `SetTextureParams` `:133`, `ResourceSubData` `:134`, `ResourceSubDataComplete` `:136`,
`ResourceCopyRegion` `:139`, `GenerateMipmap` `:140`, `GetTextureImage` `:141`, `Blit` `:143`,
`Clear` `:144`, `ReadPixels` `:145`. **Record numbering never churns — the wire opcode is the
1-based position, so a new call is APPENDED to its group** `:26-29`.
---
## 12. The client emission machinery P4a mirrors
- **Slot allocator** `MG_Impl/Pipe/SlotAllocator.{h,cpp}` — `Allocate` `cpp:38-81`,
`AllocateFor` `:83-95`, `FindByLifetimeId` `:97-105`, `Acquire` `:107-111`, `Free` `:113-130`
(**stale-gen free is a no-op** `:117-119`), `IsLive` `:132-137`, `HighWater` `:151-153`,
`Reset` `:161-168`. **Gen moves only on reuse** `cpp:66-75`, `h:24-28`. `MGPipeSlots()`
`cpp:170-181` is **never destroyed** with the ID-18 rationale spelled out at `:171-179`.
- **CSO cache** `MG_Impl/Pipe/CsoCache.h` — the exact template for a P4a sampler-CSO or
program-CSO cache: version-first skip `:14-25`, hash + **memcmp confirm** `:84-98`
(a bare 64-bit equality would alias two states — `:20-24`), `Mint` `:138-172`, LRU `Evict`
`:174-183` (emits `delete_*` and frees the slot), capacity 64 `:53`, counters `:57-69`,
`s_hashForTest` seam `:121-128`, `MGPipeCsoCacheInstance()` never destroyed `:197-203`.
- **Set-hash suppressor** `MG_Impl/Pipe/SetHashSuppressor.h` — `MGPipeSuppressorSlot` `:44-53`
already reserves `SetSamplerViews` (P3b), `BindSamplerStates` (P3b), `SetShaderImages` (P4b),
`SetShaderBuffers` (P4b), `SetStreamOutputTargets` (P4b). **There is no
`SetFramebufferState` slot** — P4a adds one (or latches `MGPFramebufferState::ContentHash`
itself). `ShouldEmit` `:61-67` (**hash 0 is reserved for "never emitted"; a computed 0 remaps to
1** `:31-33`), `Invalidate`/`InvalidateAll` `:71-75`. The requirement a wired slot puts on its
hash is stated `:23-29`: it must cover **every** input the record carries, not just the set.
- **Resource tracker** `MG_Impl/Pipe/ResourceTracker.h` — `MGPipeBindMaskForBufferTarget`
`:96-134` + the exhaustiveness `static_assert` `:136-148`, `MGPipeBuildResourceDesc` `:171-...`,
`MGPipeBuildSubDataRecord` `:225-...`, **`MGPipeForEachSubDataRecordRange` `:257-...` (the
splitter for ranges past a single record's bound)**, `class MGPipeResourceTracker` `:282-...`
(`Acquire` `:292`, `Find` `:303`, `Resolve` `:313`, `Retire` `:325`, `NotePublished` `:342`,
`BindMask` `:355`, `NoteBoundAs` `:369`, `RefreshBindMask` `:407`, counters `:448-463`,
`ResetForTest` `:493`), `MGPipeResourceTrackerInstance()` never destroyed `:554-559`, and the
reverse-channel callbacks `MGPipeClientOnBufferWriteback` `:570-...`,
`MGPipeClientOnGpuWritten` `:596-...`, `MGPipeInstallClientResourceCallbacks` `:623-...`.
- **Vertex-input emitter** `MG_Impl/Pipe/VertexInputEmit.h` — the CSO-with-blob template:
wire builders `:78-104`, `:106-121`, content hash `:123-129`,
`class MGPipeVertexInputEmitter` `:136-...` (`EmitVertexElements` `:157`, `EmitVertexBuffers`
`:200`, `EmitIndexBuffer` `:256`, `RecordIsPublished` `:307`, `NoteRecordDestroyed` `:319`,
`Reset` `:340`, `EmitCreate` `:373`, the blob staging array `:413`), instance never destroyed
`:433-441`.
- **The validate point** `MG_Impl/Pipe/PipeFill.cpp:1504-1620+`: poison serial `:1518-1524`,
verb + identity `:1525-1527`, the no-context early exit that still clears the pending base
instance `:1528-1536`, the dirty walk `:1544-1545`, the `wants()` lambda that goes through
**`MGPipeSubsystemForDirty` and never names a subsystem constant** `:1548-1557`, the
`FreshlyPrimed()` block `:1570-1585` (CSO cache reset, `MGPipeApplierReset`, suppressor
invalidate-all, vertex-input emitter reset — **and the note at `:1574-1582` that the resource
tracker is deliberately NOT reset**), then the per-subsystem emissions `:1587-1615`.
P4a's emitters go in this ladder.
Also here: `SubsystemForEmitter` `:957-...` + its pairing `static_assert`s `:984-1032`,
`kMGPipeWiredSubsystems` `:1071`, `EmittedCallSuppliesTheWholeField` `:1116`,
`MGPipeNoteAggregate` `:529-552`, and the seven F-class forwarder bodies `:875-906`.
- **Applier** `MG_Pipe/PipeApply.h` — `MGPipeResourceOps` `:74-86` (+`Set/Get` `:90-91`),
slot bounds `kMGPipeMaxResourceSlots = 1<<20` / `kMGPipeMaxVertexElementsSlots = 1<<16`
`:112-113` with the "a slot at or above these is `Fatal{ProtocolCorruption}`, never a resize"
rule `:97-111`, `MGPipeResourceRecord` `:117-132`, `MGPipeVertexElementsRecord` `:141-152`,
`MGPipeApplierState` `:154-...` — **and the explicit split at `:194-218`: object records
(`Resources` `:217`, `VertexElementsCsos` `:218`) survive a make-current and are cleared only by
the object's own death signal or `MGPipeApplierReleaseObjectRecords` `:300`; working state
(`BoundVertexElements` `:236`, `VertexBuffers` `:240`, …) is cleared by `MGPipeApplierReset`
`:291`**. Refusal counters `:228-229` exist because "a no-op nobody can see is a dropped call
nobody can see" `:220-227`.
---
## 13. Unit tests under `MG_Test` that cover these frontend objects
All registered with `LABELS unit` via `gtest_discover_tests` (e.g.
`MG_Test/Framebuffer/CMakeLists.txt:20`, `MG_Test/Texture/CMakeLists.txt:20, 38`).
| file | size | suites | what it pins for P4a |
|---|---|---|---|
| `MG_Test/Framebuffer/FramebufferTest.cpp` | 1669 L, **61 `TEST`** | `FramebufferTest`, `PackedReadbackEncodeTest` | attach/detach, draw/read buffer validation, completeness |
| `MG_Test/Texture/TextureTest.cpp` | 6714 L, **192 `TEST`** | `TextureTest`, `SharedExponentRGB9E5Test` | the whole texture surface; **ID-8 records that P3a's wave1/wave2 both appended at the same point here and collided — resolve by union, keep every name** |
| `MG_Test/Texture/TextureViewTest.cpp` | 551 L | `TextureViewTest` (`:147, 159, 169, 178, 198, 224, 236, 259`, …) | view state, `TEXTURE_VIEW_*`, composition onto the root, "a framebuffer attach is bounded by the view's own level count" `:198` — directly `MGPResourceDesc::ViewOf` / `MGPSamplerView` |
| `MG_Test/Texture/VkClearManagerTest.cpp` | | | the queued-clear materialisation `FillPoints.def:284-289` names |
| `MG_Test/State/ObjectLifetimeIdTest.cpp` | 158 L, 6 `TEST(ObjectLifetimeIdTest,…)` | | **the id invariant P4a's handles rest on**: constructs/destroys on the heap 64× (`:57-58`), publishes through a volatile sink so the new/delete pair cannot be elided (`:42-46`), asserts id ≠ 0 (`:72-73`) and strictly increasing (`:74-76`), and **skips rather than passes quietly if the allocator never repeats an address** (`:21-24`). Covers `BufferObject`, `RenderbufferObject`, `VertexArrayObject` (`:34-36`) — **not** Texture/Framebuffer/Sampler/Program, all of which now have ids. Cheapest P4a test win. |
| `MG_Test/State/RenderStateTest.cpp` | | | render state incl. the pixel-store setters |
| `MG_Test/Program/ProgramTest.cpp` | 4990 L | | link, reflection, uniforms |
| `MG_Test/Program/ProgramArtifactsTest.cpp` | 133 L, 5 `TEST(ProgramArtifacts,…)` | `AliasesAreTheSameTypes` `:28`, `TypeFactsIsPodOf44Bytes` `:44`, `VisitFieldsCoversEveryMember` `:80`, `VisitFieldsPassesConstnessThrough` `:90`, `SizesArePinnedOnThisToolchain` `:115` | **the archive contract `MGPProgramDesc::Reflection` serialises through**; `:115` is where the libc++/NDK numbers get read from (`ProgramArtifacts.h:553-557`) |
| `MG_Test/Program/ProgramPipelineCompositeTest.cpp` | 724 L | `ProgramPipelineCompositeTest` | the composite path of §9.4 |
| `MG_Test/Program/{AsyncCompile,AsyncLink,AsyncSpirvPhase,AsyncTeardown,OptimisticStatus,ParallelShaderCompile}Test.cpp` | | | the join gates a P4a emitter will trip |
| `MG_Test/Program/ProgramInterfaceTest.cpp`, `XfbBlockVaryingTest.cpp`, `TessellationLinkTest.cpp` | | | reflection surface |
| `MG_Test/Pipe/*` | | `PipeCatalogueTest` (585 L — payload sizes and the 71-record arithmetic), `PipeInputsTest` (644 L), `TrackerTest` (917 L), `CsoCacheTest` (200 L), `SlotAllocatorTest` (292 L), `ResourceEmitTest` (1874 L), `VertexInputEmitTest` (635 L), `RenderStateSpansTest` (1368 L), `MagmaPipeIdentityTest` (217 L) | **`ResourceEmitTest` and `VertexInputEmitTest` are the two files a P4a `*EmitTest` is modelled on**; `PipeCatalogueTest` is where every new payload size assertion lands |
| `MG_Test/Util/PipeStatsTest.cpp` | | `CounterNamesAreStable` (`:260`), `SummaryLineCarriesEveryClassAndGate` (`:137`) | any new `PipeStats::CallClass` must be pinned in both |
| `MG_Test/ScopedPipeVerb.h` | | | the fixture helper for driving a verb in a unit test |
Fixture trap to carry forward — **ID-14**: `MG_Test/Buffer/BufferTest.cpp`'s `ScopedBackendOps`
scoped only `BufferBackendOps`, so under a push build 26 of 86 dispatch cases routed into the
pipe; `83302ca2` made it save/null/restore the pipe table too, the way `ResourceEmitTest`'s
`ApplierGuard` scopes the applier. **Any P4a test that installs a backend ops table needs the same
two-scope shape**, and the follow-up (a pipe-shaped mock so the same assertions run over the
handle path) is still open.
---
## 14. Named risks and open questions for the brief
1. **`Complete` cannot be a purely client-side answer today.**
`CheckFramebufferStatus_State` (`GL_Framebuffer.cpp:2291-2294`) consults
`ActiveBackendRejectsDistinctDepthStencil()`, and `HasNonRenderableColorAttachment` `:2288`
reads the backend's probed format-capability cache (the comment at `:101` says so).
`FramebufferObject::CheckCompleteness()` (`FramebufferObject.cpp:163-193`) is backend-free but
is a **weaker** answer. Decide explicitly which one `MGPFramebufferState::Complete` carries and
say so in the payload comment; a client that emits the GL-visible status is reading the backend
from the client side, which P4a is supposed to be removing.
2. **Renderbuffer respecify publishes nothing** (§5.2) — a real correctness hole, not a
narrowing item.
3. **`glUseProgram` has no `DirtySurface.def` row** (§5.1); the gate is likely to go red the
moment P4a touches that path.
4. **Espryt's unpack shadow is never invalidated** (§6.2, `Managers.cpp:4911` vs
`DirectGLES.cpp:10578`/`:11112`) — once P4a's descriptor carries the strides, the shadow stops
being a benign optimisation.
5. **`FramebufferObject::SetDrawBuffer` versions the wrong attachment slot**
(`FramebufferObject.cpp:195-199`): it bumps `m_attachmentVersions[buffer]`, i.e. the value being
written, not the index being written to. `m_objectVersion` and the aggregate still move, so bit
11 is safe; a *narrower* P4a shutter built on `m_attachmentVersions` would not be.
6. **The composite band's bookkeeping is unwritten.** `MGPipeHandles.h:83-94` and
`SlotAllocator.cpp:19-23` reserve and defend the band, but nothing mints from it yet, and a
composite is created on a cache miss inside `GetProgramForDraw` (`Core.cpp:661`) — a
`MakeShared` on the draw path, whose death is an ordinary `~ProgramObject`.
7. **`ProgramArtifacts.h`'s libc++ size pins are inert** (`:563-565`). If the archive is to cross
on device in P4a, the integrator owes those four numbers from an NDK build.
8. **`MGPProgramDesc` is 192 B with six SPIR-V blobs; the ring caps one record at half its
capacity** (`ARCHITECTURE.md` §4: `RingProducer::MaxRecordBytes()`), so `create_shader_state` is
named there as one of the two emissions that must be split by the emitter. `MGPipeForEach
SubDataRecordRange` (`ResourceTracker.h:257`) is the existing splitter shape.
9. **ID-19's cost budget.** P3a already added +699 (Espryt) / +422 (Magma) ns/draw and rd12 moved
+30%/+27% on device. Every P4a per-verb emission needs a suppressor slot or a version-first
skip *before* it hashes anything — the `MGPipeCsoCache::Acquire` shape (`CsoCache.h:14-25`),
not a hash-every-verb shape.
10. **`kUnpublishedDestroy` for pipelines and shaders** (`DirtySurface.def:301-302, 305`) should be
resolved deliberately: a program pipeline has no wire object and a shader never crosses, so the
honest P4a outcome may be "the program row becomes `kExplicitDestroy`, the other two stay
`kUnpublishedDestroy` with an updated reason", not "all three close".
File diff suppressed because it is too large Load Diff