gwin-skill/SKILL.md

name, description

name	description
gwin-skill	Gowin (高云) ACG525 / GW5A-25A FPGA full toolchain: project layout, Verilog/CST/SDC design rules, gw_sh build, programmer_cli download, TFT RGB pin map. Use when the user mentions 高云, Gowin, GW5A, ACG525, .gprj, gw_sh, Programmer, TFT/LCD 刷屏, FPGA 综合下载, or asks an agent to build/flash Gowin board projects.

Gwin Skill — 高云 FPGA 全流程

立即阅读本文件后按流程执行。 细节按需打开同目录参考文档，不要凭记忆猜引脚或命令。

Agent 必做清单

- [ ] 确认工作区含 tool-chain/Gowin 与目标工程（如 proj1）
- [ ] 按 design-spec.md 组织/修改 RTL + .cst + .sdc + .gprj
- [ ] 用 scripts 或 pipe 方式跑 gw_sh（禁止 BOM、禁止交互挂起）
- [ ] 确认 impl/pnr/<name>.fs 已生成
- [ ] 板子供电 + Type-C/下载线；programmer_cli SRAM 下载
- [ ] 向用户报告比特流路径与验证方式

环境路径（本机约定）

相对工作区根 fpga/（可按实际调整，改前先 Test-Path）：

用途	路径
IDE / gw_sh.exe	tool-chain/Gowin/Gowin_V1.9.11.03_Education_x64/IDE/bin
Programmer	tool-chain/Gowin/Gowin_V1.9.11.03_Education_x64/Programmer/bin
ModelSim	tool-chain/modelSim
板卡引脚表	tool-chain/fpga/ACG525_EDA开发板引脚信息表.xlsx
例程	tool-chain/fpga/gaoyun_fpga/

器件（ACG525）：

• Series: GW5A / Package: UBGA324 / Device: GW5A-25 / Speed: C2/I1 / Version: A
• Part: GW5A-LV25UG324C2/I1
• .gprj Device 节点示例：name="GW5A-25A" pn="GW5A-LV25UG324C2/I1"

工程怎么组织

<proj>/
├── <proj>.gprj          # 工程清单（必须）
├── build.tcl            # CLI 构建（UTF-8 无 BOM）
├── build_and_download.bat
└── src/
    ├── <top>.v          # 顶层
    ├── *.v              # 子模块
    ├── <top>.cst        # 管脚约束
    └── <top>.sdc        # 时钟约束（建议）

产物（勿手改）：impl/gwsynthesis/、impl/pnr/<name>.fs

新建工程：复制 templates/ 或运行 scripts/new_project.ps1。
规范细节 → design-spec.md
引脚与 TFT → reference-pins.md

怎么编译

唯一推荐方式（Windows）： 在工程目录把 build.tcl pipe 给 gw_sh（避免 CLI 挂起、避免 UTF-8 BOM）。

$gowin = "C:\Users\Administrator\Documents\fpga\tool-chain\Gowin\Gowin_V1.9.11.03_Education_x64"
$env:PATH = "$gowin\IDE\bin;$gowin\Programmer\bin;" + $env:PATH
Set-Location <proj_dir>
cmd /c "type build.tcl | gw_sh.exe"

或直接：scripts/build.ps1 -ProjectDir <proj_dir>

build.tcl 最小模板：

open_project <name>.gprj
set_option -output_base_name <name>
set_option -synthesis_tool gowinsynthesis
set_option -top_module <top>
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
run all
exit

成功标志：日志出现 Bitstream generation completed，且存在 impl/pnr/<name>.fs。

禁止事项

• 不要直接交互运行 gw_sh.exe 后空等（易挂起）
• 不要写 set_option -verilog_std vlg2001（非法；用 v2001 或省略）
• 不要用带 BOM 的 PowerShell here-string 写 tcl 再 pipe（open_project 会变非法命令）
• 下载器不能给板子供电：必须 DC 或 Type-C 供电并拨电源开关

怎么下载

programmer_cli.exe -d GW5A-25A --fsFile "<abs>\impl\pnr\<name>.fs" -r 2

-r	含义
2	SRAM Program（掉电丢失，调试用）
4	SRAM Program and Verify
5/6	embFlash 擦写（固化）

先扫线：programmer_cli.exe --scan
应看到 Gowin USB Cable 与 GW5A-25A。

一键：scripts/build_and_download.ps1 -ProjectDir <proj_dir>

设计规范（摘要）

1. 顶层端口名与 .cst 中 IO_LOC "name" 完全一致
2. 时钟默认 clk @ T9 50 MHz；复位 rst_n @ H5（KEY5，低有效）
3. IO 标准默认 LVCMOS33，BANK_VCCIO=3.3
4. 输入按键加 PULL_MODE=UP；LCD 数据/时钟 DRIVE=8
5. TFT 2×18 口用 RGB565：R[7:3]/G[7:2]/B[7:3]（见 reference-pins.md）
6. Verilog-2001；同步复位风格与现有例程一致（posedge clk or negedge rst_n）
7. 像素时钟：无 PLL 时可用 50 MHz 二分频 ≈25 MHz（800×480 约 45 Hz，可接受）

完整规范 → design-spec.md

教其他 Agent 怎么用

1. 发现本 skill：路径 ~/.cursor/skills/gwin-skill/SKILL.md 或仓库根 gwin-skill/SKILL.md
2. 触发词：高云 / Gowin / GW5A / ACG525 / 综合下载 / TFT 刷屏 / .gprj
3. 强制步骤：先读本 SKILL.md → 改代码前读 design-spec.md → 碰 LCD/按键前读 reference-pins.md
4. 执行：只用 scripts/*.ps1 或文档中的 type build.tcl | gw_sh.exe；下载用 programmer_cli
5. 验证：--scan 有设备；下载 Finished；用户确认现象（LED/彩条等）
6. 扩展新板卡：在 reference-pins.md 增表，勿改命令骨架

人类说明 → README.md
Agent 协作约定 → AGENTS.md
端到端例子 → examples.md