100 lines
5.6 KiB
Markdown
100 lines
5.6 KiB
Markdown
# LinuxCNC tooldata source map
|
|
|
|
This map records the source basis and boundaries for LinuxCNC tooldata coverage
|
|
in native, source-link, switchkins, and WASM-safe build paths. It is a
|
|
source-link/shim guard only; it must not add CNC behavior and must not expand the temporary smoke parser.
|
|
|
|
## LinuxCNC Source Basis
|
|
|
|
- `src/emc/tooldata/Submakefile` selects `tooldata_mmap.cc` or
|
|
`tooldata_nml.cc`, and always includes `tooldata_common.cc`,
|
|
`tooldata_db.cc`, and `tool_watch.cc`.
|
|
- `src/emc/tooldata/tooldata_common.cc` provides tool table parsing,
|
|
formatting, load/save, and database-mode entry points.
|
|
- `src/emc/tooldata/tooldata_mmap.cc` provides native mmap tool table storage.
|
|
- `src/emc/tooldata/tooldata_nml.cc` provides the NML tool table registration
|
|
backend selected by `TOOL_NML_FLAG`.
|
|
- `src/emc/tooldata/tooldata_db.cc` provides external database entry points.
|
|
- `src/emc/tooldata/tooldata_db.cc` returns `-1` from
|
|
`tooldata_db_getall()` when the external DB is not live, and returns `0`
|
|
from `tooldata_db_notify()` without side effects in that same state.
|
|
- `src/emc/tooldata/tool_mmap_read.cc` is the mmap tool table reader utility
|
|
source from the same LinuxCNC tooldata build metadata; it reads through
|
|
`tool_mmap_user()`, `tooldata_last_index_get()`, and `tooldata_get()`.
|
|
- `src/emc/tooldata/tool_watch.cc` is the NML/mmap tool table watcher utility
|
|
source from the same LinuxCNC tooldata build metadata; it reads
|
|
`EMC_STAT::io.tool` fields through `RCS_STAT_CHANNEL`.
|
|
- `src/emc/tooldata/tooldata.hh` declares the tooldata API used by RS274 and
|
|
WASM-safe shims.
|
|
|
|
## Manifest And Shim Coverage
|
|
|
|
| Coverage | Boundary |
|
|
| --- | --- |
|
|
| `linuxcnc-rs274-source-files.txt` | Tracks the full LinuxCNC `src/emc/tooldata` source directory and `tooldata.hh`. |
|
|
| `linuxcnc-rs274-wasm-source-files.txt` | Links `tooldata_common.cc`, blocks native `tooldata_mmap.cc`, and records runtime shim source bases for `tooldata_db.cc` and `tooldata_nml.cc`. |
|
|
| `linuxcnc-kinematics-source-files.txt` | Tracks 10 LinuxCNC `TOOL_TABLE` files referenced by covered M428/M429/M430 INI sources as `tooldata` source coverage only. |
|
|
| `core/wasm_shims/tooldata/tooldata_mmap_backend.cc` | Adapts LinuxCNC `tooldata_mmap.cc` exports to WASM-safe in-memory storage. |
|
|
| `core/wasm_shims/tooldata/tooldata_runtime_stubs.cc` | Adapts LinuxCNC `tooldata_nml.cc` and `tooldata_db.cc` runtime entry points without native services. |
|
|
| `test-linuxcnc-wasm-tooldata-link.sh` | Links the wasm-safe tooldata shim against LinuxCNC tooldata runtime expectations. |
|
|
| `test-linuxcnc-wasm-tooldata-common-link.sh` | Links LinuxCNC `tooldata_common.cc` through the wasm-safe standalone probe. |
|
|
| `test-linuxcnc-wasm-tooldata-mmap-symbols.sh` | Compares wasm mmap backend exports with LinuxCNC `tooldata_mmap.cc`. |
|
|
| `test-linuxcnc-wasm-tooldata-runtime-symbols.sh` | Compares runtime stub exports with LinuxCNC `tooldata_db.cc` and `tooldata_nml.cc`. |
|
|
|
|
## External DB Stub Boundaries
|
|
|
|
- `core/wasm_shims/tooldata/tooldata_runtime_stubs.cc` must keep external DB services unavailable for browser-safe probes; it must not fork, exec, poll,
|
|
or keep a live external database process.
|
|
- `tooldata_db_init()` must preserve the LinuxCNC `MAX_DB_PROGRAM_ARGS=10`, `strtok_r()` argument splitting, and `access(..., X_OK)` rejection edges from
|
|
`src/emc/tooldata/tooldata_db.cc` before returning `-1`.
|
|
- `tooldata_db_getall()` must return `-1` while `db_live` is false, and
|
|
`tooldata_db_notify()` must return `0` without side effects while `db_live`
|
|
is false.
|
|
|
|
## Mmap Backend Boundaries
|
|
|
|
- `core/wasm_shims/tooldata/tooldata_mmap_backend.cc` must preserve the
|
|
LinuxCNC `tooldata_mmap.cc` export surface for the mmap creator/user/close lifecycle while using an in-memory replacement for native mmap.
|
|
- The mmap backend must keep the LinuxCNC random-toolchanger flag and
|
|
`last_index` initialization edges from `tool_mmap_creator()`, and
|
|
`tooldata_last_index_get()` must preserve the last-index unavailable return.
|
|
- The mmap backend must keep LinuxCNC's single-creator process boundary from
|
|
the `static inited` guard in `tool_mmap_creator()`, including after
|
|
`tool_mmap_close()` clears browser-safe in-memory state.
|
|
- `tool_mmap_user()` must keep LinuxCNC's unavailable mmap failure boundary,
|
|
and `tool_mmap_close()` must clear the browser-safe in-memory state without
|
|
adding filesystem mmap behavior.
|
|
|
|
## Boundaries
|
|
|
|
- Tool table files referenced by switchkins INI files are source coverage only;
|
|
they must not become browser API fields or generated switchkins aliases.
|
|
- WASM-safe tooldata shims must preserve the LinuxCNC export surface checked by
|
|
symbol probes.
|
|
- WASM-safe tooldata runtime stubs must keep external database services
|
|
unavailable while preserving LinuxCNC inactive-DB return values.
|
|
- Native and source-link paths must keep the full LinuxCNC `src/emc/tooldata`
|
|
source directory tracked in the native RS274 manifest.
|
|
- `build-wasm.sh` must run tooldata link and symbol probes before copying
|
|
browser artifacts.
|
|
- `test-native.sh`, `test-linuxcnc-source-link.sh`, and `build-wasm.sh` must
|
|
run `./check-linuxcnc-tooldata-source-map.sh` before consuming tooldata-backed
|
|
native objects, source-linked LinuxCNC objects, or browser artifacts.
|
|
- The tooldata source-map guard validates LinuxCNC source/shim ownership and
|
|
manifest drift only; it does not interpret G-code.
|
|
|
|
## Checks
|
|
|
|
Run:
|
|
|
|
```bash
|
|
./check-linuxcnc-tooldata-source-map.sh
|
|
./test-native.sh
|
|
./test-linuxcnc-source-link.sh
|
|
./build-wasm.sh
|
|
```
|
|
|
|
`check-linuxcnc-tooldata-source-map.sh` keeps this document, LinuxCNC tooldata
|
|
source anchors, manifest coverage, WASM shim/probe boundaries, and switchkins
|
|
TOOL_TABLE source-only policy synchronized.
|