RTL 模块文档模板¶

每个 RTL 模块都应该有完整的文档

模块文档模板¶

# UART 控制器 — RTL 设计文档

> 文件：rtl/uart.v | 作者：xxx | 版本：v1.0

---

## 1. 功能概述

[一句话描述模块功能]

## 2. 接口定义

### 2.1 端口列表

| 端口名 | 方向 | 位宽 | 说明 |
|--------|------|------|------|
| clk | input | 1 | 系统时钟 |
| rst_n | input | 1 | 异步复位，低有效 |
| axi_awaddr | input | 32 | AXI Write Address |
| axi_awvalid | input | 1 | Write Address Valid |
| axi_awready | output | 1 | Write Address Ready |
| data_in | input | 32 | 输入数据 |
| data_out | output | 32 | 输出数据 |
| valid_in | input | 1 | 输入有效 |
| valid_out | output | 1 | 输出有效 |

### 2.2 时钟与复位

- **时钟域：** clk_domain（800MHz）
- **复位方式：** 异步复位，同步释放
- **复位极性：** 低有效

## 3. 内部架构

```mermaid
graph TB
    subgraph 接口层
        A[AXI Slave Interface]
    end

    subgraph 控制逻辑
        B[FSM Controller]
        C[Register File]
    end

    subgraph 数据通路
        D[ALU]
        E[FIFO]
    end

    A --> B
    A --> C
    B --> D
    C --> D
    D --> E

4. 寄存器映射¶

偏移地址	寄存器名	位宽	访问	复位值	说明
0x00	CTRL	32	RW	0x0	控制寄存器
0x04	STATUS	32	RO	0x0	状态寄存器
0x08	DATA_IN	32	WO	—	数据输入
0x0C	DATA_OUT	32	RO	—	数据输出
0x10	INT_EN	32	RW	0x0	中断使能
0x14	INT_STS	32	RW1C	0x0	中断状态

CTRL 寄存器位定义¶

位	名称	读写	复位值	说明
0	EN	RW	0	模块使能
1	MODE	RW	0	0:ModeA, 1:ModeB
2	LOOPBACK	RW	0	回环测试
3	FIFO_RST	RW	0	FIFO 复位，自清除
7:4	—	RSV	0	保留
15:8	DIV	RW	0x01	时钟分频系数
31:16	—	RSV	0	保留

5. 状态机¶

stateDiagram-v2
    [*] --> RESET
    RESET --> IDLE: rst_n deasserted
    IDLE --> BUSY: valid_in && ready
    BUSY --> IDLE: done
    BUSY --> ERROR: timeout
    ERROR --> IDLE: clear_error

6. 关键时序¶

6.1 AXI 写时序¶

sequenceDiagram
    participant Master
    participant Slave

    Master->>Slave: AWADDR (写地址)
    Master->>Slave: AWVALID=1
    Slave-->>Master: AWREADY=1
    Note over Master,Slave: 地址握手完成

    Master->>Slave: WDATA (写数据)
    Master->>Slave: WVALID=1, WSTRB=0xF
    Slave-->>Master: WREADY=1
    Note over Master,Slave: 数据握手完成

    Slave-->>Master: BRESP=OKAY
    Slave-->>Master: BVALID=1
    Master-->>Slave: BREADY=1

7. 设计约束¶

最大组合逻辑级数： ≤ 8 级
时钟 skew： < 200ps
异步复位： 同步释放，≥ 3 级同步器

8. 已知问题¶

问题	严重度	状态	备注
FIFO 满时 valid_in 未屏蔽	Medium	Open	需在 TB 中验证

相关：验证计划 | Bug 列表 最后更新：2026-05-01 ```

文档编写规范¶

1. 必须包含的内容¶

2. 建议包含的内容¶

设计约束
已知问题
验证计划链接
Bug 追踪链接

3. 文档维护¶

RTL 变更时同步更新文档
使用 Git 版本控制
PR 审查包含文档检查

模板位置：docs/templates/module-template.md