279 lines
12 KiB
Markdown
279 lines
12 KiB
Markdown
# 24-04 HAL Component Precompile Manifest / Truth-Table Gate 落地蓝图
|
||
|
||
> 后续状态：阶段 A 已由 `26` 完成，阶段 B-D 已由 `27` 完成。本文保留实施合同；涉及“当前缺失/只记录事件”的段落应结合 `27` 的最终机器 gate 阅读。
|
||
|
||
## 定位
|
||
|
||
本文件落实 `ACC-036/INT-023`：在 `19-04动态加载与预编译Manifest复核.md` 和 `21-04-HAL-Component-Precompile-Manifest实现缺口复核.md` 已确认边界和缺口后，把 `and2`、`or2`、`not`、`mux2`、`scale` 的源码同步、预编译 manifest、实例化、线程执行和 truth-table/formula evidence 收敛为可直接实施的合同。
|
||
|
||
覆盖 04 条目：
|
||
|
||
- `4.7 and2 组件`
|
||
- `4.8 or2 组件`
|
||
- `4.9 not 组件`
|
||
- `4.10 mux2 组件`
|
||
- `4.11 scale 组件`
|
||
- `4.16 loadrt 加载组件`
|
||
|
||
严格口径：不得在 JS/TS 或项目自有 C/C++ 中手写五个组件公式后宣称 LinuxCNC 源码复用。组件实现必须直接编译 LinuxCNC `.comp` 的生成物，或由可复现工具从 vendored `.comp` 生成最窄适配层；manifest、生成物和 WASM 必须绑定同一上游源码哈希。
|
||
|
||
## 本轮实物复核结论
|
||
|
||
| 检查项 | 当前事实 | 严格结论 |
|
||
| --- | --- | --- |
|
||
| 上游源码 | 五个 `.comp` 均存在于 `linuxcnc/src/hal/components/` | P0 来源已确定 |
|
||
| vendored 源码 | 五个 `.comp` 已抽取到 `wasm-port/vendor/linuxcnc/src/hal/components` | 专项 P1 同步已完成，见 `26` |
|
||
| source manifest | 两个 manifest 已登记五个 `.comp`，专项 commit/字节/hash gate 已通过 | 1 个非上游 generated fallback 已由独立 manifest 锁定，全量 vendor/overlay gate 通过 |
|
||
| WASM 构建 | `build_task_hal_wasm.sh` 只编译 task subset、HAL runtime、motion runtime 和 task-HAL wrapper | 五个组件没有进入 WASM object/link |
|
||
| 导出符号 | `EXPORTED_FUNCTIONS` 不含组件实例化或执行入口 | 无真实 WASM component symbol proof |
|
||
| `loadrt` | `linuxcnc_hal_runtime.cpp` 仅追加 `loadrt:<name>` event 并返回成功 | 不是实例化证据 |
|
||
| `addf` | 当前只把函数名登记到 thread | 未绑定可调用函数指针/组件实例 |
|
||
| servo step | `lchal_step_threads()` 只追加 `call:<thread>:<function>` event | 未执行组件公式、未更新输出 pin |
|
||
| Web evidence | 代表配置有原生 `loadrt mux2/scale` 和 `addf` 文本 | 只能证明 LinuxCNC 原生配置使用组件 |
|
||
|
||
因此，`4.7-4.11` 仍是“待实现预编译执行 gate”，`4.16` 只能保持“预编译 allowlist 条件通过/任意动态加载 Blocked”。
|
||
|
||
## LinuxCNC 源码与哈希基线
|
||
|
||
上游基线 commit：
|
||
|
||
```text
|
||
60597ee0718873d2449058c824262a275e5e4bad
|
||
```
|
||
|
||
| 组件 | 上游源码 | SHA-256 | LinuxCNC 函数语义 |
|
||
| --- | --- | --- | --- |
|
||
| `and2` | `src/hal/components/and2.comp` | `29f02d1342bae24d138bbb1387b006b97f592967b8688ccb1c6c0af451cae419` | `out = in0 && in1` |
|
||
| `or2` | `src/hal/components/or2.comp` | `c27663ce45f9562d7a5dc1b542da50ec2cc60802ef591ee729222002083a3c08` | `out = in0 || in1` |
|
||
| `not` | `src/hal/components/not.comp` | `9fd9522627db9926d037dc0c116badce7dc880f190c6f8b85c690cbb8b638332` | `out = !in` |
|
||
| `mux2` | `src/hal/components/mux2.comp` | `b75e3eeb74297d09d13052e812de53a38613ea8287522c371cc2fdaf76be3284` | `sel ? in1 : in0` |
|
||
| `scale` | `src/hal/components/scale.comp` | `d6830d74fd3462c7b7285a9e0b37cbcd2c53d2243007a198e3f19bfed9817f4f` | `out = in * gain + offset` |
|
||
|
||
五个组件都声明 `function _` 和 `option period no`。LinuxCNC 原生名称规则、`names=`/`count=` 实例化以及函数注册由 `halcompile` 生成代码负责；Web/WASM 适配不得改变 pin 方向、类型、默认值、实例命名或函数语义。
|
||
|
||
## 实施顺序
|
||
|
||
### 阶段 A：P1 源码同步闭合
|
||
|
||
必须先把以下路径加入可复现同步清单：
|
||
|
||
```text
|
||
src/hal/components/and2.comp
|
||
src/hal/components/or2.comp
|
||
src/hal/components/not.comp
|
||
src/hal/components/mux2.comp
|
||
src/hal/components/scale.comp
|
||
```
|
||
|
||
目标文件必须位于：
|
||
|
||
```text
|
||
wasm-port/vendor/linuxcnc/src/hal/components/
|
||
```
|
||
|
||
最低 gate：
|
||
|
||
```bash
|
||
cd wasm-port
|
||
./tools/extract_sources.sh
|
||
./tools/verify_vendor_sync.sh
|
||
sha256sum vendor/linuxcnc/src/hal/components/{and2,or2,not,mux2,scale}.comp
|
||
```
|
||
|
||
要求：五个 vendored 文件与上游逐字节一致；任何 source hash 变化必须让 manifest gate 失败，不能自动接受新公式。
|
||
|
||
### 阶段 B：LinuxCNC 派生生成物
|
||
|
||
推荐构建路径：使用与锁定基线一致的 LinuxCNC `halcompile --preprocess` 生成 C，再通过最窄 RTAPI/HAL shim 编译到 task-HAL WASM。若源树中只有 `halcompile.g` 而没有可执行的生成器，必须先在构建工具链中生成/定位 LinuxCNC `halcompile`，不能用正则截取 `FUNCTION(_)` 或人工复制公式替代。
|
||
|
||
建议产物：
|
||
|
||
```text
|
||
wasm-port/build/generated/hal-components/and2.c
|
||
wasm-port/build/generated/hal-components/or2.c
|
||
wasm-port/build/generated/hal-components/not.c
|
||
wasm-port/build/generated/hal-components/mux2.c
|
||
wasm-port/build/generated/hal-components/scale.c
|
||
wasm-port/build/generated/hal-components/generation-report.json
|
||
```
|
||
|
||
`generation-report.json` 最少包含：
|
||
|
||
| 字段 | 要求 |
|
||
| --- | --- |
|
||
| `upstreamCommit` | 固定为锁定 commit |
|
||
| `generator` | LinuxCNC `halcompile` 路径/版本 |
|
||
| `sourcePath` | vendored `.comp` 路径 |
|
||
| `sourceSha256` | 必须等于本文件基线 |
|
||
| `generatedPath` | 生成 C 路径 |
|
||
| `generatedSha256` | 用于增量构建和漂移检查 |
|
||
| `commandFingerprint` | 生成命令和参数摘要 |
|
||
|
||
生成过程必须增量执行：源码哈希、生成器哈希和命令指纹未变化时不得无条件重生成或重编译。
|
||
|
||
### 阶段 C：预编译 Manifest
|
||
|
||
建议文件：
|
||
|
||
```text
|
||
wasm-port/runtime/manifests/hal_component_precompile_manifest.json
|
||
```
|
||
|
||
顶层最小字段：
|
||
|
||
| 字段 | 规则 |
|
||
| --- | --- |
|
||
| `apiName` | 固定为 `hal_component_precompile_manifest` |
|
||
| `schemaVersion` | 固定为 `1` |
|
||
| `upstreamCommit` | 与 `tools/upstream-baseline.txt` 一致 |
|
||
| `dynamicLoadrtSupported` | 固定为 `false` |
|
||
| `unknownComponentPolicy` | 固定为 `blocked` |
|
||
| `components[]` | 必须恰好覆盖当前 allowlist |
|
||
|
||
`components[]` 每项最小字段：
|
||
|
||
| 字段 | 规则 |
|
||
| --- | --- |
|
||
| `component` | `and2`、`or2`、`not`、`mux2`、`scale` |
|
||
| `linuxcncSource` | vendored `.comp` 相对路径 |
|
||
| `sourceSha256` | 与 P0/P1 基线一致 |
|
||
| `generatedSource` | LinuxCNC `halcompile` 派生 C |
|
||
| `wasmFactorySymbol` | 创建 `names=`/`count=` 实例的 C ABI |
|
||
| `wasmStepSymbol` | 组件函数执行入口，或绑定到 runtime function registry 的 symbol |
|
||
| `pins[]` | 名称、方向、HAL type、默认值 |
|
||
| `functions[]` | LinuxCNC HAL function 名、`usesFp`、period policy |
|
||
| `loadrtArgs` | 明确支持的 `names=`、`count=` 子集和互斥规则 |
|
||
| `tests[]` | manifest、truth-table/formula、thread/net gate 路径 |
|
||
|
||
### 阶段 D：`loadrt` / `addf` / servo-step 执行链
|
||
|
||
运行时必须形成以下调用链：
|
||
|
||
```text
|
||
HAL text loadrt
|
||
-> allowlist lookup
|
||
-> parse names=/count=
|
||
-> call precompiled factory
|
||
-> create LinuxCNC-compatible pins/functions
|
||
-> register callable function entry
|
||
HAL text addf
|
||
-> resolve registered function
|
||
-> attach callable entry to virtual thread
|
||
lchal_step_threads
|
||
-> invoke callable entry in thread order
|
||
-> update output pins
|
||
-> propagate connected signals
|
||
-> emit execution evidence
|
||
```
|
||
|
||
失败规则：
|
||
|
||
- 未知组件：返回 blocked，不得仅记录 event 后成功。
|
||
- manifest 中有组件但 WASM symbol 缺失：启动失败。
|
||
- `names=` 与 `count=` 同时出现：按 LinuxCNC 行为拒绝。
|
||
- 重复实例名、pin 名冲突、未知 `addf` function：返回错误。
|
||
- thread step 只写 `call:` event 但没有实际输出变化：gate 失败。
|
||
|
||
## Truth-Table / Formula Evidence
|
||
|
||
建议 evidence：
|
||
|
||
```text
|
||
wasm-port/build/evidence/hal-component-truth-table-evidence.json
|
||
```
|
||
|
||
顶层最小字段：
|
||
|
||
| 字段 | 规则 |
|
||
| --- | --- |
|
||
| `apiName` | `hal_component_truth_table_evidence` |
|
||
| `schemaVersion` | `1` |
|
||
| `upstreamCommit` | 锁定基线 |
|
||
| `manifestSha256` | 绑定实际 manifest |
|
||
| `runtimeSource` | `linuxcnc-derived-precompiled-hal-component` |
|
||
| `components[]` | 五个组件全部出现 |
|
||
| `integrity.complete` | 所有向量、thread/net 和 blocked case 通过时为 `true` |
|
||
|
||
每个测试向量必须记录 `instance`、`inputs`、`expected`、`actual`、`threadCycle`、`outputPin`、`connectedSignal`、`passed`。最小向量：
|
||
|
||
| 组件 | 最小覆盖 |
|
||
| --- | --- |
|
||
| `and2` | 4 组 bit 组合 |
|
||
| `or2` | 4 组 bit 组合 |
|
||
| `not` | 2 组 bit 输入 |
|
||
| `mux2` | `sel=false`、`sel=true`，并使用不相等 float 输入 |
|
||
| `scale` | 至少 3 组，覆盖正 gain、负 gain、非零 offset，误差容限显式记录 |
|
||
|
||
每个组件至少一个向量必须通过真实 `loadrt -> setp/net -> addf -> lchal_step_threads -> snapshot` 路径，不能只直接调用测试 helper。
|
||
|
||
## 建议 Gate
|
||
|
||
### `wasm-port`
|
||
|
||
建议新增：
|
||
|
||
```text
|
||
wasm-port/tools/generate_hal_component_sources.sh
|
||
wasm-port/tools/verify_hal_component_source_sync.sh
|
||
wasm-port/tests/wasm/node/verify_hal_component_precompile_manifest.mjs
|
||
wasm-port/tests/wasm/node/verify_hal_component_truth_tables.mjs
|
||
wasm-port/tests/wasm/node/verify_hal_component_thread_net_execution.mjs
|
||
```
|
||
|
||
命令和通过输出：
|
||
|
||
```bash
|
||
cd wasm-port
|
||
./tools/verify_hal_component_source_sync.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_source_sync=ok
|
||
hal_component_precompile_manifest=ok
|
||
hal_component_truth_tables=ok
|
||
hal_component_thread_net_execution=ok
|
||
unknown_loadrt_component_blocked=ok
|
||
```
|
||
|
||
### `web-rtcp-5axis-xyzbc-trt-sim-plan`
|
||
|
||
目标 Web 项目不应再实现一套组件公式。它应消费 `wasm-port` task-HAL runtime 输出，并在 evidence 中引用：
|
||
|
||
```text
|
||
halComponentManifest
|
||
halComponentExecution
|
||
halComponentBlockedCases
|
||
```
|
||
|
||
代表 profile 至少要证明 `xyzac-trt_cmds.hal` 中 `mux2` 和 `scale` 的实例名、pin、`addf` 顺序和输出来自相同 WASM runtime。`compare-xyzbc-trt-evidence.json` 需记录 native HAL 配置声明与 Web/WASM 组件实例/执行结果的对应关系，但不能用配置文本相等替代运行结果。
|
||
|
||
## 04 严格状态与晋级条件
|
||
|
||
| 04 项 | 当前状态 | 晋级条件 |
|
||
| --- | --- | --- |
|
||
| `4.7 and2` | P1 已完成，预编译执行 gate 待补 | manifest、WASM symbol、4 组 truth table、thread/net proof |
|
||
| `4.8 or2` | P1 已完成，预编译执行 gate 待补 | manifest、WASM symbol、4 组 truth table、thread/net proof |
|
||
| `4.9 not` | P1 已完成，预编译执行 gate 待补 | manifest、WASM symbol、2 组 truth table、thread/net proof |
|
||
| `4.10 mux2` | P1 已完成，预编译执行 gate 待补 | `sel` 两路、`names=` 实例化、代表 XYZAC HAL 配置、thread/net proof |
|
||
| `4.11 scale` | P1 已完成，预编译执行 gate 待补 | 公式向量、浮点容差、代表 `rpm_rps` 实例、thread/net proof |
|
||
| `4.16 loadrt` | 预编译 allowlist 条件通过/动态加载 Blocked | allowlist 组件真实实例化；未知组件 blocked；仍不得宣称任意 `.so` 动态加载 |
|
||
|
||
## 与现有文件的关系
|
||
|
||
- `19-04动态加载与预编译Manifest复核.md`：定义动态加载和预编译边界。
|
||
- `21-04-HAL-Component-Precompile-Manifest实现缺口复核.md`：确认当前实现缺口。
|
||
- 本文件：补充 source sync、哈希、生成物、manifest、runtime 调用链、evidence 和 gate 的落地合同。
|
||
- `26-04-HAL-Component-P1源码同步与哈希Gate实施记录.md`：记录阶段 A 已实施、专项 gate 已通过以及严格 upstream/生成 overlay 分层。
|
||
- 实际实现完成后，必须把运行输出回填到 `05-验收证据.md`，再更新 `14` 中 `4.7-4.11/4.16` 的状态。
|
||
|
||
## 结论
|
||
|
||
`ACC-036/INT-023` 已把 HAL component precompile 从“需要 manifest/truth-table”细化为可执行实施合同；`ACC-038/INT-025` 已完成五个 `.comp` 的专项 P1 同步/hash 和全量 vendor/overlay gate。后续仍须完成 LinuxCNC 派生生成、预编译 symbol、真实 `loadrt/addf/servo-step` 调用和结构化 truth-table/formula evidence，04 的 `4.7-4.11` 才能晋级；任意运行时动态 `loadrt` 仍保持 Blocked。
|
||
|
||
## 后续状态
|
||
|
||
剩余实施合同已由 `ACC-039/INT-026` 闭合，五组件具备可复现生成、manifest、真实预编译 factory/thread/net 执行和结构化 truth-table/formula evidence。当前状态见 `27-04-HAL-Component-Precompile-Runtime-Gate实施记录.md`；固定 allowlist 条件通过，任意运行时动态 `loadrt` 继续 Blocked。
|