226 lines
12 KiB
Markdown
226 lines
12 KiB
Markdown
# Compatibility Validation
|
|
|
|
## Purpose
|
|
|
|
This document records how the standalone LinuxCNC WASM port currently proves
|
|
that migrated behavior remains tied to LinuxCNC source code and fixture
|
|
semantics.
|
|
|
|
The primary native validation command is:
|
|
|
|
```bash
|
|
wasm-port/tests/native/verify_native_probes.sh
|
|
```
|
|
|
|
The current WASM smoke validation command is:
|
|
|
|
```bash
|
|
wasm-port/tests/wasm/node/verify_ini_wasm.sh
|
|
```
|
|
|
|
The current WASM interpreter-core smoke validation command is:
|
|
|
|
```bash
|
|
wasm-port/tests/wasm/node/verify_interp_wasm.sh
|
|
```
|
|
|
|
The current OPFS host-boundary validation command is:
|
|
|
|
```bash
|
|
wasm-port/tests/opfs/node/verify_file_service.sh
|
|
```
|
|
|
|
The current browser smoke validation command is:
|
|
|
|
```bash
|
|
wasm-port/tests/browser/verify_ini_panel_browser.sh
|
|
```
|
|
|
|
The current aggregate host/WASM/browser smoke command is:
|
|
|
|
```bash
|
|
wasm-port/tests/host/verify_host_smokes.sh
|
|
```
|
|
|
|
## Validation Chain
|
|
|
|
The native validation script runs these checks in order:
|
|
|
|
1. `tools/verify_upstream_baseline.sh`
|
|
Confirms `../linuxcnc` is at the recorded upstream commit in
|
|
`tools/upstream-baseline.txt`.
|
|
2. `tools/verify_vendor_sync.sh`
|
|
Confirms every manifest file is present in `vendor/linuxcnc/`, no extra
|
|
vendored file exists, and every vendored file is byte-identical to upstream.
|
|
3. `tools/verify_no_standalone_cnc_semantics.sh`
|
|
Confirms standalone code has not reintroduced `Interp::convert_g()`.
|
|
4. `tools/verify_native_linuxcnc_fixture_baseline.sh`
|
|
Runs a side-by-side fixture baseline through upstream
|
|
`../linuxcnc/bin/rs274` and compares normalized canonical events for
|
|
fixtures that do not require standalone-only runtime adapters.
|
|
5. `tools/build_native_probes.sh`
|
|
Builds native source probes and standalone harnesses from vendored
|
|
LinuxCNC source plus narrow runtime wrappers.
|
|
6. `tests/native/verify_native_probes.sh`
|
|
Checks probe exit codes, source-probe coverage, harness stdout, canonical
|
|
fixture events, and expected error behavior.
|
|
|
|
The WASM INI smoke script builds `runtime/ui/ini-panel/linuxcnc_ini.js` and
|
|
`linuxcnc_ini.wasm` from vendored LinuxCNC `inifile.cc`, then loads that
|
|
module through `runtime/sdk/src/linuxcnc-ini.js` in Node and verifies INI
|
|
queries against a file written to the Emscripten filesystem.
|
|
|
|
The WASM interpreter-core smoke script builds
|
|
`build/wasm/core/linuxcnc_interp.js` and `linuxcnc_interp.wasm` from the same
|
|
vendored LinuxCNC interpreter source set used by the native minimal
|
|
interpreter harness. It loads the module in Node, runs the `minimal_linear`
|
|
G-code fixture through `Interp::execute()`, and compares emitted canonical
|
|
events with `tests/fixtures/canon/minimal_linear.events`.
|
|
|
|
The OPFS host-boundary script validates the JavaScript file-service adapter
|
|
with a Node mock of the browser File System Access handles. It covers nested
|
|
directory creation, text save/load, missing file behavior, invalid relative
|
|
paths, unavailable OPFS storage, and the host-side OPFS path model for INI,
|
|
tool table, parameter, G-code, preview-cache, and session-snapshot storage
|
|
targets. It also validates the host-side session snapshot JSON envelope and
|
|
round-trip store plus pure-text machine file and G-code stores without
|
|
defining CNC machine-state or file-format semantics.
|
|
|
|
The browser smoke script serves `wasm-port/` over localhost and runs Chromium
|
|
headless against a test page that imports the JS SDK, loads the INI WASM
|
|
module, queries vendored LinuxCNC INI parsing through the SDK, and performs an
|
|
OPFS text-file, generic session snapshot, machine file, and G-code text
|
|
round trip.
|
|
|
|
The aggregate host smoke script builds the INI WASM artifact once, then runs
|
|
the Node WASM smoke, the Node OPFS mock smoke, and the Chromium browser smoke.
|
|
|
|
## Source Coverage
|
|
|
|
Every `.c` and `.cc` entry in `tools/source-manifest.txt` must have a
|
|
corresponding `*_source_probe` entry in `build/native/source-probes.tsv`.
|
|
The validation fails if:
|
|
|
|
- a manifest source file lacks a source probe;
|
|
- a source probe references a file not listed in the manifest;
|
|
- a manifest file is duplicated;
|
|
- vendored files drift byte-for-byte from upstream LinuxCNC.
|
|
|
|
## Current Native Harnesses
|
|
|
|
| Harness | Purpose |
|
|
| --- | --- |
|
|
| `linuxcnc_ini_probe` | Validates vendored LinuxCNC INI parsing can be used standalone. |
|
|
| `linuxcnc_interp_state_probe` | Validates interpreter state constants and structs compile under the standalone boundary. |
|
|
| `linuxcnc_emc_status_probe` | Validates the standalone `emcStatus` machine-units status boundary used by vendored interpreter conversion and initialization code. |
|
|
| `linuxcnc_namedparam_harness` | Validates LinuxCNC named parameter behavior, `_ini[...]`, and `_hal[...]` adapter resolution. |
|
|
| `linuxcnc_interp_minimal_harness` | Runs G-code fixtures through vendored LinuxCNC parser/execution/conversion code, captures canonical events, and validates feed-rate state readback across length-unit changes. |
|
|
| `linuxcnc_parameter_file_harness` | Validates LinuxCNC parameter file restore/save behavior and required/read-only parameter handling. |
|
|
| `linuxcnc_interp_init_harness` | Validates vendored LinuxCNC `Interp::init()` emits canonical initialization boundaries, reads metric/inch machine units, and synchronizes current/selected tool slots through standalone status adapters. |
|
|
| `linuxcnc_indexer_harness` | Validates vendored LinuxCNC single-axis rotary indexer dispatch emits lock/unlock and motion boundaries through the standalone event sink. |
|
|
| `linuxcnc_tp_api_probe` | Validates vendored LinuxCNC trajectory planner calls for linear, arc, and queued motion paths. |
|
|
| `linuxcnc_kinematics_probe` | Validates vendored LinuxCNC `trivkins.c` plus `kins_util.c` initialize and perform identity forward/inverse mapping through the standalone HAL/RTAPI boundary. |
|
|
| `linuxcnc_5axis_kinematics_probe` | Validates vendored LinuxCNC `5axiskins.c` through `switchkins.c`, including 5-axis forward/inverse round-trip behavior and switching to identity kinematics. |
|
|
| `linuxcnc_xyzac_trt_kinematics_probe` | Validates vendored LinuxCNC XYZAC TRT kinematics through `switchkins.c`, including forward/inverse round-trip behavior and switching to identity kinematics. |
|
|
| `linuxcnc_xyzbc_trt_kinematics_probe` | Validates vendored LinuxCNC XYZBC TRT kinematics through `switchkins.c`, including forward/inverse round-trip behavior and switching to identity kinematics. |
|
|
| `linuxcnc_corexy_kinematics_probe` | Validates vendored LinuxCNC CoreXY forward/inverse behavior through the standalone HAL/RTAPI boundary. |
|
|
| `linuxcnc_rotate_kinematics_probe` | Validates vendored LinuxCNC rotated-axis forward/inverse behavior. |
|
|
| `linuxcnc_rose_kinematics_probe` | Validates vendored LinuxCNC rose kinematics forward/inverse behavior. |
|
|
| `linuxcnc_max_kinematics_probe` | Validates vendored LinuxCNC max kinematics forward/inverse behavior. |
|
|
| `linuxcnc_lineardelta_kinematics_probe` | Validates vendored LinuxCNC linear-delta inverse/forward pose round-trip behavior. |
|
|
| `linuxcnc_rotarydelta_kinematics_probe` | Validates vendored LinuxCNC rotary-delta inverse/forward pose round-trip behavior. |
|
|
| `linuxcnc_scorbot_kinematics_probe` | Validates vendored LinuxCNC Scorbot forward/inverse behavior and pose round-trip behavior. |
|
|
| `linuxcnc_tripod_kinematics_probe` | Validates vendored LinuxCNC tripod inverse/forward behavior, including below-platform flag behavior. |
|
|
| `linuxcnc_scara_kinematics_probe` | Validates vendored LinuxCNC SCARA forward/inverse behavior and switching to identity kinematics. |
|
|
| `linuxcnc_puma_kinematics_probe` | Validates vendored LinuxCNC PUMA forward/inverse behavior, pose round-trip behavior, and switching to identity kinematics. |
|
|
| `linuxcnc_genser_kinematics_probe` | Validates vendored LinuxCNC generic serial kinematics forward/inverse behavior and switching to identity kinematics. |
|
|
| `linuxcnc_genhex_kinematics_probe` | Validates vendored LinuxCNC generic hexapod inverse/forward behavior, including the switchkins iterative-forward warmup path. |
|
|
| `linuxcnc_pentakins_kinematics_probe` | Validates vendored LinuxCNC pentapod inverse/forward pose round-trip behavior. |
|
|
|
|
## Current WASM Harnesses
|
|
|
|
| Harness | Purpose |
|
|
| --- | --- |
|
|
| `tests/wasm/node/verify_ini_wasm.sh` | Validates the browser-facing INI WASM module can be built from vendored LinuxCNC `inifile.cc`, loaded through the JS SDK in Node, and queried through the exported C ABI. |
|
|
| `tests/wasm/node/verify_interp_wasm.sh` | Validates the initial interpreter-core WASM module can be built from vendored LinuxCNC interpreter source, run `minimal_linear.ngc` through `Interp::execute()`, and match the native canonical event fixture. |
|
|
| `tests/opfs/node/verify_file_service.sh` | Validates the host-owned OPFS text-file adapter, path model, session snapshot store, machine file store, and G-code text store used by the browser INI panel without moving file persistence into the WASM core. |
|
|
| `tests/browser/verify_ini_panel_browser.sh` | Validates the INI SDK, WASM module loading, OPFS text-file round trip, generic session snapshot round trip, machine file text round trip, and G-code text round trip in a real browser runtime. |
|
|
| `tests/host/verify_host_smokes.sh` | Runs the current host-side Node, WASM interpreter-core, OPFS, and browser smoke validation with shared WASM builds. |
|
|
|
|
## Fixture Coverage
|
|
|
|
Positive G-code fixtures currently cover:
|
|
|
|
- linear traverse/feed
|
|
- arc semantics
|
|
- modal absolute/incremental motion
|
|
- position parameters
|
|
- canned cycles
|
|
- coordinate offsets
|
|
- G53 machine-coordinate motion
|
|
- feed and motion control modes
|
|
- probing
|
|
- threading and rigid tap
|
|
- NURBS G5/G6
|
|
- spindle orient
|
|
- tool semantics
|
|
- tool table setup
|
|
- tool-data reload boundary
|
|
- interpreter state-tag boundary
|
|
- percent-delimited file `FINISH` boundary
|
|
- file-open `ON_RESET` boundary
|
|
- comment logging canonical calls
|
|
- named and numbered parameters
|
|
- O-word subroutines
|
|
- program-end modal reset
|
|
- canonical runtime edge calls
|
|
|
|
Negative fixtures currently cover:
|
|
|
|
- zero-feed `G1`
|
|
- arc radius mismatch
|
|
- zero-radius arc
|
|
- G53 incremental-mode rejection
|
|
- read-only named parameter writes
|
|
- read-only numbered parameter writes
|
|
- missing tool
|
|
- missing tool length offset
|
|
|
|
## Validation Boundaries
|
|
|
|
Current full-core validation is native-only. WASM/SDK validation covers the
|
|
INI parser smoke harness and an initial interpreter-core canonical event smoke
|
|
for `minimal_linear`. OPFS validation is limited to the JavaScript
|
|
host-boundary adapter plus the INI browser smoke harness. Full browser
|
|
coverage, full SDK coverage, and full machine-session validation remain future
|
|
work.
|
|
|
|
The current fixture expectations validate standalone behavior against both the
|
|
vendored LinuxCNC source path and an upstream `rs274` side-by-side baseline for
|
|
parser/conversion, arc geometry, offsets, feed-control and feed-state
|
|
readback, comment/logging,
|
|
numbered-parameter, probing, spindle-orient, file-open reset, file-finish,
|
|
tool-reload, tool select/change/length-offset, canned-cycle, state-tag motion,
|
|
tool-table setup, and O-word subroutine fixtures, plus threading/rigid tap,
|
|
NURBS dispatch boundaries, and the comparable canonical runtime edge and
|
|
program-end cleanup calls. Fixtures that depend on standalone-only runtime
|
|
adapters, HAL/INI/tool-change state, upstream `rs274` output gaps such as
|
|
`WAIT` or hidden NURBS control-point detail, or richer machine session state
|
|
still need dedicated native LinuxCNC baselines.
|
|
|
|
Remaining positive fixtures that are not in the upstream `rs274` side-by-side
|
|
baseline are intentionally held out until they get a dedicated native LinuxCNC
|
|
baseline: `namedparam_semantics` depends on standalone INI/HAL adapter
|
|
resolution. `state_tag_motion` now compares its motion events with upstream
|
|
`rs274`, while `UPDATE_TAG` events remain a standalone state-tag capture
|
|
boundary. `tool_semantics` now compares T/M6/G43/G49 canonical events with
|
|
upstream `rs274`; M61 current-pocket host-state behavior remains covered by the
|
|
standalone fixture expectation, and `Interp::synch()` current/selected tool
|
|
slot reads are covered by the native init harness.
|
|
|
|
The kinematics probes currently cover LinuxCNC identity/trivial kinematics, the
|
|
switchable `5axiskins` XYZBCW bridge-mill model, TRT `xyzac`/`xyzbc`
|
|
table-rotary models, CoreXY, rotated-axis, rose, max, linear-delta,
|
|
rotary-delta, Scorbot, tripod, SCARA, PUMA, generic serial, generic hexapod,
|
|
and pentapod models.
|