text40.txt

一、接续说明

执行时间：2026-06-21 CST

本文件接续 `textbak/text39.txt`。`text39.txt` 的结论停留在：

```text
LinuxCNC TRT kinematics WASM ABI 已完成第一批；
LinuxCNC 全量 kinematics WASM ABI 仍未完成。
```

在其后续工作中，kinematics WASM ABI 已继续推进并完成全量可加载
LinuxCNC kinematics module 覆盖。因此本文件用于纠正旧结论，记录当前
最终状态和仍然不应误判为缺口的边界。

二、准确结论

当前结论：

```text
LinuxCNC 可加载 kinematics module 的独立 WASM ABI 已完成。
LinuxCNC 已 vendored 的所有实际 kinematics forward/inverse 算法均已通过独立 ABI 导出并验证。
JavaScript/SDK 没有实现 kinematics 数学，只负责加载 WASM、分配内存、传 seed buffer、调用 C ABI。
```

需要特别说明：

```text
1. `ugenserkins.c` 不是 loadable kinematics module，而是 upstream 自标注 declining usage 的 userspace test program；其调用的 genserKinematicsForward/Inverse 已由 `genser` WASM module 覆盖。
2. `lineardeltakins.cc` 和 `rotarydeltakins.cc` 是 Boost.Python wrapper，调用同一 common header 中的 kinematics_forward/kinematics_inverse；实际 LinuxCNC module 算法已由 `lineardelta` / `rotarydelta` WASM module 覆盖。
3. `cubic.c` 是 kinematics support/interpolation utility，不是独立 kinematicsForward/kinematicsInverse module。
4. `userkfuncs.c` 是 switchkins 的 user/identity fallback function set，不是单独 loadrt module；它已随 switchkins modules 编译进对应 WASM module。
```

三、已导出的独立 kinematics WASM modules

当前 SDK 支持并验证的 moduleId：

```text
trivkins
5axiskins
xyzac-trt
xyzbc-trt
corexy
rotate
rose
max
lineardelta
rotarydelta
scorbot
tripod
scara
puma
genser
genhex
pentakins
```

当前生成的 WASM 产物共 17 个：

```text
wasm-port/build/wasm/kinematics/linuxcnc_trivkins_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_5axiskins_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_xyzac_trt_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_xyzbc_trt_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_corexy_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_rotate_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_rose_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_max_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_lineardelta_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_rotarydelta_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_scorbot_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_tripod_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_scara_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_puma_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_genser_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_genhex_kinematics.wasm
wasm-port/build/wasm/kinematics/linuxcnc_pentakins_kinematics.wasm
```

四、ABI 入口

统一 C ABI wrapper：

```text
wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_kinematics_wasm.c
```

导出函数：

```text
lckins_init
lckins_exit
lckins_type
lckins_switchable
lckins_switch
lckins_forward
lckins_inverse
lckins_run_probe
lckins_free_string
```

关键 ABI 语义：

```text
1. `lckins_forward()` 使用 `pose_out` 作为 in/out pose buffer。
   这保留了 LinuxCNC genhex/pentakins 等迭代 forward kinematics 对初始 pose estimate 的要求。

2. `lckins_inverse()` 使用 `joints_out` 作为 in/out joint buffer。
   这保留了 LinuxCNC genser 等迭代 inverse kinematics 对初始 joint estimate 的要求。

3. `fflags` / `iflags` 通过指针传入传出，保留 tripod/switchkins 等 flag 语义边界。
```

五、SDK 接入

SDK wrapper：

```text
wasm-port/runtime/sdk/src/linuxcnc-kinematics.js
```

统一导出：

```text
wasm-port/runtime/sdk/src/index.js
```

SDK API：

```text
createLinuxCncKinematicsSdk()
supportedLinuxCncKinematicsModules()
linuxCncKinematicsWasmFile(moduleId)
```

运行时方法：

```text
type()
switchable()
switchKinematics(switchkinsType)
forward(joints, { seedPose })
inverse(pose, jointCount, { seedJoints })
runProbe()
```

六、构建脚本

独立构建入口：

```text
wasm-port/tools/build_kinematics_wasm.sh
```

构建策略：

```text
1. 每个 kinematics family 单独生成一个 Emscripten module，避免 LinuxCNC kinematicsForward/kinematicsInverse 同名符号冲突。
2. source 复用 vendored LinuxCNC `src/emc/kinematics`。
3. posemath-heavy modules 额外链接 vendored `src/libnml/posemath`。
4. genser 直接以 C 编译 vendored `gomath.c`，避免 C++ wrapper name mangling 造成 go_* 链接失败。
5. switchkins modules 复用 `kins_util.c`、`switchkins.c`、`userkfuncs.c`。
```

七、验证

Node/WASM 验证入口：

```text
wasm-port/tests/wasm/node/verify_kinematics_wasm.sh
wasm-port/tests/wasm/node/verify_kinematics_wasm.mjs
```

已通过命令：

```bash
source /home/cnc/emsdk/emsdk_env.sh >/dev/null && bash wasm-port/tools/build_kinematics_wasm.sh && bash wasm-port/tests/wasm/node/verify_kinematics_wasm.sh
```

通过输出：

```text
kinematics_wasm_node_smoke=ok
```

验证覆盖：

```text
1. 17 个 moduleId 列表与预期完全一致；
2. 每个 WASM module 可通过 SDK 加载；
3. 每个 module 导出 lckins_forward / lckins_inverse / lckins_run_probe；
4. kinematicsType / kinematicsSwitchable 与 LinuxCNC module 预期一致；
5. trivkins / corexy / rotate / rose / max 等直接 joint roundtrip；
6. lineardelta / rotarydelta / tripod / pentakins 等 pose -> inverse -> forward roundtrip；
7. scorbot / puma 使用 LinuxCNC native probe pattern 做 pose roundtrip；
8. scara / 5axiskins / xyzac-trt / xyzbc-trt / genser 覆盖 switchkins primary 和 identity path；
9. genhex 覆盖 inverse + iterative-forward warmup path，并验证 alternate switch path 可切换；
10. genser seedJoints、genhex/pentakins seedPose 语义被显式验证。
```

八、当前文件状态提醒

当前相关文件中有一部分仍是未跟踪文件，需要后续提交时纳入：

```text
wasm-port/runtime/core/linuxcnc_wrap/linuxcnc_kinematics_wasm.c
wasm-port/runtime/sdk/src/linuxcnc-kinematics.js
wasm-port/tests/wasm/node/verify_kinematics_wasm.mjs
wasm-port/tools/build_kinematics_wasm.sh
```

相关已修改文件：

```text
wasm-port/runtime/core/shims/hal.h
wasm-port/runtime/sdk/src/index.js
wasm-port/runtime/sdk/README.md
wasm-port/docs/porting-steps-standalone.md
wasm-port/docs/compatibility-validation.md
```

九、后续建议

就“LinuxCNC 的所有逆解相关算法，导出独立 kinematics ABI”这一项而言：

```text
无需继续扩展 kinematics module 列表。
下一步不应再手写或补造 JS kinematics 数学。
后续重点应转向把 Web/M4/M5 simulation UI 从 fixture/frame 逻辑接入 createLinuxCncKinematicsSdk() 输出，或继续推进 remap/planner/browser 集成验证。
```