AI 开发指导：PCIe8586 主项目接入

目标

把 src/Pcie8586.Driver 作为主项目的硬件基础设施层接入，稳定获得按通道拆分、单位为伏特的采样块。不要复制调试工具的 WPF 界面代码，也不要绕过 IDigitizer 在业务层直接调用 P/Invoke。

已验证基线

Windows x64、.NET 8。
厂商运行库名：ACTS1000_64.dll。
原生调用约定：StdCall。
板卡最多 8 通道；当前公开配置允许 1、2、4、8 通道。
基准采样率按 100_000_000 / ClockDivider 计算。
输入量程：±5 V、±1 V。
原始数据类型：16 位无符号码值。
DMA 数据布局：按采样点交错，即 CH0[0], CH1[0], ..., CHn[0], CH0[1], ...。
输出 SampleBlock.Channels 布局：[通道][该通道采样点]，数值单位 V。

不可破坏的调用顺序

EnumerateDevices
  → Open
  → Configure / ACTS1000_InitDeviceAD
  → Start / ACTS1000_StartDeviceAD
  → SoftwareTrigger / ACTS1000_SetDeviceTrigAD
  → Read loop / ACTS1000_ReadDeviceAD
  → Stop / ACTS1000_StopDeviceAD
  → Release AD / ACTS1000_ReleaseDeviceAD
  → Close / ACTS1000_ReleaseDevice

任何异常、取消、窗口关闭或应用退出路径都必须进入 finally，依次执行 StopAsync() 和 CloseAsync()。同一设备不能被两个进程同时占用。

主项目应增加的适配层

建议新增一个业务服务，例如 Pcie8586AcquisitionService，负责：

串行化打开、配置、启动、停止和关闭操作。
维护 Closed / Open / Running / Faulted 状态。
独占一个 CancellationTokenSource 和采集任务。
将 SampleBlock 写入有界 Channel<SampleBlock>。
通道满时采用符合业务要求的策略：等待、丢最旧显示帧，或停止并报警。测量原始数据不可静默丢弃。
将底层异常转换为主项目统一的硬件故障事件。

不要让 ViewModel、窗口或算法模块持有原生设备句柄。

参数规则

ChannelCount：只能为 1、2、4、8；启用的是从 CH0 开始的连续通道。
ClockDivider：正整数；实际采样率为 100 MHz / ClockDivider。接入后应使用设备 GetMainInfo 返回的能力做二次校验。
InputRange：±5 V 或 ±1 V，所有启用通道当前使用同一量程。
Mode：实时监控优先使用 Continuous。
FiniteSamplesPerChannel：仅有限点模式生效。厂商头文件要求后触发时“每通道点数 × 启用通道数 × 触发次数”为 512 的整数倍；主项目若启用有限点模式，应在上层对齐并做真卡专项测试。

当前硬件实现的固定参数：

DC 耦合、1 MΩ。
板载参考时钟、内部采样时基。
后触发、软件触发、触发一次。
不输出时钟、不输出触发。

如果主项目需要外触发、多卡同步、单通道独立量程或非连续通道掩码，应扩展配置模型并对照 vendor/include/ACTS1000.h，不要直接修改常量碰运气。

数据处理规则

StartSampleIndex 是每通道的相对采样序号，不是字节位置。
SamplesPerChannel 是单通道点数，总原始 word 数等于它乘以通道数。
Timestamp 是软件收到该块时的本机时间，不是硬件级精确首点时间戳。
±5 V 换算：V = ((10000 / 65536) × code - 5000) / 1000。
±1 V 换算：V = ((2000 / 65536) × code - 1000) / 1000。
0x8000 对应 0 V；最大码略低于正满量程。

若吞吐量较高，后续可把 double[][] 优化成池化缓冲或原始 ushort 管线，但必须先建立等价测试，确认交错顺序和电压换算没有改变。

并发与性能

DMA 读取已经放入后台 Task；调用方仍应在独立采集任务中消费异步流。
不要对每个采样块执行同步 UI 更新、日志逐点打印或数据库逐点写入。
绘图只取最新帧并降采样，建议 10–20 Hz 刷新。
连续存盘应使用专用写入任务和有界队列。
8 通道 100 MS/s 的理论原始吞吐约 1.6 GB/s，常规 UI/托管内存流程不适合无约束全速长期保存。先按业务需要降低分频、通道数或录制时长。

错误处理验收

至少覆盖以下场景：

未安装/找不到 ACTS1000_64.dll。
主进程不是 x64，出现 BadImageFormatException。
未发现板卡或逻辑 ID 打开失败。
初始化、启动、触发或读取返回 false。
用户取消、应用退出和采集任务异常时仍释放设备。
设备被其他进程占用。
消费速度低于采集速度时有明确背压或报警策略。

完成定义

主项目 x64 Release 编译通过。
无真卡时可注入 SimulatedDigitizer 验证完整业务数据链。
真卡可完成至少一次连续采集：枚举、打开、配置、触发、读取、停止、再次启动。
1/2/4/8 通道的顺序和点数正确。
0x8000 → 0 V 等换算测试通过。
停止、异常和退出后，调试工具或主项目可以再次打开设备，无句柄残留。
主项目的数据消费速度和内存上限经过目标采样率压力测试。

AI 修改约束

后续 AI 在改动驱动层时应遵守：

先阅读本文件、docs/API_AND_DATA_FORMAT.md、厂商头文件和现有实现。
保持 P/Invoke 集中在 Pcie8586Digitizer.cs。
不改变结构体字段顺序、数组长度、字符集和调用约定，除非有厂商文档依据。
不把原生句柄暴露给业务层。
每次改动都保留模拟卡路径，并补充纯逻辑测试。
涉及真卡行为的修改必须列出真卡复测项，不能仅以编译通过作为完成。

6.4 KiB Raw Blame History Unescape Escape