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](#a11-acq)）：

|模块|基地址|用途|
|:-|:-|:-|
|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](#441-读出参数存储)。

**控制区配置**（每组 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](#441-读出参数存储) 存储格式图）：

本例 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]|
|`0x00400044`|func_ctrl|two_sta_en [2]|`0`|三态读出模式|
|`0x00400044`|func_ctrl|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](#465-步骤3配置acq寄存器)）|
|`0x00200000`|MCU_INS|MCU程序 → 码字 `0x0003_2000`|