Files
MobileGL/docs/archive/notes/p5/verb-census.md
T

174 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# verb-census.md — which `GlobalBackendFunctionsTable` slots the reduced path actually reaches
**Status: STATIC, but not an estimate for two of the three targets.** R-4 asks for a census run
against an all-`Fatal` emit table; that table does not exist until package c1 lands, so this was
derived by reading the dispatch chain from every GL entry point down to
`gBackendFunctionsTable.GL.*`. For **OpenRA the call set is measured, not guessed** — the
fixture turned out to be hydrated locally and was dumped with the local `apitrace`. **c1 must
still confirm the whole thing by running the real all-Fatal table**, because a static read
cannot see a slot reached from a branch it did not know to follow.
Base `feat/disaggregated @ a29807cc`, read in `~/w7/p5-c0`. No GitHub fetch, no LFS.
---
## The answer
**Six slots, out of 71.** Five `GLFunctionsTable` entries plus `Present`:
| slot | A: ClearThenReadPixels | B: Triangle | D: OpenRA | reached by |
|---|---|---|---|---|
| `Clear` | ✔ (all 5 cases) | ✔ | ✔ (128 calls) | `glClear` |
| `DrawArrays` | ✔ (4 of 5) | ✔ | ✔ (3,648 calls) | `glDrawArrays` |
| `ReadPixels` | ✔ (all 5) | ✔ | ✔ (harness, not the trace) | `glReadPixels` |
| `BlitFramebuffer` | ✔ (cases 3, 4) | — | — | `glBlitFramebuffer` |
| `GetIntegeri_v` | ✔ (4 of 5) | ✔ | ✔ (once) | **the first `glCompileShader` of a context**, not any verb |
| `Present` | ✔ (all 5) | **only if it calls `EndFrame()`** | ✔ (128) | `eglSwapBuffers`, **through the EGL path, not through GLImpl** |
The other **65 slots** take `Fatal{UnmigratedVerb, "<slot>"}`.
This is **at the bottom of R-4's predicted 6–15**, and it is smaller than the brief's guessed
minimum set for reasons worth knowing rather than celebrating — see the four traps below.
---
## Four things this census found that the guess would have got wrong
**1. `Flush` and `Finish` are not slots and reach nothing.** R-4's predicted minimum set names
`Flush`. There is no `Flush` entry in `GLFunctionsTable` at all, and
`MG_Impl/GLImpl/Exporting/Definitions.cpp:111-112` makes both `glFinish()` and `glFlush()`
**literally empty bodies** — one `MGLOG_D` and a return. A `TriangleScenario` that calls
`glFlush` to order its readback is ordering nothing. If it needs a real sync it must use
`glFenceSync` + `glClientWaitSync`, which would pull in three more slots (`FenceSync`,
`ClientWaitSync`, `DeleteSync`); the readback itself is the cheaper ordering point.
> **RULING R-15 (integrator, after this census): a getter-shaped slot — one whose answer is a
> static property of the server's device — is ANSWERED LOCALLY FROM THE CAPS MIRROR, never
> emitted and never `Fatal`.** That puts `GetIntegeri_v` and `IsTimerQuerySupported` in class A
> below, leaves five slots emitted and 64 `Fatal`, and the gate already exists
> (`AdvertisedLimitsScenario.ComputeWorkGroupLimitsAreTheCapsBlocksAnswer`). The full three-class
> split, and the 41 null-checks that are really capability probes, are in `CONTRACT-P5.md §7` —
> **c1 reads it there rather than re-deriving it.**
**2. `GetIntegeri_v` is reached by compiling a shader, not by drawing.** It has no GL-verb
caller on this path at all: `MG_Util/ShaderTranspiler/CompileEnv.cpp:134-138`
(`CaptureCompileEnv`) reads it, reached lazily from `MG_State/GLState/Core.cpp:39`
(`GLContext::GetCompileEnv()`) on the **first shader compile of a context**. So *every* target
that compiles a shader touches it, whatever its entry-point set looks like — and an emit table
that raises `Fatal{UnmigratedVerb}` on it aborts on the first `glCompileShader` of every
scenario. It must have a real emitter (or be answered from the caps mirror, which is the better
answer: the six compute limits it carries already ride in `MGPCaps::Dynamic`, see CONTRACT §1).
**3. `Present` and `SetSwapInterval` have ZERO call sites in `MG_Impl`.** Both are called only
from `MG_Backend/BackendObject.cpp:396` and `:403`, reached through
`MG_Impl/EGLImpl/EGLImpl.cpp:178` / `:448`. An emit table built by mirroring the 89 GLImpl call
sites covers neither, and `Present` is on the reduced path in two of the three targets. The seam
for those two is the EGL path — which is the same seam v1 is already rerouting to the apply
thread, so they belong together.
**4. `ReadPixels` has a second, invisible caller.** Besides `glReadPixels`
(`GL_Framebuffer.cpp:3095`), the frontend fallback behind `glCopyTexSubImage*` calls it —
`CopyReadFramebufferIntoMipmapRegion`, `GL_Texture.cpp:1048`, calling at `:1084`. Not on the
reduced path, but it is the class of thing that makes "this scenario has no readback" false.
Two siblings: `GenerateMipmap` can fire from a `glTexImage*` when `GL_GENERATE_MIPMAP` is set
(`GL_Texture.cpp:1679` → `:1688`), and `DrawArrays` is reached by `glDrawTransformFeedback*`
(`GL_Drawing.cpp:1710`, `:1712`) with no `glDrawArrays` in sight.
---
## Per target
### A — `DirectGLES.Split.ClearThenReadPixelsScenario` (exists, 5 cases)
`MG_IntegrationTest/Scenarios/ClearThenReadPixelsScenario.cpp`, 335 lines.
| case (line) | slots |
|---|---|
| `ClearWithNoDrawIsVisibleToDefaultFramebufferReadPixels` (80) | Clear, DrawArrays, ReadPixels, GetIntegeri_v, Present |
| `ClearWithNoDrawIsVisibleToASubRectReadback` (143) | same |
| `ABlitIntoTheDefaultFramebufferSurvivesAnEarlierClear` (191) | + **BlitFramebuffer** |
| `AMultisampleResolveBlitIntoTheDefaultFramebufferKeepsItsOrientation` (241) | Clear, **BlitFramebuffer**, ReadPixels, Present — **no shader and no draw**, so it is the one case that does *not* need `DrawArrays` or `GetIntegeri_v` |
| `ADrawIntoTheDefaultFramebufferSurvivesAnEarlierClear` (308) | Clear, DrawArrays, ReadPixels, GetIntegeri_v, Present |
`glBlitFramebuffer` reaches **`BlitFramebuffer`**, *not* `BlitNamedFramebuffer` — the DSA slot is
reachable only from `glBlitNamedFramebuffer` (`GL_Framebuffer.cpp:3413` → `:2708`). Easy to
conflate; they are separate slots and only one is on this path.
### B — `DirectGLES.Split.TriangleScenario` (does not exist; t1 writes it)
Spec: VBO create + upload, compile + link, VAO, `glClear`, `glDrawArrays` (VBO-backed, **no
client-array indices**), `glFlush`, `glReadPixels`.
Slots: **`Clear`, `DrawArrays`, `ReadPixels`, `GetIntegeri_v`** — and `Present` **only if the
scenario ends with `HeadlessGL::EndFrame()`**. The spec as written does not, which would make B
a strict subset of A minus `Present`. **Decide that deliberately**: a reduced path whose
"minimal" case exercises fewer slots than its predecessor is fine, but it should be a choice.
Everything else the scenario calls reaches no verb slot: the buffer, VAO, program and texture
traffic is the `MG_Impl/Pipe` → `MGPipeApply*` family (37 entry points), which `EmitTables.h`
says this table deliberately does not cover, and the rest is answered in the frontend.
`glGetProgramiv` is deliberately not a slot (`BackendObject.h:206-212`).
### D — OpenRA trace, SSIM ≥ 0.99 — **measured**
`tools/trace_replay/trace_cases.json:14-28`: `openra.trace`, target call 31,249, 640×480, crop
(1,1,638,478), threshold 0.99, 180 s.
**The fixture is hydrated in this tree and is the only one that is** — `openra.tgz` is 7,232,355
bytes with gzip magic, `openra.0000031249.png` is 403,752 bytes. Every other `.tgz` there is a
130–134-byte LFS pointer. Nothing was fetched.
`apitrace dump` over the whole trace: **70,465 calls, 51 distinct entry points** (46 GL + 5
GLX). Up to call 31,249 the *set* is identical and the counts scale about 4:1.
The only entry points that reach a verb slot:
| entry point | calls (whole trace) | slot |
|---|---|---|
| `glDrawArrays` | 3,648 | `DrawArrays` |
| `glClear` | 128 | `Clear` |
| `glXSwapBuffers` → the harness's `eglSwapBuffers` (`tools/trace_replay/apitrace_glws_egl.cpp:317`) | 128 | `Present` |
| first `glCompileShader` | 14 total, 1 capture | `GetIntegeri_v` |
Plus `ReadPixels`, contributed by the **snapshot harness** rather than by OpenRA:
`tools/trace_replay/apitrace_fbo_dump.cpp:383`. (That file also has a `glGetTexImage` arm at
`:337`/`:349` for texture-attachment snapshots, which would reach `GetTexImage`; the
default-framebuffer path takes the `glReadPixels` arm.)
**OpenRA is the thinnest of the three targets, not the widest.** Its bulk — 20,055
`glVertexAttribPointer`, 7,296 `glBlendEquation`, 6,685 `glBindBuffer`, 4,866 `glUseProgram`,
4,828 `glBindTexture`, 3,030 `glBufferSubData`, all program and texture traffic — is entirely
the `MGPipeApply*` family. It widens the **site** set and the **record** set enormously and the
**verb** set not at all, which is exactly what `scout-unmigrated-census:§3` predicted for the
field set and is here confirmed for the slot set. The framebuffer work (calls 1348–1382) never
blits or clears an attachment through the table.
---
## Blast radius of the 65 Fatal slots
Of the 69 GL slots, **28 are called with no null check at all** and 41 are guarded.
- For the **28 unguarded** — the 18 draw entries, the five `ClearBuffer*`/`Clear`,
`BlitFramebuffer`, `CopyTexImage2D`, `CopyTexSubImage2D`, `GenerateMipmap`, `ReadPixels` — a
`Fatal` slot is **strictly better than today**: a null there is already an immediate crash
with no diagnostic.
- For the **41 guarded**, a `Fatal` slot is a real behaviour change, from "degrade quietly" to
"abort". The families that degrade today are sync (`FenceSync` → always-signaled),
query (`IsQueryResultAvailable` → reported available), `GetTexImage`/`GetTextureImage` (CPU
fallback), and transform feedback (silently skipped). **That change is R-4's intent** — a
silent degrade is how a split lane produces the right picture for the wrong reason — but it is
worth naming, because those are also the families most likely to be hit by an integration test
that is not on the reduced path.
## Counting notes
- **89** direct `gBackendFunctionsTable.GL.*` call sites in `MG_Impl/`, not the 91 the scout
reported; **0** of them are in `MG_Impl/Pipe/` (the two hits there are comments about the
`MGP_FILL` convention). Distribution: `GL_Drawing.cpp` 36, `GL_Query.cpp` 22,
`GL_Framebuffer.cpp` 11, `GL_Texture.cpp` 10, `GL_Sync.cpp` 6, `GL_Getter.cpp` 3,
`GL_Program.cpp` 1.
- **No** GL slot has zero `MG_Impl` call sites. The zero-call-site result belongs to `Present`
and `SetSwapInterval` (trap 3) and to `GetIntegeri_v`'s out-of-tree caller (trap 2).
- `PrefersCpuXfbPrimitiveAccounting` is not a verb: one non-test reader, `GL_Query.cpp:221`.