diff --git a/wasm-port/docs/porting-steps-standalone.md b/wasm-port/docs/porting-steps-standalone.md index 32a7ae9..760b0f7 100644 --- a/wasm-port/docs/porting-steps-standalone.md +++ b/wasm-port/docs/porting-steps-standalone.md @@ -497,6 +497,9 @@ Current verified progress: local tool versions, and fixture baseline. `tools/verify_upstream_baseline.sh` now runs before vendor sync validation so extraction drift is checked against the intended upstream HEAD, not an accidental checkout change. +- `docs/source-reuse-map.md` records the current vendored LinuxCNC source + reuse matrix and dependency matrix, tying each extracted group to its + standalone runtime boundary and validation path. ## Phase 4: Port INI Parsing Without Editing Upstream diff --git a/wasm-port/docs/source-reuse-map.md b/wasm-port/docs/source-reuse-map.md new file mode 100644 index 0000000..d7da62c --- /dev/null +++ b/wasm-port/docs/source-reuse-map.md @@ -0,0 +1,67 @@ +# Source Reuse Map + +## Purpose + +This map records which LinuxCNC source files are currently vendored into the +standalone WASM port, why they are present, which standalone boundary they +touch, and how the port verifies that they still come directly from upstream +LinuxCNC. + +The authoritative extraction list is `tools/source-manifest.txt`. The upstream +baseline is recorded in `tools/upstream-baseline.txt` and +`docs/scope-and-baseline.md`. + +## Validation Contract + +Current validation is intentionally mechanical: + +- `tools/verify_upstream_baseline.sh` checks that `../linuxcnc` is at the + recorded upstream commit. +- `tools/verify_vendor_sync.sh` checks that every manifest file exists in + `vendor/linuxcnc/`, that no extra vendored file exists, and that each + vendored file is byte-identical to the matching upstream file. +- `tools/build_native_probes.sh` builds source-level native compile probes for + every `.c` and `.cc` file in the manifest. +- `tests/native/verify_native_probes.sh` checks that every manifest `.c` and + `.cc` file has a matching source probe in `build/native/source-probes.tsv`. +- `tools/verify_no_standalone_cnc_semantics.sh` rejects standalone + `Interp::convert_g()` definitions outside `vendor/linuxcnc/`. + +## Reuse Matrix + +| Capability | LinuxCNC source files | Port classification | Standalone boundary | Current validation | +| --- | --- | --- | --- | --- | +| INI parsing | `src/emc/ini/inifile.cc`, `inifile.h`, `inifile.hh` | Copy unchanged | Native file IO remains LinuxCNC-style in the vendored parser; browser OPFS integration remains outside this layer | Vendor byte sync, `linuxcnc_ini_probe`, `linuxcnc_inifile_source_probe` | +| RTAPI compatibility headers | `src/rtapi/rtapi_*.h` in the manifest | Copy unchanged plus standalone shim include path | `runtime/core/shims/rtapi.h` supplies the minimal standalone RTAPI surface needed by vendored code | Vendor byte sync, compile coverage through dependent source probes | +| Canon/NML-facing interpreter types | `src/emc/nml_intf/canon*.hh`, `emctool.h`, `interp_return.hh`, `motion_types.h`, `emcpose.*`, `emcpos.h`, `debugflags.h`, `src/emc/linuxcnc.h` | Copy unchanged | NML transport is not ported; wrappers provide only the status/type edges needed by standalone probes | Vendor byte sync, dependent source probes, `linuxcnc_tp_api_probe`, interpreter harnesses | +| Motion state headers | `src/emc/motion/state_tag.h`, `emcmotcfg.h`, `simple_tp.h`, `motion.h`, `mot_priv.h`, `axis.h` | Copy unchanged | Realtime motion process is not ported; standalone probes seed the small motion status/config state required by TP calls | Vendor byte sync, `linuxcnc_tp_api_probe` | +| Kinematics headers | `src/emc/kinematics/kinematics.h`, `cubic.h` | Copy unchanged | Kinematics implementation modules are not yet extracted; current use is type/interface support | Vendor byte sync, dependent compile coverage | +| Trajectory planner | `src/emc/tp/tp.c`, `tc.c`, `tcq.c`, `spherical_arc.c`, `blendmath.c`, `sp_scurve.c`, `ruckig_wrapper.c`, plus matching `*.h` files | Copy unchanged | Native realtime scheduling and motion process state are replaced by standalone probe setup | Vendor byte sync, per-file source probes, `linuxcnc_tp_api_probe` | +| Ruckig C planner support | Selected `src/emc/tp/cruckig/*.c` and `*.h` files in the manifest | Copy unchanged | Used as LinuxCNC planner support code through vendored TP sources | Vendor byte sync, per-file source probes | +| Posemath | `src/libnml/posemath/posemath.cc`, `_posemath.c`, `gomath.c`, `sincos.c`, and matching headers | Copy unchanged | `gomath.c` is compiled as C; `rtapi.h` shim is C/C++ compatible for this boundary | Vendor byte sync, per-file source probes, TP probe | +| RS274 interpreter state and parser | `src/emc/rs274ngc/modal_state.*`, `interp_internal.*`, `interp_read.cc`, `interp_check.cc`, `interp_execute.cc`, `interp_find.cc`, `interp_array.cc`, `interp_queue.*`, `rs274ngc*`, `units.h` | Copy unchanged | Python/remap/runtime edges are isolated in standalone wrappers and shims; parser and execution logic remain LinuxCNC source | Vendor byte sync, per-file source probes, interpreter harness fixtures | +| RS274 conversion semantics | `src/emc/rs274ngc/interp_convert.cc`, `interp_arc.cc`, `interp_inverse.cc`, `interp_cycles.cc`, `interp_g7x.cc`, `interp_o_word.cc`, `interp_write.cc` | Copy unchanged | Canonical calls are captured by standalone event sink functions; conversion behavior stays in vendored LinuxCNC files | Vendor byte sync, per-file source probes, canonical fixture suite, no standalone `Interp::convert_g()` guard | +| Named parameters | `src/emc/rs274ngc/interp_namedparams.cc`, related interpreter headers | Copy unchanged | `_ini[...]` and `_hal[...]` resolve through standalone INI/HAL adapters while lookup order stays LinuxCNC-derived | Vendor byte sync, source probe, `linuxcnc_namedparam_harness` | +| Dynamic interpreter base | `src/emc/rs274ngc/interp_base.*` | Copy unchanged | `interp_base.cc` source probe uses standalone `EMC2_HOME` compile-time path boundary for LinuxCNC dynamic interpreter lookup | Vendor byte sync, `linuxcnc_interp_base_source_probe` | + +## Dependency Matrix + +| Dependency | LinuxCNC files that expose it | Standalone treatment | +| --- | --- | --- | +| Native file IO | `inifile.cc`, `rs274ngc_pre.cc`, parameter file paths | Allowed in native probes; browser OPFS remains a host-side future adapter | +| RTAPI | `rtapi_*.h`, TP, posemath, motion headers | Minimal standalone shim in `runtime/core/shims/rtapi.h` | +| NML transport | `emc.hh`, motion/NML type headers | Transport is not ported; only structs/types needed by vendored compute code are used | +| HAL runtime | named parameter lookup and runtime status edges | Standalone HAL adapter under `runtime/core/linuxcnc_wrap/` | +| Python/remap | `rs274ngc_pre.cc`, `interp_o_word.cc`, remap hooks | Stubbed at runtime boundary; no Python CNC semantics are reimplemented | +| Canonical machine actions | `interp_convert.cc`, `interp_execute.cc`, `interp_queue.cc` | Captured by standalone canonical event sink functions for regression fixtures | +| Realtime scheduling | TP and motion headers | Not ported; native TP probes seed deterministic status/config state | +| GUI | None used as implementation | Native LinuxCNC GUI remains reference-only | + +## Known Gaps + +- Full kinematics implementation files are not yet extracted. +- Browser/WASM C ABI and JS SDK layers are not yet built for the full + interpreter/planner core. +- OPFS persistence is not yet connected to INI, tool table, parameter file, or + G-code program loading. +- Native LinuxCNC GUI code remains out of scope for implementation.