mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-17 15:03:25 +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:
@@ -0,0 +1,36 @@
|
||||
# 构建、运行与测试
|
||||
|
||||
> 上手说明。文档导航见 [`../README.md`](../README.md);全部开关见 [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) 附 A。
|
||||
|
||||
## 四种构建
|
||||
|
||||
| 构建目录 | CMake | 用途 |
|
||||
|---|---|---|
|
||||
| `build-linux` | 默认(pull) | 出货形态;G1 的基准——它的二进制必须逐字节不变 |
|
||||
| `build-push` | `-DMOBILEGL_PIPE_PUSH=ON` | 单进程,但后端改读前端推来的状态 |
|
||||
| `build-verify` | push + `-DMOBILEGL_PIPE_VERIFY=ON` | 每个 draw 把推来的状态与前端实际状态逐字段比对;慢,永不出货 |
|
||||
| `build-split` | push + `-DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON` | 可以拆成两线程 / 两进程 / 两台机器 |
|
||||
|
||||
## 选拓扑
|
||||
|
||||
split 构建在运行时用 `MOBILEGL_TRANSPORT` 选拓扑;**不设就是单进程(monolith)对照**:
|
||||
|
||||
| `MOBILEGL_TRANSPORT` | 形态 |
|
||||
|---|---|
|
||||
| 不设 / `monolith` | 单线程直调 |
|
||||
| `inproc` | 同一进程两个线程(CI 的主验收形态) |
|
||||
| `spawn` | 两个进程;再用 `MOBILEGL_IPC_CONTROL`(`fork` / `unix:<path>` / `tcp://host:port`)与 `MOBILEGL_IPC_DATA`(`auto` / `shm` / `stream`)选控制面与数据面,跨机时还要 `MOBILEGL_IPC_TOKEN`(≥16 字节) |
|
||||
|
||||
```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 环境与私有日志
|
||||
```
|
||||
|
||||
其他常用旋钮:`MOBILEGL_IPC_RUN_AHEAD`(默认 1,client 发完就走)、`MOBILEGL_IPC_STAGE_MB`(默认 32,其 1/4 是大块上传的分块预算)、`MOBILEGL_IPC_SURFACE=server`(使用 Android server 自己的窗口)、`MOBILEGL_PIPE_STATS=1`(边界计数器,日志里的 `MGPipe stats:` 行)。
|
||||
|
||||
## Android
|
||||
|
||||
- 三份 APK flavour:pull / push / split(Gradle 属性 `mobilegl.pipePush`、`mobilegl.buildDisaggregated`、`mobilegl.buildDisaggregatedInproc`)。split APK 同样要设 `MOBILEGL_TRANSPORT`,不设就是单进程对照。
|
||||
- 设备侧 server 有两种形态:离屏的前台 Service(`MobileGLServerService`)与上屏的 `MobileGLDisplayActivity`;同一时刻只有一个。
|
||||
- 电脑当 client、手机当 server 的跨机配置(起 server、设令牌、`adb forward` 备用路线)见 [`../notes/p65/README.md`](../notes/p65/README.md) 的"两边怎么配"。
|
||||
- 性能对比只用 Redmi `2f7cbe2e`,按 [`pin-verification-2026-09-07.md`](pin-verification-2026-09-07.md) 定频,reboot-clean、同热窗口、配对 A/B。
|
||||
@@ -0,0 +1,14 @@
|
||||
# 代码地图
|
||||
|
||||
> 参考。文档导航见 [`../README.md`](../README.md);目录布局与构建选项见 [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) §16。
|
||||
|
||||
| 路径 | 作用 |
|
||||
|---|---|
|
||||
| `MobileGL/MG_Pipe/` | 接口本身:调用目录 `PipeCalls.def` 与其他 `.def` 表、payload / 句柄 / 回调头、`PipeApply`、`PipeRoute`、`generated/*.inc`(生成物,提交进树) |
|
||||
| `MobileGL/MG_Impl/Pipe/` | 前端:Tracker、`PipeFill`、`SlotAllocator`、`CsoCache`、`CompositeResolver`、`ResourceTracker`、各族 `*Emit.h` |
|
||||
| `MobileGL/MG_Backend/MGPipe/` | `PipeInputs`:后端读的、被前端推来的状态块 |
|
||||
| `MobileGL/MG_Remote/` | 拆分专用(仅 `MOBILEGL_BUILD_DISAGGREGATED`):`Protocol/`(控制面 schema)、`Transport/`(控制面 `ITransport` × 数据面 `ILink`)、`Wire/`(记录编解码)、`Client/`、`Server/`;各阶段的 wire 契约 `CONTRACT-*.md` |
|
||||
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | 边界计数器(`MOBILEGL_PIPE_STATS=1`) |
|
||||
| `MobileGL/MG_Test/Pipe/`、`MG_Test/Wire/`、`MG_IntegrationTest/Harness/*Peek` | 目录 / tracker / 发射器单元测试、wire 与 remote 单元测试、白盒断言 |
|
||||
| `scripts/` | 生成器(`gen_pipe.py`、`gen_pipe_field_ownership.py`、`gen_pipe_dirty_surface.py`、`gen_protocol.py`)、门脚本(`symbol_report.py`、`check_include_closure.py`、`link_ratchet.py`、G5 保护区脚本、`check_doc_citations.py`)、`ci/` |
|
||||
| `tools/trace_replay/`、`tools/device_bench/` | trace 回放(含 TCP 矩阵跑器)、设备定频与配对 A/B 工具 |
|
||||
@@ -0,0 +1,21 @@
|
||||
# 工程纪律与验证门
|
||||
|
||||
> 参考。验证门的设计见 [`../design/07-memory-readback-verification.md`](../design/07-memory-readback-verification.md) §13.2;各阶段实际跑门的结果在 `../notes/<阶段>/README.md`。
|
||||
|
||||
## 每个提交
|
||||
|
||||
- 默认 ALL target 必须完整构建;禁止提交热路径插桩(CI grep 门)。
|
||||
- **每个门必须能因它存在的理由变红**:带阴性对照并真跑过一次红(R-16);公共 GL 看不见的改用白盒断言。
|
||||
- 正确性门是硬门;**性能对着 pull 臂只记录、不设门**(用户 2026-09-08),但数字必须真的采到。专门的优化阶段排在路线图推完之后。
|
||||
- **拆分不顺手修 `dev` 的 bug**:发现的 `dev` 侧缺陷记成独立条目、独立 PR。
|
||||
|
||||
## 每个阶段出口
|
||||
|
||||
- 跑一次五部分门:接口纯度、语义影子比对、行为 A/B、性能记录、覆盖与句柄纪律。
|
||||
- 四条字节 / 名字级等式:**G1** pull 构建的符号集与 `.text` 对基线恒等(0 增 / 0 删 / 0 resize / 0 重命名);**G2** pull 与 push 的测试名集合相同;**G5** 受保护区域逐字节一致;**G14** 测试名只增不删。
|
||||
- 性能判据是**逐线程 CPU 时间**;设备对比走 reboot-clean + 同热窗口配对 A/B,只用 Redmi `2f7cbe2e`([`pin-verification-2026-09-07.md`](pin-verification-2026-09-07.md));Windows 机器不是正确性门。
|
||||
- 收官由异模型族审查一次,发现进入下一阶段首轮;实现方与审查方错开模型族;不过度验证(用户 2026-09-16,ID-66)。
|
||||
|
||||
## CTS
|
||||
|
||||
`gl44to46` 约 56,271 例,单独计价:逐阶段只跑该阶段可能影响的具名块;完整 caselist 只在架构边界与合并 `dev` 之前跑,放 CI 不放关键路径。
|
||||
@@ -0,0 +1,23 @@
|
||||
# 术语
|
||||
|
||||
> 参考。文档导航见 [`../README.md`](../README.md)。
|
||||
|
||||
| 术语 | 意思 |
|
||||
|---|---|
|
||||
| 前端 / 后端 | 前端 = `MG_State` + `MG_Impl`,处理应用的 GL 调用;后端 = `MG_Backend`,真正调用驱动 |
|
||||
| Espryt / Magma | 两个后端:Espryt 走 OpenGL ES(DirectGLES),Magma 走 Vulkan(DirectVulkan) |
|
||||
| client / server | 拆分后的前端角色 / 后端角色;可以是两个线程、两个进程或两台机器 |
|
||||
| monolith / inproc / spawn | 三种拓扑:单线程直调 / 同进程两线程 / 两个进程(可跨机) |
|
||||
| pull / push | 后端自己去读前端状态(旧做法)/ 前端把状态推给后端(MGPipe) |
|
||||
| verb | 会让后端真正做事的命令:draw、dispatch、clear、blit、回读、XFB、query、纹理操作。状态只在 verb 之前推送 |
|
||||
| 句柄 `{slot, gen}` | 对象的身份:client 分配的槽号 + 复用代数,server 从不回传 |
|
||||
| CSO | 常量状态对象(渲染状态、顶点格式、sampler、sampler view、shader):client 按内容去重,server 按句柄缓存 |
|
||||
| 控制面 / 数据面 | 握手与罕见控制消息走的连接 / 命令记录与批量数据走的通道;两者可分别选(共享内存或字节流、本机或 TCP) |
|
||||
| lockstep / run-ahead | client 每条命令都等 server 做完 / client 发完就走,只有需要答案的命令才等 |
|
||||
| barrier tax | 拆成两线程后多出来的逐线程 CPU 代价(split − push) |
|
||||
| device-lost | server 崩溃或断线后 client 进入的状态:GL 调用变空操作、交换缓冲返回"上下文丢失",而不是崩溃或卡死 |
|
||||
| class A / B / C | 后端函数表的槽:A 本地回答,B 发成记录,C 还没迁移、按名拒绝 |
|
||||
| Track V / Track H | 值类读点的迁移(整块数据过线)/ 对象类读点的迁移(对象指针换成句柄) |
|
||||
| G1 / G2 / G5 / G14 | 验证门:单进程构建二进制逐字节不变 / pull 与 push 测试名集合相同 / 受保护的后端函数逐字节不变 / 测试名只增不删 |
|
||||
| red-once(R-16) | 每个门都必须真的跑红过一次,证明它能因为它要抓的问题而失败 |
|
||||
| `MGGen` | server 私有的"我重建了驱动对象"纪元,永不过线;与句柄代数严格分开 |
|
||||
@@ -0,0 +1,28 @@
|
||||
# 设备定频档案与核验
|
||||
|
||||
本分支性能 A/B 所用设备的定频方式与核验结果。规则:每次运行前后各跑一次 `pin_device.sh <serial> check`,DRIFT 的运行作废重跑;stock 值硬编码、不从已钉设备采样(否则一次 restore 会把钉频变成永久);温度门 40 °C;reboot-clean、同热窗口、两臂背靠背。
|
||||
|
||||
## 当前战役设备(2026-09-11 起,P4a 之后唯一用于 A/B 的设备)
|
||||
|
||||
| 设备 | SoC / GPU | 大核 | 小核 | GPU | 备注 |
|
||||
|---|---|---|---|---|---|
|
||||
| Redmi M332BF `2f7cbe2e` | SM8750 / Adreno 830v2 | policy6 → 1958400(stock 1017600–3072000) | policy0 → 1555200(stock 556800–2745600) | kgsl `min/max_pwrlevel = 0`;2026-09-11 实测 1050 MHz(厂商 `thermal_pwrlevel` 锁 1),2026-09-16 起实测 1100 MHz | 主动风扇 `/sys/class/xm_power/hw_monitor/pwm_fan` 恒 level 2,用例间降温 <1 min;温度门 `cpuss-0-0` |
|
||||
|
||||
与小米 `35d0befa` 同 SoC、同 OPP 表,两台的钉频数值可比;跨钉频口径(1050 vs 1100 MHz)的活动不可比钟频,只有同场配对可比。Redmi 的行已于 P6 收尾(2026-09-22)并入树内 `tools/device_bench/pin_device.sh`(`2f7cbe2e` 条目;stock 范围与小米不同,GPU 实测钳在 1050 MHz:`thermal_pwrlevel` 写 0 读回 1,见 [`../notes/p6/README.md`](../notes/p6/README.md) §12.7);此前它只在树外的 `~/w7/notes/p2/devices/pin_device.sh`。
|
||||
|
||||
## 2026-09-07 核验:小米 `35d0befa` 与 Oppo `3B159D009VZ00000`(P2 / P3a 使用)
|
||||
|
||||
结论:`bench.sh` 的 `/proc/ppm` + `/proc/gpufreq` 钉法在两台上都不存在(MT6993 已改 `/proc/gpufreqv2/`),所以用 `bench.sh --no-pin` + `tools/device_bench/pin_device.sh <serial> pin|unpin|check`(纯 adb + su;exit 0 PINNED / 1 DRIFT / 2 UNPINNED,UNPINNED 非零使 `check && measure` 不可能量到未钉设备)。`devices/*.env` 的 `PROFILE_VERIFIED=1` 只认证文件里的节点与钉值,不认证 `bench.sh` 能驱动它们;给 `bench.sh` 加 `PIN_STYLE` 仍未做。
|
||||
|
||||
| | 小米 24129PN74C(SM8750 / Adreno 830v2) | Oppo PLG110(MT6993 / Mali,gpufreqv2) |
|
||||
|---|---|---|
|
||||
| 大核 | policy6 → 1958400(精确 OPP;stock 1017600–2841600) | policy4 → 2000000(最近 OPP,+2.1%;stock 300000–3500000,厂商守护随后改回 3200000) |
|
||||
| 小核 | policy0 → 1555200(精确;stock 556800–2745600) | policy0 → 1600000(+2.9%;stock 300000–2100000) |
|
||||
| 额外 | — | policy7(单核 4.21 GHz)同钉 2000000,否则一个热线程就打破钉频 |
|
||||
| 方法 | `scaling_min_freq = scaling_max_freq = 目标`;governor(walt / sugov_ext)不动;写序 min→`cpuinfo_min_freq`、max→目标、min→目标(min 高于当前 max 会被 cpufreq 钳住) | 同左 |
|
||||
| GPU | `kgsl-3d0/{min,max}_pwrlevel = 0` → 1100 MHz(devfreq 路径封顶 1050);`gpuclk` 单位是 Hz | `/proc/gpufreqv2/fix_target_opp_index = 0` → 1716000 kHz,恢复写 −1;不用 ged `custom_*`(取 OPP 下标、且被 urcc-service 争写) |
|
||||
| 温度门 | `cpuss-0-0`(zone13),idle 34.7 °C | `soc_max`(zone14),idle 36–37 °C,门只勉强可达 |
|
||||
| 30 s 八路负载核验 | 7 个样本零漂移,47 → 52 °C | 7 个样本零漂移,53 → 62 °C |
|
||||
| 陷阱 | `gpubusy` 打的是周期数,busy 百分比读 `gpu_busy_percentage` | `scaling_governor/min/max` 是 0660 system,必须经 su 读,否则空值看起来像在工作 |
|
||||
|
||||
两台核验后均已解钉并复核 UNPINNED,写过的节点全部恢复。未核验:Oppo GPU 钉在图形负载下的实际时钟(核验窗口 GPU 处于 power-collapse)、整场 bench 窗口内的钉频持久性、重启后状态、厂商热管理介入。
|
||||
Reference in New Issue
Block a user