# 设计规范 — ACG525 / GW5A-25A

## 1. 工程与命名

| 项 | 规范 |
|----|------|
| 工程目录 | 短名小写/数字：`proj1`、`tft_bar` |
| 顶层模块 | 与主文件名一致：`tft_top.v` → `module tft_top` |
| 约束 | `<top>.cst`、`<top>.sdc` |
| 工程文件 | `<dir>.gprj`，Device 固定见下 |
| 输出名 | `set_option -output_base_name` 与目录名一致 |

`.gprj` 器件行：

```xml
<Device name="GW5A-25A" pn="GW5A-LV25UG324C2/I1">gw5a25a-008</Device>
```

`FileList` 中每个源文件一行，`enable="1"`；类型：`file.verilog` / `file.cst` / `file.sdc`。

## 2. RTL 风格

- 语言：Verilog-2001（`v2001`）；勿写非法 `vlg2001`
- 时钟异步复位（与板载例程一致）：

```verilog
always @(posedge clk or negedge rst_n) begin
    if (!rst_n) ...
    else ...
end
```

- 上电：可用计数器做 POR，再与按键复位相与
- 禁止在顶层留未约束的输出端口
- 位宽：常量用足够宽的 localparam，避免截断 WARN
- TFT 像素数据与 DE 对齐：常用 `data_req` 提前一拍取色，再在 DE 有效期输出

## 3. 约束 (.cst)

```text
IO_LOC "port_name" PIN;
IO_PORT "port_name" IO_TYPE=LVCMOS33 PULL_MODE=... DRIVE=... BANK_VCCIO=3.3;
```

- `port_name` 与 HDL 端口 **逐字相同**（含 `bus[0]` 写法）
- 默认 `IO_TYPE=LVCMOS33`，`BANK_VCCIO=3.3`
- 按键/复位输入：`PULL_MODE=UP`
- 时钟输入：`PULL_MODE=NONE`
- LCD 高速脚：`DRIVE=8`
- 总线按位分别写 `IO_LOC`（高云 CST 常规写法）

## 4. 时序 (.sdc)

最少：

```tcl
create_clock -name clk -period 20.000 -waveform {0.000 10.000} [get_ports {clk}]
```

（50 MHz → period 20 ns）

分频时钟若时报 `TA1132`，可补 `create_generated_clock`，或接受警告（低频刷屏通常可过）。

## 5. GPIO 复用选项

教育板调试常用（`build.tcl`）：

```tcl
set_option -use_sspi_as_gpio 1
set_option -use_mspi_as_gpio 1
set_option -use_ready_as_gpio 1
set_option -use_done_as_gpio 1
set_option -use_cpu_as_gpio 1
```

保留 JTAG 下载：不要把 `use_jtag_as_gpio` 设为 1。

## 6. TFT 800×480 时序（TFT_V3.0）

| 参数 | 值 |
|------|-----|
| H_TOTAL | 1056 |
| H_SYNC | 128 |
| H_BACK | 88 |
| H_DISP | 800 |
| H_FRONT | 40 |
| V_TOTAL | 525 |
| V_SYNC | 2 |
| V_BACK | 33 |
| V_DISP | 480 |
| V_FRONT | 10 |

- HS/VS：同步区为低（与 VGA 类似）
- DE：有效显示区为高
- 颜色：2×18 排针 **RGB565**；`lcd_bl=1` 开背光；`lcd_reset` 常置 1

理想像素时钟约 33 MHz；无 PLL 时 25 MHz（50/2）可先点亮。

## 7. 仿真（可选）

- ModelSim：`tool-chain/modelSim`
- testbench 命名：`<module>_tb.v`；**不要**把 tb 设为综合 top
- `.gprj` 中可保留 tb，综合前确认 `set_option -top_module` 为可综合顶层

## 8. 目录卫生

- 不提交密钥；`impl/` 可本地保留，团队仓库可 gitignore
- 脚本与 `build.tcl` 使用 **UTF-8 无 BOM**
- 注释可用中文；tcl/命令行参数保持 ASCII