写在前面这不是一篇“照着官方README装环境”的流水账。记录的是我最近一直啃的一件事把开源100G网卡方案Corundum从它默认支持的板卡上挪到Bittware VV4这块Arria 10板子上。整个移植目前只完成第一阶段但也正因为只走完第一阶段踩坑的细节都还热乎着趁记忆新鲜写下来给自己留档也希望能给后来人省点时间。先交代一下背景。Corundum是Alex Forencich维护的开源FPGA网卡实现纯Verilog核心是自研的PCIe DMA引擎加自研的以太网MAC支持10G/25G/40G/50G/100G速率。它的好处是整条数据通路都是开源的从MAC、PCS、DMA到PCIe队列管理每一层都能打开看、能改、能重新综合。这点在现在尤其难得因为厂商自带的100G网卡IP基本都是黑盒可定制性差许可证还卡得死死的。而Bittware VV4这块板子呢Intel Arria 10 GX 1150加双QSFP28板载PCIe Gen3 x8天生就是干这个的料。这篇文章是系列第一篇重点不放在代码细节上先把整体设计思路、板卡资源梳理、移植前准备和第一阶段踩到的坑讲清楚。后面几篇会分别展开DMA调通、收发器配置、驱动对接和性能测试。1. 为什么非要用Corundum而不是厂商IP工程里选择方案的第一件事就是搞清楚“为什么”。如果只是想把网络流量跑起来那直接用Intel官方的例程改改比移植Corundum省力得多。我选Corundum是因为它解决的是我正在面对的一个实际问题如何在FPGA上做一套可以按需修改的100G智能网卡。1.1 这套开源网卡到底解决了什么问题Corundum的完整数据面链路是这样的主机侧通过PCIe发起DMA描述符控制面用AXI-Lite寄存器组做配置数据面用AXI-Stream传输一直到以太网MAC、PCS最后到高速收发器。中间的所有模块都在rtl目录下自己清楚得很。它自带的东西包括高性能DMA引擎支持多队列每个队列独立描述符环形缓冲区完整的多队列调度和中断合并可以减轻主机CPU负载自研的10G/25G/40G/50G/100G以太网MAC不依赖厂商MAC IPPTP硬件时间戳、校验和卸载、RSS哈希等功能模块。这里有个关键的移植友好点Corundum把“厂商相关”和“厂商无关”的逻辑分得很开。厂商无关的比如MAC、调度、DMA这些是纯RTL放到哪个FPGA平台上都一样。厂商相关的主要集中在PCIe硬核接口、高速收发器、时钟和复位这几个地方。也就是说把一块板卡上的Corundum移植到另一块板卡核心工作不是改逻辑而是换“底座”。1.2 移植思路不是从零开始而是改板级最开始我差点走弯路想着从空工程开始一个个把模块例化出来连起来。后来看了Corundum源码里的fpga/board目录才明白官方早就把板卡相关的东西隔离了。每个板卡对应一个顶层模块上面例化该板卡的PCIe硬核、收发器、时钟芯片再往下接Core逻辑。当时的思路就变成了找到官方Arria 10参考板卡的顶层文件和约束文件对照Bittware VV4的原理图把顶层里板卡相关的部分全部换掉保持Core逻辑不动顶层的接口只做信号重映射和时钟复位适配先让PCIe能被系统枚举出来再让网卡驱动挂上再让100G链路up最后才测DMA收发。这个顺序非常重要。如果一开始就想着所有功能一起调出了错根本没法定位。移植的本质不是改逻辑而是做平台适配改顶层就像换插座里面的电路板还是一样。2. Bittware VV4的硬件底子方便后面讨论先把Bittware VV4的关键资源盘一遍。这块板子不是什么新型号但在原型验证里出镜率很高网上资料也不少。板卡核心是Intel Arria 10 GX 1150逻辑单元数量超过一百万DSP和BRAM资源也不小用于100G网卡数据通路绰绰有余。真正决定移植难度的是它周围的几组信号。2.1 Arria 10 GX 1150与PCIe Gen3 x8Arria 10 GX 1150集成PCIe Gen3硬核板卡金手指提供x8链路理论带宽接近64GbpsGen3 x8单向。这里面有一个容易被忽略的点PCIe硬核的参考时钟来自金手指的REFCLK通常是一对100MHz差分信号。PCIe硬核的复位是PERST#这个信号由主板拉低再拉高作为整个PCIe链路训练的开始条件。做移植时我在顶层里最关心的就是PCIe信号的命名和方向。Bittware VV4的原理图里PCIe差分对、PERST#、CLKREQ#这些信号名字和官方参考板卡不一定一致。这些必须一个一个对照修改错一个脚PCIe枚举就会失败。2.2 双QSFP28与100G光模块链路板载两只QSFP28 cage这是最吸引我的地方。每只QSFP28提供4个高速收发器通道在Arria 10 GX上可以配置成4x25.78125Gbps正好组成一条100G以太网链路。也可以用分支线缆跑4x25G这点后面调PCS时再细说。QSFP28的问题在于它不只是高速线还有一个管理接口。QSFP28的热插拔检测、模块存在检测ModPrsL、复位ResetL、低功耗模式LPMode、I2C接口都需要FPGA这边有对应的GPIO和I2C控制器去操作。移植时最容易漏的就是这些低速管理信号漏了一个光模块就起不来。2.3 时钟和复位的特殊之处时钟是这次移植里最费心思的地方。VV4板上的时钟源和官方参考板完全不同。100G以太网MAC需要156.25MHz时钟收发器需要对应速率的参考时钟PCIe又需要100MHz参考时钟DDR、QDR等存储器又各自有独立时钟。这些时钟的频率、相位、极性甚至上电顺序都会直接影响功能是否正常。德州仪器SI5338这类可编程时钟芯片在VV4这类板卡上很常见它靠I2C配置默认配置不一定是100G以太网需要的频率。上电之后必须先把时钟芯片写好再释放FPGA内部复位否则后面的模块拿到一个错误频率的时钟调试过程会非常痛苦。2.4 板载资源映射列表整理一张表方便后面写代码时对照功能点VV4板卡资源Corundum中对应的接口PCIe金手指Gen3 x8100MHz REFCLKPERST#pcie_*端口组100G光口QSFP28 cage4x25.78G收发器mii_*接口到100G MAC光模块管理I2C、ModPrsL、ResetL、LPModeqsfp_*寄存器接口时钟可编程时钟芯片默认配置clk_*输入输出复位板上全局复位、PCIe PERSTrst_n输入调试JTAG、UART、LED、按键fpga顶层调试端口这里列出来的每一项都会在顶层设计里变成一组具体的端口或寄存器所以这张表就是我后面写RTL时的对照清单。3. 移植前准备环境、源码与架构梳理很多移植项目死在“还没开始写代码就乱套了”这点上。环境不一致、源码版本不对、板卡参考设计没下载最后编译报错都分不清是环境问题还是代码问题。所以我把准备阶段当成正事做而不是随便装个软件就开干。3.1 工具链选择与IP许可Corundum官方仓库里带有Altera平台的参考设计但用的Quartus版本可能和当前习惯版本不一样。我的建议是尽量贴近官方参考设计当初维护的Quartus版本或者至少保证工程升级时IP核能被正确迁移。Arria 10器件在Quartus Prime Pro和Standard里都有支持但工程格式不一样。我当时在Pro和Standard之间犹豫了一下最后选了Pro理由是Arria 10硬核IP在Pro里维护得更勤。许可证这块一定要提前确认好。Arria 10 GX 1150的器件支持有时候不在免费Lite许可证范围内需要设备锁定许可证。这个如果没准备好跑综合到一半才报license错误才是真的浪费时间。3.2 解读Corundum的源码结构Corundum的rtl目录按功能分得很清楚rtl/core是DMA、队列、调度等核心逻辑rtl/eth是以太网MAC、PCS相关rtl/pcie是PCIe相关适配rtl/misc是各种辅助模块。这个目录结构是移植者最好的朋友因为你能一眼看出哪些文件是纯逻辑、哪些文件是平台相关。我花了不少时间读rtl/pcie里的A10相关代码。理由很简单Arria 10的PCIe硬核接口和Xilinx的差别很大AXI/ Avalon接口类型、时钟域、复位控制都不一样。Corundum在Altera平台上使用Avalon-ST接口与PCIe硬核交互这需要理解IP核生成的接口签名才能把信号对接到官方核心逻辑上。3.3 找到官方参考设计并做差异对比Corundum仓库fpga目录里按厂商和板卡分了多个子目录。拿官方Arria 10板卡工程和VV4板卡对比差异集中在几块引脚分配参考设计的引脚名肯定对不上时钟/复位连接方式参考设计里的时钟芯片型号不同初始化和约束方式也不同PCIe硬核IP配置参考设计可能是x4或x8要按VV4实际改成x8收发器配置参考设计可能面向某个特定的QSFP cage引脚序。这块对比越细后面写顶层的时候就越顺。3.4 如何定义第一阶段的验收标准移植这种工作没有验收标准就不知道自己做到哪一步了。我给第一阶段的定义是四步Quartus工程编译通过时序收敛能正常生成bitstream板卡上电后主机通过lspci能看到FPGA网卡设备加载Corundum的Linux驱动后系统能识别出一个以太网接口把100G光模块连接好接口状态从DOWN变UP。这四步是不折不扣的“基础目标”。在没做到这些之前我不碰任何性能调优。事实证明这四步本身也不简单光第一阶段的调试就花了我好些个完整晚上。4. 核心适配工作这一章是移植的主体也是最容易出问题的部分。我按硬件数据流的方向来组织先说顶层怎么写然后说时钟和复位再说PCIe和DMA对接然后是QSFP28和100G MAC最后是约束和时序。4.1 写板卡顶层Corundum的板卡顶层本质上就是一个“把所有资源串联起来的壳”。我按VV4原理图重写顶层模块时端口列表大概是这样的module vv4_corundum ( // PCIe input wire pcie_refclk_p, input wire pcie_refclk_n, input wire pcie_perst_n, input wire [7:0] pcie_rx_p, input wire [7:0] pcie_rx_n, output wire [7:0] pcie_tx_p, output wire [7:0] pcie_tx_n, // QSFP28 0 input wire [3:0] qsfp0_rx_p, input wire [3:0] qsfp0_rx_n, output wire [3:0] qsfp0_tx_p, output wire [3:0] qsfp0_tx_n, input wire qsfp0_modprst_l, output wire qsfp0_reset_l, output wire qsfp0_lpmode, // QSFP28 1 // ... // 时钟和复位 input wire clk_sma, // 调试 input wire uart_rx, output wire uart_tx );顶层里面做什么首先是把PCIe硬核IP例化出来把Avalon-ST转换成Corundum需要的接口然后例化收发器把高速串行信号分别接到两个QSFP28 cage再把时钟芯片产生的各频点时钟连接到MAC和DMA逻辑最后把GPIO连接到光模块管理信号。这一层看起来没什么技术含量但它决定了整个工程能否编译通过。我犯过一个低级错误某个端口方向写反了结果Quartus编译时报告了一大堆连接错误排错花了半小时。后面学乖了写顶层之前先把VV4的原理图放大到能看清每个引脚方向甚至打印出来放桌上对照。4.2 时钟芯片的配置时钟是Arria 10板卡上最容易踩的坑。VV4板上那颗SI5338我一开始以为默认配置就能用。结果无论如何PCIe硬核始终训练不起来用Signal Tap抓参考时钟发现频率完全不对。这才意识到时钟芯片必须由FPGA在上电后主动通过I2C配置。解决办法是在顶层里放一个I2C主机模块上电后立刻执行一组配置序列把SI5338输出频率切成需要的值例如给收发器的156.25MHz和给PCIe硬核的核心时钟。这个序列并不是随便写的要仔细看SI5338的数据手册和VV4的原理图确认每个输出端口对应的频率、电压和使能位。还有一个容易被忽略的细节时钟芯片配置完成后后续模块的复位释放必须滞后足够时间。如果复位的释放时序在时钟稳定之前哪怕只早了几十微秒硬核同样会初始化失败。4.3 PCIe硬核与DMA对接Arria 10的PCIe硬核和Xilinx的XDMA完全是两回事。Corundum在Arria 10上的做法是包了一层适配模块把PCIe硬核的Avalon-ST接口转换成内部的AXI接口然后再接DMA引擎。我在前几次编译时PCIe硬核的配置一直不对。重点是核对几项参数链路速率Gen3链路宽度x8参考时钟频率100MHz接口类型Avalon-ST还是Avalon-MM要和Corundum顶层匹配BAR配置至少需要两个BAR一个给控制寄存器一个给DMA描述符和状态映射。这里面最麻烦的是Avalon-ST的控制信号含义和AXI不太一样比如ready、valid的时序。如果只对着官方参考板卡的PCIe模块抄很容易在时钟域转换上出问题。调试时我用了一个最简单的办法先把PCIe硬核单独拉出来通过JTAG访问BAR空间的寄存器能读能写后再接到Corundum核心逻辑上。4.4 QSFP28收发器与100G MAC100G以太网这部分的移植逻辑比较直接Corundum自带100G MAC和PCS但它不包含高速收发器。收发器需要由板卡提供然后通过类似MII/XLGMII的接口与MAC连接。在Arria 10上这意味着要例化Native PHY IP或者Ethernet IP把4个高速通道配置成25.78125Gbps并打开正确的收发器PLL和时钟恢复。QSFP28 cage上的4对差分信号直接接收发器但参考时钟和回环测试模式要额外处理。我第一次上电之后光模块的RX完全没有信号。后来用Signal Tap看收发器状态寄存器发现RX不是没有信号而是CDR没锁定。原因是我把收发器参考时钟引到了错误的时钟引脚。这种问题特别容易出因为板上时钟分布很密集引脚名字看起来都差不多必须要对照原理图逐个引脚核实。MAC和PCS的接口还有一个容易忽略的点Corundum的MAC内部有独立的TX/RX时钟域两侧异步FIFO是必需的。如果在顶层里直接跨时钟域连线时序报告会显示晚期违规而且运行时会出现随机丢包。4.5 约束与关键时序QSF文件是Altera系工程的灵魂。引脚分配、I/O标准、电流强度、差分对的命名全都在这里控制。Arria 10的IO标准要特别注意不能只看原理图上的网络名还要看供电电压对应的IO标准。比如PCIe差分信号是PCIe标准QSFP高速线是LVDS或PCML类。除了引脚分配还要定义时钟约束。我在SDC文件里需要定义PCIe参考时钟100MHz约束收发器参考时钟156.25MHz约束所有异步复位的伪路径设置跨时钟域路径的时序例外防止Quartus在客观上不需要收敛的路径上浪费努力。时序收敛这件事在Arria 10上比在Xilinx上更敏感。我第一次编译时WNS是负数大概有几十条违规路径分布在PCIe用户时钟域到MAC时钟域的跨域逻辑上。后来加了几级同步器又调整了约束中的分组才把时序压到正数。这个阶段不要着急编译一次要半个多小时每次只改一点才能积累有效的操作经验。5. 板级调试与问题排查实录这部分是这篇博文里我最想写的因为踩坑的教训比成功经验值钱。我把第一阶段遇到的主要问题列出来按现象、定位、解决三步走记下来。5.1 PCIe枚举不到设备现象板卡上电FPGA加载完成后主机系统里lspci找不到任何新设备。排查顺序先用万用表确认金手指上PERST#信号是不是正常拉高再确认REFCLK是否进入FPGA的专用时钟引脚然后确认FPGA里PCIe硬核有没有正确复位。这三点如果都正常再看是不是PCIe IP的配置和实际链路宽度不一致。我遇到的问题是PERST#极性处理错了。主板在系统启动时会把PERST#拉低再拉高但这个信号在板级上又被反了一次顶层里又一反最后硬核收到的复位一直是有效电平。解决方法是直接在顶层把极性对齐不要依赖IP核内部的默认设置。5.2 QSFP28读不到光模块信息现象系统能识别网卡但使用ethtool或i2c工具读光模块的DDM信息时返回全零或读不到。原因基本是管理信号的问题。光模块的ModPrsL、ResetL、LPMode引脚逻辑没有配对。比如光模块的I2C地址需要用ModSelL选择而很多QSFP28模块的ModSelL是低有效如果顶层里接反了I2C总线上的地址永远对不上。排查时我直接用I2C总线扫描工具把模块所有地址都扫一遍看看有没有ACK。如果完全没有说明管理信号或者I2C上拉电阻出了问题。这里补充一个经验上电后一定先给ResetL一个完整的低脉冲再释放不然部分光模块会一直处于复位状态。5.3 链路建立了但没有流量现象网络接口UP了但ping不通或者干脆没有任何收发包计数。先看MAC层状态。用Signal Tap抓MAC的PCS状态信号确认RX的CDR锁定了没有PCS是否进入正常状态。再看是否开了流控或自动协商100G通常不依赖自动协商某些调试模式反而会卡住链路。我遇到的情况是TX方向正常RX方向数据到了PCS之后校验和错。查下来是收发器的RX极性接反了。Arria 10的收发器可以动态配置极性翻转但默认情况下必须保证物理连接正确。如果原理图上RX正负和FPGA引脚定义是反的就需要在IP核里打开极性翻转选项而不是去改PCB。5.4 DMA数据不通问题现象驱动加载成功接口也UP但是用工具做收发测试时DMA描述符状态一直pending没有完成中断。这个问题的排查相对复杂我还在进行中。目前定位到的方向是BAR地址映射、描述符基地址寄存器与驱动默认值的匹配关系、以及DMA引擎的时钟域与PCIe用户时钟域之间的同步问题。这里要特别提一个排查思路先不要碰复杂的数据收发路径先把控制寄存器通路打通。比如通过devmem直接读写BAR空间里的寄存器看能否正确读到FPGA的版本号和状态。如果控制层面通了数据面还是不通那问题就一定出在DMA引擎本身或驱动对应的队列初始化上。6. 当前进展与后续安排到目前为止第一阶段里我能确认跑通的是Quartus工程编译通过PCIe链路能被主机识别Linux驱动能加载出网卡接口100G光模块能读到DDM信息接口链路能够建立并保持在UP状态。数据面DMA收发还在继续调这条线比较绕涉及驱动、DMA描述符和时钟域三方面预计会在第二篇里详细展开。这里说一个实际体会移植Corundum到VV4这么大的工作量最怕的不是逻辑复杂而是板级信息对不上。原理图、引脚约束、时钟芯片默认配置、光模块的I2C地址任何一个和顶层里的假设不一致都会表现为极其诡异的“软故障”——编译没错上电就挂。我的做法是打印一张板级信息清单把VV4原理图上所有相关信号整理成表格再对照Corundum官方参考工程的顶层信号整理成第二张表然后一张一张做映射。这个工作很枯燥但绝对正确。后面做DMA调试时如果出现难以定位的问题我大概率还是会回到这两张表上找答案。下一篇我会重点写Corundum DMA引擎在Arria 10上的具体对接、Linux驱动的加载细节以及我在数据面通路上遇到的问题。如果手里有类似板卡也想这么干的朋友欢迎在评论里交换一下信息排错这种事一个人闷头搞太慢了。