156 lines
7.2 KiB
Markdown
156 lines
7.2 KiB
Markdown
# 17-04 HAL Scope/Meter 结构化证据复核
|
||
|
||
## 定位
|
||
|
||
本文件落实 `ACC-029` 和 `INT-016`，只复核 `04基于Web的LinuxCNC兼容数控仿真平台.txt` 中与 HAL Scope/Meter 相关的条目：
|
||
|
||
- `4.13 HAL Scope`
|
||
- `4.14 HAL Meter`
|
||
- `10.7 HAL Scope`
|
||
|
||
严格口径：
|
||
|
||
1. LinuxCNC 原生 `halscope` 和 `halmeter` 是 HAL 工具，不是普通 Web 截图功能。
|
||
2. 浏览器不能声明运行了 LinuxCNC 原生 GTK/实时 HAL 工具，除非实际启动对应 native 工具并采集其输出。
|
||
3. Web 等效实现可以作为替代证据，但必须输出结构化 HAL sample、meter value 或 waveform evidence；截图只能作为 P5 辅助证据。
|
||
|
||
## LinuxCNC 源码证据
|
||
|
||
| 工具 | LinuxCNC 归属 | 关键行为 | 对 Web 的约束 |
|
||
| --- | --- | --- | --- |
|
||
| `halscope` | `src/hal/utils/scope.c`、`scope_rt.c`、`scope_shm.h`、`scope_usr.h`、`docs/src/hal/halscope.adoc`、`docs/src/man/man1/halscope.1.adoc` | 原生软件示波器，由用户态 GUI 和 `scope_rt` HAL 实时组件协作；通过共享内存、采样周期、record length、trigger、channel data 捕获 HAL pin/signal/parameter 波形 | Web 只能声明“等效 HAL waveform evidence”，不能把 canvas 折线或 UI 截图当作原生 `halscope` |
|
||
| `halmeter` | `bin/halmeter`、`docs/src/man/man1/halmeter.1.adoc` | 原生 HAL 万用表，用独立 HAL 连接观察单个 pin、signal 或 parameter 当前值 | Web 可用 virtual HAL registry/snapshot/readPin 等价覆盖当前值观察，但必须输出可复验 JSON |
|
||
|
||
源码级边界：
|
||
|
||
- `scope_rt.c` 导出 `scope.sample`，并维护 `IDLE`、`INIT`、`PRE_TRIG`、`TRIG_WAIT`、`POST_TRIG`、`DONE` 等采样状态。
|
||
- `scope_rt.c` 的采样逻辑按通道读取 HAL 数据地址，支持 bit/u32/s32/float 等数据宽度。
|
||
- `scope_shm.h` 固定了共享控制区，包括采样周期、记录长度、预触发、触发通道、触发电平、强制触发、当前样本、每通道 offset/type/len 等字段。
|
||
- `scope_usr.h` 记录用户态横轴、纵轴和通道选择状态，说明 `halscope` 不是单个静态数据点，而是有采样窗口和通道配置的波形工具。
|
||
- `halmeter.1.adoc` 将 `halmeter` 定义为观察 HAL pin、signal、parameter 的工具，行为接近单值仪表，不等价于 `halscope` 的波形缓存。
|
||
|
||
## 现有 Web/WASM 证据
|
||
|
||
| 项目 | 已有证据 | 可支撑内容 | 不足 |
|
||
| --- | --- | --- | --- |
|
||
| `wasm-port` | `tests/ui/node/verify_real_simulation_programs.mjs` | virtual HAL pin registry、bridge snapshot、runtime read/write、`spindle.0.speed-out`、`iocontrol.0.coolant-flood` 等当前值证据 | 可支撑 meter/status snapshot；不能单独支撑 `halscope` waveform |
|
||
| `wasm-port` | `runtime/opfs/snapshot-store.js` | OPFS session 中校验 `virtualHal.state.source === "browser-virtual-hal"`，并保存 virtual HAL 状态和诊断 | 证明状态可持久化；不证明固定采样周期、trigger 和多 sample 波形 |
|
||
| `web-rtcp-5axis-xyzbc-trt-sim-plan` | `tests/node/verify_gmoccapy_hal_model.mjs` | gmoccapy HAL model、pin groups、core/spindle/postgui nets、source compliance | 可支撑 HAL 模型和 UI 监视；不等价于原生 `halscope` 采样器 |
|
||
|
||
## 结构化 evidence 要求
|
||
|
||
### HAL Meter JSON
|
||
|
||
`4.14 HAL Meter` 和 `10.6 HAL 信号监视` 后续晋级至少需要输出如下结构，文件格式可为 JSON 或 JSONL：
|
||
|
||
```json
|
||
{
|
||
"apiName": "hal_meter_evidence",
|
||
"source": "browser-virtual-hal",
|
||
"sampleTime": "2026-07-10T12:41:00Z",
|
||
"items": [
|
||
{
|
||
"name": "spindle.0.speed-out",
|
||
"sourceKind": "pin",
|
||
"type": "float",
|
||
"value": 1200,
|
||
"writable": false,
|
||
"signal": "spindle-speed"
|
||
}
|
||
],
|
||
"integrity": {
|
||
"complete": true,
|
||
"sourceReference": "linuxcnc/docs/src/man/man1/halmeter.1.adoc"
|
||
}
|
||
}
|
||
```
|
||
|
||
验收规则：
|
||
|
||
- `items` 必须覆盖 pin、signal 或 parameter 中实际声称支持的类型。
|
||
- 每个 item 必须记录 `name`、`sourceKind`、`type`、`value`。
|
||
- 如支持写入或 UI 修改，必须记录 `writable`，并用 runtime read/write gate 证明写入后快照更新。
|
||
- 只显示 UI 数字、截图或 canvas 文本不构成 P3/P4 证据。
|
||
|
||
### HAL Scope Waveform JSON
|
||
|
||
`4.13 HAL Scope` 和 `10.7 HAL Scope` 后续晋级至少需要输出如下结构：
|
||
|
||
```json
|
||
{
|
||
"apiName": "hal_scope_waveform_evidence",
|
||
"source": "browser-virtual-hal",
|
||
"samplePeriodNs": 1000000,
|
||
"recordLength": 256,
|
||
"channelCount": 2,
|
||
"trigger": {
|
||
"channel": 0,
|
||
"edge": "rising",
|
||
"level": 0.5,
|
||
"forced": false
|
||
},
|
||
"channels": [
|
||
{
|
||
"index": 0,
|
||
"name": "spindle.0.speed-out",
|
||
"kind": "pin",
|
||
"type": "float",
|
||
"scale": 1,
|
||
"units": "rpm"
|
||
}
|
||
],
|
||
"samples": [
|
||
{
|
||
"sampleIndex": 0,
|
||
"timeNs": 0,
|
||
"values": [0, false]
|
||
}
|
||
],
|
||
"sourceReference": {
|
||
"linuxcnc": [
|
||
"linuxcnc/src/hal/utils/scope_rt.c",
|
||
"linuxcnc/src/hal/utils/scope_shm.h",
|
||
"linuxcnc/docs/src/hal/halscope.adoc"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
验收规则：
|
||
|
||
- `samplePeriodNs`、`recordLength`、`channelCount` 必须非空且与 `samples` 数量一致。
|
||
- `channels` 必须记录每个通道的 HAL 名称、来源类型、HAL 数据类型和缩放信息。
|
||
- `trigger` 必须记录触发来源；如采用强制触发，必须显式 `forced: true`。
|
||
- `samples` 必须是可解析的结构化数组，不能只保存截图像素或 canvas polyline。
|
||
- Node gate 至少校验字段完整性、采样数量、时间单调、通道数量和值类型；Browser gate 可在此基础上验证 UI 渲染。
|
||
|
||
## 04 条目结论
|
||
|
||
| 04 项 | 复核结论 | 后续 gate |
|
||
| --- | --- | --- |
|
||
| `4.13 HAL Scope` | 条件通过目标。LinuxCNC 原生 `halscope` 是 RT/GTK 工具；浏览器当前只能按等效 waveform evidence 验收 | 新增 `hal_scope_waveform_evidence` JSON/Node gate；可选 browser canvas 只作为 P4/P5 补充 |
|
||
| `4.14 HAL Meter` | 条件通过。当前 virtual HAL pin registry/snapshot/read/write 能支撑 meter-like 当前值证据，但不是原生 GTK `halmeter` | 新增 `hal_meter_evidence` JSON/Node gate；覆盖 pin/signal/parameter 当前值 |
|
||
| `10.7 HAL Scope` | 待实现 gate。Web UI 的 HAL Scope 不能只凭截图晋级 | 新增 waveform JSON、字段校验、浏览器渲染 smoke 和 evidence 文件路径 |
|
||
|
||
## 最小验收命令建议
|
||
|
||
后续实现对应 gate 后，至少补入以下命令之一：
|
||
|
||
```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
|
||
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:web
|
||
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run evidence:compare
|
||
```
|
||
|
||
若只是维护当前文档边界，继续使用本轮静态复核和 smoke 命令：
|
||
|
||
```bash
|
||
cd wasm-port && ./tools/verify_upstream_baseline.sh
|
||
npm --prefix web-rtcp-5axis-xyzbc-trt-sim-plan/app run smoke:node
|
||
```
|
||
|
||
## 结论
|
||
|
||
`ACC-029/INT-016` 已完成 HAL Scope/Meter 源码边界复核。当前可以把 `4.14 HAL Meter` 归为“已有 virtual HAL 基础、需 meter JSON gate 的条件通过”，把 `4.13/10.7 HAL Scope` 归为“原生工具已定位、Web 等效 waveform gate 待实现”。后续不能再用单张 UI 截图或 04 文本中的“通过”直接宣称 HAL Scope 已完整对标 LinuxCNC。
|