mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-18 15:33:22 +09:00
[Docs] (Disaggregated): the top-level files become short indexes in plain language; the design text moves to design/, the how-to and reference material to guide/
- README, ARCHITECTURE, ROADMAP, MEASUREMENTS and CURRENT_STAGE_PROGRESS are rewritten as indexes (84 KB -> 15 KB): what the project is, where it stands, and where each detail lives. ROADMAP is one plain sentence per phase; MEASUREMENTS is the five conclusions that matter plus one line per phase; CURRENT_STAGE_PROGRESS is the P12 goal, a checklist and the next steps. - ARCHITECTURE's body moves unchanged into ten design/ files, keeping §1-§17 and appendices A/B, so `ARCHITECTURE.md §N` references in code resolve through the table in ARCHITECTURE.md. - guide/ holds build-and-run, code map, glossary and the engineering discipline (from README and ROADMAP), and the device pinning record that used to sit in devices/. - The open-debt table moves to notes/DEBTS.md; the detailed current-stage tables (with decision IDs, the open line items and evidence locations) move into notes/p12/README.md. notes/README.md maps every moved path and section. - The documentation citation lint in test.yml also covers design/ and guide/, which describe the current tree as the top-level files did.
This commit is contained in:
@@ -1,78 +1,30 @@
|
||||
# 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 臂**只记录**、不作阻塞门;专门的优化阶段排在路线图推完之后。
|
||||
**做什么**:在 MobileGL 的前端(处理应用的 GL 调用)和后端(调用 GLES / Vulkan 驱动)之间立一份显式接口——前端把状态变化**推**给后端,后端不再直接读前端的内存。有了这份接口,前后端可以放在两个线程、两个进程,甚至两台机器上运行。
|
||||
|
||||
## 是什么
|
||||
**做到哪了**(2026-09-24):接口与拆分已完成到"两个进程、可经 TCP 跨机"。当前在做 **P12:让 Android 上的 server 自己开窗口,把画面直接显示到屏幕上**——功能已实现,还差真机复测和两项验收。→ [`CURRENT_STAGE_PROGRESS.md`](CURRENT_STAGE_PROGRESS.md)
|
||||
|
||||
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)
|
||||
应用的 GL 调用
|
||||
→ 前端 MG_Impl:处理 GL 语义;在每条"做事的命令"(draw、clear…)之前,把状态变化整理成记录
|
||||
→ MGPipe 接口(两张函数指针表,由调用目录 PipeCalls.def 生成)
|
||||
→ 三选一:直接调用(单线程)│ 队列 → 另一个线程 │ 队列 → 另一个进程 / 另一台机器
|
||||
→ 后端 MG_Backend:Espryt(GLES)/ Magma(Vulkan),按记录更新自己的状态并调用驱动
|
||||
← 反向消息(错误、GPU 写回、窗口尺寸)按顺序回到前端
|
||||
```
|
||||
|
||||
三种拓扑共用**同一份后端实现**:`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) | 设备定频档案与核验(跨阶段共用) |
|
||||
| 现在做到哪、下一步 | [`CURRENT_STAGE_PROGRESS.md`](CURRENT_STAGE_PROGRESS.md) |
|
||||
| 设计要点与各部分设计 | [`ARCHITECTURE.md`](ARCHITECTURE.md) → [`design/`](design/) |
|
||||
| 分几个阶段、每个阶段做了什么 | [`ROADMAP.md`](ROADMAP.md) → [`notes/<阶段>/`](notes/README.md) |
|
||||
| 性能与验证的关键数字 | [`MEASUREMENTS.md`](MEASUREMENTS.md) |
|
||||
| 怎么构建、运行、测试 | [`guide/build-and-run.md`](guide/build-and-run.md) |
|
||||
| 代码在哪 / 术语 / 工程纪律 | [`guide/code-map.md`](guide/code-map.md)、[`guide/glossary.md`](guide/glossary.md)、[`guide/discipline.md`](guide/discipline.md) |
|
||||
| 各阶段的原始计划、裁定、报告、证据 | [`notes/`](notes/README.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`。
|
||||
整理记录:2026-09-24 两次整理——顶层只留索引,设计正文拆到 `design/`,上手与参考放 `guide/`,阶段细节放 `notes/<阶段>/`;整理前的版本见提交 `1fb18d9`。更早的设计竞赛与评审稿在 git 历史(`8b31de2f`、`1794ac94`、`8349babe`、`87ee17c6`)。
|
||||
|
||||
Reference in New Issue
Block a user