Initial LinuxCNC WebAssembly workspace snapshot
This commit is contained in:
124
docs/linuxcnc-web-wasm-implementation-readiness.md
Normal file
124
docs/linuxcnc-web-wasm-implementation-readiness.md
Normal file
@@ -0,0 +1,124 @@
|
||||
# LinuxCNC Web/WASM 实施准备基线
|
||||
|
||||
**状态**：M0 已落地，M1 ABI 骨架已验证，LinuxCNC 功能移植尚未完成
|
||||
**目标**：把既有技术路线收敛成可执行的实施顺序、完整性证明和发布前置条件
|
||||
**固定基线**：LinuxCNC `2.10.0~pre0`，提交 `239dcf4284762ad7e9c65d390bc5524d855c2f8e`
|
||||
**关联文档**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)、[覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)、[源程序关联](linuxcnc-web-wasm-source-map.md)、[通信设计](linuxcnc-web-wasm-frontend-communication-design.md)、[执行策略](linuxcnc-web-wasm-execution-strategy.md)、[总控手册](linuxcnc-web-wasm-integration-playbook.md)
|
||||
|
||||
本文件是开始编写程序前的单页入口。专项文档保留详细契约；本文件只固定真实基线、先后顺序、完成定义和阻断条件。
|
||||
|
||||
## 1. 现状和不可误读项
|
||||
|
||||
本仓库已经具备完整设计文档，但此前没有 Web/WASM 运行时代码。当前 M0/M1 产物如下：
|
||||
|
||||
| 产物 | 当前事实 | 允许的结论 |
|
||||
|---|---|---|
|
||||
| `context-lock.json` | 锁定 LinuxCNC 提交、Emscripten 3.1.6、schema v1 和索引哈希 | 基线可复现 |
|
||||
| `coverage/source-index.jsonl` | 7,992 个来源文件，来自 docs/src/configs/tests/unit_tests/build | 来源扫描已开始，可审计 |
|
||||
| `coverage/manifest.jsonl` | 7,992 个一对一种子条目，全部 `planned/needs_owner` | 没有来源被静默漏掉；不代表已实现 |
|
||||
| `wasm-core` | C ABI 生命周期、固定 tick、快照、导入导出骨架 | 工程边界可编译、可调用 |
|
||||
| `build-wasm`/`build-native` | WASM 模块生成，宿主 ABI 单测通过 | 构建链路可重跑 |
|
||||
|
||||
以下能力目前都不能声明完成：rs274ngc、TP、motion、kinematics、HAL、ClassicLadder、Python/remap、OPFS、Worker、UI、Three.js、全量配置和浏览器回归。
|
||||
|
||||
## 2. 产品边界和“完整”的定义
|
||||
|
||||
产品是浏览器内离线运行的 LinuxCNC **仿真机床**。状态权威在 Worker 内的 WASM/兼容运行时，主线程只负责 UI 和渲染；所有影响结果的操作都经过固定 tick、版本化协议和可恢复账本。
|
||||
|
||||
功能全集由以下集合并集产生，而不是由一组三轴演示决定：
|
||||
|
||||
```text
|
||||
LinuxCNC 文档能力
|
||||
∪ src/emc、src/hal、classicladder、lib/python 的可观察 API/符号
|
||||
∪ configs/sim/** 的全部入口和引用资源
|
||||
∪ tests/**、unit_tests/** 的全部可运行用例
|
||||
∪ Web 工程、VCP、可视化、持久化和恢复工作流
|
||||
```
|
||||
|
||||
每个功能必须同时闭合：正常、边界、错误/报警、暂停/恢复/急停、持久化/刷新/离线，以及适用的跨域交互。`accepted` 必须有实现、自动测试、oracle、差异报告和 context lock。真实硬件、内核实时性、物理安全和宿主设备访问只能标记 `REAL-EXCLUDED`，且配置检查必须返回明确错误；仿真配置依赖的主轴、编码器、探针、限位、换刀和 IO 必须用数字孪生实现。
|
||||
|
||||
## 3. 已冻结的技术决策
|
||||
|
||||
1. **核心优先复用**：posemath、rs274ngc、TP、可移植 kinematics 优先以最小补丁编译；Linux 进程、NML/CMS、共享内存、实时 API、动态加载和桌面 GUI 不直接移植。
|
||||
2. **单 Worker、单写者**：WASM、Python、HAL、虚拟设备、工作区和恢复全部在同一 Dedicated Worker 中串行；UI 不读 WASM 指针、不直接写 OPFS。
|
||||
3. **确定性时间**：`sim_step(cycles)` 是唯一推进入口；墙钟只负责节流和渲染，不参与结果计算。1x、快速、暂停恢复、单步和回放必须得到同一逻辑终点。
|
||||
4. **两层文件系统**：WASM 内同步工作树承接 LinuxCNC 文件语义；Worker 通过 OPFS journal、checkpoint 和迁移持久化，不能每个 tick 写 OPFS。
|
||||
5. **稳定 C ABI**：TypeScript 只见版本化 C ABI 和消息 schema，不暴露 C++ 布局、STL、指针或异常字符串。
|
||||
6. **Python 受控运行时**：PY-01 前不锁定运行时；启用后必须单独创建锁，固定 Pyodide、包、补丁和 artifact hash，只提供 `linuxcnc/hal/INI` 虚拟模块，拒绝 subprocess、socket、设备和宿主路径。
|
||||
7. **镜像可替换、字节不可替换**：允许中国大陆镜像、官方站点和离线缓存；下载记录必须包含 URL、版本、大小、SHA-256、许可证。镜像切换但字节相同不改变 context；字节、补丁或版本变化必须生成新 context。
|
||||
8. **先建立 oracle 再扩展功能**：原生 LinuxCNC runner 输出解释器状态、canonical、每周期运动、HAL/IO、错误和最终状态；WASM 只以首个 divergent tick、字段差异和定义容差对照。
|
||||
|
||||
## 4. 完整移植功能分层
|
||||
|
||||
| 层 | 必须覆盖的能力 | 实现策略 | 完成证据 |
|
||||
|---|---|---|---|
|
||||
| L0 配置/工作区 | INI/include、HALFILE 顺序、TBL/VAR/NGC/PY/XML/TCL/CLP、路径和诊断 | 虚拟 `/workspace` + 解析器 + OPFS | 233 个 sim INI 全部资源图；错误含文件/行 |
|
||||
| L1 解释器 | 全部 G/M/O、模态、单位、坐标系、参数、循环、补偿、remap 边界 | 复用 rs274ngc；Python 通过受控桥接 | G/M/O manifest、错误行和 golden |
|
||||
| L2 轨迹/运动 | canonical、前瞻、blend、速度/加速度、急停、暂停、jog、home、limit、following error | TP/posemath 复用；sim_motion 状态机 | 每 tick 状态、容差、恢复终点 |
|
||||
| L3 运动学 | trivkins、5 轴、gantry、CoreXY、Delta、机器人、foam 等内置模块 | 静态编译注册，按配置选择 | forward/inverse、姿态、奇异/越限错误 |
|
||||
| L4 HAL/PLC | pin/signal/param、thread/function/addf、全量仿真组件、ClassicLadder | `.comp` 构建期清单 + 固定扫描顺序 | 组件条目、HAL graph、scan/golden |
|
||||
| L5 虚拟设备 | 主轴、编码器、stepgen、探针、限位、换刀、冷却、等离子/激光 | 可脚本化数字孪生和故障注入 | 正常/不到速/超时/失败/恢复 |
|
||||
| L6 Python/VCP | linuxcnc/hal API、remap/filter、VCP 回调和权限 | Pyodide Worker + manifest 能力授权 | API/异常/资源限制/隔离 |
|
||||
| L7 Web 工作流 | 工程、编辑器、MDI、run/pause/abort、jog/home、工具/IO/报警、HAL/PLC | React+TS，WorkerClient，domain store | 浏览器 E2E、键盘/触摸、恢复 |
|
||||
| L8 可视化/发布 | 轨迹、姿态、刀具、毛坯、日志、导入导出、离线 PWA、兼容/许可证报告 | Three.js + transferable streams + 发布清单 | 多浏览器、性能、离线和回滚演练 |
|
||||
|
||||
## 5. 可执行路线和退出条件
|
||||
|
||||
### M0：基线和来源闭包（已完成第一版）
|
||||
|
||||
入口是 LinuxCNC 版本和提交已确认。必须生成 source index、manifest seed、context lock、状态枚举、扫描器版本和下载策略。退出条件是索引/manifest 哈希与锁一致，重复 ID、孤儿来源和缺字段检查生效。
|
||||
|
||||
### M1：最小运行时闭环（当前）
|
||||
|
||||
先完成 `sim_create → sim_load_workspace → sim_command → sim_step → snapshot/event → export/import → destroy`，固定 ABI、错误码、消息 envelope、Worker 单会话队列和虚拟工作区最小接口。正常、非法状态、buffer 不足、暂停/恢复各至少一条测试；不得接 UI mock 作为完成证据。
|
||||
|
||||
### M2：解释器和运动核心
|
||||
|
||||
按 posemath → TP → rs274ngc → canonical → task/motion → kinematics 顺序接入。每个切片先接原生 runner 和差异报告，再接 Worker。M2 退出前，受影响核心条目必须达到 `verified`，且任何差异能定位到首个 tick/字段/源映射。
|
||||
|
||||
### M3：HAL、数字孪生、Python、持久化
|
||||
|
||||
接入 HAL 图和固定线程顺序，再接主轴/编码器/探针/限位/换刀/PLC；随后实现 OPFS prepare/commit、checkpoint、迁移、配额和 Worker 崩溃恢复，最后锁定 Python runtime 并接 remap/VCP。M3 不允许用“刷新后重新初始化”替代恢复。
|
||||
|
||||
### M4：Web 工作流和可视化
|
||||
|
||||
以真实 Worker/WASM 状态接入工程选择、编辑器、MDI、run/pause/abort、jog/home、工具/报警、HAL/PLC、3D、导入导出和离线 PWA。mock 只能用于早期 UI 结构开发，里程碑退出必须全部切换真实协议。
|
||||
|
||||
### M5：全量回归和发布
|
||||
|
||||
递归运行全部 `configs/sim/**`、可移植 `tests/**`、`unit_tests/**`、G/M/O、HAL 组件、Python API 和浏览器故障矩阵。发布包必须同时包含 WASM、Python 运行时、Service Worker、schema、source/coverage/golden manifest、兼容报告、排除项和回滚包；任何孤儿、无 oracle、未覆盖维度或静默降级都阻断发布。
|
||||
|
||||
## 6. 实施顺序（直接照此开工）
|
||||
|
||||
1. 保持 `context-lock.json` 不变，运行 M0 校验和上下文包测试。
|
||||
2. 为 `coverage/manifest.jsonl` 建立 owner/feature/domain 分配器，将 `seed:*` 按功能归并但保留一对多来源引用。
|
||||
3. 在原生 LinuxCNC 环境建立 runner，先覆盖 `unit_tests/interp`、`unit_tests/tp` 和 `configs/sim/axis/minimal_xyz.ini`，冻结 JSONL golden schema。
|
||||
4. 将 `wasm-core` 从 bootstrap API 扩展为 posemath/TP 最小链接；每加入一个源组就更新 manifest、编译参数和 ABI 测试。
|
||||
5. 实现固定 tick scheduler、事件队列、快照 schema 和 `WorkerClient`；先完成命令幂等和 `prepare/verify/commit` 账本。
|
||||
6. 实现虚拟工作区的 `open/read/write/stat/readdir/rename/unlink/fsync`，然后接 OPFS journal 和恢复，不提前接高频 UI。
|
||||
7. 接 HAL 核心和最小三轴数字孪生，完成正常/限位/急停/恢复四条端到端场景。
|
||||
8. 锁定 Python runtime（允许中国镜像下载，但必须记录校验）并接 `linuxcnc/hal`、remap 和一个 VCP descriptor。
|
||||
9. 接 React/TypeScript AppShell、状态面板、G-code/MDI 和 Three.js 轨迹；只消费 Worker 快照和 transferable 流。
|
||||
10. 扩展全部配置、组件、运动学、GUI 工作流和回归矩阵，按 M2-M5 门禁推进。
|
||||
|
||||
## 7. 必须持续保持的检查
|
||||
|
||||
```bash
|
||||
python3 scripts/generate_source_inventory.py
|
||||
python3 scripts/validate_baseline.py
|
||||
python3 scripts/validate_download_index.py
|
||||
python3 -m unittest discover -s scripts -p 'test_*.py' -v
|
||||
scripts/build-wasm.sh
|
||||
```
|
||||
|
||||
清单重生成后若哈希变化，必须先审查来源差异并创建新 context；不能直接覆盖锁文件。任何新下载都必须进入 `vendor/downloads/index.jsonl`（M1 前建立），任何新源码、配置或测试都必须在同一变更中更新 manifest。只有 `validate_baseline`、受影响测试、原生/WASM 对照和相应恢复场景都通过，任务才可从 `implemented` 进入 `verified`。
|
||||
|
||||
## 8. 当前明确风险
|
||||
|
||||
- 现有 LinuxCNC `meson.build` 面向原生依赖（Python、Boost、`libdl`），不能直接作为 Emscripten 构建；WASM 必须保持独立 CMake 目标。
|
||||
- `configs/sim` 文件量大且资源类型复杂，清单生成必须先于功能归并；不能用目录状态或抽样配置宣称全覆盖。
|
||||
- 浏览器没有 PREEMPT_RT；任何依赖墙钟的行为都必须改成逻辑 tick，并单独报告实时性不等价。
|
||||
- OPFS 有配额和淘汰风险；已提交版本、导出备份和配额错误必须优先于自动保存便利性。
|
||||
- Python、GUI 和 HAL 组件是最大移植面；它们必须按受控能力和静态清单接入，不允许把宿主进程/设备能力直接暴露给工程脚本。
|
||||
|
||||
当前基线允许开始编写程序，但只允许从 M1 的 ABI、runner、工作区和协议契约开始；在 M0/M1 证据闭合前，不应投入全量 UI 或声称 LinuxCNC 功能已经移植完成。
|
||||
Reference in New Issue
Block a user