readout_program/chapters/03-overview.md

# 3. 编程控制模型概述

## 3.1. 测控系统编程概述

超导量子计算机利用微波信号来驱动量子比特和读出量子比特状态，量子比特不同类型的操作依赖不同类型的信号来控制。
ez-Q 2.5测控系统包含5种物理通道，对应5类硬件接口，分别是ACQ、EXC、Pump、XYZ/Reset和ZCP通道；
系统具有7种控制信号，对应7种编程对象，分别是EXC、ACQ、Pump、XY、Reset、Z和ZCP信号；
系统具有4种控制模型，对应4种编程类型，分别是ACQ、EXC-Pump、XY/Reset和Z/ZCP模型，分类关系如下表所示。

|5种物理通道|7种控制对象|4种控制模型|
|:-:|:-:|:-:|
|XYZ通道|XY 信号|XY/Reset控制模型|
|^|Reset信号|^|
|^|Z信号|Z/ZCP控制模型|
|ZCP通道|ZCP信号|Z/ZCP控制模型|
|ACQ通道|ACQ(RO)信号|ACQ控制模型|
|EXC通道|EXC(RI)信号|EXC-Pump控制模型|
|Pump通道|Pump信号|^|

- 测控系统中的每种控制模型实现的功能都是通过以下四类数据进行定义，
    - 通道微控制器码字指令
    - 通道寄存器配置数据
    - 通道SRAM配置数据
    - 通道模拟电路配置

- 测控系统的寄存器、配置数据和模拟电路配置返回数据统一采用**大端字节序**。

通道寄存器配置数据支持微控制器实时修改，从而让通道的输入/输出控制具备动态控制能力。
ACQ和EXC-Pump通道配置寄存器的地址索引定义详见[附录A. IDS寄存器索引表](#a-ids)的 [A.2 DAQ_REG](#a2-daq_reg-acq) 和 [A.3 AWG_REG](#a3-awg_reg-exc-pump) 节。

本文档通过对不同编程模型下码字指令、通道寄存器配置数据、通道SRAM配置数据和通道模拟电路配置进行介绍，
旨在让用户掌握对读出激励信号的产生和采集信号处理的编程方法。
其中码字指令通过MCU来产生，MCU的编程关键参数如下：

* ACQ通道和EXC-Pump通道使用**相同MCU**；
* MCU分别使用**16 KB**的ITCM和DTCM；
* FPGA平台MCU主时钟频率为**250 MHz**，
* ASIC平台MCU主时钟频率为**750 MHz**；
* MCU以固定的**3个时钟周期每指令**的速度运行；
* MCU通过**0x100000**地址访问MCU数据空间；
* MCU通过**0x200000**地址访问通道配置寄存器空间；

针对具体的指令定义和使用方法，
读者可查看[《量子编程指令集》](引用文档 ez-Q 2.5-SDD-04)了解相关信息。

## 3.2. 读者阅读路径

本文档按"先总览、再分通道、最后附录"的结构组织，建议按以下路径阅读：

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 板卡上，与基带板相邻安装。

两种形态在编程模型上**完全一致**——软件通过指定基带板槽位号定位混频和泵浦功能单元，寄存器接口无差异。
下文以分离形态为例进行描述，除槽位布局外所有内容对两种形态均适用。

- 读出基带板负责产生、输出、采集和处理基带信号以及为泵浦通道产生使能信号；
- 读出混频板自身产生一个本振信号，用于实现基带信号与射频信号之间的转换；
- 而读出泵浦板负责产生一个指定功率频率的单音信号，并在外部使能信号控制下输出；

![读出子系统组成](../assets/readout_system.png)

当软件需要对不同通道编程时，其通过ip地址指定机箱、通过槽位号指定板卡、
通过扩展地址指定同一个板卡内的多个通道、通过地址指定一个通道内的不同配置项。

索引基地址定义详见[附录A. IDS寄存器索引表](#a-ids)的 [A.1 地址空间映射](#a1) 节。

本文所述的三类编程通道具体定义如下：

* ACQ 编程通道定义从混频板`rf_in`输入端口到基带板卡内部DAQ模块；
* EXC 编程通道定义为从基带板内部AWG模块混频板到`rf_out`接口；
* Pump 编程通道定义为从基带板卡内部AWG模块到泵浦板`pump_out`接口；

ASIC和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