# 10-taskintf usrmot shim 设计

## 目标

T-032 定义 `taskintf.cc` 在 WASM 中继续保留的 usrmot 语义边界，以及这些边界如何落到 standalone `lcmot_*` runtime。目标是给 T-033 之后的实现提供窄 shim 合同，而不是在本阶段直接编译完整 `linuxcnc/src/emc/motion/usrmotintf.cc`。

上游锚点：

- `linuxcnc/src/emc/motion/usrmotintf.h`
- `linuxcnc/src/emc/motion/usrmotintf.cc`
- `linuxcnc/src/emc/task/taskintf.cc`

WASM runtime 锚点：

- `runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.h`
- `runtime/core/linuxcnc_wrap/linuxcnc_motion_runtime.c`
- `runtime/core/linuxcnc_task_subset/taskintf_wasm_subset.hh`
- `runtime/core/linuxcnc_task_subset/taskintf_wasm_subset.cc`

## 不直接复用完整 `usrmotintf.cc`

完整上游 `usrmotintf.cc` 绑定 native shared memory、mutex、command ack 轮询、split read、error ring buffer、RTAPI init/exit 和 compensation file loading。WASM 当前 motion runtime 是同进程 standalone C ABI，不存在上游共享内存段，也没有 native emcmot process ack 通道。

因此 T-032 采用一个窄 usrmot shim：

```text
taskintf.cc-compatible calls
  -> wasm usrmot shim
  -> lcmot_* C ABI
  -> standalone motion runtime
```

shim 必须保留上游函数的返回值语义，但只能承诺当前 `lcmot_*` 已有或明确新增的能力。

## 映射总表

| usrmot 边界 | 上游行为 | WASM shim 映射 | 当前状态 |
| --- | --- | --- | --- |
| `usrmotIniLoad(file)` | 读取 INI 中的 motion shared memory key、timeout 等 | 只保存 `ini_path`，等待 `usrmotInit()` 调用 `lcmot_init_from_ini(ini_path, ini_text)` | 需要 shim 缓存 staged INI text |
| `usrmotInit(name)` | 连接 native emcmot shared memory | 初始化 standalone motion runtime；映射到 `lcmot_init_from_ini()` | 已有底层 ABI |
| `usrmotExit()` | 断开 native emcmot shared memory/RTAPI | 映射到 `lcmot_reset()`；不退出 WASM runtime | 已有底层 ABI |
| `usrmotWriteEmcmotCommand(c)` | 写 `emcmot_command_t`，等待 `commandNumEcho` ack | 将 taskintf 命令转换为 `lcmot_write_command_json()` 可接受的 command JSON | 已有底层 ABI，ack 语义需降级 |
| `usrmotReadEmcmotStatus(s)` | split-read 复制 `emcmot_status_t` | 映射 `lcmot_read_status_snapshot()` 到窄 `emcmot_status_t`/`EMC_MOTION_STAT` subset | 已有底层 ABI |
| `usrmotReadEmcmotConfig(s)` | split-read 复制 `emcmot_config_t` | 新增 `lcmot_read_config_snapshot()`，输出 axes/joints/queue/config_num/limits/default units 等窄 config subset | T-033 已实现窄底层 ABI |
| `usrmotReadEmcmotInternal(s)` | 读取 debug/internal shared memory | 第一阶段返回空 internal subset；后续可新增 `lcmot_read_internal_snapshot()` | 非 T-032 必需 |
| `usrmotReadEmcmotError(e)` | 从 motion error ring 取最早错误 | 新增 `lcmot_read_error_message(char *out, int out_len)` 或等价 JSON/error buffer API | T-033 已实现窄 error message queue |
| `usrmotLoadComp()` / `usrmotPrintComp()` | joint compensation 文件 IO | 暂不支持；返回 `EMCMOT_COMM_ERROR_COMMAND` 或独立 unsupported code | 后续 joint compensation 批次处理 |

## command write

上游 `usrmotWriteEmcmotCommand(emcmot_command_t *c)` 做三件事：

1. 校验 motion id。
2. 写入 shared memory command slot。
3. 轮询 `usrmotReadEmcmotStatus()`，等待 `commandNumEcho` 和 `commandStatus`。

WASM shim 的 T-033 最小实现合同：

```text
usrmotWriteEmcmotCommand(c)
  -> validate supported command and motion id
  -> convert emcmot_command_t to taskintf/lcmot command JSON
  -> lcmot_write_command_json(json)
  -> return EMCMOT_COMM_OK on accepted enqueue
```

返回值映射：

| 条件 | 返回值 |
| --- | --- |
| command 转换成功且 `lcmot_write_command_json()` 返回 0 | `EMCMOT_COMM_OK` |
| command unsupported、queue full、字段非法 | `EMCMOT_COMM_ERROR_COMMAND` |
| runtime 未初始化 | `EMCMOT_COMM_ERROR_CONNECT` |
| motion id 为 invalid sentinel | `EMCMOT_COMM_INVALID_MOTION_ID` |
| in-process WASM runtime 无 ack 通道 | 不使用 `EMCMOT_COMM_ERROR_TIMEOUT`，除非后续引入 command ack |

现有 `taskintf_wasm_subset` 已覆盖的 command family：

- `emcTrajAbort()` / `EMCMOT_ABORT`
- `emcTrajPause()` / `EMCMOT_PAUSE`
- `emcTrajStep()` / `EMCMOT_STEP`
- `emcTrajResume()` / `EMCMOT_RESUME`
- `emcTrajLinearMove()` / `EMCMOT_SET_LINE`
- `emcJogIncr()` / `EMCMOT_JOG_INCR`
- `emcJointHome()` / homing command envelope
- `emcMotionSetAout()` / `EMCMOT_SET_AOUT`

后续 T-034 到 T-036 可以把这些 command family 从 JSON 拼接继续收缩到 `emcmot_command_t -> shim -> lcmot` 的窄转换层。

## status read

上游 `usrmotReadEmcmotStatus(emcmot_status_t *s)` 是 split-read，只复制 shared memory，不推进 servo。WASM 语义必须保持这一点：

```text
usrmotReadEmcmotStatus(s)
  -> lcmot_read_status_snapshot(&snapshot)
  -> map snapshot to status subset
  -> return EMCMOT_COMM_OK
```

硬性约束：

- 不调用 `lcmot_step_servo()`。
- 不消费 motion command queue。
- 不调用 `lctask_run_cycles()`。
- 不从 JSON status 反向解析。
- `status`、`in_position`、`queue_full`、`queue_count`、`motion_id`、`program_line`、`axis_cmd/fb`、`joint_cmd/fb`、`motion_error`、`on_soft_limit` 必须来自 `LcmotStatusSnapshot`。

`LcmotStatusSnapshot.status` 到 RCS 子状态的第一阶段映射：

| `LcmotStatusSnapshot.status` | 语义 |
| --- | --- |
| `0` | motion DONE |
| `1` | motion EXEC |
| `2` | motion ERROR |

## config read

上游 `usrmotReadEmcmotConfig(emcmot_config_t *s)` 读取 config shared memory，并依赖 `head == tail` 的 split-read 稳定性。当前 `lcmot_*` 只有 `lcmot_init_from_ini()`，没有 config snapshot read API。

T-032 设计结论：

```text
usrmotReadEmcmotConfig(s)
  -> lcmot_read_config_snapshot(&config)
  -> map config to emcmot_config_t subset
```

T-033 已新增窄实现：

```c
typedef struct {
    int config_num;
    int axes;
    int joints;
    int queue_capacity;
    double linear_units;
    double angular_units;
    double axis_min_limit[LCMOT_MAX_AXES];
    double axis_max_limit[LCMOT_MAX_AXES];
} LcmotConfigSnapshot;

int lcmot_read_config_snapshot(LcmotConfigSnapshot *snapshot);
```

如果后续替换或重命名该 API，shim 不能假装 `usrmotReadEmcmotConfig()` 已支持。允许的临时行为只有：

- task 初始化阶段使用 `lcmot_init_from_ini()` 建立 runtime defaults。
- `emcMotionUpdate()` 遇到 config read 需求时返回错误，保持 readiness false。
- 文档和验证脚本继续记录 config read 是窄 runtime-edge ABI，不是 native shared-memory config promotion。

## error read

上游 `usrmotReadEmcmotError(char *e)` 从 motion error ring 取最早错误字符串。当前 `LcmotStatusSnapshot` 只有 `motion_error` 和 `on_soft_limit` 标志，不能替代错误队列。

T-032 设计结论：

```text
usrmotReadEmcmotError(e)
  -> lcmot_read_error_message(e, EMCMOT_ERROR_LEN)
```

T-033 已新增窄实现：

```c
int lcmot_read_error_message(char *out, int out_len);
```

行为合同：

- 有错误消息时返回 0，并复制最早错误。
- 无错误消息时返回 -1，匹配上游 “no error” 分支。
- `EMCMOT_INJECT_ERROR`、soft-limit、abort cleanup 写入该 error buffer。
- status flag 仍来自 `lcmot_read_status_snapshot()`，错误文本只通过 error read 消费。

## T-033 实施入口

1. T-033 已在 `taskintf_wasm_subset` 中新增 `lc_taskintf_subset_motion_init()`、`lc_taskintf_subset_motion_update()`、`lc_taskintf_subset_motion_abort()`。
2. T-033 已新增 `lcmot_read_config_snapshot()` 与 `lcmot_read_error_message()`。
3. T-033 已让 `lctask_init_session()`、task-cycle motion update 和 task abort path 通过 shim 访问 motion runtime。
4. 继续保持 task status read 和 motion status read 的周期隔离：外部 `lctask_read_status_json()` 不触发新的 motion update。
5. T-034+ 可继续把 traj control command family 从 envelope 迁到更完整的 usrmot command conversion。

## 禁止路线

- 不把完整 `usrmotintf.cc` 直接加入 WASM build。
- 不用 `lcmot_read_status_json()` 反解析生成 `emcmot_status_t`。
- 不让 status read 推进 servo 或 task cycle。
- 不把 config read 映射成 HAL snapshot。
- 不把 `motion_error` boolean 当成 `usrmotReadEmcmotError()` 的错误队列。
- 不把 T-032/T-033 的 usrmot shim 解释为 `nativeTaskReady=true` 或 `nativeHalSyncReady=true`。