readout_program/读出子系统编程控制模型.md

---
export_on_save:
  html: true

html:
  toc: true
  embed_local_images: true
  embed_svg: true

title: 读出子系统历史无关功能配置项
author: 郭成
date: 
---

# 1. 修订记录
|版本|修订日期|修订原因|修订内容|修订人|
|:-|:-|:-|:-|:-|
|v0.1|2025/10/27|统一格式|初始版本|郭成|
|v0.2|2025/10/31|评审意见|内容补充|郭成|

# 2. 前言
## 2.1. 目的与范围
本文档的目的是介绍读出芯片激励产生和采集处理相关控制，
该文档适用于ez-Q 2.5 FPGA/ASIC平台读出子系统编程。
本文档作为开放文档供大家阅读。

## 2.2. 阅读对象
本文档的预期读者是所有使用本芯片的用户以及对该芯片工作原理感兴趣的读者。

## 2.3. 文档概述
本文档首先介绍了测控系统总体的编程对象和规范，
针对读出ACQ/EXCT/Pump三种类型通道对应的ACQ/EXCT-Pump编程模型进行了详细介绍。

## 2.4. 引用文档
|文档编号|标题|版本|
|:-|:-|:-|
|-|读出子系统历史无关配置集.md|V1.0|
|-|读出子系统IDS表.xls|V1.0|
|ez-Q 2.5-SDD-04|ez-Q 2.5 测控系统研制项目指令集设计报告_V1.0.docx|V1.0|

## 2.5. 术语定义
|名字|全称|解释|
|:-|:-|:-|
|ACQ|Acquisition|读出回波采集处理通道|
|EXCT|Excitation|读出激励生成发送通道|

# 3. 编程控制模型概述

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

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

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

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

通道寄存器配置数据支持微控制器实时修改，从而让通道的输入/输出控制具备动态控制能力。
ACQ和EXCT-Pump通道配置寄存器定义参考[读出子系统IDS表.xls](TODO)的`DAQ_REG`和`AWG_REG`页。
ACQ的配置数据定义参考

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

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

针对具体的指令定义和使用方法，
读者可查看[《量子编程指令集》](TODO)了解相关信息。


## 3.2. 2 读出子系统编程
ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出泵浦板三个硬件组成
- 三个板卡以PXIe板卡的形式安装在机箱中位置相邻的三个槽位上
- 混频板的槽位号比基带板大1，泵浦板槽位号比基带板槽位号小1

因此可以通过仅指定读出基带板槽位号来定位混频板和泵浦板槽位号，
读出子系统硬件架构如下图所示。
- 读出基带板负责产生、输出、采集和处理基带信号以及为泵浦通道产生使能信号；
- 读出混频板自身产生一个本振信号，用于实现基带信号与射频信号之间的转换；
- 而读出泵浦板负责产生一个指定功率频率的单音信号，并在外部使能信号控制下输出；

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

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

```
索引基地址由《读出子系统IDS表.xls》的mapping页定义，本文不对地址翻译进行赘述。
```

本文所述的三类编程通道具体定义如下：
* ACQ 编程通道定义从混频板`rf_in`输入端口到基带板卡内部DAQ模块；
* EXCT 编程通道定义为从基带板内部AWG模块混频板到`rf_out`接口；
* Pump 编程通道定义为从基带板卡内部AWG模块到泵浦板`pump_out`接口；

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

# 4. 处理器ACQ通道编程模型

@import "ro_datapath.md"

## 4.1. 下变频电路配置

来自量子比特RO端口的射频信号需要经过前端模拟电路处理后才能够被读出基带处理单元采集处理。
前端下变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。

|配置名|描述|
|:-:|:-:|
|lo_freq|变频本振频率设置|
|mix_gain|下变频增益设置|

```
目前ez-Q 2.5 FPGA平台暂不支持下变频增益
mix_gain 设置；仅支持 lo_freq 变频本振频率设置
```

## 4.2. ACQ码字功能定义
@import "ro_codeword.md"

## 4.3. ACQ寄存器功能定义
ACQ通道寄存器的地址空间可以被SPI和MCU同时访问，
因此用户可通过SPI或者MCU设置参数，建议：
```
静态参数通过SPI配置完成就保持不变，
需要动态控制的参数通过MCU来实时更新。
```

|名字|功能描述|
|:-|:-|
|function|DAQ功能控制，控制运行模式等|
|sample_depth|波形采样深度控制，单位是时钟周期个数|
|mtf_idx_q[15:0]|解模参数控制，分别对应16个频点|
|dds_fpw_q[15:0]|解模频率相位控制，分别对应16个频点|

- sample_depth用于控制波形采集模式下采集波形的长度，单位是时钟周期；
- mtf_idx_q在使能寄存器控制情况下，用于直接索引匹配滤波器权重/系数；
  - 高16比特对应索引地址，单位是时钟周期
  - 低16比特对应索引长度，单位是时钟周期
- dds_fpw_q在使能寄存器控制情况下，用于控制解模载波的频率和相位；
  - 高20位对应载波频率控制字fcw，$F_{c}=fcw/2^{20}*sample\_rate$
  - 低12位对应载波相位控制字pcw，$\phi_{c} = pcw/2^{12}*2*\pi$
- function用来控制整个读出基带板数据处理行为；

function功能寄存器与实验控制相关的具体控制位包括：

|比特位|名字|功能描述|
|:-|:-|:-|
|[15:8]|WEIGHT_IQ| 常数权重值，8比特有符号数|
|[7]|CONST_EN| 常数权重使能, 高有效|
|[6:4]|STEP_CTRL| 计算权重模式步长控制|
|[3]|IQ_SCALE| 解模动态范围设置|
|[2]|TWO_STA_EN| 两态读出使能, 高电平使能|

* WEIGHT_IQ 常数权重值，可用于长时间解模
* CONST_EN 常数权重使能
  * `CONST_EN=0`时，权重数据通过`mtf_idx_q`来索引得到
  * `CONST_EN=1`来启用常量权重功能，此时权重值为`WEIGHT_IQ`。
* STEP_CTRL 权重点步长控制
  - `STEP_CTRL==0` 1个权重数据点可对应1个时钟周期采样点。
  - `STEP_CTRL==1` 1个权重数据点可对应2个时钟周期采样点。
  - `STEP_CTRL==2` 1个权重数据点可对应4个时钟周期采样点。
  - `STEP_CTRL==3` 1个权重数据点可对应8个时钟周期采样点。
  - `STEP_CTRL==4` 1个权重数据点可对应16个时钟周期采样点。
* IQ_SCALE 解模结果截断位置控制
  - `IQ_SCALE =0` IQ结果截位[27:8]
  - `IQ_SCALE =1` IQ结果截位[31:12]
* TWO_STA_EN 两态读出使能
  - `TWO_STA_EN==0` 默认三态读出
  - `TWO_STA_EN==1` 使能二态读出

```
ez-Q 2.5 FPGA平台采用系数直读模式，因此不支持系数生产相关功能。
即在ez-Q 2.5 FPGA平台下，dds_fpw 寄存器无实际效果;
function寄存器WEIGHT_IQ，CONST_EN, STEP_CTRL 位无实际效果
```
解模完成后，可以通过`TWO_STA_EN`来控制是否启动2态判定，
当`TWO_STA_EN=1`时，可以只配置一组直线方程系数进行态判断。

## 4.4. 匹配滤波器
匹配滤波器在FPGA/ASIC两种平台下由于资源不同实现的形式也不同，区别如下：
* 由于ASIC多计算少存储，因而ASIC平台使用系数计算模式以节省存储资源。
* 由于FPGA 多存储少计算，因此FPGA平台使用系数直读模式以节省DSP资源。

### 4.4.1. 读出参数存储


系数计算模式下，匹配滤波器的系数由DDS生成的载波乘以权重参数得到。
- 载波的频率和相位由dds_pfd控制，其高20为作为频率控制字，低12位作为相位控制字。
- 权重参数的选择由mtf_idx控制，其高16位作为地址，低16位作为长度。
- mtf_idx索引得到的权重数据颗粒度是权重数据点，一个数据点可对应多个周期采样点；
- 寄存器dds_pfw_q 和mtf_idx_q 的详细定义与查找表中定义保持相同。

读出系统的的读出参数存储格式如下图所示。
FPGA平台下的系数直读模式只使用`Ctrl`部分中的数据，并忽略`dds_pfw`控制字.

![读出ACQ通道控制模型](./assets/readout_para.png)

### 4.4.2. 匹配滤波器系数

ez-Q 2.5 FPGA平台使用系数直读模式，其需要额外的存储空间来配置匹配滤波器系数。
- 其中mtf_idx的含义从索引权重数据变为索引匹配滤波器系数。
- 匹配滤波器系数索引的粒度是时钟周期，
  - 在FPGA平台下每个时钟周期对应16个采样点数据。
- 匹配滤波器系数采样点采用8比特数据位宽，因此1个周期数据位宽为128 bit，

匹配滤波器系数存储结构如下图所示。
- 匹配滤波器的I和Q数据分开存储，每个比特的I、Q数据容量分别为16 KB。
- I路数据偏移地址为x*32KB，Q路数据偏移地址为x*32KB+16 KB，其中x为Qubit序号，范围为0~15。

![读出ACQ通道控制模型](./assets/readout_mtf.png)

## 4.5. 采集数据处理
ACQ通道采集的数据以流的形式按照先后顺序缓存，
缓存到设定数据量后或者计时器超时后数据被打包成帧上传，
上位机驱动解帧后以流模式将数据返回给调用接口。
当采集多种数据时，用户需要维护采集数据的顺序，
从而解析返回数据的含义。
建议一个实验仅仅采集一种类型数据以简化数据处理。

### 4.5.1. 采集波形数据
* FPGA平台1个时钟周期对应16个采样点（16字节）
* 数据采用大端字节序，数据遵循先采先到顺序

### 4.5.2. 采集IQ数据
* 1个完整的数据包含I,Q（8字节）
* I先到达，Q后到达
* I, Q数据采用大端字节，都占用4个字节

### 4.5.3. 采集态数据
* 1个完整数据包含16个qubit态信息（4字节）
* 每个量子比特态信息用2个比特表示
* 高位表示高序号，即32比特对应{q15,q14,...,q0};

### 4.5.4. 采态计数数据
* 1个完整数据包含4个计数器数据（16字节）
* 4个计数数据顺序为0态计数器、1态计数器、2态计数器、3态计数器
* 计数器采用大端字节序，为32比特无符号数

# 5. 处理器EXCT-Pump编程模型

@import "ri_datapath.md"

## 5.1. 1 码字功能定义
@import "ri_codeword.md"

## 5.2. 2 寄存器功能定义
EXCT-Pump通道的全部寄存器可以被SPI和MCU同时访问，
用户可以根据需要决定使用SPI还是MCU来控制寄存器的值。
|名字|功能描述|
|:-|:-|
|wave_ctrl|寄存器索引波形，包含地址和长度信息|
|amplitude|波形输出调制幅度|
|Frequency|调制载波频率|
|Phase|调制载波相位|
|Function|AWG工作模式定义|
|pump_ctrl|pump使能脉冲控制|
|mark_ctrl|标记使能脉冲控制|

- `wave_ctrl`波形输出直接控制，可直接从波形仓库取采样点输出。
  - 高16位为索引地址，单位是时钟周期
  - 低16为为索引长度，单位是时钟周期
- `amplitude`调制幅度控制字
  - 高16为幅度控制字acw，范围0\~16384，归一化幅度$Amp = acw/2^{16}$
- `frequency`调制频率控制
  - 32比特频率控制字fcw，$F_{nco}= fcw/2^{32}*F_s$，其中$F_s$是输出采样率。
- `phase`调制相位控制
  - 高16位相位控制字pcw： $\phi_{nco} = pcw/2^{16}*2*\pi$。
- `funciton`寄存器用于设置AWG的工作模式
- `pump_ctrl`泵浦脉冲使能控制
  - 高16位控制输出延迟时钟周期，范围（1~65535）
  - 低16位控制附加持续时钟周期，范围（1~65535）
- `mark_ctrl`标记脉冲使能控制
  - 高16位控制输出延迟时钟周期，范围（1~65535）
  - 低16位控制脉冲持续时钟周期，范围（1~65535）

function的详细控制如下所示：
|比特位|名字|功能描述|
|:-|:-|:-|
|[3]|INTP_SEL| 插值模式选择，1：半带插值，0：邻近插值|
|[2]|MIX_MODE| 混频模式选择，1：混频模式，0：基带模式|
|[1:0]|AWG_MODE| AWG模式, 00：直出，01：调制，10：Hilbert，11：NCO|

* `INTP_SEL`在FPGA平台下受限于DSP资源，只能设置为邻近插值模式。
* `MIX_MODE`用于直接输出射频信号，由于采用了模拟混频方案，仅使用基带模式。
* `AWG_MODE`设置AWG模式，实验选用直出模式或者调制模式，其余两种模式用于调试。

## 5.3. 3 波形索引表定义
波形查找表的深度为256条（1 kB），每个条目的位宽为32比特，
其通过8比特的波形id来索引输出波形的参数（地址和长度），最大支持256种不同的输出波形。

索引表格式定义如下图所示： wave_id是mcu产生的码字，其可以作为地址索引波形控制参数。
波形控制参数包括波形地址`addr`和波形长度`len`参数，颗粒度是时钟周期。


![波形查找表和波形仓库](./assets/readout_lut.png)

## 5.4. 4 波形仓库定义
* ASIC平台下，每个时钟周期对应8个采样点，采样点个数需要为8的整数倍，数据更新率为6 Gsps，每个采样点持续时间为167 皮秒(6 GS/s)。
* 在FPGA平台下，每个时钟周期对应16个采样点，采样点个数需要为16的整数倍，数据更新率为 4 GSps，每个采样点持续时间为250皮秒。
* 每个采样点为16比特的二进制补码数据；
* 波形仓库的容量为128 KB，在FPGA平台和ASIC平台下最大分别支持16 us和10 us波形输出。

对于EXCT输出频率$F_{out}$（例如6.7 GHz），在本振为$F_{LO}$(例如5.5GHz)本振频率下，
则存储区描绘的基带波形频率$F_{s}$为1.2 GHz ，$F_s = F_{out} - F_{LO}$。


## 5.5. 5 EXCT上变频电路配置
来自读出基带板输出端口的中频信号需要经过混频板上变频电路处理后才能够被发送到量子芯片。
前端上变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。
目前ez-Q 2.5 FPGA平台硬件暂不支持变频增益设置。
|配置名|描述|
|:-:|:-:|
|lo_freq|变频本振频率设置|

* lo_freq：32比特整数，范围[5400000, 5600000]单位是kHz

## 5.6. 6 Pump模拟电路配置
对处理器Pump通道的编程包括模拟电路配置项和使能配置项。模拟电路用于将Pump通道配置输出一个指定功率和频率的微波信号，而使能配置项用于控制微波信号的实时开关。

Pump输出时，需要使能输出并配置好输出频率和功率，以下是具体配置项。
|配置名|描述|
|:-|:-|
|pump_freq|pump信号输出频率|
|pump_power|pump信号输出功率|
|pump_enable|pump信号输出使能|

* pump_freq: 32比特整数，范围[7000000, 9000000], 单位是kHz
* pump_power: 32比特整数，范围[-1100, -300]， 具体映射关系取决于硬件
* pump_enable: 0x11 为使能，0x00为关闭