本文档记录将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，FPGAXCKU5P-2FFVB676I（Kintex UltraScale+，
FFVB676 封装，速度等级 -2，工业级）。
已从 Vivado 2024.1 验证：cmac_usplus:3.1IP 可针对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.1build/build.sh
与源文件相同（Vivado 2024.1，batch 模式调用build.tcl）。
3.2build/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.3build/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_0CONFIG.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.4build/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 |
| 复位 | AV12RESET（高有效, LVCMOS18） | K9KEY1（低有效, 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.5rtl/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 = >_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 构建
cdfpga/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：
注意：本设计未开 RS-FEC，与 RFSoC 验证环境一致；若网卡侧 FEC 配置为iplinkshow<iface># 应显示 LOWER_UP / UPethtool<iface>|grep-E"Speed|Link"# Speed: 100000Mb/s, Link detected: yes
强制 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 物理位置均正确。）
