Files
MobileGL/docs/Disaggregated/notes/p12/INTEGRATOR-DECISIONS-P12.md
T

22 lines
11 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.
# P12 集成者裁定日志(「server 自有屏幕窗口」子集)
> 形式沿用 [`../p7/INTEGRATOR-DECISIONS-P7.md`](../p7/INTEGRATOR-DECISIONS-P7.md):一条裁定一个 ID,只记「定了什么、为什么、影响哪些文件」,不记来回。计划与交接见 [`PLAN-P12.md`](PLAN-P12.md),任务书见 [`BRIEF-onscreen.md`](BRIEF-onscreen.md)。
| ID | 日期 | 裁定 | 理由 | 影响 |
|---|---|---|---|---|
| ID-P12-1 | 2026-09-24 | 用户四条裁定为本子集的边界:server APK 自建 `ANativeWindow`(自己的 SurfaceView)**上屏**,离屏(pbuffer)路径保留;**同一时刻只一条活跃**,在 server 初始化 / context 创建时决定;拓扑为**进程内 server**(display Activity 自己的进程里一个线程跑 TCP server,会话串行);client 以新的 `WindowKind::ServerOwned`(控制修订 3)接入,可**完全无头**,几何由 server 回传。 | 用户裁定(`BRIEF-onscreen.md` §User rulings);ROADMAP P12 行「按重审 §6 改小」已删掉 Surface 传递那一半。 | 全部 15 个 `(P12)` 提交 |
| ID-P12-2 | 2026-09-24 | 会话的表面模式在**第一次成功的表面创建**时闩定(ServerOwned 窗口 → 上屏,pbuffer → 离屏),之后另一种表面**具名拒绝**(`SurfaceRefusal::SurfaceModeMismatch`,reply ok=false,不闩会话);client 自己命名的窗口(X11/Win32/None,D8 未关)两种都不算、不闩也不拒。 | 「同一时刻只一条活跃」落到每会话;拒绝是配置答复,不是对端坏字节。 | `ServerLoop.{h,cpp}`(`SessionSurfaceModeAdmits`) |
| ID-P12-3 | 2026-09-24 | 失窗(`surfaceDestroyed` → `ServerDisplay::Detach`)的顺序即契约:apply 线程先让后端放掉窗口(Espryt 销毁 EGL surface/context,Magma 销毁 swapchain/VkSurface),再以 `Fatal{ServerWindowLost}` 闩会话(client 读干净 device lost),**最后**才结束租约、让回调返回;`Detach` 有界 3 s,超时不抽走窗口(引用留到租约结束),具名 `TimedOut`。 | GLSurfaceView 契约:回调返回后不得再往窗口渲染;UI 线程不能被无界占住。 | `ServerDisplay.{h,cpp}`、`ServerLoop.cpp`、`FatalFamilies.def`、`DisplayServerJni.cpp` |
| ID-P12-4 | 2026-09-24 | 进程内 server 用线程交接会话(`TcpSupervisor::Handoff::Thread`):预认证、Busy、DataBind 路由与 fork 形状同一份代码;会话间 `ResetSessionLatch`;后端**按进程钉住**(无 `MOBILEGL_BACKEND_TYPE` 时取第一个会话的);fork 出的会话子进程 `PR_SET_PDEATHSIG` 随监督进程去。以崩溃隔离换窗口可达:会话里一个未武装的 `SessionFail` 会带走 Activity 进程。 | `ANativeWindow` 过不了 fork / exec;Espryt 与 Magma 永不同进程(`BenchService.java` 的规则)。 | `ServerMain.cpp`、`InProcessServer.h` |
| ID-P12-5 | 2026-09-24 | 以下是**审查轮的修复**(15 条发现归并为 10 个问题,2 条被驳回为本改动之前就有的问题、不在本 diff 内)。**大项一**:失窗请求在 `DrainRing` 的**每次 pop 之前**也检查(在 latch 检查之后,`ph_latch_sites.py` 的 MECHANICS 行仍钉 latch 检查为循环首句),不再只在批与批之间由 `PumpControlRequest` 应答。 | 持续推帧的 client 让命令环数秒不空:`surfaceDestroyed` 在 UI 线程等满 3 s 后 `TimedOut`,会话继续往已销毁的窗口 present。 | `ServerLoop.cpp`;`ServerLoopLatchTest.ALostServerWindowIsReleasedMidBatchWhileTheClientStreams` |
| ID-P12-6 | 2026-09-24 | **大项二**:`DropEveryTwinForEndedServerSession` 同时清空 `TextureImpl::g_boundTexturesCache`、`SamplerImpl::g_boundSamplersCache`,并把 `g_activeTextureUnit` 置回 0。 | twin 在 `InProcessTeardown()` 为真时不从单元影子里擦掉自己,影子留下指向已释放 twin 的裸指针;下一会话的 twin 落在回收地址上就读成「已绑定」而跳过真实绑定,上传落到 texture 0、画面黑。新 context 的活动单元是 `GL_TEXTURE0`。 | `Managers.cpp`;`SanityTest EsprytServerSession.TheServerBackendsDestructionEmptiesTheTextureAndSamplerUnitShadows` |
| ID-P12-7 | 2026-09-24 | **停在推流中**:进程内 server 停止(`mobilegl_server_stop_inprocess`)时,`RunSession` 在 `loop.Stop()` 之前调 `ServerLoop::AbandonQueuedRecords()`:drain 在手上这条记录后停,退出路径不再 drain 剩余队列(与 `ReverseChannelForfeit` 同形)。**正常的 client EOF 仍 drain 完**。 | 批内剩余 + 退出 drain 一个仍在被补满的环,会超出 `Stop()` 的 5 s 有界 join,`Fatal{ApplyThreadJoinTimeout}` 带走 Activity 进程。 | `ServerLoop.{h,cpp}`、`ServerMain.cpp`;`ServerLoopTest.StoppingTheServerUnderAStreamingClientLeavesTheQueueAndJoinsPromptly` |
| ID-P12-8 | 2026-09-24 | **会话结束的清理补齐两处**:Magma 的 `~BackendObject_DirectVulkan` 在传输下丢弃进程全局的 `pVulkanRenderer`(带代际递增与程序反射缓存清理,同 `ReleaseEGLResources`);Espryt 的析构调 `ForgetRequestedSwapInterval()`。monolith 不变;pull 构建的析构仍为 `= default` / 不变(G1)。 | 未经 `eglTerminate` 就断开的 client 不会发 `ReleaseEGLResources`,renderer(窗口上的 swapchain / VkSurface)在租约结束后仍挂在窗口上;swap interval 是有意跨表面重建保留的进程全局,下一会话会静默继承上一个 client 的值。 | `BackendObject_DirectVulkan.cpp`、`DirectGLES.{h,cpp}`、`BackendObject_DirectGLES.cpp` |
| ID-P12-9 | 2026-09-24 | **陈旧尺寸**:`ServerDisplay` 记下最后请求的几何与布局最后报告的尺寸;在固定尺寸之后请求 0/0(窗口自己的尺寸)时,等(几何宽限内)布局尺寸回来,或等请求之后任何一次不等于旧固定尺寸的报告。 | `setSizeFromLayout` 与 `setFixedSize` 一样是异步应答;原实现对 0/0 立即授租,拿到的是上一会话的固定尺寸。 | `ServerDisplay.{h,cpp}`;`ServerDisplayTest.TheWindowsOwnSizeAfterAFixedSizeIsTheLayoutsNotTheStaleFixedOne` |
| ID-P12-10 | 2026-09-24 | **client 侧几何三条**:(a) 对 server-owned 表面的 `ResizeEGLWindowSurface` 走几何请求(同一持有者重取租约、等 display),后端表面随窗口**真实**尺寸,reply 带回该尺寸,client 采用它而不是自己请求的值(`ServerResizeServerOwnedWindowSurface`);(b) client 跟踪**全部** server-owned 表面,一个 extent 应用到所有(它们共用 server 的一个窗口);(c) Espryt 的 extent 发布只针对 server 自己的窗口——`ServerLoop` 经 split-only 的 `MGPipeServerSetOwnedWindow` 告诉后端哪个窗口是自己的,client 自己命名的窗口保持只发格式。 | (a) 原实现只改后端记录,手机上的 SurfaceView 不变,EGL 状态报的是请求值;(b) 单槽让第二个表面抢走第一个的更新、释放后第一个再无更新;(c) 不带旋钮的会话被切到了重分配臂。 | `ServerLoop.{h,cpp}`、`BackendObject_Remote.cpp`、`ClientSession.{h,cpp}`、`PipeInputs.{h,cpp}`、`DirectGLES.cpp` |
| ID-P12-11 | 2026-09-24 | **日志转发**:进程内 server 装 `SetSessionLogForwarder`——只有会话线程与选择加入的线程(该会话的 apply 线程,`SetThreadForwardsLogToPeer`)转发,且在释放日志互斥之后、在独立的转发互斥下发送(`WithLogBarrier` 两把都拿,flush ack 仍在每条已开始的发送之后;发送本身打的日志不再转发)。fork 出的会话子进程仍用 `SetLogForwarder`,pull 构建的 `Log()` 不变(G1)。 | `MOBILEGL_IPC_ROLE=server` 让 Activity 进程里每个线程都是 server 角色:UI 线程与监听线程(含别的对端地址、Busy 拒绝)的日志进了当前 client 的控制 socket;而阻塞的 `SendFrame` 在全局日志互斥下执行,不读的 client 会在 UI 线程下一次打日志时把它挂住。 | `Log.{h,cpp}`、`ServerMain.cpp`、`ServerLoop.cpp` |
| ID-P12-12 | 2026-09-24 | `IterationRPProgram203Scenario`(`integration-magma-full-split`)**不在本轮范围内**,门里出现时按「既有、环境敏感」读(ID-P7-22),不阻塞 P12 的合并。 | 用户裁定(2026-09-24);PLAN-P12 §2 已独立复核非本包引入。 | 过程 |
| ID-P12-13 | 2026-09-24 | 审查轮修复**未在真机上复测**:本轮的执行环境是没有 Android 设备与 NDK 的云容器,APK 重建、设备七项检查、以及「推流中按 HOME、回调返回前 surface 已释放并记录耗时」这一项都**没有跑**,留作 P12 收尾的下一次设备窗口。主机门见 ID-P12-14。 | 如实记录;设备证据仍是 `device/` 下审查轮之前(`29b7b284`)的。 | 过程 |
| ID-P12-14 | 2026-09-24 | **主机门(审查轮,云容器:4 核、clang-19、lavapipe/mesa 25.2)**:`unit` **2605/2605**(含本轮四个新用例)、spawn / tcp 与三条 Magma 双进程车道全绿,卫生 12/12,fatal census 79 / link ratchet 171 不变,协议修订 3 钉住(`gate/gate-review-3c342c97.log`)。**两个大项的红-绿已演示**:删掉 `DrainRing` 的逐记录失窗检查,新用例红——`Detach answered TimedOut in 3000 ms after 200 of 200 streamed records`;删掉三处单元影子重置,新用例四条期望全红(影子仍指向结束会话的 twin);恢复后皆绿。门里剩下的红**全部归环境**:`SplitLogPaths` 与 `spawn_lane_parity` 读的是 ctest 注册,而本容器的 CMake 3.28 生成的注册缺车道环境(CTest 3.x 还解析不了生成脚本的 `IN_LIST`,CMake 4.4 则把车道环境列表压成一个变量——`gate/gate-review-d04ac7d1-cmake4.log` 里 integration-gpu 2052 红即此);integration-gpu 的 4 条 `PersistentCoherentMapScenario` 与 3 条 `F1WireScenario` 在 `cb0404f2` 与本轮 head 上用同一环境**直接跑二进制**结果完全相同(前者两边都红、后者两边都绿),故非本轮引入;`IterationRPProgram203Scenario` 见 ID-P12-12。自 `cb0404f2` 起没有任何 CMake 文件改动。 | 如实记录;在与原门同一 CMake 版本的机器上复跑是合并前的剩余一步。 | 过程;`gate/`、`gate-container.sh` |
| ID-P12-15 | 2026-09-24 | **G1 成立(审查轮)**:pull 构建(`DISAGGREGATED=OFF`、`PIPE_PUSH=OFF`,连测试全目标编过)在 `cb0404f2` 与本轮 head 上同机同编译器(clang-19)构建,`libMobileGL.so` 的 `.text` 两边都是 `0x9b1bf2`,`nm --defined-only \| awk '{print $3}'` 符号集 30614 对 30614、**增 0 减 0**。(`0xa52203` 是原门那台机器的编译器读数,跨机不可比;同机前后对比才是 G1 的读法。) | 审查轮改动都在 `MOBILEGL_BUILD_DISAGGREGATED` 之内,`Log()` 的锁形状在 pull 构建里也保持 `lock_guard`。 | 过程 |