117 lines
9.5 KiB
Markdown
117 lines
9.5 KiB
Markdown
# 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, including boolean conversion through LinuxCNC `iniFindBool()` and string lookup for INI-declared `[RS274NGC]PARAMETER_FILE` and `[EMCIO]TOOL_TABLE` machine file names. |
|
|
| Canonical output | Canonical calls are captured as test events instead of driving hardware. |
|
|
| Feed-rate state | `SET_FEED_RATE` updates standalone canonical runtime state so vendored `convert_length_units()` can read it back through `GET_EXTERNAL_FEED_RATE()` during G20/G21 changes. |
|
|
| Tool-data reload | LinuxCNC `RELOAD_TOOLDATA` is captured as a canonical test event; browser/native tool-table reload plumbing remains a future host/runtime adapter. |
|
|
| Tool table storage | Vendored LinuxCNC `tooldata_common.cc` owns tool-table parsing and formatting; the standalone boundary only supplies the in-memory `tooldata_get()`/`tooldata_put()` callbacks, exposes load/save through the WASM C ABI, and forwards the host random-toolchanger flag to LinuxCNC `tooldata_init()`. |
|
|
| Tool slot status | Standalone tool adapter state supplies `GET_EXTERNAL_TOOL_SLOT()` and `GET_EXTERNAL_SELECTED_TOOL_SLOT()` for vendored `Interp::synch()`; `linuxcnc_interp_init_harness` guards current/selected slot synchronization. |
|
|
| Interpreter state tags | LinuxCNC `UPDATE_TAG` callbacks are captured from the state tags packed by vendored interpreter code; standalone code does not derive modal state. |
|
|
| Rotary indexer lock state | LinuxCNC `UNLOCK_ROTARY` and `LOCK_ROTARY` callbacks are captured from the vendored single-axis indexer path; standalone code does not implement rotary-indexing semantics. |
|
|
| File flush | LinuxCNC `FINISH` is captured as a canonical test event on the vendored `%`-delimited file-reading path. |
|
|
| WASM parameter-file backup | LinuxCNC `save_parameters()` calls `link()` to create the `.bak` parameter-file backup; `runtime/core/linuxcnc_wrap/linuxcnc_wasm_posix_stubs.cpp` maps that WASM/MEMFS edge to a file copy so the vendored save path can run unchanged. |
|
|
| Interpreter reset | LinuxCNC `ON_RESET` is captured as a canonical test event on the vendored interpreter reset/file-open path. |
|
|
| Interpreter init | LinuxCNC `INIT_CANON` and the canonical initialization sequence from vendored `Interp::init()` are captured as test events. |
|
|
| Comment logging | LinuxCNC `LOGOPEN`, `LOG`, `LOGAPPEND`, and `LOGCLOSE` callbacks are captured as canonical test events instead of writing host log files. |
|
|
| EMC status machine units | A narrow standalone `emcStatus` shim exposes the machine-units field used by vendored interpreter conversion and initialization code; `linuxcnc_emc_status_probe` and `linuxcnc_interp_init_harness` guard the inch/mm boundary. |
|
|
| 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. |
|
|
| Kinematics component lifecycle | Kinematics modules are initialized through LinuxCNC module entry points where native runtime probes exist, while HAL component init/ready/exit, HAL pin allocation, and RTAPI module metadata are handled by standalone shims. |
|
|
| Go math C/C++ linkage | `genserkins` runtime probing compiles vendored `gomath.c` through a narrow C++ wrapper so LinuxCNC `genserfuncs.c` can link to the upstream Go math symbols without editing vendored source. |
|
|
| Switchkins iterative forward | `genhexkins` runtime probing follows LinuxCNC switchkins iterative-forward behavior, including the first-call warmup path before asserting roundtrip convergence. |
|
|
| Browser storage | OPFS remains outside the native core; `runtime/opfs/file-service.js` owns browser text-file persistence, `runtime/opfs/path-model.js` owns host-side storage paths for INI, tool table, parameter, G-code, preview-cache, and session-snapshot content, `runtime/opfs/snapshot-store.js` owns generic JSON session snapshot persistence, `runtime/opfs/machine-file-store.js` owns pure-text machine-file and G-code persistence, `runtime/opfs/linuxcnc-parameter-bridge.js` only copies parameter files between OPFS text storage and the LinuxCNC-backed WASM parameter-file ABI, `runtime/opfs/linuxcnc-tool-table-bridge.js` only copies tool tables between OPFS text storage and the LinuxCNC-backed WASM tool-table ABI, and `runtime/opfs/linuxcnc-machine-session-bridge.js` groups INI, parameter, and tool-table loading while using the LinuxCNC-backed INI SDK for `[EMCIO]RANDOM_TOOLCHANGER`, `[RS274NGC]PARAMETER_FILE`, and `[EMCIO]TOOL_TABLE` when available; explicit host session file-name options take precedence over INI-derived file names, missing INI file-name values fall back to host default parameter/tool-table paths, and path validation remains owned by the OPFS path model, including rejection of traversal or nested path segments from INI-derived file names. |
|
|
|
|
## 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::...` member definitions outside the
|
|
documented Python/remap runtime-edge stubs.
|
|
- 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/full-core WASM parity tests yet. The INI parser now has Node and
|
|
Chromium smoke harnesses against vendored LinuxCNC `inifile.cc`.
|
|
- JS SDK validation now covers the INI WASM wrapper around vendored LinuxCNC
|
|
`inifile.cc`, including LinuxCNC boolean conversion and INI-declared
|
|
parameter/tool-table file-name lookup, and the interpreter-core SDK wrapper
|
|
around the existing exported C ABI. The interpreter SDK only manages strings,
|
|
Emscripten file writes, and calls into vendored LinuxCNC execution paths,
|
|
including parameter-file restore/save and tool-table load/save.
|
|
- OPFS validation covers a Node mock of the file-service adapter, the
|
|
host-side path model, generic session snapshot storage, pure-text machine
|
|
file and G-code storage, parameter/tool-table bridge copying into the
|
|
interpreter SDK filesystem, grouped machine-session loading, explicit
|
|
session file-name overrides, default host path fallback when INI file names
|
|
are absent, invalid INI-derived machine file names, generic session snapshot
|
|
custom filenames plus envelope/path rejection paths, G-code program filename
|
|
rejection paths, and a Chromium localhost round trip for those persistence
|
|
paths.
|
|
- Host-side smoke validation is aggregated by
|
|
`tests/host/verify_host_smokes.sh` so Node, WASM, OPFS, and browser checks
|
|
run from one command.
|
|
- Identity/trivial, `5axiskins`, TRT `xyzac`/`xyzbc`, delta, SCARA, PUMA,
|
|
serial, hexapod, pentapod, and related kinematics sources now have native
|
|
source-probe coverage.
|
|
- Full machine baselines beyond the current identity/trivial, `5axiskins`,
|
|
TRT, delta, SCARA, PUMA, serial `genserkins`, hexapod `genhexkins`,
|
|
pentapod `pentakins`, and other existing runtime probes are not established.
|
|
- Positive cutter-compensated motion and cutter compensation rejection paths
|
|
now have standalone interpreter fixture coverage through vendored LinuxCNC
|
|
source.
|
|
- Fixture expectations are checked against the standalone vendored source
|
|
path. The upstream `rs274` side-by-side baseline now covers simple motion,
|
|
arc geometry, offsets, feed-control, comment/logging, numbered-parameter,
|
|
probing, spindle-orient, file-open reset, file-finish, tool-reload, and
|
|
tool select/change/length-offset, canned-cycle, state-tag motion, tool-table
|
|
setup, and O-word subroutine fixtures; it also covers threading/rigid tap,
|
|
NURBS dispatch boundaries, and comparable canonical runtime edge and
|
|
program-end cleanup calls.
|
|
Adapter-heavy fixtures, standalone modal-state assertions, and upstream
|
|
`rs274` output gaps such as `WAIT` or hidden NURBS control-point detail still
|
|
need dedicated native LinuxCNC baselines.
|
|
- `canned_cycles` is now in the upstream `rs274` side-by-side baseline after
|
|
the minimal interpreter harness was aligned with LinuxCNC `Interp::init()`
|
|
default `G73/G83` peck-clearance values for millimeter units.
|
|
- `tool_table_setup` is now in the upstream `rs274` side-by-side baseline using
|
|
a dedicated `rs274 -t` tool table and `-i` millimeter-unit INI boundary.
|
|
- `tool_semantics` now compares its T/M6/G43/G49 canonical subset with
|
|
upstream `rs274 -t -i`; M61 current-pocket host-state behavior remains a
|
|
standalone fixture expectation.
|
|
|
|
## 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.
|