205 lines
9.7 KiB
Markdown
205 lines
9.7 KiB
Markdown
# XYZAC TRT 完整 TP/前瞻数值对标任务轨道
|
||
|
||
状态：`TP-PARITY-00` native oracle 已 verified；WASM 已接入上游 LinuxCNC TP/TC 源码并完成同一 28 段运行，但完整数值对标仍为 `STOP_RELEASE`。
|
||
|
||
当前 oracle 证据：`coverage/xyzac-native-tick-trace.report.json` 已由源
|
||
`run-5axis-rtcp.sh` 产生连续 task-heartbeat tick；源 Python NML 扩展暴露
|
||
`task_heartbeat`，并记录 XYZAC pose/joints、queue、current-line、速度和加速度。
|
||
干净 checkout 使用 `scripts/build_linuxcnc_native_oracle.sh` 应用并编译同一源 patch。
|
||
`scripts/compare_xyzac_native_wasm_tick_trace.py` 已接入同一 case 的 WASM trace，
|
||
当前完整窗口首个差异为 `$.segments[17][4003].motion_line`；共同 TP 前缀的
|
||
position、velocity、acceleration、queue、joint command/feedback 已逐 tick 对齐，
|
||
但后续 segment duration 尚未闭合，因此不得把 TP-PARITY-01..08 写成数值 parity verified。
|
||
|
||
目标不是证明页面能绘制一条曲线，而是对同一 `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
|
||
|
||
状态：`in_progress`。生产 Worker 的 `planner:"linuxcnc-tp"` 直接调用上游 TP/TC
|
||
源码切片；native/WASM 完整窗口仍报告 task 元数据和后续 segment duration 差异。
|
||
|
||
来源：`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 完整路径控制
|
||
|
||
状态：`in_progress`，WASM interpreter 侧已闭合指令模式和容差状态，numeric
|
||
blend 仍待 TP port 和 comparator 通过。
|
||
|
||
来源：
|
||
|
||
- `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 样本。
|
||
|
||
当前 WASM C interpreter 已输出三种模式及 P/Q 容差到 `sim_program.v1`，Worker
|
||
在入队前应用对应 queue profile；LinuxCNC exact-path 与 exact-stop 的细微
|
||
差别、P/Q 驱动的 corner blend 仍由 TP-PARITY-03/06 的 native tick comparator
|
||
验证，尚未标记完成。
|
||
|
||
退出条件：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 两侧样本。
|
||
|
||
已提供可重复入口：
|
||
|
||
- `scripts/run_xyzac_wasm_tick_trace.mjs`
|
||
- `scripts/compare_xyzac_native_wasm_tick_trace.py`
|
||
- `coverage/xyzac-native-wasm-tick-parity.report.json`
|
||
- 最终坐标相同但中间 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 数值闭环。
|