readout_program/chapters/04-03-acq-registers.md

## 4.3. ACQ寄存器功能定义

ACQ通道寄存器的地址空间可以被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在使能寄存器控制情况下，用于直接索引匹配滤波器权重/系数；
    - 高16比特对应索引地址，单位是时钟周期
    - 低16比特对应索引长度，单位是时钟周期
- dds_fpw_q在使能寄存器控制情况下，用于控制解模载波的频率和相位；
    - 高20位对应载波频率控制字fcw，$F_{c}=fcw/2^{20}*sample\\_rate$
    - 低12位对应载波相位控制字pcw，$\phi_{c} = pcw/2^{12}*2*\pi$
- function用来控制整个读出基带板数据处理行为；

function功能寄存器与实验控制相关的具体控制位包括：

|比特位|名字|功能描述|
|:-|:-|:-|
|[15:8]|WEIGHT_IQ| 常数权重值，8比特有符号数|
|[7]|CONST_EN| 常数权重使能, 高有效|
|[6:4]|STEP_CTRL| 计算权重模式步长控制|
|[3]|IQ_SCALE| 解模动态范围设置|
|[2]|TWO_STA_EN| 两态读出使能, 高电平使能|

* WEIGHT_IQ 常数权重值，可用于长时间解模
* CONST_EN 常数权重使能
    * `CONST_EN=0`时，权重数据通过`mtf_idx_q`来索引得到
    * `CONST_EN=1`来启用常量权重功能，此时权重值为`WEIGHT_IQ`。
* STEP_CTRL 权重点步长控制
    - `STEP_CTRL==0` 1个权重数据点可对应1个时钟周期采样点。
    - `STEP_CTRL==1` 1个权重数据点可对应2个时钟周期采样点。
    - `STEP_CTRL==2` 1个权重数据点可对应4个时钟周期采样点。
    - `STEP_CTRL==3` 1个权重数据点可对应8个时钟周期采样点。
    - `STEP_CTRL==4` 1个权重数据点可对应16个时钟周期采样点。
* IQ_SCALE 解模结果截断位置控制
    - `IQ_SCALE =0` IQ结果截位[27:8]
    - `IQ_SCALE =1` IQ结果截位[31:12]
* TWO_STA_EN 两态读出使能
    - `TWO_STA_EN==0` 默认三态读出
    - `TWO_STA_EN==1` 使能二态读出


> **注意：** ez-Q 2.5 FPGA平台采用系数直读模式，因此不支持系数生产相关功能。
即在ez-Q 2.5 FPGA平台下，dds_fpw 寄存器无实际效果;
function寄存器WEIGHT_IQ，CONST_EN, STEP_CTRL 位无实际效果

解模完成后，可以通过`TWO_STA_EN`来控制是否启动2态判定，
当`TWO_STA_EN=1`时，可以只配置一组直线方程系数进行态判断。

### 参数选择指南

#### 查找表模式 vs 寄存器模式

ACQ 通道提供两种参数索引方式，由码字位 `MTF_IDX_SEL` 和 `DDS_FPW_SEL` 分别控制：

| 模式 | 控制位值 | 参数来源 | 优点 | 缺点 | 适用场景 |
|:---|:---|:---|:---|:---|:---|
| 查找表 (LUT) | `0` | DAQ_PAR 中预存的 16 组参数（PARA_ID 0~15） | 切换速度快（一条码字即可切换）、参数经过预校验 | 最多 16 组，需提前加载 | **推荐**：常规多比特轮询实验 |
| 寄存器 | `1` | DAQ_REG 中的 `mtf_idx_q` / `dds_fpw_q` 寄存器 | 参数数量不限，MCU 可实时写入任意值 | 切换需 MCU 先写寄存器再发码字（多指令开销） | 需要超过 16 组参数、或参数需动态计算的高灵活度场景 |

> **建议**：大多数实验使用查找表模式即可满足需求（16 组参数 × 16 qubit = 256 种组合）。仅在参数空间超过 16 组时（如扫频实验中频率步进 > 16 步）才启用寄存器模式。

#### 权重步长 (STEP_CTRL) 选择

`STEP_CTRL` 控制一个权重点覆盖的时钟周期数，直接影响解模精度和最大可支持的解模长度：

| STEP_CTRL | 时钟周期 / 权重点 | 解模精度 | 最大解模长度（时钟周期） | 适用场景 |
|:---:|:---:|:---:|:---:|:---|
| 0 | 1 | 最高 | 最短（受权重区容量限制） | 需要精确波形匹配、解模长度较短的场景 |
| 1 | 2 | 高 | 2× | 常规读出（推荐起点） |
| 2 | 4 | 中等 | 4× | 包络缓变信号，平衡精度与覆盖长度 |
| 3 | 8 | 较低 | 8× | 长解模窗口，精度要求不高的场景 |
| 4 | 16 | 最低 | 16× | 极长解模窗口，粗粒度解模 |

> - 每个时钟周期对应 8 个采样点（ASIC，6 Gsps）或 16 个采样点（FPGA，4 Gsps）。
> - **选择原则**：STEP_CTRL 越大，相同权重存储空间可覆盖的解模长度越长，但时间分辨率越低。建议从 `STEP_CTRL=1`（1:2）开始，根据所需的解模窗口长度和解模 SNR 是否满足需求逐步调整。
> - STEP_CTRL 仅 ASIC 平台（系数计算模式）有效，FPGA 平台（系数直读模式）下该位无实际效果。

#### IQ 动态范围 (IQ_SCALE) 选择

`IQ_SCALE` 控制解模结果从累加器（32 位以上）截取到输出位宽时的截位位置：

| IQ_SCALE | 截取位段 | 数值范围 | 适用场景 |
|:---:|:---|:---:|:---|
| 0 | [27:8] | 20 位有符号数 | 低增益/短解模长度（推荐默认值） |
| 1 | [31:12] | 20 位有符号数（高位移位） | 高增益/长解模长度，避免溢出 |

> **选择原则**：若解模结果频繁溢出（I/Q 值达到 ±524287 附近），切换到 `IQ_SCALE=1`；若解模结果幅值过小（有效位数不足），切换到 `IQ_SCALE=0`。可通过采集原始 IQ 数据观察其分布来优化此设置。

#### 两态 vs 三态判定

| TWO_STA_EN | 模式 | 所需直线方程 | 态值 | 适用场景 |
|:---:|:---|:---|:---|:---|
| 0 | 三态 | line0, line1, line2（3 组） | 0, 1, 2, 3(错误态) | 量子比特三能级读出（含泄漏态检测） |
| 1 | 两态 | line0（1 组） | 0, 1 | 标准 0/1 态读出（数据量更小、延迟更低） |

> **建议**：若实验只关心 |0⟩ 和 |1⟩ 两种状态，使能 `TWO_STA_EN=1` 仅配置 line0 即可，可减少配置工作。