Initial gwin-skill: Gowin ACG525 full toolchain skill for agents.
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Administrator
@@ -0,0 +1,141 @@
|
||||
---
|
||||
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)
|
||||
Reference in New Issue
Block a user