Files
MobileGL/docs/Disaggregated/README.md
T
swung0x48 43b5cfa94e [Docs] (Disaggregated): the four index documents keep only summaries, and every phase's detail lives in its own notes/<phase>/README.md
- ROADMAP, MEASUREMENTS and ARCHITECTURE are rewritten as summaries (333 KB of index text -> 84 KB).
  ROADMAP's phase table is one line per phase plus a link; MEASUREMENTS keeps headline numbers under
  its old §1-§13 numbering (plus §14-§16 for P6.5, P7 and P12); ARCHITECTURE keeps every decided rule
  under the same §1-§17 / appendix numbering, so the `ARCHITECTURE.md §N` references in code still
  land, and §17 becomes an index of the phase landing shapes.
- CURRENT_STAGE_PROGRESS now describes the current stage (the P12 on-screen-server subset) and absorbs
  CURRENT_STAGE_STATUS, which is removed. The P7 status tables, the P6 closing snapshot and the P6.5
  first-wave snapshot move to notes/p7, notes/p6 and notes/p65.
- Each phase gets notes/<phase>/README.md: a short summary, then the verbatim material that left
  the index documents (its ROADMAP row, its MEASUREMENTS section with subsection numbers kept, its
  ARCHITECTURE §17 part, milestones) and a file index. P8-P11 and P13 get their planned scope;
  the full open-question list moves to notes/OPEN-QUESTIONS.md.
- The phase reports that sat at the top level move into their phase folders with unchanged names:
  P5D-INPROC-PERFORMANCE, P5E-RUNAHEAD, P5F-WIRE-COMPLETENESS, P6-SPAWN-PLAN, P6-CONTRACT-DRAFT,
  P6-ENDSTATE-REVIEW. Their relative links, CONTRACT-P6.md's links to them and one tool docstring
  are updated; notes/README.md maps every old path and section number to its new place.
- 71 files under notes/recovered/ that were byte-identical copies of phase-folder files are removed.
- Corrections made while condensing: the server process reads Transport as Spawn (CONTRACT-P6 §3.1
  amended the old "child forces monolith" rule); both backends now publish kCapRunAheadApply;
  MOBILEGL_IPC_RESPAWN is a named refusal and MOBILEGL_IPC_IDLE_EXIT_S is not parsed; the Redmi
  pin row is in tools/device_bench/pin_device.sh.

check_doc_citations over docs/Disaggregated/*.md: 0 problems. No relative link is newly broken.
2026-09-24 22:21:09 +00:00

79 lines
7.5 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.
# MGPipe:MobileGL 前后端拆分
> **状态(2026-09-24)**:P0 … P7 已收官;P6.5 第一波已落地;**当前阶段 P12**「server 自有屏幕窗口」子集,已实现、未收官——[`CURRENT_STAGE_PROGRESS.md`](CURRENT_STAGE_PROGRESS.md)。阶段表见 [`ROADMAP.md`](ROADMAP.md)。
>
> 性能纪律(2026-09-08 起):逐线程 CPU 对着 pull 臂**只记录**、不作阻塞门;专门的优化阶段排在路线图推完之后。
## 是什么
MGPipe 是 MobileGL 前端(`MG_State` + `MG_Impl`)与后端(`MG_Backend`:Espryt = DirectGLES、Magma = DirectVulkan)之间的一份**显式接口**:gallium 形状、句柄寻址、只推不拉。它取代后端每 draw 直接读 `MG_State::pGLContext` 的做法,让后端拥有自己的状态机,并在此之上把前后端拆到**两个线程**(`inproc`)、**两个进程**(`spawn`),乃至经 TCP 的**两台机器**。
接口本身是可独立交付的产物:即使 IPC 永不上线,`inproc` 就是 monolith 的渲染线程。
## 架构(一段)
```
应用 GL 调用
→ MG_Impl(GL 语义、错误、shadow)
→ MG_Impl/Pipe/Tracker:在每条 verb 之前 validate,把变化推成 MGPipe 调用
→ MGPipeScreen / MGPipeContext(两张函数指针表,单一真相源 PipeCalls.def)
monolith:直调后端 split:发射器写记录 → 数据面(共享段 / 字节流)→ server 的 applier(apply 线程)
→ server 对象表(按 {slot, gen} 句柄索引)+ PipeInputs(后端被推送的状态块)
→ MG_Backend(Espryt / Magma),两个后端的 ring / pool / memo / lowering 原样不动
← MGPipeCallbacks(9 个具名反向回调 + 1 个正向终止符,split 下走 SEG_EVENT)
```
三种拓扑共用**同一份后端实现**:`monolith`(默认)、`inproc`(同进程两线程,CI 主验收;client 在 draw 路径上 run-ahead——Espryt 自 P5e、Magma 自 P5f 之后)、`spawn`(两进程;控制面 `fork` / `unix:` / `tcp://` × 数据面共享段 / 字节流,可跨机)。设计全文见 [`ARCHITECTURE.md`](ARCHITECTURE.md)。
## 构建与运行
四个 flavour:`build-linux`(pull,默认)、`build-push`(`-DMOBILEGL_PIPE_PUSH=ON`)、`build-verify`(+`MOBILEGL_PIPE_VERIFY`,影子比对)、`build-split`(+`MOBILEGL_BUILD_DISAGGREGATED` +`MOBILEGL_BUILD_DISAGGREGATED_INPROC`)。split 构建必须显式选拓扑,不设时是 monolith 对照臂:
```text
MOBILEGL_TRANSPORT=inproc MOBILEGL_ITEST_REQUIRE_GPU=1 ctest --test-dir build-split -L integration-split --output-on-failure
ctest --test-dir build-split -L 'integration-(spawn|tcp)' --output-on-failure # 条目自带 spawn / tcp 环境与私有日志
```
常用旋钮(全表见 [`ARCHITECTURE.md`](ARCHITECTURE.md) 附 A):`MOBILEGL_TRANSPORT`(拓扑)、`MOBILEGL_IPC_CONTROL` / `MOBILEGL_IPC_DATA`(控制面 / 数据面)、`MOBILEGL_IPC_TOKEN`(非 loopback 必需)、`MOBILEGL_IPC_RUN_AHEAD`、`MOBILEGL_IPC_STAGE_MB`(默认 32,1/4 是内容分块预算)、`MOBILEGL_IPC_SURFACE=server`(使用 server 自有窗口,P12)、`MOBILEGL_PIPE_STATS=1`(边界计数器)。
Android:三份 APK flavour(pull / push / split,Gradle 属性 `mobilegl.pipePush`、`mobilegl.buildDisaggregated`、`mobilegl.buildDisaggregatedInproc`)。设备侧 server 有离屏的前台 Service 与上屏的 `MobileGLDisplayActivity` 两种形态。设备 A/B 只用 Redmi `2f7cbe2e`,定频协议见 [`devices/pin-verification-2026-09-07.md`](devices/pin-verification-2026-09-07.md)。
## 文件地图
| 文件 | 内容 |
|---|---|
| [`CURRENT_STAGE_PROGRESS.md`](CURRENT_STAGE_PROGRESS.md) | 当前阶段:落地了什么、门、下一步、阻塞(摘要;细节链到 `notes/<当前阶段>/`) |
| [`ROADMAP.md`](ROADMAP.md) | 纪律、两条跑道、阶段表(每阶段一行摘要 + 细节链接)、里程碑、开放的债务与问题 |
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | 已定稿的设计(§1–§16)、阶段落地形状索引(§17)、开关(附 A)与计数器(附 B) |
| [`MEASUREMENTS.md`](MEASUREMENTS.md) | 每阶段的头条实测数字,全文在各阶段 notes |
| [`notes/`](notes/README.md) | **阶段细节**:每阶段一个目录,`README.md` 是该阶段的汇总(阶段表原行、逐门数字、落地形状),其余是计划、契约草稿、裁定、审计、报告与证据 |
| [`devices/`](devices/pin-verification-2026-09-07.md) | 设备定频档案与核验(跨阶段共用) |
代码地图:
| 路径 | 作用 |
|---|---|
| `MobileGL/MG_Pipe/` | 调用目录与各 `.def` 表、payload / 句柄 / 回调头、`PipeApply`、`PipeRoute`、`generated/*.inc`(G1–G8 产物,提交进树) |
| `MobileGL/MG_Impl/Pipe/` | Tracker、`PipeFill`、`SlotAllocator`、`CsoCache`、`CompositeResolver`、`ResourceTracker`、各族 `*Emit.h` |
| `MobileGL/MG_Backend/MGPipe/` | `PipeInputs`(后端被推送的状态块) |
| `MobileGL/MG_Remote/` | 仅 `MOBILEGL_BUILD_DISAGGREGATED`:`Protocol/`、`Transport/`(`ITransport` / `ILink` 两轴)、`Wire/`、`Client/`、`Server/`;各阶段 wire 契约 `CONTRACT-*.md` |
| `scripts/` | `gen_pipe.py`(G1–G7)、`gen_pipe_field_ownership.py`(G8)、`gen_pipe_dirty_surface.py`、`gen_protocol.py`、`symbol_report.py`(G1)、`check_include_closure.py`、`check_doc_citations.py`(本目录 `file:line` lint)、`link_ratchet.py`、G5 保护区脚本、`ci/` |
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | 边界计数器,`MOBILEGL_PIPE_STATS=1` 开启 |
| `MobileGL/MG_Test/Pipe/`、`MG_Test/Wire/`、`MG_IntegrationTest/Harness/*Peek` | 目录 / tracker / emitter 单元、wire 与 remote 单元、白盒断言 |
| `tools/trace_replay/`、`tools/device_bench/` | retrace 跑器(含 TCP 矩阵)、设备定频与配对 A/B 工具 |
## 术语
- **client / server**:前端角色 / 后端角色;`inproc` 下是两个线程,`spawn` 下是两个进程(可在两台机器上)。
- **verb**:会让 server 做事的命令(draw、dispatch、clear、blit、readback、XFB 跨度、query、纹理操作);推送只发生在 verb 之前的 validate 时刻。
- **class A / B / C**:后端槽的三类——A 从 caps mirror 本地回答,B 发射记录,C 具名拒绝(`Fatal{UnmigratedVerb}`),永不回落到 monolith。
- **CSO**:常量状态对象(render state、vertex elements、sampler、sampler view、shader),client 侧内容寻址,server 侧按句柄缓存。
- **Track V / Track H**:值类读点的迁移(整块 POD 过线)/ 对象类读点的迁移(`SharedPtr<前端对象>` → 句柄)。
- **lockstep / run-ahead**:每条 verb 等 server 应用完 / client 发布完即走,只有 barriered 记录才等(P5e)。
- **`MGGen`**:server 私有的"我重铸了驱动对象"纪元,永不过线;与句柄里的 client 世代严格分开。
- **G1 / G2 / G5 / G14**:pull 符号恒等 / pull == push 测试名 / 保护区字节一致 / 测试名只增不删。**barrier tax**:split − push 的逐线程 CPU 增量。
## 历史
本目录最早是一份 328 KB 的实施计划加 135 KB 的设计竞赛与评审记录;设计定稿后只保留设计与架构,评审与早期草案在 git 历史(`8b31de2f`、`1794ac94`、`8349babe`、`87ee17c6`),以及 `notes/recovered/` 里捞回的独有稿。2026-09-24 再次整理:四份索引文档只留摘要,各阶段细节(阶段表原行、逐门数字、落地形状、当时的进度页)移入 `notes/<阶段>/README.md`,散在本层的阶段报告与计划(P5d / P5e / P5f / P6)移入各自阶段目录;整理前的版本见 `1fb18d9`。