15 KiB
15 KiB
LinuxCNC Web/WASM 仿真功能与源程序关联目录
文档状态：Draft v0.1
适用基线：LinuxCNC 2.10.0~pre0；源码根目录为 linuxcnc/
上层路线：技术路线
覆盖验收：仿真全功能覆盖矩阵
执行治理：项目执行与交付策略
前端与通信：前端与 LinuxCNC 通信详细设计
总控执行：移植总控执行手册
本目录把“功能”与 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。每个条目仍须按覆盖矩阵的正常、边界、错误、暂停/恢复、持久化/离线和交互维度验收。
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 |
| Worker 协议与固定 tick 边界 | wasm-core/include/sim_protocol.h、wasm-core/src/sim_protocol.c、web/worker/sim-session.mjs、web/worker/sim-worker.mjs |
版本化 envelope、单调 seq/tick、会话状态机和错误映射；WASM 核心只暴露受控 C ABI | wasm-core/tests/sim_protocol_test.c、web/worker/test_wasm_session.mjs、scripts/test_protocol.py |
| 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 注册；不使用宿主动态库；按K0-K8 运动学主线闭合正逆解、flags、分支、奇异性和恢复 | linuxcnc/configs/sim/axis/gantry/**、linuxcnc/configs/sim/axis/foam/**、linuxcnc/configs/sim/axis/ldelta*、机器人样例；运动学单测和 native FK/IK golden |
| 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. 生成、审查和变更规则
- M0 扫描源码、文档、配置和测试，生成带
source_sha的初始索引；扫描器版本和排除规则写入 context lock。 - 领域负责人把索引项归并为稳定
feature_id，保留一对多和多对一关系，不删除原始来源引用。 - C/C++/C/Python/组件符号由固定版本的解析器或
compile_commands.json生成；解析失败的项为blocked，不得手工填充“已覆盖”。 - 文件新增、删除、重命名、构建清单变化或配置入口变化都必须触发 manifest diff；差异没有对应任务和测试时 CI 失败。
- 发布使用锁定的 source map、coverage manifest、golden manifest 和 context lock；source map 与 coverage manifest 的数量、哈希和反向索引必须一致。
source map 是移植的导航和审计入口，不以目录级“已处理”替代文件级和功能级证据。只有源文件关联、实现、测试、差异和排除理由全部闭合，功能条目才允许进入 accepted。