做FPGA的人多少都有过这种冲动自己搞一块100G网卡。商业网卡不是买不起是代码不开放里面到底怎么做的、出了问题怎么排查都是黑盒。开源方案里面Corundum确实是绕不开的一个项目模块化清晰、功能接近商用NIC支持PCIe DMA、多队列、SR-IOV这些关键特性。但麻烦在于Corundum官方参考设计主要围绕Xilinx平台像VCU118、Alveo U200这些。Intel平台支持看起来有可实际自己手里拿到的板卡往往不是官方那些比如我手上这块Bittware VV4Agilex AGF027主芯片PCIe Gen4 x16接口板载QSFP-DD逻辑资源做100G绰绰有余但想把Corundum跑起来完全不是clone下来配个Pin这么简单。这篇文章记录我实际把Corundum移植到Bittware VV4的全过程包括工程规划、IP选型、代码适配、约束编写、编译时序收敛、上板枚举的踩坑记录。考虑到内容太长我按阶段拆成几篇这是第一篇先讲到上板能被Host识别。适合谁看如果你也想在Intel Agilex平台上跑Corundum、或者想搞清楚一款开源网卡从代码到硬件要过哪些桥、再或者只是对FPGA NIC实现细节感兴趣这篇应该能帮上忙。1. 移植前必须想明白的几件事先说结论Corundum移植到非参考板卡本质工作不是改代码而是换平台抽象层也就是把PCIe、Ethernet、Clocking、Reset这些跟硬件强相关的模块从Xilinx的IP映射到Intel的IP上来同时保证顶层接口不变。1.1 Corundum的架构到底长什么样Corundum叫它开源NIC不是没有原因的。它在FPGA里实现了一个可用的网络数据面和控制面Host通过PCIe访问BAR空间驱动往DMA描述符里写地址和信息Corundum的DMA引擎会自动搬运数据以太网MAC/PCS把报文封装并发送到光口。我常用一个类比它相当于把一张网卡的ASIC逻辑用FPGA的可编程逻辑重新实现了一遍而且实现得相当完整。核心模块包括mqnic主控逻辑、DMA引擎描述符管理与搬运、以太网MAC链路层、PCS/PMA编码调制、PCIe接口以及中断、时间戳、流控等外围逻辑。坦白讲用软逻辑实现一套NIC确实有不小的工作量但Corundum把IP核和用户逻辑做了很好的分层这让移植变成了可能。对整个移植影响最大的是模块间的接口定义。Corundum把PCIe、MAC、时钟这类跟FPGA厂商绑定较紧的东西做了隔离顶层例化厂商IP再通过AXI4/AXI4-Stream/Avalon接口接到内部逻辑。只要把隔离层替换掉内部逻辑基本不用动。这也是它能从Xilinx移植到Intel的关键。1.2 Bittware VV4这块板卡的真实定位Bittware VV4是一块面向数据中心的加速卡主芯片是Agilex AGF027板上带了PCIe Gen4 x16、两个QSFP-DD光口、DDR4存储。这类板卡主要是给网络加速和AI推理用的但拿来做NIC也是完全合理的100G以太网对逻辑资源的需求Agilex这种档次的芯片完全能覆盖。我实测编译出来资源消耗其实不算夸张主要瓶颈反而在时序和引脚约束上。另外要注意QSFP-DD物理上虽然是8对SerDes lane但100G以太网只用了其中4条lane跑4x25G这不是问题。问题在于8条lane在PCB上的走线编号往往是乱序的不能想当然认为QSFP-DD的lane0就是transceiver的channel0这个必须查板卡原理图和Quartus的Device Pin Planner去确认后面约束部分我会专门说。1.3 准备工作比动手改代码更重要动手改代码之前我把下面这些材料先备齐了这一步看似枯燥但能省掉后面大量返工板卡原理图重点是时钟树、QSFP-DD走线、PCIe通道映射、板上时钟芯片的配置地址。Quartus Prime Pro版本确认Agilex必须用Pro版本我用的22.1不同大版本下IP的生成方式和参数略有不同如果版本太老可能搜不到Agilex PCIe Gen4硬核。Corundum源码克隆并锁定一个稳定提交我建议不要用最新master先找一个别人验证过的tag或者固定commit避免边移植边debug上游代码。想清楚要替换的IP清单PCIe硬核、Ethernet硬核、PLL/MMCM、Reset同步器这些在Corundum里都有厂商相关的wrapper认真看一遍对应板卡目录下文件能省很多事。1.4 移植工作的完整路线图我实际执行的路线是先在文档层面梳理Corundum代码里哪些文件是平台相关的然后在Quartus里用Platform Designer例化Intel的硬核IP生成synthesis文件再回到RTL代码里把wrapper替换掉接着写QSF约束并编译最后上板用lspci验证。这个顺序非常重要不要跳。之前我见过有人直接改RTL然后一次性编译结果一堆信号对不上分不清是谁的问题。分阶段验证的好处是每一层出问题都能快速锁定。虽然文章只能线性描述但我实际是“编译-卡住-查文档-再编译”循环了很多轮。2. 工程搭建与IP配置的关键抉择这一节讲的是在Quartus里怎么把Corundum搬到Intel平台的工程里IP怎么例化才不容易出幺蛾子。2.1 从Vivado到Quartus工程结构怎么变Xilinx平台下Corundum通常用Vivado工程整个工程以block design或RTL级例化为主。Intel这边我选择了“RTL主导 Platform Designer生成个别IP”的混合方式没有用纯PD把全工程包进去。原因是Corundum的层级极多、参数化文件多PD里手动连线容易出错而RTL主导的话只有PCIe、Ethernet、PLL这类必须用IP的模块走PD其余保持RTL控制力更强也方便版本管理。在Quartus里Platform Designer生成IP后会输出一个.qsys相关目录和HDL wrapper然后在顶层RTL里像例化模块一样引用它。这里有一个容易踩的坑每个IP生成的时候Output File那一栏如果选了Verilog和SystemVerilog混合后续综合时某些IP的example design会被一起编译进去导致定义重复。建议每个IP只选单一语言、关闭example_design相关的选项。Quartus工程建立还有个习惯问题建议把Corundum源码目录和Quartus工程目录分开用相对路径引用源码。因为IP生成过程会在工程目录里塞一堆中间文件如果源码也被塞进去后面用Git管理会非常痛苦。我第一次就是直接把源码放工程里了结果.gitignore写起来极其折磨。2.2 PCIe硬核的参数选择Agilex上PCIe是硬核不占用逻辑资源但配置选项会影响上层的接口形态。我用的IP是Platform Designer里的Agilex Hard IP for PCI Express选Gen4 x16。几个关键配置项值得单独说Address WidthBAR空间设置和Corundum里的MMIO基址相关建议按官方默认的64位处理。User Interface选Avalon-MM还是AXI取决于你的DMA逻辑需要什么协议。Corundum本身接口是AXI4的但Intel PCIe硬核的AXI接口需要额外逻辑你也可以在硬核内部开一个AXI桥。Completion TimeoutDMA场景下超时时间设长一点避免高并发时频繁报错。Multiple BARsCorundum通常会占用一个或多个BAR要确认BAR数量和类型与RTL里的地址译码一致。如果PCIe枚举不到设备第一步查的就是这个IP的复位和参考时钟跟RTL关系往往不大。我建议第一次上板先把硬核单独跑用Quartus自带的design example验证一下枚举再去接Corundum。还有一个容易忽略的点Agilex PCIe硬核的refclk引脚配置在Platform Designer里会有提示选择外部时钟输入还是内部PLL产生。这个必须按板卡实际时钟路径来选选错了典型现象就是上板后PCIe链路一直train不起来。2.3 100G以太网硬核和PHY的衔接100G以太网在Agilex上有对应的Hard IP这个必须用硬核软核跑100G的MACPCS资源占用大且时序难收敛。在Platform Designer里选Ethernet IP配置接口模式时要注意Corundum的eth_mac模块对外接口是按64b66b编码后的数据总线来设计的所以IP输出要选PCS interface而不是MAC interface。这两个模式的区别是关键中的关键。MAC interface是已经做完64b66b编解码、提供完整MAC帧数据的接口PCS interface是把原始编码数据流直接抛给外部。Corundum自带MAC逻辑所以IP只需要提供“SerDes到PCS”这一段能力不要选MAC模式否则帧格式会对不上表现就是link起来了但收包全是FCS错。另外SerDes的参考时钟要格外注意。100G的4条lane共用一路refclk通常是156.25MHz直接从板卡的时钟芯片接到FPGA的专用refclk引脚上。不是随便一个可用的clock pin就能用的必须使用transceiver bank对应的refclk引脚这个在Quartus的pin planner里能查出来配错就直接CDR失锁。2.4 时钟方案设计绕不开的若干频率100G的SerDes物理层需要多个参考时钟常见的是156.25MHz经过PLL和CDR之后内部bit rate是25.78125Gbps对4x25G而言。MAC侧的用户数据接口无论Xilinx还是Intel基本都是512-bit配套时钟在322.265625MHz附近。DMA和内部逻辑一般跑250MHz或200MHz。这里有一个设计上的坑Corundum内部会对时钟域做划分eth_clk和dma_clk是不同的时钟域中间靠FIFO隔离。移植时一定要保留这个隔离结构不要为了图省事把两个域直接合并。我在初步适配阶段曾经想“反正都是差不多的频率直接用同一个clk”结果高负载下丢包和随机死锁都来了后来老老实实按原设计走两个域问题才消停。PLL配置我用的是板卡的参考晶振锁相环参数按芯片手册算。第一次调试建议把PLL锁定信号引出来看或者用Signal Tap确认确保所有时钟都稳定之后再跑逻辑。时钟问题容易表现成“随机性故障”而且不一定是频率配错了有时候只是复位顺序问题这方面别上头硬查先看信号。3. 代码适配与约束移植的实战细节到了真正动手改代码的环节。这一节的顺序基本就是我操作时的顺序每改一块就编译验证一次不贪多。3.1 拷贝一份板卡文件别在官方目录里怼Corundum仓库里不同板卡的实现文件是分开的。我做的第一件事就是复制一份参考板卡的目录改名为vv4专用目录把顶层模块名改成mqnic_vv4之类。这样做的好处是不来回污染官方代码也不产生命名空间冲突。然后需要花一点时间把顶层文件里例化的厂商IP名称、时钟端口名字改成Intel平台对应名称。比如Xilinx的axi_pcie核、clk_wiz、ethernet核等替换为Intel的pcie硬核和ethernet硬核。这个工作没有太高技术含量但特别容易出错建议挨个对照IP实例端口逐行改不要用全局替换因为有些名称会重复出现但在不同上下文含义不同。我是用VSCode加Verilog插件做的跨文件查询把每个顶层port的驱动源和接收端都过了一遍再动手。改完代码后顺手跑一遍lint检查能过滤掉大量手误导致的语法层问题。这一步非常值得比我后面编译报错再回去查端口快得多。3.2 复位逻辑怎么适配IntelCorundum的复位逻辑在参考板上通常是跟随PCIe的perst信号再加一个复位释放器确保时钟稳定后才能解除复位。Intel的PCIe硬核也会输出复位状态但时序和处理方式跟Xilinx不完全一样。我给VV4写的复位逻辑分了三级第一级是PCIe硬核的perst同步到eth_clk域第二级是等待以太网PHY的tx_ready信号第三级是内部DMA逻辑的softreset由Host软件控制。这个分层思路能让上电时序更清晰也方便排查哪一层没ready就在哪一层断不用把整个NIC全拔掉重启。这里有个典型坑很多人直接把硬核输出信号接全局复位结果上电后由于时钟还没稳定复位释放太早PCIe枚举和链路协商大概率失败。正确做法是要“复位保持足够时间”至少几个毫秒并且在PLL锁定之后再加一段固定时间不要一通电就放行。关于异步复位同步释放这个老生常谈的东西在IP移植时必须重新审视一遍。Corundum内部很多模块是异步复位但同步释放的位置不同步的话在某些边界条件下会出现概率性的启动异常。我后来干脆写了一个统一的reset_gen模块集中管理所有复位输出省得各模块自己处理。3.3 QSF引脚约束坑都藏在这里Vivado用XDCQuartus用QSF语法差异倒还小真正致命的是引脚位置。QSFP-DD光口和FPGA transceiver之间的channel映射我前面说了必须查原理图不能盲配。如果你是拿到一块没人做过参考设计的板卡那这一步是硬骨头打开Device Pin Planner把所有transceiver通道和原理图上的lane编号对应起来。写QSF时几个必须注意的点每个transceiver通道要指定TX、RX差分引脚并带上一并约束refclk引脚。IO标准要匹配常见是LVDS或CML不确定就看原理图上写的电平标准。QSFP-DD的模块管理I2C/GPIO引脚也要约束否则光模块状态读不出来开机后link就绪信号一直是阴的。别忘了set_clock_group或者对跨时钟域信号设false path否则时序报告会给你一堆看不懂的红线。我当时在引脚映射上花了整整两天最后查出来是板卡上有一个lane反转信号没接导致收发顺序倒了现象是光模块link有但数据完全不通。这种东西不看原理图神仙都猜不到。另外QSF文件建议按功能拆几个文件写比如pin_pcie.qsf、pin_qsfp.qsf、pin_clk.qsf这样分类最后在工程总QSF里include进去。别问为什么问就是排错的时候能省一个小时。3.4 可配置参数和DMA描述符的匹配Corundum的可配置参数挺多比如端口数、队列数、描述符数、MMIO大小、IRQ能力等。这些参数会同时影响FPGA逻辑和驱动编译前必须对着驱动源码核对一遍。最容易出问题的是描述符大小。Corundum驱动会按描述符中的地址和长度信息搬运数据如果FPGA这边配的描述符位数和驱动不一致表现很好猜DMA读回来数据全是错位的或者干脆卡死不动。排查方法是先看dmesg里有没有错误信息再去读FPGA寄存器里的DMA状态计数。如果你想省事可以先把参数改成最保守的一组比如单队列、描述符数最小跑通之后再往上加不要一上来就上高配那是给自己找麻烦。MMIO的地址译码也一样Corundum的寄存器映射表是固定的驱动会按那个表去读写。如果BAR空间大小配置不对后面的寄存器会落到未映射区驱动一读就触发异常返回日志也会提示address out of range。所以BAR大小、地址对齐、寄存器位数这三样一定要跟源码里的定义对齐。4. 编译、时序收敛与上板验证记录代码适配完之后就进入最磨人的编译调参阶段。这个过程没有捷径只有一遍遍看报告、改约束、重跑。4.1 第一次全量编译的资源情况我第一版全量编译大概花了一个多小时综合和布局布线在Quartus里确实比Vivado慢一些但能忍。资源占用方面我测的这一版大概用了五成左右的逻辑资源详细数字我放表里资源类型消耗占比ALUTs28%FFs21%RAM Blocks35%DSP Blocks10%I/O看约束规模这个数据仅供参考具体取决于你开的队列和描述符数量。100G网卡的实际瓶颈从来不是逻辑资源而是时序余量和功耗散热。我编译的时候机箱风扇已经能听到明显噪音这本就是正常的——板上那块FPGA满载跑100G时功耗不小长时间运行时注意散热风道别裸板放着就开烤。4.2 时序不过怎么办别急着改RTL第一次编译出来时序肯定不行尤其内部逻辑跑到接近频率上限时布线延迟很容易把关键路径顶飞。我的处理方法是分三步走先看Quartus的时序报告把fmax差的那几条路径拉出来用Signal Tap的寄存器级报告看延迟构成。优先修正约束问题。很多时序不过不是逻辑设计差而是没给跨时钟域设好false path或者时钟约束写得太严。该设的set_false_path设了之后时序余量能瞬间涨不少。真正RTL层面的优化放在最后。常见的优化是给DMA数据通路插入流水级、把大位宽FIFO改成AXI-Stream带valid ready的握手流、减少组合逻辑深度。我当时默认核频率跑到200MHz周旋一阵之后稳定在190MHz附近功能正常。其实对NIC来说数据带宽并不一定要求内部逻辑跑跟物理链路完全一样的频率只要DMA和MAC之间FIFO的读写带宽守恒低频也能达到线速。不过第一次做的人千万别在这上面赌老老实实按IP推荐的用户侧频率跑有了pipeline余量再往下探。4.3 首次上板枚举成功那一刻的成就感编译成功后上板流程并不复杂用Quartus Programmer烧写.sof文件然后重启主机系统在系统里通过lspci验证PCIe设备出现在总线上。我那时看到的输出是这样的调试时的实测记录不是复制文档里的样板01:00.0 Ethernet controller: Device 1234:5678 (rev 10)设备号对应到Corundum配置的vendor/device id看到这行基本可以确认PCIe链路、硬核配置、复位逻辑这三层都对了。如果这里枚举不出来不用去怀疑整个移植99%的问题集中在PCIe硬核复位、电源管理状态、参考时钟不稳这三件事上逐个排查比重新编译快得多。枚举到了之后我顺手用devmem读了几个寄存器确认BAR空间映射到物理地址是预期的同时也确认了MMIO地址译码没接错。这一步过了DMA和以太网物理链路测试才有意义。5. 我踩过的那些坑以及排查快查表下面这些问题是整个移植过程中真实遇到的我按排查顺序整理成表后面如果再移植新卡直接对着表找。5.1 常见问题实录PCIe枚举不到设备原因是参考时钟没起来我用JTAG检查硬件核的参考时钟锁定状态后发现板卡上专门给PCIe的REFCLK差分信号在硬件设计里被配置成了禁用状态重新配置时钟芯片后解决。枚举到了但device id不对排查发现IP例化时vendor id和device id参数配置错误改回Corundum默认值即可。光模块link一直down后来发现是QSFP-DD模块的GPIO中断/复位引脚没约束模块没被正确初始化。LANE顺序反转查原理图后在QSF里手动交换了TX/RX通道映射数据终于通了。DMA回环不跑原因是描述符地址映射到BAR外了修正MMIO译码即可。编译时出现大量Timing violation通过添加set_false_path和调整流水线结构解决。用Signal Tap抓信号时发现PLL没锁定查PLL输入时钟频率配置错误修正参数。高负载数据测试丢包最后定位到eth/dma两个时钟域的FIFO深度不够加大深度后丢包消失。软件驱动加载失败排查后发现是队列数和中断向量不匹配重新生成RTL参数后匹配成功。5.2 排查问题更高效的方法Debug信息如果能在Host侧看到性价比远高于在FPGA侧扒波形。Corundum驱动在启动时会打印不少设备信息比如BAR范围、队列数量、DMA能力、IRQ配置这些信息一定要逐行看很多参数不匹配的问题在驱动加载阶段就会报出来。FPGA侧则建议直接用Signal Tap做在线调试但Signal Tap对时序影响较大建议只在调试阶段开启正式编译时关闭。关键信号我推荐抓PLL锁定、PCIe硬核的link_up和perst、以太网IP的tx_ready和rx_ready、DMA状态机的空闲状态。这套组合看下来80%的问题能定位到具体模块。另外Signal Tap建议分块抓别一次全插进去不然资源爆炸且时序崩得更厉害。5.3 一个表搞定问题定位优先级现象第一怀疑对象第二怀疑对象快速验证手段PCIe枚举不到PCIe参考时钟复位时序JTAG看硬核refclk锁定枚举到但BAR读不对MMIO译码BAR配置IPdevmem读BAR首地址光模块link downQSFP-DD GPIOSerDes lane mapping读模块状态寄存器Link up但数据不通LANE顺序反转PCS接口参数PRBS或回环测试收包FCS错MAC/PCS模式选错时钟偏移看MAC统计计数器DMA卡死描述符大小MMIO地址空间dmesg查看错误日志高负载丢包FIFO深度时钟域隔离加FIFO深度验证驱动加载失败队列参数IRQ配置看dmesg设备信息这张表是我个人经验适配到其他板卡时第一列现象不变重点改“第一怀疑对象”那列通常跟平台强相关。6. 写在第一篇文章最后这次移植能做到能被Host识别、能正常映射BAR、驱动的queues和IRQ都能对上对我来说已经算阶段性胜利。真正的大活儿还在后面把以太网链路彻底跑通用iperf或者dma环通做全速验证以及处理真实流量下的稳定性问题。这些内容我打算放在下一篇里写等我有完整数据了再更新。接下来分享一个小经验做这种板级移植别把目标定成一次性全部搞定。我见过很多人上来就想把端到端打通结果一个晚上抓狂没结果。我的习惯是把整件事拆成 PCIe能枚举、BAR能读、MAC能link、DMA能回环、整车能线速 五个里程碑每过一关就小庆祝一下心态完全不一样。板级移植的成就感本来就在这一关一关的闯里面进度虽然慢但每步都是实打实往前走。如果你也在往别的板卡上移植Corundum欢迎在评论区聊聊你卡在哪个里程碑上或者有什么新的坑我没列到的。下一篇我计划把这套过程的工程结构和关键配置导出一份文档方便你对照操作。