RFSoC-PYNQ → RK-XCKU5P-F 移植记录

本文档记录将 fpga/pynq/rfsoc-pynq/（NVIDIA HSB 开源项目，基于 QSFP28 + GTY +

cmac_usplus v3.1 的 RoCEv2 网卡/协议栈简单实现）移植到开发板

RK-XCKU5P-F V1.2 （FPGA 器件 XCKU5P-2FFVB676I ）的全部改动内容、

依据的资料信息，以及构建/验证方法。

移植结果代码位于：fpga/vitis/xcku5p/rk-xcku5p-f/

1. 源项目与目标平台

1.1 源项目（已验证正确）

fpga/pynq/rfsoc-pynq/，目标器件 xczu48dr-ffvg1517-2-e（Zynq UltraScale+ RFSoC，

RFSoC 4x2 板卡），Vivado 2024.1 构建。结构：

复制代码

rfsoc-pynq/
├── build/
│   ├── build.sh                  # 入口脚本，调用 vivado -mode batch
│   ├── build.tcl                 # 建工程、加 RTL/BD/XDC、跑综合实现、导出 bit
│   ├── constraints/constraints.xdc
│   └── ip/bd_gen.tcl             # 生成 block design（cmac_usplus + clk_wiz + xlconstant）
└── rtl/
    ├── top/FPGA_top.sv           # 顶层：时钟/复位、100GbE、HOLOLINK_top、ILA、ram_player
    ├── top/HOLOLINK_def.svh      # HOLOLINK 配置包（时钟频率/接口宽度/寄存器数等）
    ├── eth_100gb/eth_100gb_top.sv# 100GbE 封装：例化 BD，CMAC 上电初始化状态机
    └── rst/rst.sv                # 系统复位 / CMAC 复位

要点：

以太网：QSFP28，CAUI-4（4×25.78125G），cmac_usplus:3.1，AXIS 512bit 用户接口，
不开 RS-FEC（INCLUDE_RS_FEC 默认 0），无流控。
GT 参考时钟 156.25 MHz；CMAC gt_txusrclk2 = 322.265625 MHz，经 clk_wiz
分出 50 MHz（APB）和 100 MHz（PTP）。
系统时钟 100 MHz → IBUFDS→BUFG 作为 CMAC/GT 的 init_clk（free-running）。
HOLOLINK（fpga/nv_hsb_ip/，板级无关 RTL）实现 RoCEv2/UDP/BOOTP/PTP 等协议栈。

1.2 目标平台

开发板 RK-XCKU5P-F V1.2 ，FPGA XCKU5P-2FFVB676I （Kintex UltraScale+，

FFVB676 封装，速度等级 -2，工业级）。

已从 Vivado 2024.1 验证：cmac_usplus:3.1 IP 可针对 xcku5p-ffvb676-2-i 创建，

且该器件含 GTY（GTYE4）收发器，满足 CAUI-4（25.78125 Gb/s/lane）速率要求。

2. 目标板硬件信息（改动依据）

资料来源：fpga/xcku5p-rfsoc_4x2-docs/

RK-XCKU5P-F V1.2原理图.pdf（原理图）
RK-XCKU5P-F V1.2管脚定义.xls（管脚定义，含 QSFP28 / 其他等工作表）
pg203-cmac-usplus.pdf（CMAC v3.1 产品指南）
ug578-ultrascale-gty-transceivers.pdf、ug571-ultrascale-selectio.pdf 等

2.1 QSFP28 接口（原理图 "QSFP & CONN" 页 + 管脚定义 QSFP28 表）

QSFP28 笼子 4 条高速通道全部落在 GTY Quad 225，与连接器管脚一一对应（无交叉、无极性翻转）：

QSFP28 通道	FPGA 网络	RX 引脚 (N/P)	TX 引脚 (N/P)	GTYE4_CHANNEL
QSFP1 (Tx1/Rx1)	QSFP1_TX/RX_P/N	Y1 / Y2	AA4 / AA5	X0Y4 (lane0)
QSFP2 (Tx2/Rx2)	QSFP2_TX/RX_P/N	V1 / V2	W4 / W5	X0Y5 (lane1)
QSFP3 (Tx3/Rx3)	QSFP3_TX/RX_P/N	T1 / T2	U4 / U5	X0Y6 (lane2)
QSFP4 (Tx4/Rx4)	QSFP4_TX/RX_P/N	P1 / P2	R4 / R5	X0Y7 (lane3)

GT 参考时钟：GT_CLK156P25_P/N = V7 / V6 （MGTREFCLK0_225），

由 SiT9120AI-2D3-33E156.250000（156.25 MHz LVDS，3.3V）经 100nF 交流耦合输入。

→ 与源设计 GT_REF_CLK_FREQ = 156.25 一致，无需改 CMAC 配置。

QSFP28 低速控制/状态（Bank 84，VCCO = +3.3V，连接器直连 FPGA，板级无上下拉，

SCL/SDA/MODPRSL/INTL 板上有 4.7K 上拉）：

信号	引脚	方向(FPGA)	说明
QSFP_LPMODE	W14	输出	必须驱动为 0，否则模块处于低功耗模式，链路不会 up（模块内部上拉）
QSFP_RESETL	W12	输出	低有效模块复位，驱动为 1 释放复位
QSFP_MODSELL	W13	输出	低有效 2-wire 选择，驱动为 1（本设计不用 I2C）
QSFP_MODPRSL	AA13	输入	模块在位指示，低有效
QSFP_INTL	Y13	输入	模块中断，低有效（本设计未使用）
QSFP_SCL / QSFP_SDA	AE15 / AE13	-	模块 I2C，本设计未使用

2.2 系统时钟（原理图 "SYS CLK" 页）

晶振 Y2：SG3225VAN 200.000000M-KEGA3（200 MHz，LVDS，3.3V）
输出经 C194/C195（100nF）交流耦合；FPGA 侧 R70/R71/R73/R74（10K）分压
提供 VCM = DDR_1V2/2 ≈ 0.6V，R72 = 100Ω 提供板上差分终端。
接入 Bank 65（HP，VCCO = DDR_1V2 = 1.2V ）的 GC 引脚：
SYS_CLK_P = T24，SYS_CLK_N = U24。
结论：IOSTANDARD 应选 DIFF_HSTL_I_12 （HP Bank、1.2V VCCO、VCM≈0.6V 均匹配；
板上已有外部 100Ω 终端，无需打开内部 DIFF_TERM）。
注意与源板不同：源板系统时钟为 100 MHz，本板为 200 MHz 。
CMAC v3.1 的 GT DRP/init clock 允许范围为 50--250 MHz（PG203 第 4 章
"GT DRP/Init Clock"），200 MHz 合法；同时在 BD 中把
CONFIG.GT_DRP_CLK 设为 200.00 使 GT Wizard 复位时序参数与实际时钟一致。

2.3 按键与 LED（原理图 "40PIN IO" 页 + 管脚定义其他表）

KEY1--KEY4：按键一端接地，网络经 4.7K 上拉到 3.3V（R97/R100/R103/R106），
并联 100nF 去抖电容 → 低有效 （松开=高，按下=低）。
本设计用 KEY1（K9 ，Bank 86，3.3V）作板级复位；源设计复位为高有效，
故在 RTL 内取反。
LED1--LED4：FPGA 经 1K 电阻驱动 NPN 三极管（MMBT3904）点亮 LED → 高有效 。
引脚：LED1=H9、LED2=J9、LED3=G11、LED4=H11（Bank 86，3.3V）。

2.4 器件 GTY 资源（Vivado 查询结果）

xcku5p-ffvb676-2-i 的 GTYE4_CHANNEL_X0Y4...X0Y7 即 Quad 225

（其 MGTREFCLK0 = Bank 225 的 V6/V7，属 GTYE4_COMMON_X0Y1）。

CMAC 默认 LANE1..4_GT_LOC = X0Y4..X0Y7，与本板走线完全一致；

XDC 中仍显式 LOC 锁定，与源设计做法相同（巧合的是源设计 channel 坐标同为

X0Y4--X0Y7，仅 package pin 不同）。

3. 改动清单

移植目录：fpga/vitis/xcku5p/rk-xcku5p-f/（目录结构与源项目一致；

注意本目录比源项目深一级，见 3.2 节 hsb_ip_dir 的调整）。

3.1 `build/build.sh`

与源文件相同（Vivado 2024.1，batch 模式调用 build.tcl）。

3.2 `build/build.tcl`

项	源 (rfsoc-pynq)	新 (rk-xcku5p-f)
`part_name`	`xczu48dr-ffvg1517-2-e`	`xcku5p-ffvb676-2-i`
`project_name`	`rfsoc-pynq`	`rk-xcku5p-f`
`hsb_ip_dir` 相对层级	`../../../../nv_hsb_ip`	`../../../../../nv_hsb_ip`（本目录比源项目深一级：vitis/xcku5p/rk-xcku5p-f vs pynq/rfsoc-pynq）
输出 bit 文件名	`rfsoc_pynq_<ts>.bit`	`rk_xcku5p_f_<ts>.bit`

其余流程（BD 生成/注册、RTL 添加顺序、run 配置）完全一致。

3.3 `build/ip/bd_gen.tcl`

项	源	新	原因
`part_name`	`xczu48dr-ffvg1517-2-e`	`xcku5p-ffvb676-2-i`	目标器件
`init_clk_0` 端口 `freq_hz`	100017438	200000000	本板 init_clk=200 MHz
`cmac_usplus_0` `CONFIG.GT_DRP_CLK`	未设置（默认 100.00）	`200.00`	与 200 MHz init_clk 一致（范围 50--250 MHz，PG203）

CMAC 其余配置保持不变：CMAC_CAUI4_MODE=1、GT_REF_CLK_FREQ=156.25、

INS_LOSS_NYQ=1、RX_EQ_MODE=LPM、无流控、USER_INTERFACE=AXIS、

不使能 RS-FEC（与已验证的 RFSoC 设计一致；对端 Mellanox CX5 需同样关闭 FEC，

即与 RFSoC 板验证时相同的网卡配置）。

clk_wiz_0 配置完全不变（输入仍是 gt_txusrclk2 = 322.265625 MHz，

输出 50 MHz / 100 MHz；KU5P 同为 MMCME4 原语）。

3.4 `build/constraints/constraints.xdc`

按第 2 节硬件信息全部重写引脚约束：

信号	源引脚 (ZU48DR)	新引脚 (KU5P)	电平
ETH_REFCLK_P/N	AA33/AA34	V7/V6（MGTREFCLK0_225）	-
sysclk_p/n	AM15/AN15 (LVDS, 100MHz)	T24/U24（DIFF_HSTL_I_12, 200MHz）	DIFF_HSTL_I_12
复位	AV12 `RESET`（高有效, LVCMOS18）	K9 `KEY1`（低有效, LVCMOS33）	LVCMOS33
gt gtx_p/n $0$	Y35/Y36	AA5/AA4	-
gt gtx_p/n $1$	T35/T36	W5/W4	-
gt gtx_p/n $2$	V35/V36	U5/U4	-
gt gtx_p/n $3$	R33/R34	R5/R4	-
gt grx_p/n $0$	R38/R39	Y2/Y1	-
gt grx_p/n $1$	W38/W39	V2/V1	-
gt grx_p/n $2$	U38/U39	T2/T1	-
gt grx_p/n $3$	AA38/AA39	P2/P1	-

GT channel LOC 约束保持 GTYE4_CHANNEL_X0Y4..X0Y7，但 GT Wizard 生成层次中

gen_channel_container 的序号随器件/Quad 选择变化：

源设计（ZU48DR）：...gen_gtwizard_gtye4.gen_channel_container[1].gen_enabled_channel...
本设计（KU5P，Quad 225）：...gen_gtwizard_gtye4.gen_channel_container[3].gen_enabled_channel...

XDC 中 4 条 GT LOC 与 2 条 set_clock_groups（引用 GT TXOUTCLK）的层次路径

已同步改为 gen_channel_container[3]。该差异很关键 ：若 container 序号不匹配，

set_clock_groups 无法作用，clk_wiz 输出（50/100 MHz）与 gt_txusrclk2

（322 MHz）之间的跨时钟路径会被错误分析，导致约 1.9 万个端点 setup 违例

（首次构建实测 WNS = -3.64 ns，修复约束后时序收敛，见第 5 节）。

新增引脚：

QSFP_LPMODE=W14、QSFP_RESETL=W12、QSFP_MODSELL=W13（LVCMOS33 输出，SLOW）；
QSFP_MODPRSL=AA13、QSFP_INTL=Y13（LVCMOS33 输入）；
LED1=H9 / LED2=J9 / LED3=G11 / LED4=H11（LVCMOS33 输出，SLOW）。

时序约束：

ETH_REFCLK_P：create_clock 6.400（156.25 MHz，不变）；
sysclk_p：create_clock 5.000（200 MHz，原为 10.000）；
clk_wiz 两路输出与 GT TXOUTCLK 的 set_clock_groups -asynchronous 不变；
新增：KEY1、QSFP 控制/状态、LED 的 set_false_path（异步板级信号）。

3.5 `rtl/top/FPGA_top.sv`

最小化改动（其余逻辑与源文件逐行一致）：

端口：RESET → KEY1（低有效按键）；内部 assign RESET = ~KEY1;，
下游所有复位逻辑不变。
新增 QSFP28 控制输出（常量驱动）：
- QSFP_RESETL = 1'b1（释放模块复位）
- QSFP_MODSELL = 1'b1（不选 2-wire 接口）
- QSFP_LPMODE = 1'b0（退出低功耗模式，链路 up 的必要条件）
新增状态输入 QSFP_MODPRSL、QSFP_INTL（INTL 未使用）。
新增 4 个 LED 状态指示：
- LED1 = aligned[0] ------ 100GbE RX 对齐 = 链路 up 指示
- LED2 = ~QSFP_MODPRSL ------ QSFP28 模块已插入
- LED3 = &gt_powergoodout ------ 4 条 GTY 通道全部上电完成
- LED4 = pll_locked[0] ------ clk_wiz 锁定（usr 时钟链正常）
注释更新：sysclk 为 200 MHz。

3.6 未改动直接拷贝的文件

rtl/top/HOLOLINK_def.svh ------ 时钟频率（HIF 322.265625 MHz / APB 50 MHz /
PTP 100 MHz）、接口宽度、寄存器数量等均不变。
rtl/eth_100gb/eth_100gb_top.sv ------ BD 例化封装与 CMAC 上电初始化状态机不变
（BD 端口名保持一致）。
rtl/rst/rst.sv ------ 复位逻辑与工艺无关。
fpga/nv_hsb_ip/ 全部共享 IP ------ 板级无关 RTL，未做任何改动。

4. 构建与验证

4.1 构建

bash 复制代码

cd fpga/vitis/xcku5p/rk-xcku5p-f/build
# build.sh 中 VIVADO_PATH 默认为空，需先编辑为本机 Xilinx 安装根目录
# （例如 $HOME/Xilinx），或直接用下面的手动命令：
./build.sh        # 或手动: mkdir -p project_folder && cd project_folder && \
                  #   ~/Xilinx/Vivado/2024.1/bin/vivado -mode batch -source ../build.tcl

产物：fpga/vitis/xcku5p/rk-xcku5p-f/bitfile/rk_xcku5p_f_<时间戳>.bit

（构建验证结果见第 5 节）

4.2 上板验证步骤

用 JTAG（板上 USB Type-C JTAG）烧写 bit 文件（Vivado Hardware Manager，
识别到 XCKU5P 器件后 program 即可）。
插入 QSFP28 光模块/AOC，光纤连接对端 Mellanox ConnectX-5 (MCX566A) 的
QSFP28 端口。
观察板载 LED：
- LED2 亮 = 模块在位；LED3 亮 = GTY 上电完成；LED4 亮 = 时钟链锁定；
- LED1 亮 = CMAC RX 已对齐（100G 链路建立）。
在对端主机上确认链路 up：
bash 复制代码
```
ip link show <iface>        # 应显示 LOWER_UP / UP
ethtool <iface> | grep -E "Speed|Link"   # Speed: 100000Mb/s, Link detected: yes
```
注意：本设计未开 RS-FEC，与 RFSoC 验证环境一致；若网卡侧 FEC 配置为
强制 RS-FEC，链路将无法对齐，请保持与 RFSoC 验证时相同的
ethtool --set-fec ... encoding off（或 auto）配置。
板级复位：按下 KEY1 可复位 CMAC/HOLOLINK 逻辑（链路会重新对齐）。

5. 构建验证记录

Vivado 版本：2024.1（与源项目要求一致）
cmac_usplus:3.1 针对 xcku5p-ffvb676-2-i 创建 IP 成功（免费 license 可用，
与任务前提一致）。
器件 GTY 资源确认：Quad 225 = GTYE4_CHANNEL_X0Y4...X0Y7，refclk0 = V6/V7。

5.1 端到端构建结果（build.sh 全流程，2026-07-27）

BD 生成、CMAC/clk_wiz IP 综合、顶层设计综合、实现、bitstream 全部通过，0 ERROR。
位流：bitfile/rk_xcku5p_f_20260727040117.bit（15,431,243 B）
资源占用：CLB LUT 33,559 / 216,960（15.5%），寄存器 50,402 / 433,920（11.6%），
RAMB36 368 / 480（76.7%），DSP48E2 8，GTYE4_CHANNEL 4 / 16，MMCME4 1。
DRC（routed）：无 error 级违例（仅 DSP 流水线、BRAM 写冲突等 advisory 警告，
与源 IP 固有属性一致）。
引脚/位置复核（placed 网表实测）：
- 33 个顶层端口全部落在第 3.4 节目标引脚上；
- CMAC lane0...3 分别锁定在 GTYE4_CHANNEL_X0Y4/X0Y5/X0Y6/X0Y7
  （与 QSFP1...4 一一对应）。
时序：
- clk_out1/2_design_1_clk_wiz_0_0（50/100 MHz）、sysclk_p（200 MHz）、
  rxoutclk、各 TXOUTCLKPCS 域：全部收敛；
- txoutclk_out[0]（322.265625 MHz 用户数据通路）：
  WNS = -0.170 ns，TNS = -29.9 ns（596/140734 端点，Slow corner）。
  最差路径位于 u_hololink_top 的 rx_parser（RAMB36→组合逻辑→RAMB36），
  属于 fpga/nv_hsb_ip 共享 IP 在 322 MHz 下的固有长路径；源 RFSoC 工程
  在相同速率等级（-2）、相同时钟频率下使用完全相同的 RTL，属同一性质
  （经 phys_opt_design + route tns_cleanup 验证不再恶化也不改善）。
  违例幅度约为周期的 5%，不影响 CMAC PCS 对齐与链路 up 判据；
  对温度/电压余量敏感的场景可在后续用 Performance_Explore 策略多次布局布线
  进一步收敛。

5.2 第一次构建暴露的问题及修复（已并入 3.4 节）

首次构建时 XDC 沿用源设计的 gen_channel_container[1] 层次路径，

而 KU5P 上 CMAC GT 实例实际生成在 gen_channel_container[3] 下，导致

2 条 set_clock_groups 未生效、clk_wiz 时钟与 322 MHz 用户时钟间的

异步路径被错误分析（WNS = -3.636 ns，19,276 端点违例）。

将 XDC 中相关路径改为 [3] 后重建，上述 1.9 万端点违例全部消除。

（注：4 条 GT LOC 虽未匹配，但 8 对 PACKAGE_PIN 约束已把通道钉在正确位置，

故两次构建的 GT 物理位置均正确。）