按推荐建议,继续执行
结论:新增 compatibility-validation 与 drift-report,记录当前 native 验证链路、fixture 覆盖、无漂移规则和已知缺口,继续约束移植行为跟随 LinuxCNC 源程序。
This commit is contained in:
95
wasm-port/docs/compatibility-validation.md
Normal file
95
wasm-port/docs/compatibility-validation.md
Normal file
@@ -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.
|
||||||
60
wasm-port/docs/drift-report.md
Normal file
60
wasm-port/docs/drift-report.md
Normal file
@@ -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.
|
||||||
@@ -500,6 +500,11 @@ Current verified progress:
|
|||||||
- `docs/source-reuse-map.md` records the current vendored LinuxCNC source
|
- `docs/source-reuse-map.md` records the current vendored LinuxCNC source
|
||||||
reuse matrix and dependency matrix, tying each extracted group to its
|
reuse matrix and dependency matrix, tying each extracted group to its
|
||||||
standalone runtime boundary and validation path.
|
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
|
## Phase 4: Port INI Parsing Without Editing Upstream
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user