wasm-simulator/docs/linuxcnc-wasm-shims-source-map.md

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	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_PYTHON_NOT_INITIALIZED, PLUGIN_NO_CALLABLE, and PLUGIN_EXCEPTION while keeping Python execution disabled.
• The PythonPlugin shim must not execute bp::exec, bp::exec_file, or PyObject_Call; those remain browser blockers 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:

./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.