144 lines
6.0 KiB
Markdown
144 lines
6.0 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Project Overview
|
||
|
||
本项目是 **RBPU16 读出基带处理芯片** 的数据手册（datasheet/user manual）。RBPU16 是一款用于超导量子比特态信息读出的 SoC 芯片，最大支持 16 个量子比特并行读出，内部集成 PLL、ADC、DAC、DSP 等模块。
|
||
|
||
手册基于纯文本管理，通过 Python 脚本生成精美的 HTML 和 PDF 报告（参考 AD9164 数据手册风格）。
|
||
|
||
## 文件结构
|
||
|
||
| 路径 | 用途 |
|
||
|------|------|
|
||
| `chapters/*.md` | 手册章节源文件（Markdown，按章节拆分，纯文本 git 友好） |
|
||
| `chapters/appendix/*.md` | 附录（运维手册、配置用例） |
|
||
| `data/pin_name.csv` | 管脚定义表（编号、名称、类型、描述） |
|
||
| `data/pin_loc.csv` | 管脚物理位置网格表（行×列 → 信号名） |
|
||
| `data/seg_define.csv` | 寄存器地址段定义（功能模块→子模块→起始地址→大小） |
|
||
| `data/ids.json` | 寄存器详细定义 JSON（由 XLS 生成，供脚本读取） |
|
||
| `assets/` | 手册内嵌图片（框图、管脚图、协议图等 PNG/JPG 文件） |
|
||
| `templates/` | Jinja2 模板（base HTML + macros + CSS） |
|
||
| `templates/css/report.css` | 报告样式表（AD9164 风格，支持打印和屏幕） |
|
||
| `templates/macros/` | 可复用 Jinja2 宏（管脚表、寄存器表、地址映射表） |
|
||
| `build.py` | 主构建脚本（一键生成 HTML + PDF） |
|
||
| `requirements.txt` | Python 依赖（Jinja2, markdown, Pygments, WeasyPrint） |
|
||
| `output/` | 构建产物（gitignore） |
|
||
| `script/ids_import.ipynb` | Jupyter notebook：解析 `读出子系统IDS表.xls` 生成 `data/ids.json` |
|
||
| `script/读出子系统IDS表.xls` | 寄存器详细定义 Excel（多 sheet） |
|
||
|
||
### 旧文件（过渡期保留）
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `读出芯片用户使用手册.md` | 旧 MPE 单文件手册（过渡期保留，不再更新） |
|
||
| `读出芯片用户使用手册.html` | 旧 MPE 导出 HTML |
|
||
| `specification.md` | 旧 SPI/LVDS 规格（内容已合并到 chapters/） |
|
||
| `pin_name.csv` (root) | 旧位置（已复制到 data/） |
|
||
| `pin_loc.csv` (root) | 旧位置（已复制到 data/） |
|
||
| `seg_define.csv` (root) | 旧位置（已复制到 data/） |
|
||
| `ids/` | 旧位置（JSON 已复制到 data/ids.json） |
|
||
| `pin_loc.xlsx` | 旧 Excel 文件 |
|
||
|
||
## 构建流程
|
||
|
||
### 一键构建
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 构建 HTML + PDF
|
||
python build.py
|
||
```
|
||
|
||
产物输出到 `output/` 目录：
|
||
- `output/RBPU16 读出基带处理芯片_数据手册.html`
|
||
- `output/RBPU16 读出基带处理芯片_数据手册.pdf`
|
||
|
||
### 构建步骤（build.py 内部流程）
|
||
|
||
1. 加载数据源：`data/*.csv` + `data/ids.json`
|
||
2. 初始化 Jinja2 模板引擎
|
||
3. 处理章节文件：`chapters/*.md`
|
||
- 识别 `<!-- MACRO: xxx -->` 标记并替换为 Jinja2 宏渲染的 HTML
|
||
- Python-Markdown 将 Markdown 转为 HTML
|
||
4. 生成目录 (TOC)
|
||
5. 渲染完整 HTML（封面 + TOC + 章节 + 修订历史）
|
||
6. WeasyPrint 将 HTML 转为 PDF
|
||
|
||
### 宏标记说明
|
||
|
||
章节 Markdown 文件中使用 `<!-- MACRO: xxx -->` 注释标记来指示脚本动态生成表格：
|
||
|
||
| 宏标记 | 功能 | 数据源 |
|
||
|--------|------|--------|
|
||
| `<!-- MACRO: pin_table -->` | 渲染管脚描述表 | `data/pin_name.csv` |
|
||
| `<!-- MACRO: pin_loc_grid -->` | 渲染 BGA 焊球网格 | `data/pin_loc.csv` |
|
||
| `<!-- MACRO: address_map -->` | 渲染地址映射总表 | `data/seg_define.csv` |
|
||
| `<!-- MACRO: register_table -->` | 渲染完整寄存器定义 | `data/ids.json` |
|
||
|
||
### 寄存器定义更新流程
|
||
|
||
当 XLS 寄存器定义文件更新后：
|
||
1. 在 VS Code 中打开 `script/ids_import.ipynb`，运行所有 cell
|
||
2. notebook 解析 `script/读出子系统IDS表.xls` 的多个 sheet
|
||
3. 输出为 `data/ids.json`
|
||
4. 运行 `python build.py` 重新构建手册
|
||
|
||
## 章节编辑指南
|
||
|
||
### 添加新章节
|
||
|
||
1. 在 `chapters/` 下创建新 `.md` 文件
|
||
2. 文件名格式：`{序号}_{英文名}.md`（如 `10_timing_diagrams.md`）
|
||
3. 文件以 `# 章节标题` 开头
|
||
4. 运行 `python build.py` 验证
|
||
|
||
### 修改管脚定义
|
||
|
||
1. 编辑 `data/pin_name.csv`（或根目录 `pin_name.csv`，然后复制到 data/）
|
||
2. 运行 `python build.py`，管脚表自动更新
|
||
|
||
### 修改寄存器定义
|
||
|
||
1. 编辑 `script/读出子系统IDS表.xls`
|
||
2. 运行 `script/ids_import.ipynb` 更新 `data/ids.json`
|
||
3. 运行 `python build.py`，寄存器表自动更新
|
||
|
||
### 修改样式
|
||
|
||
编辑 `templates/css/report.css`：
|
||
- CSS 变量（颜色、字体、间距）在 `:root` 块中
|
||
- 打印样式使用 `@page` 规则
|
||
- 屏幕样式使用 `@media screen`
|
||
|
||
## 技术栈
|
||
|
||
- **模板引擎**: Jinja2 — Python 标准，Flask 生态
|
||
- **Markdown 解析**: Python-Markdown + extensions (tables, codehilite, toc, fenced_code)
|
||
- **HTML→PDF**: WeasyPrint — 纯 Python，CSS Paged Media
|
||
- **代码高亮**: Pygments — Python-Markdown codehilite 依赖
|
||
- **数学公式**: KaTeX — CDN 加载，HTML 中动态渲染
|
||
- **图表**: Mermaid — CDN 加载（当前手册未使用）
|
||
|
||
## 关键约定
|
||
|
||
- 所有文档内容为中文，技术术语保留英文缩写（ADC、DAC、PLL、LVDS、SPI、AWG、DAQ、MCU、NCO 等）
|
||
- 管脚编号采用 BGA 网格命名（字母行 + 数字列，如 F4、G7）
|
||
- 地址和寄存器偏移使用 24 位十六进制表示（如 `0x100000`）
|
||
- SPI 协议格式：1 bit R/W + 25 bit addr + 5 bit chip_id + 1 bit reserved + N×32 bit data
|
||
- LVDS 协议帧格式：4 bit header + 16/32/64/128 bit payload + 8 bit CRC8
|
||
- 章节文件命名：`{序号}_{英文名}.md`，序号决定章节顺序
|
||
- 图片路径：相对于 repo 根目录，从 `assets/` 引用
|
||
|
||
## PDF 生成注意事项
|
||
|
||
WeasyPrint 需要系统依赖：
|
||
- **Windows**: 通常开箱即用
|
||
- **macOS**: `brew install pango cairo`
|
||
- **Linux**: `apt install libpango-1.0-0 libpangocairo-1.0-0`
|
||
|
||
中文 PDF 字体：若系统缺少中文字体，可在 CSS `:root` 中调整 `--font-body` 和 `--font-heading` 变量，使用系统可用字体。
|