Files
MobileGL/docs/Disaggregated/notes/p4a/p4a-results/contract-v5.md
T
swung0x48 aba329cc53 [Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.

1. P6's plan and contract draft (neither started; not one line of code)

     docs/Disaggregated/P6-SPAWN-PLAN.md      the package plan
     docs/Disaggregated/P6-CONTRACT-DRAFT.md  the contract draft (moves to
                                              MG_Remote/CONTRACT-P6.md when c6 lands)

   The three findings that mattered, all written into the documents:

   a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
      the tree and already tested: SocketDoorbell including hangup detection and the two
      lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
      passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
      protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
      SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
      assembly plus a control plane plus a process, not "write a socket transport".

   b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
      audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
      the tree again. So the first package, a6, is a read-only audit that writes no code, and
      every contract row that depends on it is marked PENDING a6 rather than decided in
      advance.

   c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
      and protocol.fbs:186-196's own comment says Android transfers the window out of band -
      that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
      the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
      gate measures. A real window reaching the server is a named refusal. This gets its own
      section because "P6 is done" would otherwise read as "the game runs now".

   The contract adds rule G: a role may not name a process-local handle. It extends P5c's
   rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
   EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
   a token this contract defines or they do not cross, and a descriptor crosses only through
   SCM_RIGHTS, where the kernel renumbers it.

   What P5e left for P6 gets its own section. The latch semantics are already designed
   (ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
   client no longer waits while the peer process can DIE: the client holds records that were
   published and will never be applied, and Android's freezer suspends the child without
   closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
   That is P6's only new design; everything else is carriage. It shares a predicate with E1's
   outstanding re-specification (ID-122), and the two should be designed together.

   Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
   match integration-split's name for name, because a differing set means the lane is quietly
   running less; and the arm-proof gate requires every entry to record the child pid and
   transport=spawn in its OWN private log - ID-124 established that this kind of false green
   really happens, and a spawn lane that actually ran monolith would pass every other gate.
   S2's shape must be settled before it is written, and the document says why: E1 is the
   cautionary case.

2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)

   ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
   the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
   is under no version control. A record cited hundreds of times that lives only locally is not
   a record, so it moves in whole, with its directory structure intact.

   Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
   stay where they are: they are evidence DATA rather than documents - large, regenerated per
   run, and mostly carrying absolute paths and device serials that mean something only on the
   machine that produced them. The mapping and this split are written in
   docs/Disaggregated/notes/README.md.

   Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
   document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
   material salvaged from failed workflow runs, which may duplicate the like-named phase
   directories and is kept because a few of those were the only complete version at the time.

   CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
   deliberately outside it: those notes' file:line citations were written against their own
   code heads, and resolving them against today's HEAD would fail wholesale - which is not an
   error, it is their correct state as a historical record. To check one, use the revision it
   declares (--rev).

3. Inconsistencies fixed in passing

   - README.md's status line still said P5e was in progress while the stage table already said
     closed.
   - CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
     (a) and (b) were run in the previous commit; rewritten to closed plus the one item that
     actually remains (E1).
   - ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
     package order, the scope boundary and the two new gates.

Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
2026-09-18 23:31:39 -04:00

311 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P4a 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.