readout_program/chapters/04-06-acq-pipeline-demo.md

4.6. ACQ通道全流程控制示例

本节通过一个完整的示例演示ACQ通道从码字生成到采集数据获取的全流程编程控制。 示例场景：对2个量子比特（q0, q1）执行单次读出，采集解模IQ数据。

4.6.1. 流程总览

ACQ通道读出全流程包含以下步骤：

1. 配置模拟前端 — 设置下变频本振频率
2. 加载解模参数 — 配置匹配滤波器权重和DDS参数查找表
3. 配置ACQ寄存器 — 设置解模频率/相位/缩放等控制参数
4. 生成并发送码字 — MCU发出采集触发码字
5. 接收处理数据 — 固件打包上传，上位机解帧获取IQ数据

4.6.2. 步骤1：配置模拟前端

配置混频板下变频本振频率，将射频信号转换到中频：

配置项	值	说明
lo_freq	5_500_000	本振频率 5.5 GHz，单位 kHz

本振频率需根据目标量子比特频率确定。
例如量子比特频率为 6.7 GHz，则下变频后中频为 1.2 GHz。

4.6.3. 步骤2：加载解模参数

将解模参数（匹配滤波器权重、DDS频率/相位控制字）写入参数查找表。 本例配置2组参数，对应2个量子比特：

权重数据（匹配滤波器系数）

参数索引	目标比特	权重长度	iw示例	qw示例
0	q0	128 采样点	cos(ω·t) 包络采样	sin(ω·t) 包络采样
1	q1	128 采样点	cos(ω·t) 包络采样	sin(ω·t) 包络采样

DDS参数（频率/相位控制字）

参数索引	fcw (频率控制字)	pcw (相位控制字)	scale
0	fcw_q0 = F_{if} / F_s \times 2^{32}	0	1
1	fcw_q1 = F_{if} / F_s \times 2^{32}	0	1

参数查找表共支持16组参数（PARA_ID = 0~15），
每组包含独立的权重系数和DDS参数。
MCU可通过修改PARA_ID在运行时快速切换目标比特。

4.6.4. 步骤3：配置ACQ寄存器

配置解模相关寄存器（通过SPI或MCU写入）：

寄存器	值	说明
demod_len	128	解模采样点数，与权重长度一致
result_scale	1	解模结果缩放因子（1 或 16）
dds_fcw	fcw_q0	初始DDS频率控制字（可通过查找表覆盖）
dds_pcw	0	初始DDS相位控制字（可通过查找表覆盖）

当码字中 DDS_FPW_SEL = 0（查找表模式）时，
实际解模参数由 PARA_ID 索引的查找表决定，
寄存器中的初始值作为 fallback。

4.6.5. 步骤4：生成并发送码字

MCU生成32位ACQ码字，触发一次完整的读出采集：

码字位段	字段名	配置值	说明
[31:16]	QUBIT_EN	0x0003	使能 q0, q1（bit0=1, bit1=1）
[15]	COUNT_SAVE_EN	0	不存储态计数
[14]	STATE_SAVE_EN	0	不存储态数据
[13]	IQ_SAVE_EN	1	存储解模IQ数据
[12]	WAVE_SAVE_EN	0	不存储原始波形
[11]	MTF_IDX_SEL	0	匹配滤波器参数来自查找表
[10]	DDS_FPW_SEL	0	DDS参数来自查找表
[9]	STATE_CLR_VAL	0	不清理态计数
[8]	DEMOD_CLR_VAL	0	不清理解模求和
[7:4]	FB/STATE/SUM	0	不触发反馈/态统计/求和
[3:0]	PARA_ID	0	使用参数组0（q0参数）

完整码字值：0x0003_2000

上述码字使能了 q0 和 q1 同时解模并仅存储 IQ 数据。
若需对不同比特使用不同参数，需发送多个码字并切换 PARA_ID。
例如：
  码字1: PARA_ID=0, QUBIT_EN=q0 → 使用参数组0读出q0
  码字2: PARA_ID=1, QUBIT_EN=q1 → 使用参数组1读出q1

4.6.6. 步骤5：接收处理数据

ACQ通道完成采集后将数据打包成帧，通过rslt_push接口推送上位机。 上位机驱动解帧后按流模式返回：

IQ数据帧格式

字节偏移	字段	长度	格式
0	I (q0)	4 字节	32位有符号整数，大端
4	Q (q0)	4 字节	32位有符号整数，大端
8	I (q1)	4 字节	32位有符号整数，大端
12	Q (q1)	4 字节	32位有符号整数，大端

若码字同时使能多种数据存储，帧内数据按以下顺序排列：
波形数据 → 解模IQ数据 → 态判断数据 → 态计数数据
推荐每次仅使能一种数据类型以简化上位机解析。

4.6.7. 时序总结

单次ACQ读出的完整时序：

1. T0: MCU 发出32位码字 0x0003_2000
2. T0 + 1 cycle: 码字解码，使能 q0, q1 的解模通路
3. T0 + 2~129 cycles: ADC采集128个采样点，并行送入匹配滤波器
4. T0 + 130 cycle: 解模完成，IQ数据写入结果缓存
5. T0 + 131 cycle: 数据打包，通过 rslt_push 推送上位机

实际解模时间取决于使能比特中最长的解模长度。
若 q0 解模128点、q1 解模256点，则解模耗时 = 256 cycles。