rbpu_datasheet/CLAUDE.md

# 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` 变量，使用系统可用字体。