6.0 KiB

Raw Blame History

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 文件

构建流程

一键构建

# 安装依赖
pip install -r requirements.txt

# 构建 HTML + PDF
python build.py

产物输出到 output/ 目录：

output/RBPU16 读出基带处理芯片_数据手册.html
output/RBPU16 读出基带处理芯片_数据手册.pdf

构建步骤（build.py 内部流程）

加载数据源：data/*.csv + data/ids.json
初始化 Jinja2 模板引擎
处理章节文件：chapters/*.md
- 识别  标记并替换为 Jinja2 宏渲染的 HTML
- Python-Markdown 将 Markdown 转为 HTML
生成目录 (TOC)
渲染完整 HTML（封面 + TOC + 章节 + 修订历史）
WeasyPrint 将 HTML 转为 PDF

宏标记说明

章节 Markdown 文件中使用  注释标记来指示脚本动态生成表格：

宏标记	功能	数据源
`<!-- 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 寄存器定义文件更新后：

在 VS Code 中打开 script/ids_import.ipynb，运行所有 cell
notebook 解析 script/读出子系统IDS表.xls 的多个 sheet
输出为 data/ids.json
运行 python build.py 重新构建手册

章节编辑指南

添加新章节

在 chapters/ 下创建新 .md 文件
文件名格式：{序号}_{英文名}.md（如 10_timing_diagrams.md）
文件以 # 章节标题 开头
运行 python build.py 验证

修改管脚定义

编辑 data/pin_name.csv（或根目录 pin_name.csv，然后复制到 data/）
运行 python build.py，管脚表自动更新

修改寄存器定义

编辑 script/读出子系统IDS表.xls
运行 script/ids_import.ipynb 更新 data/ids.json
运行 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 变量，使用系统可用字体。

6.0 KiB Raw Blame History Unescape Escape