mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-16 22:43:24 +09:00
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.
435 lines
34 KiB
Markdown
435 lines
34 KiB
Markdown
# P3a package B, commits b1..b4 — the client (`client-v1`)
|
|
|
|
Branch `p3a/client`, worktree `/home/swung/w7/p3a-client`, based on `39722687` (tag `p3a/contract`, ID-1's
|
|
base ref). Not pushed. Four commits, single-line messages, no bodies, no attribution lines.
|
|
|
|
| step | hash | message |
|
|
|---|---|---|
|
|
| b1 | `73bab3d6` | `[Feat] (Pipe, State): mint a {slot, gen} handle for every buffer object and publish its create, respecify, sub-data, flush, readback and destroy as pipe calls` |
|
|
| b2 | `1ae6b4f4` | `[Feat] (Pipe): push the bound VAO's format, its vertex buffers with an explicit baseInstance, and its index binding as their own calls` |
|
|
| b3 | `71805d59` | `[Feat] (Pipe): widen the dirty-surface scan to MG_State so the MGP_NOTE_MUTATION sites stop being outside the gate` |
|
|
| b4 | `a0ac79cc` | `[Test] (Pipe): pin the buffer and vertex-input emitters - every attribute field survives the wire, a bare baseInstance change still emits, and the index-buffer bit ignores unrelated writes` |
|
|
|
|
**b1's safety property holds as specified**: nothing in the tree registers `MGPipeResourceOps`, so
|
|
`MGPipeResourceSubsystemEnabled()` is false in every build, every buffer dispatch falls through to
|
|
`g_bufferBackendOps`, and the tree behaves exactly as it did. G1 is 0/0/0/0 after each of the four.
|
|
|
|
---
|
|
|
|
## 1. Per-file summary
|
|
|
|
10 files, +1613 / -45. Every one is in C.1's table except the three marked **[outside C.1]**, each of which is
|
|
a required consequence and is argued in §4.
|
|
|
|
| file | what changed |
|
|
|---|---|
|
|
| `MG_Impl/Pipe/ResourceTracker.h` | **new.** D-A3's twelve `MGPipeBindBit`s and the `constexpr BufferTarget -> mask` table with `MGPipeEveryBufferTargetIsMapped()`'s completeness `static_assert` (no `default:` arm, so a new enumerator is a build break); the two buffer discriminators; the pure builders `MGPipeBuildResourceDesc` / `MGPipeBuildSubDataRecord`; the record-range walk `MGPipeForEachSubDataRecordRange` with its cap parameter; `MGPipeResourceTracker` (handle mint, the `slot -> BufferObject*` inverse with its `Gen` compare, the sticky bind mask with its epoch guard, the four emission observables); D-D's client callbacks `MGPipeClientOnBufferWriteback` / `MGPipeClientOnGpuWritten` and their one-shot installer. Header-only, push-only. |
|
|
| `MG_Impl/Pipe/VertexInputEmit.h` | **new.** D-G2's two pure wire conversions; D-H2.3's `MGPipeVertexBufferSetContentHash` (Start, Count **and BaseInstance** mixed in); `MGPipeVertexInputEmitter` with D-G3's three arms, the **per-handle** `Latch{Published, Gen, ConfigVersion}` table, D-H3's `MGPVertexBuffer[]` build, D-I's index record, the staging buffers that double as the emitted-record observable at no copy, and `Reset()` for a fresh context. Header-only, push-only. |
|
|
| `MG_Impl/Pipe/PipeFill.{h,cpp}` | the three stub emitters get bodies (no call site moved); the nine `MGPipeEmitResource*` definitions plus `MGPipeResourceSubsystemEnabled` / `MGPipeResourceOpsHaveSubDataResident` / `MGPipeMintResourceHandle` / `MGPipeEmitResourceDestroyAndFree`; `MGPipeSetPendingBaseInstance` + `MGPipePendingBaseInstance` and the **two** clears (the validate point consumes it after emission, `MGPipeLeaveVerb` clears it too); the emitter's `Reset()` on `FreshlyPrimed`; `kMGPipeWiredSubsystems` gains bits 7 and 8 (§3); `EmittedCallSuppliesTheWholeField` gains `GetBoundVertexArray` (§2). |
|
|
| `MG_Impl/Pipe/Tracker.h` | D-M's three `MGPipeSubsystemForDirty` arms (bits 5, 9, 10 -> `kMGPipeSubsystemVertexInput`); D-I's **narrowed** bit-10 shutter (the bound VAO's own element-slot version, widened, mixed with the bound object's lifetime id and the VAO identity) and its `MGPipeWidenedCounter`; bit 9 gains the pending base instance (§4 B-DEV-3); `SetPendingBaseInstance` / `PendingBaseInstance` / `ClearPendingBaseInstance` and their `Reset()`; `kMGPipeDirtyEmittedAtP3a`; the `:64-78` comment corrected (bits 9/10 are P3a) and the composite-shutter note re-scoped now that three composed bits are load-bearing. |
|
|
| `MG_Impl/Pipe/SetHashSuppressor.h` | comment only: slot `SetVertexBuffers` marked wired at P3a, plus the requirement a wired slot puts on its hash (why `BaseInstance` is in it). |
|
|
| `MG_Pipe/PipeMutation.h` | **declarations only**, beside the two notices: the eleven resource entry points and a forward declaration of `MG_State::GLState::BufferObject`. Why here rather than an `MG_Impl` include from `MG_State`: §4 B-DEV-1. |
|
|
| `MG_State/GLState/BufferState/BufferObject.cpp` | D-A1's dispatch branches at all nine op sites (`OnDestroy`, `Respecify`, `SubData`, `FlushMappedRange`, `ResidentSubData`, `ReadbackFromGpu`, and `AcquirePersistentMap` at its three call sites) plus the `ResidentSubData` **nullability probe** in `FillSubData`; `ResourceCreate` + the handle mint from the constructor; `ResourceDestroy` then `MGPipeSlots().Free` from `~BufferObject`, in that order. Every edit inside `#if MOBILEGL_PIPE_PUSH`, and the pull build's text is byte-for-byte what it was (G1 proves it). |
|
|
| `MG_Pipe/DirtySurface.def` | two new rows the widened scan found (§4 B-DEV-4); the header's "scans MG_Impl/GLImpl" corrected to both roots and both mechanisms; blind spot 3 marked CLOSED; `MarkBufferObjectForDeletion` / `MarkVertexArrayForDeletion` gain the comment naming the call that makes each true. |
|
|
| `scripts/gen_pipe_dirty_surface.py` | G9: `SCAN_ROOT` -> `SCAN_ROOTS` (`MG_Impl/GLImpl` + `MG_State/GLState`), `NOTE_MUTATION_RE` and the enclosing-function attribution, `scan_all` / `main`'s existence check / the report header updated. `--check`, `--self-test` and `--summary` all still work; the 21 canned negative controls all still trip. |
|
|
| `MG_Pipe/FillPoints.def` | comment only: the `MOBILEGL_PIPE_POISON_OMIT` sweep's verdict lands with the G15 caselist run, every row stays in place. |
|
|
| **[outside C.1]** `MG_Test/Pipe/TrackerTest.cpp` | `OnlyTheFiveEmittedBitsNameASubsystem` follows `kMGPipeDirtyEmittedAtP3a` instead of `...AtP2` (a mandatory consequence of D-M — see §4 B-DEV-5), **name unchanged**; the two `TheIndexBufferBit*` cases C.1's list asks for, plus their rows in the pull-skip list. |
|
|
| `MG_Test/Pipe/ResourceEmitTest.cpp` | four cases appended, disjoint from the contract commit's one. |
|
|
| `MG_Test/Pipe/VertexInputEmitTest.cpp` | seven cases appended, disjoint from the contract commit's one. |
|
|
|
|
---
|
|
|
|
## 2. `EmittedCallSuppliesTheWholeField`, field by field
|
|
|
|
The predicate answers "may the residual fill stop pulling this field, because an emitted call supplies it
|
|
completely". It is consulted only for a field whose emitter's subsystem is in `kMGPipeWiredSubsystems`, so
|
|
P3a's decision set is exactly the emitted-list rows whose emitter names one of the two new subsystems.
|
|
|
|
| field | emitter | decision | reason |
|
|
|---|---|---|---|
|
|
| `GetBoundVertexArray` | `BindVertexElements` | **false — keep pulling** | The storage is a `SharedPtr<VertexArrayObject>`, a frontend heap reference. The call carries an eight-byte `{slot, gen}` and nothing else, and the applier stores it in `MGPipeApplierState::BoundVertexElements`. It has no way to produce the pointer and P3a deliberately does not give it one — a payload never contains a pointer, and the whole point of the conversion is that the server stops holding frontend references. Skipping the pull would leave `m_boundVertexArray` **null on every draw of every push build**: not subtle staleness, every backend read of the bound VAO reading nothing. The row is therefore *emitted-and-still-pulled*, exactly like `GetPixelStoreParameters`. What retires the pull is not a better applier, it is P8, where the backend stops reading a frontend VAO at all. `Coverage.def`'s note asks for this decision to be taken here deliberately rather than inherited from the row's presence; it is, and the reasoning above is written into `PipeFill.cpp` beside the arm. |
|
|
| *(no other field)* | — | — | `MGP_COVERAGE_EMITTED_LIST` gained exactly one row at `c0` (`C4`). `GetBufferBindingSlot` is deliberately **not** in the emitted list (five of its targets are still pulled), and the resource family has no emitted row at all and cannot have one: its calls are dispatched at the GL call that causes them rather than filled into a `PipeInputs` field. |
|
|
|
|
The two pre-existing `false` rows (`GetPixelStoreParameters`, `GetCurrentVertexAttribute`) are untouched.
|
|
|
|
**Consequence, stated so the integrator does not have to derive it:** P3a retires **no** pull. Every field the
|
|
residual fill copied at `c0` it still copies. That is the correct answer for this phase and it is also why the
|
|
verify lane cannot regress on account of a skipped field — there is none.
|
|
|
|
---
|
|
|
|
## 3. The `kMGPipeWiredSubsystems` change
|
|
|
|
```
|
|
c0: RenderState | PixelPack | PatchState | VertexAttribDefaults
|
|
b1: ... | kMGPipeSubsystemResources
|
|
b2: ... | kMGPipeSubsystemVertexInput
|
|
```
|
|
|
|
Each bit is added by the commit that gives *its own* emitters their bodies, which is what B2 asks for. Both
|
|
additions are recorded in place with the reason they change nothing about the fill loop:
|
|
|
|
- **bit 7, `kMGPipeSubsystemResources`, names no emitted field at all.** `SubsystemForEmitter` can never
|
|
return it — there is no `Coverage.def` emitted row for the resource family and there cannot be one. The bit
|
|
is in the constant so that it states what this build emits for, which is what an operator reading a
|
|
recorded `MOBILEGL_PIPE_PUSH` value has to be able to trust.
|
|
- **bit 8, `kMGPipeSubsystemVertexInput`, names exactly one emitted field**, `GetBoundVertexArray`, and §2
|
|
says false for it. So the bit switches the **emission** on and changes nothing about the residual fill.
|
|
|
|
`MGPipeSubsystemForDirty`'s three new arms make `PipeFill.cpp`'s three conditional pairing `static_assert`s
|
|
(B1) hold as the equalities D-M asks for, with **no edit to them** — the contract commit wrote "no later edit
|
|
is required, and none is invited", and none was made.
|
|
|
|
---
|
|
|
|
## 4. Deviations, each with its reason
|
|
|
|
### B-DEV-1 — the resource entry points are declared in `MG_Pipe/PipeMutation.h`, not in `ResourceTracker.h`
|
|
|
|
D-A1 puts the dispatch in `BufferObject.cpp`, which is `MG_State`'s. `MG_State` may not include
|
|
`MG_Impl/Pipe/ResourceTracker.h`: that is the layering the `mutation-header` closure probe exists to protect
|
|
(*"it may only DECLARE the notice: reaching MG_Impl would pull the fill implementation into the state machine
|
|
that calls it"*). So the eleven entry points are **declared** in `PipeMutation.h` — B's file, already included
|
|
by `BufferObject.cpp`, and the one header in the tree whose job is exactly this — and **defined** in
|
|
`MG_Impl/Pipe/PipeFill.cpp`, the same split `MGP_NOTE_MUTATION` already has. The coupling is one forward
|
|
declaration of `BufferObject`; the probe still reports `mutation-header OK, 0 forbidden`.
|
|
|
|
### B-DEV-2 — the sticky `BindMask` is accumulated by sampling, not ORed at `glBindBuffer`
|
|
|
|
D-A3 asks for the OR *"at every `glBindBuffer` / `glBindBufferBase` / `glBindBufferRange` / VAO element-slot
|
|
bind"*. Those entry points are `MG_Impl/GLImpl/Buffer/GL_Buffer.cpp`'s (`BindBuffer_State`,
|
|
`BindBufferBase_State`, `BindBufferRange_State`), which C.5 assigns to **no package** and C.1 does not list for
|
|
this one, and hard rule (5) is "only your files". The mask is therefore accumulated by **sampling the
|
|
frontend's live binding state at every resource emission** — the only place its value is read — and ORed into
|
|
a per-slot sticky field that is never cleared. The scan is skipped unless a binding-slot version moved since
|
|
the last one (one `Uint16` load per global target, none per binding point), so a `glBufferSubData` pays a
|
|
compare and nothing else.
|
|
|
|
What this is exactly as good as the specified design for: the GL idiom the bit exists for — bind, then define
|
|
or update the store — which is what `glGenBuffers; glBindBuffer; glBufferData` is. It is sticky across
|
|
unbinds and across respecifies (both pinned by `ResourceEmit.ABindMaskBitIsStickyAcrossARespecifyThatDoesNotRebind`).
|
|
|
|
**What it cannot see, and this is handed on rather than hidden:** a bind that happens *after* the buffer's last
|
|
storage or content operation and is never followed by another one. Such a buffer would never publish that
|
|
bind. The specified design has a narrower version of the same hole (`BindMask` rides only on create and
|
|
respecify, so a bind after the last respecify is unpublished there too), but sampling widens it from "a bind
|
|
after the last respecify" to "a bind after the last resource emission of any kind". **The fix is three
|
|
one-line calls to a `MGPipeNoteBufferBoundAs(target, buffer)` in `GL_Buffer.cpp`'s three `*_State` binders,
|
|
and it belongs to whoever owns that file.** Nothing in P3a can observe the difference (the bit is read only
|
|
under split), so this is a P8 correctness item, recorded here and in `ResourceTracker.h` beside the function.
|
|
|
|
### B-DEV-3 — bit 9's shutter gains the pending base instance
|
|
|
|
D-H4 says *"Keep the shutter; wire the emission; add `BaseInstance` to the hash."* Kept literally, the design
|
|
does not work: bit 9's shutter is `MixShutter(anyVaoAttributeGeneration, vaoIdentity)`, and a draw whose only
|
|
change is its base instance moves **neither** — so the emitter is never reached, the content hash never gets
|
|
the chance to refuse suppression, and the server keeps the previous fetch shift. That is the same
|
|
silently-wrong-geometry the backend's `baseInstanceDirty` flag exists to prevent, one level further out, and
|
|
it is the under-firing direction `ARCHITECTURE.md 13.2` calls the dangerous one.
|
|
|
|
So the shutter is `MixShutter(MixShutter(anyVaoAttributeGeneration, vaoIdentity), pendingBaseInstance)`. It
|
|
over-fires only on the draws that actually carry a base instance and on the first plain draw after one — which
|
|
is exactly the set that has to re-publish. `VertexInputEmit.ABaseInstanceChangeAloneStillEmitsTheVertexBufferSet`
|
|
pins the hash half; the shutter half is what makes that half reachable.
|
|
|
|
Related: the pending value is **consumed and cleared by the validate point** after step 3, as well as by
|
|
`MGPipeLeaveVerb`. D-H2.1 names only `MGPipeLeaveVerb`, which nothing in the GL entry points calls — so on its
|
|
own it would leave a base-instanced draw's value standing for the next plain draw, which is precisely the
|
|
property `DrawParametersScenario.APlainDrawAfterABaseInstancedOneSeesZeroAgain` asserts. Both clears are
|
|
present and neither relies on the other.
|
|
|
|
### B-DEV-4 — what the widened scan actually found, and the two rows it produced
|
|
|
|
G9 says the scan root is widened "so the four `MGP_NOTE_MUTATION` sites in `TextureState.h` stop being outside
|
|
it". Widening the root alone does **not** do that: `MUTATOR_RE` matches `pGLContext->Set*` and finds nothing at
|
|
all under `MG_State/GLState` that was not already found elsewhere. So the widening also teaches the scanner to
|
|
read `MGP_NOTE_MUTATION` as a publish mechanism of its own, attributed to its **enclosing function** (a notice
|
|
carries a field name, not a mutator name). Both halves were load-bearing:
|
|
|
|
- `BumpSamplingResolutionGeneration` — a mutator with **no row at all**, because every caller of it lives in
|
|
`MG_State/GLState` (`SamplerObject::BumpVersion`, `TextureObjectBase`'s shape bump) and the scan did not
|
|
read that directory. Its sibling `BumpTextureBindGeneration` had a row. Answer: `NEW_SAMPLERS`, derived and
|
|
matching.
|
|
- `NoteUnitTouched` — which no `pGLContext->` pattern can ever see, because every texture and sampler bind
|
|
routes *through* it. Answer: `kPulledPartialShutter|NEW_SAMPLER_VIEWS`, derived and matching, because the
|
|
bind generation moves only on the `bindingChanged` arm while the high-water mark has no shutter at all.
|
|
|
|
`--check` went 73 -> 75 mutators, 8 -> 10 derived bit answers, 0 UNDECIDED, 0 COARSE. No new prose vocabulary
|
|
was minted: a `kNoteMutation` answer was drafted and dropped, because the existing `kPulledPartialShutter`
|
|
already states what is true and is *checked*, while a new prose word would have been another row no derivation
|
|
can back.
|
|
|
|
### B-DEV-5 — `TrackerTest.cpp` and the phase constant
|
|
|
|
Mapping bits 5/9/10 makes `TrackerWalk.OnlyTheFiveEmittedBitsNameASubsystem` fail, exactly as the contract
|
|
package's `PipeCatalogueTest` had to move `kMGPipeVerifiedPayloadCount` 69 -> 71 (its D2). The case now
|
|
compares against a new `kMGPipeDirtyEmittedAtP3a` (Tracker.h, beside the P2 constant, neither edited in place)
|
|
and asserts the three new arms by name. **The test name is unchanged** — G14 forbids removing one, and the
|
|
property it has always asserted ("a bit names a subsystem if and only if this build emits a call for it") is
|
|
the property it still asserts. The reason the name outlives the literal five is written into the case.
|
|
|
|
`MG_Test/Pipe/TrackerTest.cpp` is not in C.5's table (it is one of the "nobody" files), so no package can
|
|
conflict on it.
|
|
|
|
### B-DEV-6 — the sub-data splitter is a capped walk, and the cap is a parameter
|
|
|
|
D-A2 says a `false` from `MGPipeSetSubDataBufferRange` means "the emitter must split". With the record's own
|
|
bounds that instruction is **unreachable**: a second piece begins at least `2^32-1` bytes past the first, which
|
|
is already past the box's `2^31-1` offset cap. So an over-long range is *refused whole* (nothing emitted, one
|
|
log line) rather than split, and the walk's chunk cap is a parameter defaulting to the record's size bound —
|
|
because the transport segment is the tight one and is where splitting becomes live. The unit case drives the
|
|
split at a reachable cap (32 MiB) and the refusals at the record's, so the contiguity and
|
|
all-or-nothing properties P5 will rely on are pinned now rather than written under pressure later.
|
|
|
|
### B-DEV-7 — `kMGPipeResourceTargetBuffer` and the bind bits are spelled client-side
|
|
|
|
`MGPResourceDesc::Target` documents a discriminator (`Buffer | Tex1D.. | Renderbuffer | TexBuffer`) for which
|
|
the contract package minted no enum, and `BindMask` documents twelve bits with no names. Both are spelled in
|
|
`ResourceTracker.h` (`kMGPipeResourceTargetBuffer = 0`, since `Buffer` leads the documented list and is what a
|
|
zero-initialised record already says; `MGPipeBindBit` in the documented order) with a note that the integrator
|
|
moves them beside the fields when a second producer appears — P4a's texture family. **Coordination item: if
|
|
`espryt` or `wire` assumes a different value for the buffer arm of `Target`, one of the two has to move, and
|
|
the client is the cheaper side.**
|
|
|
|
### B-DEV-8 — `delete_vertex_elements` is not emitted by this package
|
|
|
|
D-G1 frees the CSO on the VAO's existing death notice, which `~VertexArrayObject` already raises and
|
|
`Managers.cpp`'s `OnFrontendStateObjectDestroyed` already consumes for the `VertexElementsCso` kind. That
|
|
consumer is `MG_Backend`'s, so the `delete_vertex_elements` emission and the slot free ride with package C's
|
|
`e1`/`e4`. C.1's emitter list agrees (it names only the three). **On this tree, VAO CSO slots are therefore
|
|
never freed** — harmless for a test binary, and closed the moment `espryt` lands. Recorded so the integrator
|
|
does not read the leak as a client defect.
|
|
|
|
### B-DEV-9 — the client's reverse-channel callbacks are installed, not just written
|
|
|
|
D-D says "the client's implementation of that callback". `MGPipeCallbacks` is owned by nobody, so the two
|
|
client-side entries (`OnBufferWriteback`, `OnGpuWritten`) are installed from `MGPipeMintResourceHandle`'s
|
|
one-shot installer and **only over a null slot** — a backend that installs its own is never overwritten. They
|
|
are unreachable until a backend calls them.
|
|
|
|
---
|
|
|
|
## 5. Verification transcript
|
|
|
|
All commands in `/home/swung/w7/p3a-client`, `CCACHE_BASEDIR=/home/swung/w7`, at `a0ac79cc` unless a row says
|
|
otherwise. Every gate below was also run after b1, b2 and b3 individually and was green at each.
|
|
|
|
**G1 — pull build symbol identity**
|
|
|
|
```
|
|
python3 scripts/symbol_report.py --before ~/w7/p3a-before-libMobileGL.so --after build-linux/libMobileGL.so \
|
|
--threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0 rc 0
|
|
symbol-report: Total 17209979 -> 17209979 (+0)
|
|
symbol-report: 27799 -> 27799 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
|
|
`.text` 10792739 -> 10792739 (+0, +0.000%)
|
|
```
|
|
|
|
Run three times — after b1, after b2 and after b4 (b3 touches no C++) — clean every time. P3a's
|
|
admitted-resize set is empty and stayed empty.
|
|
|
|
**One resize was found and fixed during b1** rather than admitted: an early edit to `SyncGpuWrites` dropped
|
|
`m_size == 0 ||` from the *pull* arm of its guard while moving the check into the push arm, which shrank the
|
|
function by 7 bytes and, through inlining, six of its callers. The gate caught it on the first run; the fix
|
|
restored the pull text verbatim. It is recorded because it is exactly the failure mode D-K predicts (an edit
|
|
that escaped a `#if MOBILEGL_PIPE_PUSH` guard) and because it is the evidence that G1 can go red for the
|
|
reason it exists.
|
|
|
|
> **THE SHARED BASELINE WAS REPLACED MID-ROUND — this needs the integrator's attention, and it is not this
|
|
> package's doing.** At the final sweep the same command reads `27811 -> 27799: 0 added, 12 removed, 1
|
|
> resized`, and `~/w7/p3a-before-libMobileGL.so` / `~/w7/p3a-before-ctest-names.txt` both have an mtime
|
|
> *later* than this package's last build. The twelve "removed" symbols are all
|
|
> `MG_Util::SelfTest::*PersistentBufferOrdering*` and the resized one is
|
|
> `SelfTest::(anonymous namespace)::kGlesDriverBugProbes` — i.e. the POST probe of `dev@9eae9858`, which is
|
|
> **not in P3a's base ref**; the replaced ctest-name file likewise carries
|
|
> `PersistentBufferOrderingProbeTest.*` (15 names, `dev@9eae9858`) and
|
|
> `LargeArenaAdoptionScenario.Respecified*` (`dev@d7655247`). So the baselines were re-taken from a tree ahead
|
|
> of `44c2b5cf`, and a comparison against them says nothing about P3a. This package touches no `MG_Util` file
|
|
> and adds no `SelfTest` symbol; its `build-linux/libMobileGL.so` is 19,100,448 bytes, byte-size-identical to
|
|
> the pull build of **every** P3a worktree including `p3a-contract`'s at the tag, while the replaced baseline
|
|
> is 19,114,360. **The integrator should re-take both baselines at `44c2b5cf` and re-run G1/G14 for every
|
|
> package**, or the gate is measuring the wrong thing for all four.
|
|
|
|
**Generators and closure**
|
|
|
|
```
|
|
python3 scripts/gen_pipe.py --check rc 0 "generated files are up to date"
|
|
71 calls, 71 verify payloads,
|
|
63 PipeInputs fields (7 sticky, 34 emitted)
|
|
git diff --exit-code -- MobileGL/MG_Pipe/generated rc 0 (clean)
|
|
python3 scripts/gen_pipe_dirty_surface.py --check rc 0 "75 mutators, all mapped, no stale rows;
|
|
45 render-state answers derived and matching;
|
|
10 other answers derived; 0 COARSE; 0 UNDECIDED"
|
|
python3 scripts/gen_pipe_dirty_surface.py --self-test rc 0 "21 negative controls, all tripped;
|
|
positive controls OK"
|
|
python3 scripts/gen_pipe_dirty_surface.py --summary rc 0 (report renders; scan roots printed)
|
|
python3 scripts/check_include_closure.py rc 0 "4 probes, 0 skipped, 0 problem(s)"
|
|
mutation-header OK 84 headers, 0 forbidden
|
|
python3 scripts/check_include_closure.py --mode both --compiler clang++ --self-test --require-all rc 0
|
|
"6 negative-control trip(s), parser checks OK"
|
|
```
|
|
|
|
(`--compiler clang++-20` does not exist on this host; the contract package recorded the same substitution.)
|
|
|
|
**Three builds** — `cmake --build <dir> --parallel 24`, rc 0 in all three (`build-linux`, `build-push`,
|
|
`build-verify`).
|
|
|
|
**Three unit runs** — `ctest --test-dir <dir> -L unit -j 12 --no-tests=error`:
|
|
|
|
```
|
|
build-linux 100% tests passed, 0 failed out of 1584
|
|
build-push 100% tests passed, 0 failed out of 1584
|
|
build-verify 100% tests passed, 0 failed out of 1584
|
|
```
|
|
|
|
**Name sets (G2's name half, G14)** — taken against the ORIGINAL baseline, before it was replaced (above).
|
|
|
|
```
|
|
ctest -N names: build-linux 2500, build-push 2500, build-verify 3328
|
|
diff <build-linux names> <build-push names> -> empty
|
|
comm -23 ~/w7/p3a-before-ctest-names.txt <build-linux names> -> empty (nothing removed)
|
|
comm -13 ... -> 18 added: the contract's 5, plus
|
|
ResourceEmit.{EveryBufferTargetSetsItsBindMaskBit,
|
|
ABindMaskBitIsStickyAcrossARespecifyThatDoesNotRebind,
|
|
ADestroyedBufferReleasesItsSlotAndAStaleHandleResolvesToNothing,
|
|
AWholeBufferSubDataBeyondTheRecordBoundIsSplitIntoContiguousRecords}
|
|
VertexInputEmit.{EveryAttributeFieldSurvivesTheWireConversion,
|
|
ABindingModelStrideOfZeroSurvivesAsZero,
|
|
IsLongAndFloat64TravelSeparately,
|
|
ABaseInstanceChangeAloneStillEmitsTheVertexBufferSet,
|
|
AnUnchangedSetWithAnUnchangedBaseInstanceEmitsNothing,
|
|
RebindingTheSameVaoEmitsABindAndNoCreate,
|
|
PingPongingBetweenTwoVaosNeverRecreatesEither}
|
|
TrackerWalk.{TheIndexBufferBitDoesNotFireOnAnUnrelatedBufferWrite,
|
|
TheIndexBufferBitFiresWhenTheSlotVersionWrapsOntoADifferentBuffer}
|
|
ctest --test-dir build-push -N -R 'VertexInputEmit\.|ResourceEmit\.' -> Total Tests: 13
|
|
```
|
|
|
|
The suites are `ResourceEmit` and `VertexInputEmit` and the new cases are plain `TEST`s with an RAII scope,
|
|
**not** `TEST_F`: a fixture files its cases under the *fixture's* name, which would put every one of them
|
|
outside `ctest -R 'VertexInputEmit\.'` and silently disarm G6 and G7. (This was caught by running the
|
|
binaries; the first draft used `TEST_F` and produced `VertexInputEmitFixture.*`.)
|
|
|
|
**G7's property, verified by hand** (the script itself is package D's): with
|
|
`wire.IsBgra = attrib.IsBgra ? 1 : 0;` deleted from `MGPipeBuildVertexAttribWire`,
|
|
`VertexInputEmit.EveryAttributeFieldSurvivesTheWireConversion` fails **naming `wire.IsBgra` / `attrib.IsBgra`**
|
|
(six occurrences, one per BGRA slot). Reverted and re-run: 8/8 pass. So G6 can go red for the reason it exists
|
|
and G7's scripted control has a target that answers by field name.
|
|
|
|
**The four integration lanes** — all green.
|
|
|
|
```
|
|
ctest --test-dir build-push -L integration-gpu -j 8 100% passed, 916 tests
|
|
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu -j 8 green (all-pull arm)
|
|
MOBILEGL_PIPE_PUSH=0x7f ctest --test-dir build-push -L integration-gpu -j 8 green (P3a subsystems off, G12)
|
|
ctest --test-dir build-verify -L integration-verify -j 4 green
|
|
```
|
|
|
|
**A flake worth recording, because a reader of the raw log would otherwise read it as a regression.** The
|
|
first `integration-gpu` run — taken while the 79-case retrace was running beside it — failed four cases, all
|
|
of the shape `TheXIsActuallyArmedWhenTheEnvironmentPinsItOn`:
|
|
`DirectGLES.UnlocatedIoBlocks.*`, `DirectVulkan.PrimGenReroute.*` and both `PointSizeDemotion.*`. Every one of
|
|
them asserts by **reading back a shared log file** whose path the lane's ctest `ENVIRONMENT` sets, and
|
|
`MG_IntegrationTest/CMakeLists.txt:1040` already records that shape as racing a neighbour's bring-up. Chased
|
|
down rather than waved off:
|
|
|
|
- re-run serially while the retrace was still running: 3 of the 4 passed, 1 (`PrimGenReroute`) still failed;
|
|
- that one, run alone: passes at the default mask, at `0x7f`, at `0x1ff`, at `0`, and in the **pull** build —
|
|
i.e. it passes with this package's emission compiled out entirely, so nothing here can be its cause;
|
|
- the whole lane re-run **alone**, with no competing load: `100% tests passed, 0 failed out of 916`.
|
|
|
|
So the four are load-induced races on shared log files, not regressions. The recorded lane result is the
|
|
quiet one.
|
|
|
|
**The retrace gate, verify-armed** — `MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree
|
|
~/w7/p3a-client --lib build-verify/libMobileGL.so --out ~/w7/retrace-out/p3a-client -j 4`:
|
|
|
|
```
|
|
passed 79 / 79; failed: []
|
|
grep -l 'Fatal{' ~/w7/retrace-out/p3a-client/*.log -> empty
|
|
grep -L 'MGPipe verify:' ~/w7/retrace-out/p3a-client/*.log -> empty (every case armed)
|
|
```
|
|
|
|
This is the strongest single result in this document: with the emission live in a verify build, whose
|
|
compare-at-read re-reads **every** field from the live context at **every** backend read, the whole corpus
|
|
replays with zero divergence and zero unmigrated reads on both backends. `~/w7/retrace-out/p3a-client` was
|
|
deleted afterwards.
|
|
|
|
**A trap the next package will hit.** This worktree's `tools/trace_replay/fixtures/*` were **Git-LFS pointers**,
|
|
not archives, so the first retrace run failed all 79 cases in 0 s with `Unrecognized archive format` — which
|
|
looks exactly like a catastrophic regression and is not one. The fix is to copy the real files from
|
|
`~/w7/pipe/tools/trace_replay/fixtures/` and `git update-index --assume-unchanged` them, which is what the
|
|
tree script normally does; `git status` is clean afterwards and the fixtures are left materialised for the
|
|
next package. (Second trap, same run: an inner script written to `/tmp` and launched with `setsid nohup`
|
|
vanishes when the WSL VM cycles — `/tmp` is tmpfs. Put the inner script under `~/w7/`.)
|
|
|
|
---
|
|
|
|
## 6. Left undone, and what it costs
|
|
|
|
1. **The three `MGPipeSetPendingBaseInstance` call sites.** D-H2.1 asks for one line immediately before
|
|
`MGP_FILL` at `MG_Impl/GLImpl/Drawing/GL_Drawing.cpp`'s `DrawElementsInstancedBaseVertexBaseInstance`,
|
|
`DrawElementsInstancedBaseInstance` and `DrawArraysInstancedBaseInstance`. That file is outside this
|
|
package's ownership (C.5: nobody; C.1: not listed), so the setter, its consumption, its shutter input, its
|
|
content-hash input and its unit coverage all landed here and **the three call sites are owed**. Until they
|
|
exist the emitted `BaseInstance` is 0 on every draw — which is what the tree does today and is therefore
|
|
behaviour-neutral, but it means package C **must not** delete `g_pendingFetchBaseInstance` before those
|
|
three lines exist, or instanced-array base-instance emulation loses its input. This is the single highest
|
|
priority follow-up in this document. The exact line is `MG_Pipe::MGPipeSetPendingBaseInstance(baseinstance);`
|
|
and it is documented beside the declaration in `MG_Impl/Pipe/PipeFill.h`.
|
|
2. **The `GL_Buffer.cpp` bind hook** (B-DEV-2): three one-line `NoteBoundAs` calls that would close the
|
|
sampling window. Invisible in monolith; a P8 correctness item.
|
|
3. **`delete_vertex_elements` and the VAO CSO slot free** (B-DEV-8): package C's, by the ownership split.
|
|
4. **`map-persistent-roundtrips` reads 0 on this tree**, necessarily: the counter is incremented at the
|
|
`MapPersistent` *emission*, and nothing registers `MGPipeResourceOps`, so the emission never happens. It
|
|
becomes non-zero the moment `espryt` registers the table, which is where G10 is scheduled anyway.
|
|
5. **The `MOBILEGL_PIPE_POISON_OMIT` caselist sweep** was declared off the critical path by the task; the
|
|
`FillPoints.def` comment now says the verdict lands with the G15 caselist run and every row stays.
|
|
|
|
---
|
|
|
|
## 7. What could NOT be verified on the contract base, and must be re-run after the rebase onto `wire`
|
|
|
|
The applier's fourteen entry points are **stubs** at `39722687`, so on this tree every call this package emits
|
|
is applied to nothing. That is not a gap in the emission — it is the ordering `ID-2` chose — but it means the
|
|
following are unproven here and are the integrator's re-run list once `wire` is merged underneath:
|
|
|
|
1. **Every assertion about an applier record.** The unit cases assert on what the *emitter built and handed
|
|
over* (its own staging buffers, at no copy, plus the four/four emission counters), never on
|
|
`MGPipeApplier()`. After the rebase, `ResourceEmit` and `VertexInputEmit` should gain the mirror-image
|
|
assertions — the stored `MGPipeResourceRecord::Desc`, `MGPipeVertexElementsRecord::Attributes[]`,
|
|
`VertexBuffers[]`, the three `Serial`s — and `VertexInputEmit.EveryAttributeFieldSurvivesTheWireConversion`
|
|
in particular becomes a *round-trip* rather than a conversion check. G6's statement is about what the
|
|
backend reads, and only the merged tree can say that.
|
|
2. **The applier's blob-bounds gate and its protocol refusal.** `EmitCreate` sends
|
|
`AttributeCount = BindingPointCount = 32` and a `Blob.Size` of exactly
|
|
`32*24 + 32*16 = 1280`; the case asserts the arithmetic, but nothing on this tree refuses a record that
|
|
disagrees. Re-run once the applier can.
|
|
3. **`kNeedsAck`'s per-record predicate on a live path.** `MGPipeResourceRespecifyNeedsAck` is pinned by
|
|
`PipeCatalogue` at `c0`; the emitter reads it only in prose (the monolith ack is `((void)0)`).
|
|
4. **The reverse channel end to end.** `MGPipeClientOnBufferWriteback` / `OnGpuWritten` are installed and
|
|
correct by inspection, and unreachable until a backend calls them. Their first real exercise is `espryt`'s
|
|
`e3`.
|
|
5. **`map-persistent-roundtrips`** — §6.4.
|
|
6. **G12's substance.** `MOBILEGL_PIPE_PUSH=0x7f` versus the default `0x1ff` is green in both arms, but on
|
|
this tree the two arms differ only in whether the *emission* happens; nothing consumes it, so the A/B
|
|
cannot yet show a behavioural difference. `ResourceSubsystemControlScenario` (package D) is what makes it
|
|
prove the switch is not dead.
|
|
7. **The `Target` discriminator value** (B-DEV-7) needs one look from `wire`/`espryt`.
|
|
8. **G1 and G14 themselves**, because the shared baselines were replaced mid-round (§5). Re-take them at
|
|
`44c2b5cf` and re-run; this package's readings against the original files are in §5.
|
|
|
|
Nothing in this list is expected to change a line of this package; they are assertions to *add* on the merged
|
|
tree, and the emitters are shaped so that adding them is a second `EXPECT` beside an existing one.
|
|
|
|
---
|
|
|
|
## 8. Intermediate logs and working state
|
|
|
|
Deleted: `~/w7/p3a-client-{lanes,retrace,laneA}.log`, their inner scripts under `~/w7/`, and
|
|
`~/w7/retrace-out/p3a-client/`. The tree-creation logs (`p3a-client-{submodule,build-linux-*,build-push-*,
|
|
build-verify-*}.log`) are the tree script's and were left alone.
|
|
|
|
`git status` in `/home/swung/w7/p3a-client` is clean at `a0ac79cc`. The trace fixtures are materialised (real
|
|
archives, not LFS pointers) and hidden with `git update-index --assume-unchanged`, which is the state the next
|
|
run of the retrace gate needs; nothing about them is committed.
|