102 lines
7.6 KiB
Markdown
102 lines
7.6 KiB
Markdown
# LinuxCNC WASM shims source map
|
|
|
|
This map records the source basis for the C++ sources in the
|
|
CMake `linuxcnc_wasm_safe_probe_shims` set. It is a build/source-link guard
|
|
only; it must not add CNC behavior and must not expand the temporary smoke parser.
|
|
|
|
## Generated Coverage
|
|
|
|
| Output | Count | Source coverage role |
|
|
| --- | ---: | --- |
|
|
| CMake `linuxcnc_wasm_safe_probe_shims` sources | 11 | Browser-safe LinuxCNC adaptation shims linked into WASM source probes. |
|
|
|
|
## Shim Map
|
|
|
|
| Shim | LinuxCNC source basis | Boundary |
|
|
| --- | --- | --- |
|
|
| `core/wasm_shims/dlfcn.cc` | `src/emc/rs274ngc/interp_base.cc` | Satisfies LinuxCNC `interp_base.cc` dynamic loader calls and RTLD flags for browser-safe probes while keeping dynamic loading unavailable. |
|
|
| `core/wasm_shims/emc_status_shim.cc` | `src/emc/sai/dummyemcstat.cc` | Provides the detached LinuxCNC `EMC_STAT` singleton shape without task/NML startup. |
|
|
| `core/wasm_shims/gettext_shim.cc` | `src/emc/rs274ngc/interp_internal.hh` | Preserves LinuxCNC `_()` diagnostic call sites by satisfying `gettext()` while leaving browser gettext catalogs unavailable. |
|
|
| `core/wasm_shims/linuxcnc_runtime_shim.cc` | `src/emc/rs274ngc/gcodemodule.cc`, `src/emc/task/emctaskmain.cc`, `src/emc/task/taskclass.cc`, `src/emc/rs274ngc/interp_namedparams.cc`, `include/hal.h`, `src/hal/hal_lib.c`, `src/emc/rs274ngc/rs274ngc_pre.cc` | Keeps preview/task, builtin module stubs, unavailable HAL lookup, and `wordexp()` edges compile-safe. |
|
|
| `core/wasm_shims/nml_status_shim.cc` | `src/libnml/nml/nmlmsg.cc`, `src/libnml/nml/stat_msg.cc` | Provides LinuxCNC NML status constructors, clear behavior, and `RCS_STAT_MSG` default status fields needed by source-linked EMC status objects. |
|
|
| `core/wasm_shims/python_c_api_shim.cc` | `src/emc/rs274ngc/interp_python.cc`, `src/emc/rs274ngc/interp_namedparams.cc`, `src/emc/rs274ngc/gcodemodule.cc`, `src/emc/pythonplugin/python_plugin.cc` | Satisfies Python C API symbols while Python/Boost.Python remap paths remain tracked blockers. |
|
|
| `core/wasm_shims/rcs_print_shim.cc` | `src/libnml/rcs/rcs_print.cc`, `src/libnml/rcs/rcs_print.hh` | Provides the LinuxCNC `rcs_print_error` split entry points used by NML validation without native print routing. |
|
|
| `core/wasm_shims/rtapi_compat.cc` | `src/rtapi/uspace_common.h`, `src/rtapi/rtapi.h` | Provides LinuxCNC userspace `rtapi_snprintf()` formatting by following the `rtapi.h` declaration and `uspace_common.h` `vsnprintf()` implementation path. |
|
|
| `core/wasm_shims/tooldata/tooldata_mmap_backend.cc` | `src/emc/tooldata/tooldata_mmap.cc` | Replaces native mmap storage with an in-memory WASM-safe backend for probes. |
|
|
| `core/wasm_shims/tooldata/tooldata_runtime_stubs.cc` | `src/emc/tooldata/tooldata_nml.cc`, `src/emc/tooldata/tooldata_db.cc` | Satisfies NML and external tool database entry points without native services, preserving inactive-DB return values. |
|
|
| `core/wasm_shims/pythonplugin/python_plugin.cc` | `src/emc/pythonplugin/python_plugin.cc`, `src/emc/pythonplugin/python_plugin.hh`, `src/emc/ini/inifile.cc` | Keeps LinuxCNC PythonPlugin API and negative-status short-circuit behavior available while Python execution is disabled for browser-safe probes. |
|
|
|
|
## Runtime Shim Boundaries
|
|
|
|
- `core/wasm_shims/dlfcn.cc` and `core/wasm_shims/dlfcn.h` cover the
|
|
LinuxCNC `interp_base.cc` dynamic loader calls to `dlopen()`, `dlsym()`,
|
|
`dlerror()`, `RTLD_GLOBAL`, and `RTLD_NOW`; their unavailable-loader returns
|
|
must keep handles and symbols null, keep `dlerror()` diagnostic text stable,
|
|
and leave `dlclose()` side-effect free.
|
|
- `core/wasm_shims/emc_status_shim.cc` must stay limited to the detached
|
|
LinuxCNC `EMC_STAT` singleton from `src/emc/sai/dummyemcstat.cc`; it must not
|
|
pull in task startup, NML channels, or operator callback behavior.
|
|
- `core/wasm_shims/linuxcnc_runtime_shim.cc` must keep preview `_task=0`,
|
|
matching `src/emc/rs274ngc/gcodemodule.cc`; it must not switch browser-safe probes into task mode.
|
|
- The runtime shim's builtin module stubs must match LinuxCNC's
|
|
`interpreter`/`emccanon` inittab shape from `gcodemodule.cc` and
|
|
`taskclass.cc` while returning null module pointers; they must not become
|
|
Python execution.
|
|
- The HAL lookup shim covers `hal_get_pin_value_by_name()`,
|
|
`hal_get_signal_value_by_name()`, and `hal_get_param_value_by_name()` from
|
|
`src/emc/rs274ngc/interp_namedparams.cc`, `include/hal.h`, and
|
|
`src/hal/hal_lib.c`; it must leave HAL values unavailable by returning `-1`,
|
|
`HAL_TYPE_UNINITIALIZED`, and null data pointers.
|
|
- `wordexp()` support is limited to the single-word `wordexp()` path expansion
|
|
and `wordfree()` cleanup needed by `src/emc/rs274ngc/rs274ngc_pre.cc` for
|
|
basename, program prefix, and subroutine-directory lookups; it must not become a shell expansion feature.
|
|
|
|
## Python Shim Boundaries
|
|
|
|
- `core/wasm_shims/python_c_api_shim.cc` satisfies Python C API symbols used by
|
|
LinuxCNC RS274/remap sources; it must not become Python execution.
|
|
- The Python C API shim must return inert objects, null exceptions, false
|
|
callable/type checks, and successful module/type registration statuses only
|
|
to satisfy LinuxCNC `interp_python.cc`, `gcodemodule.cc`, and
|
|
`python_plugin.cc` link expectations; it must not call into CPython runtime.
|
|
- `core/wasm_shims/pythonplugin/python_plugin.cc` must preserve LinuxCNC
|
|
`PythonPlugin` status edges for `PLUGIN_NO_SECTION`, `PLUGIN_BAD_INIFILE`,
|
|
`PLUGIN_BAD_PATH`, `PLUGIN_INITTAB_FAILED`,
|
|
`PLUGIN_PYTHON_NOT_INITIALIZED`, `PLUGIN_NO_CALLABLE`, and
|
|
`PLUGIN_EXCEPTION` while keeping Python execution disabled.
|
|
- The PythonPlugin shim must preserve the first-caller `_inittab` `PLUGIN_INITTAB_FAILED` edge from `src/emc/pythonplugin/python_plugin.cc` when a built-in module init function fails, while keeping browser-safe probes detached from real Python module execution.
|
|
- The PythonPlugin shim must preserve the `TOPLEVEL` missing-path `PLUGIN_BAD_PATH` edge from `src/emc/pythonplugin/python_plugin.cc` before reporting the browser-safe disabled Python runtime status.
|
|
- The PythonPlugin shim must preserve `PATH_PREPEND` and `PATH_APPEND` tilde-expansion failure statuses from `src/emc/pythonplugin/python_plugin.cc` and `src/emc/ini/inifile.cc` without executing Python path mutation in browser-safe probes.
|
|
- The PythonPlugin shim must not execute `bp::exec`, `bp::exec_file`, or real
|
|
Python callable dispatch; `PyObject_Call` is an inert C API symbol only.
|
|
Browser Python execution remains blocked until implemented as a source-backed
|
|
browser-safe LinuxCNC adaptation.
|
|
|
|
## Boundaries
|
|
|
|
- The CMake `linuxcnc_wasm_safe_probe_shims` set and `list-linuxcnc-wasm-safe-shims.sh` must stay synchronized.
|
|
- Each shim source must keep a nearby `LinuxCNC source basis:` comment naming the LinuxCNC source it adapts.
|
|
- Every LinuxCNC source named above must remain tracked in the RS274/WASM manifest as `core`, `header`, or `metadata`.
|
|
- These shims are browser-safe LinuxCNC adaptations for source-link probes; they are not new interpreter behavior.
|
|
- `test-native.sh`, `test-linuxcnc-source-link.sh`, and `build-wasm.sh` must
|
|
run `./check-linuxcnc-wasm-shims-source-map.sh` before consuming shim-backed
|
|
source-linked LinuxCNC objects or browser artifacts.
|
|
- The WASM shims source-map guard validates LinuxCNC source/shim ownership and
|
|
manifest drift only; it does not interpret G-code.
|
|
|
|
## Checks
|
|
|
|
Run:
|
|
|
|
```bash
|
|
./check-linuxcnc-wasm-shims-source-map.sh
|
|
./test-linuxcnc-wasm-cmake-safe-probe.sh
|
|
./test-native.sh
|
|
./test-linuxcnc-source-link.sh
|
|
./build-wasm.sh
|
|
```
|
|
|
|
`check-linuxcnc-wasm-shims-source-map.sh` keeps this document, the CMake shim
|
|
set, `list-linuxcnc-wasm-safe-shims.sh`, LinuxCNC source anchors, and the
|
|
RS274/WASM manifest synchronized.
|