Files
MobileGL/docs/Disaggregated/notes/p13/HANDOFF-2026-10-06.md
T

82 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# P13 交接(2026-10-06)
> 计划 [`PLAN-P13.md`](PLAN-P13.md),裁定 [`INTEGRATOR-DECISIONS-P13.md`](INTEGRATOR-DECISIONS-P13.md),进度表 [`README.md`](README.md),CI 清理记录 [`docs/ci/ci-cleanup-log.md`](../../../ci/ci-cleanup-log.md)。
## 1. 状态
| 波 | 状态 | 提交(`p13` 分支) | CI |
|---|---|---|---|
| CI 基线修复 | 已推 | `cde6512b` IN_LIST / TCP 端口;`0cbb1a84` spawn Welcome 冷启动预算;`c9085533` apitrace 子模块(分支 `mobilegl/android-trace-replay` 的 `45843686`:着色器 / 程序名按类型映射,修 1.17) | 基线 Test `37414803850`、APK `37405703442`,逐条归类见 ci-cleanup-log |
| W1 | 已推 `5ff33cbb` | runtime_mode_proof monolith = 无 MG_Remote;push 无 MG_Remote 控制库 + 零 MG_Remote 检查;retrace-split 不再因控制库失败整体跳过;skip 普查 | Test `37425662897`:除 verify-split 的 FencePoll 测试竞态(已修 `0a47038a`)与普查无基线外全绿 |
| W2 + W3a | 已推 `55de98a0` | 普查基线 `c6cb5dea`;`68b56165` `9f05e665` `3e11c848` W2;`55de98a0` W3a | Test `37433779649` / APK `37433779654`(交接时排队中,被旧 run 卡住,已 force-cancel 旧 run) |
| W3b | 本地 | `9e14c16d`…`a4d10dd9`、`daf2b44c`、`4d2a2443`、`1d380a6e`、`3e36bd6c`、`938f4b11`、`883b8614` | 本地:unit 2908 绿;integration-gpu monolith 3640/3640;inproc 与 split/spawn/tcp 在跑 |
| W3c | 本地 | `e2c90986` | 本地 unit 绿 |
| W4a(一项) | 本地 | `3e2aff1d` 14a:indirect 无 client 数组不再回读命令缓冲;新 `ResourceReadbacks` 计数与场景用例 | 未编译验证 |
推送规则:W3b/W3c 等 W2/W3a 的 run 绿或红已归类后再推;推前 `git fetch` 看 feat 有无他人提交。
## 2. 关键事实(实现中发现,计划里没有或有误)
- **bit 4 不能退役**:它同时门控 P5c rv 的 `set_context_values`。W3c 只删 ResidualValueBlock,bit 4 仍固定开。
- **不需要控制面修订号 +1**:删结构后 `kMGPipeWireCatalogueDigest` 变化,wireFingerprint 随之变化,新旧端按名拒绝。
- **CMake 旧缓存**:`MOBILEGL_PIPE_PUSH=OFF` / `MOBILEGL_PIPE_LEGACY_MEMOS=ON` 在旧构建树(含 FCL 的 Gradle `.cxx`)里是默认值,所以是 WARNING + 忽略,不是 FATAL。
- **位图固定开(ID-P13-3)在 W3b 落地**:`ConfigLoader` 对清 bit 0-13 的掩码 `Fatal{PipeSubsystemsFixedOn}` + abort;Off / Refused 车道改为 `DirectGLES.SubsystemMaskRefusal.<Lane>` 具名拒绝对照(`Harness/RefusedMaskControl.cmake`,读日志确认原因)。各解析函数里 `legacyMemosEnabled` 改为常量 `true`,只为单元测试的掩码扫描不 abort;这些分支 W6 删。
- **monolith 仍走借用槽位的单元列表**(`UnitTexturesByHandle()` 在 monolith 为 false)——这是 W4c 要换的。`UnitMemoRefusesToDriveATwinFromAnotherTexture` 恢复并钉 P2 掩码(单元车道没有 P4a consumer,0x3fff 下建不出记录);红检已做(见 ci-cleanup-log)。
- **单元车道无法创建纹理记录**(`NoP4aConsumer`),任何需要纹理记录的白盒单元用例都要放到集成层。
- **本地 CMake 必须 3.31.10**:CMake 4.x 下 gtest 的 ENVIRONMENT 列表转义不同,集成用例把 `MOBILEGL_BACKEND_TYPE=DirectGLES;__EGL_VENDOR...` 当成一个变量,全部假红。
## 3. 本地环境(WSL archlinux)
- `~/mgl-p13-src`:从主仓库克隆的 LF 工作副本(`origin` = Windows 主仓库,分支 `p13`),子模块从主仓库本地拉。`~/mgl-p13-tools/sync.sh` 同步到 `p13` 已提交状态并从主仓库工作区按 sha256 物化 LFS fixture(有 29 个缺)。apitrace 子模块的第三方子模块已 `--depth 1` 拉过;glslang External 用 `update_glslang_sources.py` 拉过。
- 构建:`~/mgl-p13-tools/build_split.sh`(`~/mgl-p13-split` + `~/mgl-p13-retrace`),`build_push.sh`(`~/mgl-p13-push`,FCL 形态),`itest.sh <build> <tag>`(CI 同款 integration-gpu)。PATH 前置 `~/mgl-p13-tools/venv/bin`(CMake 3.31.10)。
- 经验:WSL 命令一律写成脚本文件再 `MSYS_NO_PATHCONV=1 wsl -d archlinux -- bash <file>`,`bash -lc '...'` 的引号与 `$` 会被吃;Git Bash 的 heredoc 会吃掉反斜杠,Python 编辑脚本用 Write 工具写文件再运行。
- 工具:scratchpad 下 `pyunifdef.py`(W3b 用的部分求值器)、`retire_names.py`(从普查基线退役具名用例)。
- `~/mgl-p13-apitrace`:apitrace CLI(`apitrace dump`)。
## 3b. W4 设计要点(W4a 落地时的实际做法)
- **谓词**:`MG_Config::DataArmIsRecord()` / `RecordArmAliasesFrontend()`(`Config.h`)。monolith 的 `MonolithTakesRecordArm` 由 `MOBILEGL_PIPE_DATA_ARM`(默认 `record`,W4-W6 专用)且后端为 DirectGLES 时才为真;Magma 在其一次性换臂时加入。无 MG_Remote 构建恒 false(W5 改)。
- **三类分支**:K(生命周期、角色、caps 来源、传输层级)留 `Transport`;F(数据臂)改谓词;S(store 是否复制)问 `CopiesIntoServerStorage()`——`M:3910` 那处若误用谓词会把所有别名基址清空。
- **verb 端口**(`EmitTables.cpp`「THE MONOLITH VERB PORT」):monolith 下被端口接管的槽位跑 EmitTables 的同一套规划与 pre-verb 钩子,再把记录交给进程内 `ServerVerbSink`(它写 `VerbIndirectBuffer` 等并调真表)。由 `MobileGL/Init.cpp`(SHARED)安装,不由 `MG_Backend/Init.cpp` 装——后者是 server 对象,装会让链接棘轮报新前端引用。W4a 端口槽位:20 个 draw + 2 个 dispatch。后续波把新 verb 同时加进 `InstallMonolithVerbPort` 与 `ApplyOnMonolithPort` 的 switch。
- **§1.4 别名刷新**:`RefreshAliasedStoreFromGpu`(`Managers.cpp`):读回 GL buffer → `OnBufferWriteback`(前端把字节拷进它的影子,即别名基址)→ 清 `serverGpuWritten`、盖 serial、bump epoch。前提:monolith 记录臂在 sub-data 与 respecify 时就铸 twin;孤立 respecify 也带影子基址(上传仍按描述符的 `HasDefinedContent` 门控);`contentSinceRespecify` 代替别名 store 没有的覆盖集回答流式写法。
- **GPU 写标记**:`GpuWriteSetIsClientSide()` 改谓词,client 侧的保守集由端口的 `MarkGpuWritesForDraw` 打;后端只标自己的 twin(`serverGpuWritten`)。image 单元仍在前端臂(W4c),其 buffer-texture 写在前端臂里额外标 twin。
- **单元测试**:`BufferTest` 三例断言前端臂的 map 推送,钉 `ScopedMonolithFrontendArm`,W6 随前端臂删。
- **W6 待办(monolith 登记的余项)**:`F1WireScenario` 在 `SetUp` 用 `SplitRuntimeSkipReason()` 整组跳过 monolith,所以 Magma 的 `MGITEST_MAGMA_FORCE_SHADER_MIPMAP` 车道(`ShaderMip1/2.`、`DepthMip.`)还没有 monolith 登记;它的断言读 `emitSeq`(编码器序号),monolith 记录臂走路由表不经编码器。W6 删前端臂时把 F1 的门改成「记录臂」并换掉 `emitSeq` 证据,再补 monolith 登记、退役对应的 census 跳过。
- **Magma 换臂**(同一会话稍后):一次性;`MonolithTakesRecordArm` 对两后端都为真。坑:服务端产生的字节(回读落入 pack buffer 的 `LandReadbackInBuffer`、纹理重铸 / 再生成的 `Adopt`)绝不能被别名 store 当基址——缓冲侧用 `MGPipeServerOriginatedWriteScope` 走「直接上传 GL + 标 GPU 写」,纹理侧 `Adopt*` 默认复制、只有客户端记录的 run 传 `frontendShadow=true`(曾造成 use-after-free:重铸后首 16 字节是 malloc 元数据)。
- **本机 retrace**:`~/mgl-p13-tools/sync.sh` 才物化 LFS fixture(`sb.sh` 用的 `sync2.sh` 会把它们复原为指针);跑前设 `MOBILEGL_GPU_HANG_BUDGET_MS=0`。
- 完整的 site 分类表与后续步骤(W4b 纹理别名 store、W4c、Magma)见 Plan 代理的设计(会话 scratchpad `W4-design.md`;要点已并入本节)。
## 3c. W5 要点(记录臂移出 MG_Remote,S7 已翻转)
- **形态**:`MOBILEGL_BUILD_RECORD_ARM` 是普通 CMake 变量,S7 起恒 ON(S8 unifdef 掉)。push 库(无 MG_Remote,FCL 形态)现在跑记录臂:`runtime_mode_proof` 要两形态都有 `MG_Record` 符号(push 294 / split 300),push 仍 0 个 `MG_Remote`。
- **代码位置**(命名空间 `MG_Record`):暂存库 `MG_Backend/Record/`;`RecordVerbSink`(记录动词的服务端半边,`ServerVerbSink` 继承它);动词发射器 + monolith 动词端口 + GPU 写集合 `MG_Impl/Pipe/Verb/`;持久映射跟踪器 `MG_State/GLState/BufferState/`。跨层只经缝:`MG_Pipe/PipeSessionFail.h`(`MGPipeRecordFail/Latch/Latched`,`FatalFunnel.cpp` 静态注册)、`PipeClientSeam.h`(设备丢失 / 拒绝后确认丢失)、`MG_Backend/Record/ApplyRoleBackend.h`、`VerbPort.h` 的 `VerbSession` 解析器(`EmitTables.cpp` 静态安装)。include-closure 的 `record-core` 探针守住它们不碰 `MG_Remote/` 与 flatbuffers。
- **翻转后的教训**:试翻转「能链接」不等于「行为相同」——split 里的 monolith 记录臂跑过的很多块仍挂在 DISAGG 上,push 编进了谓词却漏了消费者,结果是 Magma 析构崩(wire store 没在 VMA 之前清)、Espryt 读回 ERROR(记录动词的 verb 状态盖章没编进来)。办法:`scratchpad/suspects.py` 扫「DISAGG 块里出现记录臂机制」的块,逐个判;然后用 push 的 unit + integration-gpu + verify 树三套跑到绿。还剩的 DISAGG 块(约 300)都是传输本身:会话、共享图像、T0、设备丢失闩、角色拆分、caps 来源、EGL 服务端窗口。
- **verify 树第一次跑 monolith 记录臂**:监视读钩子在端口的中性 pack 窗口里改用已应用的 pack(`MonolithPortApplyingForVerify()`);monolith 的 poison-omission 对照改省略 `ReadPixels:GetPixelStoreParameters`(记录臂不再读 `GetActiveTextureUnit@GenerateMipmap`)。
- **FCL 开关**:`MOBILEGL_PIPE_PERSISTENT_MPROTECT=0` 不装跟踪器的 SIGSEGV 处理器(JVM 隐式空指针检查也用 SIGSEGV,处理器按设计链式转交,但从未在 HotSpot 里跑过)。设备上 FCL 冒烟仍是延后检查项。
- **剩余**:S8(unifdef 掉 `RECORD_ARM`、`!RECORD_ARM` 臂、`retired_switches` 规则、`wire_declines_audit` 回到单守卫);测试文件里仍有 DISAGG 守卫的记录臂用例(`SplitBufferTest` 等)随 S8 / W6 处理。
## 3d. W6 要点(删 monolith 前端臂,2026-10-07)
- **找死代码的办法**(脚本在会话 scratchpad,思路可复用):split 形态的库用 `-ffunction-sections -fdata-sections -fno-inline` 另建一棵树,链接时加 `--gc-sections --print-gc-sections` 和把 `_Z*` 设为 local 的 version script,取「所有副本都被回收」的函数;再开 `-Wunused-function/-Wunused-private-field/-Wunused-member-function` 找静态与成员残留;`lld --why-live=<sym>` 回答「谁还引用它」。每轮删完重建、再列,直到收敛。删函数时注意重载(同名多个定义)和只在其他平台 `#if` 里用到的函数(Android 的 AHB / YUV 导入保留)。
- **谓词折叠**:前端臂的选择器都已恒真——`DataArmIsRecord()`(W6a 起 constexpr)、Espryt 各族 `*SubsystemEnabled()` / `UnitTexturesByHandle()` / `ProgramHandleArm()` / `VertexInputReadsRecords()` / `MGB_TEXTURE_RECORD_ARM_SELECTED()` 及局部别名、Magma `MagmaProgramSource::IsWire()`。族谓词的锁存函数还在(集成 peek 读它们),启动时只剩 `ResolveRecordArmFamilies()` 查色彩附件上限;掩码由 ConfigLoader 拒绝。
- **后端表**:verb port 在两种模式都覆盖、记录 sink 又不调用的后端入口(`ClearNamedFramebuffer*`、`BlitNamedFramebuffer`、`GetTexImage`、`GetTextureImage`、`MultiDrawElements`)从两后端的表里删了;`DirectGLESSanity.ProvidesNamedFramebufferBlitForDirectStateAccess` 改为断言 verb port 提供它们。
- **link ratchet**:171 → 49,`# P13` 95 → 9。余下 9 条留给 W7(都是分区问题,不是前端臂):
- Espryt 以前端对象铸句柄的 slot 表入口与 apply 线程拒绝函数 7 条(`MGPipeSlots()`、`MGPipeSlotAllocator::{Acquire,FindByLifetimeId,Free}`、`MGPipeRefuse{Allocator,FrontendKeyedRegistry}FromApplyThread`、`MGPipeApplierIsUnbarrieredApply`):`SlotTables.h` 的 `GetOrCreate(StatePtr)` / `HandleOf` / `NoteStateForHandle` / `StateForHandle` / `OnFrontendObjectDestroyed` 与 `MGPipeFrontendKeyedRegistryScope` 的 8 处(纹理同步、unit sampler、`HandleOfBuffer`、`HandleOfSamplerViewForTexture`、`ResolveOwnRecord`、sampler / RBO 的前端 `SyncToBackend`)。这些路径在记录臂上收到的前端指针应恒为空,逐个证明后折掉即可;
- `PipeInputs::HasOpenTransformFeedbackSpan`(Magma XFB 计数槽选择)与 `PipeInputs::InvalidateCompileEnv`(Magma caps 变更):计划说要 pipe 侧替身——前者应由 applier 自己记开着的 span,后者用一个 MG_Pipe 钩子由前端静态注册。
- 断言「`# P13` 行为 0」随这 9 条一起加。
- **仍留着但已空转的**:`VkTextureManager` 以前端纹理为键的表(`m_aliveObjects` / `m_textureResources` 等)与其 GC、`VkClearManager` 类本身(只剩 Initialize/Shutdown)、`MG_Backend::...` 里若干只被单元测试用的纯函数(`ResolveSampledImageViewAspectMask`、`ConvertReadbackPixels`、`SamplerOverlapsWritableImageSubresource`)。机械清理,不影响行为。
## 4. 下一步
1. W2/W3a 的 CI:看完归类;然后推 W3b/W3c(普查基线已同提交退役名字)。
2. W4a 起:按计划 §1.2 的 F 类分支换臂。建议先引入一个 `MG_Backend::DataArmIsRecord()`(DISAGG 构建恒 true),逐子系统替换 `Transport != Monolith`,每个子系统跑一次 monolith 全量 integration-gpu(两后端)+ split 车道;§1.4 的别名 store 刷新先做(缺陷 a/b/c 依赖它)。
3. 14a 已在本地(`3e2aff1d`),先编译验证。
## 5. P13 之后:性能(用户裁定,2026-10-07)
P13 内不做性能工作。收官后的性能工作以 `dev` 分支构建(pull monolith)为「之前」基线,不用 W6 前的 feat 构建:设备上钉时钟,对比 dev 与 feat,场景 FCL MC 与 anland glmark2,两个后端都测。Magma monolith 记录臂约慢 16% 的读数(DEBTS.md 对应行)留作那时的起点,现在不补测。
## 6. 收官(2026-10-07)
P13 全部波完成(W9 移到 P13 之后的性能轮)。出口门、设备延后清单与 CI 见 [`README.md`](README.md) 的「出口门(收官)」与「设备侧延后清单」。收官时新发现并修掉的:无传输库的单进程不发 `set_context_values`、`RenderStateParameters` 填充字节未清零(W8 recorder 首跑抓到);verify+split 构建不建 server-only 链接检查目标(G4 比较器按设计跨两半)。本机构建目录与手机 `/data/local/tmp/p13` 已清理。