完善报告

.gitignore

@@ -5,3 +5,6 @@ output/
 __pycache__/
 *.pyc
 *.pyo
+
+# IDE
+.vscode/

CLAUDE.md

@@ -92,6 +92,7 @@ python build.py
 | §5.6 | `chapters/05-06-pump-config.md` | Pump 模拟电路配置 |
 | §5.7 | `chapters/05-07-exc-pipeline-demo.md` | EXC-Pump 全流程控制示例 |
 | 附录A | `chapters/80-appendix-ids-table.md` | IDS 寄存器索引表（DAQ_REG / AWG_REG / 地址映射） |
+| 附录B | `chapters/81-appendix-troubleshooting.md` | 故障排查（常见问题、原因分析与排查步骤） |
 
 ## 编辑工作流
 

chapters/01-changelog.md

@@ -2,6 +2,7 @@
 
 |版本|修订日期|修订原因|修订内容|修订人|
 |:-|:-|:-|:-|:-|
-|v0.1|2025/10/27|统一格式|初始版本|郭成|
+|v0.1|2025/10/27|统一格式|初始版本：完成全部章节的 Markdown 源文件、项目结构与构建管道搭建|郭成|
-|v0.2|2025/10/31|评审意见|内容补充|郭成|
+|v0.2|2025/10/31|评审意见|内容补充：新增 §4.4 匹配滤波器、§4.5 采集数据处理；完善 §4.6 与 §5.7 全流程示例的地址表与配置步骤|郭成|
-|v0.3|2026/07/27|用户反馈|内容梳理|郭成|
+|v0.3|2026/07/27|用户反馈|内容梳理：重构 §4.3 / §5.2 寄存器描述，统一码字字段命名；新增 §80 附录（IDS 寄存器索引表，由外部 JSON 自动渲染）；更新 project.yaml 版本号与章节排序|郭成|
+|v0.4|2026/07/30|编辑完善|扩充薄弱章节（§4.1 下变频、§5.5 上变频、§5.6 Pump 配置）；新增 §3.3 FPGA vs ASIC 平台差异汇总矩阵；为 §4.2 增加死时间量化数据，为 §4.3 / §4.4 / §5.2 增加设计决策指导；修正引用文档表；新增 §81 故障排查附录|郭成|

chapters/02-preface.md

@@ -17,11 +17,10 @@
 
 ## 2.4. 引用文档
 
-|文档编号|标题|版本|
+|文档编号|标题|版本|说明|
-|:-|:-|:-|
+|:-|:-|:-|:-|
-|-|读出子系统历史无关配置集.md|V1.0|
+|-|读出子系统历史无关配置集|V1.0|ez-Q 2.5 读出子系统历史无关配置项定义，包含多个功能使用示例|
-|-|读出子系统IDS表.xls|V1.0|
+|ez-Q 2.5-SDD-04|ez-Q 2.5 测控系统研制项目指令集设计报告|V1.0|量子编程指令集定义，包含 MCU 指令编码、时序与编程约束|
-|ez-Q 2.5-SDD-04|ez-Q 2.5 测控系统研制项目指令集设计报告_V1.0.docx|V1.0|
 
 ## 2.5. 术语定义
 
@@ -29,3 +28,14 @@
 |:-|:-|:-|
 |ACQ|Acquisition|读出回波采集处理通道|
 |EXC|Excitation|读出激励生成发送通道|
+|Pump|Pump|泵浦通道，用于产生特定频率和功率的单音微波信号以辅助量子比特读出|
+|AWG|Arbitrary Waveform Generator|任意波形发生器，EXC-Pump 通道的核心数字模块|
+|DAQ|Data Acquisition|数据采集，ACQ 通道的核心数字模块|
+|RBPU|Readout Baseband Processing Unit|读出基带处理单元（ASIC 芯片名）|
+|MCU|Micro Controller Unit|通道微控制器，执行码字指令序列|
+|NCO|Numerically Controlled Oscillator|数控振荡器，用于产生数字单音信号进行调制/解调|
+|IDS|Index Data Sheet|寄存器索引表，定义寄存器地址、位域、权限和默认值|
+|MTF|Matched Filter|匹配滤波器，用于对采集波形进行最优解模以最大化 SNR|
+|SPI|Serial Peripheral Interface|串行外设接口，上位机通过该接口配置通道寄存器|
+|解模|Demodulation|将 ADC 采集的数字波形与匹配滤波器做相关运算，提取 I/Q 分量|
+|态判断|State Discrimination|通过直线方程将解模 IQ 数据映射到量子比特态（0/1/2）|

chapters/03-overview.md

@@ -41,16 +41,62 @@ ACQ和EXC-Pump通道配置寄存器的地址索引定义详见[附录A. IDS寄
 * MCU通过**0x200000**地址访问通道配置寄存器空间；
 
 针对具体的指令定义和使用方法，
-读者可查看[《量子编程指令集》](TODO)了解相关信息。
+读者可查看[《量子编程指令集》](引用文档 ez-Q 2.5-SDD-04)了解相关信息。
 
-## 3.2. 读出子系统编程
+## 3.2. 读者阅读路径
 
-ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出泵浦板三个硬件组成
+本文档按"先总览、再分通道、最后附录"的结构组织，建议按以下路径阅读：
-- 三个板卡以PXIe板卡的形式安装在机箱中位置相邻的三个槽位上
+
-- 混频板的槽位号比基带板大1，泵浦板槽位号比基带板槽位号小1
+1. **新用户快速上手**：先读 §3（本章）了解系统全貌 → 跳到 §4.6（ACQ 全流程示例）或 §5.7（EXC-Pump 全流程示例）获取端到端编程体验 → 再回头查阅具体章节了解细节
+2. **驱动开发工程师**：按章节顺序阅读，重点关注 §4.3/§4.4（ACQ 寄存器与匹配滤波器）和 §5.2~§5.4（EXC 寄存器、索引表、波形仓库），附录 A 为日常编程的寄存器速查参考
+3. **FPGA/ASIC 平台移植**：先读 [§3.3 FPGA vs ASIC 平台差异汇总](#33-fpga-vs-asic) 了解全局差异，再逐章核对各模块的平台相关标注
+4. **问题排查**：直接访问 [附录 B. 故障排查](#b) 查找常见问题及解决方案
+
+## 3.3. FPGA vs ASIC 平台差异汇总
+
+ez-Q 2.5 同时支持 FPGA 和 ASIC 两种硬件平台，二者在时钟、采样率、数据处理模式等方面存在显著差异。
+下表汇总了所有影响编程的关键差异，各差异点在正文对应章节均有详细说明。
+
+### 3.3.1. 全局参数差异
+
+| 参数 | FPGA 平台 | ASIC 平台 | 参考章节 |
+|:---|:---|:---|:---|
+| MCU 主时钟频率 | 250 MHz | 750 MHz | [§3.1](#31-测控系统编程概述) |
+| ADC/DAC 采样率 | 4 Gsps | 6 Gsps | [§3.4](#34-读出子系统编程) |
+| 每时钟周期采样点数 | 16 samples/cycle | 8 samples/cycle | [§4.5.1](#451-采集波形数据) / [§5.4](#54-波形仓库定义) |
+| ADC/DAC 实现 | 外部商用芯片 | RBPU 片内集成 | [§3.4](#34-读出子系统编程) |
+| PLL | 外部商用芯片 | RBPU 片内集成 | [§3.4](#34-读出子系统编程) |
+| 波形仓库最大输出时长 | ~16 μs | ~10 μs | [§5.4](#54-波形仓库定义) |
+
+### 3.3.2. ACQ 通道差异
+
+| 功能 | FPGA 平台 | ASIC 平台 | 参考章节 |
+|:---|:---|:---|:---|
+| 匹配滤波器模式 | **系数直读模式**（DAQ_FLT 预存系数） | **系数计算模式**（DDS×权重实时计算） | [§4.4](#44-匹配滤波器) |
+| dds_fpw 寄存器 | 无实际效果 | 有效：控制解模载波频率/相位 | [§4.3](#43-acq寄存器功能定义) |
+| WEIGHT_IQ / CONST_EN / STEP_CTRL | 无实际效果 | 有效：控制常数权重与步长 | [§4.3](#43-acq寄存器功能定义) |
+| 匹配滤波器系数存储 | 需要 DAQ_FLT (`0x00580000`)，I/Q 各 16 KB/Qubit | 不需要 DAQ_FLT，系数由 DAQ_PAR 权重 + DDS 实时计算 | [§4.4.2](#442-匹配滤波器系数) |
+
+### 3.3.3. EXC-Pump 通道差异
+
+| 功能 | FPGA 平台 | ASIC 平台 | 参考章节 |
+|:---|:---|:---|:---|
+| 半带插值滤波器 (INTP_SEL) | 不支持（DSP 资源受限） | 支持，可优化输出平坦度 | [§5.2](#52-寄存器功能定义) |
+| 混频模式 (MIX_MODE) | 仅基带模式（外部模拟混频） | 支持基带+MIX 模式（可射频直出） | [§5.2](#52-寄存器功能定义) |
+
+> **编程提示**：为 FPGA 平台编写 MCU 程序时，注意规避标注为"无实际效果"的寄存器位段——写入这些位段不会报错，但不会产生预期效果，可能导致调试困惑。
+
+## 3.4. 读出子系统编程
+
+ez-Q 2.5 读出子系统包含三类硬件功能单元：读出基带板、读出混频板和读出泵浦板。
+这三类功能单元在物理上存在两种硬件形态：
+
+- **分离形态**：基带板、混频板、泵浦板为三个独立 PXIe 板卡，安装在机箱中相邻槽位（混频板槽位 = 基带板槽位 + 1，泵浦板槽位 = 基带板槽位 − 1）；
+- **合并形态**：混频与泵浦功能集成在一个 PXIe 板卡上，与基带板相邻安装。
+
+两种形态在编程模型上**完全一致**——软件通过指定基带板槽位号定位混频和泵浦功能单元，寄存器接口无差异。
+下文以分离形态为例进行描述，除槽位布局外所有内容对两种形态均适用。
 
-因此可以通过仅指定读出基带板槽位号来定位混频板和泵浦板槽位号，
-读出子系统硬件架构如下图所示。
 - 读出基带板负责产生、输出、采集和处理基带信号以及为泵浦通道产生使能信号；
 - 读出混频板自身产生一个本振信号，用于实现基带信号与射频信号之间的转换；
 - 而读出泵浦板负责产生一个指定功率频率的单音信号，并在外部使能信号控制下输出；
@@ -70,7 +116,6 @@ ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出
 
 ASIC和FPGA平台具有以下区别：
 
-* ez-Q 2.5 FPGA平台读出子系统混频板和泵浦板复用同一个硬件板卡。
 * ez-Q 2.5 FPGA平台将读出基带芯片RBPU和FPGA集成在一个FPGA中。
 * ez-Q 2.5 FPGA平台使用外部商用ADC、DAC和PLL来替换RBPU的对应功能。
 * ez-Q 2.5 FPGA平台ADC、DAC采样率为4 Gsps, ASIC平台暂定为6 Gsps

chapters/04-00-acq-model.md

@@ -2,7 +2,7 @@
 
 来自量子芯片RO端口的射频信号首先经过混频板调理后再进入读出基带处理单元采集处理。
 混频板负责将输入功率和频率的信号转换成基带板卡能够处理的频率功率合适的信号，
-因此对混频板的编程主要包括`变频增益`和变频`本振频率`。
+因此对混频板的编程主要包括本振频率设置（增益为预留接口）。
 
 模拟信号进入基带处理单元后，先经过巴伦将单端信号转换成ADC所需的差分信号。
 接着基带板上的读出芯片`RBPU`利用ADC(FPGA平台为8 bit@4 Gsps，ASIC 平台为8 bit@6 Gsps）采样,
@@ -14,9 +14,9 @@
 - MCU指令+MCU数据可用于编程发出触发码字以及实时修改控制寄存器；
 - DAQ控制寄存器用于指定解模频率、相位、权重/系数数据的索引等参数；
 - 解模参数数据定义了具体的权重数据和量子态判断参数等数据。
-- 模拟电路配置用于设置变频增益和本振频率。
+- 模拟电路配置用于设置本振频率（增益为预留接口，支持情况取决于混频板硬件形态）。
 
-目前模拟电路采用固定变频增益，仅支持设置本振频率。下图是ASIC平台ACQ通道数字部分编程控制模型。
+下图是ACQ通道数字部分编程控制模型。
 
 ![读出ACQ通道控制模型](../assets/readout_ro.png)
 

chapters/04-01-acq-downconversion.md

@@ -1,14 +1,44 @@
 ## 4.1. 下变频电路配置
 
-来自量子比特RO端口的射频信号需要经过前端模拟电路处理后才能够被读出基带处理单元采集处理。
+来自量子比特 RO 端口的射频信号需要经过前端模拟电路处理后才能够被读出基带处理单元采集处理。
-前端下变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。
+前端下变频电路将射频信号下变频到 ADC 可采样的中频范围。
 
-|配置名|描述|
+### 4.1.1. 配置项
-|:-:|:-:|
-|lo_freq|变频本振频率设置|
-|dn_gain|下变频增益设置|
 
-* lo_freq：32比特整数，范围[5400000, 5600000]单位是kHz
+| 配置名 | 描述 | 访问方式 |
+|:-:|:-|:-|
+| `lo_freq` | 变频本振频率设置 | SPI（基地址 `0x00100000`） |
+| `dn_gain` | 下变频增益设置 | SPI（预留） |
 
->目前ez-Q 2.5 FPGA平台暂不支持下变频增益dn_gain 设置；
+### 4.1.2. 本振频率配置
-仅支持 lo_freq 变频本振频率设置，单板上下变频通道共享lo_freq设置
+
+`lo_freq` 是下变频的核心参数，决定输入射频信号被搬移到哪个中频。
+
+| 参数 | 说明 |
+|:---|:---|
+| 位宽 | 32 比特整数 |
+| 单位 | kHz |
+| 支持范围 | 5,400,000 ~ 5,600,000（即 5.4 ~ 5.6 GHz） |
+
+**频率关系**：
+
+$$F_{IF} = |F_{RF} - F_{LO}|$$
+
+其中 $F_{RF}$ 为量子比特读出谐振腔频率（射频输入），$F_{LO}$ 为本振频率，$F_{IF}$ 为进入 ADC 的中频信号频率。
+
+### 4.1.3. 共享本振约束
+
+> **重要**：同一块混频板上的 4 个通道**共享同一个本振信号**。这意味着：
+> - 一块混频板上的全部 4 个 ACQ 通道必须使用相同的 $F_{LO}$；
+> - 上变频和下变频通道也共享同一个本振（见 [§5.5](../chapters/05-05-exc-upconversion.md)）；
+> - 多比特实验时，所有 qubit 的中频 $F_{IF}$ 由同一个 $F_{LO}$ 决定，需在选择 $F_{LO}$ 时综合考虑所有 qubit 的频率分布。
+
+### 4.1.4. 增益设置
+
+`dn_gain` 为预留接口，其支持情况取决于混频板硬件形态。
+
+### 4.1.5. 配置时序
+
+下变频电路配置应在 ACQ 通道触发采集**之前**通过 SPI 完成。配置写入后需等待本振锁相环（PLL）锁定，建议在初始化阶段完成配置。
+
+配置顺序：SPI 写混频板寄存器 → 等待 PLL 锁定 → 配置 DAQ 寄存器 → 加载 MCU 程序 → 等待触发。

chapters/04-02-acq-codeword.md

@@ -48,4 +48,20 @@ ACQ通道利用MCU产生32位的码字来控制读出行为，32位的操控码
 * 在一个指令中同时使能了态计数清零、态计数和计数存储时，顺序为：
     1. 先执行态计数清零
     1. 再执行态计数
-    1. 最后执行计数结果存储
+    1. 最后执行计数结果存储
+
+### 死时间与存储选择
+
+同时使能多种数据存储将引入额外的死时间（dead time），即硬件在完成当前数据推送之前无法响应下一触发的时间间隔。不同存储类型的相对数据量如下：
+
+| 存储类型 | 单次数据量 | 特点 |
+|:---|:---|:---|
+| 波形数据 (WAVE_SAVE_EN) | 取决于 `sample_depth`（时钟周期数 × 每周期采样点数 × 8 bit） | 数据量最大 |
+| 解模 IQ 数据 (IQ_SAVE_EN) | 8 字节/qubit（I 4B + Q 4B） | 数据量较小 |
+| 态数据 (STATE_SAVE_EN) | 4 字节/全部 qubit（每 qubit 2 bit） | 数据量最小 |
+| 态计数 (COUNT_SAVE_EN) | 16 字节/全部 qubit（4 个计数器各 4B） | 数据量较小 |
+
+> **推荐实践**：
+> - 同时使能多种存储类型时，存储顺序为：波形数据 → 解模 IQ 数据 → 态判断数据 → 态计数数据；
+> - 同时使能多种存储会叠加死时间并增加数据帧解析复杂度。**建议每次仅使能一种存储类型**；
+> - 实际死时间取决于使能数据类型、qubit 数量和平台时钟频率，具体数值应通过实验测定。

chapters/04-03-acq-registers.md

@@ -56,3 +56,52 @@ function寄存器WEIGHT_IQ，CONST_EN, STEP_CTRL 位无实际效果
 
 解模完成后，可以通过`TWO_STA_EN`来控制是否启动2态判定，
 当`TWO_STA_EN=1`时，可以只配置一组直线方程系数进行态判断。
+
+### 参数选择指南
+
+#### 查找表模式 vs 寄存器模式
+
+ACQ 通道提供两种参数索引方式，由码字位 `MTF_IDX_SEL` 和 `DDS_FPW_SEL` 分别控制：
+
+| 模式 | 控制位值 | 参数来源 | 优点 | 缺点 | 适用场景 |
+|:---|:---|:---|:---|:---|:---|
+| 查找表 (LUT) | `0` | DAQ_PAR 中预存的 16 组参数（PARA_ID 0~15） | 切换速度快（一条码字即可切换）、参数经过预校验 | 最多 16 组，需提前加载 | **推荐**：常规多比特轮询实验 |
+| 寄存器 | `1` | DAQ_REG 中的 `mtf_idx_q` / `dds_fpw_q` 寄存器 | 参数数量不限，MCU 可实时写入任意值 | 切换需 MCU 先写寄存器再发码字（多指令开销） | 需要超过 16 组参数、或参数需动态计算的高灵活度场景 |
+
+> **建议**：大多数实验使用查找表模式即可满足需求（16 组参数 × 16 qubit = 256 种组合）。仅在参数空间超过 16 组时（如扫频实验中频率步进 > 16 步）才启用寄存器模式。
+
+#### 权重步长 (STEP_CTRL) 选择
+
+`STEP_CTRL` 控制一个权重点覆盖的时钟周期数，直接影响解模精度和最大可支持的解模长度：
+
+| STEP_CTRL | 时钟周期 / 权重点 | 解模精度 | 最大解模长度（时钟周期） | 适用场景 |
+|:---:|:---:|:---:|:---:|:---|
+| 0 | 1 | 最高 | 最短（受权重区容量限制） | 需要精确波形匹配、解模长度较短的场景 |
+| 1 | 2 | 高 | 2× | 常规读出（推荐起点） |
+| 2 | 4 | 中等 | 4× | 包络缓变信号，平衡精度与覆盖长度 |
+| 3 | 8 | 较低 | 8× | 长解模窗口，精度要求不高的场景 |
+| 4 | 16 | 最低 | 16× | 极长解模窗口，粗粒度解模 |
+
+> - 每个时钟周期对应 8 个采样点（ASIC，6 Gsps）或 16 个采样点（FPGA，4 Gsps）。
+> - **选择原则**：STEP_CTRL 越大，相同权重存储空间可覆盖的解模长度越长，但时间分辨率越低。建议从 `STEP_CTRL=1`（1:2）开始，根据所需的解模窗口长度和解模 SNR 是否满足需求逐步调整。
+> - STEP_CTRL 仅 ASIC 平台（系数计算模式）有效，FPGA 平台（系数直读模式）下该位无实际效果。
+
+#### IQ 动态范围 (IQ_SCALE) 选择
+
+`IQ_SCALE` 控制解模结果从累加器（32 位以上）截取到输出位宽时的截位位置：
+
+| IQ_SCALE | 截取位段 | 数值范围 | 适用场景 |
+|:---:|:---|:---:|:---|
+| 0 | [27:8] | 20 位有符号数 | 低增益/短解模长度（推荐默认值） |
+| 1 | [31:12] | 20 位有符号数（高位移位） | 高增益/长解模长度，避免溢出 |
+
+> **选择原则**：若解模结果频繁溢出（I/Q 值达到 ±524287 附近），切换到 `IQ_SCALE=1`；若解模结果幅值过小（有效位数不足），切换到 `IQ_SCALE=0`。可通过采集原始 IQ 数据观察其分布来优化此设置。
+
+#### 两态 vs 三态判定
+
+| TWO_STA_EN | 模式 | 所需直线方程 | 态值 | 适用场景 |
+|:---:|:---|:---|:---|:---|
+| 0 | 三态 | line0, line1, line2（3 组） | 0, 1, 2, 3(错误态) | 量子比特三能级读出（含泄漏态检测） |
+| 1 | 两态 | line0（1 组） | 0, 1 | 标准 0/1 态读出（数据量更小、延迟更低） |
+
+> **建议**：若实验只关心 |0⟩ 和 |1⟩ 两种状态，使能 `TWO_STA_EN=1` 仅配置 line0 即可，可减少配置工作。

chapters/04-04-acq-matched-filter.md

@@ -65,3 +65,42 @@ ez-Q 2.5 FPGA平台使用系数直读模式，其需要额外的存储空间来
 - I路数据偏移地址为 x × 32 KB，Q路数据偏移地址为 x × 32 KB + 16 KB，其中 x 为 Qubit 序号，范围为 0~15。
 
 ![匹配滤波器系数存储结构](../assets/readout_mtf.png)
+
+### 4.4.3. 匹配滤波器系数设计原则
+
+匹配滤波器系数直接影响解模信噪比（SNR）。本小节提供系数设计的基本指导原则。
+
+#### 系数计算模式（ASIC 平台）
+
+ASIC 平台下，匹配滤波器系数由 DDS 载波与权重参数实时计算：
+
+$$\text{FilterCoeff}[n] = \text{Weight}[n] \times e^{j(2\pi f_{IF} \cdot n / F_s + \phi)}$$
+
+其中 $f_{IF}$ 为中频频率（由 `dds_fpw.fcw` 决定），$F_s$ 为采样率。
+
+**权重设计要点**：
+
+1. **权重的包络应匹配输入信号的幅度包络**。理想情况下，权重是输入脉冲波形的时域反转复共轭；
+2. **权重长度**（`mtf_idx.len`）应覆盖输入信号从开始到完全衰减的时间窗口。过短 → SNR 损失；过长 → 引入额外噪声且增加解模延迟；
+3. **STEP_CTRL 优化**：若信号包络变化缓慢，增大 `STEP_CTRL` 可在相同权重存储空间下覆盖更长的解模窗口（见 [§4.3 参数选择指南](04-03-acq-registers.md)）；
+4. **权重归一化**：建议权重系数峰值设为 ±127（8 位有符号数最大值），以充分利用动态范围。
+
+**典型设计流程**：
+1. 采集原始波形数据（`WAVE_SAVE_EN=1`），观察信号幅度和持续时间
+2. 提取信号的幅度包络作为权重初始值
+3. 根据 SNR 需求调整权重长度和 `STEP_CTRL`
+4. 通过解模 IQ 数据的 SNR 验证权重设计效果
+
+#### 系数直读模式（FPGA 平台）
+
+FPGA 平台下，匹配滤波器系数需预计算并直接存入 DAQ_FLT（`0x00580000`），每 qubit 的 I/Q 各 16 KB。
+
+**系数预计算**：
+$$\text{I\_Coeff}[n] = \text{Weight}[n] \times \cos(2\pi f_{IF} \cdot n / F_s + \phi)$$
+$$\text{Q\_Coeff}[n] = \text{Weight}[n] \times \sin(2\pi f_{IF} \cdot n / F_s + \phi)$$
+
+其中每个采样点 n 对应一个时钟周期（FPGA: 16 ADC samples/cycle）。
+
+**存储布局注意**：每个时钟周期的 128 位数据（16 samples × 8 bit）需按大端字节序排列，I/Q 分开存储且地址偏移为 16 KB（见 [§4.4.2](#442-匹配滤波器系数) 存储结构图）。
+
+> **跨平台一致性**：对于同一组解模参数，ASIC 和 FPGA 平台应产生相同的解模结果（在量化误差范围内）。建议在平台移植时，用相同的输入波形验证两个平台的 IQ 输出一致性。

chapters/05-00-exc-model.md

@@ -7,10 +7,10 @@ MCU的指令、MCU的数据、控制寄存器、波形索引表、波形仓库
 - 控制寄存器可用于指定调制频率、调制相位、工作模式等参数；
 - 波形索引表定义了从波形ID到波形地址和长度的映射；
 - 波形仓库定义了波形具体的采样点数据；
-- 混频板配置用于设置变频增益和本振频率；
+- 混频板配置用于设置本振频率（增益为预留接口）；
 - 泵浦板配置用于配置Pump通道的频率和功率等；
 
-> 混频板上变频不支持增益设置，只能设置本振频率，并且上下变频通道共享同一个本振设置，这里不额外赘述了。
+> 混频板上下变频通道共享同一个本振设置。增益为预留接口，支持情况取决于混频板硬件形态。
 
 数字部分（MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库）的编程模型如下图所示：
 ![读出RI-Pump通道控制模型](../assets/readout_ri.png)

chapters/05-02-exc-registers.md

@@ -41,3 +41,45 @@ function的详细控制如下所示：
 * `INTP_SEL`在FPGA平台下受限于DSP资源，只能设置为邻近插值模式。
 * `MIX_MODE`用于直接输出射频信号，由于采用了模拟混频方案，仅使用基带模式。
 * `AWG_MODE`设置AWG模式，实验选用直出模式或者调制模式，其余两种模式用于调试。
+
+### AWG 工作模式选择指南
+
+`func_ctrl` 寄存器的 `AWG_MODE` 字段定义了 AWG 模块的四种工作模式，不同模式适用于不同的实验场景：
+
+| AWG_MODE | 模式名称 | 数据路径 | 典型用途 | 频率灵活性 |
+|:---:|:---|:---|:---|:---|
+| `00` | 直出模式 (Direct) | 波形仓库 → DAC | **量子比特操作**：直接输出包含多频点的基带波形，配合外部模拟混频实现多比特并行读出 | 频率固定（由波形数据决定） |
+| `01` | 调制模式 (Modulation) | 波形仓库 → NCO 混频 → DAC | **腔频扫描**：基带波形为 DC 包络，NCO 频率可由寄存器实时切换实现扫频 | 频率灵活（MCU 实时改 NCO） |
+| `10` | Hilbert 模式 | 波形仓库 → Hilbert 变换 → DAC | **调试**：输出波形的正交分量，用于验证 Hilbert 变换实现 | — |
+| `11` | NCO Only 模式 | NCO → DAC | **性能测试**：输出纯净单音连续波，连接外部仪器测试芯片性能 | 仅输出 NCO 频率 |
+
+**模式选择决策树**：
+
+1. **实验需要输出量子门操作波形** → 使用**直出模式** (`00`)
+   - 波形包含多个读出频率分量，可并行读出多个 qubit
+   - 频率由预计算的基带波形确定，触发后不可实时改变
+   
+2. **实验需要扫频（如腔频扫描、Rabi 振荡）** → 使用**调制模式** (`01`)
+   - 基带波形仅定义脉冲包络，NCO 提供频率灵活性
+   - MCU 可通过写 `frequency` 寄存器实时改变输出频率，无需重新加载波形
+   
+3. **芯片本身性能验证（如相噪、杂散测试）** → 使用**NCO Only 模式** (`11`)
+   - 输出连续波，不受波形仓库长度限制
+   
+4. **验证 Hilbert 变换硬件实现** → 使用**Hilbert 模式** (`10`)
+   - 仅用于调试，正常实验不使用
+
+> **建议**：常规量子实验使用直出模式（`00`）；需要频率扫描的实验使用调制模式（`01`）；Hilbert 和 NCO Only 模式仅在调试和测试阶段使用。
+
+### 输出模式 (NRZ/MIX/HBNRZ/HBMIX) 选择
+
+结合 `MIX_MODE` 和 `INTP_SEL`，AWG 支持四种最终输出模式：
+
+| 输出模式 | MIX_MODE | INTP_SEL | 特点 | 平台支持 | 适用场景 |
+|:---|:---:|:---:|:---|:---|:---|
+| NRZ | 0（基带） | 0（邻近插值） | 基带直出，无插值滤波 | FPGA + ASIC | 外部模拟混频，低频输出 |
+| MIX | 1（混频） | 0（邻近插值） | 混频输出，无插值滤波 | FPGA + ASIC | 射频直出，高频输出 |
+| HBNRZ | 0（基带） | 1（半带插值） | 基带 + 半带插值，平坦度优化 | **仅 ASIC** | 外部模拟混频 + 高平坦度要求 |
+| HBMIX | 1（混频） | 1（半带插值） | 混频 + 半带插值，最佳高频性能 | **仅 ASIC** | 射频直出 + 最优平坦度（推荐 ASIC 高频场景） |
+
+> **当前推荐**：ez-Q 2.5 采用模拟混频方案，所有平台使用 **NRZ 模式**（`MIX_MODE=0, INTP_SEL=0`）。MIX/HBMIX/HBNRZ 模式为 ASIC 平台射频直出方案预留。

chapters/05-05-exc-upconversion.md

@@ -1,11 +1,50 @@
-## 5.5. EXC上变频电路配置
+## 5.5. EXC 上变频电路配置
 
 来自读出基带板输出端口的中频信号需要经过混频板上变频电路处理后才能够被发送到量子芯片。
-前端上变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。
+上变频电路将 DAC 输出的基带/中频信号搬移到量子比特工作频段。
 
-|配置名|描述|
+### 5.5.1. 配置项
-|:-:|:-:|
-|lo_freq|变频本振频率设置|
-|up_gain|上变频增益设置|
 
-> 目前ez-Q 2.5 FPGA平台硬件暂不支持变频增益设置。
+| 配置名 | 描述 | 访问方式 |
+|:-:|:-|:-|
+| `lo_freq` | 变频本振频率设置 | SPI（基地址 `0x00100000`） |
+| `up_gain` | 上变频增益设置 | SPI（预留） |
+
+### 5.5.2. 本振频率配置
+
+`lo_freq` 设置上变频本振频率，输出射频频率由下式确定：
+
+$$F_{RF\_out} = F_{baseband} + F_{LO}$$
+
+或当使用正交调制模式时：
+
+$$F_{RF\_out} = F_{baseband} + F_{NCO} + F_{LO}$$
+
+其中 $F_{baseband}$ 为波形仓库中存储的基带波形频率，$F_{NCO}$ 为 AWG 内部 NCO 调制频率，$F_{LO}$ 为本振频率。
+
+| 参数 | 说明 |
+|:---|:---|
+| 位宽 | 32 比特整数 |
+| 单位 | kHz |
+| 支持范围 | 5,400,000 ~ 5,600,000（即 5.4 ~ 5.6 GHz） |
+
+**配置示例**：输出 $F_{RF\_out}$ = 6.7 GHz 的单音激励信号：
+- 若使用基带直出模式（`awg_mode=0`），基带波形频率 $F_{baseband}$ = 1.2 GHz，$F_{LO}$ = 5.5 GHz → $F_{RF\_out}$ = 6.7 GHz
+- 若使用调制模式（`awg_mode=1`），基带波形为 DC 包络，$F_{NCO}$ = 1.2 GHz，$F_{LO}$ = 5.5 GHz → $F_{RF\_out}$ = 6.7 GHz
+
+### 5.5.3. 共享本振约束
+
+> **重要**：同一块混频板上的**上下变频通道共享同一个本振信号**（寄存器地址同为 `0x00100000`）。这意味着：
+> - 同一混频板的 ACQ（下变频）和 EXC（上变频）使用相同的 $F_{LO}$；
+> - 量子比特的读出频率 $F_{RO}$ 和激励频率 $F_{RI}$ 必须能够用同一个本振覆盖；
+> - 若 $F_{RO}$ 和 $F_{RI}$ 差距过大导致无法共用本振，需将它们分配到不同混频板（不同槽位）。
+
+### 5.5.4. 增益设置
+
+`up_gain` 为预留接口，其支持情况取决于混频板硬件形态。
+
+### 5.5.5. 配置时序
+
+上变频配置应在 MCU 触发之前通过 SPI 完成。配置写入后需等待本振锁相环（PLL）锁定，建议在初始化阶段完成配置。
+
+配置顺序：SPI 写混频板寄存器 → 等待 PLL 锁定 → 配置 AWG 寄存器 → 加载波形 → 加载 MCU 程序 → 等待触发。

chapters/05-06-pump-config.md

@@ -1,15 +1,48 @@
-## 5.6. Pump模拟电路配置
+## 5.6. Pump 模拟电路配置
 
-对处理器Pump通道的编程包括模拟电路配置项和使能配置项。模拟电路用于将Pump通道配置输出一个指定功率和频率的微波信号，而使能配置项用于控制微波信号的实时开关。
+对处理器 Pump 通道的编程包括模拟电路配置项和使能配置项。模拟电路用于将 Pump 通道配置输出一个指定功率和频率的微波信号，而使能配置项用于控制微波信号的实时开关。
 
-Pump输出时，需要使能输出并配置好输出频率和功率，以下是具体配置项。
+### 5.6.1. 配置项
 
-|配置名|描述|
+| 配置名 | 描述 | 访问方式 |
-|:-|:-|
+|:-|:-|:-|
-|pump_freq|pump信号输出频率|
+| `pump_freq` | Pump 信号输出频率 | SPI（ch0 基址 `0x00200000`） |
-|pump_power|pump信号输出功率|
+| `pump_power` | Pump 信号输出功率 | SPI（ch0 基址 `0x00300000`） |
-|pump_enable|pump信号输出使能|
+| `pump_enable` | Pump 信号输出使能 | SPI（ch0 基址 `0x00400000`） |
 
-* pump_freq: 32比特整数，范围[7000000, 9000000], 单位是kHz
+### 5.6.2. 频率配置
-* pump_power: 32比特整数，范围[-1100, -300]， 具体映射关系取决于硬件
+
-* pump_enable: `32'h11` 为使能（开），`32'h00` 为关闭（关）
+| 参数 | 说明 |
+|:---|:---|
+| 位宽 | 32 比特整数 |
+| 单位 | kHz |
+| 取值范围 | 7,000,000 ~ 9,000,000（即 7.0 ~ 9.0 GHz） |
+
+### 5.6.3. 功率配置
+
+| 参数 | 说明 |
+|:---|:---|
+| 位宽 | 32 比特整数 |
+| 取值范围 | -1100 ~ -300 |
+
+> **注意**：`pump_power` 的值与最终输出功率之间的映射关系取决于泵浦板的硬件校准数据，实际使用时应参照具体硬件的校准表进行修正。不同槽位的 Pump 板可能有不同的校准曲线。
+
+### 5.6.4. 使能控制
+
+Pump 输出采用**两级使能**机制：
+
+| 级别 | 控制方式 | 说明 |
+|:---|:---|:---|
+| 硬件使能 | `pump_enable` 寄存器（SPI 配置） | `32'h11` = 使能输出通道，`32'h00` = 完全关闭。设为 `32'h00` 时，无论 MCU 码字如何设置，Pump 均无输出 |
+| 脉冲使能 | MCU 码字 `PUMP_EN` 位（实时控制） | 在硬件使能开启的前提下，每帧触发时通过码字实时控制 Pump 脉冲的发出与关闭 |
+
+> **建议**：初始化阶段通过 SPI 设置 `pump_enable = 32'h11` 打开硬件使能，实验中通过 MCU 码字的 `PUMP_EN` 位控制 Pump 脉冲的实时输出，避免 Pump 信号持续输出加热制冷机。仅在长期不需要 Pump 输出时（如设备维护）才将 `pump_enable` 设为 `32'h00` 完全关闭。
+
+### 5.6.5. Pump 脉冲时序
+
+Pump 脉冲的时序由 AWG 模块的 `pump_ctrl` 寄存器控制（见 [§5.2](05-02-exc-registers.md)）：
+
+- **延迟 (delay)**：从 MCU 码字触发到 Pump 脉冲开始的时钟周期数
+- **宽度 (width)**：Pump 脉冲持续的时钟周期数
+
+Pump 脉冲应在激励波形输出前开始（提前稳定），在激励波形结束后关闭（保证完整覆盖）。`delay` 和 `width` 根据实际波形的持续时长和 Pump 通道的开启稳定时间来确定。

chapters/80-appendix-ids-table.md

@@ -12,7 +12,7 @@
 
 1. **网络地址（IP）** — 定位机箱。软件通过指定目标机箱的 IP 地址来确定与哪个机箱内的板卡通信。一个机箱内可安装多块 PXIe 板卡，IP 地址是整个通信链路的起点。
 
-2. **扩展地址（Exaddr）** — 定位槽位和总线。[7:3]对应槽位号，exaddr[2:0]对应总线号。读出基带板允许安装在4或者15槽，泵浦板和混频板分别在左右相邻位置，因此软件仅需指定基带板槽位号即可定位全部三个板卡。
+2. **扩展地址（Exaddr）** — 定位槽位和总线。[7:3]对应槽位号，exaddr[2:0]对应总线号。读出基带板允许安装在4或者15槽，混频和泵浦功能单元位于基带板相邻槽位（分离形态下混频板和泵浦板分别在基带板左右两侧；合并形态下混频/泵浦合板位于基带板右侧槽位）。软件仅需指定基带板槽位号即可定位全部功能单元。
 
 3. **片选地址（Cid）** — 定位总线上芯片ID。采用5比特编码最大支持32颗芯片挂载到同一个spi总线上，在当前的实现中，直接使用总线编址通道号，每个芯片独占一个总线，因此Cid固定为0。
 

chapters/81-appendix-troubleshooting.md

@@ -0,0 +1,110 @@
+# 附录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 确认帧格式，再逐步增加复杂度。

project.yaml

@@ -2,7 +2,7 @@
 title: ez-Q 2.5 读出子系统编程控制模型
 subtitle: 
 author: 郭成
-version: V0.3
+version: V0.4
 doc_type: 用户手册
 logo: assets/logo.png  # 封面 logo 路径（需明确指定；不指定则无 logo）
 lang: zh-CN
@@ -26,4 +26,5 @@ chapters:
   - 05-05-exc-upconversion.md
   - 05-06-pump-config.md
   - 05-07-exc-pipeline-demo.md
-  - 80-appendix-ids-table.md
+  - 80-appendix-ids-table.md
+  - 81-appendix-troubleshooting.md