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

19 KiB
Raw Blame History

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:

    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:

        // 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:

        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:

    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:

    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.