83 lines
4.8 KiB
Markdown
83 lines
4.8 KiB
Markdown
# 11-WASM核心状态机边界与后续完善路线
|
||
|
||
## 目标
|
||
|
||
本文件固定后续完善 `wasm-port` 程序时的边界：WASM/C++ 程序作为核心状态机实现的运行载体，JS/SDK 和 JSON 只承担 host/browser 边界职责。
|
||
|
||
后续新增代码任务前，必须先把对应任务补入 `04-任务矩阵.md`，写明验收标准和 gate，再按本文件推进。
|
||
|
||
## 分层边界
|
||
|
||
| 层 | 职责 | 不应承担 |
|
||
| --- | --- | --- |
|
||
| WASM/C++ | LinuxCNC 语义复用、task/motion 核心状态机、task cycle、motion snapshot、command read/plan/execute、RCS 聚合、`StandaloneEmcStatus` | 浏览器 UI 状态、DOM、OPFS 业务流程、JSON 文本状态机 |
|
||
| JS/SDK | 加载 WASM、管理 Emscripten FS/OPFS 边界、传入 command JSON、读取 status JSON、提供测试和 UI 友好 API | G-code 语义、task/motion 状态机、LinuxCNC planner/canon 语义 |
|
||
| JSON | host 与 WASM 的输入/输出通信格式，例如 `lctask_send_command_json()` 和 `lctask_read_status_json()` | 保存事实状态、推进 task 周期、执行 motion 语义、替代结构体状态 |
|
||
|
||
## 核心原则
|
||
|
||
1. `lctask_run_cycles()` 是 task 状态变化的主入口。
|
||
2. `lctask_send_command_json()` 只入队 host command，不直接改变 LinuxCNC task/motion 语义状态。
|
||
3. `lctask_read_status_json()` 只导出最后一次 status write，不推进 cycle、不重新读取 motion、不触发 command 执行。
|
||
4. 核心状态保存在 C/C++ 结构体、枚举、队列和周期函数中；当前集中容器为 `StandaloneEmcStatus`。
|
||
5. motion 状态通过 `LcmotStatusSnapshot` 在 task 周期内读入，再映射到 `StandaloneEmcStatus.motion`。
|
||
6. JSON 字段可以兼容旧 SDK/UI，但必须从核心结构体导出，不能成为新的事实源。
|
||
7. 若 LinuxCNC 上游源码已有对应语义，优先接入 vendored source 或窄 shim，不在 JS/JSON 中重写。
|
||
|
||
## 当前事实源
|
||
|
||
当前阶段的事实源如下：
|
||
|
||
- task cycle skeleton：`linuxcnc_task_hal_wasm.cpp` 中的 command read、plan、execute、motion update、subordinate sync、task update、status write。
|
||
- task/motion/io/top status：`StandaloneEmcStatus`。
|
||
- motion runtime snapshot：`LcmotStatusSnapshot` 和 `lcmot_read_status_snapshot()`。
|
||
- RUN 主路径：staged program -> `emcTaskPlanRead()` -> `emcTaskPlanCommand()` -> `emcTaskPlanExecute()` -> `emccanon.cc` command envelope -> `taskintf.cc` motion issue。
|
||
- JSON status：`statusSource=StandaloneEmcStatus` 的外部导出视图。
|
||
|
||
status JSON 的 LinuxCNC `EMC_STAT` 字段映射、兼容策略和后续 SJ 批次见 `12-status-json-LinuxCNC对标方案.md`。
|
||
|
||
当前 `12-status-json-LinuxCNC对标方案.md` 中 SJ-1 到 SJ-5 已补入 `04-任务矩阵.md` 的 T-051 到 T-055，并已闭合。后续不得再只用“后续路线”描述实际任务；凡是出现可执行实现项，必须同步进入任务矩阵。
|
||
|
||
## 后续完善路线
|
||
|
||
后续 WASM 程序完善应按以下顺序拆成新任务：
|
||
|
||
1. 扩展 `StandaloneEmcStatus` 字段覆盖，而不是扩展 status JSON 自有字段。
|
||
2. 将更多 `TaskRuntime` 分散字段迁移到 task/motion/io/top status 容器。
|
||
3. 继续把 plan/execute 分支替换为 vendored `emctask.cc`、`taskintf.cc`、`emccanon.cc` 的 source-anchored 子集。
|
||
4. 扩展 `taskintf.cc` usrmot shim，使 motion command/status/config/error 的映射更接近上游。
|
||
5. 评估 `emc_nml.hh` 的分阶段 typedef 或窄编译复用，但不得为了 readiness 提前引入完整 native NML/process topology。
|
||
6. 将新增状态字段同步补齐 WASM smoke、SDK smoke、state matrix 和 source reuse/drift docs gate。
|
||
7. 只有在完整 native task/HAL/runtime 边界被实际采用并验证后，才能提升 `nativeTaskReady`、`nativeHalSyncReady` 或 `fullLinuxCncProgramExecutionReady`。
|
||
|
||
本轮已闭合的 status JSON 子任务：
|
||
|
||
- T-051 / SJ-1：`emcStatus.motion.traj`。
|
||
- T-052 / SJ-2：task current/read/motion line 和 call level。
|
||
- T-053 / SJ-3：`emcStatus.motion.axis[]` 与 `joint[]`。
|
||
- T-054 / SJ-4：`emcStatus.io.aux/tool/coolant` 窄边界。
|
||
- T-055 / SJ-5：`tools/verify_task_status_json_contract.sh`。
|
||
|
||
## 代码修改检查清单
|
||
|
||
每次按本路线改 WASM runtime 时，至少检查：
|
||
|
||
- 新状态是否有 C/C++ 结构体字段，而不是只新增 JSON 字段。
|
||
- 新 command 是否先入队，再由 `lctask_run_cycles()` 消费。
|
||
- 新 status JSON 字段是否从 `StandaloneEmcStatus` 或明确的 C/C++ status buffer 导出。
|
||
- JS/SDK 是否只做边界包装和兼容 API。
|
||
- 是否新增或更新 `tools/verify_task_*` gate。
|
||
- 是否同步更新 `03-推进台账.md`、`05-验收证据.md`、`06-决策记录.md`。
|
||
|
||
## 验收要求
|
||
|
||
后续实现任务完成时，至少运行：
|
||
|
||
```bash
|
||
cd /home/mes123456/cnc_wams/wasm-port
|
||
./tools/verify_task_full_closure.sh
|
||
git diff --check
|
||
```
|
||
|
||
如任务新增专用 gate，应先运行专用 gate，再运行 full closure gate。
|