Corundum开源100G网卡移植到非Xilinx FPGA：接口适配与踩坑记录

做网络FPGA开发的朋友应该都听说过Corundum这个开源100G NIC项目。简单说它是一套基于FPGA的完整10G/25G/40G/100G网卡实现由MIT的Alex Forencich维护包含PCIe DMA、以太网MAC、队列管理、TSN支持等一整套核心逻辑是目前开源社区里最接近商用智能网卡方案的代码库之一。最近我把Corundum往Bittware VV4板卡上移植了一版过程比想象中曲折但整体框架打通之后后续很多工作都能复用了。这篇文章先记录第一阶段的移植思路、改动点、实际操作流程和踩坑记录给打算在非Xilinx平台跑Corundum的朋友做个参考。很多人在网上搜Corundum默认它是Xilinx专属的因为原版工程大量使用Xilinx FPGA MAC、PCIe硬核和GTY SerDes。但Corundum的核心价值在于它的逻辑架构MAC、DMA、队列调度这些与厂商IP强绑定的部分其实只占一小部分。换平台最麻烦的从来不是逻辑本身而是接口适配PCIe硬核接口、SerDes通道布局、时钟树、复位时序以及工具链的约束语法。Bittware VV4用的是Achronix Speedster7t系列FPGA资源、SerDes能力和PCIe Gen4硬核都够用把Corundum搬过来是可行的只是需要动一番外科手术。这篇内容适合三类人想了解Corundum内部结构怎么和业务解耦的手上有非Xilinx平台、想跑开源NIC方案的以及单纯想看看100G网卡移植会遇到哪些坑的。我不会讲太多理论重点放在“我在VV4上实际怎么改、为什么这么改、跑起来后遇到了什么问题”尽量给出一份能跟着操作的路线图。1. 为什么选择Corundum和Bittware VV41.1 Corundum到底解决了什么问题Corundum这个项目的定位很明确做一套开源的、可扩展的、高性能的网卡软硬件方案。它不是一个简单的UDP收发demo而是一整套可用的数据中心网卡实现。核心件包括PCIe DMA引擎支持多队列、多中断并且把描述符管理做成通用结构以太网MAC层支持10G/25G/40G/100G包含流控、CRC、MAC过滤高速接口模块比如100G用的4路25G SerDes通道完整的Linux驱动可以对接普通网口驱动栈也可以暴露控制面给用户态程序换句话说你拿到Corundum后相当于拿到了一块“逻辑上完整的智能网卡”剩下的工作是把它适配到具体板卡、具体FPGA、具体光模块上。我选择Corundum还有一个现实原因它的代码风格非常干净顶层模块和子模块边界清晰。模块之间要么是AXI4-Lite配置通道要么是AXI4-Stream数据通道没有大量跨模块的全局信号纠缠。这种风格对移植极其友好因为你在换平台时只需要去替换与FPGA物理资源相关的模块而不用重写整个数据通路。相比之下很多商业IP核和网卡参考设计把控制和数据混在一起一旦想换平台基本要推倒重来。1.2 Bittware VV4板卡的基本盘Bittware VV4是一块基于Achronix Speedster7t AC7t1500 FPGA的加速卡。这块板卡最吸引人的是三个地方PCIe Gen4 x16硬核带宽足够100G网卡使用板载4个QSFP-DD或者多个QSFP28接口物理上支持100G光模块Achronix的112G SerDes能力很强跑4x25G或1x100G都有余量Speedster7t这个芯片的另一个亮点是片内集成了所谓的“机器学习处理器”阵列但这块和网卡移植关系不大真正重要的是它的SerDes资源、PCIe硬核和大量支持外部存储的IO。我拿到的是VV4-PCIE板卡正面两个QSFP-DD接口侧面还有用于管理用的USB/UART整体布局和Xilinx那类自带QSFP的加速卡差别不小。对于一台100G NIC来说板卡层面的关键资源是高速收发器通道必须能连到光模块PCIe硬核必须有足够通道数和链路速率板卡时钟源需要支持SerDes所需的各种参考频率。Bittware VV4都满足但这只是必要条件真正的难点在逻辑层如何把它们和Corundum接起来。1.3 移植的整体思路换接口不换架构第一阶段移植我给自己定了三条原则避免陷进细节泥潭第一不改Corundum内部的数据通路逻辑。DMA、MAC、队列管理这些核心模块只要接口信号符合AXI标准就保持原样。越少改动后期升级原项目代码时就越轻松。第二只做“平台适配层”。所谓适配层就是把Achronix的PCIe硬核、SerDes收发器、时钟管理模块包装成Corundum顶层期望的接口。相当于给Corundum做一套“转接头”。第三先跑通100G的MAC到光模块通路再折腾PCIe DMA。因为移植初期最容易出现的问题是数据面不同步、复位时序不对如果一上来就同时验证PCIe和以太网出了问题很难定位。先把以太网链路测通再用Corundum自带的测试模块去验证DMA分阶段推进。这个思路听起来简单但实际执行时会发现Corundum顶层对复位、时钟、MAC接口的时序要求很明确而每个FPGA厂商的硬核行为又不一样适配层才是工作量最大的地方。2. 移植前的准备资料梳理与硬件确认2.1 先对齐IO资源和引脚约束移植前最重要的一件事是把FPGA的引脚约束彻底理清楚。Corundum原版针对某个Xilinx开发板它的约束文件里包含了所有SerDes所连的GTY通道、PCIe引脚、LED、时钟输入等。到了VV4上这些全部要重写。我先把Bittware官方提供的VV4板卡约束文件找出来重点看三块内容QSFP-DD/QSFP28接口连到哪几个SerDes通道包括接收、发送、极性关系PCIe硬核对应的引脚是怎么分配的板载时钟源特别是156.25MHz、100MHz这类参考时钟分别接到哪个时钟引脚这一步千万不能敷衍。我就见过有人在移植时把SerDes的TX极性弄反或者把不同QSFP口的通道接错导致链路怎么都起不来。VV4的约束文件里通常带一组例化的SerDes引脚说明照着映射就行。把IO资源对齐后我画了一张非常简单的映射表记录“Corundum顶层信号 - VV4引脚 - 对应硬核通道”后面写约束文件和调试时都靠这张表。这里也建议读者别嫌麻烦用表格管理这些映射比在代码里肉眼搜快得多。2.2 Corundum工程结构里的关键线索Corundum的代码仓库里有一个fpga目录里面按厂商和板卡分好了各种example。通常有xcvu3p、xcu250、xcu200等目录这些目录下的顶层模块和约束文件就是移植时最好的参考资料。我通常不是直接复制某个example而是把example里与“平台相关”的部分拎出来对比辨别哪些是Corundum通用逻辑哪些是厂商相关逻辑。基本规律如下rtl目录下的大多数模块是通用逻辑比如mqnic_core、mqnic_ethernet、mqnic_rx、mqnic_tx、dma_if等lib目录里有一些厂商相关的wrapper比如Xilinx的MAC封装、PCIe封装每个example顶层的fpga模块是把以上通用逻辑和厂商IP粘起来的地方对我来说移植的核心动作就是重新写一个顶层fpga模块把Achronix的PCIe硬核、SerDes收发器、时钟模块接成Corundum通用逻辑需要的标准接口。这就像换主机时CPU、内存、硬盘都是标准的只需要换一块匹配的主板。2.3 环境与工具链准备Corundum本身用Verilog编写理论上任何支持Verilog的FPGA工具链都能编译但需要特别注意不同工具对SystemVerilog和原语的支持程度。Achronix的设计环境ACE我用的版本支持Verilog-2001和部分SystemVerilog特性Corundum的主要代码都能直接进综合个别语法需要调整。另外要准备好Achronix ACE综合实现工具以及对应的license一个用于生成PCIe硬核和SerDes配置的IP配置工具通常在ACE环境里集成一个串口终端或者JTAG调试工具用于看板卡运行状态Linux主机上的驱动编译环境用于后续验证我自己习惯先在工程里只加入“最小可运行”模块也就是PCIe 一个简单的LED闪烁逻辑先确认工具链、板卡下载链路、PCIe枚举是好的。这一步过了再往工程里加Corundum逻辑。否则一上来就编译整个工程如果环境有问题你会分不清是代码问题还是工具链问题。3. 核心改造点从Aurora到XGMII的取舍3.1 Corundum的MAC接口到底长什么样Corundum的100G MAC接口从代码层看有两种风格。一种是原版针对Xilinx硬核MAC的接口直接使用Xilinx的100G Ethernet MAC IP核这种接口天然带XGMII/XLGMII风格的字节通道信号另一种是Corundum在lib目录下提供的独立MAC模块使用AXI4-Stream接口收发以太网帧。这里必须说清楚一个容易混淆的点很多人在移植时以为Corundum一定需要厂商MAC IP其实不是。Corundum内部有一个完整可综合的以太网MAC实现在lib/ethernet里它可以直接对接各种物理层接口。问题在于Corundum顶层example里默认用的是Xilinx 100G MAC IP这个IP的输出信号和Corundum内部的数据接口之间还有一个适配层。所以我的思路是绕开Xilinx IP直接让Corundum的MAC模块对接我们自己在VV4上做的64B/66B编解码器。也就是说物理编码子层由Achronix的SerDes硬核和用户逻辑完成MAC层则直接用Corundum自带模块。这样既减少了对外部IP的依赖也让整个链路更透明排查问题更方便。3.2 为VV4定制PHY wrapperAchronix Speedster7t的SerDes支持多种编码模式包括64B/66B、64B/67B等也可以工作在原始模式由用户逻辑自己处理编码。100G以太网使用的是4路25G每路物理层采用64B/66B编码加RS-FEC或者无FEC模式。VV4的SerDes硬核支持直接配置成64B/66B模式但我实测下来硬核自带的编码器更偏向于“透传”模式很多状态机需要用户逻辑自己控制。因此我写了一个PHY wrapper功能包括例化Achronix SerDes收发器配置成4路25G NRZ模式把SerDes的并行数据接口转换成Corundum MAC模块期望的64位或128位数据接口完成66B块同步、通道绑定、对齐标记插入/删除这些PCS功能产生link status、同步状态等信号喂给上层状态机这一层是整个移植最核心的工作。原因很简单Corundum的MAC层只认“干净的帧数据”它不管你底层是用了多少条SerDes通道、怎么做的64B/66B对齐。PCS层时序稍有不对MAC层就会收到大量错误帧。我第一版移植时偷懒直接用了SerDes的“自动同步”功能结果发现它只同步了单通道块边界没有做4通道对齐导致MAC层收到的数据乱序。后来才在wrapper里补上了通道绑定逻辑才真正把100G链路跑通。3.3 时钟和复位方案的重新设计移植中最隐蔽的问题往往在时钟和复位。Corundum原版example用的是Xilinx的时钟管理方案比如用MMCM/PLL把参考时钟分频倍频成MAC时钟和用户逻辑时钟。VV4上呢Achronix有自己的时钟资源而且100G链路对时钟抖动很敏感SerDes的参考时钟最好直接来自板载的高质量时钟源而不是经过普通逻辑时钟网络分频出来的信号。我最后采用的方案是100G SerDes使用板载156.25MHz参考时钟输入确保满足25Gbps速率下的抖动要求PCIe硬核使用独立的100MHz参考时钟用户逻辑时钟比如DMA和MAC侧由SerDes恢复时钟或者独立的core clock分频得到所有复位信号做成异步拉低、同步释放并且严格区分PCIe复位、SerDes复位、MAC复位三个域说到复位我踩过一个非常典型的坑Achronix的SerDes在配置完成之前输出的恢复时钟是不稳定的。如果我在此时把恢复时钟直接接到MAC逻辑上整个MAC状态机会乱跳。后来我在wrapper里加了tx_rx_up信号只有等SerDes完成初始化和码字同步后才把恢复时钟和有效数据释放给MAC层。这个“时钟有效门控”的思路强烈建议移植时也加上。4. 实际操作一步一步改代码4.1 建立顶层文件与模块划分这一步的目标是把Corundum顶层例化成VV4平台的样子。我建议按下面这个层次搭建工程最外层vv4_top包含板级引脚、时钟、复位、PCIe硬核、SerDes硬核、QSFP控制引脚等中间层corundum_fpga_wrapper把Achronix硬核接口转换成Corundum通用接口最内层corundum原模块基本不改动这样的好处是以后Corundum代码升级时只需要把最内层整体替换再调整中间层接口即可。我在实际开发中的习惯是给每一层都加上版本注释防止改乱了之后不知道哪一层对应哪一版。顶层文件里还有一个容易忽略的点QSFP-DD/QSFP28的I2C控制、中断引脚、模块复位引脚。Corundum本身不带QSFP管理逻辑但光模块的初始化比如配置成100G模式、读取模块信息通常由Linux侧的i2c驱动完成。因此顶层必须把这些引脚引出并正常约束否则板卡上电后光模块可能完全不工作。4.2 修改核心配置参数编译前要把三组关键参数设对第一PCIe相关参数。Corundum工程里通常用宏或参数指定PCIe通道数、链路速率、DMA描述符数量等。我在VV4上启用的是PCIe Gen4 x8或者x16实测在只跑一个100G端口时x8足够但如果你想跑满两个100G端口并开启多队列建议直接上x16。因为PCIe Gen4 x8大概有64GT/s的有效载荷带宽两个100G端口加上协议开销余量并不大。第二MAC和队列参数。Corundum默认的队列数量和描述符深度需要根据你的使用场景调整。如果你只做一个简单的iperf测速默认配置就行如果要在上面跑多队列或TSN实验需要把NUM_QUEUES、TX_QUEUE_OP这些参数从4扩到几十甚至上百。参数改完要注意逻辑资源占用特别是BRAM/URAM数量队列深了以后存储消耗会明显上升。第三物理层参数。包括每条SerDes通道的速率、PCS模式、是否启用RS-FEC。100G标准里无FEC模式使用4x25.78125Gbps启用RS-FEC则每条通道变成25.78125Gbps并附加额外开销。我在VV4上先关闭FEC跑通了再开。开FEC会引入额外的编解码延迟而且与光模块的对端必须协商一致否则链路根本起不来。4.3 约束文件编写的关键要点Achronix ACE的约束语法和Xilinx XDC有些差异但核心思想一致。我写约束时重点覆盖以下几类引脚位置约束把每个SerDes通道映射到对应的QSFP引脚电平标准高速信号一般由硬核自动配置普通IO需要根据板卡原理图设置电压域时钟约束给每个输入时钟和PLL输出时钟创建时钟域定义时钟周期时序约束对DMA数据通路、MAC数据通路加一些多周期路径或者约束避免时序不收敛这里有一件很重要的事SerDes的参考时钟必须做精确的时钟约束否则工具可能把不同时钟当成同一时钟域布局布线后出现严重的时序问题。我在做第一版时就是因为参考时钟没约束好导致编译后的比特流在板卡上完全不工作折腾了半天才发现是约束问题。另外建议把时序报告里worse path挨个看一下尤其是跨时钟域路径。Corundum的DMA引擎和MAC侧工作在不同时钟域跨域信号如果完全不做约束工具会默认按异步处理行为不可控。我在工程里显式声明了这些CDC路径并加上set_clock_groups -asynchronous让工具知道这是有意为之的异步设计。4.4 编译与资源占用观察当工程第一次能完整跑完综合实现时先别急着高兴看几个关键数据LUT/FF占用率如果整体超过70%后续加功能会很痛苦BRAM/URAM占用率队列数、描述符缓存直接吃存储资源DSP占用率Corundum本身DSP用得不多但如果你开了TSN、流量整形会有额外消耗时序收敛情况主要看100G侧的高频时钟路线我第一版全功能配置在AC7t1500上LUT用了不到30%BRAM不到40%整体很宽松。这也说明Corundum的代码优化得不错给后加功能留了很大空间。编译时建议先只编一个最简配置比如1个100G端口、4个队列、PCIe x4能把整套链路跑通后再慢慢加资源。不要一开始就开满所有特性否则遇到时序不收敛你会很难定位到底是哪里导致。下载到板卡后检查顺序是电源电压、时钟是否存在、PCIe是否被主机枚举、SerDes的TX/RX是否完成初始化、光模块link灯是否亮起。任何一步卡住都先回到约束文件和顶层例化去查不要急着改Corundum内部逻辑。5. 常见问题与排查技巧实录5.1 100G链路段落不工作先查对齐再查编码移植后最容易出现的现象是MAC层能配置但收不到对端任何数据包或者收到大量CRC错误帧。排查第一步看光模块和SerDes层状态。用串口打印或者ILA抓一下rx_block_lock、rx_align_done信号。如果rx_block_lock都不亮说明66B块同步根本没完成往下去查时钟和信号完整性。如果块同步正常但align_done不亮那就是4通道绑定有问题重点检查对齐标记的插入位置、通道顺序和极性。还有一个常见原因是对端设备开启了RS-FEC而本端没有或者两端的FEC模式不匹配。100G的FEC状态无法通过简单的link灯看出来必须读寄存器或者看PCS状态机。我在排查时直接把SerDes寄存器抓出来逐个确认是否是rsfec_en置位很快就能定位。如果这些都正常再看MAC侧的错误统计。Corundum的MAC模块里有统计寄存器能区分出CRC错误、长度错误、代码错误等这些信息对定位PCS层还是MAC层的问题特别有帮助。5.2 PCIe枚举缓慢或识别不到设备Achronix的PCIe硬核配置和Xilinx很不一样特别是复位时序。在VV4上如果PCIe硬核没有在系统上电后规定时间内完成初始化主机BIOS就会跳过它表现为lspci里根本看不到设备。我遇到的情况是单独用JTAG下载比特流后PCIe能识别但板卡冷启动时偶尔识别不到。排查后发现是PCIe硬核的复位信号依赖了板卡上电时序而FPGA逻辑里的复位释放太慢错过了BIOS枚举窗口。解决办法是把PCIe硬核的复位做成上电立即释放、不再等待用户逻辑复位让硬核尽快完成初始化。还有一个容易被忽略的点PCIe的参考时钟。如果100MHz参考时钟丢失或者抖动超标硬核链路培训会失败表现为设备轮询时断时续。用示波器看参考时钟是最直接的排查方式。5.3 DMA路径上数据错乱与复位顺序问题当链路层和PCIe都正常但DMA传输出来的数据错乱十有八九是跨时钟域没有处理好。Corundum的DMA引擎工作在PCIe时钟域MAC侧工作在网络时钟域两者之间通过异步FIFO或者同步握手来交互。如果直接复用了Xilinx平台的复位顺序而没有适配Achronix硬核的初始化时间很容易出现DMA引擎先开始搬运、但MAC侧数据通路尚未就绪的情况。表现为能收到包但每个包前面多了几个垃圾字节或者包顺序完全错乱。解决方式是重新梳理复位释放顺序PCIe硬核先就绪DMA引擎后启动最后才是MAC侧发送/接收通道使能。我在代码里加了一个简单的状态机用计数方式分批释放复位确保每个模块都在前级稳定之后再开始工作。加上这个之后DMA数据错乱的问题就彻底消失了。调试这类问题建议用Corundum自带的loopback测试。Corundum的寄存器空间里内置了回环开关可以配置成MAC内部回环、PHY回环、串行回环等模式。先用MAC内部回环验证DMA和数据通路再逐步向外扩展到PHY层这样可以把问题范围迅速缩小。5.4 常见问题速查表现象高频原因快速排查方法光模块link不亮SerDes未初始化、光模块管理引脚未约束检查tx_rx_up信号、确认I2C引脚约束收到大量CRC错误帧64B/66B对齐异常、FEC模式不匹配抓rx_align_done状态、核对两端FEC配置PCIe枚举不到PCIe硬核复位太慢、参考时钟异常示波器测100MHz、检查硬核复位释放时序DMA数据错乱跨时钟域未同步、复位顺序错误用MAC内部回环定位、分批释放复位编译时序不收敛参考时钟未约束、跨时钟域未声明检查时钟约束、声明异步时钟组6. 后续扩展计划与个人体会第一阶段移植到现在100G以太网链路已经跑通PCIe DMA也能正常收发数据。下一步我打算做几件事一是把两个QSFP-DD口都启用做成双端口100G网卡二是把Corundum的Linux驱动完整适配到当前内核版本在宿主机上做iperf性能测试三是尝试打开RS-FEC和TSN特性看看Speedster7t在这些功能上的表现。我个人实际操作下来的体会是Corundum移植到非Xilinx平台真正的难点不在逻辑设计而在于对板卡物理资源、时序复位细节的耐心打磨。很多问题都是“约束文件里少了一行”“复位信号晚放了几个周期”这类小问题但每个都会让你耗掉半天。建议准备一张纸质的信号映射表把每个模块的时钟、复位、数据接口都列出来调试时对着表看会省很多时间。最后分享一个小技巧在工程里保留一个简单的“裸机诊断模块”比如一个能直接向光模块发送固定伪随机序列的测试逻辑。这样当遇到链路问题你可以先跳过Corundum主体单独验证SerDes和光模块是否健康。跑通了这层再接入主体逻辑排查成本会大幅下降。这个习惯我后来在好几个移植项目里都用了确实很值。