Plan full LinuxCNC TP numerical parity
This commit is contained in:
178
doc-rtcp/xyzac-trt-full-tp-parity-plan.md
Normal file
178
doc-rtcp/xyzac-trt-full-tp-parity-plan.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# XYZAC TRT 完整 TP/前瞻数值对标任务轨道
|
||||
|
||||
状态：`TP-PARITY-00` 已建立，完整 LinuxCNC 数值对标尚未完成。
|
||||
|
||||
目标不是证明页面能绘制一条曲线，而是对同一 `xyzac-trt.ini`、同一 G-code、同一初始状态，比较 native LinuxCNC 与 WASM Worker 的每个运动 tick：
|
||||
|
||||
```text
|
||||
source G-code
|
||||
-> LinuxCNC RS-274 canonical output
|
||||
-> LinuxCNC TP/lookahead/blend
|
||||
-> motion/kinematics
|
||||
-> pose/joints/velocity/active motion/queue/current line
|
||||
```
|
||||
|
||||
Web 端只有在该链路和 native trace 逐字段一致后，才能声明 `PARITY_VERIFIED`。Three.js、React 和浏览器时间不能作为运动数据来源。
|
||||
|
||||
## 任务分解
|
||||
|
||||
### TP-PARITY-00：Native LinuxCNC 逐 tick oracle
|
||||
|
||||
来源：
|
||||
|
||||
- `run-5axis-rtcp.sh`
|
||||
- `linuxcnc/src/emc/usr_intf/axis/extensions/emcmodule.cc`
|
||||
- `linuxcnc/src/emc/task/taskintf.cc`
|
||||
- `linuxcnc/src/emc/motion/motion.h`
|
||||
- `linuxcnc/src/emc/tp/tp_debug.h`
|
||||
- `linuxcnc/src/emc/tp/tp.c`
|
||||
- `linuxcnc/src/emc/tp/tcq.c`
|
||||
- `linuxcnc/src/emc/tp/tc.c`
|
||||
|
||||
交付：
|
||||
|
||||
- `scripts/run_xyzac_native_tick_trace.py`
|
||||
- `coverage/xyzac-native-tick-trace.report.json`
|
||||
- native trace JSONL，包含 `tick/taskbeat`、task/interpreter/exec state、current/motion/read line、actual/commanded pose、joint actual pose、velocity、acceleration、queue、active queue、queue full、motion id、feed/rapid override 和 G-code source hash。
|
||||
|
||||
验收：
|
||||
|
||||
- 必须由 `./run-5axis-rtcp.sh` 启动 native LinuxCNC。
|
||||
- 使用 `linuxcnc.stat()` 读取状态，不能从 GUI 截图推断运动值。
|
||||
- trace 必须保留重复 tick、空 queue tick 和程序结束排空阶段。
|
||||
- `motion_id` 映射为 native active motion identifier；若 native API 不提供 segment geometry，必须显式记录 `active_segment_geometry: unavailable`，不能伪造。
|
||||
|
||||
### TP-PARITY-01：锁定 LinuxCNC TP 数据模型和 C ABI
|
||||
|
||||
来源：`linuxcnc/src/emc/tp/{tp.c,tp.h,tp_types.h,tc.c,tcq.c,tc_types.h,blendmath.c,blendmath.h,spherical_arc.c}`。
|
||||
|
||||
工作：
|
||||
|
||||
- 逐项登记 `TP_STRUCT`、`TC_STRUCT`、termination condition、queue depth、active depth、current velocity、acceleration、jerk、tolerance 和 motion id。
|
||||
- 决定采用源码等价移植还是直接编译可移植 LinuxCNC TP 源码到 WASM；优先保留原始 C 算法和数据布局，避免再写第二套近似 planner。
|
||||
- 为每个 ABI 增加 native/WASM size、endianness、state hash 和 checkpoint restore 测试。
|
||||
|
||||
退出条件：native 和 WASM 对同一静态 TC 队列的 enqueue、activate、step、pop 逐字段一致。
|
||||
|
||||
### TP-PARITY-02：G64/G61/G61.1 完整路径控制
|
||||
|
||||
来源：
|
||||
|
||||
- `linuxcnc/src/emc/rs274ngc/interp_convert.cc` 的 G64/G61 处理
|
||||
- `linuxcnc/src/emc/rs274ngc/interp_internal.hh` 的 `tolerance`/`naivecam_tolerance`
|
||||
- `linuxcnc/src/emc/tp/tp.c` 的 `tpSetTermCond` 和 termination condition
|
||||
|
||||
工作：
|
||||
|
||||
- `G61`：exact path；`G61.1`：exact stop；`G64`：blend；`G64 P... Q...`：路径和 naive-cam tolerance。
|
||||
- 保存 modal 状态、每个 canonical motion 的 termination condition 和 tolerance。
|
||||
- 增加直线-直线、直线-圆弧、圆弧-直线、圆弧-圆弧、急转角、短段、零容差和非法 P/Q 样本。
|
||||
|
||||
退出条件：native/WASM 每条 TC 的 termination mode、tolerance、blend point、速度和完成 tick 一致。
|
||||
|
||||
### TP-PARITY-03：Lookahead、corner blending、acceleration/jerk
|
||||
|
||||
来源：
|
||||
|
||||
- `linuxcnc/src/emc/tp/tp.c`：target/final velocity、activate、queue starvation、periodic update
|
||||
- `linuxcnc/src/emc/tp/blendmath.c`：cornering speed、blend geometry、acceleration/jerk bound
|
||||
- `linuxcnc/src/emc/tp/tc.c`：segment acceleration and interpolation
|
||||
- `linuxcnc/src/emc/motion/control.c`：trajectory period and current velocity
|
||||
|
||||
工作：
|
||||
|
||||
- 移除当前 `lookahead=1` 的最小近似，复用或等价移植 LinuxCNC 的完整 active-depth/lookahead。
|
||||
- 按 LinuxCNC 的 blend geometry 计算 corner speed 和 transition segment。
|
||||
- 保持 queue starvation、pause、abort、feed hold、queue drain 的真实语义。
|
||||
- acceleration、jerk、cycle time、velocity limit 从 INI/TRAJ 配置进入同一 planner。
|
||||
|
||||
退出条件：至少覆盖 2、4、8、32 段 lookahead，连续/精确路径，短段和速度突变；逐 tick pose/velocity/acceleration/queue 一致。
|
||||
|
||||
### TP-PARITY-04：XYZAC rotary velocity semantics 和 RTCP
|
||||
|
||||
来源：
|
||||
|
||||
- `linuxcnc/src/emc/task/emccanon.cc`
|
||||
- `linuxcnc/src/emc/kinematics/{xyzac-trt-kins.c,trtfuncs.c,switchkins.c,kins_util.c}`
|
||||
- `linuxcnc/src/emc/motion/control.c`
|
||||
|
||||
工作：
|
||||
|
||||
- 统一线性轴 mm、旋转轴 deg 的速度单位和合成路径长度。
|
||||
- 验证 A/C 单独运动、XYZ+AC 同时运动、G93 inverse time、G94 units/min、RTCP pivot/tool offset。
|
||||
- native trace 同时导出 Cartesian actual/commanded pose 和五 joint actual/commanded pose。
|
||||
- 将 M428/M429/M430 的切换点纳入 planner queue 和 trace，而不是只比较最终姿态。
|
||||
|
||||
退出条件：同一切换点前后 pose 连续、joint 速度/路径长度/active motion id 与 native 一致。
|
||||
|
||||
### TP-PARITY-05：WASM Worker 真实 planner 接入
|
||||
|
||||
工作：
|
||||
|
||||
- `WasmProgramRuntime` 输出 LinuxCNC canonical motion/termination 条件。
|
||||
- Worker 只调用 WASM TP/kinematics/motion ABI；删除 selected-case 中的简化 `sim_motion_queue` 速度决策。
|
||||
- React 继续只消费 snapshot/delta，不参与 tick、前瞻、姿态补偿或路径重建。
|
||||
- Feed/rapid override、pause/resume、abort、restart、checkpoint 都必须落到同一 WASM planner state。
|
||||
|
||||
退出条件：Worker trace 与 WASM C trace byte-identical，且不会回退到 `AuthoritativeRuntime` 或 `ProgramRunner` 的 authority path。
|
||||
|
||||
### TP-PARITY-06：Native/WASM 逐 tick comparator
|
||||
|
||||
交付：
|
||||
|
||||
- `scripts/compare_xyzac_native_wasm_tick_trace.py`
|
||||
- `coverage/xyzac-native-wasm-tick-parity.report.json`
|
||||
|
||||
比较字段：
|
||||
|
||||
```text
|
||||
tick
|
||||
task_state/mode/interp_state/exec_state
|
||||
current_line/motion_line/read_line
|
||||
actual_pose/commanded_pose
|
||||
joint_actual/joint_commanded
|
||||
velocity/acceleration
|
||||
queue/active_queue/queue_full
|
||||
motion_id/active_segment
|
||||
feed_override/rapid_override
|
||||
kinematics_mode/RTCP offsets
|
||||
state_hash
|
||||
```
|
||||
|
||||
比较规则：
|
||||
|
||||
- 浮点使用固定绝对/相对容差，并记录原始值和差异值。
|
||||
- 列表长度、字段缺失、状态顺序不允许静默忽略。
|
||||
- 保存 `first_divergent_tick`、`difference_path`、native/WASM 两侧样本。
|
||||
- 最终坐标相同但中间 tick 不同必须判定为 `diverged`。
|
||||
|
||||
### TP-PARITY-07：预览和实际执行一致性
|
||||
|
||||
工作：
|
||||
|
||||
- 预览使用同一 canonical/TP 输入生成 planned path，不使用独立的几何近似。
|
||||
- 实时路径使用同一 planner 的 actual motion trace。
|
||||
- 对比 planned TC、executed TC、active segment 和完成后的 endpoint；明确 rapid、blend、exact-stop 的颜色/线型只属于显示层。
|
||||
|
||||
退出条件：预览不改变 planner state；执行 trace 的 segment/source line 可回指预览 TC；同一程序重复运行 preview hash 稳定。
|
||||
|
||||
### TP-PARITY-08：最终门禁
|
||||
|
||||
必须通过：
|
||||
|
||||
- native `run-5axis-rtcp.sh` trace
|
||||
- native CTest 和 WASM CTest
|
||||
- Worker trace
|
||||
- native/WASM 逐 tick comparator
|
||||
- XYZAC M428/M429/M430、G64/G61/G61.1、G93/G94、短段、拐角、queue full、pause/abort/restart/recovery
|
||||
- Chromium 浏览器只读显示验证
|
||||
|
||||
只有 `first_divergent_tick: null`、所有字段状态 hash 通过、所有输入和报告自哈希一致，才允许将状态写为 `PARITY_VERIFIED`。否则保持 `TP-PARITY-*` 对应任务的 `blocked` 或 `diverged`。
|
||||
|
||||
## 当前明确边界
|
||||
|
||||
- 当前 `coverage/xyzac-trt-trace-parity.report.json` 证明的是项目内 native C/WASM C/Worker 实现之间的 selected-case 一致，不是 native LinuxCNC TP oracle 对标。
|
||||
- 当前 `wasm-program-runtime.mjs` 的 preview 是 WASM interpreter canonical segments；完整 LinuxCNC TP 前瞻和 G64 corner blend 尚未接入。
|
||||
- 当前 `sim_motion_queue.c` 的 lookahead/blend 是简化实现，不能作为真实 LinuxCNC TP 数值等价证明。
|
||||
- `run-5axis-rtcp.sh` 当前只启动 native AXIS；TP-PARITY-00 必须补齐 `linuxcnc.stat()` trace 导出后，才有资格进行逐 tick comparator。
|
||||
- Safari、物理断电和真实硬件仍按项目范围排除，不影响本仿真任务的 native/WASM 数值闭环。
|
||||
Reference in New Issue
Block a user