按推荐建议，继续执行
结论：新增 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
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user