mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-16 14:33: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.
235 lines
16 KiB
Markdown
235 lines
16 KiB
Markdown
# pa-v1 — the program family leaves the frontend on the draw and dispatch paths
|
||
|
||
Tree `~/w7/p5e-pa`, branch `p5e/pa`, base `7c6f6886`, head **`dd899510`**.
|
||
`53b83469` (MG_Backend, MG_Remote) + `dd899510` (MG_Test). 4 files, +392/−20.
|
||
|
||
## 1 Read-site inventory (what is actually there)
|
||
|
||
All five accessor sites the kimi index names are accounted for
|
||
(`GetProgramForDraw` D:4781/5308/5679/5734, `GetProgramForDispatch` D:6126):
|
||
|
||
| site (head line) | kimi | at base | now |
|
||
|---|---|---|---|
|
||
| `DirectGLES.cpp:6229` `PrepareForDraw` | 91 | unconditional pull | arm-selected (pa) |
|
||
| `:7032` `BindCurrentTextures()` no-arg, exported at `DirectGLES.h:25` | index D:5308 | unconditional pull | arm-selected (pa) |
|
||
| `:8145` `PrepareForCompute` | 92 | unconditional pull | arm-selected (pa) |
|
||
| `:7675` `GetCurrentBackendProgram` | 107 | already gated | pg, untouched |
|
||
| `:7747` `CurrentProgramMayNeedPerSubDrawBuiltins` | 108 | already gated | pg, untouched |
|
||
|
||
The consumers of the hoisted value — **this is where the brief's §3 differs from the tree**:
|
||
|
||
- **`SyncCurrentVertexAttributeValues` (kimi 106) is the only one that still genuinely needs the
|
||
object**: `GetActiveAttributeLocationMask` + `GetAttribType`.
|
||
- **`ResolveAndBindUnitTextures`' reads are on its LEGACY arm.** `sampledTargetForUnit` is declared
|
||
*after* tx2's `if (UnitTexturesByHandle()) { … return; }`, so the handle arm never reaches it.
|
||
§3.2(a) reads as if the miss path still needed serving; it does not — but see §2.
|
||
- **`BindCurrentTextures`' memo key (kimi 100)** was already by-handle (ID-86); what was left is the
|
||
unconditional `programKey = currentProgram.get()` load and three `currentProgram ? … : 0` memo
|
||
stores. Retired.
|
||
- **`BindCurrentProgramWithResources` (kimi 101–105)** needed no code change: every read is on the
|
||
`:` side of a `handleArm ? <record> :` pick or inside the `else` of `if (handleArm)`. The one pair
|
||
that is *guarded* rather than picked — `globalConstants ? … : currentProgram->{GetUBOContentVersion,MapUBO}()`
|
||
— is unreachable on that arm because the `set_global_constants` refusal above it is `[[noreturn]]`
|
||
**in the same function**; I added that sentence to its comment rather than restructuring pg's lines.
|
||
|
||
Kimi rows: **retired** 91, 92, 106 and the residue of 100. **Left barriered** 109
|
||
(`ValidateProgramName`, P9) and the XFB row D:1387 (§5.7). **Not as the audit has it**: row 106's
|
||
`dup` column says "none" — wrong now, the archive carries both fields; that column predates pg.
|
||
No row of this family was found not to exist.
|
||
|
||
## 2 Design
|
||
|
||
`DrawProgramFromRecords()` (`:6173`) states the arm once, as a **conjunction**:
|
||
`ProgramHandleArm() && TextureImpl::UnitTexturesByHandle()`. One hoisted value serves four callees,
|
||
so the arm must name every consumer, not this family alone; the second conjunct is
|
||
`BindCurrentTextures`'. **The family bits are independently settable A/Bs** (`0x0ff` is supported),
|
||
so "the program family is on the handle arm" is *not* "no consumer needs the object" — reading the
|
||
first as the second is the shape that cost the phase 137 scenarios (ID-107/109/110). Both conjuncts
|
||
reduce to `Transport != Monolith && <family bit>`, so push-monolith is false here and keeps the
|
||
frontend hoist token for token. In the **mixed A/B** (program on, textures off) the hoist keeps
|
||
pulling and the row stays red — deliberate, smallest, and stated at the selector (ruling R-2).
|
||
|
||
`SyncCurrentVertexAttributeValues` gains a **second overload** taking `MGPipeHandle cso` (`:2380`,
|
||
under `#if MOBILEGL_PIPE_PUSH`), per §5.8's "two overloads, not an `#if` inside one body". It makes
|
||
the same three-part test `SyncCurrentProgramByHandle` makes (`record == nullptr ||
|
||
Desc.LinkStatus == 0 || Desc.SpirvStatus == 0` → return; ID-88's reason — that is the record-arm
|
||
spelling of the frontend's `if (!program) return;`), computes the mask from
|
||
`record->Archive->Link.attribs` with ProgramObject's own rule (`min(size,32)`, bit where the name is
|
||
non-empty), reads the type from `…->Link.attribTypes[location]` **bounds-checked** (the frontend
|
||
form is not, because its mask came off the same instance; here the two vectors arrived over a wire),
|
||
and logs `cso.Slot/Gen` rather than a GL name (`ProgramArchiveSource::Identity`'s rule).
|
||
**Nothing added to the wire, no record changed, no catalogue regenerated.**
|
||
|
||
A live, linked record with **no archive** on that arm is `Fatal{RoleViolation, "program-handle-arm"}`,
|
||
never a fall-back — the shape of `RefuseNullFrontendTextureOffTheHandleArm`.
|
||
|
||
Two deliberate deviations from the wave-3 scout note: I did **not** build a `ProgramArchiveSource`
|
||
per draw (its `FromRecord` allocates a vector and a map) — the hot path reads `record->Archive->Link`
|
||
directly — and I did **not** add the two accessors to `ProgramArchiveSource`, because no caller would
|
||
use them. And the overload **copies** vi's memo arm rather than sharing a tail: a shared tail would
|
||
rewrite the frontend overload's preprocessed text, which G1 measures at 0/0/0/0
|
||
(`SyncCurrentProgramByHandle` / `SyncCurrentVAOFromRecords` are the same precedent).
|
||
|
||
Also: the ledger at `:6239` now adds `(vertexInputFromRecords ? 0 : 1) + (programFromRecords ? 0 : 1)`
|
||
— **zero accessor calls per draw** on the record arm — and the stale comment in
|
||
`PipeApplier::OnLaunchGrid` (`PipeApplier.cpp:782`) saying the compute program is pulled is corrected.
|
||
|
||
## 3 Composite and relink
|
||
|
||
**Composite.** `ProgramEmit.h:126` takes `drawProgram = ctx.GetProgramForDraw()` (the flattened
|
||
composite when a pipeline is bound), `:129` acquires its CSO via `AcquireShaderCso`, which `:635`
|
||
routes through `MGPipeSlots().AllocateComposite` for a composite, and `:180`
|
||
`MGPipeRouteSetDrawProgram(HandleOnly(drawCso))` names *that* handle — so `set_draw_program` names
|
||
the composite and pg archives it like any other CSO. Server side `PipeShaderCsoRecordForHandle`
|
||
(`Managers.cpp:4483`) is band-aware. Green lane evidence: `ProgramPipelineScenario.*` (2 split
|
||
entries) and `TessellationXfbCaptureScenario.CapturesFromASeparableEvaluationProgramInAPipelineObject`.
|
||
|
||
**Relink.** The overload holds no pointer across calls — it re-resolves the record and re-reads
|
||
`Archive->Link` every draw, and `MGPipeApplyCreateShaderState` replaces `Archive` wholesale — so a
|
||
draw after a relink reads the new archive by construction. A failed relink is `Desc.LinkStatus == 0`
|
||
(ID-88) and declines before the archive is consulted.
|
||
|
||
**One behavioural delta between the arms, named not hidden:** for a program the frontend reports
|
||
*unlinked*, the monolith arm may still issue `glVertexAttrib*` current values (its guard is
|
||
`if (!program)`, not link status) while the record arm returns early. No program is bound in that
|
||
state on either arm (`SyncCurrentProgram*` binds 0), so it is unobservable.
|
||
|
||
**Gap:** the split lane has **no relink scenario**. `RelinkStageSetScenario`, `PostLinkAttachScenario`,
|
||
`HandleRecycleScenario`, `ImageLoadStoreSsoScenario` are `DirectGLES.` (monolith-arm) entries only,
|
||
covered by `gpu` 1294/1294. Named as debt, not claimed as record-arm evidence.
|
||
|
||
## 4 Red-once, verbatim
|
||
|
||
**(1) Arm reverted** (`DrawProgramFromRecords()` → `false`, vertex-attribute call site back on the
|
||
frontend overload), rebuilt, full census: lane back to **7 passed / 109 red**, marker back at
|
||
**62 + 7** — not 61 + 7, confirming the coordinator's correction in my own tree.
|
||
|
||
```
|
||
[11:48:24] [Linux mgl-srv-apply/FATAL]: MGPipe: Fatal{UnmigratedPipeInput, "GetProgramForDraw@DrawArrays"} [BARRIER-PULLED, MOBILEGL_IPC_STRICT_ERRORS=1, retires in P5e (Espryt unbarriered), P7 (Magma)]
|
||
[11:47:57] [Linux mgl-srv-apply/FATAL]: MGPipe: Fatal{UnmigratedPipeInput, "GetProgramForDispatch@DispatchCompute"} [BARRIER-PULLED, MOBILEGL_IPC_STRICT_ERRORS=1, retires in P5e (Espryt unbarriered), P7 (Magma)]
|
||
```
|
||
|
||
The 62nd is `…PersistentMapArm.PersistentCoherentMapScenario.TheMapLandsInTheArmItsLaneDeclares`,
|
||
taken under its own lane environment (`~/w7/p5e-logs/pa-census-red1/`).
|
||
|
||
**(2) Archive lookup forced to answer null** on the handle arm
|
||
(`if (true /* P5E-PA-RED-ONCE-2 */ || !record->Archive)`), entry
|
||
`TriangleScenario.AVboBackedTriangleReachesReadPixels`, log `~/w7/p5e-logs/pa-red2.log`:
|
||
|
||
```
|
||
[11:49:20] [Linux mgl-srv-apply/FATAL]: MGPipe: Fatal{RoleViolation, "program-handle-arm"} - SyncCurrentVertexAttributeValues needs the active-attribute mask and the attribute types of ShaderCso {1, 0} and that record carries no server-owned archive. The arm is selected by Transport != Monolith AND the program subsystem bit (CONTRACT-P5E §5.8, ID-81), so this record's create_shader_state was applied under a transport and must have adopted one; the frontend ProgramObject is not a fall-back here, it IS the client memory this row retires
|
||
```
|
||
|
||
**(3) Both put back** → `build rc=0`, `unit 2250/2250`, `isplit 120/120`.
|
||
|
||
**(4) The new pin's own negative control (R-16):** with the arm reverted all four
|
||
`DirectGLES.Split.StrictProgramArm.` entries abort — `GetProgramForDraw@DrawArrays` in the MultiDraw
|
||
one, `GetProgramForDispatch@DispatchCompute` in the three AtomicCounter ones, each from its own
|
||
private log.
|
||
|
||
## 5 Marker census, before and after
|
||
|
||
Both tables are from **my own tree** with a corrected census (`.p5e/census_pa.sh`): the gtest filter
|
||
and the whole `ENVIRONMENT` come from `ctest -N -V` per entry instead of the last two dot components
|
||
plus one hard-coded env block — the blind spot addendum §4 names. "Before" is the red-once-1 build.
|
||
|
||
| marker | before | after | owner |
|
||
|---|---|---|---|
|
||
| `GetProgramForDraw@DrawArrays` | **62** | **0** | **pa** |
|
||
| `GetProgramForDispatch@DispatchCompute` | **7** | **0** | **pa** |
|
||
| `GetFramebufferBindingSlot@ReadPixels` | 19 | 67 | allowlist (readback, P7) |
|
||
| `GetTransformFeedbackProgram@DrawArrays` | 0 | 11 | XFB §5.7 — no P5e package retires it |
|
||
| `GetBoundVertexArray@DrawArrays` | 9 | 11 | mv |
|
||
| `GetTextureObject@CopyImageSubData` | 6 | 6 | allowlist (P7) |
|
||
| `ValidateProgramName@ShaderStorageBlockBinding` | 2 | 2 | allowlist (P9) |
|
||
| `GetTextureUnitObject@CopyTexImage2D` | 2 | 2 | allowlist (CopyTex) |
|
||
| `GetFramebufferBindingSlot@Clear` (DirectVulkan) | 2 | 2 | Magma, ID-90 / P7 |
|
||
| **red / lane** | **109 / 116** | **101 / 116** | |
|
||
|
||
**Eight entries went fully green** — exactly my seven dispatch entries plus
|
||
`MultiDrawScenario.BaseVertexDrawsRejectMalformedArguments`. Three rows moved that are **not mine**,
|
||
all of them *unmasking* and none of them new reads (my marker fired first at base and hid them):
|
||
|
||
- `…@ReadPixels` +48: the draw scenarios that read pixels back.
|
||
- `GetBoundVertexArray@DrawArrays` +2: both `ClientVertexArrayScenario` entries. **mv's.**
|
||
- `GetTransformFeedbackProgram@DrawArrays` +11 (7 `TessellationXfbCaptureScenario`, 4
|
||
`XfbCaptureBufferReuseScenario`): read at `DirectGLES.cpp:1892` from
|
||
`StartPendingTransformFeedback`, the **last** statement of `PrepareForDraw`, which is why nothing
|
||
ever reached it. `kBarrierPulled`, retirement "P3b/P4b (Espryt), P7 (Magma)", and §5.7 calls it
|
||
"an object row no package retires". **Missing from the addendum's allowlist table** (R-4).
|
||
|
||
`GetFramebufferBindingSlot@Clear` (DirectVulkan `NamedBlit.F1WireScenario.*`) is **identical before
|
||
and after in my census**: a census-method artefact of the shared script (those entries' real lane is
|
||
Magma; the shared script re-ran them as DirectGLES), not anything I caused. Out of scope (ID-90).
|
||
|
||
## 6 Gate
|
||
|
||
| step | result |
|
||
|---|---|
|
||
| `build` | rc=0 |
|
||
| `unit` | **2250 / 2250** |
|
||
| `isplit` | **120 / 120** (116 + four new pin entries) |
|
||
| `gpu` | **1294 / 1294** (run twice, before and after the pin commit; the pin is `integration-split`-labelled so the count is unchanged) |
|
||
| `gens` | all seven rc=0; `check_doc_citations` rc=0 with 3 pre-existing problems in `CONTRACT-P5.md`, a file I did not touch |
|
||
| `strict` | 19 passed / 101 failed of 120 (was 7 / 109 of 116); per-entry census §5 |
|
||
| `flavours` (ID-124) | **rc=1 — both halves pre-existing, proved below** |
|
||
|
||
`flavours` printed `pull ARM CHECK FAILED (compile_commands says MOBILEGL_PIPE_PUSH=1)` and
|
||
`nodisagg build rc=1 (726 TUs)` with two errors, `ComputeShaderStorageBlockBindingSignatureOf`
|
||
(`:5749`) and `keysMatch` (`:6981`). `.p5e/nodisagg_base_tu.sh` compiles the **base revision's**
|
||
`DirectGLES.cpp` with the `nodisagg` flavour's own command from its `compile_commands.json` and gets
|
||
`rc=1` with **the same two errors and no others**. Cause of the second is in the base text:
|
||
`const Bool keysMatch =` sits inside `#if MOBILEGL_BUILD_DISAGGREGATED` (base `:6695`) while
|
||
`if (!keysMatch || …)` does not. That is tx2's line, inside the block pa edits; I left it rather
|
||
than fixing another package's line under an already-red gate (R-7).
|
||
|
||
## 7 G1 / monolith impact
|
||
|
||
Every added token is inside `#if MOBILEGL_PIPE_PUSH` / `#if MOBILEGL_BUILD_DISAGGREGATED`, except
|
||
three constructs copied deliberately from **vi's already-cleared shape**: the
|
||
`inline Bool DrawProgramFromRecords()` selector with the `#if` inside it (vi's
|
||
`VertexInputReadsRecords`), the `const SharedPtr<ProgramObject> noFrontendProgram;` local (vi's
|
||
`noFrontendVao`), and the `x ? noFrontend : MGB_CTX->Get…()` ternary — all three constant-fold to
|
||
the pre-change expression in a pull build. No other shared-code delta; the push-monolith arm takes
|
||
the frontend branch everywhere, token for token. **I did not run `symbol_report.py`** (no pull
|
||
baseline here, and the flavour does not build at the base either way); the evidence I do have is
|
||
§6's: base and head fail `nodisagg` with the same two pre-existing errors, so my diff added no
|
||
pull-build text that fails to compile.
|
||
|
||
## 8 Rulings wanted
|
||
|
||
- **R-1** `Fatal{RoleViolation, "program-handle-arm"}` follows `…OffTheHandleArm`'s
|
||
`"texture-handle-arm"`. Confirm the vocabulary (alternative: `Fatal{UnmigratedVerb, "create_shader_state"}`).
|
||
- **R-2** The hoist's second conjunct. Keep the mixed A/B pulling, or have tx2 give
|
||
`sampledTargetForUnit` an archive arm so the conjunct can go?
|
||
- **R-3** The new `DirectGLES.Split.StrictProgramArm.` lane (4 entries, `integration-split` only,
|
||
private log paths). It exists because **nothing gated my marker** — pg declared this red-once and
|
||
it never landed. mv and gl will want to extend it and all three of us touch
|
||
`MG_IntegrationTest/CMakeLists.txt`, so **expect a conflict** and consider re-homing it to the
|
||
integration commit. Name, labels and scenario choice are yours to overrule.
|
||
- **R-4** Add `GetTransformFeedbackProgram@DrawArrays` (11) to the allowlist table in the addendum /
|
||
`STRICT-WORKLIST.md`; §5.7 already rules it out of P5e.
|
||
- **R-5** Pre-existing, not mine: on the **dispatch** path `BindCurrentTextures`' by-handle memo key
|
||
uses `st.DrawProgram` although the caller's program is `st.DispatchProgram`. Benign today (the
|
||
by-handle resolution does not consult the program at all, so it only over-keys) but it is a key
|
||
naming the wrong row.
|
||
- **R-6** `~/w7/notes/tools/p5e_gate.sh` was edited **while my `gpu` run was reading it** (mtime
|
||
11:55:45, new `flavours` step). The ctest log is unaffected (1294/1294) but the driver printed a
|
||
parse error from the half-written file; I ran `flavours` from `.p5e/p5e_gate_snapshot.sh`. Pin the
|
||
driver for the wave.
|
||
- **R-7** Two `flavours` findings that are the integrator's: (a) the `pull` arm cannot exist as
|
||
specified — `MOBILEGL_BUILD_DISAGGREGATED=ON` forces `MOBILEGL_PIPE_PUSH=ON`
|
||
(`CMakeLists.txt:496-500`), so only `nodisagg` is a real pull build; (b) `nodisagg` is red at
|
||
`7c6f6886`. Both are one-line fixes; say the word and pa takes them.
|
||
|
||
## 9 What I did not do
|
||
|
||
- No device run, no adb, no push, no merge; no other tree touched.
|
||
- No accessors added to `ProgramArchiveSource`, no shared-tail refactor of
|
||
`SyncCurrentVertexAttributeValues` (§2, G1).
|
||
- No DirectVulkan `GetProgramForDraw` sites (`VulkanRenderer.cpp:6384/6815/6853/7424/7476`): Magma
|
||
keeps the lockstep for all of P5e (ID-90).
|
||
- No relink scenario added to the split lane (§3's gap).
|
||
- Left in the tree: `build-nodisagg/` and `build-pull/`, both untracked, created by the `flavours`
|
||
step (which `rm -rf`s them itself on the next run).
|