mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-17 15:03:25 +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.
492 lines
35 KiB
Markdown
492 lines
35 KiB
Markdown
# P4a package A — `w1`..`w4`, the applier bodies. Result, v1
|
||
|
||
Branch `refs/heads/p4a/wire`, worktree `/home/swung/w7/p4a-wire`, on top of the tag
|
||
`refs/tags/p4a/contract` = `08192d72`. **Four commits, two production files and seven test
|
||
files, +3147 / −49. Not pushed. Nothing else touched.**
|
||
|
||
| commit | message (single line, empty body, no attribution) |
|
||
|---|---|
|
||
| `86835b50` | `[Feat] (Pipe): apply the framebuffer record per bound target and the texture and renderbuffer resource calls into their own slot-indexed records` |
|
||
| `bc9abfbd` | `[Feat] (Pipe): apply sampler states, sampler views and the three unit sets into the server's own working state` |
|
||
| `0f990633` | `[Feat] (Pipe): apply the shader CSO's artefacts and the default uniform block without ever re-linking on the server` |
|
||
| `3c07c8c3` | `[Test] (Pipe): pin every P4a record's lifecycle, its bounds gate and what a make-current does and does not clear` |
|
||
|
||
```
|
||
MobileGL/MG_Pipe/PipeApply.cpp | 1016 ++++++++++++++++++--
|
||
MobileGL/MG_Pipe/PipeApply.h | 46 +-
|
||
MobileGL/MG_Test/Pipe/CompositeResolverTest.cpp | 237 +++++
|
||
MobileGL/MG_Test/Pipe/FramebufferEmitTest.cpp | 249 +++++
|
||
MobileGL/MG_Test/Pipe/ImageEmitTest.cpp | 248 +++++
|
||
MobileGL/MG_Test/Pipe/ProgramEmitTest.cpp | 397 ++++++++
|
||
MobileGL/MG_Test/Pipe/ResourceEmitTest.cpp | 148 +++
|
||
MobileGL/MG_Test/Pipe/SamplerEmitTest.cpp | 444 +++++++++
|
||
MobileGL/MG_Test/Pipe/TextureEmitTest.cpp | 411 ++++++++
|
||
```
|
||
|
||
**Behaviour neutrality holds and is structural.** Nothing in this package registers a consumer
|
||
of any record: the four subsystem bits are absent from `kMGPipeWiredSubsystems`, every client
|
||
emitter beside them is still a stub, `MGPipeResourceOps` is unchanged at nine members, and no
|
||
backend reads the new state. `grep` over `MobileGL/` for the fifteen entry points returns hits
|
||
only in `MG_Pipe/PipeApply.{h,cpp}` and in `MG_Test/Pipe/*EmitTest.cpp`. The pull build is
|
||
byte-identical to `$BASE`'s (G1 0/0/0/0).
|
||
|
||
---
|
||
|
||
## 1. Verdict on the hard rules (after `3c07c8c3`; re-run unchanged after every commit)
|
||
|
||
| rule | result |
|
||
|---|---|
|
||
| **G1** `symbol_report --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` | rc 0, **0 added / 0 removed / 0 renamed / 0 resized** after each of the four commits |
|
||
| `gen_pipe.py --check` / `--self-test` | rc 0 / rc 0 (7 controls tripped) |
|
||
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | rc 0 |
|
||
| `gen_pipe_dirty_surface.py --check` / `--self-test` | rc 0 / rc 0, 27 negative controls, all tripped |
|
||
| `check_include_closure.py --mode both --compiler clang++ --self-test --require-all` | rc 0, 4 probes, 0 problems, 6 controls tripped |
|
||
| `p3a_untouched_regions.sh 37da3c3a HEAD` | rc 0, the eleven byte-identical |
|
||
| three builds compile (pull / push / verify) | all three, after every commit |
|
||
| `ctest -L unit` in all three | **1668 / 1668 in each**, 0 failed (1635 at the tag, +33) |
|
||
| ctest names pull == push | `diff` empty |
|
||
| no name removed vs `~/w7/p4a-before-ctest-names.txt` | empty; 46 added (the contract's 13 + this package's 33) |
|
||
| only A's files | yes — `MG_Pipe/PipeApply.{h,cpp}` and the seven `MG_Test/Pipe/*Test.cpp` C.7 gives A |
|
||
| four commits, exact messages, no attribution, not pushed, no other worktree | yes |
|
||
| `grep -rc 'pGLContext' MG_Backend` | only `MGPipe/PipeInputs.h:1`, pre-existing |
|
||
|
||
---
|
||
|
||
## 2. Per-entry-point behaviour: record, serial, bounds, refusal
|
||
|
||
The two verdicts are P3a's and the difference between them is the whole discipline:
|
||
|
||
* **a call naming a record this applier does not have is a DEFINED NO-OP that is COUNTED.**
|
||
One legal sequence produces it (teardown → `MGPipeApplierReleaseObjectRecords` → `~Object` →
|
||
death notices naming records already dropped), so it cannot be a wire; `MOBILEGL_ASSERT` is
|
||
inert at INFO, so it cannot be only an assertion. `RefusedResourceCalls` takes the resource
|
||
family (buffers, textures **and** renderbuffers — they are resource calls);
|
||
`RefusedObjectCalls` takes the five object families (framebuffer, sampler, sampler view,
|
||
program, texture params).
|
||
* **a record that would make the server index or allocate outside its own storage is
|
||
`Fatal{ProtocolCorruption}`** with the record's identity in the line, and it is **not**
|
||
counted as a refusal.
|
||
|
||
### 2.1 `set_framebuffer_state`
|
||
|
||
| | |
|
||
|---|---|
|
||
| storage | `DrawFramebuffer` / `ReadFramebuffer`, working state. `Target != Read` writes the draw record, `Target != Draw` writes the read record, so `Both` writes both. |
|
||
| serial | `FramebufferSerial`, one for the pair, `++` once per applied record (**a `Both` record is one record and bumps once**). |
|
||
| bounds | `Target >= MGPipeFramebufferTarget::Count` → Fatal. Every `DrawBuffers[i]` outside `[-1, kMGPipeMaxColorAttachments)` → Fatal (an index into the record's own `Color[]`). |
|
||
| refusal | **none, ever.** A framebuffer has a handle but no wire lifetime (D-I2), so there is no record to resolve; and the surfaces' `Res` handles are deliberately **not** resolved, because an attachment pins its texture through the frontend's own `SharedPtr` in monolith and a refusal here would enforce a lifetime rule monolith cannot need (D-I3). This entry point never touches `RefusedObjectCalls`. |
|
||
|
||
### 2.2 `resource_create` / `resource_respecify` / `resource_subdata` / `resource_destroy`
|
||
|
||
The four P3a entry points now **branch on the descriptor's `Target`** (on the handle's `Kind`
|
||
for the destroy, which carries no descriptor). The three tables are `Resources`,
|
||
`TextureResources`, `RenderbufferResources`; the record **type** is shared and the bound
|
||
(`kMGPipeMaxResourceSlots`) is shared, only the table is per kind.
|
||
|
||
| | |
|
||
|---|---|
|
||
| table selection | `Target == Buffer` → `Resources`; `Target == Renderbuffer` → `RenderbufferResources`; every other enumerator below `Count` → `TextureResources`; `>= Count` → Fatal. Destroy: `Kind` ∈ {Buffer, Texture, Renderbuffer}, anything else → Fatal. |
|
||
| create | starts the record over, `Gen` from the handle, `Live = true`, `Serial` stays **0**. Dispatches to `MGPipeResourceOps::Create` **only for a buffer**. |
|
||
| respecify | replaces `Desc` whole, `++Serial`, **clears `PendingUploads`** (§2.4), dispatches **only for a buffer**. |
|
||
| destroy | drops the record whole, keeps `Gen`, dispatches **only for a buffer** (the op table is the buffer family's). |
|
||
| bounds | `slot >= kMGPipeMaxResourceSlots` → Fatal naming the bound; the table is never grown by a corrupt slot. |
|
||
| refusal | `RefusedResourceCalls`, through `ResolveResourceIn`. |
|
||
|
||
### 2.3 `set_texture_params`
|
||
|
||
| | |
|
||
|---|---|
|
||
| storage | `MGPipeResourceRecord::Params` on the **texture** record, addressed by resource and independent of any binding. |
|
||
| serial | `ParamsSerial`, `++` per applied call. `Serial` (the storage serial) does **not** move — a parameter push is not a storage mutation. |
|
||
| bounds | `params.BuiltinSampler == kMGPipeNullHandle` → **Fatal** (§5, hazard H1). |
|
||
| not checked | the CSO the record names is **not resolved**: the sampler bit may legitimately be clear while the texture bit is set, so an unresolvable `BuiltinSampler` is an ordering fact, not a corrupt one. |
|
||
| refusal | `RefusedObjectCalls`. |
|
||
|
||
### 2.4 The sub-data validator, per target
|
||
|
||
`SubDataBoxFault` was **split in two** rather than widened; every statement it made is a
|
||
statement about the buffer convention and every one of them is false for a texture.
|
||
|
||
**Buffer half (`Target == kMGPipeResourceTargetBuffer`, unchanged from P3a):** offset above
|
||
`0x7FFFFFFF` → Fatal; `Level != 0` → Fatal; `RegionCount != 0` → Fatal; `Blob.Size != 0 &&
|
||
Blob.Size != MGPipeSubDataBufferSize(record)` → Fatal; then `BufferRangeFault` against
|
||
`Desc.Width`; then a non-empty write with `bytes == nullptr` → Fatal. Dispatches to
|
||
`MGPipeResourceOps::SubData` / `SubDataResident`.
|
||
|
||
**Texture half (every other `Target`):**
|
||
|
||
| rule | verdict |
|
||
|---|---|
|
||
| `Level >= kMGPipeMaxTextureLevels` (32) | Fatal |
|
||
| the union box has a negative origin, or `origin + extent > 0x7FFFFFFF` on any axis | Fatal |
|
||
| `RegionCount > kMGPipeMaxPendingUploadRegions` (256) | Fatal |
|
||
| `RegionCount != 0 && regions == nullptr` | Fatal |
|
||
| a region with a negative origin or an unencodable extent | Fatal |
|
||
| **a region not inside the union box** | Fatal |
|
||
| an empty box **and** zero regions ("no texels at all") | Fatal |
|
||
| `bytes == nullptr` | Fatal |
|
||
| more distinct `(UploadTarget, Level)` keys than `kMGPipeMaxPendingUploads` (256) | Fatal |
|
||
|
||
The region-containment rule is the one that matters: the union box **is** the union of the
|
||
regions, the server picks the upload shape from the pair, so a region outside the box means the
|
||
box misses its texels and the region writes where the box never said it would.
|
||
|
||
**Deliberately NOT checked, so a later reader does not add them back as an oversight:** (a) the
|
||
level against `Desc.Levels` — a mutable texture defines its levels one `glTexImage2D` at a
|
||
time, so the descriptor's level count is not an upper bound at every instant and a gate on it
|
||
would refuse a legal upload; (b) the box against the descriptor's extents — the record
|
||
addresses the **level's** coordinate system and a view remaps that space, so the arithmetic is
|
||
the storage owner's; (c) the blob — **no field of a texture record describes its own byte
|
||
length**, so the one Blob rule has nothing to cross-check and is inert here by construction.
|
||
|
||
**Pending-upload accumulation (D-D5).** Keyed `(UploadTarget, Level)` on the texture's record.
|
||
Boxes union; rect lists concatenate; and the moment either side says "box only", or the list
|
||
would outgrow `kMGPipeMaxPendingUploadRegions`, the entry becomes **box only** — never a
|
||
dropped region, because the box still covers every texel the dropped list named. That is the
|
||
frontend's own model one level up (`MipmapStorage` answers "0 rects" for everything it cannot
|
||
describe that way). An entry is never created empty, which is why an empty `Regions` after the
|
||
first contribution unambiguously means box-only. `++Serial` on acceptance, and the acceptance
|
||
is what the client reads before clearing its own dirty flag.
|
||
|
||
### 2.5 `create_sampler_state` / `delete_sampler_state`
|
||
|
||
| | |
|
||
|---|---|
|
||
| storage | `SamplerCsos[slot]`, `Params` by value **including `borderColorForm`**. |
|
||
| serial | a **fresh or recycled identity** starts over with `Serial = 0` (a create is not a mutation, and a fresh twin starting at 0 agrees without either side publishing); a **re-issue on a live identity** keeps the record and `++Serial`. |
|
||
| bounds | `Parameters.Size != 0 && != sizeof(SamplerParameters)` → Fatal; `parameters == nullptr` → Fatal; `slot >= kMGPipeMaxSamplerCsoSlots` → Fatal. |
|
||
| delete | drops the record whole, keeps `Gen`. **Does not sweep `BoundSamplerStates`** — that window is "the last set as received" and the client re-emits it at the next verb. |
|
||
| refusal | `RefusedObjectCalls`. |
|
||
|
||
### 2.6 `create_sampler_view` / `delete_sampler_view`
|
||
|
||
| | |
|
||
|---|---|
|
||
| storage | `SamplerViewCsos[slot]`, `View` verbatim, plus **the texture's `ViewCso` back-pointer**. |
|
||
| serial | the same fresh-vs-re-issue rule as the sampler CSO. A re-issue **does not rebind** anything. |
|
||
| bounds | `slot >= kMGPipeMaxSamplerViewSlots` → Fatal. `View.Target`, `MinLevel`/`NumLevels`/`MinLayer`/`NumLayers` are **not policed** (`MGPVertexBuffer::BindingIndex`'s precedent: the applier cannot justify that contract). |
|
||
| back-pointer | written through a **silent** `FindIn` (no refusal counted) — a view arriving before or without its texture record is legal in a mixed-bit lane. The delete clears it **only if the texture still names this view**. |
|
||
| refusal | `RefusedObjectCalls` on the delete. |
|
||
|
||
### 2.7 The three `kVarTail` unit sets
|
||
|
||
One shared body (`ApplyUnitWindow`), because they differ only in what an entry is.
|
||
|
||
| | |
|
||
|---|---|
|
||
| bounds | `Start + Count > 192` → **Fatal** (`kMGPipeMaxTextureUnits` for the two sampler sets, `kMGPipeMaxImageUnits` for the images; the two constants are equal and a case pins that). `Count != 0 && tail == nullptr` → Fatal. |
|
||
| storage | entries land at `Start + i` and **nowhere else**; `Start`/`Count` stored; **entries outside the window are not cleared** — the record is "the last set as received", and a set that names four units has said nothing about the other 188. |
|
||
| serials | `SamplerViewsSerial` / `SamplerStatesSerial` / `ShaderImagesSerial`, `++` per applied set, independently. |
|
||
| refusal | **none** — a set is working state and resolves no record. A **null handle in any tail entry is legal** everywhere (a unit the program does not resolve, a unit with no sampler object, an unbound unit) and the entry's own `Unit` field is deliberately unpoliced: the destination is `Start + i`, which the window already bounds. |
|
||
| empty set | applied, not refused, and it still moves the serial — a program with no images publishes one. |
|
||
|
||
### 2.8 `create_shader_state`, the two bindings, `bind_shader_state`, `set_global_constants`
|
||
|
||
| | |
|
||
|---|---|
|
||
| table | `MGPipeIsCompositeShaderSlot(slot)` routes to `CompositeShaderCsos[slot − base]`, bounded by the band's width; every other slot to `ShaderCsos[slot]`, bounded by **the band's base** (an ordinary program can never be handed a band slot, so a non-composite slot at or above the base is out of range by definition). A slot at or above `kMGPipeShaderCsoSlotLimit` → Fatal naming `kMGPipeMaxShaderCsoSlots`. **The server never learns a handle is a composite**; the split is two functions and nothing else branches on it. |
|
||
| create | fresh/recycled → record starts over, `Serial = 0`; re-issue on a live identity → `++Serial` **and the default uniform block is dropped** (image cleared, version back to the `~0u` sentinel, `++GlobalConstantsSerial`), because a relink replaces the layout the block was sized to. `Desc` stored; the artefacts are **not** stored (in monolith the backend reads the frontend's own archive). |
|
||
| create bounds | `link == nullptr || spirv == nullptr` → Fatal ("declares no blobs and carries no artefacts"); `GlobalUboSize > kMGPipeMaxGlobalConstantsBytes` (16 MiB) → Fatal. |
|
||
| bind / draw / dispatch | one `ProgramBindingSerial` for the three, `++` per applied call. A **null** handle is legal in all three and means "nothing bound" (and still bumps); a **dead** handle leaves the previous binding untouched and is counted. |
|
||
| delete | drops the record whole, keeps `Gen`, and **clears every one of the three bindings that named it** (unlike the unit sets: these are single handles resolved against the record just dropped), bumping `ProgramBindingSerial` only if one was actually cleared. The **second** delete — a composite's other release path — is a counted refusal and moves nothing. |
|
||
| `set_global_constants` | on the **program's** record. `Version == ~0u` → Fatal (the backends' never-uploaded sentinel); `Blob.Size != 0 && != Desc.GlobalUboSize` → Fatal; `GlobalUboSize != 0 && bytes == nullptr` → Fatal. Stores `GlobalUboSize` bytes, sets `GlobalConstantsVersion`, `++GlobalConstantsSerial`. `Serial` does not move — a block upload is not a relink. The allocation is bounded **at the create**, so this call can only ever allocate what the create already declared. |
|
||
|
||
### 2.9 `MGPipeApplierReset` / `MGPipeApplierReleaseObjectRecords`
|
||
|
||
Unchanged from the contract commit and re-pinned by four cases: the reset clears the two
|
||
framebuffer records, the three unit sets and the three program handles and **advances** all five
|
||
P4a serials; it does **not** touch texture/renderbuffer resources, sampler CSOs, sampler views
|
||
or shader CSOs — nor the `Params`, `ParamsSerial`, `ViewCso` and `PendingUploads` that ride on a
|
||
resource record. `ReleaseObjectRecords` is the only teardown scope and advances the serials
|
||
again for the same reason.
|
||
|
||
---
|
||
|
||
## 3. The verify-only codec round trip (D-H3)
|
||
|
||
`PipeApply.cpp` includes `<MG_State/GLState/ProgramState/ProgramArtifactsCodec.h>` **inside
|
||
`#if MOBILEGL_PIPE_VERIFY`** — the only place the codec is called, and the coupling the
|
||
contract header already anticipated ("the verify build is the only place the codec runs, and it
|
||
runs from `PipeApply.cpp`"). `PipeApply.h` keeps its two forward declarations and reaches no
|
||
frontend header; the include-closure gate's four probes are unaffected (none of them names
|
||
`PipeApply.*`).
|
||
|
||
`PinProgramArchiveRoundTrip(desc, link, spirv)` runs **before the record is stored**, so a lane
|
||
that aborts aborts on the record that was wrong:
|
||
|
||
1. `EncodeProgramArtifacts(link, spirv, encoded)` — empty output for a program that has
|
||
artefacts is a fault;
|
||
2. `DecodeProgramArtifacts(...)` returning false is a fault;
|
||
3. re-encoding the decoded pair and comparing the bytes — a mismatch is a fault (the codec's own
|
||
suite reads the members back explicitly; what this adds is that it runs over **every real
|
||
program the verify lane links** rather than over one hand-built instance);
|
||
4. `decodedLink.program != nullptr` is a fault — the live glslang `TProgram` is the one member
|
||
the tables omit, and a decode that reconstructed one would be carrying the compiler front end
|
||
across the boundary that exists to keep it on the client side.
|
||
|
||
The verdict is `MGP_TRIP_WIRE_REPORT` with `MGP_TRIP_WIRE_TAG("PipeVerifyDiffer")`, so a verify
|
||
or poison build writes `Fatal{PipeVerifyDiffer} program-archive create_shader_state {slot=…,
|
||
gen=…}: …` and aborts — the marker G4 greps the retrace logs for. **Zero cost in push and
|
||
pull**: the include, the function and the call site are all inside the verify guard.
|
||
|
||
Mutation **M41** (making the decode fail) is what proves the pin is live code rather than a
|
||
comment.
|
||
|
||
---
|
||
|
||
## 4. Deviations, each with its reason
|
||
|
||
**W1 — `MGPipeApplyResourceSubData` gained a trailing defaulted parameter,
|
||
`const MGPSubRegion* regions = nullptr`.** The contract's signature has no tail parameter, and
|
||
D-D5 is unimplementable without one: `ResourceSubData` has carried `kVarTail` since P2, the
|
||
applier's pending-upload set is `(UnionBox, RegionCount, Regions[])`, and the verify lane's
|
||
retain mode compares all three. The parameter is **trailing and defaulted**, so P3a's one call
|
||
site (`MG_Impl/Pipe/PipeFill.cpp:705`), every existing case and every other package compile
|
||
unchanged. **Package B must pass the tail** when it emits a texture upload; a record that
|
||
declares `RegionCount != 0` and passes no tail is refused. This is the only signature change in
|
||
the package.
|
||
|
||
**W2 — four new bounds constants in `PipeApply.h`.** `kMGPipeMaxTextureLevels = 32`,
|
||
`kMGPipeMaxPendingUploads = 256`, `kMGPipeMaxPendingUploadRegions = 256`,
|
||
`kMGPipeMaxGlobalConstantsBytes = 16 MiB`. Every one of them is a number that arrives inside a
|
||
payload and decides how much the applier allocates or how far it indexes; the slot bounds' own
|
||
argument ("never allocated by being named; a slot at or above the bound is
|
||
`Fatal{ProtocolCorruption}` and never a resize") applies to each unchanged. They are additive
|
||
and inside A's own file.
|
||
|
||
**W3 — `resource_destroy` dispatches to the backend only for a buffer**, and the same is true
|
||
of `resource_create` and `resource_respecify`. D-B1 says every non-buffer target "stores and
|
||
returns"; the destroy's guard was missing in the first draft of `w1` and
|
||
`ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` found it. The fix is
|
||
folded into `86835b50` where it belongs (the branch was rewritten before anything was pushed,
|
||
so the four-commit shape and the four exact messages are intact).
|
||
|
||
**W4 — `set_framebuffer_state` counts no refusal.** The contract's header text lists
|
||
"framebuffer" among the families `RefusedObjectCalls` covers. It cannot: D-I2 gives the
|
||
framebuffer a handle and no wire lifetime, so this call resolves no record and there is nothing
|
||
to refuse. Its only verdict is `Fatal{ProtocolCorruption}` on a malformed record. Recorded here
|
||
rather than by weakening D-I3 into a surface-handle refusal, which the brief forbids in as many
|
||
words.
|
||
|
||
**W5 — the P4a records' create/re-issue serial rule differs from
|
||
`create_vertex_elements`'s, deliberately.** P3a's vertex-elements record bumps
|
||
`ContentSerial` on *every* create including the first ("Serial 0 means never created"). The
|
||
three P4a record types follow the **contract header's** rule instead: a fresh or recycled
|
||
identity leaves `Serial` at 0 so a fresh backend twin agrees without either side publishing, and
|
||
only a re-issue on a live identity counts up. Both statements are in the tree; this package
|
||
implements the one written on the P4a records.
|
||
|
||
**W6 — a re-issued `create_shader_state` clears the default uniform block.** Not stated by the
|
||
brief either way. A relink replaces the block's layout, so an image sized to the old one is a
|
||
hazard for the consumer and the `~0u` sentinel is exactly the value that says "nothing has been
|
||
uploaded for this program". `++GlobalConstantsSerial` announces the clearing so a twin cannot
|
||
match what it uploaded before the relink.
|
||
|
||
**W7 — a respecify clears the record's `PendingUploads`.** Not stated by the brief. The pending
|
||
entries are boxes and rects in the coordinate system of a level the respecify has just
|
||
redefined; keeping one across a shrink would have Espryt upload past the end of the new store,
|
||
and nothing is lost because the frontend entry points that respecify a texture re-mark the
|
||
levels they define (`AllocateStorage` then `MarkStorageDirty`).
|
||
|
||
**W8 — `~/w7/p4a-trees2.log` never contained `REBUILT wire`, and is empty.** The rebuild
|
||
nevertheless happened and finished: `~/w7/p4a-wire-submodule.log` (11:24:24) and
|
||
`~/w7/p4a-wire-build-{linux,push,verify}-build.log` (11:24:48 / 11:25:12 / 11:25:34) each end on
|
||
the last link of a complete build (980, 991, 991 targets), no builder was still running, and a
|
||
no-op `cmake --build` over all three returned rc 0 before any edit was made. The package
|
||
proceeded on that evidence. **The summary line the orchestration script was to append is the
|
||
thing that is missing, not the work** — worth knowing before the next package waits on it.
|
||
Those four logs were deleted with the round's own (ID-5); the timestamps and byte counts above
|
||
are the record.
|
||
|
||
---
|
||
|
||
## 5. What B, C, D, E and F must know
|
||
|
||
**H1 — `MGPTextureParams::BuiltinSampler` may never be null, and bit 10 can be set while bit 11
|
||
is clear.** The contract makes a null built-in sampler `Fatal{ProtocolCorruption}` and this
|
||
package implements it. But D-K2's dependency table has **no** "bit 10 requires bit 11", and
|
||
says the mirror pair is fine — so a `MOBILEGL_PIPE_PUSH=0x5ff` lane (texture resources on,
|
||
samplers off) would emit `set_texture_params` while the sampler CSO family is switched off. If
|
||
B/C mint the built-in sampler's handle only from the sampler emitter, that lane aborts on the
|
||
first `glTexParameter`. **Either** the handle is minted whenever the texture family emits
|
||
(the allocator, not the CSO cache, is what mints it), **or** the integrator adds "bit 10
|
||
requires bit 11" to D-K2. This is the one cross-package hazard the package found and cannot fix
|
||
from inside `MG_Pipe`.
|
||
|
||
**Blob size rules, exactly.**
|
||
|
||
| record | rule |
|
||
|---|---|
|
||
| `MGPSubData` (buffer) | `Blob.Size` is 0, or exactly `MGPipeSubDataBufferSize(record)`. Anything else is Fatal. |
|
||
| `MGPSubData` (texture) | **inert.** No field describes the blob's byte length, so any value is accepted; the destination is bounded by the box and the regions. Leave it 0. |
|
||
| `MGPSamplerDesc::Parameters` | 0, or exactly `sizeof(SamplerParameters)` (100). Anything else is Fatal. The value itself travels through the companion pointer, which may never be null. |
|
||
| `MGPProgramDesc::Spirv[6]` + `Reflection` | **inert**, all seven. Nothing in the descriptor describes their lengths. Leave them 0 and pass the two artefact pointers; **both** non-null or the record is Fatal. |
|
||
| `MGPGlobalConstants::Blob` | 0, or exactly the program's `Desc.GlobalUboSize` as the create declared it. Anything else is Fatal. |
|
||
|
||
**Unit-set window semantics, exactly.** `Start + Count <= 192` or Fatal. Entries land at
|
||
`Start + i`; **entries outside the window are never cleared**, so an emitter that wants a unit
|
||
unbound must include it in the window carrying a null handle. `Count == 0` is legal and still
|
||
moves the serial. A null handle in any entry is legal. The entry's own `Unit` field is stored
|
||
verbatim and never compared against `Start + i` — if the emitter lets the two disagree, nothing
|
||
here will say so.
|
||
|
||
**Serial semantics for D and E.** All five P4a working serials (`FramebufferSerial`,
|
||
`SamplerViewsSerial`, `SamplerStatesSerial`, `ShaderImagesSerial`, `ProgramBindingSerial`) are
|
||
`MGGen`-class: they **only ever advance**, including across `MGPipeApplierReset` and
|
||
`MGPipeApplierReleaseObjectRecords`, so no value can ever recur and a twin may safely memoise
|
||
one. The per-record serials (`Serial`, `ParamsSerial`, `GlobalConstantsSerial`) restart with the
|
||
record, which is safe because the handle's `Gen` moves with it. **Every serial moves before
|
||
anything downstream is told.**
|
||
|
||
**What D reads, per kind.** `TextureResources[slot]` / `RenderbufferResources[slot]` for the
|
||
descriptor, the parameters (`Params` + `ParamsSerial`), the view handle (`ViewCso`) and the
|
||
pending uploads; `SamplerCsos[slot].Params`; `SamplerViewCsos[slot].View`;
|
||
`ShaderCsos[slot]` **or** `CompositeShaderCsos[slot − kMGPipeShaderCsoCompositeSlotBase]` — a
|
||
consumer that resolves a `ShaderCso` handle must use the same band split the applier does, and
|
||
`MGPipeIsCompositeShaderSlot` is the one predicate for it. **Espryt consumes and clears a
|
||
`PendingUploads` entry only where it actually uploads**; a bail must leave it intact, which is
|
||
the whole point of the set being server-side.
|
||
|
||
**For F.** The package adds **33** ctest names — `ResourceEmit.` +3, `FramebufferEmit.` +4,
|
||
`TextureEmit.` +6, `SamplerEmit.` +7, `ImageEmit.` +4, `ProgramEmit.` +6,
|
||
`CompositeResolver.` +3 — for 46 added against `~/w7/p4a-before-ctest-names.txt` in total (the
|
||
contract's 13 plus these 33). None is removed and every one of them is a visible SKIP in a pull
|
||
build, so `ctest -N` stays name-for-name identical between the pull and push trees.
|
||
The six suites' `main()` points `MOBILEGL_LOG_FILE_PATH` at a per-pid temp file, because the
|
||
refusal cases read the trip wire's line back out of it.
|
||
|
||
---
|
||
|
||
## 6. Verification transcript (on `3c07c8c3`, working tree clean)
|
||
|
||
```
|
||
$ python3 scripts/symbol_report.py --before ~/w7/p4a-before-libMobileGL.so \
|
||
--after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change \
|
||
--fail-on-added-bytes 0
|
||
### Removed (0) _none_ ### Added (0) _none_
|
||
### Resized (0) _none_ ### Renamed only (same size) (0) _none_ rc=0
|
||
|
||
$ python3 scripts/gen_pipe.py --check
|
||
gen_pipe: inventory 477 rows: ... 0 UNMAPPED
|
||
gen_pipe: generated files are up to date rc=0
|
||
$ python3 scripts/gen_pipe.py --self-test
|
||
gen_pipe: self-test: 7 negative-control trip(s), positive control OK rc=0
|
||
$ git diff --exit-code -- MobileGL/MG_Pipe/generated rc=0
|
||
|
||
$ python3 scripts/gen_pipe_dirty_surface.py --check rc=0
|
||
$ python3 scripts/gen_pipe_dirty_surface.py --self-test
|
||
dirty-surface self-test: 27 negative controls, all tripped rc=0
|
||
|
||
$ python3 scripts/check_include_closure.py --mode both --compiler clang++ \
|
||
--self-test --require-all
|
||
include-closure: self-test: 6 negative-control trip(s), parser checks OK
|
||
include-closure: 4 probes, 0 skipped, 0 problem(s) rc=0
|
||
|
||
$ bash scripts/p3a_untouched_regions.sh 37da3c3a HEAD
|
||
[p3a-untouched] the 11 ... functions are byte-identical rc=0
|
||
|
||
$ cmake --build build-linux -j 12 ok
|
||
$ cmake --build build-push -j 12 ok
|
||
$ cmake --build build-verify -j 12 ok
|
||
$ ctest --test-dir build-linux -L unit -j 12 100% 1668/1668, 0 failed
|
||
$ ctest --test-dir build-push -L unit -j 12 100% 1668/1668, 0 failed
|
||
$ ctest --test-dir build-verify -L unit -j 12 100% 1668/1668, 0 failed
|
||
|
||
$ diff <(build-linux names) <(build-push names) (empty)
|
||
$ comm -23 ~/w7/p4a-before-ctest-names.txt <(build-linux names) (empty)
|
||
$ comm -13 ~/w7/p4a-before-ctest-names.txt <(build-linux names) 46 added
|
||
$ grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$'
|
||
MobileGL/MG_Backend/MGPipe/PipeInputs.h:1 # pre-existing, unchanged
|
||
```
|
||
|
||
Two failures were found during the round and both were the gates doing their job:
|
||
`ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` (deviation W3, a real
|
||
defect in `w1`'s first draft) and one flake of `LogLevel.ProductionBuildKeepsErrorAndWarn` under
|
||
`-j 12` (green on re-run and on every subsequent full run; a pre-existing shared-temp-file race
|
||
in a suite this package does not touch).
|
||
|
||
---
|
||
|
||
## 7. Mutation evidence
|
||
|
||
**41 mutations, 41 red, measured.** Each was applied to `MobileGL/MG_Pipe/PipeApply.cpp` in
|
||
this worktree, the tree rebuilt, the family's suite run, and the file restored from the commit
|
||
(the working tree was verified clean before and after; no other worktree was created). The rule
|
||
the brief asks for — *for each entry point a case that fails if its body is deleted* — is
|
||
therefore measured rather than claimed.
|
||
|
||
| # | mutation | first case to go red |
|
||
|---|---|---|
|
||
| M1 | `set_framebuffer_state`: the draw store removed | `FramebufferEmit.ADrawRecordAndAReadRecordAreKeptApartAndBothWritesBoth` |
|
||
| M2 | `set_framebuffer_state`: the read store removed | the same |
|
||
| M3 | `set_framebuffer_state`: the serial bump removed | the same |
|
||
| M4 | `set_framebuffer_state`: the target gate removed | `FramebufferEmit.ATargetOutsideTheThreeBindingsIsRefusedNamingTheRecord` |
|
||
| M5 | `set_framebuffer_state`: the draw-buffer gate removed | `FramebufferEmit.ADrawBufferEntryOutsideTheRecordsOwnArrayIsRefusedRatherThanRead` |
|
||
| M6 | `resource_create`: every target routed to the buffer table | `ResourceEmit.TheThreeResourceKindsKeepTheirOwnSlotSpaceAndDoNotSeeEachOther` |
|
||
| M7 | `resource_destroy`: every kind routed to the buffer table | the same |
|
||
| M8 | `resource_destroy`: the texture dispatch guard removed | `ResourceEmit.NoTextureOrRenderbufferResourceCallReachesTheBackendOpTable` |
|
||
| M9 | `set_texture_params`: the store removed | `TextureEmit.ATexturesParametersLandOnItsOwnRecordAndMoveOnlyTheirOwnSerial` |
|
||
| M10 | `set_texture_params`: the serial bump removed | the same |
|
||
| M11 | `set_texture_params`: the null-sampler gate removed | `TextureEmit.ARecordWithNoBuiltinSamplerCsoIsRefusedNamingTheTexture` |
|
||
| M12 | `set_texture_params`: the resolver replaced by a silent find (the refusal stops being counted) | `TextureEmit.ATexturesParametersLandOnItsOwnRecordAndMoveOnlyTheirOwnSerial` |
|
||
| M13 | sub-data: the region-containment gate removed | `TextureEmit.TheSubDataValidatorRefusesALevelABoxAndARegionTheRecordCannotDescribe` |
|
||
| M14 | sub-data: the level bound removed | the same |
|
||
| M15 | sub-data: the encodable-box gate removed | the same |
|
||
| M16 | sub-data: the missing-tail gate removed | the same (**SegFault**, §7.1) |
|
||
| M17 | pending uploads: the box union removed | `TextureEmit.AnAccumulatedUploadUnionsItsBoxesAndCollapsesToTheBoxWhenARectListCannotDescribeIt` |
|
||
| M18 | pending uploads: the box-only collapse removed | the same |
|
||
| M19 | pending uploads: the accumulation removed | the same |
|
||
| M20 | respecify: the pending-upload clear removed | `TextureEmit.ARespecifyDropsThePendingUploadsAgainstTheStorageItReplaces` |
|
||
| M21 | `create_sampler_state`: the parameter store removed | `SamplerEmit.ACreateStoresTheParametersByValueAndAReissueOnALiveIdentityCountsUp` |
|
||
| M22 | `create_sampler_state`: the re-issue serial bump removed | the same |
|
||
| M23 | `create_sampler_state`: the blob-length gate removed | `SamplerEmit.ARecordThatDoesNotDescribeItsOwnParametersIsRefusedNamingTheLength` |
|
||
| M24 | `delete_sampler_state`: the record drop removed | `SamplerEmit.ADeleteDropsTheRecordAndAStaleNoticeIsCountedRatherThanSilentlyDropped` |
|
||
| M25 | `create_sampler_view`: the back-pointer write removed | `SamplerEmit.AViewIsReissuedOnTheSameHandleAndKeepsItsTexturesBackPointerInStep` |
|
||
| M26 | `delete_sampler_view`: the back-pointer clear removed | the same |
|
||
| M27 | the unit sets: the entry copy loop removed | `SamplerEmit.TheTwoUnitSetsLandInTheirWindowAndLeaveEverythingOutsideItAlone` |
|
||
| M28 | the unit sets: the window gate removed | `SamplerEmit.AUnitWindowPastTheMergedUnitSpaceIsRefusedRatherThanTruncated` |
|
||
| M29 | `set_sampler_views`: the serial bump removed | `SamplerEmit.TheTwoUnitSetsLandInTheirWindowAndLeaveEverythingOutsideItAlone` |
|
||
| M30 | `set_shader_images`: the serial bump removed | `ImageEmit.TheImageSetLandsInItsWindowWithEveryFieldTheShaderWasBuiltAgainst` |
|
||
| M31 | `create_shader_state`: the descriptor store removed | `ProgramEmit.ACreateStoresTheDescriptorAndARelinkCountsUpAndDropsTheBlockKeyedToTheOldLayout` |
|
||
| M32 | `create_shader_state`: the relink block clear removed | the same |
|
||
| M33 | `create_shader_state`: the artefact gate removed | `ProgramEmit.ACreateWithNoArtefactsAnOversizedBlockOrACorruptSlotIsRefusedNamingTheProgram` |
|
||
| M34 | `bind_shader_state`: the store removed | `ProgramEmit.TheThreeBindingsFollowTheirOwnHandleAndADeadOneLeavesThePreviousBindingStanding` |
|
||
| M35 | `set_draw_program`: the store removed | the same |
|
||
| M36 | `set_dispatch_program`: the store removed | the same |
|
||
| M37 | `delete_shader_state`: the binding sweep removed | `ProgramEmit.ADeleteDropsTheRecordAndClearsEveryBindingThatNamedIt` |
|
||
| M38 | `set_global_constants`: the image store removed | `ProgramEmit.ACreateStoresTheDescriptorAndARelinkCountsUpAndDropsTheBlockKeyedToTheOldLayout` |
|
||
| M39 | `set_global_constants`: the sentinel gate removed | `ProgramEmit.TheDefaultUniformBlockLandsOnTheProgramsRecordAndTheSentinelIsRefused` |
|
||
| M40 | the composite band routed into the ordinary table | `CompositeResolver.ACompositeRecordLandsInTheBandsOwnTableAndNeverGrowsTheOrdinaryOne` |
|
||
| M41 | **verify build**: the archive decode made to fail | three `ProgramEmit.*` cases, `Subprocess aborted` |
|
||
|
||
M1-M40 ran in `build-push`; **M41 ran in `build-verify`**, and it is the one that proves the
|
||
codec round trip is live code with a gate rather than a comment: with the decode failing, every
|
||
`ProgramEmit` case that creates a shader state dies on `Fatal{PipeVerifyDiffer}`.
|
||
|
||
### 7.1 A note on reading a mutation harness
|
||
|
||
Two of the forty-one (M16 and M41) kill the test **process** rather than failing an assertion —
|
||
M16 dereferences the tail it no longer refuses, M41 aborts inside the verify trip wire — so
|
||
`ctest` reports `***Exception: SegFault` and `Subprocess aborted` instead of `(Failed)`. A
|
||
harness that greps for `(Failed)` reads both as SURVIVED. They were re-run with the exit code as
|
||
the verdict (`rc=8` in both cases) and are red. **Worth knowing for anyone repeating this:
|
||
grepping ctest output for `(Failed)` silently under-reports exactly the mutations that matter
|
||
most.**
|
||
|
||
---
|
||
|
||
## 8. Left undone, and who owns it
|
||
|
||
- **Every emitter body** and the four `kMGPipeWired*Subsystem` constants — B and C, in their own
|
||
headers. Nothing consumes a record until they land.
|
||
- **`CompositeResolver.h`** — still not created; wholly C's. This package's
|
||
`CompositeResolverTest` cases are the applier's half of the band and are disjoint from C's.
|
||
- **`Resolve<Family>SubsystemArm()`**, D-C3's `MaxColorAttachments > 8` refusal, and the D-K2
|
||
dependency refusals — backend-side, package D. **H1 above is an input to that work.**
|
||
- **The five `MGPipeUnmigratedEmulation` call sites** — D and E.
|
||
- **`p4a_untouched_regions.sh`**, `p4a_descriptor_negative_control.sh`, the itest phase-mask
|
||
moves and `MagmaPipeArms.h` — package F.
|
||
- **The retain-mode comparison of the emitted `(UnionBox, RegionCount, Regions[])`** against the
|
||
tracker's pre-clear set (part of G4): the applier's half exists — the pending set is
|
||
accumulated and never recomputed — and the tracker's half is the client packages'.
|