linuxcncAllWasm/docs/linuxcnc-web-wasm-source-map.md

# LinuxCNC Web/WASM 仿真功能与源程序关联目录

**文档状态**：Draft v0.1
**适用基线**：LinuxCNC `2.10.0~pre0`；源码根目录为 `linuxcnc/`
**上层路线**：[技术路线](linuxcnc-web-wasm-technical-roadmap.md)
**覆盖验收**：[仿真全功能覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)
**执行治理**：[项目执行与交付策略](linuxcnc-web-wasm-execution-strategy.md)
**前端与通信**：[前端与 LinuxCNC 通信详细设计](linuxcnc-web-wasm-frontend-communication-design.md)
**总控执行**：[移植总控执行手册](linuxcnc-web-wasm-integration-playbook.md)

本目录把“功能”与 LinuxCNC 的实际源程序、配置、样例和测试绑定。表中的路径是当前仓库中的真实路径；`*`、`**` 通配范围必须由 manifest 生成器展开为逐文件条目，不能把通配符本身当成完成证据。源码文件发生增删、重命名或符号变化时，来源扫描必须更新 manifest 并阻断未关联的提交。

## 1. 关联契约

每个功能条目至少包含以下关联字段：

| 字段 | 要求 |
|---|---|
| `feature_id` | 稳定的功能 ID，不随文件重命名改变 |
| `domain`、`capability` | 功能域和用户可观察能力 |
| `source_files` | 仓库相对路径，展开到具体文件并记录 `source_sha` |
| `source_symbols` | 从 C/C++/C/Python/组件文件生成的符号或入口；无法解析时标记 `blocked` |
| `config_inputs` | `configs/sim/**` 中实际启用该功能的 INI/HAL/NGC/PY/XML/TCL/CLP 文件 |
| `adaptation` | `SIM-CORE`、`SIM-ADAPTER`、`SIM-DEVICE`、`WEB-EQUIV`、`PY-WASM` 或 `REAL-EXCLUDED` |
| `test_sources`、`test_id` | 原生测试、单测、浏览器测试和故障/恢复测试 |
| `oracle` | 原生 golden、规范输出、状态机不变量或明确 Web 等价判定 |
| `status`、`difference` | 实施状态、首个差异位置、容差和差异说明 |
| `protocol_messages`、`state_fields` | 前端命令、事件、快照字段和 LinuxCNC 状态的映射；详细契约见前端与通信设计 |

源文件关联只说明“必须审查和适配的来源”，不表示该文件可直接编译进 WASM。每个条目仍须按[覆盖矩阵](linuxcnc-web-wasm-simulation-coverage.md)的正常、边界、错误、暂停/恢复、持久化/离线和交互维度验收。

## 2. 核心行为源程序映射

| 功能域 | LinuxCNC 源程序/文件范围 | Web/WASM 处理 | 首批测试来源 |
|---|---|---|---|
| INI、配置和 HAL 初始化 | `linuxcnc/src/libnml/inifile/inifile.cc`、`inifile.hh`、`inivar.cc`；`linuxcnc/src/emc/ini/emcIniFile.cc`、`iniaxis.cc`、`inijoint.cc`、`inispindle.cc`、`initraj.cc`、`inihal.cc` | 复用解析规则；路径、include、变量和错误映射到 `/workspace` | `linuxcnc/configs/sim/**` 及其关联启动/配置测试 |
| RS-274/G-code 读取 | `linuxcnc/src/emc/rs274ngc/interp_read.cc`、`interp_check.cc`、`interp_setup.cc`、`interp_base.cc`、`rs274ngc.hh` | 优先编译核心；输入和诊断通过稳定 ABI 暴露 | `linuxcnc/unit_tests/interp/**`；`linuxcnc/tests/interp/**` |
| G/M/O 执行和 canonical 输出 | `linuxcnc/src/emc/rs274ngc/interp_execute.cc`、`interp_convert.cc`、`interp_cycles.cc`、`interp_o_word.cc`、`interp_queue.cc`、`interp_write.cc`、`canonmodule.cc` | 复用解释器状态和 canonical；队列接入 `sim_task` | `linuxcnc/tests/m70-m73/**`、`linuxcnc/tests/mdi-*`、全部 G/M/O manifest |
| Remap、Python 和命名参数 | `linuxcnc/src/emc/rs274ngc/interp_remap.cc`、`interp_python.cc`、`interp_namedparams.cc`、`pyparamclass.cc`、`pyinterp1.cc`、`pyarrays.cc`；`linuxcnc/src/emc/pythonplugin/python_plugin.cc`、`python_plugin.hh` | Pyodide/CPython-WASM 虚拟模块；禁止宿主进程、线程、设备和任意路径 | `linuxcnc/configs/sim/**/python/**`、`tests/**/remap.py`、`unit_tests/interp/**` |
| 模态、单位和坐标状态 | `linuxcnc/src/emc/rs274ngc/modal_state.cc`、`modal_state.hh`、`interp_parameter_def.hh`、`units.h`、`interp_inverse.cc` | 状态快照版本化；与原生模态 golden 对照 | `linuxcnc/unit_tests/interp/**`；坐标/单位仿真配置 |
| 轨迹规划和队列 | `linuxcnc/src/emc/tp/tp.c`、`tp.h`、`tp_types.h`、`tc.c`、`tcq.c`、`tcq.h`、`blendmath.c`、`spherical_arc.c`、`spherical_arc.h` | 固定 tick 驱动；保留前瞻、blend、exact path/stop 和容差 | `linuxcnc/unit_tests/tp/**`；`linuxcnc/tests/motion-logger/**` |
| Task、canonical 和 NML | `linuxcnc/src/emc/task/emctaskmain.cc`、`taskclass.cc`、`taskintf.cc`、`emccanon.cc`；`linuxcnc/src/emc/nml_intf/emc.cc`、`emc.hh`、`emc_nml.hh`、`interpl.cc`；`linuxcnc/src/libnml/nml/nml.cc`、`stat_msg.cc`、`cmd_msg.cc` | 单 Worker `sim_task` 和 message bus；删除 fork/进程边界但保留状态、命令和错误语义 | `linuxcnc/tests/mdi-*`、`linuxcnc/tests/abort/**`、`linuxcnc/tests/linuxcncrsh-*` |
| NML/CMS/共享内存边界 | `linuxcnc/src/libnml/cms/**`、`linuxcnc/src/libnml/buffer/**`、`linuxcnc/src/libnml/nml/**` | 进程间通信改为 Worker message bus；共享内存改为进程内结构和版本化快照 | NML、linuxcncrsh、状态/命令 golden |
| RTAPI、OS 接口和时钟 | `linuxcnc/src/rtapi/**`；`linuxcnc/src/libnml/os_intf/timer.cc`、`_timer.c`、`sem.cc`、`shm.cc`；`linuxcnc/src/emc/linuxcnc.h` | 固定逻辑时钟、虚拟同步原语和受控内存；内核实时、CPU 绑定和设备访问标记为 `REAL-EXCLUDED` | `linuxcnc/tests/lowlevel/**`、`linuxcnc/tests/rtapi-shmem/**`（可移植部分） |
| Motion、回零和限位 | `linuxcnc/src/emc/motion/motion.c`、`control.c`、`command.c`、`homing.c`、`emcmotglb.c`、`emcmotutil.c`、`simple_tp.c`、`motion_struct.h`、`homing.h` | `sim_motion` 状态机；虚拟编码器、开关、跟随误差和故障注入 | `linuxcnc/tests/hard-limits/**`、`linuxcnc/tests/abort/**`、`linuxcnc/tests/limit3/**` |
| Kinematics | `linuxcnc/src/emc/kinematics/*kins.c`、`*kins.cc`、`kins_util.c`、`genserfuncs.c`、`trtfuncs.c`、`switchkins.c`；关键文件包括 `trivkins.c`、`5axiskins.c`、`genhexkins.c`、`genserkins.c`、`lineardeltakins.c`、`rotarydeltakins.c`、`corexykins.c`、`xyzac-trt-kins.c`、`xyzbc-trt-kins.c` | 静态 WASM 模块和 manifest 注册；不使用宿主动态库 | `linuxcnc/configs/sim/axis/gantry/**`、`linuxcnc/configs/sim/axis/foam/**`、`linuxcnc/configs/sim/axis/ldelta*`、机器人样例；运动学单测 |
| Posemath 和几何 | `linuxcnc/src/libnml/posemath/posemath.cc`、`posemath.h`、`gomath.c`、`gomath.h`、`sincos.c`、`gotypes.h` | 原样编译或等价 ABI；固定浮点编译选项 | posemath 相关单测、TP/kinematics golden |
| Tooldata、工具表和数据库 | `linuxcnc/src/emc/tooldata/tooldata_common.cc`、`tooldata_nml.cc`、`tooldata_db.cc`、`tooldata_mmap.cc`、`tool_mmap_read.cc`、`tooldata.hh` | 内存工具服务 + OPFS 事务；兼容 pocket、offset、wear 和数据库迁移 | `linuxcnc/tests/mdi-queue/**`、`linuxcnc/configs/sim/**/*.tbl` |
| IO、换刀、主轴和冷却 | `linuxcnc/src/emc/iotask/ioControl.cc`、`ioControl_v2.cc`；`linuxcnc/src/emc/tooldata/**` | 虚拟 IO、主轴、换刀、探针和故障模型；真实协议排除 | `linuxcnc/configs/sim/axis/iocontrolv2/**`、`linuxcnc/configs/sim/axis/lathe_multispindle/**`、换刀测试 |

## 3. HAL、PLC 和数字孪生映射

| 功能域 | LinuxCNC 源程序/文件范围 | Web/WASM 处理 | 首批测试来源 |
|---|---|---|---|
| HAL 核心对象和生命周期 | `linuxcnc/src/hal/hal_lib.c`、`hal.h`、`hal_priv.h`、`halmodule.cc` | pin/signal/param/component 图和生命周期；固定线程顺序 | `linuxcnc/tests/hal-*`、`linuxcnc/tests/basic/**` |
| halcmd/halrun/Scope | `linuxcnc/src/hal/utils/halcmd.c`、`halcmd_commands.cc`、`halcmd_main.c`、`halsh.c`、`scope.c`、`scope_rt.c`、`meter.c` | Web 命令控制台、波形采样和回放；真实 PCI 工具排除 | `linuxcnc/tests/halrun-*`、`linuxcnc/tests/threads.*`、`linuxcnc/tests/mux/**` |
| `.comp` 编译和组件 ABI | `linuxcnc/src/hal/utils/halcompile.g`；`linuxcnc/src/hal/components/*.comp`、`*.c` | 构建期静态组件 manifest；每个 `.comp` 展开为独立条目 | `linuxcnc/tests/symbols.*`、组件同名测试和 `configs/sim/**` |
| 虚拟轴/主轴/编码器/回零 | `linuxcnc/src/hal/components/sim_axis_hardware.comp`、`sim_spindle.comp`、`sim_encoder.c`、`sim_home_switch.comp`、`sim_parport.comp`、`sim_matrix_kb.comp` | 通用数字孪生；输入、延迟、噪声和故障可录制 | `configs/sim/**`、`tests/hard-limits/**`、`tests/edge/**` |
| 运动和控制组件 | `linuxcnc/src/hal/components/stepgen.c`、`encoder.c`、`encoder_ratio.c`、`pid.c`、`simple_tp.comp`、`gantry.comp`、`corexy_by_hal.comp`、`spindle.comp`、`spindle_monitor.comp` | 固定周期组件和类型转换；与 HAL golden 对照 | `linuxcnc/tests/limit3/**`、`linuxcnc/tests/biquad/**`、组件测试 |
| 探针、等离子和激光 | `linuxcnc/src/hal/components/sphereprobe.comp`、`plasmac.comp`、`laserpower.comp`、`homecomp.comp`、`thc.comp`、`thcud.comp`、`ohmic.comp` | 虚拟触发、arc-ok、torch、功率和超时故障模型 | `configs/sim/axis/laser/**`、probe/PlasmaC 样例 |
| ClassicLadder | `linuxcnc/src/hal/classicladder/*.c`、`*.h`、`projects_examples/*.clp`，重点为 `classicladder.c`、`calc.c`、`calc_sequential.c`、`files.c`、`files_project.c`、`protocol_modbus_master.c` | PLC 扫描、梯形图、顺序控制和虚拟寄存器；真实串口/TCP Modbus 排除 | ClassicLadder 工程样例、`configs/sim/**` 中 `.clp` |

## 4. Python、UI 和可视化映射

| 功能域 | LinuxCNC 源程序/文件范围 | Web/WASM 处理 | 首批测试来源 |
|---|---|---|---|
| Python HAL/LinuxCNC API | `linuxcnc/lib/python/hal.py`、`hal_glib.py`、`pyhal.py`、`tooldb.py`、`linuxcnc_util.py`、`rs274/**` | 虚拟模块和受控回调；API、异常和返回值对照 | `configs/sim/**/**/*.py`、Python remap/filter tests |
| AXIS/Gremlin 路径显示 | `linuxcnc/src/emc/usr_intf/axis/scripts/axis.py`、`axis-remote.py`、`mdi.py`、`hal_manualtoolchange.py`；`gremlin/gremlin.py`、`qt5_graphics.py`；`linuxcnc/lib/python/rs274/glcanon.py` | Web 控制台、3D 轨迹和程序工作流；不复制 GTK 窗口 | AXIS 仿真配置、UI tests、路径 golden |
| Gmoccapy/Gscreen/Touchy | `linuxcnc/src/emc/usr_intf/gmoccapy/*.py`、`*.glade`；`gscreen/*.py`、`*.glade`；`touchy/*.py`、`*.glade` | 状态、触控、jog、MDI、报警和偏好 Web 等价 | `configs/sim/**` 面板样例、浏览器 E2E |
| QtVCP/PyVCP/GladeVCP | `linuxcnc/src/emc/usr_intf/qtvcp/qtvcp.py`；`linuxcnc/lib/python/qtvcp/**`、`gladevcp/**`、`pyvcp_widgets.py`、`pyngcgui.py`、`vcpparse.py` | XML/descriptor 转 Web Component schema；保留 pin、属性、回调和权限 | `configs/sim/axis/gladevcp/**`、`halui_pyvcp/**`、QtVCP samples |
| Vismach/机床模型 | `linuxcnc/src/hal/user_comps/vismach/*.py`、`linuxcnc/lib/python/vismach.py` | Three.js/WebGPU 模型、姿态和刀具层 | vismach/5-axis/机器人仿真配置 |
| PlasmaC、NGCGUI 和工具界面 | `linuxcnc/src/emc/usr_intf/qtplasmac/*.py`；`linuxcnc/lib/python/plasmac/**`、`pyngcgui.py` | 等离子流程、材料表、参数表单和预览 Web 等价 | `configs/sim/axis/laser/**`、相关 qtplasmac/NGCGUI 样例 |

Stepconf/Pncconf 的真实板卡、引脚和实时配置源文件仍需进入 manifest，但标记为 `REAL-EXCLUDED`；其中可生成纯仿真 INI/HAL 的部分必须拆出并按 `WEB-EQUIV` 验收，不能整体排除。

## 5. 仿真配置与测试来源映射

配置文件不是“示例附件”，而是功能来源。manifest 生成器必须递归扫描 `linuxcnc/configs/sim/**`，为每个入口 INI 建立资源图，至少关联其 HAL、TBL、VAR、NGC、PY、XML、TCL、UI、模型和材料文件。当前重点入口包括：

| 仿真能力 | 配置入口/资源范围 |
|---|---|
| 最小三轴、坐标和 INI include | `linuxcnc/configs/sim/axis/minimal_xyz.ini`、`axis/ini_with_includes/**` |
| Gantry、额外关节、锁定转台 | `axis/gantry/**`、`axis/extrajoints/**`、`axis/ja_tests/**` |
| 车床、Fanuc Y、多主轴 | `axis/lathe.ini`、`axis/lathe-fanucy/**`、`axis/lathe_multispindle/**` |
| Foam/Delta/机器人/多轴 | `axis/foam/**`、`axis/ldelta*`、`**/*kins*`、`axis/*gui*` |
| Laser/Plasma/探针 | `axis/laser/**`、`axis/gladevcp/probe.*`、所有包含 `plasmac`/`probe` 的 sim 入口 |
| IOControl v2、换刀和 O-word | `axis/iocontrolv2/**`、所有 `toolchange`、`oword`、`m6` 入口 |
| HAL UI、Scope、VCP 和面板 | `axis/halui_pyvcp/**`、`axis/gladevcp/**`、所有 `*.halshow`、`*.halscope`、`*.xml` |

测试来源按功能反向绑定：`linuxcnc/tests/**` 的每个可运行测试、`linuxcnc/unit_tests/**` 的每个测试目标和配置入口都必须至少出现在一个 manifest 条目的 `test_sources` 或 `config_inputs` 中。只依赖真实硬件、实时内核或宿主驱动的测试登记为 `REAL-EXCLUDED`，并写明对应的仿真替代测试。

### 5.1 构建和链接来源

构建文件也是源程序关联的一部分。以下文件必须扫描并绑定到对应的编译目标、组件 manifest 和排除理由：

| 构建来源 | 关联要求 |
|---|---|
| `linuxcnc/meson.build`、`linuxcnc/src/meson.build` | 记录原生目标、子目录和源文件集合；WASM 目标以独立 CMake/Emscripten manifest 对照 |
| `linuxcnc/src/**/meson.build`、`linuxcnc/src/**/Submakefile` | 记录每个库、模块、组件和测试目标的实际输入；源文件未被任何目标引用时标记为孤儿候选 |
| `linuxcnc/src/hal/components/*.comp` 的生成规则 | 记录 `.comp` 到生成 C/ABI 的映射和编译参数；生成文件不能替代原始 `.comp` 来源 |
| `linuxcnc/unit_tests/**/meson.build`、`linuxcnc/tests/**/test.sh` | 记录测试入口、预期结果和需要的仿真资源；测试脚本失败或不可移植时必须登记替代测试 |

## 6. 生成、审查和变更规则

1. M0 扫描源码、文档、配置和测试，生成带 `source_sha` 的初始索引；扫描器版本和排除规则写入 context lock。
2. 领域负责人把索引项归并为稳定 `feature_id`，保留一对多和多对一关系，不删除原始来源引用。
3. C/C++/C/Python/组件符号由固定版本的解析器或 `compile_commands.json` 生成；解析失败的项为 `blocked`，不得手工填充“已覆盖”。
4. 文件新增、删除、重命名、构建清单变化或配置入口变化都必须触发 manifest diff；差异没有对应任务和测试时 CI 失败。
5. 发布使用锁定的 source map、coverage manifest、golden manifest 和 context lock；source map 与 coverage manifest 的数量、哈希和反向索引必须一致。

source map 是移植的导航和审计入口，不以目录级“已处理”替代文件级和功能级证据。只有源文件关联、实现、测试、差异和排除理由全部闭合，功能条目才允许进入 `accepted`。