From d5c5b0852f561ace07382822adceeb4e27211101 Mon Sep 17 00:00:00 2001 From: wangdequan Date: Sun, 7 Jun 2026 18:41:25 +0800 Subject: [PATCH] =?UTF-8?q?=E6=8C=89=E6=8E=A8=E8=8D=90=E5=BB=BA=E8=AE=AE?= =?UTF-8?q?=EF=BC=8C=E7=BB=A7=E7=BB=AD=E6=89=A7=E8=A1=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 结论：新增 compatibility-validation 与 drift-report，记录当前 native 验证链路、fixture 覆盖、无漂移规则和已知缺口，继续约束移植行为跟随 LinuxCNC 源程序。 --- wasm-port/docs/compatibility-validation.md | 95 ++++++++++++++++++++++ wasm-port/docs/drift-report.md | 60 ++++++++++++++ wasm-port/docs/porting-steps-standalone.md | 5 ++ 3 files changed, 160 insertions(+) create mode 100644 wasm-port/docs/compatibility-validation.md create mode 100644 wasm-port/docs/drift-report.md diff --git a/wasm-port/docs/compatibility-validation.md b/wasm-port/docs/compatibility-validation.md new file mode 100644 index 0000000..c5dce04 --- /dev/null +++ b/wasm-port/docs/compatibility-validation.md @@ -0,0 +1,95 @@ +# 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 validation command is: + +```bash +wasm-port/tests/native/verify_native_probes.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/build_native_probes.sh` + Builds native source probes and standalone harnesses from vendored + LinuxCNC source plus narrow runtime wrappers. +5. `tests/native/verify_native_probes.sh` + Checks probe exit codes, source-probe coverage, harness stdout, canonical + fixture events, and expected error behavior. + +## 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_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 and captures canonical events. | +| `linuxcnc_parameter_file_harness` | Validates LinuxCNC parameter file restore/save behavior and required/read-only parameter handling. | +| `linuxcnc_tp_api_probe` | Validates vendored LinuxCNC trajectory planner calls for linear, arc, and queued motion paths. | + +## Fixture Coverage + +Positive G-code fixtures currently cover: + +- linear traverse/feed +- arc semantics +- modal absolute/incremental motion +- position parameters +- canned cycles +- coordinate offsets +- feed and motion control modes +- probing +- threading and rigid tap +- NURBS G5/G6 +- spindle orient +- tool semantics +- tool table setup +- 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 +- read-only named parameter writes +- read-only numbered parameter writes +- missing tool +- missing tool length offset + +## Validation Boundaries + +Current validation is native-only. WASM, browser, SDK, OPFS, and full +machine-session validation remain future work. + +The current fixture expectations validate standalone behavior against the +vendored LinuxCNC source path. They do not yet run a side-by-side native +LinuxCNC executable comparison for each fixture. diff --git a/wasm-port/docs/drift-report.md b/wasm-port/docs/drift-report.md new file mode 100644 index 0000000..b74a234 --- /dev/null +++ b/wasm-port/docs/drift-report.md @@ -0,0 +1,60 @@ +# Drift Report + +## Current Status + +As of the current upstream baseline, no byte-level drift is allowed between +files listed in `tools/source-manifest.txt` and the matching files under +`../linuxcnc/`. + +The enforced upstream baseline is: + +```text +60597ee0718873d2449058c824262a275e5e4bad +``` + +`tools/verify_vendor_sync.sh` enforces this by comparing every manifest file +against upstream during native validation. + +## Allowed Standalone Boundaries + +The following differences are intentional runtime boundaries, not LinuxCNC +semantic rewrites: + +| Boundary | Standalone treatment | +| --- | --- | +| RTAPI | Minimal compatibility shim in `runtime/core/shims/rtapi.h`. | +| HAL lookup | Standalone HAL adapter for `_hal[...]` named parameter reads. | +| INI lookup | Standalone INI adapter around vendored LinuxCNC INI parser behavior. | +| Canonical output | Canonical calls are captured as test events instead of driving hardware. | +| Python/remap | Python/remap hooks are stubbed at the runtime edge. | +| Dynamic interpreter path | `interp_base.cc` probe uses standalone `EMC2_HOME` compile-time path boundary. | +| Realtime scheduler | TP probes seed deterministic status/config data instead of running LinuxCNC realtime process topology. | +| Browser storage | OPFS remains outside the native core and is not yet connected. | + +## Enforced Non-Drift Rules + +- Do not edit `../linuxcnc/`. +- Do not patch vendored files without adding a patch under `patches/` and + documenting the reason. +- Do not add standalone `Interp::convert_g()`. +- Do not add `.c` or `.cc` manifest files without a source compile probe. +- Do not sync from a different upstream commit without updating + `tools/upstream-baseline.txt` and `docs/scope-and-baseline.md`. + +## Known Gaps + +- No browser/WASM parity tests yet. +- No JS SDK validation yet. +- No OPFS persistence validation yet. +- Full kinematics implementation files are not yet extracted. +- Full 3-axis, non-trivial kinematics, and 5-axis machine baselines are not + established. +- Fixture expectations are currently checked against the standalone vendored + source path, not by running a native LinuxCNC binary for every fixture. + +## Current Drift Conclusion + +Within the native extracted-core scope, the port currently has no permitted +byte-level drift from vendored LinuxCNC source files. All current behavior +coverage is guarded by upstream baseline validation, vendor sync validation, +source compile probes, native harnesses, and fixture checks. diff --git a/wasm-port/docs/porting-steps-standalone.md b/wasm-port/docs/porting-steps-standalone.md index 760b0f7..ada8dce 100644 --- a/wasm-port/docs/porting-steps-standalone.md +++ b/wasm-port/docs/porting-steps-standalone.md @@ -500,6 +500,11 @@ Current verified progress: - `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. +- `docs/compatibility-validation.md` records the current validation chain, + source coverage requirements, native harnesses, fixture coverage, and + validation boundaries. +- `docs/drift-report.md` records current no-drift enforcement, allowed + standalone runtime boundaries, known gaps, and the current drift conclusion. ## Phase 4: Port INI Parsing Without Editing Upstream