6.8 KiB
6.8 KiB
01-项目功能内容
项目目标
将 wasm-port 的 task/motion/HAL 运行时从当前 minimal adapter 推进到尽可能贴近 LinuxCNC 原生 emctaskmain.cc 的 task 主循环结构。
核心要求：
- 每个 task 周期都建立 LinuxCNC 式 motion 状态快照。
- task 状态机使用该 motion 快照驱动等待、错误、estop、abort、queueFull、in-position、program line 等行为。
- 周期顺序对标上游
emctaskmain.cc：command read -> plan -> execute -> motion update -> subordinate sync -> task update -> status write。 - 当前 JSON 自有状态机逐步收缩为 host/runtime 边界，CNC/task 语义优先来自 LinuxCNC 源码。
- 后续 WASM 程序定位为核心状态机实现的运行载体：task/motion 状态机、周期调度、状态聚合、命令执行位于 C/C++ WASM 侧；JS/SDK 和 JSON 只承担外部边界职责。
对标源
主要对标文件：
/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emctaskmain.cc/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emctask.cc/home/mes123456/cnc_wams/linuxcnc/src/emc/task/taskintf.cc/home/mes123456/cnc_wams/linuxcnc/src/emc/task/emccanon.cc/home/mes123456/cnc_wams/linuxcnc/src/emc/task/task.hh/home/mes123456/cnc_wams/linuxcnc/src/emc/nml_intf/emc.hh/home/mes123456/cnc_wams/linuxcnc/src/emc/nml_intf/emc_nml.hh/home/mes123456/cnc_wams/linuxcnc/src/emc/motion/usrmotintf.h/home/mes123456/cnc_wams/linuxcnc/src/emc/motion/motion.h
当前 WASM 侧入口：
/home/mes123456/cnc_wams/wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_task_hal_wasm.cpp/home/mes123456/cnc_wams/wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c/home/mes123456/cnc_wams/wasm-port/runtime/sdk/src/linuxcnc-task-hal.js
当前闭合状态
当前 wasm-port 已有：
lctask_*C ABI。lcmot_*minimal motion runtime。- HAL pin/snapshot runtime。
- Node WASM task/motion/HAL smoke。
- LinuxCNC 式 task 周期骨架：command read -> plan -> execute -> motion update -> subordinate sync -> task update -> status write。
- 周期内
LcmotStatusSnapshot到StandaloneEmcStatus.motion的映射。 StandaloneEmcStatus作为当前阶段EMC_STAT等价容器，集中导出 task/motion/io/top status。- RUN 文件主路径通过 staged program plan read/command/execute、
emccanon.cccommand envelope 和taskintf.ccmotion issue 工作，不依赖 host JSON motion plan。 - task 状态、模式、pause/resume/step/home/run gate、wait-for-motion、queueFull、motion error、soft-limit、IO error、RCS 聚合和 no-JSON RUN path 的 WASM/SDK/state-matrix 覆盖。
当前保守边界：
- 当前 shim
runtime/core/shims/nml_intf/emc.hh只暴露motion.traj.linearUnits，远小于上游emc_nml.hh中EMC_STAT、EMC_TASK_STAT、EMC_MOTION_STAT、EMC_TRAJ_STAT的字段范围。 - task-HAL WASM 构建接入的是
emctask.cc、taskintf.cc、emccanon.cc的窄 source-anchored subset，不是完整上游 process/NML topology。 tools/task-hal-source-manifest.txt仍是 Phase 0 references，task_hal_runtime_promoted=0。nativeTaskReady=false、nativeHalSyncReady=false、fullLinuxCncProgramExecutionReady=false仍是当前 readiness contract。
WASM核心状态机边界
后续完善时按以下职责划分：
| 层 | 职责 |
|---|---|
| WASM/C++ | 核心状态机、LinuxCNC 语义复用、task cycle、motion snapshot、StandaloneEmcStatus、command read/plan/execute、RCS 聚合。 |
| JS/SDK | 加载 WASM、传命令、读状态、管理 Emscripten FS/OPFS 和浏览器/Node 边界。 |
| JSON | 作为外部通信格式，例如 command JSON 和 status JSON；不得作为核心状态机事实源。 |
因此，新增状态应优先进入 C/C++ 结构体、枚举、队列和周期函数；status JSON 只能从最后一次 status write 或 StandaloneEmcStatus 导出。
status JSON 的具体 LinuxCNC 对标方案详见 12-status-json-LinuxCNC对标方案.md。该方案要求 emcStatus 成为 LinuxCNC 对标字段的唯一 task/motion/io 状态入口；task、motionStatus、rcsStatus、taskTopLevelStatus 等旧顶层字段不再输出。
功能范围
本阶段要实现或准备实现：
- 在 WASM task runtime 内建立
EMC_STAT等价状态容器。 - 将 minimal motion runtime 的状态导入
EMC_STAT.motion等价快照。 - 重排
lctask_run_cycles()，使每个 task 周期符合上游主循环顺序。 - 把 wait-for-motion、motion queue、pause/step/resume、abort/error 逻辑改为依赖 motion 快照。
- 增加测试证明 task 周期内读取 motion，而不是只在 status API 读取时拼接 motion。
- 分阶段引入 vendored/upstream task 源码，减少自有状态机语义。
最小字段闭环
第一阶段必须优先闭合以下字段，原因是它们直接参与 emctaskmain.cc 主循环、emcTaskExecute() 或顶层 status 聚合：
| 领域 | 字段 | 用途 |
|---|---|---|
| task | state、mode |
state/mode gate、power/home/run 前置 |
| task | execState、interpState |
emcTaskPlan() 和 emcTaskExecute() 状态机 |
| task | currentLine、readLine、motionLine |
interpreter/motion line 对齐 |
| task | task_paused |
pause/resume/step |
| motion | status |
wait-for-motion、error、top-level status |
| motion.traj | enabled、inpos、queue、activeQueue、queueFull |
motion wait、queue gate、disable edge |
| motion.traj | id、paused、single_stepping |
stepping、motion id、pause |
| motion.traj | position、actualPosition、current_vel |
UI/status、interpreter sync |
| motion | on_soft_limit |
soft-limit error path |
| io | status、aux.estop |
subordinate sync、top-level status |
完整字段映射详见 07-emctaskmain周期对标蓝图.md。
后续 WASM 核心状态机完善路线详见 11-WASM核心状态机边界与后续完善路线.md。
非目标
本阶段不做：
- 驱动真实硬件。
- 浏览器内复刻 LinuxCNC 原生多进程拓扑。
- 移植 native GUI。
- 用 JavaScript 重写 CNC/task/motion 语义。
- 一次性完整移植 realtime motion controller。
完成定义
阶段完成至少满足：
- 文档记录 task 主循环对标范围、步骤、任务矩阵和验收证据。
- 新增测试能区分“task 周期读取 motion”和“status API 拼接 motion”。
lctask_run_cycles()内存在清晰的 LinuxCNC 式周期结构。nativeTaskReady、nativeHalSyncReady、fullLinuxCncProgramExecutionReady等 readiness 字段与真实能力一致。- 现有 WASM task/motion/HAL smoke 不回退。
lctask_send_command_json()不再直接产生 LinuxCNC task 语义变化；语义变化必须由后续lctask_run_cycles()的 command read/plan/execute 阶段产生。lctask_read_status_json()不推进、不同步、不重新读取 motion；它只导出最后一次 status write 的快照。