mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-20 00:11:56 +09:00
[Docs] (.claude/skills, .github/workflows, CMakeLists.txt, docs/archive, docs/Disaggregated, docs/MobileVA, docs/Performance, MG_Backend, MG_Backend/DirectGLES, MG_Backend/DirectVulkan, MG_Backend/Record, MG_Gbm, MG_Impl, MG_Impl/EGLImpl, MG_Impl/GLImpl, MG_Impl/GLXImpl, MG_Impl/Pipe, MG_IntegrationTest, MG_IntegrationTest/Harness, MG_IntegrationTest/Scenarios, MG_Pipe, MG_Pipe/generated, MG_Remote, MG_Remote/Client, MG_Remote/Server, MG_Remote/Transport, MG_Remote/Wire, MG_State/GLState, MG_Test/Pipe, MG_Test/Util, MG_Test/Wire, MobileGL, scripts, scripts/data, tools/device_bench, userguide): archive the planning notes and agent contracts under docs/archive
- DEBTS.md and OPEN-QUESTIONS.md stay maintained, now in docs/Disaggregated.
This commit is contained in:
@@ -0,0 +1,406 @@
|
||||
# MobileGL 前后端进程拆分实施计划(branch `feat/disaggregated`)
|
||||
|
||||
---
|
||||
|
||||
## 0. TL;DR 与核心决策
|
||||
|
||||
**Server 就是 `libMobileGL` 自己**,在自己的进程里跑一个**真实的 `MG_State::GLState::GLContext`(replica)**,由一个 delta applier 通过普通 MG_State mutator API 驱动。**两个 backend(DirectGLES 27k / DirectVulkan 40k 行)一行不改。** Client 也是同一个 `libMobileGL`,在 init 时换掉几个对象:`MG_Backend::gBackendFunctionsTable` 换成发射表,`MG_Backend::pActiveBackendObject` 换成 `BackendObject_Remote`,`SetBufferBackendOps` 换成发射 ops。一份产物,两个角色,由一个 env var 选择。
|
||||
|
||||
这样做的唯一理由是:**backend 的 draw-path 失效模型无法表达成 wire 字段。** DirectGLES 有 memo 直接借用 binding slot 的 `shared_ptr` 地址(`DirectGLES.cpp:1463-1477` `UnitTextureSyncEntry` + `PairingsIntact`);`VertexInputStateFactory.cpp:78` 把**后端堆上的裸指针**写进前端 VAO;`IsBufferDrawClean` 开头就是裸指针身份比较(`Managers.cpp:1435-1436`,注释:"Identity first: a respecify path can hand the frontend a NEW resource");三个门控计数器是回绕的 `Uint16`,只有配合指针身份比较才正确(`Managers.h:772-777`,postmortem 在 `DirectGLES.cpp:2823-2831`);`UniformManager.cpp:1418-1497` 构造并驱动真实 `TextureObject2D`;`VulkanRenderer.cpp:4211-4356` 通过真实 `ShaderObject`/`ProgramObject` 编译链接 GLSL。replica 逐字满足 DirectGLES 107/107、DirectVulkan 165/169 次 `pGLContext` 读取;重写则是把一套被文档记录为"具体设备 bug 疤痕组织"的失效模型重新推导一遍——那正是 `Feat/CS-Delta-IPC` 走的路,它一帧都没渲出来。
|
||||
|
||||
**第二个核心决策:每个困难语义先上"慢但可证明正确"的版本,后续阶段用 flag 换成快版本,并把慢版本保留成 oracle。**
|
||||
- Phase 1-4:**server 从源码重新 link shader**(只需 5 个 schema 字段,而不是 ~40 字段的 reflection schema),并带 `reflectionDigest` 交叉校验 → Phase 5 换成 `ProgramPublish`,`relink` 保留为 A/B 对照与常驻 oracle。
|
||||
- Phase 1-6:**关闭 ≥16MiB persistent-map 采纳**(前端在 `BufferObject.cpp:174,439-442,470-472` 已容忍 `nullptr` 返回,`MOBILEGL_DISABLE_LARGE_BUFFER_ADOPTION` 已存在)→ Phase 7 攻 external memory 导出,**允许结论是"设备 X 上拒绝,已记录,回退成本 N ms"**。
|
||||
- Phase 1-4:**调用时刻拷贝进 ring**(WAR 由构造消除)→ Phase 4.5 shadow-in-shm 零拷贝。
|
||||
|
||||
**第三个核心决策(本轮对抗性评审后新增,是本计划与上一版最大的语义差异):客户端是所有"隐式发布"语义的唯一发起者。**
|
||||
上一版把三件事交给"server 在 replica 上照常做,事件回传给 client",全部被证伪:
|
||||
1. **persistent-map 的写发布**:`BufferObject::SyncPersistentMappedRange()`(`BufferObject.cpp:238-250`)是 shadow-backed persistent 非-FLUSH_EXPLICIT map 的**唯一**推送点,而 `grep -rn SyncPersistentMappedRange MobileGL/` 的全部生产调用点都在 `MG_Backend/` 里(DirectGLES.cpp:262/4412/4666/4667/4768/4769、Managers.cpp:1547、MultiDraw.cpp:498、DirectVulkan.cpp:290/481/895、UniformManager.cpp:2022、VkBufferManager.cpp:573/620、VulkanRenderer.cpp:3432/3511/3826/7070/12015/12016)。MG_Impl 与 MG_State 里**一个都没有**。拆分后这段代码跑在 server 对 replica 上,而 replica 的 `m_isMapped` 是 false(没有 map delta),第一行就 return;client 侧则根本没人调。**应用通过 coherent persistent map 写下的字节会被静默丢弃。**
|
||||
2. **`MarkGpuWritten`**:同样只有 `MG_Backend/` 里的 6 个调用点(`DirectGLES.cpp:465,509,1809`;`UniformManager.cpp:1073,1229`;`VulkanRenderer.cpp:11210`),而它在 monolith 里是**在 draw 调用内同步置位的**。拆分后 draw 是 fire-and-forget,`glDrawElements(); glMapBufferRange(SSBO, READ);` 会在 server 还没 apply 之前就读到陈旧 shadow,零 round trip、零报错。
|
||||
3. **纹理 dirty flag**:上一版声称"client 从不清 dirty flag",但 `MipmapStorage::MarkDirtyRegion`(`MipmapStorage.cpp:196-233`)只要 `m_isDirty[level]` 为真就把 incoming **并进** union box 并追加 rect,只有 `MarkDirty(level,false)`(`:171-189`)会重置。永不清 = union box 只增不减、rect 列表饱和、`summedArea*4 >= unionArea*3` 一触发就退化成整 level 上传,正好与计划要保留的调优相反。
|
||||
|
||||
所以本版的规则是:**任何 monolith 里由 backend 代码触发的"前端状态发布/消费",在拆分模式下必须由 client 在发射点自己做一遍**,server 侧那份照常跑(它对 replica 操作,幂等或无害)。事件回传只允许作为**收窄优化**,永远不允许作为语义的**建立者**。
|
||||
|
||||
**Phase 1 的目标改为:在 Linux 上以 `inproc` 与 `spawn` 两种传输跑通垂直切片;真机 OpenRA trace(SSIM ≥ 0.99)移到 P2 出口判据。** 理由见 §15:Android 交付链(server `.so` 打包、`untrusted_app` 域 exec、trace app 的 env 透传)本身是独立工作量,把它压进 P1 的 10 天里是上一版最薄弱的排期假设。
|
||||
|
||||
### 核心决策速查
|
||||
|
||||
| # | 决策 | 理由 |
|
||||
|---|---|---|
|
||||
| D1 | Server = replica `GLContext` + 未改动 backend | 293 次 `pGLContext` 读、13 个身份键 memo、25 个 backend→frontend 写全部原样工作 |
|
||||
| D2 | 发射点 = 三个**已经是间接的**边界(`gBackendFunctionsTable` / `pActiveBackendObject` / `SetBufferBackendOps`),不进 MG_State mutator | monolith 侵入面 = `MG_Backend/Init.cpp:48-70` 里一个 switch 分支;~250 个边界调用点零 `#ifdef` |
|
||||
| D3 | 版本计数器**不上线**;replica 靠 mutator replay 自然 bump | 不需要 `Install*` setter,不需要在 wire 上维护回绕 `Uint16` 的单调性 |
|
||||
| D4 | 控制面走 **SPSC shm ring**,watermark 放在一条**共享 cache line**;**双向 doorbell** | `GetSyncStatus`/`IsQueryResultAvailable`/ring 回收/present credit 变成一次 acquire load;但**所有等待都必须能挂起**,不能自旋 |
|
||||
| D5 | FlatBuffers:热路径用 **`struct`**(定长、无 vtable、无 verifier walk),罕见/变长用 `table` 走 socket | 满足"用 FlatBuffers 序列化"的要求,同时 `DrawArrays` 记录 32B 而不是 ~60B |
|
||||
| D6 | **composite pipeline program 由 client 解析**并下发 handle | `Core.cpp:644` 在 pipeline cache miss 时 `MakeShared<ProgramObject>(0u)` 并 **link**;server 在 Phase 5 之后没有源码,必须由 client 定 |
|
||||
| D7 | 覆盖度由**两侧生成的编译期断言**保证:backend 的 READ 面 **和** MG_Impl 的 MUTATOR 面 | backend 新增一个 read、或 MG_Impl 在 table 调用旁新增一个 mutation 而 applier 没 replay → 编译失败,而不是设备回归 |
|
||||
| D8 | monolith 保留由 **`nm --defined-only` + `.text` size diff** 机械证明,且**每个阶段都跑**,不只 P0 | 不靠"测试没变" |
|
||||
| D9 | **client 是隐式发布语义的唯一发起者**(persistent map 推送、`MarkGpuWritten`、纹理 dirty 清除、XFB CPU 计数、生成 mip 的存储分配) | 见上文三条被证伪的假设 |
|
||||
| D10 | `inproc` 与 `spawn` 拆成**两个 CMake option**:出货构建只开 `spawn`,`pGLContext` 保持普通全局,GL 热路径上没有 TLS | Android dlopen 的 shared library 无法用 initial-exec TLS,1494 个 `pGLContext->` 上每次 `__tls_get_addr` 调用不可接受 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 目标
|
||||
1. 前端(MG_Impl + MG_State + glslang 链接)与后端(MG_Backend + SPIRV-Cross + 驱动)跑在两个进程,通过 IPC 通信。
|
||||
2. Client 把前端状态 reconcile 成 delta,序列化(FlatBuffers)后发送;server 更新自身状态并调用 backend API。
|
||||
3. **稳态帧零 round trip**(readback / 阻塞式 query / sync wait / present credit / 分配类错误 ack 之外)。
|
||||
4. 两半尽可能互相异步:client 至多领先 server 1 个 present(默认值,见 §9 的延迟叠加分析)。
|
||||
5. 平台特定代码最小化并集中在 `MG_Remote/Transport/` 与 `MG_Remote/Client/Surface*`。
|
||||
6. **单进程 Monolith 保持字节级不变**,且可机械验证。
|
||||
7. 所有验收门用**现有测试**:`ctest -L unit` / `-L integration-gpu` / `tools/trace_replay` / `tools/cts` / `tools/device_bench`。
|
||||
|
||||
### 非目标(本分支明确不做)
|
||||
- **share-group sessioning 重构。** monolith 今天所有 EGL context 共用一个 `GLContext`(`GLState/Core.cpp:20,1487`;`eglCreateContext` 只存 `SharedContext` 于 `EGLState/Core.cpp:640`,全代码库无人读取)。单 context client 与今天等价。`c7c9e346`/`29d721ef` 那套(共享 VAO-0 破坏、四个头文件 `public:` 泄漏、无锁进程全局 current session、`MOBILEGL_SESSION_SWAP` kill switch)整体丢弃。
|
||||
- **BFA strict-C-ABI backend 插件 / UtilRuntime C-ABI 化。** server 与 backend 同一 CMake 工程、同一产物发布,ABI 边界永不移动。
|
||||
- **macOS 拆分。** `CAMetalLayer` 无公开跨进程表示,MobileGL 在 macOS 是 `DYLD_INSERT_LIBRARIES` interposer(导出表锁定于 `CMakeLists.txt:600-612`),无 CI 无设备 → **monolith only,写进文档**。
|
||||
- **Windows 窗口拆分。** WGL / ANGLE-DXGI 对外进程 HWND 不是受支持配置 → **headless(pbuffer) only**。
|
||||
- Phase 9 之前不做任何窗口路径(全部离屏)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状:今天的前后端边界(七个面)
|
||||
|
||||
### (a) `GLFunctionsTable` — 73 项,`MG_Backend/BackendObject.h:117-285`
|
||||
MG_Impl 侧 91 个调用点(`GL_Drawing.cpp` 37、`GL_Query.cpp` 22、`GL_Framebuffer.cpp` 11、`GL_Texture.cpp` 10、`GL_Sync.cpp` 6、`GL_Getter.cpp` 3、`GL_Program.cpp` 1)+ `MG_Util/ShaderTranspiler/CompileEnv.cpp:134,138` 两处。
|
||||
|
||||
- 20 个 draw、9 个 clear(4 个 `ClearNamedFramebuffer*` 携带 `SharedPtr<FramebufferObject>`)、5 个 blit/copy(`CopyImageSubData` 携带两个 `CopyImageEndpoint`,`BackendObject.h:32-39`)、`GenerateMipmap`、3 个 readback、4 个 compute/barrier、`BindImageTexture`(已经收 GL name)。
|
||||
- **两项是死代码**:`GetInteger64i_v`(`BackendObject.h:196`,MG_Impl 零调用点;`GL_Getter.cpp:1307` 把 64 位形式委派给 32 位)和 `GetProgramiv`(`:197`;`GL_Program.cpp:851` 全部从 `ProgramObject` 回答)。两个 backend 都注册并实现了它们。
|
||||
- `GetIntegeri_v` 只有 `GL_MAX_COMPUTE_WORK_GROUP_COUNT/SIZE` 真正转发(`GL_Getter.cpp:1161-1179`)。
|
||||
- `BeginOcclusionQuery != nullptr` 被当作能力探测用(`GL_Query.cpp:471,545,768`);DirectVulkan 只注册 64/72 项(`BackendObject_DirectVulkan.cpp:690-770`,不注册 7 个 XFB + `PatchParameteri` + `SetSwapInterval`)。
|
||||
|
||||
### (b) `BackendObject` 虚函数 — `BackendObject.h:541-568`
|
||||
MG_Impl 侧 89 个 `pActiveBackendObject->`,**其中 45 个是 `GetDynamicParameters()`**,若干落在 per-API-call 校验路径上(`Buffer/Validators.cpp:63`、`VertexArray/Validators.cpp:22`、`GL_VertexArray.cpp:536`、`GL_Texture.cpp:406`)。
|
||||
**关键时序:`InitCapabilities()` 懒执行在第一次成功的 `eglMakeCurrent` 内部**(`BackendObject.cpp:341-347`),DirectGLES 在那里才改写 advertised extension string(`BackendObject_DirectGLES.cpp:786-796`)。
|
||||
|
||||
### (c) `BufferBackendOps` — 7 个 hook,`BufferState/BufferObject.h:76-121`,注册入口 `:124`
|
||||
DirectGLES 注册 7/7(`Managers.cpp:1336-1345`),DirectVulkan 注册 6/7(无 `ResidentSubData`,`VkBufferManager.cpp:104-111`)。
|
||||
`AcquirePersistentMap`(`:112`)**把 GPU 内存裸指针交给应用**;`TryAdoptLargeStorage`(`BufferObject.cpp:167-176`,`kLargeBufferAdoptBytes = 16MiB`)在 store **定义时**单方面采纳。理由块 `BufferObject.cpp:153-166`:MC 26.3 的 128MB chunk arena,实测 p99 163→21ms、40→115fps、省 ~400MB。
|
||||
|
||||
### (d) 状态拉取 — 293 个 `pGLContext->`(DirectGLES 124 / DirectVulkan 169)+ ~90 个前端对象 getter
|
||||
`PrepareForDraw`(`DirectGLES.cpp:2916-2976`)与 `SetupDraw`(`VulkanRenderer.cpp:6371`)在这里把整个 `GLContext` 拉出来。**这一面在本设计中不过线。**
|
||||
|
||||
### (e) backend → frontend 写回(25 个语义点 / 14 个类)
|
||||
`MarkGpuWritten` ×3、`WritebackFromBackend` ×7、`MarkStorageDirty` ×11、`SetBackendResource` ×2、`AllocateStorage` ×1、`RecordError` ×2,加两处 shadow `Memcpy`(`DirectGLES.cpp:6861` 生成 mip、`:7144` CopyImage 镜像);DirectVulkan 另有 `SetBackendHashMemo`/`SetBackendStateMemo`(**存后端堆裸指针**)/`SetBackendAuxMemo`/`EnsureGpuResidentStorage`/`InvalidateCompileEnv`/`SwapchainObject.cpp:276-331` 改写 default-FBO 占位纹理。
|
||||
**replica 模型下这 25 处大部分落在 server 自己的 replica 上**,但其中三类是"语义建立者",client 必须自己做一遍(§5.6、§5.6a)。
|
||||
|
||||
### (f) backend 反向进 MG_Impl — 恰好 6 处
|
||||
`DirectGLES.cpp:1917,2838,2867,9675`(`pDefaultFramebufferInfo`)、`SwapchainObject.cpp:276`、`VulkanRenderer.cpp:10700`(`CopyTextureImageToClientOrPBO_State`)。replica 模型下全部正常解析(server 也链接完整 MG_Impl)。
|
||||
但注意:`MG_Impl::GLImpl::FramebufferImpl::pDefaultFramebufferInfo` 全库 22 处引用,client 侧 MG_Impl 也在读(`GL_Framebuffer.cpp:495,1827,1837,1897,1905,1913,1927,1936,2549,2590,2598,2608,2611`)。它是**第二个进程全局**,`inproc` 模式下必须与 `pGLContext` 一起做角色隔离(§12)。
|
||||
|
||||
### (g) MG_Impl 在 table 调用旁做的 MG_State mutation(**上一版遗漏的第七个面**)
|
||||
`GLFunctionsTable` 是一个**命令**边界,不是一个**状态**边界的两侧对称点:MG_Impl 在调 table 之前/之后还会自己改 MG_State,而这些改动 applier 只 replay table 是拿不到的。已确认的两族:
|
||||
|
||||
1. **`glGenerateMipmap` / `glGenerateTextureMipmap` / 自动 mipmap**:`GLImpl::GenerateMipmap`(`GL_Texture.cpp:6681-6699`)在 `GenerateMipmap_Backend` **之前** 调 `EnsureGeneratedMipmapStorageAllocated(*mipmapTexture)`(`GL_Texture.cpp:501-541`),后者对 level 1..N 做 `AllocateStorage`、`MarkStorageDirty(...,false)`(`:528`)、`TruncateMipmapLevels`(`:533`)、`BumpContentVersion()`(`:538`)。`:534-537` 的注释写明了这个 version bump 存在的理由:没有它,"a cached sampled VkImageView built for the pre-generate level range would otherwise stay stale and clamp LOD>0 sampling to mip 0"。只 replay table 的 applier 会在 replica 上**精确复现这个已知 bug**。`GenerateTextureMipmap`(`:6702-6711`)和 `MaybeAutoGenerateMipmap`(`:1625-1635`)同形。
|
||||
2. **Transform feedback CPU 计数**:`AccountTransformFeedbackPrimitives`(`GL_Drawing.cpp:172-236`)在每个被捕获的 draw 上改 6 个 GLContext 计数器:`AddTransformFeedbackPausedPrimitives`(:177)、`AddTransformFeedbackInputPrimitives`(:184)、`AddTransformFeedbackGeometryCaptureDraw`(:214)、`AddTransformFeedbackPrimitives`(:231)、`AddTransformFeedbackCapturedVertices`(:232)、`AddTransformFeedbackAccountedCaptureDraw`(:237)。DirectGLES 在 `DirectGLES.cpp:900` 读 `GetTransformFeedbackCapturedVertices()` 来给 scattered capture 定容量;DirectVulkan 在 `DirectVulkan.cpp:1384` 读 `GetTransformFeedbackPausedPrimitiveCounter()` 并在 `:1337` 把前端 delta 折进 query 结果。这些计数器**没有版本号**,也不在任何 accessor 的门控里;replica 上它们恒为 0 → scattered XFB 什么都不捕、`PRIMITIVES_WRITTEN`/`PRIMITIVES_GENERATED` 错。它们还在 XFB 对象绑定时按对象存取(`Core.cpp:1273,1296`;`Core.h:313-357`),所以简单"发个标量"的补丁必须跟着对象切换走。
|
||||
|
||||
§5.9 的覆盖生成器**抓不到这一类**:它扫 `MG_Backend/**` 的 READ 面,所以 backend 读 `GetTransformFeedbackCapturedVertices` 会被正常分类并通过,而 MG_Impl 那半个生产者从来没被审计过。**所以 §5.9 必须有第二个生成器**(见 §5.9b)。
|
||||
|
||||
### (h) 工作树污染(Phase 0 必须先清)
|
||||
`DirectGLES.cpp:290-303` 与 `Managers.cpp:875-877` 有**未提交的 per-draw `fprintf(stderr)`**(格式串里还有字面量 `' + NL + '`,且位于 `pendingMutex` 临界区内的 buffer flush 路径上)。`Feat/CS-Delta-IPC` 的 `d96be9f3` 提交过同类东西(`DirectGLES.cpp:+2583-2590`),导致该分支上**每一次测量**(144-failure Windows run、OpenRA `ssim=0.000036` 设备 run)都跑在每 draw 一次 stderr 写的构建上。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标架构总览
|
||||
|
||||
```
|
||||
┌───────────────────────── CLIENT 进程 (libMobileGL.so) ─────────────────────────┐
|
||||
│ App / LWJGL │
|
||||
│ │ gl* │
|
||||
│ ▼ │
|
||||
│ MG_Impl (validate → RecordError → 调 MG_State mutator) ← glGetError 本地 │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ MG_State::pGLContext (权威状态 + ShaderCompilePool + glslang) │
|
||||
│ │ │
|
||||
│ ├─ gBackendFunctionsTable = EmitTable ─┐ │
|
||||
│ ├─ pActiveBackendObject = BackendObject_Remote (+ CapsMirror) │
|
||||
│ └─ SetBufferBackendOps(&g_emitBufferOps) ─┤ │
|
||||
│ ▼ │
|
||||
│ MG_Remote::WireMirror │
|
||||
│ (① PublishImplicitState:persistent-map 推送、 │
|
||||
│ MarkGpuWritten 保守置位、XFB 计数、mip 分配 │
|
||||
│ ② 读版本计数器 → 决定发什么 │
|
||||
│ ③ 清 dirty flag / 记录 shipped 水位) │
|
||||
│ │ │
|
||||
└──────────────────────────────────────────────────┼─────────────────────────────┘
|
||||
SEG_CMD (SPSC ring, POD 记录) ────────────┤ 写
|
||||
SEG_STAGE (bulk 字节 ring, 独立游标) ─────┤ 写
|
||||
SEG_SHADOW[n] (P4.5+, client 拥有)────────┤ RW
|
||||
RingControl (一条 cache line 的 atomics) ◄─┤ 读 watermark(acquire load)
|
||||
├─ producerParked ──► server 敲门铃
|
||||
SEG_REPLY / SEG_EVENT (server 拥有) ◄─┘ 读(在每个等待循环里排空)
|
||||
CTRL socket (socketpair / 继承 overlapped pipe): FlatBuffers table
|
||||
+ SCM_RIGHTS + 双向 doorbell
|
||||
┌──────────────────────────────────────────────────┼─────────────────────────────┐
|
||||
│ MobileGLServer (dlopen libMobileGL.so → mobilegl_server_main) │
|
||||
│ thread mgl-srv-io : asio,framing,fd 传递,doorbell,控制面 RPC │
|
||||
│ thread mgl-srv-apply: 终身持有 EGL/Vulkan context(可绑大核) │
|
||||
│ │ │
|
||||
│ ▼ Applier::Apply(RecHeader) → MG_State mutator / 共享 helper / │
|
||||
│ GLFunctionsTable │
|
||||
│ MG_State::pGLContext (replica) │
|
||||
│ ▲ │
|
||||
│ │ 293 次 pGLContext-> + ~90 getter,**零改动** │
|
||||
│ MG_Backend (DirectGLES / DirectVulkan) + MG_Util(SPIRV-Cross, 转译缓存) │
|
||||
│ │ │
|
||||
│ ▼ 真实 GLES / Vulkan 驱动 │
|
||||
└────────────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
三种运行模式(`MOBILEGL_TRANSPORT`):`monolith`(默认,编译期折叠)、`inproc`(同进程第二个 `GLContext` + apply 线程,**需要 `MOBILEGL_BUILD_DISAGGREGATED_INPROC`**)、`spawn` / `unix:<path>` / `pipe:<name>`(真跨进程,出货形态)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界定义(每个面变成什么)
|
||||
|
||||
| 面 | 变成 |
|
||||
|---|---|
|
||||
| **(a) `GLFunctionsTable`** | `MG_Remote::Client::MakeEmitTable()` 返回的发射表。61 项 = 先跑 `PublishImplicitState`、再追加一条定长记录、返回;5 项 request/reply;4 项分配类 `kNeedsAck`(§5.6c);`GetIntegeri_v` 由 CapsMirror 本地回答;`GetInteger64i_v`/`GetProgramiv` **从 wire 与 table 中删除**(并提议在 `dev` 上删掉两个 backend 的实现)。7 个携带 `SharedPtr` 的项转成 `WireHandle`。**DirectVulkan 未注册的 8 个槽由 `CapsSnapshot.tableSlotMask` 精确复现**(`GL_Query.cpp:471,545,768` 拿槽位空否当能力探测)。 |
|
||||
| **(b) `BackendObject` 虚函数** | `BackendObject_Remote`。8 个 EGL 生命周期虚函数 → `SurfaceOp` RPC(前 4 个阻塞,因为返回 `Bool`)。`GetDynamicParameters`(45)/`GetRendererInfo`(8)/`GetFormatCapabilities`(4)/`GetBackendType`(3)/`GetBackendAPIVersionString` → **CapsMirror 本地,零 round trip**。`DynamicBackendParameters`(`BackendObject.h:299-521`)是 flat POD,逐字节传。先例:`CompileEnv`(`CompileEnv.h:28-45`)就是为同一个原因做的同一件事。`GetBackendType()` 返回**远端**类型,所以 `GL_Texture.cpp:6453-6457`、`CompileEnv.cpp:122`、`GL_Framebuffer.cpp:38` 全部照旧。 |
|
||||
| **(c) `BufferBackendOps`** | `g_emitBufferOps`:`Respecify`/`SubData`/`FlushMappedRange`/`OnDestroy` → 记录;`ResidentSubData` P7 之前不注册(只有 adopted store 才可达);`AcquirePersistentMap` → P1-6 返回 `nullptr`,P7 返回 `AdoptSeg` 映射基址;`ReadbackFromGpu` → 阻塞请求(monolith 里本来就是 `glFinish()`,`Managers.cpp:1246`)。 |
|
||||
| **(d) 状态拉取** | **不过线。** backend 读 server 自己的 replica。 |
|
||||
| **(e) backend→frontend 写** | 大部分落在 replica 上;三类"语义建立者"由 client 自己做(`MarkGpuWritten`、纹理 dirty 清除、persistent-map 推送);六类需要事件回传(§5.6)。**per-row `WritebackFromBackend` 循环(`Utils.cpp:2342`、`DirectGLES.cpp:7633`)在 server 内部执行,永远不会变成"每扫描线一次 IPC"。** |
|
||||
| **(f) MG_Impl 反向调用** | server 链接完整 MG_Impl,6 处照常解析。default-FBO 描述通过 `EvDefaultFramebufferInfo` 事件回传给 client(`SwapchainObject.cpp:276-331` 的写在 server 侧发生)。 |
|
||||
| **(g) MG_Impl 在 table 旁的 mutation** | 抽成 client/server 共享 helper(`MG_Remote::Shared::`),applier 在 replay 对应记录时调同一个 helper;或作为显式记录下发。由 §5.9b 的生成器强制全覆盖。 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 状态 delta 模型
|
||||
|
||||
### 5.0 决定:replica `GLContext` vs 重写 backend
|
||||
|
||||
**选 replica。** 三条不可协商的证据:
|
||||
1. **身份键 memo 无 delta 对应物。** `UnitTextureSyncEntry` 借用 binding slot 的 `shared_ptr` **地址**(`DirectGLES.cpp:1463-1467`),`PairingsIntact` 再校验 `entry.slot->get() != entry.texture`(`:1472-1477`)——注释明说没有它"replay 会拿纹理 B 的前端状态驱动纹理 A 的后端 twin"。`IsBufferDrawClean`(`Managers.cpp:1435-1436`)第一句就是资源裸指针身份比较。DirectVulkan 13 个缓存同类。replica 里这些**逐字工作**,因为对象仍由 `SharedPtr` 持有、unit 数组仍按值存放。
|
||||
2. **回绕计数器。** `FramebufferBindingSlot::GetVersion()`、`FramebufferObject::GetObjectVersion()`、`VAO::GetIndexBufferBindingSlot().GetVersion()` 都是 `Uint16` 回绕,只有配合指针身份才正确。replay 让两侧跑同一段回绕逻辑。
|
||||
3. **backend 自有 generation 表达的是"驱动对象被重新铸造"**(`g_bufferBackendIdGeneration`、`g_attachmentBackendIdGeneration`),**任何 client delta 都无法承载**——它们本来就该纯 server 侧,replica 天然满足。
|
||||
|
||||
代价:server 进程要链接 MG_State + MG_Impl + MG_Util(SPIRV-Cross、转译缓存、格式处理器、POST 探针)。这本来就无法避免——`BackendProgramObjectImpl::TranspileSpirvToEssl`(`Managers.cpp:6575-7110`)在 draw 线程跑 SPIRV-Cross,`UniformManager.cpp:1418-1497` 构造真实 `TextureObject`,`VulkanRenderer.cpp:4211-4356` 走 `ShaderObject::Compile()`/`ProgramObject::Link(false)`。"thin server"在这个代码库里是伪命题。
|
||||
|
||||
**replica 模型的边界必须明确写出来(R1 的真正内容)**:replica 只保证"对 backend 可见的状态"与 client 一致。凡是 client 的**入口点**(MG_Impl)在调 table 之外还做过的 MG_State 改动,applier 必须显式复刻——这不是理论风险,是 §2(g) 已经确认的两族实例。§5.9b 把它变成编译期门。
|
||||
|
||||
### 5.1 reconcile 在哪里发生
|
||||
|
||||
`MobileGL/MG_Remote/Client/WireMirror.{h,cpp}`,在**发射点**运行:每个 `GLFunctionsTable` 命令、`Present`、任何阻塞请求。
|
||||
|
||||
每个发射点分三步,顺序不可换:
|
||||
|
||||
**步骤 ①:`PublishImplicitState(scope)`** —— 复刻 backend 在 monolith 里会做的隐式发布,**必须在读任何版本计数器之前跑**,因为它自己会 bump 版本:
|
||||
- 对 scope 内每个 **live persistent-mapped buffer** 调 client 侧的推送(§5.10)。
|
||||
- 对 draw/dispatch scope,保守置 `MarkGpuWritten()`:镜像 `MarkShaderStorageBuffersGpuWritten`(`DirectGLES.cpp:459-467`,走 `GetTouchedBufferBindingPointCount(ShaderStorage)` + `GetBufferBindingPoint`)、`SyncAtomicCounterBuffers` 的 `:509`、以及可写 image-buffer 纹理的 `:1809`。XFB active 时对每个 capture target 同样置位(镜像 `VulkanRenderer.cpp:11210`)。
|
||||
- 对 draw scope,若 XFB active,跑共享的 `AccountTransformFeedbackPrimitives` helper(§2(g)-2;monolith 里这一步本来就在 MG_Impl 里,拆分后它继续在 client 跑,同时把结果作为 `RecXfbAccounting` 下发给 replica)。
|
||||
- 对 `GenerateMipmap` scope,`EnsureGeneratedMipmapStorageAllocated` 本来就在 client 的 MG_Impl 里跑过了;WireMirror 只需把它产生的 level 分配 + `TruncateMipmapLevels` + `BumpContentVersion` 作为 `RecGenerateMipmapLevels` 下发(§5.6a)。
|
||||
|
||||
**步骤 ②:可达性遍历。** 这就是 `DirectGLES::PrepareForDraw`(`DirectGLES.cpp:2916-2976`)的遍历,把 sync 换成 emit——不是比喻,是同一集合、同一顺序、同一门控:
|
||||
|
||||
1. `GetBoundVertexArray()` → `GetConfigVersion()`;其 enabled attribute 的 `BufferObject`;index buffer slot(**版本 + 裸指针身份**)。
|
||||
2. `GetProgramForDraw()`(在 client 侧 join compile pool,与今天一致)→ link/UBO-content/block-binding/SSBO-override 版本。**composite pipeline 见 §5.7。**
|
||||
3. texture unit `[0, GetMaxTouchedTextureUnit()]`,门控 `GetTextureBindGeneration()`;每纹理 `GetContentVersion()`/`GetTextureParamsVersion()`;每 unit `GetSamplerObject()->GetVersion()`。
|
||||
4. image unit `[0, imageHighWater]` 经 `GetImageTextureBinding(unit)`。
|
||||
5. 每 target 的 buffer binding point,上界 `GetTouchedBufferBindingPointCount(target)`。
|
||||
6. draw/read FBO,门控 slot version + `GetObjectVersion()` + `GetAllFramebufferAttachmentVersions()`,再逐 attachment;**attachment 若是 renderbuffer,另查 `RenderbufferObject::GetVersion()`**(P0 新增,见 §5.4)。
|
||||
7. `GetRenderStateParameters()`,门控 render-state 版本。
|
||||
8. **pack** pixel-store(backend 从不读 unpack;六个读点全部传 `false`:`DirectGLES.cpp:6129,7614,9101,9480`、`Utils.cpp:2301`、`VulkanRenderer.cpp:10622`;`ScopedDefaultUnpackState` 强制默认值,`Managers.cpp:2888-2910`)。
|
||||
|
||||
**步骤 ③:清消费型状态。** 对本次发射的每个纹理 level 调 `MarkStorageDirty(uploadTarget, level, false)`(§5.6a)。
|
||||
|
||||
因为 backend 自身这套门控已被证明有界且便宜,reconciler 的每 draw 成本形状是**已知的**,不是估计。
|
||||
|
||||
存储:
|
||||
```cpp
|
||||
// MobileGL/MG_Remote/Client/WireMirror.h
|
||||
struct ShipRecord { // 40 B
|
||||
Uint64 shippedA, shippedB, shippedC; // 打包版本元组,按 kind 解释
|
||||
Uint32 flags; // Created | Published | Deleted | ServerAuthoritative
|
||||
Uint32 pad;
|
||||
};
|
||||
class WireMirror {
|
||||
ska::flat_hash_map<Uint64 /*lifetimeId*/, ShipRecord> m_ship;
|
||||
struct DrawKeys { Uint64 contextId, samplingGen, bindGen; Int maxUnit; } m_lastDrawKeys;
|
||||
// ① 的输入:只遍历真正 mapped / 真正可能被 GPU 写的对象,不是全表
|
||||
ska::flat_hash_set<MG_State::GLState::BufferObject*> m_livePersistentMaps;
|
||||
ska::flat_hash_map<Uint64 /*lifetimeId*/, Uint64 /*emitSeq*/> m_gpuWritePendingSeq;
|
||||
public:
|
||||
void PublishImplicitState(EmitScope, RingProducer&);
|
||||
void ReconcileForDraw(RingProducer&); // 上面 1-8
|
||||
void ReconcileForDispatch(RingProducer&);
|
||||
void ReconcileForClear(RingProducer&);
|
||||
void OnObjectCreated(ObjKind, Uint32 name, Uint64 lifetimeId);
|
||||
void OnObjectDestroyed(ObjKind, Uint64 lifetimeId);
|
||||
void OnBufferMapped(BufferObject&, Range1D, BufferMappingAccess);
|
||||
void OnBufferUnmapped(BufferObject&);
|
||||
};
|
||||
```
|
||||
外加与 backend `DrawTextureSyncKeys`(`DirectGLES.cpp:1496-1518`)同键的 per-draw memo:状态未变的重复 draw 只花 ~10 次整数比较就追加一条 32 字节记录。
|
||||
|
||||
### 5.2 版本计数器**不上线**
|
||||
|
||||
applier 不设置版本,它 **replay mutation**,所以 replica 的计数器恰在 applier 改动了东西时 bump——恰是 backend 必须重新 sync 的时刻。
|
||||
|
||||
- 不需要给 `RenderState`/`ProgramObject` 加 `Install*` setter(`Feat/CS-Delta-IPC` 的 `b50f3348` 加了,代价是把 `RenderState.h` 的私有成员漏成 public)。
|
||||
- 不需要在 wire 上维护回绕 `Uint16` 的单调性。
|
||||
- 唯一残留风险是**过度失效**:replica bump 了而 client 没 bump。只要 applier 只做 client 明确下发的 mutation,就不会发生;`RenderStateBlob` 整块下发是唯一例外(它整块 bump `m_version`,与 client 自己的 bump 等价)。
|
||||
|
||||
### 5.3 触发器 → delta 对照表
|
||||
|
||||
| Client 触发器(accessor / 事件) | Delta 记录 |
|
||||
|---|---|
|
||||
| `BufferObject::GetChangeSerial()` + emit-ops 里排队的 range | `RecBufferRespecify` / `RecBufferSubData` / `RecBufferFlushRange` |
|
||||
| `glMapBuffer*` / `glUnmapBuffer`(**新增**) | `RecBufferMap{handle, range, accessFlags}` / `RecBufferUnmap{handle}` |
|
||||
| persistent-map 脏块(**新增**,§5.10) | `RecBufferSubData`(块粒度) |
|
||||
| `MipmapStorage::IsStorageDirty(target,level)`, `GetContentVersion()` | `RecTexAllocLevel` / `RecTexSubImage`(union box 或 ≤96 rects,变长) |
|
||||
| `glGenerateMipmap` 前的 level 分配(**新增**) | `RecGenerateMipmapLevels{handle, target, requiredLevelCount, bytesPerTexel}` |
|
||||
| `ITextureObject::GetTextureParamsVersion()` | `RecTexParam` |
|
||||
| `ITextureObject::GetViewStorageOwner()` + view 字段 | `RecTexView`(**必须先于 owner 的任何 re-mint 顺序到达**) |
|
||||
| `SamplerObject::GetVersion()` | `RecSamplerParam` |
|
||||
| `RenderbufferObject::GetVersion()`(**P0 新增**) | `RecRenderbufferStorage{handle, internalFormat, w, h, samples}` |
|
||||
| `VertexArrayObject::GetConfigVersion()` + 每 attrib Switch/Format/Buffer 版本 | `RecVaoConfig`(变长,整份配置;P6 再做逐属性 diff) |
|
||||
| index buffer slot version **+ 指针身份** | `RecVaoIndexBuffer` |
|
||||
| `FramebufferObject::GetObjectVersion()` + attachment 版本 | `RecFboAttach` / `RecFboDrawBuffers` / `RecFboReadBuffer` |
|
||||
| `RenderState::m_version` / `m_pipelineStateVersion` | `RecRenderStateBlob`(整个 trivially-copyable `RenderStateParameters`,`RenderState.h:517-535`) |
|
||||
| `ProgramObject::GetLinkVersion()` | `RecProgramLinkOp`(P1-4) → `RecProgramPublish`(P5+) |
|
||||
| `ProgramObject::GetUBOContentVersion()` | `RecProgramUboContent` |
|
||||
| block-binding / SSBO-override 版本 | `RecProgramBlockBinding` / `RecProgramSsboBinding` |
|
||||
| `GetProgramForDraw()` 解析出 composite | `RecSetResolvedDrawProgram`(§5.7) |
|
||||
| `GetTextureBindGeneration()` + unit slot 遍历 | `RecBindTexture` / `RecBindSampler` / `RecActiveTexture` |
|
||||
| `GetTouchedBufferBindingPointCount()` 遍历 | `RecBindBuffer` / `RecBindBufferRange` |
|
||||
| `GetImageTextureBinding(unit)` | `RecBindImageTexture` |
|
||||
| pack `PixelStoreParameters` | `RecPixelStorePack` |
|
||||
| XFB active 时的 draw(**新增**) | `RecXfbAccounting{pausedPrims, inputPrims, prims, capturedVerts, geomDraws, accountedDraws}` 增量 |
|
||||
| `GLFunctionsTable` 命令 | `RecDraw*` / `RecClear*` / `RecBlit*` / `RecCopy*` / `RecDispatch*` / `RecXfb*` / `RecPresent` … |
|
||||
|
||||
### 5.4 对象身份、创建/删除顺序
|
||||
|
||||
wire handle = `WireHandle { kind:u8, glName:u32, lifetimeId:u64 }`。`GetLifetimeId()` 永不复用(`BufferObject.h:208`、`FramebufferObject.h:158`、`ProgramObject.h:1620`、`VertexArrayObject.h:120`、`SamplerObject.h:141`、`TextureObject.h:83,161`)。
|
||||
|
||||
**`RenderbufferObject` 既没有 `GetLifetimeId()` 也没有 `GetVersion()`(已在 `MG_State/GLState/RenderbufferState/RenderbufferObject.h` 上确认为零命中)—— Phase 0 两个都补上**,`GetVersion()` 取 `SamplerObject::GetVersion` 的同款形状(`Uint16`,每次 `RenderbufferStorage*` bump),并在 §5.1 步骤②-6 的 per-attachment 遍历里读它。理由:`BackendRenderbufferObject::SyncToBackend`(`Managers.cpp:~8620-8700`)缓存 `{internalFormat,width,height,samples}`,而对一个**已 attach 的** renderbuffer 重新 `glRenderbufferStorageMultisample` 不必然 bump `GetAllFramebufferAttachmentVersions()`,没有 `GetVersion()` 就没有触发器。
|
||||
|
||||
replica 使用**与 client 相同的 GL name**:applier 直接 `ctx.CreateBufferObject(name)`,绕过 server 自己的 `IndexGenerator`。server 侧维护 `ska::flat_hash_map<(kind,name), {SharedPtr<T>, clientLifetimeId}>`。
|
||||
|
||||
**若某次 create 的 `lifetimeId` 与记录不符 → `Fatal{IdentityDivergence}`,不做"先销毁再创建"的修复。** 上一版的"先销毁"是错的:replica 上那个对象可能仍被 FBO attachment、binding slot、texture view(`GetViewStorageOwner`)或 XFB capture target 通过 `SharedPtr` 合法持有,GL 保证它活到最后一个引用消失;强行销毁要么留下悬挂引用要么静默 detach,把一个协议 bug 变成一个会被归咎于 backend 的渲染 bug。协议正确时这个分支不可达,所以响亮地停下来严格优于静默的破坏性修复(`MOBILEGL_IPC_RESPAWN=1` 时改为强制 `ResyncSnapshot`)。
|
||||
|
||||
这就是 packed_pixels 的教训(身份 + 计数器,绝不单靠计数器)在协议层的应用,也是本设计对 name 空间漂移的**结构性预防**(而非事后 checksum 检测)。
|
||||
|
||||
创建/删除在 `glGen*`/`glDelete*` 时刻**立即**发射,顺序即 ring 顺序。client 的 `~BufferObject` 触发 emit-ops 的 `OnDestroy` 追加 `RecObjDelete`;server 的 replica `~BufferObject` 触发**真实**的 `Ops_OnDestroy`,完成 pooling / 延迟 `glDeleteBuffers`(`Managers.cpp:1271-1300`)——一行不改。
|
||||
|
||||
### 5.5 合并规则
|
||||
|
||||
1. **版本门控本身就是合并器。** 两个发射点之间的 N 次 mutation 折叠成一条 delta;改了又改回去的状态永不上线。
|
||||
2. **Buffer range** 在 per-buffer `VecRange1D` 里累积(复用 `MG_Util/Math/VectorTypes.h:264` 已调优的 7% span gap 合并),在该 buffer 的下一个发射点 flush。**绝不 union 成整个 buffer**——`Managers.cpp:860-864` 的 postmortem 记录了那样会每帧重拷近乎整个 chunk-mesh arena。
|
||||
3. **纹理区域**逐字沿用 `MipmapStorage::GetDirtyRects`,含 `summedArea*4 >= unionArea*3` 回退(`MipmapStorage.cpp:305`)。**注意代价轴是反的**:buffer 按字节计价,texture sub-image 按 **job 数**计价(`Managers.cpp:4311-4319`,~100 rects vs 一个 box 实测 +6ms/frame)。client 下发**区域形状**(union box 或 rect 列表,按 client 自己的 `GetDirtyRects` 判定),server 的 backend 从自己 replica 的 dirty 状态重新推导**上传形状**,让已调优的启发式留在付 GPU 代价的那一侧。
|
||||
4. `RecRenderStateBlob`、各类 bind:last-writer-wins,reconciler 只发**当前值**。
|
||||
5. **命令永不合并、永不重排。**
|
||||
|
||||
### 5.6 backend→frontend 写:三种归属
|
||||
|
||||
| 写 | 归属 |
|
||||
|---|---|
|
||||
| `SetBackendResource`、`SetBackendHashMemo`/`StateMemo`/`AuxMemo` | **纯 server 本地**,零 wire 流量 |
|
||||
| `MarkGpuWritten` ×3 + `EnsureGpuResidentStorage` | **client 保守自建**(§5.6b)。server 侧照常在 replica 上置位;`EvGpuWritten{handle, ranges[]}` 仅作为**收窄提示** |
|
||||
| `MarkStorageDirty(…,false)` ×11 | **client 在发射后自己清**(§5.6a)。server 侧照常在 replica 上清 |
|
||||
| `MarkStorageDirty(…,true)`(`Managers.cpp:2813` RequireImageBindableStorage 的 re-dirty) | 纯 server 本地:它是 server 的 re-mint 导致的,client 无从预测,也无需知道——重传由 server 自己在 replica 上完成 |
|
||||
| `WritebackFromBackend`(PBO/XFB) | server 侧写 replica shadow;合并后的 range 变成 `EvBufferWriteback` 回传 client |
|
||||
| `RecordError` ×2(`DirectGLES.cpp:6319`、`Managers.cpp:8679`)+ DirectVulkan 4 处 | **分两类**(§5.6c):分配类同步 ack,其余走 `EvGlError` 晚一批可见 |
|
||||
| `AllocateStorage` 生成 mip(`DirectGLES.cpp:6270-6271,6861`)、`MirrorCopyImageIntoDestinationShadow`(`:7144`) | **per-level `serverAuthoritative` 位**(§6.6) |
|
||||
| `InvalidateCompileEnv`、`SwapchainObject` 改写 default-FBO 占位纹理 | 事件 `EvCompileEnvInvalidate` / `EvDefaultFramebufferInfo` |
|
||||
|
||||
#### 5.6a 纹理 dirty flag:client 必须清(推翻上一版)
|
||||
|
||||
上一版写"client 的 dirty flag 从不被清,已发送状态存在 WireMirror 里"。这是错的:
|
||||
- `MipmapStorage::MarkDirtyRegion`(`MipmapStorage.cpp:196-233`)只要 `m_isDirty[level]` 为真,就把 incoming **union 进** `m_dirtyRegions[level]` 并 `InsertDirtyRect`;只有 `MarkDirty(level,false)`(`:171-189`)重置两者。永不清 ⇒ box 单调增长、rect 列表撑满 `kMaxDirtyRects`、`GetDirtyRects` 一旦跨过 3/4 阈值就返回 0("用 box"),于是每次动画图集 tick 都传整个 level。
|
||||
- `ShipRecord` 只有三个 `Uint64` 版本字,**无法**从中重建区域。
|
||||
- `MarkDirtyRegion` 的 rect 播种分支(`:214-221`:`if (!m_isDirty[level]) rects.clear(); else if (rects.empty() && !region.Empty()) rects.push_back(region);`)本身就是为"有人会清"写的。
|
||||
|
||||
好消息是清是安全的:**MG_Impl 里没有任何 `IsStorageDirty(` / `GetStorageDirtyRects(` / `GetStorageDirtyRegion(` 调用点**(已 grep 确认为零),前端从不读自己的 dirty 状态;它自己也在五处主动清(`GL_Texture.cpp:528,701,5547,5621,5691`)。
|
||||
|
||||
**规则**:WireMirror 在追加纹理记录之后,立刻对该 (target, level) 调 `MarkStorageDirty(..., false)`。ack 问题按两条收口:
|
||||
1. `ResyncSnapshot` 永远从**完好的 shadow** 传整 level(shadow 从不被丢弃,除非 buffer 被 adopt——纹理没有 adopt 路径),所以"清早了导致重传丢数据"在 resync 场景不成立。
|
||||
2. 硬 drain(§6.5)会 bump `ringGeneration`;drain 后 client 对**所有已发射但未 `appliedSeq` 覆盖的纹理记录**做一次重发(WireMirror 保留最近一批记录的 (handle, target, level) 列表 + emitSeq,drain 时把 seq > appliedSeq 的重新标脏并重发)。这是有界的,因为 ring 里最多只有 ring 容量那么多未 apply 的记录。
|
||||
|
||||
#### 5.6b `MarkGpuWritten`:client 保守自建(推翻上一版)
|
||||
|
||||
monolith 里这个 flag 是在 draw 调用**内部同步**置位的:`MarkShaderStorageBuffersGpuWritten`(`DirectGLES.cpp:459-467`)走 `GetTouchedBufferBindingPointCount(ShaderStorage)` 并对每个绑定对象 `MarkGpuWritten()`,从 draw 路径的 `SyncNeccessaryBuffers` 调用(`DirectGLES.cpp:687,697`);atomic counter 在 `:509`;可写 image-buffer 纹理在 `:1809`;DirectVulkan 在 `UniformManager.cpp:1073,1229` 与 `VulkanRenderer.cpp:11210`。
|
||||
|
||||
拆分后 draw 是 fire-and-forget,所以 `glDispatchCompute(); glMapBufferRange(SSBO,...,GL_MAP_READ_BIT);` 会在 server 还没 apply 前就走完 `AcquireMemoryRange` → `SyncGpuWrites()`(`BufferObject.cpp:454`)→ `m_gpuWritePending` 为 false → 立即 return(`BufferObject.cpp:266`)→ 应用拿到陈旧 shadow,零 round trip、零报错。这会以"看起来像 flaky"的形式打掉 P4 计划里的 `SsboArrayLengthScenario`、`AtomicCounterScenario`、`StorageBufferRegrowScenario` 一整族。
|
||||
|
||||
**规则**:`PublishImplicitState`(§5.1 步骤①)在每个 draw/dispatch 发射点保守置位,输入与 `DirectGLES.cpp:459-467/509/1809` 完全一致(client 全都有)。同时把 `emitSeq` 记进 `m_gpuWritePendingSeq`。在任一读入口(`glMapBuffer*`、`glMapBufferRange`、`glGetBufferSubData`、`glGetNamedBufferSubData`、`glCopyBufferSubData` 的源、`FillSubData`):若该 buffer 在 pending 集合里 → `Publish()` → 等 `appliedSeq >= recordedSeq` → 排空 `SEG_EVENT` → 再读。`EvGpuWritten{handle, ranges[]}` 只用于**取消**该 pending 项或**收窄** readback 范围,晚到无害。
|
||||
|
||||
同时,§7.4 的事件排空点必须补上 `glMapBuffer` / `glMapBufferRange` / `glGetBufferSubData` / `glGetNamedBufferSubData`——上一版的排空点列表(`glGetError`、`glGetQueryObject*`、`glClientWaitSync`、`eglSwapBuffers`)不含它们。
|
||||
|
||||
#### 5.6c GL 错误:分配类同步 ack,其余晚到
|
||||
|
||||
上一版把所有 backend `RecordError` 一律走"晚一批"事件,只给 CTS lane 留 `MOBILEGL_IPC_STRICT_ERRORS`。这在**分配探测**这个通用惯用法上是错的:那两个站点(`Managers.cpp:8679` renderbuffer 存储、`DirectGLES.cpp:6319` 纹理操作)报的是 `GL_OUT_OF_MEMORY`,而应用的标准写法是 `glRenderbufferStorage(...); if (glGetError() == GL_OUT_OF_MEMORY) { 用更小的目标重试; }`。晚到 ⇒ 应用走成功分支 ⇒ 往一块 server 从未分配的存储上渲染。
|
||||
|
||||
**规则**:只把**分配类**入口点标 `kNeedsAck`——`glRenderbufferStorage` / `glRenderbufferStorageMultisample` / `glNamedRenderbufferStorage*`、`glTexImage*` / `glTexStorage*` / `glCopyTexImage*` 中 backend 可能失败的形式、`glBufferStorage`。它们本来就罕见且昂贵,ack 几乎免费,换来 OOM 探测精确。其余全部保持晚到。有了这个划分,`MOBILEGL_IPC_STRICT_ERRORS` 从"CTS 专用"降级为纯诊断开关(默认 0,出问题时用来判断某个失败是不是错误时序引起的)。
|
||||
|
||||
`glGetError` 本身永远本地(`GL_Getter.cpp:2811-2817`;`Core.cpp:48-49` 的 "GL error state is GL-thread-owned" 不变式)。
|
||||
|
||||
### 5.7 composite pipeline program
|
||||
|
||||
`GLContext::GetProgramForDraw()`(`Core.cpp:612-660`)在 program-pipeline 路径下:join 每个 stage → `ComputeDrawProgramSignature()` → cache miss 时 **`MakeShared<ProgramObject>(0u)` 并 link 一个匿名 composite**(`Core.cpp:644`;注释明说"故意不是命名 program……不得占用应用可能拿到的 name"),随后 `RefreshCompositeUniforms`/`MirrorUniformValues` 每 draw 改它。
|
||||
|
||||
- **Phase 1-4(server relink)**:下发 pipeline 状态(`UseProgramStages` 等)+ 各 stage program 的 `RecProgramLinkOp`;server 的 replica 自己走同一路径构建自己的 composite。加一条 `RecResolvedProgramDigest{signature, reflectionDigest}` 让分歧当场暴露。
|
||||
- **Phase 5+(ProgramPublish)**:server 没有源码,**不得 link**。client 解析 composite,把它作为**保留高位 handle 的合成 program** 发布(`RecProgramPublish` + `RecSetResolvedDrawProgram{handle}`)。MG_State 加:
|
||||
```cpp
|
||||
// MobileGL/MG_State/GLState/Core.h (整段 #if MOBILEGL_BUILD_DISAGGREGATED 包裹,保证 monolith 字节不变)
|
||||
void SetReplicaResolvedDrawProgram(SharedPtr<ProgramObject>);
|
||||
void SetReplicaResolvedDispatchProgram(SharedPtr<ProgramObject>);
|
||||
// GetProgramForDraw()/GetProgramForDispatch() 首行先查该槽位
|
||||
```
|
||||
server 因此**永不 link、永不 join compile pool**,`PrepareForDraw` 首条语句照常工作。
|
||||
|
||||
### 5.8 全量快照 / resync
|
||||
|
||||
稳态**没有初始状态**:transport 在 `MG_Backend::Init()` 内建立,早于任何 GL 对象存在。
|
||||
|
||||
`ResyncSnapshot` 只服务三件事:**server 重启**、**backend context 丢失**(EGL surface 变更销毁整个原生 context 并 bump `g_backendContextGeneration`/`g_syncContextGeneration`,`DirectGLES.cpp:10664-10676`)、**硬 drain 后的纹理重发**(§5.6a)。实现 = 同一个 reconcile 遍历,关闭"已发送版本"门控。
|
||||
|
||||
**关键纪律:一个 applier、两个 producer**——快照发同样的记录种类,因而被同一套测试覆盖。`Feat/CS-Delta-IPC` 的结构性错误正是有一个与生产路径零共享代码的平行 applier(`StateEmitter.h:312-501` vs `ServerCore.cpp:389-401`)。
|
||||
|
||||
**P7 之后的限制**:adopted store 的字节住在 server,client 无法重建它们。因此 `MOBILEGL_IPC_RESPAWN=1` 与 `MOBILEGL_IPC_ADOPT_TIER != 2` 互斥:要么关采纳换可 resync,要么开采纳并接受 server 死亡 = context lost(不重启)。这条互斥必须在 `ConfigLoader` 里显式检查并 `MGLOG_W`。
|
||||
|
||||
### 5.9 覆盖度的**编译期**保证
|
||||
|
||||
#### 5.9a READ 面(backend 读了什么)
|
||||
|
||||
1. `scripts/gen_backend_state_surface.py` 扫描 `MG_Backend/**`,抽出 `pGLContext->X` 与前端对象 getter,生成 `MG_Remote/Protocol/generated/BackendStateSurface.inc`(**已提交**)。相对 `Feat/CS-Delta-IPC` 的 `extract_backend_read_inventory.py`:**删掉 `GetBuffer*`/`GetTexture*`/`GetProgram*`/`GetVertex*` 前缀兜底规则**(`:234-241`,它把"0 UNMAPPED"制造出来),未知 accessor 一律 `UNMAPPED`。同时把"真 pull point"与"signature handle 化"分开统计(那 167 个 "handle-ify" 里含 `BackendObject.h:158-186` 的**声明**和 `DirectGLES.cpp:55` 的静态全局)。
|
||||
2. 手维护 `MG_Remote/Protocol/Coverage.def`:`accessor → 记录种类 | MGL_COVER_LOCAL | MGL_COVER_NA(理由字符串)`。
|
||||
3. `MG_Remote/Client/CoverageAssert.cpp` 同时 include 两者,未映射 accessor → `#error`。
|
||||
|
||||
#### 5.9b MUTATOR 面(MG_Impl 在 table 调用旁改了什么)—— **本轮新增,是 §2(g) 的门**
|
||||
|
||||
1. `scripts/gen_impl_mutation_surface.py` 扫描 `MG_Impl/**`:找出**同时**包含 `gBackendFunctionsTable.GL.*` 或 `pActiveBackendObject->` 调用**和** `pGLContext->` mutator 调用(写方法:`Add*`/`Set*`/`Mark*`/`Bump*`/`Allocate*`/`Truncate*`/`Record*`/`Notify*`/`Begin*`/`End*`)的函数,把每个 mutator 站点写进 `MG_Remote/Protocol/generated/ImplMutationSurface.inc`(**已提交**)。为避免误报,脚本对每个函数做一次简单的调用图一层展开(`EnsureGeneratedMipmapStorageAllocated` 这种 helper 会被计入调用它的 `GenerateMipmap`)。
|
||||
2. 手维护 `MG_Remote/Protocol/MutationCoverage.def`:`函数::mutator → MGL_MUT_REPLAYED_BY(记录种类) | MGL_MUT_SHARED_HELPER(helper 名) | MGL_MUT_CLIENT_ONLY(理由) | MGL_MUT_NA(理由)`。
|
||||
3. 同一个 `CoverageAssert.cpp` 展开两张表,未映射站点 → `#error`。
|
||||
|
||||
已知必须在第一轮映射的条目(不是穷举,是脚本首次运行时保证不为空的锚点):
|
||||
- `GenerateMipmap` / `GenerateTextureMipmap` / `MaybeAutoGenerateMipmap` → `EnsureGeneratedMipmapStorageAllocated` 的 `AllocateStorage` / `MarkStorageDirty(false)` / `TruncateMipmapLevels` / `BumpContentVersion` ⇒ `MGL_MUT_REPLAYED_BY(RecGenerateMipmapLevels)`。applier 收到该记录后调**同一个共享 helper**(把 `EnsureGeneratedMipmapStorageAllocated` 抽到 `MG_Remote::Shared::` 或让 applier 直接调 `MG_Impl::GLImpl::TextureImpl::` 里那个已存在的函数——server 链接完整 MG_Impl,这是可行且最省的做法)。
|
||||
- `DrawArrays`/`DrawElements`/… 的 `AccountTransformFeedbackPrimitives` 六个计数器 ⇒ `MGL_MUT_REPLAYED_BY(RecXfbAccounting)`(applier 把六个增量加到 replica 的对应计数器上;必须跟着 `RecBindTransformFeedback` 的对象切换走,因为它们按 XFB 对象存取,`Core.cpp:1273,1296`)。
|
||||
- `glCopyTexSubImage*` 里 `CopyReadFramebufferIntoMipmapRegion` 的 `MarkStorageDirty(...,true)`(`GL_Texture.cpp:1095`)⇒ `MGL_MUT_CLIENT_ONLY`(该函数整体留在 client,见 §6.6)。
|
||||
- `glClearTexImage` 的 `MarkStorageDirty(...,true)`(`GL_Texture.cpp:1005`)⇒ `MGL_MUT_CLIENT_ONLY`(同上)。
|
||||
- `GL_Query.cpp` 的 conditional-render 布尔与查询结果缓存 ⇒ `MGL_MUT_CLIENT_ONLY`。
|
||||
|
||||
CI:两个生成器都重新生成 + `git diff --exit-code`。
|
||||
|
||||
**backend 长出一个 reconciler 走不到的 read,或 MG_Impl 长出一个 applier 没 replay 的 mutation → 编译失败,而不是设备回归。**
|
||||
|
||||
### 5.10 persistent map:client 侧的推送(本轮新增的独立小节)
|
||||
|
||||
**问题**(已在仓库确认):`BufferObject::SyncPersistentMappedRange()`(`BufferObject.cpp:238-250`)依次早退于 GPU-resident、非 Persistent、非 Write、FlushExplicit、空 range,剩下的情况(**persistent + write + coherent + shadow-backed**)走 `NotifySubData(整个 mapped range)`。它的全部生产调用点都在 `MG_Backend/` 里(19 处,见 §0)。P1-P6 默认关采纳(§6.8 T2),`AcquireMemoryRange`(`BufferObject.cpp:459-475`)于是回退到 shadow 并把 `m_resource.Bytes() + range.start` 交给应用——应用之后**不再调任何 GL 函数**就直接写。拆分后:client 没人推,server 的 replica `m_isMapped==false` 第一行就 return。字节丢失。
|
||||
|
||||
另外,`IsBufferDrawClean` 里 `if (frontend->IsMapped()) return false;`(`Managers.cpp:1447`,注释:"A live non-zero-copy map may owe a per-draw SyncPersistentMappedRange push")也依赖 map 位,replica 上恒 false 会把这个 buffer 判成 clean 而跳过整个同步。
|
||||
|
||||
**解法三件套**:
|
||||
|
||||
1. **map/unmap 上线**:`RecBufferMap{handle, rangeStart, rangeEnd, accessFlags}` 与 `RecBufferUnmap{handle}`,从 `glMapBuffer`/`glMapBufferRange`/`glUnmapBuffer`/`glFlushMappedBufferRange` 的 MG_Impl 入口发射(emit-ops 的 `FlushMappedRange` 已覆盖最后一个)。replica 的 `m_isMapped`/`m_mappedRange`/`m_mappingAccess` 于是与 client 一致,`IsMapped()` 门和 server 侧的 `SyncPersistentMappedRange` 都恢复 monolith 行为。
|
||||
|
||||
2. **client 侧脏块推送**:WireMirror 维护 `m_livePersistentMaps`(只装 persistent+write+非-FlushExplicit+非-GpuResident 的 buffer,进出由 `OnBufferMapped`/`OnBufferUnmapped` 维护)。`PublishImplicitState` 对**本次操作可达的**每个这类 buffer(VAO attribute buffer、index buffer、indirect/parameter buffer、UBO/SSBO/atomic binding point、XFB capture target——即 backend 那 19 个调用点的并集)做**块粒度**发送:把 mapped span 切成 64KiB 块,只发自上次发送以来被改过的块。
|
||||
|
||||
"被改过"的判定:P1-4 用**保守版**(每个发射点把该 buffer 的整个 mapped span 当脏,但按块拆成多条 `RecBufferSubData`,让 §6.5 的 range 合并与 ring 复用机制生效);P4.5 shadow-in-shm 落地后升级为**精确版**(shadow 住在 client 拥有的 `SEG_SHADOW` 里,用与 WAR 水位同一套 64KiB 块脏位跟踪;块脏位由 `SyncPersistentMappedRange` 的调用点触发一次 `memcmp` 或由 mprotect 写屏障提供——先做 `memcmp`,它对 1MB 块是 ~50µs 量级,且只在真正 mapped 的 buffer 上跑)。
|
||||
|
||||
**这是 §6.4 拷贝表里上一版完全没有的一行**,且在 P1-4 的保守版下代价可观(一个持久映射的 chunk arena 会在每个可达发射点重传整个 mapped span)。所以:`MOBILEGL_IPC_PERSISTENT_BLOCK_KB`(默认 64)可调,且**P1 验收必须记录这条路径的字节量**(Tracy 计数器分类为 `persistent-map-push`)。若 P1-4 的保守版在 Create/Flywheel fixture 上不可接受,把 P4.5 的精确版提前到 P2(这是计划里唯一一个允许因测量结果而改变阶段顺序的地方)。
|
||||
|
||||
3. **P1 就要有门**:新增 `PersistentCoherentMapScenario`(map PERSISTENT|WRITE|COHERENT、写、不做任何其它 GL 调用、draw、readback 校验),列为 P1 验收项。**今天计划里没有任何门能抓到这个 bug。**
|
||||
|
||||
**与 `MOBILEGL_COHERENT_AS_FLUSH` 的关系**:该开关(`GL_Buffer.cpp:297-305`,默认 false,`Config.h:174` / `ConfigLoader.cpp:185`)把应用请求的 persistent+FLUSH_EXPLICIT 改写成 coherent,从而**制造**上面这个情形。上一版禁止它在拆分模式下生效——但那只处理了"我们自己改写出来的 coherent map",没处理"应用自己就请求 coherent"。有了上面的三件套,两种来源都被覆盖,所以**禁令改为可选**:`MOBILEGL_COHERENT_AS_FLUSH` 在拆分模式下**照常生效**,这样 `tools/trace_replay/trace_cases.json` 里那两个带 `coherent_as_flush: true` 的用例(`minecraft-1.21.1-neoforge-create-indirect-in-world`、`minecraft-1.21.1-neoforge-create-instancing-in-world`)在 split 与 monolith 下走同一条 buffer 路径,P2 的逐名对比才有意义。若 P2 测出保守推送在这两个 fixture 上代价过高,改为"这两个用例在 split 模式下同时关掉该开关,并在报告里标注",而不是让两侧走不同路径还宣称对比通过。
|
||||
@@ -0,0 +1,403 @@
|
||||
---
|
||||
|
||||
## 6. 数据面
|
||||
|
||||
### 6.1 段(segment)布局
|
||||
|
||||
| 段 | 拥有者 | 默认大小 | 内容 |
|
||||
|---|---|---|---|
|
||||
| `SEG_CMD` | client(server 只读) | 8 MiB,2 的幂,64B 对齐 | `RingControl`(4KiB) + POD 记录 + ≤4KiB 内联负载 |
|
||||
| `SEG_STAGE` | client(server 只读) | 32 MiB → 上限由实测定,**不是默认 256 MiB** | bulk 字节:buffer sub-data、纹理区域、UBO scratch、client 顶点/索引/indirect 数组、persistent-map 脏块 |
|
||||
| `SEG_REPLY` | **server**(client 只读) | 8 MiB,4KiB slot | readback 像素、buffer writeback |
|
||||
| `SEG_EVENT` | **server**(client 只读) | 256 KiB SPSC ring | `EvQueryResult`/`EvGpuWritten`/`EvGlError`/`EvLogLine`/`EvDefaultFramebufferInfo`… |
|
||||
| `SEG_SHADOW[n]` | client(server 只读) | 每对象,P4.5+,≥256KiB shadow | 零拷贝 buffer/texture shadow |
|
||||
| `SEG_ADOPT[n]` | **server**(client RW) | 每 buffer,P7,≥16MiB adopted store | 应用直写 GPU 内存 |
|
||||
|
||||
创建:Android `ASharedMemory_create`(API 26,`android/sharedmem.h:78`;libc 的 `memfd_create` wrapper 是 API 30,`sys/mman.h:196`);桌面 Linux `syscall(SYS_memfd_create, …)`;macOS `shm_open`+`shm_unlink`;Windows `CreateFileMappingW`(`Local\`)。
|
||||
|
||||
**传递:POSIX `SCM_RIGHTS`,在第一个 transport commit 里实现**(asio 无 cmsg API → 在 `socket.native_handle()` 上裸 `sendmsg`/`recvmsg`,约 80 行)。`Feat/CS-Delta-IPC` 把它推迟到"P6"(`LocalSocketTransport.h:16-20`,`PollOffer` 里 `out->fd = -1` 硬编码于 `:296`),结果它的数据面在唯一重要的平台上**一个字节都过不去**。
|
||||
|
||||
**SEG_SHADOW 块的退休规则(本轮新增)**:§6.4 的 64KiB 块发送水位只解决"覆盖一个**活着的** shadow";它没说怎么**释放**一个 shadow。`glDeleteBuffers` 或 `glBufferData` 重定义会释放/重分配 `SEG_SHADOW` 的 arena 块,而携带 `{segId, offset, size}` 指向该块的记录可能还没被 apply——server 于是读到另一个对象的字节。规则:释放的块进入 pending 链表,只有当 `appliedSeq`(对被借入 GPU 时间线的 slot 是 `retiredSeq`)越过最后一条引用它的记录之后才归还 arena,而不是在对象析构时立即归还。
|
||||
|
||||
### 6.2 RingControl:watermark 是一条共享 cache line,**且带双向 doorbell**
|
||||
|
||||
```cpp
|
||||
// MobileGL/MG_Remote/Transport/Ring.h
|
||||
struct alignas(4096) RingControl {
|
||||
// ---- SEG_CMD 游标 ----
|
||||
alignas(64) std::atomic<Uint64> cmdHead; // producer:累计写入字节
|
||||
alignas(64) std::atomic<Uint64> cmdAppliedTail; // consumer:已解码并拷出的字节
|
||||
std::atomic<Uint64> cmdRetiredTail; // consumer:被借入 GPU 时间线的 slot 已释放
|
||||
// ---- SEG_STAGE 游标(独立三元组;上一版遗漏)----
|
||||
alignas(64) std::atomic<Uint64> stageHead;
|
||||
alignas(64) std::atomic<Uint64> stageAppliedTail;
|
||||
std::atomic<Uint64> stageRetiredTail;
|
||||
// ---- 序号 / 帧水位 ----
|
||||
alignas(64) std::atomic<Uint64> appliedSeq; // 已 apply 的记录序号
|
||||
std::atomic<Uint64> submittedSeq; // 已提交给驱动
|
||||
std::atomic<Uint64> retiredSeq; // GPU 已完成
|
||||
std::atomic<Uint64> completedFrameSerial;
|
||||
std::atomic<Uint64> presentAckSerial;
|
||||
// ---- doorbell / 代 ----
|
||||
alignas(64) std::atomic<Uint32> serverEpoch; // context 丢失 / server 重启时 ++
|
||||
std::atomic<Uint32> ringGeneration; // 硬 drain 后 ++,作废缓存 offset
|
||||
std::atomic<Uint32> consumerParked; // server 睡了,producer 要敲门
|
||||
std::atomic<Uint32> producerParked; // client 睡了,server 要敲门(本轮新增)
|
||||
std::atomic<Uint32> eventRingFull; // SEG_EVENT 满,server 已停止 apply
|
||||
std::atomic<Uint32> eventDropped; // 被丢弃的 EvLogLine 计数
|
||||
};
|
||||
```
|
||||
|
||||
**三个 seq 水位严格区分**(混为一谈是经典错误):`appliedSeq` 释放 `cmdAppliedTail`/`stageAppliedTail`;`submittedSeq` 释放 staging;`retiredSeq`/`completedFrameSerial` 释放 `*RetiredTail` 与 `SEG_ADOPT` 复用。
|
||||
|
||||
**两个 tail 是必须的**:`Ops_ResidentSubData` 把字节拷进 `pendingResidentWrites`(`Managers.cpp:1158-1166`),P7 之后 server 会**借用** ring slot 而不是再拷一次——那种 slot 只能在 `completedFrameSerial` 之后回收。单 tail 会在 P7 落地当天变成保守回收。
|
||||
|
||||
**SEG_STAGE 必须有自己的游标三元组**:§7.2 把"`SEG_STAGE` 余量 < 1/4"列为 Publish 触发器,而第二个 ring 的占用率无法从第一个 ring 的游标算出;且 stage slot 的退休条件(`retiredSeq`)与 cmd 记录(`appliedSeq`)不同。
|
||||
|
||||
#### 6.2a 双向 doorbell(本轮新增,修 "client 只能自旋" 的缺陷)
|
||||
|
||||
- **client → server**:consumer 自旋 ~200µs → 置 `consumerParked=1` → 在控制 socket 上阻塞读 1 字节;producer 在 release-store `cmdHead` 之后,仅当 `consumerParked` 时写 1 字节(字节码 `0x01 = 'ring advanced'`)。
|
||||
- **server → client**(上一版缺失):client 在**任何**等待里(present credit、`kNeedsAck` 阻塞请求、ring/stage 满的升级等待)先自旋 `MOBILEGL_IPC_SPIN_US`(默认 50µs),再置 `producerParked=1`,然后在同一个 socket 的反向流上阻塞读;server 在 release-store 任何 watermark 之后,仅当 `producerParked` 时写 1 字节(字节码 `0x02 = 'watermark advanced'`)。
|
||||
|
||||
没有这一条,上一版的每一处 client 等待都退化成跨进程自旋一条共享 cache line:present-credit 等待最长一整帧(60Hz 下 16.6ms),在手机上就是一颗大核满频空转,与 GPU 和游戏 JVM 抢核;§6.5 的"有界 50ms 等待"就是 50ms 自旋。而 MobileGL 全库没有任何亲和性控制(`grep -rn 'sched_setaffinity\|cpu_set_t' MobileGL/` 零命中),无法把它赶到小核上。
|
||||
|
||||
`spawn` 模式用 socketpair 的两个方向做 doorbell;`inproc` 模式用一对 `std::condition_variable`(同一套 `producerParked`/`consumerParked` 语义)。**零 futex/eventfd/named-event 平台代码**(asio 已 vendored,`3rdparty/asio/include` 已在主 target 的 include path 上,`CMakeLists.txt:483`)。
|
||||
|
||||
### 6.3 记录格式
|
||||
|
||||
```cpp
|
||||
// MobileGL/MG_Remote/Protocol/RecordKinds.h
|
||||
struct RecHeader { Uint16 kind; Uint16 flags; Uint32 size; }; // 8 B,size 含 header,8 字节倍数
|
||||
enum RecFlags : Uint16 { kNone=0, kNeedsAck=1<<0, kHasBlob=1<<1, kPad=1<<2, kBorrowSlot=1<<3, kVarTail=1<<4 };
|
||||
struct BlobRef { Uint32 seg; Uint32 pad; Uint64 offset; Uint64 size; }; // 24 B
|
||||
```
|
||||
**没有 per-record 序号字段**:seq 就是记录序数(producer `m_emitSeq++`,consumer `m_applySeq++`),省 8B/记录并消除一整类失步。
|
||||
|
||||
X-macro 单一真相源:
|
||||
```cpp
|
||||
// MobileGL/MG_Remote/Protocol/Records.def
|
||||
#define MGL_REC_LIST(X) \
|
||||
X(BindBuffer, RecBindBuffer, 24) \
|
||||
X(DrawArrays, RecDrawArrays, 32) \
|
||||
X(DrawElements, RecDrawElements, 56) \
|
||||
X(BufferSubData, RecBufferSubData, 64) \
|
||||
X(BufferMap, RecBufferMap, 40) \
|
||||
X(BufferUnmap, RecBufferUnmap, 24) \
|
||||
X(RenderStateBlob, RecRenderStateBlob, 40) \
|
||||
X(XfbAccounting, RecXfbAccounting, 56) \
|
||||
X(GenerateMipmapLevels, RecGenerateMipmapLevels, 32) \
|
||||
X(RenderbufferStorage, RecRenderbufferStorage, 40) \
|
||||
/* … ~95 项 … */
|
||||
#define MGL_REC_SIZE_CHECK(name, T, sz) \
|
||||
static_assert(sizeof(MobileGL::Wire::T) == (sz), #name " record size drift");
|
||||
MGL_REC_LIST(MGL_REC_SIZE_CHECK)
|
||||
```
|
||||
**每种一条 `static_assert`** ——修掉正是 `Feat/CS-Delta-IPC` 中过一次的 bug 类(`b50f3348`:"旧的 off-by-one 让 applier 误读 TexImage 之后的每一条 state delta"),而它那条只断言 union 首成员的 assert(`ServerCore.cpp:31-33`)永远抓不到中间插入。
|
||||
|
||||
**运行期边界纪律(本轮新增)**:`SEG_CMD` 是对端并发写入的区域,编译期 `static_assert` 管不到运行期损坏。同一个 X-macro 额外生成 applier 分发前的前置条件:
|
||||
```cpp
|
||||
#define MGL_REC_BOUNDS_CHECK(name, T, sz) \
|
||||
case RecKind::name: \
|
||||
if (h.size < (sz) || h.size > remainingRingBytes || (h.size & 7u)) \
|
||||
return Fatal(FatalCode::ProtocolCorruption, #name); \
|
||||
break;
|
||||
```
|
||||
`kVarTail` 记录额外校验 `定长前缀 + 尾巴自描述长度 == h.size`。违反一律 `Fatal{ProtocolCorruption}`,绝不进入未定义行为。
|
||||
|
||||
变长记录(`RecVaoConfig`、`RecTexSubImage` 的 rect 列表、`RecProgramLinkOp`、`RecMultiDrawArgs`):`kVarTail` + 定长前缀 + 自描述长度的内联尾巴。
|
||||
|
||||
### 6.4 WAR 危害与字节稳定性
|
||||
|
||||
**Phase 1-4 规则:GL 调用时刻把字节拷进 ring slot。** slot 从写入到 `stageAppliedTail` 越过它为止不可变,client 拿不回它 → **危害按构造消除**。代价是一次 memcpy,而 `Ops_ResidentSubData`(`Managers.cpp:1165`)和 `StageBlocksIntoUnpackRing` 在 monolith 里已经在付同样的钱。
|
||||
|
||||
**Phase 4.5 规则(shadow-in-shm,零拷贝):** ≥256KiB 的 shadow 分配在 client 拥有的 `SEG_SHADOW` 里——`PipeResource` 的 `MapAlignedAllocator`(`PipeResource.h:33-60`,无状态、25 行、64B 对齐)增加一个 shm arena(保留 `MIN_MAP_BUFFER_ALIGNMENT=64` 契约,`PipeResource.h:28`),`MipmapStorage` 的 level vector 同理。`RecBufferSubData` 于是只带 `{segId, offset, size}`,**client 侧零拷贝**。
|
||||
WAR 用 **per-shadow 64KiB 块发送水位**:若应用写入某块而该块最后一次发送尚未 `appliedSeq` 覆盖,这次写走 `SEG_STAGE`。有界、局部、压力下自动退化成 Phase-1 行为。这套块水位同时是 §5.10 精确版 persistent-map 推送的脏位来源。
|
||||
|
||||
**该改动必须整段 `#if MOBILEGL_BUILD_DISAGGREGATED` 包裹**:`PipeResource` 与 `MipmapStorage` 住在 `MG_State`,不在 `MG_Remote`,而改一个容器的 allocator 就改了类型;不包裹的话 §12/D8 的 `nm`/`.text` 门会在 P4.5 变红。写法是"分配器特化:option OFF 时逐字折叠成今天的 `MapAlignedAllocator`"。
|
||||
|
||||
#### 拷贝账(更正版,MC pan 一帧约 9MB section mesh + ~1MB UBO scratch)
|
||||
|
||||
上一版这张表把 monolith 和 split 两侧都数少了。逐条核对:
|
||||
|
||||
- monolith 的 `glBufferSubData` → shadow store 是 **2 次**:(1) app→shadow(`BufferObject::UploadSubData` 的 `Memcpy`),(2) shadow→目的地(`FlushPendingRangesNow`:`Memcpy(dst, bufferObject.MappedData()+start, size)` 进 invalidating map,`Managers.cpp:914`;或 `Memcpy(g_uploadRing.store.mappedPtr+ringOffset, ..., size)` 进 upload ring,`Managers.cpp:922`)。
|
||||
- split P1-4 是 **4 次**:app→client shadow (1)、client shadow→`SEG_STAGE` (2)、applier replay mutator ⇒ `SEG_STAGE`→**replica** shadow (3)、server 的 `FlushPendingRangesNow` ⇒ replica shadow→upload ring (4)。
|
||||
- P4.5 只去掉 (2),剩 **3 次**。它去不掉 (3),因为 `SEG_SHADOW` 是 client 拥有 / server 只读,而 replica 的 `BufferObject` 拥有自己的 `PipeResource` 分配。
|
||||
|
||||
| 路径 | monolith | P1-4 | P4.5 | P4.5+replica-adopt(可选,见下) |
|
||||
|---|---|---|---|---|
|
||||
| `glBufferSubData` → shadow store | 2 | 4 | 3 | **2** |
|
||||
| `glBufferSubData` → adopted store(P7) | 2 | — | — | 2 |
|
||||
| `glMapBufferRange(WRITE)`+unmap | 3 | 5 | 4 | 3 |
|
||||
| persistent coherent map 推送(§5.10 保守版) | 0 | 2/发射点 | 1/发射点(精确块) | 1/发射点 |
|
||||
| `glTexSubImage` | 2 | 3 | 2 | 2 |
|
||||
| 全局 UBO / draw | 1 | 2 | 2 | 1 |
|
||||
| adopted ≥16MiB(P7 T1/T0) | 0 | — | — | 0 |
|
||||
|
||||
**目标选择(必须在 P4.5 之前拍板)**:
|
||||
- **方案 A(默认,保守)**:接受 3 次,写进文档。P4.5 的价值是消掉 client 侧那次拷贝与那份重复内存。
|
||||
- **方案 B(激进,需额外设计)**:给 replica 的 `PipeResource` 增加**第三种模式** `AdoptedClientShadow`——`Bytes()` 返回 server 映射的 client `SEG_SHADOW`(只读),applier 的 `UploadSubData` 退化成一次 range 记账 + change-serial bump,只剩 server 的 ring 拷贝。这保持了 mutator replay 的全部副作用(包括 `IsBufferDrawClean` 比较的 change serial),只是不搬字节。风险:replica 的 shadow 变成只读会让任何 server 侧写(`WritebackFromBackend`、生成 mip、CopyImage 镜像)需要就地 copy-on-write 升级回普通 shadow。**先按方案 A 实现并测量,方案 B 作为 P6 的候选优化项,由 Tracy 计数器决定是否值得。**
|
||||
|
||||
无论选哪个,`TracyPlot` 字节计数器必须**装在 wire 两侧**(client 的 emit 字节 + server 的 apply 字节 + server 的 ring/staging 字节),P4.5 的验收看**总量**,不是只看 client 一侧的数字。
|
||||
|
||||
### 6.5 Ring 分配与背压
|
||||
|
||||
逐字移植 `PersistentRing`(`Managers.cpp:657-727`、`RingAllocateSlow` `:1891-1970`、`RingOnPresent` `:1975-2016`):单调 head/tail、2 的幂掩码、frame mark。分配失败升级:**扩容(翻倍) → 对最老未 retire 批次有界等待(默认 50ms,走 §6.2a 的 producerParked doorbell,不是自旋) → 硬 `Drain` 请求 + `ringGeneration` bump**。generation bump 上线,防止后续记录引用被回收的 offset;硬 drain 之后按 §5.6a 重发未 apply 的纹理记录。
|
||||
|
||||
`SEG_CMD` 与 `SEG_STAGE` 各自独立跑这套升级(各有自己的游标三元组)。
|
||||
|
||||
### 6.6 纹理
|
||||
|
||||
- **Unpack PBO 完全在 client 解析**(`GL_Texture.cpp:1719,1765,1887,1976,2457,2604,2722,4458,6176` 读 `pixelUnpackBufferObject->MappedData() + (SizeT)pixels`,再由 `ProcessTexturePixelsDataUnpack` 紧密重排)。**没有任何纹理像素以 PBO 引用形式过线,server 永远不需要 `GL_PIXEL_UNPACK_BUFFER` 状态。`PixelStoreBlob` 只用于 PACK 方向。**
|
||||
- **压缩纹理永不到达任何 backend**(前端在 `glTexImage` 时把压缩 internalformat 解析成非压缩后备,`GL_Texture.cpp:298-306`;`grep -i compress MG_Backend/DirectGLES/*.cpp` 只命中一条注释)。逐字节 `m_compressedData` blob 仅供 `glGetCompressedTexImage`,纯 client 侧,不过线。
|
||||
- **`glCopyTexSubImage*` 与 `glClearTexImage` 整体留在 client(推翻上一版的 P4 项)。** 已确认这两个入口今天就是**纯前端操作**:`CopyTexSubImage{1,2,3}D_State`(`GL_Texture.cpp:3955,3979`)调 `CopyReadFramebufferIntoMipmapRegion`(`:1044-1097`),它借一次 backend `ReadPixels` 进 CPU scratch(`:1079`)、逐行 memcpy 进 mipmap shadow(`:1089-1094`)、`MarkStorageDirty(...,true)`(`:1095`)。拆分后它恰好是**一次阻塞 ReadPixels round trip**,产生的脏区按普通纹理 delta 下发——正确,且不需要任何新命令。上一版提议"整体移到 server + `EvTexWriteback`"是错的:那个事件在 §7.4 的列表里根本不存在(只有 `EvBufferWriteback`),它仍然要付一次 round trip(client shadow 必须为 `glGetTexImage` 保持最新),还多出一个 `GLFunctionsTable` 里没有对应项的命令。`glClearTexImage`(`GL_Texture.cpp:985-1006`)同形。
|
||||
- **per-level `serverAuthoritative` 位**只保留给两处**字节确实在 backend 里写进 shadow** 的场景:生成 mip 的 CPU 路径(`DirectGLES.cpp:6270-6271,6861` 的 `AllocateStorage` + 直写 `MapMipmapData`)与 `MirrorCopyImageIntoDestinationShadow`(`:7144`,`glCopyImageSubData` 的目的地镜像)。client 在发射对应命令时对受影响 level 置位。`CopyTextureImageToClientOrPBO_State` 查它:**清 → 本地 shadow 回答,零 round trip**(应用自己上传的 level 全走这条);**置 → 一次 round trip**。
|
||||
|
||||
### 6.7 回读
|
||||
|
||||
| 路径 | monolith | 拆分后 |
|
||||
|---|---|---|
|
||||
| `glReadPixels` → 客户内存 | 阻塞 | 一次 round trip,像素放 `SEG_REPLY` slot;per-row 循环留在 server 内 |
|
||||
| `glReadPixels` → pack PBO | **也阻塞**(`DirectGLES.cpp:9189-9205` 把整个 PBO map 回来写 shadow) | **fire-and-forget** + client 侧对该 PBO 置 `MarkGpuWritten`(§5.6b),代价推迟到之后的 map/read。**严格优于 monolith** |
|
||||
| `glGetTexImage`/`glGetTextureImage` | DirectGLES 从 client shadow 回答 | DirectGLES **零 round trip**(除 `serverAuthoritative` level);DirectVulkan 一次 |
|
||||
| `glGetBufferSubData` / `glMapBuffer(READ)` on gpuWritePending | 阻塞(`glFinish()`,`Managers.cpp:1246`) | 一次,由 client 侧 pending 集合触发(§5.6b),被 `EvGpuWritten{ranges}` 收窄 |
|
||||
| XFB capture writeback | `glEndTransformFeedback` 里无条件无限 `ClientWaitSync`(`GL_Drawing.cpp:1326-1337`) | **不等**,client 对 capture target 置 `MarkGpuWritten`,首次读时付;`FixupGsStripCaptureOrder` 移到 server |
|
||||
| `glCopyTexSubImage*` | 内含一次同步 ReadPixels | 一次 round trip(保持前端实现不变) |
|
||||
|
||||
### 6.8 persistent map 与 ≥16MiB 采纳
|
||||
|
||||
三档,由**运行时 POST 探针**选择(遵循本项目"后端限制一律探针判定、绝不硬编码驱动名"的既定规则):
|
||||
|
||||
- **T2 — 拒绝(P1-6 默认,永久正确回退)**:`AcquirePersistentMap` 返回 `nullptr`。**此档下 §5.10 的 client 侧推送是强制的**,否则应用的 coherent persistent 写会丢。
|
||||
- **T1 — server 导出自己的映射(P7 主攻)**:server 照常铸造 coherent map(`Managers.cpp:988-1058` / `VkBufferManager.cpp:515-563`),经 `VK_KHR_external_memory_fd` / `AHardwareBuffer_sendHandleToUnixSocket`(API 26,`hardware_buffer.h:521`)/ `VK_KHR_external_memory_win32` / `GL_EXT_memory_object_fd` 导出,client `mmap` 后调 `PipeResource::AdoptPersistentMap(base)`。**每 store 生命周期一次 round trip。** 采纳成功后 §5.10 的推送对该 buffer 自动停止(`SyncPersistentMappedRange` 的 `IsGpuResident()` 早退),与 monolith 一致。
|
||||
- **T0 — server 导入 client 分配**:client 分配 `AHardwareBuffer`/dma-buf,server 以 `GL_EXT_external_buffer`+`glBufferStorageExternalEXT` 或 `VK_EXT_external_memory_host` 导入。理想但可用性未知。
|
||||
|
||||
**`MOBILEGL_COHERENT_AS_FLUSH` 在拆分模式下照常生效**(推翻上一版的禁令,理由见 §5.10 结尾):有了 client 侧推送,被改写出来的 coherent map 与应用原生请求的 coherent map 走同一条正确路径,两个 Create/Flywheel fixture 才能在 split 与 monolith 下做同路径对比。
|
||||
|
||||
### 6.9 program artifacts
|
||||
|
||||
- **P1-4**:`RecProgramLinkOp{handle, shaderSources[], bindAttribLocations[], bindFragDataLocations[], xfbVaryings[], xfbMode, separable, reflectionDigest}` — server 重新 link。只需 5 个 schema 字段,**且分歧不可能静默**(两半跑同一二进制里的同一段代码)。源码可得:`ProgramObject::GetLinkedShaderSnapshot()`(`ProgramObject.h:157`)刻意持有 linked shader 的 `SharedPtr`(注释在 `:1716`),所以 `glDeleteShader` 之后源码仍在。
|
||||
- **`reflectionDigest` 必须覆盖 backend 实际读的全集**:xxHash over
|
||||
`(uniformName, location, type, typeFacts, samplerOrImageUnitIndex)` 全表 + `maxUniformLocation` + `(blockName, blockBinding, blockSize)` 全表 + `shaderStorageBlockBindingOverrides` + `PointSizeDemoted` + `GetLinkedShaderStages` + `xfbVaryings/xfbStrides/xfbPackedStride/xfbBufferMode` + **`GetGeneratedSpirv()` 各 module 的 xxHash**。不匹配 → `Fatal{ReflectionDivergence}`。
|
||||
(理由:本项目自己的二分历史记录过"glslang 反射/生成顺序是真载重,桌面字节一致是语料受限的假绿"。)
|
||||
- **P5**:`RecProgramPublish{handle, stages[], spirvBlobs[], reflectionBlobRef}`,reflection 用 **`Visit()` 式归档**:
|
||||
```cpp
|
||||
// MobileGL/MG_State/GLState/ProgramState/ProgramArtifactsArchive.h
|
||||
template <class Ar> void Visit(Ar& ar, LinkArtifacts& a) { ar(a.writtenUniformLocationBits, /*…全字段…*/); }
|
||||
static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE,
|
||||
"新字段请加进 Visit() 并 bump MGL_LINKARTIFACTS_SIZE");
|
||||
```
|
||||
一份字段表服务两个方向 + `sizeof` 绊线。**序列化整个结构体**(而非 backend 当前读的 ~40 字段),这样 backend 新增一次 read 永不需要改协议。
|
||||
安装入口:`ProgramObject::InstallPublishedLink(LinkArtifacts&&, SpirvArtifacts&&, linkVersion, imageUnitVersion, backendStateVersion)`,绕过 `m_pendingLink`/`m_pendingSpirv`,**server 因此不需要 compile pool**。
|
||||
- `relink` 路径保留为常驻 oracle 与 A/B 对照(`MOBILEGL_IPC_PROGRAM=publish|relink`)。
|
||||
- 全局 UBO scratch 相反:小、每次 `glUniform*` 变、有版本 → 走 `SEG_STAGE`,键 `(programHandle, uboContentVersion)`,复现 monolith 的"每 program 每帧至多一次"(`DirectGLES.cpp:3369-3392`)。
|
||||
|
||||
### 6.10 应用指针(四类,范围全部可算)
|
||||
|
||||
| 类 | 范围 | 站点 |
|
||||
|---|---|---|
|
||||
| client 顶点数组(仅 DrawArrays 族) | `(first+count-1)*stride + elementSize` | `Managers.cpp:2560`、`VulkanRenderer.cpp:3737` |
|
||||
| client 索引数组 | `count * indexSize` | `DirectGLES.cpp:4436`、`VulkanRenderer.cpp:4081` |
|
||||
| client indirect / parameter 块 | `stride*(drawcount-1)+cmdSize` | `DirectGLES.cpp:276`、`DirectVulkan.cpp:303` |
|
||||
| `MultiDraw*` 参数数组、`ClearBuffer*` value | `drawcount*4`、16B | `DirectVulkan.cpp:963-1057` |
|
||||
|
||||
唯一无界的是**索引 draw 下的 client 顶点数组**:索引扫描(`TryComputeMaxIndexFromHostBytes`,`VulkanRenderer.cpp:3406-3470`)必须在 **client** 侧跑,只有 client 同时持有两个数组。实现于 `MG_Remote/Client/ClientArrayBounds.cpp`,两个 backend 共用。
|
||||
|
||||
**陈旧索引危害(本轮新增)**:monolith 在每次这类扫描之前都调 `indexBuffer->SyncGpuWrites()`(`DirectGLES.cpp:4413`、`MultiDraw.cpp:499`、`VulkanRenderer.cpp:3431,4159`),因为 EBO 可能刚被 compute shader 或 XFB 写过。client 侧扫的是 client shadow,若不做同样的强制回读,算出的 `maxIndex` 来自陈旧字节,顶点数组会被少拷 → 几何缺失/花屏,或越界读应用数组。同样的暴露面还有 primitive-restart 重写(`DirectGLES.cpp:4412-4414`)与 `*IndirectCount` 的 parameter buffer 读(`DirectGLES.cpp:4666-4693,4768-4793`)。
|
||||
|
||||
**规则**:`ClientArrayBounds`、restart 重写、indirect-count 读者在触碰 shadow 之前,必须走 §5.6b 的 pending 检查(Publish + 等 `appliedSeq` + 排空事件),即 monolith 里 `SyncGpuWrites()` 所在的**同一个位置**。P2 增加 `ClientArrayAfterComputeWriteScenario` 作为门。
|
||||
|
||||
draw 记录里 `indicesAreClient` 由"是否绑定了 element array buffer"决定(`DirectGLES.cpp:4423` vs `:4425-4442`),在 binding 所在的一侧判定。
|
||||
|
||||
---
|
||||
|
||||
## 7. 控制面
|
||||
|
||||
### 7.1 FlatBuffers 用法
|
||||
|
||||
**一份 schema `MobileGL/MG_Remote/Protocol/protocol.fbs`,两种用法:**
|
||||
- **热路径 → FlatBuffers `struct`**(flatc 保证定长布局、无 vtable、无偏移间接、无需 verifier walk,只需边界检查),直接放进 ring:`[RecHeader | struct | 可选变长尾]`。`DrawArrays` = 8+24 = 32B(对比 table-per-command 的 ~60B 与一次 vtable 遍历)。这正是 `Feat/CS-Delta-IPC` 自己的 plan 第 55 行要求而实现没做的事。
|
||||
- **罕见/变长/需演进 → FlatBuffers `table`**,走 CTRL socket。
|
||||
|
||||
```fbs
|
||||
namespace MobileGL.Wire;
|
||||
|
||||
// ---------- 热路径 struct(进 ring)----------
|
||||
struct WireHandle { kind:ubyte; p0:ubyte; p1:ubyte; p2:ubyte; glName:uint; lifetimeId:ulong; }
|
||||
struct BlobRef { seg:uint; pad:uint; offset:ulong; size:ulong; }
|
||||
struct RecBindBuffer { target:uint; index:uint; h:WireHandle; }
|
||||
struct RecDrawArrays { mode:uint; first:int; count:int; instances:int; baseInstance:uint; pad:uint; }
|
||||
struct RecDrawElements { mode:uint; count:int; type:uint; flags:uint; indices:ulong; blob:BlobRef; }
|
||||
struct RecBufferSubData { h:WireHandle; offset:ulong; size:ulong; blob:BlobRef; }
|
||||
struct RecBufferMap { h:WireHandle; rangeStart:ulong; rangeEnd:ulong; access:uint; pad:uint; }
|
||||
struct RecBufferUnmap { h:WireHandle; }
|
||||
struct RecTexSubImage { h:WireHandle; target:uint; level:uint; box:[uint:6]; rectCount:uint;
|
||||
pad:uint; blob:BlobRef; } // rects 在变长尾
|
||||
struct RecGenerateMipmapLevels { h:WireHandle; target:uint; requiredLevelCount:uint;
|
||||
bytesPerTexel:uint; shrinkingAxes:uint; }
|
||||
struct RecRenderbufferStorage { h:WireHandle; internalFormat:uint; width:int; height:int;
|
||||
samples:int; pad:uint; }
|
||||
struct RecXfbAccounting { pausedPrims:ulong; inputPrims:ulong; prims:ulong;
|
||||
capturedVerts:ulong; geomDraws:uint; accountedDraws:uint; }
|
||||
struct RecRenderStateBlob{ version:ushort; pipelineVersion:ushort; pad:uint; blob:BlobRef; }
|
||||
struct RecPresent { frameSerial:ulong; swapInterval:int; pad:uint; }
|
||||
struct RecSetResolvedDrawProgram { h:WireHandle; }
|
||||
// … 共约 95 个
|
||||
|
||||
// ---------- 控制面 table(走 socket)----------
|
||||
table SegmentRef { id:uint; kind:ubyte; sizeBytes:ulong; name:string; }
|
||||
table Hello { abiMajor:uint; abiMinor:uint; buildFingerprint:string; backendType:uint;
|
||||
pid:uint; configBlob:[ubyte]; }
|
||||
table Welcome { abiMajor:uint; abiMinor:uint; serverPid:uint;
|
||||
cmdRing:SegmentRef; stageRing:SegmentRef; replyPool:SegmentRef; eventRing:SegmentRef; }
|
||||
table CapsSnapshot { dynamicParameters:[ubyte]; // DynamicBackendParameters 逐字节
|
||||
rendererInfo:[ubyte]; formatCaps:[ubyte]; extensions:[string];
|
||||
apiVersion:string;
|
||||
maxComputeWorkGroupCount:[int:3]; maxComputeWorkGroupSize:[int:3];
|
||||
tableSlotMask:ulong; // 远端实际注册了哪些 GLFunctionsTable 槽
|
||||
prefersCpuXfbPrimitiveAccounting:bool; }
|
||||
table DefaultFramebufferInfo { width:int; height:int; colorFormat:uint; depthFormat:uint; stencilFormat:uint; }
|
||||
table SurfaceOp { seq:ulong; kind:ubyte; display:ulong; surface:ulong; windowKind:ubyte;
|
||||
nativeToken:ulong; width:int; height:int; swapInterval:int; }
|
||||
table SurfaceReply { seq:ulong; ok:bool; eglMajor:int; eglMinor:int; defaultFb:DefaultFramebufferInfo; }
|
||||
table ProgramReflection { /* Visit() 归档的结构化镜像,P5 */ }
|
||||
table ResyncRequest { serverEpoch:uint; } table ResyncDone {}
|
||||
table AuxRequest { seq:ulong; kind:ubyte; payload:[ubyte]; } // 外来线程 sync/query
|
||||
table Fatal { code:uint; message:string; }
|
||||
table LogLine { level:ubyte; text:string; }
|
||||
union CtrlMsg { Hello, Welcome, CapsSnapshot, SurfaceOp, SurfaceReply,
|
||||
ProgramReflection, ResyncRequest, ResyncDone, AuxRequest, Fatal, LogLine }
|
||||
table CtrlEnvelope { msg:CtrlMsg; }
|
||||
root_type CtrlEnvelope;
|
||||
```
|
||||
|
||||
`protocol_generated.h` **提交进仓库**,由 `scripts/gen_protocol.py` 重新生成(镜像 `tools/trace_replay/CMakeLists.txt:52-69` 驱动 `glproc.py` 的做法);CI 加 `flatc-check` 步骤重新生成并 `git diff --exit-code`。
|
||||
|
||||
**codegen 绝不进默认构建图(本轮加强)**:`Feat/CS-Delta-IPC:MobileGL/Protocol/CMakeLists.txt:22-38` 在 `MOBILEGL_FLATC_EXECUTABLE` 未设时 `add_subdirectory(3rdparty/flatbuffers)` 并开 `FLATBUFFERS_BUILD_FLATC ON`——这正是它自称要修的 NDK 陷阱(交叉编译造出 arm64 `flatc` 然后在 host 上执行)。**本计划不复用这一段**:`gen_protocol.py` 是纯开发者/CI 目标,默认构建图里没有 `flatc`,`MOBILEGL_FLATC_EXECUTABLE` 只服务 CI 的 `flatc-check`。FlatBuffers 运行时是 header-only,只需要 `3rdparty/flatbuffers/include` 在 include path 上(P4 用 `nm` 复核 `libMobileGL.so` 链接行没有新增库,不靠断言)。
|
||||
|
||||
### 7.2 帧封装与 flush 策略
|
||||
|
||||
CTRL socket 封帧:`[u32 'MGLF'][u32 len][payload]`,64MiB 上限,**读时校验**(`Feat/CS-Delta-IPC` 的 `Feed()` 永远返回 OK,坏 magic 变成静默永久挂起,`Framing.h:41-45`;`StartRead` 直接按 wire 长度分配无上限检查,`LocalSocketTransport.cpp:232-236`)。接收缓冲不足时**返回所需大小并保留消息**(上一版的 transport 会失败且不弹出消息,把流永久卡死)。
|
||||
|
||||
#### Publish 触发器(重写,删掉 64KiB 阈值)
|
||||
|
||||
上一版设 "records ≥ 64KiB" 为主触发器。按 §6.3 的记录尺寸,64KiB ≈ 1200-2700 条记录,即**一整帧**(计划自己把 MC 帧估为 1000-4000 draw)。那意味着 server 在 client 发完整帧之前无法开始工作——这不是异步,是一个整帧的流水线气泡,且在 present credit 之上再加一整帧延迟。它还在 P2.5 跑之前就先把 P2.5 的假设否掉了(inproc 的全部意义就是让 `PrepareForDraw` 与 GL 线程重叠,帧粒度 publish 保证零重叠)。而 `SEG_CMD` 是 SPSC ring,"publish" 只是一次 `cmdHead` 的 release store,唯一值得摊销的是门铃写。
|
||||
|
||||
**新规则**:
|
||||
- **每条记录(或每 8-16 条,用来摊销 store)release-store `cmdHead`**;仅当 `consumerParked` 时敲门铃。
|
||||
- 显式门铃点:`Present`、任何 `kNeedsAck` 阻塞请求、`eglMakeCurrent`、`glFlush`(**刷出 outbox,不等待**)。
|
||||
- **`SEG_STAGE` 余量 < 1/4** 时敲门铃(用 `stageHead - stageAppliedTail`)。
|
||||
- **轮询类入口点也是门铃点(本轮新增,修 livelock)**:`glClientWaitSync`(任意 timeout)、`glGetSynciv(GL_SYNC_STATUS)`、`glGetQueryObject*(GL_QUERY_RESULT_AVAILABLE | GL_QUERY_RESULT_NO_WAIT)`。
|
||||
理由:GL 的标准惯用法是 `glFenceSync(); while (glClientWaitSync(s, GL_SYNC_FLUSH_COMMANDS_BIT, 0) == GL_TIMEOUT_EXPIRED) {}` 与 `while (!avail) glGetQueryObjectuiv(id, GL_QUERY_RESULT_AVAILABLE, &avail);`。循环里没有别的 GL 调用,若这些入口不 publish,`RecFenceSync` 就永远躺在 ring 里,server 看不到,watermark 不动,循环永久自旋——这是挂死,不是变慢。仓库自己在意这件事:`DirectVulkan.cpp:1158-1160` 写明 "GL_SYNC_FLUSH_COMMANDS_BIT: flush regardless of timeout, so a zero-timeout poll loop makes progress across calls",而 MG_Impl 无条件把 flags 透传给 backend(`GL_Sync.cpp:96`)。
|
||||
**携带 `GL_SYNC_FLUSH_COMMANDS_BIT` 的调用无条件 publish**(spec 要求 flush)。
|
||||
- **饥饿升级**:同一个 handle 连续 N 次(默认 64,`MOBILEGL_IPC_POLL_ESCALATE`)本地回答 `TIMEOUT_EXPIRED` / "未就绪" 而 watermark 毫无移动时,升级成一次阻塞 round trip,这样一个已经卡住的 server 不会把 client 自旋成死循环。
|
||||
|
||||
**`glFinish` 保持纯 no-op**(`Definitions.cpp:111-112`)——应用唯一的强制停顿手段在 monolith 里免费,拆分后也必须免费。
|
||||
|
||||
### 7.3 序号与 credit
|
||||
|
||||
seq = 记录序数。**两个互相独立的窗口,绝不是 per-batch 锁步**(`Feat/CS-Delta-IPC` 在 apply 循环里同步发 ack,`ServerCore.cpp:421-429`,是最差的节奏;而且它的 credit 算成 `baseSeq + items.size()`,只有 `baseSeq==0` 时才对):
|
||||
|
||||
- **字节 credit**:`SEG_CMD` 与 `SEG_STAGE` 各自的占用,升级路径见 §6.5。
|
||||
- **Present credit**:`eglSwapBuffers` 在 `presentsSent - presentAckSerial >= MOBILEGL_IPC_PRESENT_CREDIT`(**默认 1**,见 §9)时阻塞。
|
||||
|
||||
server 端**不发 credit 消息**:它对 `RingControl` 做 release store,consumer 每 64 条记录更新一次 `appliedSeq`,并在 `producerParked` 时敲反向门铃。
|
||||
|
||||
### 7.4 事件回传通道
|
||||
|
||||
`SEG_EVENT` 是 server→client 的 SPSC POD ring:`EvQueryResult{handle, available, value}`、`EvFenceSignaled{handle}`、`EvGpuWritten{handle, rangeCount, ranges[]}`、`EvBufferWriteback{handle, offset, BlobRef}`、`EvReadbackDone{seq, BlobRef}`、`EvGlError{code}`、`EvDefaultFramebufferInfo`、`EvCompileEnvInvalidate`、`EvLogLine{level,len,text}`。
|
||||
|
||||
#### 排空点(补齐)
|
||||
|
||||
client 在下列位置排空:`glGetError`、`glGetQueryObject*`、`glClientWaitSync`、`glGetSynciv`、`eglSwapBuffers`、**`glMapBuffer` / `glMapBufferRange` / `glGetBufferSubData` / `glGetNamedBufferSubData` / `glCopyBufferSubData`**(§5.6b 要求),以及**每一次等待循环的每一轮**(present credit、`kNeedsAck`、ring/stage 满)。最后一条是必须的,见下。
|
||||
|
||||
#### 溢出策略(本轮新增,修一个双向死锁)
|
||||
|
||||
上一版没说 `SEG_EVENT` 满了怎么办,也没要求 client 在**等待中**排空。具体死锁:client 卡在 `eglSwapBuffers` 等 present credit;server 的 apply 线程一边 apply 一边产 `EvLogLine` 与 `EvGpuWritten`;`SEG_EVENT` 满;apply 线程阻塞在生产上;`presentAckSerial` 永不前进;client 永不离开 `eglSwapBuffers`,因而永不排空。两边都死。
|
||||
|
||||
**策略**:
|
||||
1. client **必须**在每个等待循环内排空 `SEG_EVENT`,不只是在入口点边界。
|
||||
2. `EvLogLine` 是**有损**的:覆盖最旧,并累加 `RingControl.eventDropped`(client 在排空时把丢失条数打进日志)。丢一条日志绝不允许卡住渲染。
|
||||
3. 语义承载事件(`EvGpuWritten`、`EvReadbackDone`、`EvFenceSignaled`、`EvBufferWriteback`、`EvGlError`、`EvDefaultFramebufferInfo`、`EvCompileEnvInvalidate`)**无损**:ring 装不下时 server 置 `RingControl.eventRingFull=1` 并**停止 apply**(停在一条记录的边界上,不是记录中间),敲反向门铃;client 排空后清标志并敲正向门铃。状态因此永远可恢复。
|
||||
4. 故障注入测试:在 client 被 credit 阻塞时灌满 `SEG_EVENT`,与 P8 的 SIGKILL 测试并列。
|
||||
|
||||
server 侧的 `MGLOG` 与延迟诊断按流顺序 replay 进 client 日志流——复用已存在的 `DeferredLogLine`/`ApplyDeferredDiagnostics` 机制(`JobNode.h:26-58,149-158`)。
|
||||
|
||||
---
|
||||
|
||||
## 8. Roundtrip 清单
|
||||
|
||||
### 不可避免的阻塞点
|
||||
|
||||
| # | 站点 | 频率 | 为什么 |
|
||||
|---|---|---|---|
|
||||
| 1 | 握手 `Hello`/`Welcome` + 段 fd 传递 | 一次 | — |
|
||||
| 2 | `InitializeEGLDisplay`(写 `major`/`minor`) | 一次 | 出参 |
|
||||
| 3 | `CreateEGL{Window,Pbuffer}Surface` / `Resize` | 罕见 | 返回 `Bool`;回复顺带 `DefaultFramebufferInfo` |
|
||||
| 4 | 首次 `MakeEGLCurrent` + `InitCapabilities` → `CapsSnapshot` | 每 surface 一次 | caps 只在那一刻才存在(`BackendObject.cpp:341-347`) |
|
||||
| 5 | `glReadPixels` → 客户内存 | 罕见(CTS 热) | GL 要求返回时字节已就位 |
|
||||
| 6 | `glCopyTexSubImage*` / `glClearTexImage`(内含 ReadPixels) | 罕见 | 前端实现本来就借一次 ReadPixels |
|
||||
| 7 | `glGetTexImage`/`glGetTextureImage`(DirectVulkan;DirectGLES 仅 `serverAuthoritative` level) | 罕见 | — |
|
||||
| 8 | `glGetBufferSubData` / `glMapBuffer(READ)` on client-pending | 罕见 | monolith 里本来就阻塞;client pending 集合触发 |
|
||||
| 9 | client 顶点数组的索引扫描 / restart 重写 / indirect-count 读(当 EBO 在 pending 集合里) | 罕见 | monolith 在同一位置调 `SyncGpuWrites()` |
|
||||
| 10 | `glClientWaitSync(timeout>0)` 超出 watermark | 每帧级 | 应用请求的等待 |
|
||||
| 11 | `glGetQueryObject*(GL_QUERY_RESULT)` 未完成;`glBeginConditionalRender` | 罕见 | `GL_Query.cpp:300`、`:705-706`(后者注释明说"by WAITING even for the _NO_WAIT modes") |
|
||||
| 12 | 轮询饥饿升级(连续 N 次无进展) | 极罕见 | 防死锁保险 |
|
||||
| 13 | **分配类入口点的错误 ack**(`glRenderbufferStorage*`、部分 `glTexImage*`/`glTexStorage*`/`glCopyTexImage*`、`glBufferStorage`) | 罕见 | OOM 探测惯用法(§5.6c) |
|
||||
| 14 | `AcquirePersistentMap`(仅 P7 T1) | 每 store 一次 | 返回映射 |
|
||||
| 15 | ring/stage 耗尽、present credit | 节奏 | 非语义 |
|
||||
|
||||
### 变成异步或本地的
|
||||
|
||||
- 全部 20 个 draw、9 个 clear、blit/copy、`GenerateMipmap`、dispatch、barrier、image bind、7 个 XFB 跨度标记、`PatchParameteri`、`ShaderStorageBlockBinding`(权威状态已在 client,`GL_Program.cpp:3391`)、所有 buffer/texture/program/VAO/FBO delta、`Present`。
|
||||
- **`glGetError` 永远本地**(`GL_Getter.cpp:2811-2817`;`Core.cpp:48-49` 的不变式)。
|
||||
- **`glFinish`/`glFlush` 保持免费**。
|
||||
- **89 个 caps 站点全部本地**(45 `GetDynamicParameters` + 8 `GetRendererInfo` + 4 `GetFormatCapabilities` + 3 `GetBackendType` + `IsTimerQuerySupported` + `PrefersCpuXfbPrimitiveAccounting` + `BeginOcclusionQuery!=nullptr`)。
|
||||
- **`glGetIntegeri_v` 全部本地**;`glDispatchCompute` 的三次 per-dispatch 校验查询(`GL_Drawing.cpp:719`)改读 `CompileEnv::maxComputeWorkGroupCount`(`CompileEnv.h:52-54`)。
|
||||
- **`GetInteger64i_v`、`GetProgramiv` 删除**。
|
||||
- **`FenceSync`、`Begin{TimeElapsed,Occlusion,XfbPrimitives}Query`、`QueryCounterTimestamp` → client 铸造 handle**,fire-and-forget(前端本来就铸造应用可见的名字:`GL_Sync.cpp:61`、`GL_Query.cpp:54`)。
|
||||
- **`GetSyncStatus`、`ClientWaitSync(0)`、`IsQueryResultAvailable`、`GetQueryResult64(wait=false)` → 先 publish(§7.2),再从水位一次 acquire load 回答**。miss 返回 `GL_UNSIGNALED` / "未就绪",两处契约明确允许(`BackendObject.h:210-214`、`:236-241`;`GL_Query.cpp:302-311` 已遵守:读 0、**不缓存**、保留 backend handle)。
|
||||
- **`glReadPixels` 进 PBO → fire-and-forget**(配 client 侧 `MarkGpuWritten`),比 monolith 更好。
|
||||
- **`glEndTransformFeedback` 的无限 fence 等待取消**(配 client 侧对 capture target 置 `MarkGpuWritten`)。
|
||||
|
||||
**稳态帧:零 round trip**(对不使用 conditional render / 阻塞式 query / 分配类调用的帧而言;见 §15 P3 的门措辞修正)。
|
||||
|
||||
### fence 完成度必须来自真 fence,不是 present 水位(本轮新增)
|
||||
|
||||
上一版让 `retiredSeq`/`completedFrameSerial` 兜底 fence 语义。但在 DirectGLES 上这两个水位**只在 `Present()` 里前进**(`DirectGLES.cpp:10626-10643` 在 `eglSwapBuffers` 之后轮询 4 深 fence ring),或在 `WaitForFrameSerialCompleted`(`:10583-10607`)里。帧中创建的 fence 于是要等到**下一次 present 退休**才报 signalled,即 fence 完成度退化成帧计数推断。`DirectVulkan.cpp:1120-1128` 恰恰写明这是被修掉的 bug:完成度必须"track the GPU itself rather than the frame-count inference; MC 1.21.5's fence-paced ring buffers depend on this to recycle their space instead of growing without bound",而项目记忆 `magma-mc1215-fence-oom` 记录了它曾导致 native-heap OOM kill。
|
||||
|
||||
**规则**:`RecFenceSync` 在 server 侧转成一次**真实的 backend `FenceSync()`**;server 用自己已有的逐 fence 轮询(DirectGLES 有 `WaitForFrameSerialCompleted` 的 fence 选择逻辑 `:10586-10600` 可复用;DirectVulkan 有 `IsSubmitIndexComplete`)在**非 present 时刻**也推进,并发 `EvFenceSignaled{handle}`。client 的本地快路径读的是"由真实逐 fence 退休导出的 handle 水位",不是 present 水位。
|
||||
|
||||
### 三个应先独立落到 `dev` 的 monolith 修复(可二分、monolith 自身受益)
|
||||
1. `glEndTransformFeedback` 的无条件无限 `ClientWaitSync`(`GL_Drawing.cpp:1326-1337`)→ 用既有 `MarkGpuWritten`/`SyncGpuWrites` 推迟到首次读。
|
||||
2. `glDispatchCompute` 三次 `GetIntegeri_v` → `CompileEnv`。
|
||||
3. 删除 `GetInteger64i_v`/`GetProgramiv` 两个死表项及两个 backend 的实现。
|
||||
|
||||
---
|
||||
|
||||
## 9. Present 与帧节奏
|
||||
|
||||
`eglSwapBuffers` → `EGLImpl::SwapBuffers`(`EGLImpl.cpp:162-183`)→ `BackendObject::SwapEGLBuffers`(`BackendObject.cpp:369-398`,其线程归属校验全部对 client 镜像的 EGL 状态求值,**不需要回复**)→ 发 `RecPresent{frameSerial, swapInterval}` → publish + 敲门铃 → 返回,除非 `presentsSent - presentAckSerial >= MOBILEGL_IPC_PRESENT_CREDIT`。
|
||||
|
||||
**`Present` 与应用的 `eglSwapBuffers` 严格 1:1,绝不批量。** Magma 侧四次 `OnFrameBoundary()` 缓存老化、`TryDrainFrameTransients` 和全部四次 `BeginFrame` 只在 `Present` 内发生(`VulkanRenderer.cpp:12765-12904`);Espryt 侧三个 ring 与 `TrimBufferPool` 在那里 retire(`DirectGLES.cpp:10646-10649`)。批量会饿死这些排空。
|
||||
|
||||
### 9.1 延迟是叠加的:credit 默认改为 1
|
||||
|
||||
上一版设 credit=2 并论证它"镜像系统已有预算",因此"不引入新的停顿类别"。停顿**类别**确实不新,但**延迟会叠加**,而上一版没有把它加起来:
|
||||
|
||||
- server 自己的 `Present` 在返回之前就已经等了 2-3 帧:`VulkanRenderer::Present` 末尾调 `FrameContext::WaitAndAcquireNextImage`,其第一条语句是 `vkWaitForFences(device, 1, &frame.imageInFlightFence, VK_TRUE, timeout)`(`FrameContext.cpp:288-290`)。`presentAckSerial` 因此只能在那次等待完成后才前进。
|
||||
- 一个被允许领先 2 个 present 的 client,叠在一个自身已领先 GPU 2-3 帧的 server 上 = **端到端 4-5 帧**,60Hz 下 66-83ms,对第一人称游戏不可接受。
|
||||
- 现有的验收门都看不见它:SSIM 是帧内容比较,`bench.sh` 量的是 FPS,都不是 input-to-photon。
|
||||
|
||||
**规则**:`MOBILEGL_IPC_PRESENT_CREDIT` **默认 1**(可配 1-4)。文档里写明叠加公式:`端到端 ≈ client credit + server FIF + 驱动深度`。P3 与 P9 的验收增加**输入延迟测量**:用已有的 `GetGpuTimestampNs` 与 trace-replay `--benchmark` 的逐帧 JSON 构建 "记录发射时刻 → present 完成时刻" 直方图;只有当实测吞吐收益能抵掉实测延迟代价时才调高 credit。
|
||||
|
||||
参考基线:`MagmaFramesInFlight = 3` 钳到 `[2, maxImageCount]`(`VulkanRendererConfig.h:14-19`、`VulkanRenderer.cpp:3051-3058`),Espryt 深度 4 的 fence ring 刻意高于驱动的 2-3(`DirectGLES.cpp:10071-10074`)。
|
||||
|
||||
### 9.2 swap interval 与 Magma
|
||||
|
||||
Swap interval 搭 `RecPresent` 过去。注意 Magma 从不注册 `SetSwapInterval`(`BackendObject_DirectVulkan.cpp:698` 只注册 `Present`)且偏好 `MAILBOX`/`IMMEDIATE`(`SwapchainObject.h:74-79`),因此 **IPC credit 成为 Magma 唯一的显式限帧器** —— 记录在案,P6/P9 在设备上测量输入延迟与帧节奏;若 Magma 需要,把"注册 `SetSwapInterval` 并映射到 FIFO"作为**独立的 `dev` 变更**,不让两套机制同时管节奏。
|
||||
|
||||
### 9.3 无 present 循环下的水位饥饿
|
||||
|
||||
`retiredTail` 的回收依赖 server 发布准确的 `completedFrameSerial`。DirectVulkan 有 `TryDrainFrameTransients`/`RefreshCompletedSubmits` 可以在非 present 时刻推进,**DirectGLES 没有对应物**:`g_completedFrameSerial` 只在 `Present()` 里(`DirectGLES.cpp:10626-10643`)和 `WaitForFrameSerialCompleted`(`:10583-10607`,且要求存在覆盖目标 serial 的活 fence,slot 被回收时返回 false)前进。在无 present 的负载里——`tools/cts` 的 `run_cts_local.py`、回读循环、从不 swap 的 `MG_IntegrationTest` 场景——一个 fence 都不会被插入,`retiredTail` 永不前进,`SEG_STAGE` 填满,§6.5 的升级路径在每个用例上都跑到硬 drain。那会把一次 CTS run 变成一连串 50ms 等待加整体 drain,并可能被误读成一致性回归。
|
||||
|
||||
**规则**:给 DirectGLES 的 server 加**非 present fence tick**——距上次 `Present` 超过阈值(默认 8ms)或每 N 条已 apply 记录(默认 4096)时,插入一个 `glFenceSync` 并轮询 fence ring,复用 `g_frameFenceRing` 机制。同时把 ring 占用率与升级次数打进 Tracy 计数器(P0 交付),让"水位饿死"表现为一个指标而不是一次无法解释的停顿。P2 增加一个无 present 的 split 用例。
|
||||
@@ -0,0 +1,231 @@
|
||||
---
|
||||
|
||||
## 10. 线程模型
|
||||
|
||||
### Client
|
||||
- **v1 不加线程。** 编码在调用方 GL 线程上直接写进 ring。前端本来就是 per-context 单线程契约(`GLContext` 无 mutex;`EGLState::MakeCurrent` 强制一个 owner 线程,`EGLState/Core.cpp:1215-1220`,测试在 `MG_Test/EGLState/EGLStateTest.cpp:39-92`)。
|
||||
- **flow = per context,不是 per thread。** 今天恰好一个 flow。`eglMakeCurrent` 是 flow 所有权转移,在既有 `EGLOperationMutex`(`EGLImpl.cpp:241`)下发射。**顺手修既有漏洞**:`EGLImpl::ReleaseThread`(`:341-350`)与 `SwapInterval`(`:435-450`)今天不取该锁而另外三个(`MakeCurrent`/`SwapBuffers`/`DestroySurface`)取。
|
||||
- **外来线程的 sync/query**:读全部从 `RingControl` 无锁 acquire load 回答(比取 registry mutex 更好);少数必须发射的(`FenceSync`、`Begin*Query`,以及 §7.2 要求的轮询 publish)取 `ctrlMutex` 并走 CTRL socket 的 out-of-band `AuxRequest` 帧(SPSC ring 不允许第二个 producer)。
|
||||
- **等待必须能挂起**:所有 client 侧等待(present credit、`kNeedsAck`、ring/stage 满、轮询升级)走 §6.2a 的 `producerParked` + 反向门铃,自旋窗口 `MOBILEGL_IPC_SPIN_US`(默认 50µs)。
|
||||
- ShaderCompilePool 原样保留在 client(`ShaderCompilePool.h:77-82`,≤4 worker,为 RSS 上限)。
|
||||
- 可选 `mgl-client-tx` 双缓冲发送线程:**P6 项,凭测量决定**。在 P6 的 Tracy 数据出来之前不要预先加线程(会引入拷贝或锁)。
|
||||
|
||||
### Server
|
||||
| 线程 | 职责 |
|
||||
|---|---|
|
||||
| `mgl-srv-io` | asio `io_context::run`:封帧读写、`SCM_RIGHTS`、双向 doorbell、CTRL RPC |
|
||||
| `mgl-srv-apply` | **终身持有原生 EGL/Vulkan context**:消费 ring → 解码 → apply 进 replica → 调 backend 表 |
|
||||
| `mgl-srv-dec`(可选,P6) | FlatBuffers/边界校验前置,凭测量决定 |
|
||||
|
||||
因为 context 永不迁移:`g_backendContextOwnerThread`(`DirectGLES.cpp:10052`)只写一次;`DirectGLES::MakeCurrent` 的 8 缓存失效风暴(`:10123-10140`)变成启动期一次性成本;`IsBackendContextCurrentOnThisThread` 的每帧 EGL 复核(`:10195-10228`,动机是 `eglGetCurrentContext` 实测占渲染线程 16%)恒真。DirectGLES 的 off-thread 降级(`FenceSync` 返回 null 等)消失——**保真度提升**。延迟 replay 机制(`Managers.h:458-473` 的 `pendingRespecify`/`pendingRanges`/`pendingResidentWrites`)保留但永不触发。
|
||||
|
||||
### 核心放置(本轮新增,是性能主张的前提)
|
||||
|
||||
§5.1 明说 reconciler "就是 `PrepareForDraw` 的可达性遍历"。这意味着这套遍历**每 draw 跑两次**:client 的 `WireMirror` 一次,server 未改动的 `PrepareForDraw`(`DirectGLES.cpp:2916-2975`)一次,外加编码与解码。其中有些并不便宜:`CurrentUnitBindingsEpoch`(`DirectGLES.cpp:1421-1438`)在 `GetTextureBindGeneration()` 变动时会退化成对每个 touched texture unit 做 owner-equality 全走查,而代码自己注明这在冗余重绑时就会发生("26.2 re-binds the unit's own sampler around every texture-unit switch")。
|
||||
|
||||
所以拆分的全部性能主张都押在"两半落在两个都快的核上"。而 MobileGL 全库从不设置亲和性(`grep -rn 'sched_setaffinity\|cpu_set_t\|affinity' MobileGL/` 零命中),server 是 fork/exec 出来的独立进程、不继承 launcher 的亲和性,项目记忆 `pojav-bigcore-affinity-trap` 又记录过 `pojavBigCore=true` 把整个游戏 JVM 加 MobileGL worker 钉死单核、让一整批历史测量作废。若 `mgl-srv-apply` 落到 1.55GHz 小核,它做的工作严格多于 monolith 在 1.96GHz 大核上做的,拆分按构造就是回归,而 §15 P3 的"帧时在 monolith 10% 内"会以一个没人会正确归因的理由失败。
|
||||
|
||||
**规则**:
|
||||
1. 计划里必须写出**总 CPU 工作量差**(client reconcile + encode + decode + server `PrepareForDraw` vs monolith 的 `PrepareForDraw`),不只是单侧成本。
|
||||
2. 复用 `ShaderCompilePool` 已有的大核探测(`ShaderCompilePool.cpp:73-96` 的 `ReadCpuMaxFrequencyKHz` / `DetectBigCoreCount`)把 `mgl-srv-apply` 绑到大核,开关 `MOBILEGL_IPC_SERVER_AFFINITY`(默认 auto),并把解析出的 mask 打进日志。
|
||||
3. P2.5 与 P3 必须报**逐线程 CPU 时间**,不只是墙钟帧时,这样"没有收益"的结论能被归因到放置 vs 编码成本。
|
||||
|
||||
### 拆机顺序(三条约束)
|
||||
`Publish()` + server 排空并 ack → 停 apply 线程 → 关 transport →(client)排空 compile pool(必须先于 `glslang::FinalizeProcess()` 与 `pGLContext` 析构,`ShaderCompilePool.h:106-110`、`Init.cpp:56-62`)→ `MobileGL::Destroy()`(`EGLImpl.cpp:335-338`)→ 释放 sync/query handle(`GL_Sync.cpp:223-226`)。
|
||||
|
||||
---
|
||||
|
||||
## 11. EGL/窗口与进程生命周期
|
||||
|
||||
### 11.1 启动与握手
|
||||
|
||||
client 定位 server 的顺序(**本轮修正**):
|
||||
1. `MOBILEGL_IPC_SERVER_PATH`(**主要机制**)。
|
||||
2. `dladdr(&MobileGL::Initialize)` → dirname → `libMobileGLServer.so`(**兜底**)。
|
||||
|
||||
上一版把 `dladdr` 当主要机制,但两个桌面验收门都因此找不到 server:`MG_IntegrationTest/CMakeLists.txt:28-35` 在非 Android 上把 `MGL_ITEST_MOBILEGL_TARGET` 设成 `MobileGL_s`(**静态链接**),`dladdr` 解析到测试可执行文件自身的路径而不是库目录;trace replay 则由 `tools/trace_replay/CMakeLists.txt:285-290` 显式传 `-DMOBILEGL_LIBRARY=$<TARGET_FILE:MobileGL>`,其目录是 MobileGL 的构建输出目录,而 CMake 默认把 `add_executable` 放在定义它的目录的 binary dir。
|
||||
|
||||
**配套**:把 `MobileGLServer` 的 `RUNTIME_OUTPUT_DIRECTORY` 设成 `$<TARGET_FILE_DIR:MobileGL>`,并把 `"MOBILEGL_IPC_SERVER_PATH=$<TARGET_FILE:MobileGLServer>"` 加进每一条新的 ctest `ENVIRONMENT`(经 `mgl_itest_join_environment` 与 `${MGL_ITEST_COMMON_ENV}` 合并)以及 `add_trace_replay_test` 的 `SPLIT` 分支。**并复核绝对路径能否活过 CI 的 artifact 搬运**:`.github/workflows/test.yml:174-185` 只重写 `CTestTestfile.cmake` 里的 `cmake` 路径,不重写 `ENVIRONMENT` 值——若不行,改为在测试启动时由 harness 相对 `argv[0]` 解析。
|
||||
|
||||
启动方式:`socketpair(AF_UNIX, SOCK_STREAM)` + `fork`/`execve`,fd 3 = socket(Windows 见 §11.5)。**无文件系统 socket 路径、无 abstract namespace、Android 上无 SELinux 争议。**
|
||||
|
||||
**子进程必须被强制成 monolith(本轮新增,修无界 fork 链)**:`MG_Config::Transport` 由 `ConfigLoader` 从环境变量读(与 `features.CoherentAsFlush = QueryEnvFlag(...)`(`ConfigLoader.cpp:185`)同形),而 `fork`/`execve` 的子进程会继承 `MOBILEGL_TRANSPORT=spawn`。server stub 里 `dlopen(libMobileGL.so)` + `dlsym("mobilegl_server_main")` 之后必然要起一个真 backend,即走 `MG_Backend::Init()`(`Init.cpp:48-70`)——变量还在,于是它再构造一个 `BackendObject_Remote` 并再 spawn 一次,首次 GL 调用时形成无界 fork 链。
|
||||
**规则**:(a) spawn 时构造**显式 envp**,剔除 `MOBILEGL_TRANSPORT` 与所有 `MOBILEGL_IPC_*`(只保留 server 真正需要的少数几个,如 `MOBILEGL_BACKEND_TYPE`、日志路径);(b) `mobilegl_server_main` 在能到达 `MG_Backend::Init()` 之前把 `MG_Config::Transport` 硬置为 `Monolith`。两条都做,任一条单独失效时另一条兜住。P0 增加一个 `MG_Test/Wire` 测试:spawn 一个 server 并断言进程树只多出**恰好一个**子进程。
|
||||
|
||||
`Hello{abiVersion, backendType, buildFingerprint, configBlob}` → `Welcome`。`configBlob` 转发 client 解析好的 `MG_Config::Features`,两半不可能对某个 quirk 开关有分歧。`buildFingerprint`(git hash + `Records.def` 的 hash)不匹配 → 握手期 `Fatal`。
|
||||
|
||||
### 11.2 `mobilegl_server_main` 的可见性(本轮新增)
|
||||
|
||||
`CMakeLists.txt:497-510` 在**非 Debug** 构建上给共享目标设 `C_VISIBILITY_PRESET hidden` / `CXX_VISIBILITY_PRESET hidden` / `VISIBILITY_INLINES_HIDDEN ON`——而 plugin 与 FCL 出货的正是 RelWithDebInfo(`MobileGL/build.gradle` 的 `fordebug` 类型强制 `-DCMAKE_BUILD_TYPE=RelWithDebInfo`)。所以 `dlsym("mobilegl_server_main")` 在 Debug 下能用、在设备上静默失败。
|
||||
|
||||
**规则**:入口点声明为
|
||||
```cpp
|
||||
extern "C" __attribute__((visibility("default"))) int mobilegl_server_main(int argc, char** argv);
|
||||
```
|
||||
并在 P0 验收里加 `nm -D libMobileGL.so | grep mobilegl_server_main` 断言(与既有的 `nm --defined-only` 门并列)。若哪天 macOS/Windows 也要托管 server,还需同步 `MG_Impl/DyldInterpose/ExportedSymbols.txt` 与 `wgl.def`。
|
||||
|
||||
### 11.3 Android
|
||||
|
||||
**minSdk 26 没有任何公开 NDK API 能扁平化 `ANativeWindow`**(NDK r27.3 的 `android/native_window.h` 无 parcel 符号;`libbinder_ndk` 是 API 29,`binder_ibinder.h:191`;`ASurfaceControl` 是 API 29,`surface_control.h:67`)。`Feat/CS-Delta-IPC` 的 `nativeBlob`"binder-flattened ANativeWindow"(`protocol.fbs:377-379`)不可实现。
|
||||
|
||||
- **P1-P8 验证路径:无窗口。** 两个 PIE ELF。**实测**:从解压出的 nativeLibraryDir exec 在 API 36 上可行(`run-as … libtrace_replay_runner.so` → exit 132 = SIGILL,即 ELF 已被加载进入,而非 `EACCES`;文件 0755 / `u:object_r:apk_data_file:s0` 且无 MLS category,**跨 package 也可**)。`useLegacyPackaging = true` 在 FCL(`../FCL/build.gradle.kts:76-82`)与 plugin(`android-plugin/app/build.gradle.kts:198-203`)都已开。surface 用 pbuffer 或 `AImageReader` 支持的 `ANativeWindow`(`HeadlessGL.cpp:86-131,268-274`),trace replay 默认 pbuffer(`apitrace_glws_egl.cpp:614-618`)。
|
||||
**注意实测的域**:上述 SIGILL 证据是经 `run-as` 取得的,即 `runas_app` 域,而不是 trace Activity 所在的 `untrusted_app` 域。**P0 的 Android spike 必须从应用自身进程 `posix_spawn` 一次**(见 §15 P0)。
|
||||
- **P9 生产路径**:Java `Surface`(Parcelable)→ Messenger/AIDL → `MobileGLServerService`(`android:process=":mgl"`)→ JNI `ANativeWindow_fromSurface(env, surface)`,就是 FCLauncher 今天在 `egl_bridge.c:81` 做的那一次调用。**仓内先例**:`android-plugin` 的 `BenchService` 已在 `android:process=":bench"` 里跑 MobileGL(`BenchService.java:19-77`)。代价:server 进程多一个 ART(~15-25MB)。
|
||||
- **纠正一条过期笔记**:FCL 把游戏 JVM 跑在**主进程**,不是 `:jvm`(`../FCL/src/main/AndroidManifest.xml:112-121`,`JVMActivity` 没有 `android:process`;`:jvm` 是下载 Service)。第二个进程必须新建。
|
||||
- **HeadlessGL 的 fork 预检与孤儿 server(本轮新增)**:`MG_IntegrationTest/Harness/HeadlessGL.cpp:344-368` 会 fork 一个子进程跑完整 EGL bring-up 然后 `_exit(step)`,注释(`:364-366`)明说这是刻意的——"every atexit handler and static destructor in this address space belongs to the parent's copy of the world"。拆分模式下那个子进程的 bring-up 会走到 `MG_Backend::Init()` 并 spawn 一个 server;`_exit` 不跑任何拆机,那个 server 成为孤儿,活到它发现 EOF 或撞上 `MOBILEGL_IPC_IDLE_EXIT_S`(默认 30s)。父进程随即对同一设备起自己的 server。`HeadlessGL.cpp:585-589` 已经把这种失败模式命名为"a leaked exclusive device, an environment the child did not have"。
|
||||
**规则**:server 的 EOF 检测必须**即时且无条件退出**(亚秒级,不靠 30s 看门狗);client spawn 时把 socket fd 设成 `_exit` 会确定性关闭的形态(不设 `FD_CLOEXEC` 以外的保活);再加一次**有界重试的就绪握手**,这样残留的预检 server 不会把父进程弄 flaky。这个交互本身列为 P1 验收步骤 1 的一部分,先于任何广度工作。
|
||||
|
||||
### 11.4 Linux / X11
|
||||
|
||||
`Window` 是 XID,`nativeToken:u64` 直接送。backend 自己 `XOpenDisplay(getenv("DISPLAY"))` 并构造 `VkXlibSurfaceCreateInfoKHR`(`VulkanRenderer.cpp:14486-14521`),只要同 `DISPLAY`/`XAUTHORITY` 就免费。Wayland 今天不支持(`BackendObject.h:529` TODO),维持。
|
||||
WSL/CI:**永不开窗** —— `EGL_PLATFORM=surfaceless` + `EnsureHeadlessPlatform()`(`HeadlessGL.cpp:160-196`,它存在正是因为一台带 WSLg `DISPLAY` 的工作站曾把这条 lane 弄挂)。
|
||||
|
||||
### 11.5 Windows
|
||||
|
||||
`HWND` 进 `nativeToken`。Vulkan 可行(`hinstance` 是历史遗留,`VulkanRenderer.cpp:14456-14463`);**WGL/ANGLE-DXGI 对外进程 HWND 不受支持 → headless only**。
|
||||
|
||||
transport:默认 named pipe(asio `windows::stream_handle`)。**"继承句柄就免掉 accept/connect"这句在 asio 上不能直接照搬(本轮修正)**:`windows::stream_handle` 的 IOCP 服务要求句柄是 **overlapped** 的,而 `CreatePipe` 造的匿名管道不是。所以句柄对必须这样造:用一个 GUID 唯一命名的 `CreateNamedPipeW(..., FILE_FLAG_OVERLAPPED)` 做 server 端,配一次 `CreateFileW(..., FILE_FLAG_OVERLAPPED)` 做 client 端,然后把 server 端句柄设为可继承并 `CreateProcess` 传下去。§11 必须把这套构造写清楚。
|
||||
|
||||
asio 1.38.2 在 Win32 上确实定义了 `ASIO_HAS_LOCAL_SOCKETS`(`3rdparty/asio/asio/include/asio/detail/config.hpp:1085-1092`,只排除 `ASIO_WINDOWS_RUNTIME`,且自带 `sockaddr_un_type` 于 `socket_types.hpp:220`),但其 IOCP `async_accept` 走 `AcceptEx`,AF_UNIX 从不支持它——AF_UNIX-everywhere 是 P6 的**可选简化**,需真编真跑验证,named pipe 是已知可用的默认。
|
||||
|
||||
### 11.6 崩溃
|
||||
|
||||
- **server 死**:client 读到 EOF/EPIPE → device-lost 闩锁:后续 GL 调用变 no-op、`eglSwapBuffers` 返回 `EGL_FALSE`+`EGL_CONTEXT_LOST`、`glGetGraphicsResetStatus`(若 robustness 分支落地)返回 `GL_UNKNOWN_CONTEXT_RESET`。`MOBILEGL_IPC_RESPAWN=1` 时重启 + `ResyncSnapshot`(默认关,静默重启会掩盖 bug;且与 `MOBILEGL_IPC_ADOPT_TIER != 2` 互斥,见 §5.8)。
|
||||
- **client 死**:server 读到 EOF → **立即**销毁原生 context 并退出(不等看门狗);`MOBILEGL_IPC_IDLE_EXIT_S`(默认 30)只作为 EOF 都收不到时的最后保险。
|
||||
|
||||
---
|
||||
|
||||
## 12. Monolith 保留与模式选择
|
||||
|
||||
**四层保证,从强到弱:**
|
||||
|
||||
1. **编译期折叠。** `MOBILEGL_BUILD_DISAGGREGATED`(默认 **OFF**)关闭时 `MobileGL/MG_Remote/**` 不进 `SOURCE_FILES`,`MG_Config::Transport` 是 `constexpr Monolith`,`MG_Backend/Init.cpp` 里的分支在编译期消失。**默认构建与今天字节一致。**
|
||||
2. **唯一 hook 点。** 整个拆分入口是 `MG_Backend/Init.cpp:48-70` 里的一个分支:
|
||||
```cpp
|
||||
void Init() {
|
||||
MGLOG_D("Initializing MobileGL Backend...");
|
||||
#if MOBILEGL_BUILD_DISAGGREGATED
|
||||
if (MG_Config::Transport != TransportKind::Monolith) {
|
||||
pActiveBackendObject = MakeUnique<MG_Remote::BackendObject_Remote>();
|
||||
} else
|
||||
#endif
|
||||
switch (MG_Config::ActiveBackendType) { /* 原样不动 */ }
|
||||
if (!InitSpecificBackendLibs()) { /* 原样 */ }
|
||||
LogBackendInfo();
|
||||
}
|
||||
```
|
||||
`BackendObject_Remote::GetBackendFunctions()` 返回发射表,`Initialize()` 负责 spawn/connect。下游 ~250 个边界调用点**零 `#ifdef`**。
|
||||
3. **P4.5 的 allocator 改动必须同样包裹。** `PipeResource::MapAlignedAllocator` 与 `MipmapStorage` 的 level vector 住在 `MG_State`,改它们的 allocator 就改了类型;写成"分配器特化,option OFF 时逐字折叠回今天的 `MapAlignedAllocator`",否则第 4 层会在 P4.5 变红。
|
||||
4. **机械证明**:对 `libMobileGL.so` 做 `nm --defined-only` 与去调试信息后的 `.text` size diff,改前改后必须一致。**这是每个阶段的出口判据(P0…P9),不只是 P0**(上一版只在 P0 跑)。
|
||||
|
||||
### 12.1 两个 option,不是一个(本轮重大修正)
|
||||
|
||||
上一版说"OFF 时字节一致",但**每一条部署路径都要求出货构建是 ON**:FCL 用户可编辑 env、plugin APK 的 V2 开关表、ctest `ENVIRONMENT` 变体、`/data/local/tmp` CTS 路径。而上一版又说 ON 构建里 `inproc` 会把 `pGLContext` 变成 thread-local 加 `operator->` shim。那个 shim 坐在全库最热的路径上:`grep -rho 'pGLContext->' MobileGL/MG_Impl | wc -l` = **1494**,加 DirectGLES 124、DirectVulkan 169。Android 上 dlopen 的共享库无法可靠使用 initial-exec TLS,每次访问会退化成一次 `__tls_get_addr` 调用,而今天那里只是一次对全局引用的加载(`Core.h:564` `extern UniquePtr<GLState::GLContext>& pGLContext`)。
|
||||
|
||||
**规则**:拆成两个 option。
|
||||
- **`MOBILEGL_BUILD_DISAGGREGATED`**(出货形态):只含 `spawn`/`unix:`/`pipe:`。每进程只有一个 `GLContext`、一份 `gBackendFunctionsTable`、一个 `pActiveBackendObject`、一份 `pDefaultFramebufferInfo` → 这四个**全部保持普通全局**,GL 热路径上没有任何 TLS 与间接。侵入面就是 `MG_Backend/Init.cpp` 里那一个可预测的分支。
|
||||
- **`MOBILEGL_BUILD_DISAGGREGATED_INPROC`**(CI/调试形态,隐含开启前者):额外加角色隔离 shim。
|
||||
|
||||
### 12.2 `inproc` 需要隔离的是**四个**进程全局,不是一个(本轮修正)
|
||||
|
||||
上一版只谈了 `pGLContext`。实际上 `inproc` 下同一进程要同时扮演两个角色,以下四个全局都必须按角色分身:
|
||||
|
||||
| 全局 | 定义处 | 谁读 |
|
||||
|---|---|---|
|
||||
| `MG_State::pGLContext` | `GLState/Core.h:564` 声明,`Core.cpp:1487` 定义,`Core.cpp:20` 构造,`Init.cpp:63` reset | 全部 |
|
||||
| `MG_Backend::gBackendFunctionsTable` | `MG_Backend/Init.cpp:44` 赋值 | client 侧 MG_Impl(91 处)**与 server 侧 MG_Impl**(`GL_Texture.cpp:1621` `GenerateMipmap_Backend`、`:6713-6725` `GetTexImage` 回退链、`FixupGsStripCaptureOrder`、`CopyReadFramebufferIntoMipmapRegion` 的 `ReadPixels`) |
|
||||
| `MG_Backend::pActiveBackendObject` | `MG_Backend/Init.cpp:53-61` 赋值 | MG_Impl 89 处 + backend 内部 |
|
||||
| `MG_Impl::GLImpl::FramebufferImpl::pDefaultFramebufferInfo` | `GL_Framebuffer.cpp:3344` 定义,全库 22 处引用 | client 侧 MG_Impl 13 处(`GL_Framebuffer.cpp:495,1827,1837,1897,1905,1913,1927,1936,2549,2590,2598,2608,2611`)+ server 侧 backend 5 处(`DirectGLES.cpp:1917,2838,2867,9675`、`SwapchainObject.cpp:276`,其中 `SwapchainObject` 是**写**) |
|
||||
|
||||
一旦 client 装上发射表,`inproc` 里 applier 与 server 侧 MG_Impl 就没有任何路径能拿到真正的 DirectGLES/DirectVulkan 表;而一个进程也不可能同时持有 client 的 default-FBO 描述与 server 的(`SwapchainObject` 直接往里写 server 的视角)。
|
||||
|
||||
**shim 的完整需求**(上一版只提了 `operator->`):`operator->`、`operator bool`、`get()`、`== nullptr` 相等比较、从 `MakeUnique` 赋值、`reset()`。非箭头用法的实际数量是 **133**(`grep -rn pGLContext MobileGL/ --include=*.cpp --include=*.h | grep -v 'pGLContext->' | wc -l` = 133,上一版写的"约 65 处"少了一倍),其中 MG_Impl 只有 2 处(`GL_Debug.cpp:99` 的 `.get()`、`GL_Program.cpp:1630` 的 `== nullptr`),绝大多数在 MG_Backend——尤其 DirectVulkan 里约 90 处 `MOBILEGL_ASSERT(MG_State::pGLContext, ...)` 的真值判断,另有 `DirectGLES.cpp:146` 的 `.get()` 与 `Managers.cpp` 里十来处 `if (MG_State::pGLContext)` 守卫。**因为 backend 侧那一簇恰恰是必须看到 replica 的,shim 的原型应当先拿 `MG_Backend/DirectVulkan/DirectVulkan.cpp` 的 assert 密集区开刀。**
|
||||
|
||||
**如果这层隔离的成本被判定过高**,退路是把 `inproc` 降级为**纯测试模式**:applier 通过显式传入的表指针工作,server 侧不跑 MG_Impl(于是 `GenerateMipmap_Backend` 那类回退不可用,需要在 `inproc` 下走另一条路径)。但那样 P2.5 就不再测量它本该测量的"monolith 渲染线程"交付物——**这个取舍必须在 P0 结束前拍板并写进文档,不能悬着**。
|
||||
|
||||
### 12.3 `inproc` 作为产品交付物
|
||||
|
||||
在隔离成本可接受的前提下,`inproc` 不只是测试脚手架:同进程第二个 `GLContext` + `mgl-srv-apply` 线程 = monolith 的渲染线程。今天 `PrepareForDraw`(状态调和、VAO/FBO/纹理/program/render-state sync、UBO ring memcpy)加驱动调用全部同步跑在 `glDrawElements` 里;把它们搬到 apply 线程,对 GL 线程 CPU-bound 的应用(本项目的 profiling 史说 Minecraft 就是)是**手上最大的单一杠杆**,且不需要任何 IPC/shm/平台工作。§15 的 P2.5 就是证伪它的门。
|
||||
|
||||
### 12.4 运行时选择与开关
|
||||
|
||||
`MOBILEGL_TRANSPORT = monolith(默认) | inproc | spawn | unix:<path> | pipe:<name>`,在 `ConfigLoader.cpp` 与既有开关并列解析。这一个选择免费换来:ctest `ENVIRONMENT` 变体、trace-replay 的 `setenv` 块(`trace_replay_core.cpp:134-207`)、FCL 的用户可编辑 env 偏好(`FCLauncher.java:417-430`)、plugin APK 的 V2 开关表(`android-plugin/app/build.gradle.kts:77-103`,由 `.github/scripts/validate-plugin-apks.sh` 校验)、`/data/local/tmp` CTS 路径。**零新增管线。**
|
||||
|
||||
保留全部既有负面对照开关(`MOBILEGL_ESPRYT_DISABLE_{UBO,UNPACK,UPLOAD}_RING`、`_INVALIDATE_FLUSH`、`MOBILEGL_DISABLE_LARGE_BUFFER_ADOPTION`),新增:`MOBILEGL_IPC_SHADOW_SHM`、`MOBILEGL_IPC_ADOPT_TIER`、`MOBILEGL_IPC_PROGRAM`、`MOBILEGL_IPC_INLINE_PAYLOADS`、`MOBILEGL_IPC_PRESENT_CREDIT`、`MOBILEGL_IPC_SPIN_US`、`MOBILEGL_IPC_POLL_ESCALATE`、`MOBILEGL_IPC_PERSISTENT_BLOCK_KB`、`MOBILEGL_IPC_SERVER_AFFINITY`。
|
||||
|
||||
---
|
||||
|
||||
## 13. 构建布局
|
||||
|
||||
```
|
||||
MobileGL/MG_Remote/
|
||||
Protocol/ protocol.fbs protocol_generated.h(提交) Records.def RecordKinds.h
|
||||
Handles.h Coverage.def MutationCoverage.def
|
||||
generated/BackendStateSurface.inc(提交) generated/ImplMutationSurface.inc(提交)
|
||||
Transport/ ITransport.h InProcessTransport.{h,cpp} SocketTransport.{h,cpp}
|
||||
Framing.h Ring.{h,cpp} ShmSegment.{h,cpp} ShmSegmentPosix.cpp ShmSegmentWin32.cpp
|
||||
FdPassing.{h,cpp} Doorbell.{h,cpp}
|
||||
Shared/ XfbAccounting.{h,cpp} # client 与 applier 共用的 MG_Impl-side mutation helper
|
||||
MipmapLevelPlan.{h,cpp}
|
||||
Client/ WireMirror.{h,cpp} EmitTable.cpp EmitBufferOps.cpp
|
||||
BackendObject_Remote.{h,cpp} CapsMirror.{h,cpp}
|
||||
ClientArrayBounds.cpp CompositeResolver.cpp ShadowArena.{h,cpp}
|
||||
PersistentMapTracker.{h,cpp} GpuWritePending.{h,cpp}
|
||||
CoverageAssert.cpp Surface/{X11,Win32,Android,Headless}.cpp
|
||||
Server/ ReplicaContext.{h,cpp} Applier.cpp ServerLoop.{h,cpp}
|
||||
ReplyPool.{h,cpp} EventRing.{h,cpp} ServerMain.cpp
|
||||
ServerJni.cpp # Android,与 DriverPostJni.cpp 并列
|
||||
scripts/ gen_protocol.py gen_backend_state_surface.py gen_impl_mutation_surface.py
|
||||
MobileGL/MG_Test/Wire/CMakeLists.txt # 复制自 MG_Test/Buffer/(27 行)+ MobileGL_Protocol
|
||||
```
|
||||
|
||||
CMake:
|
||||
- `MG_Remote/**` 仅在 `MOBILEGL_BUILD_DISAGGREGATED` 下追加进 `SOURCE_FILES`(`CMakeLists.txt:226-419`),因此 `MobileGL`(`:485`)与 `MobileGL_s`(`:552`)都拿到。
|
||||
- `MobileGLServer`:桌面 `add_executable` 链接 `MobileGL_s`,`RUNTIME_OUTPUT_DIRECTORY` 设为 `$<TARGET_FILE_DIR:MobileGL>`(§11.1);**Android** `add_executable` + `set_target_properties(MobileGLServer PROPERTIES PREFIX "lib" SUFFIX ".so" OUTPUT_NAME "MobileGLServer")` 并链接**共享**的 `MobileGL`(一份 ~43MB 的 glslang/SPIRV-Cross/SPIRV-Tools),由 AGP 打进 `jniLibs`。server 主体是 ~30 行 stub:`dlopen(libMobileGL.so)` → `dlsym("mobilegl_server_main")`(可见性见 §11.2)。**一份共享库、两个角色,版本必然匹配**(对比 `Feat/CS-Delta-IPC` 的四件必须互相匹配的产物)。
|
||||
**AGP 能否打包一个被改名成 `lib*.so` 的 `add_executable`,是 P0 spike 的验证项之一**(`MobileGL/build.gradle` 没有设 `targets` 列表,上一版把这条当成已知事实)。
|
||||
- **FlatBuffers**:submodule `3rdparty/flatbuffers` 置于既有的 `if (EXISTS .../flatbuffers/CMakeLists.txt)` 保护下,**去掉 `if (NOT ANDROID)` 一刀切**。因为 `protocol_generated.h` 已提交,**默认构建图里没有 `flatc`,也不 `add_subdirectory(3rdparty/flatbuffers)`**(§7.1)。运行时是 header-only,只需要 `3rdparty/flatbuffers/include` 在 include path 上。
|
||||
**guard(本轮新增)**:若 `MOBILEGL_BUILD_DISAGGREGATED=ON` 而 `3rdparty/flatbuffers/include` 不存在,强制把该 option 设回 OFF 并 `message(WARNING ...)`——否则 `MG_Remote/**` 已经进了 `SOURCE_FILES` 而头文件找不到,构建以一个莫名其妙的错误失败(现有的 `EXISTS` 保护只包住 Protocol 子目录)。
|
||||
`MOBILEGL_FLATC_EXECUTABLE` 只服务 CI 的 `flatc-check`,经 `MobileGL/build.gradle:17-21` 已在用的 `externalNativeBuild { cmake { arguments } }` 槽传入。
|
||||
- 测试接线:
|
||||
- `MG_Test/Wire/`(label `unit`)→ 现有 CI `test` job 自动收,**无需改 workflow**。
|
||||
- `MG_IntegrationTest/CMakeLists.txt` 每 backend 增加一条 `gtest_discover_tests`(`TEST_PREFIX "DirectGLES.Split."` / `"DirectVulkan.Split."`),**必须用 `mgl_itest_join_environment(... ${MGL_ITEST_COMMON_ENV})` 构造**,并带上 `MOBILEGL_IPC_SERVER_PATH`。三个已被文档记录的陷阱要遵守:ctest `ENVIRONMENT` 是**替换而非追加**(`:339-343`)、`;` 必须转义(`:322-332`)、property 覆盖 job env(`test.yml:253-262`)。
|
||||
- **trace replay 的 `SPLIT` 接线(本轮补细节)**:`add_trace_replay_test` 今天把测试命名为 `MobileGLTraceReplay.${CASE_NAME}.${BACKEND}`(`tools/trace_replay/CMakeLists.txt:330-332`),加一个 `SPLIT` 参数会与同 case+backend 的现有测试**重名**。改成 `MobileGLTraceReplay.${CASE_NAME}.${BACKEND}${SPLIT_SUFFIX}`。另外该测试的命令是 `cmake -P run_trace_case.cmake` 加约 18 个 `-DTRACE_*` 变量,所以还要加 `-DTRACE_TRANSPORT=` 并在 `run_trace_case.cmake` 里消费它——**这两个文件都要列进 P2 的交付物**。
|
||||
- CI 新增三个 step:`flatc-check`(重生成 `protocol_generated.h` + `git diff --exit-code`)、`coverage-check`(重生成两个 `.inc` + `git diff --exit-code`)、`monolith-abi-check`(OFF 构建与 ON+monolith 构建的 `nm --defined-only` / `.text` size 对基线)。
|
||||
- **CI 新增一条 grep 门**:禁止 `MG_Backend/` 与 `MG_State/` 下出现 `fprintf(stderr` / `printf(`。
|
||||
|
||||
---
|
||||
|
||||
## 14. 对 `Feat/CS-Delta-IPC` 的复用清单
|
||||
|
||||
### REUSE(原样取)
|
||||
| 路径 | commit | 备注 |
|
||||
|---|---|---|
|
||||
| `docs/CS_Refactor/HandleSessionGeneration.md` | `546895aa` | 分支上最好的产物。三处修改:handle 清单补 `RenderbufferObject::GetLifetimeId()` **与 `GetVersion()`**;把第 2 节的 server 侧 share-group 要求降为 v2;把"lifetimeId 不符 → 销毁重建"改成 `Fatal`(§5.4) |
|
||||
| `MobileGL/Protocol/mg_protocol_base.h` | `546895aa` | 干净无依赖的词汇(`MobileGLResult`、span、`ShmRegion`、id typedef、structSize-first 版本纪律) |
|
||||
| `MobileGL/Protocol/tests/ProtocolSmoke.cpp` | `546895aa` | schema 往返门(默认改 ON) |
|
||||
| 根 `CMakeLists.txt` 的 `EXISTS` 保护 + `.gitmodules` 条目 | `546895aa` | 去掉 `NOT ANDROID`,另加 §13 的 include-dir guard |
|
||||
| `docs/CS_Refactor/HANDOFF.md` 第 6 节"已知坑清单" | `d5c00b9d`/`5964628d` | 逐字留作事后复盘:路径转换、versionCode 降级、双设备 `ANDROID_SERIAL`、flatbuffers camelCase accessor、union vector 产生指针、Release 下 `MGLOG_D` 被编译掉、嵌套 submodule 配方、`assembleTraceDebug` 改名 |
|
||||
|
||||
### CHANGE(取走并改造)
|
||||
| 路径 | commit | 改造 |
|
||||
|---|---|---|
|
||||
| `MobileGL/Protocol/protocol.fbs` | `546895aa` | 保留 delta 目录、`RenderStateBlob` 整块思想、`BufferShmAdopt`、命令清单、事件分类学。改:热路径转 `struct` + ring;删掉冗余的 `inlineBytes`/`data` 双胞胎(`:111-112`、`:125-126`,两半代码对哪个字段是真的意见不一:`ServerCore.cpp:184-208` 只读 `data`,`StateEmitter.h:60,111` 只写 `inlineBytes`);加 `ResyncSnapshot`、`AuxRequest`;给 `ProgramPublish.reflection` 与 `ObjectCreate.params` 真 schema;kind 枚举生成 + 每 kind `static_assert` + 运行期边界检查 |
|
||||
| `MobileGL/Protocol/CMakeLists.txt` 的 flatc 解析 | `546895aa`/`65717b4c` | **不再照搬**:`add_subdirectory(3rdparty/flatbuffers)` 从默认路径整段删除(它就是那个 NDK 陷阱本体);只保留 `MOBILEGL_FLATC_EXECUTABLE` 供 CI;`enable_testing()` 移到根 |
|
||||
| `MobileGL/ServerCore/ServerCore.{h,cpp}` | `65717b4c`+`c2260dd8` | 保留握手→解码→apply→credit 形状与 plugin manifest loader 思路。修:单次校验 + 零拷贝解码(今天校验两次外加一次整体拷贝,`:492-498` 与 `:218-221`);io/apply 分线程(`:404-406` 自承 worker 从未落地);完整事件集(`SendEvent` 只实现 `BATCH_APPLIED`,`:373-382`);credit 用最后一条实际 seq(`:427` 的 `baseSeq + items.size()`);接收缓冲不能是对着 64MiB 帧上限的固定 4MiB(`:478`);真正的段生命周期(`m_segments` 只增不减,`blobOwners` 只 push 不释放) |
|
||||
| `ServerCore/tests/LoopbackSmoke.cpp` + `Backends/Dummy/` | `65717b4c` | 分支上最便宜的端到端门,**第一个重建**,重定向到真 applier |
|
||||
| `MobileGL/Remote/InProcessTransport.h` | `65717b4c` | 重表述在 C++ `ITransport` 上;单侧 shutdown(今天 `:89-92` 连对端 inbox 一起关);真段生命周期(`Unmap`/`Close` 今天是 no-op);补 §6.2a 的双向 doorbell(condvar 版) |
|
||||
| `MobileGL/Remote/Framing.h` | `65717b4c` | 保留帧格式;`m_pendingSize`/`m_haveHeader` 改 `mutable`(今天 `const_cast`,`:81,85`);`Feed()` 真校验 magic 与长度(今天永远返回 OK,坏 magic = 静默永久挂起);缓冲不足返回所需大小且**保留消息**;真正在 socket transport 里使用它(今天是死代码) |
|
||||
| `MobileGL/RemoteClient/StateEmitter.h:39-307`(**仅 emit 半边**) | `b50f3348`+`d96be9f3` | 各域字段遍历是真知识,抬进 `WireMirror`/`ResyncSnapshot`。GL name 换 `lifetimeId`(今天 `:48-49,85,166-168,203,230` 全把 GL name 塞进 `handle`);`:175-181,:244-249,:253-258,:293-298` 的 O(n²) 线性扫描换 handle map;固定 6 attachment(`:232-236`)换 `MaxColorAttachments`;补上被跳过的 texture view(`:70-74`)。**不取 applier 半边(`:312-501`)** |
|
||||
| `scripts/extract_backend_read_inventory.py` | `546895aa` | 改造成 `gen_backend_state_surface.py`:删掉前缀兜底(`:234-241`),未知 accessor 一律 UNMAPPED 并**编译失败**;把真 pull point 与 signature handle 化分开统计。**另写一个全新的 `gen_impl_mutation_surface.py`**(§5.9b),它在原分支没有对应物 |
|
||||
|
||||
### DROP
|
||||
| 路径 | 理由 |
|
||||
|---|---|
|
||||
| `MobileGL/Protocol/bfa.h`(480 行) | "strict C ABI"不是 C ABI:`ServerCore.cpp:177-179` 把 FlatBuffers 生成表的指针交给插件,插件必须是 C++ 且链接 FlatBuffers(`StateEmitter.h:330,351,362,372` 就是这么用的)。手抄的 60 字段 `MobileGLDynamicParameters`(`:63-129`)自承尾部不全、同步脚本从未写过——正是已在本项目造成 481 例 CTS 失败簇的那类数据的**长期静默漂移炸弹**。而本设计根本不需要 delta-apply vtable |
|
||||
| `MobileGL/Protocol/mgruntime_api.h` + `MobileGL/UtilRuntime/*` | 360 行契约对 ~50 行实现(8 域实现 2 域);唯一消费者传 `nullptr`(`ServerCore.cpp:61`);缓存每次命中整份拷贝(`:79`)、按 `clear()` 淘汰(`:91-93`);smoke 断言 `api->metrics == nullptr`(`RuntimeApiSmoke.cpp:66`)。它的唯一理由随 BFA 消失;且本设计里翻译全在 server(它无论如何要链 SPIRV-Cross),glslang 全在 client |
|
||||
| `MobileGL/Remote/LocalSocketTransport.{h,cpp}`、`ShmFactory.{h,cpp}` 实现 | 从未被任何测试执行(`LoopbackSmoke` 用的是 `InProcessTransport`,唯一另一个消费者 `ServerHost` 编译不过);每次 send 都 use-after-free(`:199`,`asio::buffer(next)` 指向局部 vector 而 lambda 捕获的是另一份拷贝);按 wire 长度无上限分配(`:232-236`);`Start` 里阻塞 accept/connect(`:116`、`:139-144`);无 strand 且 `framesSent++` 非原子(`:177-178`);**且完全没有 POSIX fd 传递**(`:296` 硬编码 `fd=-1`),Linux/Android 数据面一字节过不去。只保留 `ShmFactory.h:4-12` 作平台矩阵规格 |
|
||||
| `MobileGL/ServerHost/main.cpp` | 编译不过(`:31,39,44,53-54` 对指针用 `.`,`c2260dd8` 改返回类型后成为死码)。`MobileGLServer` 在默认 ALL target 里,**分支 tip 无法完成一次完整构建** |
|
||||
| `MobileGL/RemoteClient/tests/StateEquivalenceTest.cpp` | 把 delta apply 进第二个 `MG_State::GLContext`——验证的是它自己的 thin-server 前提说不该存在的数据路径;与生产 apply 路径零共享代码;只测全量 resync;`d96be9f3` 声称五域逐字段而文件只比了纹理、buffer、render-state blob、buffer binding slot(没有 VAO 属性/FBO attachment/RBO 格式比较) |
|
||||
| `c7c9e346` + `29d721ef` 全部(share-group sessioning) | 非 v1 前提(monolith 只有一个 `GLContext`:`GLState/Core.cpp:20,1487`);且非可合并质量:`VertexArrayState.cpp:+20-26` 往已共享的表里再压一个 default VAO 并重复 `Insert(0)`;四个头文件 `public:` 未复位泄漏私有成员;current session 是无锁进程全局,连它自己的 per-thread current 都没兑现;在状态权威里塞 `MOBILEGL_SESSION_SWAP` env kill switch 与 `s_defaultAdopted` 偷 context 的 hack。日后作为独立 PR 带多 context 测试落 `dev` |
|
||||
| `b50f3348` 的 `RenderState::InstallParameters` + `public:` | 本设计不需要 Install setter(D3);若日后需要整块安装,用正确作用域的方法或单条 friend,绝不靠裸 `public:` |
|
||||
| `d96be9f3` 的 TRIAGE 指令(`DirectGLES.cpp:+2583-2590`) | per-draw `fprintf(stderr)`。**分支上每一次测量都跑在它上面。** 同规则适用于当前工作树的 `[IBOTX]`/`[BUFTX]`(P0 清除) |
|
||||
@@ -0,0 +1,241 @@
|
||||
---
|
||||
|
||||
## 15. 分阶段实施计划
|
||||
|
||||
> 通用纪律(每个 commit 都适用):默认 ALL target 必须能完整构建;禁止提交热路径插桩;每个门必须**能因它存在的理由变红**;**Windows 机器不是正确性门**(其 Vulkan 缺 `vkCreateHeadlessSurfaceEXT`,占该机 567 个基线集成失败中的 423 个);设备对比走 reboot-clean + 同窗口配对 A/B;**每个阶段的出口都跑一次 §12 第 4 层的 `nm`/`.text` monolith 门**(不只是 P0)。
|
||||
|
||||
### P0 — 卫生、骨架与两个 spike(5 天)
|
||||
|
||||
**交付物**
|
||||
- 清除工作树 `[IBOTX]`/`[BUFTX]` fprintf(`DirectGLES.cpp:290-303`、`Managers.cpp:875-877`,后者在 `pendingMutex` 临界区内)。
|
||||
- `RenderbufferObject::GetLifetimeId()` **与 `GetVersion()`**(§5.4)。
|
||||
- 两个 CMake option:`MOBILEGL_BUILD_DISAGGREGATED`(OFF) 与 `MOBILEGL_BUILD_DISAGGREGATED_INPROC`(OFF);`MOBILEGL_TRANSPORT` 解析;§13 的 flatbuffers include-dir guard。
|
||||
- `MG_Remote/{Protocol,Transport}` 骨架:`ITransport`、`InProcessTransport`、校验型 `Framing`、`Ring` + `RingControl`(**双 tail、双游标三元组、双向 doorbell**)、`Doorbell`、`ShmSegment`(memfd/ASharedMemory/shm_open/CreateFileMappingW)、**`SCM_RIGHTS` fd 传递(第一优先)**。
|
||||
- `protocol.fbs` + 提交的 `protocol_generated.h` + `gen_protocol.py` + CI `flatc-check`;`Records.def` 的 `static_assert` 与**运行期边界检查**生成。
|
||||
- `gen_backend_state_surface.py` + `Coverage.def` **和** `gen_impl_mutation_surface.py` + `MutationCoverage.def` + `CoverageAssert.cpp` + CI `coverage-check`。
|
||||
- `MG_Test/Wire/` 目录(复制 `MG_Test/Buffer/CMakeLists.txt`)。
|
||||
- **`TracyPlot` 字节计数器**,装在 wire **两侧**,按类别分:`cmd-records`、`stage-buffer`、`stage-texture`、`stage-ubo`、`persistent-map-push`、`server-ring`、`server-staging`(树里今天完全没有 per-frame 字节度量:`MG_Util/Metrics` 只是格式算术,Tracy 只有 zone 无 plot,MC 26.3 战役的 PANDIAG 已不在树里)。
|
||||
- `mobilegl_server_main` 的 `extern "C" __attribute__((visibility("default")))` 声明(§11.2)。
|
||||
- **spike A(Android 交付链,半天)**:从根 CMakeLists 造一个平凡的 `libMobileGLServer.so`(`add_executable` + `PREFIX "lib"/SUFFIX ".so"`),确认 AGP 把它打进 `lib/arm64-v8a/`;让 `TraceReplayActivity` 从 `getApplicationInfo().nativeLibraryDir` **`posix_spawn`** 它并打一行日志——在**应用自身进程(`untrusted_app` 域)**验证 exec,而不是靠 `run-as`。同时把一个通用 env 透传(`--es mobilegl_env "K=V;K=V"`)接进 trace 路径的五个文件(`trace-replay-ci.sh`、`TraceReplayActivity.java`、JNI Request marshalling、`trace_replay_core.cpp`、`run_android_retrace_local.py`),取代逐 knob 加 `--es/--ez`。
|
||||
- **spike B(external memory 可行性,半天)**:最小程序,导出一个 `HOST_VISIBLE|HOST_COHERENT` VkBuffer 的 fd,`mmap` 后回读校验,在 `35d0befa`(Adreno 830)与 `3B159D009VZ00000`(Mali)各跑一次。与 `SCM_RIGHTS` 测试同批。**目的是让 P7 的结论在第一周就有方向**:若两台都不行,P7 缩为"记录并回退",省 6 天。
|
||||
|
||||
**验收**
|
||||
- Linux 与 Android/NDK 上 `cmake --build .` 默认 target 成功。
|
||||
- `ctest -L unit`、`-L integration-gpu` 与 `81b17c0b` 同一通过集。
|
||||
- `MG_Test/Wire` 的 fd 传递测试把一个 memfd 从 fork 出的子进程传回父进程并读到相同字节。
|
||||
- **`nm --defined-only` 与去符号 `.text` size 与改动前的 `libMobileGL.so` 一致**(OFF 构建);`nm -D | grep mobilegl_server_main` 在 RelWithDebInfo 下命中。
|
||||
- spike A:设备上打出那行日志。
|
||||
- spike B:结论写进 §17 的开放问题并驱动 P7 的排期。
|
||||
- **§12.2 的取舍拍板**:`inproc` 走"四全局角色隔离"还是"降级为纯测试模式",写进文档。
|
||||
|
||||
### P1a — 垂直切片(client + inproc applier),Linux 门(6 天)
|
||||
|
||||
**范围刻意收窄到 OpenRA 需要的东西**:仅 DirectGLES;buffer(仅 shadow,采纳强制关,**含 §5.10 的 persistent-map 推送**);2D 纹理的整 level 与 union-box 上传(**含 §5.6a 的 clear-on-emit**);VAO;FBO;render state;binds;索引与非索引 draw;clear;present;**server 从源码 relink**(带全字段 `reflectionDigest`);一条阻塞 `ReadPixels`;**client 侧 `MarkGpuWritten` 保守置位(§5.6b)**。不含 sync/query/XFB/compute/dirty-rects/MultiDraw。
|
||||
|
||||
**交付物**:`WireMirror`(含 `PublishImplicitState`、`PersistentMapTracker`、`GpuWritePending`)、`EmitTable`、`EmitBufferOps`、`BackendObject_Remote`、`CapsMirror`、`ClientArrayBounds`、`CompositeResolver`(P1-4 走"server 自建 composite + digest 校验",见 §5.7);`ReplicaContext`、`Applier`(含 `MG_Remote::Shared::` 的 XFB/mipmap helper 接线,即使这一阶段还用不到 XFB)、`ServerLoop`(io+apply);`InProcessTransport` 上跑通。
|
||||
|
||||
**验收**
|
||||
1. `ctest -R "DirectGLES\.Split\..*(ClearThenReadPixels|Triangle)"` 在 Linux + `MOBILEGL_TRANSPORT=inproc` 绿。
|
||||
2. **新增 `PersistentCoherentMapScenario`**(map `PERSISTENT|WRITE|COHERENT`、写、不做任何其它 GL 调用、draw、readback 校验)在 split 下绿。**这是本计划里唯一一个专为一个 fatal 缺陷设的门**,必须在 P1a 就绿。
|
||||
3. 记录**两个进程/两个角色的峰值 RSS**(不只是 server 的)作为 P5 与 §16-R14 的基线。
|
||||
4. Tracy 计数器给出 `persistent-map-push` 的字节量(§5.10 保守版的代价)。
|
||||
|
||||
**明确非目标**:性能。P1-4 双份 glslang,**MC 级负载不在此测**。
|
||||
|
||||
### P1b — spawn transport,Linux 门(4 天)
|
||||
|
||||
**交付物**:`SocketTransport`(socketpair + `fork`/`execve` + 显式 envp 剔除 `MOBILEGL_TRANSPORT`/`MOBILEGL_IPC_*`)、`ServerMain`、`MOBILEGL_IPC_SERVER_PATH` 发现链、就绪握手与有界重试、EOF 即时退出。
|
||||
|
||||
**验收**
|
||||
1. P1a 的全部测试在 `MOBILEGL_TRANSPORT=spawn` 下绿(两个真进程、真 socket、真 `SCM_RIGHTS` 段)。
|
||||
2. **fork 链测试**:spawn 一个 server 并断言进程树只多出恰好一个子进程(§11.1)。
|
||||
3. **HeadlessGL 预检交互测试**:在开着 fork 预检的 Linux 上跑整套 split 集成用例,断言没有孤儿 server(用 `pgrep` 计数 + 预检结束后 100ms 内归零)。
|
||||
|
||||
### P2 — 广度:集成套件、trace 语料对齐、设备首跑(9 天)
|
||||
|
||||
**交付物**
|
||||
- 其余记录种类(MultiDraw/indirect 族含 client 数组范围计算与索引扫描、纹理 dirty rects、texture view、buffer texture、image unit、sampler、**renderbuffer storage**、program pipeline、`CopyImageSubData`、`BlitNamedFramebuffer`、`PixelStorePack`、`CurrentAttrib`)。
|
||||
- 完整 caps mirror 与 `tableSlotMask`。
|
||||
- DirectVulkan applier 支持(`SwapchainObject` 的 default-FBO 占位写变成 `EvDefaultFramebufferInfo`)。
|
||||
- `add_trace_replay_test` 的 `SPLIT` 参数:测试名加后缀、`-DTRACE_TRANSPORT=` 与 `run_trace_case.cmake` 的消费、`MOBILEGL_IPC_SERVER_PATH` 注入(§13)。
|
||||
- 一个**无 present** 的 split 集成用例(§9.3)。
|
||||
- `ClientArrayAfterComputeWriteScenario`(§6.10)。
|
||||
|
||||
**验收**
|
||||
1. `ctest -L integration-gpu -R '^DirectGLES\.Split\.'` 与 `'^DirectGLES\.'` **逐名同一通过/失败集**;DirectVulkan 同。
|
||||
2. CI 全部 trace case(OpenRA、`minecraft-1.21.4-startup`、`-main-menu`、`1.21.11`、`1.17`、两个 Create)在 Linux split 模式 SSIM ≥ 0.99。**两个带 `coherent_as_flush: true` 的 Create 用例在 split 与 monolith 下都开着该开关跑**(§5.10 已让两侧走同一路径),若 Tracy 显示保守推送在这两个 fixture 上代价不可接受,则把 §5.10 的精确版(P4.5 的块脏位)提前到本阶段——这是全计划唯一允许因测量改变阶段顺序的地方。
|
||||
3. **`python tools/trace_replay/run_android_retrace_local.py --case OpenRA --backend DirectGLES` 在 `35d0befa` 上 SSIM ≥ 0.99(split 模式)** —— 本阶段的出口判据(从 P1 移来),每轮约 1 分钟。
|
||||
|
||||
### P2.5 — inproc 渲染线程:单机收益证伪门(3 天)
|
||||
|
||||
**交付物**:`add_trace_replay_test` 的 `INPROC` 变体;应用线程与 apply 线程的**逐线程 CPU 时间**插桩(不只是墙钟);`MOBILEGL_IPC_SERVER_AFFINITY` 的大核绑定(复用 `ShaderCompilePool.cpp:73-96`);用现有 `--benchmark --benchmark-tail-frames --benchmark-result` 在全部 fixture 上跑。
|
||||
|
||||
**验收**:`inproc` 与 `monolith` 的应用线程帧时差 + 两侧 CPU 时间在 Create/Flywheel 与 MC fixture 上被**测量并记录**,且带亲和性开/关两组。若不利,整个计划的价值主张在第 6 周(而不是第 15 周)被重新审视。**这是本计划最早的证伪点,也是 §16-R15 排期风险的退火器。**
|
||||
|
||||
### P3 — sync / query / present 节奏(5 天)
|
||||
|
||||
**交付物**
|
||||
- client 铸造的 sync/query handle;轮询入口的 publish + 饥饿升级(§7.2)。
|
||||
- **fence 完成度来自真实逐 fence 退休**(§8 末尾):server 侧真 `FenceSync` + 非 present 轮询 + `EvFenceSignaled`。
|
||||
- **DirectGLES 的非 present fence tick**(§9.3)。
|
||||
- `EvQueryResult`;present credit **默认 1** + 三个 seq 水位;swap interval 搭 `RecPresent`。
|
||||
- §8 的三个 `dev` 独立修复。
|
||||
- per-frame round-trip 计数器;**输入延迟直方图**(记录发射 → present 完成,§9.1)。
|
||||
|
||||
**验收**
|
||||
1. `XfbPrimitiveQueryScenario`、`PrimitivesGeneratedNoXfbScenario`、`AsyncCompileScenario` 在 split 下绿。
|
||||
2. round-trip 计数器:在**全部 trace case** 的稳态帧上,draw/state/upload 路径的 round trip 读 **0**;conditional render 与阻塞式 query 的次数按用例列表公布(不是笼统宣称"零 round trip")。
|
||||
3. **零 timeout 轮询循环测试**:一个只有 `glFenceSync` + `while(glClientWaitSync(...,0)==GL_TIMEOUT_EXPIRED){}` 的用例必须在有界时间内退出(若无 §7.2 的 publish 规则它会永久挂起)。
|
||||
4. `bench.sh` 在 `35d0befa` 配对 A/B(两侧均关采纳)显示 split 帧时在 monolith 的 10% 内,且**输入延迟直方图**的 p50/p99 被记录。
|
||||
|
||||
### P4 — 回读与 GPU-written(5 天)
|
||||
|
||||
**交付物**:`SEG_REPLY`;阻塞 `ReadPixels` → 客户内存;PBO readback 变 fire-and-forget + client 侧 `MarkGpuWritten`;`EvGpuWritten` 作为收窄提示;`EvBufferWriteback`;`glGetTexImage`/`GetTextureImage` 路由 + **per-level `serverAuthoritative` 位**(只覆盖生成 mip 与 CopyImage 镜像两处,§6.6);`EvGlError` + **分配类入口的 `kNeedsAck`**(§5.6c);`SEG_EVENT` 溢出策略与等待中排空(§7.4)。
|
||||
**`glCopyTexSubImage*` / `glClearTexImage` 保持前端实现不变**(推翻上一版的"移到 server + `EvTexWriteback`")。
|
||||
|
||||
**验收**
|
||||
1. split 下 `DepthStencilReadbackScenario`、`DepthStencilReadbackMatrixScenario`、`DepthStencilReadbackAttachmentShapeScenario`、`PackedWordReadbackScenario`、`LayeredTextureReadbackScenario`、`ClearThenReadPixelsScenario`、`PixelStoreSweepScenario`、`CopyImage*`(4)、`SsboArrayLengthScenario`、`AtomicCounterScenario`、`StorageBufferRegrowScenario` 双 backend 全绿。
|
||||
2. **OOM 探测用例**:请求一个必然失败的巨大 renderbuffer,断言紧接着的 `glGetError()` 返回 `GL_OUT_OF_MEMORY`。
|
||||
3. **事件 ring 溢出故障注入**:client 被 present credit 阻塞时灌满 `SEG_EVENT`,双方都不死锁,`eventDropped` 只统计到 `EvLogLine`。
|
||||
|
||||
### P4.5 — 零拷贝 shadow-in-shm 前移(4 天)
|
||||
|
||||
(原计划推到 P6;MC pan 每帧 ~9MB 的额外拷贝不该背六个阶段)
|
||||
|
||||
**交付物**:`ShadowArena`;`MapAlignedAllocator` 与 `MipmapStorage` level vector 的 shm arena(≥256KiB 才走,**整段 `#if MOBILEGL_BUILD_DISAGGREGATED` 包裹**,§12 第 3 层);per-shadow 64KiB 块发送水位 WAR 规则;**shadow 块退休规则**(§6.1);§5.10 精确版 persistent-map 推送复用同一套块脏位;`MOBILEGL_IPC_SHADOW_SHM` 开关。
|
||||
|
||||
**验收**
|
||||
1. P2/P4 门在开关两态下均不回归。
|
||||
2. **两侧** `TracyPlot` 显示 buffer 上传路径的总拷贝次数从 4 降到 3(或选方案 B 则到 2,§6.4);staged-copy 回退率被记录成数字。
|
||||
3. `nm`/`.text` monolith 门仍绿(这一条是本阶段最容易破的)。
|
||||
4. 对象删除/重定义与未 apply 记录并发的压力测试不读到别的对象的字节。
|
||||
|
||||
### P5 — `ProgramPublish`,退役 server relink(6 天)
|
||||
|
||||
**交付物**:`ProgramArtifactsArchive.h`(`Visit()` + `sizeof` 绊线);`ProgramObject::InstallPublishedLink`;`GLContext::SetReplicaResolvedDrawProgram`(`#if MOBILEGL_BUILD_DISAGGREGATED` 包裹)+ client 侧 composite 解析;`MOBILEGL_IPC_PROGRAM=publish|relink`;`publish` 下移除 server compile pool;**顺带把 DirectVulkan 的 blit / depth-mipmap 四段固定 shader 在构建期烘成 SPIR-V**(`VulkanRenderer.cpp:4211-4356`,同时也从 **monolith 启动**里去掉一次 glslang 编译链接;逃生口 `MOBILEGL_BAKED_INTERNAL_SHADERS=0`)。
|
||||
|
||||
**验收**
|
||||
1. P2 全门在 `publish` 下重跑不变。
|
||||
2. `relink` 下 `reflectionDigest` 在每个 trace case 绿(即它是活门不是死门)。
|
||||
3. `35d0befa` 上用 `minecraft-1.21.4-startup` trace 做首帧 link 延迟 A/B,`publish ≤ relink`。
|
||||
4. **`nm` 复核 `libMobileGLServer.so` 在 `publish` 下不再引用 glslang 库符号**(注意 `ProgramObject.h` 传递包含 `ShaderObject.h` → `ShaderCompileTask.h`,所以这条必须**用 `nm` 验证而不是断言**)。
|
||||
5. server 峰值 RSS 相对 P1a 基线下降;两个进程的 RSS 合计与 §16-R14 的预算对表。
|
||||
|
||||
### P6 — 数据面性能(6 天)
|
||||
|
||||
**交付物**:`PendingResidentWrite` 借用 ring slot(用 `*RetiredTail` 门控);全局 UBO ring 进 shm;解码移到 `mgl-srv-io`;可选 `mgl-client-tx`;bind 合并(凭数据决定);`mirror-map` 两次映射消除 ring wrap;`MOBILEGL_IPC_INLINE_PAYLOADS` 负面对照;§6.4 方案 B(replica adopt client shadow)的可行性评估与实现(若 Tracy 数据支持);Windows AF_UNIX 评估(§11.5);`MOBILEGL_IPC_SPIN_US` 与 `MOBILEGL_IPC_PRESENT_CREDIT` 的设备调优。
|
||||
|
||||
**验收**:两台设备上 `minecraft-1.21.4-fabric-sodium-in-world` 的配对 A/B,每项优化用自己的开关单独可 A/B;P2/P4 门在任意开关组合下不回归;输入延迟直方图不因任何优化恶化。
|
||||
|
||||
### P7 — persistent map 与 ≥16MiB 采纳(8 天,若 P0 spike B 全否则缩为 2 天)
|
||||
|
||||
**交付物**:`SEG_ADOPT`(server 分配)+ 三档探针(T2/T1/T0)+ 自动回退到 P4.5 路径;阻塞 `AcquirePersistentMap`;client 侧注册 `ResidentSubData`;`MOBILEGL_IPC_RESPAWN` 与 `MOBILEGL_IPC_ADOPT_TIER` 的互斥检查(§5.8)。
|
||||
|
||||
**验收**:`LargeArenaAdoptionScenario`、`ResidentIndexScenario` 在采纳开启下绿;`bench.sh` 在 Mali 设备 `3B159D009VZ00000` 上用 `minecraft-1.21.4-in-world` 报出 {monolith, split+采纳, split+回退} 的 p99 帧时,以 MC 26.3 的 163→21ms 为标尺。
|
||||
**"设备 X 上拒绝,已记录,回退成本 N ms" 是本阶段的可接受结论**——因为回退路径在 P1a/P4.5 已交付并测量。
|
||||
|
||||
### P8 — XFB / compute / 健壮性 / 多线程(6 天)
|
||||
|
||||
**交付物**:XFB capture writeback 与 scatter(全部在 server 对 replica 执行,只有合并后的 range 过线);**`RecXfbAccounting` 与共享 helper 的完整接线**(§2(g)-2;注意它必须跟着 `RecBindTransformFeedback` 的对象切换走,`Core.cpp:1273,1296`);GS strip 顺序修正移到 server;compute dispatch/indirect/barrier/image load-store;`EvGlError` 与 `glGetError` 的顺序 + `MOBILEGL_IPC_STRICT_ERRORS` 诊断开关;server 死亡的 device-lost 闩锁与 client 死亡的 server 拆机;外来线程 sync/query 的 `AuxRequest`;修 `EGLOperationMutex` 既有漏洞(`ReleaseThread`、`SwapInterval`)。
|
||||
|
||||
**验收**
|
||||
1. split 下 `Xfb*`(5)、`Tessellation*`(2)、`SsboArrayDynamicIndexScenario`、`ImageLoadStoreSsoScenario` 双 backend 绿。
|
||||
2. `tools/cts/scripts/run_cts_local.py --backend {DirectGLES,DirectVulkan} --env MOBILEGL_TRANSPORT=spawn` 在 GL33 caselist 上 conformance rate 与 monolith 相差 ≤ 0.5 个百分点(按项目既定的逐 backend 表格式报告:行=GL 版本/扩展,列=状态计数,conformance rate = Pass/(Pass+Fail),分母不含 NS)。
|
||||
3. 故障注入测试在帧中 SIGKILL server,client 干净地以 `EGL_CONTEXT_LOST` 退出而不崩溃。
|
||||
|
||||
**注**:XFB 场景的 `RecXfbAccounting` 骨架其实在 P1a 就要落地(helper + 记录 + applier 分支),只是这里才被真正测到。§5.9b 的生成器会在 P0 就把它标成未映射并让编译失败,从而强制这个顺序。
|
||||
|
||||
### P9 — Android 生产窗口路径(10 天)
|
||||
|
||||
**交付物**:`MobileGLServerService`(`android:process=":mgl"`);Messenger/AIDL 的 `Surface` 交接;surface 生命周期(`surfaceDestroyed`、1×1 pbuffer 交换舞、resize)作为协议消息;`ResyncSnapshot`;APK 打包与 `validate-plugin-apks.sh` 更新;`MOBILEGL_TRANSPORT` 进 plugin V2 metadata 与 FCL 用户 env 偏好。
|
||||
|
||||
**验收**:FCL 在 `35d0befa` 上以 split 模式把 Minecraft 1.21.4 拉到主菜单并进入世界;`bench.sh` 在同一个热窗口内报出 split vs monolith 的游戏内 FPS **与输入延迟**;plugin APK 通过 `.github/scripts/validate-plugin-apks.sh`;旋屏/后台切换的 surface 销毁重建无泄漏无挂起;两个进程的合计 RSS 落在预算内。
|
||||
|
||||
**合计 ≈ 77 人日 ≈ 16 周**(5+6+4+9+3+5+5+4+6+6+8+6+10)。里程碑:**第 3 周末 Linux 上跨进程渲染出第一帧**(P1b),**第 5 周末真机 OpenRA 绿**(P2),**第 6 周有 monolith 侧的独立收益数字**(P2.5)。
|
||||
|
||||
---
|
||||
|
||||
## 16. 风险与对策
|
||||
|
||||
| # | 风险 | 对策 |
|
||||
|---|---|---|
|
||||
| R1 | **replica applier 在某个长尾副作用上与 client 的 MG_State 语义分歧**——具体形态是 MG_Impl 在 table 调用旁做的 mutation(§2(g) 已确认两族:`EnsureGeneratedMipmapStorageAllocated`、`AccountTransformFeedbackPrimitives`)。症状是错误像素或错误查询结果,不是崩溃 | **§5.9b 的第二个生成器**把这一面变成编译期门:MG_Impl 里任何与 table 调用同函数的 mutator 未映射即 `#error`。两族已知实例在 P1a 就用共享 helper 接线。P2 的门是**全部集成场景 + trace 语料的逐名通过集对齐**,远比 `Feat/CS-Delta-IPC` 的两 `GLContext` 逐字段比较(且只查了 5 域中的 2 域)严苛。外加 `MOBILEGL_IPC_VALIDATE_SERVER`(server 侧保留 MG_Impl 校验器,分歧变成 server 侧 GL error 而非错误像素;CI 常开,出货构建用 `kPrevalidated` 短路) |
|
||||
| R2 | **应用通过 coherent persistent map 写下的字节丢失**(`SyncPersistentMappedRange` 无 client 侧调用者) | §5.10 三件套:map/unmap 上线、client 侧块粒度推送、`PersistentCoherentMapScenario` 作为 **P1a 门**。这是本轮新增的最高优先级修复 |
|
||||
| R3 | **read-after-GPU-write 静默读到陈旧 shadow**(`MarkGpuWritten` 无 client 侧建立者) | §5.6b:client 在每个 draw/dispatch 发射点保守置位并记 `emitSeq`;读入口强制 publish+等待+排空;`EvGpuWritten` 降级为收窄提示。§7.4 的排空点补上四个 buffer 读入口 |
|
||||
| R4 | **零 timeout 轮询循环挂死**(轮询入口不是 publish 触发器) | §7.2:`glClientWaitSync`/`glGetSynciv`/`glGetQueryObject*(AVAILABLE\|NO_WAIT)` 全部成为门铃点,`GL_SYNC_FLUSH_COMMANDS_BIT` 无条件 publish;连续 N 次无进展升级为阻塞 round trip。P3 有专门的门 |
|
||||
| R5 | **fence 完成度退化成帧计数推断**(DirectGLES 的 `completedFrameSerial` 只在 Present 前进),重蹈 MC 1.21.5 的 native-heap OOM | §8 末尾:server 侧真 fence + 非 present 轮询 + `EvFenceSignaled`;§9.3 的非 present fence tick 同时解决无 present 循环下的 ring 饥饿 |
|
||||
| R6 | **纹理每次更新都传整 level**(永不清 dirty flag ⇒ union box 单调增长) | §5.6a:client 在发射后立刻 `MarkStorageDirty(...,false)`;ack 问题由"resync 从完好 shadow 传整 level"+"硬 drain 后重发未 apply 记录"两条收口。已确认 MG_Impl 从不读自己的 dirty 状态,所以清是安全的 |
|
||||
| R7 | **每 draw 编解码成本超过它替换掉的东西**,MC 级帧(1000-4000 draw)反而更慢;且总 CPU 工作量本来就变大(遍历跑两次) | 记录是 FlatBuffers `struct`(8B header + 定长),无 verifier walk;publish 是每记录一次 release store 而不是 64KiB 攒批(§7.2)。**`TracyPlot` 两侧计数器在 P0 就落地**;P2.5 在第 6 周给出 inproc 的证伪数字**并带逐线程 CPU 时间**;`mgl-srv-apply` 绑大核(§10),mask 打日志;P3 门要求 split 帧时在 monolith 10% 内**才**授权后续优化 |
|
||||
| R8 | **client 侧等待全是跨进程自旋**(无 producer 侧门铃),手机上一颗大核满频空转 | §6.2a 的双向 doorbell:`producerParked` + 反向 1 字节;自旋窗口 `MOBILEGL_IPC_SPIN_US` 可调可测。`inproc` 用 condvar |
|
||||
| R9 | **`SEG_EVENT` 满 + client 被 credit 阻塞 = 双向死锁** | §7.4:等待循环内必须排空;`EvLogLine` 有损(覆盖最旧 + `eventDropped` 计数);语义事件无损,满时 server 置 `eventRingFull` 并停在记录边界上停止 apply。P4 有故障注入门 |
|
||||
| R10 | **端到端延迟叠加**(client credit + server FIF + 驱动深度 = 4-5 帧) | §9.1:credit 默认 1;文档写出叠加公式;P3/P9 增加**输入延迟直方图**门,只有实测吞吐收益抵得过实测延迟才调高 |
|
||||
| R11 | **`inproc` 因为四个进程全局而不可行**,从而 P2.5 这个最早的证伪门消失 | §12.1/§12.2:拆成两个 CMake option(出货只开 `spawn`,热路径无 TLS);四个全局都要角色隔离,shim 需求列全,非箭头用法实测 133 处;**P0 结束前必须拍板**是做隔离还是把 `inproc` 降级为纯测试模式,并写清后者对 P2.5 的含义 |
|
||||
| R12 | **分配类 GL 错误晚到,OOM 探测惯用法失效** | §5.6c:只把分配类入口标 `kNeedsAck`(罕见且本来就贵),其余保持晚到;`glGetError` 永远本地。P4 有 OOM 探测门 |
|
||||
| R13 | **server 分配的 host-visible coherent 内存无法导出重映射**,丢掉 ≥16MiB 采纳(值 p99 163→21ms、~400MB RSS) | 排在**最后**(P7),且 **P0 的 spike B 在第一周就给出方向**。此时 P1a/P4.5 的 shadow 路径已交付并测量。阶段明确允许"拒绝,已记录"的结论。前端已容忍 `nullptr`(三处),kill switch 已存在,无需回滚任何代码 |
|
||||
| R14 | **内存翻倍无预算**:client 段(`SEG_CMD` 8MiB + `SEG_STAGE` 32MiB↑)+ 完整 replica context(每 buffer 一份 `PipeResource`、每 texture level 一份 `MipmapStorage`)+ server 自己的三个 ring(UBO/unpack/upload 各 4→64MiB,`Managers.cpp:82-96`)+ 64MiB buffer pool(`Managers.cpp:566`)。合计可达 ~450MiB 新增,而本项目把"省 400MB"当作采纳修复的头条成果,且有 blanket-immutable 导致 LMK 屠杀的记忆 | 计划里与 round-trip 预算并列写出**稳态内存预算**;P1a 验收记录**两个进程**的 RSS(不只是 server);`SEG_STAGE` 上限由实测定而不是默认 256MiB;优先推进 §6.4 方案 B(replica 采纳 client shadow),因为它同时消掉重复 shadow 而不只是一次拷贝 |
|
||||
| R15 | **排期乐观**(P0 5 天含两个 spike + 四平台 shm + SCM_RIGHTS + 两个代码生成器;P1a+P1b 10 天做完整 client 与 server)。校准点:`Feat/CS-Delta-IPC` 10 个 commit / 6668 行、从未渲出一帧,并自承四天耗在一个不可复现的回归上 | P1 已拆成 P1a/P1b,设备 retrace 移到 P2 出口;**P2.5 是排期风险的退火器**——第 6 周就能拿到"这条路值不值得走"的数字,且它本身不依赖任何跨进程工作。若 P0/P1 超期 50%,先跑 P2.5 的 inproc 部分再决定是否继续 |
|
||||
| R16 | **socket transport 是新实现**,而上一版有每次 send 的 UAF、无上限分配、无 fd 传递 | 从设计草图重写而非修补:读时按 64MiB 上限校验 magic/长度;接收缓冲不足时返回所需大小**且保留消息**;`async_write` 用 `shared_ptr` payload 自持缓冲;socketpair + 继承 fd 完全去掉 accept/connect(Windows 用 overlapped named pipe 对,§11.5)。**`SCM_RIGHTS` 是 P0 交付物并带独立测试** |
|
||||
| R17 | **Android 交付链**(server `.so` 打包、`untrusted_app` 域 exec、trace app env 透传)比想象的重,或被 AGP/SELinux 挡住 | **P0 的 spike A** 在第一周就验证;P1-P8 全部离屏且不依赖它(Linux 门优先);两条回退:裸 exec PIE server 配 `AHardwareBuffer_sendHandleToUnixSocket` blit-back;或把 split 作为 headless/工装专用配置发布 |
|
||||
| R18 | **spawn 出来的 server 继承 `MOBILEGL_TRANSPORT` 而无限 fork** | §11.1 双保险:显式 envp 剔除 + `mobilegl_server_main` 强制 Monolith;P1b 有进程树计数门 |
|
||||
| R19 | **HeadlessGL 的 fork 预检留下持有 GPU 的孤儿 server** | §11.3:EOF 即时退出(亚秒);就绪握手有界重试;P1b 有 `pgrep` 计数门 |
|
||||
| R20 | **`MobileGLServer` 在两个桌面门里都找不到**(`dladdr` 对静态链接的 itest 与显式 `-DMOBILEGL_LIBRARY` 的 retrace 都失效) | §11.1:`MOBILEGL_IPC_SERVER_PATH` 为主、`dladdr` 兜底;`RUNTIME_OUTPUT_DIRECTORY` 对齐;每条新 ctest `ENVIRONMENT` 都注入;并复核 CI artifact 搬运后绝对路径是否还成立 |
|
||||
| R21 | **`mobilegl_server_main` 在出货构建里 dlsym 不到**(非 Debug 的 hidden visibility preset) | §11.2:显式 `visibility("default")`;P0 加 `nm -D` 断言 |
|
||||
| R22 | **Magma 的 present 节奏被 IPC credit 改变**(它从不注册 `SetSwapInterval` 且偏好 MAILBOX/IMMEDIATE) | `MOBILEGL_IPC_PRESENT_CREDIT` 可配;P6/P9 在设备上测量输入延迟与帧节奏;若 Magma 需要,把"注册 `SetSwapInterval` 并映射到 FIFO"作为**独立的 `dev` 变更**,不让两套机制同时管节奏 |
|
||||
| R23 | **两件 Android 产物版本漂移** | 一份共享库两个角色:server 是 ~30 行 stub,`dlopen(libMobileGL.so)` + `dlsym(mobilegl_server_main)`;`Hello`/`Welcome` 里的 build fingerprint(git hash + `Records.def` hash)不匹配 → 明确报错而非静默协议故障 |
|
||||
| R24 | **`SEG_CMD` 的记录被并发写坏导致 applier 游标走飞** | §6.3 的运行期边界检查(`size >= sizeof(T) && size <= remainingRingBytes && (size%8)==0`,`kVarTail` 另查尾长自洽),违反即 `Fatal{ProtocolCorruption}`,绝不进入 UB |
|
||||
|
||||
---
|
||||
|
||||
## 17. 开放问题
|
||||
|
||||
1. **T1/T0 采纳在 Adreno 830 与 Mali-G925 上到底能不能用?** 由 **P0 的 spike B** 在第一周回答(导出 `HOST_VISIBLE|HOST_COHERENT` VkBuffer 的 fd,client `mmap` 后回读),与 `SCM_RIGHTS` 测试同批。若两台设备都不行,P7 缩为"记录并回退",节省 6 天;若可行,还要回答 GLES 侧能否用 `GL_EXT_memory_object_fd` + `glBufferStorageMemEXT` 走同一条路(DirectGLES 的采纳今天走的是 `glBufferStorageEXT` + `glMapBufferRange(PERSISTENT|COHERENT)`,不是外部内存)。
|
||||
2. **`glGetError` 的严格性 CTS 到底要求到什么程度?** §5.6c 已把分配类改成同步 ack,剩下的晚到错误里,哪些 CTS case 可能观察到?P8 需要列出清单。若清单为空,`MOBILEGL_IPC_STRICT_ERRORS` 可以永久保持默认关。
|
||||
3. **P2.5 的 inproc 数字若为负怎么办?** 需要事先约定:若 inproc 相对 monolith 无收益甚至更慢(含亲和性绑定之后),是继续(因为拆分本身还有内存隔离、崩溃隔离、工装价值)还是收缩到 headless 工装用途?**建议在 P2.5 前由协调者拍板判据**,并同时约定"绑大核后仍无收益"与"未绑核无收益"是两个不同的结论。
|
||||
4. **§12.2 的隔离取舍**:`inproc` 做四全局角色隔离(含 133 处非箭头用法的 shim)值不值?若判定不值而把 `inproc` 降级为纯测试模式,P2.5 测的就不再是 monolith 渲染线程交付物——那时 monolith 侧的收益要靠什么证明?**P0 结束前必须有答案。**
|
||||
5. **§6.4 的拷贝目标选方案 A 还是 B?** 方案 B(replica 的 `PipeResource` 采纳 client 的 `SEG_SHADOW` 只读映射)能把 buffer 上传路径从 3 次降到 2 次并消掉重复 shadow(对 R14 的内存预算意义更大),但要处理 server 侧写(`WritebackFromBackend`、生成 mip、CopyImage 镜像)的 copy-on-write 升级。P4.5 先做 A 并测量,P6 由数据决定是否做 B。
|
||||
6. **`SEG_SHADOW` 在 Android 上应该用 `ASharedMemory` 还是 memfd?** 前者是平台正道且有 `setProt` 只读降权(正好匹配"client 拥有、server 只读"),后者有 sealing。大 buffer 频繁重映射的场景需要一次实测。
|
||||
7. **client 侧是否需要 `mgl-client-tx` 发送线程?** 只有 P6 的 `TracyPlot` 数据能回答;在此之前不要预先加线程(会引入拷贝或锁)。
|
||||
8. **`ResyncSnapshot` 与采纳的互斥能否放松?** §5.8 目前规定 `MOBILEGL_IPC_RESPAWN=1` 与 `MOBILEGL_IPC_ADOPT_TIER != 2` 互斥,因为 adopted store 的字节在 server。是否值得为 adopted buffer 单独做一条"server 死亡时其内容视为丢失、按 `hasDefinedContent=false` 重建"的降级路径?取决于 MC 的 chunk arena 在 respawn 后能否被应用自己重填。
|
||||
9. **Windows AF_UNIX-everywhere 是否值得?** asio 的 IOCP `async_accept` 走 `AcceptEx`(AF_UNIX 从不支持);我们用继承 overlapped 句柄绕开 accept,理论上可行但需真编真跑。P6 评估,named pipe 是已知可用的默认。
|
||||
10. **P9 的 ART 启动成本具体是多少?** 若不可接受,是否接受"游戏内走 monolith,工装/CTS 走 split"的长期二元形态?
|
||||
11. **`tools/trace_replay` 的 Android 应用内路径是否从非主线程驱动 GL、是否每重放帧调 `Present`?** 桌面重放器传 `--singlethread`(`trace_replay_core.cpp:430`),Android 应用内路径本次未完整追踪,它决定该工装能否验证节奏模型(尤其是 §9.1 的输入延迟直方图)。
|
||||
12. **`MOBILEGL_IPC_PERSISTENT_BLOCK_KB` 的默认值与脏块判定方式**:P1-4 的保守版(整 mapped span 按块重传)在 Create/Flywheel fixture 上的实测代价是多少?精确版用 `memcmp` 还是 mprotect 写屏障?前者对 1MB 块是 ~50µs 量级且只在真正 mapped 的 buffer 上跑,看起来够用,但需要 P2 的数据确认。
|
||||
13. **`SEG_STAGE` 的上限该定多少?** R14 要求由实测定而不是默认 256MiB。需要 P2 之后用 MC in-world 与 Create 两类 fixture 的 `stage-*` Tracy 计数器给出 p99 占用。
|
||||
|
||||
---
|
||||
|
||||
## 附:环境变量与 CMake 选项汇总
|
||||
|
||||
**CMake**
|
||||
| 选项 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `MOBILEGL_BUILD_DISAGGREGATED` | OFF | 出货形态。开启后 `MG_Remote/**` 进 `SOURCE_FILES`,支持 `spawn`/`unix:`/`pipe:`。四个进程全局保持普通全局,GL 热路径无 TLS |
|
||||
| `MOBILEGL_BUILD_DISAGGREGATED_INPROC` | OFF | CI/调试形态,隐含开启上者,额外加四全局角色隔离 shim |
|
||||
| `MOBILEGL_FLATC_EXECUTABLE` | 空 | 只服务 CI 的 `flatc-check`;默认构建图里没有 `flatc` |
|
||||
| `MOBILEGL_BAKED_INTERNAL_SHADERS` | ON (P5+) | DirectVulkan 的 blit/depth-mipmap shader 构建期烘 SPIR-V;monolith 也受益 |
|
||||
|
||||
**运行时**
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `MOBILEGL_TRANSPORT` | `monolith` | `monolith` / `inproc` / `spawn` / `unix:<path>` / `pipe:<name>` |
|
||||
| `MOBILEGL_IPC_SERVER_PATH` | 空 | server 可执行文件路径(**主要发现机制**,`dladdr` 兜底) |
|
||||
| `MOBILEGL_IPC_RING_MB` | 8 | `SEG_CMD` 大小 |
|
||||
| `MOBILEGL_IPC_STAGE_MB` | 32 | `SEG_STAGE` 初始大小;上限由实测定(§17-13) |
|
||||
| `MOBILEGL_IPC_PRESENT_CREDIT` | **1** | client 允许领先的 present 数(1-4);延迟叠加见 §9.1 |
|
||||
| `MOBILEGL_IPC_SPIN_US` | 50 | 挂起前的自旋窗口(两侧 doorbell 共用) |
|
||||
| `MOBILEGL_IPC_POLL_ESCALATE` | 64 | 同一 handle 连续无进展轮询多少次后升级为阻塞 round trip |
|
||||
| `MOBILEGL_IPC_PERSISTENT_BLOCK_KB` | 64 | persistent-map 推送的块粒度 |
|
||||
| `MOBILEGL_IPC_PROGRAM` | `relink` (P1-4) → `publish` (P5+) | program artifact 传输方式;`relink` 保留为常驻 oracle |
|
||||
| `MOBILEGL_IPC_ADOPT_TIER` | `auto` | `auto`/`0`(T0)/`1`(T1)/`2`(T2 拒绝);与 `MOBILEGL_IPC_RESPAWN` 互斥(§5.8) |
|
||||
| `MOBILEGL_IPC_SHADOW_SHM` | 1 (P4.5+) | shadow-in-shm 零拷贝 |
|
||||
| `MOBILEGL_IPC_INLINE_PAYLOADS` | 0 | 负面对照:一律内联,不用 `SEG_STAGE` |
|
||||
| `MOBILEGL_IPC_SERVER_AFFINITY` | `auto` | `mgl-srv-apply` 的核绑定;`auto` 用 `ShaderCompilePool` 的大核探测 |
|
||||
| `MOBILEGL_IPC_VALIDATE_SERVER` | CI=1,出货=0 | server 侧保留 MG_Impl 校验器,分歧变成 server GL error |
|
||||
| `MOBILEGL_IPC_STRICT_ERRORS` | 0 | 诊断开关:让所有 backend 错误同步 ack(分配类默认已是同步) |
|
||||
| `MOBILEGL_IPC_AUDIT` | 0 | 记录级审计日志 |
|
||||
| `MOBILEGL_IPC_TRACE` | 0 | 逐记录 trace(仅调试构建) |
|
||||
| `MOBILEGL_IPC_ATTACH` | 空 | 附着到已运行的 server(调试) |
|
||||
| `MOBILEGL_IPC_RESPAWN` | 0 | server 死亡后重启 + `ResyncSnapshot` |
|
||||
| `MOBILEGL_IPC_IDLE_EXIT_S` | 30 | server 的最后保险看门狗(EOF 应当即时退出) |
|
||||
|
||||
**保留的既有负面对照开关**:`MOBILEGL_ESPRYT_DISABLE_UBO_RING`、`_UNPACK_RING`、`_UPLOAD_RING`、`_INVALIDATE_FLUSH`、`MOBILEGL_DISABLE_LARGE_BUFFER_ADOPTION`、`MOBILEGL_COHERENT_AS_FLUSH`(**在拆分模式下照常生效**,§5.10/§6.8)。
|
||||
@@ -0,0 +1,374 @@
|
||||
# MobileGL 方案 B 实施计划:gallium 式显式接口 + backend 自有状态机(MGPipe)
|
||||
|
||||
> 状态:设计定稿 v2(2026-09-05,经三轮对抗性评审修订)。基线 `dev@81b17c0b`;实施分支 `feat/disaggregated`(worktree `../MobileGL-disagg`)。
|
||||
> 本文是**方案 B** 的实施计划。方案 A(server 内跑 `MG_State::GLState::GLContext` replica)见同目录 `PLAN.md`,其评审记录见 `REVIEW.md`。
|
||||
> 本文继承方案 A 的 §6-§13(传输、数据面、同步、present、线程、平台、构建),**只替换它的状态模型**(§5 与 §12 的 replica 特化部分)。凡标注"继承 PLAN.md §X"的内容,以 `PLAN.md` 为准,本文不复述。
|
||||
> 全部 `file:line` 引用针对**工作树** `dev@81b17c0b`。工作树有两处未提交的 `fprintf` 插桩,使 `DirectGLES.cpp` 在 ~660 行之后偏移 +11、`Managers.cpp` 在 872 行之后偏移 +3;`MG_State/`、`MG_Impl/`、`MG_Backend/DirectVulkan/` 的行号与 HEAD 一致。
|
||||
> **v2 修订说明**:v1 里一批继承自调研报告的 `SamplerObject.h` 行号(`:455-492`、`:532-537`、`:551`)指向文件末尾之后——该文件共 160 行。实际位置:`BorderColorForm` 在 `:60-70`、`SamplerParameters` 在 `:72-96`、`GetLifetimeId()` 在 `:141`、`BumpVersion()` 在 `:151`、`m_version` 在 `:155`。**P0 增加一条 CI lint:本目录下所有 `.md` 里的 `file:line` 必须在基线提交上解析到存在的行**(`git show <base>:<path> | wc -l` 比较),防止同类转抄错误再次进入实施规格。
|
||||
> 阅读顺序:本文件(§0-§3)→ `part2.md`(§4-§6)→ `part3.md`(§7-§10)→ `part4.md`(§11-§14 + 附)。
|
||||
|
||||
---
|
||||
|
||||
## 0. TL;DR、推荐与决策
|
||||
|
||||
### 0.1 一句话
|
||||
|
||||
**`MG_Backend` 已经是一台贴着目标 API 的状态机;它缺的不是状态,而是一份"我被告知了什么"的显式声明。MGPipe 就是那份声明。** 前端不再让 backend 每 draw 走 293 次 `MG_State::pGLContext->` 把整个 `GLContext` 拉出来,而是在每条命令之前由一个 state tracker 把变化**推**过去;server 进程因此只需要装 `MG_Backend` + MGPipe 的对象表,**不链接 `MG_State`、不链接 `MG_Impl`、不链接 glslang**。
|
||||
|
||||
### 0.2 接口不是从 gallium 自顶向下设计的,是从两个 backend 自己维护的关键结构反推出来的
|
||||
|
||||
这是本设计与"照抄 gallium"的根本区别,也是完整性论证的来源:
|
||||
|
||||
| backend 已有的结构 | 它是什么 | 反推出的接口 |
|
||||
|---|---|---|
|
||||
| `SetupDrawSnapshot`(`VulkanRenderer.h:948-1042`,40+ 字段) | Magma 一次 draw 必须钉住的**全部**东西的枚举 | `set_*` 组的并集 |
|
||||
| `DrawTextureSyncKeys` + `BackendTextureObject::IsDrawSyncClean`(`Managers.h:1003-1020`) | Espryt 纹理"是否还干净"的**全部**输入 | `set_sampler_views` + `create_sampler_view` + `set_texture_params` |
|
||||
| `ResolvedDrawBuffers`(`Managers.h:697-717`)/ `ResolvedVertexBindings`(`VulkanRenderer.h:1153-1218`) | 顶点输入的完整声明 | `bind_vertex_elements_state` + `set_vertex_buffers` + `set_index_buffer` |
|
||||
| `g_syncedRenderStateParameters`(`DirectGLES.cpp:1956`) | 渲染状态声明,**逐字节** | `create/bind_render_state` + `set_dynamic_state`(见 0.5 D-B1) |
|
||||
| `UnpackStagingBlock`(`Managers.cpp:4340-4390`,`{src, rowBytes, rows, slices, srcRowStride, srcSliceStride, offset}`) | Espryt 纹理上传的**带步长的源描述符**,已经存在 | `MGPSubData` 的 region 形状 |
|
||||
| `BufferBackendOps`(`BufferObject.h:76-120`,7 个 hook) | 已经是接口,且注释自称 "the `pipe_context` buffer-op analogue"(`:68`) | `resource_*` 全族 |
|
||||
|
||||
把这些结构的**输入集合**推过去,接口就按构造完整。gallium 是**目的地**(同名同形的词汇让形状可读、可迁移),不是**推导前提**。凡 gallium 的词汇与本仓库的证据冲突的地方,本文按证据走,并在 §4.6 逐条记名列出偏离与理由。
|
||||
|
||||
### 0.3 四条结构性推论(决定了后面每一节)
|
||||
|
||||
**推论 1 — 推送必须发生在 verb 时刻,不是 GL setter 时刻。** Blaze3D 每个 batch 都用 `glEnable/glDisable(GL_BLEND)` 包住,代码自己把它标成最热的路径(`DirectGLES.cpp:2029-2032`:`mc_state_toggle` 干的最热的事)。天真的 per-setter 推送会把每一次冗余开关变成一次接口调用加一次 server 侧 CSO 查表,**严格慢于今天**。正确形态是 gallium 的 `st_validate_state`。
|
||||
**v2 修订**:v1 把这条写成"只有资源 mutation 在 GL 调用时刻推送——这恰恰是 `BufferBackendOps` 今天的做法"。**这句话对 buffer 成立,对纹理不成立。** 实测:`glTexSubImage*` **根本不调 backend 表**——`MG_Impl/GLImpl/Texture/GL_Texture.cpp` 里只有 3 处 `MarkStorageDirtyRegion`,全部纹理上传由 Espryt 在 sync 时刻按**累积**区域做(`Managers.cpp:4274-4390`),那里才跑 `MipmapStorage` 的 96-rect 级联合并与 `summedArea*4 >= unionArea*3` 回退,并在 unpack ring 可用时**刻意把 rect 列表塌成一个 union box**(`:4386-4390`:`if (BufferImpl::UnpackRingAvailable()) dirtyRectCount = 0;`,注释记录 ~100 个精灵 rect 变成 ~100 个 Mali 作业,实测 **+6 ms/frame**)。若每次 `glTexSubImage` 发一条 `resource_subdata`,就精确复现了那个 ~100 作业的形状。**规则的正确措辞见 §5.1.1。**
|
||||
|
||||
**推论 2 — handle 就是身份,而且必须是稠密 slot。** 每个前端对象已经有一个永不复用的 `GetLifetimeId()`(`BufferObject.h:202-208`、`VertexArrayObject.h:110-120`、`FramebufferObject.h:151-158`、`ProgramObject.h:1620`、`TextureObject.h:83`、`SamplerObject.h:141`),它们存在的唯一理由是 GL name 会被 `IndexGenerator::Generate` 从 free list 尾部 LIFO 复用(`MG_Util/Miscellany/IndexGenerator.h:30-42`)、堆地址会被分配器复用。但**单调的 64 位 id 不能索引数组**——如果 wire handle 直接用 lifetimeId,server 侧仍然是一张哈希表,那就只是把指针键换成整数键,并没有删掉查表层。所以 wire handle 是 `{slot: Uint32, gen: Uint32}`,**slot 由 client 按 kind 稠密分配**,`gen` 在 slot 复用时 ++。lifetimeId 留在 client 侧作为 tracker 自己的身份,不过线。这一条才真正把 6 个 `StateBackendObjectRegistry` 哈希表和 13 个 Magma 身份键缓存变成**数组**。
|
||||
|
||||
**推论 3 — server 拥有 client 看不见、也永远不该被问的 generation。** 今天有 12 个纯 backend 侧的单调计数器,它们表达的是"**我自己**重新铸造了驱动对象",与任何前端版本无关:Espryt 的 `g_bufferMutationEpoch`(`Managers.h:397-441`)、`g_bufferBackendIdGeneration`(`:551`)、`g_attachmentBackendIdGeneration`(`:1298`)、`g_backendContextGeneration`;Magma 的 `m_textureImageEpoch`、`m_resourceEraseEpoch`、`m_renderbufferImageEpoch`、`m_sliceEpochCounter`、`m_cacheStructureEpoch`、`m_evictionEpoch`、`m_recordingGeneration`、`m_frameSerial`。本文把它们统称 `MGGen`,**它们永不上线**。"server 拥有自己的状态机"在工程上的确切含义就是这一条:client 绝不是"我的 server 侧状态是否新鲜"的唯一权威。
|
||||
|
||||
**推论 4(v2 新增)— dirty 位对值类组可以**轮询**,对对象类组必须**标记**。**
|
||||
v1 同时主张两件互斥的事:§5.2 说"dirty 位全部来自已有计数器,`MG_State` 零新增记账",§5.1/§10.2 说稳态是"一次 64 位 dirty word 测试"。对**值类**组(渲染状态、pack、patch、attrib 默认值)两者兼容——一个 `Uint16` 比较就是全部。对**对象类**组不兼容:`NEW_SAMPLER_VIEWS` 在 §5.2 里映射到 `GetContentVersion`/`GetShapeVersion`/`GetTextureParamsVersion`(**逐纹理**)加 `GetTextureBindGeneration()`/`GetSamplingResolutionGeneration()`,没有任何聚合能回答"有没有哪张已绑定纹理的内容动了"。这正是 Magma 不得不用**有损**的 `sampledContentSum`/`sampledParamsSum`(`VulkanRenderer.h:975-1000`)的原因。轮询版本 = 每次 validate 走查 touched 单元,那不是 O(1),而且是**新增的 client 侧工作**(backend 的 `ResolvedTextureBindingMemo` 今天恰好跳过它)。
|
||||
|
||||
**决定**:
|
||||
- **值类组**:沿用既有计数器,O(1) 比较,`MG_State` 零新增。
|
||||
- **对象类组**:在 `MG_State` 里**新增 5 个聚合世代计数器**,在既有的 choke point 上 bump,让 tracker 的快门是 O(1):
|
||||
- `TextureState::m_anyTextureContentGeneration`(`ITextureObject::MarkStorageDirtyRegion` / `BumpContentVersion` 里 ++)
|
||||
- `TextureState::m_anyTextureParamsGeneration`(`BumpTextureParamsVersion` 里 ++)
|
||||
- `BufferState::m_anyBufferChangeGeneration`(`BufferObject::BumpChangeSerial` 里 ++)
|
||||
- `VertexArrayState::m_anyVaoAttributeGeneration`(属性/绑定点 setter 里 ++)
|
||||
- `FramebufferState::m_anyAttachmentGeneration`(attachment setter 里 ++)
|
||||
合计约 **20 行**,全部落在既有的 bump 点上,**不是**枚举 181 个 GL 入口。快门为真时 tracker 才做 touched 前缀走查并重算集合 hash。
|
||||
- **完整性绊线**:把 `PLAN.md` 的 `gen_impl_mutation_surface.py` **改造**(而不是删除)成 `gen_pipe_dirty_surface.py`:它枚举 `MG_Impl/GLImpl/**` 里每一个会改变某组的 mutator,映射到必须 bump 的聚合世代,CI 上重生成 + `git diff --exit-code`,**未映射的 mutator 直接失败**。这是 B-R6 的第四层,也是对"reconciler 完整性只有测试绊线"这条历史结论的第二个答案。
|
||||
- §5.2 的措辞随之改为"**值类零新增记账;对象类新增 5 个聚合世代,换掉 tracker 的逐对象走查**"。§10.2 的稳态成本行同步改写(见 §10.2)。
|
||||
|
||||
### 0.4 与方案 A 的结论性对比(详表见 §3)
|
||||
|
||||
**方案 B 在架构、内存、长期价值上赢;方案 A 在"多快能拿到第一帧"上赢,而且赢得毫无悬念。**
|
||||
|
||||
方案 B 赢的四点,全部可核对:
|
||||
|
||||
1. **内存(v2 修订过的算术)。** `PLAN.md` 自己的 R14(第 1222 行)给 replica 预算 "合计可达 ~450MiB 新增":每个 <16MiB store 一份重复 `PipeResource`、每个纹理 level 一份重复 `MipmapStorage`、一整份 `GLContext` 对象图,叠在两侧都要付的传输段与 ring 之上。
|
||||
方案 B 的账(v1 的 "+50-60MiB" 漏算了它自己引入的两项,此处补全):
|
||||
|
||||
| 项 | 字节 | 说明 |
|
||||
|---|---|---|
|
||||
| 传输段 | **48.25 MiB** | `SEG_CMD` 8 + `SEG_STAGE` 32 + `SEG_REPLY` 8 + `SEG_EVENT` 0.25 |
|
||||
| `SEG_STAGE` 额外余量 | **+0~32 MiB** | 四类新字节(§8.2)实测后定;上限由 P0 计数器给 |
|
||||
| server 侧**索引宿主镜像**(**仅 split,仅 `kCapNeedsHostIndexBytes`**) | **0~64 MiB(默认上限)** | D-B7;只镜像曾被绑为 ELEMENT_ARRAY 的 buffer,由 subdata 流增量维护,零额外线上流量 |
|
||||
| 纹素保留 LRU | **默认 0** | `MOBILEGL_PIPE_TEXEL_RETAIN_MB` **默认改为 0**;只有实测拉取率非平凡才开(§7.5d) |
|
||||
| POD slot 记录 + CSO 缓存 | ~1-2 MiB | |
|
||||
| **典型(不开索引镜像)** | **≈ +50-60 MiB** | |
|
||||
| **最坏(镜像满 + stage 余量满)** | **≈ +145 MiB** | 仍是 replica 的 1/3 |
|
||||
|
||||
**诚实注记**:索引宿主镜像是方案 B 唯一的"数据副本",它是把 restart 重写与 multi-draw 分档**留在 server**(D-B7)所付的价钱。它只覆盖索引缓冲、有显式预算与计数器、且超预算时有回退路径(逐 draw 通过 `MGHostSpan` 发送,代价记账)。这与 replica 复制**全部** buffer 与**全部**纹素在量级上不是一回事。
|
||||
2. **拷贝。** `PLAN.md` §6.4 数出 `glBufferSubData` → store 在 split P1-4 是 **4 次**、P4.5 是 **3 次**,其中第 (3) 次是 `SEG_STAGE`→**replica** shadow。没有 replica 就没有这次拷贝:方案 B 是 **3 / 2**。而 `PLAN.md` 自己把 2 次称作"方案 B(激进,需额外设计)"(第 549 行),要求给 replica 的 `PipeResource` 加第三种 `AdoptedClientShadow` 模式并处理 server 侧写的 copy-on-write 升级,且把它推迟到 P6 由 Tracy 数据决定(开放问题 §17-5)。方案 B **按结构就在那个目标上**,并顺带关掉它自己的开放问题。
|
||||
3. **漂移面。** replica 是一份必须与 20k 行 `MG_State` **语义**长期锁步的手写状态模型,而它的守卫(生成的 `is_same_v`/`sizeof`/`offsetof` + `reflectionDigest`)只能看见**签名**漂移。`MipmapStorage` 的 96-rect 级联合并与 union-box 回退(`MipmapStorage.cpp:300-305`)、`VecRange1D` 的 7% gap 比、`PipeResource` 的模式切换、`BufferObject` 的 persistent-map 状态机——任何一处行为不一致都能编译通过、在多数内容上渲染正确,而这恰好是本项目已经实测出 **+6ms/frame** 悬崖的那块地方。方案 B 只有一份状态模型,这一类失效**不可表达**。
|
||||
4. **整块子系统消失而不是被移植。** `PLAN.md` §2(g) 的"第七个面"(MG_Impl 在 table 调用旁做的 `MG_State` mutation:`AccountTransformFeedbackPrimitives`、`EnsureGeneratedMipmapStorageAllocated`)连同 `MutationCoverage.def`、`ImplMutationSurface.inc`、`MG_Remote::Shared::` helper 族和风险 R1,在方案 B 里**不存在**——没有 replica 就不需要 replay。(**注意**:那个生成器本身**不删**,改造成 §0.3 推论 4 的 dirty-surface 生成器;replay 的义务消失,标记的义务出现,两者不是同一件事,v1 把它们混为一谈。)同样消失的还有:§5.6a 的纹理 ack 协议与 R6;§5.7 的 "server 自建 composite" 分支;§6.9 的 relink 档与整个阶段 P5(6 天);§12.2 里跨越 1494 个 `MG_Impl` 站点的 `pGLContext` shim(`inproc` 需要隔离的进程全局从 4 个降到 2 个)。
|
||||
|
||||
**`RecProgramLinkOp` 不是"不理想",是不可能。** `ProgramObject.h:11` include `ShaderObject.h`,后者 `:12` include `ShaderCompileTask.h`、`:146` 返回 `SharedPtr<glslang::TShader>`;`ProgramObject.h:14` 又拉进 `SpvcSession.h`(后者 include `spirv_reflect.h`)。**任何链接真 `ProgramObject` 的 server 就链接了整条编译链。** 所以方案 A 的两档 program 方案在方案 B 里塌成一档。
|
||||
**v2 修订(重要)**:v1 由此推出 `nm -D libMobileGLServer.so | grep glslang` 为空是"整个论点的强制执行点",但**没有注意到它自己的反射 payload 也住在同一个头文件里**:`TypeFacts`(`:44`)、`ResourceReflection`(`:76`)、`XfbVarying`(`:1146`)、`LinkArtifacts`(`:1210`)、`SpirvArtifacts`(`:1409`)全部声明在 `ProgramObject.h` 内。server 要**反序列化进**这些类型就必须 include 那个被门禁止的头。所以**新增一个前置阶段 P0.5**(§11):把这五个类型抽到独立的 `MG_State/GLState/ProgramState/ProgramArtifacts.h`,它不 include `ShaderObject.h`、不 include `SpvcSession.h`,更新 7 个 includer,并加一条 CI 断言"`ProgramArtifacts.h` 的传递 include 闭包里没有 glslang / SPIRV-Cross / spirv_reflect 头"。**没有这一步,P7 的验收判据不可达。**
|
||||
|
||||
方案 A 赢的一点,也毫无悬念:
|
||||
|
||||
- **到首个跨进程帧的时间。** `PLAN.md` 的阶段天数逐项相加恰好是 **77 天**,其中 **P1b 出口(≈第 15 天)就是首个跨进程帧**,因为它一行 backend 代码都不用改。方案 B 最早的 `inproc` IPC 帧在第 ~95 天,最早的**跨进程**帧在第 ~100 天,且那一帧是**缩减路径**(emulation 在 P8 之前于 split 模式下直接 Fatal),全功能要等 P8(第 ~139 天)。总估时 **261-329 人天**(含 IPC;不含 CTS 周转,见 §11.5)。
|
||||
**v2 修订**:v1 报的 "200-260 天 / 第 64 天 inproc 帧" 与它自己的 §6.4/§6.5 逐子系统表**互相矛盾**(例如 P3a 给 12 天,而它的三行子系统合计 22-29 天,等于"再基线检查点"按构造必然触发)。§11.5 已按逐行求和重建,并公布算术。
|
||||
|
||||
**如果目标是"这个季度拿到一个能跑的拆分",选方案 A。如果目标是用户实际提出的那个——"backend server 拥有自己的状态机并暴露统一的、gallium 式的接口把前后端解耦"——方案 A 在任何价格下都不交付它**:它用复制前端来回答耦合,而不是用定义契约来回答耦合,而且那份复制的维护成本是**永久**的;方案 B 的成本是**一次性**的,且在第一个字节过 socket 之前就已经把 monolith 变好(净删除 ~370 行 per-draw 失效发现机制、让复用地址 ABA 一类失效不可表达、删掉一个排序 hazard、删掉一处分层倒置、修掉两个潜伏 bug、暴露一个死能力)。
|
||||
|
||||
### 0.5 八个必须先记下来的具体决定(这些是评审里争议最大的点)
|
||||
|
||||
**D-B1(v2 重写):渲染状态用"整块 blob"过线,但 CSO 的**身份**只取 pipeline 相关子集,动态状态单独走。**
|
||||
|
||||
v1 写的是"整块 blob + CSO handle,绝不拆成 blend/depth-stencil/rasterizer 三个 CSO",理由全部成立且保留:`RenderStateParameters`(`RenderState.h:222-370`)是平凡可复制 POD,Espryt 在 `DirectGLES.cpp:2035` 亲自 `static_assert(std::is_trivially_copyable_v<...>)`,紧接着做 head/blend/tail **三段 memcmp**(`:2038-2047`);`RenderState.h:359-368` 白纸黑字写着 `ScissorBoxWrittenMask` 与 `ClipDistanceEnabledMask` 是**故意**摆在 tail 段里,好让那次 span memcmp 抓到它们;**字段顺序是承重的**;拆成三个 CSO 要手工维护一张 ~150 字段划分表且没有完整性绊线。
|
||||
|
||||
**但 v1 同时犯了一个内部矛盾**:它一边在 D3 里说"CSO 边界跟 Vulkan 动态状态走:viewport、scissor、depth range、blend color、line width、depth bias、stencil ref/write mask 是 `set_*` 而非 CSO 字段",一边把 CSO 的**内容寻址键**定义为**整块**的三段 xxHash。两者不能同真:整块内容寻址意味着 `glViewport`/`glScissor`/`glBlendColor`/`glClearColor`/`glLineWidth`/`glStencilMask`/`glPolygonOffset` 每一次都产生不同的 hash、不同的 CSO handle,于是 (a) 64 项 LRU 在 Iris 光影与阴影级联下颠簸,(b) 每次未命中重发 ~1.2KB,(c) 新 handle 冲掉 server 侧按 CSO 缓存的 pipeline hash——**正是 `RenderState.h:519-528` 记录的那次回归**("共用一个计数器让 `glViewport` 把下一个 draw 从 pipeline memo **和** draw 快路径上打下来")。实测确认:`RenderState.cpp` 里 viewport/scissor/line-width 一族的 setter 只做 `++m_version`,`SET_CAPABILITY`(`:312`)与 pipeline 相关 setter 才做 `BumpVersions()`。
|
||||
|
||||
**最终形态**:
|
||||
|
||||
```
|
||||
create_render_state(cso, MGPBlobRef pipelineSubsetChunks) // 只带 pipeline 子集的字节段
|
||||
bind_render_state(cso, Uint16 version, Uint16 pipelineVersion) // 稳态 12 B
|
||||
set_dynamic_state(MGPBlobRef dynamicChunks, Uint16 version) // 只带动态子集的变化段
|
||||
```
|
||||
|
||||
- server 每 context 持有**一份** working `RenderStateParameters`(~1.2KB)。`bind_render_state` 把 CSO 的 chunk 散射进去,`set_dynamic_state` 把动态 chunk 散射进去。**Espryt 的 `SyncRenderState` 拿到的仍然是一个 `const RenderStateParameters&`,693 行函数体与三段 memcmp 一行不动。**
|
||||
- Magma 的 pipeline memo 键是 `cso.slot`——**`glViewport` 不再冲掉它**;动态尾巴仍按 `set_dynamic_state` 的 version 走 `ApplyDynamicDrawStateTail` 今天的两级门。
|
||||
- **划分只写在一个地方**:`MGPipeComputePipelineSubsetHash(const RenderStateParameters&)` 与它的 chunk 表,**从 `VulkanRenderer.cpp:4826-4906` 原样搬进 `MG_Pipe/`**,client 与两个 backend 共用同一个函数。这样"哪些字段属于 pipeline"不再有第二份定义。
|
||||
- **完整性绊线(这是 v1 拒绝三 CSO 时点名要求、却没给自己的那一条)**:G7 生成一个 `MG_Test`,遍历 `MG_State::GLState::RenderState` 的**每一个 public setter**,用一个不同的值调用它,断言 `pipelineSubsetHash 变了 ⟺ m_pipelineStateVersion 变了`。新加一个 setter 若 `BumpVersions()` 却不在 chunk 表里,这个测试立刻红。
|
||||
- **两个版本计数器都过线**(`RenderState.h:522` / `:529`),职责不变。
|
||||
- **两套 span 划分并存,互不干扰**:Espryt 的 head/blend/tail 三段是**驱动侧增量**的划分(不动);pipeline/dynamic 是**线上与 CSO 身份**的划分(新增)。两者都有各自的绊线。文档必须写清楚它们不是同一件事。
|
||||
- **热路径成本(诚实版)**:`m_pipelineStateVersion` 未动 → 复用上一个 CSO handle,**零哈希**;动了 → 哈希 pipeline 子集(~25-30 字,正是 Magma 今天已经在算的那个)+ 一次 map 探测。Blaze3D 的 enable/disable 交替会命中两个交替的 CSO,不重发 blob。对比今天:Espryt 1.2KB×3 段 memcmp + Magma ~30 字哈希。**净变便宜,但差距不大**,所以 P2 必须带一个**专门的 enable/draw/disable/draw 微基准**(MC batch 速率)。
|
||||
|
||||
**D-B2:`create_shader_state` 不返回一个"做完了的"对象。** backend program 还依赖 8 个额外输入(`DirectGLES.cpp:2766-2818`:draw FBO 的 snorm/unorm fallback clamp mask、由 draw-buffer 数组推出的 fragColor 广播数、storage-block 绑定签名、atomic counter 绑定集、**活的** `glBindImageTexture` 格式、patch 参数;Magma 另加 FragCoord-Y-flip 的 default-FB 高度和 XFB 布局)。接口**明说规则**:`create_shader_state` 发布**制品**,server 在 **verb 时刻**从它已经被推送过的状态**惰性特化**。这正是两个 backend 今天的做法。
|
||||
|
||||
**D-B3(v2 重写):真正承重的不是"framebuffer 第一",而是"verb 之前状态齐全 + verb 处惰性特化"。**
|
||||
v1 把 §5.3 的编号顺序(1 framebuffer → 2 program → 3 images → 4 render state → 5 vertex)写成契约,并说这是退役 `ImageUnitFormatsStillMatch`(`Managers.cpp:6545-6573`,注释明说"不可表达为单调版本")与 fragColor 重推导 workaround(`DirectGLES.cpp:2712-2732`)的机制。**但它自己把 images 排在 program 之后**——所以退役这两条的其实是 **D-B2 的惰性特化**,不是调用顺序。
|
||||
**规范条款改为**:
|
||||
> 一条 verb 的全部 `set_*`/`bind_*` 必须在该 verb 之前完成;server 在 verb 处、从它此刻持有的全部已推送状态特化 shader 与 pipeline。除"资源 create 先于对它的 bind"外,`set_*` 之间**没有**顺序要求。
|
||||
|
||||
§5.3 的编号列表降级为**推荐实现顺序**(便于 tracker 的代码组织与 dirty 位遍历),不再是正确性契约。收益不变:`DirectGLES.cpp:2712-2732` 的 workaround 与 `g_broadcastMemo*` 照删,因为特化发生在 verb 处、那时 FBO 状态一定已在。
|
||||
|
||||
**D-B4:AcquirePersistentMap 在整个改造期一动不动。** 它是**永久的地址空间捐赠**而不是 gallium 的 scoped `transfer_map`:返回一个 host-visible coherent 指针,成为该 buffer 的唯一真相源(`BufferObject.h:102-118`),由 `PipeResource::AdoptPersistentMap`(`PipeResource.h:115`)采纳、经 `MappedData()` 交给应用、≥16MiB 可变 store 由 `TryAdoptLargeStorage` 自动走到(`:226-228`)。实测代价是 MC 26.3 的 p99 163→21ms、40→115fps、省 ~400MB。**它今天就已经是一个"返回指针的显式调用",因此原样穿过 monolith 改造;只有 IPC 那一步才会打破它。** 改造期不碰,IPC 期按 `PLAN.md` §6.8 的三档 POST 探针决定,spike B 第一周给答案。绝不允许一个平台未知数挡住 260 天的接口工作。
|
||||
**v2 补注**:`map_persistent` 的 round trip 是**每次存储定义(respecify)一次**,不是"每 store 生命周期一次"——`TryAdoptLargeStorage` 在存储定义时触发,一个反复扩容的 arena 会付 N 次。`StorageBufferRegrowScenario` 必须发布 `map-persistent-roundtrips` 计数。
|
||||
|
||||
**D-B5(v2 修订):monolith 字节一致门按构造死亡,这是本方案的成本;但语义门必须活过 P13。**
|
||||
`PLAN.md` §12 第 4 层(`nm --defined-only` + 剥调试信息后 `.text` size 相等)在方案 B 里不成立——**不存在任何配置能让旧字节回来**。替换是**五部分门**(§10.3),其中第 ② 部分(每 draw 逐字段的 pushed-vs-snapshot 影子比对)在语义上**严格强于**任何符号 diff。
|
||||
**但 v1 的 P13 删掉 `SnapshotFromGLContext()`,而那正是 verify 的参照物来源**——删完之后 verify 无物可比,设计从此没有语义绊线。**修正**:
|
||||
- `SnapshotFromGLContext()` 与它需要的 `MG_State` include **在 P13 之后继续存在,但整体包在 `#if MOBILEGL_PIPE_VERIFY` 里**;verify 构建**永不出货**。
|
||||
- 纯度门(`grep -c 'pGLContext' MG_Backend/` == 0、include 白名单、`nm --undefined-only`)**只跑非 verify 构建**,这一点写进门的定义。
|
||||
- 另外在 P13 交付 §10.4-9 已经勾勒的**录制-金标**模式:把 `MG_Test` 的 mock backend 变成 MGPipe recorder,在一组 fixture 上录下每 draw 的已推送状态,后续构建对比录像。它不依赖 `MG_State`,所以是长期可用的语义门,也是开放问题 11 的答案。
|
||||
|
||||
**D-B6:方案 B 引入一个方案 A 没有的新停顿类:server 发起的纹理重铸拉取。** server 不保留纹素字节,所以 `RequireImageBindableStorage` 的 re-dirty(`Managers.cpp:2813`)、整格式再生(`:3950-4195`)、view 源重铸(`:3616-3707`)都必须回头向 client 要数据。**三条缓解同时上,不是三选一**,加一个专门的门、一个逐 trace 用例发布的计数器,**以及一个显式的"答不出来"终止符**(§7.5)——因为存在 client **没有**字节可发的 level(纯渲染产生、`CanMirrorCopyImageShadow` 拒绝的 copy 目标、GPU 生成的 mip),没有终止符 apply 线程会永久 park。上一轮 thin-server 设计正是因为把这条一笔带过而被判死。
|
||||
|
||||
**D-B7(v2 新增):restart 重写与 multi-draw 分档**留在 server**,split 下由一份**索引宿主镜像**喂养。**
|
||||
v1 的 §5.8 把这两条按 `!kCapPrimitiveRestart` / `!kCapMultiDraw` 下放到 client,而 §4.5.7 的表又写"monolith:`ptr` 指向 shadow(server 做)"——**两处互相矛盾**。更根本的是这个划分不可表达:
|
||||
- `ResolveTierForBatch`(`MultiDraw.cpp:282-320`)**逐 batch**在五档里选,输入包含 `programReadsDrawID`——**转译出的 ESSL 的性质,只存在于 server**——以及 `perSubDrawBaseVertex`、`hasIndexBuffer`、`arbitraryRestart`,并在 `kMaxFlattenedIndices`(`:72`,1<<24)与 `kMaxComputeFlattenedIndices`(`:82`)上做容量判定。自动阶梯是 Ext → BaseVertex → MultiIndirect → Indirect → DrawElements(`:241-243`),CPU 展平的 `DrawElements` 档是**回退**,client 无法预判。
|
||||
- restart 重写**两个 backend 都做**(`DirectGLES.cpp:4283/4377`、`VulkanRenderer.cpp:3990/4089/4161`),所以 `kCapPrimitiveRestart` 恒为 false,"cap 门控"没有门可控。
|
||||
|
||||
**决定**:`kCapPrimitiveRestart` / `kCapPrimitiveRestartFixedIndex` / `kCapMultiDraw` / `kCapMultiDrawIndirect` / `kCapMultiDrawIndirectCount` 作为**归属开关**删除。规则改为一句话:**multi-draw 分档与 restart 重写永远由 server 拥有;client 在 caps 说 server 可能需要时提供索引字节。** 提供方式不是逐 draw 拷贝,而是:
|
||||
|
||||
> **`kCapNeedsHostIndexBytes` 开启时,server 为"曾被绑为 `GL_ELEMENT_ARRAY_BUFFER` 的 buffer"维护一份宿主镜像**,由它本来就要收的 `resource_subdata` / `resource_respecify` 流**增量**维护,**零额外线上流量、零 round trip**。预算 `MOBILEGL_PIPE_INDEX_MIRROR_MB`(默认 64),逐帧计数;超预算时该 buffer 退化为逐 draw 通过 `MGHostSpan` 传送并计入 `index-bytes-shipped` 计数器。
|
||||
|
||||
好处:monolith 行为**零变化**(不搬代码、不改诊断落在哪个线程 → 开放问题 12 关闭)、split 下 restart/multidraw 零 round trip、`kMaxRestartRewriteBytes = 1<<26`(64 MiB,`DirectGLES.cpp:4218`)这种单条记录不再需要塞进 32 MiB 的 `SEG_STAGE`。代价是那份镜像的内存,已计入 §0.4-1。
|
||||
|
||||
**D-B8(v2 新增):per-draw 的**具名 uniform block 字节**必须有自己的载体。**
|
||||
v1 §7.2 断言 20 处 `SyncPersistentMappedRange` "作为反向调用彻底消失,因为紧邻它们的 CPU 读全部搬到了 client"。**有一处反例**:`UniformManager::ResolveUniformBufferPayload` 在 `UniformManager.cpp:2022` 调 `SyncPersistentMappedRange()`,随后在 `:2052` 读 `bufferObject->MappedData() + rangeStart`(不足时在 `:2053-2057` 零填充),把具名 UBO 块打进 **Magma 自己的 UBO ring**——消费者在 server,搬不走。而 §4.4.3 的 `set_shader_buffers` 只有 `V` 标志,没有 `kHasBlob`/`MGHostSpan`;`set_global_constants`(D6)只覆盖**默认** uniform block。**结果是每个带具名 UBO 的 Iris/MC draw 都有一条没被承载的数据依赖。**
|
||||
**决定**:`set_shader_buffers(cls == Uniform, ...)` 的每个 range 增加可选的 `MGHostSpan payload`(`kHostSpan` 标志),由 `kCapNeedsHostUboBytes` 门控(Espryt 不需要——它把具名 UBO 直接绑给驱动)。字节量进 `SEG_STAGE` 的尺寸表(§8.2)与 P0 计数器(`stage-ubo-named`)。**在 P0 计数器给出逐帧字节量之前,不冻结这个 payload 的形状。** 备选(不在本计划内、需独立 `dev` PR + Iris 性能门):让 Magma 直接描述符绑定常驻 `VkBuffer` 的 range,不再 ring-pack。
|
||||
|
||||
### 0.6 推荐
|
||||
|
||||
**推荐执行方案 B,但按下面这个对冲路径起步,在第 42 天做一次真正的 GO/NO-GO:**
|
||||
|
||||
先原样跑 `PLAN.md` 的 P0(卫生、传输骨架、两个 spike,尤其是 **`TracyPlot` 逐帧字节计数器**——树里今天完全没有 per-frame 字节或调用度量,`MG_Util/Metrics` 只是格式算术,Tracy 只有 zone 无 plot),然后跑本文的 **P0.5 + P1 + P2**。
|
||||
|
||||
- **第 ~25 天(P1 出口)— 机制里程碑,零产品风险**:`MOBILEGL_PIPE_VERIFY` 影子比对 harness 在全部 40 个 trace 用例与 367 个集成测试上逐 draw 逐字段证明"推送等价于拉取"。这一天**不**是 GO/NO-GO——它只证明机制,不给性能数字。
|
||||
- **第 ~42 天(P2 出口)— GO/NO-GO**。
|
||||
|
||||
**v2 修订:GO/NO-GO 的口径必须包含一片 Track H,否则它测的不是它要决定的事。**
|
||||
v1 把 GO/NO-GO 放在"只迁了渲染状态"的时点,而渲染状态恰好是推送**收益最小、v1 的 CSO 设计开销最大**的那个面:Espryt 已经有逐字节镜像 + 单个 `Uint16` 早退(`DirectGLES.cpp:2016-2018`),Magma 已经按 `GetPipelineStateVersion()` 缓存哈希(`:4982-4993`)并双门控动态尾巴(`:5888-5893`)。绿灯不能证明它要担保的事(Track H 的 handle 化在 260 天里划得来),红灯更可能是在指控 CSO 设计而不是推送模型。
|
||||
**因此 P2 的范围扩大为**:渲染状态 CSO(双后端)**+ 最便宜的两片 Track H**——Espryt 的 0b handle 基建(`SlotAllocator` + 6 个 registry 变 slot 数组 + 删 `TwinLookupMemo`×3/`OwnerEquals`)与 Magma 的子系统 4(`VertexInputStateFactory`/`VaoDrawMemo` 重键,§6.5 自评"低(纯结构性收益)")。第 42 天你手上会有:
|
||||
|
||||
- 逐 draw 逐字段的语义等价证明(P1 交付);
|
||||
- 两个 backend 上都已推送的渲染状态,`SyncRenderState` 的 693 行函数体一行未动;
|
||||
- **Track H 的实测单位成本**(两片,两个 backend 各一);
|
||||
- 两台设备上 reboot-clean 配对的**逐线程 CPU 时间**增量,含一个专门的 Blaze3D blend-toggle 微基准;
|
||||
- 一个**负面对照**:关掉 CSO 内容寻址(`MOBILEGL_PIPE_PUSH` 的一个子位)重跑,把"推送更慢"与"CSO 设计更慢"分开。
|
||||
|
||||
**退回成本(诚实版)**:P0(9-11 天)是 `PLAN.md` 共有的;P0.5 的头文件抽取对方案 A 也有用(它同样想序列化反射);真正只为方案 B 花的是 P1 + P2 ≈ **27-37 天**。v1 说"只损失 16 天"是按一个与它自己的子系统表矛盾的排期算的。**若第 42 天的 CPU 数字为负、或 Track H 的单位成本比估计高 50% 以上,退回方案 A 损失 27-37 天。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
1. **定义并落地一份显式的前后端接口 MGPipe**:句柄寻址、只推不拉、gallium 形状,client 与 server 都只依赖它。
|
||||
2. **backend 拥有自己的状态机**:`MG_Backend` 在 MGPipe 构建(非 verify)下**不含** `MG_State::pGLContext`,`MG_State` include 收缩到一张共享**值**头文件白名单,server 产物的 `nm --undefined-only` 里没有 `MG_State::GLState::` 符号、没有 glslang 符号。
|
||||
3. **前后端跑在两个进程**,通过 IPC 通信;client 把状态 reconcile 成推送调用、序列化(FlatBuffers)后发送;server 更新自身状态并调 backend API。
|
||||
4. **稳态帧零 round trip**(回读 / 阻塞式 query / sync wait / present credit / 分配类错误 ack / 纹理拉取之外,且后者的次数必须**实测发布**而非声称为零)。
|
||||
5. 两半尽可能互相异步;client 至多领先 server 1 个 present(默认,延迟叠加分析继承 `PLAN.md` §9.1)。
|
||||
6. 平台特定代码最小化并集中在 `MG_Remote/Transport/` 与 `MG_Remote/Client/Surface*`(继承 `PLAN.md` §11)。
|
||||
7. **单进程 Monolith 保持功能与性能不回归**,由五部分门机械验证(§10.3)。注意这**不是**方案 A 的"字节级不变"——见 D-B5。
|
||||
8. 所有验收门用**现有测试**:`ctest -L unit`(428 个 `TEST(`)/ `-L integration-gpu`(367 个 `TEST_F`,75 个场景文件)/ `tools/trace_replay`(40 个用例,默认 SSIM ≥ 0.99)/ `tools/cts` / `tools/device_bench`。
|
||||
9. **接口本身是可独立交付的产物**:即使 IPC 永不上线,`inproc`(同进程第二个 apply 线程)就是 monolith 的渲染线程交付物,且是本项目手上最大的单一 CPU 杠杆。
|
||||
|
||||
### 1.2 非目标
|
||||
|
||||
- **share-group sessioning 重构。** 与 `PLAN.md` 一致:`eglCreateContext` 的 `shareCtx` 只在 `EGLState/Core.cpp:632` 被校验、`:640` 被存进 `EGLContextState::SharedContext`,**全代码库无人读取**;`pGLContext` 是唯一进程全局(`GLState/Core.cpp:20, 1487`)。v1 = 一条 flow、一个扁平 handle 空间。但**接口头文件从第一天就把 `MGPipeScreen` 与 `MGPipeContext` 分开**(§4.3)。`c7c9e346`/`29d721ef` 那套整体丢弃(理由见 `PLAN.md` §14 DROP)。
|
||||
- **BFA strict-C-ABI backend 插件 / UtilRuntime C-ABI 化**(同 `PLAN.md`)。
|
||||
- **macOS 拆分**(同 `PLAN.md`:`CAMetalLayer` 无公开跨进程表示 → monolith only)。
|
||||
- **Windows 窗口拆分**(同 `PLAN.md`:headless/pbuffer only)。
|
||||
- **把 emulation 层重写到 client。** 只有**三**个"读前端字节的纯 CPU 变换"下放到 client(v1 说五个,D-B7 收回了两个):client 顶点数组的范围计算、最大索引扫描、`*IndirectCount` 的计数解析。viewport-array 回放、**multi-draw 分档**、**primitive-restart 重写**、fp64 顶点转换、image-bindable 存储加宽等**全部留在 server 作为 lowering pass**,接口只负责把它们的输入表达清楚(含 D-B7 的索引宿主镜像)。
|
||||
- **在 P13 之前删除 pull 路径。** 旧路径一直编译在里面,任何提交都能用一个 env 位 A/B(**但要注意 §6.7 说明的 A/B 口径在 stage C 之后会收窄**)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状:边界为什么不清楚
|
||||
|
||||
### 2.1 今天的边界有七个面(沿用 `PLAN.md` §2 的分面,数字按工作树复核)
|
||||
|
||||
**(a) `GLFunctionsTable`** — `MG_Backend/BackendObject.h:117-278`。**实测 67 个函数指针 + 1 个 `Bool` 能力位**(`PrefersCpuXfbPrimitiveAccounting`),`GlobalBackendFunctionsTable`(`:279-285`)再加 `Present` 与 `SetSwapInterval` → **全体 69 个函数指针**。
|
||||
MG_Impl 侧 **~93** 个 `gBackendFunctionsTable.GL.*` 调用点,覆盖 **70 个不同表项**。**null 项已经表示"未实现,前端回退"**,写进头注释(`:212-215` 的 sync 族、`:265-269` 的 XFB 跨度),且 DirectVulkan 确实留空 8 项而 Espryt 填满。三项是错位的前端查询:`GetIntegeri_v`/`GetInteger64i_v`(`:195-196`,`DirectGLES.cpp:7264-7386` 有 15 个 case 完全不碰 GL)、`GetProgramiv`(`:197`)。
|
||||
|
||||
**这 70 个表项里只有约 22 个是 draw/dispatch**(20 个 draw 族 + `DispatchCompute`/`DispatchComputeIndirect`)。**其余 ~48 个是 clear(9)、blit(2)、copy(3)、`GenerateMipmap`、回读(4)、barrier(2)、XFB 跨度(6)、query/sync(~19)、`BindImageTexture`、`PatchParameteri`、`ShaderStorageBlockBinding` 等**,而其中很多**自己就读 `pGLContext`**(例:`UpdateTextureBindingAtTarget` 在 `DirectGLES.cpp:6051-6052` 读 `GetActiveTextureUnit()` + `GetTextureUnitObject()`,被 `CopyTexImage2D`/`CopyTexSubImage2D` 路径命中;`PackStateFromContext` 在 `:6129` 读 `GetPixelStoreParameters(false)`;`Clear` 在 `:4106` 读 `GetRenderStateParameters().ClearColor`、`:4165` 读 draw FBO;`BlitFramebuffer` 在 `:5988-5989` 读两个 FBO slot)。代码自己说明了这一点:`DirectGLES.cpp:1501-1502` 写着无参 `CaptureDrawTextureSyncKeys` 包装存在是"for every non-draw call site (Clear, readbacks)"。
|
||||
**这是 v1 的一个实质性缺口**:它只在 `PrepareForDraw` 与 `SetupDraw` 两处填快照。修正见 §6.2.1 与 §11 P1。
|
||||
|
||||
**(b) `BackendObject` 虚函数** — `BackendObject.h:543-568`,MG_Impl 侧 **40** 个 `pActiveBackendObject->`(其中 35 个是 `GetDynamicParameters()`)。`InitCapabilities()` 懒执行在第一次成功的 `eglMakeCurrent` 内部(`BackendObject.cpp:341-347`),且每次 surface 变更重新武装(`:301`)。
|
||||
|
||||
**(c) `BufferBackendOps`** — `BufferObject.h:76-120`,**7 个 hook**,注册入口 `:124`。Espryt 注册 7/7(`Managers.cpp:1338-1346`),Magma 注册 6/7(**故意**不注册 `ResidentSubData`,`VkBufferManager.cpp:104-111`)。**这个面已经是 MGPipe 的三分之一,且注释自称 `pipe_context` 类比。**
|
||||
**注意它只覆盖 buffer。** 纹理**没有**对应的 GL 调用时刻分发面(推论 1 的 v2 修订)。
|
||||
|
||||
**(d) 状态拉取** — `MG_State::pGLContext->` 在 `MG_Backend` 里 **293 次出现 / 290 行**(DirectGLES 124;DirectVulkan 169),**外加 58 行非箭头用法**(见 2.4)。此外还有约 1997 个前端对象 getter 调用点、186 个不同 getter(上界统计)。
|
||||
|
||||
**(e) backend → frontend 写回** — 逐名 grep 实测 **95 个调用点 / 17 个方法**:`SyncPersistentMappedRange` 20、`MarkStorageDirty` 18、`AllocateStorage` 8、`WritebackFromBackend` 8、`SetInternalFormat` 7、`SyncGpuWrites` 6、`MarkGpuWritten` 6、`RecordError` 6、`SetBackendResource` 4、`EnsureGpuResidentStorage` 3、`SetBackendHashMemo` 2、`InvalidateCompileEnv` 2、`SetBackendStateMemo` 1、`SetBackendAuxMemo` 1、`UpdateMipmapSubData` 1、`TruncateMipmapLevels` 1、`SetSamples` 1。
|
||||
|
||||
**(f) backend 反向进 MG_Impl** — 恰好 6 处:`DirectGLES.cpp:1917, 2838, 2867, 9675`(`pDefaultFramebufferInfo` 身份比较)、`SwapchainObject.cpp:276`(**写**)、`VulkanRenderer.cpp:10700`(`CopyTextureImageToClientOrPBO_State`,一处真正的分层倒置)。
|
||||
|
||||
**(g) MG_Impl 在 table 调用旁做的 `MG_State` mutation** — `EnsureGeneratedMipmapStorageAllocated`(`GL_Texture.cpp:501-544`,调用点 `:6698, 6708`)与 `AccountTransformFeedbackPrimitives`(`GL_Drawing.cpp:172`,调用点 `:1133, 1141, 1195, 1668`)。**在方案 B 里这个面的 replay 义务不存在**;但**标记义务**出现(推论 4),由改造后的 dirty-surface 生成器覆盖。
|
||||
|
||||
**(h) 工作树污染** — `DirectGLES.cpp:290-303`/`:640-663` 与 `Managers.cpp:875-877` 的未提交 per-draw `fprintf(stderr)`(后者在 `pendingMutex` 临界区内)。**P0 第一件事就是清掉。**
|
||||
|
||||
### 2.2 backend 已有的状态机清单(这就是"server 已经是薄服务端"的实证)
|
||||
|
||||
**DirectGLES(Espryt)**
|
||||
- 6 个 twin registry,全部是 `StateBackendObjectRegistry<StateObject*, {BackendPtr, weak_ptr}>`(模板 `Managers.h:270-390`;实例 `:806`(VAO) `:1123`(Texture) `:1216`(FBO) `:1731`(Program) `:1830`(Sampler) `:1858`(Renderbuffer)),键是**前端裸堆地址**,用同址 `weak_ptr` 防 ABA,GC 阈值 `kGCInterval=1024` draw / `kCreationGCInterval=64` 次创建。
|
||||
- 三条 persistent-mapped bump ring(UBO `Managers.h:591-637`、纹理 unpack PBO `:639-671`、buffer upload `:673-…`),各自 4MiB 起 → 64MiB 上限;buffer pool 预算 `kMaxPoolBytes = 64MiB`、单 buffer 上限 8MiB(`Managers.cpp:564-565`)。
|
||||
- 每对象 twin:`GLESBufferResource`(`Managers.h:443-497`)、`BackendVertexArrayObject`(`:675-803`)、`BackendTextureObject`(`:944-1119`)、`BackendFramebufferObject`(`:1140-1213`)、`BackendProgramObjectImpl`(`:1473-1725`)、`BackendSamplerObject`(`:1808-1824`)、`BackendRenderbufferObject`(`:1838-1855`)。
|
||||
- 完整的渲染状态**值镜像** `g_syncedRenderStateParameters`(`DirectGLES.cpp:1956`)+ 单个 `Uint16` 早退门(`:2016-2018`)+ 三段 memcmp(`:2038-2047`)。
|
||||
- 驱动绑定影子、三个共享 scratch FBO 及其驱动侧 attachment 影子、`PackState`。
|
||||
- **`UnpackStagingBlock`**(`Managers.cpp:4340-4390`)——一个已经存在的**带步长源描述符**,`MGPSubData` 的 region 直接照抄它的形状(§4.5.6)。
|
||||
|
||||
**DirectVulkan(Magma)**
|
||||
- `VulkanRenderer`:`PipelineMemoEntry m_pipelineMemo[8]`、`SetupDrawSnapshot m_setupDrawSnapshots[4]`(40+ 字段)、`VaoDrawMemo m_vaoDrawMemoTable[2048]`、`ResolvedVertexBindings`、`m_convertedVertexStreams`、`DynamicStateShadow g_dynamicStateShadow`、采样集/LOD/BaseVertex 三个 memo、11 个 per-draw scratch vector。
|
||||
- 5 个 manager(`VkBufferManager`、`VkTextureManager` 3504 行、`VkRenderPassManager`、`VkSamplerManager`、`VkClearManager`)、3 个 factory、`UniformManager`、`FrameContext`、`SwapchainObject`。
|
||||
|
||||
**结论:两个 backend 都已经是完整的、贴着各自 API 的状态机。** 上面**没有一样东西需要在方案 B 里删除或重写**——需要改的只是它们**怎么知道**这些事实,以及它们的 memo **用什么做键**。
|
||||
|
||||
### 2.3 pull 模型的读点分类:A/B/C/D/E 五类
|
||||
|
||||
| 类 | 含义 | DirectGLES | DirectVulkan | 合计 | 占比 |
|
||||
|---|---|---|---|---|---|
|
||||
| **A** | 只为**探测变化** | ~21 | ~14 | **~35** | 12% |
|
||||
| **B** | **翻译输入**,backend 无镜像 | ~88 | ~128 | **~216** | 74% |
|
||||
| **C** | 瞬时 draw 参数 | ~2 | ~2 | ~4 | 1% |
|
||||
| **D** | **身份 / 缓存键**(与 B 重叠计) | ~24 | ~24 | ~48 | — |
|
||||
| **E** | 数据字节(经 `pGLContext` 本身) | 1 | 2 | 3 | 1% |
|
||||
| **写** | `RecordError` 6 + `InvalidateCompileEnv` 2 | 2 | 6 | 8 | 3% |
|
||||
|
||||
**这张表否定了两种直觉方案:**
|
||||
|
||||
- **"bump 一个版本让 server 自己拉"行不通。** 只有 12% 是 A 类。74% 是 B 类:值本身必须过去。
|
||||
- **两个 backend 想要的推送粒度不同,但可以被同一个接口满足。** Espryt 持有逐字节镜像;Magma **没有任何镜像**,它按 `GetPipelineStateVersion()` 缓存一个**值哈希**(`VulkanRenderer.cpp:4982-4993`),然后在 payload 构建器里把 ~40 个字段再读一遍(`:5155-5200`,**仅在 pipeline memo 未命中时**)。整块 blob 同时满足两者。
|
||||
|
||||
另一个角度:1997 个前端 getter 站点里,**89 个是纯版本/序号读(A 类)**——推送模型里根本不过线;**72 个是数据字节读(E 类)**,全部在 §5.7/§5.8 处理;**38 个是 `GetLifetimeId()` 身份读(D 类)**,全部变成 handle。
|
||||
|
||||
### 2.3.1 v2 新增:把"每 draw 成本"用**动态**口径说清楚
|
||||
|
||||
v1 的 §10.2 把今天的每 draw 状态获取写成 "Espryt 124 / Magma 169 次 accessor 调用"。**124/169 是静态调用点数(§2.1(d) 的定义),不是动态每 draw 调用数。** 树里每一处都已经被 memo 门控:
|
||||
|
||||
| 路径 | 稳态实际做的事 |
|
||||
|---|---|
|
||||
| `SyncRenderState`(`DirectGLES.cpp:2003`) | `:2007` 读一个 `Uint16`,`:2016-2018` 相等即 `return`。**三段 memcmp 只在版本移动后跑。** |
|
||||
| `SyncNeccessaryTextures`(`:1520`) | 6 值键比较 + `PairingsIntact` + 每条目一次 `IsDrawSyncClean` 字比较;单元走查只在未命中时跑 |
|
||||
| `CurrentUnitBindingsEpoch`(`:1418-1436`) | 三值快门;owner 走查只在 bind generation 移动后跑 |
|
||||
| `TrySetupDrawFastPath`(`VulkanRenderer.cpp:5994`) | ~10 次 accessor + ~20 次字比较 |
|
||||
| `GetOrCreatePipeline`(`:4948`) | `:4982-4993` 只在 `GetPipelineStateVersion()` 移动后重算哈希;`:5155-5200` 的 ~40 次 accessor 走查**只在 pipeline memo 未命中时**跑 |
|
||||
| `ApplyDynamicDrawStateTail`(`:5871`) | `:5888-5893` 一次版本比较,然后一次 bulk fetch 建值键 |
|
||||
|
||||
**所以真实稳态大约是每 backend 每 draw 10-25 次 accessor 调用加几十次字比较,不是 124/169。** 推送模型的优势因此比 v1 声称的**窄得多**,而且它在 §10.2 的对照表必须按动态口径重写(已改)。**推论**:
|
||||
1. P0 的计数器交付物**必须包含动态调用计数器**(每 draw 实际执行的 accessor 次数、每个 memo 门的命中/未命中),不只是字节计数器——否则 P2 仍然是在猜。
|
||||
2. 第 42 天的 GO/NO-GO 阈值必须是一个**绝对数字**(tracker 每 draw 的 ns,两台设备实测),不能只写"落在 monolith-pull 的噪声内"——当真实基线是 20 次调用时,相对噪声阈值会平凡通过。
|
||||
|
||||
### 2.4 pull 模型里 293 之外的 58 行:迁移机制必须显式处理的缺口
|
||||
|
||||
| 形态 | 数量 | 例子 | 处理 |
|
||||
|---|---|---|---|
|
||||
| `MOBILEGL_ASSERT(MG_State::pGLContext, ...)` 真值判定 | ~34 | `DirectVulkan.cpp` 密集区、`UniformManager.cpp` 9 处 | **直接删除**(`Defines.h:114` 在非 debug 下宏为空,所以这批**在 RelWithDebInfo 里本来就不生成代码**);替换成 §6.2 的 poison mask |
|
||||
| `if (MG_State::pGLContext)` 空守卫 | 7 | `Managers.cpp:3608`(守 `BackendTextureObject::StampViewSyncKeys` 的三次赋值)、`:3737, 3808, 4663, 8678`、`BackendObject_DirectVulkan.cpp:388, 788` | 删除守卫,改读 `PipeInputs` 字段(永远有效)。**这批会改变 `.text`**(见 §11 P1 验收修正) |
|
||||
| `MG_State::pGLContext != nullptr ? A : B` 三元 | 3 | `Managers.cpp:7120, 7128, 7131`(patch 参数,在 transpile 路径内) | 由 `set_patch_state` 覆盖,三元塌成直接读。**改变 `.text`** |
|
||||
| `MG_State::pGLContext.get()` 裸指针捕获 | 1 | `DirectGLES.cpp:146` | **`sed` 完全抓不到**,必须手改。相邻的 `:142` 还有一个 `decltype(MG_State::pGLContext->GetFramebufferBindingSlot(...))` 类型别名,同属此类 |
|
||||
| `!= nullptr` 条件 | 14 | `VulkanRenderer.cpp:11150, 12649` 等 | 同空守卫 |
|
||||
| 注释 | 1 | `VertexInputStateFactory.h:133` | 改写措辞 |
|
||||
|
||||
**因此:纯度门 grep 的是 `pGLContext`,不是 `pGLContext->`**,且 P1 的机械替换步骤必须把这 58 行列成显式清单逐条转换。
|
||||
|
||||
### 2.5 pull 模型为了弥补"没有接口"而付的代价(v2:区分**真删除**与**搬迁**)
|
||||
|
||||
v1 把下表全部记作"~550 行删除"。**其中一部分是搬迁,不是删除**,必须分开记账,否则 §10.4 的 monolith 收益被高估。
|
||||
|
||||
**真删除(结构性,`{slot, gen}` 与显式 destroy 让它们不可表达)**
|
||||
|
||||
| 机制 | 位置 | 行数 |
|
||||
|---|---|---|
|
||||
| `TwinLookupMemo` ×3(4096+256+64 槽 ≈ 140KiB)+ `OwnerEquals` | `DirectGLES.cpp:62-131` | ~75 |
|
||||
| `g_fbSlotCache` + `GetFramebufferBindingSlotFast` | `DirectGLES.cpp:139-155` | ~17 |
|
||||
| `StateBackendObjectRegistry::CollectGarbage` ×6 | `Managers.h:353-390` | ~40 |
|
||||
| `m_convertedVertexStreams` 的 `SharedPtr sourcePin` | `VulkanRenderer.h:1124-1127` | ~5 |
|
||||
| `UniformManager` 的 8 类占位 `TextureObject` 构造 | `UniformManager.cpp:161-181, 1416-1500, 1624-1634` | ~120 |
|
||||
| `SetupDrawSnapshot` 的 `sampledContentSum`/`sampledParamsSum` 与 ~14 个探测字段 | `VulkanRenderer.h:975-1000` | ~30 |
|
||||
| `g_broadcastMemo*` + fragColor 重推导 workaround | `DirectGLES.cpp:2669-2732` | ~60 |
|
||||
| `VkTextureManager::PruneDeadTextures` 的 `WeakPtr::expired()` GC | `VkTextureManager.cpp:1694-1720` | ~25 |
|
||||
| **小计** | | **~372** |
|
||||
|
||||
**搬迁到 client(**不是**净删除)**
|
||||
|
||||
| 机制 | 位置 | 行数 | 为什么搬而不是删 |
|
||||
|---|---|---|---|
|
||||
| `UnitBindingsSnapshot` / `CaptureUnitBindings` / `UnitBindingsUnchanged` / `CurrentUnitBindingsEpoch` / `UnitTextureSyncEntry` / `PairingsIntact` + 8 个支撑全局 | `DirectGLES.cpp:1372-1489` | ~115 | 它存在的理由是 `GetTextureBindGeneration()` **在冗余重绑时也 bump**(`:1414-1420` 注释:26.2 在每次纹理单元切换前后重绑同一个 sampler)。而 §5.2 恰好把这个计数器列为 `NEW_SAMPLER_VIEWS` 的 dirty 输入。**若 tracker 直接信它,每一次冗余 `glBindSampler` 都会重发一次 `set_sampler_views`——一条 `kVarTail` 变长记录,每 draw 几百字节,且 server 侧 `viewSetSerial` 一动就冲掉解析绑定 memo 与 sampler pass memo。** 这正是那 115 行要防的 per-batch 回归。**去抖必须搬到 client**:tracker 对已解析的 view/image/buffer 集合算 hash,hash 未变则**不发**(`MGPFramebufferState::contentHash` 已经演示了这个模式,这里把它推广到其余 `kVarTail` 的 `set_*`,并且在 client 侧当作**发射抑制器**用,不只是 server 的 memo 键) |
|
||||
| `g_fboTextureSyncList`(`:1580-1601`) | | ~20 | 同上,针对 attachment;由 `MGPFramebufferState::contentHash` 抑制 |
|
||||
| `ResolvedTextureBindingMemo` 的完备性解析(`IsMipmapCompleteForFilter` / `SamplesAsIncompleteTexture` / `IsUndefinedDefaultTexture`) | `DirectGLES.cpp:3218-3291` + `TextureObject.h:309/315/329` | ~40 | §5.5 把 view 解析放在 client,所以 client 需要自己的 memo 才不会每 draw 重解析 |
|
||||
| **小计** | | **~175** |
|
||||
|
||||
**净账:monolith 侧真删除 ~372 行;另有 ~175 行从 backend 搬到 `MG_Impl/Pipe/Tracker.cpp`。** §10.4 与 §3 的对照表按这个数字改写。
|
||||
|
||||
### 2.6 21 个 D 类身份 memo:它们各自守什么,以及为什么 `{slot, gen}` 能等价替换
|
||||
|
||||
统一事实:**每一个进入 memo 键的版本计数器要么是回绕的 `Uint16`,要么根本不会被它真正害怕的那个 mutation bump。** `BindingSlot::m_version`(`MG_Util/Types.h:197`)、`FramebufferObject::m_objectVersion`(`:183`)、`SamplerObject::m_version`(`SamplerObject.h:155`)、`RenderStateParameters` 版本(`RenderState.h:522`)、`TextureObjectBase::m_textureParamsVersion`(`:203`)全部回绕。**身份比较是堵住回绕洞的那块补丁。** 完整的 21 条重键表在 §4.7;这里只点三条最有教育意义的:
|
||||
|
||||
- **D3 `UnitTextureSyncEntry` + `PairingsIntact`**(`DirectGLES.cpp:1441-1481`):注释写明它存在是因为"一次不经过 bind generation 的 slot 交换(DSA by-name 模拟以前就会静默交换一个 slot)会让每个键都匹配,而借来的 slot 指向另一张纹理,replay 于是会**用纹理 B 的前端状态驱动纹理 A 的后端 twin**——用 B 的形状重新指定 A 的后端存储并毁掉 A 的内容"。**这是整份调研里最强的"支持推送接口"的论据**:这一整类 bug 只在"client 能改一个绑定而不移动任何计数器"时才存在。审计义务从"哪些读需要守卫"变成"哪些 mutator 必须发消息",由 §10.3 的 verify 模式、poison mask 与推论 4 的 dirty-surface 生成器共同强制。(**注意**:这条的**去抖**部分搬到 client,见 §2.5。)
|
||||
- **D11 `VertexInputStateFactory::ComputeHash`**(`VertexInputStateFactory.cpp:38-49`):注释是一份 postmortem——"地址会被分配器复用……一个已销毁 buffer 的 GPU 切片被绑给了它的后继者的 draw,这就是一次 transform feedback 捕获拿回一个死 VAO 的顶点数据(0,0,0,1……)的原因"。**所以 `gen` 必须被混进 server 侧的每一个 content hash,而不只是被比较。**
|
||||
- **D18 `VkRenderPassManager::m_renderbufferResources` / `VkTextureManager::m_textureResources` 用节点式 `std::unordered_map` 而不是本项目开放寻址的 `UnorderedMap`**(postmortem 在 `VkRenderPassManager.h:375-397`):因为调用方会跨后续查表缓存 `RenderbufferResource*`/`TextureResource*`,一次扩表搬迁曾让 `BlitFramebuffer` 静默停在"source image layout is undefined"。**这一条在重键表里被显式标为 UNCHANGED**,并进 review checklist。
|
||||
|
||||
### 2.7 v2 新增:MGPipe **增加**的代码(诚实账)
|
||||
|
||||
§2.5 数了删除,v1 没有数新增。永久新增的大致规模:
|
||||
|
||||
| 组件 | 估计行数 |
|
||||
|---|---|
|
||||
| `MG_Pipe/`(`PipeCalls.def` ~72 行 + `MGPipeTypes.h` ~14 个 POD + handles + host span + callbacks) | ~1,200 |
|
||||
| 7 个生成器 `scripts/gen_pipe.py`(G1-G7) | ~1,500 |
|
||||
| 生成产物(`PipeTables.inc`/`PipeThunks.inc`/`PipeWire.inc`/`PipeVerify.inc`/`PipeFilled.inc`/`PipeCoverage.inc`/`PipeSpanTable.inc`) | ~4,000(生成,不手写) |
|
||||
| `MG_Impl/Pipe/`(Tracker、SlotAllocator、CsoCache、HostResolve、CompositeResolver)**含从 backend 搬来的 ~175 行** | ~2,200 |
|
||||
| `MG_Backend/MGPipe/`(`PipeInputs.h` + 两个 impl) | ~1,500 |
|
||||
| `MG_State` 的 5 个聚合世代 + `ProgramArtifacts.h` 抽取 + `MGPipeValueTypes.h` 抽取 | ~250(净新增很小,多为搬移) |
|
||||
| `MG_Remote/`(emitter、`PipeApplier`、`PipeObjectTables`)——**仅 disaggregated 构建** | ~2,500 |
|
||||
| **monolith 永久新增(不含 `MG_Remote`)** | **≈ 6,650 手写 + 4,000 生成** |
|
||||
|
||||
**所以 monolith 的净行数是增加的,不是减少的。** §10.4 与 §3 里 "~550 行删除" 不再作为主论据;**主论据是 §10.3-④ 的逐线程 CPU 数字**(每 draw 指令数与 cache line 触达数的减少),而删除清单降级为佐证。B-R2 因此有了一个可证伪的预测而不只是定性主张。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与方案 A(replica `GLContext`)的逐项对比
|
||||
|
||||
> 方案 A = `../MobileGL-disagg/docs/Disaggregated/PLAN.md`(feat/disaggregated@8b31de2f)。阶段天数逐项相加 = **77 天**。
|
||||
|
||||
| 维度 | 方案 A(replica) | 方案 B(MGPipe) | 判定 |
|
||||
|---|---|---|---|
|
||||
| **边界清晰度** | 边界**就是** replica:server 侧跑一份真 `GLContext`,backend 的 293 次拉取原样成立。没有写下来的契约,也无法写。新增 backend 必须先学会 186 个前端 getter 与 17 个 mutator 族 | 一份显式函数表(~72 项)+ 一份 POD payload 表 + `PipeCalls.def` 单一真相源。新增 backend 只实现两张表。`MG_Backend` 的 `MG_State` include 从 50 行 / 18 个头文件收缩到一张共享**值**头白名单 | **B 完胜**,这正是用户提出的目标 |
|
||||
| **状态副本** | 一份完整 `GLContext` 对象图 + 每个 <16MiB buffer 一份 `PipeResource` + 每个纹理 level 一份 `MipmapStorage` + server 侧 `MG_State`/`MG_Impl`/`MG_Util`(含 glslang ~43MB 文本页) | **一处副本**:split 且 `kCapNeedsHostIndexBytes` 时的索引宿主镜像(有预算、有计数器、有回退)。其余零副本 | **B 完胜**(量级差别) |
|
||||
| **CPU 工作量** | `PLAN.md` §10 自承:"这套遍历**每 draw 跑两次**"——client 的 `WireMirror` 一次、server 未改动的 `PrepareForDraw` 一次,外加编解码 | 遍历**搬走**而不是翻倍:client 做 O(1) 快门(值类用既有计数器、对象类用 5 个新增聚合世代)+ 未命中时的 touched 前缀走查 + N 次 `set_*`,server 侧真删除 ~372 行失效发现机制。**但基线比 v1 声称的窄**(§2.3.1)——**这是主张,不是测量** | **B 理论上更好,未证实**。两者都必须以逐线程 CPU 时间为准 |
|
||||
| **内存** | `PLAN.md` R14 自估 **可达 ~450MiB 新增** | 典型 **+50-60MiB**;最坏(索引镜像满 + stage 余量满)**+145MiB** | **B 完胜** |
|
||||
| **Roundtrip** | 稳态零(除回读/阻塞 query/分配 ack/present credit) | 稳态零(同上),**外加**一个新类:server 发起的纹理重铸拉取。三条缓解 + 终止符 + 专门的门 + 逐用例计数器(§7.5、§9.3) | **A 略优**,差距被压到"实测发布"而非"声称为零" |
|
||||
| **改造量** | backend **一行不改** | backend 改 293 个读点 + 58 行非箭头用法 + 95 个写回点 + ~66 个 memo 族重键 + 两处 `MG_State` 类型内部用法重写 + 一个头文件抽取前置阶段 | **A 完胜** |
|
||||
| **迁移期风险** | 风险**集中在末端**且**难以测试**:replica 的行为漂移编译通过、多数内容渲染正确,守卫只看签名 | 风险**分布在 ~14 个阶段**,每阶段可二分、有现成测试套件作门、有**逐 draw 逐字段的语义比对**。但它**改动 monolith**,且 **stage C 之后 `MOBILEGL_PIPE_PUSH` 的 A/B 口径会收窄**(§6.7 v2 修订) | **B 的正确性风险更低,A 的产品风险更低** |
|
||||
| **到首帧时间** | **~第 15 天**跨进程首帧 | **~第 95 天** inproc 首帧、**~第 100 天** 跨进程首帧,且是**缩减路径**;全功能在第 ~139 天。最早可见里程碑是**第 ~25 天**的 verify harness 全绿 | **A 完胜(6-7 倍)** |
|
||||
| **长期价值** | 拆分达成;monolith 不变;边界仍未定义。维护成本**永久** | 边界被写下来、被生成、被测试。第三个 backend、shader 缓存服务、record/replay 层、真正的第二个 context 都变得可行。成本**一次性**。**但 monolith 的净代码量增加**(§2.7) | **B 完胜** |
|
||||
| **对 monolith 的收益** | 零(按设计如此) | ~372 行 per-draw 失效机制**真删除**(另 ~175 行搬到 client);复用地址 ABA 一类不可表达;FBO→program 排序 hazard 消失;`pDefaultFramebufferInfo` 分层倒置消失;`inproc` = 渲染线程杠杆;顺带修两个潜伏 bug;顺带暴露一个死能力(`FramebufferSrgb`/`DepthClamp` 无存储,`RenderState.cpp:380/428-429`,6 个 backend 读点恒为 false) | **B 完胜**,但**收益要以 CPU 数字而非行数计**(§2.7) |
|
||||
|
||||
### 3.1 方案 A 里被证明**不可能**、而不只是"不理想"的两件事
|
||||
|
||||
1. **`RecProgramLinkOp`(server 从源码重新 link)**。`ProgramObject.h:11 → ShaderObject.h:12 → ShaderCompileTask.h`,`ShaderObject.h:146` 返回 `SharedPtr<glslang::TShader>`,`ProgramObject.h:14 → SpvcSession.h`。链接真 `ProgramObject` 就链接 glslang。所以 `ProgramPublish` 第一天上、`MOBILEGL_IPC_PROGRAM=publish|relink` 开关消失、阶段 P5 整个消失(6 天回收)。**但方案 B 因此欠下 P0.5 的头文件抽取**(§0.4)。
|
||||
2. **方案 A 的字节一致门在方案 B 里不成立**(D-B5)。这不是方案 B 的缺陷论证,是它必须公开承认的成本。
|
||||
|
||||
### 3.2 方案 B 复用方案 A 的比例
|
||||
|
||||
`PLAN.md` 的 §6-§14 按体量算是全文的大部分,且与状态模型无关。方案 B 原样继承,逐条对照见 §8 与 §14。**因此"选 B 不选 A"并不浪费传输侧的设计投资。**
|
||||
|
||||
### 3.3 一句话决策规则
|
||||
|
||||
- 目标是**这个季度出一个能跑的拆分**,或拆分的价值主要按"进程隔离/崩溃隔离"计算 → **选方案 A**。
|
||||
- 目标是**用户提出的那个架构** → **选方案 B**,按 §0.6 的对冲路径起步,第 42 天用真数字做 GO/NO-GO。
|
||||
- **不要**试图先做 A 再做 B。A 的 replica 一旦上线就成为"边界"的既成事实,而 B 的第一步会作废 A 的全部 applier 代码——两条路的 backend 侧改造互斥,共享的只有传输层。
|
||||
@@ -0,0 +1,888 @@
|
||||
## 4. 接口设计:MGPipe
|
||||
|
||||
### 4.1 文件布局与单一真相源
|
||||
|
||||
```
|
||||
MobileGL/MG_Pipe/ # client 与 server 都 include;不链接 MG_State,不链接 MG_Impl
|
||||
PipeCalls.def # X-macro:调用目录的唯一真相源,一行一个调用
|
||||
MGPipe.h # 由 .def 生成的两张函数表 + 手写 payload 声明
|
||||
MGPipeTypes.h # 全部 payload POD(trivially copyable,逐个 static_assert)
|
||||
MGPipeValueTypes.h # ★v2 新增:无依赖的共享值类型(见 §4.7.2)
|
||||
MGPipeHandles.h # MGPipeHandle、MGPipeKind、保留 handle、slot 分配契约
|
||||
MGPipeHostSpan.h # 唯一一个"形状随传输而变"的访问器(§4.5.7)
|
||||
MGPipeCallbacks.h # 反向通道(事件/回复)的函数表,见 §7
|
||||
MGPipeRenderStateSpans.{h,cpp} # ★v2 新增:pipeline/dynamic 划分的唯一定义(§4.5.2)
|
||||
generated/PipeTables.inc # G1:两张函数表
|
||||
generated/PipeThunks.inc # G2:monolith 直调 thunk
|
||||
generated/PipeWire.inc # G3:wire 记录 + static_assert + 运行期边界检查 + applier switch
|
||||
generated/PipeVerify.inc # G4:逐字段影子比对器
|
||||
generated/PipeFilled.inc # G5:written-once 位图与 poison 断言(**逐 verb 世代**)
|
||||
generated/PipeCoverage.inc # G6:477 读点 → MGPipe 调用的映射表
|
||||
generated/PipeSpanTable.inc # ★G7:render-state 的 pipeline/dynamic chunk 表 + setter 一致性测试
|
||||
MobileGL/MG_Impl/Pipe/
|
||||
Tracker.{h,cpp} # st_validate_state 类比物(含从 backend 搬来的 ~175 行去抖/解析)
|
||||
SlotAllocator.{h,cpp} CsoCache.{h,cpp}
|
||||
HostResolve.cpp # 客户端数组界限 / 索引扫描 / indirect count 解析
|
||||
CompositeResolver.cpp # program pipeline 合成体的 handle 生命周期
|
||||
MobileGL/MG_Backend/MGPipe/
|
||||
PipeInputs.h # backend 私有的"被推送状态"块(迁移载体,§6.2)
|
||||
MGPipeImpl_DirectGLES.cpp # 用 Espryt 的函数填 MGPipeContext
|
||||
MGPipeImpl_DirectVulkan.cpp # 用 Magma 的函数填 MGPipeContext
|
||||
MobileGL/MG_Remote/ # 传输,继承 PLAN.md §13(删掉 Server/ReplicaContext.*)
|
||||
Server/PipeApplier.cpp Server/PipeObjectTables.{h,cpp} Server/IndexHostMirror.{h,cpp}
|
||||
scripts/gen_pipe.py # 跑 G1..G7
|
||||
scripts/gen_pipe_dirty_surface.py # ★v2:MG_Impl mutator → 聚合世代 的覆盖生成器(推论 4)
|
||||
scripts/check_doc_citations.py # ★v2:docs/**.md 的 file:line 必须解析到存在的行
|
||||
```
|
||||
|
||||
`PipeCalls.def` 一行一个调用,**七个生成器**消费它:
|
||||
|
||||
```cpp
|
||||
// MG_Pipe/PipeCalls.def — X(Name, PayloadStruct, Class, Flags)
|
||||
// Class : kScreen | kCtxCso | kCtxState | kCtxObject | kCtxVerb | kCtxQuery
|
||||
// Flags : kNone | kNeedsAck | kHasBlob | kVarTail | kHostSpan | kReplySlot | kOptional
|
||||
#define MGP_CALL_LIST(X) \
|
||||
/* ---- screen ---- */ \
|
||||
X(GetCaps, MGPCaps, kScreen, kReplySlot) \
|
||||
X(ResourceCreate, MGPResourceDesc, kScreen, kNone) \
|
||||
X(ResourceRespecify, MGPResourceDesc, kScreen, kNone) \
|
||||
X(ResourceDestroy, MGPHandleOnly, kScreen, kNone) \
|
||||
X(MapPersistent, MGPHandleOnly, kScreen, kReplySlot|kOptional) \
|
||||
/* ---- CSO ---- */ \
|
||||
X(CreateRenderState, MGPRenderStateDesc, kCtxCso, kHasBlob) \
|
||||
X(BindRenderState, MGPBindRenderState, kCtxCso, kNone) \
|
||||
/* ---- state ---- */ \
|
||||
X(SetDynamicState, MGPDynamicState, kCtxState, kHasBlob) \
|
||||
X(SetFramebufferState, MGPFramebufferState, kCtxState, kNone) \
|
||||
X(SetSamplerViews, MGPSamplerViews, kCtxState, kVarTail) \
|
||||
X(SetTextureParams, MGPTextureParams, kCtxObject,kNone) \
|
||||
X(SetShaderBuffers, MGPShaderBuffers, kCtxState, kVarTail|kHostSpan) \
|
||||
/* ---- verb ---- */ \
|
||||
X(DrawVbo, MGPDrawInfo, kCtxVerb, kHostSpan|kVarTail) \
|
||||
X(ResourceSubData, MGPSubData, kCtxObject,kHasBlob|kVarTail) \
|
||||
X(RenderbufferStorage, MGPRbStorage, kCtxObject,kNeedsAck) \
|
||||
/* … 共约 74 项,完整目录见 §4.4 与 part4 的速查表 … */
|
||||
```
|
||||
|
||||
| 生成器 | 产物 | 替代/新增 |
|
||||
|---|---|---|
|
||||
| **G1** | `struct MGPipeScreen { … };` / `struct MGPipeContext { void (*DrawVbo)(const MGPDrawInfo*, …); … };` | 替代今天手写的 `GLFunctionsTable` |
|
||||
| **G2** | monolith thunk:`inline void MGP_DrawVbo(const MGPDrawInfo* p){ gPipeCtx.DrawVbo(p); }` | 替代 `gBackendFunctionsTable.GL.*`(~93 个 MG_Impl 站点改名即可) |
|
||||
| **G3** | wire 记录结构 + 每种一条 `static_assert(sizeof==N)` + applier 分发前的运行期边界检查 → `Fatal{ProtocolCorruption}` | 继承并扩展 `PLAN.md` §6.3 的 `Records.def` 机制到**全部**调用 |
|
||||
| **G4** | `MOBILEGL_PIPE_VERIFY` 的逐字段比对器 | **新增**:每份候选设计都被判缺失的语义绊线 |
|
||||
| **G5** | `PipeInputs::m_filledGen[]` 的位/世代定义 + 读未填字段时的 `Fatal{UnmigratedPipeInput, "<field>"}` | **新增**(v2:由"位图"升级为"**逐 verb 世代**",见 §6.2.2) |
|
||||
| **G6** | 477 行读点清单 → MGPipe 调用的映射,CI 重生成并 `git diff --exit-code`,0 UNMAPPED | 改造自 `Feat/CS-Delta-IPC` 的 `extract_backend_read_inventory.py` |
|
||||
| **G7(v2 新增)** | `RenderStateParameters` 的 pipeline/dynamic chunk 表 + **一个遍历每个 `RenderState` public setter、断言 `pipelineSubsetHash 变 ⟺ m_pipelineStateVersion 变` 的 `MG_Test`** | **新增**:D-B1 拒绝三 CSO 时点名要求、v1 却没给自己的完整性绊线 |
|
||||
|
||||
**G4、G5、G7 与调用目录从同一份 `.def`/同一张 chunk 表生成,因此不可能漂移。**
|
||||
|
||||
**接口表用函数指针 struct,不用虚基类。** 三条本仓库自己的理由:(1) 边界今天**就是**函数指针 struct,装在 `MG_Backend/Init.cpp:44` 的唯一 hook 点上;(2) `nullptr` 项**已经**表示"未实现,前端回退"(`BackendObject.h:212-215`、`:265-269`),DirectVulkan 确实留空 8 项——**一个 null `set_*` 恰好就是"这个子系统还没迁移,继续拉取"**,纯虚类只能用说谎的 stub override 来模拟;(3) `MG_Test` 已经会替换这张表做 mock。稀有的 EGL/caps 面继续留在 `pActiveBackendObject` 的虚函数上。
|
||||
|
||||
### 4.2 对象模型
|
||||
|
||||
#### 4.2.1 Handle
|
||||
|
||||
```cpp
|
||||
enum class MGPipeKind : Uint8 {
|
||||
Buffer=1, Texture, Renderbuffer, Framebuffer, Xfb,
|
||||
RenderStateCso, VertexElementsCso, SamplerCso, SamplerViewCso, ShaderCso,
|
||||
Fence, Query, Context
|
||||
};
|
||||
struct MGPipeHandle { Uint32 slot; Uint32 gen; }; // 8 B,POD,按值走寄存器对
|
||||
```
|
||||
|
||||
- **slot 稠密、按 kind 分配**,把 server 的对象表从哈希表变成**数组**;`SlotAllocator` 是 free-list + 高水位,与 `IndexGenerator` 无关(后者的 LIFO 复用正是问题本身)。
|
||||
- **`gen` 只在 slot 复用时 ++**,不是每次 respecify。`{slot, gen}` 在同一 slot 被复用 2³² 次之前唯一;文档写明上界,debug 断言它。
|
||||
- **GL name 只在 `resource_create` 的 payload 里出现一次,纯诊断**,永不做身份、永不进 memo 键或 content hash。
|
||||
- **`GetLifetimeId()` 留在 client 侧**作为 tracker 自己的身份,不过线;client 维护 `lifetimeId → slot`。
|
||||
- **保留 handle**:`{0,0}` = null;`{slot=0, gen=1, kind=Framebuffer}` = 默认帧缓冲(退役 `DirectGLES.cpp:1917, 2838, 2867, 9675` 四处 `pDefaultFramebufferInfo->defaultFBO` 身份比较);`ShaderCso` 的高 1/16 slot 段保留给 **program pipeline 合成体**(§5.6)。
|
||||
|
||||
#### 4.2.2 两种 generation,严格分开
|
||||
|
||||
| | 拥有者 | 回答什么 | 是否过线 |
|
||||
|---|---|---|---|
|
||||
| **身份**(`MGPipeHandle::gen`) | client | "还是同一个 GL 对象吗?" | 是 |
|
||||
| **`MGGen`**(server 纪元) | **server** | "**我自己**是不是重铸了驱动对象 / 冲了自己的缓存?" | **client→server 永不;server→client 只以纹理拉取请求的形式出现**(§7.5) |
|
||||
|
||||
**接口规范条款:任何 MGPipe 调用都不得要求 client 提供或知晓 `MGGen`。** 反过来也是规范:**client 侧的版本计数器永远不是新鲜度的唯一证明**——每一个回绕的 `Uint16`(§2.6)在过线时要么加宽到 32 位、要么与 `{slot, gen}` 同行。
|
||||
|
||||
#### 4.2.3 CSO vs 可变对象
|
||||
|
||||
| 类别 | 形态 | 因为 backend 今天就是这么缓存的 |
|
||||
|---|---|---|
|
||||
| `VertexElementsCso` | `create/bind/delete` | `VertexInputStateFactory::m_cache`,键正是那组字段的 content hash(`VertexInputStateFactory.cpp:19-50`) |
|
||||
| `SamplerCso` | `create/bind/delete` | `VkSamplerManager::m_samplers`;Espryt 的 `BackendSamplerObject`(`Managers.h:1808-1824`) |
|
||||
| `SamplerViewCso` | `create/delete` + 由 `set_sampler_views` 绑定 | `TextureResource::{perMipViews, …, storageImageViews}`(`VkTextureManager.h:173-370`);Espryt 的 `SyncTextureViewToBackend`(`Managers.cpp:3616-3707`) |
|
||||
| `ShaderCso` | `create/bind/delete` + **server 侧惰性特化**(D-B2) | `ProgramFactory::m_cache`;`BackendProgramObjectImpl` |
|
||||
| `RenderStateCso` | `create/bind/delete`,**身份 = pipeline 子集**(D-B1 v2) | Espryt 的值镜像 + 单 `Uint16` 早退 + 三段 memcmp;Magma 的 `ComputePipelineStateHash` |
|
||||
| Buffer / Texture / Renderbuffer | `create` / `respecify` / `subdata` / `destroy` | `GLESBufferResource`、`BackendTextureObject`、`VkBufferResource`、`TextureResource` |
|
||||
| Framebuffer / Xfb | per-context 身份 + `set_*` payload | `BackendFramebufferObject`、`m_xfbCounterSlotByObject` |
|
||||
|
||||
**CSO 在 client 侧内容寻址**(Mesa `cso_context`/`cso_cache` 先例):每类一张 `ska::flat_hash_map<Uint64 xxHash, MGPipeHandle>`,容量上限(render-state 64、vertex-elements 1024、sampler 256、sampler-view 4096、shader 跟随 `ProgramObject` 生命周期),LRU 淘汰时发 `delete_*_state`。**收益**:两个不同 program 设置了相同状态时 server 侧**零状态转换**。
|
||||
|
||||
**任何 `create_*` 都不返回 server 铸造的 handle。** 这是对 gallium 的**有意偏离**(D1),也是这份目录能在**零创建 round trip** 下远程化的根本原因。`BackendSyncHandle`/`BackendQueryHandle = void*`(`BackendObject.h:110, 115`)随之变成 `MGPipeHandle`。
|
||||
|
||||
### 4.3 `MGPipeScreen` 与 `MGPipeContext`
|
||||
|
||||
| `MGPipeScreen`(share group) | `MGPipeContext` |
|
||||
|---|---|
|
||||
| caps、format 能力表、renderer 字符串;buffer / texture / renderbuffer / sampler / shader 的对象命名空间;fence | 全部 `set_*`、全部 CSO 绑定、VAO / FBO / XFB 对象 / query 的命名空间、命令流、present |
|
||||
|
||||
v1 只有一个 screen、一个 context、一条 flow。**但两张表从第一天就分开**,因为事后拆分意味着给每个记录种类重新编号。两处必须重新归类的事实:`GetTextureBindGeneration()` 与 `GetSamplingResolutionGeneration()`(`Core.h:130, 136`)是**绑定**(context)事实却住在 share-group 作用域的 `TextureState` 里;`GetTextureContextId()`(`:143`)直接**就是** context handle。
|
||||
|
||||
### 4.4 完整调用目录
|
||||
|
||||
#### 4.4.1 `MGPipeScreen`(14 项)
|
||||
|
||||
| 调用 | payload | 取代 |
|
||||
|---|---|---|
|
||||
| `get_caps(MGPCaps* out)` | `DynamicBackendParameters`(`BackendObject.h:302-522`,~90 标量,平坦 POD)+ `RendererInfo` + `FormatCapabilityCache`(`:88-99`)+ `callMask` | 40 个 `pActiveBackendObject->` 站点、89 个 caps 读点 |
|
||||
| `resource_create(h, const MGPResourceDesc*)` | §4.5.1 | buffer/texture/renderbuffer 的创建 |
|
||||
| `resource_respecify(h, const MGPResourceDesc*)` | 同上 | `BufferBackendOps::Respecify`(`BufferObject.h:80`)泛化 |
|
||||
| `resource_destroy(h)` | handle | `OnDestroy`(`:101`)+ **两个 `WeakPtr` GC 扫描** |
|
||||
| `map_persistent(h) → MGPMapResult` / `unmap_persistent(h)` | — | `AcquirePersistentMap`(`:112`)。**改造期不碰**(D-B4) |
|
||||
| `fence_create/status/wait/destroy` | handle (+timeout) | `FenceSync`…`GetSyncStatus`(`:220-224`)。两值契约(`:243-249`)**逐字保留** |
|
||||
| `query_create/begin/end/available/result/destroy` | handle + kind | `BackendObject.h:230-256` |
|
||||
| EGL 生命周期 8 项 | `BackendObject.h:548-559` | 原样保留为虚函数(罕见) |
|
||||
|
||||
**`callMask` 取代"槽位是否为 null"这个隐式能力探测**(`GL_Query.cpp:471, 545, 768`)。**v2 修订的能力位集**(v1 的五个 emulation 归属位按 D-B7 删除):
|
||||
`kCapViewportArray`、`kCapFloat64VertexAttrib`、`kCapResidentSubData`、`kCapCpuXfbPrimitiveAccounting`、`kCapTimerQuery`、`kCapOcclusionQuery`、`kCapXfbPrimitivesQuery`、**`kCapNeedsHostIndexBytes`**(server 侧的 restart 重写/multi-draw 展平需要索引宿主字节 → split 下开启索引宿主镜像,D-B7)、**`kCapNeedsHostUboBytes`**(server 侧要把具名 UBO 打进自己的 ring → 需要 `set_shader_buffers` 的 host payload,D-B8)。
|
||||
**删除**:`kCapPrimitiveRestart`、`kCapPrimitiveRestartFixedIndex`、`kCapMultiDraw`、`kCapMultiDrawIndirect`、`kCapMultiDrawIndirectCount`——它们表达的"归属开关"不可表达(D-B7)。
|
||||
|
||||
#### 4.4.2 `MGPipeContext` — CSO(15 项)
|
||||
|
||||
`create/bind/delete` × { `render_state`, `vertex_elements`, `sampler`, `sampler_view`, `shader` }。payload 见 §4.5.2-4.5.5。
|
||||
|
||||
#### 4.4.3 `MGPipeContext` — `set_*`(17 项,v2 从 14 增至 17)
|
||||
|
||||
| 调用 | 取代的拉取点 |
|
||||
|---|---|
|
||||
| `set_dynamic_state(MGPBlobRef chunks, Uint16 version)` **(v2 新增)** | 渲染状态里 `m_pipelineStateVersion` 不覆盖的那一半(viewport / scissor / depth range / blend color / line width / polygon offset / stencil ref+write mask / clear values / sample coverage / hints / point-size 族)。**这条让 `glViewport` 不再铸造新 CSO**(D-B1) |
|
||||
| `set_framebuffer_state` | `GetFramebufferBindingSlot` ×19、`GetAllAttachmentObjects`、`GetDrawBuffers`、`GetReadBuffer`、4 处 `pDefaultFramebufferInfo` |
|
||||
| `set_vertex_buffers(start, count, const MGPVertexBuffer*)` | VAO binding-point 走查 |
|
||||
| `set_index_buffer(const MGPIndexBuffer*)` | `GetIndexBufferBindingSlot`;**独立调用**——VAO config version 不是它的超集(D5) |
|
||||
| `set_indirect_buffers(drawIndirect, parameter)` | `GetBufferBindingSlot(DrawIndirect/Parameter)` |
|
||||
| `set_sampler_views(start, count, const MGPBoundView*)` **(v2:删掉 stage 形参)** | `GetTextureUnitObject` ×19、`GetActiveTextureUnit` ×8、`GetTextureBindGeneration` ×5。**client 侧已解析**(§5.5) |
|
||||
| `bind_sampler_states(start, count, const MGPipeHandle*)` **(v2:删掉 stage 形参)** | `TextureUnit.h:394` |
|
||||
| `set_texture_params(res, const MGPTextureParams*)` **(v2 新增)** | base/max level、swizzle、depth-stencil mode、LOD 钳。**必须独立于 sampler view**,见下 |
|
||||
| `set_shader_images(start, count, const MGPImageView*)` | `GetImageTextureBinding` ×14;**退役 `ImageUnitFormatsStillMatch`**(`Managers.cpp:6545-6573`) |
|
||||
| `set_shader_buffers(cls, start, count, const MGPBufferRange*, writableMask)` **(v2:Uniform 类的 range 可带 `MGHostSpan payload`)** | `GetBufferBindingPoint` ×19、`GetTouchedBufferBindingPointCount` ×2。`cls` ∈ {Uniform, ShaderStorage, AtomicCounter}。**payload 由 `kCapNeedsHostUboBytes` 门控**(D-B8) |
|
||||
| `set_stream_output_targets(count, const MGPBufferRange*, const Uint32* offsets, Uint64 generation)` | XFB 绑定走查 |
|
||||
| `set_global_constants(shaderCso, MGPBlobRef, Uint32 version)` | `MapUBO`/`GetUBOData`/`GetUBOSize`/`GetUBOContentVersion`(§4.6 D6)。**只覆盖默认 uniform block** |
|
||||
| `set_vertex_attrib_defaults(Uint32 mask, const MGPAttribValue*)` | `GetCurrentVertexAttribute` ×2;float/int/uint 视图由 `ClassifyVertexAttribType`(`Core.h:51`)在 client 侧解析 |
|
||||
| `set_pixel_pack_state(const PixelStoreParameters*)` | 6 个 PACK 读点。**没有 unpack 对应项**(§4.6 D5) |
|
||||
| `set_patch_state(Uint32 vertices, const Float outer[4], const Float inner[2])` | `GetPatchVertices`/`…OuterLevel`/`…InnerLevel` ×6。**同时是 shader variant 输入** |
|
||||
| `set_draw_program(shaderCso)` / `set_dispatch_program(shaderCso)` | `GetProgramForDraw` ×7、`GetProgramForDispatch` ×3。含 composite(§5.6) |
|
||||
|
||||
**为什么删掉 `stage` 形参(v2)**:MobileGL 的纹理单元空间是**合并的**,不是分 stage 的——`TextureState::m_textureUnits` 是 `Array<TextureUnit, MAX_TEXTURE_IMAGE_UNITS>` 且 `MAX_TEXTURE_IMAGE_UNITS = 192`(`TextureState.h:41, 128`),每 stage 的 32 只是一个**广告数字**(`:46`);`TextureUnit` 本身是 `Array<BindingSlot<ITextureObject>, TextureTargetCount>` 加一个 sampler(`TextureUnit.h:20, 24-25`);两个 backend 都按合并单元绑定(`g_boundTexturesCache[192][TargetCount]`)。同一个合并单元可以被两个 stage 采样。加 stage 维度会逼 client 要么按 stage 复制 view、要么发明一个 GL 未定义的 stage 归属,而 server 还得把它塌回去。**stage 只在目标 API 真正需要时出现(Magma 的描述符 stage flags),由 server 从反射归档推导。**
|
||||
|
||||
**为什么纹理参数不能只挂在 sampler view 上(v2)**:Espryt 对**每个 touched 单元绑定**与**每个 draw-FBO attachment 纹理**都调 `SyncTextureParamsToBackend`(`DirectGLES.cpp:1548-1560` 单元表、`:1580-1601` attachment 表),而 `RequireImageBindableStorage` 会置 `m_forceTextureParamsResync`,正是因为通道加宽后的载体需要一个前端 params 版本**不会移动**的 swizzle 覆盖(`Managers.cpp:2815-2821`)。一张**只作 FBO attachment**、**只作 image 单元绑定**、或**只作 `glCopyImageSubData` 端点**的纹理**没有 sampler view**,它的 `glTexParameter` 状态在 v1 的映射里没有载体。所以:**base/max level、swizzle、depth-stencil mode、LOD 钳挂在 `set_texture_params(res, …)` 上;`MGPSamplerView` 只带"视图限制"(min/num level、min/num layer、别名格式)。** 这同时让 `glTextureView` 保持它真正的身份——一个有自己参数、自己能当 FBO attachment、自己能当 `glTexSubImage` 目标的**真纹理对象**(`TextureObjectView.cpp:281, 290`)——而不是被降格成"普通 view CSO"。
|
||||
|
||||
**迁移期额外一项(显式临时)**:`set_residual_value_state(MGPBlobRef)`,见 §6.3。
|
||||
|
||||
#### 4.4.4 `MGPipeContext` — transfer(12 项)
|
||||
|
||||
`resource_subdata`(buffer + texture 同一形状,**带步长的多 region 描述符**,§4.5.6)、`resource_flush_range(h, Range1D, Flags<BufferMappingAccessBit>)`(携带应用**真实**的 access flags,`BufferObject.h:94-96`)、`resource_readback(h, off, size, MGPReplySlot)`、`resource_copy_region`、`blit`、`clear`(一条,判别式合并今天的 `Clear` + 4 个 `ClearBuffer*` + 4 个 `ClearNamedFramebuffer*`)、`generate_mipmap(h, target, const MGPMipPlan*)`、`read_pixels(const MGPReadbackInfo*, MGPReplySlot)`、`get_texture_image(...)`、`buffer_subdata_resident(h, off, MGPBlobRef)`(**可为 null**)。
|
||||
|
||||
**`buffer_subdata_resident` 的 per-backend 可选性必须被接口允许。** Espryt 注册它、Magma 故意不注册(`VkBufferManager.cpp:104-111`),差别是 `glBufferSubData` 在活的 coherent map 上的排序语义(`BufferObject.h:84-92` 的 Minecraft 撕裂 postmortem)。表现为 `kCapResidentSubData` 位 + null 项。
|
||||
|
||||
#### 4.4.5 `MGPipeContext` — 命令(10 项)
|
||||
|
||||
```cpp
|
||||
void draw_vbo (const MGPDrawInfo*, Uint32 drawIdOffset,
|
||||
const MGPDrawIndirect*, const MGPDrawRange*, Uint numDraws);
|
||||
void launch_grid(const MGPGridInfo*);
|
||||
void memory_barrier(GLbitfield bits, Bool byRegion);
|
||||
void begin_stream_output(GLenum primitiveMode);
|
||||
void end_stream_output(const MGPXfbAccounting*);
|
||||
void pause_stream_output(); void resume_stream_output();
|
||||
void flush(Uint32 flags);
|
||||
void present(Uint64 frameSerial); void set_swap_interval(Int interval); // 后者可 null(Magma)
|
||||
```
|
||||
|
||||
**今天 20 个 draw 入口塌成 `draw_vbo` 一条**,`MGPDrawRange[]` **就是** `MultiDraw*` 族今天的形状(gallium 的 `pipe_draw_start_count_bias`)。
|
||||
|
||||
#### 4.4.6 显式删除、不移植的项
|
||||
|
||||
- `GetIntegeri_v` / `GetInteger64i_v` / `GetProgramiv`(`BackendObject.h:195-197`)。只有 `GL_COMPUTE_WORK_GROUP_SIZE`(`DirectVulkan.cpp:790-795`)是真后端答案,进 `MGPCaps`。
|
||||
- `ShaderStorageBlockBinding`(`:207-208`)→ 折进 `MGPProgramDesc` 的反射归档。
|
||||
- **总规则:server 不回答任何 client 能自己回答的问题;剩下的每个 server 查询都是 async-with-handle,绝不阻塞。**
|
||||
|
||||
### 4.5 关键 payload
|
||||
|
||||
#### 4.5.1 `MGPResourceDesc`(判别式,三种 GL 存储类合一)
|
||||
|
||||
```cpp
|
||||
struct MGPResourceDesc {
|
||||
Uint8 target; // Buffer | Tex1D..TexCubeArray | Tex2DMS.. | Renderbuffer | TexBuffer
|
||||
Uint8 storageKind; // Mipmap | Buffer (== TextureStorageType, TextureEnum.h:61-64)
|
||||
Uint16 bindMask; // VERTEX|INDEX|CONSTANT|SHADER_BUFFER|INDIRECT|SAMPLER|SHADER_IMAGE|
|
||||
// RENDER_TARGET|DEPTH_STENCIL|STREAM_OUTPUT|ATOMIC|ELEMENT_ARRAY
|
||||
Uint32 internalFormat; // 已在前端解析为非压缩后备
|
||||
Uint32 width, height, depth;
|
||||
Uint16 arrayLayers, levels, samples;
|
||||
Uint8 fixedSampleLocations, immutable;
|
||||
Uint32 usage; // BufferUsage
|
||||
Uint32 storageFlags; // glBufferStorage flags
|
||||
Uint8 hasDefinedContent; // NULL-data respecify 之后为 false,BufferObject.h:216
|
||||
Uint8 imageBindableHint; // client 侧 everImageBound,预防性分配(§7.5(a))
|
||||
Uint8 glNameForDiag[2]; // 仅诊断
|
||||
MGPipeHandle viewOf; // 纹理视图的存储属主(GetViewStorageOwner,TextureObject.h:100)
|
||||
MGPipeHandle bufferForTexBuffer; Uint64 bufOffset, bufSize; // kWholeBuffer = ~0,实时解析
|
||||
};
|
||||
```
|
||||
|
||||
`bindMask` 里的 **`ELEMENT_ARRAY` 位是 D-B7 的开关**:server 见到它且 `kCapNeedsHostIndexBytes` 为真时,把该资源纳入索引宿主镜像。
|
||||
|
||||
**Renderbuffer 保持独立类**:自己的 format-capability target 索引(`BackendObject.h:85`)、自己的 `ComponentSizes` 上报(`RenderbufferObject.h:37-43`)、自己的 twin(`Managers.h:1838`)。
|
||||
|
||||
#### 4.5.2 渲染状态:`MGPRenderStateDesc` / `MGPBindRenderState` / `MGPDynamicState`(D-B1 v2)
|
||||
|
||||
```cpp
|
||||
// MG_Pipe/MGPipeRenderStateSpans.h —— 划分的唯一定义
|
||||
struct MGPStateChunk { Uint16 offset, length; };
|
||||
extern const MGPStateChunk kPipelineChunks[]; // G7 生成,来源 = VulkanRenderer.cpp:4826-4906 的字段表
|
||||
extern const MGPStateChunk kDynamicChunks[]; // 补集
|
||||
Uint64 MGPipeComputePipelineSubsetHash(const RenderStateParameters&); // client 与两个 backend 共用
|
||||
|
||||
struct MGPRenderStateDesc { // create:只带 pipeline 子集的 chunk 字节
|
||||
MGPipeHandle cso;
|
||||
Uint32 chunkMask; // 未命中时可只发变化的 chunk;全新 CSO 为全 1
|
||||
MGPipeHandle baseCso; // 增量基(chunkMask 非全 1 时有效)
|
||||
MGPBlobRef blob;
|
||||
};
|
||||
struct MGPBindRenderState { // bind:稳态 12 B
|
||||
MGPipeHandle cso; Uint16 version; Uint16 pipelineVersion;
|
||||
};
|
||||
struct MGPDynamicState { // 动态子集,只发变化的 chunk
|
||||
Uint32 chunkMask;
|
||||
Uint16 version; Uint16 pad;
|
||||
MGPBlobRef blob;
|
||||
};
|
||||
```
|
||||
|
||||
**server 侧模型**:每 context 一份 working `RenderStateParameters`(~1.2KB)。`bind_render_state` 把 CSO 的 chunk 散射进去;`set_dynamic_state` 把动态 chunk 散射进去。**Espryt 的 `SyncRenderState` 拿到的仍是 `const RenderStateParameters&`,693 行函数体、单 `Uint16` 早退、三段 memcmp、`g_syncedColorMaskAlphaWidenMask`、dual-source decline 一行不动。** Magma 的 pipeline memo 键是 `cso.slot`,`glViewport` 不再冲掉它;动态尾巴仍走 `ApplyDynamicDrawStateTail` 的两级门。
|
||||
|
||||
**两套 span 划分并存,互不干扰,各有绊线:**
|
||||
|
||||
| 划分 | 用途 | 定义在哪 | 绊线 |
|
||||
|---|---|---|---|
|
||||
| head / blend / tail(`DirectGLES.cpp:2038-2047`,按 `offsetof(BlendStates)`、`offsetof(LogicOp)`) | Espryt **驱动侧**增量 | `DirectGLES.cpp` 原地,**不动** | 已有:`static_assert(is_trivially_copyable_v)`;`RenderState.h:359-368` 的字段顺序注释 |
|
||||
| pipeline / dynamic | **线上传输与 CSO 身份** | `MGPipeRenderStateSpans.cpp`,G7 生成 | **G7 的 setter 一致性测试**:遍历每个 `RenderState` public setter,断言 `pipelineSubsetHash 变 ⟺ m_pipelineStateVersion 变` |
|
||||
|
||||
**client 侧的取值顺序(热路径,必须照此实现):**
|
||||
1. `m_pipelineStateVersion` 未变 → **复用上一个 CSO handle,零哈希**;
|
||||
2. 变了 → 对 pipeline 子集算 xxHash(~25-30 字,正是 Magma 今天在算的那个)→ CSO map 探测 → 命中发 12 B `bind_render_state`,未命中发变化 chunk 的 `create_render_state` 再 bind;
|
||||
3. `m_version` 变而 pipeline 子集未变 → 只发 `set_dynamic_state` 的变化 chunk(~200 B)。
|
||||
|
||||
**性能诚实注记**:Blaze3D 的 `glEnable/glDisable(GL_BLEND)` 走 `SET_CAPABILITY`(`RenderState.cpp:312`)→ `BumpVersions()`,所以每次都进第 2 步。交替的两个状态命中两个交替的 CSO,不重发 blob。对比今天:Espryt 1.2KB×3 段 memcmp + Magma ~30 字哈希。**净变便宜但差距不大**,因此 **P2 必须带一个专门的 enable/draw/disable/draw 微基准**(MC batch 速率,两台设备)。
|
||||
|
||||
#### 4.5.3 `MGPVertexElements`
|
||||
|
||||
携带**两个视图,缺一不可**:解析后的 `VertexAttribute[32]`(`VertexArrayObject.h:17-53`)**和** `VertexBufferBindingPoint`(`:58-64`,初始 stride 是 **16** 不是 0,`:61-62`)。`VertexArrayObject.h:22-29` 记录了合并它们的代价:pointer 调用的 stride 0 被解析成 element size,而 binding-model 的 stride 0 意味着每个顶点读**同一个** element,塌成一个害了 `KHR-GL43.vertex_attrib_binding.basic-input-case7/8`。`IsLong` 与 `Type == Float64` **分开携带**(`:34-39`)。**仅供查询的 `LegacyStride`/`LegacyPointer`(`:51-52`)留在 client。**
|
||||
|
||||
#### 4.5.4 `SamplerParameters` 与 `MGPSamplerView` / `MGPTextureParams`
|
||||
|
||||
`SamplerParameters`(**`SamplerObject.h:72-96`**,v1 误引为 `:468-492`)**逐字节原样过线,包括 `borderColorForm`**(**`:66-70`**):`:60-65` 明说没有它 backend 无法在 `glSamplerParameterIiv` 与 `fv` 之间、或在 `VkBorderColor` 家族之间选择,因为三种表示(`borderColor`/`borderColorI`/`borderColorUI`,`:93-95`)**永远都被数值填满**。`SamplerObject::BumpVersion()`(`:151`,`m_version` 在 `:155`)**同时**bump context 级 sampling-resolution generation,因为 MIN_FILTER 决定是否读 mip 链 → 决定 mipmap 完备性 → 决定 backend 到底绑不绑这张纹理。
|
||||
|
||||
```cpp
|
||||
struct MGPTextureParams { // ★v2:per-texture-object,与 view 无关
|
||||
MGPipeHandle res;
|
||||
Uint16 baseLevel, maxLevel;
|
||||
Uint8 swizzle[4];
|
||||
Uint8 depthStencilMode, pad[3];
|
||||
Float minLod, maxLod, lodBias;
|
||||
Uint8 forceResync; // 对应 m_forceTextureParamsResync(Managers.cpp:2815-2821)
|
||||
};
|
||||
struct MGPSamplerView { // = pipe_sampler_view,**只带视图限制**
|
||||
MGPipeHandle cso, texture;
|
||||
Uint32 internalFormat; // 别名格式(glTextureView)
|
||||
Uint8 target, pad[3];
|
||||
Uint16 minLevel, numLevels, minLayer, numLayers;
|
||||
Uint16 samples; Uint8 fixedSampleLocations, pad2;
|
||||
};
|
||||
```
|
||||
|
||||
`GetViewStorageOwner()`(`TextureObject.h:96-100`,一个 `SharedPtr`,且**它自己永远不是 view**)变成 `resource_create` 的 `viewOf` + server 侧 keep-alive。
|
||||
|
||||
#### 4.5.5 `MGPProgramDesc`(`create_shader_state` 的 payload)
|
||||
|
||||
```cpp
|
||||
struct MGPProgramDesc {
|
||||
MGPipeHandle cso;
|
||||
Uint32 stageMask; // == GetLinkedShaderStages()
|
||||
MGPBlobRef spirv[6]; // GetGeneratedSpirv(),逐 stage
|
||||
MGPBlobRef reflection; // Visit() 归档的 LinkArtifacts + SpirvArtifacts(全结构体)
|
||||
Uint32 globalUboSize;
|
||||
Uint32 reservedNumSamplesOffset;
|
||||
Uint8 spirvStatus, nativeFloat64, pointSizeDemoted, enableSpirvValidation;
|
||||
};
|
||||
```
|
||||
|
||||
**v2 前置条件(P0.5):反射类型必须先搬出 `ProgramObject.h`。** `TypeFacts`(`ProgramObject.h:44`)、`ResourceReflection`(`:76`)、`XfbVarying`(`:1146`)、`LinkArtifacts`(`:1210`)、`SpirvArtifacts`(`:1409`)今天全部声明在 `ProgramObject.h` 里,而该文件 `:11` include `ShaderObject.h`(→ `ShaderCompileTask.h` → glslang;`ShaderObject.h:146` 返回 `SharedPtr<glslang::TShader>`)、`:14` include `SpvcSession.h`(→ `spirv_reflect.h`)。**server 要反序列化进这些类型就必须 include 被门禁止的头。** P0.5 把它们抽到:
|
||||
|
||||
```
|
||||
MG_State/GLState/ProgramState/ProgramArtifacts.h # 只 include <Includes.h> 与容器/向量类型
|
||||
```
|
||||
|
||||
更新 7 个 includer(`ProgramFactory.h`、`UniformManager.cpp`、`VulkanRenderer.cpp`、`ProgramInterface.cpp`、`ProgramLinkTask.h`、`ProgramObject.h`、`ProgramTranslationCache.h`),并加 CI 断言:**`ProgramArtifacts.h` 的 `-H` 传递 include 闭包里不得出现 glslang / SPIRV-Cross / spirv_reflect 任何头**。没有这一步,P7 的 `nm -D | grep glslang` 判据不可达。
|
||||
|
||||
反射归档**序列化整个结构体**,机制沿用 `PLAN.md` §6.9 的 `Visit()` + `sizeof` 绊线,但**用途改变**:不再是"分歧预言机"(没有可分歧的对象),而是**schema 完整性绊线**:
|
||||
|
||||
```cpp
|
||||
template <class Ar> void Visit(Ar& ar, LinkArtifacts& a) { ar(a.writtenUniformLocationBits, /*…全字段…*/); }
|
||||
static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE,
|
||||
"新字段请加进 Visit() 并 bump MGL_LINKARTIFACTS_SIZE");
|
||||
```
|
||||
|
||||
归档必须覆盖:四个 `ResourceReflection`(各带 `TypeFacts`)、`uniformSamplerOrImageUnitIndex`(`:1298`)、`uniformBlockBinding`(`:1314`)、`shaderStorageBlockBinding`(按名字,`:1325`)、`explicitOpaqueUniformBindings`(`:1303`)、`xfbVaryings`/`xfbStrides`/`xfbPackedStride`/`xfbNeedsScatteredCapture`(`:1357-1394`)、`computeLocalSize`、GS/TCS/TES 事实(`:1373-1388`)、`usesReservedNumSamples`(`:1345`)、`uniformOffsets`(`:1416`)。
|
||||
|
||||
**`XfbVarying`(`:1146-1171`)必须带两套拼写**:GL 名字(Espryt 的 ESSL 驱动侧捕获列表)**和** `blockInstanceName`/`blockName`/`blockMemberIndex`/`blockMemberElement`(`:1163-1170`)。
|
||||
|
||||
#### 4.5.6 `MGPFramebufferState` 与 `MGPSubData`
|
||||
|
||||
```cpp
|
||||
struct MGPSurface { // = pipe_surface
|
||||
MGPipeHandle res;
|
||||
Uint32 internalFormat; // 内联!让四个跨对象 mask 在推送时刻零查表推出
|
||||
Uint8 kind; // Texture | Renderbuffer | None
|
||||
Uint8 layered; Uint16 level;
|
||||
Uint32 layer; Uint16 uploadTarget; Uint16 pad;
|
||||
};
|
||||
struct MGPFramebufferState {
|
||||
MGPipeHandle fbo; // {0,1} = 默认帧缓冲
|
||||
MGPSurface color[8], depth, stencil;
|
||||
MGPSurface readSurface; // *** client 侧已解析的读表面,不是索引 ***
|
||||
Int8 drawBuffers[8]; // attachment 索引,-1 = NONE
|
||||
Uint16 width, height, layers, samples;
|
||||
Uint8 fixedSampleLocations, isDefault, complete, pad;
|
||||
Uint64 contentHash; // client 计算;server 的 render-pass memo 键 + **client 侧发射抑制器**
|
||||
};
|
||||
```
|
||||
|
||||
1. **`readSurface` 是 client 解析后的表面**,按结构消灭 read-buffer-shared-FBO 缺陷类。
|
||||
2. **`internalFormat` 内联**,四个跨对象 mask(`Managers.cpp:5616-5619`)在 `set_framebuffer_state` 内部零查表推出。
|
||||
3. **`contentHash` 有两个用途**(v2 强调第二个):server 的 memo 键(取代 D7 四元组与 D15 三元组)**以及 client 的发射抑制器**——hash 未变就不发这条记录,这是 §2.5 里那 ~175 行去抖搬到 client 后的载体。**同一模式必须推广到每一条 `kVarTail` 的 `set_*`**(`set_sampler_views`、`bind_sampler_states`、`set_shader_images`、`set_shader_buffers`),否则 26.2 的冗余 `glBindSampler` 会让每个 batch 重发一条变长记录。
|
||||
|
||||
```cpp
|
||||
struct MGPSubRegion { // ★v2:形状照抄已存在的 UnpackStagingBlock(Managers.cpp:4340-4390)
|
||||
Int32 x, y, z; // 目标 box 原点(level 坐标系)
|
||||
Uint32 w, h, d;
|
||||
Uint64 srcOffset; // blob 内偏移
|
||||
Uint32 srcRowStride; // 源行距(字节);0 = 紧密(= w * bpp)
|
||||
Uint32 srcSliceStride; // 源片距(字节);0 = 紧密
|
||||
};
|
||||
struct MGPSubData {
|
||||
MGPipeHandle res;
|
||||
Uint16 target, level;
|
||||
Uint8 sourceIsVerbatimLevelShadow; // ★ 取代 backend 里的 `uploadData == mipData` 指针比较
|
||||
Uint8 pad[3];
|
||||
MGPBox unionBox; // union box(server 可选它)
|
||||
Uint32 regionCount; // MGPSubRegion[] 在变长尾(server 可选它们)
|
||||
MGPBlobRef blob;
|
||||
};
|
||||
```
|
||||
|
||||
**同时携带 union box 与 region 列表,由 server 选上传形状。** 这不是冗余:Mali 按**作业数**给纹理上传计价,实测 ~100 个精灵 rect 对一个 union box 是 **+6 ms/frame**(`Managers.cpp:4386-4390`)。client 按 `MipmapStorage::GetDirtyRects` 的语义产生区域形状(96-rect 级联合并 + `summedArea*4 >= unionArea*3` 回退,`MipmapStorage.cpp:300-305`),**决策留在付 GPU 代价的那一侧**。
|
||||
|
||||
**v2 关键修正:sub-rect 上传不能再靠指针比较判定。** 今天 `Managers.cpp:4278-4283` 用 `uploadData == mipData` 判"上传源就是整 level shadow",随后 `:4288-4293` 与 `rectShadowPtr`(`:4321-4326`)用 `levelRowBytes`/`levelSliceBytes` 跨步进**整 level**。在 split 下这个前提不成立:client 若发整 level 就毁掉带宽收益并与 §0.4 的零副本主张矛盾;若发紧密区域则 `uploadData == mipData` 为假,静默退回整 level 上传;若什么都不发就需要 server 侧整 level 镜像——那就是 replica 的 `MipmapStorage`。
|
||||
**修正**:`MGPSubRegion` 显式携带源步长,`sourceIsVerbatimLevelShadow` 显式携带原来那个指针比较回答的语义问题("这批字节是未经转换的 level shadow 吗")。`Managers.cpp:4274-4326` 相应改为**从描述符**取步长而不是从指针算,`UNPACK_ROW_LENGTH` 从 `srcRowStride/bpp` 设。
|
||||
**注意树里已经有这个形状**:unpack ring 路径的 `UnpackStagingBlock`(`Managers.cpp:4340-4390`)就是 `{src, rowBytes, rows, slices, srcRowStride, srcSliceStride, offset}`,且注释明说 ring 路径把区域**紧密重打包**、因此完全不发 `glPixelStorei`。所以 split 的自然形态就是"永远走紧密重打包 + 描述符",与 ring 路径同构。
|
||||
**这项工作从 v1 的"原地不动"移出,计入子系统 5 的天数**(§6.4),并加一个 Mali 设备门发布 box-vs-rect 作业数与帧时增量。
|
||||
|
||||
#### 4.5.7 `MGPDrawInfo` 与 `MGHostSpan`
|
||||
|
||||
```cpp
|
||||
struct MGPDrawInfo { // = pipe_draw_info
|
||||
Uint32 mode;
|
||||
Uint8 indexSize; // 0 = arrays,否则 1/2/4
|
||||
Uint8 flags; // kHasUserIndices | kPrimitiveRestart | kIndicesAreClient |
|
||||
// kHasIndexRange | kHasXfbCount
|
||||
Uint16 pad;
|
||||
Uint32 instanceCount, startInstance;
|
||||
Uint32 restartIndex;
|
||||
MGPipeHandle indexResource;
|
||||
// 以下三项**由 flags 门控**,只在有消费者时才计算与携带(v2)
|
||||
Uint32 minIndex, maxIndex; // kHasIndexRange;client 计算,~0 = 未知
|
||||
Uint64 xfbCpuCapturedVertices; // kHasXfbCount;GetTransformFeedbackCapturedVertices()
|
||||
MGHostSpan userIndices; // kHasUserIndices;否则不进变长尾
|
||||
};
|
||||
struct MGPDrawRange { Uint32 start, count; Int32 indexBias; }; // = pipe_draw_start_count_bias
|
||||
```
|
||||
|
||||
**v2 成本诚实化**:今天的 `DrawArrays(GLenum, GLint, GLsizei)` 是三个寄存器实参(`BackendObject.h:117`)。替换成一个 ~48 B 的固定头(含 handle)加按需的变长尾。`minIndex/maxIndex` 今天**只**在 client-memory 数组路径算(`TryComputeMaxIndexFromHostBytes`,`VulkanRenderer.cpp:3407-3470`,用于 `:3599`),`xfbCpuCapturedVertices` 今天**只**在 XFB scatter 路径读(`DirectGLES.cpp:900`)——所以两者由 `flags` 门控,**不是每 draw 都算**。`userIndices` 的 32 B `MGHostSpan` **移出固定头进变长尾**,让 VBO 路径(MC/Sodium 的全部 draw)不为它付字节。**每 draw payload 字节数进 P0 的计数器直方图**(`cmd-records` 是逐帧的,这里要逐 draw 的分布,它才是 `SEG_CMD` 的定尺依据)。
|
||||
|
||||
**`MGHostSpan` 是整份接口里唯一一个"形状随传输而变"的东西**:
|
||||
|
||||
```cpp
|
||||
struct MGHostSpan { // 32 B
|
||||
const void* ptr; // monolith:指向前端 shadow / 应用内存。split:nullptr
|
||||
Uint64 size;
|
||||
Uint32 seg; // split:SEG_STAGE id,或 kFromServerIndexMirror
|
||||
Uint32 pad;
|
||||
Uint64 offset;
|
||||
};
|
||||
inline const void* MGPipeHostBytes(const MGHostSpan&); // 一次可预测分支
|
||||
```
|
||||
|
||||
**v2 修订的消费者表**(与 §5.8 一致,解决 v1 §4.5.7 与 §5.8 互相矛盾的问题):
|
||||
|
||||
| 消费者 | 今天的站点 | 归属 | monolith 填法 | split 填法 |
|
||||
|---|---|---|---|---|
|
||||
| client 顶点数组 | `Managers.cpp:2500-2592`、`VulkanRenderer.cpp:3737` | **client 供字节** | `ptr = attrib.Offset` | tracker 暂存同样范围进 `SEG_STAGE` |
|
||||
| client 索引数组 | `DirectGLES.cpp:4425-4442`、`VulkanRenderer.cpp:3418-3433` | **client 供字节** | `ptr = indices` | 暂存 `count*indexSize` |
|
||||
| indirect / parameter 命令块 | `DirectGLES.cpp:4655-4695`、`:4768-4793`、`VulkanRenderer.cpp:12045` | **client 解析计数** | `ptr` 指向 shadow | tracker **解析出计数**并发解析后的 `MGPDrawRange[]`(几十字节) |
|
||||
| **restart 重写 / multi-draw 展平的索引字节** | `DirectGLES.cpp:4412-4415`、`MultiDraw.cpp:498-540`、`VulkanRenderer.cpp:4159` | **server 拥有变换**(D-B7) | `ptr` 指向前端 shadow | `seg = kFromServerIndexMirror`:**server 从自己的索引宿主镜像取**,零线上流量;镜像超预算时退化为 client 逐 draw 暂存并计数 |
|
||||
|
||||
**monolith 代价**:一次可预测分支 + 变长尾里的 32 B(仅 `kHasUserIndices` 时)。它顺带消灭"backend 在 draw 中途回头调前端 reconcile"的大部分:20 处 `SyncPersistentMappedRange` + 6 处 `SyncGpuWrites` 里,凡消费者搬到 client 的那些改由 **tracker 在填 span 之前**做同一次 reconcile(**逐站点对照见 §5.8.1,不是一条笼统规则**)。
|
||||
|
||||
### 4.6 与 gallium 的对应与偏离(十条,逐条记名)
|
||||
|
||||
| # | gallium | MGPipe | 理由(证据) |
|
||||
|---|---|---|---|
|
||||
| **D1** | `create_*_state` 返回 driver 指针 | **调用方提供 handle** | 零创建 round trip;handle 是稠密 slot;退役全部 D 类指针 memo |
|
||||
| **D2** | `get_param(cap)`、`is_format_supported(...)` 逐项查询 | **一个 `MGPCaps` POD + 一张稠密 format 表** | `DynamicBackendParameters` 与 `FormatCapabilityCache` 本来就是平坦结构 |
|
||||
| **D3** | CSO 切分是 D3D10 时代的 | **CSO 边界跟 Vulkan 动态状态走** | `RenderState.h:519-528` 记录共用一个版本号让 `glViewport` 冲掉 pipeline memo **和** draw 快路径;`m_pipelineStateVersion`(`:529`)恰好是 CSO 相关子集;Magma 的 `DynamicStateShadow` 与 `ApplyDynamicDrawStateTail` 已经这么切 |
|
||||
| **D3b(v2 重写)** | 三个独立 CSO:blend / depth_stencil / rasterizer | **一个 `RenderStateCso`,传输是整块 chunk,身份是 pipeline 子集,动态子集走 `set_dynamic_state`** | 整块的理由:`is_trivially_copyable_v` 断言(`DirectGLES.cpp:2035`)、三段 memcmp(`:2038-2047`)、**字段顺序承重**(`RenderState.h:359-368`)、两个 backend 都按 span/bulk 消费。子集身份的理由:整块内容寻址会让 `glViewport` 铸造新 CSO 并冲掉 pipeline memo——即 D3 要防的那次回归。完整性由 G7 的 setter 一致性测试保证 |
|
||||
| **D4** | `transfer_map`/`transfer_unmap`(scoped) | **`resource_subdata` 推送 + `map_persistent`(永久地址空间捐赠)** | `AcquirePersistentMap`(`BufferObject.h:102-118`)把指针交给**应用**;≥16MiB 自动走到(`:226-228`)。实测 p99 163→21ms |
|
||||
| **D5** | driver 看得见压缩格式与 pixel-unpack 状态 | **两者都不存在** | 前端在 `glTexImage` 时解析压缩 internalformat(`GL_Texture.cpp:298-306`);`ScopedDefaultUnpackState`(`Managers.cpp:2888-2910`)强制 unpack 默认值。**只有 PACK 方向过线** |
|
||||
| **D6** | 默认 uniform block = `constant_buffer 0` | **独立入口 `set_global_constants`** | `SpirvArtifacts::globalUboScratch`(`ProgramObject.h:1418`)是 link **phase B** 产出的 CPU 数组,布局由**优化后**的 SPIR-V 决定(`:1400-1408`)。它没有 GL name、没有 `BufferObject`、没有 `PipeResource` |
|
||||
| **D7** | `pipe_shader_state` = tokens → 完成的 handle | **handle + server 侧惰性特化**,variant 键取自**已推送**状态 | D-B2 的 8 个输入。这其实**就是** gallium(Mesa 的 `st_variant` 也按已绑定状态键控) |
|
||||
| **D8** | `pipe_context::flush` + fence 是唯一反向通道 | **`MGPipeCallbacks`**:10 个具名回复/事件(§7) | gallium 没有 shadow writeback、GPU-write 通知、纹理重发请求/终止、default-FB 几何这些词汇 |
|
||||
| **D9** | `set_viewport_states(start_slot, num)` | **float 数组 + 独立的 `writtenMask`** | viewport 是 **float**(`RenderState.h:229-237`:`KHR-GL43.viewport_array.viewport_api` 用 `==` 无容差);scissor 必须单独带 `ScissorBoxWrittenMask`(`:363`),因为 `glScissor(0,0,0,0)` 是合法 GL、意思是"拒绝每个片元"(`:352-362`) |
|
||||
| **D10(v2 新增)** | 纹理参数(swizzle / base-max level / dsMode)住在 `pipe_sampler_view` 里 | **`set_texture_params(res, …)` 独立,`MGPSamplerView` 只带视图限制** | 一张只作 FBO attachment / image 单元 / CopyImage 端点的纹理没有 sampler view,但 Espryt 对 attachment 也调 `SyncTextureParamsToBackend`(`DirectGLES.cpp:1580-1601`),且 `RequireImageBindableStorage` 要在前端 params 版本不动的情况下强制重同步(`Managers.cpp:2815-2821`) |
|
||||
|
||||
**没有 `pipe_transfer`、没有 `set_pixel_unpack_state`、没有压缩格式概念、renderbuffer 不折进纹理、`set_sampler_views` 没有 stage 维度。**
|
||||
|
||||
### 4.7 覆盖论证
|
||||
|
||||
#### 4.7.1 对 477 读点分类的逐类映射
|
||||
|
||||
| delta 类 | n | 满足它的 MGPipe 调用 | 残余 |
|
||||
|---|---|---|---|
|
||||
| handle 化(wire 句柄) | 167 | 每个命名对象的调用签名里的 `MGPipeHandle` | — |
|
||||
| RenderStateBlob | 99 | `create/bind_render_state` + `set_dynamic_state` | — |
|
||||
| ObjectBind:Texture / Sampler | 33 | `set_sampler_views` + `bind_sampler_states` | — |
|
||||
| ObjectBind:Buffer | 29 | `set_vertex_buffers` / `set_index_buffer` / `set_indirect_buffers` | — |
|
||||
| ObjectBind:BufferRange | 24 | `set_shader_buffers` / `set_stream_output_targets` | **Uniform 类另带 host payload**(D-B8) |
|
||||
| FboAttach + DrawBuffers + ReadBuffer | 19 | `set_framebuffer_state` | — |
|
||||
| Buffer ops delta | 17 | `resource_*` 全族 | — |
|
||||
| XfbOp | 15 | `set_stream_output_targets` + `*_stream_output` | — |
|
||||
| ObjectBind:Image | 14 | `set_shader_images` | — |
|
||||
| ObjectBind:VAO | 12 | `bind_vertex_elements_state` + `set_vertex_buffers` + `set_index_buffer` | — |
|
||||
| ObjectBind:Program | 10 | `set_draw_program` / `set_dispatch_program` | — |
|
||||
| TexParam / SamplerParam | 9 | **`set_texture_params`** + `create_sampler_state` + `create_sampler_view` | **v2 修正归属**(D10) |
|
||||
| Texture state(dirty level/rect) | 7 | `resource_subdata`(带步长描述符) | **归属反转**(§7.3) |
|
||||
| PixelStoreBlob | 6 | `set_pixel_pack_state` | unpack **删除** |
|
||||
| client-resolved(error queue) | 6 | `on_gl_error` 回调(§7) | — |
|
||||
| ProgramPublish | 3 | `create_shader_state` | 依赖 P0.5 |
|
||||
| client-resolved(validation) | 3 | client 自答 | — |
|
||||
| CurrentAttrib | 2 | `set_vertex_attrib_defaults` | — |
|
||||
| client-resolved(compile env) | 2 | `on_caps_invalidated` | — |
|
||||
| Patch 参数 | — | `set_patch_state` | 同时是 variant 输入 |
|
||||
| 条件渲染 | — | **client 解析,永不过线** | `Core.h:387-391` |
|
||||
| XFB CPU 计数 | — | **纯 client**;`MGPDrawInfo::xfbCpuCapturedVertices`(flag 门控) | — |
|
||||
| backend 重铸纪元 | — | **无 client 对应物**:`MGGen`,server 私有 | — |
|
||||
|
||||
那 1997 个前端 getter 站点不是第二个面:89 个纯版本读**根本不过线**,72 个数据字节读全部落在 §5.7/§5.8 与 `MGHostSpan`,38 个 `GetLifetimeId()` 变成 handle。
|
||||
|
||||
#### 4.7.2 覆盖论证不是这张表,是这三道门(v2:从两道增至三道)
|
||||
|
||||
上表是**声明**。证明是机械的:
|
||||
|
||||
**门 A —— include 图门(v2 新增,取代 v1 单靠 `nm` 的那半)。**
|
||||
v1 说 `MG_Backend` 只允许 include "一张共享**值**头白名单(`RenderState.h` 的 `RenderStateParameters`、`SamplerObject.h` 的 `SamplerParameters`、…)"。**实测这张白名单不是叶子集**:`RenderState.h:12` include `FramebufferState/FramebufferObject.h`,后者 `:12-13` 再 include `TextureState/TextureObject.h` 与 `RenderbufferState/RenderbufferObject.h`;依赖是结构性的——`RenderStateParameters` 用 `FramebufferObject::MAX_DRAW_BUFFERS` 给两个数组定长(`RenderState.h:263, 273`)。所以"把 `RenderStateParameters` 交给纯净的 `MG_Backend`"会把整张 framebuffer/texture/renderbuffer 类图一起拖进来。**而 `nm --undefined-only` 看不见这个**:只 include 而不调用其成员函数的类不产生未定义符号,门可以在 include 图完全耦合的情况下为绿。
|
||||
**修正**:P0.5 交付 `MG_Pipe/MGPipeValueTypes.h`——把 `MAX_DRAW_BUFFERS`、`PerBufferBlendState`、`StencilFaceState`、`PixelStoreParameters`、`RenderStateParameters`、`SamplerParameters`、`BorderColorForm`、`VertexAttribute` 与相关枚举搬进去,**它不 include `MG_State/GLState` 的任何东西**;`RenderState.h`/`SamplerObject.h`/`VertexArrayObject.h` 反过来 include 它。门变成:
|
||||
|
||||
> **在 disaggregated 配置下编译 `MG_Backend` 时,把 `MG_State/GLState` 从 include 搜索路径里移除**(或对 `-H` 输出断言)。这是唯一一条能因它存在的理由变红的检查。
|
||||
|
||||
**门 B —— 符号门。** `nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空。保留,作为门 A 的补充(它能抓到通过前置声明+跨 TU 调用绕过 include 图的情况)。
|
||||
|
||||
**门 C —— 未声明门。** 在 `MOBILEGL_PIPE_PUSH=all` **且非 verify** 构建里,`MG_State::pGLContext` **未声明**。任何接口没满足的读是一次**指名文件与行号的编译错误**。strangler 结束时 `grep -c 'pGLContext' MG_Backend/` == 0(**grep `pGLContext` 不是 `pGLContext->`**,因为还有 58 行非箭头用法)。**这条门只跑非 verify 构建**(D-B5:verify 构建保留 `SnapshotFromGLContext()`)。
|
||||
|
||||
**这三道门比生成一张 477 行的清单严格得多:它们禁止那次读,而不是给它编目,而且不会过期。** 那份 inventory 保留为 tracker 侧覆盖检查表(G6,CI `git diff --exit-code`,0 UNMAPPED)。
|
||||
|
||||
#### 4.7.3 21 条 D 类身份 memo 的重键表
|
||||
|
||||
| # | 今天的键 | 守什么 | MGPipe | 净效果 |
|
||||
|---|---|---|---|---|
|
||||
| D1 | `StateBackendObjectRegistry` 用裸 `StateObject*` + 同址 `weak_ptr`(`Managers.h:282-325`)×6 | 分配器地址复用;**也是唯一的删除信号** | 按 slot 索引的数组 + `gen` 比较;显式 `resource_destroy` | GC(1024/64 阈值)**删除** ×6 |
|
||||
| D2 | `TwinLookupMemo` ×3 + `OwnerEquals`(`DirectGLES.cpp:62-131`) | 复用堆地址命中 memo 槽 | **删除**——数组下标**就是**查表 | ~75 行 + 140KiB |
|
||||
| D3 | `UnitTextureSyncEntry` + `PairingsIntact`(`:1441-1481`) | 不移动任何计数器的 slot 交换(DSA by-name) | **server 侧删除**;**去抖搬到 client**(§2.5:`set_sampler_views` 的 client 侧 hash 抑制器,否则冗余 `glBindSampler` 会 per-batch 重发) | server −115 行 / client +~60 行 |
|
||||
| D4 | `IsBufferDrawClean` 身份优先比较(`Managers.cpp:1436`) | respecify 交给前端一个**新**资源 | server 拥有资源表;`gen` 比较;`GetChangeSerial()`(`Uint64`,不回绕)继续过线 | 简化 |
|
||||
| D5 | `ResolvedDrawBuffers::iboFrontend`(`Managers.h:711-716`) | 索引 slot 重绑而无 epoch/config 移动 | `set_index_buffer` 是独立调用 | 结构性 |
|
||||
| D6 | `m_syncedIndexBufferObject` 陪一个回绕 `Uint16`(`:775-780`) | 版本回绕后换了个 buffer | `{slot, gen}` 比较,不回绕 | 结构性 |
|
||||
| D7 | `StampSyncedFBO` 四元组(`DirectGLES.cpp:1856-1901`);`packed_pixels` postmortem `:2815-2827` | 版本回绕 + backend 侧纹理重铸 | `MGPFramebufferState::contentHash` + server 私有 `attachmentRemintEpoch`(`MGGen`) | 一次 64 位比较 |
|
||||
| D8 | `g_fboTextureSyncList`(`:1580-1601`) | 同 D3,针对 attachment | server 侧删除;由 `contentHash` 在 client 侧抑制 | server −20 行 |
|
||||
| D9 | `ResolvedTextureBindingMemo`:9 个键 + 驱动绑定影子的 `memcmp`(`:3218-3291`) | 任何未枚举的写者扰动某个 unit | `(shaderCso.slot, viewSetSerial)` 两字比较;`viewSetSerial` 由 server 在 `set_sampler_views` **内部** ++。**前提是 client 侧的 hash 抑制器已经挡住冗余推送**,否则这个 serial 每个 batch 都动 | 更便宜(有前提) |
|
||||
| D10 | `UnitSamplerLookupMemo` 的 `WeakPtr` owner 测试(`:3105-3125`) | 死 sampler 复活 | 数组下标 | 删除 |
|
||||
| D11 | `VertexInputStateFactory::ComputeHash` 混入 `GetLifetimeId()`(`:38-49`) | 复用 buffer 地址重现整个 content hash | CSO handle **就是**身份;`gen` **混进** server 侧每个 content hash | 删除一整类 |
|
||||
| D12 | `SetBackendStateMemo(&entry, evictionEpoch)`:**前端 VAO 里存后端堆裸指针**(`VertexInputStateFactory.cpp:78`) | table 淘汰 | **直接删除,不翻译** | — |
|
||||
| D13 | `VaoDrawMemo` 槽(`VulkanRenderer.h:1230-1245`) | ABA | CSO handle | 2 字 |
|
||||
| D14 | `SetupDrawSnapshot` 的三组 `(ptr, lifetimeId, version)` + **有损的** `sampledContentSum`/`sampledParamsSum` | 一切 | 三个 handle + 两个 server 纪元 + dirty mask | ~14 个探测字段 → 1 次比较;**顺带消灭一类哈希碰撞** |
|
||||
| D15 | `m_rpFast*`(`VkRenderPassManager.h:305-320`) | ABA | `contentHash` + `MGGen` | 1 次比较 |
|
||||
| D16 | `VkTextureManager::TextureIdentity` + `GetTextureObject(name)` 存活探测(`VkTextureManager.cpp:806-819`) | 名字复用 / 删了但仍被 FBO 引用 / 默认纹理 | `{slot, gen}` + 显式 destroy | 三种失效模式一起消失 |
|
||||
| D17 | `VkClearManager::TextureIdentity`(`VkClearManager.h:76-83`) | ABA | `{slot, gen}` | — |
|
||||
| D18 | 纹理/renderbuffer 资源用**节点式** `std::unordered_map`(postmortem `VkRenderPassManager.h:375-397`) | 扩表搬迁使缓存的 `Resource*` 失效 | **UNCHANGED。** 接口零约束;这是 server 内部分配纪律。**postmortem 注释必须逐字带进 review checklist** | 保留 |
|
||||
| D19 | `ProgramFactory::m_cacheStructureEpoch` | 守 server 内部裸指针 | **UNCHANGED**(`MGGen` 族) | 保留 |
|
||||
| D20 | `ConvertedVertexStreamKey` + **纯为防地址复用**持有的 `SharedPtr sourcePin` | ABA | server 拥有资源;`changeSerial` 过线 | **pin 删除** |
|
||||
| D21 | `m_xfbCounterSlotByObject[GetBoundTransformFeedbackName()]`(`VulkanRenderer.cpp:11136-11146`) | **什么都没守——活的潜伏 bug** | XFB 对象 handle | **顺带修一个 bug**,先独立落 `dev` |
|
||||
|
||||
**总计:11 条直接删除,2 条(D3/D8)server 删除但去抖搬到 client,7 条重键成更便宜的比较,1 条(D18)原样不动。**
|
||||
|
||||
---
|
||||
|
||||
## 5. 前端 state tracker
|
||||
|
||||
### 5.1 推送发生在哪里——本设计里最容易做错的一个决定
|
||||
|
||||
**不在 GL setter 里。** `glEnable(GL_BLEND)` 绝不调 `bind_render_state`。Blaze3D 每个 batch 都用它包住,代码自己标注它是最热的路径(`DirectGLES.cpp:2029-2032`)。天真的 per-setter 推送把每一次冗余开关变成一次接口调用加一次 server 侧 CSO 查表——**严格慢于今天**。
|
||||
|
||||
**在 verb 之前的 validate 时刻。**
|
||||
|
||||
```cpp
|
||||
// MG_Impl/Pipe/Tracker.h
|
||||
class MGPipeTracker {
|
||||
public:
|
||||
// 每一类 verb 一个入口;由 PipeCalls.def 的 kCtxVerb / kCtxObject 条目生成(§6.2.1)
|
||||
void ValidateForDraw(const MGPValidateHint&); // 20 个 GL draw 入口
|
||||
void ValidateForDispatch(); // glDispatchCompute*
|
||||
void ValidateForClear(GLbitfield); // framebuffer + 渲染状态(ClearColor 在其中)
|
||||
void ValidateForBlitOrCopy(); // framebuffer + pack state
|
||||
void ValidateForTextureOp(MGPipeHandle res); // GenerateMipmap / CopyTex* / BindImageTexture
|
||||
void ValidateForReadback(); // ReadPixels / GetTexImage
|
||||
void ValidateForXfbSpan(); // Begin/End/Pause/Resume TransformFeedback
|
||||
void ValidateForQuery(); // query begin/end
|
||||
private:
|
||||
Uint64 m_dirty;
|
||||
Uint64 m_lastPushed[kGroupCount];
|
||||
Uint64 m_lastSetHash[kVarTailGroupCount]; // ★ kVarTail set_* 的发射抑制器(§2.5)
|
||||
};
|
||||
```
|
||||
|
||||
**这八个入口不是随手列的**:`MG_Impl` 用到 **70 个不同表项 / ~93 个调用点**,其中只有 ~22 个是 draw/dispatch,其余 ~48 个是纹理操作、回读、blit、clear、XFB 跨度、query——**而它们中很多自己就读 `pGLContext`**(§2.1(a) 列了具体行号)。v1 只给 4 个 validate 入口、只在两处填快照,会让第一个 `glGenerateMipmap`/`glReadPixels` 撞上 poison Fatal,`MOBILEGL_PIPE_VERIFY` 的全绿验收因此不可达。
|
||||
|
||||
#### 5.1.1 哪些操作在 GL 调用时刻推送(v2 修正推论 1)
|
||||
|
||||
**规则的正确措辞**:
|
||||
|
||||
> **只有今天就在 GL 调用时刻分发的资源 op 在 GL 调用时刻推送**——即 `BufferBackendOps` 的七个 hook(`BufferObject.h:70-71` 自己写着"在 GL 调用时刻分发,就在 shadow 拷贝刚更新之后")。**纹理 subdata 不在此列。**
|
||||
|
||||
理由:`glTexSubImage*` **根本不调 backend 表**(`GL_Texture.cpp` 只有 3 处 `MarkStorageDirtyRegion`),全部纹理上传由 Espryt 在 sync 时刻按**累积**区域做,那里才跑 96-rect 级联合并与 union-box 回退,并在 unpack ring 可用时刻意塌成一个 box(`Managers.cpp:4386-4390`,实测 +6 ms/frame)。逐 `glTexSubImage` 发一条 `resource_subdata` 精确复现那个 ~100 作业的形状。
|
||||
|
||||
**因此纹理路径的形态是**:client 在自己的 `MipmapStorage` rect 模型里累积(§7.3 的发射游标),在**下一个 validate / flush 点**把合并后的形状作为**一条** `resource_subdata`(带 union box + region 列表)发出。`MOBILEGL_PIPE_STATS` 必须把逐帧 `resource_subdata` 发射次数单列一类,并在 MC 动画图集 fixture 上设上限。
|
||||
|
||||
**稳态成本**:见 §10.2(v2 已按动态口径重写)。
|
||||
|
||||
### 5.2 dirty bits:值类零新增记账,对象类新增 5 个聚合世代(推论 4)
|
||||
|
||||
| dirty 位 | 类别 | 快门来源 |
|
||||
|---|---|---|
|
||||
| `NEW_RENDER_STATE` / `NEW_PIPELINE_STATE` | 值 | `m_version` / `m_pipelineStateVersion`(`RenderState.h:522, 529`;bump 点 `RenderState.cpp:311-312` 等) |
|
||||
| `NEW_PIXEL_PACK` | 值 | `PixelStoreParameters`(`RenderState.h:190-199`) |
|
||||
| `NEW_PATCH_STATE` | 值 | patch 三字段,用 `BitwiseEqual` 比较(NaN 合法,`DirectGLES.cpp:2807-2814`) |
|
||||
| `NEW_VERTEX_ATTRIB_DEFAULTS` | 值 | `GetCurrentVertexAttribute` |
|
||||
| `NEW_VERTEX_ELEMENTS` | 值 | `VertexArrayObject::GetConfigVersion()`(`Uint32`,`:155`) |
|
||||
| `NEW_VERTEX_BUFFERS` | **对象** | **`VertexArrayState::m_anyVaoAttributeGeneration`**(新增)→ 命中后走 32 属性前缀 + 逐属性 `VertexAttributeVersion`(`:66-70`) |
|
||||
| `NEW_INDEX_BUFFER` | **对象** | 索引 slot `GetVersion()`(回绕 `Uint16`)+ 绑定对象 `{slot,gen}` |
|
||||
| `NEW_FRAMEBUFFER` | **对象** | **`FramebufferState::m_anyAttachmentGeneration`**(新增)+ `GetObjectVersion()` + slot 版本 → 命中后重算 `contentHash` |
|
||||
| `NEW_SAMPLER_VIEWS` | **对象** | **`TextureState::m_anyTextureContentGeneration` + `m_anyTextureParamsGeneration`**(新增)+ `GetTextureBindGeneration()` + `GetSamplingResolutionGeneration()` → 命中后走 `GetMaxTouchedUnit()` 前缀、重算集合 hash、**hash 未变则不发** |
|
||||
| `NEW_SAMPLERS` | **对象** | `SamplerObject::GetVersion()`(回绕 `Uint16`,`SamplerObject.h:155`)+ 上面的聚合 |
|
||||
| `NEW_SHADER_IMAGES` | **对象** | `ImageTextureBinding::Version`(`TextureState.h:24, 34`)+ `m_anyTextureContentGeneration` |
|
||||
| `NEW_SHADER` | 值 | `GetLinkVersion()` + `GetImageUnitVersion()`(`ProgramObject.h:844, 906`) |
|
||||
| `NEW_SHADER_BINDINGS` | 值 | `GetBackendStateVersion()`、`GetBlockBindingVersion()`、`GetUniformWriteSetVersion()` |
|
||||
| `NEW_GLOBAL_CONSTANTS` | 值 | `GetUBOContentVersion()`(`~0u` 跳过回绕,`:791-794`) |
|
||||
| `NEW_CONST_BUFFERS` / `NEW_SHADER_BUFFERS` / `NEW_SO_TARGETS` | **对象** | **`BufferState::m_anyBufferChangeGeneration`**(新增)+ slot 版本 → 命中后走 `GetTouchedBindPointCount()` 前缀 |
|
||||
|
||||
**五个新增聚合世代**(`TextureState` 两个、`BufferState`、`VertexArrayState`、`FramebufferState` 各一)**全部落在既有 bump 点上,合计约 20 行**。它们把对象类组的快门从"每 validate 走查 192 个单元 / 84×4 个绑定点 / 32 个属性 / 40 个 attachment"降成一次 `Uint64` 比较;只有快门为真时才走 touched 前缀并重算集合 hash。
|
||||
|
||||
**完整性由 `gen_pipe_dirty_surface.py` 保证**(推论 4):它枚举 `MG_Impl/GLImpl/**` 里每一个会改变某组的 mutator,映射到必须 bump 的聚合世代,CI 重生成 + `git diff --exit-code`,**未映射的 mutator 直接失败**。这是 `PLAN.md` 的 `gen_impl_mutation_surface.py` 的改造版(replay 义务消失、标记义务出现),也是 B-R6 的第四层。
|
||||
|
||||
**三个回绕的 `Uint16` 在 tracker 边界加宽。** `m_lastPushed[]` 是 tracker 自己的字段,加宽到 `Uint32`/`Uint64` **不需要改 `MG_State` 一行**;同时 handle 与它同行过线。**回绕在 tracker 本地是无害的**(一次回绕造成一次多余的重推,永不漏推),何况集合 hash 抑制器会把多余重推吞掉。
|
||||
|
||||
### 5.3 每命令 validate 的**不变式**(v2:从"固定顺序契约"降级)
|
||||
|
||||
**规范条款(D-B3 v2)**:
|
||||
|
||||
> 一条 verb 的全部 `set_*`/`bind_*` 必须在该 verb 之前完成;server 在 verb 处、从它此刻持有的全部已推送状态特化 shader 与 pipeline。除"资源 create 先于对它的 bind"外,`set_*` 之间**没有**顺序要求。
|
||||
|
||||
**推荐实现顺序**(便于 tracker 的代码组织与 dirty 位遍历,**不是**正确性契约):
|
||||
|
||||
```
|
||||
1 set_framebuffer_state
|
||||
2 set_draw_program(create_shader_state 在 link 时刻已发)
|
||||
3 set_texture_params / set_sampler_views / bind_sampler_states / set_shader_images /
|
||||
set_shader_buffers / set_global_constants
|
||||
4 bind_render_state(未命中时先 create_render_state)/ set_dynamic_state
|
||||
5 bind_vertex_elements_state / set_vertex_buffers / set_index_buffer / set_vertex_attrib_defaults
|
||||
6 set_patch_state / set_stream_output_targets
|
||||
7 draw_vbo
|
||||
```
|
||||
|
||||
**退役 workaround 的机制是惰性特化,不是调用顺序**:`DirectGLES.cpp:2712-2732` 的 fragColor 重推导与 `g_broadcastMemo*` 之所以能删,是因为 server 在 **verb 处**才特化,那时 `set_framebuffer_state` 一定已到;同理 `ImageUnitFormatsStillMatch`(`Managers.cpp:6545-6573`,注释明说"不可表达为单调版本")由 `set_shader_images` 在 verb 之前告知。**v1 把这归因于"framebuffer 严格第一",但它自己把 images 排在 program 之后——那个论证站不住,结论仍然成立。**
|
||||
|
||||
`create_shader_state` **从编译池的终止 continuation 发出**(`JobNode.h:109-123`),不是从 draw 发出,这样 SPIR-V 在用到它的第一个 draw 之前就到达 server。这是 monolith 拿不到的异步收益。
|
||||
|
||||
### 5.4 合并:保留代码库已经发现的三条,加上第四条
|
||||
|
||||
1. **整块结构优于逐字段。** Magma 的 `ComputePipelineStateHash`(`VulkanRenderer.cpp:4818-4826`)已经把 ~17 次 accessor 调用换成一次 bulk fetch;Espryt 的三段 memcmp 同理。
|
||||
2. **高水位标记。** `BufferState::TouchBindPoint` / `GetTouchedBindPointCount`(`BufferState.h:51-62`,每 target 84 个绑定点)与 `TextureState::NoteUnitTouched` / `GetMaxTouchedUnit`(`Core.h:124-126`,192 个单元)**必须留在 tracker 的走查里**,它们直接就是 `set_shader_buffers` / `set_sampler_views` 的 `count` 实参。
|
||||
3. **只发 program 解析过的集合**,用 `LinkArtifacts::uniformSamplerOrImageUnitIndex`(`ProgramObject.h:1298`)。两个 backend 今天已经在算(`ResolveAndBindUnitTextures`,`DirectGLES.cpp:2973`;`UniformManager::CollectSampledTextures`)。
|
||||
4. **(v2 新增)集合 hash 抑制器。** 每一条 `kVarTail` 的 `set_*` 在 client 侧算一次已解析集合的 xxHash,与 `m_lastSetHash[]` 比较,**未变就不发**。这是 §2.5 里那 ~175 行去抖搬到 client 后的载体,也是 D9 的前提——没有它,`GetTextureBindGeneration()` 在冗余重绑时的 bump(`DirectGLES.cpp:1414-1420`,26.2 每次纹理单元切换都重绑同一个 sampler)会让每个 batch 重发一条几百字节的变长记录并冲掉 server 的两个 memo。
|
||||
|
||||
**索引绑定的范围必须在 validate 时刻实时解析,不是在 bind 时刻快照。** `BindingSlotRange1D::GetRange()` 对整 buffer 绑定返回 `Range1D(0, object->GetSize())`,因为 `glBindBufferBase` 之后再 `glBufferData` 是普通应用代码。
|
||||
|
||||
### 5.5 sampler view 在 client 侧解析
|
||||
|
||||
GL 是**每个 unit 每个 target 各一个绑定**(`TextureUnit.h:20, 24-25`;`TextureState::m_textureUnits` 是 `Array<TextureUnit, 192>` **按值**存放,`TextureState.h:128`,每 stage 广告上限 32,`:46`),shader 看见哪一个取决于 sampler uniform 的声明类型、mipmap 完备性(`IsMipmapCompleteForFilter`,`TextureObject.h:309`;`SamplesAsIncompleteTexture`,`:315`)和 `IsUndefinedDefaultTexture`(`:329-332`)。**gallium 的"每槽一个 view"就是解析后的形态。**
|
||||
|
||||
**解析留在 client**,并且 client 必须为它保留一个自己的 memo(§2.5 的 ~40 行搬迁项),否则每 draw 重跑完备性规则。**合并单元空间,无 stage 维度**(§4.4.3)。
|
||||
|
||||
**两处 backend 特定的后处理留在 server**,作用在已解析的集合上:Espryt 的 raw-depth-fetch sampler 替换(`DirectGLES.cpp:3540-3546`)与 Magma 的 feedback-loop 检测(对着 draw FBO,`UniformManager.cpp:554`)。两者都可从已推送的 `set_framebuffer_state` + view 集合判定。
|
||||
|
||||
### 5.6 对象生命周期、共享组与 composite pipeline program
|
||||
|
||||
#### 5.6.1 生命周期
|
||||
|
||||
`resource_create` 在**前端对象构造**时发,存储由 `resource_respecify` 惰性定义。`resource_destroy` 在前端对象析构时发。三条顺序约束:
|
||||
|
||||
- **view 先于其存储属主销毁**:`GetViewStorageOwner()`(`TextureObject.h:96-100`)→ `MGPResourceDesc::viewOf` + server 侧 keep-alive。
|
||||
- **FBO attachment 钉住纹理**(`FramebufferObject.h:95`)→ `set_framebuffer_state` 的 surface handle 隐含 server keep-alive。
|
||||
- **buffer texture 钉住 buffer,范围实时解析**(`TextureObjectBuffer.h:28, 35-46`)→ `MGPResourceDesc::{bufferForTexBuffer, bufOffset, bufSize}`。
|
||||
|
||||
#### 5.6.2 共享组
|
||||
|
||||
v1:一个 screen、一个 context、一个扁平 handle 空间、一条 flow。`eglMakeCurrent` 是 flow 所有权转移,在既有 `EGLOperationMutex`(`EGLImpl.cpp:241`)下发射——**顺手修今天不取该锁的两个入口**:`ReleaseThread`(`:341-350`)与 `SwapInterval`(`:435-450`)。
|
||||
|
||||
#### 5.6.3 composite pipeline program:判过死刑的那个反对意见,答案是"什么都不用做"
|
||||
|
||||
`GLContext::GetProgramForDraw()`(`Core.cpp:592`)**今天就已经完全在前端**完成合成:join 每个 stage 的 `JoinLinkAndSpirv()`、按 `ComputeDrawProgramSignature()`(`:630`)查 cache、miss 时构造**故意不命名**的 `MakeShared<ProgramObject>(0u)`(`:644`)、挂上每个 stage 被钉住的 linked snapshot、重装捕获 stage 的 XFB varyings、`Link(true)`、缓存、`RefreshCompositeUniforms`。
|
||||
|
||||
tracker 调它,拿到 `SharedPtr<ProgramObject>`,推**一个 handle**。合成体没有 GL name,但**有 lifetimeId**,slot 从 `ShaderCso` 的保留高位段分配。生命周期:pipeline cache 淘汰该条目时释放 slot、`gen++`、发 `delete_shader_state`——`CompositeResolver.cpp` 里三行。
|
||||
|
||||
**合成体从不过线、从不被重新实现,`PLAN.md` 提议的 `SetReplicaResolvedDrawProgram` 钩子完全不需要。** 副带收益:阻塞的 `JoinLinkAndSpirv()` 彻底离开 server 的 draw path。
|
||||
|
||||
### 5.7 program artifacts 与全局 UBO scratch
|
||||
|
||||
**`create_shader_state` 的 payload 是 SPIR-V + 全结构体反射归档**(§4.5.5),不是源码。**依赖 P0.5 的头文件抽取。**
|
||||
|
||||
**SPIRV-Cross 留在 server**(`TranspileSpirvToEssl`,`Managers.cpp:6575`):它消费 SPIR-V 加设备事实。**glslang 留在 client。** 这是一次文件级切割。
|
||||
|
||||
**全局 UBO scratch 走独立入口**(D6):`set_global_constants(shaderCso, MGPBlobRef bytes, Uint32 version)`,键 `(shaderCso.slot, uboContentVersion)`,复现 `DirectGLES.cpp:3369-3392` 的"每 program 每帧至多一次"。
|
||||
|
||||
**具名 UBO 字节走 `set_shader_buffers` 的 host payload**(D-B8):`UniformManager::ResolveUniformBufferPayload` 在 `UniformManager.cpp:2022` 调 `SyncPersistentMappedRange()`、`:2052` 读 `MappedData() + rangeStart` 打进 **Magma 自己的 UBO ring**——消费者在 server,搬不走。由 `kCapNeedsHostUboBytes` 门控(Espryt 直接绑给驱动,不需要)。**逐帧字节量进 `stage-ubo-named` 计数器;在 P0 给出数字之前不冻结这个 payload 的形状。**
|
||||
|
||||
**backend 侧 program link/compile 失败不需要任何同步返回,也不需要新事件种类。** 实测:`SyncToBackend` 在 `Managers.cpp:8091` link、`:8094` 读 `GL_LINK_STATUS`、`:8095` 折进 `m_backendProgramUsable`、`:8097-8101` 取驱动日志、`:8106` 发 `MGLOG_E`;`Use()` 随后绑 program 0(`:8357`)并 `MGLOG_E_ONCE`(`:8364-8372`)。**没有 GL error、没有 `ProgramObject` 变更、`GL_LINK_STATUS` 永不撤回**(`:7098`、`:7247-7249`、`:6478`、`:7827`)。同步查询由 client 从 `ProgramObject` 回答(`GL_Program.cpp:851` → `ProgramObject.h:913`)。所以 `on_log` 逐字复现它——**但由此推出一条对 `PLAN.md` §7.4 的强制修正,见 §7.4**。
|
||||
|
||||
### 5.8 emulation 所需前端数据的显式传递(v2 按 D-B7 重写)
|
||||
|
||||
归属规则:**驱动表达不了的变换在 state tracker 里 lowering,硬件/驱动强加的变换在 driver 里 lowering**。**v1 用 cap 位门控 emulation 归属的做法对 restart 与 multi-draw 不可表达(D-B7),此处收回。**
|
||||
|
||||
| emulation | 归属 | 门 | 过线的是什么 |
|
||||
|---|---|---|---|
|
||||
| **client 顶点数组**(`Managers.cpp:2500-2592` 把 `attrib.Offset` 当应用裸指针,每 draw 每属性上传 `(first+count-1)*stride+elementSize`;`VulkanRenderer.cpp:3737` 是**唯一无界**的应用指针读) | **client**(它拥有地址空间) | — | **字节,永不是指针**(`MGHostSpan`) |
|
||||
| **索引扫描**(`TryComputeMaxIndexFromHostBytes`,`VulkanRenderer.cpp:3407-3470`,用于 `:3599` 给上一条定界) | **client**(只有它同时持有两个数组) | — | `MGPDrawInfo::minIndex/maxIndex`(`kHasIndexRange` 门控),`~0` = 未知 |
|
||||
| **client 索引数组** | client | — | `MGPDrawInfo::userIndices`(`kHasUserIndices` 门控) |
|
||||
| **primitive-restart 重写**(`DirectGLES.cpp:4368-4470` 整 EBO 重写,`kMaxRestartRewriteBytes = 1<<26` = 64 MiB,`:4218`;`VulkanRenderer.cpp:4159-4161`) | **server(v2 改:v1 曾说 client)** | `kCapNeedsHostIndexBytes` → 索引宿主镜像 | **零线上流量**:server 从镜像读。**monolith 行为零变化**,诊断仍落在原线程(开放问题 12 关闭) |
|
||||
| **multi-draw 分档 + 展平**(`MultiDraw.cpp:282-320` 的 `ResolveTierForBatch` **逐 batch** 在五档里选,输入含 `programReadsDrawID`——**转译出的 ESSL 的性质,只存在于 server**;容量判定 `kMaxFlattenedIndices` `:72` / `kMaxComputeFlattenedIndices` `:82`;自动阶梯 Ext→BaseVertex→MultiIndirect→Indirect→DrawElements `:241-243`,CPU 展平是**回退**) | **server,全部五档**(v2 改) | `kCapNeedsHostIndexBytes` | `draw_vbo(info, indirect, MGPDrawRange[], numDraws)`;索引字节走镜像 |
|
||||
| **`*IndirectCount` CPU 回退**(`DirectGLES.cpp:4655-4695` 从 `parameterBuffer->MappedData()` 读实际 draw 数) | **client** | — | client 从自己的 shadow 解析计数,发解析后的 `MGPDrawRange[]`(几十字节)。**注意它今天只调 `SyncPersistentMappedRange()`,不调 `SyncGpuWrites()`**(§5.8.1) |
|
||||
| **viewport-array N 遍回放**(`DirectGLES.cpp:3742-3846`,今天包住 14 个 draw 入口) | **server** | `kCapViewportArray` | 无新增:16 组 viewport/scissor/depth-range 已在渲染状态里 |
|
||||
| **fp64 顶点窄化**(`Managers.cpp:2518-2557`) | **server**(后端格式决策) | `kCapFloat64VertexAttrib`(`BackendObject.h:487-500` 明说它与 `SupportsShaderFloat64` **独立**) | 原始字节;`IsLong` 与 `Type` 分开过线 |
|
||||
| **image-bindable 存储加宽/拆分**(`Managers.cpp:2789-2822`、`:4620-4630`) | **server** | — | 正向 `imageBindableHint`;反向 `on_texture_pull_request` + 终止符(§7.5) |
|
||||
| **生成 mipmap 的前端存储** | **拆开**:client 分配 level 存储,server 生成 | — | `MGPMipPlan`;`on_mip_levels_generated` **只带形状不带字节**(见 §9.1 的说明);CPU 回退路径的纹素由 `on_texture_writeback` 回来 |
|
||||
| **CopyImage shadow 镜像**(`DirectGLES.cpp:7065-7140`) | **client** | — | 只回"拷贝成功"。**删掉一整条 server→client 字节通道** |
|
||||
| **XFB CPU 图元计数**(`GL_Drawing.cpp:172`,调用点 `:1133, 1141, 1195, 1668`) | **纯 client** | `kCapCpuXfbPrimitiveAccounting` | `MGPDrawInfo::xfbCpuCapturedVertices`(flag 门控)+ `end_stream_output` 的 `MGPXfbAccounting` |
|
||||
| **XFB scatter 的 read-modify-write**(`DirectGLES.cpp:893-960`) | **client(v2 新增行)** | — | 见 §7.2 的 `on_buffer_writeback` 修正 |
|
||||
| **压缩纹理 / pixel unpack 规整** | **纯 client** | — | 无 |
|
||||
|
||||
#### 5.8.1 陈旧索引纪律——**逐站点**表,不是一条笼统规则(v2 修正)
|
||||
|
||||
v1 写"上表里每一次 client 侧扫描/重写,在 monolith 里都紧跟在 `SyncPersistentMappedRange()` + `SyncGpuWrites()` 之后"。**对 `*IndirectCount` 不成立**:`DirectGLES.cpp:4666-4667` **只**调两次 `SyncPersistentMappedRange()`,然后在 `:4690-4694` 直接读 `MappedData()`;**没有 `SyncGpuWrites()`,因此今天没有停等**。而 `SyncGpuWrites` 才是触发 `ReadbackFromGpu`(`BufferObject.cpp:265-274`)的那一条。照 v1 的笼统规则实施,`glMultiDrawElementsIndirectCount` 会平白获得一次 publish-and-wait round trip——而 trace 语料里恰好有 `minecraft-1.21.1-neoforge-create-indirect-in-world`(Create/Flywheel,indirect 与 parameter buffer 每帧被写),于是这会变成一个**逐帧逐 batch 的同步 round trip**,而 §9.2 第 10 行还把它写成"常见情况代价为零"。
|
||||
|
||||
**逐站点 reconcile 表(必须逐字复现 monolith 的集合,不多不少):**
|
||||
|
||||
| client 侧动作 | monolith 对应站点 | 必须做的 reconcile |
|
||||
|---|---|---|
|
||||
| client 顶点数组范围计算 + 暂存 | `Managers.cpp:2500-2592`(无 buffer,源是应用指针) | **无**(应用内存,无 GPU 写者) |
|
||||
| 最大索引扫描(EBO 源) | `VulkanRenderer.cpp:3406-3470` 前的 `:3431` | `SyncPersistentMappedRange()` **+** `SyncGpuWrites()` |
|
||||
| 最大索引扫描(client 索引源) | 同上,client 指针分支 | **无** |
|
||||
| `*IndirectCount` 计数解析 | `DirectGLES.cpp:4666-4667`、`:4768-4793` | **只** `SyncPersistentMappedRange()`。**不加 `SyncGpuWrites()`** |
|
||||
| (server 侧)restart 重写 | `DirectGLES.cpp:4412-4413` | server 从镜像读;镜像由 subdata 流维护,**GPU 写者的可见性由 `on_gpu_written` 收窄集驱动**——server 侧本地判定,无 round trip |
|
||||
| (server 侧)multi-draw 展平 | `MultiDraw.cpp:498-499` | 同上 |
|
||||
|
||||
**client 侧需要 reconcile 的那两条的形态**:publish → 等 `appliedSeq` → 排空事件 → 再碰 shadow。跳过它,`maxIndex` 来自陈旧字节,顶点数组被少拷 → 几何缺失,或越界读应用数组。
|
||||
|
||||
门:`ClientArrayAfterComputeWriteScenario`(新增),**必须能因它存在的理由变红**。
|
||||
门:`create-indirect` fixture 上的 `roundtrips-per-frame` 计数器**必须读零**(P8 验收),这是上面那条"不加 `SyncGpuWrites()`"的绊线。
|
||||
|
||||
**另注**:monolith 在 `*IndirectCount` 上不调 `SyncGpuWrites()` 本身可能是一个潜在缺口(compute 写的 indirect buffer)。**那是一个独立的 `dev` 问题,拆分不得借机"顺手修"**——那会改变基线并让逐名对比失去意义。列入开放问题。
|
||||
|
||||
---
|
||||
|
||||
## 6. 后端状态机改造
|
||||
|
||||
### 6.1 什么原样不动(先说这个,因为它是"最短可信改造"的依据)
|
||||
|
||||
**每一个 ring、pool、arena、quirk、lowering pass 原地不动:**
|
||||
|
||||
Espryt:三条 persistent-mapped ring、`PersistentRing` 的分配/背压算法、buffer pool、全部 7 条 fallback-repack 路径(`Managers.cpp:3209-3527`)、`m_backendColorSlots` draw-buffer 置换表、三个 scratch FBO 及其驱动侧 attachment 影子、`PackState`、全部驱动绑定影子、Adreno 的"禁用属性无指针 SIGSEGV" workaround(`Managers.cpp:2371-2380, 2427-2433`)、Mali 的 XFB 捕获丢失 workaround(`DirectGLES.cpp:400-410`)、`ScopedDefaultUnpackState`、SPIRV-Cross 会话与 6 次 post-emission ESSL 重写、驱动 POST 自检族、**restart 重写与 multi-draw 五档**(D-B7)。
|
||||
|
||||
Magma:`VulkanRenderer` 全部 memo 与 scratch、`PipelineFactory`、`ProgramFactory`、`UniformManager` 的 ring 与描述符集、五个 `Vk*Manager`、`FrameContext`、`SwapchainObject`、`DynamicStateShadow`、`VertexInputStateFactory` 的 cache **本体**、**以及 D18 的节点式容器纪律**。
|
||||
|
||||
**v2 从"原样不动"里移出的一项**:`Managers.cpp:4274-4326` 的 sub-rect 上传判定与跨步计算——它今天靠 `uploadData == mipData` 指针比较与整 level 步长算术,split 下不成立(§4.5.6),必须改成从 `MGPSubRegion` 描述符取步长。**这不是 v1 说的"只把输入从拉取的 shadow 指针换成 `MGPBlobRef`",是真代码改动,计入子系统 5。**
|
||||
|
||||
**唯一两处必须真改的 `MG_State` 类型内部用法**:
|
||||
|
||||
1. **Magma 的占位纹理**(`UniformManager.cpp:161-181, 1416-1500, 1624-1634`):构造真的 `TextureObject2D` / `TextureObject2DMultisample` / `TextureObject2DMultisampleArray`,走 `SetInternalFormat(RGBA8)` / `AllocateStorage({1,1,1},4)` / `UpdateMipmapSubData` / `MarkStorageDirty` / `SetSamples(2)`(VUID-RuntimeSpirv-samples-08726)/ `TruncateMipmapLevels(1)`,**唯一理由**是让"未绑定单元"复用 `SyncTextureAndGetDescriptor(ITextureObject&)` 这个签名。改成 backend 自己分配 `VkImage` + view + descriptor:**~120 行前端对象木偶戏变成 ~60 行直白的 VMA/Vulkan,34 个 `MOBILEGL_ASSERT(pGLContext)` 里的 9 个随之消失。**
|
||||
2. **Magma 的两个内部 shader**(`InitializeBlitResources` `VulkanRenderer.cpp:4210-4283`、`InitializeDepthMipmapResources` `:4287-4356`):**烘焙成 SPIR-V。** 方式:把生成的 SPIR-V、uniform location、UBO 布局作为生成头文件签进树,用一个 `MG_Test` 重跑树内 glslang 对同一批源码字符串并逐字节比对守新鲜度。不用构建期 host glslang target。`uSource` 的描述符绑定本来就由 `ProgramFactory` 自己的 SPIRV-Reflect 走查找到(`:4340-4350`),原样存活。**顺带把一次 glslang 编译从 monolith 启动路径上删掉。**
|
||||
|
||||
Espryt 有一个小号同类:`g_rawDepthFetchSamplerState`(`DirectGLES.cpp:166-179`)→ backend 原生 sampler 记录,~40 行。
|
||||
|
||||
### 6.2 strangler 脚手架:`PipeInputs` + 逐 verb 填充器 + poison 世代
|
||||
|
||||
```cpp
|
||||
// MG_Backend/MGPipe/PipeInputs.h
|
||||
namespace MobileGL::MG_Pipe {
|
||||
struct PipeInputs {
|
||||
// 阶段 A:字段类型与 backend 今天读到的**完全一致**
|
||||
const RenderStateParameters& GetRenderStateParameters() const;
|
||||
Uint16 GetRenderStateParametersVersion() const;
|
||||
const MGPVaoRec& GetBoundVertexArray() const;
|
||||
// … 每个 backend 真正用到的 GLContext 方法一个访问器(Espryt 32 个 / Magma 55 个)
|
||||
#if MOBILEGL_DEBUG || MOBILEGL_BUILD_DISAGGREGATED
|
||||
Uint64 m_filledGen[kFieldCount]; // ★v2:逐字段"上次填充的 verb 序号",不是一位
|
||||
Uint64 m_currentVerbSerial;
|
||||
#endif
|
||||
};
|
||||
extern PipeInputs gPipeInputs;
|
||||
}
|
||||
#if MOBILEGL_PIPE_PUSH
|
||||
# define MGB_CTX (&::MobileGL::MG_Pipe::gPipeInputs)
|
||||
#else
|
||||
# define MGB_CTX (::MG_State::pGLContext)
|
||||
#endif
|
||||
```
|
||||
|
||||
**`PipeInputs` 按 memo 键组织,不是按读点组织。** 这是它只有 ~20KB、且字段集在整个迁移期稳定的原因。
|
||||
|
||||
#### 6.2.1 三个阶段,其中阶段 A 可证明是**近乎** no-op
|
||||
|
||||
| 阶段 | 改什么 | 怎么证明 |
|
||||
|---|---|---|
|
||||
| **A — 别名** | 机械 `sed`:`MG_State::pGLContext->` → `MGB_CTX->`(**293 处**);**外加手工转换 58 行非箭头用法**(§2.4)。**逐 verb 类填充点**(见下)填 `gPipeInputs`。backend 函数体其余部分不变 | `nm --defined-only` 不变;`.text` size **在可逐行归因的范围内**(**不是**完全相等,见下) |
|
||||
| **B — 推送** | tracker 填 `gPipeInputs`;填充器仍在,按 `MOBILEGL_PIPE_PUSH` 位图逐字段让位 | **`MOBILEGL_PIPE_VERIFY=1`**(§10.3-②):tracker 再填一份快照版,G4 生成的比对器**逐字段**每 draw 比一次 |
|
||||
| **C — handle 化** | `SharedPtr<FrontendObject>` 字段 → `MGPipeHandle` + POD 描述符;memo 重键;写回变回调 | 全套门(§10.3)。**注意 A/B 口径在此收窄,见 §6.7** |
|
||||
|
||||
**v2 修正 1:填充点必须逐 verb 类,不能只有两处。**
|
||||
v1 只在 `PrepareForDraw`(`DirectGLES.cpp:2916`)与 `SetupDraw`(`VulkanRenderer.cpp:6371`)顶端填快照。但 `MG_Impl` 用到的 70 个表项里有 ~48 个不是 draw/dispatch,其中多个自己就读 `pGLContext`(`UpdateTextureBindingAtTarget` `:6051-6052`、`PackStateFromContext` `:6129`、`Clear` `:4106/:4165`、`BlitFramebuffer` `:5988-5989`、`GetTexImage` `:9254-9257`、DSA by-name `:4038-4043`、`:7417-7418`),而代码自己说明了这一点(`:1501-1502`:"for every non-draw call site (Clear, readbacks)")。
|
||||
**做法**:G5 从 `PipeCalls.def` 生成"每个 `kCtxVerb`/`kCtxObject` 调用可能读哪些 `PipeInputs` 字段"的表,并在 `MG_Impl` 的 ~93 个边界站点上生成对应的 validate/fill 调用。这同时把 poison 从"某个 draw 上炸"升级为"在**需要它的那个 verb** 上炸"。
|
||||
|
||||
**v2 修正 2:poison 从"位图"升级为"逐 verb 世代"。**
|
||||
一个只被上一个 draw 填过的字段,在紧随其后的 `glTexSubImage`/`glReadPixels` 里读到的是**陈旧值**,位图版的 poison 看不见(位已置)。世代版:每次 verb 递增 `m_currentVerbSerial`,字段被填时记下当时的序号,读取时断言 `m_filledGen[f] == m_currentVerbSerial`(对"跨 verb 有效"的字段单独标注为 sticky 并在生成表里显式列出)。**这才让"一个字段在某个 verb 上没被推送"必然是一次 Fatal 而不是一次静默陈旧。**
|
||||
|
||||
#### 6.2.2 poison 世代是完整性的运行期绊线
|
||||
|
||||
在 debug 与 disaggregated 构建里,读一个当前 verb 未填的非 sticky 字段是 **`Fatal{UnmigratedPipeInput, "GetStencilState@DrawVbo"}`**——响亮、精确、不可能渲染过去。P13 之后(`SnapshotFromGLContext()` 只在 verify 构建里)完整性变成**构建期事实**:一个从未被写入的字段就是一个编译器能标出来的字段。
|
||||
|
||||
### 6.3 Track V / Track H 与残余值块
|
||||
|
||||
- **Track V(值类型)**:`GetRenderStateParameters`、`GetPixelStoreParameters`、`IsCapabilityEnabled(+Indexed)`、`GetStencilState`、`GetColorMaskIndexed`、`GetDepthMask`、`GetScissorBox`、`GetPatchVertices`、`GetCurrentVertexAttribute`、Magma 的 ~22 个标量 getter…… **约占 B 类读点的 55%**。机械,每组 ~1 天。
|
||||
- **Track H(对象类型)**:167 个 `SharedPtr<MG_State…>` 点。真活。
|
||||
|
||||
**Track V 的 55% 不需要逐字段接口条目就能跑起来**,所以 P2 发一个**显式临时**调用 `set_residual_value_state(MGPBlobRef)`:
|
||||
|
||||
```cpp
|
||||
struct ResidualValueBlock {
|
||||
RenderStateParameters renderState; // 直到 create/bind_render_state + set_dynamic_state 落地
|
||||
PixelStoreParameters pack; // 直到 set_pixel_pack_state 落地
|
||||
Uint64 capabilityBits;
|
||||
Uint32 patchVertices; Float patchOuter[4], patchInner[2];
|
||||
// … 每个阶段变小 …
|
||||
};
|
||||
```
|
||||
|
||||
**三条硬性纪律:**
|
||||
|
||||
1. **退役是一个编译错误。** `static_assert(sizeof(ResidualValueBlock) == MGL_RESIDUAL_BLOCK_SIZE)`,常量每阶段**下调**;P13 到 0 之后 `static_assert(sizeof(ResidualValueBlock) == 0, ...)` 一直红到最后一个字段消失。
|
||||
2. **布局必须逐成员断言,不能只断言 sizeof。** 异质 POD 并集跨编译器/ABI 最容易出 padding 差异,而 monolith 的 verify harness **看不见它**(两侧是同一个 TU)。所以 G3 为每个成员生成 `static_assert(offsetof(...) == N)`,**并且**在 split 下该块**逐字段序列化**而不是整块 memcpy。
|
||||
3. **只在 P2..P13 之间存在**,`MOBILEGL_PIPE_STATS` 单独计一类字节。
|
||||
|
||||
### 6.4 DirectGLES(Espryt)逐子系统
|
||||
|
||||
`PrepareForDraw` 的阶段顺序(`DirectGLES.cpp:2916-2975`):`GetBoundVertexArray` → `ResolveVaoTwin` → `GetProgramForDraw`(**join 编译池**)→ `CaptureDrawTextureSyncKeys` → `SyncNeccessaryBuffers` → `SyncCurrentVAO` → `SyncNeccessaryTextures` → `SyncImageTextureBindingsForDraw` → `MarkWritableImageBufferTexturesGpuWritten`(**改前端**)→ `SyncCurrentFBO` → `SyncCurrentProgram` → `SyncRenderState` → `BindCurrentFBO` → VAO bind → `SyncCurrentVertexAttributeValues` → `BindCurrentTextures` → `BindCurrentProgramWithResources` → `StartPendingTransformFeedback`。
|
||||
|
||||
| # | 子系统 | 消除读点 | memo | 写回 | 轨 | 天 | 风险 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| 0a | `GetIntegeri_v`/`GetInteger64i_v`/`GetProgramiv` 移回 `MG_Impl` | 14 | 0 | 0 | — | 1-2 | 极低(严格 no-op) |
|
||||
| 0b | handle 基建;6 个 registry → slot 数组;删 `TwinLookupMemo`×3 / `OwnerEquals` / `g_fbSlotCache` / 2 个 GC 扫描 | — | 9 删 | — | — | 5-7 | 低 |
|
||||
| 1 | **渲染状态**(`DirectGLES.cpp:1962-2654`,693 行) | **4**(`:2007, 2021, 2050, 2133`) | 0 | 0 | V | **3-5** | **低**:693 行函数体、单 `Uint16` 早退、三段 memcmp 全不动 |
|
||||
| 2 | buffer + 7 个 `BufferBackendOps` | 19 | 3 | 6(+23 处 re-entry 删除) | H | 10-13 | **高**(不碰 `AcquirePersistentMap`) |
|
||||
| 3 | VAO / vertex elements | 2(+~10 getter) | 4 | **0**(Espryt 不往前端对象写 memo) | H | 7-9 | 中 |
|
||||
| 4 | framebuffer / renderbuffer | 8 + 4 处 `pDefaultFramebufferInfo` | 4 | 1 | H | 7-9 | 中高 |
|
||||
| 5 | 纹理 / sampler / image unit / **`set_texture_params`** / **subdata 描述符改造** | 18(+~35 getter) | 8(5 删) | 21 | H | **23-30**(v1 为 20-26,+3-4 为 §4.5.6 的跨步描述符改造) | **高** |
|
||||
| 6 | program + constant buffer | 16(+~30 getter) | 5 | 0 | H | 14-18 | **高** |
|
||||
| 7 | XFB(含 **scatter 搬到 client**,§7.2) | 3 | 1 | 2 | H | 5-7 | 中 |
|
||||
| 8 | emulation + `MGHostSpan` + **索引宿主镜像的 server 侧接口** | ~12 | 0 | 3 | — | 8-11 | 中 |
|
||||
| 9 | 回读 / pack state | ~10 | 1 | 7 | V+H | 5-7 | 中 |
|
||||
| 10 | 删 pull 路径 + `MGB_CTX` | — | — | — | — | 4-6 | 低 |
|
||||
| | **合计** | **124** | ~32 | 28 | | **92-124** | |
|
||||
|
||||
**子系统 5 是全表最危险的一处**:它同时压着实测 +6ms/frame 的 box-vs-rects 悬崖(`Managers.cpp:4386-4390`)、7 条 fallback-repack 路径、以及 v2 新增的跨步描述符改造。缓解:`resource_subdata` 同时携带 box 与 region 列表且 **server 选形状**;repack 族本体不动;**子系统 5 拆成两个可独立落地的半**(先 sampler view + sampler + `set_texture_params`,再 image unit + dirty 归属反转 + 跨步描述符),让回归能二分到其中一半。**Mali 设备门必须发布逐帧上传作业数与帧时增量**(不是只有 SSIM)。
|
||||
|
||||
### 6.5 DirectVulkan(Magma)逐子系统
|
||||
|
||||
| # | 子系统 | 读点 | memo | 写回 | 天 | 风险 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 0a/0b | 同 Espryt;13 个身份缓存重键 | ~10 | 13 | 0 | 5-8 | 低 |
|
||||
| 1 | **pipeline + 动态状态** | ~55 | 1 | 0 | **3-4** | **低——两个 backend 里最便宜的一次转换** |
|
||||
| 2 | `SetupDraw` + `TrySetupDrawFastPath`(`:5994`,377 行)+ `SetupDrawSnapshot[4]` | ~48 | 4 | 0 | 10-13 | 高 |
|
||||
| 3 | `VkBufferManager`(7 个 op 里的 6 个;`ResidentSubData` 保持 null) | ~19 | 2 | 4 | 7-9 | 高 |
|
||||
| 4 | `VertexInputStateFactory` + `VaoDrawMemo`(**删掉写进前端 VAO 的后端堆裸指针**) | ~6 | 2 | 3 | 2-3 | **低(纯结构性收益)** |
|
||||
| 5 | `VkTextureManager`(3504 行)+ `VkSamplerManager` + **`set_texture_params`** | ~30 | 3 | 7 | 13-16 | 高 |
|
||||
| 6 | `UniformManager` 描述符 + **占位纹理原生化** + **具名 UBO host payload**(D-B8) | ~35 | 4 | 6,**且删 ~120 行** | 12-15 | 高 |
|
||||
| 7 | `VkRenderPassManager` / `VkClearManager` / framebuffer(**保留 D18**) | ~20 | 2 | 0 | 7-9 | 中高 |
|
||||
| 8 | `ProgramFactory` + **内部 shader 烘焙**(含 4 天烘焙与回归测试) | ~15 | 1 | 2 | 7-9 | 中(构建 lane) |
|
||||
| 9 | XFB(**顺带修 D21**)+ query + 回读 | ~15 | 2 | 5 | 11-14 | 中 |
|
||||
| 10 | swapchain / default FBO(`SwapchainObject.cpp:276-330` 的**写**变 `on_surface_changed`) | ~4 | 0 | 7 | 4-5 | 中 |
|
||||
| 11 | 删 pull 路径 | — | — | — | 4-6 | 低 |
|
||||
| | **合计** | **169** | ~34 | 42 | **85-111** | |
|
||||
|
||||
**Espryt 的子系统 1 与 Magma 的子系统 1 作为一个里程碑一起做**(合计 6-9 天),这样同一个接口调用在两个 backend 上同时被证明。
|
||||
|
||||
### 6.6 strangler 顺序(风险最小化)
|
||||
|
||||
```
|
||||
0a getter 移出(AdvertisedLimitsScenario;严格 no-op)
|
||||
0b 字节/调用计数器落地 ← 含**动态** accessor 计数与 memo 命中率(§2.3.1)
|
||||
0c 清工作树 per-draw fprintf
|
||||
0d 值头与制品头抽取(MGPipeValueTypes.h、ProgramArtifacts.h)+ include 图门 ← P0.5
|
||||
0e handle 基建:slot 分配器 + registry 变数组 + 删 TwinLookupMemo/OwnerEquals/g_fbSlotCache/GC
|
||||
1 渲染状态(两个 backend 一起)+ Magma 子系统 4 ← 机制证明 + 第一片 Track H
|
||||
2 buffer + BufferBackendOps ← 泛化已存在的模式;不碰 AcquirePersistentMap
|
||||
3 VAO / vertex elements
|
||||
4 framebuffer
|
||||
5 纹理 / sampler / image unit(拆两半)
|
||||
6 program + constant buffer
|
||||
7 XFB + query + 回读 ← 可与 5/6 并行(第二个工程师)
|
||||
8 emulation + 索引宿主镜像
|
||||
9 删 pull 路径;三道纯度门转绿
|
||||
```
|
||||
|
||||
**0b 必须在任何迁移之前**:所有 ring 尺寸、批处理阈值、wire 粒度决策否则都是猜测。**0c 必须在基线之前**:那两处 per-draw `fprintf` 污染每一次测量。**0d 必须在 program 与渲染状态之前**:否则纯度门与 `nm -D | grep glslang` 判据不可达。
|
||||
|
||||
### 6.7 A/B:旧路径怎么保留,**以及它的口径在哪里收窄**
|
||||
|
||||
```
|
||||
MOBILEGL_PIPE_PUSH = <子系统位图> # 0 = 全 pull;每位一个子系统;含一位关闭 CSO 内容寻址(负面对照)
|
||||
MOBILEGL_PIPE_VERIFY = 0|1 # 影子比对(~5-10x 慢,永不出货;P13 之后仍保留)
|
||||
MOBILEGL_PIPE_STATS = 0|1 # 字节/调用/roundtrip/纹理拉取/上传形状计数器
|
||||
MOBILEGL_PIPE_LEGACY_MEMOS= 0|1 # ★v2:编译期开关,保留 registry / TwinLookupMemo 实现
|
||||
```
|
||||
|
||||
在 init 时刻锁存,与 `MOBILEGL_BACKEND_TYPE` 同一套机制(`ConfigLoader.cpp:212-225`),与树里已有的 ~40 个 `MOBILEGL_*` 开关并列。
|
||||
|
||||
**v2 必须写明的口径收窄。** v1 说"任何一次提交都能在同一份二进制上按子系统 A/B,设备回归可以二分到'哪个子系统'"。**这在阶段 B(值字段)成立,在阶段 C(handle 化)之后不成立**:stage C 把 `PipeInputs` 的字段**类型**从 `SharedPtr<FrontendObject>` 换成 `MGPipeHandle` + POD 描述符、把 6 个 `StateBackendObjectRegistry` 哈希表换成 slot 数组、删掉 `TwinLookupMemo`×3 与 `OwnerEquals`、把 memo 重键成 `{slot, gen}`。位清零时,`SnapshotFromGLContext()` 仍要从 client 的 slot 表**合成**那个 handle,backend 仍然跑重键后的 memo 代码——**两个分支跑的是同一份新代码**。一个重键 bug(正是 D1/D2/D3/D11/D13 那一类)在两个分支里都在,位图二分不出来。
|
||||
|
||||
**对策**:`MOBILEGL_PIPE_LEGACY_MEMOS`(**编译期**开关)在 P3a 与 P4a 期间保留 registry / `TwinLookupMemo` 的实现活在同一个 `PipeInputs` 接口之下,给前两波 handle 化保留一个**真正的**旧-vs-新臂;随 pull 路径一起在 P13 退役。**这条开关的存在期与代价必须写在阶段计划里**(P3a/P4a 各 +1 天维护成本)。
|
||||
|
||||
**P13 删除 pull 路径时**:删 `SnapshotFromGLContext()` 的**非 verify** 编译分支、`MGB_CTX` 宏、`MOBILEGL_PIPE_PUSH`、`MOBILEGL_PIPE_LEGACY_MEMOS`;**`MOBILEGL_PIPE_VERIFY` 连同它需要的 `SnapshotFromGLContext()` 与 `MG_State` include 一起保留**(D-B5);`static_assert(sizeof(ResidualValueBlock) == 0)` 必须编译通过;三道纯度门(§4.7.2)在**非 verify** 构建上转绿。
|
||||
@@ -0,0 +1,320 @@
|
||||
## 7. backend → frontend 反向通道
|
||||
|
||||
这是历次评审对任何薄 backend 设计的中心反对意见,所以逐条处理,**不做概括**。实测:`grep -rnoE "(->|\.)(SetBackendResource|SetBackendHashMemo|SetBackendStateMemo|SetBackendAuxMemo|WritebackFromBackend|MarkGpuWritten|MarkStorageDirty|AllocateStorage|SetInternalFormat|UpdateMipmapSubData|EnsureGpuResidentStorage|SyncPersistentMappedRange|SyncGpuWrites|RecordError|InvalidateCompileEnv|TruncateMipmapLevels|SetSamples)\(" MG_Backend/` = **95 个调用点 / 17 个方法**,外加 6 处 backend 反向进 `MG_Impl`。
|
||||
|
||||
### 7.1 `MGPipeCallbacks`:把反向通道具名化(对 gallium 的偏离 D8)
|
||||
|
||||
```cpp
|
||||
// MG_Pipe/MGPipeCallbacks.h —— context_create 时安装;monolith 里是直调,split 里是记录
|
||||
struct MGPipeCallbacks {
|
||||
void (*on_gl_error) (Uint32 code);
|
||||
void (*on_gpu_written) (MGPipeHandle res, Uint rangeCount, const MGPRange*);
|
||||
void (*on_buffer_writeback) (MGPipeHandle res, Uint64 off, MGPBlobRef bytes);
|
||||
void (*on_texture_writeback) (MGPipeHandle res, const MGPBox*, MGPBlobRef bytes);
|
||||
void (*on_texture_pull_request) (MGPipeHandle res, Uint16 target, Uint16 firstLevel, Uint16 levelCount,
|
||||
Uint64 pullSerial);
|
||||
void (*on_mip_levels_generated) (MGPipeHandle res, Uint16 base, Uint16 count); // 只带形状,不带字节
|
||||
void (*on_surface_changed) (const MGPSurfaceInfo*);
|
||||
void (*on_caps_invalidated) ();
|
||||
void (*on_log) (Uint8 level, const char* text);
|
||||
void (*on_xfb_scatter_ready) (MGPipeHandle scratch, Uint64 packedStride, Uint64 vertices); // ★v2
|
||||
};
|
||||
```
|
||||
|
||||
配套的**正向终止符**(在 `MGPipeContext` 里,不在 callbacks 里,因为它是 client→server):
|
||||
|
||||
```cpp
|
||||
// ★v2:拉取请求的显式应答,可以携带零个 region
|
||||
void (*resource_subdata_complete)(MGPipeHandle res, Uint16 target, Uint16 firstLevel,
|
||||
Uint16 levelCount, Uint64 pullSerial);
|
||||
```
|
||||
|
||||
gallium 没有 shadow writeback、GPU-write 通知、纹理重发请求/终止、default-FB 几何这些词汇——因为在 Mesa 里 state tracker 与 driver 共享地址空间。**把它们具名化为 10 个回调 + 1 个终止符,好过藏在 95 个 poke 点里。**
|
||||
|
||||
### 7.2 95 个写回点的逐族归属
|
||||
|
||||
| 族 | n | 变成什么 |
|
||||
|---|---|---|
|
||||
| `SyncPersistentMappedRange` | **20** | **v2 修正:不是"全部消失",而是逐站点归属。** 其中多数紧挨着一次对客户端字节的 CPU 读,而那些读搬到了 client(§5.8),由 **tracker 在填 `MGHostSpan` 之前**做同一次 reconcile(逐站点表见 §5.8.1)。**但至少一处的消费者搬不走**:`UniformManager::ResolveUniformBufferPayload`(`UniformManager.cpp:2022` 同步,`:2052` 读 `MappedData()+rangeStart`,`:2053-2057` 零填充)把具名 UBO 打进 **Magma 自己的 UBO ring**——由 D-B8 的 `set_shader_buffers` host payload 承载,client 在**发射前**做 reconcile。**P1 的交付物包含这 20 处的逐站点归属表**(哪些消失、哪些变 client 发射前 reconcile、哪些需要 host payload),不接受笼统结论 |
|
||||
| `MarkStorageDirty` | **18** | 16 处是 server 本地记账——**零消息**(dirty 归属反转,§7.3)。2 处 `true`(`Managers.cpp:2813`、`DirectGLES.cpp:6852`)变 `on_texture_pull_request` / `on_texture_writeback` |
|
||||
| `AllocateStorage` | **8** | 6 处是 **backend 凭空造出来的前端对象**(Magma 的占位纹理、`SwapchainObject` 的 default-FBO 占位,`SwapchainObject.cpp:284, 305, 329`)→ **server 原生,永不上线**;1 处是生成 mip 的 shadow(`DirectGLES.cpp:6261`)→ `on_mip_levels_generated`;1 处是 swapchain 尺寸变更 → `on_surface_changed` |
|
||||
| `WritebackFromBackend` | **8** | `MGPReplySlot`(回读)+ `on_buffer_writeback`(PBO 回读、XFB 捕获)。**必须按操作级批处理**:其中两处今天在循环里**逐行**写回(`Utils.cpp:2342`、`DirectGLES.cpp:7633`),绝不能变成"每扫描线一次 IPC" |
|
||||
| `SetInternalFormat` | **7** | 与 `AllocateStorage` 同批 |
|
||||
| `SyncGpuWrites` | **6** | 同 `SyncPersistentMappedRange`:**逐站点**,见 §5.8.1 |
|
||||
| `MarkGpuWritten` | **6** | client 在每个 draw/dispatch 发射点**保守自建**,镜像 `DirectGLES.cpp:459-467, 509, 1809` 与 `UniformManager.cpp:1073, 1229`、`VulkanRenderer.cpp:11210` 的输入。`on_gpu_written{res, ranges[]}` 是**收窄**通道 |
|
||||
| `RecordError` | **6** | `on_gl_error`,**必须对命令流有序**(§7.4) |
|
||||
| `SetBackendResource` | **4** | **删除。** server 拥有资源表;pooling / 延迟释放原样搬到 server |
|
||||
| `EnsureGpuResidentStorage` | **3** | server 本地决策 |
|
||||
| `SetBackendHashMemo` / `SetBackendAuxMemo` | **3** | 纯值 → server 侧 per-slot 字段 |
|
||||
| `InvalidateCompileEnv` | **2** | `on_caps_invalidated`,低频 |
|
||||
| `SetBackendStateMemo` | **1** | **直接删除,不翻译**(D12) |
|
||||
| `UpdateMipmapSubData` / `TruncateMipmapLevels` / `SetSamples` | **3** | 全在 Magma 的占位纹理里 → server 原生 |
|
||||
|
||||
**6 处 backend 反向进 `MG_Impl`:** 四处 `pDefaultFramebufferInfo` 身份比较 → 保留 handle `{0,1}` + `MGPFramebufferState::isDefault`;`SwapchainObject.cpp:276-330`(backend **创建** default FBO 的三张 `ITextureObject`)→ `on_surface_changed`,client 自己合成对象——**顺带删掉 monolith 里的一处分层倒置**;`VulkanRenderer.cpp:10700`(`CopyTextureImageToClientOrPBO_State`)→ `get_texture_image` 返回 **"该 level 无 GPU 背书,请从你自己的 shadow 回答"**(`:10691-10704` 今天测的正是这个条件)。
|
||||
|
||||
#### 7.2.1 v2 新增:XFB scatter 是对 client shadow 的 read-modify-write,必须搬到 client
|
||||
|
||||
v1 把 8 处 `WritebackFromBackend` 全部归给单向的 server→client 通道。**`ScatterCapturedRecords`(`DirectGLES.cpp:893-960`)不是单向的**:它在 `:928` 做
|
||||
|
||||
```cpp
|
||||
Memcpy(staged.data(), target.buffer->MappedData() + target.start, rangeBytes);
|
||||
```
|
||||
|
||||
——**从应用已有的字节起步**,然后只把捕获到的 varying 补进去,"这样 `gl_SkipComponents` 要求的空洞保留应用原本放在那里的东西——**这正是这个特性的全部意义**"(`:889-892` 的注释;`:880-883` 点名 `KHR-GL46.transform_feedback.capture_special_interleaved_test` 是走到这条路径的用例)。server 没有 `MappedData()`,而 `MGPipeCallbacks` 里也没有反向的 buffer 读。照 v1 实施,要么空洞被清零(一致性破坏),要么需要一次 §9.2 没有列出的、发生在 `glEndTransformFeedback` 上的同步反向读。
|
||||
|
||||
**修正(不新增停顿类)**:**scatter 搬到 client。**
|
||||
|
||||
1. server 把驱动捕获到的**紧密打包** scratch 字节通过 `on_buffer_writeback(scratchHandle, 0, bytes)` 推给 client,并用 `on_xfb_scatter_ready(scratchHandle, packedStride, vertices)` 告知布局参数;
|
||||
2. client 拥有目的 shadow,也从反射归档里拥有 `GetTransformFeedbackVaryings()` / `GetTransformFeedbackStride()` / `GetTransformFeedbackPackedStride()`(`ProgramObject.h:1146-1171, 1357-1394`),于是原样跑今天 `:930-939` 的补丁循环;
|
||||
3. client 把补好的范围当作**普通 `resource_subdata`** 重新发下去(复现今天 `:946-948` 的 `glBufferSubData` 回灌),并 bump 自己的 change serial(复现 `:942` + `BumpBufferMutationEpoch()`)。
|
||||
|
||||
副作用:`:906-914` 的"CPU 模型给出 0 顶点 → 整批捕获丢弃"的诊断**落到应用线程**上,比落在 server 上更有用。计入 Espryt 子系统 7(§6.4)。
|
||||
|
||||
### 7.3 纹理 dirty 归属反转
|
||||
|
||||
**client** 保留 `MipmapStorage` 的模型(96-rect 级联合并 + `summedArea*4 >= unionArea*3` union-box 回退,`MipmapStorage.cpp:300-305`),维护一份**发射游标**,在发射后清自己的标志。**server 从不碰 client 的标志。**
|
||||
|
||||
这是安全的,且已核实:**`MG_Impl` 里没有任何 `IsStorageDirty(` / `GetStorageDirtyRects(` / `GetStorageDirtyRegion(` 调用点**(前端从不读自己的 dirty 状态),而它自己在五处主动清(`GL_Texture.cpp:528, 701, 5547, 5621, 5691`)。**这一条删掉 `PLAN.md` §5.6a 的整个 ack 协议与风险 R6。**
|
||||
|
||||
**v2 修正 1:发射游标必须按**存储属主**键控,不能按 `(texture, uploadTarget, level)`。**
|
||||
`TextureObjectView` 把 `IsStorageDirty` / `MapMipmapData` / `MarkStorageDirty` / `MarkStorageDirtyRegion` / `GetStorageDirtyRegion` **全部转发给存储属主的 mipmap 并做索引重映射**(`TextureObjectView.cpp:290-322`;`:281` 直接写属主的数据)。一个 view 与它的属主**共用同一份 dirty 状态**却会各带一个游标:谁先发射谁就清掉了另一个还需要的标志,或者两边都发同一批纹素。
|
||||
**正确键**:`(storageOwnerHandle, ownerUploadTarget, ownerLevel)`——查询与清除前先经 `GetViewStorageOwner()` 与 view 的 `ToOwnerUploadTarget()` / `ToOwnerLevel()` 映射。
|
||||
**门**:新增场景,通过 view 上传、经属主采样(以及反向),跨 draw 边界各一次。
|
||||
|
||||
**v2 修正 2:`MOBILEGL_PIPE_VERIFY` 需要一个"保留模式",否则它在最危险的子系统上是瞎的。**
|
||||
影子比对(§10.3-②)的参照物是"从头重算一次快照"。但发射后 client 已经把 dirty 标志清了,**从头重算无法重建当时的 rect 集合**——于是子系统 5(`resource_subdata` 的 payload)恰恰是 verify 看不见的那一块,而它同时是 §6.4 标注"全表最危险"、押着 +6ms/frame 悬崖与 7 条 repack 路径的那一块。
|
||||
**修正**:`MOBILEGL_PIPE_VERIFY=1` 时 tracker **保留清除前的 dirty 集合**到本次 draw 结束,G4 比对**发射出去的 `(unionBox, regionCount, regions[])`** 与快照重算的结果。**并且**新增 `TextureUploadShapeScenario`:把逐纹理逐帧的上传形状(box vs N 个 region、作业数)录成金标,与 SSIM 并列比对——**+6ms 悬崖由形状相等把关,不是由 SSIM 把关**(SSIM 对它完全不敏感)。
|
||||
|
||||
**上传形状决策留在 server**:`resource_subdata` 同时带 union box 与 region 列表(§4.5.6),Mali 按作业数计价的悬崖在哪一侧付 GPU 代价,决策就留在哪一侧。
|
||||
|
||||
### 7.4 反向通道的有序性是正确性要求,不是优化
|
||||
|
||||
**`on_buffer_writeback` 必须与 epoch bump 有序。** 今天每一次 `WritebackFromBackend` 后面都紧跟一次 `BumpBufferMutationEpoch()`(`DirectGLES.cpp:834-837, 942, 7625-7629`),否则 server 自己的 draw-clean memo 会在 epoch 背后变陈旧。split 里这变成**反向通道上的一条排序规则**:一次写回的 epoch bump 必须在任何后续读该 handle 的命令之前被 server 侧应用。**反向通道需要与正向通道相同的有序保证。**
|
||||
|
||||
**`on_gl_error` 必须对命令流有序**,否则 `glGetError` 答错。`glGetError` 本身永远本地(`GL_Getter.cpp:2811-2817`;不变式 `Core.cpp:48-49`)。
|
||||
|
||||
**v2 修正:`kNeedsAck` 只标真正**同步**的分配点,不是"看起来像分配"的 GL 入口。**
|
||||
v1 把 "`glRenderbufferStorage*`、可能失败的 `glTexImage*`/`glTexStorage*`/`glCopyTexImage*` 形式、`glBufferStorage`" 全标成 `kNeedsAck`,让 OOM 探测惯用法(`allocate; if (glGetError()==GL_OUT_OF_MEMORY) 用更小的重试;`)成立。**实测这批里纹理族根本不调 backend 表**:`MG_Impl/GLImpl/Texture/GL_Texture.cpp` 在 `:2515, 2671, 2755` 只做 `MarkStorageDirty(..., true)`,Espryt 在 sync 时刻才惰性分配;纹理侧的错误上报 `RecordGLError`(`DirectGLES.cpp:6309-6324`)**只有一个调用者**——`glGenerateMipmap`(`:6916`)。连唯一一处真正的同步分配 `glRenderbufferStorage*` 也是在 `BackendRenderbufferObject::SyncToBackend`(`Managers.cpp:8674-8684`)里惰性做的。
|
||||
|
||||
**修正后的规则**:
|
||||
- **纹理分配的 OOM 在 monolith 里就已经推迟到 sync 时刻,拆分不改变任何可观察行为** —— 这批**不标** `kNeedsAck`,并把这条事实写进文档(避免后人以为是遗漏)。
|
||||
- **`kNeedsAck` 只标两项**:`glBufferStorage`(真同步)与 `glRenderbufferStorage*`(**若**决定把它的分配提前到 GL 调用时刻以支持 OOM 探测;否则它也不标,同样写明)。**这个"若"由 P0 回答**:查 MC / Iris 语料里有没有真的 `glRenderbufferStorage` OOM 探测惯用法;没有就不标,省掉整条 ack 路径。
|
||||
- 其余错误一律晚到,走有序的 `on_gl_error`。
|
||||
|
||||
**对 `PLAN.md` §7.4 的强制修正:`on_log` 必须按严重级分级。** `PLAN.md` 把**全部** `EvLogLine` 设为有损(覆盖最旧 + `eventDropped`)。但 §5.7 已确认:**backend program link/compile 失败只以一行日志加一次 bind-program-0 的空 draw 呈现**。统一有损策略下,系统里诊断价值最高的那一行会在日志压力下静默消失。
|
||||
|
||||
**规则**:`on_log(level ≤ WARN)` 有损;**`on_log(level ≥ ERROR)` 无损**,加入触发 `eventRingFull` + 停止 apply 的语义事件集;再加一个**每秒 ERROR 速率限制器**,超限时发一条显式的 "N errors suppressed"。`MGLOG_E_ONCE` 的 latch 变成 per-server。P9 的故障注入门:日志洪泛下注入一次 link 失败,那行 ERROR 必须出现**且**两侧都恢复。
|
||||
|
||||
### 7.5 唯一的新停顿类:server 发起的纹理重铸拉取(D-B6)
|
||||
|
||||
server 不保留纹素字节,三个原因会要求 client 重发已发过的 level:`RequireImageBindableStorage` 的 re-dirty(`Managers.cpp:2813`)、整格式再生(`:3950-4195`)、view 源重铸(`:3616-3707`)。**四条缓解同时上**(v1 是三条,v2 补第 (e) 条终止符),加一个专门的门和一个必须发布的计数器:
|
||||
|
||||
**(a) 预防主因。** client 给纹理打 `everImageBound` 标记,`resource_create`/`respecify` 一直携带 `imageBindableHint`,于是 image-bindable 存储在前期就分配好。这把 `RequireImageBindableStorage` 从稳态里彻底移除。
|
||||
|
||||
**(b) 拉取是异步的。** server 发 `on_texture_pull_request{res, target, levels[], pullSerial}` 并把那个 twin **标为 not-ready**;client 在下一次 publish 时重发。因为 client 跑在前面,常见情况下字节在 server 到达采样该纹理的 draw 之前就到了;即使没到,**阻塞的是 `mgl-srv-apply` 线程,不是应用线程**。
|
||||
|
||||
**(c) 有上限的保留(默认关闭)。** 可选的逐纹理保留位,受一个显式的 LRU 字节预算约束(`MOBILEGL_PIPE_TEXEL_RETAIN_MB`,**v2 把默认从 32 改为 0**)。理由:`MipmapStorage` 保有每个 level 的完整 CPU 影子(`MipmapStorage.h:117` 的 `Vector<Vector<Uint8>> m_data`),所以一次拉取**总是能**从 client 已有的字节服务——保留缓存买的是**延迟**,不是正确性,而它花的是**内存**,恰好是 §0.4 用来对比 replica 的那个指标。只有 (d) 的实测拉取率非平凡才开,并拿真预算。
|
||||
|
||||
**(d) 门与计数器。** `TextureRemintPullScenario`:同时强制 `RequireImageBindableStorage` 与一次帧中格式再生。**拉取次数逐 trace 用例发布**,与 SSIM 并列。**本设计从不声称"零 round trip",它测量并公布。**
|
||||
|
||||
**(e) v2 新增:显式终止符——因为存在"答不出来"的拉取。**
|
||||
`RequireImageBindableStorage` 的重放会 re-dirty 每个上传目标的每个 level(`Managers.cpp:2789-2822`),而它自己已经跳过 `GetMipmapByteSize(...) == 0` 的 level(`:2810-2812`)。但还有一类 level:**内容只来自渲染、来自一次 `CanMirrorCopyImageShadow` 拒绝的 `glCopyTexSubImage`(`DirectGLES.cpp:7068-7073`)、或来自 GPU 侧 mip 生成**——client 那里根本没有字节。没有终止符,apply 线程会 park 在一个**永远不会 ready 的 twin** 上。B-R4 与 `TextureRemintPullScenario` 只针对拉取的**频率**,从来没针对**无解的拉取**。
|
||||
**修正**:
|
||||
- 拉取是 request/response 对,由 `resource_subdata_complete(res, target, firstLevel, levelCount, pullSerial)` 终止,**它可以携带零个 region**;
|
||||
- 收到零 region 的应答时,server **带着"已分配但为空"的存储继续**(这正是 monolith 的行为:`EnsureGenerateMipmapStorageAllocated`(`DirectGLES.cpp:6270-6271`)也是 `AllocateStorage` + `MarkStorageDirty(false)`,不填内容),并记一条 `MGLOG_W`;
|
||||
- **`TextureRemintPullScenario` 必须包含这个无解用例**(一张只被渲染过、随后被 image-bind 的纹理),**且它必须在终止符落地之前是红的**(表现为 apply 线程挂死或超时)。
|
||||
|
||||
若在真实语料(MC 与 Iris fixture)上实测拉取率非平凡,(c) 从可选升级为强制并拿到真预算。
|
||||
|
||||
---
|
||||
|
||||
## 8. 传输、数据面、同步、present、线程、平台、构建
|
||||
|
||||
### 8.1 原样继承方案 A 的部分
|
||||
|
||||
以下全部**逐条继承 `PLAN.md`,本文不复述**:
|
||||
|
||||
| `PLAN.md` 章节 | 内容 |
|
||||
|---|---|
|
||||
| **§6.1** | 段布局(`SEG_CMD` 8MiB / `SEG_STAGE` 32MiB↑ / `SEG_REPLY` 8MiB / `SEG_EVENT` 256KiB / `SEG_SHADOW[n]` / `SEG_ADOPT[n]`);shm 创建矩阵;**`SCM_RIGHTS` 必须在第一个 transport commit 里实现**(`Feat/CS-Delta-IPC` 把 `out->fd = -1` 硬编码在 `LocalSocketTransport.cpp:296`,它的数据面在唯一重要的平台上一个字节都没过去);`SEG_SHADOW` 块的 pending free-list 退休规则 |
|
||||
| **§6.2 / §6.2a** | `RingControl`:两组独立游标三元组、三个 seq 水位、`serverEpoch`、`ringGeneration`、`consumerParked`/`producerParked`、`eventRingFull`/`eventDropped`;**双向 doorbell**,`MOBILEGL_IPC_SPIN_US` 默认 50µs,`inproc` 用 condvar |
|
||||
| **§6.3** | 记录格式:8B `RecHeader`、24B `BlobRef`、**无 per-record 序号**、X-macro 每种一条 `static_assert` **加**生成的运行期边界检查 → `Fatal{ProtocolCorruption}`、`kVarTail` 自描述长度自洽校验。方案 B 把这套机制扩展到**全部** MGPipe 调用(G3) |
|
||||
| **§6.4** | WAR 纪律:调用时刻拷进 ring slot(P1-4);P4.5 的 `SEG_SHADOW` 零拷贝 + 逐 shadow 64KiB 块发送水位 |
|
||||
| **§6.5** | ring 分配与背压:逐字移植 `PersistentRing`(`Managers.cpp:641-727`、`RingAllocateSlow` `:1891-1970`、`RingOnPresent` `:1975-2016`) |
|
||||
| **§6.6 前三条** | unpack PBO 完全在 client 解析;压缩 internalformat 永不到达 backend;`glCopyTexSubImage*` 与 `glClearTexImage` 整体留在 client |
|
||||
| **§6.7 第 2、5 行** | PBO 回读改 fire-and-forget(**严格优于 monolith**,`DirectGLES.cpp:9189-9205` 无条件停等);`glEndTransformFeedback` 的无限 `ClientWaitSync`(`GL_Drawing.cpp:1326-1337`)推迟到首次读 |
|
||||
| **§6.8** | persistent map 与 ≥16MiB 采纳的三档,**由运行时 POST 探针选择,绝不硬编码驱动名** |
|
||||
| **§7.1** | FlatBuffers 纪律;`protocol_generated.h` 提交;`gen_protocol.py` + CI `flatc-check`;**默认构建图里没有 `flatc`** |
|
||||
| **§7.2** | 帧封装;publish 触发器(每记录 release-store `cmdHead`、显式门铃点、`SEG_STAGE` 余量 < 1/4、**轮询入口也是门铃点**、`GL_SYNC_FLUSH_COMMANDS_BIT` 无条件 publish、`MOBILEGL_IPC_POLL_ESCALATE` 饥饿升级);**`glFinish`/`glFlush` 保持免费**(`Definitions.cpp:111-112`) |
|
||||
| **§7.3** | 两个互相独立的窗口(字节 credit、present credit);server 不发 credit 消息 |
|
||||
| **§7.4** | 事件 ring + 排空点 + 溢出策略。**加上 §7.4 的分级修正** |
|
||||
| **§8 末尾** | fence 完成度必须来自**真的逐 fence 退休**,不是 present 水位(`DirectVulkan.cpp:1120-1128`;`magma-mc1215-fence-oom`);三个应先独立落 `dev` 的 monolith 修复 |
|
||||
| **§9 / §9.1-§9.3** | `Present` 与 `eglSwapBuffers` 严格 1:1、绝不批量;`MOBILEGL_IPC_PRESENT_CREDIT` **默认 1** 与延迟叠加公式;Magma 从不注册 `SetSwapInterval`(`BackendObject_DirectVulkan.cpp:698`);DirectGLES 的非 present fence tick |
|
||||
| **§10** | 线程模型;server 的 `mgl-srv-io` + `mgl-srv-apply`;核心放置与 `MOBILEGL_IPC_SERVER_AFFINITY`、**报逐线程 CPU 时间**;拆机顺序 |
|
||||
| **§11.1-§11.6** | 启动与握手;`extern "C" visibility("default")` 与 `nm -D` 门;Android 的 `android:process=":mgl"` Service 路径;X11 XID;`EGL_PLATFORM=surfaceless`;Windows overlapped named pipe;崩溃时的 device-lost latch |
|
||||
| **§12 第 1-3 层 / §12.4** | 编译期折叠;**唯一 hook 点** `MG_Backend/Init.cpp:48-70`;P4.5 的 allocator 改动整段包裹;`MOBILEGL_TRANSPORT` 复用全部既有开关通道 |
|
||||
| **§13** | 目录形状;一份库两个角色;FlatBuffers submodule 的双重 guard;ctest/trace-replay 的三个陷阱;`SPLIT` 后缀与 `-DTRACE_TRANSPORT=`;CI 的 `flatc-check` 与 `fprintf` grep 门 |
|
||||
| **§14** | 对 `Feat/CS-Delta-IPC` 的 REUSE / CHANGE / DROP 判定 |
|
||||
| **§15 P0** | 卫生清单与两个 spike |
|
||||
|
||||
### 8.2 与方案 A 的差异
|
||||
|
||||
**删除:**
|
||||
`Server/ReplicaContext.{h,cpp}`(换成 `Server/PipeObjectTables.{h,cpp}` + `Server/IndexHostMirror.{h,cpp}`);§5.0 的"replica vs 重写"决策;§5.1 的三步发射协议;§5.2;§5.4 的 replica 对象表规则与 `Fatal{IdentityDivergence}`;§5.6a 的纹理 ack 协议;§5.7 的 Phase 1-4 composite 分支;§5.9b 的 mutation **replay** 机制(`MutationCoverage.def`、`ImplMutationSurface.inc`、`MG_Remote::Shared::` helper 族);§6.9 的 relink 档与 `MOBILEGL_IPC_PROGRAM`;§6.4 的拷贝第 (3) 行;§12.2 的 `pGLContext` shim;阶段 **P5**(6 天回收);风险 **R1** 与 **R6**;开放问题 **§17-5**。
|
||||
**不删**:`gen_impl_mutation_surface.py` 本体——它改造成 `gen_pipe_dirty_surface.py`(§0.3 推论 4)。
|
||||
|
||||
**改变:**
|
||||
|
||||
| `PLAN.md` § | 差异 |
|
||||
|---|---|
|
||||
| §5.9a | READ 面的**编目**生成器变成**三道禁止门**(§4.7.2)。原 477 行 inventory 保留为 tracker 侧覆盖检查表(G6) |
|
||||
| §6.4 拷贝账 | 第 (3) 行不存在:**P1-4 = 3 次,P4.5 = 2 次**。`PLAN.md` 自己的"方案 B"目标**按结构达成**,开放问题 §17-5 自动关闭 |
|
||||
| §6.6 第 4 条 | 逐 level `serverAuthoritative` 位被 dirty 归属反转(§7.3)+ `on_texture_writeback` + `on_texture_pull_request`/`resource_subdata_complete` 取代 |
|
||||
| §6.9 | `RecProgramLinkOp` **不可能**(§5.7)。`ProgramPublish` 第一天;`reflectionDigest` 换成"schema 完整性绊线";P5 消失。**新增前置 P0.5 的头文件抽取**(§4.5.5),否则 `nm -D | grep glslang` 判据不可达 |
|
||||
| §5.10 | 第 2、3 条**逐字继承**(**R2 仍是最高优先级正确性项**)。第 1 条缩成**一个推送的 `hasLiveHostWrites` 位** |
|
||||
| §6.10 | 四类应用指针按 §5.8 归属;`ClientArrayBounds` 变成 flag 门控的 `MGPDrawInfo::minIndex/maxIndex`。**陈旧索引纪律改为逐站点表**(§5.8.1),不是笼统规则 |
|
||||
| §7.4 | `on_log` **按严重级分级**,加每秒 ERROR 速率限制器 |
|
||||
| §12.2 | 需要角色隔离的进程全局从 **4 个降到 2 个** |
|
||||
| §13 | `MG_Pipe/` 是**默认构建里的非可选目录**;只有 `MG_Remote/` 在 `MOBILEGL_BUILD_DISAGGREGATED` 之后 |
|
||||
| §15 | **在 P1a 之前新增两整段**:P0.5(头文件抽取)与 backend 推送改造。`PLAN.md` 把后者定价为"~0 逻辑改动";在方案 B 里它是工作量主体 |
|
||||
|
||||
**新增:**
|
||||
|
||||
- **`SEG_STAGE` 尺寸必须额外容纳这些它以前不承载的字节**(v2 修订清单):
|
||||
1. client 顶点数组;
|
||||
2. client 索引数组;
|
||||
3. multi-draw 参数块(`first[]`/`count[]`/`indices[][]`/`basevertex[]`,`drawcount*4` 级);
|
||||
4. client 解析后的 `*IndirectCount` 命令块(几十字节);
|
||||
5. **具名 UBO 的 host payload**(D-B8,`kCapNeedsHostUboBytes` 下逐 draw 逐块);
|
||||
6. **纹理 subdata 的紧密重打包区域**(§4.5.6;今天走 unpack ring 时也已经紧密重打包,所以字节量同阶,但现在过 ring slot)。
|
||||
**不在此列**(v1 曾担心,D-B7 解决):restart 重写的整 EBO(`kMaxRestartRewriteBytes = 1<<26` = 64 MiB,是默认 `SEG_STAGE` 的两倍)与 multi-draw 展平的索引流(`kMaxFlattenedIndices = 1<<24`)——**它们由 server 侧的索引宿主镜像喂养,不过 `SEG_STAGE`**。
|
||||
上限由 P0 落地的计数器实测定,不用默认值猜。**并且 G3 必须为"单条记录大于段容量"定义明确的分块/降级路径**(大 subdata 分块成多条,而不是一条巨记录)。
|
||||
- **`Server/IndexHostMirror`**(D-B7):由 `resource_create/respecify/subdata` 流增量维护,覆盖 `bindMask & ELEMENT_ARRAY` 的资源;预算 `MOBILEGL_PIPE_INDEX_MIRROR_MB`(默认 64);逐帧发布 `index-mirror-bytes` 与 `index-bytes-shipped`(超预算退化路径的计数)。
|
||||
- **新事件种类**:`on_texture_writeback`(CopyImage 镜像搬走后只剩一个生产者:CPU 生成 mip 路径 `DirectGLES.cpp:6811-6861`)、`on_texture_pull_request`、`on_mip_levels_generated`、`on_xfb_scatter_ready`;正向终止符 `resource_subdata_complete`。`on_buffer_writeback` 从"优化"升级为**承载语义**。
|
||||
- **新环境变量**:`MOBILEGL_PIPE_PUSH`、`_VERIFY`、`_STATS`、`_LEGACY_MEMOS`、`_TEXEL_RETAIN_MB`(**默认 0**)、`_INDEX_MIRROR_MB`(默认 64)。
|
||||
- **`RenderbufferObject::GetLifetimeId()`**(今天没有)。**但不需要 `GetVersion()`**——推送模型里 `glRenderbufferStorage*` **本身就是**一次 pipe 调用。
|
||||
|
||||
### 8.3 persistent map:唯一被显式隔离的传输相关决策
|
||||
|
||||
`AcquirePersistentMap`(`BufferObject.h:112`)是**永久的地址空间捐赠**(D4/D-B4)。**它原样穿过 monolith 改造(P0..P13 一动不动),只有 IPC 那一步才打破它。** 决策路径:
|
||||
|
||||
- **P0 的 spike B 在第一周给方向**:导出 `HOST_VISIBLE|HOST_COHERENT` VkBuffer 的 fd,client `mmap` 后回读,在两台设备上跑。
|
||||
- **T2(拒绝,永久正确的回退)**:返回 `nullptr`,前端已在三处容忍(`BufferObject.cpp:174, 439-442, 470-472`)。**此档下 `PLAN.md` §5.10 的 client 侧块粒度推送是强制的**,由 `PersistentCoherentMapScenario` 把门。
|
||||
- **T1(server 导出自己的映射)**:**每次存储定义一次** round trip(v2 修正 v1 的"每 store 生命周期一次"——`TryAdoptLargeStorage` 在存储定义时触发,反复扩容的 arena 付 N 次)。`StorageBufferRegrowScenario` 必须发布 `map-persistent-roundtrips`。
|
||||
- **T0(server 导入 client 分配)**:理想但可用性未知。
|
||||
|
||||
若两台设备都否,IPC 期的该阶段从 8 天缩为 2 天的文档与负面对照。**绝不允许一个平台未知数挡住 260 天的接口工作。**
|
||||
|
||||
---
|
||||
|
||||
## 9. Roundtrip 清单与稳态零 roundtrip 论证
|
||||
|
||||
### 9.1 稳态零 roundtrip 的项
|
||||
|
||||
| 类 | roundtrip | 依据 |
|
||||
|---|---|---|
|
||||
| 全部 draw、clear、blit、copy、dispatch、barrier、XFB 跨度标记、全部 bind、全部 CSO create/bind、全部 `set_*`、全部 buffer/texture 上传、`present` | **0** | 单向记录;present 只查 credit |
|
||||
| **全部 89 个 caps 站点** | **0** | 首次 `MakeEGLCurrent` 的一次 `MGPCaps` 快照(`BackendObject.cpp:341-347`,每次 surface 变更重新武装 `:301`);`callMask` 精确复现 DirectVulkan 少注册的槽位 |
|
||||
| `glGetError` / `glFinish` / `glFlush` | **0** | 前者永远本地(`GL_Getter.cpp:2811-2817`;不变式 `Core.cpp:48-49`),后两者是彻底的 no-op(`Definitions.cpp:111-112`)**且必须继续免费** |
|
||||
| fence 与 query 的**创建**,以及每一次**非阻塞轮询** | **0** | handle 由 client 铸造;未命中合法地答 `GL_UNSIGNALED`/"未就绪"(`BackendObject.h:210-214`、`:236-241`;前端已遵守,`GL_Query.cpp:302-311`) |
|
||||
| `glGetTexImage` / `glGetTextureImage`(**DirectGLES**),**包括 GPU 生成的 mip level** | **0** | client shadow 回答(`CopyTextureImageToClientOrPBO_State`,`GL_Texture.cpp:5368-5420`,取用点 `:6460`)。**v2 显式决定**:`on_mip_levels_generated` **只带形状不带字节**,因为 monolith 也是如此——`EnsureGenerateMipmapStorageAllocated`(`DirectGLES.cpp:6243-6274`)对每个新 level 做 `AllocateStorage(...)` + `MarkStorageDirty(..., false)`,**内容留空**。split 因此与 monolith **行为一致**:GPU 生成的 level 在两种模式下都返回已分配但未填充的影子。**只有 CPU 回退生成路径**(RGB16F/RGB32F,`:6811-6861`)产生真纹素,由 `on_texture_writeback` 回来 |
|
||||
| `glReadPixels` → pack PBO | **0** | fire-and-forget + client 侧 `MarkGpuWritten`。**严格优于 monolith**(`DirectGLES.cpp:9189-9205` 无条件停等) |
|
||||
| `glEndTransformFeedback` | **0** | 取消无限 fence 等待(`GL_Drawing.cpp:1326-1337`),改为对 capture target 置 `MarkGpuWritten`;scatter 由 §7.2.1 的 client 侧路径完成 |
|
||||
| `eglSwapBuffers` | **0 次阻塞 round trip**,一次非阻塞 credit 检查 | 只有 `presentsSent - presentAckSerial >= MOBILEGL_IPC_PRESENT_CREDIT`(默认 1)时才阻塞 |
|
||||
| **`glMultiDrawElementsIndirectCount` / `glMultiDrawArraysIndirectCount`** | **0** | client 从自己的 shadow 解析计数,只做 `SyncPersistentMappedRange()`——**与 monolith 完全相同的 reconcile 集合**(§5.8.1)。**P8 验收要求 `create-indirect` fixture 上该计数器读零** |
|
||||
| **primitive-restart 重写 / multi-draw 展平** | **0** | server 从索引宿主镜像读(D-B7) |
|
||||
|
||||
### 9.2 不可避免的阻塞点(全部罕见,逐条给理由与缓解)
|
||||
|
||||
| # | 站点 | 为什么不可避免 | 缓解 |
|
||||
|---|---|---|---|
|
||||
| 1 | 握手 `Hello`/`Welcome` + 段 fd 传递 | — | 一次 |
|
||||
| 2 | `InitializeEGLDisplay`、`Create/Resize EGL*Surface`、首次 `MakeEGLCurrent` + `InitCapabilities` | 出参 / 返回 `Bool`;caps 只在那一刻存在 | 每 surface 至多一次;surface 回复顺带 `MGPSurfaceInfo`。`SwapEGLBuffers` 不需要回复(`BackendObject.cpp:365-393` 对 client 镜像的 EGL 状态求值) |
|
||||
| 3 | `glReadPixels` → 客户内存 | GL 要求返回时字节已就位 | 像素进 `SEG_REPLY` slot;**逐行写回循环留在 server 内,按操作级批成一段** |
|
||||
| 4 | `glGetTexImage`/`glGetTextureImage`(**DirectVulkan**) | Magma 对只存在于 GPU 的 level 没有 client 可答的 shadow | `get_texture_image` 对"无 GPU 背书"的 level 返回"请从你的 shadow 回答"(`VulkanRenderer.cpp:10691-10704`) |
|
||||
| 5 | GPU-write pending 的 buffer 首次 CPU 读 | shader 在前端背后写了 store | monolith 里**本来就阻塞**(`Managers.cpp:1246` 的 `glFinish()`;`VkBufferManager.cpp:80-85` → `VulkanRenderer.cpp:9807-9817`)。client 保守 pending 集触发,由 `writableMask` 与 `on_gpu_written{ranges}` 两侧收窄 |
|
||||
| 6 | `glClientWaitSync(timeout>0)`、`glGetQueryObject*(GL_QUERY_RESULT)` 未完成、`glBeginConditionalRender` | GL 定义即阻塞;`glBeginConditionalRender` 连 `_NO_WAIT` 模式也阻塞(`GL_Query.cpp:705-706`) | 非阻塞兄弟是 0 round trip。条件渲染谓词**只解析一次**(`Core.h:387-391`),之后每个条件 draw 在 client 侧丢弃,**server 永远不需要那个 query 对象** |
|
||||
| 7 | 分配类入口的 ack | OOM 探测惯用法 | **v2 收窄**:只有 `glBufferStorage`(真同步)与——**若 P0 证实语料里确有 `glRenderbufferStorage` OOM 探测**——`glRenderbufferStorage*`。纹理族在 monolith 里就已经推迟到 sync 时刻,**不标 `kNeedsAck`**(§7.4) |
|
||||
| 8 | `map_persistent`(仅 T1 档) | 应用必须拿到一个不再经过任何 API 调用就能写的地址 | **每次存储定义一次**(v2 修正),不是每 store 生命周期一次;`StorageBufferRegrowScenario` 发布计数 |
|
||||
| 9 | **server 发起的纹理重铸拉取** | server 不保留纹素 | **四条缓解 + 终止符 + 专门的门 + 逐用例发布的计数器**(§7.5)。异步形态下阻塞的是 `mgl-srv-apply` 而非应用线程;零 region 的应答让 server 带着空存储继续,永不永久 park |
|
||||
| 10 | client 侧索引扫描,当源 EBO 在 pending 集里 | monolith 在**同一位置**调 `SyncGpuWrites()`(`VulkanRenderer.cpp:3431`) | §5.8.1 的逐站点表;**`*IndirectCount` 不在此列**(它今天不调 `SyncGpuWrites()`) |
|
||||
| 11 | ring/stage 耗尽、present credit | **节奏,非语义** | `PersistentRing` 的升级路径 + `producerParked` doorbell |
|
||||
|
||||
### 9.3 论证的形式:测量,不是声称
|
||||
|
||||
**验收门措辞**:在**全部 40 个 trace 用例**上发布**逐用例的 roundtrip 计数器、纹理拉取计数器、索引镜像字节数与 `index-bytes-shipped`**。**不做笼统的"零 round trip"声明。** 条件渲染与阻塞 query 的次数按用例列出。
|
||||
|
||||
轮询挂死的防护(继承 `PLAN.md` §7.2/R4)必须有它自己的门:`glFenceSync(); while (glClientWaitSync(s, GL_SYNC_FLUSH_COMMANDS_BIT, 0) == GL_TIMEOUT_EXPIRED) {}` 必须在有界时间内退出。
|
||||
|
||||
---
|
||||
|
||||
## 10. Monolith 保留
|
||||
|
||||
### 10.1 接口在进程内就是直调
|
||||
|
||||
monolith 模式下 `MGPipeContext` 用 backend 自己的函数填充,`MGPipeCallbacks` 用对 `MG_State` 的直调填充,`MGHostSpan.ptr` 指向 client 自己的 shadow(**零新增拷贝**),`MGPipeHandle` 按值走一对寄存器。split 模式下同一张表换成发射器,applier 反序列化后调**同一批 backend 函数**。**全世界只有一份 backend 实现。**
|
||||
|
||||
### 10.2 热路径的间接成本,**动态口径**的诚实版(v2 重写)
|
||||
|
||||
v1 这张表把今天的每 draw 状态获取写成 "Espryt 124 / Magma 169 次 accessor 调用"。**那是静态调用点数**(§2.1(d) 的定义),不是动态每 draw 调用数——树里每一处都已被 memo 门控(§2.3.1 逐条列了早退位置)。按动态口径重写:
|
||||
|
||||
| | 今天(动态稳态) | 之后(动态稳态) |
|
||||
|---|---|---|
|
||||
| 每 verb 的分发 | 1 次间接调用 + 3 个寄存器实参(`DrawArrays`) | 1 次间接调用 + **~48 B 固定头**(`MGPDrawInfo`)+ 按 flag 的变长尾。**这是一项新增成本,不是持平** |
|
||||
| 每 draw 的状态获取(值类) | Espryt:1 次 `Uint16` 比较(`DirectGLES.cpp:2016-2018`)早退;未命中时 1.2KB×3 段 memcmp。Magma:1 次版本比较(`:4982`)+ 1 次版本比较(`:5888`);pipeline memo 未命中时 ~40 次 accessor 走查(`:5155-5200`) | 1 次 `Uint16` 比较;pipeline 版本动了才算 ~25-30 字的子集哈希 + 1 次 map 探测(D-B1);动态子集动了才发 ~200 B |
|
||||
| 每 draw 的状态获取(对象类) | Espryt:`SyncNeccessaryTextures` 6 值键 + `PairingsIntact` + 每条目 `IsDrawSyncClean`;`CurrentUnitBindingsEpoch` 三值快门。Magma:`TrySetupDrawFastPath` ~10 次 accessor + ~20 次字比较 + 两次**有损**版本求和(`:6249-6250`) | 5 个聚合世代各 1 次 `Uint64` 比较(推论 4);命中才走 touched 前缀 + 集合 hash;hash 未变**不发**(§5.4-4) |
|
||||
| memo 查表 | 对指针位做斐波那契散列的直接映射探测 + owner 相等性(3 次/draw) | 按 slot 的数组下标 |
|
||||
| 真删除的机制 | — | **~372 行 per-draw 失效发现**(§2.5) |
|
||||
| 搬到 client 的机制 | — | **~175 行**(去抖 + 完备性解析,§2.5) |
|
||||
|
||||
**结论(诚实版)**:推送在稳态**应当**是净减少——省掉三次散列探测、一次 1.2KB 三段 memcmp(换成 ~30 字哈希)、两次有损求和、`CurrentUnitBindingsEpoch` 的 owner 走查;付出 `MGPDrawInfo` 的 payload 构造与集合 hash。**但差距远小于 v1 声称的量级**,而且 §2.7 表明 monolith 的净行数是**增加**的。**所以本设计的 monolith 论据是 §10.3-④ 的逐线程 CPU 数字,不是删除行数。**
|
||||
|
||||
两个诚实的告诫:
|
||||
1. **可达性遍历是搬走了,不是消失了**,头号指标必须是**逐线程 CPU 时间**。
|
||||
2. **Magma 的 `SetupDrawSnapshot` 快路径命中率在两种模式下会合法地不同**,A/B 比的是**渲染输出与计数器**,永远不是 memo 轨迹。
|
||||
|
||||
两个 backend 编进同一个共享库(`CMakeLists.txt:356-383`、`:485`),backend 在 init 时锁存一次(`ConfigLoader.cpp:212-225`),所以去虚化在两种形态下都不可得,也都不需要。**函数指针 struct 而非虚基类**的理由见 §4.1。
|
||||
|
||||
### 10.3 替代字节一致门的五部分验证门
|
||||
|
||||
**先把成本写在明面上**:`PLAN.md` §12 第 4 层在方案 B 里**按构造死亡**。这是方案 B 的代价,必须写进设计文档而不是藏起来。
|
||||
|
||||
**①(v2 扩为三道)接口纯度门。**
|
||||
- **门 A(include 图)**:disaggregated 配置编译 `MG_Backend` 时把 `MG_State/GLState` 从 include 搜索路径移除(或断言 `-H` 输出)。**这是唯一能因它存在的理由变红的检查**——`nm --undefined-only` 对"只 include 不调用"是瞎的,而 `RenderState.h:12 → FramebufferObject.h:12-13 → TextureObject.h / RenderbufferObject.h` 正是这种耦合,`RenderStateParameters` 用 `FramebufferObject::MAX_DRAW_BUFFERS` 定长(`:263, 273`)。依赖 P0.5 的 `MGPipeValueTypes.h`。
|
||||
- **门 B(符号)**:`nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空。
|
||||
- **门 C(未声明)**:`grep -c 'pGLContext' MG_Backend/` == 0(grep `pGLContext` 不是 `pGLContext->`)。**三道门都只跑非 verify 构建**(D-B5)。
|
||||
- **外加**一条 debug 断言"每个 backend memo 键都是 `{slot, gen}` 对,永不是裸前端指针",由 `HandleRecycleScenario` 支撑——**这个场景在 0e 重键之前必须在至少一个 backend 上是红的**。
|
||||
|
||||
**② 语义影子比对(`MOBILEGL_PIPE_VERIFY=1`)——决定性的那一条。**
|
||||
阶段 B 期间两套状态模型活在同一个地址空间:tracker 再用 `SnapshotFromGLContext()` 填一份 `PipeInputs`,G4 生成的比对器**逐字段**、**每 draw** 与推送版本比对,打印第一个分歧字段名与 draw 序号。抓三种事:(a) tracker 忘了推的字段;(b) **dirty 位触发得太少**——危险的那个方向;(c) 两条路径上被变换得不一样的值。第三种 CI 模式,跑全部 40 个 trace 与 367 个集成测试;~5-10× 慢,永不出货。
|
||||
**必须逐字段比而不是 `memcmp`**:`DirectGLES.cpp:2029-2033` 明确记录 `RenderStateParameters` 的 memcmp 会因 padding false-DIFFER(无害)但永不 false-match——比对器要零误报。
|
||||
**v2 修正 A:verify 需要"保留模式"。** 消费即清的组(纹理 dirty rect)在发射后无法从头重算,所以 verify 在纹理 subdata 上是瞎的——而那正是最危险的子系统。`MOBILEGL_PIPE_VERIFY=1` 时 tracker 保留清除前的集合,G4 比对**发射出去的** `(unionBox, regionCount, regions[])`(§7.3)。
|
||||
**v2 修正 B:verify 活过 P13。** `SnapshotFromGLContext()` 与它的 `MG_State` include 整体包在 `#if MOBILEGL_PIPE_VERIFY` 里保留;纯度门只跑非 verify 构建(D-B5)。P13 另交付**录制-金标**模式(MGPipe recorder,§10.4-9)作为不依赖 `MG_State` 的长期语义门。
|
||||
|
||||
**③ 行为 A/B。**
|
||||
全部 ~40 个 trace 用例(`tools/trace_replay/trace_cases.json`,默认 SSIM 阈值 0.99)在 `{monolith-pull, monolith-push, split}` 三种下同一判定、SSIM ≥ 0.99;`ctest -L integration-gpu` 在 `DirectGLES.` 与 `DirectGLES.Pipe.`/`DirectGLES.Split.`(以及 DirectVulkan 对)之间产生**逐名相同**的通过/失败集;428 个单元测试全绿;CTS 逐后端 conformance 在 0.5 个百分点内,按本项目的逐后端表格式上报(行 = GL 版本/扩展,列 = 状态计数,rate = Pass/(Pass+Fail),NS 不进分母)。
|
||||
**两个 Create fixture 带 `coherent_as_flush: true`**,必须在两种模式下都开着该开关跑。
|
||||
**v2 补充:`TextureUploadShapeScenario`**——上传形状(box vs N region、作业数)录金标比对,因为 SSIM 对 +6ms 悬崖完全不敏感(§7.3)。
|
||||
**v2 补充:参考构建的定义。** P2 之后 monolith 本身已经变了,所以逐名基线必须明确为**"P1 出口的重构后 monolith"**,而 P1 出口本身要先用 verify 证明重构等价于 `81b17c0b`。**`81b17c0b` 的 monolith 只作为 §10.3-④ 性能对照的锚点,不作为逐名功能基线。**
|
||||
|
||||
**④ monolith 性能不回归。**
|
||||
两台设备(`35d0befa` Adreno 830、`3B159D009VZ00000` Mali),reboot-clean、同热窗口、配对 A/B,用 `tools/bench.sh` + trace replay 的 `--benchmark --benchmark-tail-frames --benchmark-result` 逐帧 JSON。**指标是逐线程 CPU 时间**,monolith-push 在 **p50 与 p99** 上都要落在 monolith-pull 的噪声内。CPU 定频按本项目协议。
|
||||
**v2 补充三条**:(a) **绝对阈值**——tracker 每 draw 的 ns 必须公布并设上限,因为真实拉取基线只有 10-25 次 accessor(§2.3.1),相对噪声阈值会平凡通过;(b) **Blaze3D blend-toggle 微基准**(enable/draw/disable/draw,MC batch 速率)单列,它是 D-B1 的判据;(c) **负面对照**——关掉 CSO 内容寻址(`MOBILEGL_PIPE_PUSH` 的一位)重跑,把"推送更慢"与"CSO 设计更慢"分开。
|
||||
|
||||
**⑤ 覆盖 + poison + handle 纪律。**
|
||||
`gen_pipe.py` 重生成 477 行 inventory 的 MGPipe 映射列,0 UNMAPPED,`git diff --exit-code`;**`gen_pipe_dirty_surface.py` 重生成 mutator→聚合世代 映射,0 未映射**(推论 4);`PipeInputs::m_filledGen` 的**逐 verb**世代 poison(§6.2.2);G7 的 render-state setter 一致性测试;P13 的 `static_assert(sizeof(ResidualValueBlock) == 0)`;`ResidualValueBlock` 的逐成员 `offsetof` 断言。
|
||||
|
||||
**两条字节级等式仍然幸存**:`MOBILEGL_BUILD_DISAGGREGATED=OFF` 时 `nm --defined-only libMobileGL.so | grep MG_Remote` 为空且链接行不增加任何库;`nm -D libMobileGL.so | grep mobilegl_server_main` 在 RelWithDebInfo 里命中。
|
||||
**符号与 `.text` 漂移每阶段作为信息性指标发布**——一次无法解释的跳变仍然是一个 smell,只是不再是一条断言。
|
||||
|
||||
### 10.4 monolith 侧净收益清单(即使 IPC 永不上线也成立)
|
||||
|
||||
1. **~372 行 per-draw 失效发现机制真删除**(§2.5),另有 ~175 行搬到 client。**注意 §2.7:monolith 的净代码量是增加的**(约 +6,650 手写 + 4,000 生成),所以这一条是**佐证**,不是主论据。
|
||||
2. **复用地址 ABA 一整类不可表达**:D1/D2/D3/D10/D11/D13/D14/D16/D17/D20 全部由 `{slot, gen}` 关闭。
|
||||
3. **FBO → program 排序 hazard 消失**:`DirectGLES.cpp:2712-2732` 的 fragColor 重推导 workaround 与 `g_broadcastMemo*` 删除(机制是惰性特化,D-B3 v2)。
|
||||
4. **一处分层倒置消失**:`SwapchainObject.cpp:276-330` 不再往 `MG_Impl` 的 `pDefaultFramebufferInfo` 里写。
|
||||
5. **两个潜伏 bug 顺带修掉**:D21(`m_xfbCounterSlotByObject` 用裸 GL name 做键,`VulkanRenderer.cpp:11136-11146`)与 `RenderbufferObject` 缺 `GetLifetimeId()`。**两条都先独立落 `dev`。**
|
||||
6. **一个死能力被暴露**:`CapabilityInput::FramebufferSrgb` 与 `DepthClamp`(`RenderState.h:165, 168`)**没有任何存储**——`SetCapability` 落到 `default: // not supported currently`(`RenderState.cpp:380`),`IsCapabilityEnabled` 返回 `false`(`:428-429`)。**六个 backend 读点今天恒为 false。** **必须在渲染状态 chunk 表冻结之前回答**(它决定 pipeline/dynamic 划分里要不要这个字段)。
|
||||
7. **一次 glslang 编译离开 monolith 启动路径**(Magma 的内部 shader 烘焙)。
|
||||
8. **`inproc` = monolith 的渲染线程**,且只需隔离两个进程全局——本项目手上最大的单一 CPU 杠杆。
|
||||
9. **`MG_Test` 的 mock backend 顺理成章变成 MGPipe recorder**:`tools/trace_replay` 获得一种比 apitrace 精确得多的 MGPipe 级录制格式(记录的是**已解析**的状态),**而且它是 P13 之后不依赖 `MG_State` 的长期语义门**(D-B5、开放问题 11 的答案)。
|
||||
@@ -0,0 +1,351 @@
|
||||
## 11. 分阶段实施计划
|
||||
|
||||
> **通用纪律(每个 commit 都适用)**:默认 ALL target 必须能完整构建;禁止提交热路径插桩;**每个门必须能因它存在的理由变红**;Windows 机器不是正确性门(其 Vulkan 缺 `vkCreateHeadlessSurfaceEXT`,占该机 567 个基线集成失败中的 423 个);设备对比走 reboot-clean + 同热窗口配对 A/B,CPU 定频按项目协议(大核 1.96 / 小核 1.55GHz,GPU 拉满,40°C 门槛);**每个阶段的出口都跑一次 §10.3 的五部分门**;**每个阶段的性能判据都是逐线程 CPU 时间**,不是墙钟帧时。
|
||||
> **两条跑道**:P0-P4a、P3b/P4b、P7、P8、P13 是 **monolith 跑道**,每一段都可独立交付、可随时中止且 monolith 严格好于起点;P5、P6、P9-P12 是 **IPC 跑道**,整段继承 `PLAN.md` §6-§13。
|
||||
> **v2 排期修订说明**:v1 的阶段天数与它自己的 §6.4/§6.5 逐子系统表互相矛盾(例如 P3a 给 12 天,而它包含的三行合计 22-29 天,等于"再基线检查点"按构造必然触发;P7 报 48 天下界而同口径是 85-111)。**本节的每个天数都是它所含 §6.4/§6.5 行的求和**,算术在 §11.5 公布。
|
||||
|
||||
### P0 — 卫生、度量、门与骨架(9-11 天)
|
||||
|
||||
**交付物**
|
||||
- **清工作树 per-draw `fprintf`**:`DirectGLES.cpp:290-303`、`:640-663`、`Managers.cpp:875-877`(后者在 `pendingMutex` 临界区内)。CI 加 grep 门禁止 `MG_Backend/` 与 `MG_State/` 下出现 `fprintf(stderr` / `printf(`。
|
||||
- **`TracyPlot` 逐帧计数器,装在边界两侧**,**字节类**:`cmd-records`、`cmd-bytes-per-draw`(**直方图**,`SEG_CMD` 的定尺依据)、`stage-buffer`、`stage-texture`、`stage-vertex-client`、`stage-index-client`、`stage-ubo-global`、`stage-ubo-named`、`persistent-map-push`、`server-ring`、`server-staging`、`residual-value-block`、`index-mirror-bytes`、`index-bytes-shipped`、`texture-pull`;**调用类(v2 新增,`PLAN.md` 与 v1 都没有)**:每 draw 实际执行的 accessor 次数、每个 memo 门(`SyncRenderState` 早退、`SyncNeccessaryTextures` 键比较、`CurrentUnitBindingsEpoch` 快门、`TrySetupDrawFastPath`、pipeline memo、`ApplyDynamicDrawStateTail`)的命中/未命中、`resource_subdata` 发射次数与上传作业数。**没有调用类计数器,P2 的判据仍然是猜**(§2.3.1)。两台设备取基线。
|
||||
- `MG_Pipe/PipeCalls.def` + `MGPipeTypes.h` + `MGPipeHandles.h` + `MGPipeCallbacks.h`:**完整调用目录,即使暂未实现的条目也占位**(记录编号绝不 churn)。
|
||||
- `scripts/gen_pipe.py` 与七个生成器 G1-G7 的骨架 + CI `pipe-gen-check`(重生成 + `git diff --exit-code`)。
|
||||
- `scripts/gen_pipe_dirty_surface.py` 骨架(推论 4)与 CI 接线。
|
||||
- **`scripts/check_doc_citations.py`**(v2 新增):`docs/**` 里每个 `file:line` 必须在基线提交上解析到存在的行。**v1 有一批 `SamplerObject.h` 引用指向 160 行文件的 468-551 行**;本文件已修正,lint 防止再犯。
|
||||
- `MOBILEGL_PIPE_PUSH` / `_VERIFY` / `_STATS` / `_LEGACY_MEMOS` / `_TEXEL_RETAIN_MB` / `_INDEX_MIRROR_MB` 在 `ConfigLoader.cpp` 与既有开关并列解析。
|
||||
- **三个严格 no-op 的免费收益**:`GetIntegeri_v`/`GetInteger64i_v`/`GetProgramiv` 的纯前端 case 移回 `MG_Impl`(Espryt 14 / Magma ~10 个读点);`RenderbufferObject::GetLifetimeId()`(**不加 `GetVersion()`**);D21 重键——**这一条是潜伏 bug 修复,先独立落 `dev`**。
|
||||
- 回答两个阻塞问题:`FramebufferSrgb`/`DepthClamp` 无存储是潜伏 bug 还是有意为之(§10.4-6,**必须在渲染状态 chunk 表冻结之前**);**语料里是否存在 `glRenderbufferStorage` 的 OOM 探测惯用法**(决定 `kNeedsAck` 要不要标它,§7.4)。
|
||||
- `MG_Remote/{Protocol,Transport}` 骨架与 `PLAN.md` P0 完全一致(**`SCM_RIGHTS` 第一优先**);`protocol.fbs` + 提交的 `protocol_generated.h` + `flatc-check`;`MG_Test/Wire/`。
|
||||
- **`PLAN.md` P0 的两个 spike 原样跑**:spike A(Android 交付链);**spike B(external memory 导出,两台设备)**。
|
||||
|
||||
**验收**:`AdvertisedLimitsScenario`(6 个测试)绿;367 集成 × 2 backend + 428 单元逐名不变;40 个 trace 全绿;两台设备的基线**字节、调用、逐线程 CPU** 数字记录在案;spike A/B 出结论(spike B 直接决定 P11 规模);citation lint 全绿。
|
||||
|
||||
### P0.5 — 值头与制品头抽取(6-9 天)★v2 新增,**P1 与 P7 的硬前置**
|
||||
|
||||
**交付物**
|
||||
- **`MG_Pipe/MGPipeValueTypes.h`**:把 `MAX_DRAW_BUFFERS`、`PerBufferBlendState`、`StencilFaceState`、`PixelStoreParameters`、`RenderStateParameters`、`SamplerParameters`、`BorderColorForm`、`VertexAttribute`、`VertexBufferBindingPoint` 与相关枚举搬进来,**它不 include `MG_State/GLState` 的任何东西**;`RenderState.h` / `SamplerObject.h` / `VertexArrayObject.h` 反过来 include 它。
|
||||
**必须做的理由**:`RenderState.h:12` include `FramebufferState/FramebufferObject.h`,后者 `:12-13` 再 include `TextureObject.h` 与 `RenderbufferObject.h`;`RenderStateParameters` 用 `FramebufferObject::MAX_DRAW_BUFFERS` 给两个数组定长(`:263, 273`)。所以 v1 的"共享值头白名单"不是叶子集,把它交给"纯净的 `MG_Backend`"会拖进整张类图,而 `nm --undefined-only` 看不见(只 include 不调用不产生未定义符号)。
|
||||
- **`MG_State/GLState/ProgramState/ProgramArtifacts.h`**:把 `TypeFacts`(`ProgramObject.h:44`)、`ResourceReflection`(`:76`)、`XfbVarying`(`:1146`)、`LinkArtifacts`(`:1210`)、`SpirvArtifacts`(`:1409`)抽出来,**不 include `ShaderObject.h`、不 include `SpvcSession.h`**;更新 7 个 includer(`ProgramFactory.h`、`UniformManager.cpp`、`VulkanRenderer.cpp`、`ProgramInterface.cpp`、`ProgramLinkTask.h`、`ProgramObject.h`、`ProgramTranslationCache.h`)。
|
||||
**必须做的理由**:server 要**反序列化进**这五个类型就必须有它们的定义,而它们今天住在会拖进 glslang(`ShaderObject.h:12` → `ShaderCompileTask.h`;`:146` 返回 `SharedPtr<glslang::TShader>`)与 spirv_reflect(`ProgramObject.h:14` → `SpvcSession.h`)的头里。**没有这一步,P7 的 `nm -D | grep glslang` 判据不可达。**
|
||||
- **CI include 闭包断言**:`MGPipeValueTypes.h` 的 `-H` 闭包里没有 `MG_State/GLState/`;`ProgramArtifacts.h` 的闭包里没有 glslang / SPIRV-Cross / spirv_reflect 任何头。
|
||||
- `ProgramArtifacts.h` 的 `Visit()` 归档 + `sizeof` 绊线(§4.5.5)。
|
||||
|
||||
**验收**:全套现有测试逐名不变(这是一次纯搬移);两条 include 闭包断言绿,且**人为把一个 `MG_State` include 加回 `MGPipeValueTypes.h` 能让它变红**;`nm --defined-only` 与 `.text` 变化可逐符号归因(搬移会改变某些内联决策,允许,但要解释)。
|
||||
|
||||
### P1 — `PipeInputs` 替换与 verify harness(10-13 天)
|
||||
|
||||
**交付物**
|
||||
- `MG_Backend/MGPipe/PipeInputs.h`:每个 backend 真正用到的 `GLContext` 方法一个访问器(Espryt 32 / Magma 55),**字段类型与今天读到的完全一致**,按 memo 键组织。
|
||||
- 机械 `sed`:`MG_State::pGLContext->` → `MGB_CTX->`(**293 处**);**外加逐条手工转换 58 行非箭头用法**(§2.4:~34 处 `MOBILEGL_ASSERT` 真值判定删除、7 处空守卫改直读、3 处 patch 三元、`DirectGLES.cpp:146` 的 `.get()` 裸指针捕获与 `:142` 的 `decltype` 别名、14 处 `!= nullptr`、1 处注释)。**这份 58 行清单是本阶段的显式交付物。**
|
||||
- **逐 verb 类填充点**(v2 修正,§6.2.1):G5 从 `PipeCalls.def` 生成"每个 `kCtxVerb`/`kCtxObject` 调用可能读哪些 `PipeInputs` 字段"的表,并在 `MG_Impl` 的 ~93 个边界站点上生成对应的 validate/fill 调用。**不是只在 `PrepareForDraw`/`SetupDraw` 两处**——`MG_Impl` 用到的 70 个表项里 ~48 个不是 draw/dispatch,其中多个自己就读 `pGLContext`(`UpdateTextureBindingAtTarget` `:6051-6052`、`PackStateFromContext` `:6129`、`Clear` `:4106/:4165`、`BlitFramebuffer` `:5988-5989`、`GetTexImage` `:9254-9257`、DSA by-name `:4038-4043`、`:7417-7418`),而 `:1501-1502` 的注释已经点明"for every non-draw call site (Clear, readbacks)"。
|
||||
- **G5 的逐 verb 世代 poison**:`m_filledGen[f] == m_currentVerbSerial`(非 sticky 字段);debug 与 disaggregated 构建里读陈旧/未填字段 = `Fatal{UnmigratedPipeInput, "<field>@<verb>"}`。
|
||||
- **G4 的 `MOBILEGL_PIPE_VERIFY=1` 逐字段影子比对器** + 第三种 CI 模式接线。
|
||||
- **20 处 `SyncPersistentMappedRange` + 6 处 `SyncGpuWrites` 的逐站点归属表**(§7.2、§5.8.1),作为文档交付物。
|
||||
|
||||
**验收(v2 修正)**
|
||||
- **`nm --defined-only` 在 pull 构建里不变;`.text` size 变化必须能逐行归因。** v1 要求"完全一致",但本阶段自己的交付物里就有 ~24 处会生成代码的转换(7 处 `if (pGLContext)` 空守卫、14 处 `!= nullptr`、3 处三元)——只有 ~34 处 `MOBILEGL_ASSERT` 是真免费(`Defines.h:114` 在非 debug 下宏为空)。此外 `SnapshotFromGLContext` 与 G4/G5 机制必须包在 `#if MOBILEGL_PIPE_PUSH/_VERIFY/DEBUG` 里,pull 构建才不多出调用。**把空守卫与三元的重写推迟到 P2**(那时字段确实永远有效),本阶段只做 assert 删除与 `sed`,则 `.text` 差异可压到零附近。
|
||||
- 全部 40 个 trace 与 367 个集成测试在 `MOBILEGL_PIPE_VERIFY=1` 下零分歧;
|
||||
- **故意损坏一个快照字段能让 verify 门变红**;
|
||||
- **故意在某个非 draw verb(`glGenerateMipmap`)的填充表里漏一个字段,能在那条 verb 上触发 poison Fatal**——不是在某个后续 draw 上。
|
||||
|
||||
**★ 第 25 天(低端估计)— 最早可见里程碑:**零产品风险地证明"推送等价于拉取",逐 draw 逐字段。**这不是 GO/NO-GO**(它没有性能数字,也没有 Track H 单位成本)。
|
||||
|
||||
### P2 — 值推送:渲染状态 CSO(双后端)+ 第一片 Track H + 残余值块(18-26 天)
|
||||
|
||||
**交付物**
|
||||
- `MG_Impl/Pipe/Tracker.{h,cpp}`:dirty 位(§5.2,值类用既有计数器、**对象类新增 5 个聚合世代**)+ §5.3 的不变式 + §5.4-4 的集合 hash 抑制器骨架。
|
||||
- **`MG_State` 的 5 个聚合世代**(`TextureState` 两个、`BufferState`、`VertexArrayState`、`FramebufferState` 各一,合计约 20 行)+ `gen_pipe_dirty_surface.py` 的首轮映射与 CI 接线。
|
||||
- `MG_Pipe/MGPipeRenderStateSpans.{h,cpp}` + **G7**:pipeline/dynamic chunk 表(从 `VulkanRenderer.cpp:4826-4906` 原样搬来)+ **遍历每个 `RenderState` public setter 断言 `pipelineSubsetHash 变 ⟺ m_pipelineStateVersion 变` 的测试**。
|
||||
- `MG_Impl/Pipe/CsoCache`:64 项 LRU,键是 **pipeline 子集**的 xxHash(**不是整块**,D-B1 v2)。
|
||||
- `create_render_state` / `bind_render_state` / **`set_dynamic_state`**:Espryt 侧 `RenderStateImpl` 的 693 行函数体、单 `Uint16` 早退、三段 memcmp、`g_syncedColorMaskAlphaWidenMask`、dual-source decline **一行不动**(消除 4 个读点);Magma 侧 `ComputePipelineStateHash` / `GetOrCreatePipeline` / `ApplyDynamicDrawStateTail` 改从 CSO 与动态 payload 取(消除 ~55 个读点)。两个版本号都过线。
|
||||
- `set_pixel_pack_state`(PACK only)、`set_patch_state`、`set_vertex_attrib_defaults`;P1 推迟的空守卫/三元重写。
|
||||
- **`set_residual_value_state` + `ResidualValueBlock`**(§6.3):`static_assert(sizeof == MGL_RESIDUAL_BLOCK_SIZE)`(逐阶段**下调**)+ **逐成员 `offsetof` 断言** + split 下逐字段序列化。
|
||||
- **第一片 Track H(v2 新增,让 GO/NO-GO 测的是它要决定的事)**:Espryt 子系统 0b(`SlotAllocator` + 6 个 registry → slot 数组 + 删 `TwinLookupMemo`×3 / `OwnerEquals` / `g_fbSlotCache` / 2 个 GC 扫描)与 Magma 子系统 4(`VertexInputStateFactory` / `VaoDrawMemo` 重键,**删掉写进前端 VAO 的后端堆裸指针**)。
|
||||
- **`MOBILEGL_PIPE_LEGACY_MEMOS`** 编译期开关(§6.7):让前两波 handle 化保留一个**真正的**旧-vs-新臂。
|
||||
|
||||
**验收**
|
||||
- 367 集成 × 2 backend × 2 模式(pull / push)逐名相同;40 个 trace 在 monolith-push 下 SSIM ≥ 0.99,双后端;`ClipDistance`、`SampleMaskScope`、`SampleVariables`、`DualSourceBlend`、`ViewportArray`、`PrimitiveRestart` 场景绿;verify 模式零分歧;
|
||||
- **`HandleRecycleScenario` 绿,且它在 0b 重键之前必须是红的**;
|
||||
- **G7 的 setter 一致性测试绿,且人为把一个字段从 pipeline chunk 表里拿掉能让它变红**;
|
||||
- **两台设备 reboot-clean 配对**:monolith-push 在 p50 与 p99 逐线程 CPU 上落在 monolith-pull 噪声内或更好,**并且 tracker 每 draw 的绝对 ns 落在预设上限内**(相对阈值不够,§10.3-④a);
|
||||
- **Blaze3D blend-toggle 微基准**(enable/draw/disable/draw,MC batch 速率)单列发布;
|
||||
- **负面对照**:关掉 CSO 内容寻址重跑,把"推送更慢"与"CSO 设计更慢"分开。
|
||||
|
||||
**★ 第 43 天(低端估计)— GO/NO-GO 决策点。** 此刻手上有:verify harness、双后端已推送的渲染状态、真实 CPU 增量与绝对 ns、Blaze3D 微基准、CSO 负面对照、**Track H 在两个 backend 的最便宜子系统上的实测单位成本**。
|
||||
**退回成本(诚实版)**:P0 与 P0.5 对方案 A 也有用(后者同样要序列化反射),真正只为方案 B 花的是 **P1 + P2 ≈ 28-39 天**。**若 CPU 数字为负、或 Track H 单位成本超估计 50%,退回方案 A 损失 28-39 天。**
|
||||
|
||||
### P3a — handle wave 1(Espryt):buffer、VAO(18-23 天)
|
||||
|
||||
> handle 基建(0b)已在 P2 交付。
|
||||
|
||||
**交付物**:7 个 `BufferBackendOps` → `resource_create/respecify/destroy`、`resource_subdata`、`buffer_subdata_resident`(**可 null,保住 Magma 的差异**)、`resource_flush_range`(带应用真实 access flags)、`resource_readback`、`map_persistent`(**不碰实现**);pool 与延迟释放机制原样搬;`create/bind/delete_vertex_elements_state`(**两个视图都带**;`IsLong` 与 `Type` 分开);`set_vertex_buffers`(**`baseInstance` 是显式字段**,不再是调用方武装的 `ScopedFetchBaseInstance` 作用域);`set_index_buffer`(带 restart index 与模式);Adreno 禁用属性 SIGSEGV workaround 原样保留;`MOBILEGL_PIPE_LEGACY_MEMOS` 分支维护。
|
||||
|
||||
**验收**:全套门(monolith-push,DirectGLES);`LargeArenaAdoption`、`ResidentIndex`、`StorageBufferRegrow`(**发布 `map-persistent-roundtrips`**)、`AtomicCounter`、`BufferTexture`、`CrossFrameBuffer`、`SsboArrayLength`、`SsboArrayDynamicIndex`、`VertexArrayEnableDisable`、`VertexAttribBinding`、`DoublePrecision`、`DrawParameters`、`MultiDraw`、`PrimitiveRestart` 场景;`create-indirect`、`create-instancing`、`rd12-odinlite`、`improved-transparency-26.3`、`fabric-sodium` trace SSIM ≥ 0.99;MC 26.3 在 Adreno 上 p99 不变(16MiB 采纳结果不得回归)。
|
||||
**⚠ 再基线检查点 1:若 P3a 超过 27 天(上界 +50%),"窄 handle 化"的前提就是错的,必须在 P4a 开始之前重定基线。**
|
||||
|
||||
### P4a — handle wave 2(Espryt):FBO / 纹理 / sampler / program 的身份与描述符(26-34 天)
|
||||
|
||||
**刻意推迟到首帧之后的部分**:memo 重键、dirty 归属反转、跨步描述符改造、program 陈旧性重构(→ P3b/P4b)。
|
||||
|
||||
**交付物**:`set_framebuffer_state`(8 个 `MGPSurface` + **client 解析后的 `readSurface`** + 内联 `internalFormat` + `contentHash` + `isDefault` 保留 handle,退役 4 处 `pDefaultFramebufferInfo` 读);四个跨对象 mask 在推送时刻推出;`create/bind/delete_sampler_state`(`SamplerParameters` 逐字节含 `borderColorForm`,`SamplerObject.h:66-96`);`create/delete_sampler_view`(**只带视图限制**)+ **`set_texture_params`**(D10:base/max level、swizzle、dsMode、LOD 钳、`forceResync`);`set_sampler_views`(client 侧解析,**无 stage 维度**)+ `bind_sampler_states`;`set_shader_images`;`create/bind/delete_shader_state`(逐 stage SPIR-V + `ProgramArtifacts.h` 的 `Visit()` 全结构体归档);`set_draw_program` / `set_dispatch_program`;`set_global_constants`;`CompositeResolver.cpp`;纹理与 renderbuffer 的 `resource_create/respecify/subdata`。emulation 路径在 split 模式下**显式 Fatal** 直到 P8。
|
||||
|
||||
**验收**:全套门;`CrossFrameBuffer`、`LayeredAttachmentShape/Barrier`、`SnormAttachment`、`RenderbufferBlendFormat`、`FragmentOutputArrayIndex`、`Orientation`、`ClearThenReadPixels`、`FragCoordOrigin`、`TextureView`、`ProgramPipeline`、`PostLinkAttach`、`RelinkStageSet`、`SpirvShaderBinary`、`AsyncCompile`(6 个)场景;**新增"只作 FBO attachment / 只作 image 单元 / 只作 CopyImage 端点的纹理其 `glTexParameter` 生效"场景**(D10 的门,**必须在 `set_texture_params` 落地前是红的**);`KHR-GL46.direct_state_access.framebuffers*` 与整个 `packed_pixels` 块在两台设备上绿(**~3300 个 framebuffer/用例,handle 复用的压力测试**)。
|
||||
**⚠ 再基线检查点 1b:若 P4a 超过 39 天,同上处理。**
|
||||
|
||||
### P5 — 传输 + inproc applier + 发射表(12 天)
|
||||
|
||||
**交付物**:`MG_Remote/Client` 的发射表实现 `MGPipeScreen`/`MGPipeContext`;`Server/PipeApplier.cpp`;`ServerLoop`(`mgl-srv-io` + `mgl-srv-apply`,后者终身持有原生 context);单一 hook 点 `MG_Backend/Init.cpp:48-70` 装 `BackendObject_Remote`;`MGPCaps` 快照;一条阻塞 `read_pixels`;client 侧保守 `MarkGpuWritten` 与 `emitSeq`;**client 侧块粒度 persistent-map 推送**(T2 档下强制);`InProcessTransport`。
|
||||
|
||||
**v2 规范条款:`InProcessTransport` 必须走与 spawn **完全相同**的 G3 编解码路径**,只在门铃/拷贝机制上不同。否则第 99 天的里程碑证明不了 wire 完整性,而 P6(第 104 天)才在关键路径上发现缺口。**`PipeApplier` 里加一条 debug 断言:任何传输下都不得有 `SharedPtr` 或裸前端指针跨过 applier 边界。**
|
||||
|
||||
**验收**:`ctest -R 'DirectGLES\.Split\..*(ClearThenReadPixels|Triangle)'` 在 `MOBILEGL_TRANSPORT=inproc` 下绿;**OpenRA trace 在 split 模式下 SSIM ≥ 0.99**;**`PersistentCoherentMapScenario` 绿**;**两个角色的峰值 RSS 记录在案**,作为对 `PLAN.md` R14 的基线;`persistent-map-push` 字节量出数;任何未迁移的 `PipeInputs` 字段读产生 `Fatal{UnmigratedPipeInput}`。
|
||||
**★ 第 99 天 — 首个 IPC 帧(`inproc`)。诚实标注:这是缩减路径**——client 数组、indirect-count 解析、索引宿主镜像在 split 下仍是 Fatal,全功能要等 P8。
|
||||
|
||||
### P6 — spawn transport(5 天)
|
||||
|
||||
**交付物**:`SocketTransport`(socketpair + fork/execve,**显式 envp 剔除 + `mobilegl_server_main` 内强制 Monolith 的双保险**);`ServerMain`;`MOBILEGL_IPC_SERVER_PATH` 为主 + `dladdr` 兜底;就绪握手有界重试;client EOF 即时退出;server 死亡的 device-lost latch;trace-replay 的 `SPLIT` 后缀与 `-DTRACE_TRANSPORT=` 接线。
|
||||
|
||||
**验收**:P5 全部测试在 `MOBILEGL_TRANSPORT=spawn` 下绿;fork 链测试断言进程树只多一个子进程;`HeadlessGL` 的 fork 预检交互测试无孤儿 server;`run_android_retrace_local.py --case OpenRA --backend DirectGLES` 在 `35d0befa` 上 SSIM ≥ 0.99。
|
||||
**★ 第 104 天 — 首个跨进程帧(缩减路径)。**
|
||||
|
||||
### P3b / P4b — 深化(Espryt):memo 重键、dirty 反转、跨步描述符、XFB scatter、回读(29-38 天)
|
||||
|
||||
**交付物**:重键 `ResolvedDrawBuffers`、`PendingAttribValueMask`、`ConvertedFloat64Stream`、`SyncCurrentFBO` 四元组戳、`ResolvedTextureBindingMemo`、`SamplerPassMemo`、image sweep、program registry 到 `{slot, gen}`;**server 侧删** `g_unitTextureSyncList`、`g_fboTextureSyncList`、`g_unitSamplerLookupMemos`、`g_imageSweep*`、`DirectGLES.cpp:1372-1489` 的 ~115 行 unit-bindings epoch 推导,**同时在 `MG_Impl/Pipe/Tracker.cpp` 落地对应的集合 hash 抑制器**(§2.5、§5.4-4);**dirty 归属反转**(§7.3,client 保 rect 模型与**按存储属主键控**的发射游标、发射后自清);**`MGPSubRegion` 跨步描述符改造**(§4.5.6:`Managers.cpp:4274-4326` 从描述符取步长,替代 `uploadData == mipData` 指针比较与整 level 步长算术);**XFB scatter 搬到 client**(§7.2.1);**删** fragColor 重推导 workaround 与 `g_broadcastMemo*`;用推送状态退役 9 条陈旧性判定里的第 4-6、8-9 条;Espryt 的 raw-depth-fetch `SamplerObject` 原生化;回读 / pack state。
|
||||
|
||||
**验收**:~25 个纹理场景(`TextureView`、`LayeredTextureReadback`、`ImageSizeAfterRespec`、`FormatlessImageBake`、`NonCoreImageFormat`、`ImageFormatQualifier`、`ImageTargetKind`、`ImageLoadStoreSso`、`UnboundImageDescriptor`、`SwizzleAccessRoutine`、`IntegerBorderColor`、`PixelStoreSweep`、`SampledSetStaleness`、`ThreeChannelAttachment`、`BufferTexture`、`CopyImage*`×3、`ClearTexImageUndefinedLevelZero`、`DepthStencilReadback`×3、`PackedWordReadback`);21 个 program 场景 + 整个 `MG_Test/ShaderTranspiler` 目录;两台设备上完整 `KHR-GL46.texture_*` / `internalformat.texture2d.*` / `shader_image_*` / `packed_pixels` 块,conformance 在 pull 基线 0.5pp 内;**每一个 Iris trace**;
|
||||
**v2 新增三个门**:
|
||||
- **`TextureUploadShapeScenario`**:逐纹理逐帧的上传形状(box vs N region、作业数)录金标比对——**+6ms 悬崖由形状相等把关,SSIM 对它不敏感**;**Mali 上帧时增量必须发布**;
|
||||
- **view/owner 发射游标别名场景**:通过 view 上传、经属主采样(以及反向),跨 draw 边界各一次(§7.3 修正 1);
|
||||
- **verify 保留模式**:`MOBILEGL_PIPE_VERIFY=1` 下 `resource_subdata` 的 `(unionBox, regionCount, regions[])` 与快照重算逐项相等(§7.3 修正 2);
|
||||
- `XfbAfterClipDistance` / `XfbCaptureBufferReuse` / `XfbRepeatedCapture` / `TessellationXfbCapture` 与 **`KHR-GL46.transform_feedback.capture_special_interleaved_test`**(scatter 的 `gl_SkipComponents` 空洞保留,§7.2.1)。
|
||||
|
||||
### P7 — DirectVulkan(Magma)全量迁移(80-104 天,可与 P5/P6/P8 并行)
|
||||
|
||||
> 子系统 1(pipeline+动态状态)与子系统 4(VertexInput/VaoDrawMemo)已在 P2 交付,所以是 §6.5 的 85-111 减去 5-7。
|
||||
|
||||
**交付物**:§6.5 的其余 10 个子系统,重点四项:`SetupDrawSnapshot` 的 ~14 个探测字段(含两个**有损**的版本求和)塌成 dirty mask 比较;**`UniformManager` 的 8 类占位 `TextureObject` 换成原生 `VkImage`+view+descriptor**(~120 行删除,34 个 `MOBILEGL_ASSERT(pGLContext)` 里的 9 个消失);**具名 UBO 的 host payload**(D-B8:`ResolveUniformBufferPayload` `UniformManager.cpp:2022/2052` 改从 `set_shader_buffers` 的 `MGHostSpan` 取,`kCapNeedsHostUboBytes` 门控);**blit / depth-mipmap 内部 shader 烘焙成签进树的 SPIR-V + uniform location + UBO 布局,由一个 `MG_Test` 重跑树内 glslang 逐字节比对的用例守新鲜度**;`VertexInputStateFactory` 的后端堆裸指针写回**直接删除**;`VkRenderPassManager` / `VkTextureManager` 的**节点式容器纪律原样保留**(D18,postmortem 注释逐字带进 review checklist)。
|
||||
|
||||
**验收**:367 集成 + 40 trace 在 DirectVulkan 的 monolith-push 与 split 下全绿;verify 零分歧;**`nm -D libMobileGLServer.so | grep glslang` 为空**——这是整个论点的强制执行点(**依赖 P0.5**);`UnboundImageDescriptor`、`SampleMaskScope`、`ImageLoadStoreSso`、`AtomicCounter`、`SsboArrayDynamicIndex`、`NonCoreImageFormat`、`Orientation`、`DepthStencilReadback*` 场景;**Iris trace 上 `stage-ubo-named` 逐帧字节量发布**(D-B8 的定尺依据);两台设备 CTS 在 0.5pp 内。
|
||||
**⚠ 再基线检查点 2:P7 中点(第 40-52 个工作日)若已完成子系统 < 40%,立即重定基线**——P3a 的检查点发现不了 Magma 特有的超期,而 P7 在单跑道下位于关键路径。
|
||||
|
||||
### P8 — emulation 下放 + 索引宿主镜像 + 协议广度(12-16 天)
|
||||
|
||||
**交付物**:`MG_Impl/Pipe/HostResolve.cpp`——client 数组范围计算、**最大索引扫描**(`TryComputeMaxIndexFromHostBytes` 移到 client,唯一的无界应用指针读)、**`*IndirectCount` 计数解析**,每一条前面都有 §5.8.1 **逐站点表**规定的 reconcile(**不是笼统的 publish/wait/drain**:`*IndirectCount` 只做 `SyncPersistentMappedRange()`,因为 monolith 也只做这一个,`DirectGLES.cpp:4666-4667`);`MGHostSpan` 的 split 填法;**`Server/IndexHostMirror`**(D-B7:`bindMask & ELEMENT_ARRAY` 的资源由 subdata 流增量维护,`MOBILEGL_PIPE_INDEX_MIRROR_MB` 预算,超预算退化为逐 draw 传送并计数);**CopyImage shadow 镜像搬到 client**;`draw_vbo(info, indirect, ranges[], numDraws)` 收编 multi-draw 族(**分档仍在 server**);viewport-array 回放验证在一次 pipe 调用驱动下各遍之间观察到的状态与今天一致(`EndViewportRoutingPasses` 会调 `InvalidateSyncedRenderState`,`DirectGLES.cpp:3841`);`generate_mipmap` 返回 level 计划(**形状,不带字节**)与 CPU 回退的纹素;**G3 的"单条记录大于段容量"分块/降级路径**。
|
||||
|
||||
**验收**:`ctest -L integration-gpu -R '^DirectGLES\.Split\.'` 与 `'^DirectGLES\.'` **逐名相同**,DirectVulkan 同;40 个 trace 在 split 下双后端 SSIM ≥ 0.99,含两个 `coherent_as_flush: true` 的 Create fixture(**两种模式都开着该开关跑**);**新增 `ClientArrayAfterComputeWriteScenario` 绿,且去掉那次等待必须能看到几何缺失**;**`create-indirect` fixture 上 `roundtrips-per-frame` 读零**(§5.8.1 的绊线:证明没有给 `*IndirectCount` 平白加一次 publish-and-wait);**`index-mirror-bytes` 与 `index-bytes-shipped` 逐用例发布**;`MultiDraw`、`PrimitiveRestart`、`ViewportArray`、`DrawParameters`、`CopyImage*`×3、`GuiBatch` 场景。
|
||||
**★ 第 145 天 — 全功能 split。**
|
||||
|
||||
### P9 — 反向通道(10 天)
|
||||
|
||||
**交付物**:`SEG_REPLY` 4KiB slot 池;阻塞 `read_pixels`;PBO 回读 fire-and-forget;`on_gpu_written{res, ranges}` 收窄(配 `writableMask`);`on_buffer_writeback` **按操作级批处理**(今天两处逐行循环:`Utils.cpp:2342`、`DirectGLES.cpp:7633`)配 epoch bump 的排序规则;`on_xfb_scatter_ready` + client 侧 scatter(§7.2.1);`on_texture_writeback`(一个生产者);`on_mip_levels_generated`(**只带形状**);**`on_texture_pull_request` 四条缓解全上 + `resource_subdata_complete` 终止符**(§7.5);`on_gl_error` 有序 + **收窄后的** `kNeedsAck`(§7.4);`on_caps_invalidated`;`on_surface_changed`;**`on_log` 按严重级分级**(≤WARN 有损 / ≥ERROR 无损 + 每秒速率限制器 + "N errors suppressed");`SEG_EVENT` 溢出策略 + 等待循环内排空。
|
||||
|
||||
**验收**:`DepthStencilReadback`×3、`PackedWordReadback`、`LayeredTextureReadback`、`ClearThenReadPixels`、`XfbAfterClipDistance`、`XfbCaptureBufferReuse`、`XfbRepeatedCapture`、`TessellationXfbCapture`、`KHR-GL46.transform_feedback.capture_special_interleaved_test` 在 split 下绿;**`TextureRemintPullScenario` 绿**,**且它必须包含一个"答不出来"的用例**(一张只被渲染过、随后被 image-bind 的纹理)**并在终止符落地前表现为 apply 线程挂死/超时**;**拉取计数逐 trace 用例发布**;故障注入:client 被 credit 阻塞时灌满 `SEG_EVENT`,两侧都必须恢复;**日志洪泛下注入一次 backend link 失败,那行 ERROR 必须出现**。
|
||||
|
||||
### P10 — sync / query / present 节奏(6 天)
|
||||
|
||||
**交付物**:client 铸造 sync 与 query handle;轮询入口成为门铃点 + `MOBILEGL_IPC_POLL_ESCALATE` 饥饿升级;**fence 完成度来自真的逐 fence 退休**(不是 present 水位——那正是 MC 1.21.5 native-heap OOM 的成因);DirectGLES 的非 present fence tick;`Present` 严格 1:1;`MOBILEGL_IPC_PRESENT_CREDIT` 默认 1 + 叠加公式;逐帧 roundtrip 计数器与**输入延迟直方图**;`PLAN.md` §8 末尾的三个独立 `dev` monolith 修复。
|
||||
|
||||
**验收**:`XfbPrimitiveQuery`、`PrimitivesGeneratedNoXfb`、`AsyncCompile` 在 split 下绿;**40 个用例上 draw/state/upload 路径的 roundtrip 计数器读零**,条件渲染与阻塞 query 次数逐用例发布;零 timeout 轮询循环测试在有界时间退出;`bench.sh` 在 `35d0befa` 上配对 A/B:两侧都关采纳时 split 帧时在 monolith 10% 内,输入延迟直方图 p50/p99 记录在案。
|
||||
|
||||
### P11 — persistent map 与 ≥16MiB 采纳(8 天;spike B 全否则缩为 2 天)
|
||||
|
||||
**交付物**:由 P0 spike B 驱动的 POST 探针档位选择(T2 / T1 / T0);`SEG_ADOPT` 生命周期绑 `completedFrameSerial`;`MOBILEGL_IPC_ADOPT_TIER` 覆盖开关做负面对照。
|
||||
|
||||
**验收**:`LargeArenaAdoptionScenario` 在所选档位下绿;`improved-transparency-minecraft-26.3` 与两个 Create fixture SSIM ≥ 0.99;**`StorageBufferRegrowScenario` 发布 `map-persistent-roundtrips`**(T1 档下每次存储定义一次,不是每 store 一次);`35d0befa` 上配对 reboot-clean 的 p99 帧时与峰值 RSS 对 monolith 采纳基线(p99 163→21ms、40→115fps、~400MB)——**split 在所选档位下 p99 不得回归超过 10%;若 T2 成为永久答案,其实测代价必须写进文档**。
|
||||
|
||||
### P12 — Android 生产窗口路径(10 天)
|
||||
|
||||
**交付物**:`android:process=":mgl"` 的 Service 收 Java `Surface`(Binder)后 `ANativeWindow_fromSurface`(minSdk 26 无公开 `ANativeWindow` 扁平化;树内先例是 `android:process=":bench"` 的 `BenchService`);server 生命周期绑 Activity;FCL 用户 env 与 plugin APK V2 开关表接线(**零新增管线**)。
|
||||
|
||||
**验收**:Minecraft 通过 FCL 在 spawn 模式下在 `35d0befa` 上双后端入世界;配对 reboot-clean bench + 输入延迟直方图;杀 server 产生干净的 device-lost latch;SIGKILL 故障注入。
|
||||
|
||||
### P13 — 退役 pull 路径(8-12 天)
|
||||
|
||||
**交付物**:删 `SnapshotFromGLContext()` 的**非 verify** 编译分支、`MGB_CTX` 宏、`MOBILEGL_PIPE_PUSH`、`MOBILEGL_PIPE_LEGACY_MEMOS`;**保留 `MOBILEGL_PIPE_VERIFY` 及其 `SnapshotFromGLContext()` 与 `MG_State` include**(D-B5);**交付 MGPipe recorder 金标模式**(`MG_Test` mock backend → 录制器,§10.4-9),作为不依赖 `MG_State` 的长期语义门与开放问题 11 的答案;删 `set_residual_value_state` 与 `ResidualValueBlock`;`MG_Backend` 的 `MG_State` include 收缩到 `MGPipeValueTypes.h`;**在计数器活着的情况下重调所有幸存缓存的容量**(Magma 的 2048 槽 `VaoDrawMemo`、4 个 `SetupDrawSnapshot`、8 个 pipeline memo、8 个 `syncedTextureMemo`)并把它们变成带 env 覆盖的调优参数;最终符号/尺寸/CPU 报告。
|
||||
|
||||
**验收**:**`static_assert(sizeof(ResidualValueBlock) == 0)` 编译通过**;**三道纯度门在非 verify 构建上转绿**(include 图门 A、符号门 B、未声明门 C,§10.3-①);verify 构建仍能跑且零分歧;MGPipe recorder 金标在 40 个 trace 上建立并可回归;全套门(367 × 2 backend × {monolith, split}、428 单元、40 trace SSIM ≥ 0.99、两台设备 CTS 在 `81b17c0b` 基线 0.5pp 内);**monolith 逐线程 CPU 在两台设备的 p50 与 p99 上不差于 P0 基线**——本设计的性能主张在这里成立或倒下。
|
||||
|
||||
### 11.5 总估时、里程碑与 CTS 周转
|
||||
|
||||
**逐阶段求和(低端 / 高端,单跑道累计)**
|
||||
|
||||
| 阶段 | 天 | 累计(低端) | 构成(§6.4/§6.5 的行) |
|
||||
|---|---|---|---|
|
||||
| P0 | 9-11 | 9 | Espryt 0a(1-2) + Magma 0a(~1) + 共享基建 |
|
||||
| P0.5 | 6-9 | 15 | 头文件抽取(新增) |
|
||||
| P1 | 10-13 | 25 | `PipeInputs` + 逐 verb 填充 + verify(共享基建) |
|
||||
| P2 | 18-26 | 43 | Espryt 1(3-5) + Magma 1(3-4) + Espryt 0b(5-7) + Magma 4(2-3) + tracker/CSO/G7(4-6) + 聚合世代(1) |
|
||||
| P3a | 18-23 | 61 | Espryt 2(10-13) + 3(7-9) + LEGACY 维护(1) |
|
||||
| P4a | 26-34 | 87 | Espryt 4(7-9) + 5 前半(11-15) + 6 身份半(7-9) + LEGACY(1) |
|
||||
| P5 | 12 | 99 | IPC 跑道 |
|
||||
| P6 | 5 | 104 | IPC 跑道 |
|
||||
| P3b/P4b | 29-38 | 133 | Espryt 5 后半(12-15) + 6 后半(7-9) + 7(5-7) + 9(5-7) |
|
||||
| P8 | 12-16 | 145 | Espryt 8(8-11) + Magma 份额(4-5) |
|
||||
| P9 | 10 | 155 | IPC 跑道 |
|
||||
| P10 | 6 | 161 | IPC 跑道 |
|
||||
| P11 | 8 | 169 | IPC 跑道(spike B 全否则 2) |
|
||||
| P12 | 10 | 179 | IPC 跑道 |
|
||||
| P13 | 8-12 | 187 | Espryt 10(4-6) + Magma 11(4-6) |
|
||||
| **P7(Magma)** | **80-104** | **267** | §6.5 的 85-111 减去已在 P2 交付的子系统 1 与 4 |
|
||||
|
||||
**报作 267-337 人天**(不含 CTS 周转)。两个工程师、P7 与 P5/P6/P8 并行 → **约 7-9 个月**,真正的约束是两台设备的争用而不是人头。
|
||||
|
||||
**与独立成本分析的一致性**:一次独立的改造成本调研给出 backend 工作**单独** 202-266 天(Espryt 95-125 + Magma 85-111 + 共享 22-30)。本节的 267-337 = 那个区间 + IPC 跑道 51 天 + P0.5 的 6-9 天,**方向一致**。v1 报的 200-260(含 IPC)落在其乐观端之外,已作废。
|
||||
|
||||
**里程碑(低端估计)**:第 **25** 天 verify harness 全绿(零产品风险,**不是** GO/NO-GO);第 **43** 天 **GO/NO-GO**(含一片真 Track H);第 **99** 天首个 `inproc` IPC 帧(**缩减路径**);第 **104** 天首个跨进程帧(**缩减路径**);第 **145** 天全功能 split;第 **187 / 267** 天三道纯度门转绿。
|
||||
|
||||
**再基线检查点**:P3a > 27 天;P4a > 39 天;P7 中点(第 40-52 个工作日)完成子系统 < 40%。任一触发,先跑 `inproc` 的证伪数字再决定是否继续。
|
||||
|
||||
**CTS 周转必须单独计价,不折进阶段估时。** `gl44to46` caselist 约 56,271 例。分层门控:逐阶段只跑该阶段改动可能影响的具名 CTS 块(P4a 的 `packed_pixels`、P3b/P4b 的 `texture_*`/`shader_image_*`、P9 的 `transform_feedback*`),**完整 caselist 只在五个架构边界跑**(P0.5 头文件抽取、P3a handle、P4a framebuffer/纹理身份、P3b/P4b 纹理、P13 纯度)**以及每次合并 `dev` 之前**,且放在 CI 而不是关键路径上。设备锁协议照旧。若实测周转仍主导排期,**诚实做法是加宽估时而不是削弱门**。
|
||||
|
||||
---
|
||||
|
||||
## 12. 风险与对策
|
||||
|
||||
| # | 风险 | 对策 |
|
||||
|---|---|---|
|
||||
| **B-R1** | **效率是方案 A 的 3.5-4.4 倍、首帧晚 6-7 倍**(267-337 天 vs 77;第 104 天 vs 第 15 天)。排期驱动的评审可以只凭这一条否掉本方案 | 把价值排在承诺之前:P0-P2(43 天,其中 28-39 天是方案 B 独有)交付 handle 化 twin 与内容寻址的渲染状态 CSO——**零 IPC 风险的可测量 monolith 工作**——并产出字节/调用计数器与第一个逐线程 CPU 数字与 **Track H 单位成本**。**第 43 天显式 GO/NO-GO。** P13 是一个完全自洽、不含任何 IPC 的 monolith 交付物;P5 的 `inproc` 只要 12 天 |
|
||||
| **B-R2** | **中心性能主张未经测量,且它的基线被 v1 高估了一个数量级。** 可达性遍历是**搬走**而不是消失;真实稳态拉取只有每 backend 每 draw 10-25 次 accessor(§2.3.1),不是 124/169 | 字节**与调用**计数器是 **P0 交付物**。每阶段验收用**逐线程 CPU 时间**,两台设备、reboot-clean、配对,**并设绝对 ns 上限**(相对噪声阈值在真实基线下会平凡通过)。P2 除渲染状态外**必须含一片 Track H**,否则测的不是要决定的事。加 Blaze3D blend-toggle 微基准与 CSO 内容寻址的负面对照。**先清工作树 per-draw `fprintf`** |
|
||||
| **B-R3** | **monolith 字节一致门按构造死亡**,逐名集成基线也随之移动 | 五部分替代门,全部在 P0/P0.5/P1 落地(§10.3),其中 ② 逐 draw 逐字段影子比对在语义上严格强于任何符号 diff。两条字节等式仍作断言保留。**逐名功能基线明确定义为"P1 出口的重构后 monolith"**,而 P1 出口自己先用 verify 证明等价于 `81b17c0b`;`81b17c0b` 只作性能锚点 |
|
||||
| **B-R4** | **server 发起的纹理拉取是新停顿类**,触发路径之一(整格式再生 `Managers.cpp:3950-4195`)在普通 `glTexImage` 格式变更上就会触发、无法被 hint 预防;**而且存在 client 根本答不出来的 level**(纯渲染产生 / `CanMirrorCopyImageShadow` 拒绝的 copy 目标 / GPU 生成的 mip),会让 apply 线程永久 park | 四条缓解同时上:`imageBindableHint` 预防主因;**异步** park-and-re-emit 让停顿落在 `mgl-srv-apply`;**`resource_subdata_complete` 终止符可携带零 region**,server 带着"已分配但为空"的存储继续(正是 monolith 的行为,`DirectGLES.cpp:6270-6271`);保留 LRU **默认关闭**(`MipmapStorage` 保有完整 CPU 影子,所以拉取总能被服务,缓存买的是延迟不是正确性)。`TextureRemintPullScenario` **必须包含无解用例并在终止符前是红的**,**拉取计数逐 trace 用例发布** |
|
||||
| **B-R5** | **P3b/P4b(29-38 天)与 P7 中的 `VkTextureManager` 是最大最险的段**,压在实测 +6ms/frame 悬崖(rect 列表 vs union box)与 7 条 fallback-repack 路径上,**而后者的可行性判定 `uploadData == mipData`(`Managers.cpp:4278-4283`)在 split 下不成立**——它要求上传源就是整 level shadow 并按整 level 步长跨步 | `resource_subdata` 同时带 box 与 region 列表、**server 选形状**;**`MGPSubRegion` 显式携带 `srcRowStride`/`srcSliceStride` 与 `sourceIsVerbatimLevelShadow`**,`Managers.cpp:4274-4326` 改为从描述符取步长(形状照抄已存在的 `UnpackStagingBlock`,`:4340-4390`,ring 路径本来就紧密重打包)。**这项工作计入子系统 5 的天数**(+3-4 天),不再列为"原地不动"。**`TextureUploadShapeScenario` 录金标比对上传形状与作业数**,因为 SSIM 对这个悬崖完全不敏感。P3b/P4b 拆成两个可独立落地的半 |
|
||||
| **B-R6** | **tracker 完整性**:推送之后 server 不能再重读活状态校验快路径。任何 tracker 忘记发的 mutator 会静默漂移。历史上最危险的正是这个形状(`DirectGLES.cpp:1441-1465`) | **四层**:**(1) 构建期** G5 的逐 verb 世代表 + G7 的 render-state setter 一致性测试;**(2) 运行期** poison 在**需要该字段的那个 verb** 上 `Fatal`(不是某个后续 draw);**(3) 语义** `MOBILEGL_PIPE_VERIFY` 逐 draw 逐字段比对(**含纹理 subdata 的保留模式**,否则最危险的子系统是瞎区);**(4) 枚举** `gen_pipe_dirty_surface.py` 枚举 `MG_Impl` 里每个 mutator → 必须 bump 的聚合世代,CI 上未映射即失败。**迁移粒度是一个 accessor。** 477 行 inventory 保留为覆盖检查表 |
|
||||
| **B-R7** | **`AcquirePersistentMap` 跨进程无解**会葬送 MC 26.3 的结果,而没有任何目标平台的支持被验证过 | **显式隔离**:改造期完全不碰,只有 IPC 那一步会打破它。决策交给三档 POST 探针与 **P0 第一周的 spike B**。T2 前端已在三处容忍并让 client 侧块推送成为强制(P5 交付)。若两台设备都否,P11 从 8 天缩为 2 天。**注意 T1 是每次存储定义一次 round trip,不是每 store 一次**(`StorageBufferRegrowScenario` 发布计数)。**不让一个平台未知数挡住 267 天的接口工作** |
|
||||
| **B-R8** | **D18 的节点式容器纪律在重构中丢失**:`m_renderbufferResources` / `m_textureResources` 是**故意**用 `std::unordered_map`,一次扩表搬迁曾让 `BlitFramebuffer` 静默停在 "layout undefined"(`VkRenderPassManager.h:375-397`) | D18 是全表**唯一**标为 UNCHANGED 的身份行;**postmortem 注释必须逐字带进 P7 的 review checklist**。slot 数组在插入下稳定,实际改善了处境——但仍然点名 |
|
||||
| **B-R9** | **逐 backend 的行为不对称被统一接口抹平**(Magma 故意不注册 `ResidentSubData`,`VkBufferManager.cpp:104-111`;`PrefersCpuXfbPrimitiveAccounting`;DirectVulkan 留空的 8 个槽) | 可选性是**接口的一等属性**:null 项在本代码库里**已经**表示"未实现,前端回退"(`BackendObject.h:212-215, 265-269`),`MGPCaps` 携带显式 `callMask`。**但 v2 收回了用 cap 位表达 emulation 归属的做法**(D-B7):`ResolveTierForBatch` 逐 batch 用 `programReadsDrawID`(server 独有事实)选档,且两个 backend 都做 restart 重写,所以那五个 cap 位没有门可控。归属规则改成一句话 + 一个 `kCapNeedsHostIndexBytes` |
|
||||
| **B-R10** | **接口在未测量的形状上过早冻结**;若干 server 侧缓存的容量是按拉取模式调的 | payload 结构从第一天走 structSize-first 版本纪律,可增长。字节**与调用**计数器在 P0 落地。**`stage-ubo-named` 出数之前不冻结 `set_shader_buffers` 的 host payload 形状**(D-B8)。**P13 在计数器活着的情况下重调所有幸存缓存的容量**,并把它们当作带 env 覆盖的调优参数。screen/context 划分在 P0 定进头文件但按 context 计数 == 1 实现 |
|
||||
| **B-R11** | **58 行非箭头 `pGLContext` 用法的迁移缺口**;`DirectGLES.cpp:146` 的 `.get()` 与 `:142` 的 `decltype` 别名 `sed` 完全抓不到 | §2.4 已逐形态分类。P1 的交付物**包含这份 58 行清单的逐条转换**。**纯度门 grep 的是 `pGLContext` 而不是 `pGLContext->`** |
|
||||
| **B-R12** | **残余值块是迁移期边界上的一个洞**:poison 抓不到"两侧布局不同",而 monolith 的 verify harness **看不见它**(两侧是同一个 TU) | 逐成员 `offsetof` 断言 **加上** split 模式下逐字段序列化(走 G3 编解码器)。块的字节量单独计一类。`static_assert(sizeof == 0)` 让退役是编译错误 |
|
||||
| **B-R13** | **`SEG_EVENT` 的 ERROR 无损化重新引入死锁** | 每秒 ERROR 速率限制器 + "N errors suppressed";`MGLOG_E_ONCE` 的 latch 变 per-server;P9 的故障注入门要求"日志洪泛下注入一次 link 失败,那行 ERROR 必须出现"**且**"两侧都恢复" |
|
||||
| **B-R14** | **排期估计**:v1 的阶段天数与它自己的子系统表矛盾,且低于同口径的独立分析 | §11.5 的每个天数都是它所含 §6.4/§6.5 行的求和,**算术公布**。总数改报 **267-337**(不含 CTS)。三个再基线检查点按求和后的上界 +50% 设定。CTS 周转**单独计价** |
|
||||
| **B-R15** | **在 GL setter 时刻推送**会让整件事变慢,且这是最容易被后续实现者做错的一处 | 写成规范条款并给出证据(`DirectGLES.cpp:2029-2032` 的 Blaze3D per-batch blend toggle);P2 的设备门直接暴露它。**v2 补一条同等重要的**:`glTexSubImage` **不是** GL 调用时刻推送的对象(它根本不调 backend 表,`GL_Texture.cpp` 只有 3 处 `MarkStorageDirtyRegion`),逐调用发 `resource_subdata` 会精确复现 Mali 的 ~100 作业形状(+6ms/frame)。规则的正确措辞在 §5.1.1;`resource_subdata` 逐帧发射次数进计数器并在 MC 动画图集 fixture 上设上限 |
|
||||
| **B-R16(v2 新增)** | **stage C 之后 `MOBILEGL_PIPE_PUSH` 不再是对"旧 backend"的 A/B**:位清零时 `SnapshotFromGLContext` 仍要合成 handle,backend 仍跑重键后的 memo 代码,两个分支跑同一份新代码;一个重键 bug(D1/D2/D3/D11/D13 那一类)在两臂都在,位图二分不出来 | 在 §6.7 写明这条口径收窄。为 P3a 与 P4a 加**编译期** `MOBILEGL_PIPE_LEGACY_MEMOS`,让前两波 handle 化保留一个真正的旧-vs-新臂;随 pull 路径在 P13 退役。维护成本各阶段 +1 天,已计入 |
|
||||
| **B-R17(v2 新增)** | **`MOBILEGL_PIPE_VERIFY` 是唯一的语义门,而 v1 的 P13 删掉了它的参照物**(`SnapshotFromGLContext`),删完之后设计没有语义绊线 | `SnapshotFromGLContext()` 与它的 `MG_State` include 整体包在 `#if MOBILEGL_PIPE_VERIFY` 里保留过 P13;三道纯度门**只跑非 verify 构建**;P13 另交付 MGPipe recorder 金标模式作为不依赖 `MG_State` 的长期语义门(同时是开放问题 11 的答案) |
|
||||
| **B-R18(v2 新增)** | **monolith 的净代码量是增加的**(§2.7:约 +6,650 手写 + 4,000 生成,对 ~372 行真删除),所以"~550 行删除"不能当主论据 | 把 §10.3-④ 的**逐线程 CPU 数字**作为 monolith 论据的主体,删除清单降级为佐证。§2.7 公布净 LOC 估计,让 B-R2 有一个可证伪的预测。**若 P2 与 P13 的 CPU 数字持平而非改善,monolith 论据只剩架构性收益(ABA 不可表达、排序 hazard 消失、`inproc` 杠杆),必须据此重新评估是否值得** |
|
||||
|
||||
---
|
||||
|
||||
## 13. 开放问题
|
||||
|
||||
1. **client 侧 dirty 走查的真实每 draw CPU 代价是多少?** 中心性能主张是"遍历搬走而不是翻倍",而真实基线只有每 backend 每 draw 10-25 次 accessor(§2.3.1)。P2 的头号数字,按逐线程 CPU + **绝对 ns**、两台设备报。
|
||||
2. **真实语料上纹理重铸拉取的实际发生率?** `imageBindableHint` 能预防主因,但整格式再生(`Managers.cpp:3950-4195`)在普通 `glTexImage` 格式变更上就触发。若 MC 或 Iris fixture 上实测率非平凡,保留 LRU 从"默认 0"升为强制并需要真预算。
|
||||
3. **`AcquirePersistentMap` 跨进程能不能成?** P0 spike B 第一周回答。未验证:`VK_KHR_external_memory_fd` 的 host-visible-coherent 支持在四条 lane 上的可用性;GLES 侧能否用 `GL_EXT_memory_object_fd` + `glBufferStorageMemEXT` 走同一条路。
|
||||
4. **渲染状态的 wire 粒度**:pipeline 子集的 chunk 划分定下来之后,CSO LRU 的容量(暂定 64)与 `set_dynamic_state` 的 chunk 粒度仍需 P0 计数器定。
|
||||
5. **`MG_Util` 的切割缝在哪里?** server 需要 SPIRV-Cross pass 流水线、ESSL 转译缓存、像素/纹理格式处理器、POST 探针、loader;client 需要 glslang phase A/B 与反射层。**P0.5 解决了 `ProgramObject.h` 这一处**,但 `MG_Util` 内部是否存在一条干净的 Transpile-vs-Reflect 缝**仍未审计**。
|
||||
6. **一份反射归档能服务三个消费者吗?** Espryt 读前端表,Magma 跑 SPIRV-Reflect,而 `DirectVulkan.cpp:161` 为 `glGetProgramResource*` 又反射了第二遍。
|
||||
7. **viewport-array 回放能塞进一次 `draw_vbo` 吗?** 今天它从 14 个 draw 入口经 `ForEachViewportRoutingPass` 重发应用的 draw N 次,而 `EndViewportRoutingPasses` 会调 `InvalidateSyncedRenderState`(`DirectGLES.cpp:3841`)。未验证各遍之间观察到的状态是否与今天一致。
|
||||
8. **`ResidentSubData` 的不对称该怎么收口?** null 项保住今天的行为,但拆分工作可能正是给 Magma 补一个真实现的时机——那是**行为变更而不是重构**,应作为独立 `dev` PR。
|
||||
9. **`SEG_STAGE` 的上限定多少?** 六类新字节(§8.2)需要 P8 之后用 MC in-world 与 Create 两类 fixture 的 `stage-*` 计数器给 p99 占用。**并且 G3 的"单条记录大于段容量"分块路径需要设计与测试**。
|
||||
10. **`FramebufferSrgb` / `DepthClamp` 无存储是潜伏 bug 还是有意为之?** 六个 backend 消费者今天读到恒定 false(`RenderState.cpp:380, 428-429`)。**必须在渲染状态 chunk 表冻结之前回答**。
|
||||
11. **P13 之后 `MOBILEGL_IPC_VALIDATE_SERVER` 还有对应物吗?** **v2 部分回答**:保留 verify 构建(D-B5)+ P13 的 MGPipe recorder 金标。但 split-only 的**渲染** bug(而非状态推送 bug)仍然没有 server 侧第二意见——recorder 只覆盖推送内容,不覆盖 backend 对它的解释。
|
||||
12. **~~client 侧 restart 重写与 indirect-count 解析会不会改变可观察行为?~~** **v2 已关闭**:D-B7 把 restart 重写与 multi-draw 分档留在 server,monolith 行为零变化,诊断仍落在原线程。**只有 `*IndirectCount` 的计数解析搬到 client**,它的 decline 路径(`DirectGLES.cpp:4682-4688`)随之落到应用线程——这是改善而非退化,但需要在 P8 的验收里核对日志文本与顺序。
|
||||
13. **Magma 的两个内部 shader 烘焙后,uniform location 与 UBO 布局能否在没有活 `ProgramObject` 的情况下表达?**(`VulkanRenderer.cpp:4238-4241, 4319-4324, 8450-8452`)未做原型。
|
||||
14. **推送模型会改变哪些按拉取模式调过的缓存命中率?** Magma 的 2048 槽 `VaoDrawMemo`、4 个 `SetupDrawSnapshot`、8 个 pipeline memo、8 个 `syncedTextureMemo`;Espryt 的 4096/256/64 槽 `TwinLookupMemo`(后者会消失)。幸存者的容量在 P13 重调。
|
||||
15. **(v2 新增)monolith 的 `*IndirectCount` 不调 `SyncGpuWrites()` 是不是一个潜在缺口?** `DirectGLES.cpp:4666-4667` 只做 `SyncPersistentMappedRange()`,而 compute 写的 indirect buffer 理论上需要前者。**这是一个独立的 `dev` 问题,拆分不得借机"顺手修"**——那会改变基线并让逐名对比失去意义。
|
||||
16. **(v2 新增)索引宿主镜像的实际内存占用?** D-B7 的预算是 64 MiB 默认上限,但 MC/Sodium/Iris 语料里 element-array buffer 的总量未测。若显著超预算,退化路径(逐 draw 通过 `MGHostSpan` 传送)的频率与代价必须实测,因为它会把 §0.4 的内存优势和 §9.1 的零 round trip 主张同时削弱。
|
||||
|
||||
---
|
||||
|
||||
## 14. 对方案 A 文档与 `Feat/CS-Delta-IPC` 的复用清单
|
||||
|
||||
### 14.1 对 `PLAN.md` 的复用
|
||||
|
||||
| 判定 | `PLAN.md` 章节 |
|
||||
|---|---|
|
||||
| **原样取(不复述)** | §6.1(段布局、shm 矩阵、`SCM_RIGHTS` 第一优先、`SEG_SHADOW` 退休规则);§6.2/§6.2a;§6.3;§6.4;§6.5;§6.6 前三条;§6.7 第 2、5 行;§6.8;§7.1-§7.3;§8 末尾;§9-§9.3;§10;§11.1-§11.6;§12 第 1-3 层与 §12.4;§13;§15 P0 的卫生与两个 spike |
|
||||
| **取并改** | §7.4(**`on_log` 按严重级分级**);§12.2(隔离从四个进程全局降到**两个**);§5.10(第 2、3 条逐字取,第 1 条缩成一个 `hasLiveHostWrites` 位);§6.10(应用指针按 §5.8 归属;**陈旧索引纪律改为逐站点表**,§5.8.1);§5.9a(READ 面**编目**生成器改为**三道禁止门**);§6.4 的拷贝账(删掉第 (3) 行,P1-4=3 / P4.5=2);**§5.9b 的生成器改造而非删除**(`gen_impl_mutation_surface.py` → `gen_pipe_dirty_surface.py`,replay 义务消失、标记义务出现) |
|
||||
| **弃** | §5.0、§5.1、§5.2、§5.4 的 replica 对象表规则与 `Fatal{IdentityDivergence}`、§5.6a、§5.7 的 Phase 1-4 分支与 `SetReplicaResolvedDrawProgram` 钩子、§5.9b 的 replay 半边(`MutationCoverage.def`、`ImplMutationSurface.inc`、`MG_Remote::Shared::`)、§6.9 的 relink 档与 `MOBILEGL_IPC_PROGRAM`、§12 第 4 层的字节一致断言、`Server/ReplicaContext.*`、阶段 **P5**、风险 **R1** 与 **R6**、开放问题 **§17-5** |
|
||||
| **新增** | `MG_Pipe/` 全套与七个生成器;**P0.5 的两个头文件抽取与 include 图门**;`PipeInputs` + **逐 verb 世代** poison;`MOBILEGL_PIPE_VERIFY` 影子比对(**含保留模式,且活过 P13**);残余值块与其编译错误退役绊线;`MG_State` 的 5 个聚合世代 + dirty-surface 生成器;`set_dynamic_state`、`set_texture_params`;`Server/IndexHostMirror`(D-B7);`on_texture_pull_request` / `resource_subdata_complete` / `on_texture_writeback` / `on_mip_levels_generated` / `on_xfb_scatter_ready`;纹理拉取的四条缓解 + 终止符 + 计数器;`HandleRecycleScenario` / `TextureRemintPullScenario` / `TextureUploadShapeScenario` / view-owner 游标别名场景 / `ClientArrayAfterComputeWriteScenario`;`RenderbufferObject::GetLifetimeId()`;D21 的潜伏 bug 修复;`MOBILEGL_PIPE_LEGACY_MEMOS`;`check_doc_citations.py` |
|
||||
|
||||
### 14.2 对 `Feat/CS-Delta-IPC`(worktree `../MobileGL-CS`)的复用
|
||||
|
||||
`PLAN.md` §14 的判定**整体继承**。方案 B 的四处差异:
|
||||
|
||||
| 条目 | `PLAN.md` 判定 | 方案 B 的差异 |
|
||||
|---|---|---|
|
||||
| `docs/CS_Refactor/HandleSessionGeneration.md`(`546895aa`) | REUSE,其中"handle 清单补 `RenderbufferObject::GetLifetimeId()` **与 `GetVersion()`**" | **只补 `GetLifetimeId()`**。`GetVersion()` 只是 replica 的 delta 触发器;推送模型里 `glRenderbufferStorage*` **本身**就是一次 pipe 调用 |
|
||||
| `docs/CS_Refactor/backend_read_inventory.md` + `extract_backend_read_inventory.py` | CHANGE 成 `gen_backend_state_surface.py`,未知 accessor 一律 UNMAPPED 并编译失败 | **同意其修正**(删掉制造"0 UNMAPPED"的前缀兜底规则 `:234-241`),但**用途改变**:它变成 tracker 侧的**覆盖检查表**(G6),真正的门是 §4.7.2 的**三道纯度门**。**另外 `gen_impl_mutation_surface.py` 在方案 B 里改造成 `gen_pipe_dirty_surface.py` 而不是删除**(推论 4) |
|
||||
| `MobileGL/RemoteClient/StateEmitter.h:39-307`(仅 emit 半边) | CHANGE,各域字段遍历抬进 `WireMirror` | **更直接可用**:那些字段集**就是** pipe 的状态对象 payload。必须修的缺陷不变:GL name 换 lifetimeId(`:48-49, 85, 166-168, 203, 230`)、O(n²) 线性扫描换 handle map(`:175-181, 244-249, 253-258, 293-298`)、固定 6 attachment(`:232-236`)换 `MaxColorAttachments`、补上被跳过的 texture view(`:70-74`)。**applier 半边(`:312-501`)仍然不取** |
|
||||
| `MobileGL/Protocol/mg_protocol_base.h` | REUSE | **同意**,且 **structSize-first 版本纪律是 B-R10 的对策** |
|
||||
|
||||
**DROP 名单完全一致**:`bfa.h`、`mgruntime_api.h` + `UtilRuntime/*`、`LocalSocketTransport` 的实现(每次 send 的 UAF、无上限分配、**`fd=-1` 硬编码**)、`ServerHost/main.cpp`、`StateEquivalenceTest.cpp`、`c7c9e346`+`29d721ef` 的 share-group sessioning、`b50f3348` 的 `RenderState::InstallParameters` + 裸 `public:`、`d96be9f3` 的 per-draw `fprintf` TRIAGE 指令。
|
||||
|
||||
---
|
||||
|
||||
## 附 A:接口调用目录速查表
|
||||
|
||||
> Flags:`A`=`kNeedsAck`、`B`=`kHasBlob`、`V`=`kVarTail`、`H`=`kHostSpan`、`R`=`kReplySlot`、`O`=`kOptional`。
|
||||
|
||||
### `MGPipeScreen`(14)
|
||||
|
||||
| 调用 | payload | flags | 取代 |
|
||||
|---|---|---|---|
|
||||
| `get_caps` | `MGPCaps` | R | 40 `pActiveBackendObject->` + 89 caps 读点 |
|
||||
| `resource_create` | `MGPResourceDesc` | — | buffer/texture/renderbuffer 创建 |
|
||||
| `resource_respecify` | `MGPResourceDesc` | — | `BufferBackendOps::Respecify` 泛化 |
|
||||
| `resource_destroy` | handle | — | `OnDestroy` + 两个 `WeakPtr` GC 扫描 |
|
||||
| `map_persistent` / `unmap_persistent` | handle | R, O | `AcquirePersistentMap`(改造期不碰) |
|
||||
| `fence_create` / `_status` / `_wait` / `_destroy` | handle (+timeout) | — / — / R / — | `FenceSync`…`GetSyncStatus`(两值契约保留) |
|
||||
| `query_create` / `_begin` / `_end` / `_available` / `_result` / `_destroy` | handle + kind | — | `BackendObject.h:230-256` |
|
||||
|
||||
### `MGPipeContext` — CSO(15)
|
||||
|
||||
`create/bind/delete` × `render_state` / `vertex_elements` / `sampler` / `sampler_view` / `shader`。
|
||||
`create_render_state` 带 `B`(**只带 pipeline 子集的 chunk**);`create_shader_state` 带 `B`(SPIR-V + `ProgramArtifacts` 归档)。
|
||||
|
||||
### `MGPipeContext` — `set_*`(17 + 1 临时)
|
||||
|
||||
`set_dynamic_state`(B) · `set_framebuffer_state` · `set_vertex_buffers` · `set_index_buffer` · `set_indirect_buffers` · `set_sampler_views`(V) · `bind_sampler_states`(V) · `set_texture_params` · `set_shader_images`(V) · `set_shader_buffers`(V,H) · `set_stream_output_targets`(V) · `set_global_constants`(B) · `set_vertex_attrib_defaults` · `set_pixel_pack_state` · `set_patch_state` · `set_draw_program` / `set_dispatch_program`
|
||||
**临时(P2..P13)**:`set_residual_value_state`(B),带 `static_assert(sizeof(ResidualValueBlock)==0)` 退役绊线。
|
||||
|
||||
### `MGPipeContext` — transfer(12)
|
||||
|
||||
`resource_subdata`(B,V) · `buffer_subdata_resident`(B,O) · `resource_flush_range` · `resource_readback`(R) · `resource_copy_region` · `blit` · `clear` · `generate_mipmap` · `read_pixels`(R) · `get_texture_image`(R) · **`resource_subdata_complete`**(拉取终止符,可零 region)
|
||||
|
||||
### `MGPipeContext` — 命令(10)
|
||||
|
||||
`draw_vbo`(H,V) · `launch_grid` · `memory_barrier` · `begin/end/pause/resume_stream_output` · `flush` · `present` · `set_swap_interval`(O)
|
||||
|
||||
### 反向:`MGPipeCallbacks`(10)
|
||||
|
||||
`on_gl_error` · `on_gpu_written` · `on_buffer_writeback` · `on_texture_writeback` · `on_texture_pull_request` · `on_mip_levels_generated`(**只带形状**)· `on_surface_changed` · `on_caps_invalidated` · `on_log`(**≤WARN 有损 / ≥ERROR 无损 + 速率限制**)· `on_xfb_scatter_ready`
|
||||
|
||||
### 显式删除
|
||||
|
||||
`GetIntegeri_v` · `GetInteger64i_v` · `GetProgramiv` · `ShaderStorageBlockBinding`(折进 `MGPProgramDesc`)· `set_pixel_unpack_state`(不存在)· 压缩格式概念(不存在)· `pipe_transfer`(不存在)· `set_sampler_views` 的 stage 维度(不存在)· `kCapPrimitiveRestart` / `kCapPrimitiveRestartFixedIndex` / `kCapMultiDraw` / `kCapMultiDrawIndirect` / `kCapMultiDrawIndirectCount`(**归属不可表达,D-B7**)
|
||||
|
||||
---
|
||||
|
||||
## 附 B:环境变量与 CMake 选项
|
||||
|
||||
### CMake
|
||||
|
||||
| 选项 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `MOBILEGL_BUILD_DISAGGREGATED` | OFF | 出货形态。开启后 `MG_Remote/**` 进 `SOURCE_FILES`。**两个**进程全局保持普通全局,GL 热路径无 TLS |
|
||||
| `MOBILEGL_BUILD_DISAGGREGATED_INPROC` | OFF | CI/调试形态,隐含开启上者,额外加角色隔离 shim(只需隔离 `gPipeCtx` 与 `pActiveBackendObject`) |
|
||||
| `MOBILEGL_PIPE_VERIFY` | OFF | **构建期开关**(不只是运行期):编译进 `SnapshotFromGLContext()` 与 G4 比对器。**P13 之后仍保留**;三道纯度门只跑此项为 OFF 的构建 |
|
||||
| `MOBILEGL_PIPE_LEGACY_MEMOS` | ON(P2..P13) | 保留 registry / `TwinLookupMemo` 实现,给前两波 handle 化一个真正的旧-vs-新臂(B-R16) |
|
||||
| `MOBILEGL_FLATC_EXECUTABLE` | 空 | 只服务 CI 的 `flatc-check`;默认构建图里没有 `flatc` |
|
||||
| `MOBILEGL_BAKED_INTERNAL_SHADERS` | ON(P7+) | DirectVulkan 的 blit/depth-mipmap shader 烘焙成签进树的 SPIR-V,由 `MG_Test` 重跑树内 glslang 逐字节比对守新鲜度。**monolith 也受益** |
|
||||
|
||||
> 注:`MG_Pipe/**` **不在任何 option 之后**——它是 monolith 的架构,永远进构建。
|
||||
|
||||
### 运行时(方案 B 新增)
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `MOBILEGL_PIPE_PUSH` | 迁移期按阶段推进;P13 后删除 | 子系统位图(0 = 全 pull),**含一位关闭 CSO 内容寻址**(P2 的负面对照)。**注意 stage C 之后 A/B 口径收窄**(§6.7、B-R16) |
|
||||
| `MOBILEGL_PIPE_VERIFY` | 0 | 逐 draw 逐字段影子比对(~5-10× 慢,**含纹理 dirty 集合的保留模式**,永不出货) |
|
||||
| `MOBILEGL_PIPE_STATS` | 0 | 字节 / **调用** / roundtrip / 纹理拉取 / 上传形状 / 残余块 / 索引镜像计数器转储 |
|
||||
| `MOBILEGL_PIPE_TEXEL_RETAIN_MB` | **0**(v2 从 32 改) | 纹理重铸拉取的保留 LRU 预算。默认关闭:`MipmapStorage` 保有完整 CPU 影子,缓存买的是延迟不是正确性(§7.5c) |
|
||||
| `MOBILEGL_PIPE_INDEX_MIRROR_MB` | 64 | server 侧索引宿主镜像预算(D-B7)。超预算退化为逐 draw 传送并计入 `index-bytes-shipped` |
|
||||
|
||||
### 运行时(继承 `PLAN.md` 附录)
|
||||
|
||||
`MOBILEGL_TRANSPORT`(`monolith` 默认 / `inproc` / `spawn` / `unix:<path>` / `pipe:<name>`)· `MOBILEGL_IPC_SERVER_PATH` · `MOBILEGL_IPC_RING_MB`(8) · `MOBILEGL_IPC_STAGE_MB`(32,上限由实测定) · `MOBILEGL_IPC_PRESENT_CREDIT`(**1**) · `MOBILEGL_IPC_SPIN_US`(50) · `MOBILEGL_IPC_POLL_ESCALATE`(64) · `MOBILEGL_IPC_PERSISTENT_BLOCK_KB`(64) · `MOBILEGL_IPC_ADOPT_TIER`(auto) · `MOBILEGL_IPC_SHADOW_SHM`(1,P4.5+) · `MOBILEGL_IPC_INLINE_PAYLOADS`(0,负面对照) · `MOBILEGL_IPC_SERVER_AFFINITY`(auto) · `MOBILEGL_IPC_STRICT_ERRORS`(0) · `MOBILEGL_IPC_AUDIT`(0) · `MOBILEGL_IPC_TRACE`(0) · `MOBILEGL_IPC_ATTACH`(空) · `MOBILEGL_IPC_RESPAWN`(0) · `MOBILEGL_IPC_IDLE_EXIT_S`(30)
|
||||
|
||||
**删除**:`MOBILEGL_IPC_PROGRAM`(没有 relink 档)· `MOBILEGL_IPC_VALIDATE_SERVER`(server 没有 `MG_Impl` 校验器——替代手段是保留的 verify 构建 + P13 的 MGPipe recorder 金标,见开放问题 11)
|
||||
|
||||
**保留的既有负面对照开关**:`MOBILEGL_ESPRYT_DISABLE_UBO_RING` · `_UNPACK_RING` · `_UPLOAD_RING` · `_INVALIDATE_FLUSH` · `MOBILEGL_DISABLE_LARGE_BUFFER_ADOPTION` · `MOBILEGL_COHERENT_AS_FLUSH`(**在拆分模式下照常生效**,这样两个 `coherent_as_flush: true` 的 Create fixture 在 split 与 monolith 下走同一条 buffer 路径,逐名对比才有意义)
|
||||
@@ -0,0 +1,246 @@
|
||||
# MobileGL 方案 B 实施计划:gallium 式显式接口 + backend 自有状态机(MGPipe)
|
||||
|
||||
> 状态:设计定稿 v1(2026-09-05)。基线 `dev@81b17c0b`;实施分支 `feat/disaggregated`(worktree `../MobileGL-disagg`)。
|
||||
> 本文是**方案 B** 的实施计划。方案 A(server 内跑 `MG_State::GLState::GLContext` replica)见同目录 `PLAN.md`,其评审记录见 `REVIEW.md`。
|
||||
> 本文继承方案 A 的 §6-§13(传输、数据面、同步、present、线程、平台、构建),**只替换它的状态模型**(§5 与 §12 的 replica 特化部分)。凡标注"继承 PLAN.md §X"的内容,以 `PLAN.md` 为准,本文不复述。
|
||||
> 全部 `file:line` 引用针对**工作树** `dev@81b17c0b`。工作树有两处未提交的 `fprintf` 插桩,使 `DirectGLES.cpp` 在 ~660 行之后偏移 +11、`Managers.cpp` 在 872 行之后偏移 +3;`MG_State/`、`MG_Impl/`、`MG_Backend/DirectVulkan/` 的行号与 HEAD 一致。
|
||||
> 阅读顺序:本文件(§0-§3)→ `synth-part2.md`(§4-§6)→ `synth-part3.md`(§7-§10)→ `synth-part4.md`(§11-§14 + 附)。
|
||||
|
||||
---
|
||||
|
||||
## 0. TL;DR、推荐与决策
|
||||
|
||||
### 0.1 一句话
|
||||
|
||||
**`MG_Backend` 已经是一台贴着目标 API 的状态机;它缺的不是状态,而是一份"我被告知了什么"的显式声明。MGPipe 就是那份声明。** 前端不再让 backend 每 draw 走 293 次 `MG_State::pGLContext->` 把整个 `GLContext` 拉出来,而是在每条命令之前由一个 state tracker 把变化**推**过去;server 进程因此只需要装 `MG_Backend` + MGPipe 的对象表,**不链接 `MG_State`、不链接 `MG_Impl`、不链接 glslang**。
|
||||
|
||||
### 0.2 接口不是从 gallium 自顶向下设计的,是从两个 backend 自己维护的关键结构反推出来的
|
||||
|
||||
这是本设计与"照抄 gallium"的根本区别,也是完整性论证的来源:
|
||||
|
||||
| backend 已有的结构 | 它是什么 | 反推出的接口 |
|
||||
|---|---|---|
|
||||
| `SetupDrawSnapshot`(`VulkanRenderer.h:948-1042`,40+ 字段) | Magma 一次 draw 必须钉住的**全部**东西的枚举 | `set_*` 组的并集 |
|
||||
| `DrawTextureSyncKeys` + `BackendTextureObject::IsDrawSyncClean`(`Managers.h:1003-1020`) | Espryt 纹理"是否还干净"的**全部**输入 | `set_sampler_views` + `create_sampler_view` |
|
||||
| `ResolvedDrawBuffers`(`Managers.h:697-717`)/ `ResolvedVertexBindings`(`VulkanRenderer.h:1153-1218`) | 顶点输入的完整声明 | `bind_vertex_elements_state` + `set_vertex_buffers` + `set_index_buffer` |
|
||||
| `g_syncedRenderStateParameters`(`DirectGLES.cpp:1956`) | 渲染状态声明,**逐字节** | `create/bind_render_state`(整块,见 0.5) |
|
||||
| `BufferBackendOps`(`BufferObject.h:76-120`,7 个 hook) | 已经是接口,且注释自称 "the `pipe_context` buffer-op analogue"(`:68`) | `resource_*` 全族 |
|
||||
|
||||
把这些结构的**输入集合**推过去,接口就按构造完整。gallium 是**目的地**(同名同形的词汇让形状可读、可迁移),不是**推导前提**。凡 gallium 的词汇与本仓库的证据冲突的地方,本文按证据走,并在 §4.6 逐条记名列出偏离与理由。
|
||||
|
||||
### 0.3 三条结构性推论(决定了后面每一节)
|
||||
|
||||
**推论 1 — 推送必须发生在 draw 时刻,不是 GL setter 时刻。** Blaze3D 每个 batch 都用 `glEnable/glDisable(GL_BLEND)` 包住,代码自己把它标成最热的路径(`DirectGLES.cpp:2044-2046`:`mc_state_toggle` 干的最热的事)。天真的 per-setter 推送会把每一次冗余开关变成一次接口调用加一次 server 侧 CSO 查表,**严格慢于今天**。正确形态是 gallium 的 `st_validate_state`:前端的 21 个版本计数器就是现成的 dirty 模型,tracker 在每条命令前做一次 dirty word 比较,只发变了的组。**这是本计划里最容易做错、且做错就必然回归的一处。**
|
||||
|
||||
**推论 2 — handle 就是身份,而且必须是稠密 slot。** 每个前端对象已经有一个永不复用的 `GetLifetimeId()`(`BufferObject.h:202-208`、`VertexArrayObject.h:110-120`、`FramebufferObject.h:151-158`、`ProgramObject.h:1620`、`TextureObject.h:83`、`SamplerObject.h:533-537`),它们存在的唯一理由是 GL name 会被 `IndexGenerator::Generate` 从 free list 尾部 LIFO 复用(`MG_Util/Miscellany/IndexGenerator.h:30-42`)、堆地址会被分配器复用。但**单调的 64 位 id 不能索引数组**——如果 wire handle 直接用 lifetimeId,server 侧仍然是一张哈希表,那就只是把指针键换成整数键,并没有删掉查表层。所以 wire handle 是 `{slot: Uint32, gen: Uint32}`,**slot 由 client 按 kind 稠密分配**,`gen` 在 slot 复用时 ++。lifetimeId 留在 client 侧作为 tracker 自己的身份,不过线。这一条才真正把 6 个 `StateBackendObjectRegistry` 哈希表和 13 个 Magma 身份键缓存变成**数组**。
|
||||
|
||||
**推论 3 — server 拥有 client 看不见、也永远不该被问的 generation。** 今天有 12 个纯 backend 侧的单调计数器,它们表达的是"**我自己**重新铸造了驱动对象",与任何前端版本无关:Espryt 的 `g_bufferMutationEpoch`(`Managers.h:397-441`)、`g_bufferBackendIdGeneration`(`:551`)、`g_attachmentBackendIdGeneration`(`:1298`)、`g_backendContextGeneration`;Magma 的 `m_textureImageEpoch`、`m_resourceEraseEpoch`、`m_renderbufferImageEpoch`、`m_sliceEpochCounter`、`m_cacheStructureEpoch`、`m_evictionEpoch`、`m_recordingGeneration`、`m_frameSerial`。本文把它们统称 `MGGen`,**它们永不上线**。"server 拥有自己的状态机"在工程上的确切含义就是这一条:client 绝不是"我的 server 侧状态是否新鲜"的唯一权威。
|
||||
|
||||
### 0.4 与方案 A 的结论性对比(详表见 §3)
|
||||
|
||||
**方案 B 在架构、内存、长期价值上赢;方案 A 在"多快能拿到第一帧"上赢,而且赢得毫无悬念。**
|
||||
|
||||
方案 B 赢的四点,全部可核对:
|
||||
|
||||
1. **内存。** `PLAN.md` 自己的 R14(第 1222 行)给 replica 预算 "合计可达 ~450MiB 新增":每个 <16MiB store 一份重复 `PipeResource`、每个纹理 level 一份重复 `MipmapStorage`、一整份 `GLContext` 对象图,叠在两侧都要付的传输段与 ring 之上。这在一个把"省 400MB"当作头条战果、且有 blanket-immutable 触发 LMK 屠杀记忆的项目里,是最难辩护的一条。方案 B 不复制任何东西:传输段(~48MiB)+ POD slot 记录 + 一个**可选的、有上限的 ≤32MiB 纹素保留 LRU** ≈ **+50-60MiB**。
|
||||
2. **拷贝。** `PLAN.md` §6.4 数出 `glBufferSubData` → store 在 split P1-4 是 **4 次**、P4.5 是 **3 次**,其中第 (3) 次是 `SEG_STAGE`→**replica** shadow。没有 replica 就没有这次拷贝:方案 B 是 **3 / 2**。而 `PLAN.md` 自己把 2 次称作"方案 B(激进,需额外设计)"(第 549 行),要求给 replica 的 `PipeResource` 加第三种 `AdoptedClientShadow` 模式并处理 server 侧写的 copy-on-write 升级,且把它推迟到 P6 由 Tracy 数据决定(开放问题 §17-5)。方案 B **按结构就在那个目标上**,并顺带关掉它自己的开放问题。
|
||||
3. **漂移面。** replica 是一份必须与 20k 行 `MG_State` **语义**长期锁步的手写状态模型,而它的守卫(生成的 `is_same_v`/`sizeof`/`offsetof` + `reflectionDigest`)只能看见**签名**漂移。`MipmapStorage` 的 96-rect 级联合并与 `summedArea*4 >= unionArea*3` 回退(`MipmapStorage.cpp:300-305`)、`VecRange1D` 的 7% gap 比、`PipeResource` 的模式切换、`BufferObject` 的 persistent-map 状态机——任何一处行为不一致都能编译通过、在多数内容上渲染正确,而这恰好是本项目已经实测出 **+6ms/frame** 悬崖的那块地方。方案 B 只有一份状态模型,这一类失效**不可表达**。
|
||||
4. **整块子系统消失而不是被移植。** `PLAN.md` §2(g) 的"第七个面"(MG_Impl 在 table 调用旁做的 `MG_State` mutation:`AccountTransformFeedbackPrimitives`、`EnsureGeneratedMipmapStorageAllocated`)连同它的第二个代码生成器 `gen_impl_mutation_surface.py`、`MutationCoverage.def`、`ImplMutationSurface.inc`、`MG_Remote::Shared::` helper 族和风险 R1,在方案 B 里**不存在**——没有 replica 就不需要 replay。同样消失的还有:§5.6a 的纹理 ack 协议与 R6;§5.7 的 "server 自建 composite" 分支;§6.9 的 relink 档与整个阶段 P5(6 天);§12.2 里跨越 1494 个 `MG_Impl` 站点的 `pGLContext` shim(`inproc` 需要隔离的进程全局从 4 个降到 2 个,`PLAN.md` 最早的证伪门 P2.5 因此变便宜)。
|
||||
|
||||
**`RecProgramLinkOp` 不是"不理想",是不可能。** `ProgramObject.h:11` include `ShaderObject.h`,后者 `:12` include `ShaderCompileTask.h`、`:146` 返回 `SharedPtr<glslang::TShader>`;`ProgramObject.h:14` 又拉进 `SpvcSession.h`。**任何链接真 `ProgramObject` 的 server 就链接了整条编译链。** 所以方案 A 的两档 program 方案在方案 B 里塌成一档:`create_shader_state` 第一天就是 SPIR-V + 反射归档,`reflectionDigest` 这个"分歧预言机"因为没有可分歧的对象而被换成一个**schema 完整性绊线**(`Visit()` 全结构体归档 + `sizeof` static_assert)。
|
||||
|
||||
方案 A 赢的一点,也毫无悬念:
|
||||
|
||||
- **到首个跨进程帧的时间。** `PLAN.md` 的阶段天数逐项相加恰好是 **77 天**(P0 5 + P1a 6 + P1b 4 + P2 9 + P2.5 3 + P3 5 + P4 5 + P4.5 4 + P5 6 + P6 6 + P7 8 + P8 6 + P9 10),其中 **P1b 出口(≈第 15 天)就是首个跨进程帧**,因为它一行 backend 代码都不用改。方案 B 最早的 `inproc` IPC 帧在第 ~68 天,最早的**跨进程**帧在第 ~73 天,且那一帧是**缩减路径**(emulation 在 P8 之前于 split 模式下直接 Fatal),全功能要等 P8。总估时 **200-260 人天**(含 IPC;不含 CTS 周转,见 §11.5)。
|
||||
|
||||
**如果目标是"这个季度拿到一个能跑的拆分",选方案 A。如果目标是用户实际提出的那个——"backend server 拥有自己的状态机并暴露统一的、gallium 式的接口把前后端解耦"——方案 A 在任何价格下都不交付它**:它用复制前端来回答耦合,而不是用定义契约来回答耦合,而且那份复制的维护成本是**永久**的;方案 B 的成本是**一次性**的,且在第一个字节过 socket 之前就已经把 monolith 变好(删掉 ~550 行 per-draw 失效发现机制、让复用地址 ABA 一类失效不可表达、删掉一个排序 hazard、删掉一处分层倒置、修掉两个潜伏 bug、暴露一个死能力)。
|
||||
|
||||
### 0.5 六个必须先记下来的具体决定(这些是评审里争议最大的点)
|
||||
|
||||
**D-B1:渲染状态用"整块 blob + CSO handle",绝不拆成 blend/depth-stencil/rasterizer 三个 CSO。**
|
||||
`RenderStateParameters`(`RenderState.h:222-370`)是一个平凡可复制的 POD,Espryt 在 `DirectGLES.cpp:2035` 亲自 `static_assert(std::is_trivially_copyable_v<...>)`,紧接着做 head/blend/tail **三段 memcmp**(`:2042-2047`);而 `RenderState.h:359-368` 白纸黑字写着 `ScissorBoxWrittenMask` 和 `ClipDistanceEnabledMask` 是**故意**摆在 tail 段里,好让那次 span memcmp 像抓其它状态一样抓到它们。**字段顺序是承重的。** 拆成三个 CSO 会丢掉一条被文档化的布局不变式,还要手工维护一张 ~150 字段的"字段→CSO"划分表且没有任何完整性绊线(漏分配的新字段会静默永不推送),而 Espryt 无论如何还要保留整块 blob 才能对着驱动做增量 GL 调用。
|
||||
**最终形态**:`create_render_state(cso, const RenderStateParameters*)`(整块,每个唯一状态一次)+ `bind_render_state(cso, version, pipelineVersion)`(稳态 12 字节)。client 侧维护 64 项 LRU,键是三段的 xxHash。命中 → 12 字节;未命中 → 发生成的**变化段**(3 bit `dirtySpanMask`,段划分与现有 memcmp 完全一致)+ 前一个 CSO handle 作为基。Espryt 的 memcmp 变成 handle 比较且它自己保留每 CSO 的 blob;Magma 每 CSO 算一次 pipeline hash,而不是每次 `GetPipelineStateVersion()` 移动都算。**两个版本计数器都上线**(`m_version` `:522` 与 `m_pipelineStateVersion` `:529`)——合并它们会让每一次 `glViewport` 冲掉 Magma 的 pipeline memo,这正是 `:523-528` 记录的那次回归。
|
||||
|
||||
**D-B2:`create_shader_state` 不返回一个"做完了的"对象。** backend program 还依赖 8 个额外输入(`DirectGLES.cpp:2766-2818`:draw FBO 的 snorm/unorm fallback clamp mask、由 draw-buffer 数组推出的 fragColor 广播数、storage-block 绑定签名、atomic counter 绑定集、**活的** `glBindImageTexture` 格式、patch 参数;Magma 另加 FragCoord-Y-flip 的 default-FB 高度和 XFB 布局)。接口**明说规则**:`create_shader_state` 发布**制品**,server 在 draw 时刻从它已经被推送过的状态**惰性特化**。这正是两个 backend 今天的做法,而推送模型让它比拉取模型**更安全**(见 D-B3)。
|
||||
|
||||
**D-B3:validate 顺序是契约,不是 hazard。** framebuffer 严格先于 program。四个跨对象 mask 由 FBO sync 从 attachment 格式推出(`Managers.cpp:5616-5619`),又被渲染状态推送(`DirectGLES.cpp:2014`)和 program 陈旧性判定(`:2769-2770`)消费;今天 Espryt 靠**自己在 `SyncCurrentProgram` 里重新推导广播数**(`:2712-2732`)来绕过这个排序,注释写明"否则用陈旧计数编译出的 program 要等到下一次 draw 才会重链"。固定推送顺序把 hazard 变成免费属性,那段 workaround 和 `g_broadcastMemo*` **一起删掉**。同理 `ImageUnitFormatsStillMatch`(`Managers.cpp:6545-6573`,注释明说"不可表达为单调版本")被 `set_shader_images` 直接告知。
|
||||
|
||||
**D-B4:AcquirePersistentMap 在整个改造期一动不动。** 它是**永久的地址空间捐赠**而不是 gallium 的 scoped `transfer_map`:返回一个 host-visible coherent 指针,成为该 buffer 的唯一真相源(`BufferObject.h:102-118`),由 `PipeResource::AdoptPersistentMap`(`PipeResource.h:115`)采纳、经 `MappedData()` 交给应用、≥16MiB 可变 store 由 `TryAdoptLargeStorage` 自动走到(`:226-228`)。实测代价是 MC 26.3 的 p99 163→21ms、40→115fps、省 ~400MB。**它今天就已经是一个"返回指针的显式调用",因此原样穿过 monolith 改造;只有 IPC 那一步才会打破它。** 所以:改造期不碰,IPC 期按 `PLAN.md` §6.8 的三档 POST 探针决定,spike B 第一周给答案。绝不允许一个平台未知数挡住 200 天的接口工作。
|
||||
|
||||
**D-B5:monolith 字节一致门按构造死亡,这是本方案的成本,必须写在明面上。** `PLAN.md` §12 第 4 层(`nm --defined-only` + 剥调试信息后 `.text` size 相等,且每阶段都跑)是它最强、最机械的保证。方案 B 让 backend 停止读 `pGLContext`、让 memo 换键、让 `MG_Impl` 多出 validate 调用——**不存在任何配置能让旧字节回来**。替换是**五部分门**(§10.3),其中第 2 部分(每 draw 逐字段的 pushed-vs-snapshot 影子比对)在语义上**严格强于**任何符号 diff,而且它只有在"接口先落在 monolith 里、两套状态模型活在同一个地址空间"的前提下才存在。
|
||||
|
||||
**D-B6:方案 B 引入一个方案 A 没有的新停顿类:server 发起的纹理重铸拉取。** server 不保留纹素字节,所以 `RequireImageBindableStorage` 的 re-dirty(`Managers.cpp:2813`)、整格式再生(`:3950-4195`)、view 源重铸(`:3616-3707`)都必须回头向 client 要数据。**三条缓解同时上,不是三选一**,加一个专门的门和一个逐 trace 用例发布的计数器(§7.5)。上一轮 thin-server 设计正是因为把这条一笔带过而被判死,本文不重复。
|
||||
|
||||
### 0.6 推荐
|
||||
|
||||
**推荐执行方案 B,但按下面这个对冲路径起步,在第 24 天做一次真正的 GO/NO-GO:**
|
||||
|
||||
先原样跑 `PLAN.md` 的 P0(它的卫生、传输骨架、两个 spike,尤其是 **`TracyPlot` 逐帧字节计数器**——树里今天完全没有 per-frame 字节或调用度量,`MG_Util/Metrics` 只是格式算术,Tracy 只有 zone 无 plot),然后跑本文的 **P1 + P2**(共 ~16 天)。第 24 天你手上会有:
|
||||
|
||||
- 一套 `MOBILEGL_PIPE_VERIFY` 影子比对 harness,在全部 40 个 trace 用例和 367 个集成测试上逐 draw 逐字段证明"推送等价于拉取",**产品零风险**;
|
||||
- 两个 backend 上都已推送的渲染状态,`SyncRenderState` 的 693 行函数体一行未动、memcmp 门变成 handle 比较,Magma 的 ~40 次 accessor payload 走查消失;
|
||||
- 两台设备上 reboot-clean 配对的**逐线程 CPU 时间**增量——本设计中心性能主张("可达性遍历是**搬走**了而不是翻倍,而且更便宜")的第一个真数字;
|
||||
- Track H(对象类读点)在两个最便宜子系统上的实测单位成本。
|
||||
|
||||
这 16 天无论最后选哪个方案都不浪费:P0 完全是 `PLAN.md` 的,P1 的 `sed` 替换在 pull 构建里字节一致,P2 的渲染状态推送即使不做拆分也是 monolith 的净收益。**如果第 24 天的 CPU 数字是负的、或者 Track H 的单位成本比估计高 50% 以上,退回方案 A 只损失这 16 天。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
1. **定义并落地一份显式的前后端接口 MGPipe**:句柄寻址、只推不拉、gallium 形状,client 与 server 都只依赖它。
|
||||
2. **backend 拥有自己的状态机**:`MG_Backend` 在 MGPipe 构建下**不含** `MG_State::pGLContext`,`MG_State` include 收缩到一张共享**值**头文件白名单,server 产物的 `nm --undefined-only` 里没有 `MG_State::GLState::` 符号、没有 glslang 符号。
|
||||
3. **前后端跑在两个进程**,通过 IPC 通信;client 把状态 reconcile 成推送调用、序列化(FlatBuffers)后发送;server 更新自身状态并调 backend API。
|
||||
4. **稳态帧零 round trip**(回读 / 阻塞式 query / sync wait / present credit / 分配类错误 ack / 纹理拉取之外,且后者的次数必须**实测发布**而非声称为零)。
|
||||
5. 两半尽可能互相异步;client 至多领先 server 1 个 present(默认,延迟叠加分析继承 `PLAN.md` §9.1)。
|
||||
6. 平台特定代码最小化并集中在 `MG_Remote/Transport/` 与 `MG_Remote/Client/Surface*`(继承 `PLAN.md` §11)。
|
||||
7. **单进程 Monolith 保持功能与性能不回归**,由五部分门机械验证(§10.3)。注意这**不是**方案 A 的"字节级不变"——见 D-B5。
|
||||
8. 所有验收门用**现有测试**:`ctest -L unit`(428 个 `TEST(`)/ `-L integration-gpu`(367 个 `TEST_F`,75 个场景文件)/ `tools/trace_replay`(40 个用例,默认 SSIM ≥ 0.99)/ `tools/cts` / `tools/device_bench`。
|
||||
9. **接口本身是可独立交付的产物**:即使 IPC 永不上线,`inproc`(同进程第二个 apply 线程)就是 monolith 的渲染线程交付物,且是本项目手上最大的单一 CPU 杠杆。
|
||||
|
||||
### 1.2 非目标
|
||||
|
||||
- **share-group sessioning 重构。** 与 `PLAN.md` 一致:`eglCreateContext` 的 `shareCtx` 只在 `EGLState/Core.cpp:632` 被校验、`:640` 被存进 `EGLContextState::SharedContext`,**全代码库无人读取**(repo 级 grep 只返回这两行);`pGLContext` 是唯一进程全局(`GLState/Core.cpp:20, 1487`)。v1 = 一条 flow、一个扁平 handle 空间。但**接口头文件从第一天就把 `MGPipeScreen` 与 `MGPipeContext` 分开**(§4.3),因为事后再拆要给每个记录种类重新编号。`c7c9e346`/`29d721ef` 那套整体丢弃(理由见 `PLAN.md` §14 DROP)。
|
||||
- **BFA strict-C-ABI backend 插件 / UtilRuntime C-ABI 化**(同 `PLAN.md`)。
|
||||
- **macOS 拆分**(同 `PLAN.md`:`CAMetalLayer` 无公开跨进程表示,interposer 导出表锁定于 `CMakeLists.txt:600-612`,无 CI 无设备 → monolith only)。
|
||||
- **Windows 窗口拆分**(同 `PLAN.md`:headless/pbuffer only)。
|
||||
- **把 emulation 层重写到 client。** 只有五个"读前端字节的纯 CPU 变换"下放到 client(§5.7);viewport-array 回放、multi-draw 分档、fp64 顶点转换、image-bindable 存储加宽等**全部留在 server 作为 lowering pass**,接口只负责把它们的输入表达清楚。
|
||||
- **在 P13 之前删除 pull 路径。** 旧路径一直编译在里面,任何提交都能用一个 env 位 A/B。
|
||||
|
||||
---
|
||||
|
||||
## 2. 现状:边界为什么不清楚
|
||||
|
||||
### 2.1 今天的边界有七个面(沿用 `PLAN.md` §2 的分面,数字按工作树复核)
|
||||
|
||||
**(a) `GLFunctionsTable`** — `MG_Backend/BackendObject.h:117-278`。**实测 67 个函数指针 + 1 个 `Bool` 能力位**(`PrefersCpuXfbPrimitiveAccounting`),`GlobalBackendFunctionsTable`(`:279-285`)再加 `Present` 与 `SetSwapInterval` → **全体 69 个函数指针**。(`PLAN.md` 与几份调研报告里的 "73 项"/"71 项" 都是旧计数或口径不同,本文一律用 67+1/69。)
|
||||
MG_Impl 侧 **89** 个 `gBackendFunctionsTable.GL.*` 调用点。**null 项已经表示"未实现,前端回退"**,这一点被写进头注释(`:212-215` 的 sync 族、`:265-269` 的 XFB 跨度),且 DirectVulkan 确实留空 8 项而 Espryt 填满。三项是错位的前端查询:`GetIntegeri_v`/`GetInteger64i_v`(`:195-196`,`DirectGLES.cpp:7264-7386` 有 15 个 case 完全不碰 GL)、`GetProgramiv`(`:197`)。`ShaderStorageBlockBinding`(`:207-208`)的注释自己就说 program interface 全部由前端回答。
|
||||
|
||||
**(b) `BackendObject` 虚函数** — `BackendObject.h:543-568`,MG_Impl 侧 **40** 个 `pActiveBackendObject->`(其中 35 个是 `GetDynamicParameters()`)。`InitCapabilities()` 懒执行在第一次成功的 `eglMakeCurrent` 内部(`BackendObject.cpp:341-347`),且每次 surface 变更重新武装(`:301`)。
|
||||
|
||||
**(c) `BufferBackendOps`** — `BufferObject.h:76-120`,**7 个 hook**,注册入口 `:124`。Espryt 注册 7/7(`Managers.cpp:1338-1346`),Magma 注册 6/7(**故意**不注册 `ResidentSubData`,`VkBufferManager.cpp:104-111`,保留旧的就地宿主写;`BufferObject.h:84-92` 记录了它存在的理由是 Minecraft 在活的 coherent map 上就地改字节会撕裂正在读旧字节的帧)。**这个面已经是 MGPipe 的三分之一,且注释自称 `pipe_context` 类比。**
|
||||
|
||||
**(d) 状态拉取** — `MG_State::pGLContext->` 在 `MG_Backend` 里 **293 次出现 / 290 行**(DirectGLES 124:`DirectGLES.cpp` 102 + `Managers.cpp` 15 + `MultiDraw.cpp` 5 + `Utils.cpp` 2;DirectVulkan 169:`VulkanRenderer.cpp` 126 + `DirectVulkan.cpp` 18 + `UniformManager.cpp` 14 + `VkRenderPassManager.cpp` 3 + `VkTextureManager.cpp` 2 + `BackendObject_DirectVulkan.cpp` 2 + `VkClearManager.cpp` 1),**外加 58 行非箭头用法**(见 2.4)。此外还有约 1997 个前端对象 getter 调用点、186 个不同 getter(上界统计,少数名字与 backend 本地结构撞名)。
|
||||
|
||||
**(e) backend → frontend 写回** — 逐名 grep 实测 **95 个调用点 / 17 个方法**:`SyncPersistentMappedRange` 20、`MarkStorageDirty` 18、`AllocateStorage` 8、`WritebackFromBackend` 8、`SetInternalFormat` 7、`SyncGpuWrites` 6、`MarkGpuWritten` 6、`RecordError` 6、`SetBackendResource` 4、`EnsureGpuResidentStorage` 3、`SetBackendHashMemo` 2、`InvalidateCompileEnv` 2、`SetBackendStateMemo` 1、`SetBackendAuxMemo` 1、`UpdateMipmapSubData` 1、`TruncateMipmapLevels` 1、`SetSamples` 1。
|
||||
|
||||
**(f) backend 反向进 MG_Impl** — 恰好 6 处:`DirectGLES.cpp:1917, 2838, 2867, 9675`(`pDefaultFramebufferInfo` 身份比较)、`SwapchainObject.cpp:276`(**写**,backend 在 client 侧创建 default-FBO 的颜色/深度/模板 `ITextureObject`)、`VulkanRenderer.cpp:10700`(`CopyTextureImageToClientOrPBO_State`,一处真正的分层倒置)。
|
||||
|
||||
**(g) MG_Impl 在 table 调用旁做的 `MG_State` mutation** — `EnsureGeneratedMipmapStorageAllocated`(`GL_Texture.cpp:501-544`,调用点 `:6698, 6708`)与 `AccountTransformFeedbackPrimitives`(`GL_Drawing.cpp:172`,调用点 `:1133, 1141, 1195, 1668`)。**在方案 B 里这个面不存在**:它只有在"server 必须重放前端的副作用"时才是拆分问题,而 MGPipe 的 server 没有前端可以重放。
|
||||
|
||||
**(h) 工作树污染** — `DirectGLES.cpp:290-303`/`:640-663` 与 `Managers.cpp:875-877` 的未提交 per-draw `fprintf(stderr)`(后者在 `pendingMutex` 临界区内)。**P0 第一件事就是清掉**,它污染每一次基线测量。
|
||||
|
||||
### 2.2 backend 已有的状态机清单(这就是"server 已经是薄服务端"的实证)
|
||||
|
||||
**DirectGLES(Espryt)**
|
||||
- 6 个 twin registry,全部是 `StateBackendObjectRegistry<StateObject*, {BackendPtr, weak_ptr}>`(模板 `Managers.h:270-390`;实例 `:806`(VAO) `:1123`(Texture) `:1216`(FBO) `:1731`(Program) `:1830`(Sampler) `:1858`(Renderbuffer)),键是**前端裸堆地址**,用同址 `weak_ptr` 防 ABA,GC 阈值 `kGCInterval=1024` draw / `kCreationGCInterval=64` 次创建。
|
||||
- 三条 persistent-mapped bump ring(UBO `Managers.h:591-637`、纹理 unpack PBO `:639-671`、buffer upload `:673-…`),各自 4MiB 起 → 64MiB 上限,各带帧 fence 回收水位;buffer pool 预算 `kMaxPoolBytes = 64MiB`、单 buffer 上限 8MiB(`Managers.cpp:564-565`)。
|
||||
- 每对象 twin:`GLESBufferResource`(`Managers.h:443-497`,含 `pendingRanges`/`pendingResidentWrites`/`drawCleanEpoch`/`syncedChangeSerial`)、`BackendVertexArrayObject`(`:675-803`,32 路 client-attribute 暂存 + 转换后的 fp64 流 + 同步版本影子)、`BackendTextureObject`(`:944-1119`,`StateTextureBasicInfo` + 采样器/参数缓存 + `IsDrawSyncClean` 聚合门)、`BackendFramebufferObject`(`:1140-1213`,含 `m_backendColorSlots` draw-buffer 置换表)、`BackendProgramObjectImpl`(`:1473-1725`,最大的一个:跑 SPIRV-Cross 转 ESSL 并用 ES 驱动 link,缓存全部 emulated builtin 的 uniform location、编译输入快照、`SamplerPassMemo`)、`BackendSamplerObject`(`:1808-1824`)、`BackendRenderbufferObject`(`:1838-1855`)。
|
||||
- 完整的渲染状态**值镜像** `g_syncedRenderStateParameters`(`DirectGLES.cpp:1956`)+ 三段 memcmp 门(`:2035-2047`)。
|
||||
- 驱动绑定影子:`BindBufferId`/`BindPixelPack/UnpackBufferId`、`g_indexedUBO/SSBO/XFBBindings`、`BindBackendVAOId`、`g_driverFBOBindings`、`g_boundTexturesCache[192][TargetCount]`、`g_boundSamplersCache[192]`、`g_activeTextureUnit`、`PackState`。
|
||||
- 三个共享 scratch FBO 及其完整驱动侧 attachment 影子(`Managers.h:1338-1359`)。
|
||||
|
||||
**DirectVulkan(Magma)**
|
||||
- `VulkanRenderer`:`PipelineMemoEntry m_pipelineMemo[8]`(`VulkanRenderer.h:808-830`)、`SetupDrawSnapshot m_setupDrawSnapshots[4]`(`:948-1042`,40+ 字段)、`VaoDrawMemo m_vaoDrawMemoTable[2048]`(`:1230-1266`)、`ResolvedVertexBindings`(`:1153-1218`)、`m_convertedVertexStreams`(`:1080-1144`)、`DynamicStateShadow g_dynamicStateShadow`(`VulkanRenderer.cpp:277-340`)、采样集/LOD/BaseVertex 三个 memo、11 个 per-draw scratch vector。
|
||||
- 5 个 manager:`VkBufferManager`(`VkBufferResource` 二级 twin + transient arena + 延迟释放)、`VkTextureManager`(3504 行,`TextureIdentity{ptr, lifetimeId}` 键的节点式 map + 5 类 view 缓存 + 版本影子)、`VkRenderPassManager`(render pass 缓存 + renderbuffer twin + `m_rpFast` 快门)、`VkSamplerManager`、`VkClearManager`。
|
||||
- 3 个 factory:`PipelineFactory`、`ProgramFactory`(带 `m_cacheStructureEpoch`)、`VertexInputStateFactory`(带 `m_evictionEpoch`)。
|
||||
- `UniformManager`(描述符池 + 5 个 memo + 5 个 scratch)、`FrameContext`(frames in flight)、`SwapchainObject`。
|
||||
|
||||
**结论:两个 backend 都已经是完整的、贴着各自 API 的状态机。** 上面**没有一样东西需要在方案 B 里删除或重写**——需要改的只是它们**怎么知道**这些事实(从"每 draw 把 `GLContext` 拉出来自己推导"改成"被告知"),以及它们的 memo **用什么做键**(从裸指针 + 回绕 `Uint16` 改成 `{slot, gen}`)。
|
||||
|
||||
### 2.3 pull 模型的读点分类:A/B/C/D/E 五类
|
||||
|
||||
对 290 个 `pGLContext->` 读点逐个分类(D 与 B 有重叠,因为身份读通常同时是翻译输入):
|
||||
|
||||
| 类 | 含义 | DirectGLES | DirectVulkan | 合计 | 占比 |
|
||||
|---|---|---|---|---|---|
|
||||
| **A** | 只为**探测变化**:读一个版本号,与 backend 自己已经镜像的值比较 | ~21 | ~14 | **~35** | 12% |
|
||||
| **B** | **翻译输入**:每次都要读的值,backend 根本没有镜像 | ~88 | ~128 | **~216** | 74% |
|
||||
| **C** | 瞬时 draw 参数 | ~2 | ~2 | ~4 | 1% |
|
||||
| **D** | **身份 / 缓存键**(与 B 重叠计) | ~24 | ~24 | ~48 | — |
|
||||
| **E** | 数据字节(经 `pGLContext` 本身的只有 XFB CPU 计数两处) | 1 | 2 | 3 | 1% |
|
||||
| **写** | `RecordError` 6 + `InvalidateCompileEnv` 2 | 2 | 6 | 8 | 3% |
|
||||
|
||||
**这张表是整个设计里最重要的一张,它否定了两种直觉方案:**
|
||||
|
||||
- **"bump 一个版本让 server 自己拉"行不通。** 只有 12% 是 A 类。74% 是 B 类:值本身必须过去。一个只传失效信号的接口会在 IPC 上退化成今天的 pull 模型,而在 monolith 里退化成今天的样子加一层间接。
|
||||
- **两个 backend 想要的推送粒度不同,但可以被同一个接口满足。** Espryt 持有逐字节 `RenderStateParameters` 镜像并做三段 memcmp(A 类带 B 类回退);Magma **没有任何镜像**,它按 `GetPipelineStateVersion()` 缓存一个**值哈希**(`VulkanRenderer.cpp:4982-4993`),然后在 payload 构建器里把 ~40 个字段再读一遍(`:5155-5200`)——纯 B 类。**整块 blob 同时满足两者**:Espryt 的 memcmp 继续工作(它拿到的还是那个结构体的引用),Magma 继续算它的哈希。这就是 D-B1 的第二个理由。
|
||||
|
||||
另一个角度的统计:1997 个前端 getter 调用点里,**89 个是纯版本/序号读(A 类)**——这些在推送模型里**根本不过线**,因为推送调用本身就是变化信号;**72 个是数据字节读(E 类)**,全部在 §5.7 处理;**38 个是 `GetLifetimeId()` 身份读(D 类)**,全部变成 handle。
|
||||
|
||||
### 2.4 pull 模型里 293 之外的 58 行:迁移机制必须显式处理的缺口
|
||||
|
||||
前三份候选设计都提出"机械 `sed`:`MG_State::pGLContext->` → 宏",覆盖 293 处,**但都没有交代剩下的 58 行非箭头用法**。实测分类:
|
||||
|
||||
| 形态 | 数量 | 例子 | 处理 |
|
||||
|---|---|---|---|
|
||||
| `MOBILEGL_ASSERT(MG_State::pGLContext, ...)` 真值判定 | ~40 | `DirectVulkan.cpp:347-1108` 密集区、`UniformManager.cpp:811-1967` 9 处 | **直接删除**:MGPipe 下没有 `GLContext`,assert 的对象不存在;替换成对 `PipeInputs` 已填位的 assert(由 §6.2 的 poison mask 自动提供) |
|
||||
| `if (MG_State::pGLContext)` 空守卫 | ~10 | `Managers.cpp:3608, 3737, 3808, 4663, 8678`、`BackendObject_DirectVulkan.cpp:388, 788` | 删除守卫,改为读对应的 `PipeInputs` 字段(永远有效) |
|
||||
| `MG_State::pGLContext != nullptr ? A : B` 三元 | 3 | `Managers.cpp:7120, 7128, 7131`(patch 参数,位于 transpile 路径内) | 由 `set_patch_state` 覆盖,三元塌成直接读 |
|
||||
| `MG_State::pGLContext.get()` 裸指针捕获 | 1 | `DirectGLES.cpp:146` | **`sed` 完全抓不到**,必须手改 |
|
||||
| `!= nullptr` 条件 | 2 | `VulkanRenderer.cpp:11150, 12649` | 同空守卫 |
|
||||
| 注释 | 1 | `VertexInputStateFactory.h:133` | 改写措辞 |
|
||||
|
||||
**因此:纯度门 grep 的是 `pGLContext`,不是 `pGLContext->`**,且 P1 的机械替换步骤必须把这 58 行列成显式清单逐条转换(见 §6.2 与 §11 的 P1 交付物)。
|
||||
|
||||
### 2.5 pull 模型为了弥补"没有接口"而付的代价:~550 行 per-draw 失效发现机制
|
||||
|
||||
这些代码存在的唯一理由是 backend 必须**自己发现**状态变了,而且它们每 draw 都跑:
|
||||
|
||||
| 机制 | 位置 | 行数 | 为什么存在 |
|
||||
|---|---|---|---|
|
||||
| `UnitBindingsSnapshot` / `CaptureUnitBindings` / `UnitBindingsUnchanged` / `CurrentUnitBindingsEpoch` / `UnitTextureSyncEntry` / `PairingsIntact` + 8 个支撑全局 | `DirectGLES.cpp:1372-1489` | ~115 | `GetTextureBindGeneration()` 在**冗余重绑**时也 bump(26.2 在每次纹理单元切换前后重绑同一个 sampler),所以计数器不可信,必须走查 owner 相等性 |
|
||||
| `TwinLookupMemo` ×3(4096+256+64 槽 ≈ 140KiB)+ `OwnerEquals` | `DirectGLES.cpp:62-131` | ~75 | 让 `SharedPtr` 身份查表在 draw path 上够快 |
|
||||
| `g_fbSlotCache` + `GetFramebufferBindingSlotFast` | `DirectGLES.cpp:139-155` | ~17 | 注释:前端 getter 每次调用线性扫 slot 数组 |
|
||||
| `StateBackendObjectRegistry::CollectGarbage` ×6 | `Managers.h:353-390` | ~40×1 | **没有任何东西告诉 backend 一个 GL 对象被删除了** |
|
||||
| `m_convertedVertexStreams` 的 `SharedPtr<const BufferObject> sourcePin` | `VulkanRenderer.h:1124-1127` | — | **纯粹**为了防地址复用而持有一个强引用 |
|
||||
| `UniformManager` 的 8 类占位 `TextureObject` 构造 | `UniformManager.cpp:161-181, 1416-1500, 1624-1634` | ~120 | 只是为了让"未绑定单元"复用 `SyncTextureAndGetDescriptor(ITextureObject&)` 这个签名 |
|
||||
| `SetupDrawSnapshot` 的 `sampledContentSum`/`sampledParamsSum` 与 ~14 个探测字段 | `VulkanRenderer.h:975-1000`、`.cpp:6249-6250, 6478-6483` | — | 用**有损的版本号求和**代替"有没有变" |
|
||||
| `g_broadcastMemo*` + fragColor 重推导 workaround | `DirectGLES.cpp:2669-2732` | ~60 | FBO sync 与 program sync 之间的排序 hazard |
|
||||
| `VkTextureManager::PruneDeadTextures` 的 `WeakPtr::expired()` GC | `VkTextureManager.cpp:1694-1720` | — | 同 registry GC |
|
||||
|
||||
**这些全部在 MGPipe 下删除**,因为推送调用**就是**变化信号,`resource_destroy` **就是**删除信号,`{slot, gen}` **就是**身份。
|
||||
|
||||
### 2.6 21 个 D 类身份 memo:它们各自守什么,以及为什么 `{slot, gen}` 能等价替换
|
||||
|
||||
统一事实:**每一个进入 memo 键的版本计数器要么是回绕的 `Uint16`,要么根本不会被它真正害怕的那个 mutation bump。** `BindingSlot::m_version`(`MG_Util/Types.h:197`)、`FramebufferObject::m_objectVersion`(`:183`)、`SamplerObject::m_version`(`:551`)、`RenderStateParameters` 版本(`RenderState.h:522`)、`TextureObjectBase::m_textureParamsVersion`(`:203`)全部回绕。**身份比较是堵住回绕洞的那块补丁。** 完整的 21 条重键表在 §4.7;这里只点三条最有教育意义的:
|
||||
|
||||
- **D3 `UnitTextureSyncEntry` + `PairingsIntact`**(`DirectGLES.cpp:1441-1481`):注释写明它存在是因为"一次不经过 bind generation 的 slot 交换(DSA by-name 模拟以前就会静默交换一个 slot)会让每个键都匹配,而借来的 slot 指向另一张纹理,replay 于是会**用纹理 B 的前端状态驱动纹理 A 的后端 twin**——用 B 的形状重新指定 A 的后端存储并毁掉 A 的内容"。**这是整份调研里最强的"支持推送接口"的论据**:这一整类 bug 只在"client 能改一个绑定而不移动任何计数器"时才存在。推送之后 server 从不重读 slot,它被告知 `set_sampler_views(...)`——前提是**每一条会改绑定的前端路径都发消息**。审计义务从"哪些读需要守卫"变成"哪些 mutator 必须发消息",由 §10.3 的 verify 模式与 poison mask 强制。
|
||||
- **D11 `VertexInputStateFactory::ComputeHash`**(`VertexInputStateFactory.cpp:38-49`):注释是一份 postmortem——"地址会被分配器复用,所以一个删了又建的 buffer 会重现它;配上逐字节相同的属性布局就重现了**整个** content hash……一个已销毁 buffer 的 GPU 切片被绑给了它的后继者的 draw,这就是一次 transform feedback 捕获拿回一个死 VAO 的顶点数据(0,0,0,1……)的原因"。**所以 `gen` 必须被混进 server 侧的每一个 content hash,而不只是被比较。**
|
||||
- **D18 `VkRenderPassManager::m_renderbufferResources` / `VkTextureManager::m_textureResources` 用节点式 `std::unordered_map` 而不是本项目开放寻址的 `UnorderedMap`**(postmortem 在 `VkRenderPassManager.h:375-397`):因为调用方会跨后续查表缓存 `RenderbufferResource*`/`TextureResource*`,一次扩表搬迁曾让 `BlitFramebuffer` 静默停在"source image layout is undefined"。**这一条在重键表里被显式标为 UNCHANGED**,并进 review checklist——`ska` 的 erase-shift 让这个 hazard 更糟而不是成为历史,而"把容器优化回去"正是一次大重构最容易犯的错。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与方案 A(replica `GLContext`)的逐项对比
|
||||
|
||||
> 方案 A = `../MobileGL-disagg/docs/Disaggregated/PLAN.md`(feat/disaggregated@8b31de2f)。阶段天数逐项相加 = **77 天**。
|
||||
|
||||
| 维度 | 方案 A(replica) | 方案 B(MGPipe) | 判定 |
|
||||
|---|---|---|---|
|
||||
| **边界清晰度** | 边界**就是** replica:server 侧跑一份真 `GLContext`,backend 的 293 次拉取原样成立。没有写下来的契约,也无法写——"边界"等于"整个 `MG_State` 的语义"。新增 backend 必须先学会 186 个前端 getter 与 17 个 mutator 族 | 一份显式函数表(~72 项)+ 一份 POD payload 表 + `PipeCalls.def` 单一真相源。新增 backend 只实现两张表。`MG_Backend` 的 `MG_State` include 从 50 行 / 18 个头文件收缩到一张共享**值**头白名单 | **B 完胜**,这正是用户提出的目标 |
|
||||
| **状态副本** | 一份完整 `GLContext` 对象图 + 每个 <16MiB buffer 一份 `PipeResource` + 每个纹理 level 一份 `MipmapStorage` + server 侧 `MG_State`/`MG_Impl`/`MG_Util`(含 glslang ~43MB 文本页) | **零副本**。server 侧只有 slot 数组里的 POD 记录 + backend 自己本来就有的 twin/ring/pool | **B 完胜** |
|
||||
| **CPU 工作量** | `PLAN.md` §10 自承:"这套遍历**每 draw 跑两次**"——client 的 `WireMirror` 一次、server 未改动的 `PrepareForDraw` 一次,外加编解码。最坏情形 `CurrentUnitBindingsEpoch` 在两侧各退化成对每个 touched unit 的 owner 全走查。全部性能主张押在"两半落在两个都快的核上" | 遍历**搬走**而不是翻倍:client 做一次 dirty word 比较 + N 次 `set_*`(稳态 N=1-3,且 CSO 内容寻址让重复状态 N=0),server 侧删掉 ~550 行失效发现机制。**但这是主张,不是测量**——树里没有任何 per-frame 字节或调用度量,所以 P0 落计数器、P2 出第一个数字 | **B 理论上更好,未证实**。两者都必须以逐线程 CPU 时间为准,不是墙钟帧时 |
|
||||
| **内存** | `PLAN.md` R14 自估 **可达 ~450MiB 新增**。缓解措施是"优先推进 §6.4 方案 B(replica 采纳 client shadow)"——一个被它自己标为"激进、需额外设计"并推迟到 P6 的可选项 | 传输段 ~48MiB + POD 记录 + 可选 ≤32MiB 纹素保留 LRU ≈ **+50-60MiB**。无需任何额外设计 | **B 完胜**。在一个头条战果是"省 400MB"、有 LMK 屠杀记忆的项目里,这是最难辩护的一条 |
|
||||
| **Roundtrip** | 稳态零(除回读/阻塞 query/分配 ack/present credit) | 稳态零(同上),**外加**一个新类:server 发起的纹理重铸拉取。三条缓解 + 专门的门 + 逐用例计数器(§7.5、§9.3) | **A 略优**,但差距被缓解措施压到"实测发布"而非"声称为零" |
|
||||
| **改造量** | backend **一行不改**;改的是 `MG_Backend/Init.cpp:48-70` 一个分支 + 一份 `WireMirror` + 一份 applier + 两个代码生成器 | backend 改 293 个读点 + 58 行非箭头用法 + 95 个写回点 + ~66 个 memo 族重键 + 两处 `MG_State` 类型内部用法重写(Magma 的 8 类占位纹理、两个内部 shader 的 `ShaderObject`/`ProgramObject`) | **A 完胜** |
|
||||
| **迁移期风险** | 风险**集中在末端**且**难以测试**:replica 的行为漂移编译通过、多数内容渲染正确,守卫只看签名。`PLAN.md` 自己的 R1 承认症状是"错误像素或错误查询结果,不是崩溃" | 风险**分布在 ~13 个阶段**,每阶段可二分、有现成测试套件作门、可用 `MOBILEGL_PIPE_PUSH` 位图在同一份二进制里 A/B 回退,且有**逐 draw 逐字段的语义比对**(两套模型活在同一地址空间才可能)。但它**改动 monolith**,因此能回归出货产品 | **B 的正确性风险更低,A 的产品风险更低**。这是本对比里唯一真正的取舍 |
|
||||
| **到首帧时间** | **~第 15 天**(P0 5 + P1a 6 + P1b 4)跨进程首帧 | **~第 68 天** inproc 首帧、**~第 73 天** 跨进程首帧,且那一帧是**缩减路径**(emulation 在 P8 之前于 split 下 Fatal);全功能在 P8 之后。最早可见里程碑是**第 16 天**的 verify harness 全绿(零产品风险,但不是一帧画面) | **A 完胜(4-5 倍)** |
|
||||
| **长期价值** | 拆分达成;monolith 不变;边界仍未定义(replica **就是**边界)。维护成本**永久**:一份手写状态模型与 `MG_State` 长期锁步 | 边界被写下来、被生成、被测试。第三个 backend、shader 缓存服务、record/replay 层、校验层、真正的第二个 context 都变得可行。成本**一次性** | **B 完胜** |
|
||||
| **对 monolith 的收益** | 零(按设计如此,这是它最强的性质) | ~550 行 per-draw 失效机制删除;复用地址 ABA 一类不可表达;FBO→program 排序 hazard 消失(`DirectGLES.cpp:2712-2732` 的 workaround 删除);`pDefaultFramebufferInfo` 分层倒置消失;`inproc` = 渲染线程杠杆;顺带修两个潜伏 bug(`m_xfbCounterSlotByObject` 用裸 GL name 做键、`VulkanRenderer.cpp:11136-11146`;`RenderbufferObject` 缺 `GetLifetimeId()`);顺带暴露一个死能力(`FramebufferSrgb`/`DepthClamp` 无存储,`RenderState.cpp:380/428-429`,6 个 backend 读点恒为 false) | **B 完胜** |
|
||||
|
||||
### 3.1 方案 A 里被证明**不可能**、而不只是"不理想"的两件事
|
||||
|
||||
1. **`RecProgramLinkOp`(server 从源码重新 link)**。`ProgramObject.h:11 → ShaderObject.h:12 → ShaderCompileTask.h`,`ShaderObject.h:146` 返回 `SharedPtr<glslang::TShader>`,`ProgramObject.h:14 → SpvcSession.h`。链接真 `ProgramObject` 就链接 glslang。方案 A 里它成立(server 反正链接完整 `MG_State`),方案 B 里它不成立,所以 `ProgramPublish` 第一天上、`MOBILEGL_IPC_PROGRAM=publish|relink` 开关消失、阶段 P5 整个消失(6 天回收),而它的副产品(DirectVulkan 内部 shader 烘焙)**升级为 P7 的前置条件**,`nm -D | grep glslang` 为空成为该阶段的验收判据。
|
||||
2. **方案 A 的字节一致门在方案 B 里不成立**(D-B5)。这不是方案 B 的缺陷论证,是它必须公开承认的成本。
|
||||
|
||||
### 3.2 方案 B 复用方案 A 的比例
|
||||
|
||||
`PLAN.md` 的 §6(数据面)、§7(控制面)、§8(roundtrip 机制)、§9(present 与帧节奏)、§10(线程模型)、§11(EGL/窗口/进程生命周期)、§12 的第 1-3 层(编译期折叠、唯一 hook 点、allocator 包裹)、§12.4(运行时选择)、§13(构建布局)、§14(对 `Feat/CS-Delta-IPC` 的复用清单)**按体量算是全文的大部分,而且与状态模型无关**。方案 B 原样继承它们,逐条对照见 §8 与 §14。**因此"选 B 不选 A"并不浪费传输侧的设计投资**——那部分投资两条路都要付,且已经过对抗性评审。
|
||||
|
||||
### 3.3 一句话决策规则
|
||||
|
||||
- 目标是**这个季度出一个能跑的拆分**,或者拆分的价值主要按"进程隔离/崩溃隔离"计算 → **选方案 A**。
|
||||
- 目标是**用户提出的那个架构**(backend 拥有自己的状态机 + 统一接口解耦) → **选方案 B**,并按 §0.6 的 16 天对冲路径起步,第 24 天用真数字做 GO/NO-GO。
|
||||
- **不要**试图先做 A 再做 B。A 的 replica 一旦上线,它就成为"边界"的既成事实,而 B 的第一步(backend 停止读 `pGLContext`)会同时作废 A 的全部 applier 代码——两条路的 backend 侧改造是互斥的,共享的只有传输层。
|
||||
@@ -0,0 +1,456 @@
|
||||
## 4. 接口设计:MGPipe
|
||||
|
||||
### 4.1 文件布局与单一真相源
|
||||
|
||||
```
|
||||
MobileGL/MG_Pipe/ # client 与 server 都 include;不链接 MG_State,不链接 MG_Impl
|
||||
PipeCalls.def # X-macro:调用目录的唯一真相源,一行一个调用
|
||||
MGPipe.h # 由 .def 生成的两张函数表 + 手写 payload 声明
|
||||
MGPipeTypes.h # 全部 payload POD(trivially copyable,逐个 static_assert)
|
||||
MGPipeHandles.h # MGPipeHandle、MGPipeKind、保留 handle、slot 分配契约
|
||||
MGPipeHostSpan.h # 唯一一个"形状随传输而变"的访问器(§4.5.7)
|
||||
MGPipeCallbacks.h # 反向通道(事件/回复)的函数表,见 §7
|
||||
generated/PipeTables.inc # G1:两张函数表
|
||||
generated/PipeThunks.inc # G2:monolith 直调 thunk
|
||||
generated/PipeWire.inc # G3:wire 记录 + static_assert + 运行期边界检查 + applier switch
|
||||
generated/PipeVerify.inc # G4:逐字段影子比对器
|
||||
generated/PipeFilled.inc # G5:written-once 位图与 poison 断言
|
||||
generated/PipeCoverage.inc # G6:477 读点 → MGPipe 调用的映射表(CI 重生成 + git diff --exit-code)
|
||||
MobileGL/MG_Impl/Pipe/
|
||||
Tracker.{h,cpp} # st_validate_state 类比物
|
||||
SlotAllocator.{h,cpp} CsoCache.{h,cpp}
|
||||
HostResolve.cpp # 客户端数组界限 / 索引扫描 / restart 重写 / indirect count 解析
|
||||
CompositeResolver.cpp # program pipeline 合成体的 handle 生命周期
|
||||
MobileGL/MG_Backend/MGPipe/
|
||||
PipeInputs.h # backend 私有的"被推送状态"块(迁移载体,§6.2)
|
||||
MGPipeImpl_DirectGLES.cpp # 用 Espryt 的函数填 MGPipeContext
|
||||
MGPipeImpl_DirectVulkan.cpp # 用 Magma 的函数填 MGPipeContext
|
||||
MobileGL/MG_Remote/ # 传输,继承 PLAN.md §13(删掉 Server/ReplicaContext.*)
|
||||
Server/PipeApplier.cpp Server/PipeObjectTables.{h,cpp}
|
||||
scripts/gen_pipe.py # 跑 G1..G6
|
||||
```
|
||||
|
||||
`PipeCalls.def` 一行一个调用,**六个生成器**消费它:
|
||||
|
||||
```cpp
|
||||
// MG_Pipe/PipeCalls.def — X(Name, PayloadStruct, Class, Flags)
|
||||
// Class : kScreen | kCtxCso | kCtxState | kCtxObject | kCtxVerb | kCtxQuery
|
||||
// Flags : kNone | kNeedsAck | kHasBlob | kVarTail | kHostSpan | kReplySlot | kOptional
|
||||
#define MGP_CALL_LIST(X) \
|
||||
/* ---- screen ---- */ \
|
||||
X(GetCaps, MGPCaps, kScreen, kReplySlot) \
|
||||
X(ResourceCreate, MGPResourceDesc, kScreen, kNone) \
|
||||
X(ResourceRespecify, MGPResourceDesc, kScreen, kNone) \
|
||||
X(ResourceDestroy, MGPHandleOnly, kScreen, kNone) \
|
||||
X(MapPersistent, MGPHandleOnly, kScreen, kReplySlot|kOptional) \
|
||||
/* ---- CSO ---- */ \
|
||||
X(CreateRenderState, MGPRenderStateDesc, kCtxCso, kHasBlob) \
|
||||
X(BindRenderState, MGPBindRenderState, kCtxCso, kNone) \
|
||||
/* ---- state ---- */ \
|
||||
X(SetFramebufferState, MGPFramebufferState, kCtxState, kNone) \
|
||||
X(SetSamplerViews, MGPSamplerViews, kCtxState, kVarTail) \
|
||||
/* ---- verb ---- */ \
|
||||
X(DrawVbo, MGPDrawInfo, kCtxVerb, kHostSpan|kVarTail) \
|
||||
X(ResourceSubData, MGPSubData, kCtxObject,kHasBlob) \
|
||||
X(RenderbufferStorage, MGPRbStorage, kCtxObject,kNeedsAck) \
|
||||
/* … 共约 72 项,完整目录见 §4.4 与 part4 的速查表 … */
|
||||
```
|
||||
|
||||
| 生成器 | 产物 | 替代/新增 |
|
||||
|---|---|---|
|
||||
| **G1** | `struct MGPipeScreen { … };` / `struct MGPipeContext { void (*DrawVbo)(const MGPDrawInfo*, …); … };` | 替代今天手写的 `GLFunctionsTable` |
|
||||
| **G2** | monolith thunk:`inline void MGP_DrawVbo(const MGPDrawInfo* p){ gPipeCtx.DrawVbo(p); }` — 一次**已经在付**的间接调用 | 替代 `gBackendFunctionsTable.GL.*`(89 个 MG_Impl 站点改名即可) |
|
||||
| **G3** | wire 记录结构 + 每种一条 `static_assert(sizeof==N)` + applier 分发前的运行期边界检查 → `Fatal{ProtocolCorruption}` | 继承并扩展 `PLAN.md` §6.3 的 `Records.def` 机制到**全部**调用 |
|
||||
| **G4** | `MOBILEGL_PIPE_VERIFY` 的逐字段比对器:对每个 `kCtxState`/`kCtxCso` 调用生成 `Compare(pushed, snapshot, &firstDivergentFieldName)` | **新增**:这是每份候选设计都被判缺失的语义绊线 |
|
||||
| **G5** | `PipeInputs::m_filledMask` 的位定义 + 读未填字段时的 `Fatal{UnmigratedPipeInput, "<field>"}` | **新增**:完整性的**运行期/构建期**绊线,不只是测试绊线 |
|
||||
| **G6** | 477 行读点清单 → MGPipe 调用的映射,CI 重生成并 `git diff --exit-code`,0 UNMAPPED | 改造自 `Feat/CS-Delta-IPC` 的 `extract_backend_read_inventory.py`(删掉制造"0 UNMAPPED"的前缀兜底规则) |
|
||||
|
||||
**G4 与 G5 从同一份 `.def` 生成,因此不可能与调用目录漂移。** 这是把"完整性只有测试绊线、没有构建绊线"这条历史评审结论一次性关掉的机制。
|
||||
|
||||
**接口表用函数指针 struct,不用虚基类。** 三条本仓库自己的理由:(1) 边界今天**就是**函数指针 struct,装在 `MG_Backend/Init.cpp:44` 的唯一 hook 点上;(2) `nullptr` 项**已经**表示"未实现,前端回退",写进 `BackendObject.h:212-215` 与 `:265-269`,而 DirectVulkan 确实留空 8 项——**一个 null `set_*` 恰好就是"这个子系统还没迁移,继续拉取"**,这是 strangler 的原生表达,纯虚类只能用说谎的 stub override 来模拟;(3) `MG_Test` 已经会替换这张表做 mock。稀有的 EGL/caps 面继续留在 `pActiveBackendObject` 的虚函数上(20 个方法,`BackendObject.h:543-568, 597-598`),它们本来就罕见。
|
||||
|
||||
### 4.2 对象模型
|
||||
|
||||
#### 4.2.1 Handle
|
||||
|
||||
```cpp
|
||||
// MG_Pipe/MGPipeHandles.h
|
||||
enum class MGPipeKind : Uint8 {
|
||||
Buffer=1, Texture, Renderbuffer, Framebuffer, Xfb,
|
||||
RenderStateCso, VertexElementsCso, SamplerCso, SamplerViewCso, ShaderCso,
|
||||
Fence, Query, Context
|
||||
};
|
||||
struct MGPipeHandle { // 8 B,POD,可哈希,按值传寄存器对
|
||||
Uint32 slot; // 按 kind 稠密分配(client 侧 SlotAllocator)
|
||||
Uint32 gen; // slot 复用时 ++;client 侧维护
|
||||
};
|
||||
```
|
||||
|
||||
- **slot 稠密、按 kind 分配**。这一条是把 server 的对象表从哈希表变成**数组**的唯一途径,也是删掉 `TwinLookupMemo` 的斐波那契散列 + owner 相等性检查的原因。`SlotAllocator` 是一个 free-list + 高水位,与 `IndexGenerator` 无关(后者的 LIFO 复用正是问题本身)。
|
||||
- **`gen` 只在 slot 复用时 ++,不是每次 respecify 都 ++**。`{slot, gen}` 在**同一个 slot 被复用 2³² 次**之前唯一。文档写明这条上界,debug 构建断言它。
|
||||
- **GL name 只在 `resource_create` 的 payload 里出现一次,纯诊断用途**,永不做身份、永不进任何 memo 键、永不进任何 content hash。
|
||||
- **`GetLifetimeId()` 留在 client 侧**作为 tracker 自己的身份(它已经是永不复用的),不过线。client 侧维护 `lifetimeId → slot` 映射。
|
||||
- **保留 handle**:`{0,0}` = null;`{slot=0, gen=1, kind=Framebuffer}` = 默认帧缓冲(这一条退役 `DirectGLES.cpp:1917, 2838, 2867, 9675` 四处对 `pDefaultFramebufferInfo->defaultFBO` 的身份比较);`ShaderCso` 的高 1/16 slot 段保留给 **program pipeline 合成体**(§5.6),因为它们没有 GL name。
|
||||
|
||||
#### 4.2.2 两种 generation,严格分开
|
||||
|
||||
| | 拥有者 | 回答什么 | 是否过线 |
|
||||
|---|---|---|---|
|
||||
| **身份**(`MGPipeHandle::gen`) | client | "还是同一个 GL 对象吗?" | 是,随每个 handle |
|
||||
| **`MGGen`**(server 纪元) | **server** | "**我自己**是不是重铸了驱动对象 / 冲了自己的缓存?" | **client→server 永不;server→client 只以纹理拉取请求的形式出现**(§7.5) |
|
||||
|
||||
`MGGen` 是 §0.3 推论 3 那 12 个计数器的 wire 名字。**接口规范条款:任何 MGPipe 调用都不得要求 client 提供或知晓 `MGGen`。** 这条是"server 拥有自己的状态机"的可执行定义。反过来也是规范:**client 侧的版本计数器永远不是新鲜度的唯一证明**——每一个回绕的 `Uint16`(§2.6)在过线时要么被加宽到 32 位、要么与 `{slot, gen}` 同行。
|
||||
|
||||
#### 4.2.3 CSO vs 可变对象
|
||||
|
||||
| 类别 | 形态 | 因为 backend 今天就是这么缓存的 |
|
||||
|---|---|---|
|
||||
| `VertexElementsCso` | `create/bind/delete` | `VertexInputStateFactory::m_cache`,键正是 `VertexAttribute` 那组字段的 content hash(`VertexInputStateFactory.cpp:19-50`) |
|
||||
| `SamplerCso` | `create/bind/delete` | `VkSamplerManager::m_samplers`(`VkSamplerManager.h:104-117`);Espryt 的 `BackendSamplerObject`(`Managers.h:1808-1824`) |
|
||||
| `SamplerViewCso` | `create/delete` + 由 `set_sampler_views` 绑定 | `TextureResource::{perMipViews, perMipSampledViews, attachmentViews, alternateSampledViews, storageImageViews}`(`VkTextureManager.h:173-370`);Espryt 的 `SyncTextureViewToBackend`(`Managers.cpp:3616-3707`) |
|
||||
| `ShaderCso` | `create/bind/delete` + **server 侧惰性特化**(D-B2) | `ProgramFactory::m_cache`(`ProgramFactory.h:614-642`);`BackendProgramObjectImpl`(`Managers.h:1473-1725`) |
|
||||
| `RenderStateCso` | `create/bind/delete`,**payload 是整块 blob**(D-B1) | Espryt 的值镜像 + 三段 memcmp;Magma 的 `ComputePipelineStateHash` 单次 bulk fetch |
|
||||
| Buffer / Texture / Renderbuffer | `create` / `respecify` / `subdata` / `destroy`(可变,带存储) | `GLESBufferResource`、`BackendTextureObject`、`VkBufferResource`、`TextureResource` |
|
||||
| Framebuffer / Xfb | per-context 身份 + `set_*` payload(不带存储) | `BackendFramebufferObject`、`m_xfbCounterSlotByObject` |
|
||||
|
||||
**CSO 在 client 侧内容寻址**(Mesa `cso_context`/`cso_cache` 的先例):`MG_Impl/Pipe/CsoCache` 每类一张 `ska::flat_hash_map<Uint64 xxHash, MGPipeHandle>`,容量上限(blend/DS/rasterizer 合并后的 render-state 64、vertex-elements 1024、sampler 256、sampler-view 4096、shader 不设上限跟随 `ProgramObject` 生命周期),LRU 淘汰时发 `delete_*_state`。**内容寻址的一个直接收益**:两个不同 program 设置了相同的 blend 状态时,server 侧**零状态转换**。
|
||||
|
||||
**任何 `create_*` 都不返回 server 铸造的 handle。** 这是对 gallium 的**有意偏离**(gallium 的 `create_*_state` 返回 driver 指针),也是这份目录能在**零创建 round trip** 下远程化的根本原因。今天的 `BackendSyncHandle`/`BackendQueryHandle = void*`(`BackendObject.h:110, 115`)随之变成 `MGPipeHandle`——fence 与 query 需要的唯一改动。
|
||||
|
||||
### 4.3 `MGPipeScreen` 与 `MGPipeContext`
|
||||
|
||||
GL 的 share-group 规则本身就是分界,而 MobileGL 的容器归属**已经**吻合:
|
||||
|
||||
| `MGPipeScreen`(share group) | `MGPipeContext` |
|
||||
|---|---|
|
||||
| caps、format 能力表、renderer 字符串;buffer / texture / renderbuffer / sampler / shader 的对象命名空间;fence | 全部 `set_*`、全部 CSO 绑定、VAO / FBO / XFB 对象 / query 的命名空间、命令流、present |
|
||||
|
||||
v1 只有一个 screen、一个 context、一条 flow(`shareCtx` 是死状态,§1.2)。**但两张表从第一天就分开**,因为事后拆分意味着给每个记录种类重新编号。两处必须重新归类的事实:`GetTextureBindGeneration()` 与 `GetSamplingResolutionGeneration()`(`Core.h:130, 136`)是**绑定**(context)事实却住在 share-group 作用域的 `TextureState` 里;`GetTextureContextId()`(`:143`)已经存在正是为了在 context 重建时区分它们——它直接**就是** context handle。
|
||||
|
||||
### 4.4 完整调用目录
|
||||
|
||||
> 完整速查表(含 payload 大小与 flags)在 part4 的附录。这里给出结构与每项的来源/取代关系。
|
||||
|
||||
#### 4.4.1 `MGPipeScreen`(14 项)
|
||||
|
||||
| 调用 | payload | 取代 |
|
||||
|---|---|---|
|
||||
| `get_caps(MGPCaps* out)` | `DynamicBackendParameters`(`BackendObject.h:302-522`,~90 标量,平坦 POD)+ `RendererInfo` + `FormatCapabilityCache`(`:88-99`,14 个能力位 × 全部 internalformat × 12 target 的稠密表 + 每格 `SampleCounts`)+ `callMask` | 40 个 `pActiveBackendObject->` 站点、89 个 caps 读点 |
|
||||
| `resource_create(h, const MGPResourceDesc*)` | §4.5.1 | buffer/texture/renderbuffer 的创建 |
|
||||
| `resource_respecify(h, const MGPResourceDesc*)` | 同上 | `BufferBackendOps::Respecify`(`BufferObject.h:80`)泛化;server 自己按 busy 跟踪决定 swap-vs-in-place |
|
||||
| `resource_destroy(h)` | handle | `OnDestroy`(`:101`)+ **两个 `WeakPtr` GC 扫描**(`Managers.h:353-390`、`VkTextureManager.cpp:1694-1720`)。server 的 pooling / 延迟释放(`Managers.cpp:1271-1300`、`VkBufferManager::OnResourceDestroyed`)原样保留 |
|
||||
| `map_persistent(h) → MGPMapResult` / `unmap_persistent(h)` | — | `AcquirePersistentMap`(`:112`)。**改造期不碰**(D-B4) |
|
||||
| `fence_create/status/wait/destroy` | handle (+timeout) | `FenceSync`…`GetSyncStatus`(`:220-224`)。两值契约(`:243-249` "false = 还没好,留着 handle")**逐字保留** |
|
||||
| `query_create/begin/end/available/result/destroy` | handle + kind | `BackendObject.h:230-256` |
|
||||
| EGL 生命周期 8 项 | 见 `BackendObject.h:548-559` | 原样保留为虚函数(罕见) |
|
||||
|
||||
**`callMask` 取代"槽位是否为 null"这个隐式能力探测**(`GL_Query.cpp:471, 545, 768` 拿 `BeginOcclusionQuery != nullptr` 当能力位)。它同时是 emulation 归属的判据(§5.7):`kCapPrimitiveRestart`、`kCapPrimitiveRestartFixedIndex`、`kCapMultiDraw`、`kCapMultiDrawIndirect`、`kCapMultiDrawIndirectCount`、`kCapViewportArray`、`kCapFloat64VertexAttrib`、`kCapResidentSubData`、`kCapCpuXfbPrimitiveAccounting`、`kCapNeedsHostIndexBytes`、`kCapTimerQuery`、`kCapOcclusionQuery`、`kCapXfbPrimitivesQuery`。
|
||||
|
||||
#### 4.4.2 `MGPipeContext` — CSO(15 项)
|
||||
|
||||
`create/bind/delete` × { `render_state`, `vertex_elements`, `sampler`, `sampler_view`, `shader` }。payload 见 §4.5.2-4.5.5。
|
||||
|
||||
#### 4.4.3 `MGPipeContext` — `set_*`(14 项)
|
||||
|
||||
| 调用 | 取代的拉取点 |
|
||||
|---|---|
|
||||
| `set_framebuffer_state` | `GetFramebufferBindingSlot` ×19、`GetAllAttachmentObjects`、`GetDrawBuffers`、`GetReadBuffer`、4 处 `pDefaultFramebufferInfo` |
|
||||
| `set_vertex_buffers(start, count, const MGPVertexBuffer*)` | VAO binding-point 走查 |
|
||||
| `set_index_buffer(const MGPIndexBuffer*)` | `GetIndexBufferBindingSlot`;**独立调用**——VAO config version 不是它的超集(D5) |
|
||||
| `set_indirect_buffers(drawIndirect, parameter)` | `GetBufferBindingSlot(DrawIndirect/Parameter)` |
|
||||
| `set_sampler_views(stage, start, count, const MGPBoundView*)` | `GetTextureUnitObject` ×19、`GetActiveTextureUnit` ×8、`GetTextureBindGeneration` ×5。**client 侧已解析**(§5.5) |
|
||||
| `bind_sampler_states(stage, start, count, const MGPipeHandle*)` | `TextureUnit.h:394` |
|
||||
| `set_shader_images(start, count, const MGPImageView*)` | `GetImageTextureBinding` ×14;**这一条退役 `ImageUnitFormatsStillMatch`**(`Managers.cpp:6545-6573`) |
|
||||
| `set_shader_buffers(cls, start, count, const MGPBufferRange*, writableMask)` | `GetBufferBindingPoint` ×19、`GetTouchedBufferBindingPointCount` ×2。`cls` ∈ {Uniform, ShaderStorage, AtomicCounter} |
|
||||
| `set_stream_output_targets(count, const MGPBufferRange*, const Uint32* offsets, Uint64 generation)` | XFB 绑定走查 |
|
||||
| `set_global_constants(shaderCso, MGPBlobRef, Uint32 version)` | `MapUBO`/`GetUBOData`/`GetUBOSize`/`GetUBOContentVersion`(§4.6 D6) |
|
||||
| `set_vertex_attrib_defaults(Uint32 mask, const MGPAttribValue*)` | `GetCurrentVertexAttribute` ×2;float/int/uint 视图由 `ClassifyVertexAttribType`(`Core.h:51`)在 client 侧解析 |
|
||||
| `set_pixel_pack_state(const PixelStoreParameters*)` | 6 个 PACK 读点。**没有 unpack 对应项**(§4.6 D5) |
|
||||
| `set_patch_state(Uint32 vertices, const Float outer[4], const Float inner[2])` | `GetPatchVertices`/`…OuterLevel`/`…InnerLevel` ×6。**同时是 shader variant 输入**(`RenderState.h:243-249`) |
|
||||
| `set_draw_program(shaderCso)` / `set_dispatch_program(shaderCso)` | `GetProgramForDraw` ×7、`GetProgramForDispatch` ×3。含 composite(§5.6) |
|
||||
|
||||
**迁移期额外一项(显式临时)**:`set_residual_value_state(MGPBlobRef)`,见 §6.3。它带一个**编译错误式退役绊线**。
|
||||
|
||||
#### 4.4.4 `MGPipeContext` — transfer(12 项)
|
||||
|
||||
`resource_subdata`(buffer + texture 同一形状,**同时携带 union box 与 rect 列表**,§4.5.6)、`resource_flush_range(h, Range1D, Flags<BufferMappingAccessBit>)`(携带应用**真实**的 access flags,`BufferObject.h:94-96`)、`resource_readback(h, off, size, MGPReplySlot)`、`resource_copy_region`、`blit`、`clear`(一条,判别式合并今天的 `Clear` + 4 个 `ClearBuffer*` + 4 个 `ClearNamedFramebuffer*`)、`generate_mipmap(h, target, const MGPMipPlan*)`、`read_pixels(const MGPReadbackInfo*, MGPReplySlot)`、`get_texture_image(...)`、`buffer_subdata_resident(h, off, MGPBlobRef)`(**可为 null**,见下)。
|
||||
|
||||
**`buffer_subdata_resident` 的 per-backend 可选性必须被接口允许,不能抹平。** Espryt 注册它、Magma 故意不注册(`VkBufferManager.cpp:104-111`),差别是 `glBufferSubData` 在活的 coherent map 上的排序语义(`BufferObject.h:84-92` 的 Minecraft 撕裂 postmortem)。表现为 `kCapResidentSubData` 位 + null 项。**统一强制的接口会静默改变 Magma 的行为并发布一个 Minecraft chunk 撕裂。**
|
||||
|
||||
#### 4.4.5 `MGPipeContext` — 命令(4 + 4 + 2 项)
|
||||
|
||||
```cpp
|
||||
void draw_vbo (const MGPDrawInfo*, Uint32 drawIdOffset,
|
||||
const MGPDrawIndirect*, const MGPDrawRange*, Uint numDraws);
|
||||
void launch_grid(const MGPGridInfo*); // + indirect 变体字段
|
||||
void memory_barrier(GLbitfield bits, Bool byRegion);
|
||||
void begin_stream_output(GLenum primitiveMode);
|
||||
void end_stream_output(const MGPXfbAccounting*);
|
||||
void pause_stream_output(); void resume_stream_output();
|
||||
void flush(Uint32 flags); // GL_SYNC_FLUSH_COMMANDS_BIT 语义
|
||||
void present(Uint64 frameSerial); void set_swap_interval(Int interval); // 后者可 null(Magma)
|
||||
```
|
||||
|
||||
**今天 20 个 draw 入口塌成 `draw_vbo` 一条**——这正是 gallium 的合并,而 `MGPDrawRange[]` **就是** `MultiDraw*` 族今天的形状(gallium 的 `pipe_draw_start_count_bias`)。
|
||||
|
||||
#### 4.4.6 显式删除、不移植的项
|
||||
|
||||
- `GetIntegeri_v` / `GetInteger64i_v` / `GetProgramiv`(`BackendObject.h:195-197`)。`DirectGLES.cpp:7264-7386` 的 15 个 case 完全不碰 GL(占 Espryt 124 个读点里的 14 个);Magma 同形(`DirectVulkan.cpp:685, 759`),只有 `GL_COMPUTE_WORK_GROUP_SIZE`(`:790-795`)是真后端答案,进 `MGPCaps`。
|
||||
- `ShaderStorageBlockBinding`(`:207-208`)→ 折进 `MGPProgramDesc` 的反射归档(`LinkArtifacts::shaderStorageBlockBinding` 按**名字**索引,`ProgramObject.h:1325`)。它自己的注释已经说 program interface 由前端回答。
|
||||
- **总规则:server 不回答任何 client 能自己回答的问题;剩下的每个 server 查询都是 async-with-handle,绝不阻塞。**
|
||||
|
||||
### 4.5 关键 payload
|
||||
|
||||
#### 4.5.1 `MGPResourceDesc`(判别式,三种 GL 存储类合一)
|
||||
|
||||
```cpp
|
||||
struct MGPResourceDesc {
|
||||
Uint8 target; // Buffer | Tex1D..TexCubeArray | Tex2DMS.. | Renderbuffer | TexBuffer
|
||||
Uint8 storageKind; // Mipmap | Buffer (== TextureStorageType, TextureEnum.h:61-64)
|
||||
Uint16 bindMask; // VERTEX|INDEX|CONSTANT|SHADER_BUFFER|INDIRECT|SAMPLER|SHADER_IMAGE|
|
||||
// RENDER_TARGET|DEPTH_STENCIL|STREAM_OUTPUT|ATOMIC (== PIPE_BIND_*)
|
||||
Uint32 internalFormat; // GL internalformat,已在前端解析为非压缩后备
|
||||
Uint32 width, height, depth;
|
||||
Uint16 arrayLayers, levels, samples;
|
||||
Uint8 fixedSampleLocations, immutable;
|
||||
Uint32 usage; // BufferUsage
|
||||
Uint32 storageFlags; // glBufferStorage flags
|
||||
Uint8 hasDefinedContent; // NULL-data respecify(orphaning 惯用法)之后为 false,BufferObject.h:216
|
||||
Uint8 imageBindableHint; // client 侧 everImageBound,预防性分配(§7.5(a))
|
||||
Uint8 glNameForDiag[2]; // 仅诊断
|
||||
MGPipeHandle viewOf; // 纹理视图的存储属主(GetViewStorageOwner,TextureObject.h:100)
|
||||
MGPipeHandle bufferForTexBuffer; Uint64 bufOffset, bufSize; // kWholeBuffer = ~0,实时解析
|
||||
};
|
||||
```
|
||||
|
||||
**Renderbuffer 保持独立类,不折进纹理。** 它有自己的 format-capability target 索引(`BackendObject.h:85`)、自己的 `ComponentSizes` 上报(`RenderbufferObject.h:37-43`)、自己的 twin(`Managers.h:1838`)。合并零收益且丢掉一张独立能力表。`bindMask` 让它在**绑定语义**上与纹理统一,这就够了。
|
||||
|
||||
#### 4.5.2 `MGPRenderStateDesc` / `MGPBindRenderState`(D-B1)
|
||||
|
||||
```cpp
|
||||
struct MGPRenderStateDesc { // create:整块,每个唯一状态一次
|
||||
MGPipeHandle cso;
|
||||
Uint8 spanMask; // bit0=head, bit1=blend[], bit2=tail;未命中时只发变化段
|
||||
MGPipeHandle baseCso; // 增量基(spanMask != 0b111 时有效)
|
||||
MGPBlobRef blob; // RenderStateParameters 的对应段
|
||||
};
|
||||
struct MGPBindRenderState { // bind:稳态 12 B
|
||||
MGPipeHandle cso; Uint16 version; Uint16 pipelineVersion;
|
||||
};
|
||||
```
|
||||
段划分**与 `DirectGLES.cpp:2038-2047` 现有的 head/blend/tail 完全一致**,所以两侧对"段"的定义按构造相同。两个版本号都过线(`RenderState.h:522` / `:529`)。
|
||||
|
||||
#### 4.5.3 `MGPVertexElements`
|
||||
|
||||
携带**两个视图,缺一不可**:解析后的 `VertexAttribute[32]`(`VertexArrayObject.h:17-53`)**和** `VertexBufferBindingPoint`(`:58-64`,注意初始 stride 是 **16** 而不是 0,`:61-62`)。`VertexArrayObject.h:22-29` 记录了合并它们的代价:pointer 调用的 stride 0 被解析成 element size,而 binding-model 的 stride 0 意味着每个顶点读**同一个** element,塌成一个害了 `KHR-GL43.vertex_attrib_binding.basic-input-case7/8`。`IsLong` 与 `Type == Float64` **分开携带**(`:34-39`:`glVertexAttribFormat(GL_DOUBLE)` 读 double 转 float,`glVertexAttribLFormat` 保留 64 位,`GL_VERTEX_ATTRIB_ARRAY_LONG` 上报这个区别)。**仅供查询的 `LegacyStride`/`LegacyPointer`(`:51-52`)留在 client,永不过线。**
|
||||
|
||||
#### 4.5.4 `SamplerParameters` 与 `MGPSamplerView`
|
||||
|
||||
`SamplerParameters`(`SamplerObject.h:468-492`)**逐字节原样过线,包括 `borderColorForm`**(`:462-466`):`:455-461` 明说没有它 backend 无法在 `glSamplerParameterIiv` 与 `fv` 之间、或在 `VkBorderColor` 家族之间选择,因为三种表示(`borderColor`/`borderColorI`/`borderColorUI`)**永远都被数值填满**。
|
||||
|
||||
```cpp
|
||||
struct MGPSamplerView { // = pipe_sampler_view
|
||||
MGPipeHandle cso, texture;
|
||||
Uint32 internalFormat; // 别名格式(glTextureView)
|
||||
Uint8 target, depthStencilMode, pad[2];
|
||||
Uint16 minLevel, numLevels, minLayer, numLayers;
|
||||
Uint8 swizzle[4];
|
||||
Uint16 samples; Uint8 fixedSampleLocations, pad2;
|
||||
};
|
||||
```
|
||||
**`glTextureView` 因此从"ES name 重铸特殊路径"(`Managers.cpp:3616-3707`)变成一个普通 view CSO**,这对两个 backend 都是净简化。真正需要保留的区别是 `GetViewStorageOwner()`(`TextureObject.h:96-100`,一个 `SharedPtr`,且**它自己永远不是 view**)——它变成 `resource_create` 的 `viewOf` + server 侧 keep-alive。
|
||||
|
||||
#### 4.5.5 `MGPProgramDesc`(`create_shader_state` 的 payload)
|
||||
|
||||
```cpp
|
||||
struct MGPProgramDesc {
|
||||
MGPipeHandle cso;
|
||||
Uint32 stageMask; // == GetLinkedShaderStages()
|
||||
MGPBlobRef spirv[6]; // GetGeneratedSpirv(),逐 stage,顺序与 GetLinkedShaderSnapshot() 一致
|
||||
MGPBlobRef reflection; // Visit() 归档的 LinkArtifacts + SpirvArtifacts(全结构体)
|
||||
Uint32 globalUboSize; // GetUBOSize()
|
||||
Uint32 reservedNumSamplesOffset;
|
||||
Uint8 spirvStatus, nativeFloat64, pointSizeDemoted, enableSpirvValidation;
|
||||
};
|
||||
```
|
||||
|
||||
反射归档**序列化整个结构体,而不是 backend 今天读的那 ~40 个字段**——这样 backend 新增一次 read 永不需要改协议。机制沿用 `PLAN.md` §6.9 的 `Visit()` + `sizeof` 绊线,但**用途改变**:它不再是"分歧预言机"(没有可分歧的对象),而是**schema 完整性绊线**:
|
||||
|
||||
```cpp
|
||||
// MG_State/GLState/ProgramState/ProgramArtifactsArchive.h
|
||||
template <class Ar> void Visit(Ar& ar, LinkArtifacts& a) { ar(a.writtenUniformLocationBits, /*…全字段…*/); }
|
||||
static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE,
|
||||
"新字段请加进 Visit() 并 bump MGL_LINKARTIFACTS_SIZE");
|
||||
```
|
||||
|
||||
归档必须覆盖:`uniformReflection`/`blockReflection`/`pipeInputReflection`/`pipeOutputReflection`(`ProgramObject.h:1210-1395`,各带 `TypeFacts`)、`uniformSamplerOrImageUnitIndex`(`:1298`)、`uniformBlockBinding`(`:1314`)、`shaderStorageBlockBinding`(按名字,`:1325`)、`explicitOpaqueUniformBindings`(`:1303`)、`xfbVaryings`/`xfbStrides`/`xfbPackedStride`/`xfbNeedsScatteredCapture`(`:1357-1394`)、`computeLocalSize`、GS/TCS/TES 事实(`:1373-1388`)、`usesReservedNumSamples`(`:1345`)、`uniformOffsets`(`:1416`)。
|
||||
|
||||
**`XfbVarying`(`:1146-1171`)必须带两套拼写**:GL 名字(供 Espryt 的 ESSL 驱动侧捕获列表)**和** `blockInstanceName`/`blockName`/`blockMemberIndex`/`blockMemberElement`(`:1163-1170`),因为 SPIR-V 装饰的是 block 的实例变量与成员索引,无法装饰单个数组元素。
|
||||
|
||||
#### 4.5.6 `MGPFramebufferState` 与 `MGPSubData`
|
||||
|
||||
```cpp
|
||||
struct MGPSurface { // = pipe_surface
|
||||
MGPipeHandle res;
|
||||
Uint32 internalFormat; // 内联!让四个跨对象 mask 在推送时刻零查表推出
|
||||
Uint8 kind; // Texture | Renderbuffer | None
|
||||
Uint8 layered; Uint16 level;
|
||||
Uint32 layer; Uint16 uploadTarget; Uint16 pad;
|
||||
};
|
||||
struct MGPFramebufferState {
|
||||
MGPipeHandle fbo; // {0,1} = 默认帧缓冲
|
||||
MGPSurface color[8], depth, stencil;
|
||||
MGPSurface readSurface; // *** client 侧已解析的读表面,不是索引 ***
|
||||
Int8 drawBuffers[8]; // attachment 索引,-1 = NONE
|
||||
Uint16 width, height, layers, samples;
|
||||
Uint8 fixedSampleLocations, isDefault, complete, pad;
|
||||
Uint64 contentHash; // client 计算;server 的 render-pass memo 键
|
||||
};
|
||||
```
|
||||
|
||||
三点值得单独说:
|
||||
|
||||
1. **`readSurface` 是 client 解析后的表面,不是 `glReadBuffer` 的索引。** 这一条**按结构消灭** read-buffer-shared-FBO 缺陷类(同一个 FBO 既做 draw 又做 read 时跳过 read-buffer 同步,导致回读全取 attachment 0)。
|
||||
2. **`internalFormat` 内联在每个 `MGPSurface` 里**,所以四个跨对象 mask(`g_snormFallbackClampOutputMask`、`g_unormFallbackClampOutputMask`、`g_alphaWidenedDrawBufferMask`、`g_integerColorDrawBufferMask`,`Managers.cpp:5616-5619`)在 `set_framebuffer_state` 内部零查表推出。配合 D-B3 的固定顺序,`DirectGLES.cpp:2712-2732` 的 fragColor 重推导 workaround 与 `g_broadcastMemo*` 一起删除。
|
||||
3. **`contentHash` 是全表最有价值的一个字段**:它用一次 64 位比较取代 D7 的四元组同步戳与 D15 的 `(pointer, lifetimeId, Uint16 version)` 三元组,由一个本来就在跟踪全部输入的 client 计算。attachment enum 到 Color31(`FramebufferObject.h:65-66`)而 `MAX_DRAW_BUFFERS` 是 8(`:106`)——surface 数组是 8,其余由 `drawBuffers[]` 的解析结果承载。`ARB_framebuffer_no_attachments` 的默认值是独立字段(`:134-138`)。
|
||||
|
||||
```cpp
|
||||
struct MGPSubData {
|
||||
MGPipeHandle res;
|
||||
Uint16 target, level;
|
||||
MGPBox box; // union box
|
||||
Uint32 rectCount; // rect 列表在变长尾
|
||||
MGPBlobRef blob;
|
||||
};
|
||||
```
|
||||
**同时携带 union box 与 rect 列表,由 server 选上传形状。** 这不是冗余:Mali 按**作业数**给纹理上传计价,本项目实测 ~100 个精灵 rect 对一个 union box 的差是 **+6 ms/frame**(`Managers.cpp:4311-4319`)。client 按 `MipmapStorage::GetDirtyRects` 的语义产生区域形状(96-rect 级联合并 + `summedArea*4 >= unionArea*3` 回退,`MipmapStorage.cpp:300-305`),**决策留在付 GPU 代价的那一侧**。
|
||||
|
||||
#### 4.5.7 `MGPDrawInfo` 与 `MGHostSpan`
|
||||
|
||||
```cpp
|
||||
struct MGPDrawInfo { // = pipe_draw_info,GL 有对应概念的字段逐一对齐
|
||||
Uint32 mode;
|
||||
Uint8 indexSize; // 0 = arrays,否则 1/2/4
|
||||
Uint8 flags; // kHasUserIndices | kPrimitiveRestart | kRestartRewritten |
|
||||
// kXfbCountUnknown | kIndicesAreClient
|
||||
Uint16 pad;
|
||||
Uint32 instanceCount, startInstance;
|
||||
Uint32 restartIndex;
|
||||
Uint32 minIndex, maxIndex; // client 计算(gallium 有这两个字段);~0 = 未知
|
||||
MGPipeHandle indexResource;
|
||||
MGHostSpan userIndices; // = pipe_draw_info::index 的 union
|
||||
Uint64 xfbCpuCapturedVertices; // GetTransformFeedbackCapturedVertices(),给 scatter 路径定容量
|
||||
};
|
||||
struct MGPDrawRange { Uint32 start, count; Int32 indexBias; }; // = pipe_draw_start_count_bias
|
||||
```
|
||||
|
||||
**`MGHostSpan` 是整份接口里唯一一个"形状随传输而变"的东西**,它把 backend 今天在 draw 时刻解引用**客户端字节**的四个类统一成一个访问器:
|
||||
|
||||
```cpp
|
||||
struct MGHostSpan { // 32 B
|
||||
const void* ptr; // monolith:指向前端 shadow / 应用内存。split:nullptr
|
||||
Uint64 size;
|
||||
Uint32 seg; // split:SEG_STAGE id
|
||||
Uint32 pad;
|
||||
Uint64 offset; // split:段内偏移
|
||||
};
|
||||
inline const void* MGPipeHostBytes(const MGHostSpan&); // 一次分支,每次使用解析一次
|
||||
```
|
||||
|
||||
| 消费者 | 今天的站点 | monolith 填法 | split 填法 |
|
||||
|---|---|---|---|
|
||||
| client 顶点数组 | `Managers.cpp:2500-2592`(每 draw 每属性上传 `(first+count-1)*stride+elementSize`)、`VulkanRenderer.cpp:3737` | `ptr = attrib.Offset` | tracker 暂存同样的范围进 `SEG_STAGE` |
|
||||
| client 索引数组 | `DirectGLES.cpp:4425-4442`、`VulkanRenderer.cpp:3418-3433` | `ptr = indices` | 暂存 `count*indexSize` |
|
||||
| indirect / parameter 命令块 | `DirectGLES.cpp:4666-4695`(`MultiDrawElementsIndirectCount` 从 `parameterBuffer->MappedData()` 读实际 draw 数)、`:4768-4793`、`VulkanRenderer.cpp:12045` | `ptr` 指向 shadow | tracker **解析出计数**并暂存解析后的命令块 |
|
||||
| restart 重写 / multi-draw 展平的索引字节 | `DirectGLES.cpp:4412-4415`、`MultiDraw.cpp:498-540`、`VulkanRenderer.cpp:4159` | `ptr` 指向 shadow | 暂存,或 client 已重写(§5.7) |
|
||||
|
||||
**monolith 代价为零**(一次指针加载),而且它顺带消灭了"backend 在 draw 中途回头调前端来 reconcile"这一整类:20 处 `SyncPersistentMappedRange` + 6 处 `SyncGpuWrites` 全部是"我马上要读你的字节,先把 shadow 对齐",现在改由 **tracker 在填 span 之前**做同样的 reconcile。这在 monolith 里也是严格改进。
|
||||
|
||||
**`kCapNeedsHostIndexBytes`** 存在的理由正是这条 monolith/split 的不对称:monolith 里 span 是一个免费指针,split 里是一次拷贝。让一个从不需要宿主索引字节的 backend 不付这笔钱。
|
||||
|
||||
### 4.6 与 gallium 的对应与偏离(八条,逐条记名)
|
||||
|
||||
| # | gallium | MGPipe | 理由(证据) |
|
||||
|---|---|---|---|
|
||||
| **D1** | `create_*_state` 返回 driver 指针 | **调用方提供 handle**,create 返回 void | 零创建 round trip;handle 是稠密 slot,让 server 对象表变成数组;退役全部 D 类指针 memo |
|
||||
| **D2** | `pipe_screen::get_param(cap)`、`is_format_supported(...)` 逐项查询 | **一个 `MGPCaps` POD + 一张稠密 format 表** | `DynamicBackendParameters`(`BackendObject.h:302-522`)与 `FormatCapabilityCache`(`:88-99`)本来就是平坦结构,逐项 RPC 等于每次 `glGetInternalformativ` 一次 round trip |
|
||||
| **D3** | CSO 切分是 D3D10 时代的:polygon offset、stencil write mask 在 rasterizer/depth-stencil CSO **内部** | **CSO 边界跟 Vulkan 动态状态走**:depth bias、stencil ref/write mask、line width、min sample shading、blend color、viewport、scissor、depth range 是 `set_*` 而非 CSO 字段 | `RenderState.h:523-528` 记录了共用一个版本号导致 `glViewport` 冲掉 pipeline memo **和** draw 快路径;`m_pipelineStateVersion`(`:529`)恰好是 CSO 相关子集;Magma 的 `DynamicStateShadow`(`VulkanRenderer.cpp:277-340`)与 `ApplyDynamicDrawStateTail`(`:5871`)已经这么切 |
|
||||
| **D3b** | 三个独立 CSO:blend / depth_stencil / rasterizer | **一个 `RenderStateCso`,payload 是整块 blob** | D-B1 的全部理由:`is_trivially_copyable_v` 断言(`DirectGLES.cpp:2035`)、三段 memcmp(`:2042-2047`)、**字段顺序承重**(`RenderState.h:359-368`)、两个 backend 都按 span/bulk 消费、拆分需手工维护 ~150 字段划分表且无完整性绊线 |
|
||||
| **D4** | `transfer_map`/`transfer_unmap`(scoped) | **`resource_subdata` 推送 + `map_persistent`(永久地址空间捐赠)** | `AcquirePersistentMap`(`BufferObject.h:102-118`)把指针交给**应用**,成为唯一真相源,≥16MiB 自动走到(`:226-228`)。实测 p99 163→21ms、40→115fps。不是 scoped map |
|
||||
| **D5** | driver 看得见压缩格式与 pixel-unpack 状态 | **两者在 MGPipe 里都不存在** | 前端在 `glTexImage` 时把压缩 internalformat 解析成非压缩后备(`GL_Texture.cpp:298-306`);`ScopedDefaultUnpackState`(`Managers.cpp:2888-2910`)强制 unpack 默认值,因为 `PixelStoreProcessor` 已经规整过。**只有 PACK 方向过线** |
|
||||
| **D6** | 默认 uniform block = `constant_buffer 0` | **独立入口 `set_global_constants(shaderCso, bytes, version)`** | `SpirvArtifacts::globalUboScratch`(`ProgramObject.h:1418`)是 link **phase B** 产出的 CPU 数组,布局由**优化后**的 SPIR-V 决定(`:1400-1408` 说明它无法从 glslang 反射提出来,因为 spirv-opt 就地跑且能删掉整个 block)。它没有 GL name、没有 `BufferObject`、没有 `PipeResource`。`~0u` 跳过回绕的规则保留(`:792`,那是 backend 的"从未上传"哨兵) |
|
||||
| **D7** | `pipe_shader_state` = tokens → 完成的 handle | **handle + server 侧惰性特化**,variant 键取自**已推送**状态 | D-B2 的 8 个输入。这其实**就是** gallium:Mesa 的 `st_variant` 也按已绑定状态键控(`st_get_vp_variant`) |
|
||||
| **D8** | `pipe_context::flush` + fence 是唯一反向通道 | **`MGPipeCallbacks`**:9 个具名回复/事件(§7) | gallium 没有 shadow writeback、GPU-write 通知、纹理重发请求、default-FB 几何这些词汇。把它们具名化好过藏在 95 个写回点里 |
|
||||
| **D9** | `set_viewport_states(start_slot, num)` | **float 数组 + 独立的 `writtenMask`** | viewport 是 **float** 不是 int(`RenderState.h:229-237`:`KHR-GL43.viewport_array.viewport_api` 用 `==` 无容差比较);scissor 必须单独带 `ScissorBoxWrittenMask`(`:363`),因为矩形本身回答不了"应用说过话没有"——`ScissorBoxes` 初值全零而 `glScissor(0,0,0,0)` 是合法 GL、意思是"拒绝每个片元",把空框反转成"接受一切"被 `KHR-GL43.viewport_array.scissor_zero_dimension` 抓到(`:352-362`) |
|
||||
|
||||
**没有 `pipe_transfer`、没有 `set_pixel_unpack_state`、没有压缩格式概念、renderbuffer 不折进纹理。**
|
||||
|
||||
### 4.7 覆盖论证
|
||||
|
||||
#### 4.7.1 对 477 读点分类的逐类映射
|
||||
|
||||
`../MobileGL-CS/docs/CS_Refactor/backend_read_inventory.md`(`Feat/CS-Delta-IPC` 生成)把 477 个 backend 读点分成 19 个 delta 类、0 UNMAPPED。它的**行**已经过时(`TwinLookupMemo` 族、buffer mutation epoch、`DrawTextureSyncKeys`、`SetupDrawSnapshot`/`VaoDrawMemo`、三条 persistent ring 都晚于它),但它的**分类学是现成的覆盖清单**。逐类映射:
|
||||
|
||||
| delta 类 | n | 满足它的 MGPipe 调用 | 残余 |
|
||||
|---|---|---|---|
|
||||
| handle 化(wire 句柄) | 167 | 每个命名对象的调用签名里的 `MGPipeHandle` | — |
|
||||
| RenderStateBlob | 99 | `create/bind_render_state` | — |
|
||||
| ObjectBind:Texture / Sampler | 33 | `set_sampler_views` + `bind_sampler_states` | — |
|
||||
| ObjectBind:Buffer(array/element/indirect/parameter) | 29 | `set_vertex_buffers` / `set_index_buffer` / `set_indirect_buffers` | — |
|
||||
| ObjectBind:BufferRange(UBO/SSBO/AC/XFB) | 24 | `set_shader_buffers` / `set_stream_output_targets` | — |
|
||||
| FboAttach + DrawBuffers + ReadBuffer | 19 | `set_framebuffer_state` | — |
|
||||
| Buffer ops delta | 17 | `resource_create/respecify/destroy`、`resource_subdata`、`buffer_subdata_resident`、`resource_flush_range`、`resource_readback`、`map_persistent` | — |
|
||||
| XfbOp | 15 | `set_stream_output_targets` + `*_stream_output` | — |
|
||||
| ObjectBind:Image | 14 | `set_shader_images` | — |
|
||||
| ObjectBind:VAO | 12 | `bind_vertex_elements_state` + `set_vertex_buffers` + `set_index_buffer` | — |
|
||||
| ObjectBind:Program | 10 | `set_draw_program` / `set_dispatch_program` | — |
|
||||
| TexParam / SamplerParam | 9 | `create_sampler_view`(base/max level、swizzle、dsMode)+ `create_sampler_state` | — |
|
||||
| Texture state(dirty level/rect) | 7 | `resource_subdata` | **归属反转**(§7.3) |
|
||||
| PixelStoreBlob | 6 | `set_pixel_pack_state` | unpack **删除** |
|
||||
| client-resolved(error queue) | 6 | **删除**:`RecordError` → `on_gl_error` 回调(§7) | — |
|
||||
| ProgramPublish | 3 | `create_shader_state` | — |
|
||||
| client-resolved(validation) | 3 | **删除**:client 自答 | — |
|
||||
| CurrentAttrib | 2 | `set_vertex_attrib_defaults` | — |
|
||||
| client-resolved(compile env) | 2 | **删除**:`on_caps_invalidated` | — |
|
||||
| Patch 参数 | — | `set_patch_state` | 同时是 variant 输入 |
|
||||
| 条件渲染 | — | **client 解析,永不过线** | `Core.h:387-391`:谓词只在 `glBeginConditionalRender` 解析一次 |
|
||||
| XFB CPU 计数 | — | **纯 client**;`MGPDrawInfo::xfbCpuCapturedVertices` + `MGPCaps` 的 `kCapCpuXfbPrimitiveAccounting` | — |
|
||||
| backend 重铸纪元 | — | **无 client 对应物**:`MGGen`,server 私有 | — |
|
||||
|
||||
那 1997 个前端 getter 站点不是第二个面:89 个纯版本读**根本不过线**(推送即信号),72 个数据字节读全部落在 §5.7 与 `MGHostSpan`,38 个 `GetLifetimeId()` 变成 handle,其余是 backend 现在自己持有的 POD 记录的字段读。
|
||||
|
||||
#### 4.7.2 覆盖论证不是这张表,是这条门
|
||||
|
||||
上表是**声明**,不是证明。证明是机械的:
|
||||
|
||||
> **接口纯度门。** 在 `MOBILEGL_PIPE_PUSH=all` 构建里,`MG_Backend` 被编译时 `MG_State/GLState/Core.h` **不可用**、`MG_State::pGLContext` **未声明**。任何接口没满足的读都是一次**指名文件与行号的编译错误**。strangler 结束时:`grep -c 'pGLContext' MG_Backend/` == 0(**注意 grep 的是 `pGLContext` 不是 `pGLContext->`**,因为还有 58 行非箭头用法,§2.4);`MG_Backend` 只允许 include 一张共享**值**头白名单(`RenderState.h` 的 `RenderStateParameters`、`SamplerObject.h` 的 `SamplerParameters`、`RenderState.h` 的 `PixelStoreParameters`、`VertexArrayObject.h` 的 `VertexAttribute`、纹理/格式枚举),今天是 **50 行 include / 18 个不同头文件**;`nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空。
|
||||
|
||||
**这比生成一张 477 行的清单严格得多:它禁止那次读,而不是给它编目,而且它不会过期。** 那份 inventory 仍然保留,作为 tracker 侧的覆盖检查表(G6 生成,CI `git diff --exit-code`,0 UNMAPPED)。
|
||||
|
||||
#### 4.7.3 21 条 D 类身份 memo 的重键表
|
||||
|
||||
| # | 今天的键 | 守什么 | MGPipe | 净效果 |
|
||||
|---|---|---|---|---|
|
||||
| D1 | `StateBackendObjectRegistry` 用裸 `StateObject*` + 同址 `weak_ptr`(`Managers.h:282-325`)×6 | 分配器地址复用;**也是唯一的删除信号** | 按 slot 索引的数组 + `gen` 比较;显式 `resource_destroy` | GC(1024/64 阈值)**删除** ×6 |
|
||||
| D2 | `TwinLookupMemo` ×3 + `OwnerEquals`(`DirectGLES.cpp:62-131`) | 复用堆地址命中 memo 槽 | **删除**——数组下标**就是**查表 | ~75 行 + 140KiB |
|
||||
| D3 | `UnitTextureSyncEntry` + `PairingsIntact`(`:1441-1481`) | 不移动任何计数器的 slot 交换(DSA by-name) | **结构性删除**:`set_sampler_views` 就是信号 | ~115 行 |
|
||||
| D4 | `IsBufferDrawClean` 身份优先比较(`Managers.cpp:1436`) | respecify 交给前端一个**新**资源 | server 拥有资源表;`gen` 比较;`GetChangeSerial()`(`Uint64`,不回绕)继续过线 | 简化 |
|
||||
| D5 | `ResolvedDrawBuffers::iboFrontend`(`Managers.h:711-716`) | 索引 slot 重绑而无 epoch/config 移动 | `set_index_buffer` 是独立调用 | 结构性 |
|
||||
| D6 | `m_syncedIndexBufferObject` 陪一个回绕 `Uint16`(`:775-780`) | 版本回绕后换了个 buffer | `{slot, gen}` 比较,不回绕 | 结构性 |
|
||||
| D7 | `StampSyncedFBO` 四元组(`DirectGLES.cpp:1856-1901`);`packed_pixels` postmortem `:2815-2827` | 版本回绕 + backend 侧纹理重铸 | `MGPFramebufferState::contentHash` + server 私有 `attachmentRemintEpoch`(`MGGen`) | 一次 64 位比较 |
|
||||
| D8 | `g_fboTextureSyncList`(`:1580-1601`) | 同 D3,针对 attachment | **删除**:`set_framebuffer_state` 是信号 | — |
|
||||
| D9 | `ResolvedTextureBindingMemo`:9 个键 + 驱动绑定影子的 `memcmp`(`:3218-3291`) | 任何未枚举的写者扰动某个 unit | `(shaderCso.slot, viewSetSerial)` 两字比较;`viewSetSerial` 由 server 在 `set_sampler_views` **内部** ++ | 更便宜;自校验性质保留(server 的绑定缓存**就是**它当年比对的那份影子) |
|
||||
| D10 | `UnitSamplerLookupMemo` 的 `WeakPtr` owner 测试(`:3105-3125`) | 死 sampler 复活 | 数组下标 | 删除 |
|
||||
| D11 | `VertexInputStateFactory::ComputeHash` 混入 `GetLifetimeId()`(`:38-49`) | 复用 buffer 地址重现整个 content hash(XFB 捕获拿回死 VAO 的顶点数据) | CSO handle **就是**身份;`gen` **混进** server 侧每个 content hash 而不只是比较 | 删除一整类 |
|
||||
| D12 | `SetBackendStateMemo(&entry, evictionEpoch)`:**前端 VAO 里存后端堆裸指针**(`VertexInputStateFactory.cpp:78`) | table 淘汰 | **直接删除,不翻译**。无 wire 对应物,也不需要;Magma 自己的 `VaoDrawMemo` 已经演示了替代品 | — |
|
||||
| D13 | `VaoDrawMemo` 槽(`VulkanRenderer.h:1230-1245`,注释:"两条声明的防线都失守,因为都归约到 content hash,而 content hash 的 buffer 身份分量本身就是复用的堆地址") | ABA | CSO handle | 2 字 |
|
||||
| D14 | `SetupDrawSnapshot` 的三组 `(ptr, lifetimeId, version)` + **有损的** `sampledContentSum`/`sampledParamsSum`(`.cpp:6249-6250`) | 一切 | 三个 handle + 两个 server 纪元 + dirty mask | ~14 个探测字段 → 1 次比较;**顺带消灭一类哈希碰撞**(求和会碰撞) |
|
||||
| D15 | `m_rpFast*`(`VkRenderPassManager.h:305-320`) | ABA | `contentHash` + `MGGen` | 1 次比较 |
|
||||
| D16 | `VkTextureManager::TextureIdentity{ptr, lifetimeId}` + `pGLContext->GetTextureObject(name)` 存活探测(`VkTextureManager.cpp:806-819`) | 名字复用 / 删了但仍被 FBO 引用 / 默认纹理 | `{slot, gen}` + 显式 destroy | 三种被记录的失效模式**一起消失** |
|
||||
| D17 | `VkClearManager::TextureIdentity`(`VkClearManager.h:76-83`) | ABA | `{slot, gen}` | — |
|
||||
| D18 | 纹理/renderbuffer 资源用**节点式** `std::unordered_map`(postmortem `VkRenderPassManager.h:375-397`) | 扩表搬迁使缓存的 `Resource*` 失效(`BlitFramebuffer` 静默停在 "layout undefined") | **UNCHANGED。** 接口对此零约束;这是 server 内部分配纪律。slot 数组在插入下稳定,实际更好——但**这条 postmortem 注释必须逐字带进 review checklist** | 保留 |
|
||||
| D19 | `ProgramFactory::m_cacheStructureEpoch` | 守 `SetupDrawSnapshot` 里的 server 内部裸指针 | **UNCHANGED**(`MGGen` 族) | 保留 |
|
||||
| D20 | `ConvertedVertexStreamKey` + **纯为防地址复用**持有的 `SharedPtr sourcePin`(`VulkanRenderer.h:1124-1127`) | ABA | server 拥有资源;`changeSerial` 过线 | **pin 删除** |
|
||||
| D21 | `m_xfbCounterSlotByObject[GetBoundTransformFeedbackName()]`(`VulkanRenderer.cpp:11136-11146`) | **什么都没守——这是一个活的潜伏 bug**:删了又重建的 XFB 对象会继承前任的计数槽,配上匹配的 `m_xfbLastSeenGeneration` 会**恢复**一次本该重启的捕获 | XFB 对象 handle | **顺带修一个 bug**。这一条值得先独立落到 `dev` |
|
||||
|
||||
**总计:12 条直接删除,8 条重键成比它替代的东西更便宜的比较,1 条(D18)原样不动。** 这就是"身份键 memo 不可移植"这条历史反对意见的具体回答——它们不是**以指针形式**可移植,接口的职责正是给它们一个可移植的键,而树里的证据已经把那个键是什么讲清楚了。
|
||||
@@ -0,0 +1,308 @@
|
||||
## 5. 前端 state tracker
|
||||
|
||||
### 5.1 推送发生在哪里——本设计里最容易做错的一个决定
|
||||
|
||||
**不在 GL setter 里。** `glEnable(GL_BLEND)` 绝不调 `bind_render_state`。Blaze3D 每个 batch 都用 `glEnable/glDisable(GL_BLEND)` 包住,代码自己标注它是最热的路径(`DirectGLES.cpp:2044-2046`)。天真的 per-setter 推送把每一次冗余开关变成一次接口调用加一次 server 侧 CSO 查表——**严格慢于今天,而 trace 语料会在一天之内说出来**。
|
||||
|
||||
**在 validate 时刻。** 就是 gallium 的 `st_validate_state` 形状:
|
||||
|
||||
```cpp
|
||||
// MG_Impl/Pipe/Tracker.h
|
||||
class MGPipeTracker {
|
||||
public:
|
||||
void ValidateForDraw(const MGPValidateHint&); // 20 个 GL draw 入口调用
|
||||
void ValidateForDispatch(); // glDispatchCompute*
|
||||
void ValidateForClear(GLbitfield); // 只 framebuffer + blend/colormask
|
||||
void ValidateForBlitOrCopy(); // 只 framebuffer + pack state
|
||||
private:
|
||||
Uint64 m_dirty; // MGPIPE_NEW_* 位
|
||||
Uint64 m_lastPushed[kGroupCount]; // 每组上次推送的(加宽后的)版本
|
||||
};
|
||||
```
|
||||
|
||||
`MG_Impl` 里 89 个表调用站点中大约 40 个是 verb,validate 就插在这 40 个之前。**只有资源 mutation 在 GL 调用时刻推送**——这恰恰是 `BufferBackendOps` 今天的做法(`BufferObject.h:70-71`:"在 GL 调用时刻分发,就在 shadow 拷贝刚更新之后")。
|
||||
|
||||
**稳态成本 = 一次 64 位 dirty word 测试 + N 次 `set_*`/`bind_*` 间接调用,N = 变脏的组数(稳态 1-3;因为 CSO 内容寻址,重复状态常常 N=0)。** 这严格少于它替换掉的东西:124 / 169 次 accessor 调用 + 版本比较 + 一次 ~1.2KB 的三段 memcmp + `CurrentUnitBindingsEpoch` 的逐 unit owner 走查 + Magma 的两次有损版本求和。
|
||||
|
||||
### 5.2 dirty bits:全部来自已有计数器,`MG_State` 零新增记账
|
||||
|
||||
MobileGL 已经有 dirty 底盘,只是拼写成"由 backend 轮询的版本计数器"。tracker 只是把极性反过来。
|
||||
|
||||
| dirty 位 | 现有计数器 | 位置 |
|
||||
|---|---|---|
|
||||
| `NEW_RENDER_STATE` / `NEW_PIPELINE_STATE` | `m_version` / `m_pipelineStateVersion`(`Uint16`) | `RenderState.h:522, 529`;bump 点 `RenderState.cpp:311` |
|
||||
| `NEW_VERTEX_ELEMENTS` | `VertexArrayObject::GetConfigVersion()`(`Uint32`) | `VertexArrayObject.h:155` |
|
||||
| `NEW_VERTEX_BUFFERS` | 逐属性 `VertexAttributeVersion{Format, Buffer, Switch}` | `:66-70, 150-151` |
|
||||
| `NEW_INDEX_BUFFER` | 索引 slot `GetVersion()`(**回绕 `Uint16`**)+ 绑定对象身份 | `MG_Util/Types.h:197` |
|
||||
| `NEW_FRAMEBUFFER` | `GetObjectVersion()`(`Uint16`)+ `GetAllFramebufferAttachmentVersions()`(`Array<Uint16,40>`)+ slot 版本 | `FramebufferObject.h:145, 149, 171, 183` |
|
||||
| `NEW_SAMPLER_VIEWS` | `GetContentVersion`(`Uint64`)+ `GetShapeVersion` + `GetTextureParamsVersion`(`Uint16`)+ `GetTextureBindGeneration()` + `GetSamplingResolutionGeneration()` | `TextureObject.h:61-71, 203-214`;`Core.h:130, 136` |
|
||||
| `NEW_SAMPLERS` | `SamplerObject::GetVersion()`(`Uint16`) | `SamplerObject.h:532, 551` |
|
||||
| `NEW_SHADER_IMAGES` | `ImageTextureBinding::Version` | `TextureState.h:24, 34` |
|
||||
| `NEW_SHADER` | `GetLinkVersion()` + `GetImageUnitVersion()` | `ProgramObject.h:844, 906` |
|
||||
| `NEW_SHADER_BINDINGS` | `GetBackendStateVersion()`、`GetBlockBindingVersion()`、`GetUniformWriteSetVersion()` | `:841, 1064, 652` |
|
||||
| `NEW_GLOBAL_CONSTANTS` | `GetUBOContentVersion()`(`~0u` 跳过回绕) | `:791-794` |
|
||||
| `NEW_CONST_BUFFERS` / `NEW_SHADER_BUFFERS` / `NEW_SO_TARGETS` | slot 版本 + `BufferObject::GetChangeSerial()`(`Uint64`) | `BufferObject.h:211` |
|
||||
| `NEW_PATCH_STATE` | patch 三字段,用 `BitwiseEqual` 比较(NaN 合法,`DirectGLES.cpp:2807-2814`) | `RenderState.h:241, 247, 248` |
|
||||
| `NEW_PIXEL_PACK` | `PixelStoreParameters` | `RenderState.h:190-199` |
|
||||
|
||||
**三个回绕的 `Uint16` 在 tracker 边界加宽。** `BindingSlot::m_version`、`FramebufferObject::m_objectVersion`、`SamplerObject::m_version` 今天只有配合裸指针身份比较才正确(`packed_pixels` postmortem,`DirectGLES.cpp:2815-2827`)。`m_lastPushed[]` 是 tracker 自己的字段而不是 `MG_State` 的字段,所以加宽到 `Uint32`/`Uint64` **不需要改 `MG_State` 一行**;同时 handle 与它同行过线。**回绕在 tracker 本地是无害的**(一次回绕造成一次多余的重推,永远不会造成一次漏推),因为 tracker 还额外保存推送内容的 hash 用于 CSO 查表。
|
||||
|
||||
### 5.3 每命令 validate 与固定顺序
|
||||
|
||||
```
|
||||
1 set_framebuffer_state ← 必须先于 2 和 4
|
||||
2 create_shader_state(link 时刻发,不是 draw 时刻) / set_draw_program
|
||||
3 set_sampler_views / bind_sampler_states / set_shader_images / set_shader_buffers / set_global_constants
|
||||
4 create_render_state(未命中时)/ bind_render_state
|
||||
5 bind_vertex_elements_state / set_vertex_buffers / set_index_buffer / set_vertex_attrib_defaults
|
||||
6 set_patch_state / set_stream_output_targets
|
||||
7 draw_vbo
|
||||
```
|
||||
|
||||
**framebuffer 严格第一是承重的**(D-B3):四个跨对象 mask 从 attachment 格式推出(`Managers.cpp:5616-5619`),被渲染状态推送(`DirectGLES.cpp:2014`)与 program 陈旧性判定(`:2769-2770`)消费。今天 Espryt 靠在 `SyncCurrentProgram` 内部**自己重新推导**广播数来绕开(`:2712-2732`,注释:否则用陈旧计数编译出的 program 要迟一个 draw 才重链)。固定推送顺序把这个 hazard 变成免费属性,那段 workaround 与 `g_broadcastMemo*` **一起删掉**。同理 `ImageUnitFormatsStillMatch`(`Managers.cpp:6545-6573`,注释明说"不可表达为单调版本")由 `set_shader_images` 直接告知。
|
||||
|
||||
`create_shader_state` **从编译池的终止 continuation 发出**(`JobNode.h:109-123`),不是从 draw 发出——这样 SPIR-V 在用到它的第一个 draw 之前就到达 server。这是 monolith 拿不到的异步收益,也是把阻塞的 `JoinLinkAndSpirv()` 移出 server draw path 的那一步。
|
||||
|
||||
### 5.4 合并:保留代码库已经发现的三条
|
||||
|
||||
1. **整块结构优于逐字段。** Magma 的 `ComputePipelineStateHash`(`VulkanRenderer.cpp:4818-4826`)已经把 ~17 次 accessor 调用换成一次 bulk fetch;Espryt 的三段 memcmp 同理。tracker 发**变化的段**(`spanMask`),段划分与现有 memcmp 完全一致。
|
||||
2. **高水位标记。** `BufferState::TouchBindPoint` / `GetTouchedBindPointCount`(`BufferState.h:49-62`,每 target 84 个绑定点,理由 `:23-28`)与 `TextureState::NoteUnitTouched` / `GetMaxTouchedUnit`(`Core.h:123-126`,192 个单元)**必须留在 tracker 的走查里**——没有它们,每次 validate 都要走 84×4 个绑定点和 192 个纹理单元。它们直接就是 `set_shader_buffers` / `set_sampler_views` 的 `count` 实参。
|
||||
3. **只发 program 解析过的集合。** `set_sampler_views` 只推 shader 真正读的那些单元,用 `LinkArtifacts::uniformSamplerOrImageUnitIndex`(`ProgramObject.h:1298`)——这是 client 侧数据,所以是纯 client 收益。两个 backend 今天已经在算这个(`ResolveAndBindUnitTextures`,`DirectGLES.cpp:2973`;`UniformManager::CollectSampledTextures`)。
|
||||
|
||||
**索引绑定的范围必须在 validate 时刻实时解析,不是在 bind 时刻快照。** `BindingSlotRange1D::GetRange()` 对整 buffer 绑定返回 `Range1D(0, object->GetSize())` 而不是绑定时的快照,因为 `glBindBufferBase` 之后再 `glBufferData` 是普通应用代码,只有 `glBindBufferRange` 才钉死一个窗口。
|
||||
|
||||
### 5.5 sampler view 在 client 侧解析
|
||||
|
||||
GL 是**每个 unit 每个 target 各一个绑定**(`TextureUnit.h:393-394`;`TextureState::m_textureUnits` 是 `Array<TextureUnit, 192>` **按值**存放,`TextureState.h:128`,而每 stage 广告上限是 32,`:46`),shader 看见哪一个取决于 sampler uniform 的声明类型、mipmap 完备性(`IsMipmapCompleteForFilter`,`TextureObject.h:309`;`SamplesAsIncompleteTexture`,`:315`)和 `IsUndefinedDefaultTexture`(`:329-332`)。**gallium 的"每槽一个 view"就是解析后的形态。**
|
||||
|
||||
**解析留在 client。** 把这本 GL 完备性规则书推给 server,就是在 server 里重建前端——正是用户否掉的那个冗余。
|
||||
|
||||
**两处 backend 特定的后处理留在 server**,并作用在已解析的集合上:Espryt 的 raw-depth-fetch sampler 替换(`DirectGLES.cpp:3540-3546`)与 Magma 的 feedback-loop 检测(对着 draw FBO,`UniformManager.cpp:554`)。两者都可以从已推送的 `set_framebuffer_state` + view 集合判定,所以是普通的 server 侧 lowering。
|
||||
|
||||
### 5.6 对象生命周期、共享组与 composite pipeline program
|
||||
|
||||
#### 5.6.1 生命周期
|
||||
|
||||
`resource_create` 在**前端对象构造**时发(lifetimeId 铸造的地方),存储由 `resource_respecify` 惰性定义。`resource_destroy` 在前端对象析构时发。三条今天靠 `SharedPtr` 边表达、接口必须显式声明的顺序约束:
|
||||
|
||||
- **view 先于其存储属主销毁**:`ITextureObject::GetViewStorageOwner()`(`TextureObject.h:96-100`)是 `SharedPtr`,正是为了免费拿到 GL 的名字删除语义(`glDeleteTextures(orig)` 之后对象因 view 引用而存活)。→ `MGPResourceDesc::viewOf` + server 侧 keep-alive。
|
||||
- **FBO attachment 钉住纹理**:`FramebufferAttachmentObject::m_texture`(`FramebufferObject.h:95`)。→ `set_framebuffer_state` 的 surface handle 隐含 server 侧 keep-alive。
|
||||
- **buffer texture 钉住 buffer,且范围实时解析**:`TextureObjectBuffer::m_bufferBindingSlot`(`TextureObjectBuffer.h:46`),`kWholeBuffer = ~0`(`:28`)使后续 respecify 继续被跟随,`GetBufferRangeSizeInBytes`(`:35-41`)对实时 size 钳制。→ `MGPResourceDesc::{bufferForTexBuffer, bufOffset, bufSize}`。
|
||||
|
||||
#### 5.6.2 共享组
|
||||
|
||||
v1:一个 screen、一个 context、一个扁平 handle 空间、一条 flow,没有 session id(理由见 §1.2 与 §4.3)。`eglMakeCurrent` 是 flow 所有权转移,在既有 `EGLOperationMutex`(`EGLImpl.cpp:241`)下发射——**顺手修今天不取该锁的两个入口**:`ReleaseThread`(`:341-350`)与 `SwapInterval`(`:435-450`)。v2 的映射是干净的(每个 share group 一个 client `GLContext`,每个 GL context 一个 `MGPipeContext`),但走独立 PR 带多 context 测试落 `dev`,不在本分支。
|
||||
|
||||
#### 5.6.3 composite pipeline program:判过死刑的那个反对意见,答案是"什么都不用做"
|
||||
|
||||
`GLContext::GetProgramForDraw()`(`Core.cpp:592`)**今天就已经完全在前端**完成 program pipeline 的合成:join 每个 stage 的 `JoinLinkAndSpirv()`(`:617` 附近的 J1 join 点)、按 `ComputeDrawProgramSignature()`(`:630`,键是每个图形 stage 的 `(lifetimeId, linkVersion)`)查 cache、miss 时构造**故意不命名**的 `MakeShared<ProgramObject>(0u)`(`:644`)、挂上每个 stage 被钉住的 linked snapshot、重装捕获 stage 的 XFB varyings、`Link(true)`、缓存、`RefreshCompositeUniforms`。
|
||||
|
||||
tracker 调它,拿到一个 `SharedPtr<ProgramObject>`,推**一个 handle**。合成体没有 GL name,但它**有 lifetimeId**,而它的 slot 从 `ShaderCso` 的保留高位段分配(§4.2.1)。生命周期:pipeline cache 淘汰该条目时(signature 变化或 pipeline 删除)释放 slot、`gen++`、发 `delete_shader_state`——`CompositeResolver.cpp` 里三行。
|
||||
|
||||
**合成体从不过线、从不被重新实现,`PLAN.md` §5.7 提议往 `MG_State/GLState/Core.h` 加的 `SetReplicaResolvedDrawProgram` 钩子完全不需要**——pipe 调用**就是**那次解析。副带收益:阻塞的 `JoinLinkAndSpirv()` 彻底离开 server 的 draw path。
|
||||
|
||||
### 5.7 program artifacts 与全局 UBO scratch
|
||||
|
||||
**`create_shader_state` 的 payload 是 SPIR-V + 全结构体反射归档**(§4.5.5),不是源码。理由是硬约束而非偏好:`ProgramObject.h:11 → ShaderObject.h:12 → ShaderCompileTask.h`,`ShaderObject.h:146` 返回 `SharedPtr<glslang::TShader>`,`ProgramObject.h:14 → SpvcSession.h`——**链接真 `ProgramObject` 就链接 glslang**。所以 `RecProgramLinkOp` 不可能存在,`ProgramPublish` 第一天就上,`nm -D libMobileGLServer.so | grep glslang` 为空是**接口纯度门的一部分**。
|
||||
|
||||
**SPIRV-Cross 留在 server**(`TranspileSpirvToEssl`,`Managers.cpp:6575`):它消费 SPIR-V 加设备事实,两者都在 server 侧。**glslang 留在 client。** 这是一次文件级切割,不是一次审计。
|
||||
|
||||
**全局 UBO scratch 走独立入口**(D6):`set_global_constants(shaderCso, MGPBlobRef bytes, Uint32 version)`,键 `(shaderCso.slot, uboContentVersion)`,复现 `DirectGLES.cpp:3369-3392` 的"每 program 每帧至多一次"。`~0u` 跳过回绕的规则保留(`ProgramObject.h:792`,那是 backend 的"从未上传"哨兵)。
|
||||
|
||||
**backend 侧 program link/compile 失败不需要任何同步返回,也不需要新事件种类。** 实测:`SyncToBackend` 在 `Managers.cpp:8091` link、`:8094` 读 `GL_LINK_STATUS`、`:8095` 折进 `m_backendProgramUsable`、`:8097-8101` 取驱动日志、`:8106` 发 `MGLOG_E`;`Use()` 随后绑 program 0(`:8357`)并 `MGLOG_E_ONCE`(`:8364-8372`)。**没有 GL error、没有 `ProgramObject` 变更、`GL_LINK_STATUS` 永不撤回**——代码在四处说明理由(`:7098`、`:7247-7249`、`:6478`、`:7827`:"GL 无法撤回它已经报告为 true 的 LINK_STATUS,所以'链接了但画不出来'就是答案")。同步查询 `glGetProgramiv(GL_LINK_STATUS)` 与 `glGetProgramInfoLog` 完全由 client 从 `ProgramObject` 回答(`GL_Program.cpp:851` → `ProgramObject.h:913`)。所以 `on_log` 逐字复现它——**但由此推出一条对 `PLAN.md` §7.4 的强制修正,见 §7.4**。
|
||||
|
||||
### 5.8 emulation 所需前端数据的显式传递
|
||||
|
||||
归属规则用 gallium 自己的:**驱动表达不了的变换在 state tracker 里 lowering,硬件/驱动强加的变换在 driver 里 lowering**,且每一条由一个具名 cap 位门控(这是 Design 1 的贡献,它让归属可审计、可推广到第三个 backend)。
|
||||
|
||||
| emulation | 归属 | cap 门 | 过线的是什么 |
|
||||
|---|---|---|---|
|
||||
| **client 顶点数组**(`Managers.cpp:2500-2592` 把 `attrib.Offset` 当应用裸指针,每 draw 每属性上传 `(first+count-1)*stride+elementSize`;`VulkanRenderer.cpp:3737` 是**唯一无界**的应用指针读) | **client**(它拥有地址空间) | — | **字节,永不是指针**。范围 client 侧算。gallium 根本没有 client array 概念,Mesa 的 `_mesa_upload_vertices` 就是这么做的 |
|
||||
| **索引扫描**(`TryComputeMaxIndexFromHostBytes`,`VulkanRenderer.cpp:3407-3470`,用于给上一条定界) | **client**(只有它同时持有两个数组) | — | `MGPDrawInfo::minIndex/maxIndex`(gallium 本来就有这两个字段),`~0` = 未知 |
|
||||
| **client 索引数组** | client | — | `MGPDrawInfo::userIndices`(`MGHostSpan`) |
|
||||
| **primitive-restart 重写**(`DirectGLES.cpp:4368-4470` 整 EBO 重写,`kMaxRestartRewriteBytes` 上限;`VulkanRenderer.cpp:4159-4161`) | **client**,`!kCapPrimitiveRestart` 时 | `kCapPrimitiveRestart` / `kCapPrimitiveRestartFixedIndex` | 重写后的索引 + `kRestartRewritten` 标志。**"draw 被丢弃"的诊断随之落到应用线程上,比落在 server 上更有用** |
|
||||
| **multi-draw 展平**(`MultiDraw.cpp:498-540`) | **CPU 档在 client**(`!kCapMultiDraw`);**compute 档留 server**(`kMaxComputeFlattenedIndices`,`:81-83`,那是驱动 lowering) | `kCapMultiDraw*` | 只在 cap 说需要时才发索引字节 |
|
||||
| **`*IndirectCount` CPU 回退**(`DirectGLES.cpp:4684-4793` 从 `parameterBuffer->MappedData()` 读实际 draw 数) | **client**,`!kCapMultiDrawIndirectCount` 时 | `kCapMultiDrawIndirectCount` | client 从自己的 shadow 解析出计数,发解析后的 `MGPDrawRange[]` |
|
||||
| **viewport-array N 遍回放**(`DirectGLES.cpp:3742-3846`,今天包住 14 个 draw 入口) | **server**(它取决于转译出来的 ESSL 有没有被注入路由 gate) | `kCapViewportArray` | 无新增:16 组 viewport/scissor/depth-range 已在 render-state blob 里,decline 输入(XFB active、rasterizer discard)也在 |
|
||||
| **fp64 顶点窄化**(`Managers.cpp:2518-2557`) | **server**(这是后端格式决策) | `kCapFloat64VertexAttrib`(`BackendObject.h:487-500` 明说它与 `SupportsShaderFloat64` **独立**) | 原始字节;`IsLong` 与 `Type` 分开过线 |
|
||||
| **image-bindable 存储加宽/拆分**(`Managers.cpp:2789-2822`、`:4620-4630`) | **server**(纯驱动 workaround) | — | 正向:`imageBindableHint` 预防;反向:`on_texture_pull_request`(§7.5) |
|
||||
| **生成 mipmap 的前端存储** | **拆开**:client 分配 level 存储(它必须回答 `glGetTexImage`),server 生成 | — | `MGPMipPlan`;CPU 回退路径的纹素由 `on_texture_writeback` 回来 |
|
||||
| **CopyImage shadow 镜像**(`DirectGLES.cpp:7065-7140`) | **client**(给定区域,它可以用自己的两张纹理做同样的拷贝) | — | 只回"拷贝成功"。**删掉一整条 server→client 字节通道** |
|
||||
| **XFB CPU 图元计数**(`GL_Drawing.cpp:172`,调用点 `:1133, 1141, 1195, 1668`) | **纯 client** | `kCapCpuXfbPrimitiveAccounting` | `MGPDrawInfo::xfbCpuCapturedVertices` + `end_stream_output` 的 `MGPXfbAccounting`。**`PLAN.md` 的 `RecXfbAccounting`、`MG_Remote::Shared::` helper 族、整个 `gen_impl_mutation_surface.py` 生成器随之删除** |
|
||||
| **压缩纹理 / pixel unpack 规整** | **纯 client**(`GL_Texture.cpp:298-306`;`PixelStoreProcessor`) | — | 无 |
|
||||
|
||||
#### 5.8.1 陈旧索引纪律——这条不做就是几何消失
|
||||
|
||||
上表里每一次 client 侧扫描/重写,在 monolith 里都紧跟在 `SyncPersistentMappedRange()` + `SyncGpuWrites()` 之后(`DirectGLES.cpp:4412-4413`、`MultiDraw.cpp:498-499`、`VulkanRenderer.cpp:3431, 4159`),因为 EBO 可能刚被 compute shader 或 XFB 写过。**tracker 必须在完全相同的程序点做同一次 reconcile**:publish → 等 `appliedSeq` → 排空事件 → 再碰 shadow。跳过它,`maxIndex` 就来自陈旧字节,顶点数组被少拷 → 几何缺失/花屏,或越界读应用数组。
|
||||
|
||||
门:`ClientArrayAfterComputeWriteScenario`(新增),**必须能因它存在的理由变红**(去掉那次等待就应当看到几何缺失)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 后端状态机改造
|
||||
|
||||
### 6.1 什么原样不动(先说这个,因为它是"最短可信改造"的依据)
|
||||
|
||||
**每一个 ring、pool、arena、quirk、lowering pass 原地不动:**
|
||||
|
||||
Espryt:三条 persistent-mapped ring(UBO `Managers.h:591-637`、unpack `:639-671`、upload `:673-…`)、`PersistentRing` 的分配/背压算法、buffer pool(64MiB 预算 / 单 buffer 8MiB)、全部 7 条 fallback-repack 路径(`Managers.cpp:3209-3527`)、`m_backendColorSlots` draw-buffer 置换表(`Managers.h:1183-1195`)、三个 scratch FBO 及其驱动侧 attachment 影子、`PackState`、全部驱动绑定影子、Adreno 的"禁用属性无指针 SIGSEGV" workaround(`Managers.cpp:2371-2380, 2427-2433`)、Mali 的 XFB 捕获丢失 workaround(`DirectGLES.cpp:400-410`)、`ScopedDefaultUnpackState`、SPIRV-Cross 会话与 6 次 post-emission ESSL 重写、驱动 POST 自检族。
|
||||
|
||||
Magma:`VulkanRenderer` 全部 memo 与 scratch、`PipelineFactory`、`ProgramFactory`、`UniformManager` 的 ring 与描述符集、五个 `Vk*Manager`、`FrameContext`、`SwapchainObject`、`DynamicStateShadow`、`VertexInputStateFactory` 的 cache **本体**、**以及 D18 的节点式容器纪律**。
|
||||
|
||||
**接口改变的是 backend 怎么知道这些事实,不是它拿这些事实做什么。** 这就是为什么这是最短的可信改造路径:对多数子系统,函数体不变,只有 accessor 表达式换个地方取值。
|
||||
|
||||
**唯一两处必须真改的 `MG_State` 类型内部用法**(`PLAN.md` 把它们计为零成本,两轮评审都点了名):
|
||||
|
||||
1. **Magma 的占位纹理**(`UniformManager.cpp:161-181, 1416-1500, 1624-1634`):构造真的 `TextureObject2D` / `TextureObject2DMultisample` / `TextureObject2DMultisampleArray`,走 `SetInternalFormat(RGBA8)` / `AllocateStorage({1,1,1},4)` / `UpdateMipmapSubData` / `MarkStorageDirty` / `SetSamples(2)`(VUID-RuntimeSpirv-samples-08726 禁止 MS=1 读 1-sample image)/ `TruncateMipmapLevels(1)`,**唯一理由**是让"未绑定单元"复用 `SyncTextureAndGetDescriptor(ITextureObject&)` 这个签名。改成 backend 自己分配 `VkImage` + view + descriptor:**~120 行前端对象木偶戏变成 ~60 行直白的 VMA/Vulkan,43 个 `MOBILEGL_ASSERT(pGLContext)` 里的 9 个随之消失。** 这是推送模型**减少**工作量最清楚的一处;上一轮"薄 server 不可行"的判决,是针对一个**拉取**接口下的判决。
|
||||
2. **Magma 的两个内部 shader**(`InitializeBlitResources` `VulkanRenderer.cpp:4210-4283`、`InitializeDepthMipmapResources` `:4287-4356`):从字符串字面量构造 `ShaderObject`、`Compile()`、建 `ProgramObject`、`Link(false)`、读 `GetUniformLocation` ×7、断言 `GetUBOSize() > 0`、后面 `MapUBO()`(`:8450-8452`)。**烘焙成 SPIR-V。**
|
||||
**方式:把生成的 SPIR-V、uniform location、UBO 布局作为生成头文件签进树里,用一个 `MG_Test` 用例重跑树内 glslang 对同一批源码字符串并逐字节比对来守新鲜度。** 不用构建期 host glslang target——那需要一个 host 工具目标,在 Android NDK 交叉构建、WSL、Windows、macOS 四条 lane 上以四种不同方式坏掉。签进树 + 测试守卫是本仓库对 golden 已经在用的模式。`uSource` 的描述符绑定本来就是由 `ProgramFactory` 自己的 SPIRV-Reflect 走查找到的(`:4340-4350`),原样存活。**顺带把一次 glslang 编译从 monolith 启动路径上删掉。**
|
||||
|
||||
Espryt 有一个小号同类:`g_rawDepthFetchSamplerState`,一个独立的 `SamplerObject(0)` 被 `SyncToBackend` 驱动(`DirectGLES.cpp:166-179`)→ 改写成 backend 原生的 sampler 记录,~40 行。
|
||||
|
||||
### 6.2 strangler 脚手架:`PipeInputs` + 两个填充器 + poison mask
|
||||
|
||||
```cpp
|
||||
// MG_Backend/MGPipe/PipeInputs.h (backend 私有;迁移结束后不 include 任何 MG_State 头)
|
||||
namespace MobileGL::MG_Pipe {
|
||||
struct PipeInputs {
|
||||
// 阶段 A:字段类型与 backend 今天读到的**完全一致**
|
||||
const RenderStateParameters& GetRenderStateParameters() const;
|
||||
Uint16 GetRenderStateParametersVersion() const;
|
||||
const MGPVaoRec& GetBoundVertexArray() const;
|
||||
// … 每个 backend 真正用到的 GLContext 方法一个访问器(Espryt 32 个 / Magma 55 个)
|
||||
#if MOBILEGL_DEBUG || MOBILEGL_BUILD_DISAGGREGATED
|
||||
Uint64 m_filledMask[2]; // G5 生成;读未填字段 = Fatal{UnmigratedPipeInput, "<field>"}
|
||||
#endif
|
||||
};
|
||||
extern PipeInputs gPipeInputs;
|
||||
}
|
||||
#if MOBILEGL_PIPE_PUSH
|
||||
# define MGB_CTX (&::MobileGL::MG_Pipe::gPipeInputs)
|
||||
#else
|
||||
# define MGB_CTX (::MG_State::pGLContext)
|
||||
#endif
|
||||
```
|
||||
|
||||
**`PipeInputs` 按 memo 键组织,不是按读点组织。** 这是它只有 ~20KB、且字段集在整个迁移期稳定的原因(Design 2 的贡献)。每 draw 实际推送的增量由 §5.4 的两个高水位标记定界。
|
||||
|
||||
#### 6.2.1 三个阶段,其中阶段 A 可证明是 no-op
|
||||
|
||||
| 阶段 | 改什么 | 怎么证明 |
|
||||
|---|---|---|
|
||||
| **A — 别名** | 机械 `sed`:`MG_State::pGLContext->` → `MGB_CTX->`(**293 处**);**外加手工转换 58 行非箭头用法**(§2.4,其中 `DirectGLES.cpp:146` 的 `.get()` 裸指针捕获 `sed` 完全抓不到)。`SnapshotFromGLContext()` 在 `PrepareForDraw`(`DirectGLES.cpp:2916`)/ `SetupDraw`(`VulkanRenderer.cpp:6371`)顶端填 `gPipeInputs`。**backend 函数体其余部分不变** | `nm --defined-only` + 剥调试信息后的 `.text` size diff 在 pull 构建里一致 |
|
||||
| **B — 推送** | tracker 填 `gPipeInputs`;`SnapshotFromGLContext()` 仍在,按 `MOBILEGL_PIPE_PUSH` 位图逐字段让位 | **`MOBILEGL_PIPE_VERIFY=1`**(§10.3-2):tracker 再填一份快照版,G4 生成的比对器**逐字段**每 draw 比一次,打印第一个分歧字段名与 draw 序号 |
|
||||
| **C — handle 化** | `SharedPtr<FrontendObject>` 字段 → `MGPipeHandle` + POD 描述符;memo 重键;写回变回调 | 全套门(§10.3) |
|
||||
|
||||
**迁移粒度是一个 accessor,不是一个子系统。** §6.4/§6.5 的阶段划分只是方便的批次,不是硬边界。
|
||||
|
||||
#### 6.2.2 poison mask 是完整性的运行期绊线
|
||||
|
||||
`m_filledMask` 由 G5 从 `PipeCalls.def` 生成。在 debug 与 disaggregated 构建里,读一个 tracker 从未推送的字段是 **`Fatal{UnmigratedPipeInput, "GetStencilState"}`,发生在第一个 draw 上**——响亮、精确、不可能渲染过去。迁移结束(P13)删掉 `SnapshotFromGLContext()` 之后,完整性变成**构建期事实**:一个从未被写入的字段就是一个编译器能标出来的字段。
|
||||
|
||||
**这就是历次评审所说"reconciler 完整性只有测试绊线、没有构建绊线"的答案**,而它只有在"接口先落在 monolith 里"时才存在。
|
||||
|
||||
### 6.3 Track V / Track H 与残余值块
|
||||
|
||||
32 个 Espryt accessor 与 55 个 Magma accessor 分两条轨:
|
||||
|
||||
- **Track V(值类型)**:`GetRenderStateParameters`、`GetPixelStoreParameters`、`IsCapabilityEnabled(+Indexed)`、`GetStencilState`、`GetColorMaskIndexed`、`GetDepthMask`、`GetScissorBox`、`GetPatchVertices`、`GetCurrentVertexAttribute`、Magma 的 ~22 个标量 getter…… **约占 B 类读点的 55%**。它们**完全不需要重塑形状**:client memcpy 值,server 把自己那份的引用交给 backend。机械,每组 ~1 天。
|
||||
- **Track H(对象类型)**:167 个 `SharedPtr<MG_State…>` 点。真活:参数类型变 `MGPipeHandle` + `const MGPXRec*`,twin registry 变 slot 数组,memo 重键。
|
||||
|
||||
**Track V 的 55% 不需要逐字段接口条目就能跑起来**,所以 P2 发一个**显式临时**调用:
|
||||
|
||||
```cpp
|
||||
void (*set_residual_value_state)(MGPBlobRef); // 尚未迁移的值类 accessor 的并集,~1.5KiB
|
||||
struct ResidualValueBlock {
|
||||
RenderStateParameters renderState; // 直到 create/bind_render_state 落地
|
||||
PixelStoreParameters pack; // 直到 set_pixel_pack_state 落地
|
||||
Uint64 capabilityBits; // 直到能力位折进 render-state CSO
|
||||
Uint32 patchVertices; Float patchOuter[4], patchInner[2];
|
||||
// … 每个阶段变小 …
|
||||
};
|
||||
```
|
||||
|
||||
**三条硬性纪律,缺一不可:**
|
||||
|
||||
1. **它是显式临时的,退役是一个编译错误。** `static_assert(sizeof(ResidualValueBlock) == MGL_RESIDUAL_BLOCK_SIZE)`,常量每阶段**下调**;P13 到 0 之后 `static_assert(sizeof(ResidualValueBlock) == 0, "残余块必须清空才能删除 pull 路径")` 一直红到最后一个字段消失。**本设计里没有任何"临时重复"是没有具名退役绊线的。**
|
||||
2. **布局必须逐成员断言,不能只断言 sizeof。** 这是一个异质 POD 的并集,跨编译器/ABI 边界最容易出的正是 padding 差异,而 monolith 的 verify harness **看不见它**(monolith 里两侧是同一个 TU)。所以:G3 为块内**每个成员**生成 `static_assert(offsetof(ResidualValueBlock, X) == N)`,**并且**在 split 模式下该块**逐字段序列化**(走 G3 生成的编解码器)而不是整块 memcpy。
|
||||
3. **它只在 P2..P13 之间存在**,且 `MOBILEGL_PIPE_STATS` 必须把它的字节量单独计一类,让"它还有多大"是一个可见指标。
|
||||
|
||||
### 6.4 DirectGLES(Espryt)逐子系统
|
||||
|
||||
`PrepareForDraw` 的阶段顺序(`DirectGLES.cpp:2916-2975`,工作树行号):`GetBoundVertexArray` → `ResolveVaoTwin` → `GetProgramForDraw`(**join 编译池**)→ `CaptureDrawTextureSyncKeys` → `SyncNeccessaryBuffers` → `SyncCurrentVAO` → `SyncNeccessaryTextures` → `SyncImageTextureBindingsForDraw` → `MarkWritableImageBufferTexturesGpuWritten`(**改前端**)→ `SyncCurrentFBO` → `SyncCurrentProgram` → `SyncRenderState` → `BindCurrentFBO` → VAO bind → `SyncCurrentVertexAttributeValues` → `BindCurrentTextures` → `BindCurrentProgramWithResources` → `StartPendingTransformFeedback`。
|
||||
|
||||
| # | 子系统 | 消除读点 | memo | 写回 | 轨 | 天 | 风险 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| 0a | `GetIntegeri_v`/`GetInteger64i_v`/`GetProgramiv` 移回 `MG_Impl` | 14 | 0 | 0 | — | 1-2 | 极低(严格 no-op) |
|
||||
| 0b | handle 基建;6 个 registry → slot 数组;删 `TwinLookupMemo`×3 / `OwnerEquals` / `g_fbSlotCache` / 2 个 GC 扫描 | — | 9 删 | — | — | 5-7 | 低 |
|
||||
| 1 | **渲染状态**(`DirectGLES.cpp:1962-2654`,693 行) | **4**(`:2007, 2021, 2050, 2133`) | 0(本来就是值键) | 0 | V | **3-5** | **低**:693 行函数体、三段 memcmp、`g_syncedColorMaskAlphaWidenMask`、dual-source decline 全部不动,只有取值表达式换地方 |
|
||||
| 2 | buffer + 7 个 `BufferBackendOps` | 19 | 3 | 6(+23 处 re-entry 删除) | H | 10-13 | **高**(但不碰 `AcquirePersistentMap`) |
|
||||
| 3 | VAO / vertex elements | 2(+~10 getter) | 4 | **0**(Espryt 不往任何前端对象写 memo,已核实) | H | 7-9 | 中 |
|
||||
| 4 | framebuffer / renderbuffer | 8 + 4 处 `pDefaultFramebufferInfo` | 4 | 1 | H | 7-9 | 中高 |
|
||||
| 5 | 纹理 / sampler / image unit | 18(+~35 getter) | 8(5 删) | 21 | H | 20-26 | **高** |
|
||||
| 6 | program + constant buffer | 16(+~30 getter) | 5 | 0 | H | 14-18 | **高** |
|
||||
| 7 | XFB | 3 | 1 | 2 | H | 5-7 | 中 |
|
||||
| 8 | emulation + `MGHostSpan` | ~12 | 0 | 3 | — | 8-11 | 中 |
|
||||
| 9 | 回读 / pack state | ~10 | 1 | 7 | V+H | 5-7 | 中 |
|
||||
| 10 | 删 pull 路径 + `MGB_CTX` | — | — | — | — | 4-6 | 低 |
|
||||
| | **合计** | **124** | ~32 | 28 | | **89-120** | |
|
||||
|
||||
**子系统 5 是全表最危险的一处**,因为它同时压着实测 +6ms/frame 的 box-vs-rects 悬崖(`Managers.cpp:4311-4319`)与 7 条 fallback-repack 路径(其可行性判定要求 `uploadData == mipData`,即驱动用 `UNPACK_ROW_LENGTH` 跨步直接读前端字节)。缓解:`resource_subdata` **同时**携带 box 与 rect 列表、**server 选形状**(§4.5.6);repack 族原地不动,只把输入从"拉取的 shadow 指针"换成 `MGPBlobRef`(monolith 里是同一个指针);子系统 5 拆成两个可独立落地的半(先 sampler view + sampler,再 image unit + dirty 归属反转),让回归能二分到其中一半。
|
||||
|
||||
### 6.5 DirectVulkan(Magma)逐子系统
|
||||
|
||||
| # | 子系统 | 读点 | memo | 写回 | 天 | 风险 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 0a/0b | 同 Espryt;13 个身份缓存重键 | ~10 | 13 | 0 | 5-8 | 低 |
|
||||
| 1 | **pipeline + 动态状态**(`ComputePipelineStateHash` `:4818`、`ApplyDynamicDrawStateTail` `:5871`、`GetOrCreatePipeline` `:4948`) | ~55 | 1 | 0 | **3-4** | **低——两个 backend 里最便宜的一次转换** |
|
||||
| 2 | `SetupDraw` + `TrySetupDrawFastPath`(`:5994`,377 行)+ `SetupDrawSnapshot[4]` | ~48 | 4 | 0 | 10-13 | 高 |
|
||||
| 3 | `VkBufferManager`(7 个 op 里的 6 个;`ResidentSubData` 保持 null) | ~19 | 2 | 4 | 7-9 | 高 |
|
||||
| 4 | `VertexInputStateFactory` + `VaoDrawMemo`(**删掉写进前端 VAO 的后端堆裸指针**) | ~6 | 2 | 3 | 2-3 | **低(纯结构性收益)** |
|
||||
| 5 | `VkTextureManager`(3504 行)+ `VkSamplerManager` | ~30 | 3 | 7 | 13-16 | 高 |
|
||||
| 6 | `UniformManager` 描述符 + **占位纹理原生化**(§6.1-1) | ~35 | 4 | 6,**且删 ~120 行** | 12-15 | 高 |
|
||||
| 7 | `VkRenderPassManager` / `VkClearManager` / framebuffer(**保留 D18 的节点式容器**) | ~20 | 2 | 0 | 7-9 | 中高 |
|
||||
| 8 | `ProgramFactory` + **内部 shader 烘焙**(§6.1-2,含 4 天烘焙与回归测试) | ~15 | 1 | 2 | 7-9 | 中(构建 lane) |
|
||||
| 9 | XFB(**顺带修 D21**)+ query + 回读 | ~15 | 2 | 5 | 11-14 | 中 |
|
||||
| 10 | swapchain / default FBO(`SwapchainObject.cpp:276-330` 的**写**变 `on_surface_changed`) | ~4 | 0 | 7 | 4-5 | 中 |
|
||||
| 11 | 删 pull 路径 | — | — | — | 4-6 | 低 |
|
||||
| | **合计** | **169** | ~34 | 42 | **85-111** | |
|
||||
|
||||
**Espryt 的子系统 1 与 Magma 的子系统 1 作为一个里程碑一起做**(合计 6-9 天),这样同一个接口调用在两个 backend 上同时被证明。它们是两个 backend 里最便宜的转换,而且**它们就是整个机制本身**。
|
||||
|
||||
### 6.6 strangler 顺序(风险最小化),每步的门
|
||||
|
||||
```
|
||||
0a getter 移出(AdvertisedLimitsScenario,6 个测试;严格 no-op)
|
||||
0b 字节/调用计数器落地 ← 树里今天没有任何 per-frame 字节度量
|
||||
0c 清工作树 per-draw fprintf(DirectGLES.cpp:290-303、Managers.cpp:875-877)
|
||||
0d handle 基建:slot 分配器 + registry 变数组 + 删 TwinLookupMemo/OwnerEquals/g_fbSlotCache/GC
|
||||
1 渲染状态(两个 backend 一起) ← 机制证明,最便宜的面
|
||||
2 buffer + BufferBackendOps ← 泛化已存在的模式;不碰 AcquirePersistentMap
|
||||
3 VAO / vertex elements
|
||||
4 framebuffer(**在纹理之前**) ← 它发布四个派生 mask
|
||||
5 纹理 / sampler / image unit ← 最大;删除量也最大
|
||||
6 program + constant buffer ← 需要 4 与 5 才能退役陈旧性判定的 4-6、8-9 条
|
||||
7 XFB + query + 回读 ← 与 5/6 并行(第二个工程师)
|
||||
8 emulation
|
||||
9 删 pull 路径;纯度门转绿
|
||||
```
|
||||
|
||||
**framebuffer 必须在纹理之前**(D-B3)。**0b 必须在任何迁移之前**:所有 ring 尺寸、批处理阈值、render-state wire 粒度决策否则都是猜测。**0c 必须在基线之前**:那两处 per-draw `fprintf` 污染每一次测量,而 `Feat/CS-Delta-IPC` 的 `d96be9f3` 提交过同类东西,导致该分支上**每一次**测量都跑在每 draw 一次 stderr 写的构建上。
|
||||
|
||||
### 6.7 A/B:旧路径怎么保留
|
||||
|
||||
```
|
||||
MOBILEGL_PIPE_PUSH = <子系统位图> # 0 = 全 pull;每位一个子系统
|
||||
MOBILEGL_PIPE_VERIFY = 0|1 # 影子比对(~5-10x 慢,永不出货)
|
||||
MOBILEGL_PIPE_STATS = 0|1 # 字节/调用/roundtrip/纹理拉取计数器
|
||||
```
|
||||
|
||||
在 init 时刻锁存,与 `MOBILEGL_BACKEND_TYPE` 完全同一套机制(`ConfigLoader.cpp:212-225`:一个 `Config` 字段 + 一行 `QueryEnvUint32`),并与树里已有的 ~40 个 `MOBILEGL_*` 开关并列(`Config.h:70-303`,其中已有多个是运行时路径切换:`MOBILEGL_ESPRYT_DISABLE_UPLOAD_RING` `:186-191`、`_UBO_RING` `:177-180`、`MOBILEGL_ESPRYT_MULTIDRAW_MODE` `:237-241`)。
|
||||
|
||||
**pull 路径一直编译在里面直到 P13**,所以:
|
||||
|
||||
- **任何一次提交都能在同一份二进制上按子系统 A/B**,两个 backend 都行。这比整后端级开关细得多。
|
||||
- 设备回归可以二分到"哪个子系统"而不只是"哪个提交"。
|
||||
- trace 工装本来就有 per-case 行为开关的先例(`TRACE_COHERENT_AS_FLUSH` → `--coherent-as-flush`,`run_trace_case.cmake:26-29`),`--pipe-push` 照抄那三行。
|
||||
|
||||
**P13 删除 pull 路径时**:删 `SnapshotFromGLContext()`、`MGB_CTX` 宏、`MOBILEGL_PIPE_PUSH`(推送成为唯一路径),**保留 `MOBILEGL_PIPE_VERIFY` 的工装**给后续工作;`static_assert(sizeof(ResidualValueBlock) == 0)` 必须编译通过;纯度门(§4.7.2)转绿。
|
||||
@@ -0,0 +1,249 @@
|
||||
## 7. backend → frontend 反向通道
|
||||
|
||||
这是历次评审对任何薄 backend 设计的中心反对意见,所以逐条处理,**不做概括**。实测:`grep -rnoE "(->|\.)(SetBackendResource|SetBackendHashMemo|SetBackendStateMemo|SetBackendAuxMemo|WritebackFromBackend|MarkGpuWritten|MarkStorageDirty|AllocateStorage|SetInternalFormat|UpdateMipmapSubData|EnsureGpuResidentStorage|SyncPersistentMappedRange|SyncGpuWrites|RecordError|InvalidateCompileEnv|TruncateMipmapLevels|SetSamples)\(" MG_Backend/` = **95 个调用点 / 17 个方法**,外加 6 处 backend 反向进 `MG_Impl`。
|
||||
|
||||
### 7.1 `MGPipeCallbacks`:把反向通道具名化(对 gallium 的偏离 D8)
|
||||
|
||||
```cpp
|
||||
// MG_Pipe/MGPipeCallbacks.h —— context_create 时安装;monolith 里是直调,split 里是记录
|
||||
struct MGPipeCallbacks {
|
||||
void (*on_gl_error) (Uint32 code);
|
||||
void (*on_gpu_written) (MGPipeHandle res, Uint rangeCount, const MGPRange*);
|
||||
void (*on_buffer_writeback) (MGPipeHandle res, Uint64 off, MGPBlobRef bytes);
|
||||
void (*on_texture_writeback) (MGPipeHandle res, const MGPBox*, MGPBlobRef bytes);
|
||||
void (*on_texture_pull_request) (MGPipeHandle res, Uint16 target, Uint16 firstLevel, Uint16 levelCount);
|
||||
void (*on_mip_levels_generated) (MGPipeHandle res, Uint16 base, Uint16 count);
|
||||
void (*on_surface_changed) (const MGPSurfaceInfo*);
|
||||
void (*on_caps_invalidated) ();
|
||||
void (*on_log) (Uint8 level, const char* text);
|
||||
};
|
||||
```
|
||||
|
||||
gallium 没有 shadow writeback、GPU-write 通知、纹理重发请求、default-FB 几何这些词汇——因为在 Mesa 里 state tracker 与 driver 共享地址空间。**把它们具名化为 9 个回调,好过藏在 95 个 poke 点里。**
|
||||
|
||||
### 7.2 95 个写回点的逐族归属
|
||||
|
||||
| 族 | n | 变成什么 |
|
||||
|---|---|---|
|
||||
| `SyncPersistentMappedRange` | **20** | **作为反向调用彻底消失。** 每一处都紧挨着一次对客户端字节的 CPU 读,而那些读全部搬到了 client(§5.8);**tracker 在填 `MGHostSpan` 之前**做同一次 reconcile。**这是整份设计里最大的一处结构性简化**,而且它在 monolith 里也是净改进——今天这 20 处是 backend 在 draw 中途回头调前端 |
|
||||
| `MarkStorageDirty` | **18** | 16 处是 server 本地记账("我上传了这个 level")——**零消息**,因为 dirty 归属反转(§7.3)。2 处 `true`(`Managers.cpp:2813`、`DirectGLES.cpp:6852`)变 `on_texture_pull_request` / `on_texture_writeback` |
|
||||
| `AllocateStorage` | **8** | 6 处是 **backend 凭空造出来的前端对象**(Magma 的占位纹理、`SwapchainObject` 的 default-FBO 颜色/深度/模板占位,`SwapchainObject.cpp:284, 305, 329`)→ **server 原生,永不上线**;1 处是生成 mip 的 shadow(`DirectGLES.cpp:6261`)→ `on_mip_levels_generated`;1 处是 swapchain 尺寸变更 → `on_surface_changed` |
|
||||
| `WritebackFromBackend` | **8** | `MGPReplySlot`(回读)+ `on_buffer_writeback`(XFB 捕获、PBO 回读)。**必须按操作级批处理**:其中两处今天在循环里**逐行**写回(`Utils.cpp:2342`、`DirectGLES.cpp:7633`),绝不能变成"每扫描线一次 IPC" |
|
||||
| `SetInternalFormat` | **7** | 与 `AllocateStorage` 同批:server 原生或 `on_surface_changed` |
|
||||
| `SyncGpuWrites` | **6** | 同 `SyncPersistentMappedRange`:变成 tracker 发射前的 reconcile |
|
||||
| `MarkGpuWritten` | **6** | client 在每个 draw/dispatch 发射点**保守自建**,镜像 `DirectGLES.cpp:459-467, 509, 1809` 与 `UniformManager.cpp:1073, 1229`、`VulkanRenderer.cpp:11210` 的输入(client 全都有)。`on_gpu_written{res, ranges[]}` 是**收窄**通道——因为 server 拥有描述符解析,它能比今天"任何绑了 SSBO 的 draw 一律置位"**更精确** |
|
||||
| `RecordError` | **6** | `on_gl_error`,**必须对命令流有序**(§7.4) |
|
||||
| `SetBackendResource` | **4** | **删除。** server 拥有资源表;client 只留 `{slot, gen}`。`resource_destroy` 取代由 `~BufferObject` 驱动的 `OnDestroy`;pooling / 延迟释放(`Managers.cpp:1271-1300`、`VkBufferManager::OnResourceDestroyed`)原样搬到 server 侧 |
|
||||
| `EnsureGpuResidentStorage` | **3** | server 本地决策(`map_persistent` 的档位在 IPC 期决定,§8.3) |
|
||||
| `SetBackendHashMemo` / `SetBackendAuxMemo` | **3** | 纯值 → server 侧 per-slot 字段(Magma 的 `VaoDrawMemo` 已经在镜像其中两个) |
|
||||
| `InvalidateCompileEnv` | **2** | `on_caps_invalidated`,context 重建时,低频 |
|
||||
| `SetBackendStateMemo` | **1** | **直接删除,不翻译**(D12:前端对象里的后端堆裸指针,无 wire 对应物) |
|
||||
| `UpdateMipmapSubData` / `TruncateMipmapLevels` / `SetSamples` | **3** | 全在 Magma 的占位纹理里 → server 原生 |
|
||||
|
||||
**6 处 backend 反向进 `MG_Impl`:** 四处 `pDefaultFramebufferInfo` 身份比较(`DirectGLES.cpp:1917, 2838, 2867, 9675`)→ 保留 handle `{0,1}` + `MGPFramebufferState::isDefault`;`SwapchainObject.cpp:276-330`(backend **创建** default FBO 的三张 `ITextureObject`)→ `on_surface_changed{extent, colorFormat, depthFormat, stencilFormat}`,client 自己合成对象——**顺带删掉 monolith 里的一处分层倒置**;`VulkanRenderer.cpp:10700`(`CopyTextureImageToClientOrPBO_State`,唯一一处真正无法 handle 化的调用)→ `get_texture_image` 返回 **"该 level 无 GPU 背书,请从你自己的 shadow 回答"**(`:10691-10704` 今天测的正是这个条件),client 跑它本来就拥有的 pack/convert 路径。
|
||||
|
||||
### 7.3 纹理 dirty 归属反转
|
||||
|
||||
**client** 保留 `MipmapStorage` 的模型(96-rect 级联合并 + `summedArea*4 >= unionArea*3` union-box 回退,`MipmapStorage.cpp:300-305`),维护一份**逐 `(texture, uploadTarget, level)` 的发射游标**,在发射后清自己的标志。**server 从不碰 client 的标志。**
|
||||
|
||||
这是安全的,且已核实:**`MG_Impl` 里没有任何 `IsStorageDirty(` / `GetStorageDirtyRects(` / `GetStorageDirtyRegion(` 调用点**(前端从不读自己的 dirty 状态),而它自己在五处主动清(`GL_Texture.cpp:528, 701, 5547, 5621, 5691`)。
|
||||
|
||||
**这一条删掉 `PLAN.md` §5.6a 的整个 ack 协议与风险 R6。**
|
||||
|
||||
**但上传形状决策留在 server**:`resource_subdata` 同时带 union box 与 rect 列表(§4.5.6),Mali 按作业数计价的 +6ms/frame 悬崖(`Managers.cpp:4311-4319`)在哪一侧付 GPU 代价,决策就留在哪一侧。
|
||||
|
||||
### 7.4 反向通道的有序性是正确性要求,不是优化
|
||||
|
||||
**`on_buffer_writeback` 必须与 epoch bump 有序。** 今天每一次 `WritebackFromBackend` 后面都紧跟一次 `BumpBufferMutationEpoch()`(`DirectGLES.cpp:834-837, 942, 7625-7629`),因为写回会 bump client 的 change serial 而没有对应的 op,否则 server 自己的 draw-clean memo 会在 epoch 背后变陈旧。split 里这变成**反向通道上的一条排序规则**:一次写回的 epoch bump 必须在任何后续读该 handle 的命令之前被 server 侧应用。**反向通道需要与正向通道相同的有序保证。**
|
||||
|
||||
**`on_gl_error` 必须对命令流有序**,否则 `glGetError` 答错。分配类入口(`glRenderbufferStorage*`、可能失败的 `glTexImage*`/`glTexStorage*`/`glCopyTexImage*` 形式、`glBufferStorage`)带 `kNeedsAck`,让 OOM 探测惯用法(`allocate; if (glGetError()==GL_OUT_OF_MEMORY) 用更小的重试;`)成立;其余晚到。`glGetError` 本身永远本地(`GL_Getter.cpp:2811-2817`;不变式 `Core.cpp:48-49`)。
|
||||
|
||||
**对 `PLAN.md` §7.4 的强制修正:`on_log` 必须按严重级分级。** `PLAN.md` 把**全部** `EvLogLine` 设为有损(覆盖最旧 + `eventDropped`)。但 §5.7 已经确认:**backend program link/compile 失败只以一行日志加一次 bind-program-0 的空 draw 呈现**,没有 GL error、没有前端变更、`GL_LINK_STATUS` 永不撤回。在统一有损策略下,系统里诊断价值最高的那一行会在日志压力下静默消失。
|
||||
|
||||
**规则**:`on_log(level ≤ WARN)` 有损(`eventDropped` 计数);**`on_log(level ≥ ERROR)` 无损**,加入触发 `eventRingFull` + 停止 apply 的语义事件集。为了不让这条重新引入 §7.4 本来要防的死锁,再加一个**每秒 ERROR 速率限制器**,超限时发一条显式的 "N errors suppressed"。`MGLOG_E_ONCE` 的 latch 变成 per-server,这正是想要的行为。P9 的故障注入门:日志洪泛下注入一次 link 失败,那行 ERROR 必须出现。
|
||||
|
||||
### 7.5 唯一的新停顿类:server 发起的纹理重铸拉取(D-B6)
|
||||
|
||||
server 不保留纹素字节,所以三个原因会要求 client 重发已发过的 level:`RequireImageBindableStorage` 的 re-dirty(`Managers.cpp:2813`)、整格式再生(`:3950-4195`)、view 源重铸(`:3616-3707`)。**上一轮薄 server 设计正是因为把这条一笔带过而被判死。三条缓解同时上,加一个专门的门和一个必须发布的计数器:**
|
||||
|
||||
**(a) 预防主因。** client 给纹理打 `everImageBound` 标记,`resource_create`/`respecify` 一直携带 `imageBindableHint`(`MGPResourceDesc`),于是 image-bindable 存储在前期就分配好。这把 `RequireImageBindableStorage` 从稳态里彻底移除。
|
||||
|
||||
**(b) 拉取是异步的。** server 发 `on_texture_pull_request{res, target, levels[]}` 并把那个 twin **标为 not-ready**;client 在下一次 publish 时重发。因为 client 跑在前面,常见情况下字节在 server 到达采样该纹理的 draw 之前就到了;即使没到,**阻塞的是 `mgl-srv-apply` 线程,不是应用线程**——这是一个应用没有发起的停顿应该待的地方,也严格好过 monolith 里阻塞应用线程的行为。
|
||||
|
||||
**(c) 有上限的保留。** 可选的逐纹理保留位,受一个**显式的 LRU 字节预算**约束(默认 32MiB,`MOBILEGL_PIPE_TEXEL_RETAIN_MB`),使一张被拉过一次的纹理永不第二次停顿。
|
||||
|
||||
**(d) 门与计数器。** 新增 `TextureRemintPullScenario`:同时强制 `RequireImageBindableStorage` 与一次帧中格式再生。**拉取次数逐 trace 用例发布**,与 SSIM 并列。**本设计从不声称"零 round trip",它测量并公布。**
|
||||
|
||||
若在真实语料(MC 与 Iris fixture)上实测拉取率非平凡,(c) 从可选升级为强制并拿到真预算。
|
||||
|
||||
---
|
||||
|
||||
## 8. 传输、数据面、同步、present、线程、平台、构建
|
||||
|
||||
### 8.1 原样继承方案 A 的部分
|
||||
|
||||
以下全部**逐条继承 `PLAN.md`,本文不复述**。它们是传输/平台/节奏/构建机制,与状态模型无关,且已经过对抗性评审:
|
||||
|
||||
| `PLAN.md` 章节 | 内容 |
|
||||
|---|---|
|
||||
| **§6.1** | 段布局(`SEG_CMD` 8MiB / `SEG_STAGE` 32MiB↑ / `SEG_REPLY` 8MiB / `SEG_EVENT` 256KiB / `SEG_SHADOW[n]` / `SEG_ADOPT[n]`);shm 创建矩阵(`ASharedMemory_create` API 26 / `SYS_memfd_create` / `shm_open` / `CreateFileMappingW`);**`SCM_RIGHTS` 必须在第一个 transport commit 里实现**(asio 无 cmsg API → 在 `socket.native_handle()` 上裸 `sendmsg`/`recvmsg`,~80 行;`Feat/CS-Delta-IPC` 把 `out->fd = -1` 硬编码在 `LocalSocketTransport.cpp:296`,它的数据面在唯一重要的平台上一个字节都没过去);`SEG_SHADOW` 块的 pending free-list 退休规则 |
|
||||
| **§6.2 / §6.2a** | `RingControl`:两组独立游标三元组、三个不同的 seq 水位(`appliedSeq`/`submittedSeq`/`retiredSeq` + `completedFrameSerial`/`presentAckSerial`)、`serverEpoch`、`ringGeneration`、`consumerParked`/`producerParked`、`eventRingFull`/`eventDropped`;**双向 doorbell**,`MOBILEGL_IPC_SPIN_US` 默认 50µs,`inproc` 用 condvar。没有这条,每一次 client 等待都退化成跨进程自旋一条共享 cache line,在手机上就是一颗大核满频空转,而本库全无亲和性控制 |
|
||||
| **§6.3** | 记录格式:8B `RecHeader`、24B `BlobRef`、**无 per-record 序号**、X-macro 每种一条 `static_assert` **加**生成的运行期边界检查 → `Fatal{ProtocolCorruption}`、`kVarTail` 自描述长度自洽校验。方案 B 把这套机制扩展到**全部** MGPipe 调用(G3) |
|
||||
| **§6.4** | WAR 纪律:调用时刻拷进 ring slot(P1-4);P4.5 的 `SEG_SHADOW` 零拷贝 + 逐 shadow 64KiB 块发送水位 |
|
||||
| **§6.5** | ring 分配与背压:逐字移植 `PersistentRing`(`Managers.cpp:641-727`、`RingAllocateSlow` `:1891-1970`、`RingOnPresent` `:1975-2016`),升级路径 扩容 → 走 doorbell 的有界等待 → 硬 drain + `ringGeneration` bump |
|
||||
| **§6.6 前三条** | unpack PBO 完全在 client 解析;压缩 internalformat 永不到达 backend;`glCopyTexSubImage*` 与 `glClearTexImage` 整体留在 client |
|
||||
| **§6.7 第 2、5 行** | PBO 回读改 fire-and-forget(**严格优于 monolith**,后者无条件停等,`DirectGLES.cpp:9189-9205`);`glEndTransformFeedback` 的无限 `ClientWaitSync`(`GL_Drawing.cpp:1326-1337`)推迟到首次读 |
|
||||
| **§6.8** | persistent map 与 ≥16MiB 采纳的三档,**由运行时 POST 探针选择,绝不硬编码驱动名** |
|
||||
| **§7.1** | FlatBuffers 纪律:热路径 `struct` 进 ring、罕见/变长 `table` 走 socket;`protocol_generated.h` 提交;`gen_protocol.py` + CI `flatc-check`;**默认构建图里没有 `flatc`**(`Feat/CS-Delta-IPC` 的 NDK 陷阱本体) |
|
||||
| **§7.2** | 帧封装(`MGLF`、64MiB 上限、读时校验、缓冲不足返回所需大小**且保留消息**);publish 触发器(每记录 release-store `cmdHead`、显式门铃点、`SEG_STAGE` 余量 < 1/4、**轮询入口也是门铃点**、`GL_SYNC_FLUSH_COMMANDS_BIT` 无条件 publish、`MOBILEGL_IPC_POLL_ESCALATE` 饥饿升级);**`glFinish`/`glFlush` 保持免费**(`Definitions.cpp:111-112`) |
|
||||
| **§7.3** | 两个互相独立的窗口(字节 credit、present credit);server 不发 credit 消息,只做 release store + 反向门铃 |
|
||||
| **§7.4** | 事件 ring + 排空点 + 溢出策略(等待循环内必须排空;语义事件无损,满时 `eventRingFull` + 停在记录边界停止 apply)。**加上 §7.4 的分级修正** |
|
||||
| **§8 末尾** | fence 完成度必须来自**真的逐 fence 退休**,不是 present 水位(`DirectVulkan.cpp:1120-1128` 记录这是被修掉的 bug;`magma-mc1215-fence-oom` 记录它曾导致 native-heap OOM kill);三个应先独立落 `dev` 的 monolith 修复 |
|
||||
| **§9 / §9.1 / §9.2 / §9.3** | `Present` 与 `eglSwapBuffers` 严格 1:1、绝不批量(Magma 的四次 `OnFrameBoundary`、`TryDrainFrameTransients` 与全部四次 `BeginFrame` 只在 `Present` 内发生,`VulkanRenderer.cpp:12765-12904`;Espryt 在那里 retire 三个 ring 与 `TrimBufferPool`,`DirectGLES.cpp:10646-10649`);`MOBILEGL_IPC_PRESENT_CREDIT` **默认 1** 与延迟叠加公式;Magma 从不注册 `SetSwapInterval`(`BackendObject_DirectVulkan.cpp:698`)所以 IPC credit 是它唯一的显式限帧器;DirectGLES 的非 present fence tick |
|
||||
| **§10** | 线程模型:v1 不加 client 线程、flow = per context、外来线程的 sync/query 从 `RingControl` acquire load 回答、`ShaderCompilePool` 留 client、修 `EGLOperationMutex` 的两个漏洞;server 的 `mgl-srv-io` + `mgl-srv-apply`(终身持有原生 context);核心放置与 `MOBILEGL_IPC_SERVER_AFFINITY`、**报逐线程 CPU 时间**;拆机顺序 |
|
||||
| **§11.1-§11.6** | 启动与握手(`MOBILEGL_IPC_SERVER_PATH` 为主 + `dladdr` 兜底;socketpair + fork/execve;**显式 envp 剔除 + `mobilegl_server_main` 内强制 Monolith** 的双保险);`extern "C" visibility("default")` 与 `nm -D` 门;Android 的 `android:process=":mgl"` Service 路径(minSdk 26 无公开 `ANativeWindow` 扁平化);X11 XID;`EGL_PLATFORM=surfaceless`;Windows overlapped named pipe;崩溃时的 device-lost latch |
|
||||
| **§12 第 1-3 层 / §12.4** | 编译期折叠(`MOBILEGL_BUILD_DISAGGREGATED` 默认 OFF);**唯一 hook 点** `MG_Backend/Init.cpp:48-70`,下游 ~152 个边界调用点零 `#ifdef`;P4.5 的 allocator 改动整段包裹;`MOBILEGL_TRANSPORT` 复用全部既有开关通道(ctest `ENVIRONMENT`、trace-replay 的 `setenv` 块、FCL 用户 env、plugin APK V2 开关表、`/data/local/tmp` CTS) |
|
||||
| **§13** | 目录形状;`MobileGLServer` 作为改名成 `lib*.so` 的 `add_executable` 链接**共享**的 `MobileGL`(一份库两个角色,版本必然匹配);FlatBuffers submodule 的 `EXISTS` 保护 **加** include-dir guard;ctest/trace-replay 的三个陷阱(`ENVIRONMENT` 是替换而非追加、`;` 转义、property 覆盖 job env);`SPLIT` 后缀与 `-DTRACE_TRANSPORT=`;CI 的 `flatc-check` 与 `fprintf` grep 门 |
|
||||
| **§14** | 对 `Feat/CS-Delta-IPC` 的 REUSE / CHANGE / DROP 判定(本文 §14 只列差异) |
|
||||
| **§15 P0** | 卫生清单与两个 spike,尤其是**两侧的 `TracyPlot` 字节计数器** |
|
||||
|
||||
### 8.2 与方案 A 的差异
|
||||
|
||||
**删除:**
|
||||
`Server/ReplicaContext.{h,cpp}`(换成 `Server/PipeObjectTables.{h,cpp}`:POD 记录的 slot 数组,不是状态模型);§5.0 的"replica vs 重写"决策;§5.1 的三步发射协议;§5.2;§5.4 的 replica 对象表规则与 `Fatal{IdentityDivergence}`;§5.6a 的纹理 ack 协议;§5.7 的 Phase 1-4 composite 分支;§5.9b 与整个 mutation 覆盖生成器(`gen_impl_mutation_surface.py`、`MutationCoverage.def`、`ImplMutationSurface.inc`、`MG_Remote::Shared::` helper 族);§6.9 的 relink 档与 `MOBILEGL_IPC_PROGRAM=publish|relink`;§6.4 的拷贝第 (3) 行;§12.2 的 `pGLContext` shim;阶段 **P5**(6 天回收);风险 **R1** 与 **R6**;开放问题 **§17-5**。
|
||||
|
||||
**改变:**
|
||||
|
||||
| `PLAN.md` § | 差异 |
|
||||
|---|---|
|
||||
| §5.9a | READ 面的**编目**生成器变成**禁止**门(§4.7.2):不是"每个读都映射到某个 delta 类",而是"这次读根本编译不过"。原 477 行 inventory 保留为 tracker 侧覆盖检查表(G6) |
|
||||
| §6.4 拷贝账 | 第 (3) 行 `SEG_STAGE → replica shadow` 不存在:**P1-4 = 3 次,P4.5 = 2 次**。`PLAN.md` 自己的"方案 B"目标(第 549 行,被它标为"激进、需额外设计"并推到 P6)**按结构达成**,开放问题 §17-5 自动关闭 |
|
||||
| §6.6 第 4 条 | 逐 level `serverAuthoritative` 位被 dirty 归属反转(§7.3)+ `on_texture_writeback`(一个生产者:CPU 生成 mip 路径;CopyImage 镜像已搬到 client 而消失)+ `on_texture_pull_request` 取代 |
|
||||
| §6.9 | `RecProgramLinkOp` **不可能**(§5.7)。`ProgramPublish` 第一天;`reflectionDigest` 从"分歧预言机"换成"schema 完整性绊线";P5 消失,其副产品(内部 shader 烘焙)升级为 Magma 阶段的前置条件,`nm -D | grep glslang` 为空成为验收判据 |
|
||||
| §5.10 | 第 2、3 条**逐字继承**(client 侧块粒度 persistent 推送、`PersistentCoherentMapScenario` 作为门,**R2 仍是最高优先级正确性项**)。第 1 条从"完整 map 状态复制"缩成**一个推送的 `hasLiveHostWrites` 位**——因为 replica 的 `SyncPersistentMappedRange` 与 `IsBufferDrawClean` 的 `IsMapped()` 门(`Managers.cpp:1447`)在 server 侧都不存在 |
|
||||
| §6.10 | 四类应用指针由 §5.8 的 cap 门控 lowering 处理;`ClientArrayBounds` 变成 `MGPDrawInfo::minIndex/maxIndex`。**陈旧索引纪律(§5.8.1)一字不改地保留并加门** |
|
||||
| §7.4 | `on_log` **按严重级分级**(§7.4),加每秒 ERROR 速率限制器 |
|
||||
| §12.2 | 需要角色隔离的进程全局从 **4 个降到 2 个**:`MG_State::pGLContext` 整个退出(server 不托管 `GLContext`,因此跨越 `MG_Impl` 1494 个站点的 `operator->` shim 与 Android dlopen TLS 论证一起消失);`pDefaultFramebufferInfo` 变成接口输出(§7.2)后也退出。只剩 `gBackendFunctionsTable`(在方案 B 里是 `gPipeCtx`)与 `pActiveBackendObject`。**这实质性降低 R11 的风险,并让 `inproc`——最早的证伪门、且完全不需要跨进程工作——便宜到可以提前跑** |
|
||||
| §13 | `MG_Pipe/` 是**默认构建里的非可选目录**(它是 monolith 的架构);只有 `MG_Remote/` 在 `MOBILEGL_BUILD_DISAGGREGATED` 之后 |
|
||||
| §15 | **在 P1a 之前新增一整段 backend 推送改造**。`PLAN.md` 把这块工作定价为"~0 逻辑改动";在方案 B 里它是工作量主体,并有它自己的 monolith A/B(§10.3) |
|
||||
|
||||
**新增:**
|
||||
|
||||
- **`SEG_STAGE` 尺寸必须额外容纳四类它以前不承载的字节**:client 顶点数组、client 索引数组、multi-draw 参数块、client 解析后的 indirect 命令块。**字节体量不变**(它们今天就在每 draw 被重新上传,`glBufferData(..., GL_STREAM_DRAW)`,`Managers.cpp:~2578`),但现在这些字节要过一个 ring slot。上限由 P0 落地的计数器实测定,不用默认值猜。
|
||||
- **新事件种类**:`on_texture_writeback`(CopyImage 镜像搬走后只剩一个生产者:CPU 生成 mip 路径 `DirectGLES.cpp:6811-6861`)、`on_texture_pull_request`、`on_mip_levels_generated`。`on_buffer_writeback` 从"优化"升级为**承载语义**。
|
||||
- **新环境变量**:`MOBILEGL_PIPE_PUSH`、`MOBILEGL_PIPE_VERIFY`、`MOBILEGL_PIPE_STATS`、`MOBILEGL_PIPE_TEXEL_RETAIN_MB`(见附录)。
|
||||
- **`RenderbufferObject::GetLifetimeId()`**(今天没有)。**但不需要 `GetVersion()`**——`PLAN.md` P0 要求两个,`GetVersion()` 只是 replica 的 delta 触发器;在推送模型里 `glRenderbufferStorage*` **本身就是**一次 pipe 调用,不需要触发器。
|
||||
|
||||
### 8.3 persistent map:唯一被显式隔离的传输相关决策
|
||||
|
||||
`AcquirePersistentMap`(`BufferObject.h:112`)是**永久的地址空间捐赠**(D4/D-B4)。**它原样穿过 monolith 改造(P0..P13 一动不动),只有 IPC 那一步才打破它。** 决策路径:
|
||||
|
||||
- **P0 的 spike B 在第一周给方向**:导出 `HOST_VISIBLE|HOST_COHERENT` VkBuffer 的 fd,client `mmap` 后回读,在 `35d0befa`(Adreno 830)与 `3B159D009VZ00000`(Mali)两台上跑。
|
||||
- **T2(拒绝,永久正确的回退)**:返回 `nullptr`,前端已在三处容忍(`BufferObject.cpp:174, 439-442, 470-472`)。**此档下 `PLAN.md` §5.10 的 client 侧块粒度推送是强制的**,由 `PersistentCoherentMapScenario` 把门。
|
||||
- **T1(server 导出自己的映射)**:每 store 生命周期一次 round trip;采纳成功后推送自动停止(`IsGpuResident()` 早退),与 monolith 一致。
|
||||
- **T0(server 导入 client 分配)**:理想但可用性未知。
|
||||
|
||||
若两台设备都否,IPC 期的该阶段从 8 天缩为 2 天的文档与负面对照,代价记录在案。**绝不允许一个平台未知数挡住 200 天的接口工作。**
|
||||
|
||||
---
|
||||
|
||||
## 9. Roundtrip 清单与稳态零 roundtrip 论证
|
||||
|
||||
### 9.1 稳态零 roundtrip 的项
|
||||
|
||||
| 类 | roundtrip | 依据 |
|
||||
|---|---|---|
|
||||
| 全部 draw、clear、blit、copy、dispatch、barrier、XFB 跨度标记、全部 bind、全部 CSO create/bind、全部 `set_*`、全部 buffer/texture 上传、`present` | **0** | 单向记录;present 只查 credit |
|
||||
| **全部 89 个 caps 站点**(40 `pActiveBackendObject->` + 全部 `glGetIntegeri_v` + `IsTimerQuerySupported` + `PrefersCpuXfbPrimitiveAccounting` + `BeginOcclusionQuery != nullptr` 能力探测) | **0** | 首次 `MakeEGLCurrent` 的一次 `MGPCaps` 快照。caps 只在那一刻才存在(`BackendObject.cpp:341-347`,每次 surface 变更重新武装 `:301`);`callMask` 精确复现 DirectVulkan 少注册的槽位 |
|
||||
| `glGetError` / `glFinish` / `glFlush` | **0** | 前者永远本地(`GL_Getter.cpp:2811-2817`;不变式 `Core.cpp:48-49`),后两者是彻底的 no-op(`Definitions.cpp:111-112`)**且必须继续免费** |
|
||||
| fence 与 query 的**创建**,以及每一次**非阻塞轮询**(`GetSyncStatus`、`ClientWaitSync(0)`、`IsQueryResultAvailable`、`GetQueryResult64(wait=false)`) | **0** | handle 由 client 铸造(`GL_Sync.cpp:61` 今天就把前端堆对象 reinterpret 成 `GLsync`;`GL_Query.cpp:50-54` 铸造 id);未命中合法地答 `GL_UNSIGNALED`/"未就绪",两处契约明说(`BackendObject.h:210-214`、`:236-241`),而前端已经遵守(`GL_Query.cpp:302-311`:读 0、**不缓存**、保留 handle) |
|
||||
| `glGetTexImage` / `glGetTextureImage`(**DirectGLES**) | **0** | client shadow 回答(`CopyTextureImageToClientOrPBO_State`,`GL_Texture.cpp:5368-5420`,取用点 `:6460`) |
|
||||
| `glReadPixels` → pack PBO | **0** | fire-and-forget + client 侧 `MarkGpuWritten`。**严格优于 monolith**,后者无条件停等(`DirectGLES.cpp:9189-9205`) |
|
||||
| `glEndTransformFeedback` | **0** | 取消无限 fence 等待(`GL_Drawing.cpp:1326-1337`),改为对 capture target 置 `MarkGpuWritten` |
|
||||
| `eglSwapBuffers` | **0 次阻塞 round trip**,一次非阻塞 credit 检查 | 只有 `presentsSent - presentAckSerial >= MOBILEGL_IPC_PRESENT_CREDIT`(默认 1)时才阻塞 |
|
||||
|
||||
### 9.2 不可避免的阻塞点(全部罕见,逐条给理由与缓解)
|
||||
|
||||
| # | 站点 | 为什么不可避免 | 缓解 |
|
||||
|---|---|---|---|
|
||||
| 1 | 握手 `Hello`/`Welcome` + 段 fd 传递 | — | 一次 |
|
||||
| 2 | `InitializeEGLDisplay`(写 `major`/`minor`)、`Create/Resize EGL*Surface`、首次 `MakeEGLCurrent` + `InitCapabilities` | 出参 / 返回 `Bool`;caps 只在那一刻存在 | 每 surface 至多一次;surface 回复顺带 `MGPSurfaceInfo`(**同时删掉 `SwapchainObject.cpp:276-330` 往前端对象里的写**)。`SwapEGLBuffers` 不需要回复:它的线程归属校验对 client 镜像的 EGL 状态求值(`BackendObject.cpp:365-393`) |
|
||||
| 3 | `glReadPixels` → 客户内存 | GL 要求返回时字节已就位 | 像素进 `SEG_REPLY` slot;**逐行写回循环留在 server 内,按操作级批成一段** |
|
||||
| 4 | `glGetTexImage`/`glGetTextureImage`(**DirectVulkan**) | Magma 对只存在于 GPU 的 level 没有 client 可答的 shadow | `get_texture_image` 对"无 GPU 背书"的 level 返回"请从你的 shadow 回答"(`VulkanRenderer.cpp:10691-10704` 今天就在测这个条件),所以只有真正 GPU-only 的 level 付钱 |
|
||||
| 5 | GPU-write pending 的 buffer 首次 CPU 读(`glMapBuffer*`、`glGetBufferSubData`、`glGetNamedBufferSubData`、`glCopyBufferSubData` 源、`FillSubData`) | shader 在前端背后写了 store | monolith 里**本来就阻塞**(`glFinish()`,`Managers.cpp:1246`;Vulkan `VkBufferManager.cpp:80-85` → `VulkanRenderer.cpp:9807-9817`)。client 保守 pending 集触发,由 `set_shader_buffers` 的 `writableMask` 与 `on_gpu_written{ranges}` 两侧收窄——**比今天"任何绑了 SSBO 的 draw 一律置位"更精确** |
|
||||
| 6 | `glClientWaitSync(timeout>0)`、`glGetQueryObject*(GL_QUERY_RESULT)` 未完成、`glBeginConditionalRender` | GL 定义即阻塞;`glBeginConditionalRender` 连 `_NO_WAIT` 模式也阻塞(`GL_Query.cpp:705-706`) | 全部非阻塞兄弟是 0 round trip(§9.1)。条件渲染的谓词**只解析一次**(`Core.h:387-391`),之后每个条件 draw 在 client 侧丢弃(`ConditionalRenderDiscardsCommand`,用于 `GL_Drawing.cpp:711, 740, 795`),**server 永远不需要那个 query 对象** |
|
||||
| 7 | 分配类入口的错误 ack | OOM 探测惯用法 | `kNeedsAck` 只标这一族;罕见且本来就贵 |
|
||||
| 8 | `map_persistent`(仅 T1 档) | 应用必须拿到一个不再经过任何 API 调用就能写的地址 | **每 store 生命周期一次**,不是每次使用;档位由 POST 探针选(§8.3) |
|
||||
| 9 | **server 发起的纹理重铸拉取** | server 不保留纹素 | **三条缓解 + 专门的门 + 逐用例发布的计数器**(§7.5)。异步形态下阻塞的是 `mgl-srv-apply` 而非应用线程 |
|
||||
| 10 | client 侧索引扫描 / restart 重写 / indirect-count 解析,当源 buffer 在 pending 集里 | monolith 在**同一位置**调 `SyncGpuWrites()` | §5.8.1 的 publish/wait/drain 纪律;常见情况不 pending,代价为零 |
|
||||
| 11 | ring/stage 耗尽、present credit | **节奏,非语义** | `PersistentRing` 的升级路径 + `producerParked` doorbell(不是自旋) |
|
||||
|
||||
### 9.3 论证的形式:测量,不是声称
|
||||
|
||||
**验收门措辞(`PLAN.md` §15 P3-2 的措辞加一行)**:在**全部 40 个 trace 用例**上发布**逐用例的 roundtrip 计数器与纹理拉取计数器**。**不做笼统的"零 round trip"声明。** 条件渲染与阻塞 query 的次数按用例列出而不是宣称为零。
|
||||
|
||||
轮询挂死的防护(继承 `PLAN.md` §7.2/R4)必须有它自己的门:`glFenceSync(); while (glClientWaitSync(s, GL_SYNC_FLUSH_COMMANDS_BIT, 0) == GL_TIMEOUT_EXPIRED) {}` 必须在有界时间内退出——不加 publish 规则它会永远挂住。
|
||||
|
||||
---
|
||||
|
||||
## 10. Monolith 保留
|
||||
|
||||
### 10.1 接口在进程内就是直调
|
||||
|
||||
monolith 模式下 `MGPipeContext` 用 backend 自己的函数填充,`MGPipeCallbacks` 用对 `MG_State` 的直调填充,`MGHostSpan.ptr` 指向 client 自己的 shadow(**零新增拷贝**),`MGPipeHandle` 按值走一对寄存器。split 模式下同一张表换成发射器,applier 反序列化后调**同一批 backend 函数**。**全世界只有一份 backend 实现。** 这比方案 A 的安排更强——后者两侧都跑 `MG_Impl`。
|
||||
|
||||
### 10.2 热路径的间接成本,诚实版
|
||||
|
||||
| | 今天 | 之后 |
|
||||
|---|---|---|
|
||||
| 每 verb 的分发 | 1 次间接调用(**已经在付**:`gBackendFunctionsTable.GL.DrawArrays(...)`,89 个 `MG_Impl` 站点) | 1 次间接调用 |
|
||||
| 每 draw 的状态获取 | Espryt 124 / Magma 169 次 accessor 调用 + 版本比较 + 一次 ~1.2KB 三段 memcmp + `CurrentUnitBindingsEpoch` 的逐 unit owner 走查 + Magma 的两次有损版本求和 + ~40 次 payload accessor 走查 | 1 次 dirty word 测试 + N 次 `set_*` 间接调用(稳态 N=1-3;CSO 内容寻址下重复状态 N=0) |
|
||||
| memo 查表 | 对指针位做斐波那契散列的直接映射探测 + owner 相等性 | 按 slot 的数组下标 |
|
||||
| 删除的机制 | — | **~550 行 per-draw 失效发现**(§2.5) |
|
||||
|
||||
**推送在稳态应当是严格的减少——但只因为 tracker 在 draw 时刻 validate。** 如果有人把它实现在 GL setter 时刻,它会更慢,而 trace 语料会立刻说出来(§5.1)。
|
||||
|
||||
两个诚实的告诫:
|
||||
1. **可达性遍历是搬走了,不是消失了**,所以头号指标必须是**逐线程 CPU 时间**,不是墙钟帧时。
|
||||
2. **Magma 的 `SetupDrawSnapshot` 快路径命中率在两种模式下会合法地不同**,所以 A/B 比的是**渲染输出与计数器**,永远不是 memo 轨迹。
|
||||
|
||||
两个 backend 编进同一个共享库(`CMakeLists.txt:356-383` 的源文件列表,`add_library(... SHARED ...)` 在 `:485`),backend 在 init 时锁存一次(`ConfigLoader.cpp:212-225`),所以去虚化在两种形态下都不可得,也都不需要——代价是一次已经在付的间接调用。**函数指针 struct 而非虚基类**的理由见 §4.1。
|
||||
|
||||
### 10.3 替代字节一致门的五部分验证门
|
||||
|
||||
**先把成本写在明面上**:`PLAN.md` §12 第 4 层(`nm --defined-only` + 剥调试信息后 `.text` size **相等**,且每阶段都跑)在方案 B 里**按构造死亡**——backend 停止读 `pGLContext`、`PrepareForDraw` 的遍历搬到 client、~66 个 memo 族换键、`MG_Impl` 多出 validate 调用、Magma 的两处 `MG_State` 类型内部用法被重写。**不存在任何配置能让旧字节回来。** 这是方案 B 的代价,必须写进设计文档而不是藏起来。
|
||||
|
||||
替代品是**五部分,全部在 P0/P1 落地**,这样每一条都能因它存在的理由变红:
|
||||
|
||||
**① 接口纯度门(机械,取代读点编目生成器)。**
|
||||
`grep -c 'pGLContext' MG_Backend/` == **0**(grep 的是 `pGLContext` 不是 `pGLContext->`,因为还有 58 行非箭头用法,§2.4);`MG_Backend` 只允许 include 一张共享**值**头白名单(今天是 50 行 include / 18 个不同 `MG_State` 头);`nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空;**外加**一条 debug 断言"每个 backend memo 键都是 `{slot, gen}` 对,永不是裸前端指针",由 `HandleRecycleScenario`(删除并重建对象、跨 draw 边界复用同一个 GL name)支撑——**这个场景在 0d 重键之前必须在至少一个 backend 上是红的**,否则它没在测任何东西。
|
||||
|
||||
**② 语义影子比对(`MOBILEGL_PIPE_VERIFY=1`)——决定性的那一条。**
|
||||
阶段 B 期间两套状态模型活在同一个地址空间:tracker 再用 `SnapshotFromGLContext()` 填一份 `PipeInputs`,G4 生成的比对器**逐字段**、**每 draw** 与推送版本比对,打印第一个分歧字段名与 draw 序号。它抓三种事:(a) tracker 忘了推的字段;(b) **dirty 位触发得太少**——危险的那个方向;(c) 两条路径上被变换得不一样的值。作为第三种 CI 模式跑全部 40 个 trace 与 367 个集成测试;~5-10× 慢,永不出货。
|
||||
**必须逐字段比而不是 `memcmp`**:`DirectGLES.cpp:2029-2033` 明确记录 `RenderStateParameters` 的 memcmp 会因 padding 字节 false-DIFFER(无害)但永不 false-match——比对器要的是零误报。
|
||||
**这是历次评审在每一个候选设计上指出的那个缺失,而它只有在接口先落 monolith 时才存在。**
|
||||
|
||||
**③ 行为 A/B。**
|
||||
全部 ~40 个 trace 用例(`tools/trace_replay/trace_cases.json`,默认 SSIM 阈值 0.99;OpenRA、MC 1.17/1.21.4/1.21.11 族、15+ Iris shader pack、两个 Create fixture、`improved-transparency-minecraft-26.3`)在 `{monolith-pull, monolith-push, split}` 三种下同一判定、SSIM ≥ 0.99;`ctest -L integration-gpu` 在 `DirectGLES.` 与 `DirectGLES.Pipe.`/`DirectGLES.Split.`(以及 DirectVulkan 对)之间产生**逐名相同**的通过/失败集(367 个 `TEST_F`);428 个单元测试全绿;CTS 逐后端 conformance 在 0.5 个百分点内,按本项目的逐后端表格式上报(行 = GL 版本/扩展,列 = 状态计数,rate = Pass/(Pass+Fail),NS 不进分母)。
|
||||
**两个 Create fixture 带 `coherent_as_flush: true`**,必须在两种模式下都开着该开关跑,否则逐名对比没有意义。
|
||||
|
||||
**④ monolith 性能不回归。**
|
||||
两台设备(`35d0befa` Adreno 830、`3B159D009VZ00000` Mali),reboot-clean、同热窗口、配对 A/B,用 `tools/bench.sh` + trace replay 的 `--benchmark --benchmark-tail-frames --benchmark-result` 逐帧 JSON。**指标是逐线程 CPU 时间**(因为遍历是搬走不是消失),monolith-push 在 **p50 与 p99** 上都要落在 monolith-pull 的噪声内。CPU 定频按本项目协议(大核 1.96 / 小核 1.55GHz,GPU 拉满,40°C 门槛)。
|
||||
|
||||
**⑤ 覆盖 + poison + handle 纪律。**
|
||||
`gen_pipe.py` 重生成 477 行 inventory 的 MGPipe 映射列,0 UNMAPPED,`git diff --exit-code`;`PipeInputs::m_filledMask` poison(§6.2.2);P13 的 `static_assert(sizeof(ResidualValueBlock) == 0)`;`ResidualValueBlock` 的逐成员 `offsetof` 断言(§6.3-2)。
|
||||
|
||||
**两条字节级等式仍然幸存,仍然作为断言保留**:`MOBILEGL_BUILD_DISAGGREGATED=OFF` 时 `nm --defined-only libMobileGL.so | grep MG_Remote` 为空且链接行不增加任何库;`nm -D libMobileGL.so | grep mobilegl_server_main` 在 RelWithDebInfo 里命中(`CMakeLists.txt:497-510` 在非 Debug 下设 hidden visibility)。
|
||||
**符号与 `.text` 漂移每阶段作为信息性指标发布**——一次无法解释的跳变仍然是一个 smell,只是不再是一条断言。
|
||||
|
||||
### 10.4 monolith 侧净收益清单(即使 IPC 永不上线也成立)
|
||||
|
||||
1. **~550 行 per-draw 失效发现机制删除**(§2.5),连同运行它的每帧代价。
|
||||
2. **复用地址 ABA 一整类不可表达**:D1/D2/D3/D10/D11/D13/D14/D16/D17/D20 全部由 `{slot, gen}` 关闭。
|
||||
3. **FBO → program 排序 hazard 消失**:`DirectGLES.cpp:2712-2732` 的 fragColor 重推导 workaround 与 `g_broadcastMemo*` 删除(D-B3)。
|
||||
4. **一处分层倒置消失**:`SwapchainObject.cpp:276-330` 不再往 `MG_Impl` 的 `pDefaultFramebufferInfo` 里写。
|
||||
5. **两个潜伏 bug 顺带修掉**:D21(`m_xfbCounterSlotByObject` 用裸 GL name 做键,`VulkanRenderer.cpp:11136-11146`,删了又建的 XFB 对象会**恢复**一次本该重启的捕获)与 `RenderbufferObject` 缺 `GetLifetimeId()`。**这两条都值得先独立落 `dev`。**
|
||||
6. **一个死能力被暴露**:`CapabilityInput::FramebufferSrgb` 与 `DepthClamp`(`RenderState.h:165, 168`)**没有任何存储**——`SetCapability` 落到 `default: // not supported currently`(`RenderState.cpp:380`),`IsCapabilityEnabled` 返回 `false`(`:428-429`)。**六个 backend 读点(`DirectGLES.cpp:2133`;`VkTextureManager.cpp:951`;`VkRenderPassManager.cpp:613, 965, 1111`;`VkClearManager.cpp:57`)今天恒为 false。** 把接口写下来这件事**发现了**它。这是潜伏 bug 还是有意为之,**必须在渲染状态 blob 冻结之前回答**。
|
||||
7. **一次 glslang 编译离开 monolith 启动路径**(Magma 的内部 shader 烘焙,§6.1-2)。
|
||||
8. **`inproc` = monolith 的渲染线程**,且在方案 B 下只需隔离两个进程全局而不是四个——这是本项目手上最大的单一 CPU 杠杆,且完全不需要 shm 或平台工作。
|
||||
9. **`MG_Test` 的 mock backend 顺理成章变成 MGPipe recorder**,`tools/trace_replay` 可获得一种比 apitrace 精确得多的 MGPipe 级录制格式(它记录的是**已解析**的状态,重放确定性更强)。
|
||||
@@ -0,0 +1,274 @@
|
||||
## 11. 分阶段实施计划
|
||||
|
||||
> **通用纪律(每个 commit 都适用)**:默认 ALL target 必须能完整构建;禁止提交热路径插桩;**每个门必须能因它存在的理由变红**;Windows 机器不是正确性门(其 Vulkan 缺 `vkCreateHeadlessSurfaceEXT`,占该机 567 个基线集成失败中的 423 个);设备对比走 reboot-clean + 同热窗口配对 A/B,CPU 定频按项目协议(大核 1.96 / 小核 1.55GHz,GPU 拉满,40°C 门槛);**每个阶段的出口都跑一次 §10.3 的五部分门**(不只是 P0);**每个阶段的性能判据都是逐线程 CPU 时间**,不是墙钟帧时。
|
||||
> **两条跑道**:P0-P4a、P3b/P4b、P7、P8、P13 是 **monolith 跑道**,每一段都可独立交付、可随时中止且 monolith 严格好于起点;P5、P6、P9-P12 是 **IPC 跑道**,整段继承 `PLAN.md` §6-§13。
|
||||
|
||||
### P0 — 卫生、度量、门与骨架(8 天)
|
||||
|
||||
**交付物**
|
||||
- **清工作树 per-draw `fprintf`**:`DirectGLES.cpp:290-303`、`:640-663`、`Managers.cpp:875-877`(后者在 `pendingMutex` 临界区内)。CI 加 grep 门禁止 `MG_Backend/` 与 `MG_State/` 下出现 `fprintf(stderr` / `printf(`。
|
||||
- **`TracyPlot` 逐帧字节/调用计数器,装在边界两侧**,按类分:`cmd-records`、`stage-buffer`、`stage-texture`、`stage-ubo`、`persistent-map-push`、`server-ring`、`server-staging`、`residual-value-block`、`texture-pull`。**树里今天完全没有 per-frame 字节度量**(`MG_Util/Metrics` 只是格式算术,Tracy 只有 zone 无 plot),所以之后每一个 ring 尺寸、批阈值、wire 粒度决策否则都是猜测。两台设备取基线。
|
||||
- `MG_Pipe/PipeCalls.def` + `MGPipeTypes.h` + `MGPipeHandles.h` + `MGPipeCallbacks.h`:**完整调用目录,即使暂未实现的条目也占位**(记录编号绝不能churn)。
|
||||
- `scripts/gen_pipe.py` 与六个生成器 G1-G6 的骨架 + CI `pipe-gen-check`(重生成 + `git diff --exit-code`)。
|
||||
- `MOBILEGL_PIPE_PUSH` / `_VERIFY` / `_STATS` 在 `ConfigLoader.cpp` 与既有开关并列解析。
|
||||
- **三个严格 no-op 的免费收益**:`GetIntegeri_v`/`GetInteger64i_v`/`GetProgramiv` 的纯前端 case 移回 `MG_Impl`(Espryt 14 / Magma ~10 个读点);`RenderbufferObject::GetLifetimeId()`(**不加 `GetVersion()`**);D21 重键(`m_xfbCounterSlotByObject` 改用 XFB 对象 lifetimeId,`VulkanRenderer.cpp:11136-11146`)——**这一条是潜伏 bug 修复,先独立落 `dev`**。
|
||||
- 回答 `FramebufferSrgb`/`DepthClamp` 无存储是潜伏 bug 还是有意为之(§10.4-6)。**必须在渲染状态 blob 冻结之前。**
|
||||
- `MG_Remote/{Protocol,Transport}` 骨架与 `PLAN.md` P0 完全一致(`ITransport`、`InProcessTransport`、校验型 `Framing`、`Ring`+`RingControl` 双游标三元组双向 doorbell、`Doorbell`、`ShmSegment`、**`SCM_RIGHTS` 第一优先**);`protocol.fbs` + 提交的 `protocol_generated.h` + `flatc-check`;`MG_Test/Wire/`。
|
||||
- **`PLAN.md` P0 的两个 spike 原样跑**:spike A(Android 交付链:改名成 `lib*.so` 的 `add_executable` 能否被 AGP 打包、能否在 `untrusted_app` 域内 exec);**spike B(external memory 导出,两台设备)**。
|
||||
|
||||
**验收**:`AdvertisedLimitsScenario`(6 个测试)绿;367 集成 × 2 backend + 428 单元逐名不变;40 个 trace 全绿;`nm --defined-only` 与剥调试信息 `.text` 除三处刻意移动的符号外一致;两台设备的基线字节/调用/逐线程 CPU 数字记录在案;spike A/B 出结论并写进开放问题(spike B 的结论直接决定 P11 的规模)。
|
||||
|
||||
### P1 — `PipeInputs` 替换与 verify harness(8 天)
|
||||
|
||||
**交付物**
|
||||
- `MG_Backend/MGPipe/PipeInputs.h`:每个 backend 真正用到的 `GLContext` 方法一个访问器(Espryt 32 / Magma 55),**字段类型与今天读到的完全一致**,按 memo 键组织。
|
||||
- 机械 `sed`:`MG_State::pGLContext->` → `MGB_CTX->`(**293 处**);**外加逐条手工转换 58 行非箭头用法**(§2.4:~40 处 `MOBILEGL_ASSERT` 真值判定删除、~10 处空守卫改直读、3 处 patch 三元、`DirectGLES.cpp:146` 的 `.get()` 裸指针捕获、2 处 `!= nullptr` 条件、1 处注释)。**这份 58 行清单是本阶段的显式交付物**,不是"顺手处理"。
|
||||
- `SnapshotFromGLContext()` 在 `PrepareForDraw`(`DirectGLES.cpp:2916`)与 `SetupDraw`(`VulkanRenderer.cpp:6371`)顶端。
|
||||
- **G5 的 `m_filledMask` poison**:debug 与 disaggregated 构建里读未填字段 = `Fatal{UnmigratedPipeInput, "<field>"}`。
|
||||
- **G4 的 `MOBILEGL_PIPE_VERIFY=1` 逐字段影子比对器** + 第三种 CI 模式接线。
|
||||
|
||||
**验收**:**pull 构建里 `nm --defined-only` + 剥调试信息 `.text` size 与替换前完全一致**——本阶段可证明是一次替换(这是最后一次这条等式成立);全部 40 个 trace 与 367 个集成测试在 `MOBILEGL_PIPE_VERIFY=1` 下零分歧;**故意损坏一个快照字段能让 verify 门变红**;故意留一个字段不填能在第一个 draw 上触发 poison Fatal。
|
||||
**★ 第 16 天 — 最早可见里程碑:**零产品风险地证明"推送等价于拉取",逐 draw 逐字段。
|
||||
|
||||
### P2 — 值推送:渲染状态 CSO(双后端)+ 残余值块(8 天)
|
||||
|
||||
**交付物**
|
||||
- `MG_Impl/Pipe/Tracker.{h,cpp}`:dirty 位来自既有计数器(§5.2,三个回绕 `Uint16` 在 tracker 边界加宽)+ 固定 validate 顺序(§5.3)。
|
||||
- `MG_Impl/Pipe/CsoCache`:64 项 LRU,键是三段(head/blend/tail,与 `DirectGLES.cpp:2038-2047` 完全一致的划分)的 xxHash。
|
||||
- `create_render_state` / `bind_render_state`(D-B1):Espryt 侧 `RenderStateImpl` 的 693 行函数体、三段 memcmp、`g_syncedColorMaskAlphaWidenMask`、dual-source decline **一行不动**(消除 4 个读点:`:2007, 2021, 2050, 2133`);Magma 侧 `ComputePipelineStateHash` / `GetOrCreatePipeline` / `ApplyDynamicDrawStateTail` 改从 CSO 取(消除 ~55 个读点)。两个版本号都过线。
|
||||
- `set_pixel_pack_state`(PACK only)、`set_patch_state`、`set_vertex_attrib_defaults`。
|
||||
- **`set_residual_value_state` + `ResidualValueBlock`**(§6.3):`static_assert(sizeof == MGL_RESIDUAL_BLOCK_SIZE)`(逐阶段**下调**)+ **逐成员 `offsetof` 断言** + split 下逐字段序列化。
|
||||
|
||||
**验收**:367 集成 × 2 backend × 2 模式(pull / push)逐名相同;40 个 trace 在 monolith-push 下 SSIM ≥ 0.99,双后端;`ClipDistance`、`SampleMaskScope`、`SampleVariables`、`DualSourceBlend`、`ViewportArray`、`PrimitiveRestart` 场景绿;verify 模式零分歧;**两台设备 reboot-clean 配对:monolith-push 在 p50 与 p99 逐线程 CPU 上落在 monolith-pull 噪声内或更好**。
|
||||
**★ 第 24 天 — GO/NO-GO 决策点。** 此刻手上有:verify harness、双后端已推送的渲染状态、真实 CPU 增量、Track H 在两个最便宜子系统上的单位成本。**若 CPU 数字为负、或 Track H 单位成本超估计 50%,退回方案 A 只损失这 24 天中的 16 天**(P0 是 `PLAN.md` 共有的)。
|
||||
|
||||
### P3a — handle wave 1(Espryt):slot 基建、buffer、VAO(12 天)
|
||||
|
||||
**交付物**:`SlotAllocator`(按 kind 稠密 + `gen` + 保留段);`PipeObjectTables`(POD slot **数组**);**删** `TwinLookupMemo`×3、`OwnerEquals`、`g_fbSlotCache`、6 个 registry GC 扫描、`VkTextureManager::PruneDeadTextures`、`m_convertedVertexStreams` 的 `sourcePin`;7 个 `BufferBackendOps` → `resource_create/respecify/destroy`、`resource_subdata`、`buffer_subdata_resident`(**可 null,保住 Magma 的差异**)、`resource_flush_range`(带应用真实 access flags)、`resource_readback`、`map_persistent`(**不碰实现**);pool 与延迟释放机制原样搬;`create/bind/delete_vertex_elements_state`(**两个视图都带**:解析后的 `VertexAttribute[32]` 与 `VertexBufferBindingPoint`;`IsLong` 与 `Type` 分开);`set_vertex_buffers`(**`baseInstance` 是显式字段**,不再是调用方武装的 `ScopedFetchBaseInstance` 作用域);`set_index_buffer`(带 restart index 与模式);Adreno 禁用属性 SIGSEGV workaround 原样保留。
|
||||
|
||||
**验收**:全套门(monolith-push,DirectGLES);`LargeArenaAdoption`、`ResidentIndex`、`StorageBufferRegrow`、`AtomicCounter`、`BufferTexture`、`CrossFrameBuffer`、`SsboArrayLength`、`SsboArrayDynamicIndex`、`VertexArrayEnableDisable`、`VertexAttribBinding`、`DoublePrecision`、`DrawParameters`、`MultiDraw`、`PrimitiveRestart` 场景;`create-indirect`、`create-instancing`、`rd12-odinlite`、`improved-transparency-26.3`、`fabric-sodium` trace SSIM ≥ 0.99;**新增 `HandleRecycleScenario` 绿,且它在 slot 重键之前必须是红的**;MC 26.3 在 Adreno 上 p99 不变(16MiB 采纳结果不得回归)。
|
||||
**⚠ 再基线检查点 1:若 P3a 超期 >50%(>18 天),"窄 handle 化"的前提就是错的,必须在 P4a 开始之前重定基线。**
|
||||
|
||||
### P4a — handle wave 2(Espryt):FBO / 纹理 / sampler / program 的身份与描述符(16 天)
|
||||
|
||||
**刻意推迟到首帧之后的部分**:memo 重键、dirty 归属反转、program 陈旧性重构(→ P3b/P4b)。本阶段只做 wire 需要的身份与描述符。
|
||||
|
||||
**交付物**:`set_framebuffer_state`(8 个 `MGPSurface` + **client 解析后的 `readSurface`** + 内联 `internalFormat` + `contentHash` + `isDefault` 保留 handle,退役 4 处 `pDefaultFramebufferInfo` 读);四个跨对象 mask 在推送时刻推出;`create/bind/delete_sampler_state`(`SamplerParameters` 逐字节含 `borderColorForm`);`create/delete_sampler_view`(`glTextureView` 变普通 view CSO);`set_sampler_views`(client 侧解析)+ `bind_sampler_states`;`set_shader_images`;`create/bind/delete_shader_state`(逐 stage SPIR-V + `Visit()` 全结构体反射归档 + `sizeof` 绊线);`set_draw_program` / `set_dispatch_program`;`set_global_constants`;`CompositeResolver.cpp`(保留 slot 段 + 生命周期);纹理与 renderbuffer 的 `resource_create/respecify/subdata`。emulation 路径在 split 模式下**显式 Fatal** 直到 P8。
|
||||
|
||||
**验收**:全套门;`CrossFrameBuffer`、`LayeredAttachmentShape/Barrier`、`SnormAttachment`、`RenderbufferBlendFormat`、`FragmentOutputArrayIndex`、`Orientation`、`ClearThenReadPixels`、`FragCoordOrigin`、`TextureView`、`ProgramPipeline`、`PostLinkAttach`、`RelinkStageSet`、`SpirvShaderBinary`、`AsyncCompile`(6 个)场景;`KHR-GL46.direct_state_access.framebuffers*` 与整个 `packed_pixels` 块在两台设备上绿(**~3300 个 framebuffer/用例,是 handle 复用的压力测试**)。
|
||||
|
||||
### P5 — 传输 + inproc applier + 发射表(12 天)
|
||||
|
||||
**交付物**:`MG_Remote/Client` 的发射表实现 `MGPipeScreen`/`MGPipeContext`;`Server/PipeApplier.cpp` 从记录填 `PipeInputs` 与 `PipeObjectTables`;`ServerLoop`(`mgl-srv-io` + `mgl-srv-apply`,后者终身持有原生 context);单一 hook 点 `MG_Backend/Init.cpp:48-70` 装 `BackendObject_Remote`(下游零 `#ifdef`);`MGPCaps` 快照;一条阻塞 `read_pixels`;client 侧保守 `MarkGpuWritten` 与 `emitSeq`;**client 侧块粒度 persistent-map 推送**(T2 档下强制,`PLAN.md` §5.10 第 2 条);`InProcessTransport`。
|
||||
|
||||
**验收**:`ctest -R 'DirectGLES\.Split\..*(ClearThenReadPixels|Triangle)'` 在 `MOBILEGL_TRANSPORT=inproc` 下绿;**OpenRA trace 在 split 模式下 SSIM ≥ 0.99**;**`PersistentCoherentMapScenario` 绿**(map PERSISTENT|WRITE|COHERENT、写、不做任何其它 GL 调用、draw、回读校验——这是唯一一个为一个致命缺陷而存在的门);**两个角色的峰值 RSS 记录在案**,作为对 `PLAN.md` R14 的基线;`persistent-map-push` 字节量出数;任何未迁移的 `PipeInputs` 字段读产生 `Fatal{UnmigratedPipeInput}` 而不是静默垃圾。
|
||||
**★ 第 64 天 — 首个 IPC 帧(`inproc`)。诚实标注:这是缩减路径**——client 数组、restart 重写、indirect-count 解析在 split 下仍是 Fatal,全功能要等 P8。
|
||||
|
||||
### P6 — spawn transport(5 天)
|
||||
|
||||
**交付物**:`SocketTransport`(socketpair + fork/execve,**显式 envp 剔除 `MOBILEGL_TRANSPORT`/`MOBILEGL_IPC_*` 加 `mobilegl_server_main` 内强制 Monolith 的双保险**);`ServerMain`;`MOBILEGL_IPC_SERVER_PATH` 为主 + `dladdr` 兜底(两个桌面门都会挫败 `dladdr`);就绪握手有界重试;client EOF 即时退出;server 死亡的 device-lost latch;trace-replay 的 `SPLIT` 后缀与 `-DTRACE_TRANSPORT=` 接线。
|
||||
|
||||
**验收**:P5 全部测试在 `MOBILEGL_TRANSPORT=spawn` 下绿;fork 链测试断言进程树只多一个子进程;`HeadlessGL` 的 fork 预检交互测试无孤儿 server(`pgrep` 计数在 100ms 内归零);`run_android_retrace_local.py --case OpenRA --backend DirectGLES` 在 `35d0befa` 上 SSIM ≥ 0.99。
|
||||
**★ 第 69 天 — 首个跨进程帧(缩减路径)。**
|
||||
|
||||
### P3b / P4b — 深化(Espryt):memo 重键、dirty 反转、program 陈旧性(28 天)
|
||||
|
||||
**交付物**:重键 `ResolvedDrawBuffers`、`PendingAttribValueMask`、`ConvertedFloat64Stream`、`SyncCurrentFBO` 四元组戳、`ResolvedTextureBindingMemo`、`SamplerPassMemo`、image sweep、program registry 到 `{slot, gen}`;**删** `g_unitTextureSyncList`、`g_fboTextureSyncList`、`g_unitSamplerLookupMemos`、`g_imageSweep*`、`DirectGLES.cpp:1372-1489` 的 ~115 行 unit-bindings epoch 推导;**dirty 归属反转**(§7.3,client 保 rect 模型与发射游标、发射后自清;`resource_subdata` 带 box **与** rect 列表、server 选形状);**删** fragColor 重推导 workaround(`:2712-2732`)与 `g_broadcastMemo*`;用推送的 FBO 状态、image 格式、`set_patch_state` 退役 9 条陈旧性判定里的第 4-6、8-9 条;Espryt 的 raw-depth-fetch `SamplerObject` 原生化。
|
||||
|
||||
**验收**:~25 个纹理场景(`TextureView`、`LayeredTextureReadback`、`ImageSizeAfterRespec`、`FormatlessImageBake`、`NonCoreImageFormat`、`ImageFormatQualifier`、`ImageTargetKind`、`ImageLoadStoreSso`、`UnboundImageDescriptor`、`SwizzleAccessRoutine`、`IntegerBorderColor`、`PixelStoreSweep`、`SampledSetStaleness`、`ThreeChannelAttachment`、`BufferTexture`、`CopyImage*`×3、`ClearTexImageUndefinedLevelZero`、`DepthStencilReadback`×3、`PackedWordReadback`);21 个 program 场景 + 整个 `MG_Test/ShaderTranspiler` 目录;两台设备上完整 `KHR-GL46.texture_*` / `internalformat.texture2d.*` / `shader_image_*` / `packed_pixels` 块,conformance 在 pull 基线 0.5pp 内;**每一个 Iris trace**;**Mali 上 box-vs-rects 上传形状不得回归**(+6ms/frame 悬崖);verify 模式全程零分歧。
|
||||
|
||||
### P7 — DirectVulkan(Magma)全量迁移(48-85 天,可与 P5/P6/P8 并行)
|
||||
|
||||
**交付物**:§6.5 的 11 个子系统,重点三项:`SetupDrawSnapshot` 的 ~14 个探测字段(含两个**有损**的版本求和)塌成 dirty mask 比较;**`UniformManager` 的 8 类占位 `TextureObject` 换成原生 `VkImage`+view+descriptor**(~120 行删除,43 个 `MOBILEGL_ASSERT(pGLContext)` 里的 9 个消失);**blit / depth-mipmap 内部 shader 烘焙成签进树的 SPIR-V + uniform location + UBO 布局,由一个 `MG_Test` 重跑树内 glslang 逐字节比对的用例守新鲜度**(不用 host 工具构建步骤);`VertexInputStateFactory` 的后端堆裸指针写回**直接删除**;`VkRenderPassManager` / `VkTextureManager` 的**节点式容器纪律原样保留**(D18,postmortem 注释逐字带进 review checklist)。
|
||||
|
||||
**验收**:367 集成 + 40 trace 在 DirectVulkan 的 monolith-push 与 split 下全绿;verify 零分歧;**`nm -D libMobileGLServer.so | grep glslang` 为空**——这是整个论点的强制执行点;`UnboundImageDescriptor`、`SampleMaskScope`、`ImageLoadStoreSso`、`AtomicCounter`、`SsboArrayDynamicIndex`、`NonCoreImageFormat`、`Orientation`、`DepthStencilReadback*` 场景;两台设备 CTS 在 0.5pp 内。
|
||||
**⚠ 再基线检查点 2:P7 中点(第 24 个工作日)若已完成子系统 < 40%,立即重定基线**——P3a 的检查点只能发现 Espryt 侧的偏差,发现不了 Magma 特有的超期,而 P7 在单跑道下位于关键路径。
|
||||
|
||||
### P8 — emulation 下放 + 协议广度(14 天)
|
||||
|
||||
**交付物**:`MG_Impl/Pipe/HostResolve.cpp`——client 数组范围计算、**最大索引扫描**(`TryComputeMaxIndexFromHostBytes` 移到 client,唯一的无界应用指针读)、**primitive-restart 重写**、**indirect-count 解析**,每一条前面都有与 monolith 的 `SyncPersistentMappedRange()+SyncGpuWrites()` **完全相同位置**的 publish/wait/drain(§5.8.1);`MGHostSpan` 的 split 填法;**CopyImage shadow 镜像搬到 client**(删掉一整条 server→client 字节通道);`draw_vbo(info, indirect, ranges[], numDraws)` 收编 multi-draw 族;viewport-array 回放验证在一次 pipe 调用驱动下各遍之间观察到的状态与今天一致(`EndViewportRoutingPasses` 会调 `InvalidateSyncedRenderState`,`DirectGLES.cpp:3841`);`generate_mipmap` 返回 level 计划与 CPU 回退的纹素。
|
||||
|
||||
**验收**:`ctest -L integration-gpu -R '^DirectGLES\.Split\.'` 与 `'^DirectGLES\.'` **逐名相同**,DirectVulkan 同;40 个 trace 在 split 下双后端 SSIM ≥ 0.99,含两个 `coherent_as_flush: true` 的 Create fixture(**两种模式都开着该开关跑**);**新增 `ClientArrayAfterComputeWriteScenario` 绿,且去掉那次等待必须能看到几何缺失**;`MultiDraw`、`PrimitiveRestart`、`ViewportArray`、`DrawParameters`、`CopyImage*`×3、`GuiBatch` 场景。
|
||||
|
||||
### P9 — 反向通道(10 天)
|
||||
|
||||
**交付物**:`SEG_REPLY` 4KiB slot 池;阻塞 `read_pixels`;PBO 回读 fire-and-forget;`on_gpu_written{res, ranges}` 收窄(配 `set_shader_buffers` 的 `writableMask`);`on_buffer_writeback` **按操作级批处理**(今天两处逐行循环:`Utils.cpp:2342`、`DirectGLES.cpp:7633`)配 epoch bump 的排序规则(§7.4);`on_texture_writeback`(一个生产者);`on_mip_levels_generated`;**`on_texture_pull_request` 三条缓解全上**(§7.5);`on_gl_error` 有序 + 分配类 `kNeedsAck`;`on_caps_invalidated`;`on_surface_changed`;**`on_log` 按严重级分级**(≤WARN 有损 / ≥ERROR 无损 + 每秒速率限制器 + "N errors suppressed");`SEG_EVENT` 溢出策略 + 等待循环内排空。
|
||||
|
||||
**验收**:`DepthStencilReadback`×3、`PackedWordReadback`、`LayeredTextureReadback`、`ClearThenReadPixels`、`XfbAfterClipDistance`、`XfbCaptureBufferReuse`、`XfbRepeatedCapture`、`TessellationXfbCapture` 在 split 下绿;**新增 `TextureRemintPullScenario`**(同时强制 `RequireImageBindableStorage` 与帧中格式再生)绿,**且逐 trace 用例发布拉取计数**;故障注入:client 被 credit 阻塞时灌满 `SEG_EVENT`,两侧都必须恢复;**日志洪泛下注入一次 backend link 失败,那行 ERROR 必须出现**。
|
||||
|
||||
### P10 — sync / query / present 节奏(6 天)
|
||||
|
||||
**交付物**:client 铸造 sync 与 query handle;轮询入口成为门铃点 + `MOBILEGL_IPC_POLL_ESCALATE` 饥饿升级;**fence 完成度来自真的逐 fence 退休**(不是 present 水位——那正是 MC 1.21.5 native-heap OOM 的成因);DirectGLES 的非 present fence tick;`Present` 严格 1:1;`MOBILEGL_IPC_PRESENT_CREDIT` 默认 1 + 叠加公式写进文档;逐帧 roundtrip 计数器与**输入延迟直方图**(记录发射时刻 → present 完成时刻);`PLAN.md` §8 末尾的三个独立 `dev` monolith 修复。
|
||||
|
||||
**验收**:`XfbPrimitiveQuery`、`PrimitivesGeneratedNoXfb`、`AsyncCompile` 在 split 下绿;**40 个用例上 draw/state/upload 路径的 roundtrip 计数器读零**,条件渲染与阻塞 query 次数逐用例发布而非声称为零;零 timeout 轮询循环测试在有界时间退出(不加 publish 规则它会永远挂住);`bench.sh` 在 `35d0befa` 上配对 A/B:两侧都关采纳时 split 帧时在 monolith 10% 内,输入延迟直方图 p50/p99 记录在案。
|
||||
|
||||
### P11 — persistent map 与 ≥16MiB 采纳(8 天;spike B 全否则缩为 2 天)
|
||||
|
||||
**交付物**:由 P0 spike B 驱动的 POST 探针档位选择(T2 拒绝 / T1 server 导出 / T0 server 导入);`SEG_ADOPT` 生命周期绑 `completedFrameSerial`;`MOBILEGL_IPC_ADOPT_TIER` 覆盖开关做负面对照。
|
||||
|
||||
**验收**:`LargeArenaAdoptionScenario` 在所选档位下绿;`improved-transparency-minecraft-26.3` 与两个 Create fixture SSIM ≥ 0.99;`35d0befa` 上配对 reboot-clean 的 p99 帧时与峰值 RSS 对 monolith 采纳基线(p99 163→21ms、40→115fps、~400MB)——**split 在所选档位下 p99 不得回归超过 10%;若 T2 成为永久答案,其实测代价必须写进文档**。
|
||||
|
||||
### P12 — Android 生产窗口路径(10 天)
|
||||
|
||||
**交付物**:`android:process=":mgl"` 的 Service 收 Java `Surface`(Binder)后 `ANativeWindow_fromSurface`(minSdk 26 无公开 `ANativeWindow` 扁平化,这条路径是强制的;树内先例是 `android:process=":bench"` 的 `BenchService`);server 生命周期绑 Activity;FCL 用户 env 与 plugin APK V2 开关表接线(**零新增管线**,两条通道都已存在)。
|
||||
|
||||
**验收**:Minecraft 通过 FCL 在 spawn 模式下在 `35d0befa` 上双后端入世界;配对 reboot-clean bench + 输入延迟直方图;杀 server 产生干净的 device-lost latch 而不是挂起或崩溃;SIGKILL 故障注入。
|
||||
|
||||
### P13 — 退役 pull 路径(6 天)
|
||||
|
||||
**交付物**:删 `SnapshotFromGLContext()`、`MGB_CTX` 宏、`MOBILEGL_PIPE_PUSH`(推送成为唯一路径),**保留 `MOBILEGL_PIPE_VERIFY` 工装**;删 `set_residual_value_state` 与 `ResidualValueBlock`;`MG_Backend` 的 `MG_State` include 收缩到共享值头白名单;最终符号/尺寸/CPU 报告。
|
||||
|
||||
**验收**:**`static_assert(sizeof(ResidualValueBlock) == 0)` 编译通过**(临时物可证明地消失);`grep -c 'pGLContext' MG_Backend/` == 0;`nm --undefined-only libMobileGLServer.so` 无 `MG_State::GLState::`、无 glslang 符号;全套门(367 × 2 backend × {monolith, split}、428 单元、40 trace SSIM ≥ 0.99、两台设备 CTS 在 `81b17c0b` 基线 0.5pp 内);**monolith 逐线程 CPU 在两台设备的 p50 与 p99 上不差于 P0 基线**——本设计的性能主张在这里成立或倒下。
|
||||
|
||||
### 11.5 总估时、里程碑与 CTS 周转
|
||||
|
||||
**累计(单跑道)**:P0 8 → **8**;P1 8 → **16**;P2 8 → **24**;P3a 12 → **36**;P4a 16 → **52**;P5 12 → **64**;P6 5 → **69**;P3b/P4b 28 → **97**;P8 14 → **111**;P9 10 → **121**;P10 6 → **127**;P11 8 → **135**;P12 10 → **145**;P13 6 → **151**;**P7(Magma)48-85** → **199-236**。
|
||||
|
||||
**报作 200-260 人天**(上界含缓冲)。两个工程师、P7 与 P5/P6/P8 并行 → **约 6-7 个月**,真正的约束是两台设备的争用而不是人头。
|
||||
|
||||
**里程碑**:第 **16** 天 verify harness 全绿(零产品风险);第 **24** 天 GO/NO-GO;第 **64** 天首个 `inproc` IPC 帧(**缩减路径**);第 **69** 天首个跨进程帧(**缩减路径**);第 **111** 天全功能 split(P8 出口);第 **151/199-236** 天接口纯度门转绿。
|
||||
|
||||
**CTS 周转必须单独计价,不折进阶段估时。** `gl44to46` caselist 约 56,271 例。分层门控:逐阶段只跑该阶段改动可能影响的具名 CTS 块(P4a 的 `packed_pixels`、P3b/P4b 的 `texture_*`/`shader_image_*`、P9 的 `transform_feedback*`),**完整 caselist 只在四个架构边界跑**(P3a handle、P4a framebuffer、P3b/P4b 纹理、P13 纯度)**以及每次合并 `dev` 之前**,且放在 CI 而不是关键路径上。设备锁协议照旧。若实测周转仍主导排期,**诚实做法是加宽估时而不是削弱门**。
|
||||
|
||||
---
|
||||
|
||||
## 12. 风险与对策
|
||||
|
||||
| # | 风险 | 对策 |
|
||||
|---|---|---|
|
||||
| **B-R1** | **效率是方案 A 的 3 倍、首帧晚 4-5 倍**(200-260 天 vs 77;第 69 天 vs 第 15 天)。排期驱动的评审可以只凭这一条否掉本方案 | 把价值排在承诺之前:P0-P2(~24 天,其中 16 天是方案 B 独有)交付 handle 化 twin 与内容寻址的渲染状态 CSO——**零 IPC 风险的可测量 monolith 性能工作**——并产出字节计数器与第一个逐线程 CPU 数字。**第 24 天显式 GO/NO-GO。** P13 是一个完全自洽、不含任何 IPC 的 monolith 交付物;P5 的 `inproc` 在 P13 之后是本项目手上最大的单一 CPU 杠杆,只要 12 天 |
|
||||
| **B-R2** | **中心性能主张未经测量。** 可达性遍历是**搬走**而不是消失;若 client 侧 dirty 走查比它替换掉的拉取更贵,整个论证反转。而树里今天没有任何 per-frame 字节或调用度量 | 字节/调用计数器是 **P0 交付物**,不是后续性能阶段的事(这是历次评审对四个候选设计的共同发现)。每阶段的验收都用**逐线程 CPU 时间**,两台设备、reboot-clean、配对。P2 刻意选最便宜的面,好让机制在花掉 200 天之前就被证明。**先清工作树 per-draw `fprintf`**——它污染每一个基线 |
|
||||
| **B-R3** | **monolith 字节一致门按构造死亡**,P2 的逐名集成基线也随之移动(参考构建变了) | 五部分替代门,全部在 P0/P1 落地(§10.3),其中第 ② 部分(逐 draw 逐字段影子比对)在语义上严格强于任何符号 diff。两条字节等式仍作断言保留。**在设计文档里明写这条损失,不藏。** P2 的参考构建明确定义为"重构后的 monolith",并要求 P1 出口先证明重构本身是等价的 |
|
||||
| **B-R4** | **server 发起的纹理拉取是新停顿类**,且触发路径之一(整格式再生 `Managers.cpp:3950-4195`)在普通 `glTexImage` 格式变更上就会触发、无法被 hint 预防 | 三条缓解同时上:`imageBindableHint` 预防主因;**异步**park-and-re-emit 让停顿落在 `mgl-srv-apply` 而不是应用线程;有上限的 ≤32MiB 保留 LRU 让一张纹理不会停顿两次。`TextureRemintPullScenario` 强制两个成因,**拉取计数逐 trace 用例发布**而不是声称为零。若实测率非平凡,保留缓存从可选升为强制并拿真预算 |
|
||||
| **B-R5** | **P3b/P4b(纹理,28 天)与 P7 中的 `VkTextureManager` 是最大最险的段**,且正压在项目已实测 +6ms/frame 悬崖(rect 列表 vs union box)与 7 条 fallback-repack 路径上(其可行性判定要求 `uploadData == mipData`) | `resource_subdata` **同时**带 box 与 rect 列表、**server 选形状**——决策留在做过那次测量的那一侧。repack 族原地不动,只把输入从拉取的 shadow 指针换成 `MGPBlobRef`(monolith 里是同一个指针)。**在 Mali 设备上专门设门并公布帧时增量**。P3b/P4b 拆成两个可独立落地的半(先 sampler view + sampler,再 image unit + dirty 反转),让回归能二分到其中一半 |
|
||||
| **B-R6** | **tracker 完整性**:推送之后 server 不能再重读活状态来校验快路径命中,它必须信任上一次推送。任何 tracker 忘记发的 mutator 会静默漂移,直到某个场景恰好触及。历史上最危险的正是这个形状——DSA by-name 模拟曾在不移动任何计数器的情况下交换一个纹理单元绑定(`DirectGLES.cpp:1441-1465`) | 三层:**(1) 构建期** G5 的 written-once 位图断言每个 `kCtxState` 组在第一个 verb 消费它之前被写过;**(2) 运行期** poison mask 在读未填字段时 `Fatal{UnmigratedPipeInput}`;**(3) 语义** `MOBILEGL_PIPE_VERIFY` 逐 draw 逐字段比对,专抓"dirty 位触发得太少"这个危险方向。删掉 `SnapshotFromGLContext()`(P13)之后完整性成为构建期事实。**迁移粒度是一个 accessor**,所以一次遗漏被限制在一个阶段 B 步骤内。477 行 inventory 保留为 tracker 侧检查表 |
|
||||
| **B-R7** | **`AcquirePersistentMap` 跨进程无解**会葬送 MC 26.3 的结果(p99 163→21ms、40→115fps、省 400MB),而没有任何目标平台的支持被验证过 | **显式隔离**:改造期完全不碰(它已经是一个返回指针的显式调用,原样穿过 P0-P13),只有 IPC 那一步会打破它。决策交给 `PLAN.md` §6.8 的三档 POST 探针与 **P0 第一周的 spike B**。T2(拒绝)前端已在三处容忍并让 client 侧块推送成为强制(P5 就交付)。若两台设备都否,P11 从 8 天缩为 2 天的文档与负面对照。**不让一个平台未知数挡住 200 天的接口工作** |
|
||||
| **B-R8** | **D18 的节点式容器纪律在重构中丢失**:`m_renderbufferResources` / `m_textureResources` 是**故意**用 `std::unordered_map` 而非本项目开放寻址的 `UnorderedMap`,因为调用方跨后续查表缓存 `Resource*`;一次扩表搬迁曾让 `BlitFramebuffer` 静默停在 "source image layout is undefined"(postmortem `VkRenderPassManager.h:375-397`)。把它"优化"回去正是一次大重构最容易犯的错 | D18 是全表**唯一**标为 UNCHANGED 的身份行,理由写进设计正文:接口对此零约束,`ska` 的 erase-shift 让 hazard 更糟而不是成为历史,**postmortem 注释必须逐字带进 P7 的 review checklist**。slot 数组在插入下稳定,实际改善了处境——但仍然点名,防止有人顺手改回去 |
|
||||
| **B-R9** | **逐 backend 的行为不对称被统一接口抹平。** Magma 故意不注册 `ResidentSubData`(`VkBufferManager.cpp:104-111`),差别是 `glBufferSubData` 在活 coherent map 上的排序语义;`PrefersCpuXfbPrimitiveAccounting`、DirectVulkan 留空的 8 个槽、不同的 multi-draw 分档同形。强制统一会静默改变 Magma 行为并发布一次 Minecraft chunk 撕裂 | 可选性是**接口的一等属性**:null 项在本代码库里**已经**表示"未实现,前端回退"(`BackendObject.h:212-215, 265-269`),`MGPCaps` 携带显式的 `callMask` 能力位集,取代今天 `GL_Query.cpp:471, 545, 768` 的隐式槽位空否探测。**cap 位集同时决定每个 emulation 在哪一侧 lowering**,所以不对称成了机制而不是疣 |
|
||||
| **B-R10** | **接口在未测量的形状上过早冻结**:渲染状态 CSO 粒度、`resource_subdata` 的 box+rect 双载荷、sampler-view 解析边界、screen/context 划分全在 P0-P2 定死;而若干 server 侧缓存的容量是按拉取模式调的(Magma 的 2048 槽 `VaoDrawMemo`、4 个 `SetupDrawSnapshot`、8 个 pipeline memo、8 个 `syncedTextureMemo`;Espryt 的 4096/256/64 槽 `TwinLookupMemo`) | payload 结构从第一天走 structSize-first 版本纪律(复用 `Feat/CS-Delta-IPC` 的 `mg_protocol_base.h` 词汇),可增长。字节计数器在 P0 落地,让 P2 的 CSO 粒度决策有数据。**P13 在计数器活着的情况下重调所有幸存缓存的容量**,并把它们当作带 env 覆盖的调优参数而不是常量。screen/context 划分在 P0 定进头文件但按 context 计数 == 1 实现——现在免费,事后是一次全面重编号 |
|
||||
| **B-R11** | **58 行非箭头 `pGLContext` 用法的迁移缺口**:三份候选设计都提了"机械 sed 293 处",都没交代这 58 行;其中 `DirectGLES.cpp:146` 的 `.get()` 裸指针捕获 `sed` 完全抓不到 | §2.4 已把它们逐形态分类。P1 的交付物**包含这份 58 行清单的逐条转换**,不是"顺手处理"。**纯度门 grep 的是 `pGLContext` 而不是 `pGLContext->`**,所以漏一条就红 |
|
||||
| **B-R12** | **残余值块是迁移期边界上的一个洞**:poison mask 抓得到"未填字段",抓不到"两侧布局不同"——而这正是一个异质 POD 并集跨编译器/ABI 边界最容易出的问题,且 monolith 的 verify harness **看不见它**(monolith 里两侧是同一个 TU) | 逐成员 `offsetof` 断言(不只是 `sizeof`)**加上** split 模式下逐字段序列化(走 G3 生成的编解码器)而不是整块 memcpy。块的字节量单独计一类,让"它还有多大"可见。`static_assert(sizeof == 0)` 让退役是编译错误 |
|
||||
| **B-R13** | **`SEG_EVENT` 的 ERROR 无损化重新引入 §7.4 要防的死锁**:一个 shader 风暴产生的 `MGLOG_E` 洪泛可能停住 apply | 每秒 ERROR 速率限制器,超限发一条显式的 "N errors suppressed";`MGLOG_E_ONCE` 的 latch 变 per-server(这正是想要的);P9 的故障注入门要求"日志洪泛下注入一次 link 失败,那行 ERROR 必须出现"**且**"两侧都恢复" |
|
||||
| **B-R14** | **排期估计偏乐观**:独立的改造成本分析给出 backend 工作**单独** 202-266 天;本文的 200-260(含 IPC)落在其乐观端,而 P7 的 48 天下界明显低于同口径的 85-111 | **两个再基线检查点**(P3a 超期 >50%、P7 中点完成度 <40%),且 P7 的上界 85 已经写进总估时区间。CTS 周转**单独计价**不折进阶段。若两个检查点任一触发,先跑 `inproc` 的证伪数字再决定是否继续——这与 `PLAN.md` R15 的退火思路一致 |
|
||||
| **B-R15** | **在 GL setter 时刻推送**(而不是 draw validate 时刻)会让整件事变慢,且这是最容易被后续实现者做错的一处 | 写成规范条款并给出理由与证据(`DirectGLES.cpp:2044-2046` 的 Blaze3D per-batch blend toggle);P2 的设备门直接暴露它(monolith-push 必须在 p50 **与** p99 逐线程 CPU 上落在噪声内);两个高水位标记(`TouchBindPoint`、`NoteUnitTouched`)明确要求留在 tracker 走查里 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 开放问题
|
||||
|
||||
1. **client 侧 dirty 走查的真实每 draw CPU 代价是多少?** 中心性能主张是"遍历搬走而不是翻倍",树里没有任何度量。这是 P2 的头号数字,按逐线程 CPU、两台设备报。
|
||||
2. **真实语料上纹理重铸拉取的实际发生率?** `imageBindableHint` 能预防主因,但整格式再生(`Managers.cpp:3950-4195`)在普通 `glTexImage` 格式变更上就触发。若 MC 或 Iris fixture 上的实测率非平凡,保留 LRU 从可选升为强制并需要真预算。
|
||||
3. **`AcquirePersistentMap` 跨进程能不能成?** P0 spike B 第一周回答。未验证:`VK_KHR_external_memory_fd` 的 host-visible-coherent 支持在 Adreno 830 / Oppo Mali / lavapipe / Windows ANGLE lane 上的可用性;GLES 侧能否用 `GL_EXT_memory_object_fd` + `glBufferStorageMemEXT` 走同一条路(Espryt 今天的采纳走的是 `glBufferStorageEXT` + `glMapBufferRange(PERSISTENT|COHERENT)`,不是外部内存)。
|
||||
4. **渲染状态的 wire 粒度定多少?** ~1.2KB 整块 vs 三个现有段 vs 逐 dirty 位子集。P0 落计数器、P2 用数据定。CSO LRU 的容量(暂定 64)同理。
|
||||
5. **`MG_Util` 的切割缝在哪里?** server 需要 SPIRV-Cross pass 流水线、ESSL 转译缓存、像素/纹理格式处理器、POST 探针、loader;client 需要 glslang phase A/B 与反射层。`ProgramObject.h` 传递性 include `ShaderObject.h → ShaderCompileTask.h`,所以任何链接真 `ProgramObject` 的 client 都会拉进编译机制。**没有审计过是否存在一条干净的 Transpile-vs-Reflect 缝。**
|
||||
6. **一份反射归档能服务三个消费者吗?** Espryt 读前端表,Magma 跑 SPIRV-Reflect,而 `DirectVulkan.cpp:161` 为 `glGetProgramResource*` 又反射了第二遍。没有确认一份 payload 能同时满足三者。
|
||||
7. **viewport-array 回放能塞进一次 `draw_vbo` 吗?** 今天它从 14 个 draw 入口经 `ForEachViewportRoutingPass` 重发应用的 draw N 次,而 `EndViewportRoutingPasses` 会调 `InvalidateSyncedRenderState`(`DirectGLES.cpp:3841`)。没有验证单次 pipe 调用驱动下各遍之间观察到的状态是否与今天一致。
|
||||
8. **`ResidentSubData` 的不对称该怎么收口?** null 项保住今天的行为,但拆分工作可能正是给 Magma 补一个真实现的时机——那是**行为变更而不是重构**,应当作为独立的 `dev` PR。
|
||||
9. **`SEG_STAGE` 的上限定多少?** 现在多了四类字节(client 顶点数组、client 索引数组、multi-draw 参数块、client 解析的 indirect 命令块)。体量不变但都走 ring slot。需要 P8 之后用 MC in-world 与 Create 两类 fixture 的 `stage-*` 计数器给 p99 占用。
|
||||
10. **`FramebufferSrgb` / `DepthClamp` 无存储是潜伏 bug 还是有意为之?** 六个 backend 消费者今天读到恒定 false(`RenderState.cpp:380, 428-429`)。**必须在渲染状态 blob 冻结之前回答**,因为它决定接口里要不要这个字段。
|
||||
11. **P13 之后 `MOBILEGL_IPC_VALIDATE_SERVER` 还有对应物吗?** 方案 A 靠"server 侧保留 `MG_Impl` 校验器"把分歧变成 server GL error。方案 B 的 server 没有 `MG_Impl`,所以 split-only 的渲染 bug 没有第二意见。什么替代那个诊断能力?
|
||||
12. **client 侧 restart 重写与 indirect-count 解析会不会改变可观察行为?** 两者今天都以 `m_valid=false` 加诊断的方式退出(`DirectGLES.cpp:4405-4409`、`:4685-4688`);把 decline 移到 client 改变了哪个线程打这条日志,也可能改变它相对 GL error 的顺序。
|
||||
13. **Magma 的两个内部 shader 烘焙后,uniform location 与 UBO 布局能否在没有活 `ProgramObject` 的情况下表达?**(`VulkanRenderer.cpp:4238-4241, 4319-4324, 8450-8452`)未做原型。
|
||||
14. **推送模型会改变哪些按拉取模式调过的缓存命中率?** Magma 的 2048 槽 `VaoDrawMemo`、4 个 `SetupDrawSnapshot`、8 个 pipeline memo、8 个 `syncedTextureMemo`;Espryt 的 4096/256/64 槽 `TwinLookupMemo`(后者会消失)。幸存者的容量要在 P13 重调。
|
||||
|
||||
---
|
||||
|
||||
## 14. 对方案 A 文档与 `Feat/CS-Delta-IPC` 的复用清单
|
||||
|
||||
### 14.1 对 `PLAN.md` 的复用(本文的 §8.1 是权威列表,这里给的是"取/改/弃"总账)
|
||||
|
||||
| 判定 | `PLAN.md` 章节 |
|
||||
|---|---|
|
||||
| **原样取(不复述,以 `PLAN.md` 为准)** | §6.1(段布局、shm 矩阵、`SCM_RIGHTS` 第一优先、`SEG_SHADOW` 退休规则);§6.2/§6.2a(`RingControl`、双向 doorbell);§6.3(记录格式与运行期边界检查);§6.4(WAR 纪律与 P4.5 零拷贝);§6.5(ring 分配与背压);§6.6 前三条;§6.7 第 2、5 行;§6.8(三档采纳与 POST 探针);§7.1-§7.3;§8 末尾(真 fence 退休 + 三个独立 `dev` 修复);§9-§9.3;§10(线程模型、核心放置、拆机顺序);§11.1-§11.6;§12 第 1-3 层与 §12.4;§13(目录、一库两角色、submodule guard、三个 ctest 陷阱、`SPLIT` 接线、CI 门);§15 P0 的卫生与两个 spike |
|
||||
| **取并改** | §7.4(事件通道:**`on_log` 按严重级分级**,§7.4);§12.2(隔离从四个进程全局降到**两个**);§5.10(第 2、3 条逐字取,第 1 条缩成一个 `hasLiveHostWrites` 位);§6.10(四类应用指针改由 cap 门控 lowering;**陈旧索引纪律逐字保留并加门**);§5.9a(READ 面**编目**生成器改为**禁止**门);§6.4 的拷贝账(删掉第 (3) 行,P1-4=3 / P4.5=2,`PLAN.md` 的"方案 B"目标结构性达成) |
|
||||
| **弃** | §5.0、§5.1、§5.2、§5.4 的 replica 对象表规则与 `Fatal{IdentityDivergence}`、§5.6a、§5.7 的 Phase 1-4 分支与 `SetReplicaResolvedDrawProgram` 钩子、§5.9b 与全部 mutation 覆盖机制(`gen_impl_mutation_surface.py`、`MutationCoverage.def`、`ImplMutationSurface.inc`、`MG_Remote::Shared::`)、§6.9 的 relink 档与 `MOBILEGL_IPC_PROGRAM`、§12 第 4 层的字节一致断言、`Server/ReplicaContext.*`、阶段 **P5**、风险 **R1** 与 **R6**、开放问题 **§17-5** |
|
||||
| **新增(`PLAN.md` 没有的)** | `MG_Pipe/` 全套与六个生成器;`PipeInputs` + poison mask;`MOBILEGL_PIPE_VERIFY` 影子比对;残余值块与它的编译错误退役绊线;`on_texture_pull_request` / `on_texture_writeback` / `on_mip_levels_generated` 三个事件;纹理拉取的三条缓解与计数器;`HandleRecycleScenario` / `TextureRemintPullScenario` 两个场景;`RenderbufferObject::GetLifetimeId()`(**不含 `GetVersion()`**);D21 的潜伏 bug 修复 |
|
||||
|
||||
### 14.2 对 `Feat/CS-Delta-IPC`(worktree `../MobileGL-CS`)的复用
|
||||
|
||||
`PLAN.md` §14 的 REUSE / CHANGE / DROP 判定**整体继承**。方案 B 的四处差异:
|
||||
|
||||
| 条目 | `PLAN.md` 判定 | 方案 B 的差异 |
|
||||
|---|---|---|
|
||||
| `docs/CS_Refactor/HandleSessionGeneration.md`(`546895aa`) | REUSE,三处修改,其中"handle 清单补 `RenderbufferObject::GetLifetimeId()` **与 `GetVersion()`**" | **只补 `GetLifetimeId()`**。`GetVersion()` 只是 replica 的 delta 触发器;推送模型里 `glRenderbufferStorage*` **本身**就是一次 pipe 调用 |
|
||||
| `docs/CS_Refactor/backend_read_inventory.md` + `extract_backend_read_inventory.py`(`546895aa`) | CHANGE 成 `gen_backend_state_surface.py`,未知 accessor 一律 UNMAPPED 并编译失败 | **同意其修正**(删掉制造"0 UNMAPPED"的 `GetBuffer*`/`GetTexture*`/`GetProgram*`/`GetVertex*` 前缀兜底规则 `:234-241`,把真 pull point 与 signature handle 化分开统计),但**用途改变**:它变成 tracker 侧的**覆盖检查表**(G6),而真正的门是 §4.7.2 的**纯度门**——禁止那次读,比编目它强得多,且不会过期。**另外:`gen_impl_mutation_surface.py` 在方案 B 里不存在**(没有 replica 就没有 mutation 要 replay) |
|
||||
| `MobileGL/RemoteClient/StateEmitter.h:39-307`(仅 emit 半边,`b50f3348`+`d96be9f3`) | CHANGE,各域字段遍历抬进 `WireMirror` | **更直接可用**:在 MGPipe 下那些字段集**就是** pipe 的状态对象 payload(`MGPFramebufferState`、`MGPVertexElements`、`MGPSamplerView` …),不再是一份 delta 目录。同样必须修的缺陷不变:GL name 换 lifetimeId(`:48-49, 85, 166-168, 203, 230`)、O(n²) 线性扫描换 handle map(`:175-181, 244-249, 253-258, 293-298`)、固定 6 attachment(`:232-236`)换 `MaxColorAttachments`、补上被跳过的 texture view(`:70-74`)。**applier 半边(`:312-501`)仍然不取** |
|
||||
| `MobileGL/Protocol/mg_protocol_base.h`(`546895aa`) | REUSE(干净无依赖的词汇) | **同意**,且 **structSize-first 版本纪律是 B-R10 的对策**:payload 结构体从第一天就可增长 |
|
||||
|
||||
**DROP 名单完全一致**:`bfa.h`(480 行,"strict C ABI" 名不副实,且手抄的 60 字段 `MobileGLDynamicParameters` 是本项目已造成 481 例 CTS 失败簇的那类静默漂移炸弹)、`mgruntime_api.h` + `UtilRuntime/*`、`LocalSocketTransport` 的实现(每次 send 的 UAF、无上限分配、**`fd=-1` 硬编码**)、`ServerHost/main.cpp`(编译不过)、`StateEquivalenceTest.cpp`、`c7c9e346`+`29d721ef` 的 share-group sessioning、`b50f3348` 的 `RenderState::InstallParameters` + 裸 `public:`、`d96be9f3` 的 per-draw `fprintf` TRIAGE 指令。
|
||||
|
||||
---
|
||||
|
||||
## 附 A:接口调用目录速查表
|
||||
|
||||
> 完整 payload 定义见 `MG_Pipe/MGPipeTypes.h`;本表按 `PipeCalls.def` 的顺序。Flags:`A`=`kNeedsAck`、`B`=`kHasBlob`、`V`=`kVarTail`、`H`=`kHostSpan`、`R`=`kReplySlot`、`O`=`kOptional`(可为 null)。
|
||||
|
||||
### `MGPipeScreen`(14)
|
||||
|
||||
| 调用 | payload | flags | 取代 |
|
||||
|---|---|---|---|
|
||||
| `get_caps` | `MGPCaps` | R | 40 `pActiveBackendObject->` + 89 caps 读点 |
|
||||
| `resource_create` | `MGPResourceDesc` | — | buffer/texture/renderbuffer 创建 |
|
||||
| `resource_respecify` | `MGPResourceDesc` | — | `BufferBackendOps::Respecify` 泛化 |
|
||||
| `resource_destroy` | handle | — | `OnDestroy` + 两个 `WeakPtr` GC 扫描 |
|
||||
| `map_persistent` / `unmap_persistent` | handle | R, O | `AcquirePersistentMap`(改造期不碰) |
|
||||
| `fence_create` / `fence_status` / `fence_wait` / `fence_destroy` | handle (+timeout) | — / — / R / — | `FenceSync`…`GetSyncStatus`(两值契约保留) |
|
||||
| `query_create` / `_begin` / `_end` / `_available` / `_result` / `_destroy` | handle + kind | — | `BackendObject.h:230-256` |
|
||||
|
||||
### `MGPipeContext` — CSO(15)
|
||||
|
||||
`create/bind/delete` × `render_state` / `vertex_elements` / `sampler` / `sampler_view` / `shader`。
|
||||
`create_render_state` 带 `B`(整块或变化段);`create_shader_state` 带 `B`(SPIR-V + 反射归档)。
|
||||
|
||||
### `MGPipeContext` — `set_*`(14 + 1 临时)
|
||||
|
||||
`set_framebuffer_state` · `set_vertex_buffers` · `set_index_buffer` · `set_indirect_buffers` · `set_sampler_views`(V) · `bind_sampler_states`(V) · `set_shader_images`(V) · `set_shader_buffers`(V) · `set_stream_output_targets`(V) · `set_global_constants`(B) · `set_vertex_attrib_defaults` · `set_pixel_pack_state` · `set_patch_state` · `set_draw_program` / `set_dispatch_program`
|
||||
**临时(P2..P13)**:`set_residual_value_state`(B),带 `static_assert(sizeof(ResidualValueBlock)==0)` 退役绊线。
|
||||
|
||||
### `MGPipeContext` — transfer(12)
|
||||
|
||||
`resource_subdata`(B,V) · `buffer_subdata_resident`(B,O) · `resource_flush_range` · `resource_readback`(R) · `resource_copy_region` · `blit` · `clear` · `generate_mipmap` · `read_pixels`(R) · `get_texture_image`(R)
|
||||
|
||||
### `MGPipeContext` — 命令(10)
|
||||
|
||||
`draw_vbo`(H,V) · `launch_grid` · `memory_barrier` · `begin/end/pause/resume_stream_output` · `flush` · `present` · `set_swap_interval`(O)
|
||||
|
||||
### 反向:`MGPipeCallbacks`(9)
|
||||
|
||||
`on_gl_error` · `on_gpu_written` · `on_buffer_writeback` · `on_texture_writeback` · `on_texture_pull_request` · `on_mip_levels_generated` · `on_surface_changed` · `on_caps_invalidated` · `on_log`(**≤WARN 有损 / ≥ERROR 无损 + 速率限制**)
|
||||
|
||||
### 显式删除
|
||||
|
||||
`GetIntegeri_v` · `GetInteger64i_v` · `GetProgramiv` · `ShaderStorageBlockBinding`(折进 `MGPProgramDesc`)· `set_pixel_unpack_state`(不存在)· 压缩格式概念(不存在)· `pipe_transfer`(不存在)
|
||||
|
||||
---
|
||||
|
||||
## 附 B:环境变量与 CMake 选项
|
||||
|
||||
### CMake
|
||||
|
||||
| 选项 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `MOBILEGL_BUILD_DISAGGREGATED` | OFF | 出货形态。开启后 `MG_Remote/**` 进 `SOURCE_FILES`,支持 `spawn`/`unix:`/`pipe:`。**两个**进程全局保持普通全局,GL 热路径无 TLS |
|
||||
| `MOBILEGL_BUILD_DISAGGREGATED_INPROC` | OFF | CI/调试形态,隐含开启上者,额外加角色隔离 shim(方案 B 下只需隔离 `gPipeCtx` 与 `pActiveBackendObject`) |
|
||||
| `MOBILEGL_FLATC_EXECUTABLE` | 空 | 只服务 CI 的 `flatc-check`;默认构建图里没有 `flatc` |
|
||||
| `MOBILEGL_BAKED_INTERNAL_SHADERS` | ON(P7+) | DirectVulkan 的 blit/depth-mipmap shader 烘焙成签进树的 SPIR-V,由 `MG_Test` 重跑树内 glslang 逐字节比对守新鲜度。**monolith 也受益**(少一次启动期 glslang 编译) |
|
||||
|
||||
> 注:`MG_Pipe/**` **不在任何 option 之后**——它是 monolith 的架构,永远进构建。
|
||||
|
||||
### 运行时(方案 B 新增)
|
||||
|
||||
| 变量 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `MOBILEGL_PIPE_PUSH` | 迁移期按阶段推进;P13 后删除 | 子系统位图(0 = 全 pull)。**任何提交都能在同一份二进制上按子系统 A/B** |
|
||||
| `MOBILEGL_PIPE_VERIFY` | 0 | 逐 draw 逐字段影子比对(~5-10× 慢,永不出货,P13 后保留为工装) |
|
||||
| `MOBILEGL_PIPE_STATS` | 0 | 字节/调用/roundtrip/纹理拉取/残余块计数器转储 |
|
||||
| `MOBILEGL_PIPE_TEXEL_RETAIN_MB` | 32 | 纹理重铸拉取的保留 LRU 预算上限(§7.5c) |
|
||||
|
||||
### 运行时(继承 `PLAN.md` 附录)
|
||||
|
||||
`MOBILEGL_TRANSPORT`(`monolith` 默认 / `inproc` / `spawn` / `unix:<path>` / `pipe:<name>`)· `MOBILEGL_IPC_SERVER_PATH` · `MOBILEGL_IPC_RING_MB`(8) · `MOBILEGL_IPC_STAGE_MB`(32,上限由实测定) · `MOBILEGL_IPC_PRESENT_CREDIT`(**1**) · `MOBILEGL_IPC_SPIN_US`(50) · `MOBILEGL_IPC_POLL_ESCALATE`(64) · `MOBILEGL_IPC_PERSISTENT_BLOCK_KB`(64) · `MOBILEGL_IPC_ADOPT_TIER`(auto) · `MOBILEGL_IPC_SHADOW_SHM`(1,P4.5+) · `MOBILEGL_IPC_INLINE_PAYLOADS`(0,负面对照) · `MOBILEGL_IPC_SERVER_AFFINITY`(auto) · `MOBILEGL_IPC_STRICT_ERRORS`(0,诊断) · `MOBILEGL_IPC_AUDIT`(0) · `MOBILEGL_IPC_TRACE`(0) · `MOBILEGL_IPC_ATTACH`(空) · `MOBILEGL_IPC_RESPAWN`(0) · `MOBILEGL_IPC_IDLE_EXIT_S`(30)
|
||||
|
||||
**删除**:`MOBILEGL_IPC_PROGRAM`(没有 relink 档)· `MOBILEGL_IPC_VALIDATE_SERVER`(server 没有 `MG_Impl` 校验器——替代诊断手段见开放问题 11)
|
||||
|
||||
**保留的既有负面对照开关**:`MOBILEGL_ESPRYT_DISABLE_UBO_RING` · `_UNPACK_RING` · `_UPLOAD_RING` · `_INVALIDATE_FLUSH` · `MOBILEGL_DISABLE_LARGE_BUFFER_ADOPTION` · `MOBILEGL_COHERENT_AS_FLUSH`(**在拆分模式下照常生效**,这样两个 `coherent_as_flush: true` 的 Create fixture 在 split 与 monolith 下走同一条 buffer 路径,逐名对比才有意义)
|
||||
@@ -0,0 +1,7 @@
|
||||
# citation self-test
|
||||
|
||||
Good, resolvable by basename: `DirectGLES.cpp:2916` and `RenderState.h:263`.
|
||||
Good, full path with a range: `MobileGL/MG_Backend/BackendObject.h:302-522`.
|
||||
Bad, past the end of the file: `SamplerObject.h:468-492`.
|
||||
Bad, no such file at this revision: `NoSuchThing.cpp:12`.
|
||||
Bad, inverted range: `RenderState.h:400-100`.
|
||||
@@ -0,0 +1,27 @@
|
||||
# P0 polish package: findings from the final review of feat/disaggregated 8349babe..aa005720
|
||||
|
||||
All line numbers refer to the tree at aa005720 (~/w7/pipe). Fix every item below.
|
||||
|
||||
## MAJOR
|
||||
|
||||
### T-1 (transport, inproc doorbell has no death state -> Shutdown can never join a parked waiter)
|
||||
`InProcessChannel::Close()` (MobileGL/MG_Remote/Transport/InProcessTransport.cpp:74-88) rings each `CondVarDoorbell` once and the comment at :83-84 claims this stops a peer parked mid-frame from hanging. It does not: `Doorbell::Wait` (Doorbell.h:136-176) consumes that one ring, re-tests `ready()` (false, nothing was published), tests `Dead()` - which `CondVarDoorbell` never overrides (Doorbell.h:113, :199-211; Doorbell.cpp:29-71 has no death state) - and with `kWaitForever` loops straight back into `Park()`, forever. `Shutdown()` of the inproc transport can therefore never join a server thread that is in the design's own steady state (consumer spins, sets consumerParked, then blocks). No test covers it (every `Wait` in MG_Test/Wire uses 5000/30/0 ms).
|
||||
Fix: give `CondVarDoorbell` an `std::atomic<bool> m_dead` + `void Kill()` (set under the mutex, `notify_all`), override `Dead()`, make `Park` return false immediately when dead, have `Close()` call `Kill()` (keep `Notify()` for raw `Park` callers), and add `InProcessTransportTest.ShutdownUnparksAWaiterWithNoDeadline` (a thread in `Wait(parked, []{return false;}, kDefaultSpinUs, kWaitForever)`, `Shutdown()` from the test thread, join within a bound). Verify the test hangs (or times out) without the fix.
|
||||
|
||||
### T-2 (transport, ring accepts records it can never place -> silent producer stall)
|
||||
Ring.cpp:126 only refuses `total > m_capacity`, but a record with `capacity/2 < total <= capacity` is unreservable at any offset where neither `spaceToEnd >= total` nor `offset >= total` holds, even in an empty ring: `Reserve` (:137-148) needs `spaceToEnd + total` bytes when a pad is required, which exceeds capacity there. Concrete: 256-byte ring, one 16-byte record written, popped and retired (head offset 16, FreeBytes()==256), `Reserve(1, kRecNone, 240)` (total 248) returns nullptr forever; a producer waiting on `FreeBytes() >= 248` deadlocks. For `total <= capacity/2` the worst case is `2*total-8 <= capacity-8`, so half is the correct bound.
|
||||
Fix: reject `total > m_capacity / 2` at Ring.cpp:126 (same message, "half the ring"), state `Capacity()/2` as the chunking bound in Ring.h:169-174 and in the G3 chunking comment in MobileGL/MG_Pipe generated header comments / gen_pipe.py where the "record larger than the segment -> chunk" rule is stated, and add `RingTest.RecordLargerThanHalfTheRingIsRefused` plus the offset-16/248 scenario as the negative control (today it spins on nullptr).
|
||||
|
||||
### P-1 (interface hole: the six backend-owned compute limits have no carrier)
|
||||
`MGPCaps` (MobileGL/MG_Pipe/MGPipeTypes.h:123-140) is `DynamicBackendParameters` + `CallMask` + two blobs, and `DynamicBackendParameters` (MobileGL/MG_Backend/BackendObject.h:316-530) carries `MaxComputeWorkGroupInvocations` but no per-axis `MaxComputeWorkGroupCount[3]` / `MaxComputeWorkGroupSize[3]`. Those six are exactly the backend-owned answers that survive the getter retirement (GL_Getter.cpp:1160-1177, MG_Util/ShaderTranspiler/CompileEnv.cpp:134-138, DirectVulkan.cpp:672-703 from VkPhysicalDeviceLimits), yet the .def footer (MobileGL/MG_Pipe/PipeCalls.def:143-145) repeats the disproved claim that "only GL_COMPUTE_WORK_GROUP_SIZE is a real backend answer and it lives in MGPCaps".
|
||||
Fix: add `Int MaxComputeWorkGroupCount[3]; Int MaxComputeWorkGroupSize[3];` to `DynamicBackendParameters` and fill them in BOTH backends at capability init (DirectGLES from `glGetIntegeri_v(GL_MAX_COMPUTE_WORK_GROUP_COUNT/SIZE, i)` where the other limits are probed; DirectVulkan from `VkPhysicalDeviceLimits::maxComputeWorkGroupCount/Size`), keep the `GetIntegeri_v` table path working exactly as today (do NOT change GL_Getter/CompileEnv behaviour in this package - that is P0.5), add the unit/integration assertion that the new fields equal what `glGetIntegeri_v` answers (AdvertisedLimitsScenario is the natural home), and rewrite the .def footer to say the six limits live in MGPCaps and GL_COMPUTE_WORK_GROUP_SIZE is a frontend link artifact. Update the MGPCaps size assertion accordingly (it is a composition of sizeof(DynamicBackendParameters)+...).
|
||||
|
||||
## MINOR (one hygiene commit)
|
||||
|
||||
- S-1 stats: `PipeStats.cpp` `OnPresent()` does `store(0)` on `g_frameBytes/Calls/Gate*` which races with a concurrent `Bump` from another thread (buffer/texture staging is multi-threaded per the header): a frame-scoped add can be lost from the Tracy plot. Fix: `exchange(0, relaxed)` and plot the exchanged value.
|
||||
- T-3 FdPassing.cpp:207-209: when `MSG_CMSG_CLOEXEC` is absent (macOS/BSD) received fds have no CLOEXEC; add `fcntl(fd, F_SETFD, FD_CLOEXEC)` for every received fd under `#if !defined(MSG_CMSG_CLOEXEC)`. Same platform: `MSG_NOSIGNAL` (FdPassing.cpp:136, Doorbell.cpp:94) is undefined there; `#ifndef MSG_NOSIGNAL` -> 0 plus `SO_NOSIGPIPE` on the socket.
|
||||
- T-4 CMakeLists.txt:444-445: `set(... CACHE BOOL ... FORCE)` writes OFF into the cache, so after the operator runs `git submodule update` a plain re-configure still yields OFF with no message. Use a normal-variable `set(MOBILEGL_BUILD_DISAGGREGATED OFF)` (shadows the cache for this configure only) with the same message(WARNING).
|
||||
- P-2 PipeCalls.def: three live GLFunctionsTable entries have no carrier: `GetGpuTimestampNs` (GL_Getter.cpp:1355/2265, glGetInteger64v(GL_TIMESTAMP), synchronous server answer), `QueryCounterTimestamp` (glQueryCounter, not a begin/end pair), `WaitSync` (GPU-side wait, distinct from FenceWait's client wait). Records are append-only: APPEND `QueryTimestamp` (kCtxQuery, kReplySlot), `QueryCounter` (kCtxQuery) and `FenceWaitServer` (kScreen) at the end of their groups' natural place BUT without renumbering any existing opcode (append to the end of the list if opcodes are positional), regenerate with gen_pipe.py, update the catalogue counts in the .def header and the PipeCatalogueTest expectations.
|
||||
- P-3 MGPipeTypes.h:411-417 inlines a 32 B `MGHostSpan` in every `MGPBufferRange` of every class, and `MGPStreamOutputTargets` (:429-436) reuses it: 32 B/entry of dead space for SSBO/atomic/XFB records, and the plan's D-B8 says not to freeze this payload's shape before the `stage-ubo-named` numbers exist. Keep the range at 24 B and carry the named-UBO host span as an optional var-tail (flag kHostSpan on set_shader_buffers already exists) - adjust the payload, its field list, the size assertion and the test.
|
||||
- P-4 (accepted in review 1, never reworked): ConfigLoader.cpp:164-183 `QueryEnvUint64` accepts `-1` and silently reads octal via `strtoull(...,0)` - parse base 10 (and 0x prefix explicitly if wanted), reject a leading '-' with the warning; test.yml pipe-gates stdio grep misses `fprintf(stdout` - extend the alternation; `MGPSubData` has no buffer offset/size convention - document (and if needed add) how the buffer half of resource_subdata expresses [offset,size) (e.g. UnionBox.x/w with target==Buffer) and assert it in the test; `gen_pipe.py` does not check that every call payload has a verify field list - make it fail when a payload named in PipeCalls.def has no entry in PipeFields.def (except the documented memcmp-fallback types), and add the check to `--check`.
|
||||
- The first-review minor "MGPPixelPackState size assertion is tautological" (it asserts sizeof against itself): assert against the literal 28 that PixelStoreParameters measured.
|
||||
@@ -0,0 +1,276 @@
|
||||
# P0.5 spec extract — MGPipe design docs (feat/disaggregated @ 6e0e3df3)
|
||||
|
||||
Sources, all under `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg/docs/Disaggregated/`:
|
||||
`README.md` (57 lines), `ARCHITECTURE.md` (601 lines), `ROADMAP.md` (90 lines), `MEASUREMENTS.md` (96 lines).
|
||||
All line numbers below are lines I actually opened. Docs are in Chinese; requirement wording is quoted verbatim.
|
||||
|
||||
---
|
||||
|
||||
## 0. Where P0.5 sits
|
||||
|
||||
- `README.md:3` (verbatim): "> 状态:**P0 已落地**(`feat/disaggregated@458ccde1`,基线 `dev@81b17c0b`)。下一步 P0.5 → P1 → P2,第 43 天 GO/NO-GO。见 `ROADMAP.md`。"
|
||||
- `ROADMAP.md:9` (the two tracks, verbatim): "两条跑道:**monolith 跑道** P0 → P0.5 → P1 → P2 → P3a → P4a → P3b/P4b → P7 → P8 → P13,每段可独立交付、可随时中止且 monolith 严格好于起点;**IPC 跑道** P5 → P6 → P9 → P10 → P11 → P12。"
|
||||
- Day budget: `ROADMAP.md:32` "累计(低端):P0 9 → P0.5 15 → P1 25 → P2 43 …" i.e. P0.5 is days 10–15 on the low estimate; the row itself says **6–9 人天**.
|
||||
- `ROADMAP.md:3` sets the global framing: total 267–337 人天, two engineers, "真正的约束是两台设备的争用".
|
||||
|
||||
---
|
||||
|
||||
## 1. The P0.5 ROADMAP row (`ROADMAP.md:16`) — verbatim, field by field
|
||||
|
||||
Row header columns are `| 阶段 | 天 | 落地什么 | 验收门 | 依赖 |` (`ROADMAP.md:13`).
|
||||
|
||||
**阶段**: "**P0.5** 值头与制品头抽取"
|
||||
**天**: "6–9"
|
||||
|
||||
**落地什么** (verbatim):
|
||||
> `MG_Pipe/MGPipeValueTypes.h`(`RenderStateParameters`、`SamplerParameters`、`PixelStoreParameters`、`VertexAttribute`… 不 include `MG_State/GLState`);`MG_State/GLState/ProgramState/ProgramArtifacts.h`(五个反射类型,不 include `ShaderObject.h`/`SpvcSession.h`,更新 7 个 includer);`Visit()` 归档 + `sizeof` 绊线;CI `-H` include 闭包断言
|
||||
|
||||
**验收门** (verbatim):
|
||||
> 全套测试逐名不变(纯搬移);两条闭包断言绿且人为加回一个 `MG_State` include 能变红;`nm`/`.text` 变化可逐符号归因
|
||||
|
||||
**依赖** (verbatim):
|
||||
> P0;**P1 与 P7 的硬前置**
|
||||
|
||||
Three acceptance clauses decoded for implementers:
|
||||
1. **Pure move**: every test must still pass *by name* — no behavioural change, no renames of tests, nothing new. The move is mechanical.
|
||||
2. **Two closure assertions must be green AND must be able to go red**: this is the project-wide discipline "**每个门必须能因它存在的理由变红**" (`ROADMAP.md:7`). Deliberately re-adding one `MG_State` include has to break the gate. Two assertions = one per new header (`MGPipeValueTypes.h` must not reach `MG_State/GLState`; `ProgramArtifacts.h` must not reach `ShaderObject.h`/`SpvcSession.h`).
|
||||
3. **`nm`/`.text` diffs must be attributable symbol-by-symbol** — a pure header split may move symbols/inlining, but every delta must be explainable. (Contrast P1, `ROADMAP.md:17`, which demands `nm --defined-only` *unchanged*.)
|
||||
|
||||
### Other P0.5 mentions in ROADMAP.md
|
||||
|
||||
- `ROADMAP.md:17` — P1's 依赖 column is exactly "P0.5".
|
||||
- `ROADMAP.md:24` — P7's 依赖 column: "P0.5、P2;可与 P5/P6/P8 并行".
|
||||
- `ROADMAP.md:34` (CTS turnaround, verbatim): "完整 caselist 只在五个架构边界(P0.5、P3a、P4a、P3b/P4b、P13)与每次合并 `dev` 之前跑,放 CI 不放关键路径。" — so P0.5 exit owes a **full `gl44to46` caselist run (~56,271 例)**, in CI, not on the critical path. Per-phase otherwise only named blocks are run.
|
||||
- `ROADMAP.md:57` (NO-GO branch, verbatim): "**不回滚**:P0/P0.5/P1/P2 的产物(句柄基建与重键、两个头文件抽取、计数器、verify harness、渲染状态 CSO)全是自洽的 monolith 交付物,留在 `dev`" — the two header extractions survive a NO-GO.
|
||||
- `ROADMAP.md:58` (verbatim): "沉没成本:P0 与 P0.5 无论走哪条路都要花(后者本身是 monolith 净收益);真正只为 MGPipe 押上的是 P1 + P2 ≈ 28–39 天".
|
||||
- `ROADMAP.md:80` — open question 7, the `MG_Util` seam; see §5 below.
|
||||
- P0.5 is **not** on the GO/NO-GO checklist (`ROADMAP.md:42-58`); the 第 43 天 gate is P2's exit.
|
||||
|
||||
---
|
||||
|
||||
## 2. What ARCHITECTURE.md says about the two headers
|
||||
|
||||
### 2.1 The normative paragraph — `ARCHITECTURE.md:260` (§7, Shader state)
|
||||
|
||||
Verbatim, in full (this is the single densest requirement in the whole P0.5 scope):
|
||||
|
||||
> - **P0.5 硬前置**:反射类型今天声明在 `ProgramObject.h` 里,而它 include `ShaderObject.h`(→ glslang)与 `SpvcSession.h`(→ spirv_reflect)。P0.5 把 `TypeFacts`、`ResourceReflection`、`XfbVarying`、`LinkArtifacts`、`SpirvArtifacts` 抽到 `MG_State/GLState/ProgramState/ProgramArtifacts.h`(只 include `<Includes.h>` 与容器),更新 7 个 includer,加 CI `-H` 闭包断言。同批抽取 `MG_Pipe/MGPipeValueTypes.h`(`MAX_DRAW_BUFFERS`、`PerBufferBlendState`、`StencilFaceState`、`PixelStoreParameters`、`RenderStateParameters`、`SamplerParameters`、`BorderColorForm`、`VertexAttribute`、`VertexBufferBindingPoint`),它不 include `MG_State/GLState` 任何东西;`MGPipeTypes.h` 今天为此临时 include 了 `BackendObject.h` 与 `RenderState.h`(文件头注明为 P0.5 债务)。没有这一步,P7 的 `nm -D | grep glslang` 判据不可达。
|
||||
|
||||
Reading the two content lists as the authoritative manifests:
|
||||
|
||||
**`MG_State/GLState/ProgramState/ProgramArtifacts.h` — the five reflection types** (`ARCHITECTURE.md:260`):
|
||||
`TypeFacts`, `ResourceReflection`, `XfbVarying`, `LinkArtifacts`, `SpirvArtifacts`.
|
||||
Allowed includes: "只 include `<Includes.h>` 与容器" — `<Includes.h>` plus container headers, nothing else. Forbidden by construction: `ShaderObject.h` (pulls glslang) and `SpvcSession.h` (pulls spirv_reflect).
|
||||
Downstream: "更新 7 个 includer" — 7 files currently including the declarations must be repointed.
|
||||
|
||||
**`MG_Pipe/MGPipeValueTypes.h` — nine value types** (`ARCHITECTURE.md:260`; the ROADMAP row `ROADMAP.md:16` names a shorter, non-exhaustive subset with an ellipsis — treat ARCHITECTURE's list as the manifest):
|
||||
`MAX_DRAW_BUFFERS`, `PerBufferBlendState`, `StencilFaceState`, `PixelStoreParameters`, `RenderStateParameters`, `SamplerParameters`, `BorderColorForm`, `VertexAttribute`, `VertexBufferBindingPoint`.
|
||||
Constraint: "它不 include `MG_State/GLState` 任何东西".
|
||||
|
||||
**Debt being repaid**: "`MGPipeTypes.h` 今天为此临时 include 了 `BackendObject.h` 与 `RenderState.h`(文件头注明为 P0.5 债务)".
|
||||
Confirmed in tree — `MobileGL/MG_Pipe/MGPipeTypes.h:25-33` carries the note verbatim:
|
||||
```
|
||||
// P0.5 DEBT, recorded here so it is impossible to miss: two payloads reach into headers
|
||||
// this directory is eventually forbidden to see - MGPCaps embeds MG_Backend's
|
||||
// DynamicBackendParameters, and ResidualValueBlock embeds MG_State's RenderStateParameters
|
||||
// and PixelStoreParameters. Both are deliberate: the caps block IS that struct (section
|
||||
// 4.4.1) and the residual block is the migration carrier for Track V (section 6.3). P0.5
|
||||
// extracts MGPipeValueTypes.h and both includes below go away; until then purity gate A
|
||||
// (section 10.3) cannot be armed for this header.
|
||||
#include <MG_Backend/BackendObject.h>
|
||||
#include <MG_State/GLState/RenderState/RenderState.h>
|
||||
```
|
||||
and `MobileGL/MG_Pipe/MGPipeTypes.h:36-40` has the `using` aliases (`MG_Backend::DynamicBackendParameters`, `MobileGL::PixelStoreParameters`, `MobileGL::RenderStateParameters`) with the comment "P0.5 moves them into `MG_Pipe/MGPipeValueTypes.h`".
|
||||
Note the asymmetry the header records and the docs do not resolve: **`MGPCaps` embeds `MG_Backend::DynamicBackendParameters`** (via `<MG_Backend/BackendObject.h>`), which is *not* one of the nine types listed for `MGPipeValueTypes.h`. `ARCHITECTURE.md:112` confirms the design: "`MGPCaps` = `DynamicBackendParameters`(整块包含,~90 个标量含六个 compute 限制)+ `CallMask` + 两个 blob". Implementers must decide how that include is discharged; the ROADMAP row does not name it.
|
||||
|
||||
**Rationale sentence, verbatim** (`ARCHITECTURE.md:260`): "没有这一步,P7 的 `nm -D | grep glslang` 判据不可达。"
|
||||
|
||||
### 2.2 Current tree locations of the types (verified by grep, for the mechanical move)
|
||||
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h:44` `struct TypeFacts`
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h:76` `struct ResourceReflection`
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h:1146` `struct XfbVarying`
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h:1210` `struct LinkArtifacts`
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h:1409` `struct SpirvArtifacts`
|
||||
- `MobileGL/MG_State/GLState/RenderState/RenderState.h:191` `struct PixelStoreParameters`, `:202` `struct PerBufferBlendState`, `:212` `struct StencilFaceState`, `:222` `struct RenderStateParameters`
|
||||
- `MobileGL/MG_State/GLState/SamplerState/SamplerObject.h:66` `enum class BorderColorForm : Uint8`, `:72` `struct SamplerParameters`
|
||||
- `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h:17` `struct VertexAttribute`, `:58` `struct VertexBufferBindingPoint`
|
||||
- `MobileGL/MG_State/GLState/FramebufferState/FramebufferObject.h:106` `static constexpr Uint MAX_DRAW_BUFFERS = 8;` (note: it is a **class-scope constant inside `FramebufferObject`**, not a free constant — moving it is not a plain cut/paste; the doc lists it as part of the value header.)
|
||||
|
||||
Files that include `ProgramObject.h` today (candidate "7 个 includer" set; grep over `MobileGL/`, excluding `ProgramObject.h`/`.cpp` themselves):
|
||||
`MG_Backend/DirectVulkan/Renderer/ProgramFactory.h`, `MG_Backend/DirectVulkan/Renderer/UniformManager.cpp`, `MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp`, `MG_Impl/GLImpl/Program/ProgramInterface.cpp`, `MG_State/GLState/ProgramState/ProgramLinkTask.h`, `MG_State/GLState/ProgramState/ProgramPipelineObject.h`, `MG_State/GLState/ProgramState/ProgramState.h`, `MG_State/GLState/ProgramState/ProgramTranslationCache.h` (8 files; `MG_Pipe/MGPipeTypes.h:297` only mentions the name in a comment, not an include). Verify against the doc's count of 7 when doing the work — three of the eight are the DirectVulkan backend files, which are exactly the ones P7's symbol gate cares about.
|
||||
|
||||
### 2.3 The `create_shader_state` reflection archive (§7)
|
||||
|
||||
- `ARCHITECTURE.md:258` (verbatim): "`CreateShaderState` 的 payload 是逐 stage SPIR-V + 反射归档(`LinkArtifacts` + `SpirvArtifacts` 全结构体),**不是源码**。"server 从源码重新 link"这条路显式关闭:链接真 `ProgramObject` 就链接 glslang。glslang 全在 client,SPIRV-Cross(`TranspileSpirvToEssl`)全在 server,文件级切割。没有 `MOBILEGL_IPC_PROGRAM` 开关、没有 server 侧 compile pool。"
|
||||
- `ARCHITECTURE.md:259` — the archive mechanism and its **complete field coverage list**, verbatim:
|
||||
> - 归档机制:`Visit()` + `sizeof` 绊线(`static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE)`),一份字段表服务序列化两个方向。必须覆盖四个 `ResourceReflection`(各带 `TypeFacts`)、`uniformSamplerOrImageUnitIndex`、`uniformBlockBinding`、`shaderStorageBlockBinding`(按名字)、`explicitOpaqueUniformBindings`、`xfbVaryings/xfbStrides/xfbPackedStride/xfbNeedsScatteredCapture`、`computeLocalSize`、GS/TCS/TES 事实、`usesReservedNumSamples`、`uniformOffsets`。`XfbVarying` 带两套拼写(GL 名字 + block 实例/成员/元素)。
|
||||
- Payload shape: `MGPProgramDesc` is 192 B — "逐 stage SPIR-V blob ×6 + 反射归档 blob + `StageMask`/`GlobalUboSize`/`ReservedNumSamplesOffset` + 四个状态字节,§7" (`ARCHITECTURE.md:134`, the payload table). Confirmed in tree at `MobileGL/MG_Pipe/MGPipeTypes.h:299-310` (`MGPProgramDesc` with `MGPBlobRef Spirv[6]; MGPBlobRef Reflection;`), and the comment at `:296-298` says "P0.5 extracts those types out of ProgramObject.h so a server can deserialize into them without dragging in glslang".
|
||||
- Size of `MGPProgramDesc` = 192 is also pinned in `MEASUREMENTS.md:86`.
|
||||
- Related archive consumers: `ShaderStorageBlockBinding` is explicitly **not** ported as a pipe call — "`ShaderStorageBlockBinding`(折进反射归档)" (`ARCHITECTURE.md:102`). Stage dimension is derived by the server *from the reflection archive*: "stage 只在目标 API 需要时由 server 从反射归档推导" (`ARCHITECTURE.md:97`).
|
||||
- The archive also feeds client-side XFB scatter: "client 拥有目的 shadow 与反射归档里的 varying/stride,原样跑补丁循环" (`ARCHITECTURE.md:310`).
|
||||
- Emission timing (matters for who may touch these types): "`create_shader_state` 从编译池的终止 continuation 发出(不是从 draw),SPIR-V 在首个用到它的 draw 之前到达 server——monolith 拿不到的异步收益" (`ARCHITECTURE.md:194`).
|
||||
|
||||
### 2.4 The `Visit()` + `sizeof` 绊线 idiom
|
||||
|
||||
- Definition is `ARCHITECTURE.md:259` (quoted above): one field table serving **both serialization directions**, guarded by `static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE)`. The tripwire's purpose is that adding a field to the struct without adding it to `Visit()` becomes a compile error.
|
||||
- The same idiom family elsewhere in the design, for tone/precedent:
|
||||
- `ARCHITECTURE.md:116` — "每个 payload 是平坦 POD、显式 padding、`static_assert` 平凡可复制与**精确尺寸**;**永不含指针**。"
|
||||
- `ARCHITECTURE.md:359` — `ResidualValueBlock` discipline: "退役是编译错误(`MGL_RESIDUAL_BLOCK_SIZE` 只降不升,`MobileGL/MG_Pipe/MGPipeTypes.h:535`,P13 变成 `static_assert(sizeof == 0)`);布局逐成员 `offsetof` 断言且 split 下逐字段序列化(异质 POD 并集的 padding 差异 monolith verify 看不见)".
|
||||
- `ARCHITECTURE.md:184` — why `RenderStateParameters` moves as one block and why field order is load-bearing: "`RenderStateParameters` 是平凡可复制 POD,Espryt 自己 `static_assert` 并做 head/blend/tail 三段 memcmp,**字段顺序承重**(`ScissorBoxWrittenMask`、`ClipDistanceEnabledMask` 故意放在 tail 段);拆成 blend/depth-stencil/rasterizer 三个 CSO 要手工维护 ~150 字段划分表且无绊线。" → **Do not reorder fields while moving `RenderStateParameters`.** Espryt's own `static_assert` + three-segment memcmp must keep working; `ARCHITECTURE.md:188` says `SyncRenderState` (693 lines) must not change a line, and P2's gate repeats it (`ROADMAP.md:18`).
|
||||
- `RenderStateParameters` is 1168 B (`MEASUREMENTS.md:86`, `ARCHITECTURE.md:188`), inside `ResidualValueBlock` = 1248 B (`ARCHITECTURE.md:134`, `MEASUREMENTS.md:86`).
|
||||
- Also note `ARCHITECTURE.md:188`: "Espryt 的 head/blend/tail 划分(驱动侧增量)与 pipeline/dynamic 划分(线上与身份)是两回事,并存、各有绊线。" Two independent partitionings of the same struct both have tripwires.
|
||||
|
||||
### 2.5 Purity / include-closure gates (§13.2 item 1, and §16 CI)
|
||||
|
||||
`ARCHITECTURE.md:501`, verbatim (the three purity gates — P0.5 is the enabler for gate A, P7 for gate B):
|
||||
|
||||
> 1. **接口纯度三道门**(只跑非 verify 构建):**A 门 include 图**——disaggregated 配置编译 `MG_Backend` 时把 `MG_State/GLState` 从 include 搜索路径移除(`nm --undefined-only` 对"只 include 不调用"是瞎的,而 `RenderState.h → FramebufferObject.h → TextureObject.h` 正是这种耦合),依赖 P0.5;**B 门符号**——`nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空;**C 门未声明**——`grep -c 'pGLContext' MG_Backend/` == 0。外加 debug 断言"每个后端 memo 键都是 `{slot, gen}`,永不是裸前端指针",由 `HandleRecycleScenario` 支撑(重键前必须在至少一个后端上是红的)。
|
||||
|
||||
Key mechanics for P0.5:
|
||||
- Gate A is an **include-path removal**, not a grep: the disaggregated build of `MG_Backend` drops `MG_State/GLState` from the include search path. The cited coupling chain that makes symbol gates insufficient is `RenderState.h → FramebufferObject.h → TextureObject.h`.
|
||||
- The three gates "只跑非 verify 构建" and turn green only at P13 (`ARCHITECTURE.md:369`, `ROADMAP.md:30`); the P0.5 deliverable is the `-H` closure assertion, not gate A itself being green.
|
||||
- CI wiring: `ARCHITECTURE.md:568`, verbatim: "CI(`.github/workflows/test.yml:809` `pipe-gates`,P0 已落地):`gen_pipe.py` 重生成 + diff;`MG_Backend`/`MG_State` 下禁止 stdio 插桩的 grep 门;`gen_pipe_dirty_surface.py --summary`(信息性,P1 成门);`check_doc_citations.py`(警告级,文档定稿后 `--strict`)。独立 job `flatc-check`。后续:**`include-graph-check`(P0.5)**、`monolith-symbol-report`。"
|
||||
→ The new CI job is named **`include-graph-check`**. In tree today: `.github/workflows/test.yml:809` is `pipe-gates:`, `:304` is `flatc-check:`, `:861` runs `check_doc_citations.py … || true` (warning-level, as documented).
|
||||
- Also relevant, `ARCHITECTURE.md:425`: `WireLog.h` exists precisely so `Transport/` headers don't include the frontend umbrella — "纯度门 A 断言 `-H` 输出" — i.e. gate A's implementation is a compiler `-H` include-trace assertion, the same mechanism P0.5 must produce.
|
||||
- P13's endpoint for the value header (`ROADMAP.md:30`, verbatim fragment): "`MG_Backend` 的 `MG_State` include 收缩到 `MGPipeValueTypes.h`" — so `MGPipeValueTypes.h` is designed to be the *only* surviving `MG_State`-origin include of the backend.
|
||||
- Byte-level equalities that survive (context for the `nm`/`.text` attribution clause), `ARCHITECTURE.md:499` verbatim: ""改前改后 `nm --defined-only` 与 `.text` size 完全相等"的门在本方案里按构造死亡(不存在能让旧字节回来的配置)" and `:507`: "符号与 `.text` 漂移每阶段作为信息性指标发布。"
|
||||
|
||||
### 2.6 The `MG_Util` split seam — what the server may link vs. client-only
|
||||
|
||||
Two statements, both normative:
|
||||
|
||||
- `ARCHITECTURE.md:9` (verbatim): "server 进程因此只装 `MG_Backend` + MGPipe 对象表,不链接 `MG_State`、`MG_Impl`、glslang。"
|
||||
- `ROADMAP.md:80`, open question 7 (verbatim): "**`MG_Util` 的切割缝。** server 需要 SPIRV-Cross pass 流水线、ESSL 转译缓存、格式处理器、POST 探针;client 需要 glslang phase A/B 与反射层。P0.5 解决了 `ProgramObject.h` 一处,`MG_Util` 内部是否有干净的 Transpile-vs-Reflect 缝未审计。"
|
||||
|
||||
| side | needs |
|
||||
|---|---|
|
||||
| **server** | SPIRV-Cross pass pipeline, ESSL transpile cache, format handlers, POST probes; loader-side pieces implied by `MG_Backend` linking alone |
|
||||
| **client only** | glslang phase A/B, the reflection layer |
|
||||
|
||||
Status: **the seam inside `MG_Util` is explicitly un-audited** ("未审计"). P0.5's charter, per this question, closes exactly one point — `ProgramObject.h`. Implementers should not silently expand P0.5 into a `MG_Util` refactor; the doc treats that as still-open work. But the closure assertions they add are the tool that will later expose it.
|
||||
|
||||
Supporting facts:
|
||||
- File-level cut of the two toolchains: `ARCHITECTURE.md:258` — "glslang 全在 client,SPIRV-Cross(`TranspileSpirvToEssl`)全在 server,文件级切割。"
|
||||
- Espryt's SPIRV-Cross session and post-emission ESSL rewriting stay untouched on the server side: `ARCHITECTURE.md:316` lists "SPIRV-Cross 会话与 post-emission ESSL 重写、驱动 POST 自检族" among "原样不动的东西".
|
||||
- The shipped shared library still *contains* glslang because it serves both roles: `ARCHITECTURE.md:537` (verbatim) — "生产 server 主体是 ~30 行 stub:`dlopen(libMobileGL.so)` → `dlsym("mobilegl_server_main")`。一份共享库、两个角色、版本必然匹配(Android 上那份库仍含 glslang/SPIRV-Cross,因为它同时服务 client;B 门检的是 server 侧代码有没有引用它们)。"
|
||||
- Teardown ordering that assumes glslang is client-side: `ARCHITECTURE.md:520` — "client 排空 compile pool(先于 `glslang::FinalizeProcess()` 与 `pGLContext` 析构)".
|
||||
|
||||
### 2.7 The `nm -D libMobileGLServer.so | grep glslang` rule
|
||||
|
||||
- Stated as P7's acceptance gate, `ROADMAP.md:24` (verbatim, in P7's 验收门): "**`nm -D libMobileGLServer.so | grep glslang` 为空**".
|
||||
- Its dependency on P0.5, `ARCHITECTURE.md:260` (verbatim): "没有这一步,P7 的 `nm -D | grep glslang` 判据不可达。"
|
||||
- The stricter sibling is purity gate B, `ARCHITECTURE.md:501`: "`nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空".
|
||||
- What `libMobileGLServer.so` is: desktop `add_executable` linking `MobileGL_s`; Android `add_executable` renamed `lib*.so` linking shared `MobileGL`, packed by AGP into `jniLibs` (`ARCHITECTURE.md:565`); `mobilegl_server_main` must be `extern "C" __attribute__((visibility("default")))` because shipping builds are RelWithDebInfo with hidden visibility (`ARCHITECTURE.md:530`). Surviving byte-level equality: "`nm -D libMobileGL.so | grep mobilegl_server_main` 在 RelWithDebInfo 里命中" (`ARCHITECTURE.md:507`).
|
||||
- Practical implication for the archive: because the server must deserialize `LinkArtifacts`/`SpirvArtifacts` **without** any glslang symbol being referenced, the `Visit()` field table and the artifact structs must be glslang-free at the *type* level, not merely at the call level (gate A's whole premise, `ARCHITECTURE.md:501`).
|
||||
|
||||
---
|
||||
|
||||
## 3. What P1 and P7 need from these two headers (do not paint P1 into a corner)
|
||||
|
||||
### 3.1 P1 deliverables (`ROADMAP.md:17`, verbatim)
|
||||
|
||||
> `MG_Backend/MGPipe/PipeInputs.h`(Espryt 32 / Magma 55 访问器);`sed` 293 处 + 58 行非箭头清单逐条转换(显式交付物);逐 verb 类填充点(G5 表,~93 个边界站点);逐 verb 世代 poison;G4 影子比对器 + 第三种 CI 模式;20 处 `SyncPersistentMappedRange` + 6 处 `SyncGpuWrites` 的逐站点归属表
|
||||
|
||||
P1 acceptance (verbatim): "pull 构建 `nm --defined-only` 不变、`.text` 差异逐行归因(空守卫/三元重写推迟到 P2);40 trace + 全部集成测试在 `MOBILEGL_PIPE_VERIFY=1` 下零分歧;故意损坏一个快照字段能让 verify 变红;故意在 `glGenerateMipmap` 的填充表漏一个字段能在**那条 verb** 上触发 poison Fatal"
|
||||
|
||||
### 3.2 The `PipeInputs` / `MGB_CTX` shape P0.5 must not break (`ARCHITECTURE.md:325-340`, verbatim code block)
|
||||
|
||||
```cpp
|
||||
// MG_Backend/MGPipe/PipeInputs.h —— 按 memo 键组织,不按读点组织(~20 KB,字段集全迁移期稳定)
|
||||
struct PipeInputs {
|
||||
const RenderStateParameters& GetRenderStateParameters() const; // 阶段 A:类型与后端今天读到的完全一致
|
||||
// … 每个后端真正用到的 GLContext 方法一个访问器(Espryt 32 / Magma 55)
|
||||
#if MOBILEGL_DEBUG || MOBILEGL_BUILD_DISAGGREGATED
|
||||
Uint64 m_filledGen[kFieldCount]; // 逐字段"上次填充的 verb 序号"
|
||||
Uint64 m_currentVerbSerial;
|
||||
#endif
|
||||
};
|
||||
#if MOBILEGL_PIPE_PUSH
|
||||
# define MGB_CTX (&::MobileGL::MG_Pipe::gPipeInputs)
|
||||
#else
|
||||
# define MGB_CTX (::MG_State::pGLContext)
|
||||
#endif
|
||||
```
|
||||
|
||||
**Hard constraints this puts on P0.5:**
|
||||
1. **`PipeInputs` accessors return the exact types the backend reads today** — "阶段 A:类型与后端今天读到的完全一致" (`ARCHITECTURE.md:328`). `GetRenderStateParameters()` returns `const RenderStateParameters&`. So the moved `RenderStateParameters` must remain **the same type**, same namespace-visible name, same layout, same field order — a `using` alias or an identical-but-different type would break the mechanical `sed` and the `.text` attribution. Same for `PixelStoreParameters`, `SamplerParameters`, `VertexAttribute`, `VertexBufferBindingPoint`, etc.
|
||||
2. **`MGB_CTX` is a macro over `pGLContext` in the pull arm** — P1's phase A is a mechanical `sed` of `MG_State::pGLContext->` → `MGB_CTX->` at 293 sites plus 58 non-arrow lines (`ARCHITECTURE.md:344`). If P0.5 changes any of those spellings or the reachability of the value types from `MG_Backend`, the 293-site `sed` count and the "非箭头清单" become stale. **P0.5 must be a pure move that leaves every `MG_Backend` read site textually identical.**
|
||||
3. **The pull arm still includes `MG_State`** during P1–P12 — gate A is only armed later. So `MGPipeValueTypes.h` must be includable from *both* arms and must not force `MG_Backend` to stop seeing `MG_State` types yet.
|
||||
4. **Field-id table**: G5 generates `PipeInputs` field ids — 61 fields (`ARCHITECTURE.md:79`, `MEASUREMENTS.md:82`: "71 条调用(11 screen / 60 context)、63 个 verify payload、61 个 `PipeInputs` 字段"). Poison is a **per-verb generation**, not a bitmap (`ARCHITECTURE.md:349`): "每次 verb 递增 `m_currentVerbSerial`,字段被填时记下序号,读取时断言相等(跨 verb 有效的字段显式标 sticky)… 读一个当前 verb 未填的字段是 `Fatal{UnmigratedPipeInput, "GetStencilState@DrawVbo"}`。纯度门 grep 的是 `pGLContext` 不是 `pGLContext->`."
|
||||
→ Purity gate C greps the bare token `pGLContext`. Any comment or identifier P0.5 leaves in `MG_Backend/` containing that token counts against gate C later.
|
||||
5. **P1's verify harness (G4) compares field-by-field, never `memcmp`** — `ARCHITECTURE.md:502`: "逐字段而非 `memcmp`(padding 会 false-DIFFER)". So the moved structs' padding is not required to be identical to anything, but their **field list must be enumerable** by the `PipeFields.def` table (`ARCHITECTURE.md:78`: "字段表来自 `PipeFields.def`;浮点按位比较,NaN patch level 不会误报"). If P0.5 adds/removes/reorders a field, `PipeFields.def` and G4 must move with it — another reason for a pure move.
|
||||
6. **Track V is 55% of read points and rides `ResidualValueBlock`** (`ARCHITECTURE.md:353,359`), whose payload is `{RenderStateParameters, PixelStoreParameters, CapabilityBits, patch 三字段}` — i.e. it is built out of exactly the types P0.5 extracts, with per-member `offsetof` assertions and per-field serialization under split. Keep `offsetof` computability (standard-layout, no virtuals, no private/public interleaving that would break it).
|
||||
7. **`MOBILEGL_PIPE_VERIFY` survives P13** together with `SnapshotFromGLContext()` and its `MG_State` includes (`ARCHITECTURE.md:369`, D-B5: "**保留 `MOBILEGL_PIPE_VERIFY` 连同它需要的 `SnapshotFromGLContext()` 与 `MG_State` include**"). So `MGPipeValueTypes.h` must coexist with `MG_State` headers being included in the verify build — no `#error`-style mutual exclusion.
|
||||
|
||||
### 3.3 What P7 needs (`ROADMAP.md:24`, `ARCHITECTURE.md:321,263,142`)
|
||||
|
||||
- P7 deliverables (verbatim): "§5.5 其余 10 个子系统(子系统 1、4 已在 P2):`SetupDrawSnapshot` 探测字段塌成 dirty mask;占位纹理原生化(~120 行删除);具名 UBO host payload(D-B8,`kCapNeedsHostUboBytes`);blit/depth-mipmap 内部 shader 烘焙 + 新鲜度测试;`VertexInputStateFactory` 裸指针写回删除;D18 容器纪律原样保留"
|
||||
- The gate that depends on P0.5: "**`nm -D libMobileGLServer.so | grep glslang` 为空**" (§2.7 above).
|
||||
- Magma reads the reflection archive with SPIRV-Reflect and is one of the three archive consumers (see open question 8, §5 below).
|
||||
- Baked internal shaders (`ARCHITECTURE.md:263`, verbatim): "Magma 的两个内部 shader(blit、depth-mipmap)烘焙成签进树的 SPIR-V + uniform location + UBO 布局,用一个 `MG_Test` 重跑树内 glslang 逐字节比对守新鲜度(`MOBILEGL_BAKED_INTERNAL_SHADERS`,P7);顺带把一次 glslang 编译从 monolith 启动路径上删掉。" — this is the other half of getting glslang out of the server; P0.5's header split alone does not do it, and open question 13 (`ROADMAP.md:86`) flags "烘焙后的内部 shader 能否在没有活 `ProgramObject` 的情况下表达 uniform location 与 UBO 布局。**未做原型**。" That question bears directly on what `ProgramArtifacts.h` must be able to express standalone.
|
||||
- Server-side lazy specialization (`ARCHITECTURE.md:142`, D-B2): the backend program still needs 8 extra inputs beyond the archive (draw-FBO snorm/unorm clamp mask, fragColor broadcast count, storage-block binding signature, atomic counter set, live image formats, patch params; Magma adds default-FB height for FragCoord-Y-flip and XFB layout) — those are *pushed state*, not archive fields, so `ProgramArtifacts.h` must not try to absorb them.
|
||||
|
||||
---
|
||||
|
||||
## 4. Commit / CI discipline — ROADMAP §"通用纪律" (`ROADMAP.md:5-7`)
|
||||
|
||||
Verbatim, in full:
|
||||
|
||||
> ## 通用纪律(每个 commit)
|
||||
>
|
||||
> 默认 ALL target 必须完整构建;禁止提交热路径插桩(CI grep 门);**每个门必须能因它存在的理由变红**;Windows 机器不是正确性门;设备对比走 reboot-clean + 同热窗口配对 A/B,CPU 定频按项目协议;每阶段出口跑一次五部分门;每阶段性能判据是**逐线程 CPU 时间**。
|
||||
|
||||
Unpacked, with the backing references:
|
||||
- **默认 ALL target 必须完整构建** — every commit builds the whole default ALL target.
|
||||
- **禁止提交热路径插桩(CI grep 门)** — the existing gate is in `pipe-gates`: "`MG_Backend`/`MG_State` 下禁止 stdio 插桩的 grep 门" (`ARCHITECTURE.md:568`).
|
||||
- **每个门必须能因它存在的理由变红** — every gate must be demonstrably falsifiable. This is exactly what the P0.5 row demands ("人为加回一个 `MG_State` include 能变红", `ROADMAP.md:16`) and it recurs at P1 ("故意损坏一个快照字段"), P2 ("拿掉一个字段能红"), P4a ("落地前必须红"), P8, P9.
|
||||
- **Windows 机器不是正确性门** — repeated at `ARCHITECTURE.md:545`.
|
||||
- **设备对比走 reboot-clean + 同热窗口配对 A/B,CPU 定频按项目协议** — see `ARCHITECTURE.md:504` for the full method (two devices, `tools/bench.sh` + trace replay `--benchmark`, per-frame JSON, p50 and p99).
|
||||
- **每阶段出口跑一次五部分门** — the five-part gate is `ARCHITECTURE.md:497-505` (§13.2): ① three purity gates, ② `MOBILEGL_PIPE_VERIFY=1` shadow comparison, ③ behavioural A/B (40 traces SSIM ≥ 0.99, `ctest -L integration-gpu` name-for-name, unit tests, CTS within 0.5 pp with rate = Pass/(Pass+Fail), NS not in the denominator), ④ monolith performance non-regression (per-thread CPU time, p50/p99, absolute ns cap on the tracker, Blaze3D blend-toggle microbenchmark, CSO-content-addressing-off negative control), ⑤ coverage + poison + handle discipline (G6 0 UNMAPPED, `gen_pipe_dirty_surface.py` 0 unmapped mutators, per-verb poison, G7 setter consistency, `ResidualValueBlock` `offsetof` asserts).
|
||||
- **每阶段性能判据是逐线程 CPU 时间** — restated at `ARCHITECTURE.md:381` ("monolith 论据是逐线程 CPU 数字(§13.2-④),不是删除行数") and `ARCHITECTURE.md:519`.
|
||||
- CTS turnaround rule: `ROADMAP.md:34` — P0.5 is one of the five architecture boundaries owing a full `gl44to46` caselist (~56,271 cases), run in CI, off the critical path.
|
||||
- Repo-wide commit-message style (from project memory, not these docs): `[Type] (Scope): description`, single line, never add `Co-Authored-By`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Open questions in ROADMAP that touch these headers
|
||||
|
||||
All from `ROADMAP.md:70-90` ("仍然开放的问题"). `ROADMAP.md:72` notes what P0 already answered and is no longer listed.
|
||||
|
||||
**#7 — `MG_Util` 的切割缝** (`ROADMAP.md:80`, verbatim):
|
||||
> **`MG_Util` 的切割缝。** server 需要 SPIRV-Cross pass 流水线、ESSL 转译缓存、格式处理器、POST 探针;client 需要 glslang phase A/B 与反射层。P0.5 解决了 `ProgramObject.h` 一处,`MG_Util` 内部是否有干净的 Transpile-vs-Reflect 缝未审计。
|
||||
|
||||
**#8 — one reflection archive serving three consumers** (`ROADMAP.md:81`, verbatim):
|
||||
> **一份反射归档能否服务三个消费者**(Espryt 读前端表、Magma 跑 SPIRV-Reflect、`DirectVulkan.cpp` 为 `glGetProgramResource*` 又反射一遍)。
|
||||
|
||||
→ Direct bearing on `ProgramArtifacts.h`'s field set: the three consumers are (a) Espryt reading the frontend tables, (b) Magma running SPIRV-Reflect, (c) `DirectVulkan.cpp` reflecting a second time to answer `glGetProgramResource*`. The archive coverage list at `ARCHITECTURE.md:259` is the current best answer; whether it is sufficient for all three is **not settled**. Implementers should extract the types without narrowing them, and should not assume the field list is final.
|
||||
|
||||
**#5 — `FramebufferSrgb` / `DepthClamp` storage** (`ROADMAP.md:78`, verbatim):
|
||||
> **`FramebufferSrgb` / `DepthClamp` 的拍板。** 事实已清(无存储、`glEnable` 静默吞掉、六个读点恒 false、41 个 fixture 无一开启);建议在 chunk 表冻结前补真存储并把 `FramebufferSrgb` 划进 pipeline 半边。由计划所有者拍板,**拍板前不冻结 chunk 表**。
|
||||
|
||||
Supporting facts:
|
||||
- `ARCHITECTURE.md:190` (verbatim): "`FramebufferSrgb` 与 `DepthClamp` 今天**没有存储**(`glEnable` 被静默吞掉且不报错,六个后端读点恒为 false);chunk 表冻结前要补真存储并把 `FramebufferSrgb` 划进 pipeline 半边(它改变 attachment/blend 的解释)——待拍板,见 `ROADMAP.md`。"
|
||||
- `MEASUREMENTS.md:84` (verbatim): "**`FramebufferSrgb` / `DepthClamp`**:`FramebufferSrgb` 的六个后端读点全部消费一个编译期常量 `false`,`DepthClamp` 零读点;两者的 `glEnable` 落到 `RenderState.cpp` 的 `default:` 分支既不存储也不报 `GL_INVALID_ENUM`;41 个 fixture 无一开启任一项(补真存储不会改动任何既有 fixture 的输出)。"
|
||||
- The work itself is scheduled in **P2**, not P0.5: `ROADMAP.md:18` ends its deliverable list with "补 `FramebufferSrgb`/`DepthClamp` 存储".
|
||||
- **Impact on P0.5**: adding real storage means **adding fields to `RenderStateParameters`** — the very struct P0.5 moves, whose field order is load-bearing (`ARCHITECTURE.md:184`) and whose size (1168 B) is pinned by tripwires. P0.5 must move it *as-is* and leave the field addition to P2; but implementers should make the `sizeof`/`offsetof` tripwires easy to update in one place, since a P2 decision will change those numbers. Note also the chunk table (`MG_Pipe/MGPipeRenderStateSpans.{h,cpp}`, P2) must not be frozen before this ruling.
|
||||
|
||||
**#4 — wire granularity of render state** (`ROADMAP.md:77`, verbatim): "**渲染状态的 wire 粒度。** chunk 划分定下来后,CSO LRU 容量(暂定 64)与 `set_dynamic_state` 的 chunk 粒度由计数器定。" — same struct, same "don't freeze yet" posture.
|
||||
|
||||
**#6 — named-UBO host payload shape (D-B8)** (`ROADMAP.md:79`): first real number is in hand (Magma repacks 331 KB named-UBO bytes per frame in the 26.3 world, Espryt 0; `MEASUREMENTS.md:57,65`). Touches `MGPShaderBuffers`, not the two P0.5 headers directly, but the reflection archive's `uniformBlockBinding`/`shaderStorageBlockBinding` fields are what the server resolves against.
|
||||
|
||||
**#13 — baked internal shaders without a live `ProgramObject`** (`ROADMAP.md:86`, verbatim): "**烘焙后的内部 shader 能否在没有活 `ProgramObject` 的情况下表达 uniform location 与 UBO 布局。** 未做原型。" — a direct question about whether `ProgramArtifacts.h`'s types are expressive enough standalone.
|
||||
|
||||
**#12** (`ROADMAP.md:85`) and **#14** (`ROADMAP.md:87`) are post-P13 concerns, no header impact.
|
||||
|
||||
---
|
||||
|
||||
## 6. Quick checklist for the P0.5 implementer
|
||||
|
||||
1. Create `MobileGL/MG_Pipe/MGPipeValueTypes.h` with the nine items from `ARCHITECTURE.md:260`; includes limited to `<Includes.h>` + containers; **no** `MG_State/GLState` include. Watch `MAX_DRAW_BUFFERS` (class-scope constant at `FramebufferObject.h:106`).
|
||||
2. Create `MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h` with `TypeFacts`, `ResourceReflection`, `XfbVarying`, `LinkArtifacts`, `SpirvArtifacts`; includes limited to `<Includes.h>` + containers; **no** `ShaderObject.h`, **no** `SpvcSession.h`. Repoint the includers (doc says 7; grep finds 8 candidates, listed in §2.2).
|
||||
3. Add the `Visit()` field table (one table, both serialization directions) covering the full list at `ARCHITECTURE.md:259`, plus `static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE)` and the sibling for `SpirvArtifacts`.
|
||||
4. Delete the two P0.5-debt includes at `MobileGL/MG_Pipe/MGPipeTypes.h:32-33` and the debt comment at `:25-31`; resolve the `MGPCaps`/`DynamicBackendParameters` include separately (it is not one of the nine value types — see §2.1).
|
||||
5. Add CI job **`include-graph-check`** with two `-H` closure assertions; prove each can go red by re-adding one forbidden include.
|
||||
6. Do not reorder or add fields anywhere. Pure move. Tests unchanged by name. `nm`/`.text` deltas attributable per symbol.
|
||||
7. Run the full `gl44to46` caselist in CI (architecture boundary, `ROADMAP.md:34`), and the five-part gate once at phase exit (`ROADMAP.md:7`).
|
||||
@@ -0,0 +1,877 @@
|
||||
# P0.5 CI include-closure gate — scout report
|
||||
|
||||
Tree scouted: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch `feat/disaggregated`.
|
||||
Every path below is repo-relative to that root unless written absolute. Every line number was opened.
|
||||
|
||||
Live measurements in section 5 were run in WSL against `/home/swung/w7/pipe` (the same branch, `a4baa9d4`, 12 commits ahead of the Windows worktree) because it has configured build trees. All of the headers involved are byte-identical in the two worktrees for the purposes of these measurements; re-run the commands after rebasing if you need exact numbers for a specific commit.
|
||||
|
||||
---
|
||||
|
||||
## 0. Two naming corrections before anything else
|
||||
|
||||
The task brief names two headers as if they exist. **Neither exists in the tree today** — P0.5 *creates* them:
|
||||
|
||||
- `MobileGL/MG_Pipe/MGPipeValueTypes.h` — does not exist. `find MobileGL -iname "*ValueType*"` returns nothing. The real, existing header is `MobileGL/MG_Pipe/MGPipeTypes.h`.
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h` — does not exist. `ls MobileGL/MG_State/GLState/ProgramState/` shows: `ProgramLinkTask.{cpp,h}`, `ProgramObject.{cpp,h}`, `ProgramPipelineObject.h`, `ProgramSpirvTask.{cpp,h}`, `ProgramState.{cpp,h}`, `ProgramTranslationCache.{cpp,h}`, `ShaderCompileAdoptionMap.{cpp,h}`, `ShaderCompileTask.{cpp,h}`, `ShaderObject.{cpp,h}`, `ShaderPreprocessCache.{cpp,h}`, `ShaderSourceKey.h`, `ShaderStage.h`. The types to extract live in `ProgramObject.h`.
|
||||
|
||||
So the gate is written **against headers that P0.5 introduces**. It must therefore be able to run in a "not yet extracted" state without crashing the CI for a missing file — decide explicitly: either land the gate in the same commit as the headers, or give the script a `--allow-missing` that prints SKIP. Recommendation below: land in the same commit, no skip mode (a gate that can silently skip is the "all-skip run indistinguishable from a pass" failure the integration lane comment at `.github/workflows/test.yml:222-225` was written about).
|
||||
|
||||
---
|
||||
|
||||
## 1. Existing gates in `.github/workflows/test.yml` (861 lines total)
|
||||
|
||||
Job list with line numbers (`grep -n "^ [a-zA-Z0-9_-]*:"`):
|
||||
|
||||
| line | job | runs-on | needs |
|
||||
|---|---|---|---|
|
||||
| 12 | `build-linux` | ubuntu-latest | — |
|
||||
| 149 | `test` | ubuntu-latest | build-linux |
|
||||
| 205 | `integration` | ubuntu-latest | build-linux |
|
||||
| 304 | `flatc-check` | ubuntu-latest | — |
|
||||
| 325 | `benchmark` | ubuntu-latest | build-linux |
|
||||
| 381 | `build-retrace` | ubuntu-latest | — |
|
||||
| 526 | `trace-cases` | ubuntu-latest | — |
|
||||
| 546 | `trace-fixtures` | ubuntu-latest | — |
|
||||
| 611 | `retrace` | ubuntu-latest | — |
|
||||
| 717 | `retrace-summary` | ubuntu-latest | — |
|
||||
| 758 | `remove-artifact-clutter` | ubuntu-latest | — |
|
||||
| 809 | `pipe-gates` | ubuntu-latest | — (deliberately) |
|
||||
|
||||
Triggers, `test.yml:2-9`: `push` on `dev`, `Feat/Backend-Direct-GLES`, `Feat/Backend-Direct-Vulkan`, plus `workflow_dispatch`. **`feat/disaggregated` is not a trigger branch** — a new gate added here will only run on `workflow_dispatch` or after the branch merges, unless you add the branch to the `branches:` list. Flag this to the implementer; it is the single easiest way for a "green gate" to be green because it never ran.
|
||||
|
||||
### 1.1 `pipe-gates` (test.yml:809-861) — the job to extend
|
||||
|
||||
```yaml
|
||||
809 pipe-gates:
|
||||
810 name: MGPipe generators and hygiene gates
|
||||
811 runs-on: ubuntu-latest
|
||||
812 # Deliberately independent of build-linux: these are source-level gates, they take
|
||||
813 # seconds, and a broken build must not hide a drifted interface.
|
||||
814
|
||||
815 steps:
|
||||
816 - name: Checkout repo
|
||||
817 uses: actions/checkout@v6
|
||||
```
|
||||
|
||||
Note `actions/checkout@v6` at 816-817 with **no `with: submodules:`** — this job has an empty `3rdparty/` and an empty `include/ska/`. That is load-bearing for the design (section 5.4).
|
||||
|
||||
Steps:
|
||||
|
||||
- **819-827 "Regenerate the MGPipe interface (G1-G7)"**
|
||||
```
|
||||
python3 scripts/gen_pipe.py
|
||||
git diff --exit-code -- MobileGL/MG_Pipe/generated
|
||||
```
|
||||
Failure surfaces as a non-zero exit from `git diff --exit-code` (a diff printed to the log). Note it runs the *writing* mode and diffs, not `--check`.
|
||||
- **829-846 "No stdio instrumentation in MG_Backend or MG_State"** — the stdio grep gate:
|
||||
```bash
|
||||
if grep -rnE 'fprintf[[:space:]]*\((stderr|stdout)|(^|[^[:alnum:]_>.])printf[[:space:]]*\(|(^|[^[:alnum:]_>.:])puts[[:space:]]*\(|std::(cout|cerr)' \
|
||||
MobileGL/MG_Backend MobileGL/MG_State; then
|
||||
echo "::error::stdio instrumentation found; use MGLOG_D (compiled out in INFO builds)"
|
||||
exit 1
|
||||
fi
|
||||
echo "no fprintf(stderr/stdout / printf( / puts( / std::cout|cerr under MobileGL/MG_Backend or MobileGL/MG_State"
|
||||
```
|
||||
Failure surfaces as a GitHub `::error::` annotation plus `exit 1`. **This is the house style for a new grep/scan gate**: annotate with `::error::`, then exit 1, and print an affirmative one-liner on success. Zero exceptions by policy (comment at 831-835: "this gate starts with no exceptions, and any addition to it needs a reason in the pull request rather than a quiet whitelist entry"). Copy that policy for the closure allow-list.
|
||||
- **848 "MGPipe dirty-surface report"**: `python3 scripts/gen_pipe_dirty_surface.py --summary` — informational only (comment 846-847: "It becomes a gate in P1").
|
||||
- **850-861 "Documentation citation lint"**:
|
||||
```bash
|
||||
shopt -s nullglob
|
||||
documents=(docs/Disaggregated/*.md)
|
||||
if [ ${#documents[@]} -eq 0 ]; then echo "no disaggregation documents to check"; exit 0; fi
|
||||
python3 scripts/check_doc_citations.py "${documents[@]}" || true
|
||||
```
|
||||
Warning-only via `|| true` (comment 849-851: becomes `--strict` when the documents settle). This is the last step of the file (file ends at 861).
|
||||
|
||||
### 1.2 `flatc-check` (test.yml:298-323) — the model for a compiler-needing, submodule-selective job
|
||||
|
||||
Header comment 298-303 explains why the generated header is committed and flatc kept out of the build graph. Steps:
|
||||
|
||||
- 306-307 `Checkout repo` / `actions/checkout@v6` (no submodules)
|
||||
- 309-310 `Get CMake` / `lukka/get-cmake@v4.3.3`
|
||||
- 312-315 **`Check out the FlatBuffers submodule only`**: `git submodule update --init 3rdparty/flatbuffers`, with the comment "Just this one: the schema check has nothing to do with glslang, SPIRV-Cross or the trace fixtures."
|
||||
- 317-318 `Regenerate protocol_generated.h`: `python3 scripts/gen_protocol.py --build-dir "${{ runner.temp }}/flatc-build"`
|
||||
- 320-321 `Fail if the committed header is stale`: `git diff --exit-code -- MobileGL/MG_Remote/Protocol/generated/protocol_generated.h`
|
||||
|
||||
**Use this job's selective-submodule pattern verbatim** for the include-closure gate (section 6): `git submodule update --init include/ska 3rdparty/xxHash 3rdparty/Vulkan-Headers` is the whole dependency set (proved in 5.4).
|
||||
|
||||
### 1.3 `build-linux` (test.yml:12-148) — toolchain and configure facts
|
||||
|
||||
- 59-60 installs the toolchain: `sudo apt-get install -y ccache clang-20 clang++-20 lld-20 libc++-20-dev libc++abi-20-dev libvulkan-dev libegl1-mesa-dev libgles2-mesa-dev libgl1-mesa-dri mesa-vulkan-drivers ninja-build`. So the project's CI compiler is **clang-20**, installed explicitly, not the image default.
|
||||
- 52-54: `python update_glslang_sources.py` in `3rdparty/glslang` — a prerequisite for a *full* configure, not for the closure probe.
|
||||
- 71-91 `Configure CMake`:
|
||||
```
|
||||
cmake -S . -B "${BUILD_DIR}" -G Ninja \
|
||||
-DCMAKE_C_COMPILER=clang-20 -DCMAKE_CXX_COMPILER=clang++-20 \
|
||||
-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache \
|
||||
-DCMAKE_BUILD_TYPE="${BUILD_TYPE}" \
|
||||
-DMOBILEGL_LOG_ACTIVE_LEVEL=MOBILEGL_LOG_LEVEL_INFO \
|
||||
-DMOBILEGL_BUILD_TEST=ON -DMOBILEGL_BUILD_BENCHMARK=ON \
|
||||
-DMOBILEGL_BUILD_INTEGRATION_TEST=ON \
|
||||
-DMOBILEGL_ITEST_VK_ICD=/usr/share/vulkan/icd.d/lvp_icd.json \
|
||||
-DMOBILEGL_BUILD_TRACE_REPLAY=OFF \
|
||||
-DBENCHMARK_DOWNLOAD_DEPENDENCIES=ON -DBENCHMARK_ENABLE_TESTING=OFF \
|
||||
-DCMAKE_POLICY_VERSION_MINIMUM=3.5
|
||||
```
|
||||
**`MOBILEGL_BUILD_DISAGGREGATED` is not passed** — CI's `build-linux` builds the OFF (shipping) configuration only. `BUILD_DIR=build-linux` (env, line 17).
|
||||
- 94 `Build`: `cmake --build "${BUILD_DIR}" --parallel "$(nproc)"`
|
||||
- 122-138 packages `ci-artifacts/mobilegl-linux-runtime.tgz` containing `CTestTestfile.cmake`, `MobileGL/MG_Test`, `MobileGL/MG_Benchmark`, `MobileGL/MG_IntegrationTest` and every `*.so` found — **note it excludes `*.a` and `*.o`, and `libMobileGL.so` IS in the `SHARED_LIBS` glob (127)**. That matters for the nm report: `libMobileGL.so` already leaves `build-linux` as an artifact (140-146, `actions/upload-artifact@v7`, name `mobilegl-linux-runtime`, `if-no-files-found: error`).
|
||||
- 139-146 upload. 96-98 `ccache --show-stats` `if: always()`.
|
||||
- 100-120: rolling ccache cache entry, only written on the default branch.
|
||||
|
||||
`test` job (149-203) downloads that artifact (176-180), unpacks (182-183), rewrites CTest command paths with an inline python heredoc (185-196) and runs `ctest --output-on-failure -L unit --no-tests=error` (198-203). **`--no-tests=error` is the house guard against a vacuous pass** — any new ctest must carry the right label (`unit`) or it will never run in CI.
|
||||
|
||||
### 1.4 `scripts/gen_pipe.py --check`
|
||||
|
||||
- Docstring 9-30; usage lines 25-26:
|
||||
```
|
||||
python3 scripts/gen_pipe.py # write the generated files, print the summary
|
||||
python3 scripts/gen_pipe.py --check # fail if regenerating would change anything
|
||||
```
|
||||
- `REPO_ROOT` derived from `__file__` at line 37: `os.path.dirname(os.path.dirname(os.path.abspath(__file__)))` — **copy this idiom**, it makes the script cwd-independent.
|
||||
- `write(path, text, check, changed)` at 618-626: compares against the existing file, appends `os.path.relpath(path, REPO_ROOT)` to `changed`, writes only when `not check`.
|
||||
- `main()` 628-671: `argparse.ArgumentParser(description=__doc__)`, `--check` as `action="store_true"` (630-632). On drift with `--check` (663-666): `print("gen_pipe: OUT OF DATE: %s" % ", ".join(changed), file=sys.stderr); return 1`. Otherwise 669 `print("gen_pipe: generated files are up to date")`, `return 0`. Entry point 673-674 `sys.exit(main())`.
|
||||
- Prints a summary block at 653-660 with a `gen_pipe:` prefix on every line. **House style: `<toolname>: <message>` prefix on every stdout line.**
|
||||
- Hard errors use `sys.exit("message")` (lines 135, 153, 158, 178, 182, 193, 202, 208, 219, 519).
|
||||
|
||||
### 1.5 `scripts/check_doc_citations.py` (117 lines)
|
||||
|
||||
- Docstring 10-26 states the motivation and the two usages; last line 26: "Exits non-zero only with `--strict`, so it can be wired into CI as a warning first."
|
||||
- `REPO_ROOT` at 33, same idiom.
|
||||
- `CITATION_RE` 37-40 — a path-with-extension followed by `:line[-line]`.
|
||||
- `git(args, rev_root=REPO_ROOT)` 43-45 shells `git -C <root> …` with `check=False`.
|
||||
- `class Tree` 48-73: builds `Paths`, `ByBasename`, lazily counts lines from `git show rev:path`.
|
||||
- `main()` 76-114: `documents nargs="+"`, `--rev` (default `HEAD`), `--strict`. Summary line 108-109 `check_doc_citations: %d citations in %d document(s) against %s, %d problem(s)`; problems printed indented; `return 1` only when `problems and args.strict` (112-113).
|
||||
|
||||
**Two reusable patterns for the new script**: (a) a `--strict`-style escalation switch so the gate can land as a warning and become blocking in a later commit; (b) a machine-countable summary line printed unconditionally.
|
||||
|
||||
---
|
||||
|
||||
## 2. Build configuration — CMake facts an implementer needs
|
||||
|
||||
Root `CMakeLists.txt` is 38,244 bytes.
|
||||
|
||||
### 2.1 Options
|
||||
|
||||
| line | option | default |
|
||||
|---|---|---|
|
||||
| 5 | `MOBILEGL_BUILD_TEST` | ON (forced OFF for `ANDROID` at line 29) |
|
||||
| 6 | `MOBILEGL_BUILD_BENCHMARK` | ON (forced OFF for `ANDROID` at 30) |
|
||||
| 11 | `MOBILEGL_BUILD_INTEGRATION_TEST` | OFF |
|
||||
| 12 | `MOBILEGL_FORCE_RELEASE_OPT` | ON |
|
||||
| 13 | `MOBILEGL_ENABLE_TRACY` | OFF |
|
||||
| 14 | `MOBILEGL_BUILD_TRACE_REPLAY` | OFF |
|
||||
| 15 | `MOBILEGL_TRACE_ANGLE_VARIANTS` | OFF |
|
||||
| 16 | `MOBILEGL_IOS` | OFF |
|
||||
| 23 | `MOBILEGL_BUILD_DISAGGREGATED` | OFF |
|
||||
| 24 | `MOBILEGL_BUILD_SERVER_SPIKE` | OFF |
|
||||
| 108 | `MOBILEGL_ENABLE_LTO` | OFF |
|
||||
|
||||
`CMakeLists.txt:17-22` is the comment that names the nm equality this whole family of gates protects:
|
||||
|
||||
> "OFF is the shipping default and OFF must stay byte-comparable to a tree without MG_Remote at all: nothing under `MobileGL/MG_Remote/` is compiled, no include path is added, and no library is linked, so `nm --defined-only libMobileGL.so | grep -i MG_Remote` is empty. That emptiness is one of the two byte-level equalities the plan's validation gates keep (section 10.3)."
|
||||
|
||||
Also: `MOBILEGL_LOG_ACTIVE_LEVEL` is a cache STRING, default `"MOBILEGL_LOG_LEVEL_INFO"` (line 25).
|
||||
|
||||
### 2.2 Compiler / language
|
||||
|
||||
- 155 `enable_language(CXX)`; 157 `set(CMAKE_CXX_STANDARD 23)`; 158 `CMAKE_CXX_STANDARD_REQUIRED ON`.
|
||||
- **160 `set(CMAKE_EXPORT_COMPILE_COMMANDS ON)`** — unconditional. Every configured build tree has a `compile_commands.json`. Confirmed present at `~/w7/pipe/{build,build-linux,build-linux-split,build-retrace,build-android}/compile_commands.json`.
|
||||
- 162 `CMAKE_POSITION_INDEPENDENT_CODE ON`. 165 MSVC `/EHsc`. 149-151 MSVC `/Zc:preprocessor` + `/Zc:__cplusplus`.
|
||||
- 137-146: with `MOBILEGL_ENABLE_LTO`, `-O3 -ffunction-sections -fdata-sections` + `-Wl,--gc-sections`; off by default, so the default Release build does **not** use `--gc-sections`. Relevant to the nm/size report: section-splitting is off by default, so per-symbol sizes from `nm -S` are comparable between builds.
|
||||
- 168-183: `MGGitHash.h` is `configure_file`d into `${CMAKE_BINARY_DIR}/generated` and 185 `include_directories(${CMAKE_BINARY_DIR}/generated)` — a *build-dir* include path. (Verified in section 5.4 that the closure probe does not need it.)
|
||||
- 578-583 / 596-598 visibility presets: `hidden` in non-Debug, `default` in Debug. This directly changes the `nm --defined-only` output; **the nm report must compare two builds of the same `CMAKE_BUILD_TYPE`**.
|
||||
|
||||
### 2.3 Include directories — `MOBILEGL_INCLUDE_DIR` (`CMakeLists.txt:530-544`)
|
||||
|
||||
```cmake
|
||||
set(MOBILEGL_INCLUDE_DIR
|
||||
${CMAKE_SOURCE_DIR}/include
|
||||
${CMAKE_SOURCE_DIR}/MobileGL
|
||||
# The MGPipe boundary headers. …
|
||||
${CMAKE_SOURCE_DIR}/MobileGL/MG_Pipe # line 535
|
||||
${spirv-tools_SOURCE_DIR}
|
||||
${spirv-tools_SOURCE_DIR}/include
|
||||
${spirv-tools_BINARY_DIR}
|
||||
${SPIRV-Headers_SOURCE_DIR}/include
|
||||
${CMAKE_SOURCE_DIR}/3rdparty/asio/include
|
||||
)
|
||||
```
|
||||
and, only when disaggregated, `CMakeLists.txt:546-551` appends `${CMAKE_SOURCE_DIR}/3rdparty/flatbuffers/include`.
|
||||
|
||||
Applied to both targets: `target_include_directories(${CMAKE_PROJECT_NAME} PUBLIC ${MOBILEGL_INCLUDE_DIR})` at 579-581 (shared `MobileGL`) and 638-640 (static `MobileGL_s`, inside `if(NOT ANDROID)` at 619).
|
||||
|
||||
Note that `MG_Remote` gets **no include path of its own** — its headers are reached as `<MG_Remote/...>` through `${CMAKE_SOURCE_DIR}/MobileGL`, and internally by relative `"../Protocol/mg_protocol_base.h"` (`MobileGL/MG_Remote/Transport/ITransport.h:33`, `Framing.h:32`, `Ring.h:47`).
|
||||
|
||||
Sources: `MG_Remote` `.cpp` files are appended to `SOURCE_FILES` at `CMakeLists.txt:454-471` under `if (MOBILEGL_BUILD_DISAGGREGATED)`; the flatbuffers-submodule-missing fallback that shadows the option OFF for one configure is at 440-451; `-DMOBILEGL_BUILD_DISAGGREGATED=1` is appended to `MOBILEGL_COMPILE_DEF` at 523-525.
|
||||
|
||||
`MOBILEGL_COMPILE_DEF` (`CMakeLists.txt:512-521`): `-DVMA_STATIC_VULKAN_FUNCTIONS=0 -DVMA_DYNAMIC_VULKAN_FUNCTIONS=1 -DVMA_VULKAN_VERSION=1001000 -DASIO_STANDALONE -DASIO_NO_DEPRECATED`, plus `MOBILEGL_LOG_ACTIVE_LEVEL=${MOBILEGL_LOG_ACTIVE_LEVEL}` at 585-589 / 645-649 and `MOBILEGL_TRACE_ANGLE_VARIANTS` via a generator expression at 588.
|
||||
|
||||
### 2.4 Where the test targets are declared
|
||||
|
||||
- Root gate: `CMakeLists.txt:732-763`, inside `if (NOT ANDROID)`; 741 `enable_testing()` at top-level scope (comment 732-740 explains that this is what puts a `CTestTestfile.cmake` at the build root so `ctest -L unit` works from there); 744-746 `if (MOBILEGL_BUILD_TEST) add_subdirectory(MobileGL/MG_Test) endif()`; 750-752 integration; 754-756 benchmark; 758-760 trace_replay.
|
||||
- `MobileGL/MG_Test/CMakeLists.txt` (103 lines):
|
||||
- 1-2 `cmake_minimum_required(VERSION 3.24)` / `project(MobileGLTest)`
|
||||
- 6-7 C++23
|
||||
- **9 `set(MGL_ROOT ${CMAKE_CURRENT_LIST_DIR}/../..)`** — the variable every sub-CMakeLists uses for include paths.
|
||||
- 15-24 `FetchContent` googletest v1.17.0 (`gtest_force_shared_crt ON`)
|
||||
- 26 `enable_testing()`
|
||||
- 32-47 the `SanityTest` target, include dirs `${MGL_ROOT}/include` and `${MGL_ROOT}/MobileGL`
|
||||
- **60-62 `set(LINK_LIBRARIES MobileGL_s)`** — the variable every sub-CMakeLists links
|
||||
- 64-65 `include(GoogleTest)` + `gtest_discover_tests(SanityTest DISCOVERY_TIMEOUT 30 PROPERTIES LABELS unit)`
|
||||
- 67-74 MSVC `/WHOLEARCHIVE:MobileGL_s`
|
||||
- 76-99 the `add_subdirectory` list (`BackendLoader Buffer State EGLState Framebuffer Texture VertexArray Program Query Pipeline Pipe ShaderTranspiler Util SelfTest Backend/DirectGLES`, `Backend/DirectVulkan` under `ENABLE_INTEGRATION_TESTS`)
|
||||
- 100-103 `if (MOBILEGL_BUILD_DISAGGREGATED) add_subdirectory(Wire) endif()` — the disaggregated-only suite (this is the `MG_Test/CMakeLists.txt:93-95` the docs cite; the real lines are 100-103 in this worktree, a citation the doc lint would flag once ARCHITECTURE.md is re-pinned).
|
||||
- **The model target — `MobileGL/MG_Test/Pipe/CMakeLists.txt` (28 lines)**:
|
||||
```cmake
|
||||
1 cmake_minimum_required(VERSION 3.14)
|
||||
3 add_executable(PipeCatalogueTest PipeCatalogueTest.cpp)
|
||||
8 target_include_directories(PipeCatalogueTest PRIVATE
|
||||
9 ${MGL_ROOT}/include
|
||||
10 ${MGL_ROOT}/MobileGL
|
||||
11 ${MGL_ROOT}/MobileGL/MG_Pipe
|
||||
12 ${MGL_ROOT}/3rdparty/xxHash
|
||||
13 ${MGL_ROOT}/3rdparty/Vulkan-Headers/include
|
||||
14 ${MGL_ROOT}/3rdparty/SPIRV-Reflect
|
||||
15 )
|
||||
17 target_link_libraries(PipeCatalogueTest PRIVATE GTest::gtest_main ${LINK_LIBRARIES})
|
||||
23 if (MSVC) target_compile_options(PipeCatalogueTest PRIVATE /Zc:preprocessor) endif()
|
||||
27 include(GoogleTest)
|
||||
28 gtest_discover_tests(PipeCatalogueTest DISCOVERY_TIMEOUT 30 PROPERTIES LABELS unit)
|
||||
```
|
||||
Note lines 9-14: **this target already spells out, by hand, almost exactly the minimal include set the closure probe needs** (section 5.4). It is the precedent for hand-listing include roots outside `MOBILEGL_INCLUDE_DIR`.
|
||||
- `MobileGL/MG_Test/Wire/CMakeLists.txt` (36 lines) is the loop form: a `MOBILEGL_WIRE_TESTS` list (7-12), `FdPassingTest` appended only `if (NOT WIN32)` (14-17), and a `foreach` (21-36) that adds the executable, the include dirs (`include`, `MobileGL`, `3rdparty/flatbuffers/include`) and `gtest_discover_tests(... LABELS unit)`.
|
||||
- Non-gtest `add_test` precedent (for a script-driven ctest): `tools/trace_replay/CMakeLists.txt:350-372` — `add_test(NAME MobileGLTraceReplay.${CASE_NAME}.${BACKEND} COMMAND "${CMAKE_COMMAND}" -D... -P .../run_trace_case.cmake)`, then `set_tests_properties(... PROPERTIES ENVIRONMENT "…")` at 373-380. `find_package(Python3 REQUIRED)` + `${Python3_EXECUTABLE}` appear at `tools/trace_replay/CMakeLists.txt:15` and `:390` and at `android-plugin/app/src/trace/cpp/CMakeLists.txt:9,51`. **There is no `find_package(Python3)` in the root `CMakeLists.txt` or under `MG_Test`** — a python-driven ctest under `MG_Test` must add its own.
|
||||
- Benchmarks show the plain form: `MobileGL/MG_Benchmark/CMakeLists.txt:40 add_test(NAME SanityBench COMMAND SanityBench …)`.
|
||||
|
||||
### 2.5 Does a `compile_commands.json` / `clang -H` probe fit?
|
||||
|
||||
Yes, and better than expected — see section 5. Summary of the fit:
|
||||
|
||||
- `CMAKE_EXPORT_COMPILE_COMMANDS ON` is unconditional (`CMakeLists.txt:160`), so a local/ctest run can always read the *real* flags out of the build tree it lives in. 816 entries in `~/w7/pipe/build-linux-split/compile_commands.json`, 67 of them under `MG_State`.
|
||||
- But a full configure is **not required**: a five-flag hand-rolled command reproduces the exact same 666-line closure (5.4). So the gate can also run in a source-only job in ~0.15 s.
|
||||
- Both `clang++ -H` and `g++ -H` work and agree on the in-tree part of the closure (5.5).
|
||||
|
||||
---
|
||||
|
||||
## 3. What the docs require of the gate — verbatim quotes
|
||||
|
||||
### 3.1 `docs/Disaggregated/ROADMAP.md:16` — the P0.5 row (full row, `|`-separated)
|
||||
|
||||
> `| **P0.5** 值头与制品头抽取 | 6–9 | `MG_Pipe/MGPipeValueTypes.h`(`RenderStateParameters`、`SamplerParameters`、`PixelStoreParameters`、`VertexAttribute`… 不 include `MG_State/GLState`);`MG_State/GLState/ProgramState/ProgramArtifacts.h`(五个反射类型,不 include `ShaderObject.h`/`SpvcSession.h`,更新 7 个 includer);`Visit()` 归档 + `sizeof` 绊线;CI `-H` include 闭包断言 | 全套测试逐名不变(纯搬移);两条闭包断言绿且人为加回一个 `MG_State` include 能变红;`nm`/`.text` 变化可逐符号归因 | P0;**P1 与 P7 的硬前置** |`
|
||||
|
||||
Decomposed acceptance gate (column 4):
|
||||
1. **全套测试逐名不变(纯搬移)** — the whole suite unchanged *test-name by test-name*; the extraction is a pure move.
|
||||
2. **两条闭包断言绿** — two closure assertions green.
|
||||
3. **人为加回一个 `MG_State` include 能变红** — deliberately adding an `MG_State` include back must turn it red.
|
||||
4. **`nm`/`.text` 变化可逐符号归因** — nm/.text changes must be attributable symbol by symbol.
|
||||
|
||||
### 3.2 `docs/Disaggregated/ROADMAP.md:7` — the per-commit discipline
|
||||
|
||||
> 默认 ALL target 必须完整构建;禁止提交热路径插桩(CI grep 门);**每个门必须能因它存在的理由变红**;Windows 机器不是正确性门;…
|
||||
|
||||
"**Every gate must be able to turn red for the reason it exists**" is the sentence that makes the negative control mandatory and not optional.
|
||||
|
||||
### 3.3 `docs/Disaggregated/ARCHITECTURE.md:501` — §13.2 item 1, purity gate A
|
||||
|
||||
> 1. **接口纯度三道门**(只跑非 verify 构建):**A 门 include 图**——disaggregated 配置编译 `MG_Backend` 时把 `MG_State/GLState` 从 include 搜索路径移除(`nm --undefined-only` 对"只 include 不调用"是瞎的,而 `RenderState.h → FramebufferObject.h → TextureObject.h` 正是这种耦合),依赖 P0.5;**B 门符号**——`nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空;**C 门未声明**——`grep -c 'pGLContext' MG_Backend/` == 0。…
|
||||
|
||||
Two things to carry into the design: (a) gate A's ultimate form is *removing `MG_State/GLState` from the include search path* when compiling `MG_Backend` — the `-H` closure assertion is the P0.5 stepping stone toward that; (b) the doc names the exact chain `RenderState.h → FramebufferObject.h → TextureObject.h` as the motivating coupling, and section 5.3 below **confirms that chain exists today, byte for byte**.
|
||||
|
||||
`ARCHITECTURE.md:499` (the sentence that opens §13.2):
|
||||
|
||||
> "改前改后 `nm --defined-only` 与 `.text` size 完全相等"的门在本方案里按构造死亡(不存在能让旧字节回来的配置);替换是:
|
||||
|
||||
`ARCHITECTURE.md:507` (the two surviving byte-level equalities, and the drift-report requirement):
|
||||
|
||||
> 两条幸存的字节级等式:`MOBILEGL_BUILD_DISAGGREGATED=OFF` 时 `nm --defined-only libMobileGL.so | grep MG_Remote` 为空且链接行不增加库;`nm -D libMobileGL.so | grep mobilegl_server_main` 在 RelWithDebInfo 里命中。符号与 `.text` 漂移每阶段作为信息性指标发布。
|
||||
|
||||
("symbol and `.text` drift is published as an informational metric each phase" — that is the home for the nm/size report of section 8.)
|
||||
|
||||
### 3.4 `docs/Disaggregated/ARCHITECTURE.md:568` — §16 构建布局, the CI bullet
|
||||
|
||||
> - CI(`.github/workflows/test.yml:809` `pipe-gates`,P0 已落地):`gen_pipe.py` 重生成 + diff;`MG_Backend`/`MG_State` 下禁止 stdio 插桩的 grep 门;`gen_pipe_dirty_surface.py --summary`(信息性,P1 成门);`check_doc_citations.py`(警告级,文档定稿后 `--strict`)。独立 job `flatc-check`。后续:**`include-graph-check`(P0.5)**、`monolith-symbol-report`。
|
||||
|
||||
**The gate's name is already chosen by the docs: `include-graph-check`, and it is described as a *后续* (follow-on) item alongside `monolith-symbol-report`.** The natural reading — "独立 job `flatc-check`. 后续:`include-graph-check`(P0.5)、`monolith-symbol-report`" — is that these two are also standalone jobs. Section 6 proposes exactly that, and separately proposes reusing `monolith-symbol-report` as the name of the nm/.text job.
|
||||
|
||||
§16 also fixes the tree layout (`ARCHITECTURE.md:550-561`), naming `MobileGL/MG_Pipe/` as "永远进构建(monolith 的架构,不在任何 option 之后) [P0]".
|
||||
|
||||
Other §16 lines the implementer needs:
|
||||
- `ARCHITECTURE.md:563` — the CMake option paragraph, citing `CMakeLists.txt:23`, `454-469`, `440-451`, and `MobileGL/MG_Test/CMakeLists.txt:93-95`.
|
||||
- `ARCHITECTURE.md:564` — `MOBILEGL_BUILD_DISAGGREGATED_INPROC` (does not exist yet) and the sentence "server 角色不再读 `pGLContext`(三道纯度门就是这个断言)".
|
||||
- `ARCHITECTURE.md:567` — the ctest wiring traps: "ctest `ENVIRONMENT` 是替换而非追加、`;` 必须转义、property 覆盖 job env". Confirmed independently by the comment at `.github/workflows/test.yml:222-227`.
|
||||
|
||||
### 3.5 `docs/Disaggregated/ARCHITECTURE.md:260` — §7, the exact extraction contract
|
||||
|
||||
> - **P0.5 硬前置**:反射类型今天声明在 `ProgramObject.h` 里,而它 include `ShaderObject.h`(→ glslang)与 `SpvcSession.h`(→ spirv_reflect)。P0.5 把 `TypeFacts`、`ResourceReflection`、`XfbVarying`、`LinkArtifacts`、`SpirvArtifacts` 抽到 `MG_State/GLState/ProgramState/ProgramArtifacts.h`(只 include `<Includes.h>` 与容器),更新 7 个 includer,加 CI `-H` 闭包断言。同批抽取 `MG_Pipe/MGPipeValueTypes.h`(`MAX_DRAW_BUFFERS`、`PerBufferBlendState`、`StencilFaceState`、`PixelStoreParameters`、`RenderStateParameters`、`SamplerParameters`、`BorderColorForm`、`VertexAttribute`、`VertexBufferBindingPoint`),它不 include `MG_State/GLState` 任何东西;`MGPipeTypes.h` 今天为此临时 include 了 `BackendObject.h` 与 `RenderState.h`(文件头注明为 P0.5 债务)。没有这一步,P7 的 `nm -D | grep glslang` 判据不可达。
|
||||
|
||||
**This is the authoritative spec of the two closure assertions.** Note carefully:
|
||||
|
||||
- `ProgramArtifacts.h` is specified as "**只 include `<Includes.h>` 与容器**" — it *keeps* the umbrella header. Since `MobileGL/Includes.h:59` includes `<spirv_cross/spirv_cross_c.h>` and `:79-83` include five glslang headers, **the ProgramArtifacts assertion CANNOT be "no glslang / no spirv-cross in the closure"**. It must be "no `ShaderObject.h`, no `SpvcSession.h`" (and, in practice, none of the chain those two drag in). See section 5.6.
|
||||
- `MGPipeValueTypes.h` is specified as "不 include `MG_State/GLState` 任何东西" — a *directory-prefix* assertion. `MGPipeTypes.h`'s own P0.5 debt note names both offending includes.
|
||||
|
||||
The file-level debt note is in the tree at `MobileGL/MG_Pipe/MGPipeTypes.h:25-33`:
|
||||
|
||||
> // P0.5 DEBT, recorded here so it is impossible to miss: two payloads reach into headers
|
||||
> // this directory is eventually forbidden to see - MGPCaps embeds MG_Backend's
|
||||
> // DynamicBackendParameters, and ResidualValueBlock embeds MG_State's RenderStateParameters
|
||||
> // and PixelStoreParameters. … P0.5
|
||||
> // extracts MGPipeValueTypes.h and both includes below go away; until then purity gate A
|
||||
> // (section 10.3) cannot be armed for this header.
|
||||
> `#include <MG_Backend/BackendObject.h>` ← line 32
|
||||
> `#include <MG_State/GLState/RenderState/RenderState.h>` ← line 33
|
||||
|
||||
And `MGPipeTypes.h:35-40` has the `using` declarations that must follow the types when they move:
|
||||
```cpp
|
||||
namespace MobileGL::MG_Pipe {
|
||||
using MG_Backend::DynamicBackendParameters;
|
||||
// Both live directly in namespace MobileGL today; P0.5 moves them into
|
||||
// MG_Pipe/MGPipeValueTypes.h.
|
||||
using MobileGL::PixelStoreParameters;
|
||||
using MobileGL::RenderStateParameters;
|
||||
```
|
||||
|
||||
`ARCHITECTURE.md:259` gives the companion `Visit()`/`sizeof` tripwire requirement (`static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE)`) and enumerates the fields the archive must cover — out of scope for the include gate but same commit.
|
||||
|
||||
### 3.6 Precedent already in the tree — `MG_Remote/Transport` is umbrella-free by rule
|
||||
|
||||
`MobileGL/MG_Remote/Transport/WireLog.h:9-24` is the strongest existing statement of intent, and it names the mechanism this gate implements:
|
||||
|
||||
> // MG_Util/Debug/Log.h includes `<Includes.h>`, the GL frontend's umbrella
|
||||
> // header - **661 headers, measured with `clang++ -H`**. That is fine inside a
|
||||
> // .cpp … It is not fine in a header of this layer: ITransport.h states the rule
|
||||
> // ("nothing about a byte pipe needs the GL frontend's umbrella header") … and
|
||||
> // because the disaggregated build's include-graph purity gate (plan section
|
||||
> // 10.3, gate A) asserts on `-H` output rather than on symbols. Framing.h was
|
||||
> // the one header under Transport/ that broke the rule; it now calls this
|
||||
> // instead, and the umbrella stays inside WireLog.cpp.
|
||||
|
||||
Their includes today (all in-tree-clean):
|
||||
- `ITransport.h:33,35`: `"../Protocol/mg_protocol_base.h"`, `<cstdint>`
|
||||
- `Framing.h:32,36,38-41`: `"../Protocol/mg_protocol_base.h"`, `"WireLog.h"`, `<cstddef> <cstdint> <cstring> <vector>`
|
||||
- `Ring.h:47,49-51`: `"../Protocol/mg_protocol_base.h"`, `<atomic> <cstddef> <cstdint>`
|
||||
|
||||
**Recommendation: make this a third, free probe** (section 6.3). It is green today, it costs 30 ms, and it locks a rule that a single careless `#include <Includes.h>` in `Framing.h` has already broken once.
|
||||
|
||||
---
|
||||
|
||||
## 4. Ground truth about the headers to be extracted
|
||||
|
||||
### 4.1 Current include edges (all verified by opening the files)
|
||||
|
||||
```
|
||||
MG_Pipe/MGPipe.h:10,12-15 <Includes.h>, "MGPipeCallbacks.h", "MGPipeHandles.h", "MGPipeHostSpan.h", "MGPipeTypes.h"
|
||||
MG_Pipe/MGPipe.h:65,68,77,80,83,86,89,92 "PipeCalls.def" + the seven generated/*.inc
|
||||
MG_Pipe/MGPipeCallbacks.h:10,12-13 <Includes.h>, "MGPipeHandles.h", "MGPipeTypes.h"
|
||||
MG_Pipe/MGPipeHandles.h:10 <Includes.h> ← already MG_State-free
|
||||
MG_Pipe/MGPipeHostSpan.h:10 <Includes.h> ← already MG_State-free
|
||||
MG_Pipe/MGPipeTypes.h:10,12-13 <Includes.h>, "MGPipeHandles.h", "MGPipeHostSpan.h"
|
||||
MG_Pipe/MGPipeTypes.h:32 <MG_Backend/BackendObject.h> ← P0.5 debt
|
||||
MG_Pipe/MGPipeTypes.h:33 <MG_State/GLState/RenderState/RenderState.h> ← P0.5 debt
|
||||
|
||||
MG_State/GLState/RenderState/RenderState.h:10-12 <Includes.h>, <MG_Util/Math/VectorTypes.h>,
|
||||
<MG_State/GLState/FramebufferState/FramebufferObject.h>
|
||||
MG_State/GLState/FramebufferState/FramebufferObject.h:10-13
|
||||
"MG_Util/Types.h", <Includes.h>,
|
||||
<MG_State/GLState/TextureState/TextureObject.h>,
|
||||
<MG_State/GLState/RenderbufferState/RenderbufferObject.h>
|
||||
MG_Backend/BackendObject.h:10-11 <Includes.h>, "MG_State/GLState/TextureState/TextureEnum.h"
|
||||
|
||||
MG_State/GLState/ProgramState/ProgramObject.h:10,11,13,14
|
||||
<Includes.h>, "ShaderObject.h", <MG_Util/Metrics/BufferMetrics.h>,
|
||||
<MG_Util/ShaderTranspiler/SpvcSession.h>
|
||||
```
|
||||
|
||||
`RenderState.h → FramebufferObject.h → TextureObject.h` — the coupling `ARCHITECTURE.md:501` names — is `RenderState.h:12` → `FramebufferObject.h:12`. Confirmed.
|
||||
|
||||
### 4.2 The types to move
|
||||
|
||||
Value types (target `MG_Pipe/MGPipeValueTypes.h`), all in `MobileGL/MG_State/GLState/RenderState/RenderState.h` (538 lines, `namespace MobileGL` at the outer level, closing at 538):
|
||||
- `PixelStoreParameters` at **:191-200** (8 scalar members)
|
||||
- `PerBufferBlendState` at **:202-210**
|
||||
- `StencilFaceState` at **:212-220**
|
||||
- `RenderStateParameters` at **:222-…**, with `static constexpr Uint MAX_VIEWPORTS = 16;` at **:227** and `Array<FloatVec4, MAX_VIEWPORTS> Viewports{}` at **:238**
|
||||
- the state class's private data at **:527-537**: `Uint16 m_version`, `Uint16 m_pipelineStateVersion`, `RenderStateParameters m_parameters`, two `PixelStoreParameters`
|
||||
`ARCHITECTURE.md:260` additionally names `MAX_DRAW_BUFFERS`, `SamplerParameters`, `BorderColorForm`, `VertexAttribute`, `VertexBufferBindingPoint` — those live in the sampler/vertex-array headers, not in `RenderState.h`; grep for them before writing the probe's expectations.
|
||||
|
||||
Reflection types (target `MG_State/GLState/ProgramState/ProgramArtifacts.h`), all nested inside `class ProgramObject` in `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h`:
|
||||
- `struct TypeFacts` **:44**
|
||||
- `struct ResourceReflection` **:76**
|
||||
- `struct LinkedShaderRef` **:150** (not in the doc's list of five)
|
||||
- `struct XfbVarying` **:1146**
|
||||
- `struct LinkArtifacts` **:1210**
|
||||
- `struct SpirvArtifacts` **:1409**
|
||||
- (also `PendingUniformWrite` **:1658**, `BackendHashMemoSlot` **:1767**, forward decls `ProgramLinkTask` **:20**, `ProgramSpirvTask` **:23**, `class ProgramObject` **:25**)
|
||||
|
||||
The doc's "five reflection types" = `TypeFacts`, `ResourceReflection`, `XfbVarying`, `LinkArtifacts`, `SpirvArtifacts` (`ARCHITECTURE.md:260`). **They are nested classes today** — extracting them out of `class ProgramObject` changes their qualified names (`ProgramObject::LinkArtifacts` → `ProgramArtifacts`-namespace name), which is what makes the "全套测试逐名不变(纯搬移)" and "nm 逐符号归因" acceptance gates non-trivial. Expect mangled-name churn on every function taking one of these by reference; that is exactly what the nm report of section 8 has to attribute.
|
||||
|
||||
### 4.3 The "7 includers" of `ProgramObject.h`
|
||||
|
||||
`grep -rln "ProgramState/ProgramObject.h\|\"ProgramObject.h\"" --include=*.h --include=*.cpp MobileGL` gives 10 files (one is the header itself):
|
||||
|
||||
```
|
||||
MobileGL/MG_Backend/DirectVulkan/Renderer/ProgramFactory.h
|
||||
MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.cpp
|
||||
MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp
|
||||
MobileGL/MG_Impl/GLImpl/Program/ProgramInterface.cpp
|
||||
MobileGL/MG_State/GLState/ProgramState/ProgramLinkTask.h
|
||||
MobileGL/MG_State/GLState/ProgramState/ProgramObject.cpp
|
||||
MobileGL/MG_State/GLState/ProgramState/ProgramObject.h (self)
|
||||
MobileGL/MG_State/GLState/ProgramState/ProgramPipelineObject.h
|
||||
MobileGL/MG_State/GLState/ProgramState/ProgramState.h
|
||||
MobileGL/MG_State/GLState/ProgramState/ProgramTranslationCache.h
|
||||
```
|
||||
i.e. 9 other files, of which the doc counts 7 as needing an update (the two `MG_Backend/DirectVulkan/Renderer/*.cpp` and the `.h` all consume the reflection types; work out the exact 7 during implementation — the discrepancy is worth a line in the commit message).
|
||||
|
||||
---
|
||||
|
||||
## 5. Measured facts about `-H` (all commands run, all output real)
|
||||
|
||||
Environment: WSL Arch, `clang version 22.1.6` (`/usr/sbin/clang++`), `g++ (GCC) 16.1.1`, GNU `nm`/`size` at `/usr/sbin`. `which clang++` on the **Windows** shell returns nothing — the Windows box has no clang, so all local verification of this gate must happen in WSL (consistent with `ROADMAP.md:7` "Windows 机器不是正确性门").
|
||||
|
||||
### 5.1 `-H` goes to stderr, with dot-depth prefixes
|
||||
|
||||
```
|
||||
$ clang++ -std=c++23 -I/tmp/hprobe -H -fsyntax-only probe.cpp 2>err.txt 1>out.txt
|
||||
exit=0
|
||||
stdout bytes: 0 ← nothing on stdout
|
||||
err.txt:
|
||||
. ./outer.h
|
||||
.. ./sub/inner.h
|
||||
... /usr/bin/../lib64/gcc/.../include/c++/16/vector
|
||||
.... .../bits/requires_hosted.h
|
||||
```
|
||||
Format: `^(\.+) (path)$`; the number of dots is the include depth, so the **full inclusion chain to any forbidden header is reconstructible** by walking backwards to the nearest line with depth−1. That is the whole reason to prefer `-H` over `-MM`.
|
||||
|
||||
Paths come back **relative when the `-I` was relative or the include was resolved relative to the including file** (`. ./outer.h`, and `. MobileGL/MG_Pipe/MGPipeTypes.h` in the real run). The script must `os.path.realpath(os.path.join(compiler_cwd, path))` before matching prefixes.
|
||||
|
||||
`-H` prints a header **only on its first inclusion** (include guards suppress the rest) — irrelevant for a closure test, but it means the output is not an inclusion *count*.
|
||||
|
||||
### 5.2 `-MM` alternative
|
||||
|
||||
```
|
||||
$ clang++ -std=c++23 -I/tmp/hprobe -MM probe.cpp
|
||||
probe.o: probe.cpp outer.h sub/inner.h
|
||||
```
|
||||
One make rule, easy to parse, but it drops system headers and, critically, **loses the depth/chain information**. Use it only as a cross-check.
|
||||
|
||||
### 5.3 The real closure of `MGPipeTypes.h` today
|
||||
|
||||
Probe TU: `printf "#include <MG_Pipe/MGPipeTypes.h>\n" > probe_pipe.cpp`, flags copied verbatim from `build-linux-split/compile_commands.json` (the entry for `MobileGL/MG_State/GLState/Core.cpp`; 816 entries in that file), run with cwd = the build dir:
|
||||
|
||||
```
|
||||
exit=0
|
||||
total header lines: 666
|
||||
in-tree MobileGL/: 20
|
||||
MG_State/: 9
|
||||
MG_Impl/: 0
|
||||
MG_Backend/: 1
|
||||
glslang: 18
|
||||
spirv_cross: 2
|
||||
SPIRV-Reflect: 0
|
||||
```
|
||||
The nine `MG_State` lines, with their real depths — this is the violation set the gate must report:
|
||||
|
||||
```
|
||||
... MobileGL/MG_State/GLState/TextureState/TextureEnum.h (via MG_Backend/BackendObject.h)
|
||||
.. MobileGL/MG_State/GLState/RenderState/RenderState.h ← MGPipeTypes.h:33, depth 2
|
||||
... MobileGL/MG_State/GLState/FramebufferState/FramebufferObject.h
|
||||
.... MobileGL/MG_State/GLState/TextureState/TextureObject.h
|
||||
..... MobileGL/MG_State/GLState/TextureState/MipmapUploadTargetArray.h
|
||||
......MobileGL/MG_State/GLState/TextureState/MipmapStorage.h
|
||||
....... MobileGL/MG_State/GLState/TextureState/TextureTypes.h
|
||||
..... MobileGL/MG_State/GLState/TextureState/../SamplerState/SamplerObject.h
|
||||
.... MobileGL/MG_State/GLState/RenderbufferState/RenderbufferObject.h
|
||||
```
|
||||
Note the `TextureState/../SamplerState/SamplerObject.h` spelling — **`-H` prints the path as written, un-normalized**; prefix matching without `os.path.normpath` would miss a `../`-spelled violation. This is a real trap present in today's output.
|
||||
|
||||
The 666 total confirms (and slightly updates) the "661 headers" figure in `WireLog.h:12`.
|
||||
|
||||
### 5.4 A five-flag command reproduces the closure exactly — no build tree required
|
||||
|
||||
```bash
|
||||
cd <repo root>
|
||||
clang++ -std=gnu++23 \
|
||||
-Iinclude -IMobileGL -IMobileGL/MG_Pipe \
|
||||
-I3rdparty/xxHash -I3rdparty/Vulkan-Headers/include \
|
||||
-H -E -o /dev/null probe_pipe.cpp
|
||||
```
|
||||
Result: `exit=0`, **666 header lines, 9 `MG_State/` — byte-identical to the full-flag run.** Adding `-DMOBILEGL_LOG_ACTIVE_LEVEL=MOBILEGL_LOG_LEVEL_INFO` changes nothing (666 either way).
|
||||
|
||||
Why so few flags: `include/glslang/` and `include/spirv_cross/` are **vendored into the repo** (not submodules) — `ls include/` gives `EGL GL GLES3 KHR android_debug.h glslang ska spirv_cross`, and the `-H` output shows `include/glslang/Include/Types.h` and `include/spirv_cross/spirv_cross_c.h` winning over the `3rdparty/` copies because `-Iinclude` precedes them in `MOBILEGL_INCLUDE_DIR`. The only submodule-provided headers in the closure are:
|
||||
|
||||
| header | provider | `.gitmodules` |
|
||||
|---|---|---|
|
||||
| `ska/flat_hash_map.hpp` (`Includes.h:53`) | `include/ska` | submodule `include/ska` |
|
||||
| `xxhash.h` (`Includes.h:56`) | `3rdparty/xxHash` | submodule |
|
||||
| `vulkan/vulkan.h` (`Includes.h:131`) | `3rdparty/Vulkan-Headers/include` | submodule |
|
||||
|
||||
So the CI job needs exactly `git submodule update --init include/ska 3rdparty/xxHash 3rdparty/Vulkan-Headers` — the `flatc-check` pattern (`test.yml:312-315`). No glslang submodule, no `update_glslang_sources.py`, no SPIRV-Cross, no flatbuffers, no CMake configure, no `${CMAKE_BINARY_DIR}/generated/MGGitHash.h`.
|
||||
|
||||
### 5.5 Speed, and `-E` vs `-fsyntax-only`, and `g++`
|
||||
|
||||
| command | wall time | header lines |
|
||||
|---|---|---|
|
||||
| `clang++ … -H -E -o /dev/null probe_pipe.cpp` | **0.137 s** | 666 |
|
||||
| `clang++ … -H -fsyntax-only probe_pipe.cpp` | 1.889 s | 666 |
|
||||
|
||||
`-E` is ~14× faster and produces the identical closure, because the include graph is a preprocessor fact. **Use `-E -o /dev/null` for the closure assertion.** Keep one `-fsyntax-only` run per probe as a separate, second assertion ("the header is self-contained and compiles standing alone") — that is a genuinely different property and still under 2 s.
|
||||
|
||||
`g++` works too:
|
||||
```
|
||||
$ g++ -std=gnu++23 -Iinclude -IMobileGL -IMobileGL/MG_Pipe -I3rdparty/xxHash \
|
||||
-I3rdparty/Vulkan-Headers/include -H -E -o /dev/null probe_pipe.cpp
|
||||
exit=0 ; 651 header lines ; MG_State: 9
|
||||
. MobileGL/MG_Pipe/MGPipeTypes.h
|
||||
.. MobileGL/Includes.h
|
||||
... MobileGL/Defines.h
|
||||
.... /usr/include/signal.h
|
||||
```
|
||||
Same dot format, same 9 `MG_State` hits (the 651 vs 666 difference is entirely in libstdc++/glibc internals). **GCC trap**: `g++ -H` appends a trailer block
|
||||
|
||||
```
|
||||
Multiple include guards may be useful for:
|
||||
/usr/include/asm/errno.h
|
||||
…
|
||||
3rdparty/xxHash/xxhash.h
|
||||
include/glslang/Include/../Include/visibility.h
|
||||
```
|
||||
— 54 non-dot lines in this run. The parser **must** accept only lines matching `^\.+ ` and discard everything else, or it will count a guard-advice line as a closure member. Clang emits no such trailer.
|
||||
|
||||
Since `g++` works, the gate does **not** have to `apt-get install clang-20` (~20 s): `g++` is preinstalled on every `ubuntu-latest` image. Recommendation is still to prefer clang-20 for parity with the real build (`test.yml:59-60`) and fall back to `c++`/`g++` — the script should take `--compiler` and print which one it used.
|
||||
|
||||
### 5.6 The closure of `ProgramObject.h` today, and why "no glslang" is not an assertable property
|
||||
|
||||
Same probe method, `#include <MG_State/GLState/ProgramState/ProgramObject.h>`:
|
||||
|
||||
```
|
||||
total: 682 header lines ; in-tree: 33
|
||||
. MobileGL/MG_State/GLState/ProgramState/ProgramObject.h
|
||||
.. MobileGL/Includes.h
|
||||
... MobileGL/Defines.h
|
||||
... MobileGL/MG_Util/PlatformStubs.h
|
||||
... MobileGL/MG_Util/Debug/Log.h
|
||||
... MobileGL/MG_Util/Types.h
|
||||
.... MobileGL/MG_Util/GLExtensions.h
|
||||
.. MobileGL/MG_State/GLState/ProgramState/ShaderObject.h ← forbidden after P0.5
|
||||
... MobileGL/MG_State/GLState/ProgramState/ShaderStage.h
|
||||
... MobileGL/MG_State/GLState/ProgramState/ShaderCompileTask.h
|
||||
.... MobileGL/MG_Util/Async/JobNode.h
|
||||
..... MobileGL/MG_State/GLState/ErrorState/ErrorCode.h
|
||||
..... MobileGL/MG_State/GLState/ErrorState/ErrorInfo.h
|
||||
.... MobileGL/MG_Util/ShaderTranspiler/CompileEnv.h
|
||||
..... MobileGL/Config.h
|
||||
...... MobileGL/MG_Backend/BackendObjects.h
|
||||
....... MobileGL/MG_Backend/BackendObject.h
|
||||
........ MobileGL/MG_State/GLState/TextureState/TextureEnum.h
|
||||
....... MobileGL/MG_Backend/DirectGLES/BackendObject_DirectGLES.h
|
||||
........ MobileGL/MG_Util/BackendLoaders/OpenGL/Loader.h
|
||||
....... MobileGL/MG_Backend/DirectVulkan/BackendObject_DirectVulkan.h
|
||||
........ MobileGL/MG_Util/BackendLoaders/Vulkan/Loader.h
|
||||
.... MobileGL/MG_Util/ShaderTranspiler/Types.h
|
||||
.... MobileGL/MG_State/GLState/BufferState/BufferState.h
|
||||
..... MobileGL/MG_Util/Miscellany/IndexGenerator.h
|
||||
..... MobileGL/MG_State/GLState/BufferState/BufferObject.h
|
||||
...... MobileGL/MG_Util/Math/VectorTypes.h
|
||||
...... MobileGL/MG_State/GLState/BufferState/PipeResource.h
|
||||
.... MobileGL/MG_State/GLState/ProgramState/ShaderPreprocessCache.h
|
||||
..... MobileGL/MG_State/GLState/ProgramState/ShaderSourceKey.h
|
||||
... MobileGL/MG_State/GLState/ProgramState/ShaderCompileAdoptionMap.h
|
||||
.. MobileGL/MG_Util/Metrics/BufferMetrics.h
|
||||
.. MobileGL/MG_Util/ShaderTranspiler/SpvcSession.h ← forbidden after P0.5
|
||||
```
|
||||
The whole middle block (`ShaderStage.h` … `ShaderSourceKey.h`) hangs off `ShaderObject.h` and disappears when that include goes. `Config.h` → `MG_Backend/BackendObjects.h` → **both backends' object headers** is the surprising edge: `ProgramObject.h` currently drags in `BackendObject_DirectGLES.h` *and* `BackendObject_DirectVulkan.h` *and* both loaders. Cutting `ShaderObject.h` cuts all of them.
|
||||
|
||||
**Critical design constraint.** `MobileGL/Includes.h` is the umbrella and it pulls, unconditionally:
|
||||
- `:53` `<ska/flat_hash_map.hpp>`
|
||||
- `:56` `<xxhash.h>`
|
||||
- `:59` `<spirv_cross/spirv_cross_c.h>`
|
||||
- `:79-83` `<glslang/Include/Types.h>`, `<glslang/Public/ShaderLang.h>`, `<glslang/SPIRV/GlslangToSpv.h>`, `<glslang/Include/intermediate.h>`, `<glslang/MachineIndependent/localintermediate.h>`
|
||||
- `:131` `<vulkan/vulkan.h>`
|
||||
- `:147-148` `"MG_Util/Debug/Log.h"`, `"MG_Util/Types.h"`
|
||||
|
||||
`ARCHITECTURE.md:260` explicitly permits `ProgramArtifacts.h` to include `<Includes.h>`. **Therefore an assertion of the form "the closure contains no glslang / spirv-cross / SPIRV-Reflect header" is unsatisfiable by construction and must not be written.** The task brief's proposed forbidden set has to be narrowed to in-tree paths:
|
||||
|
||||
- Probe A (`MG_Pipe/MGPipeValueTypes.h`): forbid `MobileGL/MG_State/`, `MobileGL/MG_Impl/`, `MobileGL/MG_Backend/`, `MobileGL/MG_Remote/`. (The doc only demands `MG_State/GLState`; the other three are free and match §16's layering.)
|
||||
- Probe B (`MG_State/GLState/ProgramState/ProgramArtifacts.h`): forbid the exact files `ProgramState/ShaderObject.h` and `MG_Util/ShaderTranspiler/SpvcSession.h`, plus — because they are only reachable through those two — `MG_Util/ShaderTranspiler/`, `MobileGL/Config.h`, `MobileGL/MG_Backend/`, `MG_State/GLState/BufferState/`, `MG_State/GLState/ProgramState/Shader*.h`. Start with the doc's two names as the hard gate and add the rest as a second, tighter list once the header lands green.
|
||||
|
||||
If the project later wants the glslang-free assertion for real, the route is the `MG_Remote/Transport` route: **do not include `Includes.h`** (probe C, section 6.3), not a bigger forbidden list.
|
||||
|
||||
### 5.7 No macro-driven includes anywhere in `MobileGL/`
|
||||
|
||||
`grep -rn "^\s*#\s*include\s\+[A-Za-z_]" --include=*.h --include=*.cpp MobileGL` → **zero matches** (3377 `#include` lines total). Every include is a literal `"…"` or `<…>`. The only non-header includes are `MG_Pipe/MGPipe.h:65` `"PipeCalls.def"` and `:68,77,80,83,86,89,92` `"generated/Pipe*.inc"`.
|
||||
|
||||
This means a **pure-text transitive include walker in Python needs no compiler and cannot be fooled by macro spelling** — the basis for the fast layer-1 gate in section 6.2. It can still be fooled by `#if` (an include inside a false branch would be reported as present); the compiler probe is the arbiter.
|
||||
|
||||
---
|
||||
|
||||
## 6. Proposed design
|
||||
|
||||
Name it `scripts/check_include_closure.py`, and the CI job `include-graph-check` (the name `ARCHITECTURE.md:568` already reserves).
|
||||
|
||||
### 6.1 The probe manifest — data, not code
|
||||
|
||||
Put the probe definitions in the script as a module-level table so a reviewer can read the whole contract in one screen (the `gen_pipe.py` house style — see its `GENERATED_BANNER` and generator tables):
|
||||
|
||||
```python
|
||||
PROBES = [
|
||||
Probe(
|
||||
Name = "value-header",
|
||||
Header = "MG_Pipe/MGPipeValueTypes.h", # spelled as the TU will include it
|
||||
Forbidden = ["MobileGL/MG_State/", "MobileGL/MG_Impl/",
|
||||
"MobileGL/MG_Backend/", "MobileGL/MG_Remote/"],
|
||||
Allow = [], # deliberately empty; see policy note
|
||||
Why = "ROADMAP P0.5 / ARCHITECTURE.md:260 - it must not include MG_State/GLState",
|
||||
),
|
||||
Probe(
|
||||
Name = "artifacts-header",
|
||||
Header = "MG_State/GLState/ProgramState/ProgramArtifacts.h",
|
||||
Forbidden = ["MobileGL/MG_State/GLState/ProgramState/ShaderObject.h",
|
||||
"MobileGL/MG_Util/ShaderTranspiler/",
|
||||
"MobileGL/Config.h",
|
||||
"MobileGL/MG_Backend/"],
|
||||
Allow = [],
|
||||
Why = "ARCHITECTURE.md:260 - no ShaderObject.h (-> glslang), no SpvcSession.h",
|
||||
),
|
||||
Probe(
|
||||
Name = "wire-header", # free bonus, green today
|
||||
Header = "MG_Remote/Transport/ITransport.h",
|
||||
Forbidden = ["MobileGL/Includes.h"],
|
||||
Allow = [],
|
||||
Why = "WireLog.h:9-24 / ITransport.h:25 - no GL umbrella in the byte-pipe layer",
|
||||
),
|
||||
]
|
||||
```
|
||||
|
||||
Policy for `Allow`: copy the stdio gate's wording (`test.yml:831-835`) — **start empty; an addition needs a reason in the pull request, not a quiet whitelist entry.** If an entry is ever added, require a `Reason` string on it and print it in the summary so it stays visible.
|
||||
|
||||
`Forbidden` entries are matched as **path prefixes on the repo-relative, `os.path.normpath`-ed path** (so `TextureState/../SamplerState/SamplerObject.h` normalizes to `SamplerState/SamplerObject.h` and matches `MobileGL/MG_State/`). Any path outside the repo (system, `/usr/...`) is ignored.
|
||||
|
||||
### 6.2 Two modes, one script
|
||||
|
||||
**`--mode text` (default; no compiler, no submodules, ~50 ms).** Transitive walk of `#include` directives starting at the probe header. Resolution order per the CMake include dirs (`CMakeLists.txt:530-544`): (1) for `"quoted"` includes, the directory of the including file; (2) `include/`; (3) `MobileGL/`; (4) `MobileGL/MG_Pipe/`. Anything that does not resolve to a file inside the repo is a leaf (that is every `<vector>`, `<vulkan/vulkan.h>`, `<xxhash.h>`). Report a violation as `probe → chain → forbidden header`, using the recorded parent chain. This mode is safe in `pipe-gates` as-is.
|
||||
|
||||
**`--mode clang --compile-commands <path>` (authoritative).** Writes each probe TU into a temp dir, derives flags either from a `compile_commands.json` entry (take any entry whose `file` is under `MobileGL/`, strip `-o`, `-c`, `-MD/-MF/-MT`, and the input file; keep every `-D`, `-I`, `-isystem`, `-std`) or, when `--compile-commands` is absent, from the verified minimal set of 5.4. Runs
|
||||
|
||||
```
|
||||
<cxx> <flags> -H -E -o /dev/null <probe.cpp>
|
||||
```
|
||||
capturing **stderr**, parses `^(\.+) (.*)$` only, normalizes each path against the compiler's cwd, and applies the same forbidden/allow logic. Then, as a second assertion, runs `-fsyntax-only` once per probe and fails if the header is not self-contained.
|
||||
|
||||
The two modes should agree; make a disagreement a hard failure with a message that says which mode saw what — that is a free consistency check on the text walker.
|
||||
|
||||
Both modes print, unconditionally, one machine-greppable summary line per probe in the house style:
|
||||
|
||||
```
|
||||
include-closure: value-header OK 187 headers in closure, 0 forbidden (mode=clang, cxx=clang++-20)
|
||||
include-closure: artifacts-header OK 642 headers in closure, 0 forbidden
|
||||
include-closure: wire-header OK 8 headers in closure, 0 forbidden
|
||||
include-closure: 3 probes, 0 problem(s)
|
||||
```
|
||||
and on failure, a chain, followed by `::error::` + `exit 1`:
|
||||
|
||||
```
|
||||
include-closure: value-header FORBIDDEN MobileGL/MG_State/GLState/RenderState/RenderState.h
|
||||
include-closure: chain: MG_Pipe/MGPipeValueTypes.h
|
||||
include-closure: -> MobileGL/MG_State/GLState/RenderState/RenderState.h
|
||||
include-closure: -> MobileGL/MG_State/GLState/FramebufferState/FramebufferObject.h
|
||||
include-closure: -> MobileGL/MG_State/GLState/TextureState/TextureObject.h
|
||||
```
|
||||
|
||||
Flags to provide: `--mode {text,clang,both}`, `--compile-commands PATH`, `--compiler PATH` (default: `$CXX`, then `clang++-20`, then `clang++`, then `c++`), `--probe NAME` (run one), `--self-test`, `--json PATH` (dump the closure for the informational report), and — per the `check_doc_citations.py` precedent — a `--strict` if the gate is to land warning-only first (recommendation: it should NOT; it lands with the headers, green from commit one).
|
||||
|
||||
`REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))` — the `gen_pipe.py:37` / `check_doc_citations.py:33` idiom.
|
||||
|
||||
### 6.3 The third probe is free — take it
|
||||
|
||||
`MG_Remote/Transport/ITransport.h` includes only `"../Protocol/mg_protocol_base.h"` and `<cstdint>` (`:33,35`). Asserting "closure contains no `MobileGL/Includes.h`" is green today, costs ~30 ms, and pins the rule that `WireLog.h:9-24` says `Framing.h` has already violated once. It also gives the gate a probe that is green *before* P0.5 lands, so the script can be reviewed and merged independently of the header extraction.
|
||||
|
||||
### 6.4 The negative control as a real test, not a manual demo
|
||||
|
||||
`ROADMAP.md:7` — "每个门必须能因它存在的理由变红" — and `ROADMAP.md:16` — "人为加回一个 `MG_State` include 能变红" — require it. Make it a `--self-test` subcommand that **always runs as part of the gate**, so it cannot rot:
|
||||
|
||||
1. Synthesize a fourth, throwaway probe TU in the temp dir:
|
||||
```cpp
|
||||
#include <MG_Pipe/MGPipeValueTypes.h>
|
||||
#include <MG_State/GLState/RenderState/RenderState.h> // deliberate violation
|
||||
```
|
||||
Run the *same* analysis over it with the *same* forbidden list.
|
||||
2. Assert it reports **at least one** violation, and that the reported chain names `RenderState.h` at depth 1.
|
||||
3. If it reports zero, the gate itself is broken → `::error::` + exit 1 with the message "negative control did not trip: the closure gate is not actually checking anything".
|
||||
|
||||
Do this **without touching any tracked file** — a synthesized TU in `tempfile.mkdtemp()`, never a temporary edit of a real header. (An earlier `git checkout`-based negative control would leave the tree dirty on a crash and race the `git diff --exit-code` step of the same job.)
|
||||
|
||||
Optionally strengthen it: also self-test the *text* walker and the *clang* mode separately, so a broken parser in one mode is caught even if the other mode still works.
|
||||
|
||||
For the "两条闭包断言" wording: the gate should also assert `len(green_probes) >= 2` for the two named headers, so deleting a probe from the manifest is itself red.
|
||||
|
||||
### 6.5 Wiring as a ctest
|
||||
|
||||
Add `MobileGL/MG_Test/Purity/CMakeLists.txt` and `add_subdirectory(Purity)` to `MobileGL/MG_Test/CMakeLists.txt` next to line 90 (`add_subdirectory(Pipe)`), with a comment in the same voice as 88-89:
|
||||
|
||||
```cmake
|
||||
cmake_minimum_required(VERSION 3.14)
|
||||
|
||||
# The P0.5 include-closure assertions (ROADMAP P0.5, ARCHITECTURE.md:501 gate A). No
|
||||
# compilation of MobileGL, no GL context: it preprocesses two probe TUs and reads
|
||||
# clang's -H output. The build tree's own compile_commands.json supplies the real flags.
|
||||
find_package(Python3 REQUIRED COMPONENTS Interpreter)
|
||||
|
||||
add_test(NAME MobileGLPurity.IncludeClosure
|
||||
COMMAND ${Python3_EXECUTABLE}
|
||||
${MGL_ROOT}/scripts/check_include_closure.py
|
||||
--mode both
|
||||
--compile-commands ${CMAKE_BINARY_DIR}/compile_commands.json
|
||||
--compiler ${CMAKE_CXX_COMPILER}
|
||||
--self-test)
|
||||
set_tests_properties(MobileGLPurity.IncludeClosure PROPERTIES LABELS unit)
|
||||
```
|
||||
|
||||
Notes and traps:
|
||||
- `LABELS unit` is required or `ctest -L unit` (`test.yml:200,202`) will never run it. `--no-tests=error` protects only against an *empty* selection, not against a mislabelled test.
|
||||
- `${CMAKE_BINARY_DIR}/compile_commands.json` exists because of `CMakeLists.txt:160`, but **it is written at the end of configure**; using it from a test (run time) is fine, from `execute_process` at configure time is not.
|
||||
- Pass `${CMAKE_CXX_COMPILER}` so the test uses the same compiler that configured the build.
|
||||
- Do **not** use `set_tests_properties(... ENVIRONMENT ...)` unless you must: `ARCHITECTURE.md:567` and `.github/workflows/test.yml:222-227` both record that a ctest `ENVIRONMENT` property *replaces* and *overrides* the job environment silently.
|
||||
- This test travels in the `mobilegl-linux-runtime.tgz` only if the packaging list (`test.yml:126-137`) covers it: it packs `${BUILD_DIR}/MobileGL/MG_Test` and the root `CTestTestfile.cmake`, so a `MG_Test/Purity/CTestTestfile.cmake` **is** included — but the test then runs on the `test` job's runner, where `scripts/check_include_closure.py` exists (the job does `actions/checkout@v6` at 155-156) yet `3rdparty/` and `include/ska` do **not** (no submodules). In that environment `--mode clang` will fail on a missing `<ska/flat_hash_map.hpp>`. **Handle this explicitly**: either make the ctest `--mode text` only (always safe), or have the script detect the missing include roots and fail with a clear "run this from a full checkout" message rather than a compiler error. Recommendation: the ctest runs `--mode text --self-test` unconditionally and upgrades to `--mode both` only when the probe's include roots all exist.
|
||||
|
||||
### 6.6 Wiring as CI
|
||||
|
||||
**Preferred: a new standalone job `include-graph-check`**, modelled on `flatc-check`, inserted after the `flatc-check` job (i.e. after `test.yml:323`) so the file's ordering still reads gates-then-consumers:
|
||||
|
||||
```yaml
|
||||
# The P0.5 interface-purity gate A (ARCHITECTURE.md:501): the two extracted headers'
|
||||
# include closure, asserted on `-H` output rather than on symbols, because
|
||||
# `nm --undefined-only` is blind to "included but not called". It needs a preprocessor
|
||||
# and three submodules and nothing else - no CMake configure, no glslang sources - so
|
||||
# it does not depend on build-linux, for the same reason pipe-gates does not.
|
||||
include-graph-check:
|
||||
name: Include-closure purity gate
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
steps:
|
||||
- name: Checkout repo
|
||||
uses: actions/checkout@v6
|
||||
|
||||
- name: Check out the three header submodules the closure needs
|
||||
# ska/flat_hash_map.hpp, xxhash.h and vulkan/vulkan.h are the only submodule
|
||||
# headers Includes.h reaches; glslang and spirv_cross are vendored under include/.
|
||||
run: git submodule update --init include/ska 3rdparty/xxHash 3rdparty/Vulkan-Headers
|
||||
|
||||
- name: Install clang
|
||||
run: sudo apt-get update && sudo apt-get install -y clang-20
|
||||
|
||||
- name: Include-closure assertions and negative control
|
||||
run: python3 scripts/check_include_closure.py --mode both --compiler clang++-20 --self-test
|
||||
```
|
||||
|
||||
Drop the `Install clang` step and pass `--compiler g++` if the ~20 s apt cost is unwanted — 5.5 proves `g++ -H` gives the same in-tree answer, at the cost of not matching the shipping compiler.
|
||||
|
||||
**Alternative, if a separate job is unwanted:** add the two steps to `pipe-gates` after line 848 (before the citation lint). `pipe-gates` currently has no submodules and no compiler, so this adds a `git submodule update --init` and an apt install to a job whose comment (812-813) advertises "they take seconds". `--mode text` alone would preserve that property with zero new dependencies; `--mode both` would not. If the implementer wants exactly one job, run `--mode text --self-test` in `pipe-gates` and `--mode clang` in the new job.
|
||||
|
||||
**Do not forget** `test.yml:3-8`: add `feat/disaggregated` to the `push: branches:` list, or the gate will not run until the branch merges.
|
||||
|
||||
---
|
||||
|
||||
## 7. Summary of design decisions and their evidence
|
||||
|
||||
| decision | evidence |
|
||||
|---|---|
|
||||
| Gate name `include-graph-check` | `ARCHITECTURE.md:568` reserves it |
|
||||
| `-H`, not `-MM` | `-H` carries depth → printable chain (5.1 vs 5.2); `WireLog.h:17-19` says the gate "asserts on `-H` output" |
|
||||
| `-E -o /dev/null`, not `-fsyntax-only`, for the closure | 0.137 s vs 1.889 s, identical 666 lines (5.5) |
|
||||
| Parse only `^\.+ ` lines | `g++ -H` appends 54 guard-advice lines (5.5) |
|
||||
| `os.path.normpath` before prefix match | today's output contains `TextureState/../SamplerState/SamplerObject.h` (5.3) |
|
||||
| Forbidden set = in-tree prefixes only, **not** glslang/spirv-cross | `Includes.h:59,79-83` pulls them unconditionally and `ARCHITECTURE.md:260` lets `ProgramArtifacts.h` keep `<Includes.h>` (5.6) |
|
||||
| Selective submodules `include/ska 3rdparty/xxHash 3rdparty/Vulkan-Headers` | the only submodule headers in the closure; glslang/spirv_cross are vendored under `include/` (5.4); pattern from `test.yml:312-315` |
|
||||
| No CMake configure needed in CI | five-flag command reproduces the closure exactly (5.4) |
|
||||
| `compile_commands.json` still used, for the ctest | `CMakeLists.txt:160` makes it unconditional; 816 entries verified |
|
||||
| Negative control as an always-on `--self-test` on a synthesized TU | `ROADMAP.md:7` "每个门必须能因它存在的理由变红"; `ROADMAP.md:16` "人为加回一个 `MG_State` include 能变红" |
|
||||
| Empty allow-list, additions need a PR reason | the stdio gate's policy, `test.yml:831-835` |
|
||||
| Third probe on `ITransport.h` | free, green today, locks the rule `Framing.h` already broke (`WireLog.h:17-20`) |
|
||||
| `LABELS unit` on the ctest | `test.yml:198-203` runs `ctest -L unit --no-tests=error` |
|
||||
|
||||
---
|
||||
|
||||
## 8. The nm / `.text` per-symbol attribution report
|
||||
|
||||
Requirement, `ROADMAP.md:16`: "`nm`/`.text` 变化可逐符号归因". Home for the output, `ARCHITECTURE.md:507`: "符号与 `.text` 漂移每阶段作为信息性指标发布". Name reserved by `ARCHITECTURE.md:568`: `monolith-symbol-report`.
|
||||
|
||||
There is **no existing nm/size tooling in the tree** — `grep -rn "nm --defined\|nm -D\|size --format\|llvm-nm\|readelf"` over `*.yml *.py *.sh *.md` outside `docs/Disaggregated/` returns nothing. This is greenfield.
|
||||
|
||||
### 8.1 Verified commands (run against `~/w7/pipe/build-linux/libMobileGL.so`, 19,101,056 bytes)
|
||||
|
||||
```bash
|
||||
$ nm --defined-only libMobileGL.so | wc -l
|
||||
30511
|
||||
|
||||
$ nm --defined-only -S --size-sort libMobileGL.so | tail -3
|
||||
0000000000d8abdc 0000000000026fe4 r __GNU_EH_FRAME_HDR
|
||||
00000000007ffd80 000000000003e859 T _Z7yyparsePN7glslang13TParseContextE
|
||||
0000000000f302e0 00000000000fa000 b _ZZN8MobileGL7MG_Util5Debug3LogEPKciS3_zE6buffer
|
||||
|
||||
$ nm --defined-only -S -C libMobileGL.so | grep -E " t | T " | head -3
|
||||
0000000000c13240 0000000000000013 t atexit
|
||||
00000000001d1c90 000000000000000b t __clang_call_terminate
|
||||
0000000000ae9d20 0000000000004453 t CreateShaderModule
|
||||
|
||||
$ size --format=sysv libMobileGL.so | grep -E "^\.text|^Total"
|
||||
.text 10792579 1868752
|
||||
Total 17209819
|
||||
```
|
||||
|
||||
So: `nm --defined-only -S` yields `addr size type name` per symbol (the per-symbol `.text` attribution); `size --format=sysv` yields the section roll-up (`.text` = 10,792,579 bytes here). Both are the right tools; note `size --format=sysv` is **per-section, never per-symbol** — the per-symbol half must come from `nm -S`.
|
||||
|
||||
### 8.2 Proposed `scripts/symbol_report.py`
|
||||
|
||||
```
|
||||
python3 scripts/symbol_report.py --before <dir-or-so> --after <dir-or-so> \
|
||||
[--nm nm] [--size size] [--markdown out.md] [--json out.json] [--threshold 0]
|
||||
```
|
||||
|
||||
For each of `libMobileGL.so` (and, when present, `libMobileGL_s.a` / `MobileGLServer`):
|
||||
|
||||
1. `nm --defined-only -S <so>` → `{mangled_name: (type, size)}`. Keep the mangled name as the key (stable), carry a demangled form from `nm -C` for display only. Symbols with no size (e.g. `U`, absolute) are dropped.
|
||||
2. `size --format=sysv <so>` → per-section sizes, for the roll-up header.
|
||||
3. Diff into four buckets, each sorted by `|Δsize|` descending:
|
||||
- **removed** (in before, absent in after)
|
||||
- **added** (absent in before, in after)
|
||||
- **resized** (same name, different size)
|
||||
- **unchanged** (count only)
|
||||
4. Print a summary line and a Markdown table:
|
||||
```
|
||||
symbol-report: .text 10792579 -> 10794112 (+1533, +0.014%)
|
||||
symbol-report: 30511 -> 30514 defined symbols: 6 added, 3 removed, 11 resized
|
||||
```
|
||||
5. **Attribution.** For P0.5 specifically, the interesting bucket is *renames caused by de-nesting*: `ProgramObject::LinkArtifacts` → a namespace-scope `LinkArtifacts`. Give the script a `--rename-map old=new` (repeatable) or a `--demangle-normalize` pass that strips `ProgramObject::` before matching, so a pure move shows up as **0 added / 0 removed / N renamed, byte-identical sizes** rather than as N+N churn. That is precisely what "逐符号归因" means for this phase, and without it the report will be an unreadable wall of mangled churn.
|
||||
6. Exit 0 always in the informational form; provide `--fail-on-added-symbol-bytes N` for a future hard gate. `ARCHITECTURE.md:507` classes this as informational for now.
|
||||
|
||||
Guard rails to encode in the script and its docstring:
|
||||
- Compare only builds with the same `CMAKE_BUILD_TYPE` — the visibility presets differ between Debug and non-Debug (`CMakeLists.txt:572-583`, `622-635`), which changes `nm --defined-only` output wholesale.
|
||||
- `MOBILEGL_ENABLE_LTO` (default OFF, `CMakeLists.txt:108`) must be OFF on both sides; `-ffunction-sections`/`--gc-sections` only appear with it (137-146).
|
||||
- Note in the output which compiler and build type produced each side; a clang-20 vs clang-22 comparison is meaningless.
|
||||
|
||||
### 8.3 Where the output goes
|
||||
|
||||
A `monolith-symbol-report` job, `needs: [build-linux]` plus a second build of the *base* commit — or, cheaper for P0.5: a step inside `build-linux` that runs the script against the artifact of the previous run is not available without extra plumbing, so the practical first version is **local**: the implementer builds `HEAD~1` and `HEAD` in two WSL build dirs and runs the script, pasting the summary into the commit message / PR body, with the full Markdown attached as a CI artifact when the job exists.
|
||||
|
||||
For the CI form, follow the existing artifact idiom (`test.yml:140-146`, `290-296`):
|
||||
```yaml
|
||||
- name: Upload symbol report
|
||||
uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: monolith-symbol-report
|
||||
path: ci-artifacts/symbol-report.md
|
||||
if-no-files-found: error
|
||||
```
|
||||
and additionally echo the summary into `$GITHUB_STEP_SUMMARY` so the numbers are visible without downloading (no existing job does this yet — it would be a new, welcome idiom for an informational metric).
|
||||
|
||||
---
|
||||
|
||||
## 9. Open items for the implementer
|
||||
|
||||
1. **`feat/disaggregated` is not in `test.yml:3-8`'s trigger list.** Any gate added now is dormant until that changes or someone runs `workflow_dispatch`. Fix this in the same commit or the gate's "green" is meaningless.
|
||||
2. **Decide the two forbidden lists precisely** before writing the headers — `ARCHITECTURE.md:260` gives the minimum (`MG_State/GLState` for probe A; `ShaderObject.h` + `SpvcSession.h` for probe B); section 6.1 proposes tighter supersets. A too-tight list that the extracted header cannot satisfy will stall P0.5.
|
||||
3. **`MAX_DRAW_BUFFERS`, `SamplerParameters`, `BorderColorForm`, `VertexAttribute`, `VertexBufferBindingPoint`** are named in `ARCHITECTURE.md:260` but are not in `RenderState.h`; locate them and check whether *their* current homes pull `MG_State/GLState` transitively, because they move into the same value header.
|
||||
4. **The five reflection types are nested in `class ProgramObject`** (`ProgramObject.h:44,76,1146,1210,1409`). De-nesting them renames every mangled symbol that mentions them — plan the `--rename-map` of 8.2 before running the first report, or the "逐符号归因" gate will look catastrophic.
|
||||
5. `ARCHITECTURE.md:563` cites `MobileGL/MG_Test/CMakeLists.txt:93-95` for the `MOBILEGL_BUILD_DISAGGREGATED` guard; in this worktree it is at **100-103**. Re-pin that citation when the doc lint goes `--strict` (`test.yml:849-861`).
|
||||
6. Consider whether the gate should also run in the `MOBILEGL_BUILD_DISAGGREGATED=1` configuration. The closure of `MGPipeTypes.h` was measured with `-DMOBILEGL_BUILD_DISAGGREGATED=1` present and absent and was 666 lines either way (5.4), so today it makes no difference — but `Init.cpp`'s branch and `MG_Config::Transport` do change, so a probe that ever reaches `Config.h` would. Run both, it costs 0.3 s.
|
||||
@@ -0,0 +1,842 @@
|
||||
# Scout report — `MG_State/GLState/ProgramState/ProgramArtifacts.h` (P0.5)
|
||||
|
||||
Worktree root (all paths below are relative to it unless absolute):
|
||||
`C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`
|
||||
Branch `feat/disaggregated`. Read-only scout; nothing was modified.
|
||||
|
||||
Every file:line below was opened and read.
|
||||
|
||||
---
|
||||
|
||||
## 0. The authoritative list of the five types
|
||||
|
||||
`docs/Disaggregated/ARCHITECTURE.md:260` (section 7, "Shader state = SPIR-V + 反射归档"), verbatim
|
||||
naming of the five:
|
||||
|
||||
> P0.5 把 `TypeFacts`、`ResourceReflection`、`XfbVarying`、`LinkArtifacts`、`SpirvArtifacts` 抽到
|
||||
> `MG_State/GLState/ProgramState/ProgramArtifacts.h`(只 include `<Includes.h>` 与容器),更新 7 个
|
||||
> includer,加 CI `-H` 闭包断言。
|
||||
|
||||
`docs/Disaggregated/ROADMAP.md:16` (P0.5 row) repeats it: "`ProgramArtifacts.h`(五个反射类型,不
|
||||
include `ShaderObject.h`/`SpvcSession.h`,更新 7 个 includer);`Visit()` 归档 + `sizeof` 绊线;CI `-H`
|
||||
include 闭包断言". Exit gate: "全套测试逐名不变(纯搬移);两条闭包断言绿且人为加回一个 `MG_State`
|
||||
include 能变红;`nm`/`.text` 变化可逐符号归因". Dependency line: "P0; **P1 与 P7 的硬前置**".
|
||||
|
||||
So the five are, in dependency order:
|
||||
|
||||
1. `TypeFacts`
|
||||
2. `ResourceReflection` (+ its four aliases)
|
||||
3. `XfbVarying`
|
||||
4. `LinkArtifacts`
|
||||
5. `SpirvArtifacts`
|
||||
|
||||
Other supporting facts from the docs:
|
||||
|
||||
- `ARCHITECTURE.md:258` — `CreateShaderState`'s payload is per-stage SPIR-V + the archive
|
||||
(`LinkArtifacts` + `SpirvArtifacts`, **whole structs**), not source. glslang lives entirely on the
|
||||
client, SPIRV-Cross (`TranspileSpirvToEssl`) entirely on the server, split at file granularity.
|
||||
- `ARCHITECTURE.md:259` — archive mechanism is `Visit()` + a `sizeof` tripwire
|
||||
(`static_assert(sizeof(LinkArtifacts) == MGL_LINKARTIFACTS_SIZE)`), one field table serving both
|
||||
serialization directions. Required coverage listed explicitly: the four `ResourceReflection`
|
||||
vectors (each carrying `TypeFacts`), `uniformSamplerOrImageUnitIndex`, `uniformBlockBinding`,
|
||||
`shaderStorageBlockBinding` (by name), `explicitOpaqueUniformBindings`,
|
||||
`xfbVaryings/xfbStrides/xfbPackedStride/xfbNeedsScatteredCapture`, `computeLocalSize`, the
|
||||
GS/TCS/TES facts, `usesReservedNumSamples`, `uniformOffsets`. `XfbVarying` carries two spellings
|
||||
(GL name + block instance/member/element).
|
||||
- `ARCHITECTURE.md:133` — `MGPProgramDesc` is 192 bytes: per-stage SPIR-V blob x6 + reflection blob
|
||||
+ `StageMask`/`GlobalUboSize`/`ReservedNumSamplesOffset` + four state bytes.
|
||||
- `ARCHITECTURE.md:260` last sentence — without this step, P7's `nm -D | grep glslang` criterion is
|
||||
unreachable.
|
||||
- `ROADMAP.md` P7 row — gate is literally `nm -D libMobileGLServer.so | grep glslang` empty.
|
||||
|
||||
---
|
||||
|
||||
## 1. Current definitions — file:line, members, dependencies
|
||||
|
||||
All five live **inside `class ProgramObject`** in
|
||||
`MobileGL/MG_State/GLState/ProgramState/ProgramObject.h` (1803 lines total; class opens at :25,
|
||||
closes at :1802). They are therefore spelled `ProgramObject::TypeFacts` etc. everywhere.
|
||||
|
||||
### 1.1 `TypeFacts` — ProgramObject.h:44–72 (doc comment :41–43)
|
||||
|
||||
Flattened `glslang::TType`. All scalar POD; no heap member.
|
||||
|
||||
| line | member | type |
|
||||
|---|---|---|
|
||||
| 45 | `isArray` | `Bool` |
|
||||
| 48 | `isSizedArray` | `Bool` |
|
||||
| 49 | `isMatrix` | `Bool` |
|
||||
| 50 | `isVector` | `Bool` |
|
||||
| 51 | `isOpaque` | `Bool` |
|
||||
| 52 | `isTexture` | `Bool` |
|
||||
| 53 | `isImage` | `Bool` |
|
||||
| 54 | `isDouble` | `Bool` (`getBasicType() == EbtDouble`) |
|
||||
| 55 | `isVoid` | `Bool` (hidden block members) |
|
||||
| 56 | `isBuffer` | `Bool` (`qualifier.storage == EvqBuffer`) |
|
||||
| 57 | `isPatch` | `Bool` |
|
||||
| 58 | `hasIndex` | `Bool` |
|
||||
| 59 | `hasFormat` | `Bool` |
|
||||
| 60 | `vectorSize` | `Int` |
|
||||
| 61 | `matrixCols` | `Int` |
|
||||
| 62 | `matrixRows` | `Int` |
|
||||
| 63 | `layoutIndex` | `Int` |
|
||||
| 64 | `layoutFormat` | `Uint` |
|
||||
| 68 | `layoutMatrix` | `Int` (widened `glslang::TLayoutMatrix`) |
|
||||
| 71 | `basicType` | `Int` (widened `glslang::TBasicType`) |
|
||||
|
||||
**Already glslang-free by type** — the widening to `Int`/`Uint` was done deliberately (comments at
|
||||
:65–70 say so). `Bool`/`Int`/`Uint` come from `MG_Util/Types.h:33,29,30`.
|
||||
|
||||
### 1.2 `ResourceReflection` — ProgramObject.h:76–99 (doc comment :74–75); aliases :101–104
|
||||
|
||||
Flattened `glslang::TObjectReflection`; used for uniforms, blocks, pipe inputs and pipe outputs
|
||||
alike.
|
||||
|
||||
| line | member | type |
|
||||
|---|---|---|
|
||||
| 77 | `name` | `String` (= `std::string`, `MG_Util/Types.h:21`) |
|
||||
| 78 | `glDefineType` | `GLenum` |
|
||||
| 79 | `offset` | `Int` = -1 |
|
||||
| 82 | `size` | `Int` (raw `TObjectReflection::size`) |
|
||||
| 86 | `index` | `Int` = -1 (TPROGRAM block index owning it) |
|
||||
| 87 | `counterIndex` | `Int` = -1 |
|
||||
| 88 | `arrayStride` | `Int` |
|
||||
| 89 | `topLevelArraySize` | `Int` |
|
||||
| 90 | `topLevelArrayStride` | `Int` |
|
||||
| 91 | `binding` | `Int` = -1 |
|
||||
| 92 | `location` | `Int` = -1 |
|
||||
| 95 | `stages` | `Uint32` (an `EShLanguageMask`, widened) |
|
||||
| 98 | `arraySize` | `GLint` = 1 |
|
||||
| 99 (`type;`) | `type` | `TypeFacts` |
|
||||
|
||||
Aliases, ProgramObject.h:101–104:
|
||||
```
|
||||
using UniformReflection = ResourceReflection; // :101
|
||||
using BlockReflection = ResourceReflection; // :102
|
||||
using PipeInputReflection = ResourceReflection; // :103
|
||||
using PipeOutputReflection = ResourceReflection; // :104
|
||||
```
|
||||
Dependencies: `String`, `GLenum`/`GLint` (GL headers via `Includes.h:68–73`), `TypeFacts`. **No
|
||||
glslang type by value.**
|
||||
|
||||
### 1.3 `XfbVarying` — ProgramObject.h:1146–1171 (doc comment :1144–1145)
|
||||
|
||||
| line | member | type |
|
||||
|---|---|---|
|
||||
| 1147 | `name` | `String` (GL spelling, incl. `"Block.member"`) |
|
||||
| 1148 | `type` | `GLenum` = `GL_FLOAT` |
|
||||
| 1149 | `size` | `GLint` = 1 |
|
||||
| 1150 | `bufferIndex` | `Uint32` |
|
||||
| 1151 | `offsetBytes` | `Uint32` |
|
||||
| 1152 | `byteSize` | `Uint32` |
|
||||
| 1155 | `packedOffsetBytes` | `Uint32` |
|
||||
| 1166 | `blockInstanceName` | `String` |
|
||||
| 1167 | `blockName` | `String` |
|
||||
| 1168 | `blockMemberIndex` | `Int` = -1 |
|
||||
| 1171 | `blockMemberElement` | `Int` = -1 |
|
||||
|
||||
**No glslang type.** This is the "two spellings" struct `ARCHITECTURE.md:259` calls out.
|
||||
|
||||
### 1.4 `LinkArtifacts` — ProgramObject.h:1210–1393 (doc comment block :1173–1209)
|
||||
|
||||
53 members. Only **two** carry a glslang type:
|
||||
|
||||
- **:1215 `SharedPtr<glslang::TProgram> program;`** — live only between `LinkProgram()` and the end
|
||||
of `DoReflection`; null for an L1-memo-served link; must not be dereferenced outside
|
||||
`DoReflection` (comment :1211–1214).
|
||||
- **:1282 `Vector<glslang::TIntermediate::TUniformInitializer> uniformInitialValues;`**
|
||||
|
||||
Full member list (line: declaration):
|
||||
|
||||
```
|
||||
1215 SharedPtr<glslang::TProgram> program; <-- glslang
|
||||
1218 Vector<UniformReflection> uniformReflection;
|
||||
1219 Vector<BlockReflection> blockReflection;
|
||||
1220 Vector<PipeInputReflection> pipeInputReflection;
|
||||
1221 Vector<PipeOutputReflection> pipeOutputReflection;
|
||||
1227 Bool lastStageIsFragment = false;
|
||||
1228 Array<GLuint, 3> computeLocalSize{};
|
||||
1231 UnorderedMap<String, Int> uniformIndexByName;
|
||||
1234 Vector<String> attribs;
|
||||
1235 Vector<GLenum> attribTypes;
|
||||
1238 UnorderedMap<String, Uint> linkedFragDataLocation;
|
||||
1239 UnorderedMap<String, Uint> linkedFragDataIndex;
|
||||
1245 Vector<Int> glUniformIndexToTProgram;
|
||||
1246 Vector<Int> tProgramUniformIndexToGl;
|
||||
1247 Vector<Int> glBlockIndexToTProgram;
|
||||
1248 Vector<Int> tProgramBlockIndexToGl;
|
||||
1269 Vector<Int> glUniformBlockIndexToBlock;
|
||||
1270 Vector<Int> blockIndexToGlUniformBlock;
|
||||
1275 UnorderedMap<String, Int> linkedExplicitUniformLocations;
|
||||
1282 Vector<glslang::TIntermediate::TUniformInitializer> uniformInitialValues; <-- glslang
|
||||
1283 UnorderedMap<String, Uint> uniformLocations;
|
||||
1291 Vector<Uint64> writtenUniformLocationBits;
|
||||
1292 Vector<Uint64> writtenUniformIndexBits;
|
||||
1293 Vector<Uint> writtenUniformIndices;
|
||||
1296 Vector<Int> uniformIndexInTProgram;
|
||||
1298 Vector<Int> uniformSamplerOrImageUnitIndex;
|
||||
1303 UnorderedMap<String, Uint> explicitOpaqueUniformBindings;
|
||||
1313 UnorderedMap<String, Uint> uniformBlockIndexByName;
|
||||
1314 Vector<Int> uniformBlockBinding;
|
||||
1325 UnorderedMap<String, Int> shaderStorageBlockBinding;
|
||||
1331 std::set<String> storageBlocksWithoutBinding; <-- needs <set>
|
||||
1336 std::set<String> uniformBlocksWithoutBinding; <-- needs <set>
|
||||
1338 Uint activeUniformCount = 0;
|
||||
1346 Bool usesReservedNumSamples = false;
|
||||
1347 Uint maxUniformLocation = 0;
|
||||
1348 Int uniformNameMaxLength = 0;
|
||||
1349 Int attribInNameMaxLength = 0;
|
||||
1350 Int uniformBlockNameMaxLength = 0;
|
||||
1352 String infoLog;
|
||||
1353 Bool linkStatus = false;
|
||||
1357 Vector<XfbVarying> xfbVaryings;
|
||||
1363 Vector<String> xfbInterfaceNames;
|
||||
1364 Vector<Uint32> xfbStrides;
|
||||
1365 Vector<Uint32> gsStripTriangles;
|
||||
1366 Bool gsStripCaptureFixup = false;
|
||||
1367 GLenum gsInputPrimitive = GL_NONE;
|
||||
1371 Int tcsOutputVertices = 0;
|
||||
1380 GLenum gsOutputPrimitive = GL_NONE;
|
||||
1381 Int gsMaxVertices = 0;
|
||||
1382 Int gsInvocations = 0;
|
||||
1385 GLenum tessGenMode = GL_NONE;
|
||||
1386 GLenum tessGenSpacing = GL_NONE;
|
||||
1387 GLenum tessGenVertexOrder = GL_NONE;
|
||||
1388 Bool tessGenPointMode = false;
|
||||
1389 GLenum xfbBufferMode = GL_INTERLEAVED_ATTRIBS;
|
||||
1390 Int xfbVaryingNameMaxLength = 0;
|
||||
1391 Bool xfbNeedsScatteredCapture = false;
|
||||
1392 Uint32 xfbPackedStride = 0;
|
||||
```
|
||||
|
||||
Membership rule stated at :1177–1180: "exactly the field list `ResetLinkArtifacts()` clears (plus
|
||||
the four it forgot to — `infoLog`, `linkedFragDataLocation/Index` and the geometry strip-capture
|
||||
pair)". Access rule (invariant I5) at :1187–1192: `m_artifacts` is private and reachable only via
|
||||
`ProgramObject::Artifacts()`, which calls `EnsureLinkJoined()` first.
|
||||
|
||||
`std::set` is used at :1331 and :1336 but **`ProgramObject.h` never includes `<set>`** — it arrives
|
||||
transitively (`Includes.h` includes `<map>` at :17 but not `<set>`; `<set>` appears explicitly only
|
||||
in `MG_Util/ShaderTranspiler/glslang/TMglGlslIoResolver.h:15`, `ShaderCompiler.h:16`,
|
||||
`ShaderSourceProcessor.h:10`, `SpirvPasses/FlattenXfbInterfaceBlocksPass.h:15`,
|
||||
`SpirvPasses/UniquifyIoBlockNamesPass.h:16`, `TranslationCache.h:15`). **The new header must include
|
||||
`<set>` itself** or it will fail to compile once the transitive path is cut.
|
||||
|
||||
### 1.5 `SpirvArtifacts` — ProgramObject.h:1409–1449 (doc comment :1395–1408)
|
||||
|
||||
| line | member | type |
|
||||
|---|---|---|
|
||||
| 1410 | `generatedSpirv` | `Vector<Vector<unsigned>>` |
|
||||
| 1411 | `enableSpirvValidation` | `Bool` |
|
||||
| 1414 | `uniformOffsets` | `Vector<Uint>` |
|
||||
| 1415 | `globalUboScratch` | `Vector<Uint8>` |
|
||||
| 1420 | `reservedNumSamplesOffset` | `Uint` = **`kInvalidUniformOffset`** |
|
||||
| 1427 | `spirvStatus` | `Bool` |
|
||||
| 1436 | `nativeFloat64` | `Bool` |
|
||||
| 1448 | `pointSizeDemoted` | `Bool` |
|
||||
|
||||
**No glslang, no spirv-cross, no SPIRV-Reflect type.** One external dependency:
|
||||
`kInvalidUniformOffset`, declared at **ProgramObject.h:547** as
|
||||
`static constexpr Uint kInvalidUniformOffset = ~0u;` — i.e. a `ProgramObject` static member declared
|
||||
*before* `SpirvArtifacts` but *outside* it. Moving `SpirvArtifacts` out requires moving (or
|
||||
mirroring) this constant. Its readers, all of which spell it `ProgramObject::kInvalidUniformOffset`:
|
||||
`MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:4659` and `:8553`;
|
||||
`MG_Impl/GLImpl/Program/GL_Program.cpp:1249,1304,1522`; `MG_State/GLState/Core.cpp:513,514`;
|
||||
`MG_State/GLState/ProgramState/ProgramObject.cpp:198,273`; plus in-header uses at
|
||||
ProgramObject.h:565, :811, :1420.
|
||||
|
||||
### 1.6 `TUniformInitializer` — the one type that must be re-declared
|
||||
|
||||
`include/glslang/MachineIndependent/localintermediate.h:627–636` (vendored/forked glslang; this
|
||||
struct is a MobileGL fork addition, see commit `e5846569c`):
|
||||
|
||||
```cpp
|
||||
struct TUniformInitializer {
|
||||
std::string name;
|
||||
TBasicType basicType = EbtVoid;
|
||||
int vectorSize = 1;
|
||||
int matrixCols = 0;
|
||||
int matrixRows = 0;
|
||||
int arraySize = 1;
|
||||
std::vector<long long> intValues;
|
||||
std::vector<double> floatValues;
|
||||
};
|
||||
```
|
||||
|
||||
It is a plain aggregate — no pool allocator, no `TString`. `ProgramTranslationCache.h:44–47`
|
||||
independently states this: "the only member that ever pointed into glslang-owned memory was
|
||||
`program` itself, and `TUniformInitializer` / `XfbVarying`, which look like glslang types, are
|
||||
`std::string` + `std::vector` aggregates."
|
||||
|
||||
Producers/consumers of `uniformInitialValues`:
|
||||
- `MG_State/GLState/ProgramState/ProgramLinkTask.cpp:612–618` (dedupe + push_back)
|
||||
- `MG_State/GLState/ProgramState/ProgramObject.cpp:148` (`ApplyUniformInitialValues`, reads it)
|
||||
- `MG_State/GLState/ProgramState/ProgramObject.cpp:356` (`ResetLinkArtifacts` clears it)
|
||||
|
||||
**`ProgramObject.cpp:180–183` compares `init.basicType` against `glslang::EbtFloat`,
|
||||
`glslang::EbtFloat16`, `glslang::EbtDouble`, `glslang::EbtInt`, `glslang::EbtUint`,
|
||||
`glslang::EbtBool`.** Re-typing `basicType` to `Int` keeps this compiling only because those
|
||||
enumerators implicitly convert; if the new type is to be glslang-free, that `.cpp` (which is
|
||||
client-side and may keep including glslang) stays as-is, but the *header* must not name
|
||||
`glslang::TBasicType`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Transitive include closure of `ProgramObject.h` today
|
||||
|
||||
Direct includes, `ProgramObject.h:10–14`:
|
||||
```
|
||||
:10 #include <Includes.h>
|
||||
:11 #include "ShaderObject.h"
|
||||
:13 #include <MG_Util/Metrics/BufferMetrics.h>
|
||||
:14 #include <MG_Util/ShaderTranspiler/SpvcSession.h>
|
||||
```
|
||||
|
||||
Level 2:
|
||||
- `MG_State/GLState/ProgramState/ShaderObject.h:10–13` →
|
||||
`<Includes.h>`, `ShaderStage.h` (no includes at all), `ShaderCompileTask.h`,
|
||||
`ShaderCompileAdoptionMap.h`.
|
||||
- `MG_Util/ShaderTranspiler/SpvcSession.h:10–12` → `<Includes.h>`, **`<spirv_reflect.h>`**,
|
||||
`MG_Util/ShaderTranspiler/Types.h`.
|
||||
- `MG_Util/Metrics/BufferMetrics.h:10` → `<Includes.h>` only.
|
||||
|
||||
Level 3:
|
||||
- `ShaderCompileTask.h:10–15` → `<Includes.h>`, `MG_Util/Async/JobNode.h`,
|
||||
`MG_Util/ShaderTranspiler/CompileEnv.h`, `MG_Util/ShaderTranspiler/Types.h`,
|
||||
**`MG_State/GLState/BufferState/BufferState.h`**, `ProgramState/ShaderPreprocessCache.h`.
|
||||
- `ShaderCompileAdoptionMap.h:10–11` → `<Includes.h>`, `ProgramState/ShaderSourceKey.h`.
|
||||
- `MG_Util/ShaderTranspiler/Types.h:10–11` → `<Includes.h>`, `CompileEnv.h`.
|
||||
|
||||
**`Includes.h` is the elephant.** `MobileGL/Includes.h:79–83`, unconditional:
|
||||
```
|
||||
#include <glslang/Include/Types.h>
|
||||
#include <glslang/Public/ShaderLang.h>
|
||||
#include <glslang/SPIRV/GlslangToSpv.h>
|
||||
#include <glslang/Include/intermediate.h>
|
||||
#include <glslang/MachineIndependent/localintermediate.h>
|
||||
```
|
||||
plus `Includes.h:56` `<spirv_cross/spirv_cross_c.h>`, `:53` `<ska/flat_hash_map.hpp>`, `:55`
|
||||
`<xxhash.h>`, `:63–74` EGL/GL/GLES headers, `:130` `<vulkan/vulkan.h>`, `:148` `MG_Util/Debug/Log.h`,
|
||||
`:149` `MG_Util/Types.h` (which at :11 includes `<Includes.h>` back and at :12 `GLExtensions.h`).
|
||||
|
||||
**Consequence to flag loudly for the implementers:** the ARCHITECTURE wording "只 include
|
||||
`<Includes.h>` 与容器" does **not** by itself remove glslang from the preprocessed text of
|
||||
`ProgramArtifacts.h`, because `Includes.h` drags glslang in unconditionally. What it removes is the
|
||||
*by-value/by-symbol* dependency (`SharedPtr<glslang::TProgram>` needs `~TProgram`;
|
||||
`Vector<TUniformInitializer>` needs the type complete) — which is exactly what the P7 gate
|
||||
(`nm -D | grep glslang`, a **link/symbol** gate) measures. Two options for the header, both worth
|
||||
recording in the design note:
|
||||
- (a) include `<Includes.h>` as the docs say and rely on the type-level purge; the `-H` closure
|
||||
assertion then asserts the absence of `ShaderObject.h` / `SpvcSession.h` / `spirv_reflect.h`, not
|
||||
the absence of glslang.
|
||||
- (b) include only `MG_Util/Types.h` + `<set>` + GL headers, which would be genuinely glslang-free —
|
||||
but `MG_Util/Types.h:11` itself includes `<Includes.h>`, so this is not achievable without
|
||||
splitting `Types.h` too. **(a) is the only reachable shape today**; say so in the header comment.
|
||||
|
||||
Where `Includes.h` gets its type aliases (`MG_Util/Types.h`): `String` :21, `Int8..Uint64` :23–32,
|
||||
`Bool` :33, `Float`/`Double` :34–35, `StringView` :36, `Vector` :37–38, `Pair` :39–40, `SharedPtr`
|
||||
:41–42, `UniquePtr` :43–44, `WeakPtr` :45–46, `SizeT` :55, `Array` :56–57,
|
||||
`UnorderedMap = ska::flat_hash_map` :87–88, `Optional` :117, `Data = Vector<Uint8>` :123.
|
||||
|
||||
---
|
||||
|
||||
## 3. Every includer — verified counts
|
||||
|
||||
### 3.1 `ProgramObject.h` — 8 non-self includers (9 with its own .cpp)
|
||||
|
||||
| # | file:line | what it uses |
|
||||
|---|---|---|
|
||||
| 1 | `MobileGL/MG_Backend/DirectVulkan/Renderer/ProgramFactory.h:13` | `ProgramObject` by reference in `ComputeHash` (:474), `GetOrCreateProgram` (:475), `VkProgramObject::program` pointer (:583), `stages` doc note (:590). Names **no** artifact type. |
|
||||
| 2 | `MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.cpp:13` | `const ProgramObject&` parameter on ~15 resolvers (:232, :250, :465, :751, :808, :835, :862, :986, :1146, :1260, :1643, :1712, :1759, :1802, :1884). Accessors only; names no artifact type. |
|
||||
| 3 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:17` | `ProgramObject::kInvalidUniformOffset` (:4659, :8553); constructs internal blit/depth-mipmap `ProgramObject`s (:4232–4253, :4312–4316). |
|
||||
| 4 | `MobileGL/MG_Impl/GLImpl/Program/ProgramInterface.cpp:11` | **the heaviest consumer.** `ProgramObject::TypeFacts` (:84, :187, :198, :435), `ProgramObject::ResourceReflection` (:93), `ProgramObject::BlockReflection` (:176, :251), `ProgramObject::LinkArtifacts` (:228, :265, :328, :437, :528). Fields read off `LinkArtifacts`: `uniformReflection`, `blockReflection`, `pipeInputReflection`, `pipeOutputReflection`, `lastStageIsFragment` (only those five). |
|
||||
| 5 | `MobileGL/MG_State/GLState/ProgramState/ProgramLinkTask.h:11` | `ProgramObject::LinkArtifacts artifacts;` (:80) and `SpirvHandoff::reflection` (:118); `SharedPtr<const ProgramObject::SpirvArtifacts> cachedSpirv` (:147); `SharedPtr<const ProgramObject::LinkArtifacts> linkArtifactsForCache` (:151). Also holds `Vector<SharedPtr<glslang::TShader>> shaders` (:108) — genuinely glslang, stays client-side. |
|
||||
| 6 | `MobileGL/MG_State/GLState/ProgramState/ProgramPipelineObject.h:11` | pipeline composite; holds `SharedPtr<ProgramObject>` per stage. |
|
||||
| 7 | `MobileGL/MG_State/GLState/ProgramState/ProgramState.h:12` | the object table. **This is the fan-out node**: `MG_State/GLState/Core.h:16` includes it, so every `Core.h` includer (all of `MG_Impl`, both backends' `Managers.h`/`DirectVulkan.cpp`) reaches `ProgramObject.h` transitively. |
|
||||
| 8 | `MobileGL/MG_State/GLState/ProgramState/ProgramTranslationCache.h:11` | `ProgramTranslationResult { ProgramObject::LinkArtifacts link; ProgramObject::SpirvArtifacts spirv; }` (:50–51). |
|
||||
| (self) | `MobileGL/MG_State/GLState/ProgramState/ProgramObject.cpp:9` | — |
|
||||
|
||||
**The roadmap's "7 个 includer" does not reproduce as the ProgramObject.h includer count (8 non-self,
|
||||
9 with the .cpp).** It *does* reproduce exactly as the `ShaderObject.h` includer count (7, below), so
|
||||
the number is either a miscount or was written against `ShaderObject.h`. Implementers should plan
|
||||
for **8 includers of `ProgramObject.h`** plus the files that only *name* the types (§3.4).
|
||||
|
||||
### 3.2 `ShaderObject.h` — exactly 7 includers
|
||||
|
||||
| # | file:line | uses |
|
||||
|---|---|---|
|
||||
| 1 | `MobileGL/MG_Backend/DirectVulkan/Renderer/ProgramFactory.h:14` | `ShaderObject` for stage/source |
|
||||
| 2 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:18` | builds internal shaders (:4232 ff.) |
|
||||
| 3 | `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h:11` | `SharedPtr<ShaderObject>` attach lists, `LinkedShaderRef` (:150–154) |
|
||||
| 4 | `MobileGL/MG_State/GLState/ProgramState/ShaderObject.cpp:9` | self |
|
||||
| 5 | `MobileGL/MG_Util/Converters/GLToMG/ProgramEnumConverter.h:11` | `ShaderStage` conversion |
|
||||
| 6 | `MobileGL/MG_Util/Converters/MGToGL/ProgramEnumConverter.h:11` | ditto |
|
||||
| 7 | `MobileGL/MG_Util/ShaderTranspiler/ShaderSourceProcessor.h:13` | source preprocessing |
|
||||
|
||||
### 3.3 `SpvcSession.h` — 18 includers
|
||||
|
||||
`MobileGL/MG_Backend/DirectVulkan/Renderer/ProgramFactory.cpp:13`;
|
||||
`MobileGL/MG_Benchmark/ShaderCache/TranslationCacheBench.cpp:60`;
|
||||
`MobileGL/MG_Benchmark/Transpile/TranspileProfile.cpp:43`;
|
||||
`MobileGL/MG_State/GLState/ProgramState/ProgramObject.h:14`;
|
||||
`MobileGL/MG_State/GLState/ProgramState/ProgramSpirvTask.cpp:14`;
|
||||
`MobileGL/MG_Test/ShaderTranspiler/DemoteFloat64Test.cpp:18`;
|
||||
`.../DemotePointSizeTest.cpp:17`; `.../FlattenXfbInterfaceBlocksTest.cpp:18`;
|
||||
`.../LegalizeResourceArrayIndexTest.cpp:17`; `.../LowerViewportIndexTest.cpp:29`;
|
||||
`.../StripIoBlockLocationsTest.cpp:17`; `.../TranslationCacheTest.cpp:39`;
|
||||
`.../UniquifyIoBlockNamesTest.cpp:19`; `.../WidenImageFormatsTest.cpp:34`;
|
||||
`MobileGL/MG_Util/Converters/SPIRVCrossToGL/SpvcTypeConverter.cpp:10`;
|
||||
`MobileGL/MG_Util/Converters/SPIRVCrossToGL/SpvcTypeConverter.h:11`;
|
||||
`MobileGL/MG_Util/ShaderTranspiler/ShaderCompiler.h:11`;
|
||||
`MobileGL/MG_Util/ShaderTranspiler/SpvcSession.cpp:9`.
|
||||
|
||||
**`ProgramObject.h:14` is the only one of the 18 that is a `ProgramObject.h` include** — dropping it
|
||||
costs nothing to the other 17. Grep confirms `ProgramObject.h` names no `spvc_*` / `SpvReflect*` /
|
||||
`SpvcMetadata` symbol in its own body; the include is dead weight there (verify with a build before
|
||||
deleting — `ProgramObject.cpp` may rely on it transitively).
|
||||
|
||||
There are **no includers of any of the three headers outside `MobileGL/`** (checked the whole
|
||||
worktree; `Testing/`, `tools/`, `3rdparty/` have none).
|
||||
|
||||
### 3.4 Files that *name* one of the five types (these need `ProgramArtifacts.h`, or keep getting it
|
||||
via `ProgramObject.h`)
|
||||
|
||||
- `MobileGL/MG_Impl/GLImpl/Program/GL_Program.cpp:27–28` (`using TypeFactsRef = const ...::ProgramObject::TypeFacts&`), then :243, :250, :1197, :1213, :1246, :1301, :1545.
|
||||
- `MobileGL/MG_Impl/GLImpl/Program/ProgramInterface.cpp` — see §3.1 row 4.
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramLinkTask.cpp:48–49` (`MakeTypeFacts`), :79–81 (`MakeResourceReflection`), :94, :133, :866, :872, :876–877, :987, :991, :1114, :1122, :1302, :1331, :1383, :1439, :1539, :1730, :1758, :1768, :1789, :1796, :1857, :1944, :1960, :2038.
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramLinkTask.h:80, :114, :118, :145, :147, :148, :151, :203`.
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramSpirvTask.h:46`; `ProgramSpirvTask.cpp:127, :196, :234, :349`.
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramObject.cpp:198, :207, :273, :332–343, :356, :499–501, :686`.
|
||||
- `MobileGL/MG_State/GLState/ProgramState/ProgramTranslationCache.h:21, :34, :38–39, :46, :50–51`; `ProgramTranslationCache.cpp:39–40` (`sizeof(ProgramObject::ResourceReflection)`).
|
||||
- `MobileGL/MG_Util/ShaderTranspiler/TranslationCache.h:54, :429, :442` — **comments only**; MG_Util deliberately must not depend on MG_State (`ProgramTranslationCache.h:38–39`).
|
||||
- `MobileGL/MG_Pipe/MGPipeTypes.h:296` — comment on `MGPProgramDesc` naming the archive.
|
||||
- `MobileGL/MG_Test/Program/AsyncSpirvPhaseTest.cpp:336` — comment.
|
||||
- `MobileGL/MG_Backend/DirectGLES/Managers.cpp:6424, :6440` — uses `TypeFacts` through `const auto&`, never spelling the name.
|
||||
|
||||
---
|
||||
|
||||
## 4. How the two backends read the artifacts today
|
||||
|
||||
**Neither backend names `LinkArtifacts`, `SpirvArtifacts`, `ResourceReflection` or `XfbVarying`
|
||||
anywhere.** Both go exclusively through `ProgramObject` accessors, which are what the `PipeInputs`
|
||||
work of P1 replaces. This is good news for P0.5: moving the type declarations does not touch backend
|
||||
code at all.
|
||||
|
||||
### 4.1 DirectGLES (Espryt) — reads the **front-end tables**
|
||||
|
||||
Reaches `ProgramObject.h` transitively: `DirectGLES/Managers.h:17` → `MG_State/GLState/Core.h:16` →
|
||||
`ProgramState/ProgramState.h:12` → `ProgramObject.h`. (`DirectGLES.h:10–15` and `Managers.h:10–18`
|
||||
contain no direct include.)
|
||||
|
||||
Call sites (file:line → accessor → underlying artifact field):
|
||||
|
||||
*XFB (all `LinkArtifacts`)*
|
||||
- `DirectGLES.cpp:890` `GetTransformFeedbackPackedStride()` → `xfbPackedStride`
|
||||
- `DirectGLES.cpp:925, :1034` `GetTransformFeedbackStride(i)` → `xfbStrides[i]`
|
||||
- `DirectGLES.cpp:931`, `Managers.cpp:7448`, `Managers.cpp:8092` `GetTransformFeedbackVaryings()` → `xfbVaryings`
|
||||
- `DirectGLES.cpp:1005` `GetTransformFeedbackBufferCount()`
|
||||
- `DirectGLES.cpp:1027` `NeedsScatteredTransformFeedbackCapture()` → `xfbNeedsScatteredCapture`
|
||||
- `DirectGLES.cpp:1039, :1063` packed stride again (scatter buffer bind)
|
||||
- `DirectGLES.cpp:1097`, `Managers.cpp:8140, :8155, :8219` `GetTransformFeedbackBufferMode()` → `xfbBufferMode`
|
||||
- `Managers.cpp:8090` `GetTransformFeedbackVaryingCount()`
|
||||
|
||||
*Attributes / uniforms*
|
||||
- `DirectGLES.cpp:1247` `GetActiveAttributeLocationMask()`
|
||||
- `DirectGLES.cpp:1276, :1290` `GetAttribType(location)` → `attribTypes`
|
||||
- `DirectGLES.cpp:3036`, `Managers.cpp:6419, :6572` `GetMaxUniformLocation()` → `maxUniformLocation`
|
||||
- `DirectGLES.cpp:3038, :3564`, `Managers.cpp:468, :6450, :6589` `GetUniformSamplerOrImageUnitIndex(loc)` → `uniformSamplerOrImageUnitIndex`
|
||||
- `DirectGLES.cpp:3039`, `Managers.cpp:6423, :6576` `GetUniformType(loc)`
|
||||
- `Managers.cpp:463, :465, :6579` `GetUniformLocation(name)` → `uniformLocations`
|
||||
- `Managers.cpp:6421, :6574` `GetUniformName(loc)` → `uniformReflection[...].name`
|
||||
- **`Managers.cpp:6424` `GetUniformTypeFacts(loc)` → `uniformReflection[...].type` — the only direct
|
||||
`TypeFacts` read in either backend** (comment at :6440: "From the OWNED TypeFacts, not from a live
|
||||
TType"). It is bound with `const auto&`, so the type name never appears.
|
||||
|
||||
*Blocks / SPIR-V / status*
|
||||
- `DirectGLES.cpp:2734, :3033, :3336, :3374, :3663, :4071`, `Managers.cpp:7321` `GetLinkStatus()` / `GetSpirvStatus()` → `linkStatus` / `spirvStatus`
|
||||
- `DirectGLES.cpp:3397, :3402, :3444, :3449`, `Managers.cpp:8290, :8293` `GetUBOSize()` → `globalUboScratch.size()`
|
||||
- `DirectGLES.cpp:3481` `GetUniformBlockBinding(i)` → `uniformBlockBinding`
|
||||
- `Managers.cpp:6192, :6202, :7341` `GetShaderStorageBlockBindingOverrides()` → `shaderStorageBlockBinding`
|
||||
- `Managers.cpp:7408` `GetLinkedShaderStages()`; `:7409` `GetGeneratedSpirv()` → `generatedSpirv`;
|
||||
`:7430` `GetLinkedShaderSnapshot()`; `:7439` `GetSpirvValidationEnabled()` → `enableSpirvValidation`
|
||||
- version/identity: `GetLinkVersion` (`DirectGLES.cpp:2798, :3715, :7368`), `GetImageUnitVersion`
|
||||
(:2799), `GetBackendStateVersion` (:3335, :3350, :3540), `GetLifetimeId` (:3333, :3349),
|
||||
`GetExternalIndex` (many, `Managers.cpp:7212` ff.). These live on `ProgramObject`, **not** in the
|
||||
artifacts — they must stay behind.
|
||||
|
||||
`ARCHITECTURE.md:310` additionally notes Espryt's `ScatterCapturedRecords` is a read-modify-write on
|
||||
the *client* shadow and that under split the client keeps the varying/stride tables from the
|
||||
reflection archive.
|
||||
|
||||
### 4.2 DirectVulkan (Magma) — re-derives with **SPIRV-Reflect**
|
||||
|
||||
`MG_Backend/DirectVulkan/DirectVulkan.cpp:22` `#include <spirv_reflect.h>`.
|
||||
|
||||
The re-derivation lives in `GetProgramResourceCache(const ProgramObject&)` at
|
||||
**`DirectVulkan.cpp:161–2xx`** (the docs' "around line 161" is exact — the function opens at :161,
|
||||
the cache lookup at :162). Shape:
|
||||
|
||||
- Caches keyed by GL program name: `UnorderedMap<GLuint, ProgramResourceCache> g_programResourceCaches;`
|
||||
at `DirectVulkan.cpp:103`; cleared at `:305` (`ClearProgramResourceCaches`); insertion hazard note
|
||||
at `:728`.
|
||||
- `struct BufferVariableResource` `:51–57`, `struct StorageBlockResource` `:58–63`,
|
||||
`struct ProgramResourceCache` `:65–81` (`programLifetimeId`, `backendStateVersion`,
|
||||
`blockBindingVersion`, `Vector<StorageBlockResource> storageBlocks`,
|
||||
`Vector<BufferVariableResource> bufferVariables`).
|
||||
- Validity key `:171–174`: `GetLifetimeId()` + `GetBackendStateVersion()` +
|
||||
`GetBlockBindingVersion()`. On a block-binding-only bump (`:176–190`) it re-applies
|
||||
`program.GetShaderStorageBlockBindingOverride(block.name)` **by name** instead of re-reflecting —
|
||||
i.e. `LinkArtifacts::shaderStorageBlockBinding` is the authority and spirv-reflect is the
|
||||
structure.
|
||||
- The reflect run itself `:196–...`: `program.GetGeneratedSpirv()` → per module
|
||||
`spvReflectCreateShaderModule(spirv.size() * sizeof(Uint), spirv.data(), &module)` (:205),
|
||||
`spvReflectEnumerateDescriptorBindings` (:216, :222).
|
||||
- `NormalizeDescriptorName` `:118–131` strips a `"[0]"` suffix off `type_description->type_name`.
|
||||
- `AddBufferVariablesRecursive` `:133–159` walks `SpvReflectBlockVariable::members` recursively to
|
||||
build the `GL_BUFFER_VARIABLE` list with names/offsets/sizes.
|
||||
|
||||
This is exactly the "three consumers of one archive" open question at `ROADMAP.md:81`: Espryt reads
|
||||
the front-end tables, Magma runs SPIRV-Reflect, and `DirectVulkan.cpp` reflects a second time for
|
||||
`glGetProgramResource*`. **P0.5 changes none of it** — but note that the archive as shipped
|
||||
(`LinkArtifacts` alone) does not contain buffer-variable / storage-block reflection, which is why
|
||||
Magma re-derives; the server can keep doing exactly that from the shipped SPIR-V.
|
||||
|
||||
Magma's other `ProgramObject` reads (`UniformManager.cpp`, `ProgramFactory.h/.cpp`,
|
||||
`VulkanRenderer.cpp`) are all accessor calls; see §3.1 rows 1–3.
|
||||
|
||||
---
|
||||
|
||||
## 5. Existing `Visit()` / archive / serialization patterns to follow
|
||||
|
||||
**There is no `Visit()`, `Archive()`, `Serialize()` or `ForEachField()` in the tree today**
|
||||
(`grep -rn "Visit(\|ForEachField\|Archive(\|Serialize(\|Deserialize("` over `MobileGL/` returns
|
||||
nothing). The `Visit()` archive is genuinely new. The two prior-art patterns to imitate:
|
||||
|
||||
### 5.1 The X-macro field table — `MG_Pipe/PipeFields.def`
|
||||
|
||||
`MobileGL/MG_Pipe/PipeFields.def:9–18` states the contract: one macro per payload in
|
||||
`MGPipeTypes.h`, listing only the fields that carry **meaning** (padding deliberately absent, because
|
||||
`MOBILEGL_PIPE_VERIFY` must have zero false positives). Hand-maintained alongside the struct; a field
|
||||
added without a `.def` entry makes the comparator blind to it.
|
||||
|
||||
Shape (`PipeFields.def:83–85`):
|
||||
```c
|
||||
#define MGP_FIELDS_MGPProgramDesc(F) \
|
||||
F(Cso) F(StageMask) F(GlobalUboSize) F(ReservedNumSamplesOffset) F(SpirvStatus) F(NativeFloat64) \
|
||||
F(PointSizeDemoted) F(EnableSpirvValidation) F(Spirv) F(Reflection)
|
||||
```
|
||||
and a roll-up list at `PipeFields.def:227` enumerating every payload. Consumed by
|
||||
`scripts/gen_pipe.py` (docstring at `scripts/gen_pipe.py:9–33`), which emits
|
||||
`MobileGL/MG_Pipe/generated/{PipeWire,PipeVerify,PipeTables,PipeThunks,PipeFilled,PipeSpanTable,PipeCoverage}.inc`.
|
||||
Outputs are committed; CI regenerates and fails on a diff. `gen_pipe.py` refuses a catalogue payload
|
||||
with no field list.
|
||||
|
||||
**Recommendation:** the `Visit()` archive is the C++-template analogue of this — but because
|
||||
`LinkArtifacts` members are `String`/`Vector`/`UnorderedMap`/`std::set` rather than scalars, a
|
||||
generated `.inc` is less natural than a member-template. The prior art to cite is the
|
||||
*discipline* (one field table, both directions, a gate that goes red on a missed field), not the
|
||||
macro mechanics.
|
||||
|
||||
### 5.2 The sizeof tripwire — `MG_Pipe/MGPipeTypes.h`
|
||||
|
||||
Two idioms, both worth copying:
|
||||
|
||||
**(a) The POD assertion macro**, `MGPipeTypes.h:43–45`:
|
||||
```c
|
||||
#define MGP_ASSERT_POD(T, Size) \
|
||||
static_assert(std::is_trivially_copyable_v<T>, #T " must be trivially copyable"); \
|
||||
static_assert(sizeof(T) == (Size), #T " changed size; update the wire format and this assertion")
|
||||
```
|
||||
used e.g. `MGP_ASSERT_POD(MGPProgramDesc, 192);` at `MGPipeTypes.h:308`. Rationale at
|
||||
`MGPipeTypes.h:20–22`: "Sizes are asserted rather than merely documented because the wire records
|
||||
generated from these structs are memcpy'd; a field silently changing width is a protocol break that
|
||||
no test would otherwise see."
|
||||
|
||||
**(b) The named-constant ratchet**, `MGPipeTypes.h:527–539` — this is the exact shape
|
||||
`MGL_LINKARTIFACTS_SIZE` should take:
|
||||
```c
|
||||
#define MGL_RESIDUAL_BLOCK_SIZE 1248
|
||||
static_assert(sizeof(ResidualValueBlock) == MGL_RESIDUAL_BLOCK_SIZE,
|
||||
"the residual value block changed size; lower MGL_RESIDUAL_BLOCK_SIZE if a field "
|
||||
"retired, and do not raise it");
|
||||
```
|
||||
with a comment block (:527–535) explaining the direction of travel and what makes it a build break.
|
||||
`MGPipeTypes.h:504–507` adds the caveat that a heterogeneous POD **also** needs member-by-member
|
||||
`offsetof` assertions, since padding differs across ABIs and the monolith verify harness is blind to
|
||||
it (both sides are one TU).
|
||||
|
||||
**Caveat for `LinkArtifacts`:** `sizeof(LinkArtifacts)` is **not ABI-stable and not
|
||||
trivially-copyable** — it contains `std::string`, `std::vector`, `ska::flat_hash_map` and `std::set`,
|
||||
whose sizes differ between libstdc++/libc++/MSVC and between debug/release STL configurations.
|
||||
`MGL_LINKARTIFACTS_SIZE` therefore cannot be a single literal the way `MGL_RESIDUAL_BLOCK_SIZE` is;
|
||||
it is a **same-build tripwire** ("did somebody add a field without touching `Visit()`"), not a wire
|
||||
size. Options: (i) assert per-toolchain values behind `#if`, (ii) assert only under a canonical CI
|
||||
toolchain (`#if defined(__GLIBCXX__) && !defined(_GLIBCXX_DEBUG)`), or (iii) drop the byte count and
|
||||
assert a **field count** the `Visit()` template computes at compile time. State whichever you pick in
|
||||
the header — the ARCHITECTURE wording assumes (i)/(ii).
|
||||
|
||||
### 5.3 The `-H` include-closure gate
|
||||
|
||||
`ARCHITECTURE.md:425` describes purity gate A: `MG_Remote/Transport/` headers must not include the
|
||||
front-end umbrella, "纯度门 A 断言 `-H` 输出". **No such script exists yet** — `scripts/` contains
|
||||
only `check_doc_citations.py`, `format_code.sh`, `gen_pipe.py`, `gen_pipe_dirty_surface.py`,
|
||||
`gen_protocol.py`, `update-source-file-header.py`. The P0.5 implementer writes the first one, and
|
||||
`ROADMAP.md:16` requires it be demonstrably red when a `MG_State` include is added back.
|
||||
|
||||
Related counter-example already in the tree: `MGPipeTypes.h:24–31` documents its own P0.5 debt in the
|
||||
file header ("P0.5 DEBT, recorded here so it is impossible to miss") for `#include
|
||||
<MG_Backend/BackendObject.h>` (:32) and `#include <MG_State/GLState/RenderState/RenderState.h>`
|
||||
(:33). **Follow that convention**: any include `ProgramArtifacts.h` cannot yet drop gets an explicit
|
||||
debt paragraph in the file header.
|
||||
|
||||
---
|
||||
|
||||
## 6. Proposed contents of `ProgramArtifacts.h`
|
||||
|
||||
File: `MobileGL/MG_State/GLState/ProgramState/ProgramArtifacts.h`
|
||||
Namespace: `MobileGL::MG_State::GLState` (**top-level, not nested in `ProgramObject`**).
|
||||
|
||||
### 6.1 Includes
|
||||
|
||||
```cpp
|
||||
#pragma once
|
||||
#include <Includes.h> // String/Vector/UnorderedMap/Array + GL enums; see debt note below
|
||||
#include <set> // std::set<String>, used by LinkArtifacts - NOT in Includes.h
|
||||
```
|
||||
Nothing else. Explicitly **not**: `ShaderObject.h`, `SpvcSession.h`, `ProgramLinkTask.h`,
|
||||
`BufferMetrics.h`, `<spirv_reflect.h>`.
|
||||
|
||||
File-header debt paragraph (mandatory, mirroring `MGPipeTypes.h:24–31`): `<Includes.h>` still pulls
|
||||
glslang (`Includes.h:79–83`), spirv-cross C (`:56`) and Vulkan (`:130`). This header is glslang-free
|
||||
**by type and by symbol**, which is what the P7 `nm -D | grep glslang` gate measures; a textually
|
||||
glslang-free closure additionally requires splitting `MG_Util/Types.h` (which itself includes
|
||||
`<Includes.h>` at :11) and is out of P0.5 scope.
|
||||
|
||||
### 6.2 Types, in dependency order
|
||||
|
||||
1. **`kInvalidUniformOffset`** — move `static constexpr Uint kInvalidUniformOffset = ~0u;`
|
||||
(ProgramObject.h:547) out to a namespace-scope `inline constexpr Uint kInvalidUniformOffset = ~0u;`
|
||||
in this header, and leave `static constexpr Uint kInvalidUniformOffset = kInvalidUniformOffset;`…
|
||||
no — leave a **`using`-style re-export** in `ProgramObject`:
|
||||
`static constexpr Uint kInvalidUniformOffset = MobileGL::MG_State::GLState::kInvalidUniformOffset;`
|
||||
so the 9 existing spellings `ProgramObject::kInvalidUniformOffset` (§1.5) keep compiling
|
||||
unchanged. This is required: `SpirvArtifacts::reservedNumSamplesOffset` (:1420) uses it as a
|
||||
default member initializer.
|
||||
|
||||
2. **`struct TypeFacts`** — verbatim move of ProgramObject.h:44–72, comments included. Zero changes;
|
||||
already POD, already glslang-free.
|
||||
|
||||
3. **`struct ResourceReflection`** — verbatim move of :76–99, plus the four aliases :101–104 moved to
|
||||
namespace scope.
|
||||
|
||||
4. **`struct XfbVarying`** — verbatim move of :1146–1171. Zero changes.
|
||||
|
||||
5. **`struct UniformInitializer`** — **NEW**, the de-glslang'd replacement for
|
||||
`glslang::TIntermediate::TUniformInitializer` (`include/glslang/MachineIndependent/localintermediate.h:627–636`):
|
||||
```cpp
|
||||
struct UniformInitializer {
|
||||
String name;
|
||||
Int basicType = 0; // widened glslang::TBasicType, same convention as TypeFacts::basicType
|
||||
Int vectorSize = 1;
|
||||
Int matrixCols = 0;
|
||||
Int matrixRows = 0;
|
||||
Int arraySize = 1;
|
||||
Vector<Int64> intValues; // was std::vector<long long>
|
||||
Vector<Double> floatValues; // was std::vector<double>
|
||||
};
|
||||
```
|
||||
`Int64` = `MG_Util/Types.h:31`, `Double` = `:35`. The widening of `basicType` to `Int` matches the
|
||||
precedent already set by `TypeFacts::basicType` (ProgramObject.h:71) and
|
||||
`TypeFacts::layoutMatrix` (:68).
|
||||
|
||||
6. **`struct LinkArtifacts`** — moved from :1210–1393, with **exactly two member re-types**:
|
||||
- `:1215 SharedPtr<glslang::TProgram> program;` → **stays in `ProgramObject.h`**, see §6.3.
|
||||
- `:1282 Vector<glslang::TIntermediate::TUniformInitializer> uniformInitialValues;` →
|
||||
`Vector<UniformInitializer> uniformInitialValues;`
|
||||
All other 51 members move verbatim.
|
||||
|
||||
7. **`struct SpirvArtifacts`** — verbatim move of :1409–1449, once `kInvalidUniformOffset` is in
|
||||
scope (item 1).
|
||||
|
||||
8. **The archive** — `Visit()` as a member template on each of the five, plus the tripwires:
|
||||
```cpp
|
||||
template <class V> void TypeFacts::Visit(V&& v) { v(isArray); v(isSizedArray); /* 20 fields */ }
|
||||
```
|
||||
with a matching `static_assert` per struct. The `Visit()` must be `const`-overloaded (or take
|
||||
`auto&& self`, C++23 deducing-this — the project is C++23, see `Includes.h:47`
|
||||
`__cplusplus >= 202302L`) so one field list serves both write (const) and read (mutable), which is
|
||||
the "一份字段表服务序列化两个方向" requirement of `ARCHITECTURE.md:259`.
|
||||
|
||||
### 6.3 What must **stay** in `ProgramObject.h`
|
||||
|
||||
- `ProgramObject::MAX_UNIFORM_LOCATIONS` (:39) — `static_cast<Int>(glslang::TQualifier::layoutLocationEnd)`.
|
||||
Named by `MG_Impl/GLImpl/Getter/GL_Getter.cpp:1945`, `ProgramLinkTask.cpp:1251`. Stays glslang-bound;
|
||||
it is not one of the five types. (If P7 later needs it server-side, replace the RHS with the literal
|
||||
and `static_assert` against glslang on the client — flag but do not do this in P0.5.)
|
||||
- **`LinkArtifacts::program`** — the `SharedPtr<glslang::TProgram>`. Two options; pick (A):
|
||||
- **(A) Keep it inside `LinkArtifacts` but change nothing about the header's purity by making the
|
||||
field's type a forward-declared incomplete `glslang::TProgram`.** `SharedPtr<T>` of an incomplete
|
||||
`T` is legal to declare, copy and move; only construction and destruction need completeness, and
|
||||
both happen in `ProgramLinkTask.cpp` (the only writer: :646, :678, :764, :846, :877) and
|
||||
`ProgramObject.cpp:499–501` (whole-struct reset). **But** `LinkArtifacts`'s own implicit
|
||||
destructor must destroy the `shared_ptr`, and that is instantiated wherever a `LinkArtifacts` is
|
||||
destroyed — including in `ProgramInterface.cpp` and `ProgramTranslationCache.cpp`. A
|
||||
`shared_ptr`'s destructor does **not** require `T` complete (the deleter was type-erased at
|
||||
construction), so this works: `namespace glslang { class TProgram; }` at the top of
|
||||
`ProgramArtifacts.h` is sufficient. **Verify by compiling with a hand-edited `Includes.h` that
|
||||
hides glslang**, because this is the single highest-risk claim in this plan.
|
||||
- (B) Move `program` out of `LinkArtifacts` onto `ProgramLinkTask` and pass it beside the
|
||||
artifacts. Cleaner for the server, but touches ~30 call sites in `ProgramLinkTask.cpp`
|
||||
(§1.4 readers) and `ProgramSpirvTask.cpp:127, :234` — a bigger diff than "纯搬移" allows.
|
||||
Record as the P7 follow-up if (A)'s incomplete-type trick fails on any toolchain.
|
||||
- Everything else: the ~120 accessors, `Artifacts()`/`Spirv()` join gates (:1682–1698),
|
||||
`EnsureLinkJoined`/`EnsureSpirvJoined` (:1633, :1648), `ResetLinkArtifacts` declaration (:1457,
|
||||
defined `ProgramObject.cpp:332`), `LinkedShaderRef` (:150–154), `PendingUniformWrite` (:1658–1663),
|
||||
`BackendHashMemoSlot` (:1767–1771), and all `m_*` members (:1712–1801).
|
||||
|
||||
### 6.4 Forwarding shape
|
||||
|
||||
`ProgramObject.h` keeps compiling every existing spelling (`ProgramObject::LinkArtifacts`,
|
||||
`ProgramObject::TypeFacts`, …) via in-class `using` re-exports, so **no other file changes at all**
|
||||
in P0.5 (this is what makes the exit gate "全套测试逐名不变(纯搬移)" achievable):
|
||||
|
||||
```cpp
|
||||
// ProgramObject.h, replacing lines 41-104, 1144-1449
|
||||
#include <MG_State/GLState/ProgramState/ProgramArtifacts.h>
|
||||
...
|
||||
class ProgramObject {
|
||||
public:
|
||||
using TypeFacts = MobileGL::MG_State::GLState::TypeFacts;
|
||||
using ResourceReflection = MobileGL::MG_State::GLState::ResourceReflection;
|
||||
using UniformReflection = ResourceReflection;
|
||||
using BlockReflection = ResourceReflection;
|
||||
using PipeInputReflection = ResourceReflection;
|
||||
using PipeOutputReflection = ResourceReflection;
|
||||
using XfbVarying = MobileGL::MG_State::GLState::XfbVarying;
|
||||
using UniformInitializer = MobileGL::MG_State::GLState::UniformInitializer;
|
||||
using LinkArtifacts = MobileGL::MG_State::GLState::LinkArtifacts;
|
||||
using SpirvArtifacts = MobileGL::MG_State::GLState::SpirvArtifacts;
|
||||
static constexpr Uint kInvalidUniformOffset = MobileGL::MG_State::GLState::kInvalidUniformOffset;
|
||||
...
|
||||
```
|
||||
`ProgramObject.h` also **drops `#include <MG_Util/ShaderTranspiler/SpvcSession.h>` (:14)** — it names
|
||||
no spvc/SpvReflect symbol (verified by grep). Keep `#include "ShaderObject.h"` (:11) and
|
||||
`#include <MG_Util/Metrics/BufferMetrics.h>` (:13); both are genuinely used by `ProgramObject`
|
||||
itself. Removing :14 is the one purity win available to `ProgramObject.h` in this phase; the glslang
|
||||
dependency stays because `MAX_UNIFORM_LOCATIONS` and `SharedPtr<glslang::TProgram>` are there.
|
||||
|
||||
Note the alias `using TypeFacts = ...::TypeFacts;` inside a class whose enclosing namespace already
|
||||
declares `TypeFacts` is legal (member alias shadows), but the qualified RHS is mandatory or it
|
||||
self-references. Spell it fully qualified as above.
|
||||
|
||||
### 6.5 Where the `Visit()` archive's two directions live
|
||||
|
||||
Serializer/deserializer bodies do **not** belong in `ProgramArtifacts.h` (that would drag whichever
|
||||
byte-stream helper into every `Core.h` consumer). Put them where `MGPProgramDesc::Reflection`'s blob
|
||||
is built and parsed — the natural home is a new `MG_Pipe/` or `MG_Remote/` TU that includes
|
||||
`ProgramArtifacts.h` and nothing else from `MG_State`. `ProgramArtifacts.h` carries only the field
|
||||
tables (`Visit`) and the tripwires.
|
||||
|
||||
---
|
||||
|
||||
## 7. Risk list
|
||||
|
||||
**R1 — `Includes.h` is not glslang-free (HIGH, design-level).** `Includes.h:79–83` pulls all five
|
||||
glslang headers unconditionally. Following the ARCHITECTURE literally ("只 include `<Includes.h>` 与
|
||||
容器") yields a header that is glslang-free *by type* but not *by preprocessed text*. Decide and
|
||||
document which gate the `-H` assertion enforces before writing it, or the gate will be written to a
|
||||
criterion the header cannot meet. See §2.
|
||||
|
||||
**R2 — `sizeof(LinkArtifacts)` is not a stable number.** `String`/`Vector`/`ska::flat_hash_map`/
|
||||
`std::set` sizes vary by STL and by `_GLIBCXX_DEBUG`. `MGL_LINKARTIFACTS_SIZE` cannot be a bare
|
||||
literal the way `MGL_RESIDUAL_BLOCK_SIZE` (`MGPipeTypes.h:536`) is. Also note the project builds on
|
||||
Windows/MSVC (this worktree), Android/NDK-libc++ and Linux/libstdc++ — three different answers. See
|
||||
§5.2 for the three mitigation options.
|
||||
|
||||
**R3 — `SharedPtr<glslang::TProgram>` by value in `LinkArtifacts` (ProgramObject.h:1215).** This is
|
||||
the single member that references glslang by value in the archived types. The incomplete-type plan
|
||||
(§6.3 option A) is sound in principle but must be compile-verified on all three toolchains; MSVC in
|
||||
particular has historically been strict about `shared_ptr<Incomplete>` in aggregates with implicit
|
||||
special members. Fallback is §6.3 option B. Related: the server will deserialize a `LinkArtifacts`
|
||||
whose `program` is always null — assert that at the deserializer, matching the existing insert-time
|
||||
assertion documented at `ProgramTranslationCache.h:42–43` ("`link.program` is null by construction …
|
||||
Asserted at insert").
|
||||
|
||||
**R4 — `glslang::TIntermediate::TUniformInitializer` re-typing breaks a comparison.**
|
||||
`MG_State/GLState/ProgramState/ProgramObject.cpp:180–183` compares `init.basicType` against
|
||||
`glslang::EbtFloat` / `EbtFloat16` / `EbtDouble` / `EbtInt` / `EbtUint` / `EbtBool`. With
|
||||
`basicType` widened to `Int` this still compiles (enum→int promotion) but the file keeps a glslang
|
||||
dependency; that is fine (it is a client TU) as long as the *header* does not. Also
|
||||
`ProgramLinkTask.cpp:612–618` builds the vector via `std::find_if` on `.name` and copies the whole
|
||||
struct — a plain type substitution, no field-order sensitivity.
|
||||
|
||||
**R5 — `<set>` (MEDIUM, will bite immediately).** `LinkArtifacts` uses `std::set<String>` at :1331
|
||||
and :1336 and no header on the path includes `<set>` deliberately. Add it explicitly. See §1.4.
|
||||
|
||||
**R6 — `kInvalidUniformOffset` ordering (MEDIUM).** Declared at ProgramObject.h:547, *used* as a
|
||||
default member initializer at :1420. Moving `SpirvArtifacts` without moving the constant is an
|
||||
immediate compile error, and moving the constant without a re-export breaks 9 call sites across three
|
||||
modules (§1.5). Handle both halves in one commit.
|
||||
|
||||
**R7 — ODR / aliasing (LOW but real).** Injecting `using TypeFacts = ...::TypeFacts;` inside
|
||||
`ProgramObject` while a namespace-scope `TypeFacts` exists in the same namespace is fine, but
|
||||
`ProgramLinkTask.cpp:48` writes
|
||||
`static MobileGL::MG_State::GLState::ProgramObject::TypeFacts MakeTypeFacts(...)` — the
|
||||
fully-qualified-through-the-class spelling. That resolves through the alias unchanged. Watch for any
|
||||
place that forward-declares one of these types instead of including the header: grep found none, but
|
||||
re-check after the move. Also: **do not leave a second definition behind** — the classic P0.5 failure
|
||||
is copying the struct into the new header and forgetting to delete it from `ProgramObject.h`, which
|
||||
compiles (different scopes: `GLState::TypeFacts` vs `GLState::ProgramObject::TypeFacts`) and silently
|
||||
splits the type in two.
|
||||
|
||||
**R8 — pImpl / join-gate boundary (LOW, but the invariant to protect).** `LinkArtifacts` and
|
||||
`SpirvArtifacts` become namespace-scope types, so anyone can now *declare* one without going through
|
||||
`ProgramObject::Artifacts()`. The I5 invariant (ProgramObject.h:1187–1192, :1622–1631) is protected by
|
||||
`m_artifacts` being **private**, not by the type being nested — so the invariant survives the move.
|
||||
Say so in a comment at the top of `LinkArtifacts` in the new header, because the current comment
|
||||
explains I5 in terms of "the member below is private", and that member no longer lives next to the
|
||||
struct.
|
||||
|
||||
**R9 — `ProgramTranslationCache.cpp:40` takes `sizeof(ProgramObject::ResourceReflection)`.** It feeds
|
||||
a byte budget, not an allocator ("Approximate on purpose", `ProgramTranslationCache.cpp:46–48`), so a
|
||||
size change is harmless — but it is a second place that must keep compiling after the alias move.
|
||||
|
||||
**R10 — the "7 includers" figure is wrong.** Verified: `ProgramObject.h` has **8** non-self includers
|
||||
(9 with `ProgramObject.cpp`); `ShaderObject.h` has exactly 7; `SpvcSession.h` has 18. Budget P0.5
|
||||
against the real numbers (§3), and note that if `ProgramObject.h` drops its `SpvcSession.h` include
|
||||
(§6.4) the `SpvcSession.h` count falls to 17 while every remaining includer is a
|
||||
ShaderTranspiler/test/benchmark TU that legitimately wants spirv-cross.
|
||||
|
||||
**R11 — fan-out.** `MG_State/GLState/Core.h:16` → `ProgramState.h:12` → `ProgramObject.h` means both
|
||||
backends and all of `MG_Impl` recompile on any `ProgramObject.h` touch, and *nothing in either
|
||||
backend directly includes it*. That is the reason the extraction buys real build-time and symbol
|
||||
separation later — and the reason the `-H` closure assertion should be run against
|
||||
`MG_Backend/DirectGLES/Managers.cpp` and `MG_Backend/DirectVulkan/DirectVulkan.cpp` (the two big
|
||||
transitive consumers), not only against `ProgramArtifacts.h` itself.
|
||||
|
||||
---
|
||||
|
||||
## 8. Quick reference — file inventory
|
||||
|
||||
| path | why it matters |
|
||||
|---|---|
|
||||
| `MobileGL/MG_State/GLState/ProgramState/ProgramObject.h` | all five types live here today (1803 lines) |
|
||||
| `MobileGL/MG_State/GLState/ProgramState/ProgramObject.cpp` | `ResetLinkArtifacts` :332, `ApplyUniformInitialValues` :143–215, `kInvalidUniformOffset` uses :198/:273 |
|
||||
| `MobileGL/MG_State/GLState/ProgramState/ShaderObject.h` | 319 lines; 7 includers; the glslang/`ShaderCompileTask` path |
|
||||
| `MobileGL/MG_Util/ShaderTranspiler/SpvcSession.h` | 18 includers; pulls `<spirv_reflect.h>` :11 |
|
||||
| `MobileGL/MG_State/GLState/ProgramState/ProgramLinkTask.h` | `artifacts` :80, `SpirvHandoff` :92–158 |
|
||||
| `MobileGL/MG_State/GLState/ProgramState/ProgramLinkTask.cpp` | sole writer of `LinkArtifacts.program`; `MakeTypeFacts` :48, `MakeResourceReflection` :79 |
|
||||
| `MobileGL/MG_State/GLState/ProgramState/ProgramSpirvTask.h` | `artifacts` :46 |
|
||||
| `MobileGL/MG_State/GLState/ProgramState/ProgramTranslationCache.h` | `ProgramTranslationResult` :49–52 — the existing "whole archive as a value" precedent |
|
||||
| `MobileGL/MG_Impl/GLImpl/Program/ProgramInterface.cpp` | only consumer that names `LinkArtifacts` outside `ProgramState/` |
|
||||
| `MobileGL/MG_Impl/GLImpl/Program/GL_Program.cpp` | `TypeFactsRef` alias :27–28 |
|
||||
| `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp`, `Managers.cpp` | Espryt accessor call sites (§4.1) |
|
||||
| `MobileGL/MG_Backend/DirectVulkan/DirectVulkan.cpp` | SPIRV-Reflect re-derivation :51–305 |
|
||||
| `MobileGL/MG_Pipe/MGPipeTypes.h` | `MGPProgramDesc` :296–308; the two tripwire idioms :43–45 and :527–539; the P0.5 debt-note convention :24–33 |
|
||||
| `MobileGL/MG_Pipe/PipeFields.def` | the X-macro field-table prior art :9–18, :83–85, :227 |
|
||||
| `MobileGL/MG_Pipe/PipeCalls.def:102` | `X(CreateShaderState, MGPProgramDesc, kCtxCso, kHasBlob)` |
|
||||
| `scripts/gen_pipe.py` | the generator that consumes the `.def` files; `--check` mode is the CI gate |
|
||||
| `MobileGL/Includes.h` | :79–83 glslang, :56 spirv-cross, :17 `<map>` (no `<set>`), :149 `MG_Util/Types.h` |
|
||||
| `MobileGL/MG_Util/Types.h` | every alias the new header uses (:21–123) |
|
||||
| `include/glslang/MachineIndependent/localintermediate.h:627–636` | `TUniformInitializer` — the struct to re-declare |
|
||||
| `docs/Disaggregated/ARCHITECTURE.md:256–264` | section 7 |
|
||||
| `docs/Disaggregated/ROADMAP.md:16` | P0.5 row |
|
||||
@@ -0,0 +1,401 @@
|
||||
# Scout: `MobileGL/MG_Pipe/MGPipeValueTypes.h` (P0.5 value-header extraction)
|
||||
|
||||
Worktree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch `feat/disaggregated` @ `6e0e3df3`.
|
||||
All paths below are relative to that worktree root unless absolute. Every line number was opened and read.
|
||||
|
||||
---
|
||||
|
||||
## 0. What the tree already says the task is
|
||||
|
||||
The debt is already written down in three places; the implementer should treat these as the spec:
|
||||
|
||||
- `MobileGL/MG_Pipe/MGPipeTypes.h:24-33` — the in-file P0.5 debt note:
|
||||
> "two payloads reach into headers this directory is eventually forbidden to see - `MGPCaps` embeds MG_Backend's `DynamicBackendParameters`, and `ResidualValueBlock` embeds MG_State's `RenderStateParameters` and `PixelStoreParameters` … P0.5 extracts `MGPipeValueTypes.h` and both includes below go away; until then purity gate A (section 10.3) cannot be armed for this header."
|
||||
- `docs/Disaggregated/ARCHITECTURE.md:260` — names the exact intended member list:
|
||||
> 同批抽取 `MG_Pipe/MGPipeValueTypes.h`(`MAX_DRAW_BUFFERS`、`PerBufferBlendState`、`StencilFaceState`、`PixelStoreParameters`、`RenderStateParameters`、`SamplerParameters`、`BorderColorForm`、`VertexAttribute`、`VertexBufferBindingPoint`),它不 include `MG_State/GLState` 任何东西
|
||||
- `docs/Disaggregated/ROADMAP.md:16` — P0.5 row, 6–9 天, acceptance: 全套测试逐名不变(纯搬移);两条闭包断言绿且人为加回一个 `MG_State` include 能变红;`nm`/`.text` 变化可逐符号归因. Blocking prerequisite for **P1 and P7**.
|
||||
|
||||
Note the doc list **does not** include `DynamicBackendParameters`, but `MGPipeTypes.h:140-145` says the caps block *does* move ("until P0.5 moves the caps block into MGPipeValueTypes.h with fixed-width members"). That contradiction must be resolved by the implementers — see §7.4.
|
||||
|
||||
---
|
||||
|
||||
## 1. Current definition of each type
|
||||
|
||||
### 1.1 `MobileGL::PixelStoreParameters`
|
||||
- **Definition**: `MobileGL/MG_State/GLState/RenderState/RenderState.h:191-200`. Namespace `MobileGL` (not `MG_State::GLState`).
|
||||
- Members (all fixed-width, no pointer, no `SizeT`):
|
||||
```
|
||||
Bool SwapBytes = false; Bool LSBFirst = false;
|
||||
Int RowLength = 0; Int ImageHeight = 0; Int SkipPixels = 0;
|
||||
Int SkipRows = 0; Int SkipImages = 0; Int Alignment = 4;
|
||||
```
|
||||
- Dependencies: `Bool` = `bool` (`MobileGL/MG_Util/Types.h:33`), `Int` = `Int32` = `int32_t` (`MG_Util/Types.h:27,29`). Nothing else.
|
||||
- **Size asserted at 28** by `MobileGL/MG_Pipe/MGPipeTypes.h:494` (`sizeof(MGPPixelPackState) == 28`, and `MGPPixelPackState` is exactly `{ PixelStoreParameters Pack; }`, `MGPipeTypes.h:487-489`). Comment at `:491-493` states the layout is "two Bools, two bytes of padding, six Ints".
|
||||
- **Trivially copyable**: yes — asserted at `MGPipeTypes.h:490` via `MGPPixelPackState`.
|
||||
|
||||
### 1.2 `MobileGL::PerBufferBlendState`
|
||||
- **Definition**: `MG_State/GLState/RenderState/RenderState.h:202-210`.
|
||||
- Members: `Bool Enabled`; `BlendFactor SrcFactorRGB/DstFactorRGB/SrcFactorAlpha/DstFactorAlpha`; `BlendEquation ColorEquation/AlphaEquation`.
|
||||
- Enum deps: `BlendFactor` (`RenderState.h:15-38`, 18 enumerators incl. the four dual-source `Src1*`, plus `BlendFactorCount`, `Unknown = -1`), `BlendEquation` (`RenderState.h:40-48`). Both are plain `enum class` (underlying `int`), so 28 bytes with 3 pad bytes after `Enabled`.
|
||||
|
||||
### 1.3 `MobileGL::StencilFaceState`
|
||||
- **Definition**: `RenderState.h:212-220`.
|
||||
- Members: `DepthTestFunc Func`, `Int Ref`, `Uint32 ValueMask`, `Uint32 WriteMask`, `StencilOperation FailOp/PassDepthFailOp/PassDepthPassOp`.
|
||||
- Enum deps: `DepthTestFunc` (`RenderState.h:71-82`), `StencilOperation` (`RenderState.h:84-95`).
|
||||
|
||||
### 1.4 `MobileGL::RenderStateParameters` — the big one
|
||||
- **Definition**: `MG_State/GLState/RenderState/RenderState.h:222-370` (149 lines, heavily commented; the comments are load-bearing — several record CTS failures and must move with the struct).
|
||||
- **Constant it owns**: `static constexpr Uint MAX_VIEWPORTS = 16;` at `RenderState.h:227`. 74 references tree-wide across 17 files (`MG_Backend/DirectGLES/{BackendObject_DirectGLES,DirectGLES,Managers}.cpp`, `MG_Backend/DirectVulkan/{BackendObject_DirectVulkan,Renderer/VulkanRenderer.cpp,Renderer/VulkanRenderer.h}`, `MG_Impl/GLImpl/{Getter/GL_Getter,RenderState/GL_RenderState}.cpp`, `MG_IntegrationTest/Scenarios/{AdvertisedLimits,ViewportArray}Scenario.cpp`, `MG_State/GLState/RenderState/RenderState.{h,cpp}`, `MG_Test/Backend/DirectGLES/ViewportIndexRoutingTest.cpp`, `MG_Test/BackendLoader/BackendLoaderTest.cpp`, `MG_Test/State/RenderStateTest.cpp`, `MG_Util/BackendLoaders/OpenGL/Loader.cpp`, `MG_Util/Converters/GLToStr/GLEnumConverter.cpp`). Since it is a *member* of the struct, it moves with it for free — spelling stays `RenderStateParameters::MAX_VIEWPORTS`.
|
||||
- **External constant it depends on**: `MG_State::GLState::FramebufferObject::MAX_DRAW_BUFFERS` (`MG_State/GLState/FramebufferState/FramebufferObject.h:106`, `static constexpr Uint MAX_DRAW_BUFFERS = 8;`), used at `RenderState.h:263` (`Array<PerBufferBlendState, ...MAX_DRAW_BUFFERS> BlendStates`) and `RenderState.h:273` (`Array<BoolVec4, ...MAX_DRAW_BUFFERS> ColorMasks`). **This single reference is what drags the whole `FramebufferObject.h` subtree into `RenderState.h`** — see §2. 80 references tree-wide across 24 files.
|
||||
- Member list in declaration order (offsets matter — see §4.1):
|
||||
| # | member | type | notes |
|
||||
|---|---|---|---|
|
||||
| 1 | `Viewports` | `Array<FloatVec4, 16>` | 256 B, offset 0 |
|
||||
| 2 | `LineWidth`, `PointSize` | `Float` ×2 | |
|
||||
| 3 | `PatchVertices` | `Uint` | |
|
||||
| 4 | `PatchDefaultOuterLevel` | `FloatVec4` | hashed bitwise by Magma |
|
||||
| 5 | `PatchDefaultInnerLevel` | `FloatVec2` | |
|
||||
| 6 | `PolygonOffsetFactor/Units/Clamp` | `Float` ×3 | |
|
||||
| 7 | `ClipOrigin`, `ClipDepthMode` | `GLenum` ×2 | defaults `GL_LOWER_LEFT` / `GL_NEGATIVE_ONE_TO_ONE` |
|
||||
| 8 | `BlendStates` | `Array<PerBufferBlendState, MAX_DRAW_BUFFERS>` | **Espryt span boundary: `offsetof(...,BlendStates)`** |
|
||||
| 9 | `LogicOp` | `LogicOperation` | **Espryt span boundary: `offsetof(...,LogicOp)`** |
|
||||
| 10 | `DepthTestEnabled`, `DepthFunc`, `DepthMask` | | |
|
||||
| 11 | `ColorMasks` | `Array<BoolVec4, MAX_DRAW_BUFFERS>` | |
|
||||
| 12 | `ClearColor`, `ClearDepth`, `ClearStencil`, `BlendColor` | | |
|
||||
| 13 | `DepthRanges` | `Array<FloatVec2, 16>` | |
|
||||
| 14 | `SampleCoverageValue/Invert`, `SampleMaskValue`, `MinSampleShadingValue` | | |
|
||||
| 15 | `StencilStates` | `Array<StencilFaceState, 2>` | [0]=Front, [1]=Back |
|
||||
| 16 | `CullFaceEnabled`, `CullFaceModeSetting`, `FrontFaceModeSetting`, `ProvokingVertexModeSetting` | | |
|
||||
| 17 | 4× hint `GLenum` (`LineSmoothHint`, `PolygonSmoothHint`, `TextureCompressionHint`, `FragmentShaderDerivativeHint`) | | |
|
||||
| 18 | `PointFadeThresholdSize`, `PointSpriteCoordOrigin` | | |
|
||||
| 19 | `ClampReadColor` | `GLenum` | |
|
||||
| 20 | `PolygonModeFront/Back` | `GLenum` ×2 | |
|
||||
| 21 | `PrimitiveRestartIndex` | `Uint32` | |
|
||||
| 22 | 20 capability `Bool`s (`ColorLogicOpEnabled` … `ProgramPointSizeEnabled`) | `RenderState.h:325-344` | |
|
||||
| 23 | `ScissorTestEnabledMask` | `Uint32` | 16 bits, one per viewport |
|
||||
| 24 | `ScissorBoxes` | `Array<IntVec4, 16>` | |
|
||||
| 25 | `ScissorBoxWrittenMask`, `ClipDistanceEnabledMask` | `Uint32` ×2 | comments at `:352-369` explicitly say they are placed *after* `LogicOp` so Espryt's tail-span memcmp sees them |
|
||||
- **Enums it depends on**, all defined in `RenderState.h` above the struct, all `enum class` with an `Unknown = -1` and a `...Count` sentinel:
|
||||
`BlendFactor` `:15-38` · `BlendEquation` `:40-48` · `LogicOperation` `:50-69` · `DepthTestFunc` `:71-82` · `StencilOperation` `:84-95` · `StencilFace` `:97-102` · `PixelStoreParam` `:104-127` · `CullFaceMode` `:129-135` · `FrontFaceMode` `:137-142` · `ProvokingVertexMode` `:144-149` · `CapabilityInput` `:151-189`.
|
||||
(`StencilFace`, `PixelStoreParam` and `CapabilityInput` are *not* members of any value struct — they are the setter-API vocabulary of `class RenderState` and of the four converter headers. See §7.3 for whether they move.)
|
||||
- **Vector types**: `FloatVec2/FloatVec4/IntVec4/BoolVec4` from `MG_Util/Math/VectorTypes.h:213-224`, all `Vec2/Vec3/Vec4<T> : VecBase<...>` (`VectorTypes.h:16-92, 99-212`). `VecBase` has a user-provided default ctor and initializer-list ctor but **implicit copy ctor/assign/dtor**, so `is_trivially_copyable_v` is true while `is_trivially_default_constructible_v` is false. `GL_*` enum constants come from the GL headers pulled by `<Includes.h>`.
|
||||
- **Trivially copyable**: yes — asserted in the backend, `MG_Backend/DirectGLES/DirectGLES.cpp:2068-2069`.
|
||||
- **Size**: not directly asserted anywhere. It is pinned *indirectly* by `#define MGL_RESIDUAL_BLOCK_SIZE 1248` + `static_assert(sizeof(ResidualValueBlock) == MGL_RESIDUAL_BLOCK_SIZE)` (`MGPipeTypes.h:535-538`). Working backwards through `ResidualValueBlock`'s layout (`MGPipeTypes.h:515-524`: `RenderStateParameters` + `PixelStoreParameters`(28) + `Uint64` + `Uint32`+`Uint32` + `Float[4]` + `Float[2]` + `Uint32[2]`, block alignment 8) gives **`sizeof(RenderStateParameters) == 1168`** on the LP64/LLP64 targets — *arithmetic inference from the assertion, not a measured value; verify with a compile before relying on it.*
|
||||
- Also asserted: `MG_Test/Pipe/PipeCatalogueTest.cpp:113` — `EXPECT_GE(sizeof(ResidualValueBlock), sizeof(RenderStateParameters) + sizeof(PixelStoreParameters))`, and `:110-111` re-assert `MGL_RESIDUAL_BLOCK_SIZE` at both compile and run time.
|
||||
|
||||
### 1.5 `MobileGL::SamplerParameters`
|
||||
- **Definition**: `MG_State/GLState/SamplerState/SamplerObject.h:72-97`. Namespace `MobileGL`.
|
||||
- Members: `SamplerWrapMode wrapS/wrapT/wrapR`, `SamplerFilterMode minFilter/magFilter`, `SamplerMipmapMode mipmapMode`, `Float minLod(-1000)/maxLod(1000)/lodBias/maxAnisotropy`, `SamplerCompareFunc compareFunc`, `SamplerCompareMode compareMode`, `FloatVec4 borderColor`, `IntVec4 borderColorI`, `UintVec4 borderColorUI`, `BorderColorForm borderColorForm`.
|
||||
- Enum deps, all in the same header: `SamplerFilterMode` `:14-19` · `SamplerMipmapMode` `:21-27` · `SamplerWrapMode` `:29-36` · `SamplerCompareMode` `:38-43` · `SamplerCompareFunc` `:45-55` · `BorderColorForm : Uint8` `:66-70`.
|
||||
- Trivially copyable: yes (all members are scalars/enums/`Vec4`), but **no static_assert exists today** anywhere in the tree.
|
||||
- **No size assertion exists.** `MGPipeTypes.h:255-263` carries it as an opaque blob (`MGPSamplerDesc { MGPipeHandle Cso; MGPBlobRef Parameters; }`, `MGP_ASSERT_POD(MGPSamplerDesc, 32)`) and the comment says "Carried as a blob until P0.5 gives it a value header."
|
||||
|
||||
### 1.6 `MobileGL::MG_State::GLState::VertexAttribute` — **NOT a POD**
|
||||
- **Definition**: `MG_State/GLState/VertexArrayState/VertexArrayObject.h:17-51`. Note the *deeper namespace*: `MobileGL::MG_State::GLState`, unlike all the others which sit directly in `MobileGL`.
|
||||
- Members: `Bool Enabled`, `int Size`, `DataType Type`, `Bool Normalized`, `int Stride` (resolved, 0 is meaningful — see the CTS note at `:19-28`), `SizeT Offset`, `Bool IsInteger`, `Bool IsLong`, `Bool IsBgra`, `Uint Divisor`, **`SharedPtr<BufferObject> Buffer`**, `int LegacyStride`, `SizeT LegacyPointer`.
|
||||
- **BLOCKER**: `SharedPtr<BufferObject> Buffer` (`VertexArrayObject.h:39`) makes this **not trivially copyable** and forces `#include "../BufferState/BufferObject.h"` (`VertexArrayObject.h:11`). It also uses `SizeT`, which `MGPipeTypes.h:140-143` explicitly calls out as ABI-dependent and unacceptable in a wire type.
|
||||
- Enum dep: `DataType` (`MG_Util/Types.h:129-145`) — free, `Types.h` is already inside `<Includes.h>`.
|
||||
- `SharedPtr` = `std::shared_ptr` (`MG_Util/Types.h:41-42`); `SizeT` = `std::size_t` (`Types.h:55`); `Array` = `std::array` (`Types.h:56-57`).
|
||||
|
||||
### 1.7 `MobileGL::MG_State::GLState::VertexBufferBindingPoint` — **NOT a POD**
|
||||
- **Definition**: `VertexArrayObject.h:58-64`. Members: `SharedPtr<BufferObject> Buffer`, `SizeT Offset`, `int Stride = 16` (initial VERTEX_BINDING_STRIDE is 16, not 0), `Uint Divisor`. Same blocker.
|
||||
- Neighbour worth knowing: `VertexAttributeVersion` (`VertexArrayObject.h:66-70`, three `Uint16`) is consumed by `MG_Backend/DirectGLES/Managers.h:788`; it is trivially copyable and is a candidate to ride along.
|
||||
- The `MAX_VERTEX_ATTRIBS = 32` / `MAX_VERTEX_ATTRIB_BINDINGS = 32` constants live on `class VertexArrayObject` (`VertexArrayObject.h:76-77`), not on the value struct — 98 references tree-wide. `MGPipeTypes.h:243-245` speaks of "the resolved `VertexAttribute[32]`", so the header needs its own copy of the 32.
|
||||
|
||||
### 1.8 `MobileGL::MG_Backend::DynamicBackendParameters`
|
||||
- **Definition**: `MG_Backend/BackendObject.h:316-549` (233 lines). Namespace `MobileGL::MG_Backend`.
|
||||
- ~90 scalars. **Non-fixed-width members that block a wire type**: `SizeT UniformBufferOffsetAlignment` `:317`, `SizeT ShaderStorageBufferOffsetAlignment` `:322`, `SizeT MaxShaderStorageBlockSize` `:545`.
|
||||
- **It is not a pure aggregate**: it has two member functions — `static constexpr Uint32 PerLayerFramebufferAttachmentBit(TextureTarget)` `:487-492` and `Bool SupportsPerLayerFramebufferAttachment(TextureTarget) const` `:494-497`. Both take `TextureTarget`, which is why `BackendObject.h:11` includes `MG_State/GLState/TextureState/TextureEnum.h` — **an MG_Backend header reaching into MG_State**, and the only MG_State include in that file.
|
||||
- Also carries `GpuVendorKind GpuVendor` (enum defined `BackendObject.h:303-315`), `Int MaxComputeWorkGroupCount[3]` / `MaxComputeWorkGroupSize[3]` `:392-393` (the six indexed limits that MGPCaps exists to carry), two `GLenum` provoking-vertex fields `:445-446`.
|
||||
- Trivially copyable: yes — asserted indirectly at `MGPipeTypes.h:139` (`is_trivially_copyable_v<MGPCaps>`, and `MGPCaps` embeds it by value at `:131`).
|
||||
- Size asserted *compositionally*, not literally: `MGPipeTypes.h:144-145`, `sizeof(MGPCaps) == sizeof(DynamicBackendParameters) + 8 + 24 + 24`, with the comment at `:140-143` explaining why a literal is impossible today ("`DynamicBackendParameters` still carries `SizeT` fields, so its literal size is ABI-dependent until P0.5 moves the caps block into `MGPipeValueTypes.h` with fixed-width members").
|
||||
|
||||
---
|
||||
|
||||
## 2. Transitive include closure of each host header (what a naive move drags along)
|
||||
|
||||
Computed by walking `#include` lines from each header, resolving relative-then-root, over the real tree.
|
||||
|
||||
**Baseline — `MobileGL/Includes.h` (the umbrella every MG_Pipe header already pulls, `Includes.h:1-149`):**
|
||||
- Project headers reached (5): `Defines.h`, `MG_Util/Debug/Log.h`, `MG_Util/GLExtensions.h`, `MG_Util/PlatformStubs.h`, `MG_Util/Types.h`.
|
||||
- External headers reached (56): the whole libstdc++ set (`<bit> <map> <array> <ctime> <mutex> <queue> <regex> <atomic> <bitset> <cctype> <chrono> <cstdio> <format> <memory> <random> <string> <thread> <vector> <cassert> <climits> <cstdlib> <cstdarg> <cstring> <numeric> <expected> <iostream> <optional> <algorithm> <stdexcept> <functional> <string_view> <unordered_map>` `<stacktrace>`), plus `ska/flat_hash_map.hpp` (`:53`), `xxhash.h` (`:56`), **`spirv_cross/spirv_cross_c.h` (`:59`)**, `EGL/egl.h` `GL/gl.h` `GL/glcorearb.h` `GL/glext.h` `GLES3/gl32.h` (`:65-76`), **`glslang/Include/Types.h`, `glslang/Public/ShaderLang.h`, `glslang/SPIRV/GlslangToSpv.h`, `glslang/Include/intermediate.h`, `glslang/MachineIndependent/localintermediate.h` (`:80-84`)**, `vulkan/vulkan.h` (`:130`), `tracy/Tracy.hpp` (`:141`), plus platform (`dlfcn.h pthread.h unistd.h android/log.h android/native_window.h windows.h processthreadsapi.h signal.h`).
|
||||
|
||||
> **Critical framing for the brief**: `<Includes.h>` *already* brings glslang, SPIRV-Cross and Vulkan into every MG_Pipe header. So `MGPipeValueTypes.h` cannot be "glslang-free" while it includes `<Includes.h>`, and P7's `nm -D | grep glslang` criterion is about the *linked server binary*, not this header's textual closure. The purity gate that P0.5 actually arms is **gate A: no `MG_State/GLState` include reachable from `MG_Pipe/`**.
|
||||
|
||||
**Delta each host header adds on top of `Includes.h`:**
|
||||
|
||||
| host header | extra project headers dragged in |
|
||||
|---|---|
|
||||
| `MG_State/GLState/RenderState/RenderState.h` | **10**: `MG_Util/Math/VectorTypes.h`, `MG_State/GLState/FramebufferState/FramebufferObject.h`, `MG_State/GLState/RenderbufferState/RenderbufferObject.h`, `MG_State/GLState/SamplerState/SamplerObject.h`, `MG_State/GLState/TextureState/TextureObject.h`, `MG_State/GLState/TextureState/TextureEnum.h`, `MG_State/GLState/TextureState/TextureTypes.h`, `MG_State/GLState/TextureState/MipmapStorage.h`, `MG_State/GLState/TextureState/MipmapUploadTargetArray.h` |
|
||||
| `MG_State/GLState/SamplerState/SamplerObject.h` | **1**: `MG_Util/Math/VectorTypes.h` |
|
||||
| `MG_State/GLState/VertexArrayState/VertexArrayObject.h` | **3**: `MG_State/GLState/BufferState/BufferObject.h`, `MG_State/GLState/BufferState/PipeResource.h`, `MG_Util/Math/VectorTypes.h` (+`<new>` externally) |
|
||||
| `MG_Backend/BackendObject.h` | **1**: `MG_State/GLState/TextureState/TextureEnum.h` |
|
||||
|
||||
Chain that produces `RenderState.h`'s big closure: `RenderState.h:12` → `FramebufferState/FramebufferObject.h:12,13` → `TextureState/TextureObject.h` and `RenderbufferState/RenderbufferObject.h` → `SamplerState/SamplerObject.h`, `TextureTypes.h`, `MipmapStorage.h`, `MipmapUploadTargetArray.h`, `TextureEnum.h`. **The only reason `RenderState.h` needs `FramebufferObject.h` at all is the two `MAX_DRAW_BUFFERS` uses at `:263` and `:273`.**
|
||||
|
||||
No `spirv-cross`, `glslang` or other third-party header is reached by any of these four *beyond what `Includes.h` already pulls*. There is no `SPIRV-Reflect`/`SpvcSession`/`ShaderObject` in these closures (that is the sibling `ProgramArtifacts.h` extraction, a different scout's problem).
|
||||
|
||||
---
|
||||
|
||||
## 3. Includers of each host header
|
||||
|
||||
Whole-tree counts (`*.h *.cpp *.hpp *.inc`, textual `#include` match):
|
||||
|
||||
### `MG_State/GLState/RenderState/RenderState.h` — 8 includers
|
||||
| file | in |
|
||||
|---|---|
|
||||
| `MobileGL/MG_Pipe/MGPipeTypes.h:33` | **MG_Pipe** |
|
||||
| `MobileGL/MG_State/GLState/Core.h:15` | MG_State (the umbrella; 73 files include `GLState/Core.h`) |
|
||||
| `MobileGL/MG_Test/State/RenderStateTest.cpp` | test |
|
||||
| `MobileGL/MG_Util/Converters/GLToMG/RenderStateEnumConverter.h:11` | MG_Util |
|
||||
| `MobileGL/MG_Util/Converters/MGToGL/RenderStateEnumConverter.h:11` | MG_Util |
|
||||
| `MobileGL/MG_Util/Converters/MGToStr/RenderStateEnumConverter.h:11` | MG_Util |
|
||||
| `MobileGL/MG_Util/Converters/MGToVk/RenderStateEnumConverter.h:11` | MG_Util |
|
||||
| `MobileGL/MG_Util/Texture/PixelStoreProcessor.h:11` | MG_Util (wants `PixelStoreParameters` only) |
|
||||
- **MG_Backend includers: none directly** — both backends reach `RenderStateParameters` through `MG_State/GLState/Core.h`.
|
||||
|
||||
### `MG_State/GLState/SamplerState/SamplerObject.h` — 7 includers
|
||||
| file | in |
|
||||
|---|---|
|
||||
| `MobileGL/MG_Backend/DirectGLES/DirectGLES.h` | **MG_Backend** |
|
||||
| `MobileGL/MG_Backend/DirectGLES/Managers.h` | **MG_Backend** |
|
||||
| `MobileGL/MG_Backend/DirectVulkan/Renderer/VkSamplerManager.h:14` | **MG_Backend** |
|
||||
| `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp` | **MG_Backend** |
|
||||
| `MobileGL/MG_Impl/GLImpl/Sampler/Validators.h` | MG_Impl |
|
||||
| `MobileGL/MG_State/GLState/TextureState/TextureObject.h` | MG_State |
|
||||
| `MobileGL/MG_State/GLState/TextureState/TextureUnit.h` | MG_State |
|
||||
- MG_Pipe includers: none directly (reached transitively via `RenderState.h`).
|
||||
|
||||
### `MG_State/GLState/VertexArrayState/VertexArrayObject.h` — 5 includers
|
||||
| file | in |
|
||||
|---|---|
|
||||
| `MobileGL/MG_Backend/DirectVulkan/Renderer/VertexInputStateFactory.h` | **MG_Backend** |
|
||||
| `MobileGL/MG_Impl/GLImpl/VertexArray/Validators.h` | MG_Impl |
|
||||
| `MobileGL/MG_State/GLState/ProgramState/ProgramLinkTask.cpp` | MG_State |
|
||||
| `MobileGL/MG_Test/State/ObjectLifetimeIdTest.cpp` | test |
|
||||
| `MobileGL/MG_Util/SelfTest/DriverPost.cpp` | MG_Util |
|
||||
- MG_Pipe includers: none.
|
||||
|
||||
### `MG_Backend/BackendObject.h` — 9 includers
|
||||
| file | in |
|
||||
|---|---|
|
||||
| `MobileGL/MG_Backend/DirectGLES/BackendObject_DirectGLES.cpp` | **MG_Backend** |
|
||||
| `MobileGL/MG_Backend/DirectGLES/DirectGLES.h` | **MG_Backend** |
|
||||
| `MobileGL/MG_Backend/DirectVulkan/BackendObject_DirectVulkan.cpp` | **MG_Backend** |
|
||||
| `MobileGL/MG_Backend/DirectVulkan/DirectVulkan.h` | **MG_Backend** |
|
||||
| `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.h` | **MG_Backend** |
|
||||
| `MobileGL/MG_IntegrationTest/Harness/BackendCapsPeek.cpp` | itest |
|
||||
| `MobileGL/MG_Pipe/MGPipeTypes.h:32` | **MG_Pipe** |
|
||||
| `MobileGL/MG_Util/SelfTest/DriverPost.h` | MG_Util |
|
||||
| `MobileGL/MG_Util/ShaderTranspiler/CompileEnv.h` | MG_Util |
|
||||
|
||||
### MG_Pipe's own headers — blast radius is tiny
|
||||
- `MG_Pipe/MGPipe.h` is included by exactly **2** files: itself and `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp:18`.
|
||||
- `MG_Pipe/MGPipeTypes.h` is included by `MGPipe.h:15`, `MGPipeCallbacks.h:13`, and itself.
|
||||
- No `MG_Backend`, `MG_Impl`, `MG_State` or `MG_Remote` file includes any MG_Pipe header yet. **A change confined to MG_Pipe therefore cannot break the backends** — the risk is entirely in what the extraction does to the *MG_State* headers the backends do read.
|
||||
|
||||
---
|
||||
|
||||
## 4. How the two backends consume these types
|
||||
|
||||
### 4.1 Espryt (DirectGLES) — the three-segment memcmp, `MG_Backend/DirectGLES/DirectGLES.cpp`
|
||||
- Shadow: `static RenderStateParameters g_syncedRenderStateParameters;` at `:1984`, guarded by `g_hasSyncedRenderState`; `SyncRenderState(Bool forColorClear)` begins `:2022`; called from `:2994` and `:4121`.
|
||||
- Rationale comment `:2057-2067`; then the assertions and the spans:
|
||||
```
|
||||
:2068 static_assert(std::is_trivially_copyable_v<RenderStateParameters>,
|
||||
:2069 "span memcmp/memcpy below treats the parameter block as raw bytes");
|
||||
:2070 constexpr SizeT kBlendSpanBegin = offsetof(RenderStateParameters, BlendStates);
|
||||
:2071 constexpr SizeT kBlendSpanEnd = offsetof(RenderStateParameters, LogicOp);
|
||||
```
|
||||
Three spans (`:2074-2081`): head `[0, kBlendSpanBegin)`, blend `[kBlendSpanBegin, kBlendSpanEnd)`, tail `[kBlendSpanEnd, sizeof(RenderStateParameters))`.
|
||||
- Write-back at `:2660-2683`: three conditional `memcpy`s over the same three spans, plus the dual-source-declined patch at `:2676-2678` which re-writes `g_syncedRenderStateParameters.BlendStates[i]` for declined draw buffers.
|
||||
- **Hard constraints this places on any move**: (a) `offsetof` requires standard-layout — the struct must stay a plain aggregate with a single access specifier and no virtual/base; (b) `BlendStates` must stay the first member of the "blend" region and `LogicOp` the first member after it — i.e. **member order is load-bearing and must not be reordered by the move**; (c) the capability `Bool`s, `ScissorTestEnabledMask`, `ScissorBoxes`, `ScissorBoxWrittenMask` and `ClipDistanceEnabledMask` must stay *after* `LogicOp` (the comments at `:352-369` of `RenderState.h` say so explicitly, citing `KHR-GL43.viewport_array.scissor_zero_dimension`); (d) padding is *deliberately copied*, so any change that alters padding changes behaviour subtly (it only costs an extra field-wise pass, but it invalidates the "steady state is exact" claim at `DirectGLES.cpp:2062-2065`).
|
||||
- ~51 further per-field reads of `g_syncedRenderStateParameters` in the same function (`:2101` `SYNC_CAPABILITY` macro, `:2132`, `:2149`, `:2179-2180`, `:2196`, `:2411-2417`, `:2425`, `:2454`, `:2507`, `:2516-2537`, `:2591-2649`).
|
||||
- `SamplerParameters`: Espryt keeps two per-object shadows `SamplerParameters m_cacheSamplerParameters;` at `MG_Backend/DirectGLES/Managers.h:1087` and `:1825`, diffed **field by field** (`Managers.cpp:4778-4850+`, macro at `:4793-4796`), reset with `= SamplerParameters{}` at `Managers.cpp:2911`, and read in `ResolveBackendMinFilter(const SamplerParameters&, ...)` at `Managers.cpp:90`. **No memcmp, no offsetof, no sizeof.**
|
||||
- `VertexAttribute`: consumed by const-ref only — `Managers.h:744`, `Managers.cpp:2199, 2246, 2256, 2627`. `Managers.h:788` holds `Array<VertexAttributeVersion, VertexArrayObject::MAX_VERTEX_ATTRIBS>`.
|
||||
- `PixelStoreParameters`: used in `DirectGLES.cpp` and `MG_Backend/DirectGLES/Utils.cpp`, by value/field, no layout assumption.
|
||||
|
||||
### 4.2 Magma (DirectVulkan) — `MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp`
|
||||
- `Uint64 VulkanRenderer::ComputePipelineStateHash(Uint32 colorAttachmentCount, VkSampleCountFlagBits)` at `:4820-4900+`; declared `VulkanRenderer.h:849-850`. Callers at `:4989` and `:6338`.
|
||||
- It takes **one bulk `const RenderStateParameters&`** (`:4828`, comment `:4822-4827` explains it replaces ~17 accessor calls) and then reads **named fields only**:
|
||||
`CullFaceEnabled, DepthTestEnabled, PolygonOffsetFillEnabled, RasterizerDiscardEnabled, ColorLogicOpEnabled, StencilTestEnabled, PrimitiveRestartEnabled, PrimitiveRestartFixedIndexEnabled, DepthMask, SampleShadingEnabled` (`:4830-4839`), `MinSampleShadingValue` (bit-cast, `:4855`), `SampleMaskValue` (via `ResolveEffectiveSampleMask`, `:4817`), `PatchVertices` (`:4867`), `PatchDefaultOuterLevel[0..3]` / `PatchDefaultInnerLevel[0..1]` (bit-cast, `:4874-4881`), `PolygonModeFront`, `CullFaceModeSetting`, `DepthFunc`, `LogicOp` (`:4883-4886`), `StencilStates[]` (`:4889-4895`, "[0] is Front, [1] is Back"), `BlendStates[i]` and `ColorMasks[...]` (`:4896-4900+`), with `MOBILEGL_ASSERT(colorAttachmentCount <= p.BlendStates.size(), ...)` at `:4892-4894`.
|
||||
- Memo key `PipelineMemoEntry` (`VulkanRenderer.h:818-837`) stores only the resulting `Uint64 pipelineStateHash`; `kPipelineMemoSize = 8` at `:838`.
|
||||
- **Magma makes NO `sizeof`, `offsetof`, or memcmp assumption on any of these types.** A tree-wide grep for `sizeof(RenderStateParameters)|offsetof(RenderStateParameters|sizeof(PixelStoreParameters)|sizeof(SamplerParameters)|sizeof(VertexAttribute)` finds hits only in `DirectGLES.cpp:2070,2071,2081,2682`, `MGPipeTypes.h:492` (comment) and `MG_Test/Pipe/PipeCatalogueTest.cpp:113`.
|
||||
- `SamplerParameters` on Magma: `VkSamplerManager` (`MG_Backend/DirectVulkan/Renderer/VkSamplerManager.h`) never touches the struct — it takes `const MG_State::GLState::SamplerObject&` (`:45, 89, 95, 101`) and builds a `Uint64 BuildSamplerKey(...)` (`:89`) plus a `ResolvedBorderColor` (`:71-76`). It only includes `SamplerObject.h` at `:14`. So the *class*, not the value struct, is Magma's sampler input.
|
||||
- `VertexAttribute` on Magma: `VertexInputStateFactory` (`.h` includes `VertexArrayObject.h`); `.cpp:124, 183, 371` read fields and `GetDynamicParameters().SupportsFloat64VertexAttributes`.
|
||||
|
||||
### 4.3 `PipeStats` and MGPipe size assertions mentioning these types
|
||||
- No `PipeStats` reference to any of the four value types (grep of `MG_Util/PipeStats*` is empty). `PipeStats` only appears in `SyncRenderState`'s gate accounting (`DirectGLES.cpp:2040-2051`, `Gate::EsprytRenderState`, `CallClass::AccessorCalls`).
|
||||
- MGPipe assertions that transitively pin these types:
|
||||
- `MGPipeTypes.h:139` `is_trivially_copyable_v<MGPCaps>` → pins `DynamicBackendParameters`.
|
||||
- `MGPipeTypes.h:144-145` `sizeof(MGPCaps) == sizeof(DynamicBackendParameters) + 8 + 24 + 24`.
|
||||
- `MGPipeTypes.h:490` `is_trivially_copyable_v<MGPPixelPackState>` and `:494-495` `sizeof(MGPPixelPackState) == 28` → pins `PixelStoreParameters`.
|
||||
- `MGPipeTypes.h:525` `is_trivially_copyable_v<ResidualValueBlock>` and `:535-538` `sizeof(...) == MGL_RESIDUAL_BLOCK_SIZE` (1248) → pins `RenderStateParameters` + `PixelStoreParameters` jointly.
|
||||
- `generated/PipeWire.inc:449-455` (`MGPWireRec_SetPixelPackState`) and `:481-487` (`MGPWireRec_SetResidualValueState`) re-assert 8-byte-aligned record sizes derived from those payloads; `:121-127` does the same for `MGPWireRec_GetCaps`.
|
||||
- `MG_Test/Pipe/PipeCatalogueTest.cpp:110-113, 120-125`.
|
||||
- `generated/PipeVerify.inc:232-238` — the memcmp fallback in `MGPipeFieldEqual`, whose comment names exactly the P0.5 types:
|
||||
> "Only reached by the payload members that are still MG_State / MG_Backend value structs (`RenderStateParameters`, `PixelStoreParameters`, `DynamicBackendParameters`) and by `MGHostSpan`. Those are exactly the types P0.5 moves into `MGPipeValueTypes.h`, at which point they get field lists of their own and this branch stops being reachable from any payload."
|
||||
The generator source of that text is `scripts/gen_pipe.py:413`.
|
||||
- `generated/PipeSpanTable.inc:34-67` — `kMGPipePipelineStateMembers[24]` names `RenderStateParameters` members **by string**, taken from what `ComputePipelineStateHash` hashes; `kMGPipePipelineChunks[]` / `kMGPipeDynamicChunks[]` are `extern` and will be filled by `MG_Pipe/MGPipeRenderStateSpans.cpp` in P2 using `offsetof`. **Renaming any of those 24 members breaks P2 silently** (the strings are only checked at P2 time).
|
||||
|
||||
---
|
||||
|
||||
## 5. Existing MG_Pipe header include lines
|
||||
|
||||
| file | include lines |
|
||||
|---|---|
|
||||
| `MG_Pipe/MGPipe.h` | `:10 #include <Includes.h>` · `:12 "MGPipeCallbacks.h"` · `:13 "MGPipeHandles.h"` · `:14 "MGPipeHostSpan.h"` · `:15 "MGPipeTypes.h"` · then in-namespace `.def`/`.inc` textual includes at `:65, 68, 77, 80, 83, 86, 89, 92` |
|
||||
| `MG_Pipe/MGPipeCallbacks.h` | `:10 <Includes.h>` · `:12 "MGPipeHandles.h"` · `:13 "MGPipeTypes.h"` |
|
||||
| `MG_Pipe/MGPipeHandles.h` | `:10 <Includes.h>` only |
|
||||
| `MG_Pipe/MGPipeHostSpan.h` | `:10 <Includes.h>` only |
|
||||
| `MG_Pipe/MGPipeTypes.h` | `:10 <Includes.h>` · `:12 "MGPipeHandles.h"` · `:13 "MGPipeHostSpan.h"` · **`:32 <MG_Backend/BackendObject.h>`** · **`:33 <MG_State/GLState/RenderState/RenderState.h>`** (the two P0.5 debts) |
|
||||
| `MG_Pipe/generated/PipeVerify.inc` | `:25 "../PipeFields.def"` |
|
||||
|
||||
`MGPipeTypes.h:35-40` opens `namespace MobileGL::MG_Pipe` and pulls the three names in with `using`:
|
||||
```
|
||||
:36 using MG_Backend::DynamicBackendParameters;
|
||||
:39 using MobileGL::PixelStoreParameters;
|
||||
:40 using MobileGL::RenderStateParameters;
|
||||
```
|
||||
with the comment at `:37-38`: "Both live directly in namespace `MobileGL` today; P0.5 moves them into `MG_Pipe/MGPipeValueTypes.h`."
|
||||
|
||||
**What `<Includes.h>` brings**: see §2 baseline. Practically: `Bool/Int/Uint/Int32/Uint32/Int64/Uint64/Float/SizeT/String/Vector<T>/Array<T,N>/SharedPtr<T>/DataType/Range1D` (`MG_Util/Types.h`), `MOBILEGL_ASSERT` and the `MGLOG_*` macros (`MG_Util/Debug/Log.h`), all GL/GLES/EGL enums and `GLenum`, `vulkan.h`, glslang, SPIRV-Cross C API, ska, xxHash, and 30-odd libstdc++ headers. So `MGPipeValueTypes.h` needs **only** `<Includes.h>` plus `<MG_Util/Math/VectorTypes.h>` (which is *not* in the umbrella — verify: `Includes.h` does not include it; `RenderState.h:11`, `SamplerObject.h:11`, `VertexArrayObject.h` all include it explicitly).
|
||||
|
||||
**Build wiring**: `CMakeLists.txt:529-535` puts both `${CMAKE_SOURCE_DIR}/MobileGL` and `${CMAKE_SOURCE_DIR}/MobileGL/MG_Pipe` on the include path, so the new header is spellable as both `<MG_Pipe/MGPipeValueTypes.h>` and `<MGPipeValueTypes.h>`. `MobileGL/MG_Test/Pipe/CMakeLists.txt:8-15` repeats those two paths for `PipeCatalogueTest`. No new CMake entry is needed for a header-only addition; a future `MGPipeRenderStateSpans.cpp` (P2) would need one.
|
||||
|
||||
---
|
||||
|
||||
## 6. Proposed contents of `MobileGL/MG_Pipe/MGPipeValueTypes.h`
|
||||
|
||||
Header order below is dependency order; the file is one `namespace MobileGL { ... }` block with a nested `namespace MG_State::GLState { ... }` for the two vertex types (see §7.2 on why).
|
||||
|
||||
```
|
||||
// header banner (copy the 8-line LGPL block from MGPipeTypes.h:1-7)
|
||||
#pragma once
|
||||
#include <Includes.h>
|
||||
#include <MG_Util/Math/VectorTypes.h>
|
||||
// NOTHING from MG_State/GLState or MG_Backend. Purity gate A (plan section 10.3)
|
||||
// asserts that; adding one back must turn it red.
|
||||
|
||||
namespace MobileGL {
|
||||
// --- 1. shared constants -------------------------------------------------
|
||||
inline constexpr Uint kMGMaxDrawBuffers = 8; // canonical home of MAX_DRAW_BUFFERS
|
||||
inline constexpr Uint kMGMaxViewports = 16; // mirrored as RenderStateParameters::MAX_VIEWPORTS
|
||||
inline constexpr Uint kMGMaxVertexAttribs = 32;
|
||||
inline constexpr Uint kMGMaxVertexAttribBindings = 32;
|
||||
|
||||
// --- 2. render-state enums (verbatim from RenderState.h:15-189) ----------
|
||||
enum class BlendFactor { ... }; // RenderState.h:15-38
|
||||
enum class BlendEquation { ... }; // :40-48
|
||||
enum class LogicOperation { ... }; // :50-69
|
||||
enum class DepthTestFunc { ... }; // :71-82
|
||||
enum class StencilOperation { ... }; // :84-95
|
||||
enum class StencilFace { ... }; // :97-102 (see §7.3)
|
||||
enum class PixelStoreParam { ... }; // :104-127 (see §7.3)
|
||||
enum class CullFaceMode { ... }; // :129-135
|
||||
enum class FrontFaceMode { ... }; // :137-142
|
||||
enum class ProvokingVertexMode { ... }; // :144-149
|
||||
enum class CapabilityInput { ... }; // :151-189 (see §7.3)
|
||||
|
||||
// --- 3. render-state value structs (verbatim, MEMBER ORDER UNCHANGED) ----
|
||||
struct PixelStoreParameters { ... }; // RenderState.h:191-200
|
||||
struct PerBufferBlendState { ... }; // :202-210
|
||||
struct StencilFaceState { ... }; // :212-220
|
||||
struct RenderStateParameters { ... }; // :222-370, with :263 and :273 rewritten
|
||||
// to use kMGMaxDrawBuffers
|
||||
// --- 4. sampler enums + value struct (verbatim from SamplerObject.h) -----
|
||||
enum class SamplerFilterMode { ... }; // SamplerObject.h:14-19
|
||||
enum class SamplerMipmapMode { ... }; // :21-27
|
||||
enum class SamplerWrapMode { ... }; // :29-36
|
||||
enum class SamplerCompareMode{ ... }; // :38-43
|
||||
enum class SamplerCompareFunc{ ... }; // :45-55
|
||||
enum class BorderColorForm : Uint8 { Float, Int, Uint }; // :66-70
|
||||
struct SamplerParameters { ... }; // :72-97
|
||||
|
||||
namespace MG_State::GLState {
|
||||
// --- 5. vertex value structs -----------------------------------------
|
||||
// BufferObject is NOT visible here. See §7.1 for the three options; the
|
||||
// recommendation is a forward declaration + SharedPtr, which keeps the
|
||||
// move byte-for-byte but leaves the types non-POD, with the POD wire
|
||||
// shapes (MGPVertexAttributeWire / MGPVertexBindingWire) defined in
|
||||
// MGPipeTypes.h next to MGPVertexElements.
|
||||
class BufferObject; // fwd decl only
|
||||
struct VertexAttribute { ... }; // VertexArrayObject.h:17-51
|
||||
struct VertexBufferBindingPoint { ... };// :58-64
|
||||
struct VertexAttributeVersion { ... }; // :66-70 (trivially copyable; ride-along)
|
||||
}
|
||||
|
||||
// --- 6. new trip wires (none exist today for these) ----------------------
|
||||
static_assert(std::is_trivially_copyable_v<PixelStoreParameters>);
|
||||
static_assert(sizeof(PixelStoreParameters) == 28);
|
||||
static_assert(std::is_trivially_copyable_v<PerBufferBlendState>);
|
||||
static_assert(std::is_trivially_copyable_v<StencilFaceState>);
|
||||
static_assert(std::is_trivially_copyable_v<RenderStateParameters>);
|
||||
static_assert(std::is_standard_layout_v<RenderStateParameters>); // offsetof legality,
|
||||
// DirectGLES.cpp:2070-2071
|
||||
static_assert(offsetof(RenderStateParameters, BlendStates) < offsetof(RenderStateParameters, LogicOp));
|
||||
static_assert(std::is_trivially_copyable_v<SamplerParameters>);
|
||||
} // namespace MobileGL
|
||||
```
|
||||
|
||||
Whether `DynamicBackendParameters` joins this header is an open decision — see §7.4.
|
||||
|
||||
### What stays behind, as thin forwarding includes
|
||||
- **`MG_State/GLState/RenderState/RenderState.h`**: delete `:11 #include <MG_Util/Math/VectorTypes.h>` and `:12 #include <MG_State/GLState/FramebufferState/FramebufferObject.h>`; add `#include <MG_Pipe/MGPipeValueTypes.h>`. Delete lines `:14-370` (all enums + the four structs) and keep only `namespace MG_State::GLState { class RenderState {...}; }` at `:372-538`. Every existing spelling (`MobileGL::RenderStateParameters`, `MobileGL::BlendFactor`, …) is unchanged, so this is a pure move. **The `FramebufferObject.h` include disappearing is the single biggest win** — it removes 8 headers from the closure of a header 73 files reach through `Core.h`.
|
||||
- **`MG_State/GLState/SamplerState/SamplerObject.h`**: replace `:11 #include <MG_Util/Math/VectorTypes.h>` with `#include <MG_Pipe/MGPipeValueTypes.h>`; delete `:14-97`; keep `class SamplerObject` from `:99` on.
|
||||
- **`MG_State/GLState/VertexArrayState/VertexArrayObject.h`**: add `#include <MG_Pipe/MGPipeValueTypes.h>`; delete `:17-70`; keep `#include "../BufferState/BufferObject.h"` at `:11` (still needed by `class VertexArrayObject` and, for the `SharedPtr` members to be usable, by every TU that copies a `VertexAttribute`).
|
||||
- **`MG_State/GLState/FramebufferState/FramebufferObject.h:106`**: change `static constexpr Uint MAX_DRAW_BUFFERS = 8;` to `static constexpr Uint MAX_DRAW_BUFFERS = MobileGL::kMGMaxDrawBuffers;` (needs `#include <MG_Pipe/MGPipeValueTypes.h>` at the top, or leave the literal and add a `static_assert(MAX_DRAW_BUFFERS == kMGMaxDrawBuffers)` in a .cpp — the latter avoids a new MG_State→MG_Pipe include direction and is probably cleaner). All 80 existing `FramebufferObject::MAX_DRAW_BUFFERS` spellings keep working either way.
|
||||
- **`MG_Pipe/MGPipeTypes.h`**: delete `:32-33` (the two debt includes) and `:36-40` (the three `using`s), add `#include "MGPipeValueTypes.h"` plus `using MobileGL::PixelStoreParameters; using MobileGL::RenderStateParameters;` — or nothing at all if the payloads are respelled `MobileGL::RenderStateParameters`. Update the debt comment at `:24-33` to record that the gate is now armed. `:140-145` (the compositional `MGPCaps` assertion) becomes a literal only if `DynamicBackendParameters` also moves.
|
||||
- **`MG_Pipe/PipeFields.def`**: add `MGP_FIELDS_RenderStateParameters`, `MGP_FIELDS_PixelStoreParameters`, `MGP_FIELDS_PerBufferBlendState`, `MGP_FIELDS_StencilFaceState` (and `MGP_FIELDS_DynamicBackendParameters` if it moves), so `MGPipeFieldEqual`'s memcmp fallback (`generated/PipeVerify.inc:232-238`) stops being reachable from `ResidualValueBlock`/`MGPPixelPackState`/`MGPCaps`. That requires a `MGPipeHasFieldVerifier<T>` specialization each — `gen_pipe.py` emits those from the `.def`, so regenerate and commit `generated/*.inc`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Risks, ODR hazards, and open decisions
|
||||
|
||||
### 7.1 `VertexAttribute` cannot become a POD without a redesign (highest risk)
|
||||
`SharedPtr<BufferObject> Buffer` (`VertexArrayObject.h:39`) and `VertexBufferBindingPoint::Buffer` (`:59`) are `std::shared_ptr`. Three options, in increasing cost:
|
||||
1. **Move as-is with a forward-declared `BufferObject`** (recommended for P0.5, "pure move"). The header stays free of `MG_State/GLState` includes, every consumer keeps compiling because `BufferObject.h` is already in their TU, and the types stay non-trivially-copyable — which is fine, because `MGPipeTypes.h:247-253` already carries them as a **blob**, not inline. Risk: a TU that includes only `MGPipeValueTypes.h` and then copies a `VertexAttribute` gets an incomplete-type error. Mitigate with a `static_assert` comment and by NOT adding a POD assertion for these two.
|
||||
2. **Split into a POD wire twin** (`MGPVertexAttributeWire` with `Uint64 BufferHandle` instead of the `SharedPtr`, fixed-width `Uint64 Offset` instead of `SizeT`) defined in `MGPipeTypes.h`, leaving the frontend struct in `MGPipeValueTypes.h`. This is what `MGPVertexElements`'s blob actually needs and is probably the right end state, but it is a *design* change, not a move, and violates the P0.5 "纯搬移 / 全套测试逐名不变" acceptance criterion. Defer to P2/P3.
|
||||
3. Template on the buffer handle type — rejected; it would break `offsetof`/`sizeof` reasoning and every `const VertexAttribute&` signature (`Managers.h:744`, `Managers.cpp:2199,2246,2256,2627`, `VertexInputStateFactory.cpp`).
|
||||
|
||||
### 7.2 Namespace hazard — `VertexAttribute` is nested one level deeper
|
||||
`RenderStateParameters`, `PixelStoreParameters` and `SamplerParameters` live directly in `MobileGL`; `VertexAttribute` and `VertexBufferBindingPoint` live in `MobileGL::MG_State::GLState` (`VertexArrayObject.h:14-16`). If the new header reopens `namespace MobileGL::MG_State::GLState`, then **`MG_Pipe` defines names inside `MG_State`** — cosmetically wrong for a purity gate that is about MG_State, and it will confuse any grep-based gate. Two defensible answers: (a) keep the nesting and note it (zero call-site churn, ~100 `MG_State::GLState::VertexAttribute` spellings survive); (b) move them to bare `MobileGL` and add `namespace MG_State::GLState { using MobileGL::VertexAttribute; using MobileGL::VertexBufferBindingPoint; }` back in `VertexArrayObject.h`. (b) is cleaner and still name-transparent; the `using` alias makes `MG_State::GLState::VertexAttribute` keep resolving. **Recommend (b).**
|
||||
|
||||
### 7.3 Which enums move — the "vocabulary vs. value" cut
|
||||
`StencilFace` (`RenderState.h:97-102`), `PixelStoreParam` (`:104-127`) and `CapabilityInput` (`:151-189`) are **not members of any value struct**. They are the argument vocabulary of `class RenderState`'s setters (`RenderState.h:431-434, 456-460, 495-497`) and of the four `MG_Util/Converters/*/RenderStateEnumConverter.h`. Leaving them behind in `RenderState.h` is legal but forces those four converter headers to keep including `RenderState.h` — which after the split is cheap, since `RenderState.h`'s closure will have collapsed. Moving them is also legal and makes the converters includable from `MGPipeValueTypes.h` alone. **Either works; the ARCHITECTURE.md list does not name them.** Whichever is chosen, it must be uniform — a *split* (some enums here, some there) is what creates the worst maintenance trap.
|
||||
|
||||
### 7.4 `DynamicBackendParameters` — contradiction between the two specs
|
||||
`ARCHITECTURE.md:260` omits it from the `MGPipeValueTypes.h` list; `MGPipeTypes.h:140-143` says P0.5 moves it "with fixed-width members". "With fixed-width members" is **not a pure move** — it changes the three `SizeT` fields (`BackendObject.h:317, 322, 545`) to `Uint64` and would change `sizeof`, breaking `MGPipeTypes.h:144-145` on purpose. It also drags a second problem: `DynamicBackendParameters` has two member functions taking `TextureTarget` (`BackendObject.h:487-497`), which is why `BackendObject.h:11` includes `MG_State/GLState/TextureState/TextureEnum.h` — so moving it either drags `TextureEnum.h` into MG_Pipe or forces those two helpers to be free functions left behind in `BackendObject.h`. **Recommendation**: in P0.5 do the pure structural move only (leave `DynamicBackendParameters` where it is, keep `MGPipeTypes.h:32`'s `BackendObject.h` include, and note that gate A is armed for MG_State but not yet for MG_Backend), or move it *verbatim* including the `SizeT`s and keep the compositional assertion. Widening the fields is a separate, testable change. Escalate this to the plan owner rather than silently picking.
|
||||
|
||||
### 7.5 ODR / one-definition risks
|
||||
- **Double definition**: the move must *delete* the originals, not duplicate them. Duplicating `RenderStateParameters` in two headers under the same name in namespace `MobileGL` is an ODR violation that neither compiler will diagnose across TUs and that would silently break `DirectGLES.cpp`'s `offsetof` shadow if the two ever drift. Grep after the move: `grep -rn "struct RenderStateParameters\|struct PixelStoreParameters\|struct SamplerParameters\|struct VertexAttribute\|struct VertexBufferBindingPoint\|struct PerBufferBlendState\|struct StencilFaceState" MobileGL/` must return exactly one hit each, in `MGPipeValueTypes.h`.
|
||||
- **`MAX_DRAW_BUFFERS` divergence**: if the constant is duplicated (a `kMGMaxDrawBuffers = 8` in the new header and a literal `8` left at `FramebufferObject.h:106`), the two can drift and `RenderStateParameters::BlendStates` would silently stop matching `FramebufferObject`'s attachment arrays. Pin with a `static_assert` in a .cpp that sees both.
|
||||
- **`#pragma once` + two include paths**: `MG_Pipe` is on the include path twice (`CMakeLists.txt:531` and `:535`), so the same file is reachable as `<MG_Pipe/MGPipeValueTypes.h>` and `<MGPipeValueTypes.h>`. `#pragma once` is path-canonicalizing on GCC/Clang/MSVC so this is safe in practice, but on Windows with mixed case or symlinked worktrees it has bitten before. **Recommend adding a belt-and-braces include guard macro alongside `#pragma once`** for this one header, since it is the only header spellable two ways that also defines types with size assertions.
|
||||
- **`MG_Test/Pipe/PipeCatalogueTest.cpp` include set**: it includes `"Includes.h"` and `<MG_Pipe/MGPipe.h>` only (`:17-18`) and asserts on `RenderStateParameters`/`PixelStoreParameters` at `:113`. If `MGPipeTypes.h` stops including `RenderState.h`, this test still compiles only because the new header supplies them — good, that is exactly the gate. If someone "fixes" the test by adding a `RenderState.h` include, the gate is defeated; forbid it in review.
|
||||
- **Enum-to-`GLenum` implicit conversions**: none of these enums are `enum class` with a fixed underlying type except `BorderColorForm : Uint8`. Moving them cannot change their underlying type unless someone "tidies" it — do not. `BorderColorForm`'s `: Uint8` is load-bearing for `SamplerParameters`'s tail padding.
|
||||
- **Member reordering**: forbidden. `DirectGLES.cpp:2070-2071` reads `offsetof(..., BlendStates)` and `offsetof(..., LogicOp)`, and `generated/PipeSpanTable.inc:34-59` names 24 members by string for P2's `offsetof` table. A reorder that keeps `sizeof` at 1168 would pass every existing assertion and silently corrupt Espryt's span diffing.
|
||||
|
||||
### 7.6 Files that must change their `#include` lines
|
||||
Header edits (the move itself):
|
||||
1. `MobileGL/MG_State/GLState/RenderState/RenderState.h` — drop `:11`, `:12`; add `<MG_Pipe/MGPipeValueTypes.h>`; delete `:14-370`.
|
||||
2. `MobileGL/MG_State/GLState/SamplerState/SamplerObject.h` — replace `:11`; delete `:14-97`.
|
||||
3. `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h` — add the new include; delete `:17-70`; add the `using` aliases if §7.2(b) is chosen.
|
||||
4. `MobileGL/MG_State/GLState/FramebufferState/FramebufferObject.h:106` — pin `MAX_DRAW_BUFFERS` against the new constant.
|
||||
5. `MobileGL/MG_Pipe/MGPipeTypes.h` — drop `:32-33`, rework `:36-40`, add `"MGPipeValueTypes.h"`, update the debt comment `:24-33` and (conditionally) `:140-145`.
|
||||
6. `MobileGL/MG_Pipe/PipeFields.def` — add the four/five new field lists; then rerun `python3 scripts/gen_pipe.py` and commit `MG_Pipe/generated/PipeVerify.inc` (and any other regenerated `.inc`).
|
||||
|
||||
Includers that *could* be narrowed (optional, and each one narrowed is a place the purity gate gets stronger; none is required for the build to pass, because all five headers keep their old names and namespaces):
|
||||
7. `MobileGL/MG_Util/Texture/PixelStoreProcessor.h:11` — wants `PixelStoreParameters` only; swap `RenderState.h` → `MGPipeValueTypes.h`.
|
||||
8-11. `MobileGL/MG_Util/Converters/{GLToMG,MGToGL,MGToStr,MGToVk}/RenderStateEnumConverter.h:11` — want the enums only; swap if §7.3 moves the enums.
|
||||
12. `MobileGL/MG_Backend/DirectVulkan/Renderer/VkSamplerManager.h:14` — needs `class SamplerObject`, so it must keep `SamplerObject.h`. **No change.**
|
||||
13. `MobileGL/MG_Backend/DirectVulkan/Renderer/VertexInputStateFactory.h` — needs `class VertexArrayObject`. **No change.**
|
||||
14. `MobileGL/MG_Impl/GLImpl/Sampler/Validators.h`, `MG_Impl/GLImpl/VertexArray/Validators.h` — check whether they need the class or only the value struct.
|
||||
|
||||
Files that need **no** change and must be verified unchanged (the "纯搬移" proof): all 51 `RenderStateParameters` uses in `MG_Backend/DirectGLES/DirectGLES.cpp`, all 17 in `MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp`, the 11 in `MG_State/GLState/RenderState/RenderState.cpp`, and the 73 includers of `MG_State/GLState/Core.h`.
|
||||
|
||||
### 7.7 Suggested verification, cheapest first
|
||||
1. `grep -rn "MG_State/GLState" MobileGL/MG_Pipe/` must be empty (gate A). Add the deliberate-red check by re-adding one include.
|
||||
2. `g++ -H -fsyntax-only` (or `clang -H`) on a TU that includes only `<MG_Pipe/MGPipeValueTypes.h>` — the printed tree must contain no `MG_State/` path. This is the "CI `-H` 闭包断言" ROADMAP.md:16 asks for.
|
||||
3. Compile-only check that `sizeof(RenderStateParameters)` is unchanged before/after — add a temporary `static_assert(sizeof(RenderStateParameters) == 1168)` (confirm the real number first; 1168 above is inferred arithmetic from `MGL_RESIDUAL_BLOCK_SIZE`, not measured).
|
||||
4. `PipeCatalogueTest` (`MG_Test/Pipe/`) must stay green without gaining an include.
|
||||
5. `nm`/`.text` diff per ROADMAP.md:16 — a pure move should produce zero symbol changes.
|
||||
@@ -0,0 +1,208 @@
|
||||
# P1 implementation brief — `PipeInputs` strangler, per-verb fill points, poison generations, `MOBILEGL_PIPE_VERIFY` comparator + third CI mode
|
||||
|
||||
Tree: `feat/disaggregated @ 087685d1` (worktree `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, clean except untracked `.trace-work/`). WSL: base tree `~/w7/pipe` and five package worktrees `~/w7/p1-<slug>` on branches `p1/<slug>`, all created **from the contract commit C0** (section B.1) that the integrator lands first; every tree gets a configured `build-linux/` exactly as in the P0.5 brief (Release, `/usr/sbin/clang++`, ccache, `MOBILEGL_BUILD_TEST=ON`, `MOBILEGL_BUILD_INTEGRATION_TEST=ON`, `MOBILEGL_BUILD_DISAGGREGATED=OFF`, log level INFO) — that is the **pull build**; the core package additionally configures `build-verify/` (section C.1).
|
||||
|
||||
Every `file:line` below was re-opened at `087685d1`. Where a scout was wrong or incomplete the text says **[correction]** and the corrected fact is what the packages follow.
|
||||
|
||||
Corrections to the scouts, in one place:
|
||||
1. **Boundary catalogue is incomplete.** `MG_Impl/GLImpl/Drawing/GL_Drawing.cpp:1329` aliases the table (`auto& backendGL = MG_Backend::gBackendFunctionsTable.GL;`) and lines `1330-1334` invoke `FenceSync`/`ClientWaitSync`/`DeleteSync` through it; the "91 lines" count misses them. The complete boundary is **96 lines / 87 invocations** (table in B.9). There is **no** `pActiveBackendObject->` path from `MG_Impl` into a pull site: the only virtuals `MG_Impl` calls are `GetDynamicParameters` (35), `GetFormatCapabilities` (4), `GetBackendType` (1). `Present`/`SetSwapInterval` are not invoked from `MG_Impl` at all (`MG_Backend/Init.cpp:44` copies the table; the EGL path calls the backend's own virtuals), and neither reads a field (`DirectGLES.cpp:10550`, catalogue "no pulls").
|
||||
2. **`ShaderStorageBlockBinding` does not call `SyncNeccessaryTextures`/`SyncRenderState`** (scout-pull-sites §4.2). `DirectGLES.cpp:7355-7372` reads only `ValidateProgramName`/`GetProgramObject`; the two sync calls at `:7376/:7378` belong to `ClearBufferfi` (`:7374`). It is a `Passive` verb (B.8).
|
||||
3. **Three lines outside the 58 need hand edits**: `DirectGLES.cpp:144` (`static const MG_State::GLState::GLContext* g_fbSlotCacheContext`) and `:150` (`&ctx->GetFramebufferBindingSlot(...)` — an arrow through a local `GLContext*`, invisible to every `pGLContext` grep) change with `:147`; B.11 gives the exact text.
|
||||
4. **Counts in the docs vs the tree**: `sed` sites 277 (not 293), on 274 lines; non-arrow lines 58 (exact); distinct accessors 62 (+ one `.get()`), Espryt 32 / **Magma 56** (doc: 55); `PipeFilled.inc` field set 61 → **62** (drop `GetBoundTransformFeedbackName`, add `GetBoundTransformFeedbackLifetimeId` + `HasOpenTransformFeedbackSpan`, both read at `VulkanRenderer.cpp:11219/:11236`, declared `Core.h:441/:450`). `SyncPersistentMappedRange` 20 / `SyncGpuWrites` 6: exact.
|
||||
5. **`MOBILEGL_DEBUG` does not exist** (only `ARCHITECTURE.md:330` spells it). The repo's debug gate is `MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG` (`Defines.h:104-115`). D9 below fixes the poison gate.
|
||||
6. **The dirty-surface mapping gate is P2**, not P1 (`ROADMAP.md:18` P2 row; `ARCHITECTURE.md:172,568` and `test.yml:871-874` say P1). The ROADMAP table cell is the authority for what P1 delivers; P1 leaves `gen_pipe_dirty_surface.py --summary` informational and the integrator corrects the three P1 mentions (D.6).
|
||||
7. **The vendored inventory is not edited.** The dead accessor is retired through a new `MGP_COVERAGE_RETIRED_LIST` (D14) so G6 still maps its 477 rows; a live-tree cross-check in `gen_pipe.py` (D15) makes the field set follow the code from now on.
|
||||
8. `PipeCatalogueTest.cpp:225` pins 61 → 62; `:213` (477) is unchanged.
|
||||
|
||||
---
|
||||
|
||||
## A. Goal and acceptance gate (verbatim, then decoded)
|
||||
|
||||
`docs/Disaggregated/ROADMAP.md:17`:
|
||||
|
||||
> **P1** `PipeInputs` 替换与 verify harness | 10–13 | `MG_Backend/MGPipe/PipeInputs.h`(Espryt 32 / Magma 55 访问器);`sed` 293 处 + 58 行非箭头清单逐条转换(显式交付物);逐 verb 类填充点(G5 表,~93 个边界站点);逐 verb 世代 poison;G4 影子比对器 + 第三种 CI 模式;20 处 `SyncPersistentMappedRange` + 6 处 `SyncGpuWrites` 的逐站点归属表 | pull 构建 `nm --defined-only` 不变、`.text` 差异逐行归因(空守卫/三元重写推迟到 P2);40 trace + 全部集成测试在 `MOBILEGL_PIPE_VERIFY=1` 下零分歧;故意损坏一个快照字段能让 verify 变红;故意在 `glGenerateMipmap` 的填充表漏一个字段能在**那条 verb** 上触发 poison Fatal | P0.5
|
||||
|
||||
Supporting text every package must know: the strangler sketch and the three-phase table `ARCHITECTURE.md:323-351` (§9.2; P1 = phase A + the scaffolding for phase B); gate 13.2-② `ARCHITECTURE.md:501` (field-wise, never memcmp, first differing field + draw serial, ~5–10× slower, never shipped, survives P13); the P13 retention rule `ARCHITECTURE.md:369` (delete `MGB_CTX`/`MOBILEGL_PIPE_PUSH`/the non-verify branch of `SnapshotFromGLContext()`, keep `MOBILEGL_PIPE_VERIFY` with its `MG_State` include); purity gate C `ARCHITECTURE.md:500` greps the bare token `pGLContext` under `MG_Backend/`; the stale-index discipline table `ARCHITECTURE.md:233-238` and open question #15 `ROADMAP.md:88` (the `*IndirectCount` rows are recorded as they are, **not fixed**); `ROADMAP.md:7` — every gate must be able to go red for the reason it exists; Windows is not a correctness gate.
|
||||
|
||||
Decoded into checkable statements (the integrator ticks each in D.5):
|
||||
|
||||
| # | statement | how it is checked |
|
||||
|---|---|---|
|
||||
| G1 | The **pull build** (both new CMake options OFF, Release/INFO, LTO off) has the same `nm --defined-only` symbol set as the P0.5 baseline `087685d1`. | `scripts/symbol_report.py --json` → `added == [] and removed == []`. |
|
||||
| G2 | Every `.text` byte delta in that build is attributed to a named line of the 58-line conversion list (or to the three extra lines in correction 3). Empty-guard / ternary **rewrites** are not done in P1 — they are converted to a spelling with identical codegen (D4) and rewritten in P2. | `docs/Disaggregated/P1-symbol-attribution.md`: one row per resized symbol with the line that caused it. Expected content: the five inliners of `GetFramebufferBindingSlotFast` (`DirectGLES.cpp:1611,1905,2743,2858,2933` — the `:147/:150` change) and nothing else. |
|
||||
| G3 | On the **verify build**, all 40 traces (39 CI cases × 2 backends − 1 = 77 matrix entries; `rd12-odinlite` is `ci:false`, `iterationrp` is Magma-only) and every integration scenario (371 cases × 2 backends) run with `MOBILEGL_PIPE_VERIFY=1` and report zero divergence: no `Fatal{PipeVerifyDiffer` and no `Fatal{UnmigratedPipeInput` in any log, every case green, and the library's arming line present in every log. | `ctest -L integration-verify` (742 entries + the arming/negative lanes) and the `retrace-verify` matrix run with `verify_retrace=full`; `run_trace_case.cmake` fails a case whose `mobilegl.log` lacks `MGPipe: verify armed` (so a pull library under the lane cannot pass). |
|
||||
| G4 | Negative control A: `MOBILEGL_PIPE_VERIFY_CORRUPT=GetRenderStateParameters` makes a verify run red, naming that field. | Unit test (`PipeInputsTest.CorruptedSnapshotFieldIsNamed`), integration lane `*.VerifyCorrupted.*`, and an inverted CI step on one short scenario and one short trace. |
|
||||
| G5 | Negative control B: omitting one field from `GenerateMipmap`'s fill set raises `Fatal{UnmigratedPipeInput, "GetTextureUnitObject@GenerateMipmap"}` **on that verb** (the process aborts inside `glGenerateMipmap`, not at a later draw). | Unit test (`PipeInputsTest.OmittingOneFieldForOneVerbLeavesExactlyThatFieldStale`, fork/`waitpid` `...AbortsNamingTheVerb`), integration lane `*.PoisonOmission.*` (fork + `glGenerateMipmap`, both backends), and the literal control: delete the `X(TextureOp, GetTextureUnitObject)` row from `FillPoints.def`, regenerate, run — red on `GenerateMipmap`. |
|
||||
| G6 | The 20 + 6 sync sites are tabulated per site with their §5.7 reconcile row. | `docs/Disaggregated/SYNC_SITES.md` (B.12), lint-clean under `check_doc_citations.py`. |
|
||||
| G7 | Existing tests: no name removed (`ctest -N` diff vs baseline is additions-only), `ctest -L unit` and `ctest -L integration-gpu` green on the pull build, `gen_pipe.py --check` clean, `check_include_closure.py --require-all` green. | D.5. |
|
||||
|
||||
---
|
||||
|
||||
## B. Fixed design decisions (every package follows these; none is re-decided inside a package)
|
||||
|
||||
### B.1 The contract commit C0 (integrator, before any package branches)
|
||||
|
||||
Two new headers, nothing else. Both are owned by `p1-core` afterwards; the other four packages only include them.
|
||||
|
||||
**`MobileGL/MG_Pipe/PipeStrangler.h`** (exact content; banner as `MGPipe.h:1-7` with the path adjusted):
|
||||
|
||||
```cpp
|
||||
#pragma once
|
||||
#ifndef MOBILEGL_MG_PIPE_STRANGLER_H
|
||||
#define MOBILEGL_MG_PIPE_STRANGLER_H
|
||||
// The P1 strangler alias (ARCHITECTURE.md section 9.2, phase A). Every backend read of
|
||||
// frontend state is spelled MGB_CTX-> from P1 on. In the PULL build the three macros expand
|
||||
// to exactly the tokens the backends used before P1, so the preprocessed token stream - and
|
||||
// therefore .text - is unchanged. In the PUSH build (-DMOBILEGL_PIPE_PUSH=1) they resolve to
|
||||
// the pushed PipeInputs block. This header deliberately lives OUTSIDE MG_Backend/ so that
|
||||
// purity gate C (`grep -c pGLContext MG_Backend/ == 0`, ARCHITECTURE.md:500) is a statement
|
||||
// about backend code, not about the alias; P13 deletes this file.
|
||||
//
|
||||
// MGB_CTX_PRESENT replaces the seven empty guards, the four ternary conditions and the
|
||||
// six `!= nullptr` / `== nullptr` tests of the 58-line list: in the pull arm it is the
|
||||
// same null test those lines performed (unique_ptr::operator bool IS `get() != nullptr`),
|
||||
// in the push arm the block is always there. P2 removes the guards; P1 only respells them.
|
||||
// MGB_CTX_IDENTITY replaces the one `.get()` capture (DirectGLES.cpp:147): an opaque
|
||||
// identity that changes when the frontend context is recreated.
|
||||
#if MOBILEGL_PIPE_PUSH
|
||||
#include <MG_Backend/MGPipe/PipeInputs.h>
|
||||
#define MGB_CTX (&::MobileGL::MG_Pipe::gPipeInputs)
|
||||
#define MGB_CTX_PRESENT (true)
|
||||
#define MGB_CTX_IDENTITY (::MobileGL::MG_Pipe::gPipeInputs.FrontendIdentity())
|
||||
#else
|
||||
#define MGB_CTX (::MobileGL::MG_State::pGLContext)
|
||||
#define MGB_CTX_PRESENT (::MobileGL::MG_State::pGLContext != nullptr)
|
||||
#define MGB_CTX_IDENTITY (static_cast<const void*>(::MobileGL::MG_State::pGLContext.get()))
|
||||
#endif
|
||||
#endif
|
||||
```
|
||||
|
||||
The pull arm needs no include: every backend TU that spells `MGB_CTX` already includes what declares `MobileGL::MG_State::pGLContext` (`Core.h:596`, `extern UniquePtr<GLState::GLContext>& pGLContext;`). The push arm's `MG_Pipe → MG_Backend` include is a deliberate, documented layering exception that dies with the file at P13.
|
||||
|
||||
**`MobileGL/MG_Impl/Pipe/PipeFill.h`** (stub; core replaces the body, the macro name and the pull no-op are the contract):
|
||||
|
||||
```cpp
|
||||
#pragma once
|
||||
// P1 fill points (ARCHITECTURE.md:348). One MGP_FILL_FOR(<Verb>) immediately before each
|
||||
// backend-table invocation in MG_Impl. Pull build: nothing. Push build: an RAII verb scope
|
||||
// that bumps the poison serial, fills gPipeInputs for the verb's class, runs the verify
|
||||
// comparator when armed, and closes the verb on scope exit.
|
||||
#if MOBILEGL_PIPE_PUSH
|
||||
#include <MG_Pipe/MGPipe.h>
|
||||
namespace MobileGL::MG_Pipe {
|
||||
class MGPipeVerbScope {
|
||||
public:
|
||||
explicit MGPipeVerbScope(MGPipeVerb verb);
|
||||
~MGPipeVerbScope();
|
||||
MGPipeVerbScope(const MGPipeVerbScope&) = delete;
|
||||
MGPipeVerbScope& operator=(const MGPipeVerbScope&) = delete;
|
||||
};
|
||||
}
|
||||
#define MGP_PP_CAT2(a, b) a##b
|
||||
#define MGP_PP_CAT(a, b) MGP_PP_CAT2(a, b)
|
||||
#define MGP_FILL_FOR(Verb) \
|
||||
::MobileGL::MG_Pipe::MGPipeVerbScope MGP_PP_CAT(mgpVerbScope_, __LINE__)(::MobileGL::MG_Pipe::MGPipeVerb::Verb)
|
||||
#else
|
||||
#define MGP_FILL_FOR(Verb) ((void)0)
|
||||
#endif
|
||||
```
|
||||
|
||||
`MGPipeVerb` is the generated verb enum (`generated/PipeFillPoints.inc`, D12), so in the stub state `MGP_FILL_FOR` only compiles in the pull arm — which is all the fill-points package can build anyway. Commit message for C0: `[Feat] (Pipe): add the P1 strangler contract headers - MGB_CTX/MGB_CTX_PRESENT/MGB_CTX_IDENTITY in MG_Pipe/PipeStrangler.h and the MGP_FILL_FOR no-op in MG_Impl/Pipe/PipeFill.h`.
|
||||
|
||||
### B.2 Decisions
|
||||
|
||||
| # | decision | why / evidence |
|
||||
|---|---|---|
|
||||
| D1 | **Two CMake options**, both default OFF: `MOBILEGL_PIPE_PUSH` (→ `-DMOBILEGL_PIPE_PUSH=1`, selects the alias arm) and `MOBILEGL_PIPE_VERIFY` (→ `-DMOBILEGL_PIPE_VERIFY=1`; **forces `MOBILEGL_PIPE_PUSH` ON** with a `message(STATUS)`). The runtime `MG_Config::Features.PipePush` bitmap (`Config.h:326`) is **not consumed in P1** (a P1 push build pushes every field of the verb's set at every fill point); the runtime `Features.PipeVerify` (`Config.h:332`, env `MOBILEGL_PIPE_VERIFY`) **arms** the comparators at run time inside a verify build and does nothing in any other build. | Resolves scout R3: the `#if` in `ARCHITECTURE.md:334` is the CMake macro; the bitmap is phase B's per-field yield (P2). Verify without push is meaningless: the poison lives in the accessors, which only exist in the push arm. |
|
||||
| D2 | **Namespaces and paths.** `struct PipeInputs` and `gPipeInputs` live in `namespace MobileGL::MG_Pipe` (the doc's spelling `::MobileGL::MG_Pipe::gPipeInputs`, `ARCHITECTURE.md:331`) and are declared in `MobileGL/MG_Backend/MGPipe/PipeInputs.h` (the doc's path, `:325,:553`), defined in `MobileGL/MG_Backend/MGPipe/PipeInputs.cpp`. The frontend-facing half (`SnapshotFromGLContext`, the fillers, `MGPipeVerbScope`, knob parsing, init) lives in `MobileGL/MG_Impl/Pipe/PipeFill.{h,cpp}` — the directory P2's tracker joins (`ROADMAP.md:18` `MG_Impl/Pipe/Tracker`). `MGPipeImpl_DirectGLES/DirectVulkan.cpp` from the layout table `ARCHITECTURE.md:553` are **not created in P1** (they are the server-side table implementations, P5+); the integrator corrects the table cell to `PipeInputs.h + PipeInputs.cpp [P1+]`. | Gate C: nothing under `MG_Backend/` spells `pGLContext` after P1 (the pull arm's token lives in `MG_Pipe/PipeStrangler.h`, the filler in `MG_Impl/`). Gate A at P13 keeps `MG_State` includes for verify builds only. |
|
||||
| D3 | **Pull build is byte-for-byte the P0.5 library.** Every new `.cpp` (`PipeInputs.cpp`, `PipeFill.cpp`) is wrapped whole in `#if MOBILEGL_PIPE_PUSH … #endif` (banner outside, everything else inside — no includes reachable in the pull arm); `MGP_FILL_FOR` is `((void)0)`; the three config knobs (D18) are declared and parsed under `#if MOBILEGL_PIPE_PUSH`; the `Init.cpp` hook is `#if MOBILEGL_PIPE_PUSH`; `PipeStrangler.h` is macros only. | G1/G2. |
|
||||
| D4 | **The 58 non-arrow lines** convert as: 43 `MOBILEGL_ASSERT(… pGLContext …)` lines **deleted** (34 `DirectVulkan.cpp`, 9 `UniformManager.cpp`; no-ops in INFO builds, `Defines.h:113-115`; under push the block cannot be null); 5 bare `if (MG_State::pGLContext)` and 2 `&& MG_State::pGLContext` compounds → `MGB_CTX_PRESENT`; 4 ternary conditions (`Managers.cpp:7192/7200/7203`, `DirectVulkan.cpp:1284`) → `MGB_CTX_PRESENT ? MGB_CTX->X() : default`; `!= nullptr` at `DirectVulkan.cpp:1236`, `VulkanRenderer.cpp:12766` → `MGB_CTX_PRESENT`; `== nullptr` at `VulkanRenderer.cpp:11267` → `!MGB_CTX_PRESENT`; the `.get()` at `DirectGLES.cpp:147` → `MGB_CTX_IDENTITY` (with `:144`/`:150`, B.11); the comment `VertexInputStateFactory.h:133` reworded. Exact per-line text in B.11. | `ARCHITECTURE.md:344` (~34 assert deletions, 7 guards, 3 ternaries, `.get()`+`decltype`, 14 `!= nullptr`, 1 comment; the 9 UniformManager asserts are the doc's `!= nullptr` overlap). Pull codegen identical: `unique_ptr::operator bool` is `get() != nullptr`. |
|
||||
| D5 | **Every accessor keeps the exact `GLContext` signature** (name, parameters, return type, const-ness — `Core.h` lines in B.4). `MGB_CTX->X(args)` is therefore the only edit at 277 sites (`sed 's/MG_State::pGLContext->/MGB_CTX->/g'`), and `GetRenderStateParameters()` returns `const RenderStateParameters&` so `SyncRenderState` is untouched (GO/NO-GO item 2, `ROADMAP.md:47`). | `ARCHITECTURE.md:328` "阶段 A:类型与后端今天读到的完全一致". |
|
||||
| D6 | **Storage kinds** (B.4 has the per-field assignment). (V) *value copy*: the accessor's result is copied into a `PipeInputs` member at fill and returned from the copy; the 1168-byte `RenderStateParameters` copy is the only memoised one — copied only when `GetRenderStateParametersVersion()` changed since the last fill (Espryt's own early-out trusts that version, `DirectGLES.cpp:2026`), stamped every time. (H) *shared-pointer copy*: `SharedPtr` copied at fill (`GetBoundVertexArray`, `GetProgramForDraw`, `GetProgramForDispatch`, `GetTransformFeedbackProgram`). (R) *reference capture*: for the five accessors returning a mutable reference into a frontend container, `PipeInputs` stores the container base pointer(s) captured at fill and the accessor indexes them, returning the same live reference the backend reads today (`GetBufferBindingSlot` — one pointer per `GlobalBufferTargets` entry; `GetBufferBindingPoint` — one base pointer per `BufferBindPointTargets` entry into the contiguous `Array<BindingSlotRange1D<BufferObject>, 84>` (`BufferState.h:73`); `GetFramebufferBindingSlot` — two pointers; `GetTextureUnitObject` — base of `Array<TextureUnit, 192>` (`TextureState.h:128`); `GetImageTextureBinding` — base of `Array<ImageTextureBinding, 192>` (`:129`)), plus `GetCurrentVertexAttribute` (base of the 32-entry `Array<CurrentVertexAttributeValue, 32>`, `Core.h:513`, replicating the out-of-range branch at `Core.cpp:246-250`). (P) *pass-through*: six accessors that are not pipe data forward to the frontend through a resolver (D8). **No accessor derives its value from another field** (no re-implementation of `RenderState` logic inside `PipeInputs`): the cost is ~1 KB of copies per verb in the push build, which P2's tracker replaces. | Type identity for references cannot be met by a copy (`GetImageTextureBinding` returns `ImageTextureBinding&`; the backend only reads through it — `DirectGLES.cpp:1728-1745`, `UniformManager.cpp:1016-1030`, `VulkanRenderer.cpp:9214-9224` verified — but a copy would still break `.Bind()` semantics if ever used). Derivation would duplicate `RenderState.cpp` rules (`IsCapabilityEnabledIndexed` at `RenderState.cpp:471-490` has three branches); copying the accessor result cannot be wrong. Size: `sizeof(PipeInputs) < 4 KiB` (`static_assert(sizeof(PipeInputs) <= 8192)`), well under the doc's ~20 KB. |
|
||||
| D7 | **Poison = per-verb generation, exactly the P0 skeleton** (`PipeFilled.inc:293-307`): `PipeInputs` embeds `MGPipeFilledState m_filled` plus `MGPipeVerb m_currentVerb` and `Uint32 m_verbDepth`. A fill stamps `FilledGen[f] = CurrentVerbSerial`. Every non-pass-through accessor begins with `MGP_POISON_CHECK(Field)` = `if (!MGPipeInputFieldIsFresh(m_filled, Field)) MGPipeInputPoisonFatal(Field, CurrentVerbName())` under `MOBILEGL_PIPE_POISON` (D9). `kMGPipeInputFieldSticky[]` stays **all false in P1**: no sticky field was needed once the six pass-throughs stopped being poison fields (D8). | `ARCHITECTURE.md:349`; scout R5 (each `true` must be argued — none is). |
|
||||
| D8 | **Six pass-through accessors** declared in a new `MGP_COVERAGE_PASSTHROUGH_LIST(X)` in `Coverage.def`: `GetProgramObject(Uint)`, `GetTextureObject(Uint)` (by-name lookups, Track H residue), `HasOpenTransformFeedbackSpan(Uint64)` (a query over the TF object table, XFB is P9), `ValidateProgramName(Uint)`, `InvalidateCompileEnv()` (`kClientResolved`), `RecordError(...)` (`kReverseChannel`). They keep their `MGPipeInputField` ids (the enum stays "one id per accessor") but are neither stamped, poison-checked, compared, nor members of any fill set. They forward through `GLContext* PipeInputs::Frontend()` = `m_frontendResolver()` — a function pointer installed by `MG_Impl::Pipe::Init()` (D19) — with the same null tolerance the guarded pull sites had (`if (auto* c = Frontend()) c->InvalidateCompileEnv();`). `FrontendIdentity()` returns `static_cast<const void*>(Frontend())`. | `PipeInputs.h` must not spell `pGLContext` (gate C); `InitCapabilities` (`BackendObject_DirectVulkan.cpp:388-389`) runs before any verb. |
|
||||
| D9 | **`MOBILEGL_PIPE_POISON`** is derived in `PipeInputs.h`, not a CMake option: `#define MOBILEGL_PIPE_POISON (MOBILEGL_PIPE_VERIFY || MOBILEGL_BUILD_DISAGGREGATED || (MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG))`. The Fatal is the generated `MGPipeInputPoisonFatal` (`MGLOG_F` + `std::abort()`, live at INFO). | Correction 5; `MOBILEGL_ASSERT` would vanish in CI builds (`test.yml:85`). |
|
||||
| D10 | **Verb scope semantics** (`MGPipeVerbScope`, push builds): ctor — `if (m_verbDepth++ == 0) { ++CurrentVerbSerial; m_currentVerb = verb; }` then `SnapshotFromGLContext(gPipeInputs, kMGPipeFillSets[kMGPipeVerbClass[verb]], *pGLContext, verb)` (fills + stamps the class's set; skips the stamp of the field named by the omission knob when `verb` matches), then, if `Features.PipeVerify`, the verb-level compare (D11). dtor — `if (--m_verbDepth == 0) { ++CurrentVerbSerial; m_currentVerb = MGPipeVerb::kNone; }`. Nested scopes (e.g. `glEndTransformFeedback` → `EndTransformFeedback` then `FenceSync`, `GL_Drawing.cpp:1322-1336`) fill into the enclosing verb without re-bumping. **Closing the verb bumps the serial**, so a field read outside any verb — including from a backend path no fill point covers — is `Fatal{UnmigratedPipeInput, "<Field>@<outside any verb>"}`: that is how a missing fill point is found (D.3). | `PipeFilled.inc:19-23`: the poison must see "filled by the previous draw, read by the glTexSubImage that follows". |
|
||||
| D11 | **What the comparator compares and where it runs** (verify builds, `Features.PipeVerify` set): (a) **verb-level**: at every fill point, after the fill, `SnapshotFromGLContext(scratch, set, ctx, kNone)` then `MGPipeVerifyInputs(gPipeInputs, scratch, set, &field)` over the verb's fill set; (b) **read-level**: every non-pass-through accessor, after the poison check, re-pulls the one field (argument-scoped: the `unit`, `target`, `index` asked for) into a thread-local scratch through `SnapshotFromGLContext` and compares it to the stored value. Per-field equality is `MGPipeFieldEqual` from `PipeVerify.inc` (float bitwise) for value fields, raw-pointer equality for (H), and a POD digest for (R): `{bound.get(), GetVersion()}` per slot, `{base pointer, per touched point: bound.get(), GetRange()}` for bind points, `{per unit ≤ GetMaxTouchedTextureUnit(): 12 bound-texture pointers + sampler pointer}` for texture units, `{Texture.get(), Level, Layered, Layer, Access, Format, Version}` per image unit, the 32 values for current attributes. A difference is `MGLOG_F("MGPipe: Fatal{PipeVerifyDiffer, \"%s@%s\", verb=%llu}", field, verbName, serial)` followed by `std::abort()` unless `Features.PipeVerifyFatal == false` (log and count). In P1 the pushed value and the snapshot come from the same source, so the comparator proves the harness, the fill-point placement (a frontend mutation between the fill and the read is red) and — through the corruption knob — its own sensitivity; P2's tracker is what gives it teeth. | `ARCHITECTURE.md:501`; `Config.h:327-332`. Retention mode (texture dirty rects) is P3b, not P1. |
|
||||
| D12 | **Fill tables are data, generated.** New hand-maintained `MobileGL/MG_Pipe/FillPoints.def` (B.8) with `MGP_FILL_CLASS_LIST(X)`, `MGP_FILL_VERB_LIST(X)` (`X(Verb, Class, Table)`, 71 rows: the 69 function-pointer members of `GLFunctionsTable`, `BackendObject.h:117-289`, plus `Present`/`SetSwapInterval` from `GlobalBackendFunctionsTable`, `:293-300`) and `MGP_FILL_SET_LIST(X)` (`X(Class, Field)`). `gen_pipe.py` grows **G5b `gen_fill_points`** → `generated/PipeFillPoints.inc` (included from `MGPipe.h` after `PipeFilled.inc`): `enum class MGPipeVerb : Uint8 { …, kNone, kVerbCount }`, `kMGPipeVerbNames[]`, `enum class MGPipeVerbClass : Uint8`, `kMGPipeVerbClass[]`, `kMGPipeVerbClassNames[]`, `struct MGPipeFieldSet { Uint64 Words[(kMGPipeInputFieldCount + 63) / 64]; constexpr Bool Has(MGPipeInputField) const; }`, `kMGPipeFillSets[kMGPipeVerbClassCount]`, and `MGP_FILL_VERB_MEMBER_CHECK` (expands to `(void)&::MobileGL::MG_Backend::GLFunctionsTable::<Verb>, …` / `GlobalBackendFunctionsTable::Present` — a test TU instantiates it, so a verb name that is not a table member is a compile error). Validation in both modes: every verb's class is declared; every set field is a non-pass-through accessor; every non-pass-through accessor is in ≥ 1 set; verb count == `MGP_FILL_VERB_DOCUMENTED_COUNT 71`. | `ARCHITECTURE.md:348` ("G5 从 PipeCalls.def 生成…可能读哪些字段"); the inverse relation is not derivable from `Coverage.def` (scout-generated §10.3), so it is a new source of truth. |
|
||||
| D13 | **Verb classes** (9): `Draw` (20), `Dispatch` (4), `Clear` (9), `BlitOrCopy` (3), `TextureOp` (4), `Readback` (3), `XfbSpan` (6), `Query` (4), `Passive` (18). B.8 lists the members and the initial field sets. The doc's eight validate entries map onto the first eight; `Passive` collects the entries that read nothing (sync, timer, occlusion, `GetIntegeri_v`, `PatchParameteri`, `ShaderStorageBlockBinding`, `DeleteBackendQuery`, `IsTimerQuerySupported`, `GetGpuTimestampNs`, `Present`, `SetSwapInterval`) and still bumps the serial. | `ARCHITECTURE.md:153`. |
|
||||
| D14 | **`Coverage.def` changes**: delete row `X(GetBoundTransformFeedbackName, SetStreamOutputTargets)` (`Coverage.def:34`); add `X(GetBoundTransformFeedbackLifetimeId, SetStreamOutputTargets)` and `X(HasOpenTransformFeedbackSpan, SetStreamOutputTargets)` in alphabetical position; add `MGP_COVERAGE_PASSTHROUGH_LIST(X)` (six `X(Accessor, Reason)` rows, D8) and `MGP_COVERAGE_RETIRED_LIST(X)` with one row `X(GetBoundTransformFeedbackName, SetStreamOutputTargets, "D21 rekey (bd2b4158) replaced the name with the lifetime id + open-span query; inventory row VulkanRenderer.cpp:11137")`. G6 joins retired names as mapped (so `kMGPipeInventoryUnmapped` stays 0 and `PipeCatalogueTest.cpp:213` keeps 477); G5 excludes them from the enum. The `GetBufferBindingSlot` split by target (`Coverage.def:36-39`) stays a comment: in P1 the field is keyed by `BufferTarget` inside `PipeInputs`; the split into four wire calls is a P5 concern. | Correction 4/7. |
|
||||
| D15 | **Live cross-check** `check_live_accessor_set()` in `gen_pipe.py` (both modes): scan `MobileGL/MG_Backend/**/*.{cpp,h}` for `\b(?:pGLContext\|MGB_CTX)\s*->\s*(\w+)` (comments masked with the same masker `gen_pipe_dirty_surface.py:46-85` uses — copy the function); the set of names must equal `ACCESSOR_LIST ∪ PASSTHROUGH_LIST`; any retired name found live, any live name not listed, or any listed name not found is `sys.exit`. This is what makes `PipeCatalogueTest`'s 62 a fact about HEAD instead of about the vendored snapshot. | Scout-generated §10.1 drift. |
|
||||
| D16 | **Field lists for the four memcmp-fallback types** land in `PipeFields.def`: `MGP_FIELDS_RenderStateParameters` (every member of `MGPipeValueTypes.h:239-…`, in declaration order), `MGP_FIELDS_PixelStoreParameters` (8), `MGP_FIELDS_PerBufferBlendState` (7), `MGP_FIELDS_StencilFaceState` (7), `MGP_FIELDS_DynamicBackendParameters` (every data member of `BackendObject.h:316-549`, 84 lines match the member regex — enumerate by reading), `MGP_FIELDS_MGHostSpan` (`MGPipeHostSpan.h:126-137`). `MEMCMP_FALLBACK_TYPES` becomes empty and the fallback branch is **deleted** from `gen_verify` — a payload member without a field list is then a compile error in `PipeVerify.inc`, which is the "comparator coverage asserted" promise of `PipeFields.def:15-17`. Two dispatcher additions in `gen_verify`: `std::array<T, N>` iterates like the C-array overload; the Vec types (`VecBase::operator==` at `VectorTypes.h:41` is IEEE `==`, so a NaN patch level would false-DIFFER) compare **bitwise** through a trait `MGPipeIsBitwiseComparable<T>` specialised for `FloatVec2/3/4`, `IntVec4`, `UintVec4`, `BoolVec4` (all padding-free). | Scout R7; `PipeVerify.inc:9-23` NaN rule; P0.5 D8 deferred exactly this. |
|
||||
| D17 | **`PipeCatalogueTest` edits**: `:225` 61 → 62; new expectations that `kMGPipeVerbCount == 71`, `kMGPipeVerbClassCount == 9`, `MGP_FILL_VERB_MEMBER_CHECK` compiles, every non-pass-through field is in ≥ 1 fill set, `kMGPipeVerifiedPayloadCount == 69` (63 + 6). | |
|
||||
| D18 | **Three new runtime knobs**, declared in `Config.h` after `PipeVerify` and parsed in `ConfigLoader.cpp` after `:246`, all under `#if MOBILEGL_PIPE_PUSH`: `Bool PipeVerifyFatal = true` (`MOBILEGL_PIPE_VERIFY_FATAL`, `QueryEnvQuirkOverride(...) != ForceOff`), `String PipeVerifyCorrupt` (`MOBILEGL_PIPE_VERIFY_CORRUPT=<FieldName>`, perturbs the **snapshot** arm's field after every snapshot), `String PipePoisonOmit` (`MOBILEGL_PIPE_POISON_OMIT=<VerbName>:<FieldName>`, skips the **stamp** — not the value — of that field when that verb fills). Names are validated against `kMGPipeInputFieldNames` / `kMGPipeVerbNames` at `MG_Impl::Pipe::Init()`; an unknown name is `MGLOG_F` + `std::abort()` so a typo cannot disarm a control. | scout-test-infra B3/B4. |
|
||||
| D19 | **Init**: `MobileGL/Init.cpp` calls `MG_Impl::Pipe::Init()` right after `MG_Util::PipeStats::Init()` (`Init.cpp:114`), under `#if MOBILEGL_PIPE_PUSH`. It installs `gPipeInputs.m_frontendResolver = +[] { return ::MobileGL::MG_State::pGLContext.get(); }`, parses/validates the knobs, and logs once: `MGLOG_I("MGPipe: push arm active: %u fields, %u verbs, %u classes; verify %s (fatal=%d)", …, Features.PipeVerify ? "armed" : "off", …)`. The exact substring the harness greps is **`MGPipe: verify armed`** (emitted only when `Features.PipeVerify`). A pull library never prints it, which is what fails a verify lane run against the wrong binary. | scout-test-infra A3 arming idiom. |
|
||||
| D20 | **Third CI mode** = job `build-linux-verify` (build-linux's steps with `BUILD_DIR: build-linux` kept — so the tarball layout is identical — plus `-DMOBILEGL_PIPE_VERIFY=ON`, own ccache key, artifact `mobilegl-linux-runtime-verify`), job `integration-verify` (`ctest -L integration-verify --no-tests=error` on that runtime, plus the two inverted negative-control steps), job `retrace-verify` (the `retrace` matrix shape, unpacking the **verify** tarball so `build-linux/libMobileGL.so` is the verify library, `export MOBILEGL_PIPE_VERIFY=1`, `ctest --timeout 10800`, `timeout-minutes: 300`; matrix = the 8 `"verify": true` cases by default, the full 77 when `workflow_dispatch` input `verify_retrace=full`), and `run_trace_case.cmake`'s arming/divergence check. `remove-artifact-clutter` gains `retrace-verify` in `needs`. `MOBILEGL_BUILD_DISAGGREGATED` stays OFF in the verify build (poison comes from D9). | scout-test-infra B1/B2; `ENVIRONMENT`-property trap (`test.yml:252-259`, `MG_IntegrationTest/CMakeLists.txt:339-344`). |
|
||||
| D21 | **Integration registrations** (in `MG_IntegrationTest/CMakeLists.txt`, inside `if (MOBILEGL_PIPE_VERIFY)`): `DirectGLES.Verify.` / `DirectVulkan.Verify.` (all scenarios; `LABELS integration-gpu integration-verify`; `TIMEOUT 900`; env = backend + `MOBILEGL_PIPE_VERIFY=1` + `MOBILEGL_LOG_FILE_PATH=<binary dir>/pipe-verify-<backend>.log` + the mandatory `${MGL_ITEST_COMMON_ENV}` / `${MGL_ITEST_VULKAN_ENV}` tail), `*.VerifyCorrupted.` (filter `PipeVerifyArmingScenario.CorruptedFieldIsReported`; adds `MOBILEGL_PIPE_VERIFY_CORRUPT=GetRenderStateParameters` and `MOBILEGL_PIPE_VERIFY_FATAL=0`), `*.PoisonOmission.` (filter `PoisonOmissionScenario.*`; adds `MOBILEGL_PIPE_POISON_OMIT=GenerateMipmap:GetTextureUnitObject`). Name parity: `DirectGLES.Verify.<Suite>.<Case>` ↔ `DirectGLES.<Suite>.<Case>`. | `ARCHITECTURE.md:503` by-name parity; 120 s `TIMEOUT` property cannot be raised by `ctest --timeout` (`:393`). |
|
||||
| D22 | **`SnapshotFromGLContext` signature**: `void SnapshotFromGLContext(PipeInputs& out, const MGPipeFieldSet& fields, MG_State::GLState::GLContext& ctx, MGPipeVerb omissionContext)`; declared in `PipeInputs.h`, defined in `MG_Impl/Pipe/PipeFill.cpp`. Its two callers are the two branches P13 talks about: the filler (`MGPipeVerbScope`, deleted at P13 with the tracker in place) and the comparator (kept). | `ARCHITECTURE.md:369`. |
|
||||
| D23 | **Ownership of the 26 sync sites in P1: no code change.** Every `SyncPersistentMappedRange()`/`SyncGpuWrites()` call stays where it is; the `BufferObject` it is called on is reached through an aliased or copied field, so the calls are unaffected by the arm. The deliverable is the table `docs/Disaggregated/SYNC_SITES.md` (B.12): per site, the verb class whose scope contains it, the §5.7 reconcile row it implements, and the phase that moves it. The `*IndirectCount` sites keep "only `SyncPersistentMappedRange`" verbatim (`ROADMAP.md:88`). | `ARCHITECTURE.md:294`. |
|
||||
| D24 | **`PipeStats`** counters are untouched: the `AccessorCalls` tallies (`PipeStats.cpp:15-100` contract) count reads in either arm. The counter names are pinned by `PipeStatsTest.CounterNamesAreStable`. | |
|
||||
| D25 | **Threading**: `gPipeInputs` is a single global for the single GL thread (`pGLContext` is one global); the only backend reads that can run off the GL thread are pass-throughs (`RecordError`). `AttachPassthroughTessControlStage` (`Managers.cpp:7184`, reads patch state) runs from `SyncToBackend` at `:8070` on the GL thread inside `SyncCurrentProgram` (a Draw). Package B re-confirms that call chain while converting the site. | |
|
||||
| D26 | **Documentation** is integrator-owned (D.6); packages do not edit `docs/`. `feat/disaggregated` stays off the push triggers (`test.yml:3-9`); CI runs are `workflow_dispatch`. | P0.5 D10. |
|
||||
|
||||
### B.3 `PipeInputs` shape (core writes this; the accessor list is the whole 62)
|
||||
|
||||
```cpp
|
||||
// MobileGL/MG_Backend/MGPipe/PipeInputs.h
|
||||
#pragma once
|
||||
#ifndef MOBILEGL_MG_BACKEND_MGPIPE_PIPE_INPUTS_H
|
||||
#define MOBILEGL_MG_BACKEND_MGPIPE_PIPE_INPUTS_H
|
||||
#include <MG_Pipe/MGPipe.h> // field ids, verbs, fill sets, poison helpers, comparators
|
||||
#include <MG_Pipe/PipeStrangler.h>
|
||||
#if MOBILEGL_PIPE_PUSH
|
||||
#include <MG_State/GLState/Core.h> // phase A: the accessor types ARE the frontend's types.
|
||||
// Gate A (P13) keeps this include in verify builds only.
|
||||
#define MOBILEGL_PIPE_POISON (MOBILEGL_PIPE_VERIFY || MOBILEGL_BUILD_DISAGGREGATED || (MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG))
|
||||
namespace MobileGL::MG_Pipe {
|
||||
using MG_State::GLState::GLContext; // etc.
|
||||
struct PipeInputs;
|
||||
void SnapshotFromGLContext(PipeInputs& out, const MGPipeFieldSet& fields, GLContext& ctx, MGPipeVerb omissionContext);
|
||||
Bool MGPipeVerifyInputs(const PipeInputs& pushed, const PipeInputs& snapshot, const MGPipeFieldSet& fields, const char** outField);
|
||||
void ApplyVerifyCorruption(PipeInputs& snapshot, MGPipeInputField field);
|
||||
|
||||
struct PipeInputs {
|
||||
// ---- accessors: 62, signatures verbatim from Core.h (B.4) ----
|
||||
Int GetActiveTextureUnit() const; // V
|
||||
const FloatVec4& GetBlendColor() const; // V
|
||||
void GetBlendEquationIndexed(Uint, BlendEquation&, BlendEquation&) const; // V (stored per draw buffer)
|
||||
…
|
||||
BindingSlot<BufferObject>& GetBufferBindingSlot(BufferTarget); // R
|
||||
BindingSlotRange1D<BufferObject>& GetBufferBindingPoint(BufferTarget, Uint); // R
|
||||
TextureUnit& GetTextureUnitObject(Int); // R
|
||||
ImageTextureBinding& GetImageTextureBinding(Int); // R (+ const overload)
|
||||
const CurrentVertexAttributeValue& GetCurrentVertexAttribute(Uint) const; // R
|
||||
const SharedPtr<VertexArrayObject>& GetBoundVertexArray(); // H
|
||||
…
|
||||
const SharedPtr<ProgramObject>& GetProgramObject(Uint); // P
|
||||
void RecordError(ErrorCode, UniquePtr<ErrorInfo>); // P
|
||||
// ---- identity / pass-through plumbing ----
|
||||
GLContext* Frontend() const { return m_frontendResolver ? m_frontendResolver() : nullptr; }
|
||||
const void* FrontendIdentity() const { return Frontend(); }
|
||||
const char* CurrentVerbName() const;
|
||||
// ---- storage (public: PipeFill.cpp fills it; the unit test corrupts it) ----
|
||||
GLContext* (*m_frontendResolver)() = nullptr;
|
||||
MGPipeFilledState m_filled{};
|
||||
MGPipeVerb m_currentVerb = MGPipeVerb::kNone;
|
||||
Uint32 m_verbDepth = 0;
|
||||
Uint m_renderStateVersionCopied = ~0u; // memo key of the 1168-byte copy
|
||||
RenderStateParameters m_renderState{};
|
||||
… (one member per field, B.4)
|
||||
};
|
||||
extern PipeInputs gPipeInputs;
|
||||
static_assert(sizeof(PipeInputs) <= 8192, "PipeInputs grew past the P1 budget; a field moved to the wrong storage kind");
|
||||
}
|
||||
#endif
|
||||
#endif
|
||||
```
|
||||
|
||||
Accessor body pattern (generated by hand, one per field; the macros live in `PipeInputs.h`):
|
||||
|
||||
```cpp
|
||||
inline const FloatVec4& PipeInputs::GetBlendColor() const {
|
||||
MGP_POISON_CHECK(GetBlendColor); // no-op unless MOBILEGL_PIPE_POISON
|
||||
MGP_VERIFY_READ(GetBlendColor); // no-op unless MOBILEGL_PIPE_VERIFY && Features.PipeVerify (read-level compare, D11 b)
|
||||
return m_blendColor;
|
||||
}
|
||||
```
|
||||
|
||||
`MGP_VERIFY_READ` for an argument-taking accessor passes the argument so the re-pull is scoped (`MGP_VERIFY_READ_ARG(GetTextureUnitObject, unit)`); the implementation is `PipeInputs::VerifyRead(field, …)` in `PipeInputs.cpp`, which calls `SnapshotFromGLContext(tls_scratch, MGPipeFieldSet::Of(field), *Frontend(), MGPipeVerb::kNone)` and then the per-field compare.
|
||||
@@ -0,0 +1,116 @@
|
||||
# P1 pull-site catalogue — every backend read of frontend state
|
||||
|
||||
Tree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch `feat/disaggregated` @ `5635e33f`.
|
||||
Scope: `MobileGL/MG_Backend/**` (`.cpp` + `.h`), 55 files, both backends plus the shared `BackendObject.h` / `BackendObject.cpp` / `Init.cpp`.
|
||||
Every file:line below was opened; expressions are verbatim from the tree.
|
||||
|
||||
## 0. Headline counts (measured on THIS tree, not on the vendored inventory)
|
||||
|
||||
| what | count | how it was measured |
|
||||
|---|---|---|
|
||||
| lines containing `pGLContext` anywhere in `MG_Backend` | **332** | `grep -rn pGLContext --include=*.cpp --include=*.h` |
|
||||
| `pGLContext->` / `pGLContext.` **member-access sites** | **278** | regex `pGLContext\s*(?:->|\.)\s*(\w+)` over whole files, multi-hit lines counted once per hit |
|
||||
| lines mentioning `pGLContext` with **no** arrow on that line | **58** | `grep -v 'pGLContext->'` — matches the design's 58 exactly |
|
||||
| distinct GLContext accessors actually called | **62** (61 named accessors + one `.get()`) | histogram below |
|
||||
| `SyncPersistentMappedRange()` call sites | **20** | matches the design's 20 |
|
||||
| `SyncGpuWrites()` call sites | **6** | matches the design's 6 |
|
||||
| lines declaring/passing `SharedPtr<MG_State…>` or `WeakPtr<MG_State…>` | **177** (76 in headers, 101 in .cpp) | these are the "handle-ify" rows |
|
||||
| `GetLifetimeId()` reads on frontend objects | **39** | |
|
||||
| version reads (`GetChangeSerial` / `GetContentVersion` / `GetVersion`) | **36** | |
|
||||
| `BufferBackendOps` touchpoints | **17** lines in `MG_Backend` | 2 register calls + 2 tables + register/unregister plumbing |
|
||||
| other `MG_State::` globals reached by the backends | **0** | only `MG_State::pGLContext`; everything else is `MG_State::GLState::<type>` |
|
||||
|
||||
### 0.1 Drift against the vendored inventory — READ THIS FIRST
|
||||
|
||||
`scripts/data/backend_read_inventory.md:1-30` is a **stale, vendored** copy (generated by
|
||||
`extract_backend_read_inventory.py`, which lives in MobileGL-CS, not in this repo). It claims
|
||||
"pGLContext accesses: **293**", "SharedPtr<MG_State wire args: **167**", "scanned files: **57**",
|
||||
"total read points: 477". This tree has **278** arrow sites, **177** SharedPtr lines and **55**
|
||||
scannable files. The design's "293" is therefore an over-count of about 15 relative to the code
|
||||
P1 will actually edit; the "58 non-arrow lines" figure is exact.
|
||||
|
||||
Three concrete accessor-level drifts, each of which will bite a mechanical P1 sweep:
|
||||
|
||||
| drift | evidence |
|
||||
|---|---|
|
||||
| `GetBoundTransformFeedbackName` is a `MGPipeInputField` (`MG_Pipe/generated/PipeFilled.inc:32`) and a `Coverage.def` accessor (`MG_Pipe/Coverage.def:34`), but **no backend reads it any more**. Its only readers are the frontend (`MG_Impl/GLImpl/Drawing/GL_Drawing.cpp:1562`, `MG_Impl/GLImpl/Getter/GL_Getter.cpp:2678`). It is a dead PipeInputs field. | grep for the name over `MG_Backend` returns nothing |
|
||||
| `GetBoundTransformFeedbackLifetimeId` **is** read by a backend (`DirectVulkan/Renderer/VulkanRenderer.cpp:11219`) and is **absent** from both `PipeFilled.inc` and `Coverage.def`. | `MG_State/GLState/Core.h:441` declares it |
|
||||
| `HasOpenTransformFeedbackSpan` **is** read by a backend (`DirectVulkan/Renderer/VulkanRenderer.cpp:11236`) and is **absent** from both. | `MG_State/GLState/Core.h:450` declares it |
|
||||
|
||||
Net: the PipeInputs field set must go **61 → 62** (drop one dead field, add two real ones), and
|
||||
`Coverage.def`'s `MGP_COVERAGE_ACCESSOR_LIST` must gain the same two rows or `gen_pipe.py`'s
|
||||
coverage join will report them UNMAPPED.
|
||||
|
||||
Also note: there is **no** `MobileGL/MG_Pipe/generated/PipeInputs.inc`. The file the design means is
|
||||
`MobileGL/MG_Pipe/generated/PipeFilled.inc`; the 61 is asserted at `PipeFilled.inc:92`
|
||||
(`static_assert(kMGPipeInputFieldCount == 61, "the PipeInputs field set moved")`).
|
||||
|
||||
### 0.2 Accessor histogram (all 278 member-access sites)
|
||||
|
||||
| accessor | sites | accessor | sites |
|
||||
|---|---|---|---|
|
||||
| `GetBufferBindingSlot` | 29 | `GetPrimitiveRestartIndex` | 3 |
|
||||
| `IsCapabilityEnabled` | 29 | `GetProgramForDispatch` | 3 |
|
||||
| `GetFramebufferBindingSlot` | 19 | `GetProgramObject` | 3 |
|
||||
| `GetTextureUnitObject` | 19 | `GetScissorBox` | 3 |
|
||||
| `GetBoundVertexArray` | 12 | `GetTransformFeedbackProgram` | 3 |
|
||||
| `GetRenderStateParameters` | 11 | `ValidateProgramName` | 3 |
|
||||
| `GetBufferBindingPoint` | 9 | `GetCurrentVertexAttribute` | 2 |
|
||||
| `GetSamplingResolutionGeneration` | 9 | `GetRenderStateParametersVersion` | 2 |
|
||||
| `GetActiveTextureUnit` | 8 | `GetTouchedBufferBindingPointCount` | 2 |
|
||||
| `GetStencilState` | 8 | `GetTransformFeedbackPausedPrimitiveCounter` | 2 |
|
||||
| `GetImageTextureBinding` | 7 | `InvalidateCompileEnv` | 2 |
|
||||
| `GetProgramForDraw` | 7 | `IsTransformFeedbackPaused` | 2 |
|
||||
| `GetColorMaskIndexed` | 6 | `GetBlendColor` | 1 |
|
||||
| `GetPixelStoreParameters` | 6 | `GetBlendEquationIndexed` | 1 |
|
||||
| `GetTextureContextId` | 6 | `GetBlendFuncIndexed` | 1 |
|
||||
| `RecordError` | 6 | `GetBoundTransformFeedbackLifetimeId` | 1 |
|
||||
| `GetDepthMask` | 5 | `GetClampReadColor` | 1 |
|
||||
| `GetTextureBindGeneration` | 5 | `GetClearColor` | 1 |
|
||||
| `IsTransformFeedbackActive` | 5 | `GetClearDepth` | 1 |
|
||||
| `GetBufferBindingPointCount` | 3 | `GetClearStencil` | 1 |
|
||||
| `GetPatchDefaultInnerLevel` | 3 | `GetCullFaceMode` | 1 |
|
||||
| `GetPatchDefaultOuterLevel` | 3 | `GetDepthFunc` | 1 |
|
||||
| `GetPatchVertices` | 3 | `GetDepthRangeIndexed` | 1 |
|
||||
| `GetPipelineStateVersion` | 3 | `GetLineWidth` | 1 |
|
||||
| `GetLogicOp` | 1 | `GetMaxTouchedTextureUnit` | 1 |
|
||||
| `GetMinSampleShadingValue` | 1 | `GetPolygonModeFront` | 1 |
|
||||
| `GetPolygonOffsetFactor` | 1 | `GetPolygonOffsetUnits` | 1 |
|
||||
| `GetProvokingVertexMode` | 1 | `GetTextureObject` | 1 |
|
||||
| `GetTransformFeedbackCapturedVertices` | 1 | `GetTransformFeedbackGeneration` | 1 |
|
||||
| `GetViewport` | 1 | `GetViewportIndexed` | 1 |
|
||||
| `HasOpenTransformFeedbackSpan` | 1 | `IsCapabilityEnabledIndexed` | 1 |
|
||||
| `.get()` (raw context pointer) | 1 | | |
|
||||
|
||||
### 0.3 Per-file distribution of the 278 sites
|
||||
|
||||
| file | sites |
|
||||
|---|---|
|
||||
| `DirectVulkan/Renderer/VulkanRenderer.cpp` | 130 |
|
||||
| `DirectGLES/DirectGLES.cpp` | 92 |
|
||||
| `DirectGLES/Managers.cpp` | 15 |
|
||||
| `DirectVulkan/Renderer/UniformManager.cpp` | 14 |
|
||||
| `DirectVulkan/DirectVulkan.cpp` | 12 |
|
||||
| `DirectGLES/MultiDraw.cpp` | 5 |
|
||||
| `DirectVulkan/Renderer/VkRenderPassManager.cpp` | 3 |
|
||||
| `DirectGLES/Utils.cpp` | 2 |
|
||||
| `DirectVulkan/BackendObject_DirectVulkan.cpp` | 2 |
|
||||
| `DirectVulkan/Renderer/VkTextureManager.cpp` | 2 |
|
||||
| `DirectVulkan/Renderer/VkClearManager.cpp` | 1 |
|
||||
|
||||
(`DirectGLES/BackendObject_DirectGLES.cpp`, `DirectGLES/Utils.h`, `DirectGLES/Managers.h`,
|
||||
`DirectGLES/DirectGLES.h`, `DirectVulkan/DirectVulkan.h`, `DirectVulkan/Renderer/VulkanRenderer.h`,
|
||||
`.../UniformManager.h`, `.../VkBufferManager.*`, `.../VkSamplerManager.cpp`,
|
||||
`.../VertexInputStateFactory.*`, `.../ProgramFactory.*`, `.../PipelineFactory.*`,
|
||||
`.../FrameContext.*`, `.../SwapchainObject.*`, `BackendObject.h/.cpp`, `Init.cpp` contain **zero**
|
||||
`pGLContext` member accesses — they reach the frontend only through handles/objects, §2.)
|
||||
|
||||
---
|
||||
|
||||
## 1. The complete site catalogue
|
||||
|
||||
Legend for the `accessor` column: `_(non-arrow)_` marks one of the 58 lines that names `pGLContext`
|
||||
without dereferencing it on that line (null guards, asserts, ternary conditions, the raw-pointer
|
||||
cache, a comment). The `verb path` column names the verb boundary the site sits under; where a
|
||||
helper serves more than one verb the entry says so.
|
||||
|
||||
@@ -0,0 +1,331 @@
|
||||
---
|
||||
|
||||
## 2. The non-`pGLContext` paths by which a backend reaches frontend objects
|
||||
|
||||
`pGLContext` is the only `MG_State::` global the backends touch (§0, "other MG_State globals: 0").
|
||||
Every other reach is one of the five shapes below. P1 cannot succeed by rewriting only the 278
|
||||
arrow sites: the accessors return **references to live frontend objects**, and the backends then
|
||||
call ~200 distinct methods on those objects.
|
||||
|
||||
### 2.1 The one static cache of a frontend pointer
|
||||
|
||||
`MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:142-155` — the only place a raw `GLContext*` is
|
||||
stored across calls:
|
||||
|
||||
```
|
||||
142: using FbBindingSlot =
|
||||
143: std::remove_reference_t<decltype(MG_State::pGLContext->GetFramebufferBindingSlot(FramebufferTarget::Draw))>;
|
||||
144: static const MG_State::GLState::GLContext* g_fbSlotCacheContext = nullptr;
|
||||
145: static Array<FbBindingSlot*, SizeT(FramebufferTarget::FramebufferTargetCount)> g_fbSlotCache = {};
|
||||
146: static inline FbBindingSlot& GetFramebufferBindingSlotFast(FramebufferTarget target) {
|
||||
147: MG_State::GLState::GLContext* ctx = MG_State::pGLContext.get();
|
||||
148: if (ctx != g_fbSlotCacheContext) { ... &ctx->GetFramebufferBindingSlot(...) ... }
|
||||
```
|
||||
|
||||
It caches **interior pointers into the GLContext object** (the by-value binding-slot members),
|
||||
keyed on the raw context address. Under P1 this cache has no meaning across a pipe boundary — the
|
||||
slots are not addressable from the backend at all. Its five call sites are the hot framebuffer
|
||||
path and each is a `GetFramebufferBindingSlot` read that the arrow-site table does **not** list
|
||||
(they read through the cache, not through `pGLContext`):
|
||||
|
||||
| call site | enclosing function | verb path | what it reads |
|
||||
|---|---|---|---|
|
||||
| `DirectGLES/DirectGLES.cpp:1611` | `SyncNeccessaryTextures` | texture op (draw/dispatch) | draw FBO binding slot |
|
||||
| `DirectGLES/DirectGLES.cpp:1905` | `SyncCurrentFBO` | framebuffer sync | slot for `target` |
|
||||
| `DirectGLES/DirectGLES.cpp:2743` | `SyncCurrentProgram` | program/uniform sync | draw FBO binding slot |
|
||||
| `DirectGLES/DirectGLES.cpp:2858` | `BindCurrentFBO` | framebuffer sync | slot for `target` |
|
||||
| `DirectGLES/DirectGLES.cpp:2933` | `ForceBindCurrentFBO` | framebuffer sync | slot for `target` |
|
||||
|
||||
Each of those five also reads the slot's **version** (`BindingSlot::GetVersion()`) at
|
||||
`DirectGLES.cpp:1614`, `1917`, `2745`, `2936` — a value block P1 must carry alongside the handle.
|
||||
|
||||
There are **no** other `GLContext&`/`GLContext*` parameters or local aliases anywhere in
|
||||
`MG_Backend`: `grep -rn 'GLContext\s*[&*]' --include=*.cpp --include=*.h` returns exactly the one
|
||||
line 144 above once `pGLContext` matches are excluded.
|
||||
|
||||
### 2.2 `SharedPtr<MG_State::GLState::…>` in signatures and members (the "handle-ify" surface)
|
||||
|
||||
177 lines. The ones that matter structurally are the **table-level** ones (they are the verb
|
||||
signatures themselves) and the **member-level** ones (backend containers that own or weakly hold
|
||||
frontend objects across frames).
|
||||
|
||||
Table-level (these five `GLFunctionsTable` entries take frontend objects **by handle today**):
|
||||
|
||||
| declaration | file:line |
|
||||
|---|---|
|
||||
| `ClearNamedFramebufferfv(const SharedPtr<FramebufferObject>&, …)` | `BackendObject.h:158` |
|
||||
| `ClearNamedFramebufferfi(const SharedPtr<FramebufferObject>&, …)` | `BackendObject.h:160` |
|
||||
| `ClearNamedFramebufferiv(const SharedPtr<FramebufferObject>&, …)` | `BackendObject.h:162` |
|
||||
| `ClearNamedFramebufferuiv(const SharedPtr<FramebufferObject>&, …)` | `BackendObject.h:164` |
|
||||
| `BlitNamedFramebuffer(const SharedPtr<FramebufferObject>& read, const SharedPtr<FramebufferObject>& draw, …)` | `BackendObject.h:168-169` |
|
||||
| `GetTextureImage(const SharedPtr<ITextureObject>&, …)` | `BackendObject.h:186` |
|
||||
| `CopyImageSubData(const CopyImageEndpoint& src, …, const CopyImageEndpoint& dst, …)` where `CopyImageEndpoint` is `{SharedPtr<ITextureObject> Texture; SharedPtr<RenderbufferObject> Renderbuffer;}` | `BackendObject.h:33-38`, `BackendObject.h:176-180` |
|
||||
|
||||
Their per-backend mirrors: `DirectGLES/DirectGLES.h:60,62,64,66,70,71`;
|
||||
`DirectVulkan/DirectVulkan.h:36,38,40,42,76,77,101`;
|
||||
`DirectVulkan/Renderer/VulkanRenderer.h:184,186,188,190,195,196,256,1400`.
|
||||
|
||||
Member-level (backend state that outlives a verb and holds frontend objects):
|
||||
|
||||
| holder | file:line | what it holds |
|
||||
|---|---|---|
|
||||
| `UniformManager::m_fallbackTexture2D` | `Renderer/UniformManager.h:305` | `SharedPtr<ITextureObject>` — a synthesised frontend texture the backend itself created |
|
||||
| `UniformManager::m_fallbackMultisampleTextures` | `Renderer/UniformManager.h:308` | `UnorderedMap<Uint32, SharedPtr<ITextureObject>>` |
|
||||
| `UniformManager::m_unboundStorageImageTextures` | `Renderer/UniformManager.h:317` | `UnorderedMap<Uint64, SharedPtr<ITextureObject>>` |
|
||||
| `VkClearManager::m_aliveObjects` | `Renderer/VkClearManager.h:167` | `unordered_map<TextureIdentity, WeakPtr<ITextureObject>>` |
|
||||
| `VkTextureManager::m_aliveObjects` | `Renderer/VkTextureManager.h:725` | `unordered_map<TextureIdentity, WeakPtr<ITextureObject>>` |
|
||||
| `VkRenderPassManager` attachment records | `Renderer/VkRenderPassManager.h:45,51,330,359` | `WeakPtr<ITextureObject>` / `WeakPtr<RenderbufferObject>` |
|
||||
| `VulkanRenderer` blit/clear helper programs | `Renderer/VulkanRenderer.h:378,379,380,388` | `SharedPtr<ProgramObject>` + two `SharedPtr<SamplerObject>` the backend **constructs itself** |
|
||||
| DirectGLES raw-depth-fetch sampler | `DirectGLES/DirectGLES.cpp:55` (`static SharedPtr<SamplerObject> g_rawDepthFetchSamplerState`), built at `DirectGLES.cpp:150-160` | same pattern: backend-authored frontend object |
|
||||
|
||||
The last two rows are the P1 trap: these are frontend objects **created by the backend**, so under
|
||||
disaggregation the server has no frontend to create them in. They need either a server-local
|
||||
equivalent or a client-side create call.
|
||||
|
||||
### 2.3 The twin registries and the owner-keyed memos
|
||||
|
||||
`DirectGLES/Managers.h:271` `template <typename StateObject, typename BackendObject> class
|
||||
StateBackendObjectRegistry` — hash map **keyed on the raw frontend object pointer**
|
||||
(`using BackendMap = UnorderedMap<StateObject*, Entry>;`, `Managers.h:284`), each `Entry` holding
|
||||
`{BackendPtr backend; StateWeakPtr stateRef;}` (`Managers.h:280-283`). Liveness is decided by
|
||||
`entry.stateRef.expired()` (`Managers.h:318`, `Managers.h:339`).
|
||||
|
||||
Six instances, all reached by the draw path:
|
||||
|
||||
| registry | declared | keyed on |
|
||||
|---|---|---|
|
||||
| `VertexArrayImpl::g_backendVertexArrayObjects` | `Managers.h:803-804` | `VertexArrayObject*` |
|
||||
| `TextureImpl::g_backendTextureObjects` | `Managers.h:1124-1125` | `ITextureObject*` |
|
||||
| `FramebufferImpl::g_backendFramebufferObjects` | `Managers.h:1215-1216` | `FramebufferObject*` |
|
||||
| `PrgramImpl::g_backendProgramObjects` | `Managers.h:1733-1734` | `ProgramObject*` |
|
||||
| `SamplerImpl::g_backendSamplerObjects` | `Managers.h:1833-1834` | `SamplerObject*` |
|
||||
| `RenderbufferImpl::g_backendRenderbufferObjects` | `Managers.h:1860-1861` | `RenderbufferObject*` |
|
||||
|
||||
On top of them, `DirectGLES/DirectGLES.cpp:83-115` `class TwinLookupMemo` — a direct-mapped memo
|
||||
whose slot is `{StateObject* key; WeakPtr<StateObject> owner; BackendObject* twin;}`
|
||||
(`DirectGLES.cpp:100-104`), indexed by Fibonacci-hashing the **frontend heap address**
|
||||
(`DirectGLES.cpp:108-112`), validated by `OwnerEquals` (`DirectGLES.cpp:62-65`, a
|
||||
`weak_ptr::owner_before` pair test). Three instances: `g_vaoTwinLookupMemo`
|
||||
(`DirectGLES.cpp:122-123`), `g_programTwinLookupMemo` (`DirectGLES.cpp:124-125`),
|
||||
`g_fboTwinLookupMemo` (`DirectGLES.cpp:130-131`); looked up at `DirectGLES.cpp:1204`, `2767`,
|
||||
`2872` and stored at `1212`, `2775`, `2877`.
|
||||
|
||||
**Both mechanisms are pointer-identity based and cannot survive a process/thread split.** P1 has to
|
||||
replace "frontend heap address + `weak_ptr` owner equality" with the wire handle plus a lifetime
|
||||
id. The good news is that the frontend already exposes exactly that: `GetLifetimeId()` (§2.4).
|
||||
|
||||
### 2.4 Lifetime-id and version reads (the memo keys P1 must carry over the wire)
|
||||
|
||||
39 `GetLifetimeId()` reads:
|
||||
|
||||
| object kind | sites |
|
||||
|---|---|
|
||||
| program | `DirectGLES/DirectGLES.cpp:3333`, `3349`; `DirectVulkan/DirectVulkan.cpp:163`; `Renderer/UniformManager.cpp:482`, `696`, `2272`, `2384`, `2732`; `Renderer/VulkanRenderer.cpp:6044`, `6484`, `6524`, `6577`, `6648`, `6962` |
|
||||
| texture | `Renderer/UniformManager.cpp:656`, `1746`, `1792`; `Renderer/VkClearManager.cpp:155`, `197`, `251`, `368`, `459`; `Renderer/VkRenderPassManager.cpp:642`; `Renderer/VkTextureManager.cpp:235`, `733` |
|
||||
| sampler | `Renderer/UniformManager.cpp:654`, `1747`, `1793` |
|
||||
| VAO | `Renderer/VertexInputStateFactory.cpp:48` (via `attr.Buffer`, actually a buffer); `Renderer/VulkanRenderer.cpp:3552`, `6107`, `6384`, `6965` |
|
||||
| FBO | `Renderer/VkRenderPassManager.cpp:844`, `869`; `Renderer/VulkanRenderer.cpp:6112`, `6968` |
|
||||
| buffer | `DirectGLES/Managers.cpp:2678`; `Renderer/VertexInputStateFactory.cpp:48` |
|
||||
|
||||
36 version reads:
|
||||
|
||||
| version | sites | what it gates |
|
||||
|---|---|---|
|
||||
| `BindingSlot::GetVersion()` (framebuffer slot) | `DirectGLES/DirectGLES.cpp:1614`, `1917`, `2745`, `2936` | the FBO-sync short-circuit (`g_fboSyncedSlotVersions`) |
|
||||
| `BindingSlot::GetVersion()` (VAO index-buffer slot) | `DirectGLES/Managers.cpp:2307` | element-array rebind |
|
||||
| `BufferObject::GetChangeSerial()` | `DirectGLES/Managers.cpp:794`, `1078`, `1151`, `1163`, `1203`, `1238`, `1245`, `1283`, `1468`, `1553`, `1580`, `1581`, `2679`; `Renderer/VkBufferManager.cpp:697`; `Renderer/VulkanRenderer.cpp:3849` | every buffer upload/re-upload decision on both backends |
|
||||
| `ITextureObject::GetContentVersion()` | `DirectGLES/Managers.cpp:3649`, `3776`, `3826`, `4731`; `Managers.h:1012`; `Renderer/VkTextureManager.cpp:1646`, `1755`; `Renderer/VulkanRenderer.cpp:6293`, `7016` | texture upload short-circuit + the draw-time content-sum memo |
|
||||
| `SamplerObject::GetVersion()` | `DirectGLES/Managers.cpp:4756`, `8534`; `Managers.h:1016`; `Renderer/UniformManager.cpp:655`; `Renderer/VkSamplerManager.cpp:401` | sampler twin re-sync |
|
||||
| `ITextureObject::GetShapeVersion()` | `Renderer/VkTextureManager.cpp:1647`, `1756` | image recreate decision |
|
||||
| `ITextureObject::GetTextureParamsVersion()` | 14 sites, e.g. `DirectGLES/Managers.cpp:3647`, `3777`, `3847` | texture-parameter re-push |
|
||||
| `ProgramObject::GetBackendStateVersion()` / `GetLinkVersion()` / `GetImageUnitVersion()` / `GetUBOContentVersion()` / `GetBlockBindingVersion()` | `DirectGLES/DirectGLES.cpp:3335`, `3350`, `3540`, `2798`, `2799`, `3715`, `3401`; `Renderer/UniformManager.cpp:2273`; `DirectVulkan/DirectVulkan.cpp:165` | program twin re-sync + UBO re-upload |
|
||||
| `VertexArrayObject::GetConfigVersion()` | `DirectGLES/DirectGLES.cpp:1258`, `2962`; `DirectGLES/Managers.cpp:2306` | VAO re-emit |
|
||||
| `FramebufferObject::GetObjectVersion()` | `DirectGLES/DirectGLES.cpp:1615`, `1918`, `2937` | FBO twin re-sync |
|
||||
|
||||
### 2.5 `BufferBackendOps` — the reverse (frontend → backend) immediate-op table
|
||||
|
||||
Declared `MobileGL/MG_State/GLState/BufferState/BufferObject.h:76-123`; seven function pointers:
|
||||
`Respecify`, `SubData`, `ResidentSubData`, `FlushMappedRange`, `OnDestroy`, `AcquirePersistentMap`,
|
||||
`ReadbackFromGpu`. Every one takes `BufferObject&` — a **frontend object by reference**, and the
|
||||
callee reads the frontend shadow through it.
|
||||
|
||||
| backend | table | registered | unregistered |
|
||||
|---|---|---|---|
|
||||
| DirectGLES | `g_glesBufferBackendOps` (`DirectGLES/Managers.cpp:1351-1361`, all seven filled, each wrapped in a `…Tracked` shim that bumps the buffer-mutation epoch) | `Managers.cpp:1374-1379` `RegisterBufferBackendOps()`, called from `DirectGLES/BackendObject_DirectGLES.cpp:849` and `DirectGLES/DirectGLES.cpp:10063` | `Managers.cpp:1381-1392`, also from `OnBackendContextDestroyed` (`Managers.cpp:1397`) |
|
||||
| DirectVulkan | `g_vulkanBufferBackendOps` (`Renderer/VkBufferManager.cpp:106-113`, **six** filled — `ResidentSubData` is left null) | `Renderer/VkBufferManager.cpp:132` inside `VkBufferManager::Initialize` | `Renderer/VkBufferManager.cpp:139-141` inside `Shutdown` |
|
||||
|
||||
The epoch the GLES shims maintain (`Managers.cpp:1362-1372`, `CurrentBufferMutationEpoch` /
|
||||
`BumpBufferMutationEpoch`) is itself a frontend-write-visibility signal the draw path memos read.
|
||||
|
||||
### 2.6 Backend → frontend **writes** (not pulls, but the same coupling, and P1 must not miss them)
|
||||
|
||||
These are calls the backend makes that mutate a frontend object. They are the mirror image of the
|
||||
pull sites and a pipe with only a pull direction will silently drop them:
|
||||
|
||||
| method on frontend object | sites |
|
||||
|---|---|
|
||||
| `BufferObject::MarkGpuWritten()` | `DirectGLES/DirectGLES.cpp:510`, `1828`; `Renderer/UniformManager.cpp:1074`, `1230` |
|
||||
| `BufferObject::SetBackendResource()` | `DirectGLES/Managers.cpp:1015`, `1482`; `Renderer/VkBufferManager.cpp:297` (+1) |
|
||||
| `BufferObject::EnsureGpuResidentStorage()` | `Renderer/UniformManager.cpp:1072`, `1228`; `Renderer/VulkanRenderer.cpp:11326` |
|
||||
| `BufferObject::WritebackFromBackend()` | `DirectGLES/Managers.cpp:1279` |
|
||||
| `ITextureObject::AllocateStorage()` / `MarkStorageDirty()` / `TruncateMipmapLevels()` / `SetInternalFormat()` / `SetSamples()` / `SetFixedSampleLocations()` | `DirectGLES/DirectGLES.cpp:6326`, `6327`; `Renderer/UniformManager.cpp:1484`, `1489`, `1490`, `1496`, `1497`, `1498`, `1625`, `1628`, `1635` |
|
||||
| `ProgramObject::SetDrawID()` / `SetBaseVertex()` / `SetBaseInstance()` / `SetViewportPassMask()` | `DirectGLES/DirectGLES.cpp:3683`, `3689`, `3677`, `3813` |
|
||||
| `ProgramObject::AttachShader()` / `Link()` / `MarkUBOContentDirty()` / `SetBackendHashMemo()` | `Renderer/VulkanRenderer.cpp:4233`, `4234`, `4235`, `4313`, `4315`, `4665`, `8564`; `Renderer/ProgramFactory.cpp:3448` |
|
||||
| `VertexArrayObject::SetBackendHashMemo()` / `SetBackendStateMemo()` / `SetBackendAuxMemo()` | `Renderer/VertexInputStateFactory.cpp:60`, `78`, `83` |
|
||||
| `SamplerObject::SetWrapS/T/R`, `SetMinFilter`, `SetMagFilter`, `SetMipmapMode`, `SetLodRange` | `Renderer/VulkanRenderer.cpp:4270-4276` |
|
||||
| `GLContext::RecordError()` | 6 sites, §3 accessor `RecordError` |
|
||||
| `GLContext::InvalidateCompileEnv()` | 2 sites, §3 accessor `InvalidateCompileEnv` |
|
||||
|
||||
### 2.7 Frontend-object method surface reached through the pulled references
|
||||
|
||||
Counted by receiver-name heuristic over `MG_Backend/**` (excludes comment lines). This is the size
|
||||
of the "handle + value block" problem P1 inherits once the arrow sites are replaced:
|
||||
|
||||
| frontend class | distinct methods called | call sites | top methods |
|
||||
|---|---|---|---|
|
||||
| `BufferObject` | 16 | 169 | `GetSize` 50, `MappedData` 42, `SyncPersistentMappedRange` 20, `GetChangeSerial` 15, `GetBackendResource` 11, `SyncGpuWrites` 6 |
|
||||
| `ITextureObject` | 38 | 411 | `GetExternalIndex` 147, `GetTarget` 48, `GetFormat` 47, `GetTextureParamsVersion` 14, `GetStorageType` 11, `IsTextureView` 11, `GetLifetimeId` 10 |
|
||||
| `ProgramObject` | 56 | 275 | `GetExternalIndex` 69, `GetLifetimeId` 14, `GetLinkStatus` 14, `GetUBOSize` 14, `GetUniformLocation` 12, `GetUniformSamplerOrImageUnitIndex` 10 |
|
||||
| `FramebufferObject` | 9 | 115 | `GetAttachment` 39, `GetExternalIndex` 19, `IsDefaultFramebuffer` 18, `GetDrawBuffers` 16, `GetReadBuffer` 8, `GetObjectVersion` 7 |
|
||||
| `SamplerObject` | 26 | 52 | `GetVersion` 5, `GetAllSamplerParameters` 3, then one-per-parameter getters (`GetWrapS/T/R`, `GetMinFilter`, …) |
|
||||
| `VertexArrayObject` | 12 | 40 | `GetIndexBufferBindingSlot` 11, `GetAttribute` 6, `GetConfigVersion` 6, `GetBackendHashMemo` 4, `GetLifetimeId` 4 |
|
||||
|
||||
Total ≈ **1062** method calls on frontend objects across 157 distinct methods. `MGPResourceDesc`,
|
||||
`MGPProgramDesc`, `MGPSamplerDesc`, `MGPFramebufferState` and `MGPVertexElements` in
|
||||
`MG_Pipe/PipeFields.def` are the intended replacements; the field lists there are visibly narrower
|
||||
than this surface, which is the second thing P1 has to reconcile.
|
||||
|
||||
---
|
||||
|
||||
## 3. (a) The `PipeInputs` accessor surface
|
||||
|
||||
Return types are from `MobileGL/MG_State/GLState/Core.h` (the `GLContext` class body starts at
|
||||
`Core.h:61`). "sites" is the count from §0.2; full site lists are in §1.
|
||||
|
||||
### 3.1 Accessors that return a **handle to a frontend object** (must become an `MGPipeHandle`)
|
||||
|
||||
| accessor | signature (Core.h) | sites | verb paths served |
|
||||
|---|---|---|---|
|
||||
| `GetBufferBindingSlot` | `BindingSlot<BufferObject>& GetBufferBindingSlot(BufferTarget)` — `Core.h:78` | 29 | draw (indirect/parameter), dispatch (indirect), readback (PixelPack), buffer op (`SyncBoundBuffer`) |
|
||||
| `GetBufferBindingPoint` | `BindingSlotRange1D<BufferObject>& GetBufferBindingPoint(BufferTarget, Uint)` — `Core.h:79` | 9 | buffer op (SSBO/UBO/atomic), xfb, program/uniform sync (descriptor) |
|
||||
| `GetFramebufferBindingSlot` | `BindingSlot<FramebufferObject>& GetFramebufferBindingSlot(FramebufferTarget)` — `Core.h:473` | 19 (+5 via the fast cache, §2.1) | framebuffer sync, clear, blit, readback, draw, pipeline build |
|
||||
| `GetTextureUnitObject` | `TextureUnit& GetTextureUnitObject(Int)` — `Core.h:120` | 19 | texture op, program/uniform sync (descriptor) |
|
||||
| `GetImageTextureBinding` | `ImageTextureBinding& GetImageTextureBinding(Int)` (+ const overload) — `Core.h:121-122` | 7 | texture op (image unit), program/uniform sync (storage image/texel) |
|
||||
| `GetBoundVertexArray` | `const SharedPtr<VertexArrayObject>& GetBoundVertexArray()` — `Core.h:102` | 12 | vertex sync, draw |
|
||||
| `GetProgramForDraw` | `const SharedPtr<ProgramObject>& GetProgramForDraw()` — `Core.h:174` | 7 | draw, program/uniform sync |
|
||||
| `GetProgramForDispatch` | `const SharedPtr<ProgramObject>& GetProgramForDispatch()` — `Core.h:179` | 3 | dispatch |
|
||||
| `GetProgramObject` | `const SharedPtr<ProgramObject>& GetProgramObject(Uint)` — `Core.h:159` | 3 | program/uniform sync (`ShaderStorageBlockBinding`, `GetBackendProgramId`) |
|
||||
| `GetTextureObject` | `const SharedPtr<ITextureObject>& GetTextureObject(Uint)` — `Core.h:110` | 1 | texture op (`VkTextureManager::SyncTextureAndGetDescriptor` liveness check) |
|
||||
| `GetTransformFeedbackProgram` | `const SharedPtr<ProgramObject>& GetTransformFeedbackProgram() const` — `Core.h:329` | 3 | xfb |
|
||||
| `GetCurrentVertexAttribute` | `const CurrentVertexAttributeValue& GetCurrentVertexAttribute(Uint)` — `Core.h:106` | 2 | vertex sync |
|
||||
|
||||
**The four in bold below return a reference to a mutable slot, not a value**, so a `PipeInputs`
|
||||
accessor cannot simply copy them: `GetBufferBindingSlot`, `GetBufferBindingPoint`,
|
||||
`GetFramebufferBindingSlot`, `GetTextureUnitObject`. Every call site immediately follows with
|
||||
`.GetBoundObject()`, `.GetRange()`, `.GetVersion()` or `.GetSamplerObject()`; those are the value
|
||||
blocks P1 must materialise. `PipeFields.def` already models them as `MGPVertexBuffer`,
|
||||
`MGPIndexBuffer`, `MGPIndirectBuffers`, `MGPBufferRange`, `MGPShaderBuffers`, `MGPBoundView`,
|
||||
`MGPSamplerViews`, `MGPImageView`, `MGPFramebufferState`.
|
||||
|
||||
### 3.2 Accessors that return a **plain value** (a `PipeInputs` field can hold them verbatim)
|
||||
|
||||
| accessor | return type (Core.h line) | sites |
|
||||
|---|---|---|
|
||||
| `GetActiveTextureUnit` | `Int` (146) | 8 |
|
||||
| `GetBlendColor` | `const FloatVec4&` (278) | 1 |
|
||||
| `GetBlendEquationIndexed` | `void(Uint, BlendEquation&, BlendEquation&)` — **out-params** (255) | 1 |
|
||||
| `GetBlendFuncIndexed` | `void(Uint, BlendFactor&×4)` — **out-params** (250) | 1 |
|
||||
| `GetBufferBindingPointCount` | `constexpr SizeT(BufferTarget)` (80) | 3 |
|
||||
| `GetTouchedBufferBindingPointCount` | `SizeT(BufferTarget)` (86) | 2 |
|
||||
| `GetClampReadColor` | `GLenum` (235) | 1 |
|
||||
| `GetClearColor` | `const FloatVec4&` (272) | 1 |
|
||||
| `GetClearDepth` | `Float` (274) | 1 |
|
||||
| `GetClearStencil` | `Uint32` (276) | 1 |
|
||||
| `GetColorMaskIndexed` | `BoolVec4(Uint)` (270) | 6 |
|
||||
| `GetCullFaceMode` | `CullFaceMode` (294) | 1 |
|
||||
| `GetDepthFunc` | `DepthTestFunc` (259) | 1 |
|
||||
| `GetDepthMask` | `Bool` (261) | 5 |
|
||||
| `GetDepthRangeIndexed` | `const FloatVec2&(Uint)` (282) | 1 |
|
||||
| `GetLineWidth` | `Float` (211) | 1 |
|
||||
| `GetLogicOp` | `LogicOperation` (257) | 1 |
|
||||
| `GetMaxTouchedTextureUnit` | `Int` (126) | 1 |
|
||||
| `GetMinSampleShadingValue` | `Float` (289) | 1 |
|
||||
| `GetPatchDefaultInnerLevel` | `const FloatVec2&` (219) | 3 |
|
||||
| `GetPatchDefaultOuterLevel` | `const FloatVec4&` (217) | 3 |
|
||||
| `GetPatchVertices` | `Uint` (215) | 3 |
|
||||
| `GetPixelStoreParameters` | `PixelStoreParameters(Bool isUnpack)` (292) | 6 (all with `isUnpack=false`) |
|
||||
| `GetPolygonModeFront` | `GLenum` (237) | 1 |
|
||||
| `GetPolygonOffsetFactor` | `Float` (222) | 1 |
|
||||
| `GetPolygonOffsetUnits` | `Float` (223) | 1 |
|
||||
| `GetPrimitiveRestartIndex` | `Uint32` (240) | 3 |
|
||||
| `GetProvokingVertexMode` | `ProvokingVertexMode` (298) | 1 |
|
||||
| `GetRenderStateParameters` | `const RenderStateParameters&` (205) | 11 |
|
||||
| `GetScissorBox` | `const IntVec4&` (300) | 3 |
|
||||
| `GetStencilState` | `const StencilFaceState&(StencilFace)` (266) | 8 |
|
||||
| `GetViewport` | `IntVec4` (207) | 1 |
|
||||
| `GetViewportIndexed` | `const FloatVec4&(Uint)` (209) | 1 |
|
||||
| `IsCapabilityEnabled` | `Bool(CapabilityInput)` (242) | 29 |
|
||||
| `IsCapabilityEnabledIndexed` | `Bool(CapabilityInput, Uint)` (244) | 1 |
|
||||
| `IsTransformFeedbackActive` | `Bool` (325) | 5 |
|
||||
| `IsTransformFeedbackPaused` | `Bool` (326) | 2 |
|
||||
| `HasOpenTransformFeedbackSpan` | `Bool(Uint64 lifetimeId)` (450) — **NOT in PipeFilled.inc** | 1 |
|
||||
| `ValidateProgramName` | `Bool(Uint) const` (157) — pseudo-call `kClientResolved` | 3 |
|
||||
|
||||
The 14 distinct `CapabilityInput` values the 30 capability reads ask for (P1's `CapabilityBits`
|
||||
block, which `PipeFields.def` already names in `MGP_FIELDS_ResidualValueBlock`): `FramebufferSrgb`,
|
||||
`RasterizerDiscard`, `PrimitiveRestart`, `PrimitiveRestartFixedIndex`, `Multisample`, `SampleMask`,
|
||||
`CullFace`, `DepthTest`, `PolygonOffsetFill`, `ColorLogicOp`, `StencilTest`, `SampleShading`,
|
||||
`ScissorTest`, `Blend` (only via `IsCapabilityEnabledIndexed`).
|
||||
|
||||
### 3.3 Accessors that return a **version / generation counter** (memo keys)
|
||||
|
||||
| accessor | return type (Core.h line) | sites | memo it keys |
|
||||
|---|---|---|---|
|
||||
| `GetPipelineStateVersion` | `Uint` (204) | 3 | Vulkan pipeline cache + fast-path snapshot |
|
||||
| `GetRenderStateParametersVersion` | `Uint` (202) | 2 | GLES render-state shadow, Vulkan dynamic-state tail |
|
||||
| `GetTextureBindGeneration` | `Uint64` (130) | 5 | per-draw sampled-texture set |
|
||||
| `GetSamplingResolutionGeneration` | `Uint64` (136) | 9 | mipmap-completeness re-resolve |
|
||||
| `GetTextureContextId` | `Uint64` (143) | 6 | disambiguates a recreated context at the same address |
|
||||
| `GetTransformFeedbackGeneration` | `Uint64` (334) | 1 | xfb counter-buffer rebind |
|
||||
| `GetTransformFeedbackCapturedVertices` | `Uint64` (357) | 1 | GLES scatter-capture record count |
|
||||
| `GetTransformFeedbackPausedPrimitiveCounter` | `Uint64` (349) | 2 | xfb primitives-written query |
|
||||
| `GetBoundTransformFeedbackLifetimeId` | `Uint64` (441) — **NOT in PipeFilled.inc** | 1 | Vulkan xfb counter-slot ownership |
|
||||
|
||||
### 3.4 Non-read accessors (reverse channel / client-resolved)
|
||||
|
||||
| accessor | signature | sites | Coverage.def classification |
|
||||
|---|---|---|---|
|
||||
| `RecordError` | `void(ErrorCode, UniquePtr<ErrorInfo>)` — `Core.h:66` | 6 | `kReverseChannel` |
|
||||
| `InvalidateCompileEnv` | `void()` — `Core.h:506` | 2 | `kClientResolved` |
|
||||
| `ValidateProgramName` | `Bool(Uint) const` — `Core.h:157` | 3 | `kClientResolved` |
|
||||
|
||||
### 3.5 Reconciliation with `PipeFilled.inc`'s 61 fields
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| fields in `PipeFilled.inc` (`generated/PipeFilled.inc:28-90`, asserted at `:92`) | **61** |
|
||||
| distinct accessors read by the backends on this tree | **61** (+`.get()`) |
|
||||
| in `PipeFilled.inc` but **never read by a backend** | 1 — `GetBoundTransformFeedbackName` (`PipeFilled.inc:32`) |
|
||||
| read by a backend but **absent from `PipeFilled.inc`** | 2 — `GetBoundTransformFeedbackLifetimeId`, `HasOpenTransformFeedbackSpan` |
|
||||
| corrected field count for P1 | **62** |
|
||||
|
||||
Additional structural gaps that PipeInputs-as-generated does not model, all of which have real
|
||||
sites:
|
||||
|
||||
1. **`.get()` on the context itself** (`DirectGLES.cpp:147`) has no accessor to map to; the whole
|
||||
`GetFramebufferBindingSlotFast` cache (`DirectGLES.cpp:142-155`, 5 call sites) must be deleted
|
||||
or rebuilt on handles.
|
||||
2. **Slot version reads** (`BindingSlot::GetVersion()`, 5 sites, §2.4) ride on
|
||||
`GetFramebufferBindingSlot`/`GetBoundVertexArray` and are not separate fields today;
|
||||
`MGP_FIELDS_MGPBindRenderState` has a `Version` and `MGP_FIELDS_MGPFramebufferState` has a
|
||||
`ContentHash`, but no field carries a framebuffer **binding-slot** version.
|
||||
3. **`GetBufferBindingSlot` is polymorphic over `BufferTarget`** — `Coverage.def:37-42` already
|
||||
flags this ("its rows split across set_vertex_buffers, set_index_buffer, set_indirect_buffers
|
||||
and set_shader_buffers once the inventory carries the target argument (P1)"). The five targets
|
||||
actually asked for are `DrawIndirect` (13 sites), `Parameter` (4), `PixelPack` (7),
|
||||
`DispatchIndirect` (1), plus a runtime `target` parameter at `DirectGLES.cpp:518`
|
||||
(`SyncBoundBuffer`, called with `DrawIndirect` @`:664` and `DispatchIndirect` @`:691`).
|
||||
4. **`GetBufferBindingPoint` is likewise polymorphic**: `TransformFeedback` (3), `ShaderStorage`
|
||||
(1), `AtomicCounter` (1), `Uniform` (2), plus a runtime `target`/`bufferTarget` at
|
||||
`DirectGLES.cpp:370` and `UniformManager.cpp:1194`.
|
||||
|
||||
@@ -0,0 +1,214 @@
|
||||
---
|
||||
|
||||
## 4. (b) Verb-boundary entry points, and which accessors are reachable from each
|
||||
|
||||
The verb boundary is `struct GLFunctionsTable` (`MobileGL/MG_Backend/BackendObject.h:117-289`) —
|
||||
**69 function pointers plus one plain `Bool` policy flag** (`PrefersCpuXfbPrimitiveAccounting`,
|
||||
`BackendObject.h:265`) — wrapped by `struct GlobalBackendFunctionsTable`
|
||||
(`BackendObject.h:293-300`), which adds `Present` (`:295`) and `SetSwapInterval` (`:298`).
|
||||
**72 entries total.** Both tables are filled once, lazily, in
|
||||
`BackendObject_DirectGLES::GetBackendFunctions()` (`DirectGLES/BackendObject_DirectGLES.cpp:1230-1325`)
|
||||
and `BackendObject_DirectVulkan::GetBackendFunctions()` (`DirectVulkan/BackendObject_DirectVulkan.cpp:694-777`).
|
||||
|
||||
### 4.1 Fill-site differences between the two backends (a per-verb fill/validate must cope with both)
|
||||
|
||||
| entry | DirectGLES | DirectVulkan |
|
||||
|---|---|---|
|
||||
| `GetTextureImage` | **not filled** | `BackendObject_DirectVulkan.cpp:736` |
|
||||
| `PatchParameteri` | `BackendObject_DirectGLES.cpp:1319` | **not filled** |
|
||||
| `BeginTransformFeedback` / `End` / `Pause` / `Resume` / `Bind` / `Delete` | `:1320-1325` (all six, `XfbImpl::*`) | **none filled** — Magma drives capture from its own draw recording |
|
||||
| `PrefersCpuXfbPrimitiveAccounting` | `= true` at `:1312` | left `false` |
|
||||
| `SetSwapInterval` | `:1231` | **not filled** |
|
||||
| `Present` | `:1230` | `:698` |
|
||||
| timer-query group (`IsTimerQuerySupported`…`GetGpuTimestampNs`) | `:1292-1296` + `:1313-1315`, gated on `AreTimerQueriesSupported()` | `:754-761`, gated on `!MG_Config::Features.DisableTimerQuery` |
|
||||
|
||||
### 4.2 Verb → reachable accessors
|
||||
|
||||
Reachability was traced by following the helper call graph out of each entry point (caller greps
|
||||
cited in §4.3). "direct" = the site's enclosing function is the entry point itself.
|
||||
|
||||
#### DirectGLES (Espryt)
|
||||
|
||||
| verb entry point (impl) | reachable accessors |
|
||||
|---|---|
|
||||
| `DrawArrays` (`DirectGLES.cpp:4564`) | direct: `GetBoundVertexArray`. Via `PrepareForDraw`: everything in the draw closure below. |
|
||||
| `DrawElements`, `DrawElementsBaseVertex`, `DrawElementsInstanced*`, `DrawRangeElements*`, `DrawArraysInstanced*` (`DirectGLES.cpp:4556-4931`, 14 `PrepareForDraw` call sites) | the draw closure + `ResolveRestartSubstitution`/`ScopedRestartIndexSubstitution` (`IsCapabilityEnabled`×2, `GetPrimitiveRestartIndex`×2) + `BoundElementArrayBuffer` (`GetBoundVertexArray`) |
|
||||
| `MultiDrawArrays` (`:4597`) | direct `GetBoundVertexArray`; + draw closure |
|
||||
| `MultiDrawElementsIndirect` (`:4646`), `MultiDrawArraysIndirect` (`:4754`), `DrawElementsIndirect` (`:4956`), `DrawArraysIndirect` (`:5003`) | direct `GetBufferBindingSlot(DrawIndirect)`; + draw closure; + `ResolveIndirectCommandBytes` (`:261`) |
|
||||
| `MultiDrawElementsIndirectCount` (`:4685`), `MultiDrawArraysIndirectCount` (`:4793`) | direct `GetBufferBindingSlot(DrawIndirect)` **and** `(Parameter)`; + draw closure |
|
||||
| **the draw closure** = `PrepareForDraw` (`:2949`) | `GetBoundVertexArray` (`:2957`), `GetProgramForDraw` (`:2968`) → `SyncNeccessaryBuffers` (`:538`→`GetBufferBindingSlot`), `CaptureDrawTextureSyncKeys` (`:1513`→`GetTextureContextId`, `GetMaxTouchedTextureUnit`, `GetSamplingResolutionGeneration`), `SyncNeccessaryTextures` (`:1527`→`GetTextureUnitObject`, fb-slot fast cache), `SyncCurrentVertexAttributeValues` (`:1237`→`GetBoundVertexArray`, `GetCurrentVertexAttribute`), `SyncRenderState` (`:2022`→`GetRenderStateParametersVersion`, `GetRenderStateParameters`, `GetViewport`, `IsCapabilityEnabled`), `SyncCurrentProgram` (`:2722`→`GetPatchVertices`, `GetPatchDefaultOuterLevel`, `GetPatchDefaultInnerLevel`, fb-slot fast cache), `BindCurrentProgramWithResources` (`:3371`→`GetBufferBindingPoint(Uniform)`, `GetTextureUnitObject`), `BindCurrentTextures` (`:3299/:3361`→`GetProgramForDraw`), `ResolveAndBindUnitTextures` (`:3023`→`GetTextureUnitObject`), `BindCurrentUnitSamplers` (`:3200`→`GetTextureUnitObject`), `SyncBufferBindingPoints` (`:351`→`GetTouchedBufferBindingPointCount`, `GetBufferBindingPoint`), `MarkShaderStorageBuffersGpuWritten` (`:460`), `SyncAtomicCounterBuffers` (`:470`), `SyncBoundBuffer` (`:514`), `BeginViewportRoutingPasses` (`:3792`→`IsTransformFeedbackActive`, `IsCapabilityEnabled`, `GetRenderStateParameters`), `XfbImpl::StartPendingTransformFeedback` (`:981`→`GetTransformFeedbackProgram`, `GetBufferBindingPoint(TransformFeedback)`), `CurrentProgramMayNeedPerSubDrawBuiltins` (`:3711`), `GetCurrentBackendProgram` (`:3661`) |
|
||||
| `DispatchCompute` (`:6983`), `DispatchComputeIndirect` (`:6991`) | `PrepareForCompute` (`:4054`) → `GetProgramForDispatch`, plus `CaptureDrawTextureSyncKeys`, `SyncNeccessaryTextures`, `BindCurrentProgramWithResources`, `SyncBufferBindingPoints`, `MarkShaderStorageBuffersGpuWritten`, `SyncBoundBuffer(DispatchIndirect)`, `MarkWritableImageBufferTexturesGpuWritten` (`:1816`) |
|
||||
| `Clear` (`:4111`) | direct `GetRenderStateParameters` (`:4156`), `GetFramebufferBindingSlot(Draw)` (`:4215`); + `SyncRenderState(forColorClear)` (`:4121`), `SyncNeccessaryTextures` (`:4115`) |
|
||||
| `ClearBufferfv/iv/uiv/fi` (`:7424`, `:7437`, `:7453`, `:7469`, `:7506`) | `SyncNeccessaryTextures` + `SyncRenderState(forColorClear)`; no direct pulls |
|
||||
| `ClearNamedFramebuffer*` (`DirectGLES.h:60-67`) | same, plus the `SharedPtr<FramebufferObject>` handle argument |
|
||||
| `BlitFramebuffer` (`:6015`) | direct `GetFramebufferBindingSlot(Read)` + `(Draw)` (`:6044-6045`); + `SyncCurrentFBO`, `SyncRenderState` (`:6029`), `BindCurrentFBO`×2, `SyncNeccessaryTextures` (`:6021`), `ResolveThenBlit` (`:5093`→`IsTransformFeedbackActive`, `IsTransformFeedbackPaused`) |
|
||||
| `BlitNamedFramebuffer` (`:6055`) | same + two FBO handle arguments |
|
||||
| `CopyTexImage2D` (`:6676`) | `GetActiveTextureUnit`, `GetTextureUnitObject`; + `SyncNeccessaryTextures` (`:6683`), `SyncRenderState` (`:6691`) |
|
||||
| `CopyTexSubImage2D` (`:6769`) | same pair at `:6794-6795`; + `:6777`, `:6785` |
|
||||
| `CopyImageSubData` | no direct pulls; both endpoints arrive as `CopyImageEndpoint` handles |
|
||||
| `GenerateMipmap` (`:6928`) | `GetActiveTextureUnit`, `GetTextureUnitObject` |
|
||||
| `ReadPixels` (`:8999`) | `GetPixelStoreParameters` (`:9041`), `GetBufferBindingSlot(PixelPack)` (`:9084`); + `PackStateFromContext` (`:6184`), `StoreReadbackRowsToClient` (`:7552`), `ReadPixelsViaFormatConversion` (`:8526`), `Utils::StoreClientRows` (`Utils.cpp:2294`) |
|
||||
| `GetTexImage` (`:9166`) | `GetActiveTextureUnit`+`GetTextureUnitObject` (`:9194-9197`), `GetPixelStoreParameters` (`:9420`), `GetBufferBindingSlot(PixelPack)` (`:9510`); + `GetTexImageViaShadowConversion` (`:8759`) |
|
||||
| `ShaderStorageBlockBinding` (`:7355`) | `ValidateProgramName`, `GetProgramObject`; + `SyncNeccessaryTextures` (`:7376`), `SyncRenderState` (`:7378`) |
|
||||
| `BindImageTexture` (→`TextureImpl::SyncImageTextureBinding`, `:7317`) | `GetImageTextureBinding` (`:1728`) |
|
||||
| `BeginTransformFeedback` (`:969`) / `EndTransformFeedback` (`:1102`) | `EndTransformFeedback`→`ScatterCapturedRecords` (`:885`→`GetTransformFeedbackCapturedVertices`) |
|
||||
| `PauseTransformFeedback` (`:1131`), `ResumeTransformFeedback` (`:1140`), `BindTransformFeedback` (`:1147`), `DeleteTransformFeedback` (`:1167`), `PatchParameteri` (`:6923`) | **no pulls** |
|
||||
| `Present` (`:10550`), `SetSwapInterval` (`:9945`) | **no pulls** |
|
||||
| sync / timer / occlusion / xfb-query group | **no pulls** in DirectGLES |
|
||||
| `GetIntegeri_v` | **no pulls** |
|
||||
| error reporting (`RecordGLError`, `:6365`) reachable from every entry above | `RecordError` |
|
||||
|
||||
Two more DirectGLES pull sites sit on paths reached from several verbs and are worth calling out
|
||||
separately because they are in `Managers.cpp`, not `DirectGLES.cpp`:
|
||||
|
||||
| site | function | reached from |
|
||||
|---|---|---|
|
||||
| `Managers.cpp:5355` | `GetReadColorAttachment` | readback + `SyncReadBufferToBackend` (framebuffer sync) |
|
||||
| `Managers.cpp:5460` | `IsFixedPointFallbackReadAttachment` | readback |
|
||||
| `Managers.cpp:6230` | `BoundImageUnitFormat` | program link (image-unit format) |
|
||||
| `Managers.cpp:7193/7201/7204` | `AttachPassthroughTessControlStage` | program link (`SyncToBackend`) |
|
||||
| `Managers.cpp:8751` | `BackendSamplerObject::SyncToBackend` | sampler sync — `RecordError` |
|
||||
| `Managers.cpp:3645/3646/3774/3775/3845/3846/4735/4736/4737` | `StampViewSyncKeys` / `SyncMipmapsToBackend` | texture upload, from every verb that calls `SyncNeccessaryTextures` |
|
||||
| `MultiDraw.cpp:45/51/52/87/95` | `RestartSentinelFor`, `RestartActive`, `BoundDrawIndirectBufferId`, `BoundIndexBuffer` | the CPU multi-draw flattener, reached from `MultiDrawElements*` |
|
||||
|
||||
#### DirectVulkan (Magma)
|
||||
|
||||
Every `DirectVulkan.cpp` entry point opens with
|
||||
`MOBILEGL_ASSERT(MG_State::pGLContext, "DirectVulkan::<verb> called with null GL context")` — that
|
||||
is 30 of the 58 non-arrow lines, and it is the cleanest possible marker of the verb boundary: each
|
||||
of those asserts is exactly where a per-verb `PipeInputs` fill/validate would go.
|
||||
|
||||
| verb entry point (impl) | reachable accessors |
|
||||
|---|---|
|
||||
| `DrawArrays` (`DirectVulkan.cpp:815`), `DrawElements` (`:840`), `DrawElementsBaseVertex` (`:975`), `MultiDrawArrays` (`:863`), `MultiDrawElements` (`:968`) / `MultiDrawElementsImpl` (`:894`→`GetBoundVertexArray`), `MultiDrawElementsBaseVertex` (`:998`), `DrawElementsInstancedBaseVertexBaseInstance` (`:493`), `DrawArraysInstancedBaseInstance` (`:564`), `BuildClosedLineLoopIndices` (`:779`→`GetBoundVertexArray`) | the **draw closure** below |
|
||||
| `DrawElementsIndirect` (`:521`), `DrawArraysIndirect` (`:580`), `MultiDrawArraysIndirect` (`:392`), `MultiDrawElementsIndirect` (`:387`) | direct `GetBufferBindingSlot(DrawIndirect)` (`:533`, `:586`, `:402`) + `ResolveIndirectCommandBytes` (`:277-278`); + draw closure |
|
||||
| `MultiDrawArraysIndirectCount` (`:448`), `MultiDrawElementsIndirectCount` (`:442`) | direct `GetBufferBindingSlot(Parameter)` (`:465`); + `VulkanRenderer::MultiDrawElementsIndirectCount` (`:12074`→`GetBoundVertexArray`, `GetBufferBindingSlot(DrawIndirect)`, `(Parameter)`) |
|
||||
| **the draw closure** = `VulkanRenderer::SetupDraw` (`:6420`) and its fast path `TrySetupDrawFastPath` (`:6034`) | `GetProgramForDraw` (`:6043`, `:6434`, `:6472`), `GetBoundVertexArray` (`:6105`, `:6471`), `GetFramebufferBindingSlot(Draw)` (`:6110`, `:6464`), `GetPipelineStateVersion` (`:6121`, `:6972`), `GetTextureBindGeneration` (`:6122`, `:6526`, `:6650`, `:6973`), `GetRenderStateParameters` (`:6130`), `GetSamplingResolutionGeneration` (`:6304`, `:6532`, `:6669`, `:6999`), `IsTransformFeedbackActive` (`:6091`, `:6512`), `IsCapabilityEnabled(DepthTest/StencilTest)` (`:6830-6831`); via `GetBaseTransformFlagsRaw` (`:6005`→`GetFramebufferBindingSlot`, and `GetShaderTransformFlags` `:2985`); via `ResolvePrimitiveRestartEnable` (`:4935`→`GetRenderStateParameters`); via `GetOrCreatePipeline` (`:4950`, **25 sites**: `GetPipelineStateVersion`, 6×`IsCapabilityEnabled`, `GetFramebufferBindingSlot`×2, `GetStencilState`×2, `GetPolygonModeFront`, `IsCapabilityEnabled(SampleShading)`, `GetMinSampleShadingValue`, `GetPatchVertices`, `GetCullFaceMode`, `GetDepthMask`, `GetDepthFunc`, `GetLogicOp`, `GetPatchDefaultOuterLevel`, `GetPatchDefaultInnerLevel`, `GetBlendFuncIndexed`, `GetBlendEquationIndexed`, `IsCapabilityEnabledIndexed(Blend)`, `GetColorMaskIndexed`); via `ComputePipelineStateHash` (`:4820`→`GetRenderStateParameters`) and `ResolveEffectiveSampleMask` (`:4812`→2×`IsCapabilityEnabled`, `GetRenderStateParameters`); via `SelectProvokingVertexMode` (`:12737`→`GetProvokingVertexMode`); via `ApplyDynamicDrawStateTail` (`:5901`→`GetRenderStateParametersVersion`, `GetRenderStateParameters`) → `ComputeGLViewport` (`:450`→`GetViewportIndexed`, `GetDepthRangeIndexed`), `ComputeGLScissorRect` (`:5855`→`GetRenderStateParameters`), `ApplyBlendConstants` (`:522`→`GetBlendColor`), `ApplyPolygonOffsetState` (`:555`→`GetPolygonOffsetUnits`, `GetPolygonOffsetFactor`), `ApplyLineWidthState` (`:569`→`GetLineWidth`), `ApplyStencilState` (`:648`→`GetStencilState`×2); via `UploadAndBindVertexBuffers` (`:3580`→`GetCurrentVertexAttribute` `:3926`) → `TryComputeMaxIndexFromHostBytes` (`:3409`→2×`IsCapabilityEnabled`); via `UploadAndBindIndexBuffer` (`:4031`→`GetRenderStateParameters` `:4060`); via `UniformManager::BindProgramUniformBuffers` (`UniformManager.cpp:2346`) → the whole descriptor group below; via `BeginXfbCaptureForDraw` (`:11266`) / `EndXfbCaptureForDraw` (`:11366`) |
|
||||
| **descriptor group** (`UniformManager.cpp`) | `ResolveSamplerDescriptor` (`:464`→`GetTextureUnitObject` `:506`, `GetFramebufferBindingSlot(Draw)` `:555`), `ResolveSamplerTexture` (`:808`→`GetTextureUnitObject` `:821`), `ResolveSamplerTextureRaw` (`:834`→`:847`), `ProgramSamplesOnlySingleLevelTextures` (`:750`→`:782`), `ResolveSampledBinding` (`:1643`→`:1662`), `ResolveStorageTexelBufferDescriptor` (`:986`→`GetImageTextureBinding` `:1016`), `ResolveStorageImageDescriptor` (`:1259`→`:1295`), `ResolveStorageBufferDescriptor` (`:1146`→`GetBufferBindingPointCount` `:1189`, `GetBufferBindingPoint` `:1194`), `ResolveUniformBufferPayload` (`:1962`→`GetBufferBindingPointCount` `:2013`, `GetBufferBindingPoint(Uniform)` `:2018`), `CollectStorageImageTextures` (`:1801`→`GetImageTextureBinding` `:1850`), `CollectSamplerImageFeedback` (`:1883`→`:1938`) |
|
||||
| **xfb group** | `BeginXfbCaptureForDraw` (`VulkanRenderer.cpp:11266`): `IsTransformFeedbackActive` `:11268`, `IsTransformFeedbackPaused` `:11274`, `GetTransformFeedbackProgram` `:11277`, `GetBufferBindingPoint(TransformFeedback)` `:11316`, `GetTransformFeedbackGeneration` `:11347`; `EndXfbCaptureForDraw` (`:11366`): `GetTransformFeedbackProgram` `:11370`; `CurrentXfbCounterSlot` (`:11217`): `GetBoundTransformFeedbackLifetimeId` `:11219`, `HasOpenTransformFeedbackSpan` `:11236` |
|
||||
| `DispatchCompute` (`DirectVulkan.cpp:642` → `VulkanRenderer.cpp:7031`) | `GetProgramForDispatch` `:7036`; + `BindProgramUniformBuffers` → descriptor group |
|
||||
| `DispatchComputeIndirect` (`:648` → `VulkanRenderer.cpp:7084`) | `GetProgramForDispatch` `:7088`, `GetBufferBindingSlot(DispatchIndirect)` `:7132`; + descriptor group |
|
||||
| `MemoryBarrier` / `MemoryBarrierByRegion` (`:654`) | **no pulls** beyond the null assert |
|
||||
| `Clear` (`:756` → `VulkanRenderer.cpp:7251`, **13 sites**) | `IsCapabilityEnabled(RasterizerDiscard)` `:7257`, `GetFramebufferBindingSlot(Draw)` `:7260`, `GetClearColor` `:7268`, `GetClearDepth` `:7269`, `GetClearStencil` `:7270`, `IsCapabilityEnabled(ScissorTest)` `:7277`, `GetColorMaskIndexed` `:7300`/`:7389`/`:7410`, `GetDepthMask` `:7327`/`:7369`, `GetStencilState` `:7340`/`:7373`; + `PrepareScissoredClear` (`:7188`→`GetScissorBox`×2) |
|
||||
| `ClearBufferfi/fv/iv/uiv` (`DirectVulkan.cpp:335-356`) | `QueueClearBufferPayload` (`VulkanRenderer.cpp:7626`→`GetFramebufferBindingSlot(Draw)` `:7628`) → `QueueClearBufferPayloadForFramebuffer` (`:7434`, 5 sites: `IsCapabilityEnabled(RasterizerDiscard)` `:7439`, `(ScissorTest)` `:7481`, `GetDepthMask` `:7512`, `GetStencilState` `:7514`, `GetColorMaskIndexed` `:7526`) → `RecordScissoredClearBuffer` (`:7568`: `GetColorMaskIndexed` `:7583`, `GetDepthMask` `:7601`, `GetStencilState` `:7609`) + `PreCompensateSrgbClearColor` (`VkClearManager.cpp:53`→`IsCapabilityEnabled(FramebufferSrgb)` `:57`) |
|
||||
| `ClearNamedFramebuffer*` (`DirectVulkan.cpp:359-386`) | same minus the `GetFramebufferBindingSlot` (the FBO arrives as a handle) |
|
||||
| `BlitFramebuffer` (`:1005` → `VulkanRenderer.cpp:8583`) | `GetFramebufferBindingSlot(Read)` `:8586`, `(Draw)` `:8587`; → `BlitNamedFramebuffer` (`:8591`→`IsCapabilityEnabled(ScissorTest)` `:8619`, `GetScissorBox` `:8620`) |
|
||||
| `BlitNamedFramebuffer` | as above, FBOs by handle |
|
||||
| `CopyTexImage2D` (`:613`), `CopyTexSubImage2D` (`:619` → `VulkanRenderer.cpp:9196`) | `GetTextureUnitObject`+`GetActiveTextureUnit` `:9214`, `GetFramebufferBindingSlot(Read)` `:9222` |
|
||||
| `CopyImageSubData` (`:625`) | endpoints by handle; no direct pull |
|
||||
| `GenerateMipmap` (`:636` → `VulkanRenderer.cpp:10940`) | `GetTextureUnitObject`+`GetActiveTextureUnit` `:10963` |
|
||||
| `ReadPixels` (`:739` → `VulkanRenderer.cpp:9927`) | `GetFramebufferBindingSlot(Read)` `:9933`; → `PackReadbackToClientOrPbo` (`:2732`→`GetClampReadColor` `:2771`), `ReadDepthStencilImageToClient` (`:10424`→`GetBufferBindingSlot(PixelPack)` `:10688`, `GetPixelStoreParameters` `:10689`) |
|
||||
| `GetTexImage` (`:744` → `VulkanRenderer.cpp:10716`) | `GetTextureUnitObject`+`GetActiveTextureUnit` `:10719`; + the same pack path |
|
||||
| `GetTextureImage` (`:749`) | texture by handle; + the same pack path |
|
||||
| `ShaderStorageBlockBinding` (`DirectVulkan.cpp:709`) | `RecordError` `:716`; + `TryGetDirectVulkanProgram` (`:269`→`ValidateProgramName` `:270`, `GetProgramObject` `:273`) |
|
||||
| `BeginXfbPrimitivesQuery` (`DirectVulkan.cpp:1275`) | `GetTransformFeedbackPausedPrimitiveCounter` `:1284` |
|
||||
| `GetQueryResult64` (`DirectVulkan.cpp:1209`) | `GetTransformFeedbackPausedPrimitiveCounter` `:1237` |
|
||||
| `Present` (`DirectVulkan.cpp`, table `:698`) | **no pulls** |
|
||||
| `BindImageTexture`, `GetIntegeri_v`, sync group, timer group, occlusion group, `EndXfbPrimitivesQuery` | **no pulls** |
|
||||
| **init/caps** — `BackendObject_DirectVulkan::InitCapabilities` (`:370`) and `ApplyVulkanCapabilitiesForTesting` (`:781`) | `InvalidateCompileEnv` (`:389`, `:787`) — the only pulls outside a GL verb |
|
||||
| framebuffer/render-pass helpers reachable from every drawing verb | `VkRenderPassManager::ComputeHash` (`:602`→`IsCapabilityEnabled(FramebufferSrgb)` `:613`), `GetOrCreateRenderPass` (`:767`→`:965`), `ConvertTextureInternalFormatToVkEnum` (`:1044`→`:1111`), `VkTextureManager::GetOrCreateAttachmentViewAtMipLevel` (`:898`→`:952`), `VkTextureManager::SyncTextureAndGetDescriptor` (`:752`→`GetTextureObject` `:809`) |
|
||||
| error reporting reachable from many verbs | `RecordClearBufferError` (`VulkanRenderer.cpp:1242`), `RecordTextureCopyError` (`:1246`), `RecordUnsupportedFramebufferError` (`:1302`) — all `RecordError` |
|
||||
|
||||
### 4.3 Caller evidence used for the reachability above
|
||||
|
||||
`PrepareForDraw` 14 call sites `DirectGLES.cpp:4556,4569,4587,4602,4663,4703,4771,4811,4856,4869,4894,4916,4931`;
|
||||
`PrepareForCompute` `:6983,6991`; `SyncRenderState` 13 call sites `:2994,4121,6029,6064,6691,6785,7378,7424,7437,7453,7469,7489,7506`;
|
||||
`SyncNeccessaryTextures` 13 call sites `:2983,4066,4115,6021,6063,6683,6777,7376,7422,7435,7451,7468`;
|
||||
`SyncCurrentProgram` `:2993,4069`; `BindCurrentProgramWithResources` `:3012,4084`;
|
||||
`SyncBufferBindingPoints` `:678,687,688`; `MarkShaderStorageBuffersGpuWritten` `:679,689`;
|
||||
`SyncBoundBuffer` `:664,691`; `SyncAtomicCounterBuffers` `:3523`;
|
||||
`SyncCurrentVertexAttributeValues` `:3009`; `SyncImageTextureBinding` `:1841,7317`;
|
||||
`XfbImpl::StartPendingTransformFeedback` `:3016`; `ScatterCapturedRecords` `:1123`;
|
||||
`PackStateFromContext` `:9027,9270`; `StoreReadbackRowsToClient` `:8159,8271,8322`.
|
||||
Vulkan: `SetupDraw` `VulkanRenderer.cpp:11422,11744,11780,11985,12127,12224,12289`;
|
||||
`TrySetupDrawFastPath` `:6450`; `GetOrCreatePipeline` `:6371,6896`;
|
||||
`ApplyDynamicDrawStateTail` `:6407,6949`; `ApplyStencilState` `:5911,5986`;
|
||||
`ApplyBlendConstants` `:5908,5983`; `ApplyPolygonOffsetState` `:5909,5984`;
|
||||
`ApplyLineWidthState` `:5910,5985`; `ComputeGLViewport` `:510,5889`; `ComputeGLScissorRect` `:5890`;
|
||||
`ResolveEffectiveSampleMask` `:4845,4862,5290`; `ComputePipelineStateHash` `:4989,6338`;
|
||||
`ResolvePrimitiveRestartEnable` `:6067,6897,6960`; `GetBaseTransformFlagsRaw` `:6139,6510,6974`;
|
||||
`GetShaderTransformFlags` `:6026`; `UploadAndBindVertexBuffers` `:6400,6937`;
|
||||
`UploadAndBindIndexBuffer` `:6404,6945`; `TryComputeMaxIndexFromHostBytes` `:3601`;
|
||||
`BeginXfbCaptureForDraw` `:11430,11753`; `EndXfbCaptureForDraw` `:11439,11763`;
|
||||
`CurrentXfbCounterSlot` `:11346,11372`; `PrepareScissoredClear` `:7279,7483`;
|
||||
`QueueClearBufferPayload` `:7641,7661,7758,7779`;
|
||||
`QueueClearBufferPayloadForFramebuffer` `:7632,7683,7708,7723,7737`;
|
||||
`RecordScissoredClearBuffer` `:7489`; `PackReadbackToClientOrPbo` `:10111,10119,10936`;
|
||||
`ReadDepthStencilImageToClient` `:10368,10420,10817`; `SelectProvokingVertexMode` `:4433,5309`;
|
||||
`BindProgramUniformBuffers` `:4754,6394,6928,7071`; `CollectStorageImageTextures` `:5687`;
|
||||
`CollectSamplerImageFeedback` `:5787`; `ProgramSamplesOnlySingleLevelTextures` `:6556`;
|
||||
UniformManager internals `ResolveSamplerDescriptor` `:2619`, `ResolveSamplerTexture` `:875`,
|
||||
`ResolveSamplerTextureRaw` `:505,773`, `ResolveStorageTexelBufferDescriptor` `:2522`,
|
||||
`ResolveStorageBufferDescriptor` `:2543`, `ResolveStorageImageDescriptor` `:2569`,
|
||||
`ResolveSampledBinding` `:1742,1785,1901`, `ResolveUniformBufferPayload` `:2257`.
|
||||
|
||||
---
|
||||
|
||||
## 5. (c) `SyncPersistentMappedRange` and `SyncGpuWrites` call sites
|
||||
|
||||
Both are methods on `MG_State::GLState::BufferObject`. They are the two places a backend forces the
|
||||
frontend's CPU shadow to become authoritative before it reads bytes out of it — i.e. the two places
|
||||
a pipe boundary would otherwise hand the server stale memory.
|
||||
|
||||
### 5.1 `SyncPersistentMappedRange()` — 20 sites
|
||||
|
||||
Semantics: pushes writes made through a **non-adopted** persistent map (which mutate the shadow
|
||||
with no API call and therefore bump no change serial) down into the backend resource. A no-op for
|
||||
every buffer that is not such a map.
|
||||
|
||||
| # | file:line | receiver | enclosing function | verb that owns it | what it syncs |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | `DirectGLES/DirectGLES.cpp:263` | `drawBuffer` | `ResolveIndirectCommandBytes` (`:260`) | draw (indirect, CPU fallback) | `GL_DRAW_INDIRECT_BUFFER` before the CPU reads the command struct out of `MappedData()` |
|
||||
| 2 | `DirectGLES/DirectGLES.cpp:4468` | `indexBuffer` | `ScopedRestartIndexSubstitution` (`:4433`) | draw (primitive-restart rewrite) | the element-array buffer before the whole-buffer restart-index rewrite |
|
||||
| 3 | `DirectGLES/DirectGLES.cpp:4722` | `drawBuffer` | `MultiDrawElementsIndirectCount` (`:4685`) | draw (indirect count) | `GL_DRAW_INDIRECT_BUFFER` |
|
||||
| 4 | `DirectGLES/DirectGLES.cpp:4723` | `parameterBuffer` | same | draw (indirect count) | `GL_PARAMETER_BUFFER` |
|
||||
| 5 | `DirectGLES/DirectGLES.cpp:4824` | `drawBuffer` | `MultiDrawArraysIndirectCount` (`:4793`) | draw (indirect count) | `GL_DRAW_INDIRECT_BUFFER` |
|
||||
| 6 | `DirectGLES/DirectGLES.cpp:4825` | `parameterBuffer` | same | draw (indirect count) | `GL_PARAMETER_BUFFER` |
|
||||
| 7 | `DirectGLES/Managers.cpp:1569` | `bufferObject` | `EnsureBufferResource` (the GLES buffer-resource ensure path) | buffer op (draw/dispatch resource sync) | pushes map writes before the respecify / pending-range flush decision at `:1575-1584` |
|
||||
| 8 | `DirectGLES/MultiDraw.cpp:510` | `indexBuffer` | the CPU multi-draw index flattener | draw (MultiDrawElements flatten) | the element-array buffer before flattening indices |
|
||||
| 9 | `DirectVulkan/DirectVulkan.cpp:280` | `drawBuffer` | `ResolveIndirectCommandBytes` (`:277`) | draw (indirect, CPU fallback) | `GL_DRAW_INDIRECT_BUFFER` |
|
||||
| 10 | `DirectVulkan/DirectVulkan.cpp:471` | `parameterBuffer` | `MultiDrawArraysIndirectCount` (`:448`) | draw (indirect count, CPU fallback) | `GL_PARAMETER_BUFFER` before `memcpy`ing the draw count |
|
||||
| 11 | `DirectVulkan/DirectVulkan.cpp:795` | `indexBufferShared` | line-loop / CPU index path (`:788`) | draw (index read) | the element-array buffer before reading indices |
|
||||
| 12 | `DirectVulkan/Renderer/UniformManager.cpp:2023` | `bufferObject` | `ResolveUniformBufferPayload` (`:1962`) | program/uniform sync (UBO) | the bound UBO before its bytes are staged into a descriptor |
|
||||
| 13 | `DirectVulkan/Renderer/VkBufferManager.cpp:628` | `bufferObject` | `AcquireResidentSlice` (`:620`) | buffer op (any verb that acquires a resident slice) | the buffer before its GPU-resident slice is used |
|
||||
| 14 | `DirectVulkan/Renderer/VkBufferManager.cpp:679` | `bufferObject` | `AcquireStreamedSlice` (`:672`) | buffer op (streamed upload) | the buffer before the transient copy is taken |
|
||||
| 15 | `DirectVulkan/Renderer/VulkanRenderer.cpp:3434` | `indexBufferShared` | `TryComputeMaxIndexFromHostBytes` (`:3409`) | draw (index range scan) | element-array buffer before the max-index scan |
|
||||
| 16 | `DirectVulkan/Renderer/VulkanRenderer.cpp:3513` | `bufferObject` | vertex-buffer fast-path revalidation inside `UploadAndBindVertexBuffers` (`:3580`'s memo check block at `:3500-3520`) | vertex sync (draw fast path) | each bound vertex buffer before its slice epoch is trusted |
|
||||
| 17 | `DirectVulkan/Renderer/VulkanRenderer.cpp:3828` | `sourceBufferShared` | 64-bit attribute conversion inside `UploadAndBindVertexBuffers` | vertex sync (fp64 narrowing) | the source vertex buffer before CPU-side conversion |
|
||||
| 18 | `DirectVulkan/Renderer/VulkanRenderer.cpp:7137` | `indirectBuffer` | `DispatchComputeIndirect` (`:7084`) | dispatch (indirect) | `GL_DISPATCH_INDIRECT_BUFFER` |
|
||||
| 19 | `DirectVulkan/Renderer/VulkanRenderer.cpp:12132` | `drawBuffer` | `MultiDrawElementsIndirectCount` (`:12074`) | draw (indirect count) | `GL_DRAW_INDIRECT_BUFFER` |
|
||||
| 20 | `DirectVulkan/Renderer/VulkanRenderer.cpp:12133` | `parameterBuffer` | same | draw (indirect count) | `GL_PARAMETER_BUFFER` |
|
||||
|
||||
Split: 8 DirectGLES / 12 DirectVulkan. By verb: draw 13, buffer op 3, vertex sync 2, dispatch 1,
|
||||
program/uniform sync 1.
|
||||
(Two further mentions are comments, not calls: `DirectGLES/Managers.cpp:1461`, `:2681`,
|
||||
`DirectVulkan/Renderer/VulkanRenderer.h:1214`.)
|
||||
|
||||
### 5.2 `SyncGpuWrites()` — 6 sites
|
||||
|
||||
Semantics: a submit-and-wait plus writeback for a buffer flagged gpu-write-pending (XFB capture,
|
||||
SSBO, storage texel buffer). Always paired with a CPU read of `MappedData()`.
|
||||
|
||||
| # | file:line | receiver | enclosing function | verb that owns it | what it syncs |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | `DirectGLES/DirectGLES.cpp:4469` | `indexBuffer` | `ScopedRestartIndexSubstitution` (`:4433`) | draw (primitive-restart rewrite) | pulls shader-written index bytes back before the rewrite |
|
||||
| 2 | `DirectGLES/Managers.cpp:2643` | `bufferObject` | the fp64 vertex-attribute converter (`ConvertAttributeStream`, in `BackendVertexArrayObject`) | vertex sync (fp64 narrowing) | pulls shader writes back before the CPU narrows doubles to floats |
|
||||
| 3 | `DirectGLES/MultiDraw.cpp:511` | `indexBuffer` | CPU multi-draw index flattener | draw (MultiDrawElements flatten) | shader-written indices before flattening |
|
||||
| 4 | `DirectVulkan/Renderer/VulkanRenderer.cpp:3433` | `indexBufferShared` | `TryComputeMaxIndexFromHostBytes` (`:3409`) | draw (index range scan) | recorded-but-unexecuted GPU writes into the coherent index mapping |
|
||||
| 5 | `DirectVulkan/Renderer/VulkanRenderer.cpp:3827` | `sourceBufferShared` | 64-bit attribute conversion in `UploadAndBindVertexBuffers` (`:3580`) | vertex sync (fp64 narrowing) | XFB/SSBO/texel-buffer writes into the source vertex buffer |
|
||||
| 6 | `DirectVulkan/Renderer/VulkanRenderer.cpp:4161` | `indexBufferShared` | `UploadAndBindIndexBuffer` (`:4031`), restart-substitution branch | draw (primitive-restart rewrite) | shader-written indices before the whole-buffer rewrite |
|
||||
|
||||
Split: 3 DirectGLES / 3 DirectVulkan. By verb: draw 4, vertex sync 2.
|
||||
(Three further mentions are comments: `DirectGLES/DirectGLES.cpp:459`, `:509`,
|
||||
`DirectGLES/Managers.cpp:2681`.)
|
||||
|
||||
**P1 note on both lists.** Every one of the 26 sites is a *synchronous, blocking* call that the
|
||||
backend makes on a frontend object in order to read host bytes. Twelve of them are followed
|
||||
immediately by `MappedData()` (`DirectGLES.cpp:269`, `4470`, `4740`; `MultiDraw.cpp:512`;
|
||||
`DirectVulkan.cpp:282`, `477`, `796`; `UniformManager.cpp:2025`; `VulkanRenderer.cpp:3435`, `3830`,
|
||||
`4163`). Under disaggregation there is no shared address space for `MappedData()` to point into, so
|
||||
each of these 26 becomes either a *pull-host-bytes* reverse call or a client-side pre-resolution
|
||||
that ships the bytes with the verb. `MG_Pipe/MGPipeHostSpan.h` and the `HostSpanCount` field of
|
||||
`MGP_FIELDS_MGPShaderBuffers` (`PipeFields.def`) are the existing hooks; nothing in
|
||||
`PipeFields.def` covers the *index buffer* host span, which is what sites 1-3, 8, 11, 15 and
|
||||
4/6 above need.
|
||||
@@ -0,0 +1,428 @@
|
||||
# P1 specification, extracted from the MGPipe design docs
|
||||
|
||||
Scout report. Worktree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg` (branch `feat/disaggregated`). Read-only; nothing was edited.
|
||||
|
||||
Docs read in full: `docs/Disaggregated/README.md` (57 lines), `ARCHITECTURE.md` (601 lines), `ROADMAP.md` (90 lines), `MEASUREMENTS.md` (96 lines). Every code claim below carries a path + line that I actually opened in this tree.
|
||||
|
||||
Quoting convention: `>` blocks are **verbatim** from the doc (Chinese as written). Everything else is my summary or my own measurement.
|
||||
|
||||
---
|
||||
|
||||
## 0. Where P1 sits
|
||||
|
||||
- `docs/Disaggregated/README.md:3`: `> 状态:**P0、P0.5 已落地**(`feat/disaggregated@5d99ee43`,基线 `dev@50fb1343`)。下一步 P1 → P2,第 43 天 GO/NO-GO。见 `ROADMAP.md`。`
|
||||
- Track: monolith lane. `ROADMAP.md:9` — `> 两条跑道:**monolith 跑道** P0 → P0.5 → P1 → P2 → P3a → P4a → P3b/P4b → P7 → P8 → P13,每段可独立交付、可随时中止且 monolith 严格好于起点;**IPC 跑道** P5 → P6 → P9 → P10 → P11 → P12。`
|
||||
- Milestone: `ROADMAP.md:38` — `> - **第 25 天(P1 出口)**:verify harness 逐 draw 逐字段证明"推送等价于拉取"。零产品风险,**不是** GO/NO-GO。`
|
||||
- Cumulative day count: `ROADMAP.md:32` — P0 9 → P0.5 15 → **P1 25** → P2 43 …
|
||||
- Sunk-cost framing: `ROADMAP.md:58` — `> 真正只为 MGPipe 押上的是 P1 + P2 ≈ 28–39 天,NO-GO 分支下仍留下上述产物。`
|
||||
- Under NO-GO, P1's output is explicitly **not rolled back** (`ROADMAP.md:57`): `> **不回滚**:P0/P0.5/P1/P2 的产物(句柄基建与重键、两个头文件抽取、计数器、verify harness、渲染状态 CSO)全是自洽的 monolith 交付物,留在 `dev``.
|
||||
|
||||
---
|
||||
|
||||
## 1. The P1 row of the phase table (verbatim), `ROADMAP.md:17`
|
||||
|
||||
Columns are: 阶段 | 天 | 落地什么 | 验收门 | 依赖.
|
||||
|
||||
**阶段**: `**P1** `PipeInputs` 替换与 verify harness`
|
||||
**天**: `10–13`
|
||||
|
||||
**落地什么 (deliverables), verbatim:**
|
||||
|
||||
> `MG_Backend/MGPipe/PipeInputs.h`(Espryt 32 / Magma 55 访问器);`sed` 293 处 + 58 行非箭头清单逐条转换(显式交付物);逐 verb 类填充点(G5 表,~93 个边界站点);逐 verb 世代 poison;G4 影子比对器 + 第三种 CI 模式;20 处 `SyncPersistentMappedRange` + 6 处 `SyncGpuWrites` 的逐站点归属表
|
||||
|
||||
Broken out — six deliverables:
|
||||
1. `MG_Backend/MGPipe/PipeInputs.h`, Espryt 32 accessors / Magma 55 accessors.
|
||||
2. The mechanical `sed` of 293 arrow sites **plus** a per-line conversion of the 58-line non-arrow list — the doc calls this an **explicit deliverable** (i.e. the list itself is a produced artifact, not a side effect).
|
||||
3. Per-verb-class fill points: the G5 table, ~93 boundary sites.
|
||||
4. Per-verb generation poison.
|
||||
5. G4 shadow comparator + **a third CI mode**.
|
||||
6. A per-site ownership table for the 20 `SyncPersistentMappedRange` and 6 `SyncGpuWrites` sites.
|
||||
|
||||
**验收门 (acceptance gate), verbatim:**
|
||||
|
||||
> pull 构建 `nm --defined-only` 不变、`.text` 差异逐行归因(空守卫/三元重写推迟到 P2);40 trace + 全部集成测试在 `MOBILEGL_PIPE_VERIFY=1` 下零分歧;故意损坏一个快照字段能让 verify 变红;故意在 `glGenerateMipmap` 的填充表漏一个字段能在**那条 verb** 上触发 poison Fatal
|
||||
|
||||
Four gate clauses:
|
||||
1. On the **pull** build, `nm --defined-only` unchanged; `.text` differences attributable line by line. Empty-guard / ternary rewrites are **deferred to P2** — do not do them in P1, they would break this gate's attributability.
|
||||
2. 40 traces + **all** integration tests, run under `MOBILEGL_PIPE_VERIFY=1`, **zero divergence**.
|
||||
3. Negative control A: deliberately corrupting one snapshot field must turn verify red.
|
||||
4. Negative control B: deliberately omitting one field from `glGenerateMipmap`'s fill table must raise the poison Fatal **on that verb** (not on a later draw). This is what makes the poison a per-verb *generation* rather than a bitmap.
|
||||
|
||||
**依赖**: `P0.5`. And from the P0.5 row (`ROADMAP.md:16`, last cell): `> P0;**P1 与 P7 的硬前置**` — P0.5 is a hard prerequisite for P1 and P7.
|
||||
|
||||
### Every other P1 mention in the docs
|
||||
|
||||
| Where | Verbatim / content |
|
||||
|---|---|
|
||||
| `ARCHITECTURE.md:172` | `> 完整性由 `scripts/gen_pipe_dirty_surface.py` 保证:枚举 `MG_Impl/GLImpl` 里每个 mutator → 必须 bump 的聚合世代,CI 重生成 + `git diff --exit-code`,未映射即失败(P1 起成为门)。` Also gives the measured surface: 926 mutator calls over 73 distinct mutators; 92 of them (7 mutators, mostly `RecordError`) sit at "即时发布点"; the other 834 are published by the following verb. `> 映射表是 73 条目的问题。` |
|
||||
| `ARCHITECTURE.md:323` | Section title: `### 9.2 strangler 脚手架:`PipeInputs` + 逐 verb 填充 + poison 世代(P1)` — §2 below. |
|
||||
| `ARCHITECTURE.md:503` (gate 13.2-③) | `> 逐名功能基线是"P1 出口的重构后 monolith"(P1 出口先用 verify 证明等价于 `81b17c0b`);`81b17c0b` 只作性能锚点。` **P1's exit becomes the by-name functional baseline for every later phase.** |
|
||||
| `ARCHITECTURE.md:553` | Build layout: `MobileGL/MG_Backend/MGPipe/ PipeInputs.h + MGPipeImpl_DirectGLES/DirectVulkan.cpp [P1+]` — i.e. P1 creates that directory with **three** files: the header plus one impl TU per backend. (The directory does not exist yet: `MobileGL/MG_Backend/` currently holds only `BackendObject.cpp`, `BackendObject.h`, `BackendObjects.h`, `Init.cpp`, `DirectGLES/`, `DirectVulkan/`.) |
|
||||
| `ARCHITECTURE.md:568` | CI: `> `gen_pipe_dirty_surface.py --summary`(信息性,P1 成门)` |
|
||||
| `ARCHITECTURE.md:583` (附 A) | `> `MOBILEGL_PIPE_VERIFY` \| OFF \| 计划(P1;构建期开关,编译进 `SnapshotFromGLContext()` 与 G4 比对器,P13 后保留)` — note **CMake-level** switch, distinct from the runtime env var of the same name. |
|
||||
| `ROADMAP.md:46` (GO/NO-GO) | `> - [ ] P1 交付的逐 draw 逐字段语义等价证明(40 trace + 全部集成测试零分歧)` |
|
||||
| `ROADMAP.md:18` | P2's 依赖 cell is `P1`. |
|
||||
|
||||
In-tree code comments that name P1 (these are contracts the P1 implementer inherits):
|
||||
|
||||
- `MobileGL/MG_Pipe/generated/PipeFilled.inc:26` / `scripts/gen_pipe.py:462`: `// P0 is the skeleton: the enum, the tables and the assertion helper exist, PipeInputs // itself lands in P1.`
|
||||
- `MobileGL/MG_Pipe/generated/PipeFilled.inc:161` / `scripts/gen_pipe.py:479`: `// true has to be argued for in P1 when the fillers land: a sticky field is a field // the poison cannot protect.`
|
||||
- `MobileGL/MG_Pipe/PipeFields.def:16`: `// here makes the comparator blind to it; that gap closes in P1, when the verify harness // goes live and the comparator's coverage is itself asserted.`
|
||||
- `scripts/gen_pipe.py:165` and `MobileGL/MG_Pipe/generated/PipeVerify.inc:236`: the memcmp fallback types (`RenderStateParameters`, `PixelStoreParameters`, `DynamicBackendParameters`, `MGHostSpan`, listed at `scripts/gen_pipe.py:167-172`) `// P1 gives them field lists of their own, at which point this branch stops being reachable from any payload.`
|
||||
- `MobileGL/MG_Pipe/MGPipeTypes.h:32`: `// needs fixed-width members before it can move (a type change, not a move): P1/P7.` — about `DynamicBackendParameters` inside `MGPCaps`, which is what still keeps purity gate A off `MGPipeTypes.h`.
|
||||
- `MobileGL/MG_Pipe/Coverage.def:36-40`: `GetBufferBindingSlot` is polymorphic over `BufferTarget`; `/* inventory carries the target argument (P1) */` — its rows must split across `set_vertex_buffers` / `set_index_buffer` / `set_indirect_buffers` / `set_shader_buffers` in P1.
|
||||
- `scripts/gen_pipe_dirty_surface.py:21-22`: `P0 is the skeleton: it reports. P1 adds the mapping file and CI regenerates it with `git diff --exit-code` and zero unmapped mutators, the same shape as gen_pipe.py's G6.`
|
||||
- `scripts/gen_pipe_dirty_surface.py:193-194`: `dirty-surface: every mutator above is UNMAPPED - the aggregate-generation mapping file lands in P1, and this report is what it has to cover.`
|
||||
- `scripts/check_include_closure.py:15` and `:86` describe the P0.5 closure gate that P1 must not regress.
|
||||
|
||||
---
|
||||
|
||||
## 2. The strangler scaffold (ARCHITECTURE §9.2, lines 323–351)
|
||||
|
||||
### 2.1 `PipeInputs` + `MGB_CTX` — verbatim code block (`ARCHITECTURE.md:325-340`)
|
||||
|
||||
> ```cpp
|
||||
> // MG_Backend/MGPipe/PipeInputs.h —— 按 memo 键组织,不按读点组织(~20 KB,字段集全迁移期稳定)
|
||||
> struct PipeInputs {
|
||||
> const RenderStateParameters& GetRenderStateParameters() const; // 阶段 A:类型与后端今天读到的完全一致
|
||||
> // … 每个后端真正用到的 GLContext 方法一个访问器(Espryt 32 / Magma 55)
|
||||
> #if MOBILEGL_DEBUG || MOBILEGL_BUILD_DISAGGREGATED
|
||||
> Uint64 m_filledGen[kFieldCount]; // 逐字段"上次填充的 verb 序号"
|
||||
> Uint64 m_currentVerbSerial;
|
||||
> #endif
|
||||
> };
|
||||
> #if MOBILEGL_PIPE_PUSH
|
||||
> # define MGB_CTX (&::MobileGL::MG_Pipe::gPipeInputs)
|
||||
> #else
|
||||
> # define MGB_CTX (::MG_State::pGLContext)
|
||||
> #endif
|
||||
> ```
|
||||
|
||||
Load-bearing details in that block:
|
||||
- **Organized by memo key, not by read point.** That is why the field set is small (61) and stable across the whole migration. `MobileGL/MG_Pipe/generated/PipeFilled.inc:15-17` repeats this: `// PipeInputs is organized by MEMO KEY, not by read point, which is why the field set is // small and stable across the whole migration).`
|
||||
- Size budget: `~20 KB`.
|
||||
- **Phase A rule**: the accessor return types are *exactly* what the backends read today (`const RenderStateParameters&`, etc.), so the `sed` is type-neutral.
|
||||
- The poison members are compiled only under `MOBILEGL_DEBUG || MOBILEGL_BUILD_DISAGGREGATED`.
|
||||
- `MGB_CTX` is a **compile-time** macro switched on `MOBILEGL_PIPE_PUSH`. Note the asymmetry with the runtime knob: `MOBILEGL_PIPE_PUSH` is *also* a runtime per-subsystem bitmask (`MobileGL/Config.h:320-326`, `Uint64 PipePush = 0;` at `Config.h:326`, parsed at `MobileGL/ConfigLoader.cpp:245`). The docs use the same name for both; the P1 implementer must decide/record how the macro arm and the runtime bitmask relate (see §7, Risk R3).
|
||||
- `gPipeInputs` is a **single global instance** in `MobileGL::MG_Pipe` (matching `gMGPipeScreen`/`gMGPipeContext` at `MobileGL/MG_Pipe/MGPipe.h:72-73`).
|
||||
|
||||
### 2.2 The three-phase table (`ARCHITECTURE.md:342-347`) — verbatim
|
||||
|
||||
> | 阶段 | 改什么 | 证明 |
|
||||
> |---|---|---|
|
||||
> | A 别名 | 机械 `sed`:`MG_State::pGLContext->` → `MGB_CTX->`(293 处)+ 手工转换 58 行非箭头用法(~34 处 `MOBILEGL_ASSERT` 删除、7 处空守卫、3 处三元、`.get()` 裸指针捕获与 `decltype` 别名、14 处 `!= nullptr`、1 处注释);逐 verb 类填充点填 `gPipeInputs` | `nm --defined-only` 不变;`.text` 差异可逐行归因(空守卫/三元的重写推迟到 P2) |
|
||||
> | B 推送 | tracker 填 `gPipeInputs`,填充器按 `MOBILEGL_PIPE_PUSH` 位图逐字段让位 | `MOBILEGL_PIPE_VERIFY=1`:tracker 再填一份快照版,G4 比对器逐字段每 draw 比一次 |
|
||||
> | C 句柄化 | `SharedPtr<前端对象>` 字段 → `MGPipeHandle` + POD 描述符;memo 重键;写回变回调 | 全套门(§13) |
|
||||
|
||||
**P1 is phase A plus the scaffolding for B** (the ROADMAP P1 row's `verify harness`). Phase B's per-field yielding by the `MOBILEGL_PIPE_PUSH` bitmap and phase C's handle-ification belong to P2+ (P2 lands the tracker + the first push subsystems; P3a/P4a land Track H).
|
||||
|
||||
The 58 non-arrow lines break down (per the doc) into: ~34 `MOBILEGL_ASSERT` deletions, 7 empty guards, 3 ternaries, `.get()` raw-pointer captures + `decltype` aliases, 14 `!= nullptr`, 1 comment. **The empty-guard and ternary rewrites are explicitly deferred to P2** so the `.text` diff stays attributable.
|
||||
|
||||
### 2.3 Fill points: the G5 table and the ~93 boundary sites (`ARCHITECTURE.md:348`) — verbatim
|
||||
|
||||
> - 填充点逐 verb 类,不只 `PrepareForDraw`/`SetupDraw` 两处:G5 从 `PipeCalls.def` 生成"每个 `kCtxVerb`/`kCtxObject` 调用可能读哪些字段"的表,在 `MG_Impl` 的 ~93 个边界站点生成 validate/fill 调用。
|
||||
|
||||
Cross-references:
|
||||
- G2 (`ARCHITECTURE.md:157`): `> monolith 直调 thunk `MGP_<Name>()`,`MG_Impl` 的约 93 个 `gBackendFunctionsTable.GL.*` 站点逐名改到它上面` — the same ~93 sites are where the fill calls go.
|
||||
- G5 (`ARCHITECTURE.md:160`): `> `PipeFilled.inc` \| `PipeInputs` 字段 id(61 个)与逐 verb 世代 poison`
|
||||
- The eight validate entry points (`ARCHITECTURE.md:153`, §5.1): `> 八个 validate 入口,由 `PipeCalls.def` 的 `kCtxVerb`/`kCtxObject` 条目生成:`ValidateForDraw`(20 个 draw 入口)、`ValidateForDispatch`、`ValidateForClear`、`ValidateForBlitOrCopy`、`ValidateForTextureOp`(GenerateMipmap / CopyTex* / BindImageTexture)、`ValidateForReadback`、`ValidateForXfbSpan`、`ValidateForQuery`。八个而不是四个,因为 `MG_Impl` 用到的 70 个表项里只有约 22 个是 draw/dispatch,其余 ~48 个(clear、blit、copy、回读、barrier、XFB 跨度、query/sync)很多自己就读 `pGLContext`。`
|
||||
- **P1 relevance**: the tracker itself lands in P2, but the *fill points* land in P1 at these same eight shapes. `glGenerateMipmap` — the P1 negative-control verb — is under `ValidateForTextureOp`.
|
||||
- Class counts (`ARCHITECTURE.md:171-172` region, §3.2 table at `ARCHITECTURE.md:165-172`): `kCtxObject` = 9 calls, `kCtxVerb` = 13 calls. Those 22 rows are the ones G5 has to enumerate fields for.
|
||||
- `ARCHITECTURE.md:155` (§5.1, still binding on where a push happens): `> **只有今天就在 GL 调用时刻分发的资源 op 在 GL 调用时刻推送**——即 `BufferBackendOps` 的七个 hook。纹理 subdata 不在此列(§6)。`
|
||||
|
||||
**Measured in this tree** (my count, for the mechanical work estimate):
|
||||
- `grep -rc "gBackendFunctionsTable" MobileGL/MG_Impl/` → 91 lines across 8 files: `GLImpl/Drawing/GL_Drawing.cpp` 37, `GLImpl/Framebuffer/GL_Framebuffer.cpp` 11, `GLImpl/Getter/GL_Getter.cpp` 3, `GLImpl/Program/GL_Program.cpp` 1, `GLImpl/Program/ProgramInterface.h` 1, `GLImpl/Query/GL_Query.cpp` 22, `GLImpl/Sync/GL_Sync.cpp` 6, `GLImpl/Texture/GL_Texture.cpp` 10. (Doc says "~93"; 91 lines here — a line may hold more than one site.)
|
||||
|
||||
### 2.4 Per-verb generation poison (`ARCHITECTURE.md:349`) — verbatim
|
||||
|
||||
> - poison 是**逐 verb 世代**不是位图:每次 verb 递增 `m_currentVerbSerial`,字段被填时记下序号,读取时断言相等(跨 verb 有效的字段显式标 sticky)。位图看不见"上一个 draw 填过、紧随的 `glTexSubImage` 读到陈旧值"。debug 与 disaggregated 构建里读一个当前 verb 未填的字段是 `Fatal{UnmigratedPipeInput, "GetStencilState@DrawVbo"}`。纯度门 grep 的是 `pGLContext` 不是 `pGLContext->`。
|
||||
|
||||
So, precisely:
|
||||
- **What is poisoned**: every one of the 61 `PipeInputs` fields, individually.
|
||||
- **When**: `m_currentVerbSerial` is bumped once per verb; a fill stamps the field with the current serial; a read asserts `stamp == currentVerbSerial` unless the field is marked *sticky*.
|
||||
- **Where it is live**: `MOBILEGL_DEBUG || MOBILEGL_BUILD_DISAGGREGATED` builds only.
|
||||
- **The Fatal**: `Fatal{UnmigratedPipeInput, "<FieldName>@<Verb>"}` — the message names the field *and* the verb.
|
||||
- **Last sentence is a separate rule**: purity gate C greps for `pGLContext`, not `pGLContext->` — so an `MGB_CTX` alias that still spells `pGLContext` in the `#else` arm inside `MG_Backend` will trip gate C. (Gate C: `ARCHITECTURE.md:502` — `> **C 门未声明**——`grep -c 'pGLContext' MG_Backend/` == 0`.) The `MGB_CTX` macro definition therefore cannot live under `MG_Backend/` at P13; in P1 gate C is not yet green anyway (it turns green with the pull path's retirement, `ARCHITECTURE.md:369`).
|
||||
|
||||
**The skeleton already in the tree** — P1 fills it in, it does not invent it. `MobileGL/MG_Pipe/generated/PipeFilled.inc` (308 lines, generated by `scripts/gen_pipe.py` from `Coverage.def` + `PipeCalls.def`, included from `MGPipe.h:86`):
|
||||
|
||||
- `PipeFilled.inc:19-26` states the poison contract verbatim in code: `// The poison is a per-verb GENERATION, not a bit. A bitmap cannot see the dangerous case: // a field filled by the previous DRAW and then read by the glTexSubImage that follows is // stale, and its bit is already set. So every verb bumps CurrentVerbSerial, filling a // field stamps it with that serial, and reading a non-sticky field whose stamp is older is // Fatal{UnmigratedPipeInput} (section 6.2.2).`
|
||||
- `PipeFilled.inc:28-91`: `enum class MGPipeInputField : Uint16 { … kFieldCount }` — the 61 field ids, in this order:
|
||||
`GetActiveTextureUnit, GetBlendColor, GetBlendEquationIndexed, GetBlendFuncIndexed, GetBoundTransformFeedbackName, GetBoundVertexArray, GetBufferBindingSlot, GetBufferBindingPoint, GetBufferBindingPointCount, GetTouchedBufferBindingPointCount, GetClampReadColor, GetClearColor, GetClearDepth, GetClearStencil, GetColorMaskIndexed, GetCullFaceMode, GetCurrentVertexAttribute, GetDepthFunc, GetDepthMask, GetDepthRangeIndexed, GetFramebufferBindingSlot, GetImageTextureBinding, GetLineWidth, GetLogicOp, GetMaxTouchedTextureUnit, GetMinSampleShadingValue, GetPatchDefaultInnerLevel, GetPatchDefaultOuterLevel, GetPatchVertices, GetPipelineStateVersion, GetPixelStoreParameters, GetPolygonModeFront, GetPolygonOffsetFactor, GetPolygonOffsetUnits, GetPrimitiveRestartIndex, GetProgramForDispatch, GetProgramForDraw, GetProgramObject, GetProvokingVertexMode, GetRenderStateParameters, GetRenderStateParametersVersion, GetSamplingResolutionGeneration, GetScissorBox, GetStencilState, GetTextureBindGeneration, GetTextureContextId, GetTextureObject, GetTextureUnitObject, GetTransformFeedbackCapturedVertices, GetTransformFeedbackGeneration, GetTransformFeedbackPausedPrimitiveCounter, GetTransformFeedbackProgram, GetViewport, GetViewportIndexed, IsCapabilityEnabled, IsCapabilityEnabledIndexed, IsTransformFeedbackActive, IsTransformFeedbackPaused, InvalidateCompileEnv, ValidateProgramName, RecordError`
|
||||
- `PipeFilled.inc:93-94`: `static_assert(kMGPipeInputFieldCount == 61, "the PipeInputs field set moved");`
|
||||
- `PipeFilled.inc:96-155`: `kMGPipeInputFieldNames[]`.
|
||||
- `PipeFilled.inc:158-225`: `kMGPipeInputFieldSticky[]` — **every entry is currently `false`**, and each `true` P1 introduces has to be argued for (`PipeFilled.inc:160-162`).
|
||||
- `PipeFilled.inc:227-291`: `kMGPipeInputFieldFilledBy[]` — the call that must have filled each field by the time a verb reads it; names come from `Coverage.def` so `PipeCoverage.inc` and `PipeFilled.inc` cannot disagree (`PipeFilled.inc:227-228`). The last three entries are pseudo-calls: `"kClientResolved"` (×2: `InvalidateCompileEnv`, `ValidateProgramName`) and `"kReverseChannel"` (`RecordError`).
|
||||
- `PipeFilled.inc:293-296`: `struct MGPipeFilledState { Uint64 CurrentVerbSerial; Uint64 FilledGen[kMGPipeInputFieldCount]; };`
|
||||
- `PipeFilled.inc:298-302`: `[[noreturn]] inline void MGPipeInputPoisonFatal(MGPipeInputField field, const char* verb)` → `MGLOG_F("MGPipe: Fatal{UnmigratedPipeInput, \"%s@%s\"}", …); std::abort();`
|
||||
- `PipeFilled.inc:304-308`: `MGPipeInputFieldIsFresh(state, field)` → sticky fields pass when `FilledGen != 0`; non-sticky require `FilledGen == CurrentVerbSerial`.
|
||||
|
||||
So P1's poison work is: instantiate `MGPipeFilledState` inside `PipeInputs` (the doc's `m_filledGen[kFieldCount]` / `m_currentVerbSerial`), stamp it from the G5-generated fill points, check it in each of the 61 accessors, and argue each `sticky = true`.
|
||||
|
||||
The source of truth behind the field list is `MobileGL/MG_Pipe/Coverage.def:29-97` (`MGP_COVERAGE_ACCESSOR_LIST`) — one `X(Accessor, PipeCall)` row per field, which is what generates both `kMGPipeInputFieldFilledBy` and the coverage table.
|
||||
|
||||
### 2.5 G4 shadow comparator / `MOBILEGL_PIPE_VERIFY`
|
||||
|
||||
The definitive statement is gate 13.2-②, `ARCHITECTURE.md:501` — verbatim:
|
||||
|
||||
> 2. **语义影子比对 `MOBILEGL_PIPE_VERIFY=1`**——决定性的一条:两套状态模型活在同一地址空间,tracker 再用 `SnapshotFromGLContext()` 填一份 `PipeInputs`,G4 比对器逐字段、每 draw 比对,打印第一个分歧字段与 draw 序号。抓 tracker 忘推的字段、**dirty 位触发得太少**(危险方向)、两条路径变换不一致的值。第三种 CI 模式,40 个 trace + 全部集成测试,~5–10× 慢,永不出货。逐字段而非 `memcmp`(padding 会 false-DIFFER)。**保留模式**:消费即清的组(纹理 dirty rect)发射后无法重算,verify 时 tracker 保留清除前的集合并比对发射出去的 `(UnionBox, RegionCount, Regions[])`。**活过 P13**。
|
||||
|
||||
Decomposed:
|
||||
- **What is compared**: field by field, the pushed `PipeInputs` against a second `PipeInputs` filled by `SnapshotFromGLContext()` — both models live in the same address space.
|
||||
- **When**: once per draw.
|
||||
- **Output on failure**: the *first* differing field name + the draw serial.
|
||||
- **What it is designed to catch**: (a) fields the tracker forgot to push; (b) **a dirty bit that fires too rarely** — the dangerous direction, which no purity gate can see; (c) values that the two paths transform inconsistently.
|
||||
- **"Zero divergence"** means: across the 40 trace fixtures and the entire integration suite, the comparator never reports a differing field. That is exactly the ROADMAP gate and exactly GO/NO-GO item 1.
|
||||
- **"The third CI mode"**: a build/run configuration alongside the existing ones, running the 40 traces + all integration tests, ~5–10× slower, **never shipped**.
|
||||
- **Field-wise, never memcmp** — padding would false-DIFFER.
|
||||
- **Retention mode (保留模式)**: for consume-and-clear groups (texture dirty rects) that cannot be recomputed after emission, the tracker under verify keeps the pre-clear set and compares the emitted `(UnionBox, RegionCount, Regions[])`. (P1 only needs the mechanism to the extent texture ops are in scope; the shape gold-standard `TextureUploadShapeScenario` is a P3b/P4b gate, `ROADMAP.md:23`.)
|
||||
- **Survives P13**: `ARCHITECTURE.md:369` — `> P13:删 `SnapshotFromGLContext()` 的非 verify 分支、`MGB_CTX`、`MOBILEGL_PIPE_PUSH`、`MOBILEGL_PIPE_LEGACY_MEMOS`;**保留 `MOBILEGL_PIPE_VERIFY` 连同它需要的 `SnapshotFromGLContext()` 与 `MG_State` include**(D-B5,verify 构建永不出货);三道纯度门在非 verify 构建上转绿。` So P1 must build `SnapshotFromGLContext()` as a *permanent* verify-only facility, not a throwaway.
|
||||
- **CMake vs env**: `ARCHITECTURE.md:583` lists `MOBILEGL_PIPE_VERIFY` as a CMake option (`OFF`, `计划(P1;构建期开关,编译进 SnapshotFromGLContext() 与 G4 比对器,P13 后保留)`); `ARCHITECTURE.md:589` lists the runtime env `MOBILEGL_PIPE_VERIFY` default `0`, `逐 draw 逐字段影子比对`. Both exist; P1 must wire both. Runtime side already landed: `MobileGL/Config.h:327-332` (`Bool PipeVerify = false;` at `Config.h:332`) and `MobileGL/ConfigLoader.cpp:246`.
|
||||
- **G4 in the catalogue table** (`ARCHITECTURE.md:159`): `> G4 \| `PipeVerify.inc` \| `MOBILEGL_PIPE_VERIFY` 的逐字段比对器(字段表来自 `PipeFields.def`;浮点按位比较,NaN patch level 不会误报)`
|
||||
|
||||
**Already in the tree**: `MobileGL/MG_Pipe/generated/PipeVerify.inc` (573 lines, included at `MGPipe.h:83`).
|
||||
- `PipeVerify.inc:9-23` restates the contract, including `// Floating-point fields are compared by BITS, so a NaN patch level - which // glPatchParameterfv accepts and ComputePipelineStateHash already hashes bitwise - equals // itself instead of tripping every draw.`
|
||||
- `PipeVerify.inc:30-…` declares one `MGPipeVerify(const X&, const X&, const char** outField)` per payload (≈63 payloads; `MEASUREMENTS.md:82` says `63 个 verify payload`).
|
||||
- `PipeVerify.inc:222-239`: the dispatch template — float → bitwise memcmp; scalar/enum → `==`; else `==` if available; **else the memcmp fallback**, reachable today only from `RenderStateParameters`, `PixelStoreParameters`, `DynamicBackendParameters` and `MGHostSpan`. `PipeVerify.inc:233-237`: `// P0.5 moved the first two into MGPipeValueTypes.h; P1 gives them field lists of their own, at which point this branch stops being reachable from any payload.` → **P1 deliverable (implied but explicit in code): add `MGP_FIELDS_*` lists for those value structs to `MobileGL/MG_Pipe/PipeFields.def`** (238 lines, format shown at `PipeFields.def:21-39`) and remove them from `MEMCMP_FALLBACK_TYPES` (`scripts/gen_pipe.py:167-172`).
|
||||
- `PipeFields.def:9-17` states the zero-false-positive requirement: `// MOBILEGL_PIPE_VERIFY has to have ZERO false positives and a padding byte is exactly what makes a memcmp of RenderStateParameters false-DIFFER`.
|
||||
|
||||
### 2.6 Track V / Track H (`ARCHITECTURE.md:353-357`, §9.3) — verbatim
|
||||
|
||||
> - Track V(值类型:`GetRenderStateParameters`、`GetPixelStoreParameters`、capability 位、stencil/colormask/depthmask/scissor/patch/attrib 默认值、Magma ~22 个标量 getter……约 B 类读点的 55%):机械。
|
||||
> - Track H(对象类型:167 个 `SharedPtr<MG_State…>` 点):真活。
|
||||
> - 读点分类实测(静态):A 探测变化 ~35(12%)、B 翻译输入 ~216(74%)、C 瞬时参数 ~4、D 身份/缓存键 ~48(与 B 重叠)、E 数据字节 3、写 8。74% 是 B 类——"bump 一个版本让 server 自己拉"行不通,值本身必须过去。
|
||||
|
||||
Glossary (`README.md:52`): `> **Track V / Track H**:值类读点的迁移(整块 POD 过线)/ 对象类读点的迁移(`SharedPtr<前端对象>` → 句柄)。`
|
||||
|
||||
P1 does neither migration — P1 makes both *addressable*: every read point, V or H, goes through a `PipeInputs` accessor. Track V's bulk moves in P2 via the residual value block; Track H's first slice moves in P2 (Espryt 0b + Magma subsystem 4) and the waves in P3a/P4a.
|
||||
|
||||
### 2.7 The residual value block (`ARCHITECTURE.md:359-360`, §9.4) — verbatim
|
||||
|
||||
> Track V 的 55% 不需要逐字段接口条目就能跑起来,所以 P2 发一个**显式临时**调用 `SetResidualValueState(MGPBlobRef)`,payload `ResidualValueBlock{RenderStateParameters, PixelStoreParameters, CapabilityBits, patch 三字段}`。三条纪律:退役是编译错误(`MGL_RESIDUAL_BLOCK_SIZE` 只降不升,`MobileGL/MG_Pipe/MGPipeTypes.h:535`,P13 变成 `static_assert(sizeof == 0)`);布局逐成员 `offsetof` 断言且 split 下逐字段序列化(异质 POD 并集的 padding 差异 monolith verify 看不见);只在 P2..P13 存在,`MOBILEGL_PIPE_STATS` 单独计一类字节(`ResidualValueBlock`,P0 已占位)。
|
||||
|
||||
**It is a P2 deliverable, not P1** — but P1 constrains it: the `PipeInputs` accessors for `GetRenderStateParameters` / `GetPixelStoreParameters` / capability bits / the three patch fields are the ones the residual block will feed in P2, so their P1 signatures must be the whole-struct-by-const-ref shape the block can satisfy.
|
||||
Verified in tree: `MobileGL/MG_Pipe/MGPipeTypes.h:534` `#define MGL_RESIDUAL_BLOCK_SIZE 1248` with the ratchet comment at `MGPipeTypes.h:525-533` (`// This number only ever goes DOWN … P13 replaces it with static_assert(sizeof(ResidualValueBlock) == 0)`), the `static_assert` at `MGPipeTypes.h:535-537`, `static_assert(std::is_trivially_copyable_v<ResidualValueBlock>)` at `MGPipeTypes.h:525`(region), and `struct MGPResidualValueState { Uint32 Version; Uint32 Pad0; MGPBlobRef Blob; }` at `MGPipeTypes.h:539-543`. Size 1248 (of which `RenderStateParameters` is 1168) is confirmed at `MEASUREMENTS.md:86`.
|
||||
|
||||
### 2.8 `SnapshotFromGLContext()`
|
||||
|
||||
Mentions (there is no other definition in the docs; the function does not yet exist in the tree — `grep -rn SnapshotFromGLContext` over the source returns nothing outside `docs/`):
|
||||
- `ARCHITECTURE.md:501` (gate 13.2-②): the tracker uses it to fill a second `PipeInputs` for the comparator.
|
||||
- `ARCHITECTURE.md:367` (§9.6): `> `MOBILEGL_PIPE_PUSH` 子系统位图(含一位关闭 CSO 内容寻址,负面对照)在阶段 B 是真正的旧-vs-新 A/B;阶段 C 之后不是——位清零时 `SnapshotFromGLContext()` 仍要合成句柄,后端仍跑重键后的 memo 代码,一个重键 bug 两臂都在。`
|
||||
- `ARCHITECTURE.md:369` (P13): delete its non-verify branch, keep the verify branch **plus the `MG_State` include it needs**.
|
||||
- `ROADMAP.md:30` (P13 row): `删 `SnapshotFromGLContext()` 非 verify 分支、`MGB_CTX`、`MOBILEGL_PIPE_PUSH`、`MOBILEGL_PIPE_LEGACY_MEMOS`;保留 `MOBILEGL_PIPE_VERIFY``.
|
||||
|
||||
So `SnapshotFromGLContext()` has **two branches from birth**: a non-verify branch (the pull path — what phase A's `MGB_CTX` `#else` arm effectively is) and a verify branch. P1 authors both.
|
||||
|
||||
### 2.9 The `SyncPersistentMappedRange` / `SyncGpuWrites` per-site ownership table
|
||||
|
||||
The rule the table has to encode is the stale-index discipline, `ARCHITECTURE.md:233-238` (§5.7) — verbatim:
|
||||
|
||||
> **陈旧索引纪律是逐站点表,不是一条笼统规则**(client 侧扫描/解析之前要做的 reconcile 必须逐字复现 monolith 的集合):
|
||||
>
|
||||
> | client 侧动作 | 必须做的 reconcile |
|
||||
> |---|---|
|
||||
> | client 顶点数组范围计算 + 暂存 | 无(应用内存,无 GPU 写者) |
|
||||
> | 最大索引扫描(EBO 源) | `SyncPersistentMappedRange()` **+** `SyncGpuWrites()` |
|
||||
> | 最大索引扫描(client 指针源) | 无 |
|
||||
> | `*IndirectCount` 计数解析 | **只** `SyncPersistentMappedRange()`,不加 `SyncGpuWrites()`——monolith 今天就只做这一个,加了会给 Create/Flywheel 的每 batch 平白加一次 publish-and-wait |
|
||||
> | server 侧 restart 重写 / multi-draw 展平 | server 从镜像读;GPU 写者可见性由 `OnGpuWritten` 收窄集在 server 本地判定 |
|
||||
|
||||
And `ARCHITECTURE.md:294` (§8.1, last sentence): `> 20 处 `SyncPersistentMappedRange` + 6 处 `SyncGpuWrites` 按 §5.7 逐站点归属,其中至少一处消费者搬不走:Magma 的 `ResolveUniformBufferPayload` 把具名 UBO 打进自己的 UBO ring → `SetShaderBuffers` 的 host payload(D-B8)。`
|
||||
|
||||
Also relevant to the same table: `ARCHITECTURE.md:239` — `> 前两条 client reconcile 的形态:publish → 等 `appliedSeq` → 排空事件 → 再碰 shadow。门:`ClientArrayAfterComputeWriteScenario`(去掉等待必须看到几何缺失);`create-indirect` fixture 上 `roundtrips-per-frame` 必须读零(P8)。`
|
||||
|
||||
**The 20 + 6 sites, enumerated from this tree** (I grepped `MobileGL/MG_Backend/`; comment-only hits excluded and listed separately). The doc's counts match exactly.
|
||||
|
||||
`SyncPersistentMappedRange()` — 20 call sites:
|
||||
|
||||
| # | Site | Backend |
|
||||
|---|---|---|
|
||||
| 1 | `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:263` `drawBuffer->` | Espryt |
|
||||
| 2 | `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:4468` `indexBuffer->` | Espryt |
|
||||
| 3 | `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:4722` `drawBuffer->` | Espryt |
|
||||
| 4 | `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:4723` `parameterBuffer->` | Espryt |
|
||||
| 5 | `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:4824` `drawBuffer->` | Espryt |
|
||||
| 6 | `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:4825` `parameterBuffer->` | Espryt |
|
||||
| 7 | `MobileGL/MG_Backend/DirectGLES/Managers.cpp:1569` `bufferObject->` | Espryt |
|
||||
| 8 | `MobileGL/MG_Backend/DirectGLES/MultiDraw.cpp:510` `indexBuffer->` | Espryt |
|
||||
| 9 | `MobileGL/MG_Backend/DirectVulkan/DirectVulkan.cpp:280` `drawBuffer->` | Magma |
|
||||
| 10 | `MobileGL/MG_Backend/DirectVulkan/DirectVulkan.cpp:471` `parameterBuffer->` | Magma |
|
||||
| 11 | `MobileGL/MG_Backend/DirectVulkan/DirectVulkan.cpp:795` `indexBufferShared->` | Magma |
|
||||
| 12 | `MobileGL/MG_Backend/DirectVulkan/Renderer/UniformManager.cpp:2023` `bufferObject->` | Magma (**the immovable consumer**: `ResolveUniformBufferPayload` / D-B8) |
|
||||
| 13 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferManager.cpp:628` `bufferObject->` | Magma |
|
||||
| 14 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VkBufferManager.cpp:679` `bufferObject->` | Magma |
|
||||
| 15 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:3434` `indexBufferShared->` | Magma |
|
||||
| 16 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:3513` `bufferObject->` | Magma |
|
||||
| 17 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:3828` `sourceBufferShared->` | Magma |
|
||||
| 18 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:7137` `indirectBuffer->` | Magma |
|
||||
| 19 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:12132` `drawBuffer->` | Magma |
|
||||
| 20 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:12133` `parameterBuffer->` | Magma |
|
||||
|
||||
Comment-only mentions to keep in view while writing the table (they carry the reasoning): `DirectGLES/Managers.cpp:1461` (`// A live non-zero-copy map may owe a per-draw SyncPersistentMappedRange push`), `DirectGLES/Managers.cpp:2681`, `DirectVulkan/Renderer/VulkanRenderer.h:1214` (`// SyncPersistentMappedRange is the push-down. A map taken AFTER the record …`).
|
||||
|
||||
`SyncGpuWrites()` — 6 call sites:
|
||||
|
||||
| # | Site | Backend |
|
||||
|---|---|---|
|
||||
| 1 | `MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp:4469` `indexBuffer->` (pairs with #2 above) | Espryt |
|
||||
| 2 | `MobileGL/MG_Backend/DirectGLES/Managers.cpp:2643` `bufferObject->` | Espryt |
|
||||
| 3 | `MobileGL/MG_Backend/DirectGLES/MultiDraw.cpp:511` `indexBuffer->` (pairs with #8 above) | Espryt |
|
||||
| 4 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:3433` `indexBufferShared->` (pairs with #15) | Magma |
|
||||
| 5 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:3827` `sourceBufferShared->` (pairs with #17) | Magma |
|
||||
| 6 | `MobileGL/MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:4161` `indexBufferShared->` | Magma |
|
||||
|
||||
Comment-only: `DirectGLES/DirectGLES.cpp:459`, `DirectGLES/DirectGLES.cpp:509`.
|
||||
|
||||
Note the pattern the table has to preserve: the EBO/max-index sites pair the two calls (rows 1/3/4/5 of the `SyncGpuWrites` list sit immediately after a `SyncPersistentMappedRange` on the same object), whereas the `*IndirectCount` parameter-buffer sites (`DirectGLES.cpp:4722-4723`, `:4824-4825`, `DirectVulkan.cpp:471`, `VulkanRenderer.cpp:12132-12133`) deliberately do **not** call `SyncGpuWrites` — exactly the row `> `*IndirectCount` 计数解析 \| **只** `SyncPersistentMappedRange()`` in the §5.7 table, and the subject of open question 15 (§6 below).
|
||||
|
||||
### 2.10 The five-part verification gates (ARCHITECTURE §13.2, `ARCHITECTURE.md:498-506`)
|
||||
|
||||
Preamble, `ARCHITECTURE.md:499`: `> "改前改后 `nm --defined-only` 与 `.text` size 完全相等"的门在本方案里按构造死亡(不存在能让旧字节回来的配置);替换是:`
|
||||
|
||||
**① Interface purity, three gates** (`ARCHITECTURE.md:500`) — verbatim:
|
||||
|
||||
> 1. **接口纯度三道门**(只跑非 verify 构建):**A 门 include 图**——disaggregated 配置编译 `MG_Backend` 时把 `MG_State/GLState` 从 include 搜索路径移除(`nm --undefined-only` 对"只 include 不调用"是瞎的,而 `RenderState.h → FramebufferObject.h → TextureObject.h` 正是这种耦合),依赖 P0.5;**B 门符号**——`nm --undefined-only libMobileGLServer.so | grep -E 'MG_State::GLState::|glslang'` 为空;**C 门未声明**——`grep -c 'pGLContext' MG_Backend/` == 0。外加 debug 断言"每个后端 memo 键都是 `{slot, gen}`,永不是裸前端指针",由 `HandleRecycleScenario` 支撑(重键前必须在至少一个后端上是红的)。
|
||||
|
||||
All three turn green only in P13 (`ARCHITECTURE.md:369`). P1 must not make them *further* from green: in particular gate C greps the bare token `pGLContext`, so the `MGB_CTX` `#else` arm must be defined outside `MG_Backend/`.
|
||||
|
||||
**②** — the verify comparator, quoted in full in §2.5 above (`ARCHITECTURE.md:501`). **This is P1's gate.**
|
||||
|
||||
**③ Behavioural A/B** (`ARCHITECTURE.md:503`) — verbatim:
|
||||
|
||||
> 3. **行为 A/B**:40 个 trace 在 `{monolith-pull, monolith-push, split}` 下 SSIM ≥ 0.99(默认阈值);`ctest -L integration-gpu` 在 `DirectGLES.` 与 `DirectGLES.Pipe.`/`DirectGLES.Split.`(DirectVulkan 同)之间逐名相同;单元测试全绿;CTS 逐后端 conformance 在 0.5 pp 内(行 = GL 版本/扩展,列 = 状态计数,rate = Pass/(Pass+Fail),NS 不进分母)。`TextureUploadShapeScenario` 把逐纹理逐帧的上传形状(box vs N region、作业数)录金标比对——+6 ms 悬崖由形状相等把关,SSIM 对它完全不敏感。逐名功能基线是"P1 出口的重构后 monolith"(P1 出口先用 verify 证明等价于 `81b17c0b`);`81b17c0b` 只作性能锚点。
|
||||
|
||||
**④ Monolith performance non-regression** (`ARCHITECTURE.md:504`) — verbatim:
|
||||
|
||||
> 4. **monolith 性能不回归**:两台设备 reboot-clean、同热窗口、配对 A/B,`tools/bench.sh` + trace replay `--benchmark` 逐帧 JSON;**指标是逐线程 CPU 时间**,p50 与 p99;**绝对阈值**——tracker 每 draw 的 ns 公布并设上限(真实拉取基线只有每 draw 6.5–9.3 次 accessor,相对噪声阈值会平凡通过);Blaze3D blend-toggle 微基准单列;关掉 CSO 内容寻址的负面对照。
|
||||
|
||||
**⑤ Coverage + poison + handle discipline** (`ARCHITECTURE.md:505`) — verbatim:
|
||||
|
||||
> 5. **覆盖 + poison + 句柄纪律**:G6 重生成 0 UNMAPPED;`gen_pipe_dirty_surface.py` 重生成 0 未映射 mutator;逐 verb 世代 poison;G7 setter 一致性测试;`ResidualValueBlock` 的 `offsetof` 断言与 P13 的 `sizeof == 0`。
|
||||
|
||||
Of ⑤, P1 owns: the poison, and the `gen_pipe_dirty_surface.py` mapping-with-zero-unmapped gate (`ARCHITECTURE.md:172`, `ARCHITECTURE.md:568`, `scripts/gen_pipe_dirty_surface.py:21-22`) — see risk R2.
|
||||
|
||||
Two surviving byte-level equalities (`ARCHITECTURE.md:506`) — verbatim: `> `MOBILEGL_BUILD_DISAGGREGATED=OFF` 时 `nm --defined-only libMobileGL.so | grep MG_Remote` 为空且链接行不增加库;`nm -D libMobileGL.so | grep mobilegl_server_main` 在 RelWithDebInfo 里命中。符号与 `.text` 漂移每阶段作为信息性指标发布。`
|
||||
|
||||
---
|
||||
|
||||
## 3. What P2 expects P1 to have left in place
|
||||
|
||||
P2 row, `ROADMAP.md:18`, deliverables verbatim:
|
||||
|
||||
> `MG_Impl/Pipe/Tracker`(dirty 位、5 个聚合世代、抑制器骨架);`gen_pipe_dirty_surface.py` 首轮映射成门;`MGPipeRenderStateSpans` + G7 setter 一致性测试;`CsoCache`(64 项,键 = pipeline 子集);`create/bind_render_state` + `set_dynamic_state`(Espryt `SyncRenderState` 一行不动;Magma `ComputePipelineStateHash`/`GetOrCreatePipeline`/`ApplyDynamicDrawStateTail` 改从 CSO 与动态 payload 取);`set_pixel_pack_state`、`set_patch_state`、`set_vertex_attrib_defaults`;`set_residual_value_state` + `ResidualValueBlock` 绊线;**第一片 Track H**:Espryt 0b(`SlotAllocator` + 6 个 registry → slot 数组 + 删 `TwinLookupMemo`×3/`OwnerEquals`/`g_fbSlotCache`/GC)与 Magma 子系统 4(`VertexInputStateFactory`/`VaoDrawMemo` 重键,删前端 VAO 里的后端裸指针);`MOBILEGL_PIPE_LEGACY_MEMOS`;补 `FramebufferSrgb`/`DepthClamp` 存储
|
||||
|
||||
P2's acceptance gate, verbatim:
|
||||
|
||||
> 集成 × 2 后端 × {pull, push} 逐名相同;40 trace push 下 SSIM ≥ 0.99 双后端;verify 零分歧;`HandleRecycleScenario` 绿且重键前红;G7 测试绿且拿掉一个字段能红;两台设备配对逐线程 CPU p50/p99 不差且 tracker 绝对 ns 在上限内;Blaze3D blend-toggle 微基准;CSO 内容寻址关闭的负面对照
|
||||
|
||||
Concretely, P1 must not paint P2 into a corner on:
|
||||
|
||||
1. **A `{pull, push}` A/B arm that is real.** P2 compares integration × 2 backends × `{pull, push}` by name. That requires the `MOBILEGL_PIPE_PUSH` bitmap to genuinely select per subsystem, per field (phase B: `> 填充器按 `MOBILEGL_PIPE_PUSH` 位图逐字段让位`, `ARCHITECTURE.md:345`). P1's accessors and fill points must be structured so a *field-granular* yield is possible, not just a whole-build switch. Note the honesty caveat P1 inherits (`ARCHITECTURE.md:367`): after phase C the bitmap stops being a true A/B, which is why P2 also introduces the compile-time `MOBILEGL_PIPE_LEGACY_MEMOS` (default ON) arm.
|
||||
2. **`SyncRenderState` untouched.** `ARCHITECTURE.md:348`-region §5.3, `ARCHITECTURE.md:347`: `> **Espryt 的 `SyncRenderState`(693 行)拿到的仍是 `const RenderStateParameters&`,单 `Uint16` 早退、三段 memcmp 一行不动**`. GO/NO-GO item 2 (`ROADMAP.md:47`) restates it: `> 两个后端上都已推送的渲染状态,`SyncRenderState` 693 行一行未动`. **P1's `PipeInputs::GetRenderStateParameters()` must therefore return `const RenderStateParameters&`** — a by-value or restructured return would force a `SyncRenderState` edit and break GO/NO-GO item 2. The doc's phase-A comment says exactly this: `// 阶段 A:类型与后端今天读到的完全一致` (`ARCHITECTURE.md:328`).
|
||||
3. **Server-side working `RenderStateParameters`.** `ARCHITECTURE.md:347`: `> server 侧:每 context 一份 working `RenderStateParameters`(1168 B),`bind` 与 `set_dynamic_state` 各把自己的 chunk 散射进去。` P1's `PipeInputs` is where that working copy will live in P2. Size it for that (`~20 KB`, `ARCHITECTURE.md:326`).
|
||||
4. **The five aggregate generations are new frontend fields P2 adds** (`ARCHITECTURE.md:164-169`, §5.2 table): `VertexArrayState::m_anyVaoAttributeGeneration`, `FramebufferState::m_anyAttachmentGeneration`, `TextureState::m_anyTextureContentGeneration` + `m_anyTextureParamsGeneration`, `BufferState::m_anyBufferChangeGeneration` — all marked 新增, landing "on existing bump points (~20 lines)" (`ARCHITECTURE.md:170`). P1 must not restructure those mutators in ways that scatter the bump points.
|
||||
5. **The dirty-surface mapping file.** P1 creates it (73 entries); P2 turns the first mapping into a gate (`ROADMAP.md:18`) — see risk R2 for the phase disagreement.
|
||||
6. **Residual value block shape.** See §2.7: `GetRenderStateParameters`, `GetPixelStoreParameters`, capability bits and the three patch fields must be reachable as whole-struct values.
|
||||
7. **CSO cache and content addressing.** `ARCHITECTURE.md:63` (§2.3): the client-side content-addressed CSO maps with LRU caps (render-state 64 / vertex-elements 1024 / sampler 256 / sampler-view 4096 / shader tied to `ProgramObject` lifetime). P2 also needs the negative control bit inside `MOBILEGL_PIPE_PUSH` that disables CSO content addressing (`Config.h:320-325`, `ARCHITECTURE.md:367`, `ROADMAP.md:52`), so P1's use of the bitmap must leave that bit free and meaningful.
|
||||
8. **Track H's first slice needs handles to be a `PipeInputs` field type.** Phase C (`ARCHITECTURE.md:346`) turns `SharedPtr<frontend object>` fields into `MGPipeHandle` + POD descriptors. Handles already exist (`MobileGL/MG_Pipe/MGPipeHandles.h`; composite-shader band at `MGPipeHandles.h:88-90`: `kMGPipeShaderCsoSlotLimit = 1u << 20`, `kMGPipeShaderCsoCompositeSlotBase = limit - (limit >> 4)`, predicate `MGPipeIsCompositeShaderSlot` at `:92-94`). P1's object-typed accessors should be shaped so the return type can be swapped without re-touching all 167 read points a second time.
|
||||
9. **The eight validate entry points** are the frame P2's tracker hangs on (`ARCHITECTURE.md:153`). P1's fill points should be those same eight shapes, generated, not hand-placed ad hoc.
|
||||
10. **G7 chunk table is frozen in P2, not P1** (`ARCHITECTURE.md:161`: `带 `offsetof` 的 chunk 表与 setter 一致性测试在 P2`), and `Coverage.def:72-74` warns `GetProvokingVertexMode` is not in `ComputePipelineStateHash` today `/* recorded here so the G7 chunk table has to answer for it before it freezes */`. P1 must keep that accessor visible in the field list (it is, field #39).
|
||||
|
||||
---
|
||||
|
||||
## 4. Commit / CI discipline (通用纪律) and the GO/NO-GO items P1 delivers
|
||||
|
||||
### 4.1 通用纪律, `ROADMAP.md:7` — verbatim (applies to **every commit**)
|
||||
|
||||
> 默认 ALL target 必须完整构建;禁止提交热路径插桩(CI grep 门);**每个门必须能因它存在的理由变红**;Windows 机器不是正确性门;设备对比走 reboot-clean + 同热窗口配对 A/B,CPU 定频按项目协议;每阶段出口跑一次五部分门;每阶段性能判据是**逐线程 CPU 时间**。
|
||||
|
||||
Enforcement in the tree (CI job `pipe-gates`, `.github/workflows/test.yml:835-887`, deliberately independent of `build-linux` per `test.yml:838-839`):
|
||||
- `test.yml:850-853` — `python3 scripts/gen_pipe.py` then `git diff --exit-code -- MobileGL/MG_Pipe/generated`.
|
||||
- `test.yml:862-869` — stdio-instrumentation grep gate over `MobileGL/MG_Backend` and `MobileGL/MG_State`: `fprintf(stderr|stdout`, `printf(`, `puts(`, `std::cout|cerr`. `test.yml:857-861` says the gate `starts with no exceptions, and any addition to it needs a reason in the pull request rather than a quiet whitelist entry`.
|
||||
- `test.yml:871-874` — `python3 scripts/gen_pipe_dirty_surface.py --summary`, with the comment `# Informational: … It becomes a gate in P1, when the mapping file exists to diff against.`
|
||||
- `test.yml:876-887` — `check_doc_citations.py`, currently `|| true` (warning only), `# It becomes --strict when the documents settle.` **P1 edits these docs, so keep `file:line` citations correct** — the lint checks exactly the `file:line` references in `docs/Disaggregated/*.md`.
|
||||
- Separate job `include-graph-check` (`test.yml:332-349`): `python3 scripts/check_include_closure.py --mode both --compiler clang++-20 --self-test --require-all`. `test.yml:330-331` restates the discipline in English: `The script's own --self-test is always on: a negative control that stopped tripping fails the job, because a gate that cannot go red is not a gate (ROADMAP.md:7).`
|
||||
|
||||
Also binding on P1 commits (from repo memory / project convention, consistent with the docs): single-line `[Type] (Scope): description` messages; no `Co-Authored-By`.
|
||||
|
||||
CTS turnaround (`ROADMAP.md:34`) — verbatim: `> **CTS 周转单独计价**:`gl44to46` 约 56,271 例。逐阶段只跑该阶段可能影响的具名块(P4a `packed_pixels`、P3b/P4b `texture_*`/`shader_image_*`、P9 `transform_feedback*`);完整 caselist 只在五个架构边界(P0.5、P3a、P4a、P3b/P4b、P13)与每次合并 `dev` 之前跑,放 CI 不放关键路径。若周转仍主导排期,加宽估时而不是削弱门。` — **P1 is not one of the five full-caselist boundaries**, but a merge to `dev` still triggers a full run.
|
||||
|
||||
### 4.2 The day-43 GO/NO-GO list, `ROADMAP.md:44-52` — verbatim, P1's contribution marked
|
||||
|
||||
> 手上必须有:
|
||||
>
|
||||
> - [ ] P1 交付的逐 draw 逐字段语义等价证明(40 trace + 全部集成测试零分歧) ← **P1 delivers this one**
|
||||
> - [ ] 两个后端上都已推送的渲染状态,`SyncRenderState` 693 行一行未动
|
||||
> - [ ] 两片 Track H 的实测单位成本(Espryt 0b、Magma 子系统 4)
|
||||
> - [ ] 两台设备(Adreno 830 `35d0befa`、Mali `3B159D009VZ00000`)reboot-clean 配对的逐线程 CPU 时间增量,p50 与 p99
|
||||
> - [ ] tracker 每 draw 的**绝对 ns**(上限从设备基线定:稳态每 draw 6.5–9.3 次 accessor + memo 探测,见 `MEASUREMENTS.md`)
|
||||
> - [ ] Blaze3D blend-toggle 微基准(enable/draw/disable/draw,MC batch 速率)
|
||||
> - [ ] 负面对照:关掉 CSO 内容寻址重跑,把"推送更慢"与"CSO 设计更慢"分开
|
||||
|
||||
Verdict criteria, `ROADMAP.md:56` — verbatim: `> - **继续**:两台设备 p50 与 p99 逐线程 CPU 增量都不为负;tracker 绝对 ns 在上限内;Track H 单位成本不超出估计的 50%。按两条跑道推进。`
|
||||
|
||||
**The per-draw per-field semantic equivalence proof** = gate 13.2-② run to zero divergence over 40 traces + the whole integration suite, with both negative controls (corrupt a snapshot field → red; drop a field from `glGenerateMipmap`'s fill table → poison Fatal on that verb). It is P1's single most important artifact and it is the first line of the GO/NO-GO list.
|
||||
|
||||
The absolute-ns ceiling P1's work is later measured against comes from `MEASUREMENTS.md:50-60` (the four-trace table) and `MEASUREMENTS.md:64`: `> **真机稳态动态 accessor 成本是每 draw 6.5–9.3 次**(预测区间 10–25 的下沿;llvmpipe 的 15.5/20.7 是 memo 冷的)。推送要打败的是 ~8 次 accessor + memo 探测,不是 124/169 的静态调用点数。GO/NO-GO 的 tracker 绝对 ns 上限从这里定。` The measured per-draw accessor counts: Espryt 9.28 / Magma 8.56 on `minecraft-1.21.4-in-world` (`MEASUREMENTS.md:52-53`); Espryt 8.44 / Magma 6.53 on `improved-transparency-minecraft-26.3` (`MEASUREMENTS.md:56-57`). `MEASUREMENTS.md:60` warns `accessor-calls` is a **lower bound** (static counting at ~10 hot entry points; site list is a contract at `MobileGL/MG_Util/Metrics/PipeStats.cpp:16-100`).
|
||||
|
||||
---
|
||||
|
||||
## 5. Open questions and caveats that touch P1
|
||||
|
||||
From `ROADMAP.md:70-90` ("仍然开放的问题"), the ones that bear on P1:
|
||||
|
||||
- **#1** (`ROADMAP.md:74`) — `> **client 侧 dirty 走查的真实每 draw CPU 代价。** 拉取基线已实测为每 draw 6.5–9.3 次 accessor + memo 探测;推送要在这个数字下净减少。P2 的头号数字,逐线程 CPU + 绝对 ns,两台设备。` P1's accessor design determines whether this is measurable at all; P1 should keep the accessor call path cheap enough that the P2 number is not dominated by P1 scaffolding.
|
||||
- **#5** (`ROADMAP.md:78`) — `> **`FramebufferSrgb` / `DepthClamp` 的拍板。** 事实已清(无存储、`glEnable` 静默吞掉、六个读点恒 false、41 个 fixture 无一开启);建议在 chunk 表冻结前补真存储并把 `FramebufferSrgb` 划进 pipeline 半边。由计划所有者拍板,**拍板前不冻结 chunk 表**。` The six `FramebufferSrgb` read points are inside `MG_Backend` and are read points P1's `sed` will touch; today they consume a compile-time `false` (`MEASUREMENTS.md:84`). P1 must alias them without silently changing them, and must not freeze the chunk table.
|
||||
- **#7** (`ROADMAP.md:80`) — `> **`MG_Util` 的切割缝。** server 需要 SPIRV-Cross pass 流水线、ESSL 转译缓存、格式处理器、POST 探针;client 需要 glslang phase A/B 与反射层。P0.5 解决了 `ProgramObject.h` 一处,`MG_Util` 内部是否有干净的 Transpile-vs-Reflect 缝未审计。` Unaudited; may surface as an unexpected include when P1 touches backend TUs.
|
||||
- **#14** (`ROADMAP.md:87`) — `> **推送模型改变哪些按拉取模式调过的缓存命中率。** 幸存者容量在 P13 重调。`
|
||||
- **#15** (`ROADMAP.md:88`) — `> **monolith 的 `*IndirectCount` 不调 `SyncGpuWrites()` 是不是潜在缺口**(compute 写的 indirect buffer)。独立 `dev` 问题,拆分不得借机顺手修。` **Directly aimed at P1's per-site ownership table**: the `*IndirectCount` rows must record today's behaviour verbatim, bug included. Do not "fix" it in P1.
|
||||
- **#17** (`ROADMAP.md:89-90`) — `> **create-indirect fixture 在 Adreno 830 上的失败**是 `dev@81b17c0b` 就有的(基线 APK 复现),不是本分支造成;它是 P3a/P8 验收清单里的用例,需要先在 `dev` 上修。` P1's "40 trace" gate inherits this: `MEASUREMENTS.md:96` — `minecraft-1.21.1-neoforge-create-indirect-in-world` fails on **both** devices (Adreno: Espryt black frame after ~4.5 min, Magma `VK_ERROR_DEVICE_LOST` on texture upload submit; Mali: SSIM 0.85 / 0.45). Expect it to be excluded or waived when running the 40-trace verify sweep.
|
||||
|
||||
Other caveats in the docs that touch P1:
|
||||
|
||||
- `ARCHITECTURE.md:3` — `> 落地状态以 `feat/disaggregated@458ccde1` 为准` while `README.md:3` says P0.5 landed at `5d99ee43`; `ROADMAP.md:3` still says `P0 已落地(feat/disaggregated@458ccde1)`. The docs' own commit anchors are inconsistent; the ROADMAP table cells are the current truth.
|
||||
- `ARCHITECTURE.md:172` measured surface: `> 926 次 mutator 调用落在 73 个不同 mutator 上` vs `MEASUREMENTS.md:81` which says `73 个不同 mutator(`RecordError` 一项就占 836 次)` and `92 次(36 个即时发布点、7 个 mutator …)`. `ARCHITECTURE.md:172` says 92 calls / 7 mutators without the 36. Consistent enough; use `MEASUREMENTS.md:81` for the full shape. Scanner limits are stated at `scripts/gen_pipe_dirty_surface.py:196-198`: it matches braced bodies textually, a mutator inside a lambda is attributed to the enclosing function, and a mutation published through a helper reads as deferred.
|
||||
- `ARCHITECTURE.md:33` (§1.3) — the `Init.cpp` hook branch lands in P5, **not** P1: `> (分支在 P5 落地;P0 的 `Init.cpp` 尚未含它。)`
|
||||
- `MobileGL/MG_Pipe/Coverage.def:16-17` says UNMAPPED rows are `allowed in P0 and merely counted, ZERO from P5 onward`, while gate 13.2-⑤ (`ARCHITECTURE.md:505`) says `G6 重生成 0 UNMAPPED` as a standing gate and `MEASUREMENTS.md:82` reports **0 UNMAPPED already**. No action for P1 beyond keeping it at zero when `GetBufferBindingSlot` is split by target (`Coverage.def:36-40`).
|
||||
- `MEASUREMENTS.md:92-95` harness traps that will bite a P1 device run: the trace app never reaches `MobileGL::DestroyImpl` so `MOBILEGL_PIPE_STATS_FILE` JSON never lands on device (only the periodic `MGPipe stats:` line in `mobilegl.log`); `run_android_retrace_local.py` `rmtree`s one shared result root per tree, so two devices must run **serially** from one tree; `--env` values containing `/data/...` need `MSYS_NO_PATHCONV=1`.
|
||||
|
||||
---
|
||||
|
||||
## 6. Risks / discrepancies I found (read these before starting)
|
||||
|
||||
**R1 — the "293 sites" figure does not match this tree.** `ROADMAP.md:17` and `ARCHITECTURE.md:344` both say `sed` 293 sites. Measured here: `grep -rno "MG_State::pGLContext->" MobileGL/MG_Backend/` → **277** occurrences (274 distinct lines), distributed: `DirectGLES/DirectGLES.cpp` 91, `DirectGLES/Managers.cpp` 15, `DirectGLES/MultiDraw.cpp` 5, `DirectGLES/Utils.cpp` 2, `DirectVulkan/BackendObject_DirectVulkan.cpp` 2, `DirectVulkan/DirectVulkan.cpp` 12, `DirectVulkan/Renderer/UniformManager.cpp` 14, `DirectVulkan/Renderer/VkClearManager.cpp` 1, `DirectVulkan/Renderer/VkRenderPassManager.cpp` 3, `DirectVulkan/Renderer/VkTextureManager.cpp` 2, `DirectVulkan/Renderer/VulkanRenderer.cpp` 127. The **58 non-arrow lines matches exactly** (`DirectGLES/DirectGLES.cpp` 1, `DirectGLES/Managers.cpp` 8, `DirectVulkan/BackendObject_DirectVulkan.cpp` 2, `DirectVulkan/DirectVulkan.cpp` 35, `DirectVulkan/Renderer/UniformManager.cpp` 9, `DirectVulkan/Renderer/VertexInputStateFactory.h` 1, `DirectVulkan/Renderer/VulkanRenderer.cpp` 2). Likely the 293 was counted at a different commit or with a different spelling. **Re-count and update `ROADMAP.md:17` / `ARCHITECTURE.md:344` as part of P1**, since these are cited numbers under the doc-citation lint.
|
||||
|
||||
**R2 — the dirty-surface mapping gate is assigned to two different phases.** `ARCHITECTURE.md:172` (`P1 起成为门`), `ARCHITECTURE.md:568` (`信息性,P1 成门`), `scripts/gen_pipe_dirty_surface.py:21-22` and `.github/workflows/test.yml:872-873` all say **P1**. `ROADMAP.md:18` puts `gen_pipe_dirty_surface.py 首轮映射成门` in the **P2** deliverables and the P1 row does not mention it. Resolve before planning P1's day budget — 73 mapping entries is real work and the P1 row's 10–13 days does not obviously include it.
|
||||
|
||||
**R3 — `MOBILEGL_PIPE_PUSH` is simultaneously a preprocessor condition and a runtime `Uint64` bitmask.** `ARCHITECTURE.md:334` uses `#if MOBILEGL_PIPE_PUSH` to switch `MGB_CTX`; `MobileGL/Config.h:326` defines `Uint64 PipePush = 0;` and `MobileGL/ConfigLoader.cpp:245` reads it from the environment; `ARCHITECTURE.md:345` says the fillers yield per field **according to the bitmap**. These cannot both be the same symbol. P1 must pick the spelling (e.g. a CMake `MOBILEGL_PIPE_PUSH` selecting the alias arm, with `MG_Config::Features.PipePush` selecting subsystems at run time) and write it down; leaving it ambiguous is how P2's `{pull, push}` by-name A/B silently degenerates into a single arm.
|
||||
|
||||
**R4 — `MGB_CTX`'s `#else` arm spells `pGLContext`.** Purity gate C greps the bare token under `MG_Backend/` (`ARCHITECTURE.md:502`, and `ARCHITECTURE.md:349`'s last sentence says so explicitly). Define the macro outside `MG_Backend/` (e.g. in `MG_Pipe/`) so the pull arm's spelling does not live where the gate looks. Gate C is not required green until P13, but placing it wrong makes P13 a second migration.
|
||||
|
||||
**R5 — sticky fields are unaudited.** All 61 entries of `kMGPipeInputFieldSticky[]` are `false` today (`PipeFilled.inc:163-225`). Any `true` P1 introduces is a field the poison stops protecting (`PipeFilled.inc:160-162`). Candidates that will *look* sticky and probably are not: `GetTextureContextId`, `GetTextureBindGeneration`, `GetSamplingResolutionGeneration`, `GetTransformFeedbackGeneration`, `GetPipelineStateVersion`, `GetRenderStateParametersVersion`. Each `true` needs a written argument in the commit.
|
||||
|
||||
**R6 — `MGPipeTypes.h` still includes `MG_Backend/BackendObject.h`.** `MobileGL/MG_Pipe/MGPipeTypes.h:25-34` documents this as P0.5 debt: `MGPCaps` embeds `DynamicBackendParameters`, so purity gate A asserts `MGPipeValueTypes.h` instead of `MGPipeTypes.h`, and `// The caps block needs fixed-width members before it can move (a type change, not a move): P1/P7.` (`MGPipeTypes.h:32`). P1 may be expected to do the fixed-width conversion; it is **not** in the ROADMAP P1 row. Confirm scope with the plan owner rather than discovering it when gate A is re-tightened.
|
||||
|
||||
**R7 — the four memcmp-fallback types.** `scripts/gen_pipe.py:167-172` (`MEMCMP_FALLBACK_TYPES = {RenderStateParameters, PixelStoreParameters, DynamicBackendParameters, MGHostSpan}`) and `PipeVerify.inc:232-237` both say P1 gives them field lists. Not listed in the ROADMAP P1 row either, but it is a *precondition of "zero false positives"* for the P1 verify gate — `RenderStateParameters` is precisely the struct documented to false-DIFFER under memcmp (`PipeFields.def:11-13`). Treat it as part of deliverable 5.
|
||||
|
||||
**R8 — verify's cost.** 5–10× slowdown over 40 traces + the whole integration suite, on two contended devices, with the serial-run constraint from `MEASUREMENTS.md:93`. Budget device time; the P1 row's 10–13 days does not price CTS turnaround (`ROADMAP.md:34`).
|
||||
|
||||
---
|
||||
|
||||
## 7. Quick reference: files P1 touches or creates
|
||||
|
||||
| Path | Status | Role in P1 |
|
||||
|---|---|---|
|
||||
| `MobileGL/MG_Backend/MGPipe/PipeInputs.h` | **create** | The 61-field struct, Espryt 32 / Magma 55 accessors, poison state (`ARCHITECTURE.md:325-340`, `:553`) |
|
||||
| `MobileGL/MG_Backend/MGPipe/MGPipeImpl_DirectGLES.cpp` | **create** | `ARCHITECTURE.md:553` |
|
||||
| `MobileGL/MG_Backend/MGPipe/MGPipeImpl_DirectVulkan.cpp` | **create** | `ARCHITECTURE.md:553` |
|
||||
| `MobileGL/MG_Backend/DirectGLES/*`, `DirectVulkan/*` | edit | 277 arrow sites + 58 non-arrow lines (R1) |
|
||||
| `MobileGL/MG_Impl/GLImpl/**` | edit | ~93 (measured 91-line) boundary sites get generated validate/fill calls |
|
||||
| `MobileGL/MG_Pipe/PipeFields.def` | edit | field lists for the four memcmp-fallback types (R7) |
|
||||
| `MobileGL/MG_Pipe/Coverage.def` | edit | split `GetBufferBindingSlot` by `BufferTarget` (`Coverage.def:36-40`) |
|
||||
| `MobileGL/MG_Pipe/generated/*.inc` | regenerate + commit | CI diffs them (`test.yml:850-853`) |
|
||||
| `scripts/gen_pipe.py` | edit | G5 fill-table emission, drop fallback types |
|
||||
| `scripts/gen_pipe_dirty_surface.py` + new mapping file | edit / create | 73-entry mapping; gate (R2) |
|
||||
| `.github/workflows/test.yml` | edit | third CI mode (`MOBILEGL_PIPE_VERIFY`); promote dirty-surface to a gate |
|
||||
| `CMakeLists.txt` | edit | `MOBILEGL_PIPE_VERIFY` build option (`ARCHITECTURE.md:583`) |
|
||||
| `MobileGL/Config.h` / `ConfigLoader.cpp` | already landed | runtime `PipePush` / `PipeVerify` (`Config.h:320-332`, `ConfigLoader.cpp:245-246`) |
|
||||
| `docs/Disaggregated/*.md` | edit | keep `file:line` citations valid (`check_doc_citations.py`, `test.yml:876-887`) |
|
||||
@@ -0,0 +1,280 @@
|
||||
# Scout: the strangler scaffold that exists (P0/P0.5) and what P1 must add
|
||||
|
||||
Worktree: `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`, branch `feat/disaggregated` @ `5635e33f` ("[Docs] (Disaggregated): record the P0.5 landing"). Working tree clean except untracked `.trace-work/`.
|
||||
|
||||
Every claim below cites a file and a line I opened. Paths are repo-relative to the worktree root.
|
||||
|
||||
---
|
||||
|
||||
## 0. One-paragraph orientation
|
||||
|
||||
`MG_Pipe` is a leaf: it is a set of headers plus a `generated/` directory of seven `.inc` files, and **nothing in the shipped library compiles any of it today**. `grep` for `MG_Pipe/` outside `MobileGL/MG_Pipe/` returns exactly five hits: four `MG_State` headers include `<MG_Pipe/MGPipeValueTypes.h>` (`MG_State/GLState/FramebufferState/FramebufferObject.h:14`, `MG_State/GLState/RenderState/RenderState.h:11`, `MG_State/GLState/SamplerState/SamplerObject.h:11`, `MG_State/GLState/VertexArrayState/VertexArrayObject.h:13`) and one test includes `<MG_Pipe/MGPipe.h>` (`MG_Test/Pipe/PipeCatalogueTest.cpp:18`). `MobileGL/MG_Pipe` appears in `CMakeLists.txt` only as an include directory (`CMakeLists.txt:535`), never in `SOURCE_FILES` (which starts at `CMakeLists.txt:234` and is an explicit list, not a glob). **P1 is therefore the first change that makes the generated headers part of the library build**, and the first that gives `MG_Pipe`/`MG_Backend/MGPipe` a `.cpp`.
|
||||
|
||||
---
|
||||
|
||||
## 1. `scripts/gen_pipe.py` — the seven generators, read end to end (676 lines)
|
||||
|
||||
### 1.1 Inputs, outputs and paths
|
||||
|
||||
| what | where set |
|
||||
|---|---|
|
||||
| `REPO_ROOT` = parent of `scripts/` | `scripts/gen_pipe.py:37` |
|
||||
| `PIPE_DIR` = `MobileGL/MG_Pipe` | `:38` |
|
||||
| `GENERATED_DIR` = `MobileGL/MG_Pipe/generated` | `:39` (created if missing, `:641-642`) |
|
||||
| `INVENTORY` = `scripts/data/backend_read_inventory.md` | `:40`; missing → `sys.exit` telling you to copy it from MobileGL-CS (`:219-220`) |
|
||||
|
||||
Sources of truth read: `PipeCalls.def`, `PipeFields.def`, `Coverage.def` (all under `MobileGL/MG_Pipe/`), plus the vendored inventory markdown. Docstring at `:9-30`.
|
||||
|
||||
Banner emitted at the top of every output: `:42-55`. It hard-codes the sentence **"This file is included from MG_Pipe/MGPipe.h inside namespace MobileGL::MG_Pipe."** — any new generated file P1 adds inherits that claim, so it must in fact be included from inside that namespace or the banner text has to be parameterised.
|
||||
|
||||
### 1.2 Parsers and the validation they perform in BOTH modes
|
||||
|
||||
- `parse_calls()` `:131-160`. Finds `#define MGP_CALL_LIST_DOCUMENTED_COUNT (\d+)` (`:133-135`), then scans from the line `#define MGP_CALL_LIST(X)` and stops at **the first line that does not end in a backslash** (`:149-150`). Row regex `CALL_RE` at `:128` = `X(Name, Payload, Class, Flags)` with `Flags` allowed to contain `|`. Index is 1-based position = wire opcode (`:146`). Exits if the parsed count ≠ the documented count (`:151-154`) or on a duplicate call name (`:155-159`).
|
||||
- `parse_verify_payloads()` `:175-184`. Regex `#define MGP_VERIFY_PAYLOAD_LIST\(P\)(.*?)\n\n` — **terminated by a blank line**, so the list macro in `PipeFields.def` must be followed by an empty line. Exits if a listed payload has no `#define MGP_FIELDS_<name>(F)` (`:181-183`).
|
||||
- `check_call_payloads_have_field_lists()` `:187-195`. Every payload named in `PipeCalls.def` must either have a field list or be in `MEMCMP_FALLBACK_TYPES` (`:167-172` = `RenderStateParameters`, `PixelStoreParameters`, `DynamicBackendParameters`, `MGHostSpan`). The comment at `:165-166` says explicitly: **"They … get field lists of their own in P1"**.
|
||||
- `parse_coverage()` `:198-212`. Two macros, both blank-line-terminated: `MGP_COVERAGE_ACCESSOR_LIST(X)` → `X(Accessor, Call)` pairs (`:201-205`) and `MGP_COVERAGE_DELTA_LIST(X)` → `X(free text delta kind, Call)` (`:207-211`).
|
||||
- `parse_inventory()` `:218-237`. Reads `### \`<file>\`` headings and table rows `| line | kind | member | delta |` (`INVENTORY_ROW_RE` at `:215`).
|
||||
|
||||
### 1.3 What each generator emits
|
||||
|
||||
| gen | function | output | content |
|
||||
|---|---|---|---|
|
||||
| G1 | `gen_tables` `:244-270` | `PipeTables.inc` (108 lines) | `struct MGPipeScreen` / `struct MGPipeContext` of function pointers, split by `Class == kScreen`; `kMGPipeScreenCallCount=11`, `kMGPipeContextCallCount=60`, `kMGPipeCallCount=71`; four `static_assert`s including "table size == count × sizeof(fnptr)" and "count == `MGP_CALL_LIST_DOCUMENTED_COUNT`". Signatures come from `Call.Signature` (`:113-125`): `const <Payload>* payload`, plus `const void* varTail, Uint32 varTailCount` if `kVarTail`, plus `MGPReplySlot* reply` if `kReplySlot`. |
|
||||
| G2 | `gen_thunks` `:273-286` | `PipeThunks.inc` (302 lines) | one `inline void MGP_<Name>(...)` per call forwarding to `gMGPipeScreen.<Name>` / `gMGPipeContext.<Name>`. Example `PipeThunks.inc:20-22`. |
|
||||
| G3 | `gen_wire` `:289-371` | `PipeWire.inc` (931 lines) | `MGPWireRecHeader` (8 bytes), `enum class MGPWireOp : Uint16` with `kInvalid=0` … `kOpCount=72`, one `struct alignas(8) MGPWireRec_<Name>` per call with a composition size assertion, `MGPipeWireProtocolFatal`, the `MGP_WIRE_CHECK_BOUNDS` macro and `MGPipeApplyWireRecord()` — a skeleton switch where **every arm validates bounds then `return false`** (`:350-357` comment). Oversize-record rule (chunking at `RingProducer::MaxRecordBytes() == Capacity()/2`) documented at `:305-311`. |
|
||||
| G4 | `gen_verify` `:374-444` | `PipeVerify.inc` (573 lines) | `#include "../PipeFields.def"` (`:387`), a `MGPipeHasFieldVerifier<T>` trait, forward decls + specializations + one `MGPipeVerify(const P&, const P&, const char** outField)` per payload, the `MGPipeFieldEqual` dispatcher (`:399-418`) with the **memcmp fallback branch** and its "P1 gives them field lists … at which point this branch stops being reachable" comment (`:411-415`), the array overload (`:420-426`), the `MGP_VERIFY_FIELD` macro, and `kMGPipeVerifiedPayloadCount = 63` (tail of the file). Floats compare by bits (`:404-405`). |
|
||||
| G5 | `gen_filled` `:447-510` | `PipeFilled.inc` (308 lines) | `enum class MGPipeInputField : Uint16` of the 61 Coverage.def accessors + `kFieldCount` (`PipeFilled.inc:28`), `kMGPipeInputFieldCount` + `static_assert(== 61)` (`:93-94`), `kMGPipeInputFieldNames[]` (`:96`), `kMGPipeInputFieldSticky[]` — **every entry `false`** with the note that each `true` must be argued for in P1 (`gen_pipe.py:478-484`, output at `PipeFilled.inc:163`), `kMGPipeInputFieldFilledBy[]` (`:229`, pseudo-calls marked with a trailing comment), `struct MGPipeFilledState { Uint64 CurrentVerbSerial; Uint64 FilledGen[61]; }` (`:293`), `MGPipeInputPoisonFatal()` (`:298`) and `MGPipeInputFieldIsFresh()` (`:304`). Header comment states plainly "P0 is the skeleton … **PipeInputs itself lands in P1**" (`gen_pipe.py:461-462`). |
|
||||
| G6 | `gen_coverage` `:513-579` | `PipeCoverage.inc` (108 lines) | joins inventory rows against the accessor map (by `member`) then the delta map (by `delta`); pseudo-calls `{kClientResolved, kReverseChannel, kStructuralHandle}` at `:515`; exits if a Coverage.def call is neither a catalogue call nor a pseudo-call (`:518-520`). Emits `kMGPipeCoverage[]` (63 entries, sorted by key), `kMGPipeInventoryReadPoints=477`, `MappedToCall=299`, `ClientResolved=5`, `ReverseChannel=6`, `StructuralHandle=167`, `Unmapped=0` (`PipeCoverage.inc:96-102`) and the "every row lands in exactly one bucket" assertion (`:104-108`). |
|
||||
| G7 | `gen_span_table` `:582-616` | `PipeSpanTable.inc` (67 lines) | `kMGPipePipelineStateMembers[]` — the 24 names hard-coded in **python** at `gen_pipe.py:67-92` (taken from `VulkanRenderer::ComputePipelineStateHash`), the count, and two `extern const MGPStateChunk kMGPipePipelineChunks[]/kMGPipeDynamicChunks[]` declarations whose definitions land in `MG_Pipe/MGPipeRenderStateSpans.cpp` **in P2** (`PipeSpanTable.inc:64-67`). Three deliberate absences are named as P2 questions (`gen_pipe.py:592-601`): `FramebufferSrgb`/`DepthClamp` (no storage at all), `ProvokingVertexModeSetting`, `FrontFaceModeSetting`/`ClipOrigin`/`ClipDepthMode`. |
|
||||
|
||||
### 1.4 `write()` and `--check`
|
||||
|
||||
`write(path, text, check, changed)` `:619-626`: reads the existing file, returns if byte-identical, otherwise appends the repo-relative path to `changed` and — **only when not in check mode** — writes with `encoding="utf-8", newline="\n"` (LF, deliberate; the repo is developed on Windows).
|
||||
|
||||
`main()` `:629-671`: parses everything first (so **all validation above runs in `--check` too** — docstring `:28-29` says so explicitly), makes `GENERATED_DIR`, then writes the seven files in the fixed order `Tables, Thunks, Wire, Verify, Filled, Coverage, SpanTable` (`:646-652`), prints two summary lines and one line per UNMAPPED row (`:654-662`), and in `--check` returns **1** with `gen_pipe: OUT OF DATE: <files>` on stderr when anything would change (`:664-667`).
|
||||
|
||||
Consequence for P1: `--check` coverage of a NEW output is automatic *if and only if* the new file is produced through `write(...)` inside `main()`. A generator that writes with `open()` directly, or that emits into a path outside `GENERATED_DIR`, is invisible to both `--check` and the CI `git diff` (which only diffs `MobileGL/MG_Pipe/generated`, see §6).
|
||||
|
||||
---
|
||||
|
||||
## 2. The generated outputs as they stand
|
||||
|
||||
All seven live in `MobileGL/MG_Pipe/generated/` and are **committed**. Line counts: `PipeCoverage.inc` 108, `PipeFilled.inc` 308, `PipeSpanTable.inc` 67, `PipeTables.inc` 108, `PipeThunks.inc` 302, `PipeVerify.inc` 573, `PipeWire.inc` 931 (2397 total).
|
||||
|
||||
They are consumed in exactly one place, in this order, all **inside `namespace MobileGL::MG_Pipe`**:
|
||||
|
||||
```
|
||||
MG_Pipe/MGPipe.h:65 #include "PipeCalls.def"
|
||||
:68 #include "generated/PipeTables.inc"
|
||||
:72-73 inline MGPipeScreen gMGPipeScreen{}; inline MGPipeContext gMGPipeContext{};
|
||||
:77 #include "generated/PipeThunks.inc"
|
||||
:80 #include "generated/PipeWire.inc"
|
||||
:83 #include "generated/PipeVerify.inc"
|
||||
:86 #include "generated/PipeFilled.inc"
|
||||
:89 #include "generated/PipeCoverage.inc"
|
||||
:92 #include "generated/PipeSpanTable.inc"
|
||||
```
|
||||
|
||||
`MGPipe.h:10` includes `<Includes.h>` and `:12-15` the four sibling headers. `PipeVerify.inc` additionally does `#include "../PipeFields.def"` from inside the namespace.
|
||||
|
||||
**What compiles them today:** only `MG_Test/Pipe/PipeCatalogueTest.cpp` (target `PipeCatalogueTest`, `MG_Test/Pipe/CMakeLists.txt:3-28`; include dirs include `${MGL_ROOT}/MobileGL/MG_Pipe` at `:11`; `/Zc:preprocessor` on MSVC at `:23-25`; registered `gtest_discover_tests(... LABELS unit)` at `:28`). Registered from `MG_Test/CMakeLists.txt:88-90`.
|
||||
|
||||
Notable shapes P1 will build on:
|
||||
|
||||
- `PipeTables.inc:17-29` — the screen table ends with `FenceWaitServer`; the context table ends with `QueryTimestamp` / `QueryCounter` (tail of the file). Table member order is **catalogue order within a class**, which is *not* opcode order for the three appended calls.
|
||||
- `PipeWire.inc` gives `MGPWireOp::SetSwapInterval == 68`, `QueryTimestamp == 69`, `QueryCounter == 70`, `FenceWaitServer == 71`, `kOpCount == 72` (pinned by `PipeCatalogueTest.cpp:164-170`).
|
||||
- `PipeVerify.inc` — the `MGPipeFieldEqual` memcmp fallback is **reachable today**: `MGP_FIELDS_ResidualValueBlock` (`PipeFields.def:145-146`) names `F(RenderState)` (type `RenderStateParameters`) and `F(Pack)` (`PixelStoreParameters`); `MGP_FIELDS_MGPCaps` (`:39-40`) names `F(Dynamic)` (`DynamicBackendParameters`); `MGP_FIELDS_MGPPixelPackState` (`:139-140`) names `F(Pack)`. None of those three types defines `operator==` — `grep -n "operator==" MobileGL/MG_Pipe/MGPipeValueTypes.h` returns nothing — so all four fields fall to `std::memcmp`, which is exactly the padding-false-positive case the harness must not have.
|
||||
|
||||
---
|
||||
|
||||
## 3. `MobileGL/MG_Pipe/*.h` and the two `.def` sources
|
||||
|
||||
- **`MGPipe.h`** (93 lines). `enum MGPipeCallClass : Uint8 { kScreen, kCtxCso, kCtxState, kCtxObject, kCtxVerb, kCtxQuery, kCallClassCount }` at `:29-37` (unscoped on purpose so `PipeCalls.def` can be read by both cpp and python, `:27-28`). `enum MGPipeCallFlags : Uint32` at `:39-55` (`kNone/kNeedsAck/kHasBlob/kVarTail/kHostSpan/kReplySlot/kOptional`). Forward declaration `struct MGPipeRenderStateSpans;` at `:61` (defined in P2).
|
||||
- **`MGPipeTypes.h`** (33 KB, ~800 lines). `MGP_ASSERT_POD(T, Size)` at `:44-46`. Includes `<MG_Backend/BackendObject.h>` at `:33` — this is the reason purity gate A asserts `MGPipeValueTypes.h` and not this header (`:25-32`). `using MG_Backend::DynamicBackendParameters; using MobileGL::PixelStoreParameters; using MobileGL::RenderStateParameters;` at `:37-41`. `MGPCaps` `:126-146` (composition-based size assert at `:145`). `MGPProgramDesc` `:300-311` — `MGPBlobRef Spirv[6]` + `MGPBlobRef Reflection`, the reflection blob being "the whole LinkArtifacts + SpirvArtifacts archive" (`:297-299`). `ResidualValueBlock` `:516-527`; `#define MGL_RESIDUAL_BLOCK_SIZE 1248` at `:536` with the ratchet assertion `:537-539`. Buffer-range-in-the-box helpers `MGPipeSetSubDataBufferRange` `:593`, `MGPipeSubDataBufferOffset` `:602`, `MGPipeSubDataBufferSize` `:607`.
|
||||
- **`MGPipeValueTypes.h`** (23 KB, 548 lines). `#pragma once` **and** an include guard `MOBILEGL_MG_PIPE_VALUE_TYPES_H` at `:10-11`, with the comment "belt and braces: this file is reachable both as `<MG_Pipe/...>` and `<...>` (CMakeLists.txt:531,535)". Purity contract stated at `:23-25`. Contents: the render-state/pixel-store/sampler enums and `PixelStoreParameters` (`:208`), `PerBufferBlendState` (`:219`), `StencilFaceState` (`:229`), `RenderStateParameters` (`:239`), `SamplerParameters` (`:447`), and `namespace MG_State::GLState { VertexAttribute (:476), VertexBufferBindingPoint (:517), VertexAttributeVersion (:525) }` — i.e. it re-opens `MG_State::GLState` from inside `MG_Pipe` so old spellings still compile.
|
||||
- **`MGPipeHandles.h`** (98 lines). `enum class MGPipeKind : Uint8` `:24-40`; `struct MGPipeHandle {Uint32 Slot; Uint32 Gen;}` `:54-61` with size/align asserts `:63-65`; `kMGPipeNullHandle{0,0}` / `kMGPipeDefaultFramebuffer{0,1}` `:72-73`; `kMGPipeFirstAllocatableSlot=1` `:81`; composite ShaderCso band `:88-94`.
|
||||
- **`MGPipeHostSpan.h`** (57 lines). `kMGHostSpanSegNone=0` `:119`, `kMGHostSpanSegFromServerIndexMirror=0xFFFFFFFF` `:124`, `struct MGHostSpan` (32 bytes) `:126-137`, `MGPipeSegmentResolver` + `gMGPipeSegmentResolver = nullptr` `:144-145`, `MGPipeHostBytes()` `:148-154`.
|
||||
- **`MGPipeCallbacks.h`** (61 lines). `struct MGPipeCallbacks` with the ten reverse-channel function pointers `:182-206` (`OnGlError`, `OnGpuWritten`, `OnBufferWriteback`, `OnTextureWriteback`, `OnTexturePullRequest`, `OnMipLevelsGenerated`, `OnSurfaceChanged`, `OnCapsInvalidated`, `OnLog`, `OnXfbScatterReady`), `kMGPipeCallbackCount = 10` + size assert `:210-212`, `inline MGPipeCallbacks gMGPipeCallbacks{}` `:215`.
|
||||
- **`PipeCalls.def`** (177 lines). `#define MGP_CALL_LIST_DOCUMENTED_COUNT 71` at `:69`; the list `:72-160`; per-class counts documented `:29-37`; explicit non-migrations `:163-177`.
|
||||
- **`PipeFields.def`** (238 lines). 63 `MGP_FIELDS_*` macros `:21-219`; `MGP_VERIFY_PAYLOAD_LIST(P)` `:223-236`. Header note `:15-17`: "Adding a field to a payload without adding it here makes the comparator blind to it; **that gap closes in P1**, when the verify harness goes live and the comparator's coverage is itself asserted."
|
||||
- **`Coverage.def`** (106 lines). `MGP_COVERAGE_ACCESSOR_LIST(X)` `:29-97` (61 `X(Accessor, Call)` rows, including the three pseudo-call rows `InvalidateCompileEnv → kClientResolved` `:95`, `ValidateProgramName → kClientResolved` `:96`, `RecordError → kReverseChannel` `:97`); `MGP_COVERAGE_DELTA_LIST(X)` `:102-104` (`handle-ify (wire handle) → kStructuralHandle`, `Buffer ops delta → ResourceRespecify`). Comment at `:36-39` flags `GetBufferBindingSlot` as polymorphic over `BufferTarget` and says its rows split into four calls "**once the inventory carries the target argument (P1)**".
|
||||
|
||||
---
|
||||
|
||||
## 4. `scripts/gen_pipe_dirty_surface.py` (202 lines) — report today, gate in P1
|
||||
|
||||
Scans `MobileGL/MG_Impl/GLImpl` (`SCAN_ROOT` `:34`) for functions that BOTH mutate through `pGLContext->` with one of the prefixes `Add|Set|Mark|Bump|Allocate|Truncate|Record|Notify|Begin|End` (`MUTATOR_PREFIXES` `:37-38`, `MUTATOR_RE` `:40`) AND reach the backend via `gBackendFunctionsTable.GL.*` or `pActiveBackendObject->` (`BACKEND_RE` `:41`) in the same braced body (`FUNCTION_RE` `:42-43`, `function_bodies` `:88-103`). Comments/strings are masked first (`mask_comments_and_strings` `:46-85`). Output is a human report or `--summary` counts (`:138-141`, `:180-198`); every mutator prints `UNMAPPED` (`:178`) and the closing line says "the aggregate-generation mapping file **lands in P1**, and this report is what it has to cover" (`:193-195`). Known limits are printed by the script itself (`:196-198`): lambda bodies attributed to the enclosing function, helper-published mutations read as deferred.
|
||||
|
||||
Docstring `:21-22`: "P1 adds the mapping file and CI regenerates it with `git diff --exit-code` and zero unmapped mutators, **the same shape as gen_pipe.py's G6**." There is no mapping file and no `--check` flag today; `argparse` accepts only `--summary`.
|
||||
|
||||
---
|
||||
|
||||
## 5. `MG_State/GLState/ProgramState/ProgramArtifacts.h` (576 lines) — the P0.5 archive
|
||||
|
||||
Types: `TypeFacts` `:31`, `ResourceReflection` `:63` with the four aliases `UniformReflection`/`BlockReflection`/`PipeInputReflection`/`PipeOutputReflection` `:88-91`, `XfbVarying` `:95`, `LinkArtifacts` `:160`, `SpirvArtifacts` `:359`. Purity contract in the header banner `:16-19` (no `ShaderObject.h`, no `SpvcSession.h`, no `ShaderTranspiler/`, no `Config.h`, no `MG_Backend/`, no `BufferState/`; probe name `artifacts-header`; the token `glslang::` may appear exactly twice). Generic archive via `VisitFields(Self&, V&&)` overloads — `LinkArtifacts` visits **57 fields** (closing comment at `:534`), `SpirvArtifacts` visits **8** (`:539-547`). Size trip wires `:550-575`: `MGL_RESOURCEREFLECTION_SIZE 128`, `MGL_XFBVARYING_SIZE 128`, `MGL_LINKARTIFACTS_SIZE 1056`, `MGL_SPIRVARTIFACTS_SIZE 88`, pinned per-STL (libstdc++ only today; the libc++ branch at `:558-560` is inert until the integrator pins it). This is what `MGPProgramDesc::Reflection` (`MGPipeTypes.h:310`) will carry; nothing serializes it yet.
|
||||
|
||||
---
|
||||
|
||||
## 6. Config knobs — exact semantics, defaults and every read site
|
||||
|
||||
Declared in `MobileGL/Config.h` under the comment banner at `:319`:
|
||||
|
||||
| field | line | default | env | parsed at |
|
||||
|---|---|---|---|---|
|
||||
| `Uint64 PipePush` | `Config.h:326` | `0` | `MOBILEGL_PIPE_PUSH` (decimal or `0x`) | `ConfigLoader.cpp:245` (`QueryEnvUint64`) |
|
||||
| `Bool PipeVerify` | `:332` | `false` | `MOBILEGL_PIPE_VERIFY` | `ConfigLoader.cpp:246` (`QueryEnvFlag`) |
|
||||
| `Bool PipeStats` | `:335` | `false` | `MOBILEGL_PIPE_STATS` | `ConfigLoader.cpp:247` |
|
||||
| `Bool PipeLegacyMemos` | `:340` | `true` | `MOBILEGL_PIPE_LEGACY_MEMOS` | `ConfigLoader.cpp:251-252` — **tri-state**: `QueryEnvQuirkOverride(...) != QuirkOverride::ForceOff`, i.e. only an explicitly falsy value turns it off |
|
||||
| `Uint32 PipeTexelRetainMb` | `:344` | `0` (0–4096) | `MOBILEGL_PIPE_TEXEL_RETAIN_MB` | `ConfigLoader.cpp:253` |
|
||||
| `Uint32 PipeIndexMirrorMb` | `:349` | `64` (0–4096) | `MOBILEGL_PIPE_INDEX_MIRROR_MB` | `ConfigLoader.cpp:254` |
|
||||
| `Uint32 PipeStatsPeriod` | `:354` | `120` (1–1000000) | `MOBILEGL_PIPE_STATS_PERIOD` | `ConfigLoader.cpp:255` |
|
||||
| `String PipeStatsFile` | `:358` | `""` (no dump) | `MOBILEGL_PIPE_STATS_FILE` | `ConfigLoader.cpp:256` (`QueryEnvVariable`) |
|
||||
|
||||
`ConfigLoader.cpp:242-244` notes that no allow-list edit is needed: every `MOBILEGL_`/`LIBGL_` prefixed variable is accepted by construction. The hex/decimal parser's rules (a leading `0` is not octal; a `-` anywhere is rejected) are documented at `ConfigLoader.cpp:165`.
|
||||
|
||||
**Read sites outside Config/ConfigLoader — measured, whole tree:**
|
||||
|
||||
- `PipeStats` → `MG_Util/Metrics/PipeStats.cpp:257` (`Init()` latches `g_pipeStatsEnabled`).
|
||||
- `PipeStatsPeriod` → `PipeStats.cpp:258-260` (0 is coerced to `kDefaultSummaryFramePeriod`).
|
||||
- `PipeStatsFile` → `PipeStats.cpp:235-265` (`WriteJsonDump()` + the Init log line).
|
||||
- **`PipePush`, `PipeVerify`, `PipeLegacyMemos`, `PipeTexelRetainMb`, `PipeIndexMirrorMb`: read NOWHERE.** They are parsed and then unused — pure P0 placeholders. P1 is the first consumer of `PipeVerify` and `PipePush`.
|
||||
|
||||
There is **no CMake option and no compile-time macro** named `MOBILEGL_PIPE_VERIFY` (`grep` over `CMakeLists.txt` and all `*.txt/*.cmake` returns nothing; `option(` list is `CMakeLists.txt:5-24,108,219`). ARCHITECTURE.md:579 lists it as "计划(P1;构建期开关…)", so P1 must add the CMake option itself and decide how it interacts with the already-parsed runtime `Features.PipeVerify`.
|
||||
|
||||
Likewise **`MOBILEGL_DEBUG` does not exist anywhere in the tree** — the only hit is the plan snippet `docs/Disaggregated/ARCHITECTURE.md:330` (`#if MOBILEGL_DEBUG || MOBILEGL_BUILD_DISAGGREGATED`). The repo's real debug gate is `#if MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG` (`MobileGL/Defines.h:105`, and `MOBILEGL_ASSERT` compiles to nothing otherwise at `:113-115`). **P1 must use that spelling, not `MOBILEGL_DEBUG`.** Consequence worth stating: because `MOBILEGL_ASSERT` is already a no-op in INFO builds, deleting the ~43 `MOBILEGL_ASSERT(...pGLContext...)` lines in `MG_Backend` cannot move `.text` in an INFO build.
|
||||
|
||||
`MOBILEGL_BUILD_DISAGGREGATED` (`CMakeLists.txt:23`) appends `-DMOBILEGL_BUILD_DISAGGREGATED=1` (`CMakeLists.txt:524-526`) and the `MG_Remote` sources (`:455-490`), and gates `MG_Test/Wire` (`MG_Test/CMakeLists.txt:103-105`).
|
||||
|
||||
---
|
||||
|
||||
## 7. `MG_Util/Metrics/PipeStats.{h,cpp}` — counters P1 must keep alive
|
||||
|
||||
Header (192 lines). Enum `ByteClass` `:46-77`: `StageBuffer, StageTexture, StageUboGlobal, StageUboNamed, StageVertexClient, StageIndexClient, StageIndirectCmd, PersistentMapPush, ResidualValueBlock(placeholder, 0 until P2 — :73-75), Count`. Enum `CallClass` `:81-102`: `Draws, AccessorCalls, TextureUploadEmissions, TextureUploadBoxEmissions, TextureUploadRectEmissions, TextureUploadJobs, Count`. Enum `Gate` `:107-122`: `EsprytRenderState, EsprytTextureSyncList, EsprytUnitBindingsEpoch, MagmaDrawFastPath, MagmaPipelineMemo, MagmaDynamicTail, Count`. `kPayloadHistogramBuckets = 24` `:129` — the histogram is a **placeholder**: "MGPipe emits no records yet, so nothing in the backends calls `RecordDrawPayloadBytes`. The bucketing and the reporting are implemented and unit-tested so that the first generator to emit records only has to add the one call" (`:124-128`). API: `Enabled()` `:141`, `Init()` `:145`, `Shutdown()` `:149`, `AddBytes/AddCalls/CountGate/RecordDrawPayloadBytes` `:151-154`, `OnPresent()` `:159`, introspection `:162-173`, `FormatWindowLine()` (pure) `:179`, `AdvanceSummaryWindow()` `:183`, `FormatJson()` `:185`, test hooks `:189-190`.
|
||||
|
||||
Implementation (488 lines). The **site inventory** — "this list is the contract" — is `PipeStats.cpp:15-100`; it names what is NOT wired (compressed-texture upload, readback direction, persistent-map pushes, Magma's absent indirect array) and explains that `accessor-calls` is a **lower bound**: static tallies at ~10 hot entry points, "NOT a wrapper around all 293 `pGLContext->` sites" (`:76-88`). Counter storage `:112-124` (relaxed atomics + plain window bases). `PayloadBucketOf` `:142-152`. Name tables `:168-180`. `Init()` `:255-267`, `SummaryFramePeriod()` `:269`, `RecordDrawPayloadBytes` `:303`, `OnPresent` `:305`, `NameOf` `:362-364`, `FormatWindowLine` `:366`, `AdvanceSummaryWindow` `:434`, `FormatJson` `:448`. Called from `MobileGL/Init.cpp:114` (`Init()`, right after config load) and `Init.cpp:50` (`Shutdown()`).
|
||||
|
||||
Live counting sites (all guarded by `if (MG_Util::PipeStats::Enabled())`): DirectGLES `DirectGLES.cpp:1416,1423,1428,1520,1553,1570,2039,2045,2969,3423,3446,4368,10593`; `Managers.cpp:783,896,970,1541,2573,2607,2705,4433`; `MultiDraw.cpp:176,218,432,548,754`; DirectVulkan `DirectVulkan.cpp:1337`; `UniformManager.cpp:2080,2297`; `VkBufferManager.cpp:237,374,391,465,492,532,605,660,743`; `VkTextureManager.cpp:3154`; `VulkanRenderer.cpp:5004,5013,5257,5924,5930,6408,6442,6451,6456`.
|
||||
|
||||
**P1 obligations here:** every site above sits in a function whose `pGLContext->` reads P1 rewrites, so the tallies (`AddCalls(AccessorCalls, N)`) must be re-audited when reads move behind `PipeInputs` — the literal N at e.g. `VulkanRenderer.cpp:5273` (15) and `:6461` (3) counts accessor calls in that body. The counter NAMES are pinned by a test (§8) and are TracyPlot series names + JSON keys, so P1 must extend rather than rename; the natural P1 extension is finally calling `RecordDrawPayloadBytes` and lighting up `ResidualValueBlock`/`PersistentMapPush`.
|
||||
|
||||
---
|
||||
|
||||
## 8. The two unit suites
|
||||
|
||||
**`MG_Test/Pipe/PipeCatalogueTest.cpp` (322 lines).** Counting macros `:26-34`; per-payload POD asserts over both `MGP_CALL_LIST` and `MGP_VERIFY_PAYLOAD_LIST` `:38-44`. Tests: `HandleIsEightBytes` `:48`; `EntryCountMatchesTheDocumentedCount` `:65`; `GeneratedTablesHoldTheWholeCatalogue` `:72` (per-class 11/8/13/17/9/13 at `:86-91`); `UninstalledTablesAreAllNull` `:96`; `ResidualBlockSizeIsPinned` `:109`; `ValueTypeLayoutsArePinned` `:120` (`PixelStoreParameters` 28, `PerBufferBlendState` 28, `StencilFaceState` 28, `RenderStateParameters` **1168**, `SamplerParameters` 100, `VertexAttributeVersion` 6, `kMGMaxDrawBuffers` 8); `ResidualBlockIsExactlyItsTwoValueStructsPlusPatchTail` `:142` (offsets 0 / 1168 / 1200 / 1208); `WireOpcodesAreThePositionsInTheCatalogue` `:150`; `LateArrivalsAreAppendedWithoutRenumbering` `:164`; `ApplierAcceptsAWellFormedRecord` `:174`; `VerifyComparatorNamesTheDifferingField` `:184`; `CoverageAccountsForEveryInventoryRow` `:212` (477 rows, 0 unmapped); `PipeInputFieldsStartUnfilled` `:224` (**`EXPECT_EQ(kMGPipeInputFieldCount, 61u)` at `:225`** — this is the number that moves when P1 fixes the accessor set, see §9.1); `PipelineSubsetMembersArePinned` `:237`; `ReverseChannelHasTenCallbacks` `:244`; `HostSpanResolvesTheMonolithPointer` `:252`; `BufferRangeCarriesNoInlineHostSpan` `:271`; `SubDataBufferRangeRidesInTheUnionBox` `:297`.
|
||||
|
||||
**`MG_Test/Util/PipeStatsTest.cpp` (287 lines).** Fixture `:28`; `EnabledLatchIsTheOnlyGate` `:42`; `ByteClassesAccumulateIndependently` `:49`; `PresentClearsTheFrameButKeepsTheTotal` `:66`; `InitLatchesTheSummaryPeriodFromTheConfigAndNeverKeepsZero` `:81` (pokes `MG_Config::Features.PipeStatsPeriod` directly, `:85-92`); `GateHitsAndMissesAreSeparateCounters` `:96`; histogram tests `:112`, `:129`; `SummaryLineCarriesEveryClassAndGate` `:137`; `PerFrameFieldsKeepTwoDecimals` `:159`; `SummaryLinesReportDisjointWindows` `:174`; `FormattingTwiceDoesNotConsumeTheWindow` `:191`; zero-draw/zero-frame `:206`, `:221`; `JsonDumpNamesEveryCounter` `:234`; **`CounterNamesAreStable` `:260`** (pins all nine byte-class names and all six gate names verbatim — a rename is a breaking change); `SummaryPeriodIsOneHundredAndTwentyFrames` `:280`. Target defined at `MG_Test/Util/CMakeLists.txt:38-54`, registered `:58`.
|
||||
|
||||
---
|
||||
|
||||
## 9. CI: the `pipe-gates` job and its neighbours (`.github/workflows/test.yml`)
|
||||
|
||||
Jobs in the file: `build-linux:12`, `test:149`, `integration:205`, `flatc-check:304`, `include-graph-check:332`, `benchmark:351`, `build-retrace:407`, `trace-cases:552`, `trace-fixtures:572`, `retrace:637`, `retrace-summary:743`, `remove-artifact-clutter:784`, **`pipe-gates:835`**.
|
||||
|
||||
`pipe-gates` (`:835-887`), deliberately independent of `build-linux` (`:838-839`):
|
||||
|
||||
1. `:850-853` — **"Regenerate the MGPipe interface (G1-G7)"**: `python3 scripts/gen_pipe.py` then `git diff --exit-code -- MobileGL/MG_Pipe/generated`. Note it runs the *writing* mode and diffs, not `--check`; and the diff path is **scoped to `generated/`**.
|
||||
2. `:862-869` — stdio-instrumentation grep gate over `MobileGL/MG_Backend` and `MobileGL/MG_State` (fprintf/printf/puts/std::cout|cerr), no exceptions.
|
||||
3. `:873-874` — `python3 scripts/gen_pipe_dirty_surface.py --summary`, **informational**; the comment says "It becomes a gate in P1, when the mapping file exists to diff against."
|
||||
4. `:879-887` — `scripts/check_doc_citations.py` on `docs/Disaggregated/*.md`, warning-only (`|| true`).
|
||||
|
||||
Other relevant lanes: `test` runs `ctest -L unit` (`:186-192`); `integration` runs `ctest -L integration-gpu` **and then a second, filtered pass with an inline env var** (`MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1 ctest ... -R 'Buffer|Readback|...'`, `:281-288`) — this is the exact precedent shape for P1's third CI mode, and the comment at `:277-280` explains why an inline env works here while a ctest `ENVIRONMENT` property would not. `include-graph-check` (`:332-349`) runs `python3 scripts/check_include_closure.py --mode both --compiler clang++-20 --self-test --require-all`.
|
||||
|
||||
`scripts/check_include_closure.py` PROBES `:73-120`: `value-header` (`MG_Pipe/MGPipeValueTypes.h`, forbidding `MG_State/`, `MG_Impl/`, `MG_Backend/`, `MG_Remote/`), `artifacts-header` (`ProgramArtifacts.h`, plus `TextLimits {"glslang::": 2}`), `wire-header` (`MG_Remote/Transport/ITransport.h`, forbidding `Includes.h`). `REQUIRED_PROBE_NAMES = ("value-header", "artifacts-header")` at `:122` — deleting a probe is red. Also registered as a ctest at `MG_Test/Purity/CMakeLists.txt:9-12` (`--mode text`, label `unit`, with an explicit warning at `:11` that adding an `ENVIRONMENT` property would replace the job env).
|
||||
|
||||
---
|
||||
|
||||
## 10. P1 deliverables: what is partial, what is absent
|
||||
|
||||
### 10.1 `MG_Backend/MGPipe/PipeInputs.h` (accessors) — **nothing exists**; the field set is measurably stale
|
||||
|
||||
`MobileGL/MG_Backend/` contains only `BackendObject.cpp/.h`, `BackendObjects.h`, `Init.cpp`, `DirectGLES/`, `DirectVulkan/`. There is no `MGPipe/` directory.
|
||||
|
||||
Partial code that P1 builds on: the G5 tables (`PipeFilled.inc:28-306`) are the field id space; `MGPipeValueTypes.h` supplies the value types the phase-A accessors must return "with types identical to what the backend reads today".
|
||||
|
||||
**Measured today (whole `MobileGL/MG_Backend`, `*.cpp` + `*.h`):**
|
||||
|
||||
- `pGLContext->` occurrences: **277** (all spelled `MG_State::pGLContext->`). Per file: `DirectGLES/DirectGLES.cpp` 91, `DirectGLES/Managers.cpp` 15, `DirectGLES/MultiDraw.cpp` 5, `DirectGLES/Utils.cpp` 2, `DirectVulkan/BackendObject_DirectVulkan.cpp` 2, `DirectVulkan/DirectVulkan.cpp` 12, `DirectVulkan/Renderer/UniformManager.cpp` 14, `Renderer/VkClearManager.cpp` 1, `Renderer/VkRenderPassManager.cpp` 3, `Renderer/VkTextureManager.cpp` 2, `Renderer/VulkanRenderer.cpp` 127.
|
||||
- Lines mentioning `pGLContext` without the arrow: **58** (matches the roadmap's "58 行非箭头清单"). Breakdown of those lines: 43 `MOBILEGL_ASSERT(...)`, 14 `!= nullptr`, 5 bare `if (MG_State::pGLContext)`, 1 `== nullptr`, 1 `.get()` (`DirectGLES/DirectGLES.cpp:147`: `MG_State::GLState::GLContext* ctx = MG_State::pGLContext.get();`).
|
||||
- **ROADMAP.md:17 says "sed 293 处"; the tree has 277.** The 293 comes from the vendored inventory snapshot (`scripts/data/backend_read_inventory.md:9` "pGLContext accesses: 293"), taken before P0's D21 XFB counter-slot rekey. Implementers should work from the measured 277 + 58 and re-measure at the start of the task.
|
||||
- Distinct accessors called: **62** overall — **Espryt 32** (`DirectGLES/`) and **Magma 56** (`DirectVulkan/`), against the plan's "Espryt 32 / Magma 55".
|
||||
|
||||
**Catalogue drift, the single most important finding for P1:** the live accessor set and `Coverage.def`/G5 disagree.
|
||||
|
||||
| accessor | status |
|
||||
|---|---|
|
||||
| `GetBoundTransformFeedbackLifetimeId` | **called** at `MG_Backend/DirectVulkan/Renderer/VulkanRenderer.cpp:11219`; declared `MG_State/GLState/Core.h:441`. **No row in `Coverage.def`, no field id in `PipeFilled.inc`.** |
|
||||
| `HasOpenTransformFeedbackSpan` | **called** at `VulkanRenderer.cpp:11236`; declared `Core.h:450` (defined `Core.cpp:1278`). **No row, no field id.** |
|
||||
| `GetBoundTransformFeedbackName` | **has** a row (`Coverage.def:34`, → `SetStreamOutputTargets`) and a field id, but is **no longer called anywhere in `MG_Backend`**; the inventory row that produced it is `backend_read_inventory.md:594` pointing at `VulkanRenderer.cpp:11137`, a line the D21 rekey replaced. `Core.h:429` still declares it (frontend use only). |
|
||||
|
||||
So P1's `PipeInputs` must serve **62** accessors, `kMGPipeInputFieldCount` moves from 61 to ~62–63, and `PipeCatalogueTest.cpp:225` (`EXPECT_EQ(kMGPipeInputFieldCount, 61u)`) plus `PipeFilled.inc:94`'s `static_assert(... == 61)` must be updated in the same commit. The vendored inventory itself is stale (477 rows / 293 accesses / 57 files, `backend_read_inventory.md:8-13`) and G6's `0 UNMAPPED` is therefore a statement about the snapshot, not about HEAD — re-vendoring it (or teaching G6 to also cross-check the live tree) is a real P1 decision.
|
||||
|
||||
Also pre-flagged by the sources themselves: `GetBufferBindingSlot` is polymorphic over `BufferTarget` and its 29 rows are supposed to split into `SetVertexBuffers`/`SetIndexBuffer`/`SetIndirectBuffers`/`SetShaderBuffers` "once the inventory carries the target argument (P1)" (`Coverage.def:36-40`).
|
||||
|
||||
### 10.2 `MGB_CTX` — **nothing exists**
|
||||
|
||||
No occurrence of `MGB_CTX` anywhere in the tree. The plan's sketch is `ARCHITECTURE.md:329-334`. Constraints P1 inherits: the gating macro must be `MOBILEGL_PIPE_PUSH` as a *compile-time* macro, which today exists only as the **runtime** `MG_Config::Features.PipePush` (`Config.h:326`) — P1 must decide whether the bitmap is compile-time (as the `#if` implies), runtime, or both, and `ConfigLoader.cpp:245` already parses the runtime one. Purity gate C is specified as `grep -c 'pGLContext' MG_Backend/ == 0` (`ARCHITECTURE.md:503`, gate 1-C) — note it greps `pGLContext`, **not** `pGLContext->`, so the 58 non-arrow lines have to go too, which is why they are an explicit deliverable.
|
||||
|
||||
### 10.3 Per-verb fill points — **table exists, generator does not**
|
||||
|
||||
`kMGPipeInputFieldFilledBy[]` (`PipeFilled.inc:229-291`) records *which call* is expected to have filled each field, derived from `Coverage.def`. What does **not** exist is the inverse table the plan asks for — "G5 从 PipeCalls.def 生成『每个 `kCtxVerb`/`kCtxObject` 调用可能读哪些字段』的表,在 MG_Impl 的 ~93 个边界站点生成 validate/fill 调用" (`ARCHITECTURE.md:344`). Building it needs a *per-call → field set* relation, which `Coverage.def` today provides only in the many-to-one direction (accessor → one call). Concretely: 61 accessors map onto 20 distinct calls; inverting that gives, e.g., `CreateRenderState` ← 13 fields, `SetDynamicState` ← 14, `SetSamplerViews` ← 8. Whether that inversion is the right "may read" set for a *verb* (`DrawVbo`, `Clear`, `Blit`, `GenerateMipmap`, …) is a judgement P1 must encode — it is not derivable from the current `.def` files, because the calls named in `Coverage.def` are mostly `kCtxState`/`kCtxCso`, not verbs.
|
||||
|
||||
The "~93 边界站点" figure is the `gBackendFunctionsTable.GL.*` call-site count in `MG_Impl` that G2's thunks target (`ARCHITECTURE.md` G2 row, `:76`).
|
||||
|
||||
### 10.4 Poison generations — **skeleton exists, unused, and its debug gate is wrong**
|
||||
|
||||
Exists: `MGPipeFilledState` (`PipeFilled.inc:293-296`), `MGPipeInputPoisonFatal()` (`:298-302`, message shape `Fatal{UnmigratedPipeInput, "<field>@<verb>"}`), `MGPipeInputFieldIsFresh()` (`:304-307`), `kMGPipeInputFieldSticky[]` (`:163-227`, **all 61 entries `false`**). Missing: any instance of `MGPipeFilledState`, any bump of `CurrentVerbSerial`, any read-side assertion, and any sticky classification. The generator emits the sticky table unconditionally as `false` and its own comment (`gen_pipe.py:478-480`) demands that every `true` be argued for in P1 — meaning P1 must extend `Coverage.def` (or add a new hand-maintained source) with a sticky column, and grow `gen_filled` to consume it.
|
||||
|
||||
Gate spelling: use `#if MOBILEGL_LOG_ACTIVE_LEVEL <= MOBILEGL_LOG_LEVEL_DEBUG` (`Defines.h:104-115`) and/or `MOBILEGL_BUILD_DISAGGREGATED` — **`MOBILEGL_DEBUG` does not exist**.
|
||||
|
||||
### 10.5 The shadow comparator (G4 / `MOBILEGL_PIPE_VERIFY`) — **comparators exist; harness, snapshot and coverage assertion do not**
|
||||
|
||||
Exists and works: 63 `MGPipeVerify()` overloads, the trait, the array overload, bit-exact float comparison, first-differing-field reporting, all in `PipeVerify.inc`; unit coverage at `PipeCatalogueTest.cpp:184-208` and `:285-291`.
|
||||
|
||||
Missing / must grow:
|
||||
1. `SnapshotFromGLContext()` — does not exist anywhere.
|
||||
2. The harness that calls the comparator per draw with a draw serial.
|
||||
3. **Field lists for the four memcmp-fallback types** (`gen_pipe.py:167-172` names them; `PipeVerify.inc`'s fallback comment says P1 closes it). Today `ResidualValueBlock.RenderState` (1168 bytes), `.Pack`, `MGPCaps.Dynamic` and `MGPPixelPackState.Pack` all compare by `memcmp`, i.e. the comparator has exactly the padding false-positive property the design forbids. Adding `MGP_FIELDS_RenderStateParameters` / `_PixelStoreParameters` / `_DynamicBackendParameters` / `_MGHostSpan` to `PipeFields.def` and removing them from `MEMCMP_FALLBACK_TYPES` is a mechanical but load-bearing P1 edit; `RenderStateParameters` is defined at `MGPipeValueTypes.h:239` and is the big one.
|
||||
4. "the comparator's coverage is itself asserted" (`PipeFields.def:15-17`) — no such assertion exists. A field added to a payload in `MGPipeTypes.h` without a `PipeFields.def` entry is silently invisible today; only the *payload* (not the field) is checked (`gen_pipe.py:187-195`).
|
||||
5. The `MOBILEGL_PIPE_VERIFY` **CMake option** (absent, §6) and its interaction with the already-parsed runtime `Features.PipeVerify` (`Config.h:332`, currently read by nobody).
|
||||
6. The retain mode for consume-and-clear groups (texture dirty rects) described at `ARCHITECTURE.md:502`.
|
||||
|
||||
### 10.6 The third CI mode — **precedent exists, job does not**
|
||||
|
||||
Nothing in `test.yml` sets any `MOBILEGL_PIPE_*` variable. The shape to copy is `integration:281-288` (a second `ctest` invocation with an inline env var, plus the `:277-280` caution that a ctest `ENVIRONMENT` property would *replace* rather than extend the job env — the same trap is called out in `MG_Test/Purity/CMakeLists.txt:11` and `ARCHITECTURE.md:567`). The gate text (`ROADMAP.md:17`) is: 40 traces + all integration tests under `MOBILEGL_PIPE_VERIFY=1` with zero divergence, plus two negative controls (corrupt one snapshot field → verify red; drop one field from `glGenerateMipmap`'s fill table → poison Fatal **on that verb**). Trace lanes to hook: `trace-cases:552`, `trace-fixtures:572`, `retrace:637`; retrace env passes through `--env K=V` → intent extra `mobilegl_env` → `setenv` before loading the library (`ARCHITECTURE.md:445`).
|
||||
|
||||
### 10.7 Which generator must grow, and how `--check` must cover it
|
||||
|
||||
| generator | P1 growth | `--check` coverage requirement |
|
||||
|---|---|---|
|
||||
| **G5 `gen_filled`** | (a) absorb the 2 missing / 1 dead accessor; (b) emit a **per-verb "may read" table** (new output, e.g. `PipeFillPoints.inc`); (c) emit real sticky flags from a new column in `Coverage.def`. | Any new file must be produced by a `write(os.path.join(GENERATED_DIR, ...), ...)` call added to `main()` between `:646` and `:652` — that is what makes both `--check` and the CI `git diff -- MobileGL/MG_Pipe/generated` see it. A new *input* column must also get its own `sys.exit` validation in `parse_coverage()` so a malformed row fails in `--check` rather than silently emitting a wrong table. |
|
||||
| **G4 `gen_verify`** | consume the four new field lists; shrink/empty `MEMCMP_FALLBACK_TYPES` (`:167-172`); add a per-payload **field-count** assertion so a payload that grows a member without a `PipeFields.def` entry fails. | The field-count check needs a source of truth for "how many fields does this payload have" — the only mechanical one available is parsing `MGPipeTypes.h`, which the generator does not do today. Simplest honest form: emit `static_assert(sizeof(P) == <literal>)` next to each comparator so any layout change is red, and require the literal to be regenerated. |
|
||||
| **G6 `gen_coverage`** | re-vendor `scripts/data/backend_read_inventory.md` at HEAD (or the accessor drift stays invisible); split `GetBufferBindingSlot` by target (`Coverage.def:36-40`). | Both modes already `sys.exit` on an unknown call name (`:518-520`) and on missing macros. Keep `kMGPipeInventoryUnmapped == 0` and `PipeCatalogueTest.cpp:212-220` in sync with the new row count. |
|
||||
| **`gen_pipe_dirty_surface.py`** | add the mapping file + a `--check` mode with `git diff --exit-code` and zero unmapped mutators (its own docstring `:21-22`); promote `test.yml:873-874` from informational to a gate. | It has no `write()` helper and no `--check` at all today; both must be added, and the mapping file has to live somewhere the CI step diffs (choose a path and add it to the `git diff` argument list — the existing step only diffs `MobileGL/MG_Pipe/generated`). |
|
||||
| **G7** | untouched in P1 (chunk table + setter-consistency test are P2, `PipeSpanTable.inc:64-67`). | — |
|
||||
|
||||
Also: since P1 is the first time the library compiles `MGPipe.h`, whatever new `.cpp` files land (`MG_Backend/MGPipe/MGPipeImpl_DirectGLES.cpp`, `..._DirectVulkan.cpp`) must be added by hand to the explicit `SOURCE_FILES` list (`CMakeLists.txt:234` ff., backend block at `:366-393`) — there is no glob.
|
||||
|
||||
---
|
||||
|
||||
## 11. Naming / namespace / include conventions the new files must follow
|
||||
|
||||
1. **File header.** Every source and generated file starts with the eight-line banner: `// MobileGL - <repo-relative path>`, the two-line copyright, three licence lines, `// SPDX-License-Identifier: LGPL-3.0-only`, `// End of Source File Header`. See `MG_Pipe/MGPipe.h:1-7`, `gen_pipe.py:42-48`.
|
||||
2. **Include spelling.** `MG_Pipe` headers are reachable **both** as `<MG_Pipe/X.h>` (via `${CMAKE_SOURCE_DIR}/MobileGL` on the include path) and as `<X.h>` (via `${CMAKE_SOURCE_DIR}/MobileGL/MG_Pipe`, `CMakeLists.txt:531-535`). Because of that double reachability, `MGPipeValueTypes.h:10-11` carries **both** `#pragma once` and an `MOBILEGL_MG_PIPE_VALUE_TYPES_H` guard — new headers under `MG_Pipe/` that MG_Backend will include should do the same. `MG_Backend` headers are spelled `<MG_Backend/...>` (see `MGPipeTypes.h:33`), so the documented P1 path is **`<MG_Backend/MGPipe/PipeInputs.h>`** (`ARCHITECTURE.md:328`, build-layout table `:521`). Within `MG_Pipe` the sibling includes are relative quotes (`MGPipe.h:12-15`, `PipeVerify.inc:387` uses `"../PipeFields.def"`).
|
||||
3. **Namespaces.** Pipe code lives in `namespace MobileGL::MG_Pipe` (`MGPipe.h:26`); value types live directly in `namespace MobileGL` (`MGPipeValueTypes.h:27`) with a re-opened `namespace MG_State::GLState` inside it (`:473`) for the vertex-attribute types; counters live in `namespace MobileGL::MG_Util::PipeStats` (`PipeStats.h:41`). Backend code is `namespace MobileGL::MG_Backend` (`BackendObject.h`). The plan's `gPipeInputs` is spelled `::MobileGL::MG_Pipe::gPipeInputs` in the `MGB_CTX` sketch (`ARCHITECTURE.md:331`) even though the header lives under `MG_Backend/MGPipe/` — resolve that inconsistency explicitly rather than by accident.
|
||||
4. **Symbol naming.** Generated constants are `kMGPipe*`; generated types `MGPipe*` / `MGP*`; wire records `MGPWireRec_<CallName>`; thunks `MGP_<CallName>`; global tables `gMGPipe*`. Payload structs are `MGP<Noun>` and each gets `MGP_ASSERT_POD(T, Size)` (`MGPipeTypes.h:44-46`). Config fields are `Pipe<Thing>` on `MG_Config::Features` with env var `MOBILEGL_PIPE_<THING>`.
|
||||
5. **Generated-file discipline.** Outputs go under `MobileGL/MG_Pipe/generated/`, extension `.inc`, LF line endings (`gen_pipe.py:625`), committed to the tree, carrying the "GENERATED by scripts/gen_pipe.py from <sources> - DO NOT EDIT" banner (`:52-53`). The banner also asserts inclusion from `MGPipe.h` inside the namespace — honour it or parameterise it.
|
||||
6. **Logging.** `MGLOG_D` for non-critical (compiled out in INFO builds); `MGLOG_I` only with a stated reason (`PipeStats.cpp:224-231` is the precedent for an opt-in measurement line); `MGLOG_F` + `std::abort()` for the fatal shapes (`PipeFilled.inc:298-302`, `PipeWire.inc`'s `MGPipeWireProtocolFatal`). No `printf`/`fprintf`/`std::cout` anywhere under `MG_Backend` or `MG_State` — CI greps for it (`test.yml:862-869`).
|
||||
7. **Commit messages.** `[Type] (Scope): description`, single line, no `Co-Authored-By` (repo convention; see `git log`).
|
||||
|
||||
---
|
||||
|
||||
## 12. Traps worth carrying into the implementation
|
||||
|
||||
- `parse_verify_payloads`, and both `parse_coverage` blocks, terminate their regex at a **blank line**; appending to those macros without keeping the trailing empty line silently truncates the parse (`gen_pipe.py:177`, `:201`, `:207`).
|
||||
- `parse_calls` stops at the first line in `MGP_CALL_LIST` without a trailing backslash (`:149-150`) — a wrapped comment line inside the macro that loses its backslash silently truncates the catalogue, and the documented-count check is the only thing that catches it.
|
||||
- `PipeCatalogueTest` hard-codes 61 (`:225`), 477 (`:213`), 24 (`:238`), 71/72 (`:151-169`), 11/8/13/17/9/13 (`:86-91`), 1168/1248 (`:110-124`) — every P1 change to the field set or the catalogue lands in this file too.
|
||||
- `PipeStatsTest.CounterNamesAreStable` (`:260-279`) pins every counter name; extend, never rename.
|
||||
- The CI regeneration step diffs only `MobileGL/MG_Pipe/generated` (`test.yml:853`); a generated file placed elsewhere (e.g. a dirty-surface mapping under `scripts/data/`) needs its own diff argument.
|
||||
- `ctest` `ENVIRONMENT` properties **replace** the job environment (`MG_Test/Purity/CMakeLists.txt:11`, `test.yml:253-258`); the verify lane must set its env inline on the `ctest` command line, as the integration lane's second pass does.
|
||||
- `MG_Test/Wire` and everything under `MG_Remote/` only exist under `MOBILEGL_BUILD_DISAGGREGATED` (`MG_Test/CMakeLists.txt:103-105`, `CMakeLists.txt:455-490`); P1's work must stay green in the default OFF build, where `MGPipe.h` is compiled by nothing but the unit test today.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,257 @@
|
||||
|
||||
---
|
||||
|
||||
## C. Packages
|
||||
|
||||
**Five packages on five branches, five WSL worktrees.** The split is chosen by the code, not by P1's precedent: the value types + the chunk table + the applier are one shared contract everything else compiles against; the tracker and its caches are one client-side unit that touches no backend file; the two Track H slices are per-backend and share only the `SlotAllocator` (which is therefore in the contract); the gates, the scenario, the CI file and the measurement plumbing are cross-cutting tooling that must be able to land before the thing it gates.
|
||||
|
||||
**Branch points.** `p2/contract` from `feat/disaggregated@48268068`. Its single commit `c0` is the contract; `p2/{tracker, espryt, magma, gates}` all branch from the tag `p2/contract`, so their push builds compile and link while A finishes. `p2/spans` continues on from `c0`.
|
||||
|
||||
**Tree creation.** `scratchpad/wf4/wsl_p1_tree.sh` copied to `wsl_p2_tree.sh` with `p1`→`p2` throughout, then per slug:
|
||||
|
||||
```sh
|
||||
bash ~/w7/wsl_p2_tree.sh contract 48268068 verify # first, and it must finish before the rest
|
||||
bash ~/w7/wsl_p2_tree.sh spans p2/contract verify
|
||||
bash ~/w7/wsl_p2_tree.sh tracker p2/contract verify
|
||||
bash ~/w7/wsl_p2_tree.sh espryt p2/contract
|
||||
bash ~/w7/wsl_p2_tree.sh magma p2/contract
|
||||
bash ~/w7/wsl_p2_tree.sh gates p2/contract verify
|
||||
```
|
||||
|
||||
Each tree gets three build directories, flags identical to `~/w7/pipe/build-linux`:
|
||||
|
||||
```sh
|
||||
# pull (the G1 build)
|
||||
cmake -S . -B build-linux -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
|
||||
-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_BUILD_TYPE=Release \
|
||||
-DMOBILEGL_LOG_ACTIVE_LEVEL=MOBILEGL_LOG_LEVEL_INFO -DMOBILEGL_BUILD_TEST=ON -DMOBILEGL_BUILD_INTEGRATION_TEST=ON \
|
||||
-DMOBILEGL_BUILD_BENCHMARK=OFF -DMOBILEGL_ITEST_EGL_VENDOR=/usr/share/glvnd/egl_vendor.d/50_mesa.json \
|
||||
-DMOBILEGL_ITEST_VK_ICD=/usr/share/vulkan/icd.d/lvp_icd.json -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
|
||||
-DCMAKE_POLICY_VERSION_MINIMUM=3.5
|
||||
# push
|
||||
cmake -S . -B build-push ... same ... -DMOBILEGL_PIPE_PUSH=ON
|
||||
# verify
|
||||
cmake -S . -B build-verify ... same ... -DMOBILEGL_PIPE_VERIFY=ON -DMOBILEGL_ITEST_REQUIRE_GPU=ON
|
||||
# benchmark (package E and the integrator only; DriverBench is Linux-desktop only, CMakeLists.txt:33-35
|
||||
# force-disables the whole benchmark tree on Android)
|
||||
cmake -S . -B build-bench ... same ... -DMOBILEGL_BUILD_BENCHMARK=ON
|
||||
```
|
||||
|
||||
### C.0 Package A — `p2/contract` then `p2/spans` (trees `~/w7/p2-contract`, `~/w7/p2-spans`)
|
||||
|
||||
**Commit `c0` — the contract. Nothing in it may change after the tag without telling the other four packages.**
|
||||
|
||||
| action | file | what |
|
||||
|---|---|---|
|
||||
| MODIFY | `MobileGL/MG_Pipe/MGPipeValueTypes.h` | D3.1 — the three new `Bool`s in the `[581,584)` hole, between `ColorMasks` and `ClearColor`. The `sizeof == 1168` assert at `:541` is the check. |
|
||||
| MODIFY | `MobileGL/MG_Pipe/PipeFields.def` | D3.2 — three rows in `MGP_FIELDS_RenderStateParameters` (`:230-247`); `MGP_FIELDS_ResidualValueBlock` (`:147-148`) drops to `F(CapabilityBits)` |
|
||||
| MODIFY | `MobileGL/MG_State/GLState/RenderState/RenderState.{h,cpp}` | D3.3 (three `SET_CAPABILITY` + three `RETURN_CAPABILITY` arms, in `CapabilityInput` order) and D3.4 (`{}` on `m_parameters`, `m_pixelStorePackParameters`, `m_pixelStoreUnpackParameters`) |
|
||||
| MODIFY | `MobileGL/MG_Pipe/MGPipeTypes.h` | D9 — `ResidualValueBlock` down to `Uint64 CapabilityBits`, `MGL_RESIDUAL_BLOCK_SIZE` 1248 → 8; fix the `MGPDynamicState` comment (`:232-235`) to move "sample coverage" to the pipeline half (D6) |
|
||||
| MODIFY | `MobileGL/MG_Pipe/MGPipe.h` | D14 — the subsystem / behaviour bit constants |
|
||||
| CREATE | `MobileGL/MG_Pipe/MGPipeRenderStateSpans.{h,cpp}` | D6 — the chunk table computed with `offsetof`, the partition `static_assert`s, `MGPipeComputePipelineSubsetHash()`, and `VulkanRenderer.cpp:4780-4794`'s enumeration comment moved in as provenance |
|
||||
| CREATE | `MobileGL/MG_Pipe/PipeApply.{h,cpp}` | D2 + D5 — the seven `MGPipeApply*` entry points, the per-context CSO store, `MGPipeDeriveRenderStateFields()` |
|
||||
| CREATE | `MobileGL/MG_Impl/Pipe/SlotAllocator.{h,cpp}` | D13 — per-kind `{slot, gen}` allocator, free list + high-water, `lifetimeId → slot` maps, debug wrap assert (in the contract because both C and D need it) |
|
||||
| MODIFY | `scripts/gen_pipe.py` | extend `PIPELINE_STATE_MEMBERS` (`:75-99`) to the D6 set and rewrite `PipeSpanTable.inc`'s "deliberately absent" block (`gen_span_table()`, `:1040-1072`) to record what P2 decided; emit the `ResidualValueBlock` `offsetof` asserts; emit `kMGPipeFieldEmittedBy[]` from `MGP_COVERAGE_EMITTED_LIST` |
|
||||
| MODIFY | `MobileGL/MG_Pipe/generated/*.inc` | regenerate and commit |
|
||||
| MODIFY | `MobileGL/MG_Pipe/Coverage.def` | `MGP_COVERAGE_EMITTED_LIST` (D5); the `GetProvokingVertexMode` note at `:74-77` is answered ("in the pipeline half as of P2") |
|
||||
| MODIFY | `CMakeLists.txt` | the three new sources inside `if (MOBILEGL_PIPE_PUSH)` (`:462-468`); `option(MOBILEGL_PIPE_LEGACY_MEMOS … ON)` + `-DMOBILEGL_PIPE_LEGACY_MEMOS=1`, forced ON with a `message(STATUS)` when `MOBILEGL_PIPE_PUSH=OFF` (D14) |
|
||||
| MODIFY | `MobileGL/Config.h`, `MobileGL/ConfigLoader.cpp` | D14 — the bitmask default under `#if MOBILEGL_PIPE_PUSH`, the bit list in the comment; D18 — `Features.PipeHandleAbaControl` |
|
||||
| MODIFY | `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | D17 — `CallClass::{RenderStateCsoMints, RenderStateCsoBinds}` with short names `csom` / `csob` |
|
||||
| MODIFY | `MobileGL/MG_Test/Util/PipeStatsTest.cpp` | pin the two new names in `CounterNamesAreStable` (`:260`) and in `SummaryLineCarriesEveryClassAndGate` (`:137`) |
|
||||
| CREATE (stubs) | `MobileGL/MG_Test/Pipe/{RenderStateSpansTest, TrackerTest, SlotAllocatorTest, CsoCacheTest}.cpp` | each a compiling file with one placeholder `TEST`, so the packages that own their contents never edit `MG_Test/Pipe/CMakeLists.txt` |
|
||||
| MODIFY | `MobileGL/MG_Test/Pipe/CMakeLists.txt` | register the four stubs, `LABELS unit` |
|
||||
| MODIFY | `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp` | `:111-112` residual size 1248 → 8; `PipelineSubsetMembersArePinned` (`:354-358`) count 24 → the D6 count |
|
||||
|
||||
Ordered steps for `c0`: value types and `RenderState` first (build pull, confirm `sizeof` is still 1168 and `symbol_report --threshold 0` shows only the three named resizes) → `MGPipeTypes.h` / `PipeFields.def` / generator / regenerate → the three new source files with complete signatures and **stub bodies for `PipeApply`'s derivation** so B/C/D link → CMake / Config → tests. Then **tag `p2/contract`** and tell the other packages.
|
||||
|
||||
Message: `[Feat] (Pipe): land the P2 contract - real storage for the three swallowed capabilities, the render-state chunk table and its subset hash, the in-process applier, the slot allocator, the subsystem bitmask and the residual ratchet down to 8`.
|
||||
|
||||
**Then `p2/spans` continues** with the work only A can do:
|
||||
|
||||
- `c1`: `MGPipeDeriveRenderStateFields()` in full — the 29 derivations of D5, each transcribed from its `RenderState` getter. Message: `[Feat] (Pipe): derive every render-state PipeInputs field from the assembled working block instead of pulling it again from GLContext`.
|
||||
- `c2`: `RenderStateSpansTest.cpp` in full — D19's four tests. Message: `[Test] (Pipe): walk every RenderState setter and assert the pipeline-subset hash moves exactly when the pipeline version does`.
|
||||
- `c3`: `SlotAllocatorTest.cpp` — `Gen` moves on slot reuse and only on slot reuse; a freed slot is handed back before the high-water grows; `lifetimeId → slot` survives a recycled heap address (the `void* volatile` sink of `MG_Test/State/ObjectLifetimeIdTest.cpp:44`); slot 0 is never handed out; the composite `ShaderCso` band (`MGPipeHandles.h:83-97`) is never handed out by the ordinary allocator. Message: `[Test] (Pipe): pin the slot allocator's identity contract - gen moves only on reuse and a recycled address never reproduces a handle`.
|
||||
|
||||
**Verification (`~/w7/p2-spans`)**
|
||||
|
||||
```sh
|
||||
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test
|
||||
python3 scripts/check_include_closure.py
|
||||
cmake --build build-linux --parallel 28 && ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
|
||||
python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||||
# expect added 0 / removed 0 / renamed 0; resized == exactly RenderState::{RenderState,SetCapability,IsCapabilityEnabled}
|
||||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||||
cmake --build build-verify --parallel 28 && ctest --test-dir build-verify -L unit --no-tests=error
|
||||
bash scripts/g7_negative_control.sh build-push # must report "negative control tripped" (G7)
|
||||
sha_of_syncrenderstate () { awk '/namespace RenderStateImpl \{/,/\} \/\/ namespace RenderStateImpl/' "$1" | sha256sum; }
|
||||
sha_of_syncrenderstate MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp # equal to ~/w7/p2-before-syncrenderstate.sha (G5)
|
||||
```
|
||||
|
||||
### C.1 Package B — `p2/tracker` (tree `~/w7/p2-tracker`, from `p2/contract`)
|
||||
|
||||
**Files**
|
||||
|
||||
| action | file | what |
|
||||
|---|---|---|
|
||||
| CREATE | `MobileGL/MG_Impl/Pipe/Tracker.{h,cpp}` | D4 — `MGPipeDirty`, the tracker struct, `m_lastPushed[]` with the widened `Uint16` shutters, the per-class dirty walk, the per-bit fire counters |
|
||||
| CREATE | `MobileGL/MG_Impl/Pipe/CsoCache.{h,cpp}` | D7 — 64-entry LRU, hash → probe → `memcmp` → handle, `DeleteRenderState` on evict, the `kMGPipeBehaviourNoCsoContentAddressing` arm |
|
||||
| CREATE | `MobileGL/MG_Impl/Pipe/SetHashSuppressor.h` | D11 |
|
||||
| MODIFY | `MobileGL/MG_Impl/Pipe/PipeFill.{h,cpp}` | D1 — `MGPipeFillForVerb` → `MGPipeValidateForVerb`, the five-step body, the residual fill restricted by `kMGPipeFieldEmittedBy[]`, the `MGP_FILL` expansion |
|
||||
| MODIFY | `MobileGL/MG_Pipe/PipeMutation.h` | D4 — `MGP_NOTE_AGGREGATE(Aggregate)`, `((void)0)` in the pull build |
|
||||
| MODIFY | `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayState.*, FramebufferState/FramebufferState.*, TextureState/TextureState.*, BufferState/BufferState.*}` | D4 — the five aggregate generations, all `#if MOBILEGL_PIPE_PUSH` |
|
||||
| MODIFY | `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayObject.cpp, FramebufferState/FramebufferObject.cpp, TextureState/TextureObject.cpp, TextureState/TextureObject2DCube.cpp, SamplerState/SamplerObject.cpp, BufferState/BufferObject.cpp}` | the ~20 `MGP_NOTE_AGGREGATE` statements at the bump points D4 lists |
|
||||
| CREATE | `MobileGL/MG_Pipe/DirtySurface.def` | D16 — 73 rows |
|
||||
| MODIFY | `scripts/gen_pipe_dirty_surface.py` | D16 — `--check`, `--self-test`, mapped output |
|
||||
| MODIFY | `MobileGL/MG_Pipe/FillPoints.def` | tighten the fill table: **re-check the 8 statically over-approximated rows first** (`MEASUREMENTS.md:114-115` names the three groups: `kReadback` + `IsTransformFeedbackActive`/`IsTransformFeedbackPaused`; `kTextureOp` and `kDispatch` + `IsCapabilityEnabled`; `kBlitOrCopy`/`kTextureOp` + the shader blit's viewport and vertex/buffer bindings), and record the verdict per row in the def's comment |
|
||||
| MODIFY | `MobileGL/MG_Test/Pipe/{TrackerTest, CsoCacheTest}.cpp` | contents (the stubs are A's) |
|
||||
|
||||
**Ordered steps**
|
||||
|
||||
1. `b1`: the five aggregate generations + `MGP_NOTE_AGGREGATE`, with a unit test that each bump point moves its aggregate and no other. Build pull; `symbol_report --threshold 0` unchanged. Message: `[Feat] (State): give the frontend five aggregate generations so a tracker can answer "did any bound texture, buffer, attachment or attribute move" with one Uint64 compare`.
|
||||
2. `b2`: `Tracker.{h,cpp}` + the `MGPipeValidateForVerb` rewrite, emitting **nothing** yet — dirty computed and counted, then the full P1 residual fill runs unchanged. This step is the safety net: it proves the walk is semantically free before anything is removed. Message: `[Feat] (Pipe): compute the per-verb dirty mask at the validate point and count how often each bit fires`.
|
||||
3. `b3`: `CsoCache` + `create/bind_render_state` + `set_dynamic_state` emission; the residual fill drops the 29 derived fields. **This is where the render-state family stops being pulled.** Message: `[Feat] (Pipe): mint render-state CSOs on the pipeline subset and send only the dynamic chunks that moved - the steady-state cost of the whole render-state family is now two Uint16 compares`.
|
||||
4. `b4`: `set_pixel_pack_state`, `set_patch_state`, `set_vertex_attrib_defaults` + `SetHashSuppressor` wired to the last of the three. Message: `[Feat] (Pipe): push pixel-pack, patch and vertex-attribute-default state as their own calls, the last one behind the set-hash suppressor`.
|
||||
5. `b5`: `set_residual_value_state` + the tripwire (D9). Message: `[Feat] (Pipe): carry what has no call of its own in the residual value block and abort when it disagrees with the assembled state`.
|
||||
6. `b6`: `DirtySurface.def` + the scanner's `--check` / `--self-test`; the `FillPoints.def` tightening and the 8-row re-check. Message: `[Feat] (Pipe): map every frontend mutator onto the aggregate generation that publishes it, and make the dirty-surface scanner a gate`.
|
||||
7. `b7`: `TrackerTest.cpp` and `CsoCacheTest.cpp`.
|
||||
|
||||
**Tests to add**
|
||||
|
||||
- `TrackerTest.SteadyStateEmitsNothing` — two identical draws in a row move no `PipeStats` call counter.
|
||||
- `TrackerTest.BlendToggleReusesTwoCsos` — `enable / draw / disable / draw` × N mints exactly **2** CSOs and issues 2N binds. This is the Blaze3D shape `ARCHITECTURE.md:151` names as the reason push happens at validate and not in the setter.
|
||||
- `TrackerTest.ViewportDoesNotMintACso` — `glViewport` in a loop mints 0 CSOs and emits N `set_dynamic_state`s carrying only chunk D0. This is the regression `RenderState.h:165-170` records.
|
||||
- `TrackerTest.WrapAroundRePushesButNeverMisses` — drive `m_version` past 65535 and assert no missed emission.
|
||||
- `TrackerTest.AggregateGenerationCatchesABoundTextureMoving` — bind a texture, draw, `glTexSubImage` it, draw again; `NEW_SAMPLER_VIEWS` fires on the second draw. **This is the one direction the P1 verify comparator cannot see**, because it compares O-class fields by identity only (`PipeInputs.h:248-249`) and `ARCHITECTURE.md:502` names under-firing as the dangerous direction.
|
||||
- `CsoCacheTest.LruEvictsTheOldestAndEmitsDelete`; `CsoCacheTest.HashCollisionDoesNotAliasTwoStates` (force a collision through a test seam and assert the `memcmp` rejects it); `CsoCacheTest.ContentAddressingOffMintsEveryTime`.
|
||||
|
||||
**Constraints**: B touches **no** file under `MG_Backend/`. B does not edit `MG_Pipe/{MGPipeValueTypes.h, MGPipeTypes.h, MGPipeRenderStateSpans.*, PipeApply.*, Coverage.def, PipeFields.def}` or `scripts/gen_pipe.py` (A owns them), and does not edit `.github/workflows/test.yml` (E owns it) — so B's scanner change must keep `--summary` working until E lands.
|
||||
|
||||
**Verification (`~/w7/p2-tracker`)**
|
||||
|
||||
```sh
|
||||
python3 scripts/gen_pipe_dirty_surface.py --check && python3 scripts/gen_pipe_dirty_surface.py --self-test
|
||||
python3 scripts/gen_pipe.py --check
|
||||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
|
||||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 # the all-pull arm, same names, same result
|
||||
cmake --build build-verify --parallel 28 && ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4 --output-on-failure
|
||||
MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/p2-tracker --lib build-verify/libMobileGL.so --out ~/w7/retrace-out/p2-tracker -j 4
|
||||
grep -l 'Fatal{' ~/w7/retrace-out/p2-tracker/*/mobilegl.log # empty
|
||||
```
|
||||
|
||||
### C.2 Package C — `p2/espryt` (tree `~/w7/p2-espryt`, from `p2/contract`)
|
||||
|
||||
**Files**: `MobileGL/MG_Backend/DirectGLES/{DirectGLES.cpp, Managers.h, Managers.cpp}`, new `MobileGL/MG_Backend/DirectGLES/SlotTables.h`, and `MobileGL/MG_Test/SanityTest.cpp` (the `ScopedDirectGLESTextureBindings` fixture, `:145-197`).
|
||||
|
||||
**Ordered steps**
|
||||
|
||||
1. `e1`: `SlotTables.h` — per-kind dense arrays with a live bitset, whole-table save / reset / restore, and the `EnsureProcessTeardownSentinel()` arming moved onto first insertion (`Managers.h:295`, with `:52-57` explaining why a destructor hook is wrong). Both arms compile; nothing uses the new one yet.
|
||||
2. `e2`: the explicit-destroy hook — `delete_*` emitted when a frontend object's last `SharedPtr` drops, following `BufferBackendOps`' shape (`BufferObject.h:76-103`, fired at `BufferObject.cpp:39-41`). **This must land before the tables switch over**, because a slot table has no garbage collector; today the only death signal is the registry's `weak_ptr` expiring (`Managers.h:306-314` quantifies the dead gigabytes that costs).
|
||||
3. `e3`: switch the six kinds over behind `kMGPipeSubsystemEsprytSlots`, deleting `OwnerEquals` (`DirectGLES.cpp:63-66`), the three `TwinLookupMemo`s (`:83-132`, use sites `:1206, 1214, 2769, 2777, 2874, 2879`), `UnitSamplerLookupMemo`'s `WeakPtr` test (`:3157-3177`), the seven `CollectGarbageIfNeeded` calls (`:1223, 1533, 1898, 1899, 1900, 2728, 2729`), `SyncTextureObjectToBackend`'s by-value copy and second `Find` (`:1310-1345`), and the four `pDefaultFramebufferInfo->defaultFBO` compares (`:1939, 2874, 2898, 6420`). Keep every one of them compiled under `MOBILEGL_PIPE_LEGACY_MEMOS`.
|
||||
4. `e4`: `g_fbSlotCache` / `GetFramebufferBindingSlotFast` (`:134-157`) → a plain `MGB_CTX->GetFramebufferBindingSlot(target)` read at all five call sites (`:1613, 1907, 2745, 2860, 2935`), closing the P1 poison bypass.
|
||||
5. `e5`: the `SanityTest.cpp` fixture.
|
||||
|
||||
Messages: `[Refactor] (Espryt): key every backend twin on {slot, gen} instead of the frontend object's heap address - six registries become slot arrays and eleven identity memos go away`; `[Fix] (Espryt): tell the backend when a frontend object dies instead of discovering it in a garbage sweep`; `[Refactor] (Espryt): read the framebuffer binding slot through MGB_CTX at every call site instead of caching a raw pointer past the poison`.
|
||||
|
||||
**Must not break** — the D13 list. Each item has a named existing test: `SanityTest.cpp:2575-2596` (scratch-FBO scrub), `:2650-2665`, `:2757-2790` (context-generation guards on texture/framebuffer/renderbuffer twins), `:3020-3062` (sampled-set staleness), and `Scenarios/{SampledSetStalenessScenario, CrossFrameBufferScenario, VertexArrayEnableDisableScenario, VertexAttribBindingScenario, MultiDrawScenario, ResidentIndexScenario}.cpp`.
|
||||
|
||||
**Verification (`~/w7/p2-espryt`)**
|
||||
|
||||
```sh
|
||||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||||
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # empty (G13)
|
||||
grep -n 'OwnerEquals\|TwinLookupMemo\|g_fbSlotCache\|CollectGarbageIfNeeded' MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp
|
||||
# every remaining hit must be inside a MOBILEGL_PIPE_LEGACY_MEMOS arm
|
||||
cmake --build build-push --parallel 28
|
||||
ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R DirectGLES
|
||||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R DirectGLES # legacy arm
|
||||
python3 ~/w7/retrace_gate.py --tree ~/w7/p2-espryt --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p2-espryt -j 4 --backend DirectGLES --ssim 0.99
|
||||
```
|
||||
|
||||
### C.3 Package D — `p2/magma` (tree `~/w7/p2-magma`, from `p2/contract`)
|
||||
|
||||
**Files**: `MobileGL/MG_Backend/DirectVulkan/Renderer/{VulkanRenderer.h, VulkanRenderer.cpp, VertexInputStateFactory.h, VertexInputStateFactory.cpp}` and `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h` (deleting the three backend-memo triples — a different file from the four state containers B edits).
|
||||
|
||||
**Ordered steps**
|
||||
|
||||
1. `m1`: re-key `GetOrCreatePipeline`'s memo on the bound CSO handle (`VulkanRenderer.cpp:4997-5013`) and delete the cached-hash fields (`VulkanRenderer.h:855, 856, 860, 861, 862`; `InvalidatePipelineMemo()` at `:881-885` loses them), behind `kMGPipeSubsystemRenderState`. `renderPassHash` stays in the key — it is what separates draws that differ only in `colorAttachmentCount` / `sampleCount`. Message: `[Refactor] (Magma): key the pipeline memo on the render-state CSO handle and stop recomputing a hash the client already computed`.
|
||||
2. `m2`: `ApplyDynamicDrawStateTail` (`:5902-6004`) re-sourced from the pushed dynamic version, plus the `DynamicTailKey`-coverage unit test (D12.3). Message: `[Refactor] (Magma): drive the dynamic tail from the pushed dynamic version so a pipeline-only change stops invalidating it`.
|
||||
3. `m3`: subsystem 4 — `VertexInputStateFactory::ComputeHash`'s `bufferKey` (`VertexInputStateFactory.cpp:48`) and a slot-indexed `VaoDrawMemo` (`VulkanRenderer.h:1244-1272`, `VulkanRenderer.cpp:3540-3579`), behind `kMGPipeSubsystemMagmaVertexInput`. Message: `[Refactor] (Magma): key the vertex-input cache and the VAO draw memo on {slot, gen} instead of a lifetime id and a heap address`.
|
||||
4. `m4`: delete `SetBackendStateMemo` / `SetBackendAuxMemo` / `SetBackendHashMemo` and their storage from the frontend VAO (`VertexArrayObject.h:106-150`, `:190-197`) and the eviction-epoch dance with them (`VertexInputStateFactory.cpp:78`, `:318`, `VertexInputStateFactory.h:141`). Message: `[Refactor] (State, Magma): take the backend's raw pointers out of the frontend VAO - the state memo is deleted, the hash and aux memos become server-side per-slot fields`.
|
||||
|
||||
**Out of scope, do not touch**: `ProgramObject::{Get,Set}BackendHashMemo` (`ProgramObject.h:798-826`, sole user `ProgramFactory.cpp:3446-3448`) and the wider `SetupDrawSnapshot` re-key (`VulkanRenderer.h:958-979`) beyond collapsing its `vao` / `vaoLifetimeId` pair into the handle.
|
||||
|
||||
**Verification (`~/w7/p2-magma`)**
|
||||
|
||||
```sh
|
||||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||||
grep -rn 'BackendStateMemo\|BackendAuxMemo\|m_backendHashMemo' MobileGL/MG_State MobileGL/MG_Backend # only ProgramObject's, which is out of scope
|
||||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R DirectVulkan
|
||||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R DirectVulkan
|
||||
python3 ~/w7/retrace_gate.py --tree ~/w7/p2-magma --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p2-magma -j 4 --backend DirectVulkan --ssim 0.99
|
||||
```
|
||||
|
||||
### C.4 Package E — `p2/gates` (tree `~/w7/p2-gates`, from `p2/contract`)
|
||||
|
||||
Cross-cutting tooling. E branches from the contract and integrates **last**, but writes `HandleRecycleScenario` **first**, so its `AbaControl` arm is proven red before C and D exist — that is the "重键前红" evidence, recorded with the run log.
|
||||
|
||||
| action | file | what |
|
||||
|---|---|---|
|
||||
| CREATE | `MobileGL/MG_IntegrationTest/Scenarios/HandleRecycleScenario.cpp` | D18 |
|
||||
| CREATE | `MobileGL/MG_IntegrationTest/Scenarios/CsoContentAddressingScenario.cpp` | G12 — two entries, `kMGPipeBehaviourNoCsoContentAddressing` set vs clear, asserting `csom` / `csob` move in the expected direction and the pixels do not |
|
||||
| MODIFY | `MobileGL/MG_IntegrationTest/CMakeLists.txt` | register both scenarios (source list from `:55`) and their environments, following the negative-control precedent at `:695-725` |
|
||||
| MODIFY | `android-plugin/app/src/trace/cpp/trace_benchmark.{hpp,cpp}` | D.4.1 — a second per-frame series taken with `clock_gettime(CLOCK_THREAD_CPUTIME_ID, …)` beside the wall delta at `trace_benchmark.cpp:74-76`; `Report` gains `std::vector<double> frameCpuMs` next to `frameMs` (`trace_benchmark.hpp:32-39`) |
|
||||
| MODIFY | `android-plugin/app/src/trace/cpp/trace_replay_core.{hpp,cpp}` | `SummarizeBenchmark` (`:832-865`) reused verbatim for the CPU series; `WriteBenchmarkJson` (`:867-899`) gains `meanFrameCpuMs`, `medianFrameCpuMs`, `p95FrameCpuMs` and `frameCpuTimesMs[]` beside `frameTimesMs[]` (`:889-896`) |
|
||||
| MODIFY | `tools/trace_replay/run_android_retrace_local.py` | `format_benchmark` (`:228-237`) prints the CPU numbers |
|
||||
| CREATE | `tools/device_bench/devices/{xiaomi-adreno830.env, oppo-mali.env}` | the two missing device profiles (only `odinlite.env` exists) |
|
||||
| MODIFY | `MobileGL/MG_Benchmark/Driver/CMakeLists.txt` | a second ctest entry `DriverBenchStateToggle` running `mc_state_toggle` — `:14` currently runs only `draw_tiny`, and `mc_state_toggle` is already in `kBenchCases` (`DriverBenchCases.inc:558-570`, `:627`), so exposing it costs ~1.2 s in an existing 3 min job |
|
||||
| CREATE | `scripts/g7_negative_control.sh` | D19 |
|
||||
| MODIFY | `.github/workflows/test.yml` | `pipe-gates` (`:1477`): `gen_pipe_dirty_surface.py --check && --self-test` replacing the informational `--summary` (`:1524-1528`); a `ctest -L unit` step on the verify runtime inside `integration-verify` (`:473`) so G6 / G10's push-only unit tests actually run in CI; the two new scenario entries |
|
||||
|
||||
Messages: `[Test] (Pipe): reproduce the handle ABA through public GL and prove the pre-rekey guards are what stops it`; `[Feat] (Trace): record per-frame thread CPU time beside wall time so a paired A/B can be read as CPU cost`; `[CI] (Pipe): make the dirty-surface report a gate and run the push-only unit tests on the verify runtime`.
|
||||
|
||||
**Verification (`~/w7/p2-gates`)**
|
||||
|
||||
```sh
|
||||
cmake --build build-verify --parallel 28
|
||||
ctest --test-dir build-verify -R HandleRecycle --no-tests=error --output-on-failure
|
||||
# on the contract tree, before C/D land: .Legacy and .AbaControl pass, .Handles SKIPs with
|
||||
# "subsystem not implemented on this tree" - a visible skip, never a vanishing test
|
||||
cmake --build build-bench --parallel 28 && ctest --test-dir build-bench -L benchmark --no-tests=error
|
||||
cmake --build build-retrace --parallel 28 && ./build-retrace/trace_replay_cli --benchmark --benchmark-no-finish ...
|
||||
# the desktop CLI shares the same core (tools/trace_replay/CMakeLists.txt:229,254-255), so the
|
||||
# CPU-series change is pre-flighted on WSL before any device time is spent
|
||||
```
|
||||
|
||||
### C.5 File-ownership table
|
||||
|
||||
No two packages edit the same file. The contract is one commit that all four other branches descend from, so the integrator's rebase never sees an edit on both sides of a file.
|
||||
|
||||
| file / glob | A contract+spans | B tracker | C espryt | D magma | E gates |
|
||||
|---|---|---|---|---|---|
|
||||
| `MobileGL/MG_Pipe/{MGPipeValueTypes.h, MGPipeTypes.h, MGPipe.h, MGPipeRenderStateSpans.*, PipeApply.*, Coverage.def, PipeFields.def, generated/*.inc}` | **owner** | – | – | – | – |
|
||||
| `MobileGL/MG_Pipe/{FillPoints.def, PipeMutation.h, DirtySurface.def}` | – | **owner** | – | – | – |
|
||||
| `scripts/gen_pipe.py` | **owner** | – | – | – | – |
|
||||
| `scripts/gen_pipe_dirty_surface.py` | – | **owner** | – | – | – |
|
||||
| `scripts/g7_negative_control.sh` | – | – | – | – | **owner** |
|
||||
| `MobileGL/MG_Impl/Pipe/SlotAllocator.*` | **owner** (contract) | – | – | – | – |
|
||||
| `MobileGL/MG_Impl/Pipe/{Tracker.*, CsoCache.*, SetHashSuppressor.h, PipeFill.*}` | – | **owner** | – | – | – |
|
||||
| `MobileGL/MG_State/GLState/RenderState/RenderState.{h,cpp}` | **owner** | – | – | – | – |
|
||||
| `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayState.*, VertexArrayState/VertexArrayObject.cpp, FramebufferState/*, TextureState/*, BufferState/*, SamplerState/*}` | – | **owner** | – | – | – |
|
||||
| `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h` | – | – | – | **owner** | – |
|
||||
| `MobileGL/MG_Backend/DirectGLES/**` | – | – | **owner** | – | – |
|
||||
| `MobileGL/MG_Backend/DirectVulkan/**` | – | – | – | **owner** | – |
|
||||
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}`, `MobileGL/MG_Test/Util/PipeStatsTest.cpp` | **owner** (contract) | – | – | – | – |
|
||||
| root `CMakeLists.txt`, `MobileGL/Config.h`, `MobileGL/ConfigLoader.cpp` | **owner** (contract) | – | – | – | – |
|
||||
| `MobileGL/MG_Test/Pipe/CMakeLists.txt` and the four stubs' creation | **owner** (contract) | – | – | – | – |
|
||||
| `MobileGL/MG_Test/Pipe/{RenderStateSpansTest, SlotAllocatorTest}.cpp` contents | **owner** | – | – | – | – |
|
||||
| `MobileGL/MG_Test/Pipe/{TrackerTest, CsoCacheTest}.cpp` contents | – | **owner** | – | – | – |
|
||||
| `MobileGL/MG_Test/SanityTest.cpp` | – | – | **owner** | – | – |
|
||||
| `MobileGL/MG_IntegrationTest/**`, `.github/workflows/test.yml`, `tools/device_bench/**`, `tools/trace_replay/run_android_retrace_local.py`, `android-plugin/app/src/trace/cpp/**`, `MobileGL/MG_Benchmark/**` | – | – | – | – | **owner** |
|
||||
| `docs/Disaggregated/*.md` | – | – | – | – | – (integrator only) |
|
||||
| everything else | nobody | nobody | nobody | nobody | nobody |
|
||||
|
||||
The one file two packages both *touch conceptually* is `VertexArrayObject`: B edits `VertexArrayState.h` / `VertexArrayObject.cpp` (the aggregate generation), D edits `VertexArrayObject.h` (deleting the memo triples). They are different files, so the rebase is clean; the integrator still lands B before D so a compile error, if the split is wrong, surfaces at D's rebase and not at C's.
|
||||
@@ -0,0 +1,251 @@
|
||||
|
||||
---
|
||||
|
||||
## D. Integration order, and what the integrator runs
|
||||
|
||||
### D.0 Preconditions
|
||||
|
||||
- The baseline captures of §A (`~/w7/p2-before-libMobileGL.so`, `~/w7/p2-before-ctest-names.txt`, `~/w7/p2-before-syncrenderstate.sha`, `~/w7/p2-before-dirty-surface.txt`), taken in `~/w7/pipe` at `48268068` **before any package lands**.
|
||||
- `~/w7/pipe` clean at `48268068`; fixture binaries hidden the way `wsl_p2_tree.sh` does it (`git update-index --assume-unchanged` on `tools/trace_replay/fixtures`).
|
||||
- `~/w7/retrace_gate.py` copied from `scratchpad/wf2/retrace_gate.py`.
|
||||
- Both devices reachable and **not** locked by the GL4.6 Wave-7 campaign (`ls .../8ab6b3cb-.../scratchpad/w7/locks/`).
|
||||
|
||||
### D.1 Order: **contract → tracker → magma → espryt → gates**
|
||||
|
||||
Reason for that order, and it is not P1's by default:
|
||||
|
||||
- `contract` first because everything else compiles against it.
|
||||
- `tracker` second because it is the only package that changes semantics; after it, both backends are still reading the same bytes they read before, through unmodified code. If `tracker` is wrong, the verify lane says so before any backend has been touched.
|
||||
- `magma` third rather than last, because D's `m1`/`m2` (the render-state re-key) is the deliverable the day-43 number depends on and it is the one most likely to need iteration; `m3`/`m4` (subsystem 4) then land against a Magma that is already CSO-keyed.
|
||||
- `espryt` fourth: Espryt needs **zero** render-state change by construction (G5), so C is purely Track H and is independent of everything except the contract.
|
||||
- `gates` last, so its lanes assert against the finished tree — except `HandleRecycleScenario`, whose `AbaControl` red is recorded on the contract tree at D.2.
|
||||
|
||||
Copy `scratchpad/wf2/wsl_integrate_p05.sh` → `wsl_integrate_p2.sh` (`p05`→`p2`). Per slug: rebase `p2/<slug>` onto `feat/disaggregated` in its own worktree, `git merge --ff-only` in `~/w7/pipe`, then:
|
||||
|
||||
```sh
|
||||
cmake --build build-linux --parallel 28 && ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
|
||||
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test
|
||||
python3 scripts/gen_pipe_dirty_surface.py --check # from `tracker` onward
|
||||
python3 scripts/check_include_closure.py
|
||||
python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so \
|
||||
--threshold 0 --markdown ~/w7/p2-symbol-<slug>.md
|
||||
# 0 added / 0 removed / 0 renamed after every merge; resized ⊆ the three RenderState symbols of D15
|
||||
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # empty
|
||||
awk '/namespace RenderStateImpl \{/,/\} \/\/ namespace RenderStateImpl/' MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp | sha256sum
|
||||
# equal to ~/w7/p2-before-syncrenderstate.sha after EVERY merge (G5)
|
||||
ctest --test-dir build-linux -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort | comm -23 ~/w7/p2-before-ctest-names.txt - # empty
|
||||
```
|
||||
|
||||
### D.2 On the contract tree, before `tracker`: record the "red before" evidence
|
||||
|
||||
```sh
|
||||
cd ~/w7/p2-gates && cmake --build build-verify --parallel 28
|
||||
ctest --test-dir build-verify -R HandleRecycle --no-tests=error --output-on-failure | tee ~/w7/p2-handlerecycle-before.log
|
||||
# .AbaControl PASSES (it asserts the corrupted pixels), .Legacy PASSES, .Handles SKIPs
|
||||
```
|
||||
That log is the artefact `ROADMAP.md:18`'s "重键前红" asks for. Keep it; it goes into `MEASUREMENTS.md`.
|
||||
|
||||
### D.3 After every package has landed: the five-part gate on `~/w7/pipe`
|
||||
|
||||
**Part 1 — interface purity.**
|
||||
```sh
|
||||
python3 scripts/check_include_closure.py # gate A
|
||||
nm --undefined-only build-linux/libMobileGL.so | grep -E 'MG_State::GLState::|glslang' ; echo rc=$? # gate B (n/a in monolith; recorded)
|
||||
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # gate C: empty
|
||||
ctest --test-dir build-verify -R HandleRecycle --no-tests=error --output-on-failure # the {slot,gen} memo-key assertion (G8)
|
||||
```
|
||||
|
||||
**Part 2 — the semantic shadow comparison (the decisive one).**
|
||||
```sh
|
||||
cmake --build build-verify --parallel 28
|
||||
ctest --test-dir build-verify -L unit --no-tests=error --output-on-failure
|
||||
ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4 --output-on-failure
|
||||
MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-verify/libMobileGL.so \
|
||||
--out ~/w7/retrace-out/p2-verify -j 4
|
||||
grep -L 'MGPipe verify:' ~/w7/retrace-out/p2-verify/*/mobilegl.log # empty: every case armed
|
||||
grep -l 'Fatal{' ~/w7/retrace-out/p2-verify/*/mobilegl.log # empty
|
||||
```
|
||||
A `Fatal{UnmigratedPipeInput, "F@V"}` is a missing `FillPoints.def` row — add the row (never a sticky flag, `FillPoints.def:24-27`), regenerate, rerun. A `Fatal{PipeVerifyDiffer, …, where=read}` is a real push/pull divergence — most likely a D5 derivation transcribed wrongly; it names the field, and it is fixed, never silenced. A `Fatal{PipeResidualDiverged}` means a capability lost its carrier (D9).
|
||||
|
||||
**Part 3 — behavioural A/B.**
|
||||
```sh
|
||||
# {pull, push} name-for-name on both backends (G2)
|
||||
for d in build-linux build-push; do ctest --test-dir $d -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort > ~/w7/p2-names-$d.txt; done
|
||||
diff ~/w7/p2-names-build-linux.txt ~/w7/p2-names-build-push.txt # empty
|
||||
ctest --test-dir build-linux -L integration-gpu --no-tests=error -j 4
|
||||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
|
||||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
|
||||
# 40 traces (79 desktop cases) under push, both backends, SSIM >= 0.99 (G3)
|
||||
python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-push/libMobileGL.so --out ~/w7/retrace-out/p2-push -j 4 --ssim 0.99
|
||||
# the render-state-sensitive integration scenarios, called out by name because they are the ones a
|
||||
# chunk-table mistake shows up in first:
|
||||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 \
|
||||
-R 'ClipDistance|SampleMaskScope|SampleVariables|DualSourceBlend|ViewportArray|PrimitiveRestart'
|
||||
# the negative controls, always-on entries (G7, G8, G12)
|
||||
bash scripts/g7_negative_control.sh build-push
|
||||
ctest --test-dir build-push -R CsoContentAddressing --no-tests=error --output-on-failure
|
||||
ctest --test-dir build-verify -R 'PoisonOmitted\.|VerifyCorrupted\.|HandleRecycle' --no-tests=error
|
||||
```
|
||||
**CTS**: P2 is **not** one of the five architecture boundaries that need the full `gl44to46` caselist (`ROADMAP.md:34`) and no named block is assigned to it. The full 56,271-case run happens once, on both devices, when P2 merges to `dev` — scheduled off the critical path.
|
||||
|
||||
**Part 4 — performance non-regression.** D.4 below.
|
||||
|
||||
**Part 5 — coverage, poison, handle discipline.**
|
||||
```sh
|
||||
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test # G6 regenerates, 0 UNMAPPED
|
||||
python3 scripts/gen_pipe_dirty_surface.py --check && python3 scripts/gen_pipe_dirty_surface.py --self-test # G9
|
||||
ctest --test-dir build-push -R 'RenderStateSpans\.|Residual' --no-tests=error --output-on-failure # G6, G10
|
||||
```
|
||||
|
||||
**CI.** `gh workflow run test.yml --ref feat/disaggregated`, then once green `gh workflow run test.yml --ref feat/disaggregated -f baseline_sha=48268068` for `monolith-symbol-report`. Record both run URLs. Expected green: `pipe-gates`, `include-graph-check`, `test`, `integration`, `benchmark`, `build-linux-verify`, `integration-verify`, `retrace`, `retrace-verify`, `monolith-symbol-report`. **Note for the schedule**: the three verify lanes have never yet produced a green CI run — they were added at `0fe7bf82` / `97b997d5` and the only run whose head contained them was still in progress when the scouts were written, so their CI wall time is unknown. The only cost datum is local (`MEASUREMENTS.md:142`): 818 `integration-verify` entries at `-j 4` are about the same order as `integration-gpu`, and 79 retrace cases at `-j 4` take ~20 minutes on a 28-core WSL box. Budget accordingly and do not put the device runs behind them.
|
||||
|
||||
**A P2 decision the CI file forces**: `test.yml:520-526` records that `integration`'s second, `MOBILEGL_ESPRYT_DISABLE_INVALIDATE_FLUSH=1` filtered pass (186 entries) is not run under the comparator and says "P2 can take it once the comparator's cost is known". **Decision: P2 does not take it.** The comparator's cost is now known to be 5–10× and the 186 entries are a buffer/readback filter that P2 changes nothing in; revisit at P3b, and the integrator records that decision in `MEASUREMENTS.md` rather than leaving the note dangling.
|
||||
|
||||
### D.4 The measurement runs P2 owes the day-43 GO/NO-GO
|
||||
|
||||
Four numbers, in the order they must be produced. Items 2–7 of `ROADMAP.md:46-52` are all here; item 1 is P1's and is already recorded at `MEASUREMENTS.md:126-142`.
|
||||
|
||||
#### D.4.1 Prerequisite: a per-thread CPU series in the retrace harness (package E)
|
||||
|
||||
**There is no per-thread CPU-time instrumentation anywhere in the tree** — greps for `CLOCK_THREAD_CPUTIME_ID`, `CLOCK_PROCESS_CPUTIME_ID`, `getrusage`, `RUSAGE_THREAD` and `/proc/self/task` across `MobileGL/`, `tools/`, `android-plugin/` and `scripts/` return nothing. The metric the whole GO/NO-GO hangs on (`ROADMAP.md:56`) therefore has no first-party collector today, and the cheapest way to get one is inside the retrace benchmark itself: retrace runs `--singlethread` (`trace_replay_core.cpp:459`) and `trace_benchmark.hpp:12-13` states that `Begin` / `OnFrameBoundary` / `End` are only ever reached from that one thread, so **that thread's CPU time is the client-side CPU cost** — no sampling, no root, no debuggable build, no profiler.
|
||||
|
||||
E's four edits (D.4's cost is one afternoon, and it is pre-flighted on the desktop CLI, which shares the same core):
|
||||
`trace_benchmark.cpp:74-76` takes `clock_gettime(CLOCK_THREAD_CPUTIME_ID, …)` beside `Clock::now()`; `trace_benchmark.hpp:32-39`'s `Report` gains `frameCpuMs`; `SummarizeBenchmark` (`trace_replay_core.cpp:832-865`) is reused verbatim for the CPU series; `WriteBenchmarkJson` (`:867-899`) emits `meanFrameCpuMs` / `medianFrameCpuMs` / `p95FrameCpuMs` and the full `frameCpuTimesMs[]` array beside `frameTimesMs[]`. **p99 needs no device change even today** — the full per-frame array is dumped, so any percentile is computed host-side from `benchmark.json`; only the headline fields stop at p95.
|
||||
|
||||
**Do not** put a timer inside `MGPipeValidateForVerb`. `ROADMAP.md:7` forbids committing hot-path instrumentation, and D17 explains where the ns number comes from instead.
|
||||
|
||||
#### D.4.2 The paired two-device A/B (GO/NO-GO items 4 and 3)
|
||||
|
||||
Protocol, per device, one lock hold per arm, `scratchpad/wf2/stats_baseline.sh:16-29` as the template:
|
||||
|
||||
- **reboot-clean**: `adb -s $SER reboot`, wait for boot completion, wake and unlock (`input keyevent KEYCODE_WAKEUP; input keyevent 82`), let the device settle to the thermal floor before the first arm, and run the two arms **back to back in the same session** so they share a thermal window (`tools/device_bench/README.md:45-58`).
|
||||
- **CPU/GPU pinned** per the project protocol (big 1.96 GHz / little 1.55 GHz, GPU maxed, 40 °C gate), the pin re-checked at the end of each window and the window discarded if it drifted off-pin.
|
||||
- **serially from one tree**: `run_android_retrace_local.py` shares one `.trace-work/android-retrace-result` root per tree and `rmtree`s it per invocation (`:14`, `:354-356`), so the two devices **must not** be driven concurrently from one worktree (`MEASUREMENTS.md:93`).
|
||||
- **device lock** held ≤ 25 min per acquisition, `owner` file written, `rm -rf` on the way out; a lock held > 60 min is not to be broken — report "blocked by device lock".
|
||||
- **ColorOS traps** on `3B159D009VZ00000`: the first install of a not-yet-installed package blocks on `com.oplus.appdetail InstallGuideActivity` until "继续安装" is tapped (`input tap 353 2349` on the 1272×2772 panel); a foreign-signed APK must be uninstalled first.
|
||||
- `MSYS_NO_PATHCONV=1` on every invocation, because a `/data/...` inside an `--env` value is path-converted otherwise.
|
||||
|
||||
Arms: **{pull APK, push APK} × {`--benchmark-no-finish`, finish} × 4 cases × 2 backends**, per device.
|
||||
|
||||
```sh
|
||||
LOCKS=.../8ab6b3cb-.../scratchpad/w7/locks
|
||||
for SER in 35d0befa 3B159D009VZ00000; do
|
||||
for c in minecraft-1.21.4-in-world minecraft-1.21.4-fabric-iris-bsl-in-world improved-transparency-minecraft-26.3 minecraft-1.21.4-startup; do
|
||||
for b in DirectGLES DirectVulkan; do
|
||||
for arm in pull push; do
|
||||
until mkdir "$LOCKS/$SER" 2>/dev/null; do sleep 20; done; echo "p2-ab $(date)" > "$LOCKS/$SER/owner"
|
||||
ANDROID_SERIAL=$SER MSYS_NO_PATHCONV=1 python3 tools/trace_replay/run_android_retrace_local.py \
|
||||
--case "$c" --backend "$b" --benchmark --benchmark-no-finish --benchmark-repeats 3 --benchmark-tail-frames 200 \
|
||||
--env MOBILEGL_PIPE_STATS=1 --env MOBILEGL_PIPE_STATS_PERIOD=120
|
||||
# the same invocation yields BOTH artefacts: benchmark.json (frameCpuTimesMs[]) and
|
||||
# mobilegl.log (the 'MGPipe stats:' windows) - trace-replay-ci.sh:489,491 copies both
|
||||
rm -rf "$LOCKS/$SER"
|
||||
done; done; done; done
|
||||
```
|
||||
|
||||
Then, host-side, reduce `frameCpuTimesMs[]` over the trailing 200 frames to **p50 and p99** per arm and publish the delta `push − pull` per (device, case, backend). `--benchmark-no-finish` is the **primary** arm because P2's question is CPU cost (`trace_benchmark.hpp:16-24`); the finish-ON arm is the sanity check that GPU time did not move.
|
||||
|
||||
Also read out of the same runs, because they survive the accessor-tally relocation problem (D17): the six memo gate hit/miss pairs (`ers etl eub mfp mpm mdt`) from the **last complete window** of `grep 'MGPipe stats:' mobilegl.log`, the `resid=` byte class (G10), and the two new `csom` / `csob` call classes.
|
||||
|
||||
**Excluded**: `minecraft-1.21.1-neoforge-create-indirect-in-world` — it fails on both devices on the `dev@81b17c0b` baseline APK itself (Espryt black frame after ~4.5 min on Adreno 830, Magma `VK_ERROR_DEVICE_LOST` during a texture-upload submit; Mali SSIM 0.85 / 0.45), so it is not this branch's regression (`MEASUREMENTS.md:96`, open question 17). It stays in the 40-trace desktop SSIM corpus and out of the device A/B.
|
||||
|
||||
**Trap**: `MOBILEGL_PIPE_STATS_FILE` never produces a file on device — the JSON is written from `PipeStats::Shutdown()` (`PipeStats.cpp:271-278`) which runs from `MobileGL::Destroy` (`Init.cpp:50`), and the trace app never reaches that teardown. Only the periodic `mobilegl.log` lines exist, and a run shorter than one period yields nothing at all; hence `MOBILEGL_PIPE_STATS_PERIOD=120` (or lower for a short fixture).
|
||||
|
||||
#### D.4.3 The tracker's absolute ns per draw (GO/NO-GO item 5)
|
||||
|
||||
From `DriverBench`'s `ns_per_op` (`MobileGL/MG_Benchmark/Driver/DriverBench.c:31-32`, printed at `:288-289`), on the desktop, against the same library built three ways. `DriverBench` is a headless EGL client that is **not** linked against MobileGL: it `dlopen`s exactly one provider from `$DRIVERBENCH_EGL_LIB` (`DriverBench.c:9-18`), so the same binary measures the native driver and both MobileGL backends. It loops 30 warmup + 120 timed frames, each closed with a real fence wait rather than `glFinish` (MobileGL implements `glFinish` as a no-op, `DriverBench.c:245-266`).
|
||||
|
||||
```sh
|
||||
cd ~/w7/pipe && cmake --build build-bench --parallel 28
|
||||
for lib in build-linux build-push; do # pull vs push, same tree, same flags
|
||||
for be in espryt magma; do
|
||||
DRIVERBENCH_EGL_LIB=$PWD/$lib/libMobileGL.so \
|
||||
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh $be $PWD/$lib/libMobileGL.so
|
||||
done
|
||||
done
|
||||
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh native # the control
|
||||
```
|
||||
|
||||
Two deltas, both published, on `mc_vanilla_draw` (5495 draws/frame — the per-draw denominator):
|
||||
|
||||
- **T1, the gate number** = `ns_per_op(push, default bitmask) − ns_per_op(pull)`. This is the whole boundary cost per draw.
|
||||
- **T2** = `ns_per_op(push, MOBILEGL_PIPE_PUSH=0) − ns_per_op(pull)`. This is P1's residual fill alone, so **T1 − T2** isolates exactly what P2 added and what it removed.
|
||||
|
||||
**The ceiling, and it is pinned in `MEASUREMENTS.md` before the run** (`ARCHITECTURE.md:504` demands an absolute threshold precisely because a relative one would pass trivially). Derivation: the pull baseline is **6.5–9.3 accessor calls plus memo probes per draw** (`MEASUREMENTS.md:64`, table `:50-58`: MC 1.21.4 in-world Espryt 9.28 / Magma 8.56 at 91.6 draws/frame; improved-transparency 26.3 Espryt 8.44 / Magma 6.53 at 1320 draws/frame). Priced at a non-inlined accessor call plus a load — 6–10 cycles, ~4 ns at 1.96 GHz — plus six memo probes at ~2 ns, that is **~44 ns/draw of work push has to be no worse than**. So:
|
||||
|
||||
> **T1 ≤ 45 ns/draw on Adreno 830 (`35d0befa`) and ≤ 60 ns/draw on the Mali device (`3B159D009VZ00000`)**, pinned before the A/B is run. If the pre-run calibration (one DriverBench run of the pull library, reporting `ns_per_op` for `mc_vanilla_draw`, minus the `native` control) says the per-accessor price on these devices is different, the *measured* price replaces the estimate and the ceiling is re-derived by the same arithmetic — but it is pinned before the push arm is measured, not after.
|
||||
|
||||
`DriverBench` is Linux-desktop only (`Driver/CMakeLists.txt:7-9`) and the whole benchmark tree is force-disabled on Android (`CMakeLists.txt:33-35`). That is acceptable: P2's ns question is a client-side CPU question and the desktop run answers it, while the two-device requirement (`ROADMAP.md:49`) applies to the per-thread CPU deltas, which come from D.4.2. **Do not** enable the google-benchmark tree on Android to change this; if an on-device blend-toggle is ever wanted the cheap route is a new Android-only target modelled on `DriverBench.c`, which already `dlopen`s EGL and falls back to surfaceless (`DriverBench.c:294-300, 417`).
|
||||
|
||||
#### D.4.4 The Blaze3D blend-toggle microbenchmark (GO/NO-GO item 6)
|
||||
|
||||
**The case already exists**: `case_mc_state_toggle` (`DriverBenchCases.inc:558-570`) is `glEnable(GL_BLEND); glBlendFuncSeparate(...); glDrawElements(...); glDisable(GL_BLEND); glDrawElements(...)` × 46, registered as `{"mc_state_toggle", case_mc_state_toggle, 46, 0, 46}` (`:627`) at exactly the vanilla-frame rate (46 toggle pairs and 28 `glBlendFuncSeparate` per frame). Note the case is `enable/draw/disable/draw`, which is what `ROADMAP.md:51` writes verbatim.
|
||||
|
||||
```sh
|
||||
for be in native espryt magma; do
|
||||
bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh $be ... | grep '^mc_state_toggle'
|
||||
done
|
||||
```
|
||||
Published as a table of `ns_per_op` for `{native, espryt-pull, espryt-push, magma-pull, magma-push}`, alongside `mc_vanilla_draw` and `mc_pass_switch` so the toggle number is read against a non-toggling baseline. This is the workload the whole "push at validate, not in the setter" decision (`ARCHITECTURE.md:151`) was made for, and it is where a per-setter design would have shown up as a loss.
|
||||
|
||||
#### D.4.5 The CSO negative control (GO/NO-GO item 7)
|
||||
|
||||
The knob is `kMGPipeBehaviourNoCsoContentAddressing` (bit 63 of the runtime `MOBILEGL_PIPE_PUSH` bitmask, D14). **It disables the map probe and the handle reuse, not the CSO records** — otherwise it measures a different thing: with it set, every pipeline-version change mints a fresh CSO, binds it and evicts, which is precisely "whole-block content addressing" and reproduces the regression `RenderState.h:165-170` records.
|
||||
|
||||
```sh
|
||||
# desktop: the microbenchmark and the per-draw case, with and without
|
||||
MOBILEGL_PIPE_PUSH=0x800000000000007f bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh espryt ...
|
||||
MOBILEGL_PIPE_PUSH=0x7f bash MobileGL/MG_Benchmark/Driver/run_driver_bench.sh espryt ...
|
||||
# device: one extra arm of D.4.2 on minecraft-1.21.4-in-world only, both backends, one device
|
||||
ANDROID_SERIAL=35d0befa MSYS_NO_PATHCONV=1 python3 tools/trace_replay/run_android_retrace_local.py \
|
||||
--case minecraft-1.21.4-in-world --backend DirectGLES --benchmark --benchmark-no-finish \
|
||||
--env 'MOBILEGL_PIPE_PUSH=0x800000000000007f' --env MOBILEGL_PIPE_STATS=1 --env MOBILEGL_PIPE_STATS_PERIOD=120
|
||||
```
|
||||
The point of the control is to separate **"push is slower"** from **"the CSO design is slower"**: if T1 is over the ceiling *and* the control is not, the cost is in the tracker; if both are over, the cost is in the wire shape. And because a dead switch would pass silently, `CsoContentAddressingScenario` (E) is an always-on ctest pair asserting that `csom` / `csob` move in opposite directions with and without the bit while the pixels do not move at all.
|
||||
|
||||
#### D.4.6 The Track H unit costs (GO/NO-GO item 3)
|
||||
|
||||
`ROADMAP.md:56`'s criterion is "Track H 单位成本不超出估计的 50%", against the deleted `PLAN.md`'s estimates of **Espryt 0b = 5–7 days** and **Magma subsystem 4 = 2–3 days**. So the measurement is calendar, not nanoseconds: record the actual elapsed days for packages C and D, the diff sizes, and the count of memos actually retired against `ARCHITECTURE.md:363`'s census (11 direct deletions, 2 moved to client debounce, 7 re-keyed, 1 unchanged). P2 pays into that census: **11 of the 11 direct deletions and 2 of the 7 re-keys**. The remaining slices are P3a/P3b/P4a/P4b/P7 and their unit cost is extrapolated from these two.
|
||||
|
||||
### D.5 Docs, and the merge to `dev` (integrator, one commit)
|
||||
|
||||
`scripts/check_doc_citations.py docs/Disaggregated/*.md` must stay clean — every `file:line` a doc edit adds has to be true.
|
||||
|
||||
- `README.md:3` — status → P2 landed with the hash.
|
||||
- `ROADMAP.md:18` — ✅, with the real numbers: 7 pipeline chunks / 396 B and 8 dynamic chunks / 772 B; CsoCache 64; the residual ratchet 1248 → 8; 11 memos deleted and 2 re-keyed.
|
||||
- `ROADMAP.md:74` (open question 1) — answered with T1/T2 and the two-device p50/p99 table; `:77` (Q4) — answered with the chunk granularity and the note that 64 is retuned at P13 with the counters live; `:78` (Q5) — answered, and **corrected to three capabilities** (the preamble's correction 1).
|
||||
- `ARCHITECTURE.md:153` — eight validate entries → nine, named (D1).
|
||||
- `ARCHITECTURE.md:172` and `:568` — "P1 起成为门" → P2, matching what `test.yml` actually runs.
|
||||
- `ARCHITECTURE.md:186` — the split's one place is now real; `:189` — the "~25-30 字" estimate → 396 B / 49.5 words; `:190` — the `FramebufferSrgb`/`DepthClamp` open question is closed, and `TextureCubeMapSeamless` is added.
|
||||
- `ARCHITECTURE.md:504` — `tools/bench.sh` → `tools/device_bench/bench.sh`.
|
||||
- `ARCHITECTURE.md:580`, `:588` — `MOBILEGL_PIPE_LEGACY_MEMOS` gains its CMake row; the `MOBILEGL_PIPE_PUSH` bitmask row gains the bit list and the new default.
|
||||
- `MEASUREMENTS.md` — a new §8 with: the D.4.2 two-device p50/p99 table, T1/T2 and the pinned ceiling with its derivation, the blend-toggle table, the CSO negative control, the D.2 "red before" log, the six gate hit/miss pairs before and after, the `resid=` and `csom`/`csob` numbers, the per-dirty-bit fire rates, the payload histogram, the verdict on the 8 over-approximated fill rows, and the `integration-verify` filtered-pass decision of D.3.
|
||||
|
||||
Then `[Merge]` to `dev` per the milestone flow, and schedule the full `gl44to46` caselist on both devices off the critical path (`ROADMAP.md:34`).
|
||||
|
||||
---
|
||||
|
||||
## E. Risks and mitigations
|
||||
|
||||
| risk | mitigation |
|
||||
|---|---|
|
||||
| **The `[581,584)` padding hole is not where this brief computes it**, so the three new capability bools grow `RenderStateParameters` past 1168 — which breaks the `static_assert` at `MGPipeValueTypes.h:541`, `MGL_RESIDUAL_BLOCK_SIZE`, and every offset in D6's table. | It is a **compile error on the first build of `c0`**, not a silent drift, and it is the very first thing the contract package builds. If it fires, find the real hole with a temporary `static_assert(offsetof(...))` — do **not** grow the struct: the residual ratchet only goes down and a growth is a deliberate build break by design (`MGPipeTypes.h:527-535`). |
|
||||
| **The hand-derived chunk offsets in D6 are wrong.** They were computed from declarations, not compiled. | `MGPipeRenderStateSpans.cpp` computes every boundary with `offsetof`/`sizeof` and `static_assert`s that the chunks are sorted, non-overlapping and cover exactly `[0, sizeof(RenderStateParameters))`. A mistake in this brief is a build break in that file, and the file is right. |
|
||||
| **The pipeline subset is now a superset of what Magma hashes, so more state mints CSOs** — a scissor or sample-coverage toggle that used to cost nothing now costs a hash and a probe. | Hashing runs only when `m_pipelineStateVersion` moves, which is exactly when Magma recomputes `ComputePipelineStateHash` today, so the work is moved, not added. `TrackerTest.BlendToggleReusesTwoCsos` pins that a two-state ping-pong mints two CSOs and then reuses them forever, and D.4.4's blend-toggle table is the measurement. If the number disappoints, the escape hatch is demoting the offending setters to `++m_version` — but that is a **pull-build** semantic change and therefore a P3 decision with its own gate, not an in-flight P2 fix. |
|
||||
| **A D5 derivation is transcribed wrongly**, so a backend reads a value that is subtly not what `GLContext` would have returned. `GetViewport`'s float→int rounding and the 35-way `IsCapabilityEnabled` switch are the two candidates. | This is exactly what the P1 verify comparator was built for and why the entry compare stops being tautological here: the compare-at-read re-reads every one of those fields from the live context at every backend read, field-wise, across 79 retraces and 818 integration-verify entries. On top of it, `RenderStateSpansTest.DerivationMatchesTheFrontendGetters` drives every setter and compares all 29. |
|
||||
| **A dirty bit fires too rarely** — the dangerous direction (`ARCHITECTURE.md:502`), and one the current harness is blind to for object-class state, because the verify comparator compares O-class fields **by identity only** (`PipeInputs.h:248-249`). | P2 emits for value-class bits 0–4 only; bits 5–17 are computed and *counted* but nothing depends on them yet, so an under-firing object-class bit cannot render anything stale in P2. `TrackerTest.AggregateGenerationCatchesABoundTextureMoving` is the first real test of the direction, and the per-bit fire rates go into `MEASUREMENTS.md` so P3a starts from data. The verify "保留模式" extension for consume-and-clear groups is P3b work and is recorded as such. |
|
||||
| **A slot table has no garbage collector, so an object nobody destroys leaks its twin forever** — worse than today's lazy `weak_ptr` sweep. | C's `e2` lands the explicit `delete_*` notification **before** `e3` switches the tables over, and `e3` is not merged without it. `SanityTest.cpp:2575-2596` (deleted-texture scrub) and the ~100 CTS cases `Managers.h:306-314` describes are the existing coverage; a leak check on the 79-case retrace (peak RSS, push vs pull) goes into `MEASUREMENTS.md`. |
|
||||
| **`EnsureProcessTeardownSentinel()` stops being armed** because the arming site moved off `GetOrCreate`, and a twin then `glDelete*`s a recycled name during process teardown. | The arming moves onto the slot table's first insertion in the same commit, and `Managers.h:52-57` documents why a destructor hook is the wrong answer. `SanityTest.cpp:2650-2665, 2765-2790` pin the context-generation guards that back it up. |
|
||||
| **The `g_fbSlotCache` rewrite reintroduces `pGLContext` in `MG_Backend/`** (it is the one place tempted to, since it caches a pointer into frontend storage). | Purity gate C (`grep -rc pGLContext MobileGL/MG_Backend`) runs after every merge, and the replacement is a plain `MGB_CTX->` read, which is also what closes the P1 poison bypass at those five sites. |
|
||||
| **`HandleRecycleScenario` is green for the wrong reason** — the allocator never actually reproduces the address, so the scenario proves nothing. | The `AbaControl` arm exists precisely to prove the reproducer reproduces: it defeats the two guards and asserts the *wrong* pixels. If the ABA stops happening, that arm fails. `ObjectLifetimeIdTest.cpp:120-121,130` shows the precedent of skipping rather than passing when the allocator refuses to repeat — the scenario does the same, with a visible skip. |
|
||||
| **P2 changes `glEnable(GL_FRAMEBUFFER_SRGB)` behaviour**: Espryt now issues a real `glEnable(GL_FRAMEBUFFER_SRGB)` where it previously always disabled. | `MEASUREMENTS.md:84` records that none of the 41 fixtures enables it, so G3's SSIM ≥ 0.99 over 40 traces on both backends is the gate, plus the full `gl44to46` caselist at the `dev` merge. The change is recorded in `MEASUREMENTS.md` as a deliberate conformance fix (it was a silently-swallowed `glEnable` and a lying `glIsEnabled`), not as a side effect. |
|
||||
| **The pull build's `.text` moves more than the three named symbols.** | `symbol_report.py --threshold 0` after every merge (D.1). Anything outside the named set is a defect. If a compiler schedules the `{}` differently than expected, the delta is attributed line by line in the commit message; the gate admits an attributed delta, never an unexplained one. |
|
||||
| **`acc/draw` improves for the wrong reason.** `CallClass::AccessorCalls` is a static tally at ~10 hot entry points (`PipeStats.cpp:76-88`), so a tracker that merely *relocates* reads out of `SyncRenderState` / `GetOrCreatePipeline` / `ApplyDynamicDrawStateTail` scores a lower number without removing work. | The report leads with the **gate hit/miss pairs** (which survive relocation, `PipeStats.cpp:93-99`) and the **CPU-time series**, and quotes `acc/draw` only alongside a re-audit of the tally constants at `DirectGLES.cpp:1421,1524,2043,2053,2977` and `VulkanRenderer.cpp:5009,5016,5274,5927,5934,6416,6449,6462`. This caveat is written into `MEASUREMENTS.md` above the numbers, not below them. |
|
||||
| **Device time is the schedule's long pole**, and both devices are shared with the GL4.6 Wave-7 campaign under the mkdir lock. | The desktop numbers (T1/T2, blend toggle, CSO control, all of the correctness gates) come first and can NO-GO the phase without touching a device. The device A/B is 2 devices × 4 cases × 2 backends × 2 arms ≈ 32 lock holds of ~10 min; budget two days and hold ≤ 25 min per acquisition. A lock held > 60 min is not broken — report "blocked by device lock". |
|
||||
| **The three verify CI lanes have never produced a green run**, so their wall time is unknown and could dominate. | The P2 exit does not depend on them: the local WSL verify run (D.3 part 2) is the evidence, exactly as it was for P1 (`MEASUREMENTS.md:129-142` is local `~/w7/pipe` evidence, not CI evidence). CI green is required before the `dev` merge, not before the GO/NO-GO. |
|
||||
| **`MOBILEGL_PIPE_LEGACY_MEMOS` doubles the Espryt and Magma sync code and rots.** `ARCHITECTURE.md:367` budgets +1 day per phase for it. | Both arms sit behind the same `PipeInputs` interface, and every A/B command in §C runs the suite twice (`MOBILEGL_PIPE_PUSH=0` and default) so the legacy arm cannot silently stop compiling or stop passing. It retires with the pull path at P13. |
|
||||
| **A collision in the 64-bit CSO key aliases two render states.** | The cache `memcmp`s the 396 pipeline bytes on a hash hit before reusing the handle (D7), and `CsoCacheTest.HashCollisionDoesNotAliasTwoStates` forces a collision through a test seam. The memcmp only runs when the pipeline version moved. |
|
||||
| **The patch trio travels twice** (pipeline chunk P0 and `set_patch_state`), so the two carriers could disagree. | The applier asserts under verify that they agree, which turns the redundancy into a trip wire (D6). The bytes are 28 and the state changes about once per program, so the cost is nil. |
|
||||
| **`gen_pipe_dirty_surface.py`'s three blind spots** (a mutator inside a lambda is attributed to the enclosing function; a mutation published through a helper reads as deferred; the scan root is `MG_Impl/GLImpl` only, so the four `MGP_NOTE_MUTATION` sites in `TextureState.h` are outside it) let an unmapped mutation slip past a green gate. | The gaps are written into `DirtySurface.def`'s header comment rather than left implicit, and the gate is a *completeness* gate over what the scanner does see — the semantic proof stays the verify lane, which is blind to none of them. Widening the scan root is recorded as a P3a item. |
|
||||
| **A test that drives a backend helper directly aborts on the poison** because no verb filled the block — the P1 F3 class of failure. | `MG_Test/ScopedPipeVerb.h` already exists for exactly this and eleven tests already use it (`ef6227e1`). Any new test C or D writes that calls a backend helper directly declares its verb the same way; the poison is never weakened and no test name changes. |
|
||||
| **A/B/C/D/E land against an outdated contract.** | The contract is one commit, tagged `p2/contract`. A must not change any signature in `MGPipeRenderStateSpans.h`, `PipeApply.h`, `SlotAllocator.h`, the subsystem bit constants or `RenderStateParameters` after the tag without telling the other four; a rebase-time compile error is the backstop. |
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,462 @@
|
||||
# P2 implementation brief — the frontend state tracker, render state as a CSO + dynamic state, the residual value block, and the first Track H slice
|
||||
|
||||
Tree: `feat/disaggregated @ 48268068` (worktree `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`). **This is the P2 base ref.** The scouts were written at `e7a6a72f`; the one commit since is CI-only (`48268068 [CI] (Workflows): run the test and apk lanes on every push to feat/disaggregated`, `.github/workflows/{apk,test}.yml`, +8 lines), so every scout `file:line` still holds and P2 branches from `48268068`.
|
||||
|
||||
WSL: `~/w7/pipe` is a worktree of the same repo on `feat/disaggregated`; `~/w7/base` is `dev@81b17c0b` (the performance anchor, untouched). Tree creation is `scratchpad/wf4/wsl_p1_tree.sh <slug> <base-ref> [verify]` with `p1`→`p2` throughout (it creates `~/w7/p2-<slug>` on branch `p2/<slug>`, initialises submodules, copies `3rdparty/glslang/External` and the trace fixtures, then configures and builds `build-linux` (pull), `build-push`, and with a third argument `verify` also `build-verify`). The device-lock loop is `scratchpad/wf2/stats_baseline.sh:16-29` verbatim (mkdir lock under `.../8ab6b3cb-.../scratchpad/w7/locks/<serial>`, 1500 s acquire timeout, 20 s poll, one hold per run, `rm -rf` after).
|
||||
|
||||
Every `file:line` below was re-opened at `48268068`. Corrections to the scouts are **[correction]**; deliberate departures from the design documents are **[deviation]** and carry their reason.
|
||||
|
||||
**Scout verification summary.** All five scouts were read in full and their load-bearing claims re-opened. The following are wrong or incomplete and are fixed here:
|
||||
|
||||
1. **[correction] Three capabilities have no storage, not two.** `RenderState::SetCapability`'s `default: // not supported currently` arm (`MobileGL/MG_State/GLState/RenderState/RenderState.cpp:381-382`) and `IsCapabilityEnabled`'s `default: return false;` (`:429-430`) swallow `DepthClamp`, `FramebufferSrgb` **and `TextureCubeMapSeamless`** — the last one is reachable from `glEnable` (`MG_Util/Converters/GLToMG/RenderStateEnumConverter.cpp:301` maps `GL_TEXTURE_CUBE_MAP_SEAMLESS` onto `CapabilityInput::TextureCubeMapSeamless`, `MGPipeValueTypes.h:202`) and has zero read points anywhere. `scout-render-state.md` §1.3, `generated/PipeSpanTable.inc:24-26`, `ROADMAP.md:78` and `MEASUREMENTS.md:84` all name only two. D8 gives all three real storage.
|
||||
2. **[correction] The free padding hole is exactly 3 bytes at `[581, 584)`**, between `ColorMasks` (offset 549, size 32, align 1) and `ClearColor` (offset 584, align 4). `scout-render-state.md:143-151` gropes at this and half-retracts it. It is verified from the declarations: `using Bool = bool` (`MG_Util/Types.h:33`), `BoolVec4 = Vec4<Bool>` = `VecBase<…, Bool, 4>` whose only member is `Array<Bool,4>` (`MG_Util/Math/VectorTypes.h:16-18`, alias `:222`) → align 1, size 4. Three bytes is exactly enough for the three new capability bools, so `sizeof(RenderStateParameters)` stays 1168 and **no existing member's offset moves** — which is what keeps Espryt's `kBlendSpanBegin`/`kBlendSpanEnd` (312/536) and the whole hand-derived offset table valid.
|
||||
3. **[correction] `RenderState`'s three value members are not value-initialised.** `RenderStateParameters m_parameters;` (`RenderState.h:172`) and the two `PixelStoreParameters` (`:175-176`) have no `{}`, so their padding bytes are indeterminate. A byte-range content hash over them (which is what the CSO key is) would then be stable only within one context. D3 adds `{}` to all three and pays for it with one attributed `.text` resize.
|
||||
4. **[correction] `ComputePipelineStateHash` is not a pure function of `RenderStateParameters`.** Its signature is `(Uint32 colorAttachmentCount, VkSampleCountFlagBits rasterizationSamples)` (`VulkanRenderer.cpp:4821-4822`) and it folds `ResolveEffectiveSampleMask` (`:4813-4819`, itself reading `Multisample`, `SampleMask` and `SampleMaskValue`). The scouts list the hashed fields but not that the signature makes the hash render-pass-dependent. Consequence, and it is load-bearing: a render-state CSO handle **cannot** replace `pipelineStateHash` on its own; the render-pass facts must stay in the memo key. D12 keeps `renderPassHash` as a separate key component, which already separates them.
|
||||
5. **[correction] `ARCHITECTURE.md:504` names `tools/bench.sh`; the script is `tools/device_bench/bench.sh`** (verified: `tools/device_bench/{README.md,bench.sh,profile.sh,session.sh,devices/odinlite.env}`). The integrator fixes the citation.
|
||||
6. **[correction] The eight/nine validate-entry disagreement resolves to nine.** `ARCHITECTURE.md:153` names eight; the landed `MGP_FILL_CLASS_LIST` has nine (`MG_Pipe/FillPoints.def:107-108`, with the reason in its own comment). P2 adopts nine and the integrator corrects the doc (D5).
|
||||
7. **[correction] The dirty-surface gate is not a gate yet.** `ARCHITECTURE.md:172` and `:568` say "P1 起成为门"; `.github/workflows/test.yml:1524-1528` says it stays informational and becomes a gate in P2. The workflow is what runs. P2 promotes it (D16).
|
||||
8. **Confirmed at `48268068`, unchanged from the scouts**: `python3 scripts/gen_pipe_dirty_surface.py --summary` still prints `41 files / 926 mutator calls / 73 distinct mutators / 92 in 36 IMMEDIATE PUBLISH POINTS across 7 distinct mutators / 834 DEFERRED`. `sizeof(RenderStateParameters)==1168`, `PerBufferBlendState`/`StencilFaceState`/`PixelStoreParameters` all 28 (`MGPipeValueTypes.h:536-544`). `StencilFaceState` is `Func(0) Ref(4) ValueMask(8) WriteMask(12) FailOp(16) PassDepthFailOp(20) PassDepthPassOp(24)` (`:229-237`) — so the pipeline half of a face is `[0,4) ∪ [16,28)` and the dynamic half `[4,16)`, exactly as `scout-render-state.md` §7.2 says. `ResidualValueBlock` is 1248 = 1168 + 28 + pad + 8 + 4 + 4 + 16 + 8 + 8 (`MGPipeTypes.h:516-537`). `kMGPipePipelineStateMembers[]` is 24 names (`generated/PipeSpanTable.inc:34-60`), `kMGPipePipelineChunks`/`kMGPipeDynamicChunks` are declared and never defined (`:66-67`). `VertexArrayObject`'s three backend memo triples are at `VertexArrayObject.h:106-150`, storage `:190-197`, and `SetBackendAuxMemo` has no live reader (only writer `VertexInputStateFactory.cpp:83-84`). `MGP_FILL(Verb)` expands to `MGPipeFillForVerb(MGPipeVerb::Verb)` (`MG_Impl/Pipe/PipeFill.h:52`) and `((void)0)` in the pull build (`:54`).
|
||||
9. **[correction] `scout-render-state.md` §6.4 under-counts the residual ratchet.** It says landing the render-state CSO takes 1248 → 80. P2 also lands `set_pixel_pack_state` and `set_patch_state`, so the ratchet is **1248 → 8** (D9).
|
||||
|
||||
---
|
||||
|
||||
## A. Goal and acceptance gate
|
||||
|
||||
`docs/Disaggregated/ROADMAP.md:18`, verbatim:
|
||||
|
||||
> | **P2** 渲染状态 CSO + 第一片 Track H + 残余值块 | 18–26 | `MG_Impl/Pipe/Tracker`(dirty 位、5 个聚合世代、抑制器骨架);`gen_pipe_dirty_surface.py` 首轮映射成门;`MGPipeRenderStateSpans` + G7 setter 一致性测试;`CsoCache`(64 项,键 = pipeline 子集);`create/bind_render_state` + `set_dynamic_state`(Espryt `SyncRenderState` 一行不动;Magma `ComputePipelineStateHash`/`GetOrCreatePipeline`/`ApplyDynamicDrawStateTail` 改从 CSO 与动态 payload 取);`set_pixel_pack_state`、`set_patch_state`、`set_vertex_attrib_defaults`;`set_residual_value_state` + `ResidualValueBlock` 绊线;**第一片 Track H**:Espryt 0b(`SlotAllocator` + 6 个 registry → slot 数组 + 删 `TwinLookupMemo`×3/`OwnerEquals`/`g_fbSlotCache`/GC)与 Magma 子系统 4(`VertexInputStateFactory`/`VaoDrawMemo` 重键,删前端 VAO 里的后端裸指针);`MOBILEGL_PIPE_LEGACY_MEMOS`;补 `FramebufferSrgb`/`DepthClamp` 存储 | 集成 × 2 后端 × {pull, push} 逐名相同;40 trace push 下 SSIM ≥ 0.99 双后端;verify 零分歧;`HandleRecycleScenario` 绿且重键前红;G7 测试绿且拿掉一个字段能红;两台设备配对逐线程 CPU p50/p99 不差且 tracker 绝对 ns 在上限内;Blaze3D blend-toggle 微基准;CSO 内容寻址关闭的负面对照 | P1 |
|
||||
|
||||
Binding context: `ARCHITECTURE.md:147-155` (§5.1 — push happens at validate, before the verb, never in the GL setter, because Blaze3D brackets every batch with `glEnable/glDisable(GL_BLEND)`; only `BufferBackendOps`' seven hooks push at GL-call time), `:157-174` (§5.2 — the dirty-bit table, the five aggregate generations, wrap-around widened at the tracker boundary), `:176-190` (§5.3 — D-B1: whole blob on the wire, CSO identity = the pipeline subset only, the dynamic subset enumerated, the split written in exactly one place, `SyncRenderState` untouched, the client value-fetch order, the `FramebufferSrgb`/`DepthClamp` hole), `:192-200` (§5.4 — the D-B3 validation invariant and the four coalescing rules), `:357-359` (§9.4 — the residual value block and its three disciplines), `:363` (§9.5 — the 21-memo census the Track H slice pays into), `:365-369` (§9.6 — why `MOBILEGL_PIPE_LEGACY_MEMOS` must be a compile-time arm), `:497-507` (§13.2 — the five-part validation gate), `:552` (`MG_Impl/Pipe/` is where `Tracker`, `SlotAllocator`, `CsoCache` land), `:576-597` (the switch tables). `ROADMAP.md:7`: **每个门必须能因它存在的理由变红**; ALL must build; no hot-path instrumentation may be committed; Windows is not a correctness gate; device comparisons are reboot-clean, same-thermal-window, paired A/B. `ROADMAP.md:39`: **day 43 is the GO/NO-GO.** `ROADMAP.md:42-58` is the checklist and the verdict criteria; items 2–7 of it are P2's to produce.
|
||||
|
||||
Decoded into checkable statements. Unless a row says otherwise, commands run in a P2 WSL worktree; `$BASE` = `48268068`.
|
||||
|
||||
| # | statement | the exact command that checks it |
|
||||
|---|---|---|
|
||||
| **G1** | The **pull build** (`MOBILEGL_PIPE_PUSH=OFF`, `MOBILEGL_PIPE_VERIFY=OFF`, Release/INFO) has an identical `nm --defined-only` symbol set before and after P2 — 0 added, 0 removed, 0 renamed — and the only `.text` resize is `MG_State::GLState::RenderState::RenderState()` (D3's three `{}`), named in the commit message. | `python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --json` → `added==removed==renamed==0`; `resized` is empty or exactly the one mangled `RenderState::RenderState()` symbol. |
|
||||
| **G2** | `ctest -L integration-gpu` is **name-for-name identical between the pull and the push build**, on both backends, and green in both. | `for d in build-linux build-push; do ctest --test-dir $d -N \| grep -E '^\s+Test #' \| sed 's/^ *Test *#[0-9]*: //' \| sort > ~/w7/p2-names-$d.txt; done; diff ~/w7/p2-names-build-linux.txt ~/w7/p2-names-build-push.txt` → empty; then `ctest --test-dir build-linux -L integration-gpu --no-tests=error -j 4` and the same on `build-push`, both green. |
|
||||
| **G3** | The 40-trace corpus replays **under push** with SSIM ≥ 0.99 on both backends (79 desktop cases: 40 × 2 minus `iterationrp × DirectGLES`). | `python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-push/libMobileGL.so --out ~/w7/retrace-out/p2-push -j 4 --ssim 0.99` (the P0.5/P1 script, `scratchpad/wf2/retrace_gate.py`). |
|
||||
| **G4** | The **verify** build shows zero divergence: no `Fatal{PipeVerifyDiffer`, no `Fatal{UnmigratedPipeInput`, no `Fatal{PipeResidualDiverged`, and every case armed. | `ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4`; `MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-verify/libMobileGL.so --out ~/w7/retrace-out/p2-verify -j 4`; then `grep -l 'Fatal{' ~/w7/retrace-out/p2-verify/*/mobilegl.log` empty and `grep -L 'MGPipe verify:' ~/w7/retrace-out/p2-verify/*/mobilegl.log` empty. |
|
||||
| **G5** | **`SyncRenderState` is not one line changed.** The whole of `namespace RenderStateImpl` in `DirectGLES.cpp` is byte-identical to the base ref (line numbers may move; the text may not). | `for r in $BASE HEAD; do git show $r:MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp \| awk '/^ namespace RenderStateImpl \{/,/^ \} \/\/ namespace RenderStateImpl/' \| sha256sum; done` → the two hashes are equal. |
|
||||
| **G6** | **G7 setter consistency**: for every public `RenderState` setter, the pipeline-subset hash moves ⟺ `m_pipelineStateVersion` moves; and the chunk table partitions `[0, sizeof(RenderStateParameters))` exactly (sorted, non-overlapping, complete). | `ctest --test-dir build-push -R 'RenderStateSpans\.' --no-tests=error --output-on-failure` (the partition half is a `static_assert` in `MGPipeRenderStateSpans.cpp`, so a gap is a build break). |
|
||||
| **G7** | **G6's negative control**: moving one member from `kMGPipePipelineChunks` to `kMGPipeDynamicChunks` (partition still complete, so it still compiles) turns the setter-consistency test red, naming that member's setter. | `scripts/g7_negative_control.sh` (D19) — patches `MGPipeRenderStateSpans.cpp` to demote `ColorMasks`, rebuilds, expects `ctest -R 'RenderStateSpans\.SetterConsistency'` to **fail**, then reverts. Non-zero rc from ctest is the pass. |
|
||||
| **G8** | **`HandleRecycleScenario` is green after the re-key and red before it**, on at least one backend, as three always-on ctest entries: handle arm green, legacy arm green, ABA-control arm red. | `ctest --test-dir build-verify -R 'HandleRecycle' --no-tests=error --output-on-failure` — `*.Handles` and `*.Legacy` pass, `*.AbaControl` passes **by asserting the corruption** (D18). |
|
||||
| **G9** | `gen_pipe_dirty_surface.py` is a **gate**: the mapping file covers all 73 mutators, an unmapped mutator or a mapping row naming a mutator that no longer exists fails the job, and the report regenerates with `git diff --exit-code`. | `python3 scripts/gen_pipe_dirty_surface.py --check` (rc 0) and `python3 scripts/gen_pipe_dirty_surface.py --self-test` (rc 0; canned negative controls). CI: `pipe-gates`. |
|
||||
| **G10** | The **`ResidualValueBlock` tripwire** holds: `MGL_RESIDUAL_BLOCK_SIZE` is **8** (down from 1248, never up), every member has an `offsetof` assertion, `MOBILEGL_PIPE_STATS`'s `resid=` byte class is **non-zero** in a device window, and a capability the residual block and the working block disagree about aborts. | build (the ratchet is a `static_assert`); `ctest --test-dir build-verify -R 'Residual' --no-tests=error`; on device `grep 'MGPipe stats:' mobilegl.log \| tail -1` shows `resid=` > 0. |
|
||||
| **G11** | **Two devices, reboot-clean, paired A/B: per-thread CPU p50 and p99 deltas are not negative on either device, and the tracker's absolute ns/draw is inside the pinned ceiling.** | D.4 — the `benchmark.json` `frameCpuTimesMs[]` series (E adds it) reduced host-side to p50/p99, plus the DriverBench `ns_per_op` decomposition T1/T2. The ceiling is pinned in `MEASUREMENTS.md` **before** the run (D.4.5). |
|
||||
| **G12** | The **Blaze3D blend-toggle microbenchmark** and the **CSO-content-addressing negative control** are both published, and the negative control cannot rot: a ctest entry proves the switch actually changes CSO mint/bind counts. | `MobileGL/MG_Benchmark/Driver/run_driver_bench.sh {native,espryt,magma}` on `mc_state_toggle`; `ctest --test-dir build-push -R 'CsoContentAddressing' --no-tests=error`. |
|
||||
| **G13** | Nothing reintroduces a purity violation: `pGLContext` still appears zero times under `MG_Backend/`, the include closure still holds, no stdio instrumentation, generators regenerate clean. | `grep -rc 'pGLContext' MobileGL/MG_Backend \| grep -v ':0$'` empty; `python3 scripts/check_include_closure.py`; `python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test`; the `pipe-gates` stdio grep. |
|
||||
| **G14** | Existing test names are never removed (additions only), and the full CI matrix is green. | `ctest --test-dir build-linux -N \| … \| comm -23 ~/w7/p2-before-ctest-names.txt -` empty; `gh workflow run test.yml --ref feat/disaggregated`. |
|
||||
|
||||
Baseline captures the integrator takes **before** any package lands (in `~/w7/pipe` at `48268068`):
|
||||
|
||||
```sh
|
||||
cp ~/w7/pipe/build-linux/libMobileGL.so ~/w7/p2-before-libMobileGL.so
|
||||
ctest --test-dir ~/w7/pipe/build-linux -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort > ~/w7/p2-before-ctest-names.txt
|
||||
git -C ~/w7/pipe show HEAD:MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp \
|
||||
| awk '/^ namespace RenderStateImpl \{/,/^ \} \/\/ namespace RenderStateImpl/' | sha256sum > ~/w7/p2-before-syncrenderstate.sha
|
||||
python3 scripts/gen_pipe_dirty_surface.py > ~/w7/p2-before-dirty-surface.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## B. Fixed design decisions
|
||||
|
||||
Nothing in this section is re-decided inside a package. Where a decision departs from the design documents it is marked **[deviation]** and the doc line the integrator must correct is named.
|
||||
|
||||
### D1 — Where the tracker runs: `MGP_FILL` stays; `MGPipeFillForVerb` becomes the tracker's entry point
|
||||
|
||||
`MGP_FILL(Verb)` (`MG_Impl/Pipe/PipeFill.h:52`) is already exactly one statement before every `gBackendFunctionsTable.GL.*` call, after every early return (`PipeFill.h:10-15`, and the 83 statements over 69 verbs the P1 brief §B.7 enumerates). It is the validate point `ARCHITECTURE.md:151` demands and it is already generated-table-driven.
|
||||
|
||||
**Decision: the macro spelling, the 83 call sites and the verb enum do not change. `MGPipeFillForVerb(MGPipeVerb)` is renamed `MGPipeValidateForVerb(MGPipeVerb)` and its body becomes the tracker's walk; `MGP_FILL` expands to the new name.** The tracker does **not** sit above `MGP_FILL` and there is no new `ValidateForDraw`/`ValidateForClear`/… family of functions.
|
||||
|
||||
- **[deviation] against `ARCHITECTURE.md:153`**, which asks for eight named `ValidateFor*` entry points. Reason: the landed machinery already dispatches on `kMGPipeVerbClass[verb]` (`generated/PipeFillPoints.inc:197`) into **nine** classes (`FillPoints.def:107-108`), and eight separate entry points would either duplicate that table or force a merge of `kProgramOp` back into `kDraw` that `FillPoints.def:105-106` explicitly argues against. One entry point with a class-indexed switch is the same code with one call site per verb instead of nine. The integrator corrects `ARCHITECTURE.md:153` to nine classes and names them.
|
||||
- `MGPipeLeaveVerb()` (`PipeFill.h:34`, used by `MG_Test/ScopedPipeVerb.h`) keeps its name and semantics.
|
||||
- `MGP_NOTE_MUTATION` (`MG_Pipe/PipeMutation.h`, four statements over three fields at `TextureState.h:85,98,111,133`) **stays exactly as it is**. `MEASUREMENTS.md:117` is right that it is the shape the tracker needs; the tracker does not absorb it, because it answers a different question (a backend writing frontend state *inside* a verb, after the walk has run).
|
||||
|
||||
The body of `MGPipeValidateForVerb(verb)`, in order:
|
||||
|
||||
1. everything `MGPipeFillForVerb` does today up to and including `SetIdentity` / the null-context early return (`PipeFill.cpp:566-589`) — unchanged, including the poison serial bump and the verify arming;
|
||||
2. **the dirty walk** (D4): compare the tracker's `m_lastPushed` shutters against the live counters, producing a `Uint32` dirty mask;
|
||||
3. **emission** (D6, D7, D9, D10, D11): for each set dirty bit whose subsystem bit is on in the runtime `MOBILEGL_PIPE_PUSH` bitmask, build the payload and hand it to the applier (D2);
|
||||
4. **the residual fill**: the P1 per-class copy loop (`PipeFill.cpp:591-609`), restricted to the fields **not** covered by an emitted call (D5's `kMGPipeFieldEmittedBy[]`), with stamping unchanged;
|
||||
5. `EntryCompare(inputs, mask)` under verify (`PipeFill.cpp:611`) — unchanged, and now **no longer tautological**, which is the P1 brief's D8 promise coming due.
|
||||
|
||||
### D2 — The applier and where the server's working state lives
|
||||
|
||||
**Decision: in the monolith, the server's per-context working `RenderStateParameters` *is* `PipeInputs::m_renderState` (`MG_Backend/MGPipe/PipeInputs.h:645`).** `bind_render_state` and `set_dynamic_state` scatter their chunks straight into it. That is why Espryt's `const RenderStateParameters&` binding at `DirectGLES.cpp:2056` and the `Uint16` read at `:2028` need no change at all — the block they read is the assembled block. This is the mechanism behind "`SyncRenderState` 一行不动" (`ARCHITECTURE.md:188`, `ROADMAP.md:47`), and it is what makes the verify comparator a real oracle: the compare-at-read now proves *assembled == live*, field by field, at every backend read.
|
||||
|
||||
New files: `MobileGL/MG_Pipe/PipeApply.{h,cpp}`, `namespace MobileGL::MG_Pipe`, compiled only under `MOBILEGL_PIPE_PUSH`.
|
||||
|
||||
```cpp
|
||||
// PipeApply.h — the in-process applier. Under split this file is the server half
|
||||
// (ARCHITECTURE.md:375, MG_Remote/Server/PipeApplier); in the monolith it writes gPipeInputs
|
||||
// directly, so a call and its effect are one function call apart and nothing is serialised.
|
||||
void MGPipeApplyCreateRenderState(const MGPRenderStateDesc& desc, const void* chunkBytes);
|
||||
void MGPipeApplyBindRenderState(const MGPBindRenderState& bind);
|
||||
void MGPipeApplySetDynamicState(const MGPDynamicState& dyn, const void* chunkBytes);
|
||||
void MGPipeApplySetPixelPackState(const MGPPixelPackState& pack);
|
||||
void MGPipeApplySetPatchState(const MGPPatchState& patch);
|
||||
void MGPipeApplySetVertexAttribDefaults(const MGPVertexAttribDefaults& hdr, const MGPAttribValue* tail);
|
||||
void MGPipeApplySetResidualValueState(const ResidualValueBlock& block);
|
||||
```
|
||||
|
||||
The applier owns a per-context CSO store: `Vector<RenderStateCsoRecord>` indexed by `MGPipeHandle::Slot`, each record holding the 396 pipeline bytes and a `Gen`. `MGPipeApplyBindRenderState` memcpy-scatters the record's seven pipeline chunks into `m_renderState`, then writes `m_renderStateParametersVersion = bind.Version` and `m_pipelineStateVersion = bind.PipelineVersion`. `MGPipeApplySetDynamicState` scatters the chunks named by `dyn.ChunkMask` and writes `m_renderStateParametersVersion = dyn.Version`.
|
||||
|
||||
**After any scatter the applier calls `MGPipeDeriveRenderStateFields(PipeInputs&)`** — see D5.
|
||||
|
||||
The applier `MOBILEGL_ASSERT`s (debug/verify only) that a `bind` names a live `{slot, gen}` and that `desc.ChunkMask` covers every chunk of a brand-new CSO.
|
||||
|
||||
### D3 — Value-type changes in `MGPipeValueTypes.h` and `RenderState`
|
||||
|
||||
1. **Three new members in `RenderStateParameters`**, declared *immediately after `Array<BoolVec4,8> ColorMasks;` and before `FloatVec4 ClearColor;`*, filling the 3-byte hole at `[581, 584)`:
|
||||
|
||||
```cpp
|
||||
// GL_FRAMEBUFFER_SRGB / GL_DEPTH_CLAMP / GL_TEXTURE_CUBE_MAP_SEAMLESS. Until P2 these
|
||||
// three fell to SetCapability's `default:` arm - glEnable was swallowed and
|
||||
// IsCapabilityEnabled answered a compile-time false, so DirectGLES' sRGB block
|
||||
// (DirectGLES.cpp:2168) and five DirectVulkan read points consumed a constant.
|
||||
// Placed HERE, in the three alignment bytes between ColorMasks and ClearColor, so
|
||||
// sizeof(RenderStateParameters) stays 1168 and no existing offset moves: the Espryt
|
||||
// span constants and the P2 chunk table both depend on that.
|
||||
Bool FramebufferSrgbEnabled = false;
|
||||
Bool DepthClampEnabled = false;
|
||||
Bool TextureCubeMapSeamlessEnabled = false;
|
||||
```
|
||||
|
||||
The existing `static_assert(sizeof(RenderStateParameters) == 1168, ...)` (`:541`) is the check; if it fires, the hole is not where this brief computed it and the implementer must find the real one with a temporary `static_assert(offsetof(...))` rather than growing the struct (growing it is a `MGL_RESIDUAL_BLOCK_SIZE` violation).
|
||||
2. **Three rows in `MGP_FIELDS_RenderStateParameters(F)`** (`PipeFields.def:230-247`), in declaration order. `gen_pipe.py` asserts every direct member has a row (`PipeFields.def:224-228`), so omitting one fails `pipe-gates`.
|
||||
3. **Three `SET_CAPABILITY` arms and three `RETURN_CAPABILITY` arms** in `RenderState.cpp` (`:317-338`, `:390-413`), keeping the source order of `CapabilityInput`. All three therefore call `BumpVersions()` and land in the **pipeline** half (D6). `FramebufferSrgb` on the pipeline side is what `ARCHITECTURE.md:190` asks for; `DepthClamp` is `VkPipelineRasterizationStateCreateInfo::depthClampEnable` and `TextureCubeMapSeamless` changes sampler interpretation, so both belong there too.
|
||||
4. **`{}` on the three value members** of `RenderState` (`RenderState.h:172`, `:175`, `:176`) so padding is deterministic. Cost: one `.text` resize of `RenderState::RenderState()`, allowed by G1 and named in the commit message. Reason: the CSO key is a byte-range hash (D6); indeterminate padding would make a CSO handle reproducible only within one context, and would make the residual block's byte-level trip wire meaningless.
|
||||
|
||||
**Behaviour change, and it is real, so it is gated.** With storage, `glEnable(GL_FRAMEBUFFER_SRGB)` now (a) makes `glIsEnabled` answer true and (b) makes Espryt issue a real `glEnable(GL_FRAMEBUFFER_SRGB)` at `DirectGLES.cpp:2170` — that block is **ungated** by the span dirty flags and already reads the accessor, so it needs no edit and is not a `SyncRenderState` change. `DepthClamp` and `TextureCubeMapSeamless` gain no reader on either backend (verified: no `depthClampEnable`/`alphaToOneEnable` anywhere in `PipelineFactory.{h,cpp}`/`VulkanRenderer.cpp`; `TextureCubeMapSeamless` appears only in the three enum converters), so their only effect is `glGet`/`glIsEnabled`. `MEASUREMENTS.md:84` records that none of the 41 fixtures enables any of them, so G3's SSIM gate is the check that no fixture output moves.
|
||||
|
||||
### D4 — Dirty bits and the five aggregate generations
|
||||
|
||||
**Representation.** `Uint32 MGPipeTracker::m_dirty`, one bit per row of `ARCHITECTURE.md:161-168`, declared as a plain `enum class MGPipeDirty : Uint32` in `MG_Impl/Pipe/Tracker.h` (hand-written, not generated — the list is 15 long and is design, not derived data), with `static_assert(kMGPipeDirtyCount <= 32)`:
|
||||
|
||||
| bit | name | class | shutter the tracker compares |
|
||||
|---|---|---|---|
|
||||
| 0 | `NEW_RENDER_STATE` | value | `GetRenderStateParametersVersion()` (`Uint16`, widened) |
|
||||
| 1 | `NEW_PIPELINE_STATE` | value | `GetPipelineStateVersion()` (`Uint16`, widened) |
|
||||
| 2 | `NEW_PIXEL_PACK` | value | `PixelStoreParameters` pack, `BitwiseEqual` |
|
||||
| 3 | `NEW_PATCH_STATE` | value | the patch trio, `BitwiseEqual` (**NaN is legal**, `ARCHITECTURE.md:162`) |
|
||||
| 4 | `NEW_VERTEX_ATTRIB_DEFAULTS` | value | `ContentHash` over the 32 `CurrentVertexAttributeValue`s |
|
||||
| 5 | `NEW_VERTEX_ELEMENTS` | value | `VertexArrayObject::GetConfigVersion()` |
|
||||
| 6 | `NEW_SHADER` | value | `ProgramObject::GetLinkVersion()` |
|
||||
| 7 | `NEW_SHADER_BINDINGS` | value | image-unit / backend-state / block-binding / uniform-write-set versions |
|
||||
| 8 | `NEW_GLOBAL_CONSTANTS` | value | `GetUBOContentVersion()` |
|
||||
| 9 | `NEW_VERTEX_BUFFERS` | object | `VertexArrayState::m_anyVaoAttributeGeneration` **(new)** → 32-attribute prefix |
|
||||
| 10 | `NEW_INDEX_BUFFER` | object | index slot version + bound object `{slot, gen}` |
|
||||
| 11 | `NEW_FRAMEBUFFER` | object | `FramebufferState::m_anyAttachmentGeneration` **(new)** + object/slot version → recompute `ContentHash` |
|
||||
| 12 | `NEW_SAMPLER_VIEWS` | object | `TextureState::m_anyTextureContentGeneration` **(new)** + bind generation → `GetMaxTouchedUnit()` prefix |
|
||||
| 13 | `NEW_SAMPLERS` | object | `TextureState::m_anyTextureParamsGeneration` **(new)** + sampling-resolution generation |
|
||||
| 14 | `NEW_SHADER_IMAGES` | object | the same two texture aggregates + image-unit version |
|
||||
| 15 | `NEW_CONST_BUFFERS` / `NEW_SHADER_BUFFERS` / `NEW_SO_TARGETS` (three bits, 15–17) | object | `BufferState::m_anyBufferChangeGeneration` **(new)** → `GetTouchedBindPointCount()` prefix |
|
||||
|
||||
**P2 only *emits* for bits 0–4.** Bits 5–17 are computed, counted and asserted by the tracker but their emission is P3a/P3b/P4a/P4b; their fields keep going through the residual fill loop. The tracker records, per verb class, how many draws each bit fired on, which is the first honest measurement of "does this shutter actually shut" and is what the dangerous direction (`ARCHITECTURE.md:502`, a dirty bit that fires too *rarely*) is judged against.
|
||||
|
||||
**The five aggregate generations.** `Uint64`, monotonic, bumped at the existing bump points, all **`#if MOBILEGL_PIPE_PUSH`-guarded** so the pull build's `MG_State` objects do not change size or code (G1):
|
||||
|
||||
| member | file | bumped at |
|
||||
|---|---|---|
|
||||
| `VertexArrayState::m_anyVaoAttributeGeneration` | `MG_State/GLState/VertexArrayState/VertexArrayState.h` | every `VertexArrayObject::BumpConfigVersion` site (`VertexArrayObject.cpp:299,305,311`) — reached through a new `NotifyAttributeChanged()` on the owning state |
|
||||
| `FramebufferState::m_anyAttachmentGeneration` | `.../FramebufferState/FramebufferState.h` | `FramebufferObject.cpp:192,203,215` |
|
||||
| `TextureState::m_anyTextureContentGeneration` | `.../TextureState/TextureState.h` | `TextureObject.cpp:285,354,365`; `TextureObject2DCube.cpp:51,62` |
|
||||
| `TextureState::m_anyTextureParamsGeneration` | `.../TextureState/TextureState.h` | `TextureObject.cpp:101,126,140,154,203,210,227,238,258,294,303`; `TextureObject.h:182`; `SamplerObject.cpp:27-35` |
|
||||
| `BufferState::m_anyBufferChangeGeneration` | `.../BufferState/BufferState.h` | `BufferObject.cpp:45,52,61,75,82,304,368` |
|
||||
|
||||
The bump is spelled `MGP_NOTE_AGGREGATE(VaoAttribute);` — a new macro in `MG_Pipe/PipeMutation.h` next to `MGP_NOTE_MUTATION`, `((void)0)` in the pull build, exactly the same shape and for the same reason (`PipeMutation.h:29-40`). A per-object bump reaches its owning state through a back-pointer the object already has, or, where it does not, through a free function `MGPipeNoteAggregate(MGPipeAggregate)` that finds the live `GLContext` — the second form costs a global load on a cold path and is what `MGP_NOTE_MUTATION` already does (`PipeFill.cpp:479-491`).
|
||||
|
||||
**Wrap-around.** Three shutters are `Uint16` (`RenderState::m_version`, `m_pipelineStateVersion`, `FramebufferObject::m_objectVersion`) and two more are `Uint16` on `SamplerObject`/`TextureObject` params. The tracker widens them in its **own** `m_lastPushed[]` (`Uint32` accumulator plus the last observed `Uint16`; a decrease means a wrap and adds 65536). **`MG_State` is not changed** (`ARCHITECTURE.md:174`). A wrap is harmless locally: one extra re-push, never a missed push.
|
||||
|
||||
### D5 — The derivation step, and which `PipeInputs` fields stop being copied
|
||||
|
||||
29 of the 47 `kDraw` `PipeInputs` fields are pure functions of `RenderStateParameters`. Once the applier assembles the working block, copying them again from `GLContext` would be a second pull. **Decision: the applier derives them from the working block.**
|
||||
|
||||
`MGPipeDeriveRenderStateFields(PipeInputs&)` in `PipeApply.cpp` recomputes exactly:
|
||||
`m_blendColor`, `m_blendEquation[8][2]`, `m_blendFunc[8][4]`, `m_clampReadColor`, `m_clearColor`, `m_clearDepth`, `m_clearStencil`, `m_colorMask[8]`, `m_cullFaceMode`, `m_depthFunc`, `m_depthMask`, `m_depthRange[16]`, `m_lineWidth`, `m_logicOp`, `m_minSampleShading`, `m_patchInner`, `m_patchOuter`, `m_patchVertices`, `m_polygonModeFront`, `m_polygonOffsetFactor`, `m_polygonOffsetUnits`, `m_primitiveRestartIndex`, `m_provokingVertexMode`, `m_scissorBox`, `m_stencil[2]`, `m_viewport`, `m_viewportIndexed[16]`, `m_capability[35]`, `m_capabilityIndexed` (Blend×8, ScissorTest×16).
|
||||
|
||||
- **[deviation] against P1 brief D4's "no derivation logic is re-implemented in `PipeInputs`".** Reason: the alternative is to keep pulling those 29 fields per verb, which is the cost P2 exists to remove. The derivations are one to four lines each and are mechanical transcriptions of `RenderState`'s getters (`RenderState.cpp:53-971`); two are non-trivial and must be transcribed exactly: `GetViewport()` returns viewport 0 **rounded to integers** (`RenderState.h:27-31`), and `IsCapabilityEnabled`/`IsCapabilityEnabledIndexed` are the 35-way and 2-way switches at `RenderState.cpp:387-432` and `:434-…`, including `Blend → BlendStates[0].Enabled` and `ScissorTest → ScissorTestEnabledMask & 1`.
|
||||
- **The guard is the oracle P1 built.** `MOBILEGL_PIPE_VERIFY`'s compare-at-read (`PipeInputs.h:62-63` → `PipeFill.cpp:439-463`) re-reads each of these from the live context at *every backend read* and compares field-wise. A transcription error is caught on the first draw that reads it, across 79 retraces and 818 integration-verify entries. On top of that, a unit test (`RenderStateSpansTest.DerivationMatchesTheFrontendGetters`) drives every setter and compares all 29 derived values against the `GLContext` getters.
|
||||
|
||||
`gen_pipe.py` gains a generated table `kMGPipeFieldEmittedBy[]` (from a new `MGP_COVERAGE_EMITTED_LIST` in `Coverage.def`) naming, per `MGPipeInputField`, the P2 call that now supplies it. The residual fill loop skips any field whose entry is non-`kNone` **and** whose subsystem bit is on; that is one array lookup per field and it is what makes the runtime bitmask a true per-subsystem A/B.
|
||||
|
||||
### D6 — The chunk table: the split, written in exactly one place
|
||||
|
||||
New files `MobileGL/MG_Pipe/MGPipeRenderStateSpans.{h,cpp}`, compiled **only under `MOBILEGL_PIPE_PUSH`** (appended to `SOURCE_FILES` inside the existing `if (MOBILEGL_PIPE_PUSH)` block, `CMakeLists.txt:462-468`), which is how the pull build gains no symbol (G1). `generated/PipeSpanTable.inc:66-67` already declares `kMGPipePipelineChunks` / `kMGPipeDynamicChunks`; a declaration costs the pull build nothing.
|
||||
|
||||
**The rule that decides the split, and it is the only rule:**
|
||||
|
||||
> **A byte of `RenderStateParameters` is in the pipeline half if and only if some public `RenderState` setter that calls `BumpVersions()` writes it. Every other byte is in the dynamic half. There is no third set.**
|
||||
|
||||
That makes `ARCHITECTURE.md:186`'s G7 invariant — *pipeline-subset hash moves ⟺ `m_pipelineStateVersion` moves* — true **by construction** rather than by inspection, and it resolves all six of the violations `scout-render-state.md` §2.5 found, in the direction of *growing the subset* rather than demoting setters:
|
||||
|
||||
- **[deviation] the pipeline subset is a strict superset of the 24 members `ComputePipelineStateHash` hashes today.** It adds `SampleCoverageValue`, `SampleCoverageInvert`, `FrontFaceModeSetting`, `ProvokingVertexModeSetting`, `ScissorTestEnabledMask`, `PolygonModeBack`, the 11 unhashed capability bools (`DebugOutput`, `DebugOutputSynchronous`, `Dither`, `LineSmooth`, `PolygonOffsetLine`, `PolygonOffsetPoint`, `PolygonSmooth`, `SampleAlphaToCoverage`, `SampleAlphaToOne`, `SampleCoverage`, `ProgramPointSize`) and the three new bools of D3. Reason: the alternative — demoting those setters to `++m_version` — changes `MG_State` semantics in the **pull** build and breaks G1, and it is a behaviour change to the pull path for the sake of the push path. Growing the subset costs nothing measurable: hashing happens only when `m_pipelineStateVersion` moves, which is exactly when Magma already recomputes `ComputePipelineStateHash` today, and a scissor or sample-coverage toggle now mints a *second cached* CSO whose handle is reused thereafter, the same shape as the Blaze3D blend toggle the CsoCache is built for.
|
||||
- **[deviation] against `MGPipeTypes.h:232-235`**, whose comment puts "sample coverage" in the dynamic half. `SetSampleCoverage` (`RenderState.cpp:778-784`) calls `BumpVersions()`, so under the rule it is pipeline. The implementer fixes that comment in the same commit (hints, the point-size family, clear values, blend colour, line width, polygon offset, stencil ref/write mask, viewport, scissor and depth range all stay dynamic and the comment is right about them).
|
||||
- **[deviation] the patch trio is in the pipeline half *and* is carried by `set_patch_state`.** `Coverage.def:62-64` routes the three patch accessors to `SetPatchState`; `kMGPipePipelineStateMembers` lists all three. Both are right for different reasons: they are pipeline state (`VkPipelineTessellationStateCreateInfo::patchControlPoints`, hashed at `VulkanRenderer.cpp:4864-4878`) **and** a shader-variant input both backends bake into the synthesized control stage (`MGPipeTypes.h:498-499`, read from a shader-build path at `Managers.cpp:7194-7205`, not a draw path). So the bytes travel twice — 28 bytes on a state that changes about once per program — and the applier asserts under verify that the two carriers agree. Redundancy here is a trip wire, not waste.
|
||||
|
||||
**The table.** `MGPipeRenderStateSpans.cpp` computes every boundary with `offsetof`/`sizeof` — never a literal — and carries `static_assert`s that the chunks are sorted, non-overlapping and cover exactly `[0, sizeof(RenderStateParameters))`. The offsets below are what this brief computes; **the file must derive them, and if it disagrees the file is right and this table is wrong.**
|
||||
|
||||
| # | set | range | size | members |
|
||||
|---|---|---|---|---|
|
||||
| D0 | dynamic | `[0, 264)` | 264 | `Viewports[16]`, `LineWidth`, `PointSize` |
|
||||
| P0 | pipeline | `[264, 292)` | 28 | `PatchVertices`, `PatchDefaultOuterLevel`, `PatchDefaultInnerLevel` |
|
||||
| D1 | dynamic | `[292, 312)` | 20 | `PolygonOffsetFactor/Units/Clamp`, `ClipOrigin`, `ClipDepthMode` |
|
||||
| P1 | pipeline | `[312, 584)` | 272 | `BlendStates[8]`, `LogicOp`, `DepthTestEnabled`, `DepthFunc`, `DepthMask`, `ColorMasks[8]`, **`FramebufferSrgbEnabled`, `DepthClampEnabled`, `TextureCubeMapSeamlessEnabled`** |
|
||||
| D2 | dynamic | `[584, 752)` | 168 | `ClearColor`, `ClearDepth`, `ClearStencil`, `BlendColor`, `DepthRanges[16]` |
|
||||
| P2 | pipeline | `[752, 772)` | 20 | `SampleCoverageValue`, `SampleCoverageInvert`, `SampleMaskValue`, `MinSampleShadingValue` |
|
||||
| D3 | dynamic | `[772, 784)` | 12 | `StencilStates[0].{Ref, ValueMask, WriteMask}` |
|
||||
| P3 | pipeline | `[784, 800)` | 16 | `StencilStates[0].{FailOp, PassDepthFailOp, PassDepthPassOp}`, `StencilStates[1].Func` |
|
||||
| D4 | dynamic | `[800, 812)` | 12 | `StencilStates[1].{Ref, ValueMask, WriteMask}` |
|
||||
| P4 | pipeline | `[812, 840)` | 28 | `StencilStates[1].{FailOp, PassDepthFailOp, PassDepthPassOp}`, `CullFaceEnabled`, `CullFaceModeSetting`, `FrontFaceModeSetting`, `ProvokingVertexModeSetting` |
|
||||
| D5 | dynamic | `[840, 868)` | 28 | the four hints, `PointFadeThresholdSize`, `PointSpriteCoordOrigin`, `ClampReadColor` |
|
||||
| P5 | pipeline | `[868, 876)` | 8 | `PolygonModeFront`, `PolygonModeBack` |
|
||||
| D6 | dynamic | `[876, 880)` | 4 | `PrimitiveRestartIndex` |
|
||||
| P6 | pipeline | `[880, 904)` | 24 | the 20 capability bools `ColorLogicOpEnabled`…`ProgramPointSizeEnabled`, `ScissorTestEnabledMask` |
|
||||
| D7 | dynamic | `[904, 1168)` | 264 | `ScissorBoxes[16]`, `ScissorBoxWrittenMask`, `ClipDistanceEnabledMask` |
|
||||
|
||||
**7 pipeline chunks totalling 396 bytes; 8 dynamic chunks totalling 772 bytes; 396 + 772 = 1168.** Both counts fit the `Uint32 ChunkMask` of `MGPRenderStateDesc` (`MGPipeTypes.h:215-221`) and `MGPDynamicState` (`:236-241`) with room to spare. `StencilStates` is the one member that straddles, at sub-member granularity, exactly as `scout-render-state.md` §7.2 predicted; **`StencilFaceState` is not reordered** — reordering would move Espryt's shadow bytes for no gain and would invalidate the offsets above.
|
||||
|
||||
Note the two splits are orthogonal and coexist (`ARCHITECTURE.md:188`): Espryt's head `[0,312)` / blend `[312,536)` / tail `[536,1168)` cuts across this table, and D0/P0/D1 all live in Espryt's head while P1 spans Espryt's blend and tail. Nothing about Espryt's spans changes.
|
||||
|
||||
`MGPipeComputePipelineSubsetHash(const RenderStateParameters&)` is `XXH64` over the seven pipeline chunks in ascending order, seeded with a compile-time table version so a chunk-table change invalidates every persisted key. 396 bytes ≈ 49.5 eight-byte words — **[deviation]** the doc estimates "~25-30 字" (`ARCHITECTURE.md:189`), which was the 24 hashed members without padding and without the 15 members added above; the integrator records 396 bytes / 49.5 words in `MEASUREMENTS.md`.
|
||||
|
||||
### D7 — The CsoCache
|
||||
|
||||
`MobileGL/MG_Impl/Pipe/CsoCache.{h,cpp}`, one instance per context, held by the tracker.
|
||||
|
||||
- Storage: `ska::flat_hash_map<Uint64, Uint32>` (hash → cache-entry index) plus a `Vector<Entry>` of at most **64** entries and an intrusive LRU list. `Entry = { Uint64 Hash; MGPipeHandle Cso; Array<Uint8, 396> PipelineBytes; }` — 64 × ~412 B ≈ 26 KB per context.
|
||||
- Capacity **64** (`ROADMAP.md:18`, `ARCHITECTURE.md:63`). `ROADMAP.md:77` says 64 is provisional and the counters retune it; P2 ships 64 and publishes the mint/bind/evict counters that a P13 retune reads.
|
||||
- **[deviation] a hash hit is confirmed with a `memcmp` of the 396 pipeline bytes before the handle is reused.** `ARCHITECTURE.md:63` says content addressing on an xxHash; a bare 64-bit hash equality would let a collision alias two different render states onto one CSO, which is a silent wrong-pixels bug with no gate that can see it. Mesa's `cso_cache` memcmps for the same reason. The memcmp runs only when `m_pipelineStateVersion` moved, i.e. never in the steady state.
|
||||
- Eviction is LRU and emits `DeleteRenderState` (`PipeCalls.def:94`), which frees the applier's slot and bumps its `Gen`.
|
||||
- **The lookup algorithm** (`ARCHITECTURE.md:189` verbatim, implemented):
|
||||
1. `m_pipelineStateVersion` (widened) unchanged → reuse `m_lastCso`, **zero hashing, zero probing**; emit nothing unless `m_version` also moved.
|
||||
2. changed → hash the seven pipeline chunks → probe → **hit**: `memcmp` confirms, emit `MGPBindRenderState` (12 B). **miss**: mint a slot, emit `MGPRenderStateDesc` with the changed chunks (`ChunkMask`; all-ones for a brand-new CSO, else the chunks that differ from `BaseCso`), then the 12-byte bind.
|
||||
3. `m_version` moved but the pipeline subset did not → emit `MGPDynamicState` only.
|
||||
- Counters: `PipeStats::AddCalls(CallClass::RenderStateCsoMints, 1)` and `…CsoBinds, 1)` (two new call classes, D17).
|
||||
|
||||
### D8 — What `set_dynamic_state` carries
|
||||
|
||||
`MGPDynamicState{ ChunkMask, Version, Pad0, Blob }` (`MGPipeTypes.h:236-241`, 32 B) plus a blob that is the concatenation, in ascending chunk index, of the dynamic chunks whose bit is set in `ChunkMask`. `Version` is `m_version` (widened `Uint16`, sent as the raw `Uint16` the wire type declares).
|
||||
|
||||
**Granularity: per chunk, eight bits, chosen by `memcmp` of each dynamic chunk against the tracker's staging copy.** So a `glViewport` sends chunk D0 (264 B), a `glClearColor` sends D2 (168 B), a `glScissor` sends D7 (264 B), a `glStencilMask` on the front face sends D3 (12 B). `ROADMAP.md:77` defers the final granularity to the counters; P2 ships eight chunks and gives `PipeStats::RecordDrawPayloadBytes` (`PipeStats.h:154`, implemented, unit-tested and **called by nothing** today) its first emitter, so the 24-bucket histogram answers the retune question with data. `ARCHITECTURE.md:189`'s "~200 B" estimate is in the right range; the measured per-chunk sizes above go into `MEASUREMENTS.md`.
|
||||
|
||||
The tracker keeps `RenderStateParameters m_staged{}` (value-initialised) as the "what the server has" mirror; a chunk that memcmp-matches is not sent, which is the chunk-level suppressor.
|
||||
|
||||
### D9 — The residual value block, its ratchet and its tripwire
|
||||
|
||||
After P2, `MGPipeTypes.h:516-525` becomes:
|
||||
|
||||
```cpp
|
||||
struct ResidualValueBlock {
|
||||
Uint64 CapabilityBits; // the 35 CapabilityInput bits, packed in enum order
|
||||
};
|
||||
```
|
||||
|
||||
`#define MGL_RESIDUAL_BLOCK_SIZE 8` (down from 1248 — `RenderState` 1168 retires to the CSO, `Pack` 28 to `set_pixel_pack_state`, the patch quintet 52 to `set_patch_state`). The ratchet comment at `MGPipeTypes.h:527-535` stays; the number only ever goes down.
|
||||
|
||||
**The three disciplines (`ARCHITECTURE.md:359`), implemented:**
|
||||
1. **Retirement is a compile error.** The `static_assert(sizeof(ResidualValueBlock) == MGL_RESIDUAL_BLOCK_SIZE, …)` at `:537` is what fires if a field is removed without lowering the number, or added at all.
|
||||
2. **Per-member `offsetof` assertions, and field-wise serialisation under split.** `gen_pipe.py` emits `static_assert(offsetof(ResidualValueBlock, CapabilityBits) == 0);` from `MGP_FIELDS_ResidualValueBlock` (`PipeFields.def:147-148`, which loses five of its six rows).
|
||||
3. **`MOBILEGL_PIPE_STATS` counts its bytes as their own class** — `ByteClass::ResidualValueBlock` (`PipeStats.h:73-75`), the placeholder that "stays at 0 until P2". P2 makes it non-zero (G10).
|
||||
|
||||
**The tripwire.** `CapabilityBits` is now *redundant*: every one of the 35 capabilities is answerable from the working `RenderStateParameters` once D3 closes the three storage holes. That redundancy is the point. `MGPipeApplySetResidualValueState` compares, bit by bit, the block's answer against `MGPipeDeriveRenderStateFields`' answer, and a disagreement is `Fatal{PipeResidualDiverged, "<CapabilityName>"}` in a poison or verify build (counted and logged otherwise). So the day a later call takes a capability over and forgets to carry it, the residual block says so on the next draw. The block is emitted once per context and again whenever the capability set changes.
|
||||
|
||||
### D10 — `set_pixel_pack_state`, `set_patch_state`, `set_vertex_attrib_defaults`
|
||||
|
||||
| call | payload | shutter | emitted when |
|
||||
|---|---|---|---|
|
||||
| `SetPixelPackState` (`PipeCalls.def`, `kCtxState`) | `MGPPixelPackState{ PixelStoreParameters Pack; }`, 28 B (`MGPipeTypes.h:488-496`) | `BitwiseEqual` against the tracker's copy | `NEW_PIXEL_PACK`. Applier writes `PipeInputs::m_pixelStore[0]`. **PACK only** — there is deliberately no unpack counterpart (`ARCHITECTURE.md:107`, `MGPipeTypes.h:485-487`). |
|
||||
| `SetPatchState` | `MGPPatchState{ Vertices, Pad0, Outer[4], Inner[2], Pad1[2] }`, 40 B (`:500-507`) | `BitwiseEqual`, **NaN legal** (`ARCHITECTURE.md:162`: a NaN outer level is a legal `glPatchParameterfv` value and must compare equal to itself) | `NEW_PATCH_STATE`. Applier writes the three members of the working block **and** asserts they match what the pipeline chunk P0 delivered (D6). |
|
||||
| `SetVertexAttribDefaults` (`kVarTail`) | `MGPVertexAttribDefaults{ Mask, Count }`, 8 B (`:479-483`), plus a tail of `Count` `MGPAttribValue`s for the attributes named by `Mask` | `ContentHash` (xxHash over the emitted set) through the set-hash suppressor (D11) | `NEW_VERTEX_ATTRIB_DEFAULTS`. Applier writes `PipeInputs::m_currentVertexAttribute[i]` for the named attributes. |
|
||||
|
||||
`BitwiseEqual` means `std::memcmp` over the value's bytes, which is why D3's `{}` matters for `PixelStoreParameters` (2 padding bytes at offsets 2–3).
|
||||
|
||||
### D11 — The set-hash suppressor skeleton
|
||||
|
||||
`MobileGL/MG_Impl/Pipe/SetHashSuppressor.h` — header-only:
|
||||
|
||||
```cpp
|
||||
// Coalescing rule 4 (ARCHITECTURE.md:198): every kVarTail set_* hashes the RESOLVED set on
|
||||
// the client and does not emit when the hash has not moved. This is the carrier for the
|
||||
// ~175 lines of debounce that move off the backends in P3b/P4b; P2 lands the mechanism and
|
||||
// one real consumer so the shape is pinned by a test rather than by a plan.
|
||||
class SetHashSuppressor {
|
||||
Array<Uint64, kMGPipeSuppressorSlotCount> m_lastEmitted{}; // 0 == "never emitted"
|
||||
public:
|
||||
Bool ShouldEmit(MGPipeSuppressorSlot slot, Uint64 contentHash); // and latches
|
||||
void Invalidate(MGPipeSuppressorSlot slot); // context change, server reset
|
||||
void InvalidateAll();
|
||||
};
|
||||
```
|
||||
|
||||
Slots, one per `kVarTail` `set_*` (`ARCHITECTURE.md:145`): `SetVertexBuffers`, `SetSamplerViews`, `BindSamplerStates`, `SetShaderImages`, `SetShaderBuffers`, `SetStreamOutputTargets`, `SetVertexAttribDefaults`. **P2 wires exactly one — `SetVertexAttribDefaults` — and unit-tests the class on all seven slots.** The other six are P3b/P4b (`ROADMAP.md:23`). A hash of 0 is reserved for "never emitted" so the first emission always goes out (the class remaps a computed 0 to 1).
|
||||
|
||||
### D12 — Magma re-sourced from the CSO and the dynamic payload
|
||||
|
||||
Nothing here is required for correctness — after D2 the working block is byte-identical to what Magma reads today, so an unmodified Magma is already correct under push. Everything in D12 is a **cost** deliverable, which is what makes it safe to land last.
|
||||
|
||||
1. **`GetOrCreatePipeline`'s memo key** (`VulkanRenderer.cpp:4997-5013`): `entry.pipelineStateHash == pipelineStateHash` becomes `entry.renderStateCso == boundCso` (an `MGPipeHandle` compare). The version→hash gate at `:4985-4995` and the three cached-hash fields (`VulkanRenderer.h:855,856,860,861,862`) **are deleted**: the client already did the hashing, and `m_pipelineStateHashValid`/`…Version`/`…ColorCount`/`…SampleCount` existed only to avoid re-hashing. `InvalidatePipelineMemo()` (`:881-885`) keeps clearing the memo and loses the three hash fields.
|
||||
**The render-pass facts stay in the key.** `entry.renderPassHash` already separates draws that differ only in `colorAttachmentCount`/`sampleCount` (correction 4 of the preamble), so collapsing `pipelineStateHash` to the CSO handle loses no discrimination. `ResolveEffectiveSampleMask` (`:4813-4819`) is **not** deleted — it is a *payload* computation that depends on `rasterizationSamples`, and it keeps reading `Multisample`/`SampleMask`/`SampleMaskValue` out of the working block.
|
||||
2. **`ComputePipelineStateHash`** (`:4821-4910`) is retained only under `MOBILEGL_PIPE_LEGACY_MEMOS` and is not called on the new arm. Its 20-line enumeration comment (`:4780-4794`) moves to `MGPipeRenderStateSpans.cpp` as the provenance of the pipeline chunk set, since that is now the contract it was.
|
||||
3. **`ApplyDynamicDrawStateTail`** (`:5902-6004`): the version gate at `:5920-5930` keeps reading `GetRenderStateParametersVersion()` — that value now comes from `MGPDynamicState::Version`, so it moves exactly when a dynamic chunk moved and no longer moves on a pipeline-only change. The `DynamicTailKey` build and compare (`:5944-5982`) stay; the `struct DynamicTailKey` (`:355-395`) and its input inventory (`:341-354`) are already an exact enumeration of the dynamic half and are the cross-check that D6's dynamic chunks are complete — the implementer asserts, in a unit test, that every field `DynamicTailKey` reads lies inside `kMGPipeDynamicChunks` (the two exceptions being `extentX`/`extentY`/`preTransform`/`isDefaultFbo`, which are backend facts, not GL state).
|
||||
4. **Subsystem 4** (Track H): `VertexInputStateFactory::ComputeHash`'s `const Uint64 bufferKey = attr.Buffer ? attr.Buffer->GetLifetimeId() : 0;` (`VertexInputStateFactory.cpp:48`) becomes `bufferHandle.Slot | (Uint64(bufferHandle.Gen) << 32)` — `ARCHITECTURE.md:363`'s "`lifetimeId` → `gen` 混进 server 侧每个 content hash". `VaoDrawMemo` (`VulkanRenderer.h:1244-1264`) drops `vaoKey` (raw pointer) and `vaoLifetimeId` for one `MGPipeHandle vaoHandle`; `LookupVaoDrawMemo` (`:3540-3579`) becomes a direct slot index into a grow-on-demand `Vector` with a `Gen` compare — no Fibonacci mix (`:3547-3548`), no 2-way probe, no frame-serial recycling (`:3564-3577`).
|
||||
5. **The frontend VAO loses its backend pointers.** `VertexArrayObject::{Get,Set}BackendStateMemo` and `m_backendStateMemo{,Epoch,Version}` (`VertexArrayObject.h:121-131`, `:192-194`) are **deleted outright** (`ARCHITECTURE.md:284`), and with them the eviction-epoch dance (`VertexInputStateFactory.cpp:78`, `:318`, `VertexInputStateFactory.h:141`, `s_evictionEpochSource`) — a slot-indexed table has stable entries. `{Get,Set}BackendHashMemo` and `{Get,Set}BackendAuxMemo` (`:106-114`, `:140-150`, storage `:190-191`, `:195-197`) become fields of the slot-indexed `VaoDrawMemo` entry. `SetBackendAuxMemo` has **no live reader** today (verified: its only writer is `VertexInputStateFactory.cpp:83-84`; the values moved into `VaoDrawMemo::layoutHash`/`layoutAuxMasks`, `VulkanRenderer.h:1257-1259`), so it is deleted rather than moved.
|
||||
**Out of scope, do not touch:** `ProgramObject::{Get,Set}BackendHashMemo` (`ProgramObject.h:798-826`, used by `ProgramFactory.cpp:3446-3448`), and `SetupDrawSnapshot`'s wider re-key (`VulkanRenderer.h:958-979`) beyond replacing its `vao`/`vaoLifetimeId` pair with the handle.
|
||||
|
||||
### D13 — Espryt 0b: what the first Track H slice replaces and what it must not break
|
||||
|
||||
**New**: `MobileGL/MG_Impl/Pipe/SlotAllocator.{h,cpp}` (client side, in the contract commit because Magma needs it too) and `MobileGL/MG_Backend/DirectGLES/SlotTables.h` (per-kind dense twin arrays).
|
||||
|
||||
`SlotAllocator` obeys `MGPipeHandles.h` exactly: per-`MGPipeKind` free list + high-water mark, first allocatable slot `kMGPipeFirstAllocatableSlot = 1` (`:81`), **`Gen` bumps only on slot reuse, never on respecify** (`:44-48`), a `MOBILEGL_ASSERT` on `Gen` wrap in a debug allocator, and a client-side `lifetimeId → slot` map per kind (`ARCHITECTURE.md:40`) so `GetLifetimeId()` stays the client's identity and a GL name never enters a key.
|
||||
|
||||
**Replaced / deleted** (all in `MG_Backend/DirectGLES/`):
|
||||
|
||||
| what | where | replacement |
|
||||
|---|---|---|
|
||||
| the six `StateBackendObjectRegistry` instances | `Managers.h:271-400`; instances at `Managers.h:803,1124,1215,1733,1833,1860`, definitions `Managers.cpp:2747,5075,5828,6139,8657,8769` | per-kind dense arrays indexed by `MGPipeHandle::Slot`, `Gen`-validated |
|
||||
| `Find`'s erase-on-expiry and the "a reference dies on the next call" hazard | `Managers.h:326-349` | O(1) indexed read; **`SyncTextureObjectToBackend`'s by-value copy and second `Find` (`DirectGLES.cpp:1310-1345`) are deleted in the same change**, not left as harmless |
|
||||
| `CollectGarbage` / `CollectGarbageIfNeeded` (7 call sites: `DirectGLES.cpp:1223,1533,1898,1899,1900,2728,2729`) | `Managers.h:356-391` | explicit destroy: `MarkXForDeletion` on the frontend emits `delete_*`, and the applier frees the slot |
|
||||
| `OwnerEquals` and the three `TwinLookupMemo`s | `DirectGLES.cpp:63-66`, `:83-132`; use sites `:1206,1214,2769,2777,2874,2879` | direct slot indexing — the memo existed only to avoid the hash probe |
|
||||
| `UnitSamplerLookupMemo`'s `WeakPtr` test | `DirectGLES.cpp:3157-3177` | `{slot, gen}` compare; the "a miss is never cached" contract (`:3148-3156`) survives verbatim |
|
||||
| `g_fbSlotCache` / `GetFramebufferBindingSlotFast` and its five callers (`:1613, 1907, 2745, 2860, 2935`) | `DirectGLES.cpp:134-157` | an ordinary `MGB_CTX->GetFramebufferBindingSlot(target)` read of pushed state. **This closes the P1 poison bypass** (`scout-track-h.md` §1.6): the fast getter ran the checked accessor once per context change and then handed out a raw pointer forever, so the per-verb poison stamp and the verify read-hook were skipped at those five sites. |
|
||||
| the four `pDefaultFramebufferInfo->defaultFBO` identity compares (`:1939, 2874, 2898, 6420`) | | `handle == kMGPipeDefaultFramebuffer` (`MGPipeHandles.h:71`) |
|
||||
|
||||
**Must not break** (each gets a named assertion or an existing test):
|
||||
|
||||
- `EnsureProcessTeardownSentinel()` (`Managers.h:59-60`, `Managers.cpp:161-170`) is armed by the first twin creation, today from `GetOrCreate` (`Managers.h:295`). The arming site moves to the slot table's first insertion. A registry destructor hook is **wrong** and the comment at `Managers.h:52-57` says why.
|
||||
- The twin destructors' `g_backendContextGeneration` compare (`Managers.h:64-70`) so a twin outliving its ES context does not `glDelete*` a recycled name. Pinned by `SanityTest.cpp:2650-2665, 2765-2773, 2786-2790`.
|
||||
- The whole-registry save / reset / restore fixture `ScopedDirectGLESTextureBindings` (`SanityTest.cpp:145-197`, `:160,164,178,195`) must keep working — the slot table needs the same copy-assign-and-restore shape.
|
||||
- The one direct-iteration site, `ScopedDetachedTextureFramebufferAttachments`' scan over all framebuffer twins (`DirectGLES.cpp:6413-6425`), needs a "which slots are live" bit per kind.
|
||||
- `UnitBindingsSnapshot` / `CaptureUnitBindings` / `UnitBindingsUnchanged` (`DirectGLES.cpp:1366-1400`) **stays on the backend** — moving that debounce to the client is P3b/P4b (`ROADMAP.md:23`) — but its two `OwnerEquals` calls (`:1392`, `:1394`) become `{slot, gen}` compares.
|
||||
- `g_attachmentBackendIdGeneration` (`DirectGLES.cpp:1891`), `BufferImpl::g_bufferBackendIdGeneration` (`Managers.h:800`) and `InProcessTeardown()` are *driver-object* epochs, not identity, and survive untouched.
|
||||
- Purity gate C: `grep -rc pGLContext MobileGL/MG_Backend` stays empty. The `g_fbSlotCache` rewrite is the one place tempted to break it.
|
||||
|
||||
**Explicit destroy.** Today nothing tells the backend an object died except buffers (`BufferBackendOps::OnDestroy`, `BufferObject.h:103`, fired from `BufferObject.cpp:39-41`); `Managers.h:306-314` quantifies the resulting dead gigabytes. P2 adds the death notification for the six kinds by emitting `delete_*` from the frontend's `Mark*ForDeletion` path (`Core.cpp:116-140, 167-169, 279-307, 346-352, 1188-1190, 1213-1225, 1252-1254`) when the object's last `SharedPtr` drops — **not** when the name is marked, because a still-bound object keeps living (`TextureState.cpp:118-155`). The hook follows `BufferBackendOps`' shape.
|
||||
|
||||
### D14 — `MOBILEGL_PIPE_LEGACY_MEMOS`: the compile-time arm and the runtime selector
|
||||
|
||||
`ARCHITECTURE.md:367` is right that after phase C the `MOBILEGL_PIPE_PUSH` bitmap alone is not a valid A/B, because with a bit clear the backend still runs the re-keyed memo code. So:
|
||||
|
||||
| switch | kind | default | meaning |
|
||||
|---|---|---|---|
|
||||
| `MOBILEGL_PIPE_LEGACY_MEMOS` | **new CMake `option()`** + `-DMOBILEGL_PIPE_LEGACY_MEMOS=1` | **ON** | compiles the pre-handle arm (the six registries, `OwnerEquals`, the three `TwinLookupMemo`s, `g_fbSlotCache`, `ComputePipelineStateHash`, the address-keyed `VaoDrawMemo`) alongside the handle arm, both behind the same `PipeInputs` interface. Forced ON with a `message(STATUS)` when `MOBILEGL_PIPE_PUSH=OFF`, where it is the only arm. |
|
||||
| `MOBILEGL_PIPE_LEGACY_MEMOS` | runtime, `Features.PipeLegacyMemos` (`Config.h:356-360`, `ConfigLoader.cpp:258-259`) — **already exists**, tri-state, only an explicitly falsy value turns it off | true | true: a Track-H subsystem whose bitmask bit is clear falls back to the legacy arm. false: the legacy arm is never entered, and a Track-H subsystem whose bit is clear is a startup `Fatal{PipeLegacyMemosDisabled}`. This is the lever `HandleRecycleScenario`'s arms use. |
|
||||
| `MOBILEGL_PIPE_PUSH` | runtime `Uint64` bitmask, `Features.PipePush` (`Config.h:319-326`, `ConfigLoader.cpp:245`) — **first consumed in P2** | see below | per-subsystem selector. |
|
||||
|
||||
**The subsystem bit enum** (new, `MobileGL/MG_Pipe/MGPipe.h`, next to the call-class enum at `:31`):
|
||||
|
||||
```cpp
|
||||
inline constexpr Uint64 kMGPipeSubsystemRenderState = 1ull << 0;
|
||||
inline constexpr Uint64 kMGPipeSubsystemPixelPack = 1ull << 1;
|
||||
inline constexpr Uint64 kMGPipeSubsystemPatchState = 1ull << 2;
|
||||
inline constexpr Uint64 kMGPipeSubsystemVertexAttribDefaults = 1ull << 3;
|
||||
inline constexpr Uint64 kMGPipeSubsystemResidualValues = 1ull << 4;
|
||||
inline constexpr Uint64 kMGPipeSubsystemEsprytSlots = 1ull << 5; // Espryt 0b
|
||||
inline constexpr Uint64 kMGPipeSubsystemMagmaVertexInput = 1ull << 6; // Magma subsystem 4
|
||||
// bits 7..62 reserved for the later phases, allocated in ROADMAP order.
|
||||
// NOT a subsystem, a BEHAVIOUR: turn OFF client-side content addressing of CSOs, so every
|
||||
// pipeline-version change mints a fresh CSO and the map is never probed. This is the
|
||||
// negative control the CSO design is measured against (ROADMAP.md:18, ARCHITECTURE.md:367).
|
||||
inline constexpr Uint64 kMGPipeBehaviourNoCsoContentAddressing = 1ull << 63;
|
||||
inline constexpr Uint64 kMGPipeSubsystemsMigratedAtP2 = 0x7full; // bits 0..6
|
||||
```
|
||||
|
||||
**Default.** `Config.h:322-323` documents `0` as "pull everything", and that stays literally true. `ConfigLoader.cpp:245` becomes, under `#if MOBILEGL_PIPE_PUSH`, `QueryEnvUint64("MOBILEGL_PIPE_PUSH", kMGPipeSubsystemsMigratedAtP2)` and, in the pull build, keeps its `0` (where it is meaningless). So a push build with the knob unset runs every migrated subsystem, and `MOBILEGL_PIPE_PUSH=0` in the environment is the all-subsystems-pull control that reproduces P1's behaviour exactly. `QueryEnvUint64`'s decimal/`0x` contract (`ConfigLoader.cpp:167-192`) is unchanged; the Config.h comment gains the bit list because operators pass it as hex.
|
||||
|
||||
### D15 — How the pull build stays symbol-identical
|
||||
|
||||
Every P2 artefact lands in one of four places, and none of them touches the pull build:
|
||||
|
||||
1. **New sources compiled only under `MOBILEGL_PIPE_PUSH`**, appended inside the existing `if (MOBILEGL_PIPE_PUSH)` block (`CMakeLists.txt:462-468`): `MG_Pipe/MGPipeRenderStateSpans.cpp`, `MG_Pipe/PipeApply.cpp`, `MG_Impl/Pipe/{Tracker,CsoCache,SlotAllocator}.cpp`. `generated/PipeSpanTable.inc:66-67`'s two `extern` declarations cost the pull build nothing (a declaration emits no symbol).
|
||||
2. **`#if MOBILEGL_PIPE_PUSH` arms inside existing backend files** for the Track H re-keys, with the legacy arm under `#if MOBILEGL_PIPE_LEGACY_MEMOS` (D14). In the pull build only the legacy arm is compiled and it is textually today's code.
|
||||
3. **`MGP_NOTE_AGGREGATE` and the five aggregate generations** in `MG_State`, guarded the same way, so the pull build's state objects do not change size (D4).
|
||||
4. **Three new members in `RenderStateParameters` plus three `SET_CAPABILITY`/`RETURN_CAPABILITY` arms plus three `{}`**, which *are* in the pull build. This is the one deliberate exception, and it is bounded: the members fit an existing padding hole so no offset and no `sizeof` moves; the switch arms grow two functions; the `{}` grows one constructor. **G1 therefore admits exactly the resizes of `RenderState::SetCapability`, `RenderState::IsCapabilityEnabled` and `RenderState::RenderState()`, named in the commit message, and zero added/removed/renamed symbols.**
|
||||
|
||||
The check after every merge is `symbol_report.py --threshold 0`; anything outside that named set is a defect, not a rounding error.
|
||||
|
||||
### D16 — The dirty-surface mapping file and its gate
|
||||
|
||||
**New file `MobileGL/MG_Pipe/DirtySurface.def`**, one row per distinct mutator the scanner finds (73 today):
|
||||
|
||||
```
|
||||
// X(Mutator, Answer) - what publishes this frontend mutation to the backend.
|
||||
// Answer is one of the MGPipeDirty bit names, or:
|
||||
// kImmediate - the mutating function also reaches the backend in the same body, so the
|
||||
// mutation is published inline and needs no aggregate generation
|
||||
// kReverseChannel - not state: a write INTO the frontend from the backend's side (RecordError)
|
||||
// kNoBackendRead - no backend read point observes this state at all (with the read-point
|
||||
// inventory row that proves it)
|
||||
#define MGP_DIRTY_SURFACE_LIST(X) \
|
||||
X(RecordError, kReverseChannel) \
|
||||
X(SetActiveTextureUnit, kImmediate) \
|
||||
X(SetPatchVertices, kImmediate) \
|
||||
X(SetBlendColor, NEW_RENDER_STATE) \
|
||||
X(SetCapability, NEW_PIPELINE_STATE) \
|
||||
...
|
||||
```
|
||||
|
||||
`scripts/gen_pipe_dirty_surface.py` grows:
|
||||
- `--check`: parse `DirtySurface.def`, and exit 1 if any scanned mutator has no row, or any row names a mutator the scan no longer finds. Both directions, so a deleted mutator leaves no stale row.
|
||||
- `--self-test`: two canned negative controls (a mutator withheld from the def, a row naming a nonexistent mutator), each of which must trip; `trips == 0` is an error — the shape `check_include_closure.py:541-543` and `gen_pipe.py --self-test` already use.
|
||||
- the human report writes the mapped answer instead of `UNMAPPED`, and the summary line is regenerated into `docs/Disaggregated/MEASUREMENTS.md`'s §5 by the integrator.
|
||||
|
||||
`RecordError` is **exempted explicitly by a row**, not by a filter: it is 836 of the 926 calls (90 % of the surface) and it is a reverse channel (`Coverage.def:99`, `PipeInputs.h:574`). That leaves 72 real mutators over 90 real calls.
|
||||
|
||||
The scanner's three self-declared blind spots (`gen_pipe_dirty_surface.py:195-197` and its scan root) are recorded in the def's header comment as known gaps: a mutator inside a lambda is attributed to the enclosing function; a mutation published through a helper the entry point calls reads as deferred; and the scan root is `MG_Impl/GLImpl` only, so the four `MGP_NOTE_MUTATION` sites in `MG_State/GLState/TextureState/TextureState.h:85,98,111,133` are outside it entirely.
|
||||
|
||||
CI: `.github/workflows/test.yml:1524-1528` loses its "Informational" comment and becomes `python3 scripts/gen_pipe_dirty_surface.py --check && python3 scripts/gen_pipe_dirty_surface.py --self-test`. Cost: the `pipe-gates` job runs in ~10 s and has no build dependency (`test.yml:1480-1481`); this adds nothing measurable.
|
||||
|
||||
### D17 — Counters, and the rule against hot-path instrumentation
|
||||
|
||||
`ROADMAP.md:7` forbids committing hot-path instrumentation. **The tracker gets no timer.** The absolute-ns number comes from `DriverBench`'s `ns_per_op` (D.4), which times whole frames from outside the library.
|
||||
|
||||
Two new `CallClass` values only — `RenderStateCsoMints` and `RenderStateCsoBinds` — with short names `csom` / `csob`, added in the contract commit together with the `PipeStatsTest.cpp:260 CounterNamesAreStable` update that pins them. Everything else P2 needs already exists:
|
||||
|
||||
- `ByteClass::ResidualValueBlock` (`PipeStats.h:73-75`) — the placeholder P2 makes non-zero.
|
||||
- `RecordDrawPayloadBytes` + the 24-bucket histogram (`PipeStats.h:129,154`) — implemented, unit-tested, **called by nothing**; the tracker becomes its first emitter, one call per emitted draw payload.
|
||||
- the six memo gates (`PipeStats.h:107-122`) — unchanged names, and they are the honest reading of the before/after (`PipeStats.cpp:93-99`).
|
||||
- `CallClass::AccessorCalls` — **a warning for the report**: it is a set of static tallies at ~10 hot entry points (`PipeStats.cpp:76-88`), so a tracker that *relocates* reads out of those functions scores a lower `acc/draw` without having removed any work. P2's report must therefore lead with the gate hit/miss pairs and the CPU-time series, and quote `acc/draw` only alongside a re-audit of the tally constants (`DirectGLES.cpp:1421,1524,2043,2053,2977`; `VulkanRenderer.cpp:5009,5016,5274,5927,5934,6416,6449,6462`).
|
||||
|
||||
Every counting site keeps the `if (PipeStats::Enabled())` shape (`PipeStats.h:29`) so an off build pays one predicted branch.
|
||||
|
||||
### D18 — `HandleRecycleScenario`, and how it goes red before the re-key
|
||||
|
||||
New `MobileGL/MG_IntegrationTest/Scenarios/HandleRecycleScenario.cpp`, registered in `MG_IntegrationTest/CMakeLists.txt` (source list from `:55`), following `PipeVerifyArmingScenario` / `PoisonOmissionScenario` as the template for an always-on negative control (`CMakeLists.txt:700-725`).
|
||||
|
||||
**What it reproduces**, through public GL only: delete a VAO that a backend memo slot holds; immediately create a replacement the allocator is very likely to place at the same heap address (the `void* volatile` sink trick from `MG_Test/State/ObjectLifetimeIdTest.cpp:44`) **and** give it a byte-identical attribute configuration so the content hash matches too; bind a *different* buffer to it; draw; read back and assert the pixels come from the new buffer (the red/green quad readback of `Scenarios/CrossFrameBufferScenario.cpp`). The same shape is then repeated for a texture (against `g_backendTextureObjects`) and a framebuffer.
|
||||
|
||||
**Three ctest arms**, all always-on:
|
||||
|
||||
| arm | environment | expected |
|
||||
|---|---|---|
|
||||
| `…HandleRecycleScenario.Handles` | `MOBILEGL_PIPE_PUSH` default (bits 5 and 6 set), `MOBILEGL_PIPE_LEGACY_MEMOS=0` | **green** — the `{slot, gen}` key cannot alias |
|
||||
| `…HandleRecycleScenario.Legacy` | `MOBILEGL_PIPE_PUSH=0`, legacy arm | **green** — today's `lifetimeId` + `weak_ptr` guards work |
|
||||
| `…HandleRecycleScenario.AbaControl` | `MOBILEGL_PIPE_PUSH=0` **and** `MOBILEGL_PIPE_HANDLE_ABA_CONTROL=1` | **green by asserting the corruption** — the knob makes `VertexInputStateFactory::ComputeHash` hash `attr.Buffer.get()` instead of `GetLifetimeId()` and makes `LookupVaoDrawMemo` skip the `vaoLifetimeId` compare, i.e. reverts exactly the two guards the re-key replaces; the scenario asserts the *wrong* pixels, so if the scenario ever stops reproducing the ABA it fails |
|
||||
|
||||
`MOBILEGL_PIPE_HANDLE_ABA_CONTROL` is a new `Bool Features.PipeHandleAbaControl` under `#if MOBILEGL_PIPE_PUSH` (so it cannot exist in a shipping pull build), parsed with `QueryEnvFlag`, documented next to `MOBILEGL_PIPE_VERIFY_CORRUPT` as negative control C. That third arm is what makes "`HandleRecycleScenario` 绿且重键前红" (`ROADMAP.md:18`) an always-on CI fact instead of a one-off manual demonstration.
|
||||
|
||||
### D19 — G7: the setter-consistency test and its negative control
|
||||
|
||||
`MobileGL/MG_Test/Pipe/RenderStateSpansTest.cpp` (contract commit creates it; package A fills it):
|
||||
|
||||
- `ChunkTablePartitionsTheBlock` — the sorted/non-overlapping/complete assertion is a `static_assert` in `MGPipeRenderStateSpans.cpp`; the test re-asserts it at run time so a reader sees it, and additionally asserts `kMGPipePipelineChunks` covers every member named in `kMGPipePipelineStateMembers` (`generated/PipeSpanTable.inc:34-59`).
|
||||
- `SetterConsistency` — the G7 test. Drive **every public setter** of `RenderState` (the 25 Group-A setters and 22 Group-B setters catalogued in `scout-render-state.md` §2.1–2.4, plus `SetPixelStoreParam`, which must move neither counter), each with a value that differs from the current one, and assert `MGPipeComputePipelineSubsetHash` moved **⟺** `GetPipelineStateVersion()` moved. Special cases the test must drive individually, or it does not test what it claims:
|
||||
- `SetStencilFunc` **twice**: once changing only `Ref` (version moves, hash must not — `RenderState.cpp:629-642`, the `++m_pipelineStateVersion` at `:641` is conditional on `Func` moving at `:636`), once changing `Func` (both move).
|
||||
- `SetPolygonMode` with only the back face changing (both move: `PolygonModeBack` is in P5).
|
||||
- `SetCapability(ClipDistance0..7)` (`RenderState.cpp:360-380`): version moves, pipeline version does **not**, hash must not.
|
||||
- All 25 `SET_CAPABILITY` names including D3's three new ones.
|
||||
- `SetScissorBox` including the `ScissorBoxWrittenMask` transition (`:918-941`).
|
||||
- `DerivationMatchesTheFrontendGetters` — D5's 29 derived values against `GLContext`'s getters after each setter.
|
||||
- `DynamicChunksCoverMagmasDynamicTailKey` — every field `DynamicTailKey` (`VulkanRenderer.cpp:341-395`) reads is inside `kMGPipeDynamicChunks`.
|
||||
|
||||
**The negative control (G7 in the gate list, `scripts/g7_negative_control.sh`)**: move `ColorMasks` out of chunk P1 into a new dynamic chunk. The partition stays complete so it still compiles; `SetColorMask` then bumps `m_pipelineStateVersion` without moving the hash and `SetterConsistency` fails naming `SetColorMask`. The script patches, builds, expects a non-zero `ctest` rc, and reverts. It is run by the integrator at D.3 and is not a CI lane (it rebuilds the library).
|
||||
|
||||
### D20 — Naming, layering and generated-file discipline
|
||||
|
||||
- New namespaces: none. Everything is `MobileGL::MG_Pipe`.
|
||||
- `MG_Pipe/PipeApply.h` forward-declares only; `PipeApply.cpp` may include `MG_State/GLState/RenderState/RenderState.h` (a `.cpp` in the shared directory, no cycle: `RenderState.h` includes `MGPipeValueTypes.h`, not `PipeApply.h`). Run `python3 scripts/check_include_closure.py` after adding it; if it objects, the file moves to `MG_Impl/Pipe/` (the client side is unrestricted) and nothing else changes.
|
||||
- `PipeCalls.def` is **not** edited: every call P2 emits already has an opcode (`:92-94` `CreateRenderState`/`BindRenderState`/`DeleteRenderState`, `:106` `SetDynamicState`, `:125` `SetResidualValueState`, plus `SetPixelPackState`/`SetPatchState`/`SetVertexAttribDefaults`). Opcodes are file positions, so new calls may only be appended and retired calls keep their slot (`ARCHITECTURE.md:75`); `MGP_CALL_LIST_DOCUMENTED_COUNT = 71` stays pinned by `PipeCatalogueTest.cpp`.
|
||||
- Generated files are regenerated and committed; CI diffs them (`test.yml:1492-1495`).
|
||||
- Commit messages: single-line `[Type] (Scope): description`. Never add `Co-Authored-By` or any other attribution line.
|
||||
- Logging: `MGLOG_D` for anything non-critical; `MGLOG_I` only where `PipeStats.cpp:225-229` already justifies it. No stdio anywhere under `MG_Backend`/`MG_State` (the `pipe-gates` grep, `test.yml:1515-1522`).
|
||||
@@ -0,0 +1,707 @@
|
||||
# P2 implementation brief — the frontend state tracker, render state as a CSO + dynamic state, the residual value block, and the first Track H slice
|
||||
|
||||
Tree: `feat/disaggregated @ 48268068` (worktree `C:/Users/geekerwan/AndroidStudioProjects/FoldCraftLauncher/MobileGL-disagg`). **This is the P2 base ref.** The scouts were written at `e7a6a72f`; the one commit since is CI-only (`48268068 [CI] (Workflows): run the test and apk lanes on every push to feat/disaggregated`, `.github/workflows/{apk,test}.yml`, +8 lines), so every scout `file:line` still holds and P2 branches from `48268068`.
|
||||
|
||||
WSL: `~/w7/pipe` is a worktree of the same repo on `feat/disaggregated`; `~/w7/base` is `dev@81b17c0b` (the performance anchor, untouched). Tree creation is `scratchpad/wf4/wsl_p1_tree.sh <slug> <base-ref> [verify]` with `p1`→`p2` throughout (it creates `~/w7/p2-<slug>` on branch `p2/<slug>`, initialises submodules, copies `3rdparty/glslang/External` and the trace fixtures, then configures and builds `build-linux` (pull), `build-push`, and with a third argument `verify` also `build-verify`). The device-lock loop is `scratchpad/wf2/stats_baseline.sh:16-29` verbatim (mkdir lock under `.../8ab6b3cb-.../scratchpad/w7/locks/<serial>`, 1500 s acquire timeout, 20 s poll, one hold per run, `rm -rf` after).
|
||||
|
||||
Every `file:line` below was re-opened at `48268068`. Corrections to the scouts are **[correction]**; deliberate departures from the design documents are **[deviation]** and carry their reason.
|
||||
|
||||
**Scout verification summary.** All five scouts were read in full and their load-bearing claims re-opened. The following are wrong or incomplete and are fixed here:
|
||||
|
||||
1. **[correction] Three capabilities have no storage, not two.** `RenderState::SetCapability`'s `default: // not supported currently` arm (`MobileGL/MG_State/GLState/RenderState/RenderState.cpp:381-382`) and `IsCapabilityEnabled`'s `default: return false;` (`:429-430`) swallow `DepthClamp`, `FramebufferSrgb` **and `TextureCubeMapSeamless`** — the last one is reachable from `glEnable` (`MG_Util/Converters/GLToMG/RenderStateEnumConverter.cpp:301` maps `GL_TEXTURE_CUBE_MAP_SEAMLESS` onto `CapabilityInput::TextureCubeMapSeamless`, `MGPipeValueTypes.h:202`) and has zero read points anywhere. `scout-render-state.md` §1.3, `generated/PipeSpanTable.inc:24-26`, `ROADMAP.md:78` and `MEASUREMENTS.md:84` all name only two. D8 gives all three real storage.
|
||||
2. **[correction] The free padding hole is exactly 3 bytes at `[581, 584)`**, between `ColorMasks` (offset 549, size 32, align 1) and `ClearColor` (offset 584, align 4). `scout-render-state.md:143-151` gropes at this and half-retracts it. It is verified from the declarations: `using Bool = bool` (`MG_Util/Types.h:33`), `BoolVec4 = Vec4<Bool>` = `VecBase<…, Bool, 4>` whose only member is `Array<Bool,4>` (`MG_Util/Math/VectorTypes.h:16-18`, alias `:222`) → align 1, size 4. Three bytes is exactly enough for the three new capability bools, so `sizeof(RenderStateParameters)` stays 1168 and **no existing member's offset moves** — which is what keeps Espryt's `kBlendSpanBegin`/`kBlendSpanEnd` (312/536) and the whole hand-derived offset table valid.
|
||||
3. **[correction] `RenderState`'s three value members are not value-initialised.** `RenderStateParameters m_parameters;` (`RenderState.h:172`) and the two `PixelStoreParameters` (`:175-176`) have no `{}`, so their padding bytes are indeterminate. A byte-range content hash over them (which is what the CSO key is) would then be stable only within one context. D3 adds `{}` to all three and pays for it with one attributed `.text` resize.
|
||||
4. **[correction] `ComputePipelineStateHash` is not a pure function of `RenderStateParameters`.** Its signature is `(Uint32 colorAttachmentCount, VkSampleCountFlagBits rasterizationSamples)` (`VulkanRenderer.cpp:4821-4822`) and it folds `ResolveEffectiveSampleMask` (`:4813-4819`, itself reading `Multisample`, `SampleMask` and `SampleMaskValue`). The scouts list the hashed fields but not that the signature makes the hash render-pass-dependent. Consequence, and it is load-bearing: a render-state CSO handle **cannot** replace `pipelineStateHash` on its own; the render-pass facts must stay in the memo key. D12 keeps `renderPassHash` as a separate key component, which already separates them.
|
||||
5. **[correction] `ARCHITECTURE.md:504` names `tools/bench.sh`; the script is `tools/device_bench/bench.sh`** (verified: `tools/device_bench/{README.md,bench.sh,profile.sh,session.sh,devices/odinlite.env}`). The integrator fixes the citation.
|
||||
6. **[correction] The eight/nine validate-entry disagreement resolves to nine.** `ARCHITECTURE.md:153` names eight; the landed `MGP_FILL_CLASS_LIST` has nine (`MG_Pipe/FillPoints.def:107-108`, with the reason in its own comment). P2 adopts nine and the integrator corrects the doc (D5).
|
||||
7. **[correction] The dirty-surface gate is not a gate yet.** `ARCHITECTURE.md:172` and `:568` say "P1 起成为门"; `.github/workflows/test.yml:1524-1528` says it stays informational and becomes a gate in P2. The workflow is what runs. P2 promotes it (D16).
|
||||
8. **Confirmed at `48268068`, unchanged from the scouts**: `python3 scripts/gen_pipe_dirty_surface.py --summary` still prints `41 files / 926 mutator calls / 73 distinct mutators / 92 in 36 IMMEDIATE PUBLISH POINTS across 7 distinct mutators / 834 DEFERRED`. `sizeof(RenderStateParameters)==1168`, `PerBufferBlendState`/`StencilFaceState`/`PixelStoreParameters` all 28 (`MGPipeValueTypes.h:536-544`). `StencilFaceState` is `Func(0) Ref(4) ValueMask(8) WriteMask(12) FailOp(16) PassDepthFailOp(20) PassDepthPassOp(24)` (`:229-237`) — so the pipeline half of a face is `[0,4) ∪ [16,28)` and the dynamic half `[4,16)`, exactly as `scout-render-state.md` §7.2 says. `ResidualValueBlock` is 1248 = 1168 + 28 + pad + 8 + 4 + 4 + 16 + 8 + 8 (`MGPipeTypes.h:516-537`). `kMGPipePipelineStateMembers[]` is 24 names (`generated/PipeSpanTable.inc:34-60`), `kMGPipePipelineChunks`/`kMGPipeDynamicChunks` are declared and never defined (`:66-67`). `VertexArrayObject`'s three backend memo triples are at `VertexArrayObject.h:106-150`, storage `:190-197`, and `SetBackendAuxMemo` has no live reader (only writer `VertexInputStateFactory.cpp:83-84`). `MGP_FILL(Verb)` expands to `MGPipeFillForVerb(MGPipeVerb::Verb)` (`MG_Impl/Pipe/PipeFill.h:52`) and `((void)0)` in the pull build (`:54`).
|
||||
9. **[correction] `scout-render-state.md` §6.4 under-counts the residual ratchet.** It says landing the render-state CSO takes 1248 → 80. P2 also lands `set_pixel_pack_state` and `set_patch_state`, so the ratchet is **1248 → 8** (D9).
|
||||
|
||||
---
|
||||
|
||||
## A. Goal and acceptance gate
|
||||
|
||||
`docs/Disaggregated/ROADMAP.md:18`, verbatim:
|
||||
|
||||
> | **P2** 渲染状态 CSO + 第一片 Track H + 残余值块 | 18–26 | `MG_Impl/Pipe/Tracker`(dirty 位、5 个聚合世代、抑制器骨架);`gen_pipe_dirty_surface.py` 首轮映射成门;`MGPipeRenderStateSpans` + G7 setter 一致性测试;`CsoCache`(64 项,键 = pipeline 子集);`create/bind_render_state` + `set_dynamic_state`(Espryt `SyncRenderState` 一行不动;Magma `ComputePipelineStateHash`/`GetOrCreatePipeline`/`ApplyDynamicDrawStateTail` 改从 CSO 与动态 payload 取);`set_pixel_pack_state`、`set_patch_state`、`set_vertex_attrib_defaults`;`set_residual_value_state` + `ResidualValueBlock` 绊线;**第一片 Track H**:Espryt 0b(`SlotAllocator` + 6 个 registry → slot 数组 + 删 `TwinLookupMemo`×3/`OwnerEquals`/`g_fbSlotCache`/GC)与 Magma 子系统 4(`VertexInputStateFactory`/`VaoDrawMemo` 重键,删前端 VAO 里的后端裸指针);`MOBILEGL_PIPE_LEGACY_MEMOS`;补 `FramebufferSrgb`/`DepthClamp` 存储 | 集成 × 2 后端 × {pull, push} 逐名相同;40 trace push 下 SSIM ≥ 0.99 双后端;verify 零分歧;`HandleRecycleScenario` 绿且重键前红;G7 测试绿且拿掉一个字段能红;两台设备配对逐线程 CPU p50/p99 不差且 tracker 绝对 ns 在上限内;Blaze3D blend-toggle 微基准;CSO 内容寻址关闭的负面对照 | P1 |
|
||||
|
||||
Binding context: `ARCHITECTURE.md:147-155` (§5.1 — push happens at validate, before the verb, never in the GL setter, because Blaze3D brackets every batch with `glEnable/glDisable(GL_BLEND)`; only `BufferBackendOps`' seven hooks push at GL-call time), `:157-174` (§5.2 — the dirty-bit table, the five aggregate generations, wrap-around widened at the tracker boundary), `:176-190` (§5.3 — D-B1: whole blob on the wire, CSO identity = the pipeline subset only, the dynamic subset enumerated, the split written in exactly one place, `SyncRenderState` untouched, the client value-fetch order, the `FramebufferSrgb`/`DepthClamp` hole), `:192-200` (§5.4 — the D-B3 validation invariant and the four coalescing rules), `:357-359` (§9.4 — the residual value block and its three disciplines), `:363` (§9.5 — the 21-memo census the Track H slice pays into), `:365-369` (§9.6 — why `MOBILEGL_PIPE_LEGACY_MEMOS` must be a compile-time arm), `:497-507` (§13.2 — the five-part validation gate), `:552` (`MG_Impl/Pipe/` is where `Tracker`, `SlotAllocator`, `CsoCache` land), `:576-597` (the switch tables). `ROADMAP.md:7`: **每个门必须能因它存在的理由变红**; ALL must build; no hot-path instrumentation may be committed; Windows is not a correctness gate; device comparisons are reboot-clean, same-thermal-window, paired A/B. `ROADMAP.md:39`: **day 43 is the GO/NO-GO.** `ROADMAP.md:42-58` is the checklist and the verdict criteria; items 2–7 of it are P2's to produce.
|
||||
|
||||
Decoded into checkable statements. Unless a row says otherwise, commands run in a P2 WSL worktree; `$BASE` = `48268068`.
|
||||
|
||||
| # | statement | the exact command that checks it |
|
||||
|---|---|---|
|
||||
| **G1** | The **pull build** (`MOBILEGL_PIPE_PUSH=OFF`, `MOBILEGL_PIPE_VERIFY=OFF`, Release/INFO) has an identical `nm --defined-only` symbol set before and after P2 — 0 added, 0 removed, 0 renamed — and the only `.text` resize is `MG_State::GLState::RenderState::RenderState()` (D3's three `{}`), named in the commit message. | `python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --json` → `added==removed==renamed==0`; `resized` is empty or exactly the one mangled `RenderState::RenderState()` symbol. |
|
||||
| **G2** | `ctest -L integration-gpu` is **name-for-name identical between the pull and the push build**, on both backends, and green in both. | `for d in build-linux build-push; do ctest --test-dir $d -N \| grep -E '^\s+Test #' \| sed 's/^ *Test *#[0-9]*: //' \| sort > ~/w7/p2-names-$d.txt; done; diff ~/w7/p2-names-build-linux.txt ~/w7/p2-names-build-push.txt` → empty; then `ctest --test-dir build-linux -L integration-gpu --no-tests=error -j 4` and the same on `build-push`, both green. |
|
||||
| **G3** | The 40-trace corpus replays **under push** with SSIM ≥ 0.99 on both backends (79 desktop cases: 40 × 2 minus `iterationrp × DirectGLES`). | `python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-push/libMobileGL.so --out ~/w7/retrace-out/p2-push -j 4 --ssim 0.99` (the P0.5/P1 script, `scratchpad/wf2/retrace_gate.py`). |
|
||||
| **G4** | The **verify** build shows zero divergence: no `Fatal{PipeVerifyDiffer`, no `Fatal{UnmigratedPipeInput`, no `Fatal{PipeResidualDiverged`, and every case armed. | `ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4`; `MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/pipe --lib ~/w7/pipe/build-verify/libMobileGL.so --out ~/w7/retrace-out/p2-verify -j 4`; then `grep -l 'Fatal{' ~/w7/retrace-out/p2-verify/*/mobilegl.log` empty and `grep -L 'MGPipe verify:' ~/w7/retrace-out/p2-verify/*/mobilegl.log` empty. |
|
||||
| **G5** | **`SyncRenderState` is not one line changed.** The whole of `namespace RenderStateImpl` in `DirectGLES.cpp` is byte-identical to the base ref (line numbers may move; the text may not). | `for r in $BASE HEAD; do git show $r:MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp \| awk '/^ namespace RenderStateImpl \{/,/^ \} \/\/ namespace RenderStateImpl/' \| sha256sum; done` → the two hashes are equal. |
|
||||
| **G6** | **G7 setter consistency**: for every public `RenderState` setter, the pipeline-subset hash moves ⟺ `m_pipelineStateVersion` moves; and the chunk table partitions `[0, sizeof(RenderStateParameters))` exactly (sorted, non-overlapping, complete). | `ctest --test-dir build-push -R 'RenderStateSpans\.' --no-tests=error --output-on-failure` (the partition half is a `static_assert` in `MGPipeRenderStateSpans.cpp`, so a gap is a build break). |
|
||||
| **G7** | **G6's negative control**: moving one member from `kMGPipePipelineChunks` to `kMGPipeDynamicChunks` (partition still complete, so it still compiles) turns the setter-consistency test red, naming that member's setter. | `scripts/g7_negative_control.sh` (D19) — patches `MGPipeRenderStateSpans.cpp` to demote `ColorMasks`, rebuilds, expects `ctest -R 'RenderStateSpans\.SetterConsistency'` to **fail**, then reverts. Non-zero rc from ctest is the pass. |
|
||||
| **G8** | **`HandleRecycleScenario` is green after the re-key and red before it**, on at least one backend, as three always-on ctest entries: handle arm green, legacy arm green, ABA-control arm red. | `ctest --test-dir build-verify -R 'HandleRecycle' --no-tests=error --output-on-failure` — `*.Handles` and `*.Legacy` pass, `*.AbaControl` passes **by asserting the corruption** (D18). |
|
||||
| **G9** | `gen_pipe_dirty_surface.py` is a **gate**: the mapping file covers all 73 mutators, an unmapped mutator or a mapping row naming a mutator that no longer exists fails the job, and the report regenerates with `git diff --exit-code`. | `python3 scripts/gen_pipe_dirty_surface.py --check` (rc 0) and `python3 scripts/gen_pipe_dirty_surface.py --self-test` (rc 0; canned negative controls). CI: `pipe-gates`. |
|
||||
| **G10** | The **`ResidualValueBlock` tripwire** holds: `MGL_RESIDUAL_BLOCK_SIZE` is **8** (down from 1248, never up), every member has an `offsetof` assertion, `MOBILEGL_PIPE_STATS`'s `resid=` byte class is **non-zero** in a device window, and a capability the residual block and the working block disagree about aborts. | build (the ratchet is a `static_assert`); `ctest --test-dir build-verify -R 'Residual' --no-tests=error`; on device `grep 'MGPipe stats:' mobilegl.log \| tail -1` shows `resid=` > 0. |
|
||||
| **G11** | **Two devices, reboot-clean, paired A/B: per-thread CPU p50 and p99 deltas are not negative on either device, and the tracker's absolute ns/draw is inside the pinned ceiling.** | D.4 — the `benchmark.json` `frameCpuTimesMs[]` series (E adds it) reduced host-side to p50/p99, plus the DriverBench `ns_per_op` decomposition T1/T2. The ceiling is pinned in `MEASUREMENTS.md` **before** the run (D.4.5). |
|
||||
| **G12** | The **Blaze3D blend-toggle microbenchmark** and the **CSO-content-addressing negative control** are both published, and the negative control cannot rot: a ctest entry proves the switch actually changes CSO mint/bind counts. | `MobileGL/MG_Benchmark/Driver/run_driver_bench.sh {native,espryt,magma}` on `mc_state_toggle`; `ctest --test-dir build-push -R 'CsoContentAddressing' --no-tests=error`. |
|
||||
| **G13** | Nothing reintroduces a purity violation: `pGLContext` still appears zero times under `MG_Backend/`, the include closure still holds, no stdio instrumentation, generators regenerate clean. | `grep -rc 'pGLContext' MobileGL/MG_Backend \| grep -v ':0$'` empty; `python3 scripts/check_include_closure.py`; `python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test`; the `pipe-gates` stdio grep. |
|
||||
| **G14** | Existing test names are never removed (additions only), and the full CI matrix is green. | `ctest --test-dir build-linux -N \| … \| comm -23 ~/w7/p2-before-ctest-names.txt -` empty; `gh workflow run test.yml --ref feat/disaggregated`. |
|
||||
|
||||
Baseline captures the integrator takes **before** any package lands (in `~/w7/pipe` at `48268068`):
|
||||
|
||||
```sh
|
||||
cp ~/w7/pipe/build-linux/libMobileGL.so ~/w7/p2-before-libMobileGL.so
|
||||
ctest --test-dir ~/w7/pipe/build-linux -N | grep -E '^\s+Test #' | sed 's/^ *Test *#[0-9]*: //' | sort > ~/w7/p2-before-ctest-names.txt
|
||||
git -C ~/w7/pipe show HEAD:MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp \
|
||||
| awk '/^ namespace RenderStateImpl \{/,/^ \} \/\/ namespace RenderStateImpl/' | sha256sum > ~/w7/p2-before-syncrenderstate.sha
|
||||
python3 scripts/gen_pipe_dirty_surface.py > ~/w7/p2-before-dirty-surface.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## B. Fixed design decisions
|
||||
|
||||
Nothing in this section is re-decided inside a package. Where a decision departs from the design documents it is marked **[deviation]** and the doc line the integrator must correct is named.
|
||||
|
||||
### D1 — Where the tracker runs: `MGP_FILL` stays; `MGPipeFillForVerb` becomes the tracker's entry point
|
||||
|
||||
`MGP_FILL(Verb)` (`MG_Impl/Pipe/PipeFill.h:52`) is already exactly one statement before every `gBackendFunctionsTable.GL.*` call, after every early return (`PipeFill.h:10-15`, and the 83 statements over 69 verbs the P1 brief §B.7 enumerates). It is the validate point `ARCHITECTURE.md:151` demands and it is already generated-table-driven.
|
||||
|
||||
**Decision: the macro spelling, the 83 call sites and the verb enum do not change. `MGPipeFillForVerb(MGPipeVerb)` is renamed `MGPipeValidateForVerb(MGPipeVerb)` and its body becomes the tracker's walk; `MGP_FILL` expands to the new name.** The tracker does **not** sit above `MGP_FILL` and there is no new `ValidateForDraw`/`ValidateForClear`/… family of functions.
|
||||
|
||||
- **[deviation] against `ARCHITECTURE.md:153`**, which asks for eight named `ValidateFor*` entry points. Reason: the landed machinery already dispatches on `kMGPipeVerbClass[verb]` (`generated/PipeFillPoints.inc:197`) into **nine** classes (`FillPoints.def:107-108`), and eight separate entry points would either duplicate that table or force a merge of `kProgramOp` back into `kDraw` that `FillPoints.def:105-106` explicitly argues against. One entry point with a class-indexed switch is the same code with one call site per verb instead of nine. The integrator corrects `ARCHITECTURE.md:153` to nine classes and names them.
|
||||
- `MGPipeLeaveVerb()` (`PipeFill.h:34`, used by `MG_Test/ScopedPipeVerb.h`) keeps its name and semantics.
|
||||
- `MGP_NOTE_MUTATION` (`MG_Pipe/PipeMutation.h`, four statements over three fields at `TextureState.h:85,98,111,133`) **stays exactly as it is**. `MEASUREMENTS.md:117` is right that it is the shape the tracker needs; the tracker does not absorb it, because it answers a different question (a backend writing frontend state *inside* a verb, after the walk has run).
|
||||
|
||||
The body of `MGPipeValidateForVerb(verb)`, in order:
|
||||
|
||||
1. everything `MGPipeFillForVerb` does today up to and including `SetIdentity` / the null-context early return (`PipeFill.cpp:566-589`) — unchanged, including the poison serial bump and the verify arming;
|
||||
2. **the dirty walk** (D4): compare the tracker's `m_lastPushed` shutters against the live counters, producing a `Uint32` dirty mask;
|
||||
3. **emission** (D6, D7, D9, D10, D11): for each set dirty bit whose subsystem bit is on in the runtime `MOBILEGL_PIPE_PUSH` bitmask, build the payload and hand it to the applier (D2);
|
||||
4. **the residual fill**: the P1 per-class copy loop (`PipeFill.cpp:591-609`), restricted to the fields **not** covered by an emitted call (D5's `kMGPipeFieldEmittedBy[]`), with stamping unchanged;
|
||||
5. `EntryCompare(inputs, mask)` under verify (`PipeFill.cpp:611`) — unchanged, and now **no longer tautological**, which is the P1 brief's D8 promise coming due.
|
||||
|
||||
### D2 — The applier and where the server's working state lives
|
||||
|
||||
**Decision: in the monolith, the server's per-context working `RenderStateParameters` *is* `PipeInputs::m_renderState` (`MG_Backend/MGPipe/PipeInputs.h:645`).** `bind_render_state` and `set_dynamic_state` scatter their chunks straight into it. That is why Espryt's `const RenderStateParameters&` binding at `DirectGLES.cpp:2056` and the `Uint16` read at `:2028` need no change at all — the block they read is the assembled block. This is the mechanism behind "`SyncRenderState` 一行不动" (`ARCHITECTURE.md:188`, `ROADMAP.md:47`), and it is what makes the verify comparator a real oracle: the compare-at-read now proves *assembled == live*, field by field, at every backend read.
|
||||
|
||||
New files: `MobileGL/MG_Pipe/PipeApply.{h,cpp}`, `namespace MobileGL::MG_Pipe`, compiled only under `MOBILEGL_PIPE_PUSH`.
|
||||
|
||||
```cpp
|
||||
// PipeApply.h — the in-process applier. Under split this file is the server half
|
||||
// (ARCHITECTURE.md:375, MG_Remote/Server/PipeApplier); in the monolith it writes gPipeInputs
|
||||
// directly, so a call and its effect are one function call apart and nothing is serialised.
|
||||
void MGPipeApplyCreateRenderState(const MGPRenderStateDesc& desc, const void* chunkBytes);
|
||||
void MGPipeApplyBindRenderState(const MGPBindRenderState& bind);
|
||||
void MGPipeApplySetDynamicState(const MGPDynamicState& dyn, const void* chunkBytes);
|
||||
void MGPipeApplySetPixelPackState(const MGPPixelPackState& pack);
|
||||
void MGPipeApplySetPatchState(const MGPPatchState& patch);
|
||||
void MGPipeApplySetVertexAttribDefaults(const MGPVertexAttribDefaults& hdr, const MGPAttribValue* tail);
|
||||
void MGPipeApplySetResidualValueState(const ResidualValueBlock& block);
|
||||
```
|
||||
|
||||
The applier owns a per-context CSO store: `Vector<RenderStateCsoRecord>` indexed by `MGPipeHandle::Slot`, each record holding the 396 pipeline bytes and a `Gen`. `MGPipeApplyBindRenderState` memcpy-scatters the record's seven pipeline chunks into `m_renderState`, then writes `m_renderStateParametersVersion = bind.Version` and `m_pipelineStateVersion = bind.PipelineVersion`. `MGPipeApplySetDynamicState` scatters the chunks named by `dyn.ChunkMask` and writes `m_renderStateParametersVersion = dyn.Version`.
|
||||
|
||||
**After any scatter the applier calls `MGPipeDeriveRenderStateFields(PipeInputs&)`** — see D5.
|
||||
|
||||
The applier `MOBILEGL_ASSERT`s (debug/verify only) that a `bind` names a live `{slot, gen}` and that `desc.ChunkMask` covers every chunk of a brand-new CSO.
|
||||
|
||||
### D3 — Value-type changes in `MGPipeValueTypes.h` and `RenderState`
|
||||
|
||||
1. **Three new members in `RenderStateParameters`**, declared *immediately after `Array<BoolVec4,8> ColorMasks;` and before `FloatVec4 ClearColor;`*, filling the 3-byte hole at `[581, 584)`:
|
||||
|
||||
```cpp
|
||||
// GL_FRAMEBUFFER_SRGB / GL_DEPTH_CLAMP / GL_TEXTURE_CUBE_MAP_SEAMLESS. Until P2 these
|
||||
// three fell to SetCapability's `default:` arm - glEnable was swallowed and
|
||||
// IsCapabilityEnabled answered a compile-time false, so DirectGLES' sRGB block
|
||||
// (DirectGLES.cpp:2168) and five DirectVulkan read points consumed a constant.
|
||||
// Placed HERE, in the three alignment bytes between ColorMasks and ClearColor, so
|
||||
// sizeof(RenderStateParameters) stays 1168 and no existing offset moves: the Espryt
|
||||
// span constants and the P2 chunk table both depend on that.
|
||||
Bool FramebufferSrgbEnabled = false;
|
||||
Bool DepthClampEnabled = false;
|
||||
Bool TextureCubeMapSeamlessEnabled = false;
|
||||
```
|
||||
|
||||
The existing `static_assert(sizeof(RenderStateParameters) == 1168, ...)` (`:541`) is the check; if it fires, the hole is not where this brief computed it and the implementer must find the real one with a temporary `static_assert(offsetof(...))` rather than growing the struct (growing it is a `MGL_RESIDUAL_BLOCK_SIZE` violation).
|
||||
2. **Three rows in `MGP_FIELDS_RenderStateParameters(F)`** (`PipeFields.def:230-247`), in declaration order. `gen_pipe.py` asserts every direct member has a row (`PipeFields.def:224-228`), so omitting one fails `pipe-gates`.
|
||||
3. **Three `SET_CAPABILITY` arms and three `RETURN_CAPABILITY` arms** in `RenderState.cpp` (`:317-338`, `:390-413`), keeping the source order of `CapabilityInput`. All three therefore call `BumpVersions()` and land in the **pipeline** half (D6). `FramebufferSrgb` on the pipeline side is what `ARCHITECTURE.md:190` asks for; `DepthClamp` is `VkPipelineRasterizationStateCreateInfo::depthClampEnable` and `TextureCubeMapSeamless` changes sampler interpretation, so both belong there too.
|
||||
4. **`{}` on the three value members** of `RenderState` (`RenderState.h:172`, `:175`, `:176`) so padding is deterministic. Cost: one `.text` resize of `RenderState::RenderState()`, allowed by G1 and named in the commit message. Reason: the CSO key is a byte-range hash (D6); indeterminate padding would make a CSO handle reproducible only within one context, and would make the residual block's byte-level trip wire meaningless.
|
||||
|
||||
**Behaviour change, and it is real, so it is gated.** With storage, `glEnable(GL_FRAMEBUFFER_SRGB)` now (a) makes `glIsEnabled` answer true and (b) makes Espryt issue a real `glEnable(GL_FRAMEBUFFER_SRGB)` at `DirectGLES.cpp:2170` — that block is **ungated** by the span dirty flags and already reads the accessor, so it needs no edit and is not a `SyncRenderState` change. `DepthClamp` and `TextureCubeMapSeamless` gain no reader on either backend (verified: no `depthClampEnable`/`alphaToOneEnable` anywhere in `PipelineFactory.{h,cpp}`/`VulkanRenderer.cpp`; `TextureCubeMapSeamless` appears only in the three enum converters), so their only effect is `glGet`/`glIsEnabled`. `MEASUREMENTS.md:84` records that none of the 41 fixtures enables any of them, so G3's SSIM gate is the check that no fixture output moves.
|
||||
|
||||
### D4 — Dirty bits and the five aggregate generations
|
||||
|
||||
**Representation.** `Uint32 MGPipeTracker::m_dirty`, one bit per row of `ARCHITECTURE.md:161-168`, declared as a plain `enum class MGPipeDirty : Uint32` in `MG_Impl/Pipe/Tracker.h` (hand-written, not generated — the list is 15 long and is design, not derived data), with `static_assert(kMGPipeDirtyCount <= 32)`:
|
||||
|
||||
| bit | name | class | shutter the tracker compares |
|
||||
|---|---|---|---|
|
||||
| 0 | `NEW_RENDER_STATE` | value | `GetRenderStateParametersVersion()` (`Uint16`, widened) |
|
||||
| 1 | `NEW_PIPELINE_STATE` | value | `GetPipelineStateVersion()` (`Uint16`, widened) |
|
||||
| 2 | `NEW_PIXEL_PACK` | value | `PixelStoreParameters` pack, `BitwiseEqual` |
|
||||
| 3 | `NEW_PATCH_STATE` | value | the patch trio, `BitwiseEqual` (**NaN is legal**, `ARCHITECTURE.md:162`) |
|
||||
| 4 | `NEW_VERTEX_ATTRIB_DEFAULTS` | value | `ContentHash` over the 32 `CurrentVertexAttributeValue`s |
|
||||
| 5 | `NEW_VERTEX_ELEMENTS` | value | `VertexArrayObject::GetConfigVersion()` |
|
||||
| 6 | `NEW_SHADER` | value | `ProgramObject::GetLinkVersion()` |
|
||||
| 7 | `NEW_SHADER_BINDINGS` | value | image-unit / backend-state / block-binding / uniform-write-set versions |
|
||||
| 8 | `NEW_GLOBAL_CONSTANTS` | value | `GetUBOContentVersion()` |
|
||||
| 9 | `NEW_VERTEX_BUFFERS` | object | `VertexArrayState::m_anyVaoAttributeGeneration` **(new)** → 32-attribute prefix |
|
||||
| 10 | `NEW_INDEX_BUFFER` | object | index slot version + bound object `{slot, gen}` |
|
||||
| 11 | `NEW_FRAMEBUFFER` | object | `FramebufferState::m_anyAttachmentGeneration` **(new)** + object/slot version → recompute `ContentHash` |
|
||||
| 12 | `NEW_SAMPLER_VIEWS` | object | `TextureState::m_anyTextureContentGeneration` **(new)** + bind generation → `GetMaxTouchedUnit()` prefix |
|
||||
| 13 | `NEW_SAMPLERS` | object | `TextureState::m_anyTextureParamsGeneration` **(new)** + sampling-resolution generation |
|
||||
| 14 | `NEW_SHADER_IMAGES` | object | the same two texture aggregates + image-unit version |
|
||||
| 15 | `NEW_CONST_BUFFERS` / `NEW_SHADER_BUFFERS` / `NEW_SO_TARGETS` (three bits, 15–17) | object | `BufferState::m_anyBufferChangeGeneration` **(new)** → `GetTouchedBindPointCount()` prefix |
|
||||
|
||||
**P2 only *emits* for bits 0–4.** Bits 5–17 are computed, counted and asserted by the tracker but their emission is P3a/P3b/P4a/P4b; their fields keep going through the residual fill loop. The tracker records, per verb class, how many draws each bit fired on, which is the first honest measurement of "does this shutter actually shut" and is what the dangerous direction (`ARCHITECTURE.md:502`, a dirty bit that fires too *rarely*) is judged against.
|
||||
|
||||
**The five aggregate generations.** `Uint64`, monotonic, bumped at the existing bump points, all **`#if MOBILEGL_PIPE_PUSH`-guarded** so the pull build's `MG_State` objects do not change size or code (G1):
|
||||
|
||||
| member | file | bumped at |
|
||||
|---|---|---|
|
||||
| `VertexArrayState::m_anyVaoAttributeGeneration` | `MG_State/GLState/VertexArrayState/VertexArrayState.h` | every `VertexArrayObject::BumpConfigVersion` site (`VertexArrayObject.cpp:299,305,311`) — reached through a new `NotifyAttributeChanged()` on the owning state |
|
||||
| `FramebufferState::m_anyAttachmentGeneration` | `.../FramebufferState/FramebufferState.h` | `FramebufferObject.cpp:192,203,215` |
|
||||
| `TextureState::m_anyTextureContentGeneration` | `.../TextureState/TextureState.h` | `TextureObject.cpp:285,354,365`; `TextureObject2DCube.cpp:51,62` |
|
||||
| `TextureState::m_anyTextureParamsGeneration` | `.../TextureState/TextureState.h` | `TextureObject.cpp:101,126,140,154,203,210,227,238,258,294,303`; `TextureObject.h:182`; `SamplerObject.cpp:27-35` |
|
||||
| `BufferState::m_anyBufferChangeGeneration` | `.../BufferState/BufferState.h` | `BufferObject.cpp:45,52,61,75,82,304,368` |
|
||||
|
||||
The bump is spelled `MGP_NOTE_AGGREGATE(VaoAttribute);` — a new macro in `MG_Pipe/PipeMutation.h` next to `MGP_NOTE_MUTATION`, `((void)0)` in the pull build, exactly the same shape and for the same reason (`PipeMutation.h:29-40`). A per-object bump reaches its owning state through a back-pointer the object already has, or, where it does not, through a free function `MGPipeNoteAggregate(MGPipeAggregate)` that finds the live `GLContext` — the second form costs a global load on a cold path and is what `MGP_NOTE_MUTATION` already does (`PipeFill.cpp:479-491`).
|
||||
|
||||
**Wrap-around.** Three shutters are `Uint16` (`RenderState::m_version`, `m_pipelineStateVersion`, `FramebufferObject::m_objectVersion`) and two more are `Uint16` on `SamplerObject`/`TextureObject` params. The tracker widens them in its **own** `m_lastPushed[]` (`Uint32` accumulator plus the last observed `Uint16`; a decrease means a wrap and adds 65536). **`MG_State` is not changed** (`ARCHITECTURE.md:174`). A wrap is harmless locally: one extra re-push, never a missed push.
|
||||
|
||||
### D5 — The derivation step, and which `PipeInputs` fields stop being copied
|
||||
|
||||
29 of the 47 `kDraw` `PipeInputs` fields are pure functions of `RenderStateParameters`. Once the applier assembles the working block, copying them again from `GLContext` would be a second pull. **Decision: the applier derives them from the working block.**
|
||||
|
||||
`MGPipeDeriveRenderStateFields(PipeInputs&)` in `PipeApply.cpp` recomputes exactly:
|
||||
`m_blendColor`, `m_blendEquation[8][2]`, `m_blendFunc[8][4]`, `m_clampReadColor`, `m_clearColor`, `m_clearDepth`, `m_clearStencil`, `m_colorMask[8]`, `m_cullFaceMode`, `m_depthFunc`, `m_depthMask`, `m_depthRange[16]`, `m_lineWidth`, `m_logicOp`, `m_minSampleShading`, `m_patchInner`, `m_patchOuter`, `m_patchVertices`, `m_polygonModeFront`, `m_polygonOffsetFactor`, `m_polygonOffsetUnits`, `m_primitiveRestartIndex`, `m_provokingVertexMode`, `m_scissorBox`, `m_stencil[2]`, `m_viewport`, `m_viewportIndexed[16]`, `m_capability[35]`, `m_capabilityIndexed` (Blend×8, ScissorTest×16).
|
||||
|
||||
- **[deviation] against P1 brief D4's "no derivation logic is re-implemented in `PipeInputs`".** Reason: the alternative is to keep pulling those 29 fields per verb, which is the cost P2 exists to remove. The derivations are one to four lines each and are mechanical transcriptions of `RenderState`'s getters (`RenderState.cpp:53-971`); two are non-trivial and must be transcribed exactly: `GetViewport()` returns viewport 0 **rounded to integers** (`RenderState.h:27-31`), and `IsCapabilityEnabled`/`IsCapabilityEnabledIndexed` are the 35-way and 2-way switches at `RenderState.cpp:387-432` and `:434-…`, including `Blend → BlendStates[0].Enabled` and `ScissorTest → ScissorTestEnabledMask & 1`.
|
||||
- **The guard is the oracle P1 built.** `MOBILEGL_PIPE_VERIFY`'s compare-at-read (`PipeInputs.h:62-63` → `PipeFill.cpp:439-463`) re-reads each of these from the live context at *every backend read* and compares field-wise. A transcription error is caught on the first draw that reads it, across 79 retraces and 818 integration-verify entries. On top of that, a unit test (`RenderStateSpansTest.DerivationMatchesTheFrontendGetters`) drives every setter and compares all 29 derived values against the `GLContext` getters.
|
||||
|
||||
`gen_pipe.py` gains a generated table `kMGPipeFieldEmittedBy[]` (from a new `MGP_COVERAGE_EMITTED_LIST` in `Coverage.def`) naming, per `MGPipeInputField`, the P2 call that now supplies it. The residual fill loop skips any field whose entry is non-`kNone` **and** whose subsystem bit is on; that is one array lookup per field and it is what makes the runtime bitmask a true per-subsystem A/B.
|
||||
|
||||
### D6 — The chunk table: the split, written in exactly one place
|
||||
|
||||
New files `MobileGL/MG_Pipe/MGPipeRenderStateSpans.{h,cpp}`, compiled **only under `MOBILEGL_PIPE_PUSH`** (appended to `SOURCE_FILES` inside the existing `if (MOBILEGL_PIPE_PUSH)` block, `CMakeLists.txt:462-468`), which is how the pull build gains no symbol (G1). `generated/PipeSpanTable.inc:66-67` already declares `kMGPipePipelineChunks` / `kMGPipeDynamicChunks`; a declaration costs the pull build nothing.
|
||||
|
||||
**The rule that decides the split, and it is the only rule:**
|
||||
|
||||
> **A byte of `RenderStateParameters` is in the pipeline half if and only if some public `RenderState` setter that calls `BumpVersions()` writes it. Every other byte is in the dynamic half. There is no third set.**
|
||||
|
||||
That makes `ARCHITECTURE.md:186`'s G7 invariant — *pipeline-subset hash moves ⟺ `m_pipelineStateVersion` moves* — true **by construction** rather than by inspection, and it resolves all six of the violations `scout-render-state.md` §2.5 found, in the direction of *growing the subset* rather than demoting setters:
|
||||
|
||||
- **[deviation] the pipeline subset is a strict superset of the 24 members `ComputePipelineStateHash` hashes today.** It adds `SampleCoverageValue`, `SampleCoverageInvert`, `FrontFaceModeSetting`, `ProvokingVertexModeSetting`, `ScissorTestEnabledMask`, `PolygonModeBack`, the 11 unhashed capability bools (`DebugOutput`, `DebugOutputSynchronous`, `Dither`, `LineSmooth`, `PolygonOffsetLine`, `PolygonOffsetPoint`, `PolygonSmooth`, `SampleAlphaToCoverage`, `SampleAlphaToOne`, `SampleCoverage`, `ProgramPointSize`) and the three new bools of D3. Reason: the alternative — demoting those setters to `++m_version` — changes `MG_State` semantics in the **pull** build and breaks G1, and it is a behaviour change to the pull path for the sake of the push path. Growing the subset costs nothing measurable: hashing happens only when `m_pipelineStateVersion` moves, which is exactly when Magma already recomputes `ComputePipelineStateHash` today, and a scissor or sample-coverage toggle now mints a *second cached* CSO whose handle is reused thereafter, the same shape as the Blaze3D blend toggle the CsoCache is built for.
|
||||
- **[deviation] against `MGPipeTypes.h:232-235`**, whose comment puts "sample coverage" in the dynamic half. `SetSampleCoverage` (`RenderState.cpp:778-784`) calls `BumpVersions()`, so under the rule it is pipeline. The implementer fixes that comment in the same commit (hints, the point-size family, clear values, blend colour, line width, polygon offset, stencil ref/write mask, viewport, scissor and depth range all stay dynamic and the comment is right about them).
|
||||
- **[deviation] the patch trio is in the pipeline half *and* is carried by `set_patch_state`.** `Coverage.def:62-64` routes the three patch accessors to `SetPatchState`; `kMGPipePipelineStateMembers` lists all three. Both are right for different reasons: they are pipeline state (`VkPipelineTessellationStateCreateInfo::patchControlPoints`, hashed at `VulkanRenderer.cpp:4864-4878`) **and** a shader-variant input both backends bake into the synthesized control stage (`MGPipeTypes.h:498-499`, read from a shader-build path at `Managers.cpp:7194-7205`, not a draw path). So the bytes travel twice — 28 bytes on a state that changes about once per program — and the applier asserts under verify that the two carriers agree. Redundancy here is a trip wire, not waste.
|
||||
|
||||
**The table.** `MGPipeRenderStateSpans.cpp` computes every boundary with `offsetof`/`sizeof` — never a literal — and carries `static_assert`s that the chunks are sorted, non-overlapping and cover exactly `[0, sizeof(RenderStateParameters))`. The offsets below are what this brief computes; **the file must derive them, and if it disagrees the file is right and this table is wrong.**
|
||||
|
||||
| # | set | range | size | members |
|
||||
|---|---|---|---|---|
|
||||
| D0 | dynamic | `[0, 264)` | 264 | `Viewports[16]`, `LineWidth`, `PointSize` |
|
||||
| P0 | pipeline | `[264, 292)` | 28 | `PatchVertices`, `PatchDefaultOuterLevel`, `PatchDefaultInnerLevel` |
|
||||
| D1 | dynamic | `[292, 312)` | 20 | `PolygonOffsetFactor/Units/Clamp`, `ClipOrigin`, `ClipDepthMode` |
|
||||
| P1 | pipeline | `[312, 584)` | 272 | `BlendStates[8]`, `LogicOp`, `DepthTestEnabled`, `DepthFunc`, `DepthMask`, `ColorMasks[8]`, **`FramebufferSrgbEnabled`, `DepthClampEnabled`, `TextureCubeMapSeamlessEnabled`** |
|
||||
| D2 | dynamic | `[584, 752)` | 168 | `ClearColor`, `ClearDepth`, `ClearStencil`, `BlendColor`, `DepthRanges[16]` |
|
||||
| P2 | pipeline | `[752, 772)` | 20 | `SampleCoverageValue`, `SampleCoverageInvert`, `SampleMaskValue`, `MinSampleShadingValue` |
|
||||
| D3 | dynamic | `[772, 784)` | 12 | `StencilStates[0].{Ref, ValueMask, WriteMask}` |
|
||||
| P3 | pipeline | `[784, 800)` | 16 | `StencilStates[0].{FailOp, PassDepthFailOp, PassDepthPassOp}`, `StencilStates[1].Func` |
|
||||
| D4 | dynamic | `[800, 812)` | 12 | `StencilStates[1].{Ref, ValueMask, WriteMask}` |
|
||||
| P4 | pipeline | `[812, 840)` | 28 | `StencilStates[1].{FailOp, PassDepthFailOp, PassDepthPassOp}`, `CullFaceEnabled`, `CullFaceModeSetting`, `FrontFaceModeSetting`, `ProvokingVertexModeSetting` |
|
||||
| D5 | dynamic | `[840, 868)` | 28 | the four hints, `PointFadeThresholdSize`, `PointSpriteCoordOrigin`, `ClampReadColor` |
|
||||
| P5 | pipeline | `[868, 876)` | 8 | `PolygonModeFront`, `PolygonModeBack` |
|
||||
| D6 | dynamic | `[876, 880)` | 4 | `PrimitiveRestartIndex` |
|
||||
| P6 | pipeline | `[880, 904)` | 24 | the 20 capability bools `ColorLogicOpEnabled`…`ProgramPointSizeEnabled`, `ScissorTestEnabledMask` |
|
||||
| D7 | dynamic | `[904, 1168)` | 264 | `ScissorBoxes[16]`, `ScissorBoxWrittenMask`, `ClipDistanceEnabledMask` |
|
||||
|
||||
**7 pipeline chunks totalling 396 bytes; 8 dynamic chunks totalling 772 bytes; 396 + 772 = 1168.** Both counts fit the `Uint32 ChunkMask` of `MGPRenderStateDesc` (`MGPipeTypes.h:215-221`) and `MGPDynamicState` (`:236-241`) with room to spare. `StencilStates` is the one member that straddles, at sub-member granularity, exactly as `scout-render-state.md` §7.2 predicted; **`StencilFaceState` is not reordered** — reordering would move Espryt's shadow bytes for no gain and would invalidate the offsets above.
|
||||
|
||||
Note the two splits are orthogonal and coexist (`ARCHITECTURE.md:188`): Espryt's head `[0,312)` / blend `[312,536)` / tail `[536,1168)` cuts across this table, and D0/P0/D1 all live in Espryt's head while P1 spans Espryt's blend and tail. Nothing about Espryt's spans changes.
|
||||
|
||||
`MGPipeComputePipelineSubsetHash(const RenderStateParameters&)` is `XXH64` over the seven pipeline chunks in ascending order, seeded with a compile-time table version so a chunk-table change invalidates every persisted key. 396 bytes ≈ 49.5 eight-byte words — **[deviation]** the doc estimates "~25-30 字" (`ARCHITECTURE.md:189`), which was the 24 hashed members without padding and without the 15 members added above; the integrator records 396 bytes / 49.5 words in `MEASUREMENTS.md`.
|
||||
|
||||
### D7 — The CsoCache
|
||||
|
||||
`MobileGL/MG_Impl/Pipe/CsoCache.{h,cpp}`, one instance per context, held by the tracker.
|
||||
|
||||
- Storage: `ska::flat_hash_map<Uint64, Uint32>` (hash → cache-entry index) plus a `Vector<Entry>` of at most **64** entries and an intrusive LRU list. `Entry = { Uint64 Hash; MGPipeHandle Cso; Array<Uint8, 396> PipelineBytes; }` — 64 × ~412 B ≈ 26 KB per context.
|
||||
- Capacity **64** (`ROADMAP.md:18`, `ARCHITECTURE.md:63`). `ROADMAP.md:77` says 64 is provisional and the counters retune it; P2 ships 64 and publishes the mint/bind/evict counters that a P13 retune reads.
|
||||
- **[deviation] a hash hit is confirmed with a `memcmp` of the 396 pipeline bytes before the handle is reused.** `ARCHITECTURE.md:63` says content addressing on an xxHash; a bare 64-bit hash equality would let a collision alias two different render states onto one CSO, which is a silent wrong-pixels bug with no gate that can see it. Mesa's `cso_cache` memcmps for the same reason. The memcmp runs only when `m_pipelineStateVersion` moved, i.e. never in the steady state.
|
||||
- Eviction is LRU and emits `DeleteRenderState` (`PipeCalls.def:94`), which frees the applier's slot and bumps its `Gen`.
|
||||
- **The lookup algorithm** (`ARCHITECTURE.md:189` verbatim, implemented):
|
||||
1. `m_pipelineStateVersion` (widened) unchanged → reuse `m_lastCso`, **zero hashing, zero probing**; emit nothing unless `m_version` also moved.
|
||||
2. changed → hash the seven pipeline chunks → probe → **hit**: `memcmp` confirms, emit `MGPBindRenderState` (12 B). **miss**: mint a slot, emit `MGPRenderStateDesc` with the changed chunks (`ChunkMask`; all-ones for a brand-new CSO, else the chunks that differ from `BaseCso`), then the 12-byte bind.
|
||||
3. `m_version` moved but the pipeline subset did not → emit `MGPDynamicState` only.
|
||||
- Counters: `PipeStats::AddCalls(CallClass::RenderStateCsoMints, 1)` and `…CsoBinds, 1)` (two new call classes, D17).
|
||||
|
||||
### D8 — What `set_dynamic_state` carries
|
||||
|
||||
`MGPDynamicState{ ChunkMask, Version, Pad0, Blob }` (`MGPipeTypes.h:236-241`, 32 B) plus a blob that is the concatenation, in ascending chunk index, of the dynamic chunks whose bit is set in `ChunkMask`. `Version` is `m_version` (widened `Uint16`, sent as the raw `Uint16` the wire type declares).
|
||||
|
||||
**Granularity: per chunk, eight bits, chosen by `memcmp` of each dynamic chunk against the tracker's staging copy.** So a `glViewport` sends chunk D0 (264 B), a `glClearColor` sends D2 (168 B), a `glScissor` sends D7 (264 B), a `glStencilMask` on the front face sends D3 (12 B). `ROADMAP.md:77` defers the final granularity to the counters; P2 ships eight chunks and gives `PipeStats::RecordDrawPayloadBytes` (`PipeStats.h:154`, implemented, unit-tested and **called by nothing** today) its first emitter, so the 24-bucket histogram answers the retune question with data. `ARCHITECTURE.md:189`'s "~200 B" estimate is in the right range; the measured per-chunk sizes above go into `MEASUREMENTS.md`.
|
||||
|
||||
The tracker keeps `RenderStateParameters m_staged{}` (value-initialised) as the "what the server has" mirror; a chunk that memcmp-matches is not sent, which is the chunk-level suppressor.
|
||||
|
||||
### D9 — The residual value block, its ratchet and its tripwire
|
||||
|
||||
After P2, `MGPipeTypes.h:516-525` becomes:
|
||||
|
||||
```cpp
|
||||
struct ResidualValueBlock {
|
||||
Uint64 CapabilityBits; // the 35 CapabilityInput bits, packed in enum order
|
||||
};
|
||||
```
|
||||
|
||||
`#define MGL_RESIDUAL_BLOCK_SIZE 8` (down from 1248 — `RenderState` 1168 retires to the CSO, `Pack` 28 to `set_pixel_pack_state`, the patch quintet 52 to `set_patch_state`). The ratchet comment at `MGPipeTypes.h:527-535` stays; the number only ever goes down.
|
||||
|
||||
**The three disciplines (`ARCHITECTURE.md:359`), implemented:**
|
||||
1. **Retirement is a compile error.** The `static_assert(sizeof(ResidualValueBlock) == MGL_RESIDUAL_BLOCK_SIZE, …)` at `:537` is what fires if a field is removed without lowering the number, or added at all.
|
||||
2. **Per-member `offsetof` assertions, and field-wise serialisation under split.** `gen_pipe.py` emits `static_assert(offsetof(ResidualValueBlock, CapabilityBits) == 0);` from `MGP_FIELDS_ResidualValueBlock` (`PipeFields.def:147-148`, which loses five of its six rows).
|
||||
3. **`MOBILEGL_PIPE_STATS` counts its bytes as their own class** — `ByteClass::ResidualValueBlock` (`PipeStats.h:73-75`), the placeholder that "stays at 0 until P2". P2 makes it non-zero (G10).
|
||||
|
||||
**The tripwire.** `CapabilityBits` is now *redundant*: every one of the 35 capabilities is answerable from the working `RenderStateParameters` once D3 closes the three storage holes. That redundancy is the point. `MGPipeApplySetResidualValueState` compares, bit by bit, the block's answer against `MGPipeDeriveRenderStateFields`' answer, and a disagreement is `Fatal{PipeResidualDiverged, "<CapabilityName>"}` in a poison or verify build (counted and logged otherwise). So the day a later call takes a capability over and forgets to carry it, the residual block says so on the next draw. The block is emitted once per context and again whenever the capability set changes.
|
||||
|
||||
### D10 — `set_pixel_pack_state`, `set_patch_state`, `set_vertex_attrib_defaults`
|
||||
|
||||
| call | payload | shutter | emitted when |
|
||||
|---|---|---|---|
|
||||
| `SetPixelPackState` (`PipeCalls.def`, `kCtxState`) | `MGPPixelPackState{ PixelStoreParameters Pack; }`, 28 B (`MGPipeTypes.h:488-496`) | `BitwiseEqual` against the tracker's copy | `NEW_PIXEL_PACK`. Applier writes `PipeInputs::m_pixelStore[0]`. **PACK only** — there is deliberately no unpack counterpart (`ARCHITECTURE.md:107`, `MGPipeTypes.h:485-487`). |
|
||||
| `SetPatchState` | `MGPPatchState{ Vertices, Pad0, Outer[4], Inner[2], Pad1[2] }`, 40 B (`:500-507`) | `BitwiseEqual`, **NaN legal** (`ARCHITECTURE.md:162`: a NaN outer level is a legal `glPatchParameterfv` value and must compare equal to itself) | `NEW_PATCH_STATE`. Applier writes the three members of the working block **and** asserts they match what the pipeline chunk P0 delivered (D6). |
|
||||
| `SetVertexAttribDefaults` (`kVarTail`) | `MGPVertexAttribDefaults{ Mask, Count }`, 8 B (`:479-483`), plus a tail of `Count` `MGPAttribValue`s for the attributes named by `Mask` | `ContentHash` (xxHash over the emitted set) through the set-hash suppressor (D11) | `NEW_VERTEX_ATTRIB_DEFAULTS`. Applier writes `PipeInputs::m_currentVertexAttribute[i]` for the named attributes. |
|
||||
|
||||
`BitwiseEqual` means `std::memcmp` over the value's bytes, which is why D3's `{}` matters for `PixelStoreParameters` (2 padding bytes at offsets 2–3).
|
||||
|
||||
### D11 — The set-hash suppressor skeleton
|
||||
|
||||
`MobileGL/MG_Impl/Pipe/SetHashSuppressor.h` — header-only:
|
||||
|
||||
```cpp
|
||||
// Coalescing rule 4 (ARCHITECTURE.md:198): every kVarTail set_* hashes the RESOLVED set on
|
||||
// the client and does not emit when the hash has not moved. This is the carrier for the
|
||||
// ~175 lines of debounce that move off the backends in P3b/P4b; P2 lands the mechanism and
|
||||
// one real consumer so the shape is pinned by a test rather than by a plan.
|
||||
class SetHashSuppressor {
|
||||
Array<Uint64, kMGPipeSuppressorSlotCount> m_lastEmitted{}; // 0 == "never emitted"
|
||||
public:
|
||||
Bool ShouldEmit(MGPipeSuppressorSlot slot, Uint64 contentHash); // and latches
|
||||
void Invalidate(MGPipeSuppressorSlot slot); // context change, server reset
|
||||
void InvalidateAll();
|
||||
};
|
||||
```
|
||||
|
||||
Slots, one per `kVarTail` `set_*` (`ARCHITECTURE.md:145`): `SetVertexBuffers`, `SetSamplerViews`, `BindSamplerStates`, `SetShaderImages`, `SetShaderBuffers`, `SetStreamOutputTargets`, `SetVertexAttribDefaults`. **P2 wires exactly one — `SetVertexAttribDefaults` — and unit-tests the class on all seven slots.** The other six are P3b/P4b (`ROADMAP.md:23`). A hash of 0 is reserved for "never emitted" so the first emission always goes out (the class remaps a computed 0 to 1).
|
||||
|
||||
### D12 — Magma re-sourced from the CSO and the dynamic payload
|
||||
|
||||
Nothing here is required for correctness — after D2 the working block is byte-identical to what Magma reads today, so an unmodified Magma is already correct under push. Everything in D12 is a **cost** deliverable, which is what makes it safe to land last.
|
||||
|
||||
1. **`GetOrCreatePipeline`'s memo key** (`VulkanRenderer.cpp:4997-5013`): `entry.pipelineStateHash == pipelineStateHash` becomes `entry.renderStateCso == boundCso` (an `MGPipeHandle` compare). The version→hash gate at `:4985-4995` and the three cached-hash fields (`VulkanRenderer.h:855,856,860,861,862`) **are deleted**: the client already did the hashing, and `m_pipelineStateHashValid`/`…Version`/`…ColorCount`/`…SampleCount` existed only to avoid re-hashing. `InvalidatePipelineMemo()` (`:881-885`) keeps clearing the memo and loses the three hash fields.
|
||||
**The render-pass facts stay in the key.** `entry.renderPassHash` already separates draws that differ only in `colorAttachmentCount`/`sampleCount` (correction 4 of the preamble), so collapsing `pipelineStateHash` to the CSO handle loses no discrimination. `ResolveEffectiveSampleMask` (`:4813-4819`) is **not** deleted — it is a *payload* computation that depends on `rasterizationSamples`, and it keeps reading `Multisample`/`SampleMask`/`SampleMaskValue` out of the working block.
|
||||
2. **`ComputePipelineStateHash`** (`:4821-4910`) is retained only under `MOBILEGL_PIPE_LEGACY_MEMOS` and is not called on the new arm. Its 20-line enumeration comment (`:4780-4794`) moves to `MGPipeRenderStateSpans.cpp` as the provenance of the pipeline chunk set, since that is now the contract it was.
|
||||
3. **`ApplyDynamicDrawStateTail`** (`:5902-6004`): the version gate at `:5920-5930` keeps reading `GetRenderStateParametersVersion()` — that value now comes from `MGPDynamicState::Version`, so it moves exactly when a dynamic chunk moved and no longer moves on a pipeline-only change. The `DynamicTailKey` build and compare (`:5944-5982`) stay; the `struct DynamicTailKey` (`:355-395`) and its input inventory (`:341-354`) are already an exact enumeration of the dynamic half and are the cross-check that D6's dynamic chunks are complete — the implementer asserts, in a unit test, that every field `DynamicTailKey` reads lies inside `kMGPipeDynamicChunks` (the two exceptions being `extentX`/`extentY`/`preTransform`/`isDefaultFbo`, which are backend facts, not GL state).
|
||||
4. **Subsystem 4** (Track H): `VertexInputStateFactory::ComputeHash`'s `const Uint64 bufferKey = attr.Buffer ? attr.Buffer->GetLifetimeId() : 0;` (`VertexInputStateFactory.cpp:48`) becomes `bufferHandle.Slot | (Uint64(bufferHandle.Gen) << 32)` — `ARCHITECTURE.md:363`'s "`lifetimeId` → `gen` 混进 server 侧每个 content hash". `VaoDrawMemo` (`VulkanRenderer.h:1244-1264`) drops `vaoKey` (raw pointer) and `vaoLifetimeId` for one `MGPipeHandle vaoHandle`; `LookupVaoDrawMemo` (`:3540-3579`) becomes a direct slot index into a grow-on-demand `Vector` with a `Gen` compare — no Fibonacci mix (`:3547-3548`), no 2-way probe, no frame-serial recycling (`:3564-3577`).
|
||||
5. **The frontend VAO loses its backend pointers.** `VertexArrayObject::{Get,Set}BackendStateMemo` and `m_backendStateMemo{,Epoch,Version}` (`VertexArrayObject.h:121-131`, `:192-194`) are **deleted outright** (`ARCHITECTURE.md:284`), and with them the eviction-epoch dance (`VertexInputStateFactory.cpp:78`, `:318`, `VertexInputStateFactory.h:141`, `s_evictionEpochSource`) — a slot-indexed table has stable entries. `{Get,Set}BackendHashMemo` and `{Get,Set}BackendAuxMemo` (`:106-114`, `:140-150`, storage `:190-191`, `:195-197`) become fields of the slot-indexed `VaoDrawMemo` entry. `SetBackendAuxMemo` has **no live reader** today (verified: its only writer is `VertexInputStateFactory.cpp:83-84`; the values moved into `VaoDrawMemo::layoutHash`/`layoutAuxMasks`, `VulkanRenderer.h:1257-1259`), so it is deleted rather than moved.
|
||||
**Out of scope, do not touch:** `ProgramObject::{Get,Set}BackendHashMemo` (`ProgramObject.h:798-826`, used by `ProgramFactory.cpp:3446-3448`), and `SetupDrawSnapshot`'s wider re-key (`VulkanRenderer.h:958-979`) beyond replacing its `vao`/`vaoLifetimeId` pair with the handle.
|
||||
|
||||
### D13 — Espryt 0b: what the first Track H slice replaces and what it must not break
|
||||
|
||||
**New**: `MobileGL/MG_Impl/Pipe/SlotAllocator.{h,cpp}` (client side, in the contract commit because Magma needs it too) and `MobileGL/MG_Backend/DirectGLES/SlotTables.h` (per-kind dense twin arrays).
|
||||
|
||||
`SlotAllocator` obeys `MGPipeHandles.h` exactly: per-`MGPipeKind` free list + high-water mark, first allocatable slot `kMGPipeFirstAllocatableSlot = 1` (`:81`), **`Gen` bumps only on slot reuse, never on respecify** (`:44-48`), a `MOBILEGL_ASSERT` on `Gen` wrap in a debug allocator, and a client-side `lifetimeId → slot` map per kind (`ARCHITECTURE.md:40`) so `GetLifetimeId()` stays the client's identity and a GL name never enters a key.
|
||||
|
||||
**Replaced / deleted** (all in `MG_Backend/DirectGLES/`):
|
||||
|
||||
| what | where | replacement |
|
||||
|---|---|---|
|
||||
| the six `StateBackendObjectRegistry` instances | `Managers.h:271-400`; instances at `Managers.h:803,1124,1215,1733,1833,1860`, definitions `Managers.cpp:2747,5075,5828,6139,8657,8769` | per-kind dense arrays indexed by `MGPipeHandle::Slot`, `Gen`-validated |
|
||||
| `Find`'s erase-on-expiry and the "a reference dies on the next call" hazard | `Managers.h:326-349` | O(1) indexed read; **`SyncTextureObjectToBackend`'s by-value copy and second `Find` (`DirectGLES.cpp:1310-1345`) are deleted in the same change**, not left as harmless |
|
||||
| `CollectGarbage` / `CollectGarbageIfNeeded` (7 call sites: `DirectGLES.cpp:1223,1533,1898,1899,1900,2728,2729`) | `Managers.h:356-391` | explicit destroy: `MarkXForDeletion` on the frontend emits `delete_*`, and the applier frees the slot |
|
||||
| `OwnerEquals` and the three `TwinLookupMemo`s | `DirectGLES.cpp:63-66`, `:83-132`; use sites `:1206,1214,2769,2777,2874,2879` | direct slot indexing — the memo existed only to avoid the hash probe |
|
||||
| `UnitSamplerLookupMemo`'s `WeakPtr` test | `DirectGLES.cpp:3157-3177` | `{slot, gen}` compare; the "a miss is never cached" contract (`:3148-3156`) survives verbatim |
|
||||
| `g_fbSlotCache` / `GetFramebufferBindingSlotFast` and its five callers (`:1613, 1907, 2745, 2860, 2935`) | `DirectGLES.cpp:134-157` | an ordinary `MGB_CTX->GetFramebufferBindingSlot(target)` read of pushed state. **This closes the P1 poison bypass** (`scout-track-h.md` §1.6): the fast getter ran the checked accessor once per context change and then handed out a raw pointer forever, so the per-verb poison stamp and the verify read-hook were skipped at those five sites. |
|
||||
| the four `pDefaultFramebufferInfo->defaultFBO` identity compares (`:1939, 2874, 2898, 6420`) | | `handle == kMGPipeDefaultFramebuffer` (`MGPipeHandles.h:71`) |
|
||||
|
||||
**Must not break** (each gets a named assertion or an existing test):
|
||||
|
||||
- `EnsureProcessTeardownSentinel()` (`Managers.h:59-60`, `Managers.cpp:161-170`) is armed by the first twin creation, today from `GetOrCreate` (`Managers.h:295`). The arming site moves to the slot table's first insertion. A registry destructor hook is **wrong** and the comment at `Managers.h:52-57` says why.
|
||||
- The twin destructors' `g_backendContextGeneration` compare (`Managers.h:64-70`) so a twin outliving its ES context does not `glDelete*` a recycled name. Pinned by `SanityTest.cpp:2650-2665, 2765-2773, 2786-2790`.
|
||||
- The whole-registry save / reset / restore fixture `ScopedDirectGLESTextureBindings` (`SanityTest.cpp:145-197`, `:160,164,178,195`) must keep working — the slot table needs the same copy-assign-and-restore shape.
|
||||
- The one direct-iteration site, `ScopedDetachedTextureFramebufferAttachments`' scan over all framebuffer twins (`DirectGLES.cpp:6413-6425`), needs a "which slots are live" bit per kind.
|
||||
- `UnitBindingsSnapshot` / `CaptureUnitBindings` / `UnitBindingsUnchanged` (`DirectGLES.cpp:1366-1400`) **stays on the backend** — moving that debounce to the client is P3b/P4b (`ROADMAP.md:23`) — but its two `OwnerEquals` calls (`:1392`, `:1394`) become `{slot, gen}` compares.
|
||||
- `g_attachmentBackendIdGeneration` (`DirectGLES.cpp:1891`), `BufferImpl::g_bufferBackendIdGeneration` (`Managers.h:800`) and `InProcessTeardown()` are *driver-object* epochs, not identity, and survive untouched.
|
||||
- Purity gate C: `grep -rc pGLContext MobileGL/MG_Backend` stays empty. The `g_fbSlotCache` rewrite is the one place tempted to break it.
|
||||
|
||||
**Explicit destroy.** Today nothing tells the backend an object died except buffers (`BufferBackendOps::OnDestroy`, `BufferObject.h:103`, fired from `BufferObject.cpp:39-41`); `Managers.h:306-314` quantifies the resulting dead gigabytes. P2 adds the death notification for the six kinds by emitting `delete_*` from the frontend's `Mark*ForDeletion` path (`Core.cpp:116-140, 167-169, 279-307, 346-352, 1188-1190, 1213-1225, 1252-1254`) when the object's last `SharedPtr` drops — **not** when the name is marked, because a still-bound object keeps living (`TextureState.cpp:118-155`). The hook follows `BufferBackendOps`' shape.
|
||||
|
||||
### D14 — `MOBILEGL_PIPE_LEGACY_MEMOS`: the compile-time arm and the runtime selector
|
||||
|
||||
`ARCHITECTURE.md:367` is right that after phase C the `MOBILEGL_PIPE_PUSH` bitmap alone is not a valid A/B, because with a bit clear the backend still runs the re-keyed memo code. So:
|
||||
|
||||
| switch | kind | default | meaning |
|
||||
|---|---|---|---|
|
||||
| `MOBILEGL_PIPE_LEGACY_MEMOS` | **new CMake `option()`** + `-DMOBILEGL_PIPE_LEGACY_MEMOS=1` | **ON** | compiles the pre-handle arm (the six registries, `OwnerEquals`, the three `TwinLookupMemo`s, `g_fbSlotCache`, `ComputePipelineStateHash`, the address-keyed `VaoDrawMemo`) alongside the handle arm, both behind the same `PipeInputs` interface. Forced ON with a `message(STATUS)` when `MOBILEGL_PIPE_PUSH=OFF`, where it is the only arm. |
|
||||
| `MOBILEGL_PIPE_LEGACY_MEMOS` | runtime, `Features.PipeLegacyMemos` (`Config.h:356-360`, `ConfigLoader.cpp:258-259`) — **already exists**, tri-state, only an explicitly falsy value turns it off | true | true: a Track-H subsystem whose bitmask bit is clear falls back to the legacy arm. false: the legacy arm is never entered, and a Track-H subsystem whose bit is clear is a startup `Fatal{PipeLegacyMemosDisabled}`. This is the lever `HandleRecycleScenario`'s arms use. |
|
||||
| `MOBILEGL_PIPE_PUSH` | runtime `Uint64` bitmask, `Features.PipePush` (`Config.h:319-326`, `ConfigLoader.cpp:245`) — **first consumed in P2** | see below | per-subsystem selector. |
|
||||
|
||||
**The subsystem bit enum** (new, `MobileGL/MG_Pipe/MGPipe.h`, next to the call-class enum at `:31`):
|
||||
|
||||
```cpp
|
||||
inline constexpr Uint64 kMGPipeSubsystemRenderState = 1ull << 0;
|
||||
inline constexpr Uint64 kMGPipeSubsystemPixelPack = 1ull << 1;
|
||||
inline constexpr Uint64 kMGPipeSubsystemPatchState = 1ull << 2;
|
||||
inline constexpr Uint64 kMGPipeSubsystemVertexAttribDefaults = 1ull << 3;
|
||||
inline constexpr Uint64 kMGPipeSubsystemResidualValues = 1ull << 4;
|
||||
inline constexpr Uint64 kMGPipeSubsystemEsprytSlots = 1ull << 5; // Espryt 0b
|
||||
inline constexpr Uint64 kMGPipeSubsystemMagmaVertexInput = 1ull << 6; // Magma subsystem 4
|
||||
// bits 7..62 reserved for the later phases, allocated in ROADMAP order.
|
||||
// NOT a subsystem, a BEHAVIOUR: turn OFF client-side content addressing of CSOs, so every
|
||||
// pipeline-version change mints a fresh CSO and the map is never probed. This is the
|
||||
// negative control the CSO design is measured against (ROADMAP.md:18, ARCHITECTURE.md:367).
|
||||
inline constexpr Uint64 kMGPipeBehaviourNoCsoContentAddressing = 1ull << 63;
|
||||
inline constexpr Uint64 kMGPipeSubsystemsMigratedAtP2 = 0x7full; // bits 0..6
|
||||
```
|
||||
|
||||
**Default.** `Config.h:322-323` documents `0` as "pull everything", and that stays literally true. `ConfigLoader.cpp:245` becomes, under `#if MOBILEGL_PIPE_PUSH`, `QueryEnvUint64("MOBILEGL_PIPE_PUSH", kMGPipeSubsystemsMigratedAtP2)` and, in the pull build, keeps its `0` (where it is meaningless). So a push build with the knob unset runs every migrated subsystem, and `MOBILEGL_PIPE_PUSH=0` in the environment is the all-subsystems-pull control that reproduces P1's behaviour exactly. `QueryEnvUint64`'s decimal/`0x` contract (`ConfigLoader.cpp:167-192`) is unchanged; the Config.h comment gains the bit list because operators pass it as hex.
|
||||
|
||||
### D15 — How the pull build stays symbol-identical
|
||||
|
||||
Every P2 artefact lands in one of four places, and none of them touches the pull build:
|
||||
|
||||
1. **New sources compiled only under `MOBILEGL_PIPE_PUSH`**, appended inside the existing `if (MOBILEGL_PIPE_PUSH)` block (`CMakeLists.txt:462-468`): `MG_Pipe/MGPipeRenderStateSpans.cpp`, `MG_Pipe/PipeApply.cpp`, `MG_Impl/Pipe/{Tracker,CsoCache,SlotAllocator}.cpp`. `generated/PipeSpanTable.inc:66-67`'s two `extern` declarations cost the pull build nothing (a declaration emits no symbol).
|
||||
2. **`#if MOBILEGL_PIPE_PUSH` arms inside existing backend files** for the Track H re-keys, with the legacy arm under `#if MOBILEGL_PIPE_LEGACY_MEMOS` (D14). In the pull build only the legacy arm is compiled and it is textually today's code.
|
||||
3. **`MGP_NOTE_AGGREGATE` and the five aggregate generations** in `MG_State`, guarded the same way, so the pull build's state objects do not change size (D4).
|
||||
4. **Three new members in `RenderStateParameters` plus three `SET_CAPABILITY`/`RETURN_CAPABILITY` arms plus three `{}`**, which *are* in the pull build. This is the one deliberate exception, and it is bounded: the members fit an existing padding hole so no offset and no `sizeof` moves; the switch arms grow two functions; the `{}` grows one constructor. **G1 therefore admits exactly the resizes of `RenderState::SetCapability`, `RenderState::IsCapabilityEnabled` and `RenderState::RenderState()`, named in the commit message, and zero added/removed/renamed symbols.**
|
||||
|
||||
The check after every merge is `symbol_report.py --threshold 0`; anything outside that named set is a defect, not a rounding error.
|
||||
|
||||
### D16 — The dirty-surface mapping file and its gate
|
||||
|
||||
**New file `MobileGL/MG_Pipe/DirtySurface.def`**, one row per distinct mutator the scanner finds (73 today):
|
||||
|
||||
```
|
||||
// X(Mutator, Answer) - what publishes this frontend mutation to the backend.
|
||||
// Answer is one of the MGPipeDirty bit names, or:
|
||||
// kImmediate - the mutating function also reaches the backend in the same body, so the
|
||||
// mutation is published inline and needs no aggregate generation
|
||||
// kReverseChannel - not state: a write INTO the frontend from the backend's side (RecordError)
|
||||
// kNoBackendRead - no backend read point observes this state at all (with the read-point
|
||||
// inventory row that proves it)
|
||||
#define MGP_DIRTY_SURFACE_LIST(X) \
|
||||
X(RecordError, kReverseChannel) \
|
||||
X(SetActiveTextureUnit, kImmediate) \
|
||||
X(SetPatchVertices, kImmediate) \
|
||||
X(SetBlendColor, NEW_RENDER_STATE) \
|
||||
X(SetCapability, NEW_PIPELINE_STATE) \
|
||||
...
|
||||
```
|
||||
|
||||
`scripts/gen_pipe_dirty_surface.py` grows:
|
||||
- `--check`: parse `DirtySurface.def`, and exit 1 if any scanned mutator has no row, or any row names a mutator the scan no longer finds. Both directions, so a deleted mutator leaves no stale row.
|
||||
- `--self-test`: two canned negative controls (a mutator withheld from the def, a row naming a nonexistent mutator), each of which must trip; `trips == 0` is an error — the shape `check_include_closure.py:541-543` and `gen_pipe.py --self-test` already use.
|
||||
- the human report writes the mapped answer instead of `UNMAPPED`, and the summary line is regenerated into `docs/Disaggregated/MEASUREMENTS.md`'s §5 by the integrator.
|
||||
|
||||
`RecordError` is **exempted explicitly by a row**, not by a filter: it is 836 of the 926 calls (90 % of the surface) and it is a reverse channel (`Coverage.def:99`, `PipeInputs.h:574`). That leaves 72 real mutators over 90 real calls.
|
||||
|
||||
The scanner's three self-declared blind spots (`gen_pipe_dirty_surface.py:195-197` and its scan root) are recorded in the def's header comment as known gaps: a mutator inside a lambda is attributed to the enclosing function; a mutation published through a helper the entry point calls reads as deferred; and the scan root is `MG_Impl/GLImpl` only, so the four `MGP_NOTE_MUTATION` sites in `MG_State/GLState/TextureState/TextureState.h:85,98,111,133` are outside it entirely.
|
||||
|
||||
CI: `.github/workflows/test.yml:1524-1528` loses its "Informational" comment and becomes `python3 scripts/gen_pipe_dirty_surface.py --check && python3 scripts/gen_pipe_dirty_surface.py --self-test`. Cost: the `pipe-gates` job runs in ~10 s and has no build dependency (`test.yml:1480-1481`); this adds nothing measurable.
|
||||
|
||||
### D17 — Counters, and the rule against hot-path instrumentation
|
||||
|
||||
`ROADMAP.md:7` forbids committing hot-path instrumentation. **The tracker gets no timer.** The absolute-ns number comes from `DriverBench`'s `ns_per_op` (D.4), which times whole frames from outside the library.
|
||||
|
||||
Two new `CallClass` values only — `RenderStateCsoMints` and `RenderStateCsoBinds` — with short names `csom` / `csob`, added in the contract commit together with the `PipeStatsTest.cpp:260 CounterNamesAreStable` update that pins them. Everything else P2 needs already exists:
|
||||
|
||||
- `ByteClass::ResidualValueBlock` (`PipeStats.h:73-75`) — the placeholder P2 makes non-zero.
|
||||
- `RecordDrawPayloadBytes` + the 24-bucket histogram (`PipeStats.h:129,154`) — implemented, unit-tested, **called by nothing**; the tracker becomes its first emitter, one call per emitted draw payload.
|
||||
- the six memo gates (`PipeStats.h:107-122`) — unchanged names, and they are the honest reading of the before/after (`PipeStats.cpp:93-99`).
|
||||
- `CallClass::AccessorCalls` — **a warning for the report**: it is a set of static tallies at ~10 hot entry points (`PipeStats.cpp:76-88`), so a tracker that *relocates* reads out of those functions scores a lower `acc/draw` without having removed any work. P2's report must therefore lead with the gate hit/miss pairs and the CPU-time series, and quote `acc/draw` only alongside a re-audit of the tally constants (`DirectGLES.cpp:1421,1524,2043,2053,2977`; `VulkanRenderer.cpp:5009,5016,5274,5927,5934,6416,6449,6462`).
|
||||
|
||||
Every counting site keeps the `if (PipeStats::Enabled())` shape (`PipeStats.h:29`) so an off build pays one predicted branch.
|
||||
|
||||
### D18 — `HandleRecycleScenario`, and how it goes red before the re-key
|
||||
|
||||
New `MobileGL/MG_IntegrationTest/Scenarios/HandleRecycleScenario.cpp`, registered in `MG_IntegrationTest/CMakeLists.txt` (source list from `:55`), following `PipeVerifyArmingScenario` / `PoisonOmissionScenario` as the template for an always-on negative control (`CMakeLists.txt:700-725`).
|
||||
|
||||
**What it reproduces**, through public GL only: delete a VAO that a backend memo slot holds; immediately create a replacement the allocator is very likely to place at the same heap address (the `void* volatile` sink trick from `MG_Test/State/ObjectLifetimeIdTest.cpp:44`) **and** give it a byte-identical attribute configuration so the content hash matches too; bind a *different* buffer to it; draw; read back and assert the pixels come from the new buffer (the red/green quad readback of `Scenarios/CrossFrameBufferScenario.cpp`). The same shape is then repeated for a texture (against `g_backendTextureObjects`) and a framebuffer.
|
||||
|
||||
**Three ctest arms**, all always-on:
|
||||
|
||||
| arm | environment | expected |
|
||||
|---|---|---|
|
||||
| `…HandleRecycleScenario.Handles` | `MOBILEGL_PIPE_PUSH` default (bits 5 and 6 set), `MOBILEGL_PIPE_LEGACY_MEMOS=0` | **green** — the `{slot, gen}` key cannot alias |
|
||||
| `…HandleRecycleScenario.Legacy` | `MOBILEGL_PIPE_PUSH=0`, legacy arm | **green** — today's `lifetimeId` + `weak_ptr` guards work |
|
||||
| `…HandleRecycleScenario.AbaControl` | `MOBILEGL_PIPE_PUSH=0` **and** `MOBILEGL_PIPE_HANDLE_ABA_CONTROL=1` | **green by asserting the corruption** — the knob makes `VertexInputStateFactory::ComputeHash` hash `attr.Buffer.get()` instead of `GetLifetimeId()` and makes `LookupVaoDrawMemo` skip the `vaoLifetimeId` compare, i.e. reverts exactly the two guards the re-key replaces; the scenario asserts the *wrong* pixels, so if the scenario ever stops reproducing the ABA it fails |
|
||||
|
||||
`MOBILEGL_PIPE_HANDLE_ABA_CONTROL` is a new `Bool Features.PipeHandleAbaControl` under `#if MOBILEGL_PIPE_PUSH` (so it cannot exist in a shipping pull build), parsed with `QueryEnvFlag`, documented next to `MOBILEGL_PIPE_VERIFY_CORRUPT` as negative control C. That third arm is what makes "`HandleRecycleScenario` 绿且重键前红" (`ROADMAP.md:18`) an always-on CI fact instead of a one-off manual demonstration.
|
||||
|
||||
### D19 — G7: the setter-consistency test and its negative control
|
||||
|
||||
`MobileGL/MG_Test/Pipe/RenderStateSpansTest.cpp` (contract commit creates it; package A fills it):
|
||||
|
||||
- `ChunkTablePartitionsTheBlock` — the sorted/non-overlapping/complete assertion is a `static_assert` in `MGPipeRenderStateSpans.cpp`; the test re-asserts it at run time so a reader sees it, and additionally asserts `kMGPipePipelineChunks` covers every member named in `kMGPipePipelineStateMembers` (`generated/PipeSpanTable.inc:34-59`).
|
||||
- `SetterConsistency` — the G7 test. Drive **every public setter** of `RenderState` (the 25 Group-A setters and 22 Group-B setters catalogued in `scout-render-state.md` §2.1–2.4, plus `SetPixelStoreParam`, which must move neither counter), each with a value that differs from the current one, and assert `MGPipeComputePipelineSubsetHash` moved **⟺** `GetPipelineStateVersion()` moved. Special cases the test must drive individually, or it does not test what it claims:
|
||||
- `SetStencilFunc` **twice**: once changing only `Ref` (version moves, hash must not — `RenderState.cpp:629-642`, the `++m_pipelineStateVersion` at `:641` is conditional on `Func` moving at `:636`), once changing `Func` (both move).
|
||||
- `SetPolygonMode` with only the back face changing (both move: `PolygonModeBack` is in P5).
|
||||
- `SetCapability(ClipDistance0..7)` (`RenderState.cpp:360-380`): version moves, pipeline version does **not**, hash must not.
|
||||
- All 25 `SET_CAPABILITY` names including D3's three new ones.
|
||||
- `SetScissorBox` including the `ScissorBoxWrittenMask` transition (`:918-941`).
|
||||
- `DerivationMatchesTheFrontendGetters` — D5's 29 derived values against `GLContext`'s getters after each setter.
|
||||
- `DynamicChunksCoverMagmasDynamicTailKey` — every field `DynamicTailKey` (`VulkanRenderer.cpp:341-395`) reads is inside `kMGPipeDynamicChunks`.
|
||||
|
||||
**The negative control (G7 in the gate list, `scripts/g7_negative_control.sh`)**: move `ColorMasks` out of chunk P1 into a new dynamic chunk. The partition stays complete so it still compiles; `SetColorMask` then bumps `m_pipelineStateVersion` without moving the hash and `SetterConsistency` fails naming `SetColorMask`. The script patches, builds, expects a non-zero `ctest` rc, and reverts. It is run by the integrator at D.3 and is not a CI lane (it rebuilds the library).
|
||||
|
||||
### D20 — Naming, layering and generated-file discipline
|
||||
|
||||
- New namespaces: none. Everything is `MobileGL::MG_Pipe`.
|
||||
- `MG_Pipe/PipeApply.h` forward-declares only; `PipeApply.cpp` may include `MG_State/GLState/RenderState/RenderState.h` (a `.cpp` in the shared directory, no cycle: `RenderState.h` includes `MGPipeValueTypes.h`, not `PipeApply.h`). Run `python3 scripts/check_include_closure.py` after adding it; if it objects, the file moves to `MG_Impl/Pipe/` (the client side is unrestricted) and nothing else changes.
|
||||
- `PipeCalls.def` is **not** edited: every call P2 emits already has an opcode (`:92-94` `CreateRenderState`/`BindRenderState`/`DeleteRenderState`, `:106` `SetDynamicState`, `:125` `SetResidualValueState`, plus `SetPixelPackState`/`SetPatchState`/`SetVertexAttribDefaults`). Opcodes are file positions, so new calls may only be appended and retired calls keep their slot (`ARCHITECTURE.md:75`); `MGP_CALL_LIST_DOCUMENTED_COUNT = 71` stays pinned by `PipeCatalogueTest.cpp`.
|
||||
- Generated files are regenerated and committed; CI diffs them (`test.yml:1492-1495`).
|
||||
- Commit messages: single-line `[Type] (Scope): description`. Never add `Co-Authored-By` or any other attribution line.
|
||||
- Logging: `MGLOG_D` for anything non-critical; `MGLOG_I` only where `PipeStats.cpp:225-229` already justifies it. No stdio anywhere under `MG_Backend`/`MG_State` (the `pipe-gates` grep, `test.yml:1515-1522`).
|
||||
|
||||
|
||||
---
|
||||
|
||||
## C. Packages
|
||||
|
||||
**Five packages on five branches, five WSL worktrees.** The split is chosen by the code, not by P1's precedent: the value types + the chunk table + the applier are one shared contract everything else compiles against; the tracker and its caches are one client-side unit that touches no backend file; the two Track H slices are per-backend and share only the `SlotAllocator` (which is therefore in the contract); the gates, the scenario, the CI file and the measurement plumbing are cross-cutting tooling that must be able to land before the thing it gates.
|
||||
|
||||
**Branch points.** `p2/contract` from `feat/disaggregated@48268068`. Its single commit `c0` is the contract; `p2/{tracker, espryt, magma, gates}` all branch from the tag `p2/contract`, so their push builds compile and link while A finishes. `p2/spans` continues on from `c0`.
|
||||
|
||||
**Tree creation.** `bash scratchpad/wf4/wsl_p1_tree.sh` copied to `wsl_p2_tree.sh` with `p1`→`p2` throughout, then per slug:
|
||||
|
||||
```sh
|
||||
bash ~/w7/wsl_p2_tree.sh contract 48268068 verify # first, and it must finish before the rest
|
||||
bash ~/w7/wsl_p2_tree.sh spans p2/contract verify
|
||||
bash ~/w7/wsl_p2_tree.sh tracker p2/contract verify
|
||||
bash ~/w7/wsl_p2_tree.sh espryt p2/contract
|
||||
bash ~/w7/wsl_p2_tree.sh magma p2/contract
|
||||
bash ~/w7/wsl_p2_tree.sh gates p2/contract verify
|
||||
```
|
||||
|
||||
Each tree gets three build directories, flags identical to `~/w7/pipe/build-linux`:
|
||||
|
||||
```sh
|
||||
# pull (the G1 build)
|
||||
cmake -S . -B build-linux -G Ninja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
|
||||
-DCMAKE_C_COMPILER_LAUNCHER=ccache -DCMAKE_CXX_COMPILER_LAUNCHER=ccache -DCMAKE_BUILD_TYPE=Release \
|
||||
-DMOBILEGL_LOG_ACTIVE_LEVEL=MOBILEGL_LOG_LEVEL_INFO -DMOBILEGL_BUILD_TEST=ON -DMOBILEGL_BUILD_INTEGRATION_TEST=ON \
|
||||
-DMOBILEGL_BUILD_BENCHMARK=OFF -DMOBILEGL_ITEST_EGL_VENDOR=/usr/share/glvnd/egl_vendor.d/50_mesa.json \
|
||||
-DMOBILEGL_ITEST_VK_ICD=/usr/share/vulkan/icd.d/lvp_icd.json -DCMAKE_EXPORT_COMPILE_COMMANDS=ON \
|
||||
-DCMAKE_POLICY_VERSION_MINIMUM=3.5
|
||||
# push
|
||||
cmake -S . -B build-push ... same ... -DMOBILEGL_PIPE_PUSH=ON
|
||||
# verify
|
||||
cmake -S . -B build-verify ... same ... -DMOBILEGL_PIPE_VERIFY=ON -DMOBILEGL_ITEST_REQUIRE_GPU=ON
|
||||
# benchmark (package E and the integrator only; DriverBench needs it and it is Linux-desktop only)
|
||||
cmake -S . -B build-bench ... same ... -DMOBILEGL_BUILD_BENCHMARK=ON
|
||||
```
|
||||
|
||||
### C.0 Package A — `p2/contract` then `p2/spans` (tree `~/w7/p2-contract`, `~/w7/p2-spans`)
|
||||
|
||||
**Commit `c0` — the contract. Nothing in it may change after the tag without telling the other four packages.**
|
||||
|
||||
| action | file | what |
|
||||
|---|---|---|
|
||||
| MODIFY | `MobileGL/MG_Pipe/MGPipeValueTypes.h` | D3.1 — the three new `Bool`s in the `[581,584)` hole, between `ColorMasks` and `ClearColor`. The `sizeof == 1168` assert at `:541` is the check. |
|
||||
| MODIFY | `MobileGL/MG_Pipe/PipeFields.def` | D3.2 — three rows in `MGP_FIELDS_RenderStateParameters` (`:230-247`); `MGP_FIELDS_ResidualValueBlock` (`:147-148`) drops to `F(CapabilityBits)`; `MGP_COVERAGE_EMITTED_LIST` consumers (D5) |
|
||||
| MODIFY | `MobileGL/MG_State/GLState/RenderState/RenderState.{h,cpp}` | D3.3 (three `SET_CAPABILITY` + three `RETURN_CAPABILITY` arms, in `CapabilityInput` order) and D3.4 (`{}` on `m_parameters`, `m_pixelStorePackParameters`, `m_pixelStoreUnpackParameters`) |
|
||||
| MODIFY | `MobileGL/MG_Pipe/MGPipeTypes.h` | D9 — `ResidualValueBlock` down to `Uint64 CapabilityBits`, `MGL_RESIDUAL_BLOCK_SIZE` 1248 → 8; fix the `MGPDynamicState` comment (`:232-235`) to move "sample coverage" to the pipeline half (D6) |
|
||||
| MODIFY | `MobileGL/MG_Pipe/MGPipe.h` | D14 — the subsystem/behaviour bit constants |
|
||||
| CREATE | `MobileGL/MG_Pipe/MGPipeRenderStateSpans.{h,cpp}` | D6 — the chunk table computed with `offsetof`, the partition `static_assert`s, `MGPipeComputePipelineSubsetHash()`, and `VulkanRenderer.cpp:4780-4794`'s enumeration comment moved in as provenance |
|
||||
| CREATE | `MobileGL/MG_Pipe/PipeApply.{h,cpp}` | D2 + D5 — the seven `MGPipeApply*` entry points, the per-context CSO store, `MGPipeDeriveRenderStateFields()` |
|
||||
| CREATE | `MobileGL/MG_Impl/Pipe/SlotAllocator.{h,cpp}` | D13 — per-kind `{slot, gen}` allocator, free list + high-water, `lifetimeId → slot` maps, debug wrap assert (in the contract because both C and D need it) |
|
||||
| MODIFY | `scripts/gen_pipe.py` | extend `PIPELINE_STATE_MEMBERS` (`:75-99`) to the D6 set and rewrite `PipeSpanTable.inc`'s "deliberately absent" block (`:1045-1058`) to record what P2 decided; emit the `ResidualValueBlock` `offsetof` asserts; emit `kMGPipeFieldEmittedBy[]` from `MGP_COVERAGE_EMITTED_LIST` |
|
||||
| MODIFY | `MobileGL/MG_Pipe/generated/*.inc` | regenerate and commit |
|
||||
| MODIFY | `MobileGL/MG_Pipe/Coverage.def` | `MGP_COVERAGE_EMITTED_LIST` (D5); the `GetProvokingVertexMode` note at `:74-77` is answered ("in the pipeline half as of P2") |
|
||||
| MODIFY | `CMakeLists.txt` | the three new sources inside `if (MOBILEGL_PIPE_PUSH)` (`:462-468`); `option(MOBILEGL_PIPE_LEGACY_MEMOS … ON)` + `-DMOBILEGL_PIPE_LEGACY_MEMOS=1` (D14), forced ON with a `message(STATUS)` when `MOBILEGL_PIPE_PUSH=OFF` |
|
||||
| MODIFY | `MobileGL/Config.h`, `MobileGL/ConfigLoader.cpp` | D14 — the bitmask default under `#if MOBILEGL_PIPE_PUSH`, the bit list in the comment; D18 — `Features.PipeHandleAbaControl` |
|
||||
| MODIFY | `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | D17 — `CallClass::{RenderStateCsoMints, RenderStateCsoBinds}` + short names `csom`/`csob` |
|
||||
| MODIFY | `MobileGL/MG_Test/Util/PipeStatsTest.cpp` | pin the two new names in `CounterNamesAreStable` (`:260`) and the summary-line test (`:137`) |
|
||||
| CREATE (stubs) | `MobileGL/MG_Test/Pipe/{RenderStateSpansTest, TrackerTest, SlotAllocatorTest, CsoCacheTest}.cpp` | each a compiling file with one placeholder `TEST`, so the packages that own their contents never edit `MG_Test/Pipe/CMakeLists.txt` |
|
||||
| MODIFY | `MobileGL/MG_Test/Pipe/CMakeLists.txt` | register the four stubs, `LABELS unit` |
|
||||
| MODIFY | `MobileGL/MG_Test/Pipe/PipeCatalogueTest.cpp` | `:111-112` residual size 1248 → 8; `PipelineSubsetMembersArePinned` (`:354-358`) count 24 → the D6 count |
|
||||
|
||||
Ordered steps for `c0`: value types and `RenderState` first (build pull, confirm `sizeof` still 1168 and `symbol_report --threshold 0` shows only the three named resizes) → `MGPipeTypes.h`/`PipeFields.def`/generator/regenerate → the three new source files with complete signatures and *stub bodies for `PipeApply`'s derivation* (so B/C/D link) → CMake/Config → tests. Then **tag `p2/contract`** and tell the other packages.
|
||||
|
||||
Message: `[Feat] (Pipe): land the P2 contract - real storage for the three swallowed capabilities, the render-state chunk table and its subset hash, the in-process applier, the slot allocator, the subsystem bitmask and the residual ratchet down to 8`.
|
||||
|
||||
**Then `p2/spans` continues** with the work that only A can do:
|
||||
|
||||
- `c1`: `MGPipeDeriveRenderStateFields()` in full — the 29 derivations of D5, each transcribed from its `RenderState` getter. Message: `[Feat] (Pipe): derive every render-state PipeInputs field from the assembled working block instead of pulling it again from GLContext`.
|
||||
- `c2`: `RenderStateSpansTest.cpp` in full — D19's four tests. Message: `[Test] (Pipe): walk every RenderState setter and assert the pipeline-subset hash moves exactly when the pipeline version does`.
|
||||
- `c3`: `SlotAllocatorTest.cpp` — slot reuse bumps `Gen` and only slot reuse does; a freed slot is handed back before the high-water grows; `lifetimeId → slot` survives a recycled heap address (the `void* volatile` sink of `ObjectLifetimeIdTest.cpp:44`); `kMGPipeFirstAllocatableSlot` is never handed out as 0; the composite `ShaderCso` band (`MGPipeHandles.h:83-97`) is not handed out by the ordinary allocator. Message: `[Test] (Pipe): pin the slot allocator's identity contract - gen moves only on reuse and a recycled address never reproduces a handle`.
|
||||
|
||||
**Verification (`~/w7/p2-spans`)**
|
||||
```sh
|
||||
python3 scripts/gen_pipe.py --check && python3 scripts/gen_pipe.py --self-test
|
||||
python3 scripts/check_include_closure.py
|
||||
cmake --build build-linux --parallel 28 && ctest --test-dir build-linux -L unit --no-tests=error --output-on-failure
|
||||
python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||||
# expect: added 0 / removed 0 / renamed 0; resized = exactly RenderState::{RenderState,SetCapability,IsCapabilityEnabled}
|
||||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||||
cmake --build build-verify --parallel 28 && ctest --test-dir build-verify -L unit --no-tests=error
|
||||
bash scripts/g7_negative_control.sh build-push # must report "negative control tripped"
|
||||
git show $BASE:MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp | awk '/^ namespace RenderStateImpl \{/,/^ \} \/\/ namespace RenderStateImpl/' | sha256sum
|
||||
awk '/^ namespace RenderStateImpl \{/,/^ \} \/\/ namespace RenderStateImpl/' MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp | sha256sum # equal: G5
|
||||
```
|
||||
|
||||
### C.1 Package B — `p2/tracker` (tree `~/w7/p2-tracker`, branch `p2/tracker`, from `p2/contract`)
|
||||
|
||||
**Files**
|
||||
|
||||
| action | file | what |
|
||||
|---|---|---|
|
||||
| CREATE | `MobileGL/MG_Impl/Pipe/Tracker.{h,cpp}` | D4 — `MGPipeDirty`, the tracker struct, `m_lastPushed[]` with the widened `Uint16` shutters, the per-class dirty walk, the per-bit fire counters |
|
||||
| CREATE | `MobileGL/MG_Impl/Pipe/CsoCache.{h,cpp}` | D7 — 64-entry LRU, hash → probe → `memcmp` → handle, `DeleteRenderState` on evict, the `kMGPipeBehaviourNoCsoContentAddressing` arm |
|
||||
| CREATE | `MobileGL/MG_Impl/Pipe/SetHashSuppressor.h` | D11 |
|
||||
| MODIFY | `MobileGL/MG_Impl/Pipe/PipeFill.{h,cpp}` | D1 — `MGPipeFillForVerb` → `MGPipeValidateForVerb`, the five-step body, the residual fill restricted by `kMGPipeFieldEmittedBy[]`; the `MGP_FILL` macro's expansion |
|
||||
| MODIFY | `MobileGL/MG_Pipe/PipeMutation.h` | D4 — `MGP_NOTE_AGGREGATE(Aggregate)`, `((void)0)` in the pull build |
|
||||
| MODIFY | `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayState.h, FramebufferState/FramebufferState.h, TextureState/TextureState.h, BufferState/BufferState.h}` and their `.cpp`s | D4 — the five aggregate generations and their ~20 bump lines, all `#if MOBILEGL_PIPE_PUSH` |
|
||||
| MODIFY | `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayObject.cpp, FramebufferState/FramebufferObject.cpp, TextureState/{TextureObject,TextureObject2DCube}.cpp, SamplerState/SamplerObject.cpp, BufferState/BufferObject.cpp}` | the `MGP_NOTE_AGGREGATE` statements at the bump points listed in D4 |
|
||||
| CREATE | `MobileGL/MG_Pipe/DirtySurface.def` | D16 — 73 rows |
|
||||
| MODIFY | `scripts/gen_pipe_dirty_surface.py` | D16 — `--check`, `--self-test`, mapped output |
|
||||
| MODIFY | `MobileGL/MG_Pipe/FillPoints.def` | tighten the fill table: re-check the **8 statically over-approximated rows** (`MEASUREMENTS.md:115`) named in the three groups at `MEASUREMENTS.md:114` before narrowing anything, and record the verdict per row in the def's comment |
|
||||
| MODIFY | `MobileGL/MG_Test/Pipe/{TrackerTest,CsoCacheTest}.cpp` | contents (the stubs are A's) |
|
||||
|
||||
**Ordered steps**
|
||||
|
||||
1. `b1`: the five aggregate generations + `MGP_NOTE_AGGREGATE`, with a unit test that each bump point moves its aggregate and nothing else. Build pull, `symbol_report --threshold 0` unchanged. Message: `[Feat] (State): give the frontend five aggregate generations so a tracker can answer "did any bound texture/buffer/attachment/attribute move" with one Uint64 compare`.
|
||||
2. `b2`: `Tracker.{h,cpp}` + the `MGPipeValidateForVerb` rewrite, emitting **nothing** yet (dirty computed, counted, then the full P1 residual fill runs). Push build green on `unit` and `integration-gpu`; verify build green. This step is the safety net: it proves the walk costs nothing semantically before anything is removed. Message: `[Feat] (Pipe): compute the per-verb dirty mask at the validate point and count how often each bit fires`.
|
||||
3. `b3`: `CsoCache` + `create/bind_render_state` + `set_dynamic_state` emission, and the residual fill drops the 29 derived fields. **This is where the render-state family stops being pulled.** Message: `[Feat] (Pipe): mint render-state CSOs on the pipeline subset and send only the changed dynamic chunks - the steady-state cost of the whole render-state family is now two Uint16 compares`.
|
||||
4. `b4`: `set_pixel_pack_state`, `set_patch_state`, `set_vertex_attrib_defaults` + `SetHashSuppressor` wired to the last of the three. Message: `[Feat] (Pipe): push pixel-pack, patch and vertex-attribute-default state as their own calls, the last one behind the set-hash suppressor`.
|
||||
5. `b5`: `set_residual_value_state` + the tripwire (D9). Message: `[Feat] (Pipe): carry what has no call yet in the residual value block and abort when it disagrees with the assembled state`.
|
||||
6. `b6`: `DirtySurface.def` + the scanner's `--check`/`--self-test`; the `FillPoints.def` tightening and the 8-row re-check. Message: `[Feat] (Pipe): map every frontend mutator onto the aggregate generation that publishes it, and make the dirty-surface scanner a gate`.
|
||||
7. `b7`: `TrackerTest.cpp` and `CsoCacheTest.cpp`.
|
||||
|
||||
**Tests to add**
|
||||
- `TrackerTest.SteadyStateEmitsNothing`: two identical draws in a row emit zero calls (assert the `PipeStats` call counters do not move).
|
||||
- `TrackerTest.BlendToggleReusesTwoCsos`: `enable/draw/disable/draw` × N mints exactly **2** CSOs and issues 2N binds — the Blaze3D shape (`ARCHITECTURE.md:151`).
|
||||
- `TrackerTest.ViewportDoesNotMintACso`: `glViewport` in a loop mints 0 CSOs and emits N `set_dynamic_state`s carrying only chunk D0 — the regression `RenderState.h:165-170` records.
|
||||
- `TrackerTest.WrapAroundRePushesButNeverMisses`: drive `m_version` past 65535 and assert no missed emission.
|
||||
- `TrackerTest.AggregateGenerationCatchesABoundTextureMoving`: bind a texture, draw, `glTexSubImage` it, draw again — `NEW_SAMPLER_VIEWS` fires on the second draw. (This is the "dirty bit that fires too rarely" direction, which the P1 verify comparator **cannot** see because it compares O-class fields by identity only, `PipeInputs.h:248-249`.)
|
||||
- `CsoCacheTest.LruEvictsTheOldestAndEmitsDelete`; `CsoCacheTest.HashCollisionDoesNotAliasTwoStates` (inject a forced collision through a test seam and assert the `memcmp` rejects it); `CsoCacheTest.ContentAddressingOffMintsEveryTime`.
|
||||
|
||||
**Constraints**: B touches **no** file under `MG_Backend/`. B does not edit `MG_Pipe/{MGPipeValueTypes.h, MGPipeTypes.h, MGPipeRenderStateSpans.*, PipeApply.*}` or `scripts/gen_pipe.py` (A owns them). B does not edit `.github/workflows/test.yml` (E owns it) — the CI step for the dirty-surface gate is E's, and B's scanner change must therefore be backward compatible with `--summary` until E lands.
|
||||
|
||||
**Verification (`~/w7/p2-tracker`)**
|
||||
```sh
|
||||
python3 scripts/gen_pipe_dirty_surface.py --check && python3 scripts/gen_pipe_dirty_surface.py --self-test
|
||||
python3 scripts/gen_pipe.py --check
|
||||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
|
||||
cmake --build build-verify --parallel 28 && ctest --test-dir build-verify -L integration-verify --no-tests=error -j 4 --output-on-failure
|
||||
MOBILEGL_PIPE_VERIFY=1 python3 ~/w7/retrace_gate.py --tree ~/w7/p2-tracker --lib build-verify/libMobileGL.so --out ~/w7/retrace-out/p2-tracker -j 4
|
||||
grep -l 'Fatal{' ~/w7/retrace-out/p2-tracker/*/mobilegl.log # empty
|
||||
# the per-subsystem A/B, which must be pixel-identical to the all-pull arm:
|
||||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4
|
||||
```
|
||||
|
||||
### C.2 Package C — `p2/espryt` (tree `~/w7/p2-espryt`, branch `p2/espryt`, from `p2/contract`)
|
||||
|
||||
**Files**: `MobileGL/MG_Backend/DirectGLES/{DirectGLES.cpp, Managers.h, Managers.cpp}`, new `MobileGL/MG_Backend/DirectGLES/SlotTables.h`, and `MobileGL/MG_Test/SanityTest.cpp` (the `ScopedDirectGLESTextureBindings` fixture only).
|
||||
|
||||
**Ordered steps**
|
||||
|
||||
1. `e1`: `SlotTables.h` — per-kind dense arrays with a live bitset, save/reset/restore, and the `EnsureProcessTeardownSentinel()` arming moved onto first insertion. Both arms compile; nothing uses the new one yet.
|
||||
2. `e2`: the explicit-destroy hook — `delete_*` emitted when a frontend object's last `SharedPtr` drops, following `BufferBackendOps`' shape (`BufferObject.h:76-103`, `BufferObject.cpp:26-41`). This must land **before** the tables are switched over, because the tables have no GC.
|
||||
3. `e3`: switch the six kinds over behind `kMGPipeSubsystemEsprytSlots`, deleting `OwnerEquals`, the three `TwinLookupMemo`s, `UnitSamplerLookupMemo`'s `WeakPtr` test, the seven `CollectGarbageIfNeeded` calls, `SyncTextureObjectToBackend`'s by-value copy and second `Find`, and the four `defaultFBO` identity compares (D13). Keep the legacy arm under `MOBILEGL_PIPE_LEGACY_MEMOS`.
|
||||
4. `e4`: `g_fbSlotCache` / `GetFramebufferBindingSlotFast` → a plain `MGB_CTX->GetFramebufferBindingSlot(target)` read at all five call sites (`DirectGLES.cpp:1613, 1907, 2745, 2860, 2935`), closing the P1 poison bypass.
|
||||
5. `e5`: the `SanityTest.cpp` fixture.
|
||||
|
||||
Messages: `[Refactor] (Espryt): key every backend twin on {slot, gen} instead of the frontend object's heap address - six registries become slot arrays and eleven identity memos go away`; `[Fix] (Espryt): tell the backend when a frontend object dies instead of discovering it in a garbage sweep`; `[Refactor] (Espryt): read the framebuffer binding slot through MGB_CTX at every call site instead of caching a raw pointer past the poison`.
|
||||
|
||||
**Must not break** — the D13 list; each item has a named existing test (`SanityTest.cpp:2575-2596, 2650-2665, 2757-2790, 3020-3062`; `Scenarios/{SampledSetStalenessScenario, CrossFrameBufferScenario, VertexArrayEnableDisableScenario, VertexAttribBindingScenario, MultiDrawScenario, ResidentIndexScenario}.cpp`).
|
||||
|
||||
**Verification (`~/w7/p2-espryt`)**
|
||||
```sh
|
||||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||||
grep -rc 'pGLContext' MobileGL/MG_Backend | grep -v ':0$' # empty (G13)
|
||||
grep -c 'OwnerEquals\|TwinLookupMemo\|g_fbSlotCache\|CollectGarbageIfNeeded' MobileGL/MG_Backend/DirectGLES/DirectGLES.cpp
|
||||
# -> only the occurrences inside the MOBILEGL_PIPE_LEGACY_MEMOS arm
|
||||
cmake --build build-push --parallel 28
|
||||
ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R 'DirectGLES'
|
||||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R 'DirectGLES' # legacy arm, same names, same result
|
||||
python3 ~/w7/retrace_gate.py --tree ~/w7/p2-espryt --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p2-espryt -j 4 --backend DirectGLES --ssim 0.99
|
||||
```
|
||||
|
||||
### C.3 Package D — `p2/magma` (tree `~/w7/p2-magma`, branch `p2/magma`, from `p2/contract`)
|
||||
|
||||
**Files**: `MobileGL/MG_Backend/DirectVulkan/Renderer/{VulkanRenderer.h, VulkanRenderer.cpp, VertexInputStateFactory.h, VertexInputStateFactory.cpp}` and `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h` (deleting the three backend-memo triples — a different file from the four state containers B edits).
|
||||
|
||||
**Ordered steps**
|
||||
|
||||
1. `m1`: re-key `GetOrCreatePipeline`'s memo on the bound CSO handle and delete the cached-hash fields (D12.1–12.2), behind `kMGPipeSubsystemRenderState`. Message: `[Refactor] (Magma): key the pipeline memo on the render-state CSO handle and stop recomputing a hash the client already computed`.
|
||||
2. `m2`: `ApplyDynamicDrawStateTail` re-sourced (D12.3) plus the `DynamicTailKey`-coverage unit test. Message: `[Refactor] (Magma): drive the dynamic tail from the pushed dynamic version so a pipeline-only change stops invalidating it`.
|
||||
3. `m3`: subsystem 4 — `ComputeHash`'s `bufferKey`, `VaoDrawMemo` slot-indexed, behind `kMGPipeSubsystemMagmaVertexInput` (D12.4). Message: `[Refactor] (Magma): key the vertex-input cache and the VAO draw memo on {slot, gen} instead of a lifetime id and a heap address`.
|
||||
4. `m4`: delete `SetBackendStateMemo`/`SetBackendAuxMemo`/`SetBackendHashMemo` and their storage from the frontend VAO, and the eviction-epoch dance with them (D12.5). Message: `[Refactor] (State, Magma): take the backend's raw pointers out of the frontend VAO - the state memo is deleted, the hash and aux memos become server-side per-slot fields`.
|
||||
|
||||
**Verification (`~/w7/p2-magma`)**
|
||||
```sh
|
||||
cmake --build build-linux --parallel 28 && python3 scripts/symbol_report.py --before ~/w7/p2-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0
|
||||
grep -rn 'BackendStateMemo\|BackendAuxMemo\|m_backendHashMemo' MobileGL/MG_State MobileGL/MG_Backend # only ProgramObject's, which is out of scope
|
||||
cmake --build build-push --parallel 28 && ctest --test-dir build-push -L unit --no-tests=error --output-on-failure
|
||||
ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R 'DirectVulkan'
|
||||
MOBILEGL_PIPE_PUSH=0 ctest --test-dir build-push -L integration-gpu --no-tests=error -j 4 -R 'DirectVulkan'
|
||||
python3 ~/w7/retrace_gate.py --tree ~/w7/p2-magma --lib build-push/libMobileGL.so --out ~/w7/retrace-out/p2-magma -j 4 --backend DirectVulkan --ssim 0.99
|
||||
```
|
||||
|
||||
### C.4 Package E — `p2/gates` (tree `~/w7/p2-gates`, branch `p2/gates`, from `p2/contract`)
|
||||
|
||||
Cross-cutting tooling. E branches from the contract and lands **last**, but writes `HandleRecycleScenario` **first** so that its `AbaControl` arm is proven red before C and D exist — that is the "重键前红" evidence.
|
||||
|
||||
| action | file | what |
|
||||
|---|---|---|
|
||||
| CREATE | `MobileGL/MG_IntegrationTest/Scenarios/HandleRecycleScenario.cpp` | D18 |
|
||||
| CREATE | `MobileGL/MG_IntegrationTest/Scenarios/CsoContentAddressingScenario.cpp` | G12 — two entries, bit set vs clear, asserting `RenderStateCsoMints`/`Binds` move in the expected direction |
|
||||
| MODIFY | `MobileGL/MG_IntegrationTest/CMakeLists.txt` | register both scenarios (source list from `:55`) and the five environments, following `:695-725` |
|
||||
| MODIFY | `android-plugin/app/src/trace/cpp/trace_benchmark.{hpp,cpp}` | D.4.1 — a second per-frame series, `CLOCK_THREAD_CPUTIME_ID`, alongside the wall clock at `trace_benchmark.cpp:74-77`; `Report` gains `std::vector<double> frameCpuMs` next to `frameMs` (`trace_benchmark.hpp:32-39`) |
|
||||
| MODIFY | `android-plugin/app/src/trace/cpp/trace_replay_core.{hpp,cpp}` | `SummarizeBenchmark` (`:832-865`) reused verbatim for the CPU series; `WriteBenchmarkJson` (`:867-899`) gains `meanFrameCpuMs`, `medianFrameCpuMs`, `p95FrameCpuMs` and `frameCpuTimesMs[]` beside `frameTimesMs[]` (`:889-896`) |
|
||||
| MODIFY | `tools/trace_replay/run_android_retrace_local.py` | `format_benchmark` (`:228-237`) prints the CPU numbers |
|
||||
| CREATE | `tools/device_bench/devices/{xiaomi-adreno830.env, oppo-mali.env}` | the two missing device profiles (only `odinlite.env` exists) |
|
||||
| MODIFY | `MobileGL/MG_Benchmark/Driver/CMakeLists.txt` | a second ctest entry `DriverBenchStateToggle` running `mc_state_toggle` (`:14` currently runs only `draw_tiny`), `LABELS benchmark` |
|
||||
| CREATE | `scripts/g7_negative_control.sh` | D19 |
|
||||
| MODIFY | `.github/workflows/test.yml` | `pipe-gates`: dirty-surface `--check` + `--self-test` in place of `--summary` (`:1524-1528`); a `ctest -L unit` step on the verify runtime in `integration-verify` (so G6/G10's push-only unit tests actually run in CI); the two new scenario entries |
|
||||
|
||||
Messages: `[Test] (Pipe): reproduce the handle ABA through public GL and prove the pre-rekey guards are what stops it`; `[Feat] (Trace): record per-frame thread CPU time beside wall time so a paired A/B can be read as CPU cost`; `[CI] (Pipe): make the dirty-surface report a gate and run the push-only unit tests on the verify runtime`.
|
||||
|
||||
**Verification (`~/w7/p2-gates`)**
|
||||
```sh
|
||||
cmake --build build-verify --parallel 28
|
||||
ctest --test-dir build-verify -R 'HandleRecycle' --no-tests=error --output-on-failure
|
||||
# on the contract tree, before C/D: .Legacy and .AbaControl must pass, .Handles must SKIP (subsystem not implemented)
|
||||
cmake --build build-bench --parallel 28 && ctest --test-dir build-bench -L benchmark --no-tests=error
|
||||
cd tools/trace_replay && cmake --build ../../build-retrace && ./build-retrace/trace_replay_cli --benchmark ... # desktop pre-flight of the CPU series
|
||||
```
|
||||
|
||||
### C.5 File-ownership table
|
||||
|
||||
No two packages edit the same file. The contract (`p2/contract`) is one commit that all four other branches descend from, so the integrator's rebase never sees an edit on both sides of a file.
|
||||
|
||||
| file / glob | A contract+spans | B tracker | C espryt | D magma | E gates |
|
||||
|---|---|---|---|---|---|
|
||||
| `MobileGL/MG_Pipe/{MGPipeValueTypes.h, MGPipeTypes.h, MGPipe.h, MGPipeRenderStateSpans.*, PipeApply.*, Coverage.def, PipeFields.def, generated/*.inc}` | **owner** | – | – | – | – |
|
||||
| `MobileGL/MG_Pipe/{FillPoints.def, PipeMutation.h, DirtySurface.def}` | – | **owner** | – | – | – |
|
||||
| `scripts/gen_pipe.py` | **owner** | – | – | – | – |
|
||||
| `scripts/gen_pipe_dirty_surface.py` | – | **owner** | – | – | – |
|
||||
| `scripts/g7_negative_control.sh` | – | – | – | – | **owner** |
|
||||
| `MobileGL/MG_Impl/Pipe/SlotAllocator.*` | **owner** (contract) | – | – | – | – |
|
||||
| `MobileGL/MG_Impl/Pipe/{Tracker.*, CsoCache.*, SetHashSuppressor.h, PipeFill.*}` | – | **owner** | – | – | – |
|
||||
| `MobileGL/MG_State/GLState/RenderState/RenderState.{h,cpp}` | **owner** | – | – | – | – |
|
||||
| `MobileGL/MG_State/GLState/{VertexArrayState/VertexArrayState.*, FramebufferState/*, TextureState/*, BufferState/*, SamplerState/*}` | – | **owner** | – | – | – |
|
||||
| `MobileGL/MG_State/GLState/VertexArrayState/VertexArrayObject.h` | – | – | – | **owner** | – |
|
||||
| `MobileGL/MG_Backend/DirectGLES/**` | – | – | **owner** | – | – |
|
||||
| `MobileGL/MG_Backend/DirectVulkan/**` | – | – | – | **owner** | – |
|
||||
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}`, `MobileGL/MG_Test/Util/PipeStatsTest.cpp` | **owner** (contract) | – | – | – | – |
|
||||
| root `CMakeLists.txt`, `MobileGL/Config.h`, `MobileGL/ConfigLoader.cpp` | **owner** (contract) | – | – | – | – |
|
||||
| `MobileGL/MG_Test/Pipe/CMakeLists.txt` + the four test stubs' creation | **owner** (contract) | – | – | – | – |
|
||||
| `MobileGL/MG_Test/Pipe/{RenderStateSpansTest, SlotAllocatorTest}.cpp` contents | **owner** | – | – | – | – |
|
||||
| `MobileGL/MG_Test/Pipe/{TrackerTest, CsoCacheTest}.cpp` contents | – | **owner** | – | – | – |
|
||||
| `MobileGL/MG_Test/SanityTest.cpp` | – | – | **owner** | – | – |
|
||||
| `MobileGL/MG_IntegrationTest/**`, `.github/workflows/test.yml`, `tools/device_bench/**`, `tools/trace_replay/run_android_retrace_local.py`, `android-plugin/app/src/trace/cpp/**`, `MobileGL/MG_Benchmark/**` | – | – | – | – | **owner** |
|
||||
| `docs/Disaggregated/*.md` | – | – | – | – | – (integrator) |
|
||||
| everything else | nobody | nobody | nobody | nobody | nobody |
|
||||
Reference in New Issue
Block a user