基于文档即代码重构
This commit is contained in:
parent
8159e34981
commit
68acdb1aa3
|
|
@ -1 +1,2 @@
|
||||||
读出子系统编程控制模型.html
|
# Build output
|
||||||
|
output/
|
||||||
|
|
@ -0,0 +1,96 @@
|
||||||
|
# CLAUDE.md — ez-Q 2.5 读出子系统编程控制模型
|
||||||
|
|
||||||
|
## 项目概述
|
||||||
|
|
||||||
|
本项目为 ez-Q 2.5 量子测控系统读出子系统的编程控制模型文档。采用 **"文档即代码" (Docs as Code)** 工作方式：
|
||||||
|
Markdown 纯文本写作 + Git 版本控制 + Python 构建管道 → 自包含 HTML 报告。
|
||||||
|
|
||||||
|
## 文档即代码约定
|
||||||
|
|
||||||
|
### 目录结构
|
||||||
|
```
|
||||||
|
project.yaml # 项目元数据与章节列表
|
||||||
|
chapters/ # Markdown 章节源文件（唯一编辑目标）
|
||||||
|
assets/ # 图片资源
|
||||||
|
doc_builder/ # Python 构建工具
|
||||||
|
build.py # 构建入口
|
||||||
|
templates/ # HTML 模板
|
||||||
|
themes/ # CSS 样式
|
||||||
|
output/ # 构建产物（gitignore）
|
||||||
|
```
|
||||||
|
|
||||||
|
### 文件命名规范
|
||||||
|
- 章节文件: `{序号}-{英文slug}.md`（如 `04-02-acq-codeword.md`）
|
||||||
|
- 子章节用二级编号: `{章}-{节}-{slug}.md`（如 `05-03-exct-wavetable.md`）
|
||||||
|
- 图片文件: 语义化命名（如 `readout_ro.png`），统一放在 `assets/`
|
||||||
|
|
||||||
|
### 标题层级
|
||||||
|
- 每章开头使用 `#` (H1)
|
||||||
|
- 节使用 `##` (H2)
|
||||||
|
- 子节使用 `###` (H3)
|
||||||
|
- **禁止在子章节文件中使用 H1**，确保拼接后层级正确
|
||||||
|
|
||||||
|
### 图片规范
|
||||||
|
- **一律使用项目根目录相对路径**: ``
|
||||||
|
- **禁止绝对路径**（尤其是 Windows 盘符路径如 `D:/code/...`）
|
||||||
|
- 构建时自动内嵌为 base64，生成自包含 HTML
|
||||||
|
|
||||||
|
### 交叉引用
|
||||||
|
- 内部引用: `详见 [标题锚点](#标题锚点)`
|
||||||
|
- 外部引用: `[文档名](path/to/doc.md)`
|
||||||
|
|
||||||
|
### 非标准 Markdown 扩展
|
||||||
|
本项目采用 docs-as-code skill 规范的非标准扩展：
|
||||||
|
- `@import "data/file.csv"` — 数据注入（预留）
|
||||||
|
- `{w=50%}` — 图片属性控制（预留）
|
||||||
|
- 自定义代码块渲染器（预留 `doc_builder/renderers/`）
|
||||||
|
|
||||||
|
## 构建流程
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 安装依赖（首次）
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
# 构建 HTML
|
||||||
|
python doc_builder/build.py
|
||||||
|
|
||||||
|
# 输出: output/读出子系统编程控制模型.html
|
||||||
|
```
|
||||||
|
|
||||||
|
## 文件组织表
|
||||||
|
|
||||||
|
| 章节 | 文件 | 内容 |
|
||||||
|
|:---|:---|:---|
|
||||||
|
| §1 | `chapters/01-changelog.md` | 修订记录 |
|
||||||
|
| §2 | `chapters/02-preface.md` | 前言（目的、范围、术语等） |
|
||||||
|
| §3 | `chapters/03-overview.md` | 编程控制模型概述 |
|
||||||
|
| §4 | `chapters/04-acq-model.md` | ACQ 通道编程模型（数据路径） |
|
||||||
|
| §4.1 | `chapters/04-01-acq-downconversion.md` | 下变频电路配置 |
|
||||||
|
| §4.2 | `chapters/04-02-acq-codeword.md` | ACQ 码字功能定义 |
|
||||||
|
| §4.3 | `chapters/04-03-acq-registers.md` | ACQ 寄存器功能定义 |
|
||||||
|
| §4.4 | `chapters/04-04-acq-matched-filter.md` | 匹配滤波器 |
|
||||||
|
| §4.5 | `chapters/04-05-acq-data-processing.md` | 采集数据处理 |
|
||||||
|
| §5 | `chapters/05-exct-model.md` | EXCT-Pump 编程模型（数据路径） |
|
||||||
|
| §5.1 | `chapters/05-01-exct-codeword.md` | EXCT 码字功能定义 |
|
||||||
|
| §5.2 | `chapters/05-02-exct-registers.md` | 寄存器功能定义 |
|
||||||
|
| §5.3 | `chapters/05-03-exct-wavetable.md` | 波形索引表定义 |
|
||||||
|
| §5.4 | `chapters/05-04-exct-waveform-store.md` | 波形仓库定义 |
|
||||||
|
| §5.5 | `chapters/05-05-exct-upconversion.md` | EXCT 上变频电路配置 |
|
||||||
|
| §5.6 | `chapters/05-06-pump-config.md` | Pump 模拟电路配置 |
|
||||||
|
|
||||||
|
## 编辑工作流
|
||||||
|
|
||||||
|
| 修改内容 | 编辑目标 | 构建方式 |
|
||||||
|
|:---|:---|:---|
|
||||||
|
| 正文内容 | `chapters/*.md` | `python doc_builder/build.py` |
|
||||||
|
| 章节顺序 | `project.yaml` → `chapters:` 列表 | 同上 |
|
||||||
|
| 图片 | `assets/` | 同上（自动内嵌） |
|
||||||
|
| HTML 样式 | `doc_builder/themes/*.css` | 同上 |
|
||||||
|
| HTML 模板 | `doc_builder/templates/report.html` | 同上 |
|
||||||
|
|
||||||
|
## 注意事项
|
||||||
|
|
||||||
|
1. 本项目是 **硬件寄存器级编程手册**，包含大量位域表格和时序说明
|
||||||
|
2. 平台差异（FPGA vs ASIC）使用代码块标注
|
||||||
|
3. 数学公式使用 `$...$`（行内）和 `$$...$$`（块级）LaTeX 语法
|
||||||
|
4. 原有根目录下的 `*.md` 文件是 MPE 编辑器兼容的历史文件，编辑以 `chapters/` 为准
|
||||||
60
README.md
60
README.md
|
|
@ -1,7 +1,57 @@
|
||||||
# 读出子系统编程模型
|
# 读出子系统编程控制模型
|
||||||
本项目为ez-Q 2.5 读出子系统的编程控制模型，预期用户通过阅读本文档能够通过软件操控读出系统开展实验。
|
|
||||||
|
本项目为 ez-Q 2.5 读出子系统的编程控制模型文档。采用 **"文档即代码" (Docs as Code)** 工作方式，
|
||||||
|
通过 Markdown 纯文本写作、Git 版本控制和 Python 构建管道生成自包含 HTML 报告。
|
||||||
|
|
||||||
**主要内容**
|
**主要内容**
|
||||||
* RI通道编程
|
|
||||||
* RO通道编程
|
- RI 通道编程（激励生成发送）
|
||||||
* Pump通道编程
|
- RO 通道编程（回波采集处理）
|
||||||
|
- Pump 通道编程（泵浦信号控制）
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
project.yaml # 项目配置（标题、作者、版本、章节列表）
|
||||||
|
chapters/ # Markdown 章节源文件
|
||||||
|
assets/ # 图片资源
|
||||||
|
doc_builder/ # Python 构建工具
|
||||||
|
build.py # 构建入口
|
||||||
|
templates/ # HTML 模板
|
||||||
|
themes/ # CSS 样式
|
||||||
|
output/ # 构建产物（.gitignore）
|
||||||
|
```
|
||||||
|
|
||||||
|
## 快速开始
|
||||||
|
|
||||||
|
### 构建 HTML 报告
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. 安装依赖（首次）
|
||||||
|
pip install -r requirements.txt
|
||||||
|
|
||||||
|
# 2. 构建
|
||||||
|
python doc_builder/build.py
|
||||||
|
|
||||||
|
# 3. 打开 output/读出子系统编程控制模型.html 即可浏览
|
||||||
|
```
|
||||||
|
|
||||||
|
### 编辑文档
|
||||||
|
|
||||||
|
- 修改 `chapters/` 下的 `.md` 文件
|
||||||
|
- 添加/删除/重新排序章节：编辑 `project.yaml` 的 `chapters` 列表
|
||||||
|
- 修改样式：编辑 `doc_builder/themes/report.css`
|
||||||
|
- 修改页面布局：编辑 `doc_builder/templates/report.html`
|
||||||
|
|
||||||
|
### 编辑器推荐
|
||||||
|
|
||||||
|
- VS Code + Markdown 预览
|
||||||
|
- Typora
|
||||||
|
- Obsidian
|
||||||
|
- 任何支持 Markdown 的编辑器
|
||||||
|
|
||||||
|
## 向后兼容
|
||||||
|
|
||||||
|
原有的 Markdown Preview Enhanced (MPE) 导出方式仍然可用：
|
||||||
|
在 VS Code 中安装 MPE 插件后，打开 `读出子系统编程控制模型.md` 可实时预览和导出 HTML。
|
||||||
|
不过建议优先使用 `doc_builder/build.py` 进行构建。
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,6 @@
|
||||||
|
# 1. 修订记录
|
||||||
|
|
||||||
|
|版本|修订日期|修订原因|修订内容|修订人|
|
||||||
|
|:-|:-|:-|:-|:-|
|
||||||
|
|v0.1|2025/10/27|统一格式|初始版本|郭成|
|
||||||
|
|v0.2|2025/10/31|评审意见|内容补充|郭成|
|
||||||
|
|
@ -0,0 +1,31 @@
|
||||||
|
# 2. 前言
|
||||||
|
|
||||||
|
## 2.1. 目的与范围
|
||||||
|
|
||||||
|
本文档的目的是介绍读出芯片激励产生和采集处理相关控制，
|
||||||
|
该文档适用于ez-Q 2.5 FPGA/ASIC平台读出子系统编程。
|
||||||
|
本文档作为开放文档供大家阅读。
|
||||||
|
|
||||||
|
## 2.2. 阅读对象
|
||||||
|
|
||||||
|
本文档的预期读者是所有使用本芯片的用户以及对该芯片工作原理感兴趣的读者。
|
||||||
|
|
||||||
|
## 2.3. 文档概述
|
||||||
|
|
||||||
|
本文档首先介绍了测控系统总体的编程对象和规范，
|
||||||
|
针对读出ACQ/EXCT/Pump三种类型通道对应的ACQ/EXCT-Pump编程模型进行了详细介绍。
|
||||||
|
|
||||||
|
## 2.4. 引用文档
|
||||||
|
|
||||||
|
|文档编号|标题|版本|
|
||||||
|
|:-|:-|:-|
|
||||||
|
|-|读出子系统历史无关配置集.md|V1.0|
|
||||||
|
|-|读出子系统IDS表.xls|V1.0|
|
||||||
|
|ez-Q 2.5-SDD-04|ez-Q 2.5 测控系统研制项目指令集设计报告_V1.0.docx|V1.0|
|
||||||
|
|
||||||
|
## 2.5. 术语定义
|
||||||
|
|
||||||
|
|名字|全称|解释|
|
||||||
|
|:-|:-|:-|
|
||||||
|
|ACQ|Acquisition|读出回波采集处理通道|
|
||||||
|
|EXCT|Excitation|读出激励生成发送通道|
|
||||||
|
|
@ -0,0 +1,77 @@
|
||||||
|
# 3. 编程控制模型概述
|
||||||
|
|
||||||
|
## 3.1. 测控系统编程概述
|
||||||
|
|
||||||
|
超导量子计算机利用微波信号来驱动量子比特和读出量子比特状态，量子比特不同类型的操作依赖不同类型的信号来控制。
|
||||||
|
ez-Q 2.5测控系统包含5种物理通道，对应5类硬件接口，分别是ACQ、EXCT、Pump、XYZ/Reset和ZCP通道；
|
||||||
|
系统具有7种控制信号，对应7种编程对象，分别是EXCT、ACQ、Pump、XY、Reset、Z和ZCP信号；
|
||||||
|
系统具有4种控制模型，对应4种编程类型，分别是ACQ、EXCT-Pump、XY/Reset和Z/ZCP模型，分类关系如下表所示。
|
||||||
|
|
||||||
|
|5种物理通道|7种控制对象|4种控制模型|
|
||||||
|
|:-:|:-:|:-:|
|
||||||
|
|XYZ通道|XY 信号|XY/Reset控制模型|
|
||||||
|
|^|Reset信号|^|
|
||||||
|
|^|Z信号|Z/ZCP控制模型|
|
||||||
|
|ZCP通道|ZCP信号|Z/ZCP控制模型|
|
||||||
|
|ACQ通道|ACQ(RO)信号|ACQ控制模型|
|
||||||
|
|EXCT通道|EXCT(RI)信号|EXCT-Pump控制模型|
|
||||||
|
|Pump通道|Pump信号|^|
|
||||||
|
|
||||||
|
- 测控系统中的每种控制模型实现的功能都是通过以下四类数据进行定义，
|
||||||
|
- 通道微控制器码字指令
|
||||||
|
- 通道寄存器配置数据
|
||||||
|
- 通道SRAM配置数据
|
||||||
|
- 通道模拟电路配置
|
||||||
|
|
||||||
|
- 测控系统的寄存器、配置数据和模拟电路配置返回数据统一采用**大端字节序**。
|
||||||
|
|
||||||
|
通道寄存器配置数据支持微控制器实时修改，从而让通道的输入/输出控制具备动态控制能力。
|
||||||
|
ACQ和EXCT-Pump通道配置寄存器定义参考[读出子系统IDS表.xls](TODO)的`DAQ_REG`和`AWG_REG`页。
|
||||||
|
ACQ的配置数据定义参考
|
||||||
|
|
||||||
|
本文档通过对不同编程模型下码字指令、通道寄存器配置数据、通道SRAM配置数据和通道模拟电路配置进行介绍，
|
||||||
|
旨在让用户掌握对读出激励信号的产生和采集信号处理的编程方法。
|
||||||
|
其中码字指令通过MCU来产生，MCU的编程关键参数如下：
|
||||||
|
|
||||||
|
* ACQ通道和EXCT-Pump通道使用**相同MCU**；
|
||||||
|
* MCU分别使用**16 KB**的ITCM和DTCM；
|
||||||
|
* FPGA平台MCU主时钟频率为**250 MHz**，
|
||||||
|
* ASIC平台MCU主钟频率暂定**750 MHz**；
|
||||||
|
* MCU以固定的**3个时钟周期每指令**的速度运行；
|
||||||
|
* MCU通过**0x100000**地址访问MCU数据空间；
|
||||||
|
* MCU通道**0x200000**地址访问通道配置寄存器空间；
|
||||||
|
|
||||||
|
针对具体的指令定义和使用方法，
|
||||||
|
读者可查看[《量子编程指令集》](TODO)了解相关信息。
|
||||||
|
|
||||||
|
## 3.2. 读出子系统编程
|
||||||
|
|
||||||
|
ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出泵浦板三个硬件组成
|
||||||
|
- 三个板卡以PXIe板卡的形式安装在机箱中位置相邻的三个槽位上
|
||||||
|
- 混频板的槽位号比基带板大1，泵浦板槽位号比基带板槽位号小1
|
||||||
|
|
||||||
|
因此可以通过仅指定读出基带板槽位号来定位混频板和泵浦板槽位号，
|
||||||
|
读出子系统硬件架构如下图所示。
|
||||||
|
- 读出基带板负责产生、输出、采集和处理基带信号以及为泵浦通道产生使能信号；
|
||||||
|
- 读出混频板自身产生一个本振信号，用于实现基带信号与射频信号之间的转换；
|
||||||
|
- 而读出泵浦板负责产生一个指定功率频率的单音信号，并在外部使能信号控制下输出；
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
当软件需要对不同通道编程时，其通过ip地址指定机箱、通过槽位号指定板卡、
|
||||||
|
通过扩展地址指定同一个板卡内的多个通道、通过地址指定一个通道内的不同配置项。
|
||||||
|
|
||||||
|
```
|
||||||
|
索引基地址由《读出子系统IDS表.xls》的mapping页定义，本文不对地址翻译进行赘述。
|
||||||
|
```
|
||||||
|
|
||||||
|
本文所述的三类编程通道具体定义如下：
|
||||||
|
* ACQ 编程通道定义从混频板`rf_in`输入端口到基带板卡内部DAQ模块；
|
||||||
|
* EXCT 编程通道定义为从基带板内部AWG模块混频板到`rf_out`接口；
|
||||||
|
* Pump 编程通道定义为从基带板卡内部AWG模块到泵浦板`pump_out`接口；
|
||||||
|
|
||||||
|
ASIC和FPGA平台具有以下区别：
|
||||||
|
* ez-Q 2.5 FPGA平台读出子系统混频板和泵浦板复用同一个硬件板卡。
|
||||||
|
* ez-Q 2.5 FPGA平台将读出基带芯片RBPU和FPGA集成在一个FPGA中。
|
||||||
|
* ez-Q 2.5 FPGA平台使用外部商用ADC、DAC和PLL来替换RBPU的对应功能。
|
||||||
|
* ez-Q 2.5 FPGA平台ADC、DAC采样率为4 Gsps, ASIC平台暂定为6 Gsps
|
||||||
|
|
@ -0,0 +1,14 @@
|
||||||
|
## 4.1. 下变频电路配置
|
||||||
|
|
||||||
|
来自量子比特RO端口的射频信号需要经过前端模拟电路处理后才能够被读出基带处理单元采集处理。
|
||||||
|
前端下变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。
|
||||||
|
|
||||||
|
|配置名|描述|
|
||||||
|
|:-:|:-:|
|
||||||
|
|lo_freq|变频本振频率设置|
|
||||||
|
|mix_gain|下变频增益设置|
|
||||||
|
|
||||||
|
```
|
||||||
|
目前ez-Q 2.5 FPGA平台暂不支持下变频增益
|
||||||
|
mix_gain 设置；仅支持 lo_freq 变频本振频率设置
|
||||||
|
```
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
## 4.2. ACQ码字功能定义
|
||||||
|
|
||||||
ACQ通道通过产生32位的码字来控制读出行为，32位的操控码字功能定义如下表所示。
|
ACQ通道通过产生32位的码字来控制读出行为，32位的操控码字功能定义如下表所示。
|
||||||
|
|
||||||
|比特位|名字|功能描述|
|
|比特位|名字|功能描述|
|
||||||
|
|
@ -0,0 +1,59 @@
|
||||||
|
## 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`时，可以只配置一组直线方程系数进行态判断。
|
||||||
|
|
@ -0,0 +1,32 @@
|
||||||
|
## 4.4. 匹配滤波器
|
||||||
|
|
||||||
|
匹配滤波器在FPGA/ASIC两种平台下由于资源不同实现的形式也不同，区别如下：
|
||||||
|
* 由于ASIC多计算少存储，因而ASIC平台使用系数计算模式以节省存储资源。
|
||||||
|
* 由于FPGA 多存储少计算，因此FPGA平台使用系数直读模式以节省DSP资源。
|
||||||
|
|
||||||
|
### 4.4.1. 读出参数存储
|
||||||
|
|
||||||
|
系数计算模式下，匹配滤波器的系数由DDS生成的载波乘以权重参数得到。
|
||||||
|
- 载波的频率和相位由dds_pfd控制，其高20为作为频率控制字，低12位作为相位控制字。
|
||||||
|
- 权重参数的选择由mtf_idx控制，其高16位作为地址，低16位作为长度。
|
||||||
|
- mtf_idx索引得到的权重数据颗粒度是权重数据点，一个数据点可对应多个周期采样点；
|
||||||
|
- 寄存器dds_pfw_q 和mtf_idx_q 的详细定义与查找表中定义保持相同。
|
||||||
|
|
||||||
|
读出系统的的读出参数存储格式如下图所示。
|
||||||
|
FPGA平台下的系数直读模式只使用`Ctrl`部分中的数据，并忽略`dds_pfw`控制字.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
### 4.4.2. 匹配滤波器系数
|
||||||
|
|
||||||
|
ez-Q 2.5 FPGA平台使用系数直读模式，其需要额外的存储空间来配置匹配滤波器系数。
|
||||||
|
- 其中mtf_idx的含义从索引权重数据变为索引匹配滤波器系数。
|
||||||
|
- 匹配滤波器系数索引的粒度是时钟周期，
|
||||||
|
- 在FPGA平台下每个时钟周期对应16个采样点数据。
|
||||||
|
- 匹配滤波器系数采样点采用8比特数据位宽，因此1个周期数据位宽为128 bit，
|
||||||
|
|
||||||
|
匹配滤波器系数存储结构如下图所示。
|
||||||
|
- 匹配滤波器的I和Q数据分开存储，每个比特的I、Q数据容量分别为16 KB。
|
||||||
|
- I路数据偏移地址为x*32KB，Q路数据偏移地址为x*32KB+16 KB，其中x为Qubit序号，范围为0~15。
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -0,0 +1,54 @@
|
||||||
|
## 4.5. 采集数据处理
|
||||||
|
|
||||||
|
ACQ通道采集的数据以流的形式按照先后顺序缓存，
|
||||||
|
缓存到设定数据量后或者计时器超时后数据被打包成帧上传，
|
||||||
|
上位机驱动解帧后以流模式将数据返回给调用接口。
|
||||||
|
当采集多种数据时，用户需要维护采集数据的顺序，
|
||||||
|
从而解析返回数据的含义。
|
||||||
|
建议一个实验仅仅采集一种类型数据以简化数据处理。
|
||||||
|
|
||||||
|
### 4.5.1. 采集波形数据
|
||||||
|
|
||||||
|
波形数据为模拟信号经ADC量化和符号转换后结果，
|
||||||
|
用8比特二进制补码表示，范围对应-128~127；
|
||||||
|
|
||||||
|
* ASIC平台1个时钟周期对应8个采样点(8个字节)
|
||||||
|
* FPGA平台1个时钟周期对应16个采样点（16字节）
|
||||||
|
* 数据采用大端字节序，数据遵循先采先到顺序
|
||||||
|
|
||||||
|
### 4.5.2. 采集IQ数据
|
||||||
|
|
||||||
|
解模计算公式如下：
|
||||||
|
$$
|
||||||
|
I = \\sum_{i=1}^{m}{\\sum_{j=1}^n{\\frac{S_{i,j} * iw_{i,j} * \\cos(\\omega_i t+\\phi_i)}{scale_i} }}
|
||||||
|
$$
|
||||||
|
$$
|
||||||
|
Q = \\sum_{i=1}^{m}{\\sum_{j=1}^n{\\frac{S_{i,j} * qw_{i,j} * \\sin(\\omega_i t+\\phi_i)}{scale_i} }}
|
||||||
|
$$
|
||||||
|
|
||||||
|
* $m$表示解模次数，$n$表示解模的采样点个数；
|
||||||
|
* $S_{i,j}$为输入波形的第i次解模第j个采样点，8比特有符号数
|
||||||
|
* $iw_{i,j}$、$qw_{i,j}$为i、q权重的第i次解模第j个采样点，8比特有符号数
|
||||||
|
* $\\omega_i$、$\\phi_i$分别为第i次解模的频率和相位
|
||||||
|
* $scale_i$为第i次解模的范围选择，可设置为1或者16
|
||||||
|
|
||||||
|
解模频率应设置为输入波形对应频率一遍使得解模结果频率为0，
|
||||||
|
解模结果相位等于解模设置相位设置减去输入波形相位。
|
||||||
|
若解模相位为0，则结果相位等于波形相位取反。
|
||||||
|
解模求和结果I、Q分别用32比特二进制补码表示，解模的结果存储格式如下：
|
||||||
|
|
||||||
|
* 1个完整的数据包含I,Q（8字节）
|
||||||
|
* I先到达，Q后到达
|
||||||
|
* I, Q数据采用大端字节，都占用4个字节
|
||||||
|
|
||||||
|
### 4.5.3. 采集态数据
|
||||||
|
|
||||||
|
* 1个完整数据包含16个qubit态信息（4字节）
|
||||||
|
* 每个量子比特态信息用2个比特表示
|
||||||
|
* 高位表示高序号，即32比特对应{q15,q14,...,q0};
|
||||||
|
|
||||||
|
### 4.5.4. 采态计数数据
|
||||||
|
|
||||||
|
* 1个完整数据包含4个计数器数据（16字节）
|
||||||
|
* 4个计数数据顺序为0态计数器、1态计数器、2态计数器、3态计数器
|
||||||
|
* 计数器采用大端字节序，为32比特无符号数
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
# 4. 处理器ACQ通道编程模型
|
||||||
|
|
||||||
来自量子芯片RO端口的射频信号首先经过混频板模拟电路调理后进入读出基带处理单元采集处理。
|
来自量子芯片RO端口的射频信号首先经过混频板模拟电路调理后进入读出基带处理单元采集处理。
|
||||||
混频板模拟调理电路主要负责将输入功率和频率的信号转换成基带板卡能够处理的中频信号，
|
混频板模拟调理电路主要负责将输入功率和频率的信号转换成基带板卡能够处理的中频信号，
|
||||||
对模拟调理电路的编程包括变频增益控制和变频本振频率控制。
|
对模拟调理电路的编程包括变频增益控制和变频本振频率控制。
|
||||||
|
|
@ -12,7 +14,7 @@
|
||||||
|
|
||||||
目前FPGA平台模拟电路无需配置，下图是FPGA平台ACQ通道数字部分编程控制模型。
|
目前FPGA平台模拟电路无需配置，下图是FPGA平台ACQ通道数字部分编程控制模型。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
- 射频信号经过混频板下变频后进入到ADC
|
- 射频信号经过混频板下变频后进入到ADC
|
||||||
- ADC采集的原始波形数据①从图中右侧端口输入，接着输入到解模模块中
|
- ADC采集的原始波形数据①从图中右侧端口输入，接着输入到解模模块中
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
## 5.1. 码字功能定义
|
||||||
|
|
||||||
AWG模块仅使用码字指令的低13位，其余位保留，
|
AWG模块仅使用码字指令的低13位，其余位保留，
|
||||||
控制码字功能定义如下表所示。
|
控制码字功能定义如下表所示。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,43 @@
|
||||||
|
## 5.2. 寄存器功能定义
|
||||||
|
|
||||||
|
EXCT-Pump通道的全部寄存器可以被SPI和MCU同时访问，
|
||||||
|
用户可以根据需要决定使用SPI还是MCU来控制寄存器的值。
|
||||||
|
|
||||||
|
|名字|功能描述|
|
||||||
|
|:-|:-|
|
||||||
|
|wave_ctrl|寄存器索引波形，包含地址和长度信息|
|
||||||
|
|amplitude|波形输出调制幅度|
|
||||||
|
|Frequency|调制载波频率|
|
||||||
|
|Phase|调制载波相位|
|
||||||
|
|Function|AWG工作模式定义|
|
||||||
|
|pump_ctrl|pump使能脉冲控制|
|
||||||
|
|mark_ctrl|标记使能脉冲控制|
|
||||||
|
|
||||||
|
- `wave_ctrl`波形输出直接控制，可直接从波形仓库取采样点输出。
|
||||||
|
- 高16位为索引地址，单位是时钟周期
|
||||||
|
- 低16为为索引长度，单位是时钟周期
|
||||||
|
- `amplitude`调制幅度控制字
|
||||||
|
- 高16为幅度控制字acw，范围0~16384，归一化幅度$Amp = acw/2^{16}$
|
||||||
|
- `frequency`调制频率控制
|
||||||
|
- 32比特频率控制字fcw，$F_{nco}= fcw/2^{32}*F_s$，其中$F_s$是输出采样率。
|
||||||
|
- `phase`调制相位控制
|
||||||
|
- 高16位相位控制字pcw： $\\phi_{nco} = pcw/2^{16}*2*\\pi$。
|
||||||
|
- `funciton`寄存器用于设置AWG的工作模式
|
||||||
|
- `pump_ctrl`泵浦脉冲使能控制
|
||||||
|
- 高16位控制输出延迟时钟周期，范围（1~65535）
|
||||||
|
- 低16位控制附加持续时钟周期，范围（1~65535）
|
||||||
|
- `mark_ctrl`标记脉冲使能控制
|
||||||
|
- 高16位控制输出延迟时钟周期，范围（1~65535）
|
||||||
|
- 低16位控制脉冲持续时钟周期，范围（1~65535）
|
||||||
|
|
||||||
|
function的详细控制如下所示：
|
||||||
|
|
||||||
|
|比特位|名字|功能描述|
|
||||||
|
|:-|:-|:-|
|
||||||
|
|[3]|INTP_SEL| 插值模式选择，1：半带插值，0：邻近插值|
|
||||||
|
|[2]|MIX_MODE| 混频模式选择，1：混频模式，0：基带模式|
|
||||||
|
|[1:0]|AWG_MODE| AWG模式, 00：直出，01：调制，10：Hilbert，11：NCO|
|
||||||
|
|
||||||
|
* `INTP_SEL`在FPGA平台下受限于DSP资源，只能设置为邻近插值模式。
|
||||||
|
* `MIX_MODE`用于直接输出射频信号，由于采用了模拟混频方案，仅使用基带模式。
|
||||||
|
* `AWG_MODE`设置AWG模式，实验选用直出模式或者调制模式，其余两种模式用于调试。
|
||||||
|
|
@ -0,0 +1,9 @@
|
||||||
|
## 5.3. 波形索引表定义
|
||||||
|
|
||||||
|
波形查找表的深度为256条（1 kB），每个条目的位宽为32比特，
|
||||||
|
其通过8比特的波形id来索引输出波形的参数（地址和长度），最大支持256种不同的输出波形。
|
||||||
|
|
||||||
|
索引表格式定义如下图所示： wave_id是mcu产生的码字，其可以作为地址索引波形控制参数。
|
||||||
|
波形控制参数包括波形地址`addr`和波形长度`len`参数，颗粒度是时钟周期。
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -0,0 +1,9 @@
|
||||||
|
## 5.4. 波形仓库定义
|
||||||
|
|
||||||
|
* ASIC平台下，每个时钟周期对应8个采样点，采样点个数需要为8的整数倍，数据更新率为6 Gsps，每个采样点持续时间为167 皮秒(6 GS/s)。
|
||||||
|
* 在FPGA平台下，每个时钟周期对应16个采样点，采样点个数需要为16的整数倍，数据更新率为 4 GSps，每个采样点持续时间为250皮秒。
|
||||||
|
* 每个采样点为16比特的二进制补码数据；
|
||||||
|
* 波形仓库的容量为128 KB，在FPGA平台和ASIC平台下最大分别支持16 us和10 us波形输出。
|
||||||
|
|
||||||
|
对于EXCT输出频率$F_{out}$（例如6.7 GHz），在本振为$F_{LO}$(例如5.5GHz)本振频率下，
|
||||||
|
则存储区描绘的基带波形频率$F_{s}$为1.2 GHz ，$F_s = F_{out} - F_{LO}$。
|
||||||
|
|
@ -0,0 +1,11 @@
|
||||||
|
## 5.5. EXCT上变频电路配置
|
||||||
|
|
||||||
|
来自读出基带板输出端口的中频信号需要经过混频板上变频电路处理后才能够被发送到量子芯片。
|
||||||
|
前端上变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。
|
||||||
|
目前ez-Q 2.5 FPGA平台硬件暂不支持变频增益设置。
|
||||||
|
|
||||||
|
|配置名|描述|
|
||||||
|
|:-:|:-:|
|
||||||
|
|lo_freq|变频本振频率设置|
|
||||||
|
|
||||||
|
* lo_freq：32比特整数，范围[5400000, 5600000]单位是kHz
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
## 5.6. Pump模拟电路配置
|
||||||
|
|
||||||
|
对处理器Pump通道的编程包括模拟电路配置项和使能配置项。模拟电路用于将Pump通道配置输出一个指定功率和频率的微波信号，而使能配置项用于控制微波信号的实时开关。
|
||||||
|
|
||||||
|
Pump输出时，需要使能输出并配置好输出频率和功率，以下是具体配置项。
|
||||||
|
|
||||||
|
|配置名|描述|
|
||||||
|
|:-|:-|
|
||||||
|
|pump_freq|pump信号输出频率|
|
||||||
|
|pump_power|pump信号输出功率|
|
||||||
|
|pump_enable|pump信号输出使能|
|
||||||
|
|
||||||
|
* pump_freq: 32比特整数，范围[7000000, 9000000], 单位是kHz
|
||||||
|
* pump_power: 32比特整数，范围[-1100, -300]， 具体映射关系取决于硬件
|
||||||
|
* pump_enable: 0x11 为使能，0x00为关闭
|
||||||
|
|
@ -1,3 +1,5 @@
|
||||||
|
# 5. 处理器EXCT-Pump编程模型
|
||||||
|
|
||||||
EXC-Pump通道的编程包括：
|
EXC-Pump通道的编程包括：
|
||||||
MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库和模拟电路配置6类数据。
|
MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库和模拟电路配置6类数据。
|
||||||
- MCU指令+MCU数据可用于编程发出触发码字以及实时修改控制寄存器；
|
- MCU指令+MCU数据可用于编程发出触发码字以及实时修改控制寄存器；
|
||||||
|
|
@ -7,7 +9,7 @@ MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库
|
||||||
|
|
||||||
当前模拟电路仅需配置Pump参数，下图是EXC-Pump通道数字部分的编程控制模型。
|
当前模拟电路仅需配置Pump参数，下图是EXC-Pump通道数字部分的编程控制模型。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
1. EXC-Pump通道的波形输出由AWG模块MCU发出的码字触发。
|
1. EXC-Pump通道的波形输出由AWG模块MCU发出的码字触发。
|
||||||
对于输出波形而言，MCU发出的码字定义波形的索引ID，
|
对于输出波形而言，MCU发出的码字定义波形的索引ID，
|
||||||
|
|
@ -24,11 +26,10 @@ MCU的指令、MCU的数据、控制寄存器、波形索性表、波形仓库
|
||||||
- NCO Only模式：可以输出连续波形，方便连接外部仪器上进行测试，用于芯片本身性能的测试。
|
- NCO Only模式：可以输出连续波形，方便连接外部仪器上进行测试，用于芯片本身性能的测试。
|
||||||
- 希尔伯特虚部模式：输出波形经过希尔伯特变换后的正交部分，仅用于调试。
|
- 希尔伯特虚部模式：输出波形经过希尔伯特变换后的正交部分，仅用于调试。
|
||||||
|
|
||||||
|
|
||||||
最后数字信号经过DAC转换成基带信号，基带信号再和外部本振信号模拟混频后输出读出激励波形。
|
最后数字信号经过DAC转换成基带信号，基带信号再和外部本振信号模拟混频后输出读出激励波形。
|
||||||
读出芯片不同模式输出的频响曲线如下图所示：
|
读出芯片不同模式输出的频响曲线如下图所示：
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
为了兼容混频输出和射频直出两种工作模式以及在FPGA和ASIC平台上实现，半带滤波器和MIX模块都支持旁路功能，因此最终波形输出支持NRZ、MIX、HBNRZ和HBMIX四种模式。
|
为了兼容混频输出和射频直出两种工作模式以及在FPGA和ASIC平台上实现，半带滤波器和MIX模块都支持旁路功能，因此最终波形输出支持NRZ、MIX、HBNRZ和HBMIX四种模式。
|
||||||
|
|
||||||
|
|
@ -0,0 +1,206 @@
|
||||||
|
#!/usr/bin/env python3
|
||||||
|
"""
|
||||||
|
Docs as Code — 构建入口
|
||||||
|
|
||||||
|
读取 project.yaml → 拼接 chapters/*.md → 渲染为自包含 HTML 报告。
|
||||||
|
纯 Python 实现，依赖 requirements.txt 中的 PyYAML, markdown, Jinja2。
|
||||||
|
|
||||||
|
用法:
|
||||||
|
python doc_builder/build.py
|
||||||
|
|
||||||
|
输出:
|
||||||
|
output/读出子系统编程控制模型.html （自包含 HTML，可离线分发）
|
||||||
|
"""
|
||||||
|
|
||||||
|
import os
|
||||||
|
import sys
|
||||||
|
import base64
|
||||||
|
import re
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
import yaml
|
||||||
|
import markdown
|
||||||
|
from jinja2 import Environment, FileSystemLoader
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- 配置 ----------
|
||||||
|
ROOT = Path(__file__).resolve().parent.parent
|
||||||
|
CHAPTERS_DIR = ROOT / "chapters"
|
||||||
|
ASSETS_DIR = ROOT / "assets"
|
||||||
|
OUTPUT_DIR = ROOT / "output"
|
||||||
|
OUTPUT_NAME = "读出子系统编程控制模型.html"
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- 工具函数 ----------
|
||||||
|
|
||||||
|
def load_project_config() -> dict:
|
||||||
|
"""读取 project.yaml 并校验。"""
|
||||||
|
config_path = ROOT / "project.yaml"
|
||||||
|
if not config_path.exists():
|
||||||
|
sys.exit(f"错误: 找不到 {config_path}")
|
||||||
|
with open(config_path, "r", encoding="utf-8") as f:
|
||||||
|
config = yaml.safe_load(f)
|
||||||
|
return config
|
||||||
|
|
||||||
|
|
||||||
|
def resolve_image_path(md_content: str, assets_dir: Path, inline_images: bool = True) -> tuple[str, dict]:
|
||||||
|
"""
|
||||||
|
处理 Markdown 中的图片引用:
|
||||||
|
- 如果 inline_images=True，将图片内嵌为 base64 data URI
|
||||||
|
- 否则转换为相对路径引用
|
||||||
|
|
||||||
|
返回: (处理后的内容, {原始路径: data_uri 字典})
|
||||||
|
"""
|
||||||
|
image_map = {}
|
||||||
|
|
||||||
|
def replace_img(match):
|
||||||
|
alt_text = match.group(1)
|
||||||
|
img_path = match.group(2)
|
||||||
|
|
||||||
|
# 解析路径: ./assets/xxx.png 或 assets/xxx.png
|
||||||
|
if img_path.startswith("./"):
|
||||||
|
img_path = img_path[2:]
|
||||||
|
if img_path.startswith("assets/"):
|
||||||
|
img_path = img_path[7:]
|
||||||
|
|
||||||
|
full_path = assets_dir / img_path
|
||||||
|
if not full_path.exists():
|
||||||
|
print(f" 警告: 找不到图片 {full_path}，保留原始引用")
|
||||||
|
return match.group(0)
|
||||||
|
|
||||||
|
if inline_images:
|
||||||
|
# 内嵌为 base64
|
||||||
|
with open(full_path, "rb") as img_file:
|
||||||
|
img_data = base64.b64encode(img_file.read()).decode("ascii")
|
||||||
|
ext = full_path.suffix.lower()
|
||||||
|
mime_map = {".png": "image/png", ".svg": "image/svg+xml",
|
||||||
|
".jpg": "image/jpeg", ".jpeg": "image/jpeg",
|
||||||
|
".gif": "image/gif"}
|
||||||
|
mime = mime_map.get(ext, "image/png")
|
||||||
|
data_uri = f"data:{mime};base64,{img_data}"
|
||||||
|
image_map[img_path] = data_uri
|
||||||
|
return f""
|
||||||
|
else:
|
||||||
|
return f""
|
||||||
|
|
||||||
|
return re.sub(r'!\[([^\]]*)\]\(\./assets/([^)]+)\)', replace_img, md_content), image_map
|
||||||
|
|
||||||
|
|
||||||
|
def read_and_assemble(config: dict) -> str:
|
||||||
|
"""按 project.yaml 的章节列表拼接所有 chapters/*.md 文件。"""
|
||||||
|
chapters = config.get("chapters", [])
|
||||||
|
if not chapters:
|
||||||
|
sys.exit("错误: project.yaml 中未定义 chapters 列表")
|
||||||
|
|
||||||
|
parts = []
|
||||||
|
for ch_file in chapters:
|
||||||
|
ch_path = CHAPTERS_DIR / ch_file
|
||||||
|
if not ch_path.exists():
|
||||||
|
print(f" 警告: 章节文件不存在，跳过: {ch_file}")
|
||||||
|
continue
|
||||||
|
with open(ch_path, "r", encoding="utf-8") as f:
|
||||||
|
content = f.read()
|
||||||
|
parts.append(content)
|
||||||
|
|
||||||
|
return "\n\n".join(parts)
|
||||||
|
|
||||||
|
|
||||||
|
def extract_toc(md_content: str) -> list[dict]:
|
||||||
|
"""从 Markdown 内容中提取目录结构 (H1, H2)。"""
|
||||||
|
toc = []
|
||||||
|
for line in md_content.split("\n"):
|
||||||
|
m = re.match(r'^(#{1,3})\s+(.+)$', line)
|
||||||
|
if m:
|
||||||
|
level = len(m.group(1))
|
||||||
|
title = m.group(2).strip()
|
||||||
|
# 生成锚点：去除特殊字符，空格转连字符
|
||||||
|
anchor = re.sub(r'[^\w\s一-鿿-]', '', title)
|
||||||
|
anchor = anchor.strip().replace(' ', '-').lower()
|
||||||
|
toc.append({"level": level, "title": title, "anchor": anchor})
|
||||||
|
return toc
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- HTML 生成 ----------
|
||||||
|
|
||||||
|
def generate_html(md_content: str, config: dict) -> str:
|
||||||
|
"""将 Markdown 内容转换为完整的 HTML 页面。"""
|
||||||
|
|
||||||
|
# 处理图片内嵌
|
||||||
|
processed_md, _ = resolve_image_path(md_content, ASSETS_DIR, inline_images=True)
|
||||||
|
|
||||||
|
# Markdown → HTML
|
||||||
|
md_extensions = [
|
||||||
|
"markdown.extensions.tables",
|
||||||
|
"markdown.extensions.fenced_code",
|
||||||
|
"markdown.extensions.codehilite",
|
||||||
|
"markdown.extensions.toc",
|
||||||
|
"markdown.extensions.nl2br",
|
||||||
|
]
|
||||||
|
html_body = markdown.markdown(processed_md, extensions=md_extensions)
|
||||||
|
|
||||||
|
# 提取目录
|
||||||
|
toc = extract_toc(md_content)
|
||||||
|
|
||||||
|
# 加载 Jinja2 模板
|
||||||
|
templates_dir = ROOT / "doc_builder" / "templates"
|
||||||
|
env = Environment(loader=FileSystemLoader(str(templates_dir)))
|
||||||
|
template = env.get_template("report.html")
|
||||||
|
|
||||||
|
# 读取主题 CSS
|
||||||
|
themes_dir = ROOT / "doc_builder" / "themes"
|
||||||
|
css_screen = ""
|
||||||
|
css_print = ""
|
||||||
|
screen_css_path = themes_dir / "report.css"
|
||||||
|
print_css_path = themes_dir / "print.css"
|
||||||
|
if screen_css_path.exists():
|
||||||
|
css_screen = screen_css_path.read_text(encoding="utf-8")
|
||||||
|
if print_css_path.exists():
|
||||||
|
css_print = print_css_path.read_text(encoding="utf-8")
|
||||||
|
|
||||||
|
return template.render(
|
||||||
|
title=config.get("title", "文档"),
|
||||||
|
subtitle=config.get("subtitle", ""),
|
||||||
|
author=config.get("author", ""),
|
||||||
|
version=config.get("version", ""),
|
||||||
|
toc=toc,
|
||||||
|
body=html_body,
|
||||||
|
css_screen=css_screen,
|
||||||
|
css_print=css_print,
|
||||||
|
)
|
||||||
|
|
||||||
|
|
||||||
|
# ---------- 主入口 ----------
|
||||||
|
|
||||||
|
def main():
|
||||||
|
print("=== ez-Q 2.5 读出子系统编程控制模型 构建 ===")
|
||||||
|
print()
|
||||||
|
|
||||||
|
# 1. 加载配置
|
||||||
|
print("[1/3] 读取 project.yaml ...")
|
||||||
|
config = load_project_config()
|
||||||
|
print(f" 项目: {config.get('title', '未命名')}")
|
||||||
|
print(f" 版本: {config.get('version', 'N/A')}")
|
||||||
|
print(f" 章节数: {len(config.get('chapters', []))}")
|
||||||
|
|
||||||
|
# 2. 拼接章节
|
||||||
|
print("[2/3] 拼接章节 ...")
|
||||||
|
assembled = read_and_assemble(config)
|
||||||
|
print(f" 总字符数: {len(assembled)}")
|
||||||
|
|
||||||
|
# 3. 生成 HTML
|
||||||
|
print("[3/3] 生成 HTML ...")
|
||||||
|
html = generate_html(assembled, config)
|
||||||
|
|
||||||
|
# 4. 输出
|
||||||
|
OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
|
||||||
|
output_path = OUTPUT_DIR / OUTPUT_NAME
|
||||||
|
output_path.write_text(html, encoding="utf-8")
|
||||||
|
print(f" 输出: {output_path}")
|
||||||
|
print(f" 文件大小: {output_path.stat().st_size:,} 字节")
|
||||||
|
|
||||||
|
print()
|
||||||
|
print("Build completed successfully!")
|
||||||
|
|
||||||
|
|
||||||
|
if __name__ == "__main__":
|
||||||
|
main()
|
||||||
|
|
@ -0,0 +1,74 @@
|
||||||
|
<!DOCTYPE html>
|
||||||
|
<html lang="zh-CN">
|
||||||
|
<head>
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||||
|
<meta name="author" content="{{ author }}">
|
||||||
|
<title>{{ title }} — {{ version }}</title>
|
||||||
|
|
||||||
|
{# KaTeX 数学公式支持 #}
|
||||||
|
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css">
|
||||||
|
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.js"></script>
|
||||||
|
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/contrib/auto-render.min.js"></script>
|
||||||
|
|
||||||
|
<style>
|
||||||
|
{{ css_screen }}
|
||||||
|
</style>
|
||||||
|
|
||||||
|
{# 打印样式 #}
|
||||||
|
<style media="print">
|
||||||
|
{{ css_print }}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
|
||||||
|
<header class="report-header">
|
||||||
|
<h1 class="report-title">{{ title }}</h1>
|
||||||
|
{% if subtitle %}
|
||||||
|
<p class="report-subtitle">{{ subtitle }}</p>
|
||||||
|
{% endif %}
|
||||||
|
<div class="report-meta">
|
||||||
|
<span>版本: {{ version }}</span>
|
||||||
|
<span>作者: {{ author }}</span>
|
||||||
|
</div>
|
||||||
|
</header>
|
||||||
|
|
||||||
|
{# 侧边栏目录 #}
|
||||||
|
<nav class="sidebar-toc">
|
||||||
|
<h2>目录</h2>
|
||||||
|
<ul>
|
||||||
|
{% for item in toc %}
|
||||||
|
{% if item.level == 1 %}
|
||||||
|
<li class="toc-h1"><a href="#{{ item.anchor }}">{{ item.title }}</a></li>
|
||||||
|
{% elif item.level == 2 %}
|
||||||
|
<li class="toc-h2"><a href="#{{ item.anchor }}">{{ item.title }}</a></li>
|
||||||
|
{% elif item.level == 3 %}
|
||||||
|
<li class="toc-h3"><a href="#{{ item.anchor }}">{{ item.title }}</a></li>
|
||||||
|
{% endif %}
|
||||||
|
{% endfor %}
|
||||||
|
</ul>
|
||||||
|
</nav>
|
||||||
|
|
||||||
|
{# 正文内容 #}
|
||||||
|
<main class="report-body">
|
||||||
|
{{ body }}
|
||||||
|
</main>
|
||||||
|
|
||||||
|
<footer class="report-footer">
|
||||||
|
<p>{{ title }} — {{ version }} — {{ author }}</p>
|
||||||
|
</footer>
|
||||||
|
|
||||||
|
{# KaTeX 自动渲染 #}
|
||||||
|
<script>
|
||||||
|
document.addEventListener("DOMContentLoaded", function () {
|
||||||
|
renderMathInElement(document.body, {
|
||||||
|
delimiters: [
|
||||||
|
{left: "$$", right: "$$", display: true},
|
||||||
|
{left: "$", right: "$", display: false}
|
||||||
|
]
|
||||||
|
});
|
||||||
|
});
|
||||||
|
</script>
|
||||||
|
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
|
@ -0,0 +1,60 @@
|
||||||
|
/* ============================================
|
||||||
|
ez-Q 2.5 读出子系统编程控制模型 — 打印样式
|
||||||
|
============================================ */
|
||||||
|
|
||||||
|
@media print {
|
||||||
|
body {
|
||||||
|
font-size: 12pt;
|
||||||
|
color: #000;
|
||||||
|
background: #fff;
|
||||||
|
}
|
||||||
|
|
||||||
|
.sidebar-toc {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-header {
|
||||||
|
background: none;
|
||||||
|
color: #000;
|
||||||
|
padding: 1em 0;
|
||||||
|
border-bottom: 2px solid #000;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body {
|
||||||
|
max-width: 100%;
|
||||||
|
padding: 1em 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body h1 {
|
||||||
|
page-break-before: always;
|
||||||
|
font-size: 16pt;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body h2 {
|
||||||
|
font-size: 14pt;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body h3 {
|
||||||
|
font-size: 12pt;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body pre {
|
||||||
|
border: 1px solid #ccc;
|
||||||
|
background: #f9f9f9;
|
||||||
|
page-break-inside: avoid;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body table {
|
||||||
|
page-break-inside: avoid;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body img {
|
||||||
|
max-width: 100%;
|
||||||
|
page-break-inside: avoid;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-footer {
|
||||||
|
border-top: 1px solid #000;
|
||||||
|
font-size: 10pt;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,246 @@
|
||||||
|
/* ============================================
|
||||||
|
ez-Q 2.5 读出子系统编程控制模型 — 屏幕样式
|
||||||
|
============================================ */
|
||||||
|
|
||||||
|
:root {
|
||||||
|
--primary: #1a237e;
|
||||||
|
--accent: #283593;
|
||||||
|
--bg-light: #f5f5f5;
|
||||||
|
--bg-white: #ffffff;
|
||||||
|
--text: #333333;
|
||||||
|
--text-light: #5c5c5c;
|
||||||
|
--border: #d6d6d6;
|
||||||
|
--code-bg: #f0f0f0;
|
||||||
|
--sidebar-width: 280px;
|
||||||
|
}
|
||||||
|
|
||||||
|
* {
|
||||||
|
box-sizing: border-box;
|
||||||
|
margin: 0;
|
||||||
|
padding: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
body {
|
||||||
|
font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, 'Microsoft YaHei', sans-serif;
|
||||||
|
font-size: 16px;
|
||||||
|
line-height: 1.8;
|
||||||
|
color: var(--text);
|
||||||
|
background-color: var(--bg-white);
|
||||||
|
display: flex;
|
||||||
|
flex-wrap: wrap;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- 页头 ---- */
|
||||||
|
.report-header {
|
||||||
|
width: 100%;
|
||||||
|
background: linear-gradient(135deg, var(--primary), var(--accent));
|
||||||
|
color: white;
|
||||||
|
padding: 2em 2em 1.5em;
|
||||||
|
text-align: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-title {
|
||||||
|
font-size: 2em;
|
||||||
|
font-weight: 600;
|
||||||
|
margin-bottom: 0.25em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-subtitle {
|
||||||
|
font-size: 1.1em;
|
||||||
|
opacity: 0.85;
|
||||||
|
margin-bottom: 0.75em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-meta {
|
||||||
|
font-size: 0.9em;
|
||||||
|
opacity: 0.8;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-meta span {
|
||||||
|
margin: 0 1em;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- 侧边栏 ---- */
|
||||||
|
.sidebar-toc {
|
||||||
|
width: var(--sidebar-width);
|
||||||
|
min-width: var(--sidebar-width);
|
||||||
|
padding: 1.5em 1em;
|
||||||
|
background: var(--bg-light);
|
||||||
|
border-right: 1px solid var(--border);
|
||||||
|
position: sticky;
|
||||||
|
top: 0;
|
||||||
|
height: 100vh;
|
||||||
|
overflow-y: auto;
|
||||||
|
font-size: 14px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.sidebar-toc h2 {
|
||||||
|
font-size: 1.1em;
|
||||||
|
margin-bottom: 0.75em;
|
||||||
|
color: var(--primary);
|
||||||
|
}
|
||||||
|
|
||||||
|
.sidebar-toc ul {
|
||||||
|
list-style: none;
|
||||||
|
padding: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.sidebar-toc li {
|
||||||
|
margin: 0.25em 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.sidebar-toc a {
|
||||||
|
color: var(--text);
|
||||||
|
text-decoration: none;
|
||||||
|
display: block;
|
||||||
|
padding: 0.15em 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.sidebar-toc a:hover {
|
||||||
|
color: var(--primary);
|
||||||
|
}
|
||||||
|
|
||||||
|
.toc-h1 { font-weight: 600; margin-top: 0.5em; }
|
||||||
|
.toc-h2 { padding-left: 1em; }
|
||||||
|
.toc-h3 { padding-left: 2em; font-size: 0.95em; color: var(--text-light); }
|
||||||
|
|
||||||
|
/* ---- 正文 ---- */
|
||||||
|
.report-body {
|
||||||
|
flex: 1;
|
||||||
|
min-width: 0;
|
||||||
|
max-width: 900px;
|
||||||
|
padding: 2em 2.5em 4em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body h1 {
|
||||||
|
font-size: 1.8em;
|
||||||
|
font-weight: 600;
|
||||||
|
margin: 1.2em 0 0.6em;
|
||||||
|
padding-bottom: 0.3em;
|
||||||
|
border-bottom: 2px solid var(--primary);
|
||||||
|
color: var(--primary);
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body h2 {
|
||||||
|
font-size: 1.4em;
|
||||||
|
font-weight: 600;
|
||||||
|
margin: 1em 0 0.5em;
|
||||||
|
color: var(--accent);
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body h3 {
|
||||||
|
font-size: 1.15em;
|
||||||
|
font-weight: 600;
|
||||||
|
margin: 0.8em 0 0.4em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body p {
|
||||||
|
margin: 0.5em 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body img {
|
||||||
|
max-width: 100%;
|
||||||
|
display: block;
|
||||||
|
margin: 1em auto;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- 表格 ---- */
|
||||||
|
.report-body table {
|
||||||
|
width: 100%;
|
||||||
|
border-collapse: collapse;
|
||||||
|
margin: 0.75em 0 1.25em;
|
||||||
|
font-size: 0.95em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body th,
|
||||||
|
.report-body td {
|
||||||
|
border: 1px solid var(--border);
|
||||||
|
padding: 6px 12px;
|
||||||
|
text-align: left;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body th {
|
||||||
|
background: var(--bg-light);
|
||||||
|
font-weight: 600;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- 代码块 ---- */
|
||||||
|
.report-body code {
|
||||||
|
font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
|
||||||
|
font-size: 0.9em;
|
||||||
|
background: var(--code-bg);
|
||||||
|
padding: 0.15em 0.35em;
|
||||||
|
border-radius: 3px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body pre {
|
||||||
|
background: var(--bg-light);
|
||||||
|
padding: 1em 1.2em;
|
||||||
|
border-radius: 4px;
|
||||||
|
border: 1px solid var(--border);
|
||||||
|
overflow-x: auto;
|
||||||
|
margin: 0.75em 0;
|
||||||
|
font-size: 0.9em;
|
||||||
|
line-height: 1.5;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body pre code {
|
||||||
|
background: none;
|
||||||
|
padding: 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- 引用块 ---- */
|
||||||
|
.report-body blockquote {
|
||||||
|
margin: 0.75em 0;
|
||||||
|
padding: 0.5em 1em;
|
||||||
|
background: var(--bg-light);
|
||||||
|
border-left: 4px solid var(--border);
|
||||||
|
color: var(--text-light);
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- 列表 ---- */
|
||||||
|
.report-body ul,
|
||||||
|
.report-body ol {
|
||||||
|
margin: 0.5em 0;
|
||||||
|
padding-left: 2em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body li {
|
||||||
|
margin: 0.15em 0;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- 页脚 ---- */
|
||||||
|
.report-footer {
|
||||||
|
width: 100%;
|
||||||
|
text-align: center;
|
||||||
|
padding: 1.5em;
|
||||||
|
font-size: 0.85em;
|
||||||
|
color: var(--text-light);
|
||||||
|
border-top: 1px solid var(--border);
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- KaTeX 公式 ---- */
|
||||||
|
.katex-display {
|
||||||
|
margin: 0.75em 0;
|
||||||
|
overflow-x: auto;
|
||||||
|
overflow-y: hidden;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* ---- 移动端响应式 ---- */
|
||||||
|
@media screen and (max-width: 768px) {
|
||||||
|
.sidebar-toc {
|
||||||
|
display: none;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-body {
|
||||||
|
padding: 1em 1.2em 3em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-header {
|
||||||
|
padding: 1.5em 1em 1em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.report-title {
|
||||||
|
font-size: 1.5em;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,24 @@
|
||||||
|
# ez-Q 2.5 读出子系统编程控制模型
|
||||||
|
title: 读出子系统历史无关功能配置项
|
||||||
|
subtitle: ez-Q 2.5 读出子系统编程控制模型
|
||||||
|
author: 郭成
|
||||||
|
version: V0.2
|
||||||
|
lang: zh-CN
|
||||||
|
|
||||||
|
chapters:
|
||||||
|
- 01-changelog.md
|
||||||
|
- 02-preface.md
|
||||||
|
- 03-overview.md
|
||||||
|
- 04-acq-model.md
|
||||||
|
- 04-01-acq-downconversion.md
|
||||||
|
- 04-02-acq-codeword.md
|
||||||
|
- 04-03-acq-registers.md
|
||||||
|
- 04-04-acq-matched-filter.md
|
||||||
|
- 04-05-acq-data-processing.md
|
||||||
|
- 05-exct-model.md
|
||||||
|
- 05-01-exct-codeword.md
|
||||||
|
- 05-02-exct-registers.md
|
||||||
|
- 05-03-exct-wavetable.md
|
||||||
|
- 05-04-exct-waveform-store.md
|
||||||
|
- 05-05-exct-upconversion.md
|
||||||
|
- 05-06-pump-config.md
|
||||||
|
|
@ -0,0 +1,5 @@
|
||||||
|
# ez-Q 2.5 读出子系统编程控制模型 构建依赖
|
||||||
|
# 安装: pip install -r requirements.txt
|
||||||
|
PyYAML>=6.0
|
||||||
|
markdown>=3.5
|
||||||
|
Jinja2>=3.1
|
||||||
379
读出子系统编程控制模型.md
379
读出子系统编程控制模型.md
|
|
@ -1,379 +0,0 @@
|
||||||
---
|
|
||||||
export_on_save:
|
|
||||||
html: true
|
|
||||||
|
|
||||||
html:
|
|
||||||
toc: true
|
|
||||||
embed_local_images: true
|
|
||||||
embed_svg: true
|
|
||||||
|
|
||||||
title: 读出子系统历史无关功能配置项
|
|
||||||
author: 郭成
|
|
||||||
date:
|
|
||||||
---
|
|
||||||
|
|
||||||
# 1. 修订记录
|
|
||||||
|版本|修订日期|修订原因|修订内容|修订人|
|
|
||||||
|:-|:-|:-|:-|:-|
|
|
||||||
|v0.1|2025/10/27|统一格式|初始版本|郭成|
|
|
||||||
|v0.2|2025/10/31|评审意见|内容补充|郭成|
|
|
||||||
|
|
||||||
# 2. 前言
|
|
||||||
## 2.1. 目的与范围
|
|
||||||
本文档的目的是介绍读出芯片激励产生和采集处理相关控制，
|
|
||||||
该文档适用于ez-Q 2.5 FPGA/ASIC平台读出子系统编程。
|
|
||||||
本文档作为开放文档供大家阅读。
|
|
||||||
|
|
||||||
## 2.2. 阅读对象
|
|
||||||
本文档的预期读者是所有使用本芯片的用户以及对该芯片工作原理感兴趣的读者。
|
|
||||||
|
|
||||||
## 2.3. 文档概述
|
|
||||||
本文档首先介绍了测控系统总体的编程对象和规范，
|
|
||||||
针对读出ACQ/EXCT/Pump三种类型通道对应的ACQ/EXCT-Pump编程模型进行了详细介绍。
|
|
||||||
|
|
||||||
## 2.4. 引用文档
|
|
||||||
|文档编号|标题|版本|
|
|
||||||
|:-|:-|:-|
|
|
||||||
|-|读出子系统历史无关配置集.md|V1.0|
|
|
||||||
|-|读出子系统IDS表.xls|V1.0|
|
|
||||||
|ez-Q 2.5-SDD-04|ez-Q 2.5 测控系统研制项目指令集设计报告_V1.0.docx|V1.0|
|
|
||||||
|
|
||||||
## 2.5. 术语定义
|
|
||||||
|名字|全称|解释|
|
|
||||||
|:-|:-|:-|
|
|
||||||
|ACQ|Acquisition|读出回波采集处理通道|
|
|
||||||
|EXCT|Excitation|读出激励生成发送通道|
|
|
||||||
|
|
||||||
# 3. 编程控制模型概述
|
|
||||||
|
|
||||||
## 3.1. 1 测控系统编程概述
|
|
||||||
超导量子计算机利用微波信号来驱动量子比特和读出量子比特状态，量子比特不同类型的操作依赖不同类型的信号来控制。
|
|
||||||
ez-Q 2.5测控系统包含5种物理通道，对应5类硬件接口，分别是ACQ、EXCT、Pump、XYZ/Reset和ZCP通道；
|
|
||||||
系统具有7种控制信号，对应7种编程对象，分别是EXCT、ACQ、Pump、XY、Reset、Z和ZCP信号；
|
|
||||||
系统具有4种控制模型，对应4种编程类型，分别是ACQ、EXCT-Pump、XY/Reset和Z/ZCP模型，分类关系如下表所示。
|
|
||||||
|
|
||||||
|5种物理通道|7种控制对象|4种控制模型|
|
|
||||||
|:-:|:-:|:-:|
|
|
||||||
|XYZ通道|XY 信号|XY/Reset控制模型|
|
|
||||||
|^|Reset信号|^|
|
|
||||||
|^|Z信号|Z/ZCP控制模型|
|
|
||||||
|ZCP通道|ZCP信号|Z/ZCP控制模型|
|
|
||||||
|ACQ通道|ACQ(RO)信号|ACQ控制模型|
|
|
||||||
|EXCT通道|EXCT(RI)信号|EXCT-Pump控制模型|
|
|
||||||
|Pump通道|Pump信号|^|
|
|
||||||
|
|
||||||
- 测控系统中的每种控制模型实现的功能都是通过以下四类数据进行定义，
|
|
||||||
- 通道微控制器码字指令
|
|
||||||
- 通道寄存器配置数据
|
|
||||||
- 通道SRAM配置数据
|
|
||||||
- 通道模拟电路配置
|
|
||||||
|
|
||||||
- 测控系统的寄存器、配置数据和模拟电路配置返回数据统一采用**大端字节序**。
|
|
||||||
|
|
||||||
通道寄存器配置数据支持微控制器实时修改，从而让通道的输入/输出控制具备动态控制能力。
|
|
||||||
ACQ和EXCT-Pump通道配置寄存器定义参考[读出子系统IDS表.xls](TODO)的`DAQ_REG`和`AWG_REG`页。
|
|
||||||
ACQ的配置数据定义参考
|
|
||||||
|
|
||||||
本文档通过对不同编程模型下码字指令、通道寄存器配置数据、通道SRAM配置数据和通道模拟电路配置进行介绍，
|
|
||||||
旨在让用户掌握对读出激励信号的产生和采集信号处理的编程方法。
|
|
||||||
其中码字指令通过MCU来产生，MCU的编程关键参数如下：
|
|
||||||
|
|
||||||
* ACQ通道和EXCT-Pump通道使用**相同MCU**；
|
|
||||||
* MCU分别使用**16 KB**的ITCM和DTCM；
|
|
||||||
* FPGA平台MCU主时钟频率为**250 MHz**，
|
|
||||||
* ASIC平台MCU主钟频率暂定**750 MHz**；
|
|
||||||
* MCU以固定的**3个时钟周期每指令**的速度运行；
|
|
||||||
* MCU通过**0x100000**地址访问MCU数据空间；
|
|
||||||
* MCU通道**0x200000**地址访问通道配置寄存器空间；
|
|
||||||
|
|
||||||
针对具体的指令定义和使用方法，
|
|
||||||
读者可查看[《量子编程指令集》](TODO)了解相关信息。
|
|
||||||
|
|
||||||
|
|
||||||
## 3.2. 2 读出子系统编程
|
|
||||||
ez-Q 2.5 ASIC平台读出子系统由读出基带板、读出混频板和读出泵浦板三个硬件组成
|
|
||||||
- 三个板卡以PXIe板卡的形式安装在机箱中位置相邻的三个槽位上
|
|
||||||
- 混频板的槽位号比基带板大1，泵浦板槽位号比基带板槽位号小1
|
|
||||||
|
|
||||||
因此可以通过仅指定读出基带板槽位号来定位混频板和泵浦板槽位号，
|
|
||||||
读出子系统硬件架构如下图所示。
|
|
||||||
- 读出基带板负责产生、输出、采集和处理基带信号以及为泵浦通道产生使能信号；
|
|
||||||
- 读出混频板自身产生一个本振信号，用于实现基带信号与射频信号之间的转换；
|
|
||||||
- 而读出泵浦板负责产生一个指定功率频率的单音信号，并在外部使能信号控制下输出；
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
当软件需要对不同通道编程时，其通过ip地址指定机箱、通过槽位号指定板卡、
|
|
||||||
通过扩展地址指定同一个板卡内的多个通道、通过地址指定一个通道内的不同配置项。
|
|
||||||
|
|
||||||
```
|
|
||||||
索引基地址由《读出子系统IDS表.xls》的mapping页定义，本文不对地址翻译进行赘述。
|
|
||||||
```
|
|
||||||
|
|
||||||
本文所述的三类编程通道具体定义如下：
|
|
||||||
* ACQ 编程通道定义从混频板`rf_in`输入端口到基带板卡内部DAQ模块；
|
|
||||||
* EXCT 编程通道定义为从基带板内部AWG模块混频板到`rf_out`接口；
|
|
||||||
* Pump 编程通道定义为从基带板卡内部AWG模块到泵浦板`pump_out`接口；
|
|
||||||
|
|
||||||
ASIC和FPGA平台具有以下区别：
|
|
||||||
* ez-Q 2.5 FPGA平台读出子系统混频板和泵浦板复用同一个硬件板卡。
|
|
||||||
* ez-Q 2.5 FPGA平台将读出基带芯片RBPU和FPGA集成在一个FPGA中。
|
|
||||||
* ez-Q 2.5 FPGA平台使用外部商用ADC、DAC和PLL来替换RBPU的对应功能。
|
|
||||||
* ez-Q 2.5 FPGA平台ADC、DAC采样率为4 Gsps, ASIC平台暂定为6 Gsps
|
|
||||||
|
|
||||||
# 4. 处理器ACQ通道编程模型
|
|
||||||
|
|
||||||
@import "ro_datapath.md"
|
|
||||||
|
|
||||||
## 4.1. 下变频电路配置
|
|
||||||
|
|
||||||
来自量子比特RO端口的射频信号需要经过前端模拟电路处理后才能够被读出基带处理单元采集处理。
|
|
||||||
前端下变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。
|
|
||||||
|
|
||||||
|配置名|描述|
|
|
||||||
|:-:|:-:|
|
|
||||||
|lo_freq|变频本振频率设置|
|
|
||||||
|mix_gain|下变频增益设置|
|
|
||||||
|
|
||||||
```
|
|
||||||
目前ez-Q 2.5 FPGA平台暂不支持下变频增益
|
|
||||||
mix_gain 设置；仅支持 lo_freq 变频本振频率设置
|
|
||||||
```
|
|
||||||
|
|
||||||
## 4.2. ACQ码字功能定义
|
|
||||||
@import "ro_codeword.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`时，可以只配置一组直线方程系数进行态判断。
|
|
||||||
|
|
||||||
## 4.4. 匹配滤波器
|
|
||||||
匹配滤波器在FPGA/ASIC两种平台下由于资源不同实现的形式也不同，区别如下：
|
|
||||||
* 由于ASIC多计算少存储，因而ASIC平台使用系数计算模式以节省存储资源。
|
|
||||||
* 由于FPGA 多存储少计算，因此FPGA平台使用系数直读模式以节省DSP资源。
|
|
||||||
|
|
||||||
### 4.4.1. 读出参数存储
|
|
||||||
|
|
||||||
|
|
||||||
系数计算模式下，匹配滤波器的系数由DDS生成的载波乘以权重参数得到。
|
|
||||||
- 载波的频率和相位由dds_pfd控制，其高20为作为频率控制字，低12位作为相位控制字。
|
|
||||||
- 权重参数的选择由mtf_idx控制，其高16位作为地址，低16位作为长度。
|
|
||||||
- mtf_idx索引得到的权重数据颗粒度是权重数据点，一个数据点可对应多个周期采样点；
|
|
||||||
- 寄存器dds_pfw_q 和mtf_idx_q 的详细定义与查找表中定义保持相同。
|
|
||||||
|
|
||||||
读出系统的的读出参数存储格式如下图所示。
|
|
||||||
FPGA平台下的系数直读模式只使用`Ctrl`部分中的数据，并忽略`dds_pfw`控制字.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### 4.4.2. 匹配滤波器系数
|
|
||||||
|
|
||||||
ez-Q 2.5 FPGA平台使用系数直读模式，其需要额外的存储空间来配置匹配滤波器系数。
|
|
||||||
- 其中mtf_idx的含义从索引权重数据变为索引匹配滤波器系数。
|
|
||||||
- 匹配滤波器系数索引的粒度是时钟周期，
|
|
||||||
- 在FPGA平台下每个时钟周期对应16个采样点数据。
|
|
||||||
- 匹配滤波器系数采样点采用8比特数据位宽，因此1个周期数据位宽为128 bit，
|
|
||||||
|
|
||||||
匹配滤波器系数存储结构如下图所示。
|
|
||||||
- 匹配滤波器的I和Q数据分开存储，每个比特的I、Q数据容量分别为16 KB。
|
|
||||||
- I路数据偏移地址为x*32KB，Q路数据偏移地址为x*32KB+16 KB，其中x为Qubit序号，范围为0~15。
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## 4.5. 采集数据处理
|
|
||||||
ACQ通道采集的数据以流的形式按照先后顺序缓存，
|
|
||||||
缓存到设定数据量后或者计时器超时后数据被打包成帧上传，
|
|
||||||
上位机驱动解帧后以流模式将数据返回给调用接口。
|
|
||||||
当采集多种数据时，用户需要维护采集数据的顺序，
|
|
||||||
从而解析返回数据的含义。
|
|
||||||
建议一个实验仅仅采集一种类型数据以简化数据处理。
|
|
||||||
|
|
||||||
### 4.5.1. 采集波形数据
|
|
||||||
波形数据为模拟信号经ADC量化和符号转换后结果，
|
|
||||||
用8比特二进制补码表示，范围对应-128~127；
|
|
||||||
|
|
||||||
* ASIC平台1个时钟周期对应8个采样点(8个字节)
|
|
||||||
* FPGA平台1个时钟周期对应16个采样点（16字节）
|
|
||||||
* 数据采用大端字节序，数据遵循先采先到顺序
|
|
||||||
|
|
||||||
### 4.5.2. 采集IQ数据
|
|
||||||
解模计算公式如下：
|
|
||||||
$$
|
|
||||||
I = \sum_{i=1}^{m}{\sum_{j=1}^n{\frac{S_{i,j} * iw_{i,j} * cos(\omega_i t+\phi_i)}{scale_i} }}
|
|
||||||
$$
|
|
||||||
$$
|
|
||||||
Q = \sum_{i=1}^{m}{\sum_{j=1}^n{\frac{S_{i,j} * qw_{i,j} * sin(\omega_i t+\phi_i)}{scale_i} }}
|
|
||||||
$$
|
|
||||||
|
|
||||||
* $m$表示解模次数，$n$表示解模的采样点个数；
|
|
||||||
* $S_{i,j}$为输入波形的第i次解模第j个采样点，8比特有符号数
|
|
||||||
* $iw_{i,j}$、$qw_{i,j}$为i、q权重的第i次解模第j个采样点，8比特有符号数
|
|
||||||
* $\omega_i$、$\phi_i$分别为第i次解模的频率和相位
|
|
||||||
* $scale_i$为第i次解模的范围选择，可设置为1或者16
|
|
||||||
|
|
||||||
|
|
||||||
解模频率应设置为输入波形对应频率一遍使得解模结果频率为0，
|
|
||||||
解模结果相位等于解模设置相位设置减去输入波形相位。
|
|
||||||
若解模相位为0，则结果相位等于波形相位取反。
|
|
||||||
解模求和结果I、Q分别用32比特二进制补码表示，解模的结果存储格式如下：
|
|
||||||
|
|
||||||
* 1个完整的数据包含I,Q（8字节）
|
|
||||||
* I先到达，Q后到达
|
|
||||||
* I, Q数据采用大端字节，都占用4个字节
|
|
||||||
|
|
||||||
### 4.5.3. 采集态数据
|
|
||||||
* 1个完整数据包含16个qubit态信息（4字节）
|
|
||||||
* 每个量子比特态信息用2个比特表示
|
|
||||||
* 高位表示高序号，即32比特对应{q15,q14,...,q0};
|
|
||||||
|
|
||||||
### 4.5.4. 采态计数数据
|
|
||||||
* 1个完整数据包含4个计数器数据（16字节）
|
|
||||||
* 4个计数数据顺序为0态计数器、1态计数器、2态计数器、3态计数器
|
|
||||||
* 计数器采用大端字节序，为32比特无符号数
|
|
||||||
|
|
||||||
# 5. 处理器EXCT-Pump编程模型
|
|
||||||
|
|
||||||
@import "ri_datapath.md"
|
|
||||||
|
|
||||||
## 5.1. 1 码字功能定义
|
|
||||||
@import "ri_codeword.md"
|
|
||||||
|
|
||||||
## 5.2. 2 寄存器功能定义
|
|
||||||
EXCT-Pump通道的全部寄存器可以被SPI和MCU同时访问，
|
|
||||||
用户可以根据需要决定使用SPI还是MCU来控制寄存器的值。
|
|
||||||
|名字|功能描述|
|
|
||||||
|:-|:-|
|
|
||||||
|wave_ctrl|寄存器索引波形，包含地址和长度信息|
|
|
||||||
|amplitude|波形输出调制幅度|
|
|
||||||
|Frequency|调制载波频率|
|
|
||||||
|Phase|调制载波相位|
|
|
||||||
|Function|AWG工作模式定义|
|
|
||||||
|pump_ctrl|pump使能脉冲控制|
|
|
||||||
|mark_ctrl|标记使能脉冲控制|
|
|
||||||
|
|
||||||
- `wave_ctrl`波形输出直接控制，可直接从波形仓库取采样点输出。
|
|
||||||
- 高16位为索引地址，单位是时钟周期
|
|
||||||
- 低16为为索引长度，单位是时钟周期
|
|
||||||
- `amplitude`调制幅度控制字
|
|
||||||
- 高16为幅度控制字acw，范围0\~16384，归一化幅度$Amp = acw/2^{16}$
|
|
||||||
- `frequency`调制频率控制
|
|
||||||
- 32比特频率控制字fcw，$F_{nco}= fcw/2^{32}*F_s$，其中$F_s$是输出采样率。
|
|
||||||
- `phase`调制相位控制
|
|
||||||
- 高16位相位控制字pcw： $\phi_{nco} = pcw/2^{16}*2*\pi$。
|
|
||||||
- `funciton`寄存器用于设置AWG的工作模式
|
|
||||||
- `pump_ctrl`泵浦脉冲使能控制
|
|
||||||
- 高16位控制输出延迟时钟周期，范围（1~65535）
|
|
||||||
- 低16位控制附加持续时钟周期，范围（1~65535）
|
|
||||||
- `mark_ctrl`标记脉冲使能控制
|
|
||||||
- 高16位控制输出延迟时钟周期，范围（1~65535）
|
|
||||||
- 低16位控制脉冲持续时钟周期，范围（1~65535）
|
|
||||||
|
|
||||||
function的详细控制如下所示：
|
|
||||||
|比特位|名字|功能描述|
|
|
||||||
|:-|:-|:-|
|
|
||||||
|[3]|INTP_SEL| 插值模式选择，1：半带插值，0：邻近插值|
|
|
||||||
|[2]|MIX_MODE| 混频模式选择，1：混频模式，0：基带模式|
|
|
||||||
|[1:0]|AWG_MODE| AWG模式, 00：直出，01：调制，10：Hilbert，11：NCO|
|
|
||||||
|
|
||||||
* `INTP_SEL`在FPGA平台下受限于DSP资源，只能设置为邻近插值模式。
|
|
||||||
* `MIX_MODE`用于直接输出射频信号，由于采用了模拟混频方案，仅使用基带模式。
|
|
||||||
* `AWG_MODE`设置AWG模式，实验选用直出模式或者调制模式，其余两种模式用于调试。
|
|
||||||
|
|
||||||
## 5.3. 3 波形索引表定义
|
|
||||||
波形查找表的深度为256条（1 kB），每个条目的位宽为32比特，
|
|
||||||
其通过8比特的波形id来索引输出波形的参数（地址和长度），最大支持256种不同的输出波形。
|
|
||||||
|
|
||||||
索引表格式定义如下图所示： wave_id是mcu产生的码字，其可以作为地址索引波形控制参数。
|
|
||||||
波形控制参数包括波形地址`addr`和波形长度`len`参数，颗粒度是时钟周期。
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## 5.4. 4 波形仓库定义
|
|
||||||
* ASIC平台下，每个时钟周期对应8个采样点，采样点个数需要为8的整数倍，数据更新率为6 Gsps，每个采样点持续时间为167 皮秒(6 GS/s)。
|
|
||||||
* 在FPGA平台下，每个时钟周期对应16个采样点，采样点个数需要为16的整数倍，数据更新率为 4 GSps，每个采样点持续时间为250皮秒。
|
|
||||||
* 每个采样点为16比特的二进制补码数据；
|
|
||||||
* 波形仓库的容量为128 KB，在FPGA平台和ASIC平台下最大分别支持16 us和10 us波形输出。
|
|
||||||
|
|
||||||
对于EXCT输出频率$F_{out}$（例如6.7 GHz），在本振为$F_{LO}$(例如5.5GHz)本振频率下，
|
|
||||||
则存储区描绘的基带波形频率$F_{s}$为1.2 GHz ，$F_s = F_{out} - F_{LO}$。
|
|
||||||
|
|
||||||
|
|
||||||
## 5.5. 5 EXCT上变频电路配置
|
|
||||||
来自读出基带板输出端口的中频信号需要经过混频板上变频电路处理后才能够被发送到量子芯片。
|
|
||||||
前端上变频电路包括增益和本振，这里需要注意同一个混频板上四个通道上下变频使用同一个本振信号。
|
|
||||||
目前ez-Q 2.5 FPGA平台硬件暂不支持变频增益设置。
|
|
||||||
|配置名|描述|
|
|
||||||
|:-:|:-:|
|
|
||||||
|lo_freq|变频本振频率设置|
|
|
||||||
|
|
||||||
* lo_freq：32比特整数，范围[5400000, 5600000]单位是kHz
|
|
||||||
|
|
||||||
## 5.6. 6 Pump模拟电路配置
|
|
||||||
对处理器Pump通道的编程包括模拟电路配置项和使能配置项。模拟电路用于将Pump通道配置输出一个指定功率和频率的微波信号，而使能配置项用于控制微波信号的实时开关。
|
|
||||||
|
|
||||||
Pump输出时，需要使能输出并配置好输出频率和功率，以下是具体配置项。
|
|
||||||
|配置名|描述|
|
|
||||||
|:-|:-|
|
|
||||||
|pump_freq|pump信号输出频率|
|
|
||||||
|pump_power|pump信号输出功率|
|
|
||||||
|pump_enable|pump信号输出使能|
|
|
||||||
|
|
||||||
* pump_freq: 32比特整数，范围[7000000, 9000000], 单位是kHz
|
|
||||||
* pump_power: 32比特整数，范围[-1100, -300]， 具体映射关系取决于硬件
|
|
||||||
* pump_enable: 0x11 为使能，0x00为关闭
|
|
||||||
Loading…
Reference in New Issue