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

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

本节通过一个完整的端到端示例说明ACQ通道的编程配置流程。 示例基于 ASIC 平台（ADC 8 bit@6 Gsps），场景为对2个量子比特（q0, q1）执行单次读出，采集解模IQ数据。

4.6.1. 端到端配置流程

ACQ通道的工作流程如下：

阶段	操作	说明
初始化	配置模拟前端、解模参数、ACQ寄存器	通过SPI写入，步骤1~3无先后顺序要求
初始化	加载MCU程序	写入MCU_INS，定义触发后要发出的码字
运行	外部触发 → MCU执行 → 产生码字	触发由其它硬件发出，MCU响应后执行程序并生成32位码字
运行	码字解码 → 采集 → 解模 → 推送数据	硬件自动流水线执行
运行	上位机接收数据	从 rslt_push 接口读取并解帧

关键理解：
  触发信号来自外部硬件（非MCU），MCU是被动响应方。
  MCU 程序加载到 MCU_INS 后处于待命状态，收到触发后执行并生成码字。
  初始化配置可在任意时刻通过 SPI 完成，只需在触发前生效即可。

4.6.2. 地址空间速查

以下配置基于ACQ通道0（Exaddr=0），各模块基地址如下（完整地址映射见 附录A.1.1）：

模块	基地址	用途
MCU_INS	0x00200000	MCU指令存储
MCU_DAT	0x00300000	MCU数据存储
DAQ_REG	0x00400000	DAQ控制寄存器
DAQ_PAR	0x00500000 + N×0x800	解模参数查找表（每比特 2 KB，N = qubit 序号）
MIXER_REG	0x00100000	混频板本振配置

FPGA 平台额外使用 DAQ_FLT（0x00580000）存储匹配滤波器系数（系数直读模式）。ASIC 平台使用系数计算模式，无需此项。

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

通过SPI写混频板本振频率寄存器：

地址	寄存器	字段	值	说明
0x00100000	lo_freq	fcw [31:0]	5_500_000	本振 5.5 GHz，单位 kHz

本振频率根据目标量子比特频率确定：中频 = 量子比特频率 − 本振频率。同一混频板4个通道共享本振。

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

DAQ_PAR 每比特独占 2 KB 子空间（q0 基地址 = 0x00500000，q1 基地址 = 0x00500800），详见 §4.4.1。

控制区配置（每组 8 × 32 bit = 32 字节，PARA_ID 对应基地址 = Qubit 基地址 + PARA_ID × 0x20）：

配置 q0 和 q1 各一组参数（均使用 PARA_ID=0）：

地址	寄存器	字段	值	说明
0x00500000	dds_fpw	fcw [31:12]	\lfloor F_{if} / F_s \times 2^{20} \rfloor	q0 解模频率控制字
^	^	pcw [11:0]	0	q0 解模相位控制字
0x00500004	mtf_idx	addr [31:16]	0	q0 权重起始地址（单位：时钟周期）
^	^	len [15:0]	16	q0 权重长度 16 时钟周期（= 128 采样点 / 8）
0x00500008	line0_ab	a0 [31:16]	校准值	q0 态判断直线0 系数 a
^	^	b0 [15:0]	校准值	q0 态判断直线0 系数 b
0x0050000C	line0_c	c0 [31:0]	校准值	q0 态判断直线0 系数 c
0x00500010	line1_ab	a1 / b1	校准值	q0 态判断直线1 系数
0x00500014	line1_c	c1 [31:0]	校准值	q0 态判断直线1 系数
0x00500018	line2_ab	a2 / b2	校准值	q0 态判断直线2 系数
0x0050001C	line2_c	c2 [31:0]	校准值	q0 态判断直线2 系数
0x00500800	dds_fpw	fcw [31:12]	\lfloor F_{if} / F_s \times 2^{20} \rfloor	q1 解模频率控制字
0x00500804	mtf_idx	addr [31:16]	0	q1 权重起始地址（单位：时钟周期）
^	^	len [15:0]	16	q1 权重长度 16 时钟周期
0x00500808	line0_ab	a0 / b0	校准值	q1 态判断直线0 系数
0x0050080C	line0_c	c0 [31:0]	校准值	q1 态判断直线0 系数 c
0x00500810	line1_ab	a1 / b1	校准值	q1 态判断直线1 系数
0x00500814	line1_c	c1 [31:0]	校准值	q1 态判断直线1 系数 c
0x00500818	line2_ab	a2 / b2	校准值	q1 态判断直线2 系数
0x0050081C	line2_c	c2 [31:0]	校准值	q1 态判断直线2 系数 c

三组直线方程系数（a,b,c）需通过量子比特校准实验确定，此处以"校准值"代替。
若实验不需要态判断（如仅采集 IQ 数据），直线方程系数可填 0。

权重区配置（偏移 0x200 起，布局见 §4.4.1 存储格式图）：

本例 q0 使用 16 个时钟周期的权重数据（写入 q0 权重区 0x00500200 起）， q1 同样 16 个时钟周期（写入 q1 权重区 0x00500A00 起）。 权重系数为 8 位有符号数，I 路和 Q 路分开存储，具体偏移以 readout_para.png 图示为准。

ASIC 平台下匹配滤波器系数 = DDS 载波 × 权重参数（系数计算模式），
权重数据只需存储缓变包络，一个权重点可对应多个时钟周期采样点（由 `step_ctrl` 控制）。
MCU 可通过切换 PARA_ID 在运行时快速切换目标比特。

mtf_idx 的 addr 和 len 单位为时钟周期（ASIC 平台每周期 8 采样点）。
本例 len=16 时钟周期 = 128 采样点。

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

通过SPI写DAQ控制寄存器：

地址	寄存器	字段	值	说明
0x00400044	func_ctrl	iq_scale [3]	0	IQ 结果截位 [27:8]
^	^	two_sta_en [2]	0	三态读出模式
^	^	const_en [7]	0	使用查找表权重（非常数权重）
0x00400080	mtf_idx_q0	addr [31:16] / len [15:0]	fallback 值	q0 匹配滤波器索引（查找表模式的 fallback）
0x004000C0	dds_fpw_q0	fcw [31:12] / pcw [11:0]	fallback 值	q0 DDS参数（查找表模式的 fallback）

func_ctrl 寄存器中与 ASIC 系数计算模式相关的位（const_en、step_ctrl、weight_iq）
必须按上表配置，否则可能导致解模结果错误。

4.6.6. 步骤4：MCU程序与触发

MCU程序加载到 MCU_INS（0x00200000），触发后MCU执行程序并生成32位码字。 触发信号由外部硬件发出，MCU响应后自动执行。

码字示例（使能 q0、q1 解模，仅存储IQ数据）：

位段	字段名	值	说明
[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	参数组索引（各比特独立查找）

完整码字值：0x0003_2000

一个码字可同时使能多个比特（通过 QUBIT_EN 位段），
各比特使用各自的 DAQ_PAR 子空间（基地址 = 0x00500000 + N×0x800），
因此 q0 和 q1 可共用 PARA_ID=0 且互不干扰。

若同一比特需要使用不同的解模参数（如不同频率/权重），
可在不同触发中切换 PARA_ID 来实现。

4.6.7. 步骤5：数据接收

采集完成后硬件通过 rslt_push 推送上位机。IQ数据帧格式（2比特 × 8字节）：

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

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

4.6.8. 配置清单汇总

地址	寄存器/区域	关键值
0x00100000	lo_freq	5_500_000
0x00500000 ~ 0x0050001F	DAQ_PAR q0 控制区（PARA_ID=0）	dds_fpw, mtf_idx, 3×line_coeff
0x00500800 ~ 0x0050081F	DAQ_PAR q1 控制区（PARA_ID=0）	同上结构
0x00500200 起	DAQ_PAR q0 权重区	q0 的 I/Q 权重（见存储格式图）
0x00500A00 起	DAQ_PAR q1 权重区	q1 的 I/Q 权重（见存储格式图）
0x00400044	func_ctrl	0x0000（见 §4.6.5）
0x00200000	MCU_INS	MCU程序 → 码字 0x0003_2000