更新文档结构

ri_codeword.md

@@ -0,0 +1,17 @@
+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个波形输出|

ri_datapath.md

@@ -0,0 +1,36 @@
+RI-Pump通道的编程包括：
+MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库和模拟电路配置6类数据。
+其中MCU指令+MCU数据可用于编程发出触发码字以及实时修改控制寄存器；
+控制寄存器可用于指定调制频率、调制相位等参数；
+波形索引表定义了从波形ID到波形地址和长度的映射，波形仓库定义了波形具体的采样点数据。
+模拟电路配置用于设置变频增益和输出频率。
+下图是RO通道数字部分的编程控制模型。
+
+![读出RI-Pump通道控制模型](D:/code/ezq3p0/manual_doc/readout_program/assets/readout_ri.png)
+
+RI-Pump通道的波形输出由AWG模块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来执行软复位操作，
+其能够使得状态机从异常中恢复，从而使得下一次历史无关配置项能够正确执行。
+
+
+![output_response](D:/code/ezq3p0/manual_doc/readout_program/assets/output_response.png)
+
+读出芯片兼容射频直出功能，射频直出时读取激励信号使用了高阶奈奎斯特域频率，考虑DAC采样率超频到8 GSps，使用mix-mode模式时等价采样率为16 GSps。6~7 GHz的输入频率会由于0阶保持输出功率存在sinc滚降，归一化的信号输出功率如上图红色部分所示。可以看到7 GHz输出相比直流输出功率下降了6.5 dB，6~7GHz工作范围内，功率平坦度约为2 dB。
+AWG的波形输出支持3种工作模式，分别是波形直出模式、调制模式、NCO Only模式。一般情况下，直出模式用于量子实验，通过直接输出包含多个读出频率的波形，可以实现对多个量子比特的并行读出；调制模式用于腔频扫描等应用，通过实时修改NCO频率，可以实时改变输出频率，配合DAQ进行实时读取，可以实现扫频功能。若基带信号包含多个频点，还能实现多频点并行扫描功能；NCO Only模式可以输出连续波形，方便连接外部仪器上进行测试，用于芯片本身的测试，

ro_codeword.md

@@ -0,0 +1,34 @@
+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组参数|
+
+当同一个码字指令驱动的多个量子比特解模长度不同时，
+解模时间等于最长那个比特的解模时间。
+解模在当同时使能四种数据存储时，
+存储的先后顺序为波形数据、解模IQ数据、态判断数据和计数数据。
+当同时使能解模清零和求和操作时，先执行清零再执行求和。
+当同时使能态统计和态清零时，先执行态清零再执行态统计。

ro_datapath.md

@@ -0,0 +1,22 @@
+来自量子芯片RO端口的射频信号首先经过混频板模拟电路调理后进入读出基带处理单元采集处理。
+混频板模拟调理电路主要负责将输入功率和频率的信号转换成基带板卡能够处理的中频信号，
+对模拟调理电路的编程包括变频增益控制和变频本振频率控制。
+模拟信号进入基带处理单元后，先经过巴伦将单端信号转换成ADC所需的差分信号。
+接着读出芯片利用ADC（8 bit@5.6Gsps）采样输入信号并给到数字电路。
+对读出基带单元RO通道数字电路的编程包括：MCU的指令、MCU的数据、RO通道控制寄存器、解模参数四类数据。
+其中MCU指令+MCU数据可用于编程发出触发码字以及实时修改控制寄存器；
+控制寄存器可用于指定解模频率、解模相位、解模权重数据索引地址和长度等参数；
+解模参数数据定义了具体的权重数据和量子态判断参数等数据。下图是RO通道的编程控制模型。
+
+![读出RI-Pump通道控制模型](D:/code/ezq3p0/manual_doc/readout_program/assets/readout_ro.png)
+
+射频信号经过混频板下变频后进入到ADC，ADC采集的原始波形数据①从图中右侧端口输入，接着输入到解模模块中，
+解模模块利用匹配滤波器模块生成的解模参数对输入波形进行解模运算得到IQ数据②，
+接着解模IQ数据②输入到态判断模块中，经过态判定后得到态数据④，
+最后态数据④经过态统计后得到态统计结果⑤。
+上述过程中，数据①②③④⑤都可以在数据转发模块缓存后通过`rslt_push`接口发送出去，
+需要注意到的是数据②是解模求和数据③在求和次数为1的特殊情况。
+由于RO通道有且仅有基带处理单元存在状态机，因此需要考虑到异常状态恢复，因此RO通道提供了软复位功能
+当RO通道由于上位机强制中断或者MCU配置了错误指令而产生异常时，可以通过调用驱动API函数执行复位操作，
+其能够将状态机从异常中复位（同时也复位部分寄存器的默认值），
+从而使得下一次历史无关配置项能够正确执行。

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

@@ -41,25 +41,7 @@ ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出
 
 # 2. 处理器RO编程模型
 
-来自量子芯片RO端口的射频信号首先经过混频板模拟电路调理后进入读出基带处理单元采集处理。
+@import "ro_datapath.md"
-混频板模拟调理电路主要负责将输入功率和频率的信号转换成基带板卡能够处理的中频信号，
-对模拟调理电路的编程包括变频增益控制和变频本振频率控制。
-对读出基带单元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.	模拟调理电路配置
 
@@ -72,33 +54,7 @@ ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出
 |mix_gain|下变频增益设置|
 
 ## 2.2.	RO码字功能定义
-RO通道通过产生32位的码字来控制读出行为，32位的操控码字功能定义如下表所示。
+@import "ro_codeword.md"
-码字比特[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来实时更新。
@@ -158,55 +114,11 @@ I路数据偏移地址为x*32KB，Q路数据偏移地址为x*32KB+16 KB，其中
 ![读出RO通道控制模型](./assets/readout_mtf.png)
 
 # 3. 处理器RI-Pump编程模型
-RI-Pump通道的编程包括：MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库和模拟电路配置6类数据。
-其中MCU指令+MCU数据可用于编程发出触发码字以及实时修改控制寄存器；
-控制寄存器可用于指定调制频率、调制相位等参数；
-波形索引表定义了从波形ID到波形地址和长度的映射，波形仓库定义了波形具体的采样点数据。
-模拟电路配置用于设置变频增益和输出频率。
-下图是RO通道数字部分的编程控制模型。
 
-![读出RI-Pump通道控制模型](./assets/readout_ri.png)
+@import "ri_datapath.md"
-
-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位，其余位保留。
+@import "ri_codeword.md"
-控制码字功能定义如下表所示。
-指令码低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来控制寄存器的值。
@@ -251,7 +163,13 @@ ezq2.5 FPGA平台下读出地址和长度单位是16个采样点。
 
 
 ## 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波形输出。
+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 模拟调理电路
 来自读出基带板输出端口的中频信号需要经过前端模拟电路处理后才能够被发送到量子芯片。