AI 如何看懂 FPGA 大工程？RepoKey Starter 使用记录

如果只是几个 RTL 文件，让 AI 直接读目录，问题还不大。

这次案例不是小 demo。这个 Vivado 工程围绕 RF Data Converter 搭建，里面有 MicroBlaze 控制平面、AXI interconnect、AXI4-Stream 数据通路、Block Design、生成 wrapper、IP 输出和大量 Vivado 生成目录。

这种工程直接丢给 AI，很容易出现一个熟悉的画面：AI 读了很多文件，token 用了不少，最后还是要工程师告诉它："先看 system_mb_wrapper，RFDC 在 usp_rf，MicroBlaze 控制 AXI 总线，数据流从 DDS 经过位宽转换和 FIFO 再进 RFDC。"

所以这次我没有让 AI 一上来扫目录，第一步先调用 RepoKey Starter，生成一张低 token 工程地图。

这个工程到底是干什么的

这次案例来自一个真实 Vivado 2023.2 工程，工程名为 rfconverter_ip_test_macroblaze。它的核心结构是：

RF Data Converter 负责高速 RF 数据转换；
MicroBlaze 作为软件控制平面；
AXI interconnect 连接 MicroBlaze、UARTLite 和 RFDC 控制接口；
AXI4-Stream 数据通路把 DDS 生成的数据送入 RFDC；
Block Design 生成顶层 wrapper，作为 Vivado 工程入口；
ILA 用于观察 RFDC 输出相关 AXIS 数据流。

Starter 识别到的基础信息如下：

项目	识别结果
Vivado 版本	`2023.2`
工程名	`rfconverter_ip_test_macroblaze`
器件	`xczu47dr-fsve1156-2-i`
设计 top	`system_mb_wrapper`
Block Design	`system_mb.bd`
关键用户 RTL	`user_sysref_sync_gen.v`

这个项目的复杂点不在于"文件多"这么简单，而是它混合了 RFDC、MicroBlaze、AXI、AXIS、BD wrapper、时钟复位和调试采样链路。AI 如果没有工程地图，很容易先掉进 generated files 和 IP output 里。

对话第一轮：先别扫目录，先看工程地图

客户：

这个工程是一个 RFDC + MicroBlaze 的 Vivado 工程，里面有 BD、RF Data Converter、AXI/AXIS 和生成文件。你先不要直接扫整个目录，先用 RepoKey Starter 看一下这个项目是干什么的，top 是什么，关键 IP 和数据流在哪。

AI：

可以。我会先调用 RepoKey Starter 的工程上下文能力，生成工程摘要和索引。这样我先拿到 Vivado 工程入口、设计 top、BD、IP、关键 RTL 和连接摘要，再决定后续要读哪些具体文件。

我会先执行：

powershell 复制代码

repokey-client.cmd context summarize .

摘要正常后，再生成索引和结构图：

powershell 复制代码

repokey-client.cmd context index .
repokey-client.cmd context map .

这一步的目标很明确：先建立一张"这个工程从哪里开始看"的地图，避免把所有源码直接塞进上下文。

对话第二轮：AI 返回项目骨架

AI：

Starter 已经识别到这个工程的第一层结构：

Project：rfconverter_ip_test_macroblaze
Device：xczu47dr-fsve1156-2-i
Vivado version：2023.2
Design top：system_mb_wrapper
Block Design：system_mb.bd
Key user RTL：user_sysref_sync_gen.v

从工程结构看，这是一个 RFDC + MicroBlaze + AXI/AXIS 的工程。MicroBlaze 负责控制平面，RF Data Converter 是核心高速数据转换 IP，AXI interconnect 连接控制外设，AXI4-Stream 链路负责数据流。

客户：

你能不能具体说说里面有哪些关键模块？不要只说它有 BD。

AI：

可以。Starter 从 BD 和工程结构中识别到这些关键结构：

类型	名称
RF Data Converter	`usp_rf`
MicroBlaze	`microblaze_0`
AXI UARTLite	`axi_uartlite_0`
AXI interconnect	`microblaze_0_axi_periph`
Clock wizard	`clk_wiz_1`
Reset controller	`rst_sys_clk_200M`、`rst_sys_clk_200M1`
用户 RTL	`user_sysref_sync_gen`
顶层 wrapper	`system_mb_wrapper.v`

现在我已经知道这个工程属于典型 RFSoC/RFDC 类 BD 工程：软件控制、AXI 配置、高速 AXIS 数据和调试观测同时存在，并不是单纯 RTL 项目。

这段回答的价值在于，AI 开始用"工程结构"说话，不再只复述文件名。

对话第三轮：MicroBlaze 到 RFDC 是怎么连的

客户接下来问到了更具体的问题：控制平面怎么进 RFDC？

客户：

MicroBlaze 是怎么控制 RFDC 的？你能看出 AXI 控制链路吗？

AI：

可以。Starter 在 BD 连接里识别到 MicroBlaze 的 AXI 数据端口先进入 AXI interconnect，然后再连接到 UARTLite 和 RFDC 控制接口。

关键连接包括：

text 复制代码

microblaze_0/M_AXI_DP -> microblaze_0_axi_periph/S00_AXI
microblaze_0_axi_periph/M00_AXI -> axi_uartlite_0/S_AXI
microblaze_0_axi_periph/M01_AXI -> usp_rf/s_axi

这说明 microblaze_0 通过 microblaze_0_axi_periph 访问外设。其中 M01_AXI 连接到 usp_rf/s_axi，也就是 RF Data Converter 的 AXI 控制接口。

客户：

那如果我要让 AI 后续看 RFDC 配置相关问题，它应该先读哪里？

AI：

我会先围绕这条控制路径读取相关证据：

system_mb.bd 或 BD 摘要，确认 usp_rf/s_axi 的连接；
system_mb_wrapper.v，确认 BD wrapper 暴露了哪些外部端口；
与 MicroBlaze 软件或配置相关的导出文件，如果工程中包含；
RFDC IP 的配置摘要，避免一开始读取所有 IP 生成文件；
如果问题涉及约束，再回到 XDC 和时钟复位摘要。

这就是 Starter 工程地图的作用：先知道控制链路，再按问题读取文件。

对话第四轮：AXI4-Stream 数据流怎么走

这个工程不只是控制 RFDC，还包含 AXI4-Stream 数据通路。客户继续追问数据流。

客户：

数据流呢？DDS 生成的数据是怎么进 RFDC 的？

AI：

Starter 识别到一条关键 AXI4-Stream 数据路径：

text 复制代码

dds_compiler_0/M_AXIS_DATA -> axis_dwidth_converter_0/S_AXIS
axis_dwidth_converter_0/M_AXIS -> axis_data_fifo_0/S_AXIS
axis_data_fifo_0/M_AXIS -> usp_rf/s00_axis

这条链路说明：

dds_compiler_0 产生 AXIS 数据；
axis_dwidth_converter_0 做数据位宽转换；
axis_data_fifo_0 做数据缓冲；
最终数据进入 RFDC 的 s00_axis。

如果你后续要检查"为什么 RFDC 输入没有数据"或"AXIS 位宽是否匹配"，我会优先看这条链路上的 DDS、位宽转换、FIFO 和 RFDC AXIS 端口，避免打开整个工程目录。

客户：

RFDC 输出有没有被 ILA 观察？

AI：

有。Starter 识别到 RFDC 输出和 ILA 的连接，例如：

text 复制代码

usp_rf/m00_axis -> system_ila_0/SLOT_0_AXIS
usp_rf/m01_axis -> system_ila_0/SLOT_1_AXIS
usp_rf/m10_axis -> system_ila_1/SLOT_0_AXIS
usp_rf/m11_axis -> system_ila_1/SLOT_1_AXIS

这说明工程里已经有 ILA 观测 RFDC 多路输出 AXIS 数据。后续如果要做板级调试，可以把这些 ILA 连接作为信号观察入口。

这一轮对话开始像真实工程协作了：客户问的是系统数据怎么走，AI 回答的是具体 IP 和端口连接。

对话第五轮：为什么这比盲扫目录省得多

客户：

这个工程如果直接让 AI 扫目录，会浪费多少？

AI：

在这次 RFDC + MicroBlaze 工程验证中，原始工程目录扫描估算约 148M tokens。通过 Starter 建立索引后，交给 AI 的工程上下文约 30K tokens。缓存命中后，摘要返回时间约 434 ms。

项目	数值
原始工程扫描估算	约 `148M tokens`
Starter 索引上下文	约 `30K tokens`
缓存摘要返回	约 `434 ms`

这个数据不应该理解成所有工程都有固定比例。它说明在这个 RFDC + MicroBlaze 工程里，大量 generated files、IP products、BD output 和 run/cache 目录并不适合直接塞给 AI。

Starter 的做法是先给 AI 工程地图：top、BD、关键 IP、AXI/AXIS flow、时钟复位和推荐入口。AI 需要深入时，再读具体文件。

对话第六轮：如果我要继续让 AI 改工程，它会怎么做

客户：

如果我后面想让 AI 检查 user_sysref_sync_gen，或者分析 RFDC 相关时钟复位，它下一步会怎么做？

AI：

我会先基于 Starter 的工程地图缩小范围：

如果问题是 user_sysref_sync_gen 的逻辑，我会先读取这个用户 RTL，再看它和 BD wrapper 的连接；
如果问题是 RFDC 输入数据，我会沿着 dds_compiler_0 -> axis_dwidth_converter_0 -> axis_data_fifo_0 -> usp_rf/s00_axis 读相关模块和 BD 连接；
如果问题是 MicroBlaze 配置 RFDC，我会沿着 microblaze_0 -> microblaze_0_axi_periph -> usp_rf/s_axi 看 AXI 控制路径；
如果问题是 ILA 观测，我会先看 usp_rf 到 system_ila_0/system_ila_1 的 AXIS 连接；
如果问题是时钟复位，我会优先看 clk_wiz_1、rst_sys_clk_200M、rst_sys_clk_200M1 和 XDC。

这比"把所有 RTL 和生成文件都读一遍"更接近工程师的排查方式。

客户：

所以 Starter 的重点是让 AI 先知道怎么进入工程，不是替我完成综合实现？

AI：

对。Starter 的重点是工程理解、索引和结构图。它让 AI 少扫目录、少读噪声、少让工程师重复解释。

如果后续需要执行综合、实现、报告摘要、证据归档或历史对比，可以继续使用 Pro；如果当前目标是让 AI 先理解一个复杂 Vivado 工程，Starter 就是入口层。

这次案例说明了什么

这次 RFDC + MicroBlaze 工程很适合说明 Starter 的价值。它不是单一 RTL 小项目，而是一个真实复杂工程：

有 RF Data Converter 这种重量级 Xilinx IP；
有 MicroBlaze 控制平面；
有 AXI 和 AXI4-Stream 双链路；
有 Block Design 和 generated wrapper；
有时钟、复位、FIFO、位宽转换和 ILA 观测；
有大量不适合 AI 首轮阅读的生成文件和缓存目录。

RepoKey Starter 做的事情，可以概括成一句话：

先让 AI 拿到工程地图，再让 AI 精读关键文件。

这样 AI 在面对复杂 Vivado 工程时，第一轮回答就能围绕 system_mb_wrapper、usp_rf、microblaze_0、AXI 控制链路和 AXIS 数据流展开，避开 generated files 里的无效绕路。

想自己试，可以这样问 AI

如果你正在用 Codex、Claude 或其他支持 MCP 的 AI Agent 做 FPGA 开发，可以访问 RepoKey Vivado AI 官网了解 Starter。

第一次测试时，可以直接这样问：

先用 RepoKey Starter 生成工程地图，告诉我这个 Vivado 工程的 top、器件、Block Design、关键 IP、AXI/AXIS 数据流、时钟复位和优先阅读文件。

如果你的工程里也有 IP、BD、XDC、生成文件和复杂数据通路，这个问题比"帮我分析整个工程"更容易得到有用答案。