Files
MobileGL/docs/archive/notes/p5e/reports/ra-v1.md
T

201 lines
15 KiB
Markdown

# ra — the wait rule, present credit, server-owned `gPipeInputs` (P5e)
Branch `p5e/ra`, head **48b2f56e**, based on **f6cfcbd3** (landed wave 1). Tree `~/w7/p5e-ra`.
Five commits; the mechanism is complete and **INERT** — `kMGPipeP5eRunAheadReady` is still `false`,
so `RunAheadArmed()` is false everywhere and every gate is exactly as green as the base.
## 1 Per deliverable: what is wired, and what it does when the bit flips
| # | deliverable | wired | at the flip |
|---|---|---|---|
| 1 | the predicate | c0e's `MGPipeBarriered` (all three clauses) is the server's; ra adds the CLIENT's spelling, `ClientVerbIsBarriered(verb, ctx*)` in `PipeFill.cpp` | both roles answer the same for the same record: static `WaitClass` column, XFB-active, (client arrays: vi refuses at emit) |
| 2 | the client wait rule | `EmitAndWaitTails` switches on `MGPipeWaitClassFor(op)` under `RunAheadArmed()`, **replacing** the `BatchWaits` skip; `ReleaseFillPins()` after a barriered apply; present credit in `EmitPresent`→`AcquirePresentCredit`; `OnPresent`→`ReturnPresentCredit`; forced waits before every `Server*` EGL forwarder and in `glFinish`; drains at every wait exit incl. the stage bell | `kWaitNone` rows publish and return; the steady draw path stops waiting; presents pace on a credit of 1 |
| 3 | `resource_subdata` buffer half | `MGPipeSubDataWantsItsReply(record)` — ONE predicate, read by `MGPipeRouteResourceSubData` and by `Wire_ResourceSubData`; the row keeps `kReplySlot`, the server still posts | the 64 KB persistent-map push stops being a hidden round trip per block |
| 4 | `gPipeInputs` ownership | `fillOwed = barriered` in `MGPipeValidateForVerb` gates the serial bump, `SetVerb`, `MGPipeServerClearVerbBoundary` and the whole of step 4; `MGPipeNoteFrontendMutation`/`MGPipeLeaveVerb` return; `CountBarrierPull` aborts unconditionally under an unbarriered record; the layer-2 guard is re-derived | the block is server-role memory for unbarriered records; a missed migration is a named abort, not a wrong picture |
| 5 | event-ring flow control | `ReserveEventOrBlock` (all four event kinds), `Drained()` clears **and rings**, `WaitFor{Applied,PresentAck}OrEventBacklog`, `ServerLoop`'s park gains "not while the ring is full" | a full 256 KiB ring is backpressure, not `Fatal{EventRingOverflow}`; two named refusals remain for the impossible cases |
| 6 | lifetime | the deferred-destroy queue STAYS; an enqueue from an unbarriered apply logs once and is Fatal under strict | ruling 13 (ID-91) pinned; slot reuse needs no wait (the ring orders `{s,g}` → `death` → `{s,g+1}`) |
| 7 | the strict lane | ONE step, TWO arms, and the arm is chosen by grepping `kMGPipeP5eRunAheadReady` out of `Init.cpp` | the lane becomes a hard green gate with §7's `<field>@<verb>` allowlist, in the same commit the runtime flips |
| 8 | docs | ARCHITECTURE §11.6, §11.7, §14, new §17.7, 附 A's knob table | — |
## 2 Files touched (regions, not whole files)
- `MG_Remote/Client/ClientSession.{h,cpp}` — the wait switch in `EmitAndWaitTails`; `RunAheadArmed`/`LatchRunAheadFromCaps` (latched in `PumpControlPlane`, demote-only); `ReleaseFillPins`, `WaitForApplyToCatchUp`, `Finish`, `AcquirePresentCredit`, `PresentCreditWaits`, `LastPublishedSeq`; the re-derived `RefusePipeInputsTouchWhileApplierOwnsIt(surface, isBarrieredFill)`; drains at the cmd-space wait and the stage bell; `credit-waits` on the wire ledger; the latch reset in `Stop`.
- `MG_Remote/Client/EmitTables.cpp` — `EmitPresent` mints `FrameSerial` through `AcquirePresentCredit`.
- `MG_Remote/Client/BackendObject_Remote.cpp` — `WaitForApplyBeforeEglForwarder` before the five `Server*` forwarders (NOT `ServerSwapEGLBuffers`).
- `MG_Remote/Client/WireTables.cpp` — `Wire_ResourceSubData` takes `wantReply` and posts accept-by-construction for the buffer half.
- `MG_Pipe/PipeRoute.h` — `MGPipeSubDataWantsItsReply` + the route's use of it (inside `#if MOBILEGL_PIPE_PUSH`).
- `MG_Remote/Server/PipeApplier.cpp` — `OnPresent` returns the credit and refuses `FrameSerial == 0` on a run-ahead server; `ServerPublishesRunAhead` helper; `#include "ServerSession.h"`.
- `MG_Remote/Server/ServerSession.cpp` — `ReserveEventOrBlock` replaces the four `Reserve` + Fatal sites.
- `MG_Remote/Server/ServerLoop.cpp` — the park predicate's fourth clause and the `DrainRing` gate.
- `MG_Remote/Transport/{EventRing.h,SessionRings.h,Ring.cpp}` — `SetServerDoorbell`, the ring-and-clear `Drained()`, the two `…OrEventBacklog` waits, `EventRingIsFull()`.
- `MG_Remote/Wire/PipeWireCodec.{h,cpp}` — `SetStageWaitHook`, called around the SEG_STAGE retirement park (**named delta**, see §5).
- `MG_Impl/Pipe/PipeFill.cpp` — `ClientRunsAhead`, `WireOpForVerb`, `ClientVerbIsBarriered`, `g_lastFillWasBarriered`, the `fillOwed` gate, `MGPipeReleaseResidualFillPins`, `MGPipeClientFinish`, the deferred-destroy finding, the vertex-attrib-defaults mirror read skipped under run-ahead (§3.4).
- `MG_Backend/MGPipe/PipeInputs.cpp` — `CountBarrierPull`'s unconditional arm; `StrictBarrierPullFatal` gains a reason so the lane can tell the two markers apart.
- `MG_Pipe/PipeMutation.h` (declarations + the ruling-13 comment), `MG_Pipe/PipeApply.h` (the two-constants ruling, §6).
- `MG_Impl/GLImpl/Exporting/Definitions.cpp` — `glFinish` (**named delta**, §5).
- `MG_Test/Wire/{RemoteClientTest,SessionTest}.cpp`, `.github/workflows/test.yml`, `docs/Disaggregated/ARCHITECTURE.md`.
## 3 Red-once evidence (executed, reverted, verbatim)
**1. Present without the credit wait** (`if (m_presentsSent >= credit)` → `if (false)`),
`RemoteRunAhead.ACreditOneClientPaysTheCreditAtEveryPresentAfterTheFirst`:
```
0% tests passed, 1 tests failed out of 1
../MobileGL/MG_Test/Wire/RemoteClientControls.inc:143: Failure
Actual: false
exited 103
```
(103 = `PresentCreditWaits() != 2` — red by count, which is the only way to test a wait that is
usually already satisfied.)
**2. Leave the fill in for an unbarriered record** (`const Bool fillOwed = barriered;` → `= true`),
`RemoteRunAhead.AnUnbarrieredVerbDoesNotFillPipeInputsAndIsAllowed`:
```
signal 6
[08:09:45] [Linux RemoteClientTes/FATAL]: MGPipe: Fatal{RoleViolation, "gPipeInputs"} - the GL thread touched gPipeInputs (MGPipeValidateForVerb) on a RUN-AHEAD session outside a barriered fill. With the client running a
```
**3. Count instead of Fatal under an unbarriered record** (drop `CountBarrierPull`'s first
clause), `RemoteGuards.AResidualPullUnderAnUnbarrieredRecordIsFatalWithoutTheStrictKnob`:
```
0% tests passed, 1 tests failed out of 1
../MobileGL/MG_Test/Wire/RemoteClientControls.inc:139: Failure
Actual: false
exited 0
```
(the probe stops aborting; on the lane this is every still-pulling scenario going from a named
abort to a wrong picture with a number beside it.)
**4. Keep `Fatal{EventRingOverflow}`** (`if (!ServerPublishesRunAhead(session)) Fatal…` → always),
`RemoteRunAhead.AnEventBurstBehindAnUnwaitedSequenceFlowControlsInsteadOfAborting`:
```
signal 6
[08:11:31] [Linux mgl-srv-apply/FATAL]: MGPipe: Fatal{EventRingOverflow} - the producer of kEventGpuWritten could not reserve 1040 bytes on SEG_EVENT. P5c's events are lossless and a full ring under lockstep is a produce
```
**4b. The drain stops ringing the server** (`Drained()`'s `NotifyIfParked` → `(void)wasFull;`),
`SessionTest.DrainingAFullEventRingClearsTheLatchAndRingsTheServer`:
```
../MobileGL/MG_Test/Wire/SessionTest.cpp:661: Failure
Which is: 0
Which is: 1
```
**4c. The applied park stops breaking on the ring** (drop the `eventRingFull` clause),
`SessionTest.AFullEventRingWakesAClientParkedOnAppliedSeq`:
```
../MobileGL/MG_Test/Wire/SessionTest.cpp:586: Failure
Which is: 4-byte object <02-00 00-00> (TimedOut)
Which is: 4-byte object <00-00 00-00> (Reached)
```
**5. Bit 10 for Magma** — c0e already ran and recorded this
(`MagmaPipeIdentityTest.AMagmaServerNeverPublishesTheRunAheadCapBit` fails "Which is: 1024 / 0").
Re-run here green: `MagmaPipeIdentity` 5/5.
**6. NOT RUN, and why.** `MOBILEGL_IPC_RUN_AHEAD=0` renders identically is TRIVIALLY true on this
tree — the caps bit is unpublished, so both arms are the same code path — and the SSIM arm needs
the device. `MOBILEGL_IPC_VERB_BARRIER=0` under run-ahead is likewise unreachable before the flip.
Both belong to the integrator's device exit (BRIEF §4).
## 4 Gate (this tree vs base f6cfcbd3, measured both)
| step | base f6cfcbd3 | p5e/ra 48b2f56e |
|---|---|---|
| build | rc=0 | rc=0 |
| unit | 2206/2206 | **2222/2222** (+16 cases, all new) |
| `integration-split` | 111/111 | 111/111 |
| `integration-split-strict` | 3% passed, 108 failed of 111 | **identical** |
| gens | 7 rc=0 + the pre-existing `CONTRACT-P5.md:524 Core.cpp:39` ambiguity | identical |
Strict marker table, from the 88 per-entry private logs, **before and after are the same table**
(measured by checking out f6cfcbd3, rebuilding and re-running):
| marker | count (base) | count (ra) | owner |
|---|---|---|---|
| `GetFramebufferBindingSlot@Clear` | 39 | 39 | fb |
| `GetBoundVertexArray@DrawArrays` | 14 | 14 | vi |
| `GetImageTextureBinding@BindImageTexture` | 13 | 13 | fb |
| `GetTextureUnitObject@Clear` | 9 | 9 | tx2 |
| `GetTextureObject@CopyImageSubData` | 6 | 6 | P5b debt (allowlisted) |
| `GetProgramForDispatch@DispatchCompute` | 3 | 3 | pg |
| `ValidateProgramName@ShaderStorageBlockBinding` | 2 | 2 | pg (allowlisted) |
**G1: 0 delta.** Every edit to shared code is under `MOBILEGL_BUILD_DISAGGREGATED` or
`MOBILEGL_PIPE_PUSH` (`PipeRoute.h`'s route is at line 270, inside the file's push guard).
## 5 Kimi audit cross-check (my family is list (b), not an object family)
- **RETIRED:** `PI:807, PI:812-814` — the four O-class `SharedPtr` rows (`m_boundVertexArray`,
the three programs). `ReleaseFillPins` drops them after every barriered apply, and an
unbarriered verb never re-fills them, so the apply thread can no longer become a frontend
object's last owner through this block.
- **LEFT BARRIERED:** `PI:808-811, PI:815` — the raw pointer bases into the frontend tables.
They are written only by a barriered fill; an unbarriered apply that reads through them takes
§3.3's abort by field and verb. Their retirement is the family packages' (list (c)).
- **NOT FOUND / not mine:** every row of list (c) is an `MGB_CTX->` accessor whose retirement
belongs to vi/sb/pg/tx2/fb. ra changes not who reads them but what a read costs.
## 6 Rulings I need from the integrator
1. **`kMGPipeP5eClientWaitRuleLanded` flips with `kMGPipeP5eRunAheadReady`, not when ra lands.**
ID-103 says "ra flips it in the same commit that lands the wait rule". That cannot be right:
`RunAheadArmed()` needs the server's caps bit, so between ra landing and the bit being
published the client still blocks after every record — and a `false` stamp there withdraws
§4.4's exemptions from probes that wait still makes safe, which is the "refusal with no defect
behind it" ID-103 itself refused. I left BOTH constants `false` and amended the comment at the
constant. **The integration commit throws both.** (Had I flipped it, `integration-split` would
be near-totally red on this tree: the family packages have not landed.)
2. **§3.2's "the stamp moves to applier-owned storage" is implemented as an OWNERSHIP rule, not
as moved storage.** Physically moving `m_filled`/`m_currentVerb`/`m_serverStampedVerb` out of
`gPipeInputs` means re-pointing the freshness check in all 63 generated accessors
(`generated/PipeFilled.inc`), which is c0e's file and a much larger blast radius. What ra
landed is the rule the move existed for: under run-ahead the GL thread writes those fields
only inside a barriered fill, so the E-note hazard (b.4) — a GL thread withdrawing the
server's stamp while an apply depends on it — cannot occur. Confirm, or schedule the move.
3. **`SetIdentity` is NOT skipped** (§3.1 lists it). `m_live`/`m_contextIdentity` are not fields
of the residual model — no ownership row owns them, no record carries them, no server stamp
can answer them — they are "does this process still have a GL context", which every
null-context guard reads and only the GL thread knows. Two stores per verb, no stamp.
4. **The §7 allowlist is my best reading, not a measurement.** It cannot be measured before the
flip (every entry still aborts on an unmigrated row). The integrator should re-derive it from
the first green run and delete rows rather than widen them.
## 7 Seams assumed from other packages
- **vi:** a draw with a client-memory array is refused at emit under run-ahead (`ruling 2` /
§5.1). `ClientVerbIsBarriered` therefore does NOT re-compute `kDrawClientArrays` — duplicating
vi's "does any enabled attribute lack a buffer" walk is exactly the second spelling ruling 3
replaced. If vi's refusal does not land, a client-array draw would be judged unbarriered and
its fill skipped. Named in the code comment.
- **tx2:** `GenerateMipmap` stays `kWaitApplied` until the `VerbMipRes` arm lands; the wait rule
reads the column, so tx2 flipping the row is all that is needed.
- **pg/sb/fb/tx2:** the strict allowlist's rows are theirs to delete.
- **c0e (landed):** `MGPipeWaitClassFor`, `kCapRunAheadApply`, `MGPipeRunAheadCapBitsFor`,
`IpcTable::RunAhead/PresentCredit`, `MGPipeBarriered`, the barriered-record flag + setter.
- **id (landed):** `ApplyOne`'s stamp line — untouched by ra, as the brief assigns.
## 8 Named deltas and what I did not do
- **`PipeWireCodec.{h,cpp}` (not in my scope list):** the SEG_STAGE retirement park is a CLIENT
wait and the deadlock argument needs every client wait to drain. The encoder cannot drain
SEG_EVENT itself, so it gained a `StageWaitHook` the session installs. Null in every standalone
codec; the park is otherwise byte-identical.
- **`MG_Impl/GLImpl/Exporting/Definitions.cpp` (not in my scope list):** `glFinish` was a pure
no-op. Under run-ahead "the commands issued so far have completed" is a promise the queue can
break, and this is the only place an application can ask for it. Two lines, under
`#if MOBILEGL_BUILD_DISAGGREGATED`, calling `MG_Pipe::MGPipeClientFinish`.
- **The server half of the present credit is not unit-pinned.** The `RemoteClient` fixture has no
backend object, so `ServerVerbSink::OnPresent` declines before it can reach
`ReturnPresentCredit`; the cases substitute a peer sink and assert the CLIENT's half. That the
server returns exactly one credit per swap after `Present()` returns is three lines in
`PipeApplier::OnPresent` and the device exit's `credit-waits` reading.
- **No device numbers.** The measurement arms of BRIEF §4 (fps, per-thread ms/frame, simpleperf,
SSIM) are the integrator's; no adb from here.
- **`MOBILEGL_IPC_EVENT_KB`** stays a trailing item: flow control makes 256 KiB correct rather
than fast, and the ring size is a measurement, not a correctness input.
- **G2/G14 skip twins:** the new public names are all in split-only translation units
(`MG_Remote/*`, the push-only half of `PipeFill.cpp`) and the new cases live in
`MG_Test/Wire/*`, which is a split-only binary. No monolith twin is possible or needed; unit
count moves 2206 → 2222 on the split build only.