Initial gwin-skill: Gowin ACG525 full toolchain skill for agents.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 20:18:41 +08:00
commit 1b1a68ae28
16 changed files with 765 additions and 0 deletions
@@ -0,0 +1,109 @@
+# 设计规范 — 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