微架构文档规范
适用于 design/ 下所有微架构 .md 文档。参考实现：[[LLC]] + LLC.pipeline.html。
0. 定位
- 微架构文档是人面向 RTL / [[logix]] 模型实现的合同：写完
.md就能据此写 RTL，不再回头补 - 每个单元一份主
.md（如L1.md、DMA.md、LLC.md），描述功能与流水线 - 拍级流水线强制作为独立章节，不和功能描述混写
- 可选的交互式可视化 HTML 文件挂在同目录（
<unit>.pipeline.html），不写入 git LFS、不依赖外部资源
1. 主文档骨架
主 .md 按以下顺序组织章节（编号用 #### N. 标题）：
| 编号 | 章节 | 内容 |
|---|---|---|
| §1 | 顶层参数 | 容量 / 宽度 / 深度等常量的表 |
| §2 | 顶层框图 | ASCII 框图或 mermaid，标出对外端口与内部主要模块 |
| §3 | 顶层端口 | 控制 / 数据 / 出对方向各一节，沿用本仓库已有端口约定 |
| §4 | 地址映射 | 若是存储类单元；否则按需 |
| §5 | 控制总线协议子集 | opcode 表、异步操作约定、不做合法性检查的边界 |
| §6 - §M | 各功能模块详述 | 每个功能模块独立小节（阵列、命中/缺失、出口、维护等） |
| §M+1 | 流水线 | 拍级时序契约，见 §2 |
| §M+2 - | Pin / Lock / Bypass 等可选语义、与其他单元关系、复位、调试、待规格化参数、DGMP 关联 |
数字章节用 H4 #### N.、子节用 H5 ##### N.M、子子节用 H6 ###### N.M.K。三级到顶。
2. 流水线章节
每个微架构文档必须有"流水线"章节。结构如下，编号 N 取主文档下一个未用数字（LLC.md 取 §11）：
2.1 引言
- 一段话说明：本章把哪些功能章节（§a-§b）在全局时钟上展开到拍级
- 工艺前提（如 SRAM 端口形态 1RW vs 1R1W）必须显式
- 配套交互式视图：
<unit>.pipeline.html的位置和用途 - 渲染说明：Mermaid / WaveDrom / YAML 在哪些环境能渲染
2.2 §N.1 资源清单
按拍管理的资源表。一个三列表足够：
| 资源 | 端口形态 | 来源 |
|---|---|---|
<name> |
<arb / sram_port / ff_rw / cam / table / comb> |
§x.y |
资源是硬件实体——一个仲裁器、一组 SRAM 端口、一个 FF 寄存器组、一个表。不要把功能动作写进资源清单。
2.3 §N.2 路径一览
mermaid flowchart LR 显示所有路径的分叉、合流、异步链。每条路径用一个 stage 块（不展开内部）。
2.4 §N.3 ~ §N.X 每条路径
每条路径一个子节，内部固定四件套（用 H6 ###### 编号 §N.X.Y）：
- 拓扑：mermaid
flowchart LR，stage 节点链 + 分支条件 - 拍级展开：WaveDrom JSON 代码块，横轴 cycle，纵轴 stage / latch / 资源占用，跨信号依赖用
edge字段 - latch 字段表：每个 stage→stage latch 携带的字段（含字段名 + 简短解释）
- 资源占用表：拍 × 资源 的矩阵
跨路径关系（与主路径的冲突、回填唤醒等）单独成一个子子节。
2.5 §N.{倒数 2} 资源占用全景与仲裁规则
- 资源 × 占用方表：每个资源列出主要占用方 / 次要占用方 / 仲裁规则
- stall 触发表：什么条件下哪条路径会 stall、解除条件
- 全 bank 吞吐分析（如果适用）
2.6 §N.{倒数 1} 嵌入式 schema
YAML 代码块作为机读真相源，给工具消费（未来生成 logix / RTL 骨架、跑静态检查）。schema 由四部分构成：
unit: <name>
clock: <main_clk>
resources:
<name>: { kind: ..., ports/slots/width/banks: ... }
paths:
<path_name>:
stages:
- { id: <S0/S1/...>, in: [...], uses: [...], out: [...] }
arbitration:
- { resource: <res>, contenders: [...], rule: "<text>" }
stall_conditions:
- { src: <res.cond>, effect: "<text>" }
写出哪几条路径作为样本即可，完整版可旁挂 <unit>.pipeline.yaml 文件。
3. 拍号命名约定
| 模式 | 拍号 | 例 |
|---|---|---|
| 主路径 | S0 / S1 / S2 / S3 / S4 | 读命中 |
| 主路径分支 | S3' / S4'（带撇号） | 读缺失从 S2 分叉到 mshr |
| 异步流水线 | F0 / F1 / F2 | 回填（fill） |
| 独立 FSM | W0 / W1 / W2 / W3 | 维护扫描 walker |
| 特殊短路径 | B0 / B1 | 旁路 bypass |
| 重发 | S2'（带撇号，复用主路径名 + 撇号） | 回填后 master 重发到 S2 |
不同路径的拍号空间不冲突，方便资源占用全景表交叉引用。
4. 引用与跨文档链接
- 同文档内：
§N、§N.M、§N.M.K - 跨文档：
[[文件名]] §N（Obsidian wiki link 风格），文件名不带.md后缀 - 大段引用别人的协议时，直接说"完全沿用 [[L1]] §3.2 的 NoC slave 信号集"，不要重复贴信号表
5. 三种载体的分工
| 载体 | 表达 | 谁读 |
|---|---|---|
Mermaid flowchart |
拓扑结构（节点 + 箭头） | 人（GitHub / Obsidian / VS Code 原生渲染） |
| WaveDrom JSON | 拍级时序（波形 + 跨拍依赖 + 资源冲突） | 人（wavedrom.com/editor.html、Obsidian + WaveDrom 插件） |
| 嵌入式 YAML | 机读 schema（resources / paths / stages / arbitration） | 工具 |
三者信息互补，不互相替代。同一份事实在多处出现时，YAML 是真相源——Mermaid / WaveDrom 是渲染产物（手写阶段允许双源，工具成熟后单源生成）。
不要使用：drawio（不好 diff、信息无法被工具消费）、PNG/SVG 截图（同前 + 改一处要重导）、Word/PPT（同前）。
6. 交互式 HTML（可选但推荐）
文件名约定：<unit>.pipeline.html，与主 .md 平级。
单文件、零外部依赖（CSS / JS 内嵌），打开即用。数据来源理想是同目录的 <unit>.pipeline.yaml；起步阶段允许把数据写在 <script> 的 JS 对象里，等 schema 稳定再切换。
四块信息（沿用 LLC.pipeline.html 模板）：
- 流水线甘特图：横轴 cycle，纵轴路径，stage 色块按 cycle 落格
- 资源占用网格：横轴 cycle，纵轴资源，单占用 / 多路径冲突分色
- 按硬件级展开：横轴 cycle，每拍列出所有承载的并行子功能
- 按路径展开：每条路径横排 stage 卡片，卡片内显示功能 / 资源 / 输入 / 输出 latch
第 3 / 第 4 互为转置视图。点击任一处的 stage / 子功能高亮另外两处对应项。
7. 写作原则
- 文档先行：先写
.md，再写 RTL。.md锁定的拍数是 RTL 必须满足的契约。 - 单源真相：拍级时序信息只在"流水线"章节一处描述。功能章节描述"做什么"，不描述"在哪一拍做"。
- 工艺前提显式：1RW vs 1R1W、SRAM 端口数等工艺选择必须在引言或资源清单中写明。
- 不重复：流水线章节不重述功能章节的逻辑；功能章节不写拍级时序。
- 资源 vs 功能：资源清单只列硬件实体，不列功能动作。功能动作是 stage 里的
comb字段。 - 沿用 LLC 用过的词：cacheline / set / way / pinned way / bypass / fill / writeback / mshr / walker。术语在不同文档间保持一致。
8. 待规格化清单的边界
放在主文档末尾。两类内容：
- 硬件参数：容量、深度、端口数、是否例化 ECC / prefetcher 等产品级决策
- 流水线相关：仲裁规则细节、retire 拍号、FSM 状态转移等取决于 floorplan / 实现的部分
不要把"功能未定义"的内容塞进待规格化——功能必须在功能章节里明确。
9. 参考与样板
| 角色 | 文件 |
|---|---|
| 主文档样板 | design/LLC.md |
| 流水线章节样板 | design/LLC.md §11 |
| 交互式 HTML 样板 | design/LLC.pipeline.html |
| 上层抽象（不写流水线） | design/Pipe.md、design/架构_微架构.md |
新增模块文档时：拷贝 LLC.md 结构、改章节内容、删掉用不到的小节。流水线章节直接套用 §11 的子节结构。
10. 检查清单
提交前过一遍：
- §1 - §M 功能章节完整，每个硬件模块都有独立小节
- 流水线章节存在，包含资源清单 / 路径一览 / 每条路径四件套 / 资源占用全景 / 嵌入式 YAML
- 工艺前提显式写出
- 拍号命名遵循 §3
- 跨文档引用用
[[...]] §N形式 - 资源清单只列硬件实体
- 待规格化清单只放参数和实现细节，不放未定义功能
- 配套交互式 HTML（如有）数据与文档一致
- 沿用本仓库已有的术语（参考 LLC.md / Pipe.md / GMP.md）