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.
19 KiB
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:
HasDefinedContentis storage-defining. It is not a shape field, butglBufferData(size, NULL)at an unchanged size is an orphaning reallocation. Classifying it as metadata would have made orphaning stop clearing pending uploads.GlNameForDiagis 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
- Wire v3's local constant for
Target == 3can be deleted at the rebase.MGPipeFramebufferTarget::Namedexists andCountis 4, sostate.Target >= Countaccepts 3 with no change at the validate point. - 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/andBRIEF-P4A.mdare outside my grant (my files wereMGPipeTypes.h+ the A-owned catalogue test), and ID-15's own correction puts the fourth row's implementation in package D's texture-familyResolve*SubsystemArm. Both still need an owner; neither is a contract-header edit. - 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,
Genis a validity test on read, and there is no removal path — consistent with D-I2 (no framebuffer delete call) and withReleaseObjectRecordsclearing the whole table plus both bound handles (wire m1). - B v2's suppressor is now under-specified by its current shape.
EmitFramebufferStatefeeds one globalMGPipeSuppressorSlot::SetFramebufferStateslot 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. - B v2's
ReadSurfacebuild changes. TodayBuildFramebufferState(fbo, readSurfaceSource, target, out)passes the read framebuffer as the surface source for a Draw record. Under this contractReadSurfaceis 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.