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.
218 lines
15 KiB
Markdown
218 lines
15 KiB
Markdown
# contract v7 — c0g: D-K2's dependency table, on the client (S-3 / ID-41)
|
|
|
|
**Commit `29bd4d2c`** on `p4a/c0f`, worktree `~/w7/p4a-c0f`, rebased onto
|
|
`refs/heads/feat/disaggregated` = `588b2277` (contract c0..c0f + wire + clientsp v3 + clientfb v2
|
|
+ esprytobj v2/v3). One commit, four files, +392/-46. Not pushed.
|
|
|
|
```
|
|
[Fix, Test] (MG_Impl, Pipe): gate the four P4a families on D-K2's dependency bits as well -
|
|
Espryt refuses bit 10 without bit 11 or bit 7, but the client had already emitted and the
|
|
acceptance-cleared level flags left its legacy arm nothing to upload
|
|
```
|
|
|
|
---
|
|
|
|
## 1. The defect (S-3), restated from the code
|
|
|
|
Espryt's four `Resolve<Family>SubsystemArm()` functions (`Managers.cpp:3595` / `:3642` / `:3698` /
|
|
`:3735`) REFUSE a family whose D-K2 dependency bit is clear and run the legacy arm instead — the
|
|
shape `ResolveVertexInputSubsystemArm`'s bit-8-requires-bit-7 refusal set as the precedent, and the
|
|
one ID-15 extended with the fourth row.
|
|
|
|
That refusal is a **backstop** and it cannot restore a correct picture on its own, because the
|
|
client's emission was gated on the operator's mask **alone**: at `0x7ff` (bit 10 set, bit 11 clear)
|
|
the client emitted the whole texture family, the applier accepted it, the emitter cleared each
|
|
level's per-level dirty flag on that acceptance (D-D5 as amended by ID-18 M3) — and *then* the
|
|
server refused bit 10 and ran a legacy path with nothing left to upload. **438/491** on the
|
|
DirectGLES lane, the same 47 texture-upload failures ID-39 saw on Magma for the consumer-less
|
|
version of the identical mistake (c0f).
|
|
|
|
This is c0f's rule one signal over, so it is written with c0f's rule: with a dependency unmet the
|
|
client emits **NOTHING** for that family and the legacy pull path runs untouched — *nothing at all,
|
|
not less*.
|
|
|
|
---
|
|
|
|
## 2. The dependency table, as coded
|
|
|
|
`MobileGL/MG_Impl/Pipe/PipeFill.cpp:950-1055`, immediately under `kMGPipeP4aFamilySubsystems` and
|
|
`P4aFamilyHasItsConsumer()`, in the same anonymous namespace, with the D-K2 reasons as comments:
|
|
|
|
```cpp
|
|
struct P4aFamilyDependencyRow {
|
|
Uint64 Family; // exactly one bit, and it is one of kMGPipeP4aFamilySubsystems
|
|
Uint64 Requires; // the bits MOBILEGL_PIPE_PUSH must ALSO carry for it to be live
|
|
};
|
|
|
|
inline constexpr P4aFamilyDependencyRow kMGPipeP4aFamilyDependencies[] = {
|
|
{kMGPipeSubsystemFramebuffer, kMGPipeSubsystemTextureResources},
|
|
{kMGPipeSubsystemTextureResources, kMGPipeSubsystemResources | kMGPipeSubsystemSamplers},
|
|
{kMGPipeSubsystemSamplers, kMGPipeSubsystemTextureResources},
|
|
{kMGPipeSubsystemPrograms, 0},
|
|
};
|
|
```
|
|
|
|
| family | requires | why (the comment on the row) |
|
|
|---|---|---|
|
|
| bit 9 framebuffer | bit 10 | every `MGPSurface::Res` names a Texture or Renderbuffer handle and only bit 10 populates those two slot tables (`ResolveFramebufferSubsystemArm`) |
|
|
| bit 10 textures | bit 7 **and** bit 11 | a buffer texture's `MGPResourceDesc::BufferForTexBuffer` names a Buffer handle and only bit 7 puts twins in the resource slot table (D-D1); and `MGPTextureParams::BuiltinSampler` is a `SamplerCso` HANDLE, only bit 11 mints sampler CSOs, and the applier's verdict for a null one is `Fatal{ProtocolCorruption}` (D-K2's FOURTH row, ID-14/ID-15) |
|
|
| bit 11 samplers | bit 10 | every `MGPBoundView::Texture` and `MGPImageView::Res` names a Texture handle and only bit 10 populates that slot table (`ResolveSamplerSubsystemArm`); with the row above this is SYMMETRIC — bits 10 and 11 are one arm with two switches |
|
|
| bit 12 programs | — | a `ShaderCso` handle names no texture and no buffer. The empty row is written out so the table covers the four families exhaustively rather than by absence |
|
|
|
|
**The mirror pairs that stay fine**, stated in the code beside the table (Managers.cpp:2377-2381's
|
|
own argument: an unreachable branch that says something different is how the reachable one drifts):
|
|
|
|
- bit 10 set, bit 9 clear — FINE; the legacy FBO sync reaches the texture twin through
|
|
`SyncTextureObjectToBackend`, which dispatches to the handle arm by itself;
|
|
- bit 11 set, bit 9 clear — FINE, for the same reason: a sampler view names a texture, never a
|
|
framebuffer;
|
|
- bit 7 set, bit 10 clear — FINE, and it is P3a's shipped configuration;
|
|
- bit 12 with any or none of 9/10/11 — FINE, per the last row;
|
|
- bit 10 set, bit 11 clear (and its mirror) — **NOT** fine; it is the row above, and it is the one
|
|
sentence in the brief that P4a as built withdrew.
|
|
|
|
**The rows are NON-TRANSITIVE, on purpose.** Espryt's resolvers classify their arms from
|
|
`MOBILEGL_PIPE_PUSH` alone, so the table asks the question they ask — *is the dependency BIT set* —
|
|
and never *is the other family live*. At `0x7ff` that means the framebuffer family stays LIVE on
|
|
both sides while the texture family is dead on both sides, which is the state the two must agree
|
|
on; a client that withheld more than the server refuses would leave the server's handle arm live
|
|
with no records to read, and a client that withheld less is the defect above. The `0x7ff` arm below
|
|
confirms the choice empirically (485/491, no framebuffer-shaped fallout).
|
|
|
|
**Five `static_assert`s pin the table** rather than leaving it to a reader: every P4a family has a
|
|
row (coverage `==` `kMGPipeP4aFamilySubsystems`), each of the four rows' required mask is spelled
|
|
out again by name, no row may name its own family, and `kMGPipeSubsystemsMigratedAtP4a` (0x1fff)
|
|
must satisfy every dependency the table declares — so the shipped arm cannot be narrowed by any of
|
|
this, and the table can only ever narrow a hand-picked A/B mask.
|
|
|
|
The predicate consulted at the four sites:
|
|
|
|
```cpp
|
|
Bool P4aFamilyDependenciesAreSet(Uint64 subsystem, Uint64 pushMask) {
|
|
const Uint64 required = P4aFamilyDependencyBits(subsystem); // the table, folded
|
|
return (pushMask & required) == required;
|
|
}
|
|
```
|
|
|
|
The mask is a parameter, not a read, so the walk's single read of `MG_Config::Features.PipePush`
|
|
stays the one read a whole validate point resolves against.
|
|
|
|
---
|
|
|
|
## 3. The sites — the same four c0f joined
|
|
|
|
| file:line | site | what |
|
|
|---|---|---|
|
|
| `PipeFill.cpp:1068` | `FamilyIsLive(subsystem, wired)` | the fourth conjunct. This is the predicate every P4a birth hook resolves through (nine hooks, :1253-1304) |
|
|
| `PipeFill.cpp:2399` | `wants()` in the walk | a sixth condition beside c0f's fifth; the seven walk-side emissions are inert |
|
|
| `PipeFill.cpp:2474` | the `DrainTextureSubData` gate | the one with no dirty bit over it — **the path whose acceptance clears the level flags**, i.e. where S-3 actually bit |
|
|
| `PipeFill.cpp:2555` | the residual fill's `supplied` conjunction | "supplied" means a call went out carrying this field; at a mask with a dependency clear none did, so withholding the pull would leave the field unfilled at the verb that reads it |
|
|
| `PipeFill.h:46-71` | `MGPipeP4aFamilyEmits(subsystem, wired)` | the exported observable's contract, widened from three conjuncts to four; it still returns `FamilyIsLive` itself (`PipeFill.cpp:1232`), never a second copy |
|
|
|
|
Bits 7 and 8's existing rules are untouched — read only.
|
|
|
|
---
|
|
|
|
## 4. Tests (`MG_Test/Pipe/TextureEmitTest.cpp`, beside the c0f case)
|
|
|
|
| test | what it pins |
|
|
|---|---|
|
|
| `TextureEmit.WithTheSamplerBitClearTheTextureFamilyGateIsFalseAndNothingReachesTheApplier` | the **0x7ff shape** end to end: bit 10 set, bit 11 clear → gate false; the handle is still minted (the mint stays unconditional) but not published; `CreateCount`/`RespecifyCount` 0, `TextureResources` empty, `DrainListSize` 0, `SubDataCount` 0 after an explicit drain, **`IsStorageDirty` still true**, and `RefusedNoConsumer == 0` (the *gate*, not c0f's belt, is what stopped it). Second half: with bit 11 back, the same sequence lands and the flag clears |
|
|
| `TextureEmit.WithTheBufferResourceBitClearTheTextureFamilyGateIsFalseAndNothingReachesTheApplier` | the D-D1 half of the same row: bit 10 set, bit 7 clear, identical assertions |
|
|
| `TextureEmit.EveryDKTwoDependencyRowGatesItsOwnFamilyAndTheMirrorPairsStayLive` | the table itself, one row per family, through `MGPipeP4aFamilyEmits`: all four live when every dependency is met; bit 9 and bit 11 both false without bit 10; bit 10 false without bit 11 **while bit 9 stays true at that same mask** (the non-transitivity, asserted rather than assumed); bit 10 false without bit 7 while bit 11 stays true; bit 12 live entirely on its own; the mirror pairs (10+11 without 9 = the 0xdff arm; bit 7 alone) ; and `kMGPipeSubsystemVertexInput` still true with bit 7 clear — P2/P3a's rules are not narrowed |
|
|
|
|
All three names were added to the pull-build skip list `MGL_TEXTURE_EMIT_CLIENT_TEST_LIST` at the
|
|
top of the file, and **both builds compile** (ID-40's lesson): `ctest -N` gives 2732 names in
|
|
`build-linux` and 2732 in `build-push`, diff 0.
|
|
|
|
**Two fixtures had to arm bit 7**, and this is the one thing outside `PipeFill.*` the commit
|
|
touches. `TextureScope` (`TextureEmitTest.cpp`) armed bits 10|11 and `FramebufferScope`
|
|
(`FramebufferEmitTest.cpp`) armed bits 9|10|11 — both were arming a mask D-K2 forbids, which the
|
|
server would have refused and which the client now refuses too, so without bit 7 every case in both
|
|
suites would have gone green for the wrong reason (an emitter that emits nothing). Both now arm
|
|
`kMGPipeSubsystemResources` as well, with the row quoted in the comment. Neither file constructs a
|
|
`BufferObject`, so bit 7 changes nothing else in either suite (both suites: 37/37 and 22/22).
|
|
|
|
### Mutations (run, not committed)
|
|
|
|
| # | mutation | result |
|
|
|---|---|---|
|
|
| M1 | `FamilyIsLive` drops `&& P4aFamilyDependenciesAreSet(subsystem, pushMask)` | `TextureEmit` **3 failed of 37** — exactly the three new cases (`WithTheSamplerBitClear…`, `WithTheBufferResourceBitClear…`, `EveryDKTwoDependencyRow…`). Reverted: 37/37 |
|
|
| M2 | the texture row drops `kMGPipeSubsystemResources` (bit 7) | **does not compile**: `PipeFill.cpp:1020: static assertion failed … P4aFamilyDependencyBits(kMGPipeSubsystemTextureResources) == (kMGPipeSubsystemResources \| kMGPipeSubsystemSamplers)`. The row-by-row `static_assert`s are load-bearing, not decoration. Reverted, build rc 0 |
|
|
|
|
---
|
|
|
|
## 5. Gate numbers (all on `~/w7/p4a-c0f` @ `29bd4d2c`)
|
|
|
|
| gate | result |
|
|
|---|---|
|
|
| builds | `build-linux` rc 0, `build-push` rc 0 (**both compile** — ID-40's lesson) |
|
|
| **G1 `symbol_report --threshold 0`** vs `~/w7/p4a-before-libMobileGL.so` | **0 added / 0 removed / 0 resized / 0 renamed**; `.text 10806323 -> 10806323 (+0, +0.000%)`; `.data`/`.bss`/`.rodata` all +0; 27811 -> 27811 defined symbols |
|
|
| **G5 `scripts/p3a_untouched_regions.sh 37da3c3a HEAD`** | **rc 0** — "the 11 pool / deferred-release / ring / flush-drain functions are byte-identical between 37da3c3a and HEAD" |
|
|
| `scripts/gen_pipe.py --check` | rc 0 — inventory 477 rows, 0 UNMAPPED, "generated files are up to date" |
|
|
| `scripts/gen_pipe_dirty_surface.py --check` | rc 0 |
|
|
| `scripts/gen_pipe_dirty_surface.py --self-test` | rc 0 — 27 negative controls, all tripped |
|
|
| `scripts/check_include_closure.py --compiler clang++` | rc 0 — 4 probes, 0 skipped, 0 problems |
|
|
| **`ctest -L unit` build-linux** | **100%, 0 failed of 1766** |
|
|
| **`ctest -L unit` build-push** | **100%, 0 failed of 1766** |
|
|
| **G2 `ctest -N` pull vs push** | pull 2732, push 2732, **diff 0 lines** |
|
|
| G14 vs `~/w7/p4a-before-ctest-names.txt` | 0 removed, 144 added (+3 over the tree this branched from) |
|
|
|
|
---
|
|
|
|
## 6. The arms
|
|
|
|
Every DirectGLES arm is `ctest --test-dir build-push -L integration-gpu -R DirectGLES -j 8` with
|
|
`MOBILEGL_PIPE_PUSH` set as shown.
|
|
|
|
| arm | before c0g | **after c0g** | classification |
|
|
|---|---|---|---|
|
|
| `0x7ff` (bit 10 set, bit 11 clear — S-3's own mask) | **438/491** | **485/491** | the six pinned `.Handles` aborts only |
|
|
| `0x1fff` (the P4a default) | 485/491 | **485/491** | the same six |
|
|
| `0x3ff` (bit 9 set, 10/11/12 clear) | — | **485/491** | the same six |
|
|
| `0x5ff` (bit 10 set, 9/11 clear — ID-15's arm) | — | **485/491** | the same six |
|
|
| `0x9ff` (bit 11 set, bit 10 clear — G12's pair) | — | **485/491** | the same six |
|
|
| `0xdff` (bits 10+11 set, bit 9 clear — the mirror pair) | — | **485/491** | the same six |
|
|
| **DirectVulkan**, default mask | 475/475 | **475/475** | **0 failed** |
|
|
|
|
The failing set is **byte-for-byte identical across all six DirectGLES arms** (same six names, same
|
|
md5 of the sorted list, count 6 every time):
|
|
|
|
```
|
|
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexInput
|
|
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexBufferSet
|
|
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.ABufferAtARecycledAddressDoesNotInheritItsPredecessorsContents
|
|
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.ATextureAtARecycledAddressDoesNotInheritItsPredecessorsTwin
|
|
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.AFramebufferAtARecycledAddressDoesNotInheritItsPredecessorsTwin
|
|
DirectGLES.HandleRecycle.Handles.HandleRecycleScenario.DestroyedVertexArraysReturnTheirVertexElementsSlots
|
|
```
|
|
|
|
all `Subprocess aborted`, all `Fatal{PipeLegacyMemosDisabled}` — the **0x1ff itest pins, package
|
|
F's**, closed by F's pin move. **Nothing else fails at any arm**, on either backend.
|
|
|
|
Note the two DirectGLES sampler-seam failures of ID-39 are gone at every arm here: that is D's S-1
|
|
fix, already on `588b2277`, not c0g.
|
|
|
|
---
|
|
|
|
## 7. What the other packages must know
|
|
|
|
- **The client and the server now say the same thing about a mask.** Espryt's four
|
|
`Resolve<Family>SubsystemArm()` functions are unchanged and remain the backstop; the client's
|
|
table is their mirror, bit for bit and non-transitively. If a row is ever added or changed on one
|
|
side it must be changed on the other, and `PipeFill.cpp`'s `static_assert`s name each row so the
|
|
change cannot be silent.
|
|
- **F**: the `0x5ff` dependency-refusal scenario still asserts the refusal *line* and the legacy
|
|
arm running, and that is still true; what changes is that the surrounding lane at that mask is
|
|
now green too (485/491, the pins only) — esprytobj-v3's "read F-v2-m2 as 'the scenario', not
|
|
'the lane'" caveat is discharged. The suggested arms for F's dependency-refusal coverage are
|
|
`0x5ff` / `0x9ff` / `0x7ff` / `0xdff`, all measured above.
|
|
- **B / C**: no emit header was touched. A suite that arms a hand-picked `MOBILEGL_PIPE_PUSH`
|
|
must now arm a mask D-K2 permits — `TextureScope` and `FramebufferScope` were both fixed here,
|
|
and any new emit suite that arms bit 10 needs bits 7 and 11 with it.
|
|
- **D / E**: `RefusedNoConsumer` still reads 0 on Espryt and the dependency gate never touches it
|
|
— a dependency is refused by the client's gate, so no record reaches the belt at all.
|
|
- **The shipped arm is unchanged.** `kMGPipeSubsystemsMigratedAtP4a` = 0x1fff carries every
|
|
dependency the table declares (a `static_assert`), so the default mask, the pull build and every
|
|
P2/P3a bit behave exactly as they did at `588b2277`.
|