# 09-emc_nml 复用评估

## 结论

T-029 选择：暂不直接 include 完整上游 `emc_nml.hh`，当前阶段采用窄 `StandaloneEmcStatus` / 分阶段 typedef 路线。

原因：

- `wasm-port/vendor/linuxcnc/src/emc/nml_intf/` 当前未 vendored `emc_nml.hh`。
- 上游 `emc_nml.hh` 不是单纯状态结构头文件，会拉入 NML/CMS command/status message 基类和大量 interpreter/canon 依赖。
- 当前 task runtime 已有 T-028 的 `RCS_STATUS` 等价聚合行为，T-007 已建立集中 `StandaloneEmcStatus` 容器；但完整 `emc_nml.hh` 仍需要未 promoted 的 NML/CMS/message runtime 边界，因此不直接 include。
- 直接 include 会把未设计的 NML transport、CMS serialization、command message update、RS274 active code arrays、tool/canon table 等边界提前混入 task main loop 迁移。

## 上游依赖清单

上游文件：`linuxcnc/src/emc/nml_intf/emc_nml.hh`。

直接 include 依赖：

- `linuxcnc.h`
- `emcpos.h`
- `emc.hh`
- `libnml/rcs/rcs.hh`
- `libnml/nml/cmd_msg.hh`
- `libnml/nml/stat_msg.hh`
- `rs274ngc/modal_state.hh`
- `canon.hh`
- `rs274ngc/rs274ngc.hh`

这些依赖带来的边界：

- `RCS_CMD_MSG` / `RCS_STAT_MSG` / `CMS` / `NMLTYPE` message runtime。
- `update(CMS *)` serialization hooks。
- `CANON_TOOL_TABLE`、`CANON_UNITS`、RS274 active G/M/settings arrays。
- full motion/task/io/tool/coolant/aux/spindle status object graph。

## 需要的状态子集

当前 T-028 已闭合的最小状态字段：

| 领域 | 当前字段 | LinuxCNC 对应概念 |
| --- | --- | --- |
| top | `top_level_rcs_status` | `EMC_STAT.status` |
| task | `task_rcs_status` | `EMC_STAT.task.status` |
| task | `state`、`mode`、`exec_state`、`interp_state` | `EMC_TASK_STAT.state/mode/execState/interpState` |
| motion | `motion_rcs_status`、`LcmotStatusSnapshot.status` | `EMC_STAT.motion.status` |
| motion.traj | queue、queueFull、in_position、paused、stepping、motion_id | `EMC_TRAJ_STAT` queue/inpos/pause/id 字段族 |
| motion | `on_soft_limit` | `EMC_MOTION_STAT.on_soft_limit` |
| io | `io_rcs_status`、`io_error` | `EMC_STAT.io.status` |

## 选择

采用分阶段 typedef / 窄 status 容器：

1. T-007 已建立 `StandaloneEmcStatus`，集中承载 task/motion/io/top-level 必需字段。
2. 字段命名和 JSON 导出继续对齐 `EMC_STAT`、`EMC_TASK_STAT`、`EMC_MOTION_STAT`、`EMC_TRAJ_STAT`、`EMC_IO_STAT`。
3. `RCS_STATUS` 暂以 `"DONE"`、`"EXEC"`、`"ERROR"` 字符串导出，内部可在 T-030/T-032 后替换为窄 enum。
4. T-032+ 建立 usrmot/NML shim 后，再评估是否 vendor `emc_nml.hh` 及其必要依赖，或只 vendor 一个由上游字段映射驱动的 status subset header。

## 不采用的方案

### 直接 include 完整 `emc_nml.hh`

暂不采用。

阻塞项：

- `emc_nml.hh` 未在 vendor tree 中。
- 直接 include 需要引入 `libnml`、CMS、RS274、canon 依赖链。
- 完整类中大量 `update(CMS *)` 和 message 构造路径超出当前 WASM task runtime 边界。
- 会让 T-028 已闭合的 status 聚合和后续 T-032/T-040 的 runtime edge 纠缠。

### 只扩展现有 `runtime/core/shims/nml_intf/emc.hh`

仅作为短期兼容，不作为 T-029 结论。

现有 shim 只服务解释器单位字段和 source probe：

- `EMC_STAT.motion.traj.linearUnits`
- `EmcJointType`
- `extern EMC_STAT *emcStatus`

继续无限扩展该 shim 会让 interpreter 单位兼容层和 task status 容器混在一起。

## 后续入口

- T-007：已建立集中 `StandaloneEmcStatus`。
- T-030：更新 source reuse map 与 drift 文档，记录本 T-029 决策。
- T-032：设计 `taskintf.cc` usrmot shim，明确 NML/transport 仍是 runtime boundary。
- T-033/T-038：把 motion update 和 task update 映射到 `StandaloneEmcStatus` 字段。

## 验收

T-029 的验收由 `tools/verify_task_emc_nml_reuse_plan.sh` 固定：

- 上游 `emc_nml.hh` 存在。
- 当前 vendor tree 未声称完整 `emc_nml.hh` 已 vendored。
- 本文记录直接 include 依赖、阻塞项和最终选择。
- 任务矩阵将 T-029 标为完成。