mirror of
https://github.com/MobileGL-Dev/MobileGL
synced 2026-11-17 23:13:22 +09:00
[Docs, Chore] (docs, tools, MobileGL, scripts, CONTRIBUTING.md, .gitignore): translate the documentation and use US spelling
This commit is contained in:
@@ -1,39 +1,39 @@
|
||||
# 构建、运行与测试
|
||||
# Build, run and test
|
||||
|
||||
> 上手说明。文档导航见 [`../README.md`](../README.md);全部开关见 [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) 附 A。
|
||||
> Getting started. For the documentation index see [`../README.md`](../README.md); for every switch see [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) appendix A.
|
||||
|
||||
## 三种构建
|
||||
## Three builds
|
||||
|
||||
P13 起只有一种单进程形态:后端只从前端推来的记录取状态(记录臂),旧的「后端直接读前端」路径与 pull / push 两套构建一起删掉了(`MOBILEGL_PIPE_PUSH` 不再是 CMake 选项)。
|
||||
Since P13 there is only one single-process shape: the backend takes its state solely from the records the frontend pushes (the record arm); the old "backend reads the frontend directly" path went away together with the pull / push builds (`MOBILEGL_PIPE_PUSH` is no longer a CMake option).
|
||||
|
||||
| 构建目录 | CMake | 用途 |
|
||||
| Build directory | CMake | Purpose |
|
||||
|---|---|---|
|
||||
| `build-linux` | 默认 | 出货形态(FCL 内嵌库就是它):单进程,记录臂,不编 `MG_Remote` |
|
||||
| `build-verify` | `-DMOBILEGL_PIPE_VERIFY=ON` | 每个 draw 把推来的状态与前端实际状态逐字段比对;慢,永不出货 |
|
||||
| `build-split` | `-DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON` | 可以拆成两线程 / 两进程 / 两台机器;不设 `MOBILEGL_TRANSPORT` 时是同一记录臂的单进程对照 |
|
||||
| `build-linux` | default | The shipped shape (the FCL embedded library is this one): single process, record arm, `MG_Remote` not built |
|
||||
| `build-verify` | `-DMOBILEGL_PIPE_VERIFY=ON` | Every draw compares the pushed state field by field with the frontend's actual state; slow, never shipped |
|
||||
| `build-split` | `-DMOBILEGL_BUILD_DISAGGREGATED=ON -DMOBILEGL_BUILD_DISAGGREGATED_INPROC=ON` | Can split into two threads / two processes / two machines; with `MOBILEGL_TRANSPORT` unset it is the single-process control on the same record arm |
|
||||
|
||||
库由七个 OBJECT 模块拼成(`mg_util` / `mg_pipe` / `mg_backend` / `mg_frontend` / `mg_remote_transport` / `mg_remote_client` / `mg_remote_server`,按 `scripts/link_ratchet.py` 的 PARTITION 划分);split 构建另有 `MobileGL_server_linkcheck`,证明 server 那一半不带前端模块也能链接(剩下的前端引用是 link ratchet 基线里具名的债务)。
|
||||
The library is assembled from seven OBJECT modules (`mg_util` / `mg_pipe` / `mg_backend` / `mg_frontend` / `mg_remote_transport` / `mg_remote_client` / `mg_remote_server`, partitioned by `scripts/link_ratchet.py`); the split build also has `MobileGL_server_linkcheck`, which proves the server half links without the frontend modules (the remaining frontend references are named debts in the link-ratchet baseline).
|
||||
|
||||
## 选拓扑
|
||||
## Choosing a topology
|
||||
|
||||
split 构建在运行时用 `MOBILEGL_TRANSPORT` 选拓扑;**不设就是单进程(monolith)对照**:
|
||||
The split build selects the topology at run time with `MOBILEGL_TRANSPORT`; **unset means the single-process (monolith) control**:
|
||||
|
||||
| `MOBILEGL_TRANSPORT` | 形态 |
|
||||
| `MOBILEGL_TRANSPORT` | Shape |
|
||||
|---|---|
|
||||
| 不设 / `monolith` | 单线程直调 |
|
||||
| `inproc` | 同一进程两个线程(CI 的主验收形态) |
|
||||
| `spawn` | 两个进程;再用 `MOBILEGL_IPC_CONTROL`(`fork` / `unix:<path>` / `tcp://host:port`)与 `MOBILEGL_IPC_DATA`(`auto` / `shm` / `stream`)选控制面与数据面,跨机时还要 `MOBILEGL_IPC_TOKEN`(≥16 字节) |
|
||||
| unset / `monolith` | Single thread, direct calls |
|
||||
| `inproc` | Two threads in one process (the main CI acceptance shape) |
|
||||
| `spawn` | Two processes; `MOBILEGL_IPC_CONTROL` (`fork` / `unix:<path>` / `tcp://host:port`) and `MOBILEGL_IPC_DATA` (`auto` / `shm` / `stream`) then choose the control and data planes; across machines also set `MOBILEGL_IPC_TOKEN` (at least 16 bytes) |
|
||||
|
||||
```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 环境与私有日志
|
||||
ctest --test-dir build-split -L 'integration-(spawn|tcp)' --output-on-failure # the entries carry their own spawn / tcp environment and private logs
|
||||
```
|
||||
|
||||
其他常用旋钮:`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:` 行)。
|
||||
Other common knobs: `MOBILEGL_IPC_RUN_AHEAD` (default 1, the client sends and moves on), `MOBILEGL_IPC_STAGE_MB` (default 32; a quarter of it is the chunk budget for large uploads), `MOBILEGL_IPC_SURFACE=server` (use the Android server's own window), `MOBILEGL_PIPE_STATS=1` (boundary counters, the `MGPipe stats:` lines in the log).
|
||||
|
||||
## Android
|
||||
|
||||
- 两份 APK flavour:单进程 / split(Gradle 属性 `mobilegl.buildDisaggregated`、`mobilegl.buildDisaggregatedInproc`;独立 plugin 构建默认 split,FCL 内嵌默认单进程)。split APK 同样要设 `MOBILEGL_TRANSPORT`,不设就是单进程对照。
|
||||
- 设备侧 server 有两种形态:离屏的前台 Service(`MobileGLServerService`)与上屏的 `MobileGLDisplayActivity`;同一时刻只有一个。plugin 与 trace 两个 flavour 的 APK 都带(standalone 构建默认开 `mobilegl.buildDisaggregated`),入口是 APK 底部导航栏的 “Render Server” 页;plugin flavour 的这三个组件不导出,只有 trace 允许 adb 直接按组件名拉起。
|
||||
- 电脑当 client、手机当 server 的跨机配置(起 server、设令牌、`adb forward` 备用路线)见 git 历史中的"两边怎么配"。
|
||||
- 性能对比只用 Redmi `2f7cbe2e`,按 [`pin-verification-2026-09-07.md`](pin-verification-2026-09-07.md) 定频,reboot-clean、同热窗口、配对 A/B。P13 之后的性能工作以 `dev` 分支构建为「之前」基线(用户 2026-10-07)。
|
||||
- Two APK flavors: single-process / split (Gradle properties `mobilegl.buildDisaggregated`, `mobilegl.buildDisaggregatedInproc`; a standalone plugin build defaults to split, the FCL embedding defaults to single-process). The split APK also needs `MOBILEGL_TRANSPORT`; unset means the single-process control.
|
||||
- The on-device server has two shapes: an off-screen foreground Service (`MobileGLServerService`) and the on-screen `MobileGLDisplayActivity`; only one at a time. Both the plugin and trace flavor APKs carry them (standalone builds enable `mobilegl.buildDisaggregated` by default); the entry point is the "Render Server" page in the APK's bottom navigation. In the plugin flavor these three components are not exported; only the trace build allows adb to start them directly by component name.
|
||||
- For the cross-machine setup with the computer as client and the phone as server (starting the server, setting the token, the `adb forward` fallback), see "configuring the two sides" in the phase notes (in git history).
|
||||
- Performance comparisons use only the Redmi `2f7cbe2e`, pinned as described in the pin-verification record (in git history): reboot-clean, same thermal window, paired A/B. Performance work after P13 uses the `dev` build as its "before" baseline (user, 2026-10-07).
|
||||
|
||||
@@ -1,14 +1,14 @@
|
||||
# 代码地图
|
||||
# Code map
|
||||
|
||||
> 参考。文档导航见 [`../README.md`](../README.md);目录布局与构建选项见 [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) §16。
|
||||
> Reference. For the documentation index see [`../README.md`](../README.md); for the directory layout and build options see [`../design/09-build-switches-counters.md`](../design/09-build-switches-counters.md) §16.
|
||||
|
||||
| 路径 | 作用 |
|
||||
| Path | Role |
|
||||
|---|---|
|
||||
| `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 工具 |
|
||||
| `MobileGL/MG_Pipe/` | The interface itself: the call catalog `PipeCalls.def` and the other `.def` tables, the payload / handle / callback headers, `PipeApply`, `PipeRoute`, `generated/*.inc` (generated, committed to the tree) |
|
||||
| `MobileGL/MG_Impl/Pipe/` | Frontend: Tracker, `PipeFill`, `SlotAllocator`, `CsoCache`, `CompositeResolver`, `ResourceTracker`, the per-family `*Emit.h` |
|
||||
| `MobileGL/MG_Backend/MGPipe/` | `PipeInputs`: the state block the backend reads and the frontend pushes |
|
||||
| `MobileGL/MG_Remote/` | Split-only (`MOBILEGL_BUILD_DISAGGREGATED`): `Protocol/` (control-plane schema), `Transport/` (control plane `ITransport` × data plane `ILink`), `Wire/` (record encoding and decoding), `Client/`, `Server/`; the per-phase wire contracts `CONTRACT-*.md` |
|
||||
| `MobileGL/MG_Util/Metrics/PipeStats.{h,cpp}` | Boundary counters (`MOBILEGL_PIPE_STATS=1`) |
|
||||
| `MobileGL/MG_Test/Pipe/`, `MG_Test/Wire/`, `MG_IntegrationTest/Harness/*Peek` | Catalog / tracker / emitter unit tests, wire and remote unit tests, white-box assertions |
|
||||
| `scripts/` | Generators (`gen_pipe.py`, `gen_pipe_field_ownership.py`, `gen_pipe_dirty_surface.py`, `gen_protocol.py`), gate scripts (`symbol_report.py`, `check_include_closure.py`, `link_ratchet.py`, the G5 protected-region scripts, `check_doc_citations.py`), `ci/` |
|
||||
| `tools/trace_replay/`, `tools/device_bench/` | Trace replay (including the TCP matrix runner), device clock pinning and paired A/B tooling |
|
||||
|
||||
@@ -1,21 +1,21 @@
|
||||
# 工程纪律与验证门
|
||||
# Engineering discipline and verification gates
|
||||
|
||||
> 参考。验证门的设计见 [`../design/07-memory-readback-verification.md`](../design/07-memory-readback-verification.md) §13.2;各阶段实际跑门的结果在 `../notes/<阶段>/README.md`。
|
||||
> Reference. The design of the verification gates is in [`../design/07-memory-readback-verification.md`](../design/07-memory-readback-verification.md) §13.2; the per-phase gate results are in the phase notes (in git history).
|
||||
|
||||
## 每个提交
|
||||
## Every commit
|
||||
|
||||
- 默认 ALL target 必须完整构建;禁止提交热路径插桩(CI grep 门)。
|
||||
- **每个门必须能因它存在的理由变红**:带阴性对照并真跑过一次红(R-16);公共 GL 看不见的改用白盒断言。
|
||||
- 正确性门是硬门;**性能只记录、不设门**(用户 2026-09-08),但数字必须真的采到。专门的优化阶段排在路线图推完之后;P13 之后的性能轮以 `dev` 构建为基线(用户 2026-10-07)。
|
||||
- **拆分不顺手修 `dev` 的 bug**:发现的 `dev` 侧缺陷记成独立条目、独立 PR。
|
||||
- The default ALL target must build completely; instrumenting hot paths is not allowed in commits (a CI grep gate).
|
||||
- **Every gate must be able to turn red for the reason it exists**: it has a negative control and has really run red once (R-16); what public GL cannot see is asserted white-box instead.
|
||||
- Correctness gates are hard gates; **performance is recorded, not gated** (user, 2026-09-08), but the numbers must actually be measured. Dedicated optimization phases come after the roadmap; performance rounds after P13 use the `dev` build as the baseline (user, 2026-10-07).
|
||||
- **Do not fix `dev` bugs along the way**: a defect found on the `dev` side becomes its own entry and its own PR.
|
||||
|
||||
## 每个阶段出口
|
||||
## Every phase exit
|
||||
|
||||
- 跑一次五部分门:接口纯度、语义影子比对、行为 A/B、性能记录、覆盖与句柄纪律。
|
||||
- 字节 / 名字级等式:**G5** 受保护区域逐字节一致;**G14** 测试名只增不删。**G1**(pull 构建的符号集与 `.text` 对基线恒等)与 **G2**(pull 与 push 的测试名集合相同)随 pull 构建在 P13 退役;接班的是:出货库零 `MG_Remote` 符号检查、skip 普查(新出现的跳过与消失的名字都要在基线里具名)、recorder 金标(`MG_Test/Pipe/RecorderGoldenTest.cpp`:固定 GL 调用序列的记录流逐条比对,改金标要在提交里说为什么),以及 link ratchet(server 一半对前端的引用只减不增,不允许 `# P13` 注解)。
|
||||
- 性能判据是**逐线程 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)。
|
||||
- Run the five-part gate once: interface purity, semantic shadow comparison, behavioral A/B, performance record, coverage and handle discipline.
|
||||
- Byte and name level equalities: **G5** protected regions are byte-identical; **G14** test names only grow. **G1** (the pull build's symbol set and `.text` identical to the baseline) and **G2** (the pull and push builds have the same set of test names) retired with the pull build in P13; their successors are: the zero-`MG_Remote`-symbol check on the shipped library, the skip census (newly appearing skips and disappearing names must be named in the baseline), the recorder golden (`MG_Test/Pipe/RecorderGoldenTest.cpp`: record streams from a fixed GL call sequence compared one by one; changing the golden requires saying why in the commit), and the link ratchet (the server half's references to the frontend only fall, and `# P13` annotations are not allowed).
|
||||
- The performance criterion is **per-thread CPU time**; device comparisons use reboot-clean + same-thermal-window paired A/B, on the Redmi `2f7cbe2e` only (pin-verification record, in git history); a Windows machine is not a correctness gate.
|
||||
- The close-out is reviewed once by a different model family; findings enter the first round of the next phase; implementers and reviewers use different model families; do not over-verify (user, 2026-09-16, ID-66).
|
||||
|
||||
## CTS
|
||||
|
||||
`gl44to46` 约 56,271 例,单独计价:逐阶段只跑该阶段可能影响的具名块;完整 caselist 只在架构边界与合并 `dev` 之前跑,放 CI 不放关键路径。
|
||||
`gl44to46` has about 56,271 cases and is priced separately: each phase runs only the named blocks it can affect; the full caselist runs only at architecture boundaries and before merging into `dev`, in CI rather than on the critical path.
|
||||
|
||||
@@ -1,49 +1,59 @@
|
||||
# 在宿主 APK 中嵌入 split server
|
||||
# Embedding the split server in a host APK
|
||||
|
||||
宿主应用可直接加载 `libMobileGL.so`,把自己持有的 `ANativeWindow` 交给 server。
|
||||
窗口、输入和 Android Service 的生命周期由宿主 APK 管理;不需要安装 MobileGL plugin APK。
|
||||
公共接口是 [`EmbeddedServer.h`](../../../MobileGL/MG_Remote/Server/EmbeddedServer.h),
|
||||
只使用 C 类型,也可通过 `dlsym` 调用。构建必须开启 `MOBILEGL_BUILD_DISAGGREGATED`。
|
||||
A host application can load `libMobileGL.so` directly and hand the server an `ANativeWindow` it owns.
|
||||
The window, input and the Android Service lifecycle stay with the host APK; no MobileGL plugin APK is
|
||||
needed. The public interface is
|
||||
[`EmbeddedServer.h`](../../../MobileGL/MG_Remote/Server/EmbeddedServer.h), uses only C types, and can
|
||||
also be called through `dlsym`. The build must enable `MOBILEGL_BUILD_DISAGGREGATED`.
|
||||
|
||||
## 有窗口的合成器服务
|
||||
## Compositor service with a window
|
||||
|
||||
在加载库前设置 `MOBILEGL_IPC_ROLE=server`、`MOBILEGL_IPC_DIAL=no`,清除
|
||||
`MOBILEGL_TRANSPORT`、`MOBILEGL_IPC_SERVER_PATH`、`MOBILEGL_IPC_RING_MB` 和
|
||||
`MOBILEGL_IPC_STAGE_MB`。建议放在宿主 APK 的独立服务进程中,以免渲染故障结束 UI 进程。
|
||||
Before loading the library, set `MOBILEGL_IPC_ROLE=server` and `MOBILEGL_IPC_DIAL=no`, and clear
|
||||
`MOBILEGL_TRANSPORT`, `MOBILEGL_IPC_SERVER_PATH`, `MOBILEGL_IPC_RING_MB` and
|
||||
`MOBILEGL_IPC_STAGE_MB`. Running in a separate service process of the host APK is recommended, so that
|
||||
a rendering fault does not take down the UI process.
|
||||
|
||||
1. 调用 `mobilegl_server_display_install_android(request_geometry, user)`。
|
||||
回调可为空;有回调时,它在 apply 线程运行,必须快速返回,把尺寸变更交给宿主线程。
|
||||
2. 从宿主的 `Surface` 获取 `ANativeWindow`,调用
|
||||
`mobilegl_server_display_attach_android(window, width, height)`。
|
||||
server 独立持有引用,调用者随后释放自己的引用。同一窗口再次 attach 只更新尺寸。
|
||||
3. 在服务线程调用 `mobilegl_server_serve_inprocess("@anland-mobilegl-compositor")`。
|
||||
这会在当前进程接受一个 client 会话。AF_UNIX 控制连接用 `SCM_RIGHTS` 传递共享内存段,
|
||||
数据通过 SHM 环传输。客户端设置 `MOBILEGL_TRANSPORT=spawn`、
|
||||
`MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl-compositor`、`MOBILEGL_IPC_DATA=shm` 和
|
||||
`MOBILEGL_IPC_SURFACE=server`。
|
||||
4. Surface 销毁时调用 `mobilegl_server_display_detach(3000)`。
|
||||
返回值 `0/1/2/3` 分别为无窗口、直接释放、会话释放后完成、超时。
|
||||
超时会保留引用,直到 apply 线程停止使用窗口;当前失窗会结束活动会话。
|
||||
5. 服务停止时调用 `mobilegl_server_stop_inprocess()`,等待 serve 线程返回,再调用
|
||||
`mobilegl_server_display_uninstall(3000)`。几何回调的 user 对象应至少活到此时。
|
||||
1. Call `mobilegl_server_display_install_android(request_geometry, user)`.
|
||||
The callback may be null; when present it runs on the apply thread, must return quickly, and hands
|
||||
size changes to the host thread.
|
||||
2. Take an `ANativeWindow` from the host's `Surface` and call
|
||||
`mobilegl_server_display_attach_android(window, width, height)`.
|
||||
The server holds its own reference; the caller then releases its own. Attaching the same window
|
||||
again only updates the size.
|
||||
3. On the service thread, call `mobilegl_server_serve_inprocess("@anland-mobilegl-compositor")`.
|
||||
This accepts one client session in the current process. The AF_UNIX control connection passes the
|
||||
shared-memory segment with `SCM_RIGHTS`, and data travels over a SHM ring. The client sets
|
||||
`MOBILEGL_TRANSPORT=spawn`, `MOBILEGL_IPC_CONTROL=unix:@anland-mobilegl-compositor`,
|
||||
`MOBILEGL_IPC_DATA=shm` and `MOBILEGL_IPC_SURFACE=server`.
|
||||
4. When the Surface is destroyed, call `mobilegl_server_display_detach(3000)`.
|
||||
The return values `0/1/2/3` mean no window, released directly, completed after the session
|
||||
released it, and timed out. On timeout the reference is kept until the apply thread stops using the
|
||||
window; losing the window currently ends the active session.
|
||||
5. When the service stops, call `mobilegl_server_stop_inprocess()`, wait for the serve thread to
|
||||
return, then call `mobilegl_server_display_uninstall(3000)`. The geometry callback's user object
|
||||
must live at least until then.
|
||||
|
||||
`width/height` 为零时,Android attach 从 `ANativeWindow` 查询尺寸。几何回调收到正尺寸表示
|
||||
请求固定缓冲尺寸,收到 `0/0` 表示恢复宿主布局尺寸;宿主应通过后续 attach 报告实际结果。
|
||||
安装、attach、detach 和 uninstall 由宿主串行调用。库拒绝替换已安装的 display 或尚未结束
|
||||
的旧窗口租约,避免晚到的释放使用另一组引用回调。
|
||||
When `width/height` are zero, the Android attach queries the size from the `ANativeWindow`. A positive
|
||||
size in the geometry callback requests fixed buffer dimensions; `0/0` means restore the host's layout
|
||||
size, and the host reports the actual result through a later attach. Install, attach, detach and
|
||||
uninstall are serialized by the host. The library refuses to replace an installed display or an old
|
||||
window lease that has not ended, so that a late release cannot use another set of reference callbacks.
|
||||
|
||||
## 并发的离屏应用服务
|
||||
## Concurrent off-screen application service
|
||||
|
||||
一个进程仍只有一套 backend/GL 状态。有窗口的服务只接一个合成器;其他 EGL client 可连接
|
||||
宿主 APK 打包的 `libMobileGLServer.so` 可执行文件,由另一个服务进程负责启动和结束:
|
||||
A process still has only one set of backend / GL state. A service with a window accepts a single
|
||||
compositor; other EGL clients can connect to the `libMobileGLServer.so` executable packaged by the
|
||||
host APK, which another service process starts and stops:
|
||||
|
||||
```text
|
||||
<nativeLibraryDir>/libMobileGLServer.so @anland-mobilegl --serve --max-sessions 16
|
||||
```
|
||||
|
||||
`--max-sessions` 是活动会话上限,接受 `1..64`,默认仍为 `1`。大于 `1` 只适用于
|
||||
AF_UNIX 的 `--serve` 离屏 supervisor。每个 client 单独 fork worker,拥有独立 backend,
|
||||
共享内存与其他会话隔离;worker 退出后归还名额,supervisor 结束时所有 worker 一起结束。
|
||||
这些 worker 没有 display,客户端应清除 `MOBILEGL_IPC_SURFACE`,由客户端 WSI 提交窗口图像。
|
||||
`--max-sessions` is the limit on active sessions; it accepts `1..64` and still defaults to `1`. Values
|
||||
above `1` apply only to the AF_UNIX `--serve` off-screen supervisor. Each client forks its own worker
|
||||
with an independent backend, isolated from other sessions in shared memory; a worker returning frees
|
||||
its slot, and all workers end when the supervisor ends. These workers have no display; the client
|
||||
should clear `MOBILEGL_IPC_SURFACE` and submit window images through its own WSI.
|
||||
|
||||
进程隔离解决多个应用同时连接的问题;同一应用中的真正多 context/share-group 支持仍需另行实现。
|
||||
Process isolation solves multiple applications connecting at the same time; true multi-context /
|
||||
share-group support inside one application still needs separate work.
|
||||
|
||||
@@ -1,23 +1,23 @@
|
||||
# 术语
|
||||
# Terms
|
||||
|
||||
> 参考。文档导航见 [`../README.md`](../README.md)。
|
||||
> Reference. For the documentation index see [`../README.md`](../README.md).
|
||||
|
||||
| 术语 | 意思 |
|
||||
| Term | Meaning |
|
||||
|---|---|
|
||||
| 前端 / 后端 | 前端 = `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 私有的"我重建了驱动对象"纪元,永不过线;与句柄代数严格分开 |
|
||||
| frontend / backend | frontend = `MG_State` + `MG_Impl`, handling the application's GL calls; backend = `MG_Backend`, calling the driver for real |
|
||||
| Espryt / Magma | The two backends: Espryt goes through OpenGL ES (DirectGLES), Magma through Vulkan (DirectVulkan) |
|
||||
| client / server | The frontend role / backend role after the split; they can be two threads, two processes or two machines |
|
||||
| monolith / inproc / spawn | The three topologies: single thread direct calls / two threads in one process / two processes (optionally across machines) |
|
||||
| pull / push | The backend reads the frontend's state itself (the old way) / the frontend pushes state to the backend (MGPipe) |
|
||||
| verb | A command that makes the backend actually do work: draw, dispatch, clear, blit, readback, XFB, query, texture operations. State is pushed only before a verb |
|
||||
| handle `{slot, gen}` | An object's identity: a client-allocated slot plus the reuse generation; the server never sends it back |
|
||||
| CSO | Constant state object (render state, vertex format, sampler, sampler view, shader): the client deduplicates by content, the server caches by handle |
|
||||
| control plane / data plane | The connection carrying the handshake and rare control messages / the channel carrying command records and bulk data; each can choose shared memory or a byte stream, local or TCP |
|
||||
| lockstep / run-ahead | The client waits for the server after every command / the client sends and moves on, waiting only for commands that need an answer |
|
||||
| barrier tax | The extra per-thread CPU cost of splitting into two threads (split − push) |
|
||||
| device-lost | The state the client enters after the server crashes or disconnects: GL calls become no-ops and swap buffers returns "context lost" instead of crashing or hanging |
|
||||
| class A / B / C | Slots in the backend function table: A answers locally, B becomes a record, C is not migrated yet and is refused by name |
|
||||
| Track V / Track H | Migration of value-class read points (a whole block crosses the wire) / migration of object-class read points (object pointers become handles) |
|
||||
| G1 / G2 / G5 / G14 | Verification gates: single-process build binary byte-identical / pull and push have the same test-name set / protected backend functions byte-identical / test names only grow |
|
||||
| red-once (R-16) | Every gate must really have run red once, proving it can fail for the problem it is meant to catch |
|
||||
| `MGGen` | The server's private "I rebuilt the driver object" epoch; it never crosses the wire and is kept strictly separate from the handle generation |
|
||||
|
||||
Reference in New Issue
Block a user