AI 辅助 AG32 开发指南

给谁看: 想用 AI(Mavis/mini-cap 等)帮自己自动化 AG32 工程编译/下载/测试的工程师。

目标: 让 AI 能跑通”改代码 → 编译 → 烧录 → 看 log → 改 bug”这个闭环,人只在关键节点 review。

1. 准备工作(一次配置,永久使用)

1.1 必须安装的工具

1.2 一次性装 AG32 SDK + 工具链

# 在 PowerShell 里跑
pio platform install AgRV

# 验证包都装好了
pio pkg list | Select-String "agrv"

应该看到:

tool-agrv_sdk
tool-agrv_logic
tool-agrv_openocd

1.3 验证 Quartus 可用

& 'D:\altera\13.0sp1\quartus\bin64\quartus_sh.exe' --version

必须是 13.0sp1。其它版本(如 18.x、20.x)gen_vlog 出来的 board.qsf 不兼容,会报奇怪的错误。

1.4 验证硬件连接

• AG32 板子通过 CMSIS-DAP 接到电脑 USB
• 板子 UART0 接到电脑(看原理图,通常 PIN_68/69 = COMx)
• 设备管理器里看到 COM5(或其它数字)

2. 关键路径速查

3. AI 工作流的核心命令(给 AI 的标准操作)

3.1 一键:编译 + 烧 + 跑

# 完整流程:gen_vlog → Quartus 综合 → supra P&R → gen_batch → OpenOCD 烧 → COM5 看输出
pio run -t batch_upload

给 AI 的指令模板: “请用 pio run -t batch_upload 一键 build + 烧 + 跑,然后读 COM5 给我看测试结果。”

3.2 只改 logic Verilog 后的快速迭代

# 只重跑 Quartus + supra,生成新的 board_batch.bin
& 'C:\Users\<user>\.platformio\python3\python.exe' `
   'C:\Users\<user>\.platformio\platforms\AgRV\etc\gen_vlog' `
   -s -d AGRV2KL100 -x logic\board.vex board.ve logic\board.v -m logic\user_ip.v

cd logic
quartus_sh --clean board
quartus_sh -t af_quartus.tcl
af -B -F af_run.tcl        # 如果失败换 --seed_rand 试
cd ..

给 AI 的指令模板: “我改了 logic/user_ip.v,请只重跑 CPLD 综合和 P&R,不要重编 MCU。”

3.3 只读测试输出(不重烧)

# 简单方法:打开 PuTTY/TeraTerm 连 COM5@115200
# AI 用 PowerShell 的 System.IO.Ports.SerialPort 监听:
$port = New-Object System.IO.Ports.SerialPort 'COM5', 115200, 'None', 8, 'One'
$port.Open()
$port.ReadLine()  # 一行一行读

给 AI 的指令模板: “板子已经跑起来了,帮我读 COM5 看看输出。”

3.4 单独烧 bitstream(不改 MCU)

& 'C:\Users\<user>\.platformio\packages\tool-agrv_openocd\bin\openocd_cmd.bat' `
   -s 'C:\Users\<user>\.platformio\platforms\AgRV\etc' `
   -c 'variable ADAPTER_SPEED 10000' `
   -c 'variable ADAPTER cmsis-dap' `
   -c 'variable AGRV_PROGRESS 1' `
   -f agrv2k.cfg `
   -c 'reset init; echo [agrv download {agm_cpld_spi_debug_batch.bin}]; reset halt' `
   -c 'shutdown'

# 烧完 CPU 在 halt,必须 resume 才会跑 main()
& 'C:\Users\<user>\.platformio\packages\tool-agrv_openocd\bin\openocd_cmd.bat' `
   -s 'C:\Users\<user>\.platformio\platforms\AgRV\etc' `
   -c 'variable ADAPTER_SPEED 10000' `
   -c 'variable ADAPTER cmsis-dap' `
   -c 'variable AGRV_PROGRESS 0' `
   -f agrv2k.cfg `
   -c 'reset; sleep 100; resume; shutdown'

3.5 单独烧 MCU 固件(不改 CPLD)

& 'C:\Users\<user>\.platformio\packages\tool-agrv_openocd\bin\openocd_cmd.bat' `
   -s 'C:\Users\<user>\.platformio\platforms\AgRV\etc' `
   -c 'variable ADAPTER_SPEED 10000' `
   -c 'variable ADAPTER cmsis-dap' `
   -c 'variable AGRV_PROGRESS 1' `
   -f agrv2k.cfg `
   -c 'program .pio\build\debug\firmware.elf verify reset exit'

4. 用 AI 自动化整个流程的实操示例

4.1 场景 1:AI 帮你快速验证”代码改了之后能不能跑通”

用户给 AI 的 prompt:

我刚改完 `src/main.c` 的 test_dac0_dac1 函数,加了几个新断言。
请帮我:
1. 跑 `pio run -t batch_upload` 重新 build 和烧录
2. 烧完后读 COM5 给我看完整测试输出
3. 如果有任何 FAIL,告诉我哪个 test 挂了、期望值是什么

AI 内部操作:
1. cd E:\AI_AG32\SPI_AD && pio run -t batch_upload
2. 失败的话自动 retry seed,或者读 build log 找错误
3. 跑完 OpenOCD reset + resume
4. 打开 COM5,等 15-20 秒读输出
5. 把 7 项 test 的 PASS/FAIL 状态报告给用户

4.2 场景 2:AI 帮你看 waveform 抓 bug

用户给 AI 的 prompt:

我的 ADC EOC 一直不置位,我已经按 SKILL.md 的步骤把 4 个 debug 信号
(dbg_adc_en/dbg_adc_sclk/dbg_adc_eoc/dbg_stat_eoc) 引到了 PIN15-18。
请帮我:
1. 修改 `board.ve` 和 `logic/user_ip.v` 加这 4 个 debug 输出
2. 跑 `pio run -t batch_upload` 重新 build
3. 烧录后跑 ADC 测试,读 COM5 的输出
4. 告诉我能不能从 EOC 看到期望的下降沿

AI 内部操作:
1. 读 board.ve,加 dbg_adc_en PIN_18:OUTPUT 等 4 行
2. 跑 gen_vlog -s 重新生成 user_ip_tmpl.v
3. 改 user_ip.v 加 4 个 output port + wire + assign
4. 改 apb_adc 模块加 4 个 debug output + assign
5. pio run -t batch_upload
6. 读 COM5 输出

4.3 场景 3:AI 帮你排查 UART 乱码

用户给 AI 的 prompt:

我的板子 COM5 出来的是乱码,不是 ASCII。看了 SKILL.md 的 UART 排查
清单说要检查 SYSCLK 和 BOARD_PLL_FREQUENCY。请帮我:
1. 读 `board.ve` 看 SYSCLK 是多少
2. 读 `board.c` 的 SystemInit 函数,看 BOARD_PLL_FREQUENCY 怎么设的
3. 检查 PLL 是否 lock(从打印的 CLK 频率)

5. AI 必须知道的安全红线

用户必须在 prompt 里显式提醒 AI:

5.1 永远不要跑

5.2 跑之前要确认

• 改了 platformio.ini 的 board =:确认芯片型号和板子一致
• 改了 logic_address:确认不会盖到 OSC_CAL
• 改了 board.ve 加新 pin:确认那个 pin 在芯片上确实存在
• 改了 Quartus 项目设置:会盖掉 gen_vlog 生成的 board.qsf,需手动备份

5.3 烧录失败怎么办

1. 第一次烧失败 → 重新跑 `pio run -t batch_upload`(自动换 seed)
2. 仍然失败 → 看 build log,大概率是 Verilog 语法或 port 不匹配
3. OpenOCD 报错 "No device found" → 检查 USB-CMSIS-DAP 连接
4. 烧完板子不动 → 几乎肯定是 halt 状态,跑 `reset; sleep 100; resume`
5. 烧完直接死 → 大概率是 logic_address 算错盖了 OSC_CAL,需要外部编程器恢复

6. AI 调试时的”看 log 判断程序是否正常”流程

6.1 标准模板:在 main.c 里加 printf

int main(void) {
  IWDG_Disable();  // 必加
  board_init();
  printf("=== boot, CLK: %d MHz ===\r\n", SYS_GetSysClkFreq() / 1000000);

  // 你的测试
  int ok = test_dac0_dac1();
  printf("test_dac0_dac1: %s\r\n", ok ? "PASS" : "FAIL");

  for (;;) { __asm__ volatile ("wfi"); }
}

6.2 AI 读 COM5 时的判断规则

6.3 AI 应该主动加的诊断 print

当 AI 怀疑某模块有问题时,会在 main.c 里加临时诊断:

// 检查 ADC 时钟
printf("[debug] apb_clock=%d, ctrl_sclk_div=%d, expected sclk_period=%d\r\n",
       SYS_GetBusClkFreq(), ADC0->CTRL >> 16, (ADC0->CTRL >> 16 + 1) * 2);

// 检查 SPI
printf("[debug] SPI STAT=0x%x, TX_COUNT=%d, RX_COUNT=%d\r\n",
       SPI_CTRL->STAT, SPI_CTRL->TX_COUNT, SPI_CTRL->RX_COUNT);

让用户重新 build 跑,看 COM5 输出定位问题。

7. 高级玩法:让 AI 持续迭代直到 PASS

用户 prompt 模板:

请帮我改 `src/main.c` 的 test_adc0_read 函数,加上更详细的 debug print。
然后跑 `pio run -t batch_upload`,读 COM5,告诉我 EOC 是否成功。
如果 EOC 没成功,请你自己分析可能原因,修改 `logic/user_ip.v` 里的
apb_adc 状态机逻辑,然后再 build + 烧 + 跑。
循环这个过程,直到 EOC 成功,或者你已经尝试了 3 个不同方案都失败。
每改一次,告诉我:
1. 你改了什么
2. 为什么你认为这个改动会修好问题
3. 改完之后 COM5 的新输出

AI 应该的内部循环:

1. 改代码
2. pio run -t batch_upload
3. 读 COM5
4. 分析输出,判断改对了没
5. 如果没改对,改回去,试另一个方向
6. 重复 1-5,直到成功或耗尽 budget

8. skill 库使用说明

AI 工具(Mavis/mini-cap)能读 E:\AI_AG32\skill\ 下的所有 .md 文件。

8.1 路由

让 AI 读 E:\AI_AG32\skill\SKILL.md,它会按用户的当前问题选最相关的文档读。

8.2 完整 skill 列表

8.3 skill PDF

每个 skill 同时有 .md 和 .pdf(由 md2pdf.py 生成)。AI 默认读 .md,PDF 是给人类看的。

8.4 skill 更新

用户改了 E:\AI_AG32\skill\*.md 后,跑:

cd E:\AI_AG32\skill
python md2pdf.py

会重新生成所有 PDF。

9. 常见任务清单(给用户/AI 共用)

10. 故障案例:AI 第一次跑常见错误

案例 1:”Error (12007): Top-level design entity ‘user_ip’ is undefined”

AI 应该:改 logic\board.qsf,把 TOP_LEVEL_ENTITY 改成 board。
根因:Quartus 顶层应该是自动生成的 board.v,不是 user_ip.v。

案例 2:”Port ‘dbg_adc_en’ does not exist in macrofunction ‘macro_inst'”

AI 应该:跑 gen_vlog -s -d AGRV2KL100 ... -m logic\user_ip.v 重新生成 user_ip_tmpl.v 和 board.v。
根因:改了 board.ve 加新 pin,模板没更新。

案例 3:”Can not route to pin pll_inst|auto_generated|pll1|clkin”

AI 应该:用 pio run -t batch_upload(自动换 6 个 seed),或跑 af -B -F af_run.tcl --seed_rand 多次。
根因:当前 seed 的 P&R 撞上了 routing 死角。

案例 4:”Error: Can not find module user_ip”(supra 步骤)

AI 应该:检查 af_run.tcl 里 set TOP_MODULE 是 board 还是 user_ip,改成 board。
根因:supra 默认找 user_ip,但 Quartus 已经把 user_ip 内联到 board 了。

案例 5:COM5 什么都没打印

AI 应该:跑 reset; sleep 100; resume,让 CPU 跑 main()。
根因:OpenOCD 烧完 bitstream 后 CPU 在 halt,不 resume 不会跑。

11. 进阶:AI 自动化多板并行测试

如果有多个 AG32 板子需要同时验证,可以让 AI 用不同的 OpenOCD adapter serial 编号:

# 板 1
& openocd_cmd.bat -c 'variable ADAPTER cmsis-dap' `
   -c 'variable ADAPTER_SERIAL 123456' -f agrv2k.cfg ...

# 板 2
& openocd_cmd.bat -c 'variable ADAPTER cmsis-dap' `
   -c 'variable ADAPTER_SERIAL 789012' -f agrv2k.cfg ...

COM5 / COM6 / COM7 … 也是同理,每块板子占一个 COM 口。

AI 自动化测试:
1. 写一个 PowerShell 脚本,同时打开多个 COM 口
2. 给每块板子烧同一个 bitstream
3. reset + resume 所有板子
4. 并行读所有 COM 口
5. 对比所有板子的输出,任何一块 FAIL 报警

12. 配合 Mavis 技能体系(可选)

Mavis 这个 AI agent 有自己的技能库 C:\Users\<user>\.minimax\agents\mavis\skills\,包含:

• ag32-cpld-build-flow — 完整 build 流程
• ag32-cpld-spi-master-debug — SPI 状态机调试
• ag32-ve-generation — VE 文件生成机制
• ag32-flash-layout — flash 布局
• ag32-stm32-migration — STM32 → AG32 移植

这些是 Mavis 通用 AG32 知识。E:\AI_AG32\skill\ 是项目/公司特定的扩展(你们公司板子的特定配置、经验教训、PDF 版本)。

两者配合:让 Mavis 读 E:\AI_AG32\skill\SKILL.md,它会按需读其它 skill 文件。

13. 一页速查卡(给 AI 用的”应急表”)

最常用的 3 个命令:

# 1. 一键 build + 烧 + 跑
pio run -t batch_upload

# 2. 看输出
$port = New-Object System.IO.Ports.SerialPort 'COM5', 115200, 'None', 8, 'One'; $port.Open(); $port.ReadLine()

# 3. 重置 CPU
& openocd_cmd.bat ... -c 'reset; sleep 100; resume; shutdown'
.

.

返回用AI开发