wasm-simulator/docs/linuxcnc-porting.md

# LinuxCNC to WASM porting steps

This file defines the incremental path for replacing the temporary smoke parser with the LinuxCNC interpreter.

## Step 0: Stable simulator ABI

Status: done.

The browser calls only `cnc_sim_*` functions from `core/include/cnc_sim_api.h`. This ABI remains stable while the backend changes.

Test:

```bash
g++ -std=c++17 -I core/include core/src/cnc_sim_api.cpp core/tests/cnc_sim_api_smoke.cpp -o ./cnc_sim_api_smoke
./cnc_sim_api_smoke
```

## Step 1: Temporary event parser

Status: in progress.

This parser only exists to test the ABI and UI before Emscripten and LinuxCNC are wired in. It is not a production feature implementation. Do not extend it with independently designed G-code behavior; when a behavior needs to change, first locate the LinuxCNC source implementation and either route to that source-backed backend or port the corresponding source logic. It currently handles:

- multiple G/M words on one line
- `G0`, `G1`, `G2`, `G3`
- `G17`, `G18`, `G19`
- `G90.1`, `G91.1` arc IJK distance mode
- `G20`, `G21`, `G70`, `G71`
- `G7`, `G8` lathe diameter/radius mode for X-axis input
- `G90`, `G91`
- `G4 P...`
- `G38.2`, `G38.3`, `G38.4`, `G38.5`
- `F`, `S`, `T`, `M3`, `M4`, `M5`, `M6`, `M2`, `M30`
- spindle modes `G96`, `G97`
- IJK and R arcs
- numbered and named parameter assignment/reference such as `#1 = ...`, `#<name> = ...`, `X#1`, and nested expressions like `X[[#<name> + 2] * 3]`
- expression functions `ABS[]`, `SQRT[]`, `EXP[]`, `LN[]`, degree-based `SIN[]`/`COS[]`/`TAN[]`/`ASIN[]`/`ACOS[]`, LinuxCNC-style `ATAN[]/[]`, `FIX[]`/`FUP[]`/`ROUND[]`, and source-linked `mod`/`**`/logical/relational operator precedence
- numeric and named O-word subprograms such as `O100 call` and `O<name> call`
- canned cycles `G73`, `G74`, `G81`, `G82`, `G83`, `G84`, `G85`, `G86`, `G87`, `G88`, `G89` with `G80`, `G98`, `G99`, `L`
- coordinate offset events for `G10 L2`, `G10 L20`, `G54`-`G59.3`, `G52`, `G92`, `G92.1`, `G92.2`, and `G92.3`

It is not the production interpreter. Any remaining smoke-only behavior is technical debt to replace with LinuxCNC source-backed code.

## Step 2: Canon event sink

Status: started.

Create a C++ file that implements the Canon functions declared by LinuxCNC `src/emc/nml_intf/canon.hh`.

High-priority callbacks:

- `INIT_CANON`
- `USE_LENGTH_UNITS`
- `SELECT_PLANE`
- `SET_FEED_RATE`
- `SET_SPINDLE_SPEED`
- `SELECT_TOOL`
- `CHANGE_TOOL`
- `STRAIGHT_TRAVERSE`
- `STRAIGHT_FEED`
- `ARC_FEED`
- `DWELL`
- `PROGRAM_END`
- `FINISH`

The sink will translate these callbacks to `CncSimEvent`.

Current bridge files:

- `core/src/canon_event_sink.h`
- `core/src/canon_event_sink.cpp`
- `core/src/linuxcnc_canon_bridge.h`
- `core/src/linuxcnc_canon_bridge.cpp`

The LinuxCNC bridge is optional and not built by default:

```bash
cmake -S core -B build/native-linuxcnc \
  -DCNC_SIM_ENABLE_LINUXCNC_BRIDGE=ON \
  -DCNC_SIM_LINUXCNC_ROOT=/path/to/linuxcnc
```

This bridge is intentionally thin. The production parser still needs the `rs274ngc` interpreter linked on top of it.

Bridge smoke test:

```bash
./test-linuxcnc-bridge-native.sh
```

Set `LINUXCNC_ROOT=/path/to/linuxcnc` if the LinuxCNC source tree is not next to `wasm-simulator`.

## Step 3a: Native `librs274` runner

Status: started.

Before porting `rs274ngc` sources to wasm, use the already-built native LinuxCNC `librs274` to validate the bridge and event schema:

```bash
./test-linuxcnc-rs274-native.sh
```

This builds `core/tools/linuxcnc_rs274_dump.cpp`, links LinuxCNC `librs274`, and writes:

- run-local output files under a per-run temporary `build_dir/outputs/`
- example files: `cnc_sim_linuxcnc_basic_motion.json`, `cnc_sim_linuxcnc_basic_mill.json`

This is a native-only stepping stone. Once stable, the same event sink is used by the wasm build.

`T... M6` now works in the native runner after initializing LinuxCNC mmap tooldata with a minimal tool table.

## Step 3b: API-level native `librs274` backend

Status: started.

The public `cnc_sim_api` defaults to the LinuxCNC RS274 backend and can still select backends through config JSON:

```json
{"backend":"linuxcnc-rs274"}
```

API-level native smoke:

```bash
./test-linuxcnc-api-native.sh
```

## Step 4a: Source compilation map

Status: started.

Before replacing `librs274` with source-level compilation, keep the source manifest and syntax probe green:

```bash
./test-linuxcnc-source-syntax.sh
./test-linuxcnc-source-objects.sh
```

The manifest is:

- `linuxcnc-rs274-source-files.txt`
- `docs/linuxcnc-rs274-source-map.md`

The first compile condition discovered is that LinuxCNC user-space source probes need `-DULAPI`.

## Step 3: Native LinuxCNC interpreter comparison

Build a native adapter that links:

- `src/emc/rs274ngc`
- `src/emc/nml_intf`
- the Canon event sink

Then run the same G-code corpus through both the temporary parser and LinuxCNC-backed parser. Numeric differences are expected around arc canonicalization; they must be recorded and bounded.

## Step 4: Remove browser-hostile dependencies

LinuxCNC interpreter sources currently involve Python/Boost.Python remap paths. For the first WASM target:

- disable Python remap
- disable dynamic module loading
- route LinuxCNC parameter-file reads and writes through an OPFS-backed wasm
  workspace, preserving `rs274ngc.var` and `.bak` persistence in browser runs
  as defined by `src/emc/rs274ngc/interp_internal.hh` and exercised by
  `Interp::restore_parameters`/`Interp::save_parameters` in
  `src/emc/rs274ngc/rs274ngc_pre.cc`
- provide browser-safe tool table and INI/config loading through JSON or
  OPFS-backed files

## Step 5: Emscripten build

Generate:

- `web/public/cnc_sim.js`
- `web/public/cnc_sim.wasm`

Command:

```bash
./build-wasm.sh
```

## Step 6: Controller dialects

Fanuc and Siemens support should remain outside the LinuxCNC core as preprocessors/adapters. They normalize controller-specific constructs into the internal event/interpreter input layer.

## Functional parity matrix

This matrix tracks LinuxCNC feature coverage for the web/WASM simulator. A feature is not considered covered until it has a native regression in at least the `librs274` runner and the source-link runner.

| Area | Status | Regression |
| --- | --- | --- |
| Basic modal motion `G0/G1/G2/G3` | covered, including `G18`/`G19` arc plane mapping and `G90.1`/`G91.1` IJK modes | `tests/gcode/linuxcnc_basic_motion.ngc`, `tests/gcode/basic_mill.ngc`, `tests/gcode/linuxcnc_arc_planes.ngc`, `tests/gcode/linuxcnc_arc_distance_modes.ngc` |
| Predefined position moves `G28/G28.1`, `G30/G30.1` | covered for stored position, waypoint, selected-axis return, and all-axis return | `tests/gcode/linuxcnc_predefined_positions.ngc` |
| Machine-coordinate move `G53` | covered for explicit/modal `G0`, `G1`, and incremental-mode rejection in smoke parser | `tests/gcode/linuxcnc_machine_coordinates.ngc` |
| Tool select/change `T... M6` | covered with minimal native tooldata | `tests/gcode/basic_mill.ngc` |
| Tool length offset `G43/G43.1/G43.2/G49` | covered with nonzero tool-table offset, dynamic replacement, additive axis offsets, `G43.2 H...`, and clear through LinuxCNC native/source backends | `tests/gcode/linuxcnc_tool_length.ngc`, `tests/gcode/linuxcnc_dynamic_tool_length.ngc` |
| RTCP controls `G43.4/G43.5/G49` | covered as simulator-owned control lines | `tests/gcode/linuxcnc_rtcp_controls.ngc` |
| Kinematics switch `M428/M429/M430` | covered as simulator-owned control lines | `tests/gcode/linuxcnc_rtcp_controls.ngc` |
| Spindle, coolant, program stops, and current tool number `M3/M4/M5`, `M7/M8/M9`, `M0/M1/M60/M30`, `M61 Q...` | covered through LinuxCNC native/source backends | `tests/gcode/linuxcnc_spindle_direction.ngc`, `tests/gcode/linuxcnc_coolant.ngc`, `tests/gcode/linuxcnc_program_stops.ngc`, `tests/gcode/linuxcnc_tool_number.ngc` |
| Spindle speed mode `G96/G97` | covered with Canon `SET_SPINDLE_MODE` preserved as mode state events, including `G96 D...` max-RPM value | `tests/gcode/linuxcnc_spindle_modes.ngc` |
| Spindle orientation `M19 R... P... Q...` | covered with Canon `ORIENT_SPINDLE` and `WAIT_SPINDLE_ORIENT_COMPLETE` preserved as temporary mode state events | `tests/gcode/linuxcnc_spindle_orient.ngc` |
| Spindle-synchronized feed and threading `G33/G33.1/G76` | covered through smoke, LinuxCNC native, and source-linked paths with Canon `START_SPEED_FEED_SYNCH`/`STOP_SPEED_FEED_SYNCH` preserved, rigid-tap line numbers normalized, and G76 multi-pass threading smoke-covered | `tests/gcode/linuxcnc_threading_sync.ngc`, `tests/gcode/linuxcnc_threading_cycle.ngc`, smoke API regression |
| Lathe diameter/radius mode `G7/G8` | covered through LinuxCNC native/source backends for same-block X scaling, `G76` I/J/K threading geometry interaction, and `#<_lathe_diameter_mode>`/`#<_lathe_radius_mode>` readonly named-parameter state | `tests/gcode/linuxcnc_lathe_diameter_mode.ngc`, `tests/gcode/linuxcnc_lathe_diameter_g76.ngc` |
| Digital/analog I/O `M62`-`M68` | covered with Canon digital output, analog output, and input wait callbacks preserved as temporary state events | `tests/gcode/linuxcnc_io_controls.ngc` |
| Override controls `M48`-`M53` | covered with Canon feed override, spindle speed override, adaptive feed, and feed hold callbacks preserved as temporary state events | `tests/gcode/linuxcnc_override_controls.ngc` |
| Modal state save/restore `M70`-`M73` | covered for main-program save/invalidate/restore plus O-word subroutine autorestore in smoke parser, with native/source regressions checking restored distance mode, units, and XY plane motion | `tests/gcode/linuxcnc_modal_state.ngc`, `tests/gcode/linuxcnc_modal_autorestore.ngc` |
| LinuxCNC read-only named parameters | common modal/unit/feed/spindle reads are covered through LinuxCNC native/source backends, with additional ccomp/spindle-mode readonly reads source-linked | `tests/gcode/linuxcnc_readonly_named_parameters.ngc`, `tests/gcode/linuxcnc_readonly_named_parameters_extra.ngc`, `tests/gcode/linuxcnc_lathe_diameter_mode.ngc` |
| Feed and motion control modes `G93/G94/G95`, `G61/G61.1/G64` | covered through LinuxCNC native/source backends | `tests/gcode/linuxcnc_feed_modes.ngc`, `tests/gcode/linuxcnc_motion_modes.ngc` |
| Canned cycle `G81/G80` | covered for drilling expand-to-canon path, including `G18/G19` plane-specific depth-axis mapping for representative drilling/boring cycles | `tests/gcode/linuxcnc_canned_cycle.ngc`, `tests/gcode/linuxcnc_canned_cycle_planes.ngc` |
| Coordinate offset Canon events `G10 L2`, `G10 L20`, `G10 P0 active-system targeting`, `G54`-`G59.3` selection, `G52`, `G92/G92.1/G92.2/G92.3` | covered through LinuxCNC native/source backends, including all nine G5X indices | `tests/gcode/linuxcnc_coordinate_offsets.ngc`, `tests/gcode/linuxcnc_coordinate_l20.ngc`, `tests/gcode/linuxcnc_coordinate_p0.ngc`, `tests/gcode/linuxcnc_coordinate_select_all.ngc`, `tests/gcode/linuxcnc_g92_restore.ngc`, `tests/gcode/linuxcnc_g52_offset.ngc` |
| Cutter compensation | covered for tool-table `G41/G42 D...` and explicit-radius `G41.1/G42.1/G40` through LinuxCNC native/source backends | `tests/gcode/linuxcnc_cutter_comp.ngc` |
| Probe moves `G38.2/G38.3/G38.4/G38.5` | covered as distinct probe events with LinuxCNC `probe_type` preserved through smoke, native, and source-linked paths | `tests/gcode/linuxcnc_probe_no_error.ngc` |
| O-word subroutines, calls, and control flow | covered for numeric and named `O... sub/call/return/endsub` plus `if`/`elseif`/`else`, `while`, `repeat`, `do`/`while`, `break`, and `continue` through LinuxCNC file mode; smoke parser also covers named `O<name>` sub/call/return/endsub and loop-control forms | `tests/gcode/smoke_oword_subprogram.ngc`, `tests/gcode/linuxcnc_named_oword_subprogram.ngc`, `tests/gcode/linuxcnc_oword_control_flow.ngc` |
| Parameter expressions and operators | covered for parameter references, source-linked `mod`, `**`, logical, and relational operator precedence, plus LinuxCNC divide-by-zero, negative-power, malformed `ATAN[]/[]`, and unary operation error paths from `interp_read.cc`/`interp_execute.cc` | `tests/gcode/linuxcnc_parameter_expression_assignment.ngc`, `tests/gcode/linuxcnc_expression_operators.ngc`, `tests/gcode/linuxcnc_divide_by_zero_error.ngc`, `tests/gcode/linuxcnc_negative_power_error.ngc`, `tests/gcode/linuxcnc_atan_missing_slash_error.ngc`, `tests/gcode/linuxcnc_atan_missing_bracket_error.ngc`, `tests/gcode/linuxcnc_unary_missing_bracket_error.ngc`, `tests/gcode/linuxcnc_unary_unknown_word_error.ngc` |
| Broader canned cycles `G73`, `G74`, `G82`-`G89` | partially covered: `G73`, `G74`, `G82`, `G83`, `G84`, `G85`, `G86`, `G87`, `G88`, `G89`; smoke parser maps supported cycles across `G17/G18/G19`, including LinuxCNC's special non-XY `G74/G84` tapping argument order and `G87` plane-specific `I/J/K` mapping; native/source regressions now check non-XY `G74/G84/G86/G87/G88` sequences | `tests/gcode/linuxcnc_canned_cycles_extended.ngc`, `tests/gcode/linuxcnc_canned_cycle_planes.ngc`, smoke API regression |
| Full source-level wasm build | covered for the current wasm-safe RS274 source set, with remaining work focused on broadening browser-hostile dependency replacement and feature coverage | `./build-wasm.sh`, `test-linuxcnc-wasm-runtime-link.sh`, `test-web-wasm-node-smoke.sh`, `test-web-wasm-browser-smoke.sh` |