rbpu_datasheet/readme.md

# RBPU16 读出基带处理芯片 · 数据手册

RBPU16 是一款用于超导量子比特态信息读出的 SoC 芯片，最大支持 16 个量子比特并行读出，内部集成 PLL、ADC、DAC、DSP 等模块。

本手册帮助相关工程师开展芯片性能评估、硬件设计、驱动开发及芯片使用。

## 项目结构

```
├── build.ipynb          # 构建入口：VS Code 打开 → Run All → 生成报告
├── project.yaml         # 项目配置（标题、章节列表、作者）
├── chapters/            # 章节源文件（Markdown，纯文本管理）
│   ├── 00_cover.md
│   ├── 01_specifications.md
│   ├── ...
│   └── appendix/
├── data/                # 结构化数据
│   ├── pin_name.csv     # 管脚定义（用户直接编辑）
│   ├── pin_loc.csv      # 管脚 BGA 位置网格
│   ├── seg_define.csv   # 寄存器地址段定义
│   └── ids.json         # 寄存器详细定义（由 XLS 生成，供脚本读取）
├── assets/              # 图片（PNG/JPG）
├── doc_builder/         # 构建工具
│   └── themes/
│       └── datasheet.css
└── output/              # 构建产物（gitignore）
    └── RBPU16_数据手册.html   # 自包含单文件，可直接发送
```

## 快速开始

### 生成报告

1. VS Code 打开 `build.ipynb`
2. 点击 **Run All**
3. 报告生成到 `output/` 目录

> 依赖 `markdown` 库，首次运行会自动安装。

### 编辑内容

| 修改什么 | 编辑哪个文件 | 如何重新生成 |
|---------|------------|------------|
| 正文内容 | `chapters/*.md` | Run All |
| 管脚定义 | `data/pin_name.csv` | Run All |
| 地址段 | `data/seg_define.csv` | Run All |
| 寄存器定义 | `script/读出子系统IDS表.xls` | 先运行 `script/ids_import.ipynb`，再 Run All |
| 报告样式 | `doc_builder/themes/datasheet.css` | Run All |
| 封面/标题/章节列表 | `project.yaml` | Run All |

### @import 语法

在章节 Markdown 中使用 `@import` 引用数据文件，构建时自动渲染为表格：

```markdown
@import "data/pin_name.csv"       → 管脚定义表
@import "data/pin_loc.csv"        → BGA 焊球网格
@import "data/seg_define.csv"     → 地址映射总表
@import "data/ids.json"           → 寄存器详细定义
```

### 分享报告

`output/` 中的 HTML 是**自包含**的——CSS 和图片全部内嵌，单个文件即可在任何浏览器中打开，无需附带 `assets/` 目录。