# 附录B. 故障排查

本附录汇总了读出子系统编程中的常见问题、可能原因及排查步骤。

## B.1. 解模结果异常

### B.1.1. 解模 IQ 数据全为零

| 可能原因 | 排查步骤 |
|:---|:---|
| 本振频率未配置或配置错误 | 检查混频板 `lo_freq` 寄存器（`0x00100000`）是否正确写入 |
| 码字未使能解模功能 | 检查码字 `DEMOD_SUM_VAL`（bit[4]）是否为 1 |
| 匹配滤波器参数未加载 | 检查 DAQ_PAR 中目标 PARA_ID 对应的 `dds_fpw` 和 `mtf_idx` 是否已正确写入 |
| `IQ_SCALE` 选择不当导致截位全零 | 尝试切换 `IQ_SCALE` 位（见 [§4.3 参数选择指南](04-03-acq-registers.md)），观察是否有非零输出 |
| DAQ_REG 寄存器未复位 | 执行软复位后重新加载配置（见 [§B.4](#b4-软复位)） |
| 输入信号功率过低 | 检查射频线缆连接，确认混频板输入端有信号 |

### B.1.2. 解模 IQ 数据幅值异常（过大或过小）

| 可能原因 | 排查步骤 |
|:---|:---|
| 解模频率与输入信号频率不匹配 | 验证 `dds_fpw.fcw` 计算公式：$F_c = fcw / 2^{20} \times F_s$，确保 $F_c$ 等于输入中频 $F_{IF}$ |
| 权重系数幅度不合理 | 检查 DAQ_PAR 权重区数据，权重系数为 8 位有符号数（范围 -128~127） |
| `IQ_SCALE` 位置不当 | 幅值过大时切到 `IQ_SCALE=1`（截高位），过小时切到 `IQ_SCALE=0` |
| `STEP_CTRL` 不匹配 | 若 `STEP_CTRL` 过大导致权重点稀疏，解模 SNR 下降，表现为幅值抖动增大 |

### B.1.3. FPGA 平台解模结果与 ASIC 平台不一致

| 可能原因 | 排查步骤 |
|:---|:---|
| 系数直读模式 vs 计算模式的固有差异 | 验证两个平台使用相同的权重数据和频率参数 |
| DAQ_FLT 系数计算方式错误 | FPGA 平台需预计算 I/Q 系数（见 [§4.4.3](04-04-acq-matched-filter.md)），检查系数是否按公式 $\text{Weight}[n] \times e^{j\omega n}$ 生成 |
| 采样点/时钟周期差异 | FPGA 每周期 16 采样点，ASIC 每周期 8 采样点，确保 `mtf_idx.addr` 和 `mtf_idx.len` 单位一致 |

## B.2. 态判断异常

### B.2.1. 频繁出现错误态（态值 = 3）

| 可能原因 | 排查步骤 |
|:---|:---|
| 三条直线不交于同一点 | 检查 line0/line1/line2 的系数（a, b, c）是否满足共点条件。若仅需两态判断，设置 `TWO_STA_EN=1` |
| IQ 平面分布漂移 | 量子比特状态分布可能随时间漂移，需重新校准直线方程系数 |
| 解模 IQ 数据 SNR 不足 | 检查权重设计是否合理、解模长度是否足够（见 [§B.1.2](#b12-解模-iq-数据幅值异常过大或过小)） |

### B.2.2. 两态模式下态值始终为 0 或 1

| 可能原因 | 排查步骤 |
|:---|:---|
| 直线方程系数未校准 | line0 的 (a, b, c) 需通过校准实验确定，不能使用默认值 0 |
| `TWO_STA_EN` 未正确设置 | 确认 `func_ctrl` 寄存器 bit[2] 为 1 |

## B.3. MCU 与触发问题

### B.3.1. MCU 程序不生效（无输出、无数据）

| 可能原因 | 排查步骤 |
|:---|:---|
| MCU 程序未正确加载 | 验证 MCU_INS 基地址（ACQ: `0x00200000`, EXC: `0x00700000`）已写入正确的指令序列 |
| 触发信号未到达 | 确认外部触发源已正确连接和使能。MCU 是被动响应方——无触发则无执行 |
| 码字位段值错误 | 逐位检查码字定义（ACQ: 32 位，EXC: 低 13 位），确保关键使能位（如 `DEMOD_SUM_VAL`、`PUMP_EN`）正确设置 |
| 软复位未执行 | 异常中断后需先执行软复位（见 [§B.4](#b4-软复位)），再加载 MCU 程序 |
| 寄存器配置未在触发前完成 | SPI 配置和 MCU 程序加载存在时序要求——配置必须在触发到达前完成（见 [§4.6.1](04-06-acq-pipeline-demo.md) / [§5.7.1](05-07-exc-pipeline-demo.md) 流程表） |

### B.3.2. MCU 执行正常但数据推送异常

| 可能原因 | 排查步骤 |
|:---|:---|
| 码字使能了多种存储类型 | 同时使能多种存储导致数据帧变长、解析复杂。建议仅使能一种存储类型进行调试 |
| 数据帧解析顺序错误 | 多 qubit + 多存储类型时，确认帧内数据顺序（波形 → IQ → 态 → 计数）与码字使能位一致 |

## B.4. 软复位

ACQ 和 EXC-Pump 通道均提供软复位功能，用于从上位机强制中断或 MCU 错误指令导致的异常状态中恢复。

| 通道 | 复位方式 | 复位范围 |
|:---|:---|:---|
| ACQ | 调用驱动 API 复位函数 | 状态机 + 部分寄存器默认值（详见 IDS 表中各寄存器的复位值列） |
| EXC-Pump | 调用驱动 API 复位函数 | 状态机 + 部分寄存器默认值（详见 IDS 表中各寄存器的复位值列） |

**复位后恢复流程**：
1. 执行软复位
2. 验证关键寄存器值是否正确
3. 重新加载 MCU 程序
4. 发送测试触发，验证数据通路正常工作

> **注意**：软复位不会恢复所有寄存器到上电默认值。对于被复位的寄存器，需在复位后重新配置。建议在每次软复位后执行完整的初始化序列。

## B.5. Pump 通道问题

### B.5.1. Pump 无输出

| 可能原因 | 排查步骤 |
|:---|:---|
| 硬件使能未打开 | 检查 `pump_enable` 寄存器是否为 `32'h11`（`32'h00` 时完全关闭） |
| MCU 码字 `PUMP_EN` 位未置 1 | 检查码字 bit[8] 是否为 1 |
| `pump_ctrl` 配置不当 | 检查 `delay` 和 `width` 参数，确保 width > 0 且 delay 不过大 |
| `pump_freq` 或 `pump_power` 未配置 | 这两个寄存器需要在 Pump 触发前通过 SPI 写入有效值 |

## B.6. 数据帧解析

### B.6.1. 数据帧解析错位

| 可能原因 | 排查步骤 |
|:---|:---|
| 码字使能的存储类型与解析代码不匹配 | 确保解析代码的数据类型顺序与码字使能位（WAVE→IQ→STATE→COUNT）一致 |
| 多 qubit 数据顺序混淆 | IQ 数据按 qubit 序号从小到大排列（q0 → q1 → ... → q15），验证解析代码的偏移计算 |
| 字节序错误 | 所有数据采用大端字节序（Big-Endian），确认解析代码的字节序设置正确 |
| 帧头/帧尾未正确识别 | 确认上位机驱动解帧逻辑与硬件推送的帧格式一致 |

**调试方法**：先使能单一存储类型 + 单 qubit 确认帧格式，再逐步增加复杂度。