gwin-skill/design-spec.md

设计规范 — 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 器件行：

<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
• 时钟异步复位（与板载例程一致）：

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

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

3. 约束 (.cst)

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)

最少：

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）：

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