132 lines
6.4 KiB
Markdown
132 lines
6.4 KiB
Markdown
# 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。
|
||
|
||
## 不可破坏的调用顺序
|
||
|
||
```text
|
||
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()`。同一设备不能被两个进程同时占用。
|
||
|
||
## 推荐接入步骤
|
||
|
||
1. 给主项目添加 `Pcie8586.Driver.csproj` 项目引用，并把最终可执行项目固定为 x64。
|
||
2. 在依赖注入容器中将 `IDigitizer` 注册为单例或应用级长生命周期对象：
|
||
|
||
```csharp
|
||
services.AddSingleton<IDigitizer, Pcie8586Digitizer>();
|
||
```
|
||
|
||
3. 应用启动或硬件页面进入时枚举设备；用户选择逻辑 ID 后再打开。
|
||
4. 开始任务时创建 `AcquisitionConfig` 并调用 `ConfigureAsync`。正在采集时不要重配。
|
||
5. 在后台任务消费 `StartAcquisitionAsync`，不要在 UI 线程运行 DMA 读取循环。
|
||
6. 将每个 `SampleBlock` 立即交给主项目的数据管线。显示、算法、存盘应与采集解耦，慢消费者不能阻塞读卡。
|
||
7. 停止时先取消采集令牌并等待消费任务退出，再调用 `StopAsync`。
|
||
8. 应用退出时调用 `CloseAsync`/`Dispose`。
|
||
|
||
## 主项目应增加的适配层
|
||
|
||
建议新增一个业务服务，例如 `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 在改动驱动层时应遵守：
|
||
|
||
1. 先阅读本文件、`docs/API_AND_DATA_FORMAT.md`、厂商头文件和现有实现。
|
||
2. 保持 P/Invoke 集中在 `Pcie8586Digitizer.cs`。
|
||
3. 不改变结构体字段顺序、数组长度、字符集和调用约定，除非有厂商文档依据。
|
||
4. 不把原生句柄暴露给业务层。
|
||
5. 每次改动都保留模拟卡路径，并补充纯逻辑测试。
|
||
6. 涉及真卡行为的修改必须列出真卡复测项，不能仅以编译通过作为完成。
|