---
name: gwin-skill
description: >-
  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/](templates/) 或运行 `scripts/new_project.ps1`。  
规范细节 → [design-spec.md](design-spec.md)  
引脚与 TFT → [reference-pins.md](reference-pins.md)

## 怎么编译

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

```powershell
$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` 最小模板：

```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 供电并拨电源开关

## 怎么下载

```powershell
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](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](README.md)  
Agent 协作约定 → [AGENTS.md](AGENTS.md)  
端到端例子 → [examples.md](examples.md)