209 lines
10 KiB
Markdown
209 lines
10 KiB
Markdown
# 23-04 HAL Meter/Scope JSON Evidence Gate 落地蓝图
|
||
|
||
> 后续状态：本蓝图要求的两个 JSON evidence、wasm-port gate、Web gate 和 compare 字段已由 `28` 实施完成；原生 halscope/halmeter process 边界不变。
|
||
|
||
## 定位
|
||
|
||
本文件落实 `ACC-035/INT-022`：在 `17-04-HAL-Scope-Meter结构化证据复核.md` 和 `20-04-HAL-Scope-Meter-JSON-Gate实现缺口复核.md` 已经确认缺口之后，进一步把 `hal_meter_evidence` 与 `hal_scope_waveform_evidence` 的实际落地路径、数据来源、schema、脚本位置和验收 gate 固定下来。
|
||
|
||
覆盖 04 条目：
|
||
|
||
- `4.13 HAL Scope`
|
||
- `4.14 HAL Meter`
|
||
- `10.6 HAL 信号监视`
|
||
- `10.7 HAL Scope`
|
||
|
||
严格口径：`halGraph`、`halNets`、gmoccapy HAL model、按钮状态、截图、Canvas 折线或普通 HAL snapshot 只能作为输入来源，不能直接等价为 HAL Meter/Scope 完成。只有生成独立 JSON evidence、通过 Node gate，并在 Web evidence/compare 中引用这些字段，才能把 04 的 HAL Meter/Scope 从“条件通过/待 gate”继续晋级。
|
||
|
||
## LinuxCNC 源码对照
|
||
|
||
| 对照对象 | LinuxCNC 路径 | Web/WASM 等效要求 |
|
||
| --- | --- | --- |
|
||
| HAL Meter 当前值监视 | `linuxcnc/src/hal/utils/meter.c`、`docs/src/man/man1/halmeter.1.adoc` | 输出 pin/signal/parameter 当前值、类型、来源、连接状态、source reference 和完整性 |
|
||
| HAL Scope 采样组件 | `linuxcnc/src/hal/utils/scope_rt.c`、`scope_shm.h`、`scope_usr.h` | 输出采样周期、记录长度、通道定义、触发条件、样本序列和 source reference |
|
||
| HAL Scope 用户界面 | `linuxcnc/src/hal/utils/scope.c`、`docs/src/hal/halscope.adoc`、`docs/src/man/man1/halscope.1.adoc` | Web 可用 Canvas/表格展示，但 proof 必须落到 waveform JSON |
|
||
| HAL runtime 数据源 | `linuxcnc/src/hal/hal_lib.c`、`hal_priv.h` | Web/WASM 侧只允许从 LinuxCNC-backed virtual HAL snapshot 或 native evidence 派生，不允许 UI 手填 |
|
||
|
||
## 现有可复用数据源
|
||
|
||
### `wasm-port`
|
||
|
||
| 现有资产 | 可复用内容 | 限制 |
|
||
| --- | --- | --- |
|
||
| `runtime/core/linuxcnc_wrap/linuxcnc_hal_runtime.cpp` | `snapshot_json()` 已输出 `pins`、`signals`、`params`、`threads`、`events` | 当前不是 `hal_meter_evidence` 或 `hal_scope_waveform_evidence` |
|
||
| `tests/wasm/node/verify_hal_runtime.mjs` | 已创建 bit/float/s32/u32 pin、param、net、thread，并断言 snapshot | 只证明基础 HAL runtime，不证明 meter/scope schema |
|
||
| `lchal_get_snapshot_json` | 可作为 meter 当前值的数据入口 | 需新增格式转换和 gate |
|
||
| `lchal_step_threads` | 可作为 scope 采样时钟入口 | 需记录 samplePeriodNs、recordLength 和样本序列 |
|
||
|
||
### `web-rtcp-5axis-xyzbc-trt-sim-plan`
|
||
|
||
| 现有资产 | 可复用内容 | 限制 |
|
||
| --- | --- | --- |
|
||
| `app/src/runtime/gmoccapy-hal-model.js` | gmoccapy pin group、core/spindle/postgui net、硬按钮/override/jog/tool/message pin 映射 | 是 HAL model，不是 meter/scope runtime proof |
|
||
| `tests/node/verify_gmoccapy_hal_model.mjs` | 可继续证明 HAL model 本身不漂移 | 不能替代 `hal_meter_evidence`/`hal_scope_waveform_evidence` |
|
||
| `working/evidence/web-xyzbc-trt-evidence.json` | 已有 `halGraph`、`halNets`、`taskHalFullState`、`pyvcpPostgui` | 顶层尚无 `hal_meter_evidence`、`hal_scope_waveform_evidence` |
|
||
| `working/evidence/compare-xyzbc-trt-evidence.json` | 已有 native/Web compare 框架 | 尚无 meter/scope 对比项 |
|
||
|
||
本轮复核确认当前 evidence 顶层字段：
|
||
|
||
```text
|
||
web-xyzbc-trt-evidence.json: has_hal_meter_evidence=false
|
||
web-xyzbc-trt-evidence.json: has_hal_scope_waveform_evidence=false
|
||
compare-xyzbc-trt-evidence.json: has_hal_meter_evidence=false
|
||
compare-xyzbc-trt-evidence.json: has_hal_scope_waveform_evidence=false
|
||
```
|
||
|
||
## `hal_meter_evidence` Schema
|
||
|
||
建议生成位置：
|
||
|
||
```text
|
||
wasm-port/build/evidence/hal-meter-evidence.json
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/hal-meter-evidence.json
|
||
```
|
||
|
||
最小 schema：
|
||
|
||
| 字段 | 规则 |
|
||
| --- | --- |
|
||
| `apiName` | 固定为 `hal_meter_evidence` |
|
||
| `schemaVersion` | 固定为 `1`，后续变更必须增版本 |
|
||
| `source` | `wasm-hal-runtime-snapshot`、`web-task-hal-status` 或 `native-hal-meter` |
|
||
| `profileId` | 例如 `xyzbc-trt`、`xyzac-trt`、`gmoccapy-xyzab` |
|
||
| `linuxCncReferences[]` | 至少包含 `src/hal/utils/meter.c` 和 `docs/src/man/man1/halmeter.1.adoc` |
|
||
| `snapshotCycle` | 来源 snapshot 的 cycle/taskCycle/servoCycle |
|
||
| `items[]` | 非空，且至少覆盖 pin、signal、parameter 三类中的可用类别 |
|
||
| `items[].name` | HAL pin/signal/parameter 名称 |
|
||
| `items[].sourceKind` | `pin`、`signal`、`parameter` |
|
||
| `items[].type` | `bit`、`float`、`s32`、`u32`、`s64`、`u64` |
|
||
| `items[].value` | 与 HAL type 一致的 JSON 值 |
|
||
| `items[].connected` | 对 pin/signal 必须有布尔值；parameter 可为 `false` |
|
||
| `items[].signal` | pin 连接到 signal 时必须记录 |
|
||
| `integrity.complete` | 全部必填字段通过时为 `true` |
|
||
| `integrity.missing[]` | 缺字段时列出原因，且不得晋级 |
|
||
|
||
最小覆盖集合：
|
||
|
||
```text
|
||
pin: motion.analog-out-03, motion.program-line, probe.in/probe.out
|
||
signal: probe-signal 或目标 Web evidence 中实际存在的 HAL net signal
|
||
parameter: standalone.param-float, standalone.param-s32 或目标 profile 中可回读参数
|
||
```
|
||
|
||
## `hal_scope_waveform_evidence` Schema
|
||
|
||
建议生成位置：
|
||
|
||
```text
|
||
wasm-port/build/evidence/hal-scope-waveform-evidence.json
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/working/evidence/hal-scope-waveform-evidence.json
|
||
```
|
||
|
||
最小 schema：
|
||
|
||
| 字段 | 规则 |
|
||
| --- | --- |
|
||
| `apiName` | 固定为 `hal_scope_waveform_evidence` |
|
||
| `schemaVersion` | 固定为 `1` |
|
||
| `source` | `wasm-hal-runtime-thread-samples`、`web-task-hal-servo-samples` 或 `native-halscope` |
|
||
| `profileId` | 与采样运行 profile 一致 |
|
||
| `linuxCncReferences[]` | 至少包含 `scope_rt.c`、`scope_shm.h`、`scope_usr.h`、`halscope.adoc` |
|
||
| `samplePeriodNs` | 正整数 |
|
||
| `recordLength` | 正整数 |
|
||
| `channelCount` | 必须等于 `channels.length` |
|
||
| `channels[]` | 每项包含 `index`、`name`、`kind`、`type` |
|
||
| `trigger` | 包含 `mode`、`channel`、`edge`、`level` 或显式 `forced: true` |
|
||
| `samples[]` | 长度等于 `recordLength` 或记录 `integrity.truncated=true` |
|
||
| `samples[].sampleIndex` | 从 0 递增 |
|
||
| `samples[].timeNs` | 单调递增 |
|
||
| `samples[].values[]` | 长度必须等于 `channelCount` |
|
||
| `integrity.complete` | 字段、长度、类型和时间单调均通过时为 `true` |
|
||
|
||
最小采样策略：
|
||
|
||
1. 初始化 HAL runtime，创建至少 2 个 pin 和 1 个 signal。
|
||
2. 建立 `net`，让输出 pin 传播到输入 pin。
|
||
3. 每个 sample 前修改至少一个 pin 值，调用一次 `lchal_step_threads()` 或 Web task/HAL servo step。
|
||
4. 记录 `sampleIndex`、`timeNs`、每个 channel 的值。
|
||
5. 校验至少一个 channel 值随 sample 变化，避免静态截图式 proof。
|
||
|
||
## 建议新增 Gate
|
||
|
||
### `wasm-port`
|
||
|
||
建议新增：
|
||
|
||
```text
|
||
wasm-port/tests/ui/node/verify_hal_meter_evidence.mjs
|
||
wasm-port/tests/ui/node/verify_hal_scope_waveform_evidence.mjs
|
||
```
|
||
|
||
命令：
|
||
|
||
```bash
|
||
cd wasm-port && node tests/ui/node/verify_hal_meter_evidence.mjs
|
||
cd wasm-port && node tests/ui/node/verify_hal_scope_waveform_evidence.mjs
|
||
```
|
||
|
||
通过输出：
|
||
|
||
```text
|
||
hal_meter_evidence_schema=ok
|
||
hal_meter_evidence_items=ok
|
||
hal_scope_waveform_schema=ok
|
||
hal_scope_waveform_samples=ok
|
||
```
|
||
|
||
失败条件：
|
||
|
||
- 没有 `linuxCncReferences`。
|
||
- `items[]` 或 `channels[]` 为空。
|
||
- `samples[]` 长度与 `recordLength` 不一致且没有 `truncated` 说明。
|
||
- waveform 中所有 sample 完全相同。
|
||
- 从 UI 字符串或截图生成 evidence，而不是从 HAL snapshot/runtime 派生。
|
||
|
||
### `web-rtcp-5axis-xyzbc-trt-sim-plan`
|
||
|
||
建议新增：
|
||
|
||
```text
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/tests/node/verify_hal_meter_scope_evidence.mjs
|
||
```
|
||
|
||
并扩展：
|
||
|
||
```text
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/tools/collect-web-xyzbc-trt-evidence.mjs
|
||
web-rtcp-5axis-xyzbc-trt-sim-plan/tools/compare-xyzbc-trt-evidence.mjs
|
||
```
|
||
|
||
要求：
|
||
|
||
- `web-xyzbc-trt-evidence.json` 顶层必须出现 `hal_meter_evidence` 和 `hal_scope_waveform_evidence`。
|
||
- `compare-xyzbc-trt-evidence.json` 必须出现对应 comparison 项。
|
||
- Browser smoke 只负责证明 UI 渲染，不得替代 JSON schema gate。
|
||
|
||
## 04 严格状态更新
|
||
|
||
| 04 项 | 当前状态 | 落地后晋级条件 |
|
||
| --- | --- | --- |
|
||
| `4.13 HAL Scope` | 待实现 waveform JSON gate | 生成 `hal_scope_waveform_evidence`，通过 schema、sample、trigger 和 compare gate |
|
||
| `4.14 HAL Meter` | 条件通过，待补 meter JSON gate | 生成 `hal_meter_evidence`，覆盖 pin/signal/parameter 当前值并通过 gate |
|
||
| `10.6 HAL 信号监视` | 条件通过 | 如果只声明监视模型，`halGraph`/`halNets` 可保留；若声明 meter-like 当前值，必须引用 `hal_meter_evidence` |
|
||
| `10.7 HAL Scope` | 待实现 waveform JSON gate | Canvas/UI 必须由 `hal_scope_waveform_evidence` 驱动或引用该 evidence |
|
||
|
||
## 与现有文件的关系
|
||
|
||
- `17-04-HAL-Scope-Meter结构化证据复核.md`：定义源码边界。
|
||
- `20-04-HAL-Scope-Meter-JSON-Gate实现缺口复核.md`：确认当前缺 `hal_meter_evidence` / `hal_scope_waveform_evidence`。
|
||
- 本文件：定义实际 schema、生成路径、脚本位置、通过输出和晋级条件。
|
||
- 后续实现脚本后，必须把命令输出回填到 `05-验收证据.md`，再把 `14` 中对应项从“待实现 gate”晋级。
|
||
|
||
## 结论
|
||
|
||
`ACC-035/INT-022` 已完成 HAL Meter/Scope JSON Evidence Gate 的落地蓝图。当前项目仍不能把 04 的 HAL Scope/Meter 宣称为完整完成；但后续实现已收敛为明确的两个 JSON evidence、三个 Node gate 和 Web evidence/compare 字段扩展。任何晋级必须以这些可机读字段和 gate 通过为准。
|
||
|
||
## 后续状态
|
||
|
||
蓝图已由 `ACC-040/INT-027` 实施：`hal_meter_evidence`、`hal_scope_waveform_evidence`、WASM Node gate、Web evidence 和 compare 均已通过。当前严格结论见 `28-04-HAL-Meter-Scope-JSON-Evidence-Gate实施记录.md`；该结果不继承为原生 GTK/RT `halmeter`/`halscope` process proof。
|