# 1. 编程控制模型概述

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

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

测控系统中的每种控制模型实现的功能都是通过微控制器发出的码字+当前寄存器+配置数据+模拟电路配置这4种数据来定义，
其中部分寄存器状态支持微控制器实时修改，从而让通道的输入/输出控制具备动态控制能力。
测控系统的寄存器、配置数据和模拟电路配置返回数据统一采用大端字节序。
本文档通过对不同编程模型下码字定义、控制寄存器、配置数据和模拟电路设置进行介绍，旨在让用户能够对信号的产生和处理进行编程控制。针对实验流程和码字产生的编程，读者需要查看对应指令集文档或者编程语言文档。


## 1.2 读出子系统编程
ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出泵浦板三个硬件组成，
三个板卡以PXIe板卡的形式安装在机箱中位置相邻的三个槽位上，
混频板的槽位号比基带板大1，泵浦板槽位号比基带板槽位号小1，
因此可以通过仅指定读出基带板槽位号来定位混频板和泵浦板槽位号，
读出子系统硬件架构如下图所示。
读出基带板负责产生、输出、采集和处理基带信号以及为泵浦通道产生使能信号；
读出混频板通过产生一个本振信号，用于实现基带信号与射频信号之间的转换，
而读出泵浦板负责产生一个指定功率频率的单音信号，并利用外部使能信号来实时使能微波信号的输出。
在ez-Q 2.5 FPGA平台读出子系统混频板和泵浦板复用同一个硬件板卡。

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

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

# 2. 处理器RO编程模型

来自量子芯片RO端口的射频信号首先经过混频板模拟电路调理后进入读出基带处理单元采集处理。
混频板模拟调理电路主要负责将输入功率和频率的信号转换成基带板卡能够处理的中频信号，
对模拟调理电路的编程包括变频增益控制和变频本振频率控制。
对读出基带单元RO通道的编程包括：MCU的指令、MCU的数据、RO通道控制寄存器、解模参数四类数据。
其中MCU指令+MCU数据可用于编程发出触发码字以及实时修改控制寄存器；
控制寄存器可用于指定解模频率、解模相位、解模权重数据索引地址和长度等参数；
解模参数数据定义了具体的权重数据和量子态判断参数等数据。下图是RO通道的编程控制模型。
![读出RO通道控制模型](./assets/readout_ro.png)

射频信号经过混频板下变频后进入到ADC，ADC采集的原始波形数据①从图中右侧端口输入，接着输入到解模模块中，
解模模块利用匹配滤波器模块生成的解模参数对输入波形进行解模运算得到IQ数据②，
接着解模IQ数据②输入到态判断模块中，经过态判定后得到态数据④，
最后态数据④经过态统计后得到态统计结果⑤。
上述过程中，数据①②③④⑤都可以在数据转发模块缓存后通过`rslt_push`接口发送出去，
需要注意到的是数据②是解模求和数据③在求和次数为1的特殊情况。
由于RO通道有且仅有基带处理单元存在状态机，因此需要考虑到异常状态恢复，因此RO通道提供了软复位功能
当RO通道由于上位机强制中断或者MCU配置了错误指令而产生异常时，可以通过调用驱动API函数执行复位操作，
其能够将状态机从异常中复位（同时也复位部分寄存器的默认值），
从而使得下一次历史无关配置项能够正确执行。

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

来自量子比特RO端口的射频信号需要经过前端模拟电路处理后才能够被读出基带处理单元采集处理。
前端模拟调理电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。
目前ez-Q 2.5 FPGA平台暂不支持变频增益`mix_gain`设置。
|配置名|描述|
|:-:|:-:|
|lo_freq|变频本振频率设置|
|mix_gain|下变频增益设置|

## 2.2.	RO码字功能定义
RO通道通过产生32位的码字来控制读出行为，32位的操控码字功能定义如下表所示。
码字比特[3:0]用于选择要实时从存储中加载的解模和态判断参数，总共支持16组参数进行快速切换；
解模包络参数和频率参数也可以通过码字比特[11:10]来选择寄存器控制还是查找表控制。
寄存器控制可以实时修改解模产生，而查找表控制可以支持参数快速切换。
码字比特[5:4]用于对解模数据进行统计操作，通过实时统计可降低芯片外传数据量；
码字比特[7:6]用于将读出比特数据通过并行和串行接口发出，用于支持系统局部和全局反馈功能；
码字比特[9:8]用于对统计数据进行清零；
码字比特[15:11]用于使能要存储几种数据模式，四种数据仅能在部分条件下支持同时存储，
同时存储多种数据时，死时间会增加，推荐实验过程中一次指令仅能使能一种数据；
码字比特 [31:16]用于使能对对每个比特的控制，读出芯片最大支持16个量子比特。

|比特位|名字|功能描述|
|:-|:-|:-|
|[31:16]|QUBIT_EN| 16个量子比特使能，高电平使能对应位量子比特|
|[15]|COUNT_SAVE_EN| 态计数据存储使能, 高电平使能态计数存储|
|[14]|STATE_SAVE_EN| 态数据存储使能, 高电平使能态数据存储|
|[13]|IQ_SAVE_EN| 解模数据存储使能, 高电平使能解模数据存储|
|[12]|WAVE_SAVE_EN| 波形数据存储使能, 高电平使能波形数据存储|
|[11]|MTF_IDX_SEL| 匹配滤波器索引选择，1：寄存器，0：查找表|
|[10]|DDS_FPW_SEL| 解模频率相位控制字选择, 1：寄存器，0：查找表|
|[9]|STATE_CLR_VAL| 态统计清零有效, 高电平清零计数|
|[8]|DEMOD_CLR_VAL| 解模求和清零有效, 高电平清零求和值|
|[7]|GLB_FB_VAL| 全局反馈触发有效, 高电平使能全局反馈|
|[6]|LOC_FB_VAL| 局部反馈命令有效, 高电平使能局部反馈|
|[5]|STATE_STS_VAL| 态统计命令有效, 高电平使能态计数功能|
|[4]|DEMOD_SUM_VAL| 解模求和命令有效, 高电平使能解模求和功能|
|[3:0]|PARA_ID| 读出参数查找表索引, 总共支持最大16组参数|

## 2.3 RO寄存器功能定义
RO通道寄存器的地址空间可以被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平台采用系数直读模式，因此不支持上述功能。
解模完成后，可以通过`TWO_STA_EN`来控制是否启动2态判定，
当`TWO_STA_EN=1`时，可以只配置一组直线方程系数进行态判断。

## 2.4 匹配滤波器参数
匹配滤波器在FPGA/ASIC两种平台下由于资源不同实现的形式也不同。
由于ASIC多计算少存储，因而ASIC平台时使用系数计算模式。
系数计算模式下，匹配滤波器的系数由DDS生成的载波乘以权重参数得到。
其中载波的频率和相位由dds_pfd控制，其高20为作为频率控制字，低12位作为相位控制字。
权重参数的选择由mtf_idx控制，其高16位作为地址，低16位作为长度。
寄存器dds_pfw_q 和mtf_idx_q 的详细定义与查找表中定义保持相同。
读出系统的的相关参数的存储格式如下图所示。
系数只读模式只使用`Ctrl`部分中的数据，并忽略`dds_pfw`控制字

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

## 2.5 匹配滤波器系数

由于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。

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

# 3. 处理器RI-Pump编程模型
RI-Pump通道的编程包括：MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库和模拟电路配置6类数据。
其中MCU指令+MCU数据可用于编程发出触发码字以及实时修改控制寄存器；
控制寄存器可用于指定调制频率、调制相位等参数；
波形索引表定义了从波形ID到波形地址和长度的映射，波形仓库定义了波形具体的采样点数据。
模拟电路配置用于设置变频增益和输出频率。
下图是RO通道数字部分的编程控制模型。

![读出RI-Pump通道控制模型](./assets/readout_ri.png)

RI-Pump通道的波形输出由MCU发出的码字触发。
对于输出波形而言，MCU发出的码字定义波形的索引ID，
索引ID输入到波形索引表之后输出波形在波形仓库中的起始地址和长度，
接着波形仓库利用起始地址和长度将对应采样点的原始数据输出。
原始数据经过希尔伯特变换后增加了虚部数据（滤除了负频），
接着数据进入正交数字混频模块，与NCO产生的单音信号混频后得到调频数据。
上述过程中的原始波形数据、希尔伯特虚部数据、调频数据以及NCO自身产生的单音数据都可以通过数据源选择器选择输出。
经过选择器后，数据首先经过调幅模块，接着经过半带滤波器进行插值、然后再经过MIX模块进行采样频率搬移，
半带滤波器和MIX模块都支持旁路功能，因此最终波形输出支持NRZ、MIX、HBNRZ和HBMIX四种模式。
最后经过DAC和外部模拟混频后输出读出激励波形。

Pump通道输出的使能信号由MCU码字触发输出，
当MCU输出码字的对应位使能后，脉冲发生模块从寄存器或波形索引表得到脉冲长度控制数据，
并将指定长度的脉冲信号通过I/O直接输出。

由于RI-Pump通道有且仅有基带处理单元存在状态机，
当RI-Pump通道由于上位机强制中断程序或者MCU配置了错误指令而产生异常时，
为了清除RI-Pump通道的异常状态，
RI-Pump通道提供了软复位功能，支持通过调用驱动API来执行软复位操作，
其能够使得状态机从异常中恢复，从而使得下一次历史无关配置项能够正确执行。

## 3.1 码字功能定义
AWG模块仅使用码字指令的低13位，其余位保留。
控制码字功能定义如下表所示。
指令码低8位用作波形索引，总共可以索引256种波形，能够实现多个比特不同排列组合下的读取操作；
码字比特[8]用于触发发出Pump脉冲输出，该脉冲可用于使能外部开关，避免Pump信号持续输出加热制冷机；
码字比特[9]用于触发Marker脉冲输出，该脉冲能够触发外部仪器，可协同控制与外部芯片或者仪器，方便调试；
码字比特[10]用作内部NCO清零信号，该功能可以在调制输出模式下，复位输出波形的相位；
码字比特[11]用于使能动态波形输出功能，该功能直接使用wave_ctrl寄存器中来索引波形；
码字比特[12]用于禁用波形输出，通过使能该比特可以仅输出Pump或者Marker脉冲而不输出波形。

|比特位|名字|功能描述|
|:-|:-|:-|
|[12]|PULSE_ONLY| 波形输出禁用使能，高电平不输出波形|
|[11]|PARAMETER_SEL| 波形索引选择，1：寄存器，0：查找表|
|[10]|NCO_CLR_EN| NCO清零使能, 高有效|
|[9]|MARK_EN| 标记脉冲输出使能, 高有效|
|[8]|PUMP_EN| 泵浦脉冲输出使能, 高有效|
|[7:0]|WAVE_ID| 波形编号, 最大索256个波形输出|


## 3.2 寄存器功能定义
RI-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资源，只能设置为邻近插值模式。

## 3.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)


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

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

# 4. 处理器Pump编程模型

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

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