122 lines
5.8 KiB
Markdown
122 lines
5.8 KiB
Markdown
# 27-04 HAL Component Precompile Runtime Gate 实施记录
|
||
|
||
## 定位
|
||
|
||
本文件落实 `ACC-039/INT-026`，承接 `24` 的阶段 B-D 和 `26` 的 P1 源码同步结果，把 `and2`、`or2`、`not`、`mux2`、`scale` 从“源码已同步”推进到 LinuxCNC `halcompile` 派生、预编译 manifest、WASM 实例化、线程回调、net 传播和代表 Web 配置消费均有机器 gate 的状态。
|
||
|
||
严格边界：本轮只晋级 Web/WASM 虚拟 HAL 仿真运行时。`dynamicLoadrtSupported=false`，未知组件必须 blocked；宿主 RTAPI 实时内核、共享内存、内核模块、硬件驱动和任意动态模块加载没有晋级。
|
||
|
||
## LinuxCNC 派生链
|
||
|
||
生成入口：
|
||
|
||
```text
|
||
wasm-port/tools/generate_hal_component_sources.sh
|
||
wasm-port/tools/generate_hal_component_sources.mjs
|
||
```
|
||
|
||
生成器固定为锁定源码树中的 `../linuxcnc/bin/halcompile --preprocess`。脚本校验 LinuxCNC HEAD 与 `tools/upstream-baseline.txt`，从五个 vendored `.comp` 生成 `build/generated/hal-components/*.c`，仅规范化生成时间行并附加最窄的 start/reset C ABI。`generation-report.json` 逐组件记录 source、generator、command fingerprint 和 generated SHA-256。
|
||
|
||
生成 C 不进入上游 vendor manifest，也不冒充 LinuxCNC 原始源码；其上游语义仍由 `26` 的 P0/P1 字节和固定哈希 gate 约束。
|
||
|
||
## 预编译 Manifest
|
||
|
||
新增 `wasm-port/runtime/manifests/hal_component_precompile_manifest.json`，固定：
|
||
|
||
- `upstreamCommit=60597ee0718873d2449058c824262a275e5e4bad`；
|
||
- allowlist 恰好为 `and2/or2/not/mux2/scale`；
|
||
- 每个组件的 `.comp` 路径、source SHA-256、generated path、factory/step symbol、pin 和 `count/names` 参数；
|
||
- `dynamicLoadrtSupported=false`；
|
||
- `unknownComponentPolicy=blocked`。
|
||
|
||
`verify_hal_component_precompile_manifest.mjs` 同时复算 source/generated hash，并将 manifest、generation report 和实际文件闭合。
|
||
|
||
## 真实执行链
|
||
|
||
`linuxcnc_hal_runtime.cpp` 现按以下路径执行 allowlist 组件：
|
||
|
||
```text
|
||
loadrt + names/count
|
||
-> allowlist/factory
|
||
-> halcompile 生成的 pin 与 hal_export_funct
|
||
-> addf 绑定 callback/instance
|
||
-> lchal_step_threads 调用生成公式
|
||
-> HAL_OUT 更新 signal
|
||
-> net 传播到下游 pin
|
||
```
|
||
|
||
运行时同时补齐：
|
||
|
||
- `names=` 与 `count=` 互斥和非法参数 blocked；
|
||
- 未知 `loadrt` 返回 blocked，不再只记成功事件；
|
||
- LinuxCNC HAL `net` 行的 `=>`、`<=`、`<=>` 方向标记解析；
|
||
- 同一 WASM 模块重新初始化 HAL session 时清空生成组件实例链；
|
||
- 保留 `trivkins` 既有 legacy boundary，避免回退既有 Task/Motion gate。
|
||
|
||
## 专项证据
|
||
|
||
```bash
|
||
cd wasm-port
|
||
./tools/build_task_hal_wasm.sh
|
||
node tests/wasm/node/verify_hal_component_precompile_manifest.mjs
|
||
node tests/wasm/node/verify_hal_component_truth_tables.mjs
|
||
node tests/wasm/node/verify_hal_component_thread_net_execution.mjs
|
||
```
|
||
|
||
实际输出：
|
||
|
||
```text
|
||
hal_component_generation=ok
|
||
linuxcnc_task_hal_wasm_build=ok
|
||
hal_component_precompile_manifest=ok
|
||
hal_component_truth_tables=ok
|
||
hal_component_thread_net_execution=ok
|
||
unknown_loadrt_component_blocked=ok
|
||
hal_component_session_reset=ok
|
||
```
|
||
|
||
truth-table gate 覆盖 `and2/or2` 各 4 组、`not` 2 组、`mux2` 两路选择和 `scale` 三组正负 gain/offset 浮点公式，输出 `build/evidence/hal-component-truth-table-evidence.json`。thread/net gate 证明生成函数真实执行、输出 signal 传播、非法参数阻断和第二 HAL session 重建。
|
||
|
||
## Web 代表配置消费
|
||
|
||
目标 Web 项目新增 `tests/node/verify_hal_component_runtime_evidence.mjs` 并挂入 `smoke:node`。gate 读取 vendored `xyzac-trt_cmds.hal` 中：
|
||
|
||
```text
|
||
loadrt mux2 names=J0_mux,J1_mux,J2_mux,J3_mux,J4_mux
|
||
loadrt scale names=rpm_rps
|
||
addf J0_mux servo-thread
|
||
addf rpm_rps servo-thread
|
||
```
|
||
|
||
随后用同一 task-HAL WASM 实例化并执行 `J0_mux` 和 `rpm_rps`，验证 `J0_mux.out=37.25`、`rpm_rps.out=20`，同时阻断 `web-local-formula` 未知组件。Web 项目没有复制五个组件公式。
|
||
|
||
## 回归结果
|
||
|
||
以下既有 gate 全部通过：
|
||
|
||
- `verify_hal_component_source_sync.sh`、`verify_vendor_sync.sh`；
|
||
- `verify_hal_runtime.sh`、`verify_task_hal_wasm.sh`；
|
||
- 目标 Web `smoke:node`；
|
||
- `verify_linuxcnc_task_hal_runtime.mjs`。
|
||
|
||
补充执行的 `build_native_probes.sh` 已通过。全量 `verify_native_probes.sh` 后续在组件范围外的 `xyzac_switchkins_test_3.ngc` 出现 Bus error；该 INI 引用锁定源码树中不存在的 `xyzac.var`，汇总产生 1 个 unexpected fail。本轮没有将其伪装为 expected-fail，因此不把全量 native 包列入上述通过清单。
|
||
|
||
后续状态：该历史失败已在 `ACC-045/INT-032` 中由当前 source/vendor 资产和串行全量复验解除。最终结果为 sim-config `159 total / 151 pass / 8 expected_fail / 0 unexpected_fail`、nc_files `107 total / 101 pass / 6 expected_fail / 0 unexpected_fail`，详见 `33-Native全量回归最终收口.md`。
|
||
|
||
系统 `/usr/bin/emcc` 与 `wasm-opt` 版本不匹配，因此 `wasm_incremental_build_lib.sh` 现优先加载仓库机器已有 EMSDK；最终构建使用 EMSDK 6.0.2 并通过。
|
||
|
||
## 04 状态
|
||
|
||
| 04 项 | 本轮后状态 |
|
||
| --- | --- |
|
||
| `4.7-4.11` | L3 条件通过：LinuxCNC 派生预编译 Web/WASM 仿真运行时、truth-table/formula、thread/net 和 Web 代表配置 gate 通过 |
|
||
| `4.16` | 条件通过/Blocked：allowlist `loadrt` 可实例化执行；未知组件和任意运行时动态模块加载仍 blocked |
|
||
|
||
## 下一步
|
||
|
||
优先落实 `23` 的 HAL Meter/Scope JSON evidence，或 `25` 的 host runtime evidence/release-promotion 分离 gate。不得从本轮组件仿真证据继承宿主 realtime 或 hardware promotion。
|
||
|
||
## 结论
|
||
|
||
`ACC-039/INT-026` 已闭合五个基础 HAL component 的 LinuxCNC 派生预编译运行时证据。04 的 `4.7-4.11` 可在 Web/WASM simulation 边界内晋级，`4.16` 仅对固定 allowlist 条件通过；动态模块加载仍不支持。
|