Files
MobileGL/docs/Disaggregated/notes/p3a/scout-espryt-vao.md
T
swung0x48 aba329cc53 [Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository
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.
2026-09-18 23:31:39 -04:00

42 KiB
Raw Blame History

P3a scout — Espryt's vertex-array surface

Worktree: C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg, branch feat/disaggregated. Every line number below was opened. Paths are repo-relative to MobileGL/ unless they start with docs/.


0. One-paragraph shape

Espryt has no vertex-elements CSO. It has a per-VAO twin object (BackendVertexArrayObject) that owns one driver VAO name plus per-attribute scratch buffers, and that twin re-emits glVertexAttribPointer / glEnable|DisableVertexAttribArray / glVertexAttribDivisor / glBindBuffer(GL_ELEMENT_ARRAY_BUFFER) into the driver VAO whenever a version compare says the frontend moved. So the three things P3a wants to separate — vertex elements (format), vertex buffers (which store + offset + stride), and the index buffer — are today one fused emit inside BackendVertexArrayObject::SyncToBackend, gated by one Uint32 config version plus one Uint16 index-slot version plus one global buffer-id generation. That fusion is the P3a work.


1. How a draw resolves its vertex input today

1.1 The draw prologue

PrepareForDraw — MG_Backend/DirectGLES/DirectGLES.cpp:3163-3231 (decl Managers.h:105). Order of the vertex-relevant steps:

line step
DirectGLES.cpp:3169 const auto& currentVAO = MGB_CTX->GetBoundVertexArray();
DirectGLES.cpp:3170-3171 vaoTwin = VertexArrayImpl::ResolveVaoTwin(currentVAO) — one twin resolve serves the whole draw
DirectGLES.cpp:3176 early vaoConfigVersion = currentVAO->GetConfigVersion() (deliberate cold-line prefetch)
DirectGLES.cpp:3193-3195 BufferImpl::SyncNeccessaryBuffers(currentVAO, vaoTwin, vaoConfigVersion, syncBit & IndexBuffer, syncBit & IndirectBuffer)
DirectGLES.cpp:3196 VertexArrayImpl::SyncCurrentVAO(currentVAO, vaoTwin) → vaoTwin->SyncToBackend(...)
DirectGLES.cpp:3212-3220 vaoTwin->Bind(), else BindBackendVAOId(0)
DirectGLES.cpp:3222 VertexArrayImpl::SyncCurrentVertexAttributeValues(vaoTwin, currentProgram)

DrawSyncBit (Managers.h:74-83): None / IndexBuffer(1) / IndirectBuffer(2) / Instancing(4). Note the client-array upload is not here — it runs after PrepareForDraw at the draw entry point (§1.6).

1.2 ResolveVaoTwin — DirectGLES.cpp:1236-1268

Two arms:

  • MOBILEGL_PIPE_PUSH + EsprytSlotTablesEnabled() (DirectGLES.cpp:1240-1252): g_backendVertexArrayObjects.Find(vao.get()) → GetOrCreate(vao) → MakeShared<BackendVertexArrayObject>(). No lookup memo on this arm.
  • legacy (DirectGLES.cpp:1254-1266): g_vaoTwinLookupMemo.Lookup(vao) (a 4096-slot Fibonacci-hashed direct-map, declared DirectGLES.cpp:128-129, class at DirectGLES.cpp:~80-121) then the address-keyed registry.

SyncCurrentVAO — DirectGLES.cpp:1270-1283; it still calls g_backendVertexArrayObjects.CollectGarbageIfNeeded() at 1275 (legacy arm only — the slot arm has no GC, see SlotTables.h:37-48).

1.3 SyncNeccessaryBuffers — DirectGLES.cpp:572-707

Resolves the stores the draw fetches through. It is the ResolvedDrawBuffers memo host.

  • DirectGLES.cpp:601 const Uint64 bufferEpoch = CurrentBufferMutationEpoch(); (decl Managers.h:588, doc Managers.h:548-587)
  • DirectGLES.cpp:602-603 auto* memo = vaoTwin ? &vaoTwin->GetResolvedDrawBuffersMemo() : nullptr;
  • hit path 605-621: memo valid && configVersion matches → if vboCleanEpoch != bufferEpoch, re-probe each distinct entry with IsBufferDrawClean(entry.frontend, entry.resource) (Managers.h:675), and repair only the dirty ones via EnsureBufferResource(currentVAOObject->GetAttribute(entry.attribIndex).Buffer) (DirectGLES.cpp:613-614). Stamp vboCleanEpoch = allClean ? bufferEpoch : 0 (619).
  • miss path 622-664: full walk over GetAllAttributes() (629), skip !Enabled / null Buffer, dedupe by frontend BufferObject* into a MAX_VERTEX_ATTRIBS scratch (626-627, 634-642), EnsureBufferResource each (644), rebuild memo entries (645-651), memo->configVersion = configVersion; memo->valid = true; vboCleanEpoch = 0 (654-660).
  • IBO 666-694: currentVAOObject->GetIndexBufferBindingSlot().GetBoundObject() (669), matched on bound-object identity memo->iboFrontend == possibleIBO.get() plus iboCleanEpoch (673-687) — explicitly not covered by the config version.
  • indirect 696-703: binds GL_DRAW_INDIRECT_BUFFER from MGB_CTX->GetBufferBindingSlot(BufferTarget::DrawIndirect).
  • tail 705-706: SyncBufferBindingPoints(ShaderStorage, GL_SHADER_STORAGE_BUFFER) + MarkShaderStorageBuffersGpuWritten(). UBO binding points are deliberately not synced here (comment 696-704) — the program rebind does it.

1.4 ResolvedDrawBuffers — Managers.h:833-869

struct Entry { BufferObject* frontend; GLESBufferResource* resource; Uint8 attribIndex; }  // Managers.h:849-853
Bool valid; Uint32 configVersion; Uint count; Array<Entry, MAX_VERTEX_ATTRIBS> entries;    // 854-857
BufferObject* iboFrontend; GLESBufferResource* iboResource;                                 // 858-859
Uint64 vboCleanEpoch; Uint64 iboCleanEpoch;                                                 // 866-867

Accessor GetResolvedDrawBuffersMemo() Managers.h:870; member m_resolvedDrawBuffers Managers.h:911. Key: VAO config version for the VBO half, bound-object identity + epoch for the IBO half.

PendingAttribValueMask — Managers.h:872-887 ({valid, configVersion, activeMask, pendingMask}), accessor Managers.h:884, member Managers.h:912; consumed by SyncCurrentVertexAttributeValues.

1.5 BackendVertexArrayObject::SyncToBackend — Managers.cpp:2419-2647

This is the function P3a converts into create/bind_vertex_elements_state + set_vertex_buffers + set_index_buffer.

Gate (Managers.cpp:2437-2470):

currentConfigVersion      = stateVAOObject->GetConfigVersion();                          // 2437
currentIndexBufferVersion = ...GetIndexBufferBindingSlot().GetVersion();  // Uint16      // 2438
currentBufferIdGeneration = BufferImpl::g_bufferBackendIdGeneration;                     // 2446
bufferIdsRemitted         = m_syncedBufferIdGeneration != currentBufferIdGeneration;     // 2447
attributesDirty  = bufferIdsRemitted || !m_hasSyncedConfigVersion || version mismatch    // 2448-2449
indexBufferDirty = bufferIdsRemitted || version mismatch || OBJECT-IDENTITY mismatch     // 2452-2456
baseInstanceDirty= m_syncedFetchBaseInstance != g_pendingFetchBaseInstance               // 2462-2463
emitAttributes   = attributesDirty || baseInstanceDirty || m_hasConvertedFloat64Attribute// 2467
if (!emitAttributes && !indexBufferDirty) return;                                        // 2468-2470

Per-attribute walk 2477-2617 over GetAllAttributeVersions() / GetAllAttributes():

  • SwitchVersion → glEnable/DisableVertexAttribArray (2489-2496)
  • FormatVersion / BufferVersion → format + buffer (2498-2502)
  • fp64 narrowing 2521-2542: attrib.IsLong || attrib.Type == Float64 → SyncFloat64AttributeAsFloat32; on failure the array is disabled (Adreno SIGSEGV note 2495-2520, KHR-GL43.vertex_attrib_binding.basic-input-case4)
  • zero-stride 2545-2560: attrib.Stride == 0 && HasVertexBindingApi() → SyncZeroStrideAttribute (binding-point API)
  • BindAttributeBuffer (Managers.cpp:2330-2346) then glVertexAttribPointer / glVertexAttribIPointer at fetchOffset = attrib.Offset + BaseInstanceByteShift(attrib, fetchBaseInstance) (2586-2600)
  • BGRA refusal probe 2568-2582 + 2602-2611: glGetError drain, attempt, re-check, disable on refusal (basic-input-case5). Deliberately the only format that pays a glGetError round trip.
  • glVertexAttribDivisor on needsSyncFormat (2613-2615)

Index half 2618-2638: EnsureBufferResource(indexBufferBinding) → BufferImpl::BindBufferId(GL_ELEMENT_ARRAY_BUFFER, id), else glBindBuffer(GL_ELEMENT_ARRAY_BUFFER, 0); stamps m_syncedIndexBufferVersion + m_syncedIndexBufferObject (2634-2637). Stamps at 2640-2646.

Twin private state — Managers.h:906-953:

m_resolvedDrawBuffers, m_pendingAttribValueMask                                  // 911-912
Uint m_backendVAOId                                                              // 913
Array<Uint,32> m_clientAttributeBufferIds                                        // 914
Array<Uint,32> m_convertedAttributeBufferIds                                     // 918
Array<ConvertedFloat64Stream,32> m_convertedAttributeStreams                     // 919-920
Bool m_hasConvertedFloat64Attribute                                              // 924
Uint16 m_syncedIndexBufferVersion                                                // 927
const BufferObject* m_syncedIndexBufferObject   (raw, never dereferenced)        // 931
Bool m_hasSyncedConfigVersion; Uint32 m_syncedConfigVersion                      // 937-938
Array<VertexAttributeVersion,32> m_syncedAttributeVersions                       // 939-940
Uint32 m_syncedFetchBaseInstance                                                 // 946
Uint64 m_syncedBufferIdGeneration                                                // 952

ctor/dtor Managers.cpp:2259-2296 (glGenVertexArrays; dtor deletes the VAO name and both scratch-buffer arrays, early-returns under InProcessTeardown()). Bind() Managers.cpp:2323-2327 → BindBackendVAOId shadow (Managers.cpp:2303-2312), InvalidateVAOBindingCache 2314-2316, NoteVAOIdDeleted 2318-2321.

1.6 Client-array upload path

BackendVertexArrayObject::SyncClientSideAttributesForDrawArrays(vao, first, count) — Managers.cpp:2651-2755 (decl Managers.h:831-832). Selects attrib.Enabled && !attrib.Buffer (2662-2664), then:

  • fp64 client array 2670-2715: NarrowDoubleStreamToFloat32 → glBufferData(GL_STREAM_DRAW) into m_clientAttributeBufferIds[attribIndex], counts PipeStats::ByteClass::StageVertexClient (2701-2704)
  • ordinary 2717-2752: uploadSize = (first + count - 1) * stride + elementSize (2726) — this is the exact formula ARCHITECTURE.md 5.7 assigns to the client; glBufferData then glVertexAttribPointer(..., nullptr); bytes counted at 2740-2743.

Call sites (both after PrepareForDraw, both re-Find the twin instead of reusing the resolve):

  • DrawArrays — DirectGLES.cpp:4805-4821 (Find at 4814, call at 4817)
  • MultiDrawArrays — DirectGLES.cpp:4837-4866, per sub-draw range (Find at 4855, call at 4857)

There is no client-array upload on any DrawElements* path — SyncClientSideAttributesForDrawArrays is the only uploader and only DrawArrays/MultiDrawArrays call it.

1.7 fp64 vertex narrowing

SyncFloat64AttributeAsFloat32 — Managers.cpp:2757-2874 (decl Managers.h:889-892).

  • bufferObject->SyncGpuWrites() before reading the shadow (2776); MappedData() / GetSize() (2777-2778)
  • stride-0 = "never advances" → exactly one element converted (2793-2796)
  • baseInstance folds into firstElement (2800-2806)
  • memo ConvertedFloat64Stream keyed on {sourceLifetimeId, sourceChangeSerial, sourceOffset, sourceStride, componentCount, elementCount} and never trusted for a persistently mapped buffer (2812-2820)
  • emits StageVertexClient bytes (2839-2845)
  • stride-0 output requires the binding API (2857-2866), else glVertexAttribPointer with normalized = GL_FALSE deliberately (2869-2873, basic-input-case5)

1.8 SyncCurrentVertexAttributeValues — DirectGLES.cpp:1291-1348

Feeds glVertexAttrib4fv / I4iv / I4uiv for program-active locations with no enabled array, from MGB_CTX->GetCurrentVertexAttribute(location) (1329). Memo keyed on {VAO config version, program active-attrib mask} (1311-1323). This is the read that set_vertex_attrib_defaults (already landed at P2) supplies.

1.9 Complete list of Espryt reads of frontend vertex state

Every MG_Backend/DirectGLES read of VertexArrayObject / VertexAttribute / VertexBufferBindingPoint:

file:line read
DirectGLES.cpp:128-129 TwinLookupMemo<VertexArrayObject, BackendVertexArrayObject, 12> (legacy arm)
DirectGLES.cpp:572-573 SyncNeccessaryBuffers(SharedPtr<VertexArrayObject>&, BackendVertexArrayObject*, ...)
DirectGLES.cpp:613-614 GetAttribute(entry.attribIndex).Buffer
DirectGLES.cpp:626-627 MAX_VERTEX_ATTRIBS dedupe scratch
DirectGLES.cpp:629 GetAllAttributes()
DirectGLES.cpp:669 GetIndexBufferBindingSlot().GetBoundObject()
DirectGLES.cpp:1236-1266 ResolveVaoTwin
DirectGLES.cpp:1270-1283 SyncCurrentVAO
DirectGLES.cpp:1291-1348 SyncCurrentVertexAttributeValues (1312 config version, 1317 GetAttribute(location).Enabled)
DirectGLES.cpp:3169-3176 GetBoundVertexArray(), GetConfigVersion()
DirectGLES.cpp:4624 BoundElementArrayBuffer() → GetIndexBufferBindingSlot().GetBoundObject() (restart path)
DirectGLES.cpp:4814, 4855 g_backendVertexArrayObjects.Find(currentVAO.get()) (client arrays)
Managers.cpp:210 death-notice case MGPipeKind::VertexElementsCso
Managers.cpp:2330 BindAttributeBuffer(const VertexAttribute&)
Managers.cpp:2377 BaseInstanceByteShift(const VertexAttribute&, Uint32)
Managers.cpp:2387 SyncZeroStrideAttribute(Uint, const VertexAttribute&)
Managers.cpp:2437-2438, 2453 config version, index-slot version, index bound object
Managers.cpp:2477-2478 GetAllAttributeVersions(), GetAllAttributes()
Managers.cpp:2619 index bound object (emit)
Managers.cpp:2659 GetAllAttributes() (client arrays)
Managers.cpp:2758 SyncFloat64AttributeAsFloat32(..., const VertexAttribute&, ...)
Managers.cpp:2877-2878 TwinRegistry<VertexArrayObject, BackendVertexArrayObject, MGPipeKind::VertexElementsCso> g_backendVertexArrayObjects
Managers.h:826-955 class + registry decl
BackendObject_DirectGLES.cpp:1391 VertexArrayObject::MAX_VERTEX_ATTRIBS clamp for the advertised limit
MultiDraw.cpp:98 GetIndexBufferBindingSlot().GetBoundObject()

Finding. Neither Espryt nor Magma reads VertexBufferBindingPoint, GetAttributeBindingIndex or GetAttributeRelativeOffset — grep over MG_Backend/DirectGLES and MG_Backend/DirectVulkan returns nothing. The frontend resolves the binding model eagerly into the flat VertexAttribute view (VertexArrayObject.cpp:229-260 ResolveAttributeFromBinding, 262-269 ResolveAttributesForBinding, 146-181 MirrorPointerIntoBinding). See §4.2 for why this matters to the "two views" requirement.


2. After P2's Espryt 0b slot tables

2.1 Which kind holds the VAO twin

MG_Backend/DirectGLES/Managers.cpp:2877-2878:

TwinRegistry<MG_State::GLState::VertexArrayObject, BackendVertexArrayObject,
             MG_Pipe::MGPipeKind::VertexElementsCso> g_backendVertexArrayObjects;

decl Managers.h:954-955. So MGPipeKind::VertexElementsCso (MG_Pipe/MGPipeHandles.h:31) is today the slot space of the per-VAO twin, one slot per live frontend VertexArrayObject, minted off GetLifetimeId().

TwinRegistry is an alias that swallows the kind in a pull build: Managers.h:543-549; the class carries BackendSlotTable<StateObject, BackendObject, kKind> m_slotTable only under MOBILEGL_PIPE_PUSH (Managers.h:299-305, macro MGB_TWIN_KIND_PARAM Managers.h:293-297).

BackendSlotTable — MG_Backend/DirectGLES/SlotTables.h:139-...: GetOrCreate SlotTables.h:207-243 (MGPipeSlots().Acquire(kKind, stateObj->GetLifetimeId()) at 225-226, gen mismatch resets the twin at 229-233); Find 246-253; FindByHandle 255-262; HandleOf 272-281; OnFrontendObjectDestroyed (static, per-kind, walks every holder) 295-310; ForEachLive 326-345; ReleaseTwinAt 352-374; one-entry lifetimeId→handle memo m_memoLifetimeId/m_memoHandle 429-431 (the comment at 407-428 names ResolveVaoTwin as one of the two callers the single-entry memo does help).

Arm selection: ClassifyEsprytSlotArm (SlotTables.h:86-98, impl Managers.cpp:224-...), EsprytSlotTablesEnabled() inline latch SlotTables.h:131-134, subsystem bit kMGPipeSubsystemEsprytSlots = 1ull << 5 (MG_Pipe/MGPipe.h:77).

2.2 Death announcement

VertexArrayObject::~VertexArrayObject() — MG_State/GLState/VertexArrayState/VertexArrayObject.cpp:42-54, raising NotifyStateObjectDestroyed(MG_Pipe::MGPipeKind::VertexElementsCso, m_lifetimeId) (53). Declared only under push (VertexArrayObject.h:26-31, so the pull build keeps its implicit destructor for G1). Consumer: OnFrontendStateObjectDestroyed — Managers.cpp:191-217, VAO case at 209-211 (g_backendVertexArrayObjects.DestroyByLifetimeId(lifetimeId)); ops table Managers.cpp:219-221.

2.3 Recorded debt P3a inherits

SlotTables.h:68-78 — the header is under MG_Backend/ yet it mints handles off a frontend SharedPtr's GetLifetimeId(), which MGPipeHandles.h:13-16 forbids ("minted by the CLIENT"). Its own comment says the minting and the lifetimeId→handle resolution belong on the client and the backend should receive the handle in the verb payload — i.e. exactly what P3a is supposed to do for the VAO kind. check_include_closure.py does not probe MG_Backend headers, so nothing catches this automatically.


3. Index-buffer handling (and the P8 host-mirror hooks)

3.1 The element-array binding

Owned by the VAO twin (§1.5, Managers.cpp:2618-2638). Its freshness key is { BindingSlot::GetVersion() (Uint16, wrapping), bound-object raw pointer identity } — Managers.h:922-931 explains why identity joins the version (BindingSlot lives at MG_Util/Types.h:181-204, m_version is a Uint16 bumped only on a real change, Bind() at 189-195, GetVersion() at 198). SetIndexBuffer being independent of the VAO config version (D5, docs/Disaggregated/ARCHITECTURE.md:99) matches what the code already does — the index slot is explicitly not covered by m_configVersion.

Trap that any P3a re-emit must preserve: two paths temporarily swap the element-array binding and must restore the exact previous GL name, because the twin memoised that it already synced it:

  • ScopedRestartIndexSubstitution::~ScopedRestartIndexSubstitution — DirectGLES.cpp:4788-4791 (previous name captured at 4776 via BoundElementArrayBufferId(), DirectGLES.cpp:4629-4634)
  • MultiDrawImpl — MultiDraw.cpp:101-109 (BoundIndexBufferId, comment states the memo hazard verbatim) and MultiDraw.cpp:929-937 (flattened-stream draw restores previousIndexBinding).

3.2 Primitive-restart rewrite (server-owned at P8, client today)

docs/Disaggregated/ARCHITECTURE.md:222 assigns restart rewrite to the server, reading through the index host mirror (ARCHITECTURE.md:383-391), with kCapNeedsHostIndexBytes as the switch (ARCHITECTURE.md:106) and kMGHostSpanSegFromServerIndexMirror = 0xFFFFFFFF (MG_Pipe/MGPipeHostSpan.h:26) as the "bytes are already yours" sentinel.

Today, in Espryt:

  • RestartSubstitutionKind ResolveRestartSubstitution(GLenum) — DirectGLES.cpp:4636-4653 (None / SuppressRestart when restartIndex > fixedMax / RewriteIndices)
  • ScopedSuppressedPrimitiveRestart — Managers.h:~130-145, impl DirectGLES.cpp:4657-4673 (toggles GL_PRIMITIVE_RESTART_FIXED_INDEX around the render-state shadow)
  • ScopedRestartIndexSubstitution — decl Managers.h:157-194, ctor DirectGLES.cpp:4675-4786, dtor 4788-4791
    • kMaxRestartRewriteBytes = 1<<26 (64 MiB) — DirectGLES.cpp:4510
    • EBO source: whole buffer is rewritten, never just the draw range (4691-4721), so a GPU-resident firstIndex still addresses the right element
    • the two reconcile calls P8 must reproduce: indexBuffer->SyncPersistentMappedRange(); indexBuffer->SyncGpuWrites(); then MappedData() — DirectGLES.cpp:4709-4713
    • client-pointer source: only the draw's own range (4722-4741)
    • widening UBYTE→USHORT→UINT when the source already contains the all-ones index (ContainsFixedRestartIndex 4553-4560, WiderIndexType 4515-4521, decision 4746-4764)
    • RewriteRestartIndices 4562-4578; UploadRestartScratch 4580-4617 (whole-buffer glBufferData orphan into g_restartIndices, staged through BufferImpl::TempBufferTarget), byte counter PipeStats::ByteClass::StageIndexClient at 4610-4614
    • OnRestartSubstitutionContextDestroyed 4655-4659
  • Call sites: DirectGLES.cpp:4174 (indirect, count=0 → whole-EBO form), 4799, 4830, 5099, 5112, 5137, 5159, 5174, 5191.

3.3 Multi-draw flattening (server-owned at P8, client today)

MG_Backend/DirectGLES/MultiDraw.{h,cpp}. Tier ladder documented MultiDraw.h:15-31: Ext / MultiIndirect / Indirect / BaseVertex / DrawElements / Compute.

  • DrawElementsBatch — MultiDraw.cpp:897-992 (the whole entry point, owns PrepareForDraw at 927)
  • ResolveTierForBatch(programReadsDrawID, perSubDrawBaseVertex, hasIndexBuffer, arbitraryRestart) — MultiDraw.cpp:294-347; arbitrary restart forces the rewriting tier (303-307); batched tiers demote when the program reads gl_DrawID / per-sub-draw base vertex (316-324)
  • RunRebasedDrawElements — MultiDraw.cpp:492-...; the CPU index read: indexBuffer->SyncPersistentMappedRange(); indexBuffer->SyncGpuWrites(); MappedData(); GetSize(); — MultiDraw.cpp:508-514. RebaseIndices MultiDraw.cpp:353-380 (always widens to GL_UNSIGNED_INT).
  • FlattenWithCompute — MultiDraw.cpp:690-...; declines on non-list modes (701-704), on active restart (706-717), and with no real index buffer (719-722)
  • Ceilings: kMaxFlattenedIndices = 1<<24 (MultiDraw.cpp:74), kComputeWorkGroupSize = 64 / kMaxComputeWorkGroups = 65535 (MultiDraw.cpp:81-84)
  • BoundIndexBuffer / BoundIndexBufferId MultiDraw.cpp:94-109, BoundDrawIndirectBufferId 86-92

3.4 baseInstance emulation (the thing set_vertex_buffers' explicit field retires)

  • g_pendingFetchBaseInstance — Managers.cpp:2358; SetPendingFetchBaseInstance / GetPendingFetchBaseInstance Managers.cpp:2360-2366; decl + doc Managers.h:970-983 (ScopedFetchBaseInstance at 976-982)
  • BaseInstanceByteShift — Managers.cpp:2377-2383: baseInstance * attrib.Stride, only for Divisor != 0, zero for a stride-0 array
  • applied at Managers.cpp:2586 (fetchOffset) and inside the fp64 path at Managers.cpp:2800-2806
  • EmulatedFetchBaseInstance — DirectGLES.cpp:5128-5130 (returns 0 when GL_EXT_base_instance exists, UseNativeBaseInstance 5122-5124); scopes at DirectGLES.cpp:5135, 5172, 5224
  • The shift is baked into the driver VAO's attribute offsets, is draw state, and is deliberately not covered by any frontend version (Managers.h:941-946). Un-shifting on the next non-baseInstance draw is why baseInstanceDirty exists (Managers.cpp:2462-2463).

4. The MGPipe side as it exists

4.1 Catalogue entries (all present, none implemented)

MG_Pipe/PipeCalls.def:

95:  X(CreateVertexElements,     MGPVertexElements,       kCtxCso,   kHasBlob)
96:  X(BindVertexElements,       MGPHandleOnly,           kCtxCso,   kNone)
97:  X(DeleteVertexElements,     MGPHandleOnly,           kCtxCso,   kNone)
108: X(SetVertexBuffers,         MGPVertexBuffers,        kCtxState, kVarTail)
109: X(SetIndexBuffer,           MGPIndexBuffer,          kCtxState, kNone)
117: X(SetVertexAttribDefaults,  MGPVertexAttribDefaults, kCtxState, kVarTail)   // landed at P2

Generated: dispatch-table members generated/PipeTables.inc:43-45, 55-56; thunks generated/PipeThunks.inc:96-105, 144-149; wire opcodes generated/PipeWire.inc:66-68 (20/21/22) and 78-79 (32/33), wire record PipeWire.inc:273-279; field verifier generated/PipeVerify.inc:62, 148, 376-378.

gMGPipeContext (MG_Pipe/MGPipe.h:97) is never populated anywhere outside MG_Test/Pipe/PipeCatalogueTest.cpp:102. P2 does not emit through the table — it calls the applier directly (MG_Pipe/PipeApply.h:100-121: MGPipeApplyCreateRenderState, …BindRenderState, …DeleteRenderState, …SetDynamicState, …SetPixelPackState, …SetPatchState, …SetVertexAttribDefaults, …SetResidualValueState). P3a's applier entry points follow that same shape, with MGPipeApplierState at PipeApply.h:47-86.

4.2 Payloads

MG_Pipe/MGPipeTypes.h:

253-259  MGPVertexElements { MGPipeHandle Cso; Uint32 AttributeCount; Uint32 BindingPointCount; MGPBlobRef Blob; }  // 40 B
356-364  MGPVertexBuffer   { MGPipeHandle Res; Uint64 Offset; Uint32 Stride, Divisor, BindingIndex, Pad0; }         // 32 B
367-371  MGPVertexBuffers  { Uint32 Start, Count; Uint64 ContentHash; }                                            // 16 B
374-380  MGPIndexBuffer    { MGPipeHandle Res; Uint64 Offset; Uint32 IndexSize, Pad0; }                             // 24 B
484-488  MGPVertexAttribDefaults { Uint32 Mask, Count; }                                                           //  8 B
714-728  MGPDrawInfo (56 B), 731-735 MGPDrawRange (12 B)

Draw flags MGPipeTypes.h:701-707: kDrawHasUserIndices / kDrawPrimitiveRestart / kDrawIndicesAreClient / kDrawHasIndexRange / kDrawHasXfbCount.

The two views the roadmap means (docs/Disaggregated/ROADMAP.md:19 "vertex elements 三件(两个视图都带)", ARCHITECTURE.md:130) are the two arrays concatenated in MGPVertexElements::Blob:

  1. the resolved flat MG_State::GLState::VertexAttribute[] — MG_Pipe/MGPipeValueTypes.h:491-527 (Enabled, Size, Type, Normalized, Stride, Offset, IsInteger, IsLong, IsBgra, Divisor, Buffer, plus query-only LegacyStride/LegacyPointer at 524-526 which the doc says stay client-side)
  2. VertexBufferBindingPoint[] — MGPipeValueTypes.h:530-538 (Buffer, Offset, Stride = 16 initial, Divisor)

VertexAttributeVersion (3× Uint16, size-asserted 6) — MGPipeValueTypes.h:540-544, assert 561-562.

Flag for the implementer. The stated reason both views must travel (pointer stride 0 = element size vs binding stride 0 = same element) is already resolved in the frontend: VertexAttribute::Stride is documented as the RESOLVED distance and a surviving 0 can only have come from the binding model (MGPipeValueTypes.h:496-507), and Espryt consumes exactly that (Managers.cpp:2545-2560). Today no backend reads the binding-point array at all (§1.9). So the second view is either (a) for the glGetVertexArrayIndexed* query path, which VertexArrayObject.h:88-104 keeps client-side anyway, or (b) forward-looking. Decide and record it before shipping a 2× blob for every VAO in a chunked-renderer workload.

Flag: baseInstance explicit field. ROADMAP.md:19 says "set_vertex_buffers(baseInstance 显式字段)", but MGPVertexBuffer (MGPipeTypes.h:356-364) has no baseInstance member. The only explicit field in the current catalogue is MGPDrawInfo::StartInstance (MGPipeTypes.h:719, PipeFields.def:189), which is on the draw verb, not on set_vertex_buffers. Either the roadmap line means "the fetch shift stops being folded into the vertex-buffer offsets and travels as MGPDrawInfo::StartInstance" — which is what the payloads support — or MGPVertexBuffer needs a field, which changes an already-size-asserted POD. Resolve explicitly; MGPVertexBuffer at 32 B has a Pad0 at MGPipeTypes.h:362 that could take it without moving the assert.

4.3 CSO caching

ARCHITECTURE.md:57 sets the client-side content-addressed CSO capacities (render-state 64 / vertex-elements 1024 / sampler 256 / sampler-view 4096). MG_Impl/Pipe/CsoCache.h implements only the render-state cache (kMGPipeCsoCacheCapacity = 64, CsoCache.h:53; eviction at 140). There is no vertex-elements cache yet, and the negative control bit is kMGPipeBehaviourNoCsoContentAddressing (CsoCache.h:30-37).

Slot minting: MG_Impl/Pipe/SlotAllocator.h:39-99 — FindByLifetimeId 53, Acquire 55, Free 60, FreeCount 71, singleton MGPipeSlots() 99.


5. What the tracker already pushes for VAOs (P2)

MG_Impl/Pipe/Tracker.h:

  • dirty enum — Tracker.h:56-84; the vertex rows: NewVertexAttribDefaults 63, NewVertexElements 65, NewVertexBuffers 70, NewIndexBuffer 71
  • names — Tracker.h:96-114 ("NEW_VERTEX_ATTRIB_DEFAULTS" 100, "NEW_VERTEX_ELEMENTS" 101, "NEW_VERTEX_BUFFERS" 105, "NEW_INDEX_BUFFER" 106)
  • kMGPipeDirtyEmittedAtP2 — Tracker.h:91-97: only the five value bits, vertex elements / buffers / index are computed and counted but not emitted; MGPipeSubsystemForDirty returns 0 for them (Tracker.h:122-136, default arm 132-135)
  • the shutters, MGPipeTracker::Update — Tracker.h:178-...:
Tracker.h:210-213  vaoIdentity = vao ? MGPipeMixShutter(vao->GetLifetimeId(), vao->GetConfigVersion()) : 0;
                   now[NewVertexElements] = vaoIdentity;
Tracker.h:243-244  now[NewVertexBuffers]  = MGPipeMixShutter(ctx.GetAnyVaoAttributeGeneration(), vaoIdentity);
Tracker.h:245-248  now[NewIndexBuffer]    = MGPipeMixShutter(buffers, vaoIdentity);   // over-fires on ANY buffer write
Tracker.h:208      now[NewVertexAttribDefaults] = ctx.GetAnyVertexAttribDefaultGeneration();

MGPipeMixShutter Tracker.h:143-146; MGPipeWidenedCounter Tracker.h:158-176. The over-fire policy is stated at Tracker.h:27-33 — a rarely-firing bit renders stale and P1's verify comparator cannot see it for object-class state.

FillPoints.def kDraw rows relevant to vertex state — MG_Pipe/FillPoints.def:152-199: GetBoundVertexArray 154, GetProgramForDraw 155, GetBufferBindingSlot 156, GetCurrentVertexAttribute 165, GetPrimitiveRestartIndex 193. (kDispatch, GetBufferBindingSlot 204; kReadback, GetBufferBindingSlot 289.)

Coverage.def — accessor→call map: GetBoundVertexArray → BindVertexElements (Coverage.def:36); GetBufferBindingSlot → SetIndirectBuffers with the note at 37-41 that its rows split across set_vertex_buffers / set_index_buffer / set_indirect_buffers / set_shader_buffers once the inventory is re-vendored with the target argument (deferred out of P1 — P3a is where that split lands); GetCurrentVertexAttribute → SetVertexAttribDefaults 52; GetPrimitiveRestartIndex → DrawVbo 70. Emitted list Coverage.def:158-192 contains no vertex-elements/buffers/index row yet (GetCurrentVertexAttribute → SetVertexAttribDefaults 164 and GetPrimitiveRestartIndex → SetDynamicState 178 are the only vertex-adjacent ones).

PipeInputs side — MG_Backend/MGPipe/PipeInputs.h: field list rows 79 (GetBoundVertexArray → m_boundVertexArray), 80 (GetBufferBindingSlot), 89 (GetCurrentVertexAttribute), 107 (GetPrimitiveRestartIndex); accessors 477-481, 487-493, 274-283, 369-372; storage 641, 658, 678-679; kMaxVertexAttribs 175. Fill: MG_Impl/Pipe/PipeFill.cpp:80-82 (bound VAO), 83-91 (buffer binding slots), 126-129 (current attribs); aggregate note dispatch PipeFill.cpp:537-538.


6. The P2 aggregate generations that cover vertex state

generation owner declaration bumped from
VertexArrayObject::m_configVersion (Uint32, per object) frontend VertexArrayObject.h:107 (getter), :214 (member) the three Bump*Version — VertexArrayObject.cpp:313-332
per-attribute VertexAttributeVersion{Format,Buffer,Switch} (Uint16×3) frontend MGPipeValueTypes.h:540-544; array member VertexArrayObject.h:207 same three bumpers
VertexArrayState::m_anyVaoAttributeGeneration (Uint64) frontend VertexArrayState.h:36-42 (NoteAttributeChanged / GetAnyAttributeGeneration), member :44 MGP_NOTE_AGGREGATE(VaoAttribute) inside all three bumpers (VertexArrayObject.cpp:317, 324, 331)
BufferState::m_anyBufferChangeGeneration (Uint64) frontend BufferState.h:72-78 every buffer mutator
index slot BindingSlot::m_version (Uint16, wraps) frontend MG_Util/Types.h:198, 202 BindingSlot::Bind Types.h:189-195
BufferImpl::g_bufferBackendIdGeneration (Uint64) backend Managers.h:701-707 driver-id re-mint (persistent-map adoption, immutable-store retire)
buffer-mutation epoch (CurrentBufferMutationEpoch()) backend Managers.h:548-588 any path that can dirty any buffer
VertexArrayObject::m_lifetimeId (Uint64, never reused) frontend VertexArrayObject.h:70 (GetLifetimeId), member :205; allocator :203 ctor

How a server-side VAO object table would be keyed

  • Handle: MGPipeHandle{Slot, Gen} of kind VertexElementsCso, minted client-side off GetLifetimeId() (SlotTables.h:225-226), freed on the destructor notice (VertexArrayObject.cpp:53), so the server table is a dense array indexed by Slot with a Gen compare — exactly BackendSlotTable::Entry (SlotTables.h:145-158) and MGPipeApplierState::RenderStateCsos (PipeApply.h:47-51) already do this shape for render state.
  • Freshness inside a slot: today the twin's own {m_syncedConfigVersion, m_syncedAttributeVersions[32], m_syncedIndexBufferVersion + m_syncedIndexBufferObject, m_syncedFetchBaseInstance, m_syncedBufferIdGeneration} (Managers.h:906-952). Under P3a the elements half becomes a content hash on the client (CsoCache-shaped) and the buffers/index halves become MGPVertexBuffers::ContentHash (MGPipeTypes.h:370) + a plain set_index_buffer, so m_syncedConfigVersion / m_syncedAttributeVersions / m_syncedIndexBufferObject all disappear — but g_bufferBackendIdGeneration does not: it answers "did I re-mint the driver id", which is a server-side MGGen and must never cross the wire (ARCHITECTURE.md:73-79).
  • ARCHITECTURE.md:363 records that SetBackendStateMemo (the frontend VAO holding a backend heap pointer) is deleted outright; the three legacy memos on the frontend object are VertexArrayObject.h:110-175 (GetBackendHashMemo/SetBackendHashMemo 121-129, GetBackendStateMemo/Set… 137-149, GetBackendAuxMemo/Set… 160-172, storage 216-225), all under MOBILEGL_PIPE_LEGACY_MEMOS.

7. Tests

7.1 Integration scenarios (MG_IntegrationTest/Scenarios/) — gtest TEST_F

VertexAttribBindingScenario.cpp (758 lines; every case captures the vertex shader's inputs with XFB under GL_RASTERIZER_DISCARD, poison-prefilled buffer — header note :8-17): FormatAndBindingFeedTheDraw 241, FormatBeforeBufferStillResolves 269, BindingStrideZeroRepeatsOneElement 297, PointerStrideZeroStaysTightlyPacked 324, BindingDivisorAppliesToEveryAttributeOnThePoint 349, BaseInstanceMovesTheInstancedArraysStartElement 406, BaseInstanceLeavesPerVertexArraysWhereTheyWere 451, RelativeOffsetComposesWithBindingOffset 496, InputArrayCaptureProgramFeedsTheDraw 532, EveryInputArrayElementGetsItsOwnCurrentValue 617, DoubleArrayIsFetchedAtFloat32Precision 681, NormalizedIsIgnoredForDoubleArrays 708, LongDoubleArrayIsFetchedAtFloat32Precision 734.

VertexArrayEnableDisableScenario.cpp: EitherHalfOfTheAttributesInTurn 231, TheEvenHalfAlone 245, TheOddHalfAlone 255.

MultiDrawScenario.cpp: BaseVertexBatchMatchesUnrolledDraws 225, PlainBatchMatchesUnrolledDraws 253, UnsignedShortBatchMatchesUnrolledDraws 288, UnsignedByteBatchMatchesUnrolledDraws 317, BaseVertexBeyondIndexTypeRangeMatchesUnrolledDraws 357, ClientSideIndicesBatchMatchesUnrolledDraws 391, PrimitiveRestartStripBatchMatchesUnrolledDraws 423, PrimitiveRestartUnsignedShortBatchMatchesUnrolledDraws 456, ZeroCountSubDrawsMatchUnrolledDraws 493, BaseVertexDrawsRejectMalformedArguments 526.

PrimitiveRestartScenario.cpp: AnArbitraryRestartIndexDrawsInsteadOfKillingTheProcess 215, TheFixedIndexValueTakesTheForwardingPath 236, WithoutTheCapTheStripWeldsAcrossTheGap 263, ChangingTheRestartIndexBetweenDrawsIsHonoured 281, ANonIndexedListTopologyDrawIsUnaffectedByTheCap 306, ARestartIndexTooLargeForTheIndexTypeRestartsNowhere 332, AnAllOnesVertexIndexSurvivesTheSubstitution 368.

DrawParametersScenario.cpp (the gl_BaseInstance/gl_DrawID/gl_BaseVertex side of the same emulation): DrawArraysReportsAZeroBaseVertexDespiteItsFirst 213, DrawArraysInstancedBaseInstanceReportsItsBaseInstance 221, APlainDrawAfterABaseInstancedOneSeesZeroAgain 233, DrawElementsBaseVertexReportsItsBaseVertex 245, DrawElementsAfterABaseVertexDrawReportsZeroAgain 266, MultiDrawArraysNumbersItsSubDraws 286, MultiDrawElementsIndirectCarriesEveryCommandsParameters 301, MultiDrawArraysIndirectCountObeysItsParameterBuffer 327.

ResidentIndexScenario.cpp (element-array + persistent map — the closest thing to a P8 index-mirror gate): PersistentCoherentEboWrittenEveryFrame 186, EboAlsoBoundAsVertexBufferLater 225, EboDeletedAndRecreatedAtTheSameName 271, OneEboTwoVaosMutatedAcrossFrames 311, PromotedDynamicEbo 351.

HandleRecycleScenario.cpp: TheReproducerRecyclesEveryName 440, AVertexArrayAtARecycledAddressDoesNotInheritItsPredecessorsVertexInput 483 (the P2 re-key gate for this kind), ATextureAtARecycledAddress… 573, AFramebufferAtARecycledAddress… 624.

DoublePrecisionScenario.cpp vertex-array cases: A64BitVertexFormatIsRecordedAndItsArrayIsDroppedAtDraw 863, AnEnabledLongArrayDoesNotBreakADrawThatIgnoresIt 916.

Buffer-family scenarios the roadmap names for P3a: LargeArenaAdoptionScenario.cpp (SubDataAfterAnInFlightDrawReachesTheNextDraw 204, ReadbackSeesTheLatestCpuWrite 227, GpuWriteIntoTheArenaIsReadBack 245), StorageBufferRegrowScenario.cpp (AGrownStoreIsVisibleThroughItsExistingIndexedBinding 124).

7.2 Unit tests

  • MG_Test/VertexArray/VertexArrayTest.cpp (1366 lines, 46 cases) — frontend state. Cases most load-bearing for P3a: VertexAttributeSetup 124, IndexBufferBinding 156, MultipleAttributes 221, BoundVAOPreservesState 266, VertexBindingIndexIsBoundedByTheAdvertisedAttribLimit 322, DefaultAttributeBindingIsIdentityAcrossFullCapacity 338, General_ElementArrayBufferBindingIsVaoLocalAndZeroUnbinds 557, General_ClientSideVertexAttribPointerIsAccepted 602, General_ElementBufferBindingPoint 750, ArrayFormat_PackedStored 1207, ArrayFormat_BgraStored 1228, ArrayFormat_BindingAndRelativeOffsetAreQueryable 1324.
  • MG_Test/VertexArray/VertexAttribBindingStateTest.cpp (430 lines) — the two-view invariant: DefaultsMatchTheSpecInitialState 198, SeparateFormatSequenceKeepsLegacyStrideAndPointerAtZero 209, DivisorGoesThroughTheBindingPoint 318, BindingApiRejectsTheDefaultVertexArrayInCoreProfile 370, …StillAcceptsTheDefaultVertexArrayWhenRelaxed 395, RelaxedSemanticsOverrideReopensTheDefaultVertexArray 415.
  • MG_Test/SanityTest.cpp DirectGLESSlotTable suite (20 cases, 3311–4044). VAO-specific: EveryReKeyedObjectClassAnnouncesItsOwnDeath 3706 (VAO at 3727-3734), EverySwitchedOverKindResolvesItsTwinThroughTheHandleArm 3857 (VAO at 3878-3879), plus ARecycledSlotIsANewHandleAndTheStaleOneResolvesToNothing 3311, OneDeathNoticeDropsTheTwinInEveryHolderOfTheKind 3532, AnAnnouncedDeathReturnsTheSlotWithoutASweep 3657, EglBringUpUnderTheArmlessKnobPairReturnsInsteadOfStopping 4044.
  • MG_Test/Pipe/TrackerTest.cpp: TrackerAggregates.AVertexArrayAttributeMovesOnlyTheVaoAggregate 153 (skip-list row 55), AVertexAttribDefaultMovesOnlyItsOwnAggregate 213, TrackerWalk.WrapAroundRePushesButNeverMisses 384, TrackerAttribPayload.* 490-524.
  • MG_Test/Backend/DirectGLES/BaseInstanceInjectionTest.cpp — the shader-side baseInstance gate (77-155), not the fetch shift; MG_Test/SanityTest.cpp:469-609 covers the SPIR-V rewrites.
  • MG_Test/Pipe/SlotAllocatorTest.cpp, CsoCacheTest.cpp, PipeCatalogueTest.cpp (pins MGP_CALL_LIST_DOCUMENTED_COUNT = 71, PipeCalls.def:69) — the catalogue/allocator gates P3a must keep green.

8. Traps an implementer will hit

  1. The twin bakes driver ids into the driver VAO, keyed on FRONTEND versions. g_bufferBackendIdGeneration (Managers.h:701-707, read Managers.cpp:2446) exists solely because a backend-side re-mint moves no frontend version. A set_vertex_buffers keyed on client-side content hash alone reintroduces the bug commit d7655247 fixed. The generation must stay server-local.
  2. Element-array binding restore. ScopedRestartIndexSubstitution (DirectGLES.cpp:4788-4791) and MultiDrawImpl (MultiDraw.cpp:101-109, 929-937) restore the exact previous GL name because the twin memoised it. Whatever replaces the memo must keep an equivalent invariant, or the next draw silently draws through the scratch buffer.
  3. fp64 streams are content-derived and covered by no version. m_hasConvertedFloat64Attribute (Managers.h:919-924, set Managers.cpp:2530, cleared 2471) forces a full re-walk each draw while any such array is live. A pure content-hash CSO would go stale here.
  4. The zero-stride and BGRA paths are the two Adreno SIGSEGV corners (Managers.cpp:2495-2520, 2568-2611); both must survive the split, and the BGRA probe is the one glGetError on the draw path.
  5. Client arrays are resolved after PrepareForDraw, per draw range, and only for DrawArrays / MultiDrawArrays (DirectGLES.cpp:4805-4821, 4837-4866). The push ordering contract (ARCHITECTURE.md:194) allows this, but the emitted set_vertex_buffers for a client-array attribute names a store that does not exist until the draw entry point runs.
  6. SyncNeccessaryBuffers also does SSBO binding points and MarkShaderStorageBuffersGpuWritten() (DirectGLES.cpp:705-706) — unrelated to vertex input, and it must not be dragged into set_vertex_buffers.
  7. ResolveVaoTwin's single-entry handle memo. SlotTables.h:407-428 names ResolveVaoTwin as one of the two callers a one-entry memo helps, because PrepareForDraw resolves the same VAO once per draw. Two resolves per draw (e.g. adding a second lookup for the elements CSO) would thrash it.
  8. CollectGarbageIfNeeded at DirectGLES.cpp:1275 is legacy-arm-only; do not add a matching tick on the slot arm (SlotTables.h:37-48).