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

严格口径：

LinuxCNC 原生 halscope 和 halmeter 是 HAL 工具，不是普通 Web 截图功能。
浏览器不能声明运行了 LinuxCNC 原生 GTK/实时 HAL 工具，除非实际启动对应 native 工具并采集其输出。
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：

{
  "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 后续晋级至少需要输出如下结构：

{
  "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 后，至少补入以下命令之一：

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 命令：

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。

7.2 KiB Raw Permalink Blame History Unescape Escape