131 lines
8.8 KiB
Markdown
131 lines
8.8 KiB
Markdown
# 11-LinuxCNC 源码与真实执行严格对标任务
|
||
|
||
## 目标
|
||
|
||
本轮新增任务把 native 对标基线明确升级为：
|
||
|
||
```text
|
||
/home/mes123456/cnc_wams/linuxcnc
|
||
```
|
||
|
||
该目录中的 LinuxCNC 源码、配置、构建产物和真实运行态是 `xyzbc-trt` Web 仿真的唯一 native 权威源。后续不能只用整理过的 Markdown、历史 evidence 或手写等价模型作为验收依据；任何 Web 行为、JSON 字段、截图和 compare 结论都必须能反查到 LinuxCNC 源树文件、真实运行采样或二者组合。
|
||
|
||
## 权威源范围
|
||
|
||
### 启动与运行入口
|
||
|
||
| 类别 | 权威路径 | 必须采集的事实 |
|
||
| --- | --- | --- |
|
||
| RIP 环境 | `/home/mes123456/cnc_wams/linuxcnc/scripts/rip-environment` | 环境变量、Python 模块路径、bin/rtlib 路径、启动前置 |
|
||
| AXIS 启动 | `/home/mes123456/cnc_wams/linuxcnc/bin/axis` | 实际 GUI 入口、加载的 INI、进程树 |
|
||
| Vismach 启动 | `/home/mes123456/cnc_wams/linuxcnc/bin/xyzbc-trt-gui` | wrapper 与 Python 模型入口 |
|
||
| 桌面入口 | `/home/mes123456/cnc_wams/linuxcnc/linuxcnc-rtcp-5axis-shortcuts/table-rotary-tilting/xyzbc-trt.desktop` | Exec、WorkingDirectory、加载配置 |
|
||
| 原生模块 | `/home/mes123456/cnc_wams/linuxcnc/rtlib/xyzbc-trt-kins.so` | 构建产物存在性、sha256、符号/版本绑定 |
|
||
|
||
### 配置与运行文件
|
||
|
||
| 类别 | 权威路径 | 必须对标的内容 |
|
||
| --- | --- | --- |
|
||
| 主 INI | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.ini` | DISPLAY、RS274NGC、KINS、HAL、HALUI、TRAJ、EMCMOT、TASK、EMCIO、AXIS、JOINT 全字段 |
|
||
| PyVCP | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.xml` | SWITCHKINS multilabel、type0/type1/type2、vismach-clear |
|
||
| POSTGUI HAL | `configs/sim/axis/vismach/5axis/table-rotary-tilting/switchkins_postgui.hal` | PyVCP pin 到 halui MDI 与 vismach.plotclear 的 net |
|
||
| basic_sim 生成 HAL | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt_cmds.hal` | loadrt/loadusr/net/setp/addf/thread、manual toolchange、sim spindle、PID/mux/home switch |
|
||
| tool table | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc-trt.tbl` | 工具号、长度、直径、tool-offset 闭环 |
|
||
| parameter file | `configs/sim/axis/vismach/5axis/table-rotary-tilting/xyzbc.var` | G54/G10/持久化参数和运行前后变化 |
|
||
| 示例程序 | `configs/sim/axis/vismach/5axis/table-rotary-tilting/demos/*.ngc` | 默认程序、boat 程序、真实加载/执行 |
|
||
| remap/Ngcgui 子程序 | `configs/sim/axis/vismach/5axis/table-rotary-tilting/remap_subs/*.ngc` | M428/M429/M430、xyzbc_switchkins_sub、centering、helix_bc |
|
||
|
||
### 源码级行为
|
||
|
||
| 类别 | 权威路径 | 必须对标的内容 |
|
||
| --- | --- | --- |
|
||
| switchkins wrapper | `src/emc/kinematics/xyzbc-trt-kins.c` | `identityfirst`、switchkins-type 0/1/2、required_coordinates、HAL prefix |
|
||
| TRT 运动学公式 | `src/emc/kinematics/trtfuncs.c` | XYZBC forward/inverse、offset、tool-offset、rot-point、conventional-directions、坐标映射 |
|
||
| Vismach 模型 | `src/hal/user_comps/vismach/xyzbc-trt-gui.py` | HAL pins、几何层级、颜色、方向、Capture 点、视角 |
|
||
| AXIS UI | LinuxCNC AXIS Python 源码 | 菜单、工具栏、模式、按钮联锁、MDI、jog、override、touch-off、状态消息 |
|
||
| interpreter/task/HAL | LinuxCNC 对应 C/C++/Python 源码和运行 API | 实际执行事件、状态转移、错误路径、采样时序 |
|
||
|
||
## 新增任务组
|
||
|
||
### A. 源树权威清单
|
||
|
||
1. 生成 `xyzbc-trt-source-manifest.json`：记录所有权威文件的绝对路径、sha256、mtime、文件大小、角色和被哪个 Web/evidence 字段使用。
|
||
2. Web staging 必须逐文件引用 manifest；缺失、hash 不同、来源不明都要进入 blocker。
|
||
3. 文档和 evidence 中的每个“已对标”结论必须能反查到 manifest 文件。
|
||
|
||
### B. 原生真实启动采集
|
||
|
||
1. 用 `rip-environment` 启动 `xyzbc-trt.ini`。
|
||
2. 记录实际命令、环境变量、当前工作目录、进程树、加载的 rtlib、HAL 组件、GUI 组件和 PyVCP/POSTGUI 加载顺序。
|
||
3. 采集失败时输出结构化 blocked JSON，不允许只留下 traceback。
|
||
|
||
### C. INI/HAL 全量解析
|
||
|
||
1. INI 解析必须覆盖所有 section/key，不允许只提取 profile 用到的字段。
|
||
2. HAL 解析必须合并 INI `HALCMD`、`LIB:basic_sim.tcl` 运行生成结果、`switchkins_postgui.hal` 和真实 halcmd show 输出。
|
||
3. compare 必须输出字段缺失、值不一致、未连接 pin、未采集 thread/function 的明细。
|
||
|
||
### D. 运动学公式级验证
|
||
|
||
1. 从 `xyzbc-trt-kins.c` 和 `trtfuncs.c` 生成公式对标说明。
|
||
2. 用 native 运行态 HAL pin 组合和多组随机/边界姿态验证 forward/inverse。
|
||
3. Web 与 native 对比必须记录 TCP、joint、toolAxis、offset 误差和首个差异点。
|
||
4. `conventional-directions`、`x/y/z-rot-point`、`x/y/z-offset`、`tool-offset` 都必须进入测试矩阵。
|
||
|
||
### E. remap 与 switchkins 真实语义
|
||
|
||
1. M428/M429/M430 必须按源码逐行对标：`M68 E3 Q*`、`M66` 同步、`motion.switchkins-type` 检查、debug/STOP 失败路径。
|
||
2. PyVCP type0/type1/type2 到 HALUI MDI 命令的真实路径必须采集。
|
||
3. 运行中切换、未满足 HAL pin、错误 task 模式等失败路径必须有 native/Web 成对证据。
|
||
|
||
### F. AXIS/PyVCP/Vismach UI 完整对标
|
||
|
||
1. AXIS 菜单、工具栏、状态栏、DRO、预览、程序、MDI、jog、override、spindle/coolant、touch-off 的按钮/输入/禁用态必须有来源行和真实点击结果。
|
||
2. PyVCP 的 multilabel、按钮、HAL pin、POSTGUI net 必须完整映射到 Web DOM、状态和 evidence。
|
||
3. Vismach 变换树必须按 `xyzbc-trt-gui.py` 逐层对齐，Web 需要输出 transform/pin/capture 点证据。
|
||
|
||
### G. 真实执行采样
|
||
|
||
1. native evidence 必须明确区分：
|
||
- `sourceDerived`：源文件静态解析。
|
||
- `runtimeObserved`：LinuxCNC 运行态事件/API/HAL/日志观察。
|
||
- `runtimeSampled`：按时间采样的 joint/TCP/tool/state。
|
||
2. `SERVO_PERIOD=1000000` 和 `TASK CYCLE_TIME=0.010` 必须进入 evidence；50ms 对比样本必须说明从何种原始时间基准抽取。
|
||
3. 真实执行过程必须包含当前文件/行、调用栈、参数赋值、G/M 代码、work offset、switchkins、motion segment、feed/spindle/coolant/tool 状态。
|
||
|
||
### H. Web 复现与 compare 升级
|
||
|
||
1. Web evidence 必须证明 staged 文件 hash 与 LinuxCNC manifest 一致。
|
||
2. WASM artifact 必须绑定 LinuxCNC 源码路径、构建命令、编译选项、sha256 和导出符号。
|
||
3. compare JSON 新增以下顶层结果：
|
||
- `sourceManifestComparison`
|
||
- `runtimeLaunchComparison`
|
||
- `iniFullComparison`
|
||
- `halGraphComparison`
|
||
- `kinematicsFormulaComparison`
|
||
- `uiBehaviorComparison`
|
||
- `visualComparison`
|
||
4. 任何无法从源码或真实运行证明的 Web 行为，都必须标为 fail 或 blocker。
|
||
|
||
### I. 截图与视觉证据
|
||
|
||
1. 同一运行时间点采集 native AXIS/Vismach 截图与 Web DOM/canvas 截图。
|
||
2. 截图 manifest 必须包含 sampleIndex、timeMs、当前源行、joint、TCP、toolAxis、kinstype、feed、spindle、tool、coolant。
|
||
3. 视觉差异必须有文字说明和结构化字段，不能只保存图片。
|
||
|
||
### J. 回归门禁
|
||
|
||
1. 提供一键复验命令：启动 native、采集 source/runtime evidence、采集 Web evidence、执行 compare、生成截图和摘要。
|
||
2. T-051 到 T-075 全部通过前，`working` 不得再声明“严格完整对标已完成”；2026-07-04 复验后，最新 `compare-xyzbc-trt-evidence.json` 为 `60/60 pass`，`blockers=[]`。
|
||
3. 全部通过后冻结 manifest、evidence、截图和 compare 摘要；后续任何代码或源文件变更必须重新复验。
|
||
|
||
## 当前状态
|
||
|
||
本文件最初为新增任务整理结果。2026-07-04 后续实现轮次已完成 T-051 到 T-075，并更新 `04-任务矩阵.md`、native/Web/compare evidence。当前最新状态：
|
||
|
||
- `native-xyzbc-trt-evidence.json` 新增 `sourceManifest`、`runtimeLaunch`、`iniFull`、`halGraph`、`kinematicsFormula`、`remapSemantics`、`runtimeExecutionObserved`、`runtimeEvidenceClassification`、`reverseSourceIndex`、`performanceBudget`、`strictAcceptance` 等源码/运行双基线字段。
|
||
- `web-xyzbc-trt-evidence.json` 新增 Web staging sha256、完整 INI、HAL/task 模型、WASM artifact sha256/source binding、UI/Vismach/错误路径/性能预算等同名字段。
|
||
- `compare-xyzbc-trt-evidence.json` 新增 `sourceManifestComparison`、`runtimeLaunchComparison`、`halGraphComparison`、`iniFullComparison`、`kinematicsFormulaComparison`、`uiBehaviorComparison`、`visualComparison` 和 `strictComparison`，当前 `checkCount=60`、`passCount=60`、`failCount=0`、`blockers=[]`。
|
||
|
||
因此，现有 T-001 到 T-075 均为完成状态；后续任何涉及源码、staging、WASM artifact、UI 行为或采样逻辑的修改，都必须重新生成 native/Web/compare evidence 并保持 60/60 pass 或更新验收门槛。
|