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

[TOC]

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

# 1. 前言
## 1.1. 目的与范围
本文档的目的是介绍读出芯片激励产生和采集处理相关控制，
本文档作为开放文档供大家阅读。

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

## 1.3. 文档概述
本文档首先介绍了测控系统总体的编程对象和规范，
针对读出相关的三种类型通道的编程进行了详细介绍。
读出三类通道中，EXC和ACQ通道控制较为复杂，其包含MCU编程控制。
针对这两个通道，本文详细介绍了MCU码字定义、
寄存器控制和相关存储区配置。

## 1.4. 引用文档
|文档编号|标题|版本|
|:-|:-|:-|
|-|读出子系统历史无关配置集|V1.0|
|-|读出子系统IDS表|-|

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

# 2. 编程控制模型概述

## 2.1 测控系统编程概述
超导量子计算机利用微波信号来驱动量子比特和读出量子比特状态，量子比特不同类型的操作依赖不同类型的信号来控制。
ez-Q 2.5测控系统包含5种物理通道，对应5类硬件接口，分别是处理器EXC、处理器ACQ、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信号|^|

- 测控系统中的每种控制模型实现的功能都是通过微控制器发出的码字+当前寄存器+配置数据+模拟电路配置这4种数据来定义，
其中部分寄存器状态支持微控制器实时修改，从而让通道的输入/输出控制具备动态控制能力。
- 测控系统的寄存器、配置数据和模拟电路配置返回数据统一采用**大端字节序**。

本文档通过对不同编程模型下码字定义、控制寄存器、配置数据和模拟电路设置进行介绍，旨在让用户能够对信号的产生和处理进行编程控制。针对实验流程和码字产生的编程，读者需要查看对应指令集文档或者编程语言文档。


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

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

```
在ez-Q 2.5 FPGA平台读出子系统混频板和泵浦板复用同一个硬件板卡。
```

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

当软件需要对不同通道编程时，其通过ip地址指定机箱、通过槽位号指定板卡、
通过扩展地址指定同一个板卡内的多个通道、通过地址指定一个通道内的不同配置项。
```
地址维护由专门的表来定义，本文不对地址翻译进行赘述。
```

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

@import "ro_datapath.md"

## 3.1.	模拟调理电路配置

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

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

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

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

## 3.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在使能寄存器控制情况下，用于直接索引匹配滤波器权重/系数；
- dds_fpw_q在使能寄存器控制情况下，用于控制解模的频率和相位；
- function用来控制整个读出基带板数据处理行为；

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

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

系数计算模式支持通过设置`CONST_EN=1`来启用常量权重功能，此时权重值为`WEIGHT_IQ`。
而当`CONST_EN=0`时，权重数据通过`mtf_idx_q`来索引得到，
并通过`STEP_CTRL`控制每个权重值对应多少个时钟周期的采样点。
```
ez-Q 2.5 FPGA平台采用系数直读模式，因此不支持上述功能。
即在ez-Q 2.5平台下，WEIGHT_IQ，CONST_EN 控制位无实际效果
```
解模完成后，可以通过`TWO_STA_EN`来控制是否启动2态判定，
当`TWO_STA_EN=1`时，可以只配置一组直线方程系数进行态判断。

## 3.4 匹配滤波器
匹配滤波器在FPGA/ASIC两种平台下由于资源不同实现的形式也不同。

### 3.4.1 ASIC平台
由于ASIC多计算少存储，因而ASIC平台时使用系数计算模式。

系数计算模式下，匹配滤波器的系数由DDS生成的载波乘以权重参数得到。
- 其中载波的频率和相位由dds_pfd控制，其高20为作为频率控制字，低12位作为相位控制字。
- 权重参数的选择由mtf_idx控制，其高16位作为地址，低16位作为长度。
- 寄存器dds_pfw_q 和mtf_idx_q 的详细定义与查找表中定义保持相同。

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

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

### 3.4.2 FPGA平台
由于FPGA 多存储少计算资源，因此FPGA平台时使用系数直读模式以节省DSP资源。

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)

```
ez-Q 2.5平台为FPGA平台
```

# 4. 处理器EXC-Pump编程模型

@import "ri_datapath.md"

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

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

- `wave_ctrl`的格式定义保持和波形索引表格式相同，绕过波形查找表，直接控制AWG波形输出。
- `amplitude`高16为用于设置调幅幅度，码值范围0\~16384，对应归一化范围0~1。
- `frequency`对应NCO的48位FCW的高32位，而FCW的低16位恒为0。
$F_{nco}= fcw/2^{48}*F_s$。其中`F_s`是输出采样率。
- `phase`寄存器的高16位用于设置NCO的相位控制字（PCW），
$\phi_{nco} = pcw/2^{16}*2*\pi$。
- `funciton`寄存器和实验相关的控制包括：

|比特位|名字|功能描述|
|:-|:-|:-|
|[3]|INTP_SEL| 插值模式选择，1：半带插值，0：邻近插值|
|[2]|MIX_MODE| 混频模式，用于将采用率翻倍|
|[1:0]|AWG_MODE| AWG工作模式, 直出、调制、NCO、Hilbert|

```
对于实验一般选用直出模式或者调制模式，其余两种模式用于调试。
```

```
MIX_MODE用于直接输出射频信号，由于采用了模拟混频方案，不使能该功能。
```
```
`INTP_SEL`在FPGA平台下受限于DSP资源，只能设置为邻近插值模式。
```

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

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

```
ezq2.5 ASIC平台下读出地址和长度单位是8个采样点；
ezq2.5 FPGA平台下读出地址和长度单位是16个采样点。
```

```
每个采样点为16比特的二进制补码数据。
```

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


## 4.4 波形仓库定义
ASIC平台下，每个时钟周期对应8个采样点，
数据更新率为6 Gsps，每个采样点持续时间为167 皮秒(6 GS/s)。
在FPGA平台下，每个时钟周期对应16个采样点，
数据更新率为 4 GSps，每个采样点持续时间为250皮秒。
对于EXC输出频率F（例如6.7 GHz），在本振为5.5GHz本振频率下，
则存储区描绘的基带波形频率为1.2 GHz ，等于F（6.7 GHz）-本振（5.5 GHz）。
波形仓库的容量为128 KB，在FPGA平台和ASIC平台下最大分别支持16 us和10 us波形输出。

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

# 5. 处理器Pump编程模型

对处理器Pump通道的编程包括模拟电路配置项和使能配置项。模拟电路用于将Pump通道配置输出一个指定功率和频率的微波信号，而使能配置项用于控制微波信号的实时开关。
## 5.1 模拟配置项定义
Pump输出时，需要使能输出并配置好输出频率和功率，以下是具体配置项。
|配置名|描述|
|:-|:-|
|pump_freq|pump信号输出频率|
|pump_power|pump信号输出功率|
|pump_enable|pump信号输出使能|

## 5.2 输出使能配置项定义
Pump通道的输出使能配置采用处理器EXC-Pump通道编程模型，
其寄存器控制和码字控制参考处理器EXC-Pump编程模型，这里不再赘述。