100G FPGA UDP协议栈移植实战：从GTY上板到吞吐调优全记录

这块板子在我桌上吃灰了快半年终于趁着手头项目要上一套高速采集链路把它拎出来当网络转发节点用。项目名很直白开源100G FPGA UDP协议栈移植并上板跑通。折腾了大概两周中间踩了不少坑有些问题翻遍GitHub issue和Xilinx论坛才找到答案所以把这回完整的过程整理出来给后面做100G UDP方向的兄弟一个参考。这篇东西适合两类人看一类是刚入门FPGA、对高速以太网还停留在“听说过100G”阶段的同学可以借此理解一套完整UDP数据通路在硬件上是怎么一层层搭起来的另一类是已经写过不少RTL、但没在真实板子上用光模块跑过100G流量的工程师这里面关于时钟、端序、流控和排障的细节应该能帮你省下几个通宵。先交代一下我的硬件环境主控FPGA是Xilinx UltraScale系列的VU3P板卡自带QSFP28光口配了Finisar 100G SR4光模块。软件环境是Vivado 2023.1。协议栈用的是GitHub上star数很高的开源项目verilog-ethernet作者Alex Forencich它支持从1G到100G的完整UDP/IP/MAC栈代码风格干净文档也算齐全是我目前见过最适合做二次开发的以太网开源RTL。1. 项目背景与方案选型1.1 为什么在FPGA上做100G UDP而不是用CPU或者网卡先说一个很多人都会问的问题100G的UDP收发随便找一张带RDMA的网卡不就行了吗为什么要费劲在FPGA里自己做一套协议栈原因其实集中在两点。第一是吞吐需求背后的时延问题。FPGA里做UDP转发从光口收进来到MAC解析出包头再到用户逻辑决定往哪个方向发整个过程是纯硬件流水线时延是固定的、纳秒级可算的。而CPU哪怕用DPDK在100G线速下也要面对PCIe中断、缓存miss、多核调度这些开销时延抖动很难压下去。第二是定制化能力。FPGA上的UDP栈说白了是一段可以随便改的RTL你可以把包头解析和用户业务逻辑放在同一个时钟域里流水处理比如收包的同时直接做特征提取、流量整形、加密甚至把UDP payload往DDR里搬的同时就开始做图像预处理。这些在网络卸卡场景里是做不到的。所以FPGA做100G UDP本质上是把那层网络协议处理变成你整个数据通路里可控的一环而不是一个绕不开的瓶颈。1.2 用现成开源协议栈还是自己写UDP栈自己写一个能用的UDP栈在10G以下还能接受到了100G事情就没那么简单了。100G以太网物理层是4路25G lane并行传输涉及64B/66B编码、多通道分发MLD、RS-FEC这些处理光是把PCS层调通就要掉一层皮。更别提MAC层还涉及前导码处理、CRC32校验、帧间隙控制任何一个细节出错线上对面设备就会一直报错。所以这轮我毫不犹豫选择用开源方案。Alex Forencich那套verilog-ethernet之所以好用主要有几个原因代码用标准AXI4-Stream接口所有模块之间是一根根TDATA、TVALID、TREADY信号连起来跟Xilinx自家IP的风格一致调试起来很顺手。支持完整的MACPCS你只要在外面把高速收发器GTY的并行数据接口连到他的模块上后面IP、UDP、ARP、checksum都替你写好了。工程结构透明不是打包成黑盒IP核所有RTL摊开给你看出问题可以直接改源码。有配套的example工程脚本虽然不是直接对应我的板卡但拿来做移植起点足够。对比下来自研协议栈在这个项目里没有任何优势。如果你是为了学习拆他的代码源码完全够你研究几个月如果是产品化基于这个改也比从零写省太多时间。1.3 硬件平台与整体数据通路设计开始移植之前先把整个方案在脑子里过了一遍。我的目标很明确FPGA从QSFP28光口收100G UDP数据经协议栈解出IP/UDP头把payload送入用户逻辑用户逻辑把收到的数据原样打包再通过协议栈发出去。相当于做一个双向透传统计节点。整体数据通路是这样的光模块接收光信号由GTY收发器转成并行数据4个lane每个lane 66bit进入MAC核完成64B/66B解码和帧同步。MAC核去掉前导码和FCS后把完整以太网帧送到IP层接收模块这里会做IP首部校验确认是发给本机的帧。IP模块解出上层协议号把UDP报文交给UDP接收模块UDP模块剥掉UDP头把payload和数据长度、源端口、目的端口一起打包成AXI-Stream格式送去用户逻辑。发送方向完全对称用户逻辑往UDP发送模块丢数据发送模块自动算好UDP长度、IP首部校验和、MAC地址再往下发给MAC发送通路最终由GTY串行发送。为了让板卡在跑100G的时候不丢数用户逻辑两端各挂了一个深度较大的AXI FIFO做缓冲。100G线速下一个周期就是好几个字节FIFO几乎是最低成本的防毛刺方案。2. 100G UDP数据通路核心拆解2.1 100G以太网的物理层与链路层特点在移植代码之前有必要把100G以太网和它低速版本的区别理清楚否则很多代码逻辑你会看不懂。100G以太网在物理层上不是一根线跑100G而是通过4个25.78125Gbps的串行通道并行的。所以它引入了一个叫“多通道分发”的机制也就是发送端把数据流切分到4个通道接收端再把这4个通道的数据重新拼起来。这意味着MAC层给出的数据宽度比1G/10G时代大了很多。VU3P上的GTY收发器每个lane的并行数据宽度是66bit4个lane合在一起就是264bit而MAC内部的核心数据总线一般是512bit跑在322.265625MHz。再说编码。100G用的是64B/66B编码编码开销约3.125%。所以大家常说的100G实际上链路速率是4×25.78125Gbps 103.125Gbps多出来的3.125Gbps就是编码开销。如果开了RS-FECRS(528,514)开销会更大但能换来更好的纠错能力。理解了这一层你就知道为什么移植时最难的不是RTL本身而是时序和接口对齐。2.2 开源协议栈的模块划分与AXI接口约定verilog-ethernet这套代码里跟我们这个项目相关的核心模块有这么几个模块名作用说明eth_mac_100g100G MAC核包含64B/66B编解码、MLD、帧定界、CRCeth_axis_rx / eth_axis_tx以太网帧与AXI-Stream转换负责去掉/加上前导码、FCS等eth_udp_tx / eth_udp_rxUDP发送/接收处理UDP头、IP头、checksumeth_arpARP应答方便主机找到FPGA的MAC和IPaxis_fifoAXI-Stream FIFO跨时钟域缓冲防止突发数据打爆这套框架最舒服的一点是MAC层之上的所有模块都遵循同一套AXI-Stream的TDATA/TVALID/TREADY握手协议。TDATA的位宽在100G下是512bit也就是说一个时钟节拍最多能传512bit 64字节数据。TUSER信号里打包了包起始、包结束、字节使能这些信息剥包组包都靠它。2.3 关键信号与时序tkeep、tuser、字节序提到AXI-Stream我在调试过程中发现很多坑都出在两个信号上一个tkeep一个tuser。tkeep的作用是标注当前节拍里哪些字节是有效的。比如包尾那拍可能只剩3个字节有效那tkeep的低3位为1其余为0。如果tkeep没接对MAC层组帧时会把无效字节也塞进去对方网卡收到后CRC校验必挂。tuser在verilog-ethernet里用来标包边界。一般约定tuser是1的时候表示这一拍的数据是一个包的开始。在总线位宽很大比如512bit的时候一个包可能横跨好几个时钟周期tuser还能配合tkeep区分包尾的字节计数。字节序这块更是重灾区。Xilinx的GTY接口和AXI总线的字节序定义方向是反的如果直接把MAC输出的512bit接到模块输入上基本会出现整个帧内容“倒着读”的情况表现出来就是wireshark里能看到包但是MAC地址和IP地址完全反了CRC永远不对。这个问题后面会在调试章节详细说。3. 从GitHub到Vivado移植实操全过程3.1 代码获取与版本核对第一步把代码仓库拉下来git clone https://github.com/alexforencich/verilog-ethernet.git拉完代码之后别急着开Vivado先把目录结构看一遍。重点看两个地方一个是rtl目录下的源码清单确认你需要的UDP相关模块都在另一个是example目录下的脚本里面包含作者验证过的FPGA工程配置比如VU3P、VCU118这些UltraScale板卡的tcl脚本能帮你快速理解约束文件的写法。这里有个我要特别提醒的点一定要确认你拉的版本和你目标Vivado版本是否兼容。verilog-ethernet更新频率不低而Vivado在不同版本里对GTY原语的例化方式是有差异的。我最初在master分支上遇到过综合报错后来改用release分支才稳下来。建议直接checkout最新的release tag。git checkout v1.6.0另外这个项目的RTL大量使用include文件来定义参数和宏工程里必须把rtl/include目录加进include路径否则综合会报一堆找不到文件。3.2 开源工程里GTY收发器的额外配置verilog-ethernet拿到的默认代码MAC层和IP/UDP层是齐的但是GTY高速收发器的配置部分作者没有给你封装成完整的黑盒IP而是提供一个接口要求你自己完成底层。原因很简单不同板卡用的GTY参考时钟频率、QSFP28引脚分配、Bank位置不同这部分必然是跟板卡强相关的。我在example/scripts里找到适配xcvu3p的tcl工程脚本这里面就已经写好了MGTMulti-Gigabit Transceiver相关的原语例化模板。如果你的板卡也是UltraScale可以直接在这个基础上改引脚约束。需要注意的是100G Base-R模式下GTY的参考时钟通常要求156.25MHz4个lane共用一个QPLL输出。这个频率不能错错了QPLL根本锁不上光口link起不来。3.3 参数配置与顶层模块例化接下来是重头戏把我们自己的顶层模块里把MAC、UDP TX/RX、FIFO按数据流方向例化起来。以下是一个简化但足够说明问题的示例我把不相关的信号都省掉了// 顶层模块内部的核心例化示意 eth_mac_100g #( .TX_USE_CLK90(1b0) ) u_mac_100g ( .tx_clk (gt_txusrclk2), .rx_clk (gt_rxusrclk2), .tx_axis_tdata (mac_tx_tdata), .tx_axis_tvalid (mac_tx_tvalid), .tx_axis_tready (mac_tx_tready), .tx_axis_tuser (mac_tx_tuser), .rx_axis_tdata (mac_rx_tdata), .rx_axis_tvalid (mac_rx_tvalid), .rx_axis_tuser (mac_rx_tuser), .gt_txdata (gt_txdata), // 连接GTY并行发送数据 .gt_rxdata (gt_rxdata) // 连接GTY并行接收数据 ); eth_udp_rx #( .CHECK_CHECKSUM(1b1) ) u_udp_rx ( .clk (mac_rx_clk), .rst (rst), .s_axis_tdata (mac_rx_tdata), .s_axis_tvalid (mac_rx_tvalid), .s_axis_tuser (mac_rx_tuser), .m_axis_tdata (udp_rx_payload), .m_axis_tvalid (udp_rx_valid), .m_axis_tlast (udp_rx_last), .m_axis_tkeep (udp_rx_keep), .src_ip (udp_rx_src_ip), .src_port (udp_rx_src_port), .dst_port (udp_rx_dst_port) );这里有个很关键的点MAC的tx_user和rx_user信号含义不完全一样。在发送方向tuser为1代表这一拍是包起始在接收方向tuser也会带着错误标志位。所以接tuser的时候不要想当然要对着源码里的注释看一遍。3.4 约束文件编写和时序收敛100G工程和普通低速工程最大的不同就是时序约束。芯片内部总线跑在322MHz左右依位宽而定而且GTY的并行接口信号有很高的时序要求任何一条路径slack为负都可能导致上板后随机出错。约束文件里至少要有这几项QSFP28引脚锁定也就是GTY的RXP/RXN、TXP/TXN引脚位置必须和你板卡原理图一一对应。GTY参考时钟引脚锁定包括复位和使能信号。异步时钟域约束MAC出来的用户时钟txusrclk2/rxusrclk2和用户逻辑时钟往往不同步要正确设置ASYNCC_REG或者使用FIFO隔离。create_clock约束所有输入时钟避免Vivado盲猜时钟频率导致时序分析失真。我第一版约束文件图省事只写了引脚锁定结果综合后时序一塌糊涂。后来老老实实照着example里的XDC改时序马上干净了。工程跑在322.265625MHz布线后建立时间slack还有0.3ns左右对100G设计来说算是余量充足。3.5 综合、布线与上板前检查时序收敛以后别急着上板。把综合报告里的资源占用和时钟频率确认一遍VU3P的GTY够用、LUT用量没爆、BRAM余量充足再往下走。上板前的最后一件事是确认ILA集成逻辑分析仪调试核已经挂在关键总线上。我一般习惯挂三个观测点MAC接收出来的AXI流、UDP模块剥完头之后的payload流、以及用户逻辑转发出去的AXI流。ILA的采样深度不用太大1024就够了主要用来抓协议握手是否正常。4. 上板调试从灯亮到打满100G4.1 先看link再谈数据上板第一步不是灌数据而是确认物理链路起来了。QSFP28光模块上有几个状态位GTY里的QPLL锁定、复位完成、信号丢失RX LOS这些信号可以用VIO核读出来。我第一次上电的时候QPLL一直锁不上查了半天发现是参考时钟引脚约束错了156.25MHz的时钟根本没有进到这个Bank。修改约束、重新布线之后QPLL稳定锁定光模块的link灯也亮了。很多新手在这一步容易急光模块link灯不亮就疯狂查逻辑。其实link问题八成出在物理层配置跟上面的UDP栈一点关系都没有。先把GTY的相关状态寄存器全读一遍确认无误再往上查。4.2 用ILA抓包验证数据通路Link起来之后先在FPGA内部做一次回环验证也就是通过ILA观察MAC层输出的数据是不是一个结构正确的以太网帧。这里说一个我自己用得非常顺手的验证方法先用FPGA内部逻辑伪造一个UDP包发给MAC发送模块然后在MAC接收侧接一根线直接环到MAC发送侧用ILA抓接收方向的数据。如果ILA里能看到完整的帧结构目的MAC、源MAC、以太网类型0x0800、IP头、UDP头、payload、FCS说明MAC层组帧没问题。第一次在这步就翻车了ILA里看到的数据完全乱了帧头跑到帧尾后来发现是GTY并行数据到MAC输入之间的bit映射顺序错了。Xilinx的GTY把串行数据转成并行后byte的排列顺序是从低位开始的而MAC核期望的是从左到右的正序中间需要做一次bit reverse。4.3 端序和CRC问题的排查字节序问题是整个项目里最消耗耐心的一环。wireshark显示收到了UDP包但解析出来源IP是0x0100007F这种倒序数字CRC校验全是bad这种症状几乎就是端序反了。以我的板子为例GTY从光模块收到的并行数据lane 0在最前面还是最后面跟MAC核里对lane序的定义不一定一致。alexforencich的代码里有一个参数叫LANE_ENDIANNESS专门用来处理不同板卡的lane顺序差异。把它从0改成1之后MAC地址和IP地址就完全正常了。类似的还有一个BYTE_ENDIANNESS参数。如果你做完lane翻转后还是不对就把这个参数也翻一下。这两个参数组合起来有四种情况可以用排除法一个个试配合ILA观察基本五分钟内定位。4.4 主机侧工具链验证UDP收发链路通了之后接下来就是在主机侧验证完整闭环。我用的是Linux主机插了一张100G网卡直连FPGA的QSFP28口。先给FPGA配一个固定的IP地址比如192.168.50.2主机网卡配192.168.50.1然后从主机ping FPGA。如果ping通了说明ARP和ICMP处理没问题IP层已经工作正常。ping通之后再做UDP验证。这里就要用到我最常用的工具iperf3和sockperf。iperf3用来压吞吐sockperf用来测时延和特定包大小的传输。先跑一个最简单的UDP回环测试# 主机侧发包给FPGAFPGA收到后原样打回 sockperf pp -i 192.168.50.2 --udp -m 1024 -t 10如果sockperf能正常收到回包说明FPGA的UDP RX和UDP TX两条通路都已经通了可以进入带宽测试阶段。4.5 iperf3打流与100G吞吐量实测结果接下来是所有人最关心的环节到底能不能跑满100G。iperf3 -u -c 192.168.50.2 -b 100G -l 1472 -t 30注意参数里-l 1472这是1500MTU下UDP能承载的最大payload大小。为什么要用大包测因为吞吐测试里包越大包头开销占比越小越接近线速极限。小包测试是另一回事那个考验的是包处理速率后面专门说。实测下来TCP以外的UDP大包吞吐稳定在93.5Gbps左右线速的93.5%CPU占用很低。之所以没到100G主要是以太网帧间隔、前导码、CRC这些开销必然存在。按1500B帧长算理论极限就是95%左右93.5G和理论值基本吻合。然后我也测了一下极端情况64字节小包。这个数字就相当残酷了吞吐直线掉到25Gbps左右这不是协议栈不行而是100G线速下64B小包的包速率高达1.48亿包每秒任何系统在软件层处理这个速率都会崩。FPGA如果只做转发也许能扛但一旦涉及用户逻辑查表、统计、搬运DDR就会成为瓶颈。4.6 从光模块回环到双机对传的进阶验证如果你想确认不是FPGA自说自话还有一个更严谨的验证方案两边都用真实网卡对传也就是主机A → FPGA → 主机B。FPGA在这里做纯转发不修改任何字段。我在这个测试里遇到了一个有趣的现象主机A发过来的包FPGA转发到主机B后wireshark里能看到包但checksum是错的。排查后发现是我顶层模块里把rx侧M_AYIS_TUSER带过来的错误标志位又原样传给了tx侧MAC层检查到错误标志就不重新计算CRC。把tuser清掉之后问题消失。这类“标志位污染”问题在二次开发时非常常见值得留意。5. 常见问题与排查技巧实录5.1 时钟与复位类问题上板后最容易出现的几个故障我整理成了一张表后面的人遇到了可以直接对照排查。现象可能原因排查方法QPLL锁不上link灯不亮参考时钟引脚错/频率不对用VIO读GTY状态检查156.25MHz时钟是否稳定上板后全部数据CRC错字节序或lane顺序不对调MAC的BYTE_ENDIANNESS和LANE_ENDIANNESS参数偶尔丢包但吞吐不高跨时钟域没处理好检查FIFO是否用异步时钟复位释放是否同步系统复位后第一包总丢复位释放时序问题确认复位信号同步释放MAC内部要求复位拉高至少几个时钟周期数据偶发错位、串包tuser或tkeep处理不当ILA抓边界重点看包尾那拍的tkeep是否符合预期5.2 tuser标志位的“元凶”现场我这次最深的坑出在一个看起来人畜无害的tuser上。verilog-ethernet的UDP RX模块在输出payload时m_axis_tuser有时会携带错误标记。我在用户逻辑里把这个tuser原样接到了UDP TX模块的s_axis_tuser上。结果就是MAC发送模块看到tuser里的错误位认为这个包有问题不重新做FCS计算。最要命的是这种错误不是每次必现而是偶发——因为不是每个包都带错误标志只有个别从线上抓到有问题的包才会触发。这种偶发问题最浪费时间我一度怀疑是代码时序问题最后用ILA加了很复杂的触发条件才抓到现场。处理很简单转发逻辑里把tuser强制清掉只保留tvalid和tlast。但这个问题很典型开源代码的接口语义和你直觉理解的不一样所以接任何一根线之前都建议先读一遍对应的源码注释。5.3 接收端FIFO溢出与丢包分析100G UDP还有一个绕不开的话题丢包。UDP没有流控发送端想发多少发多少接收端处理不过来只能硬丢。FPGA里的用户逻辑如果处理一个包需要可变周期峰值来临时FIFO就会溢出。我在设计里做了三件事来缓解用户逻辑入口挂了深度为64K的AXI FIFO扛住短时突发。给每个包打上序号丢包可以精确定位丢的是第几个包。在统计寄存器里记录FIFO溢出次数通过UART或AXI-Lite读出来方便长时间跑测试时判断稳定性。调试时最容易忽略的是主机端app如果用默认socket缓冲区也可能在软件层丢包造成你误判FPGA丢包。所以我测试时用setsockopt把收发缓冲区调大了很多int rcvbuf_size 512 * 1024 * 1024; setsockopt(fd, SOL_SOCKET, SO_RCVBUF, rcvbuf_size, sizeof(rcvbuf_size));另外还有一个小技巧打流时加--udp-counters-64bit避免iperf3的32位计数器在大流量下算出负数。5.4 带宽上不去的几个原因如果你的吞吐测试结果离理论值差很远按下面顺序排查通常能命中90%的根因先确认MTU。主机网卡MTU是不是1500如果是默认1500但FPGA侧不支持jumbo frame会导致大包被分片或丢弃。我一般直接把两端MTU都设置在9000减少包数量吞吐更容易拉上去。再看PCIe和内存带宽。如果数据还需要经过DDR或者PCIe搬到上位机瓶颈往往不在FPGA协议栈而在搬运链路。100G单向就是12.5GB/sPCIe Gen3 x16的理论带宽也就这个数实际打八折。想靠PCIe满速收100G数据几乎不可能。检查是否有CPU中断瓶颈。即便用DPDK单核处理小包的PPS上限也就几Mpps对100G线速来说远远不够。最后确认FPGA内部有没有在某个环节用了共享总线。比如所有流量都过一个单口RAM做查表带宽就会卡在那里。5.5 长稳测试与光模块散热性能验证通过不算完项目要交付还得跑长稳。我连续跑了72小时固定用iperf3压90Gbps左右流量同时观察FPGA温度、光模块温度、丢包计数、CRC错误计数。这里有个硬件层面的坑100G光模块发热非常可观如果散热片没贴好或风道不畅模块温度超过85度后会直接降速或者断链。我第一次长稳测试就是跑到第10个小时左右出现偶发丢包查了一圈发现是光模块温度飙到88度触发告警。加了主动散热之后问题彻底消失。所以如果你也在高密度板上跑100G别只盯着逻辑温度这一项在长稳测试中真的能让你一夜回到解放前。最后再分享一个小技巧整个项目收了尾我发现一个对后续调试特别有帮助的习惯在用户逻辑里放一组简单的统计计数器包括收包总数、发包总数、CRC错误数、IP校验失败数、UDP端口不匹配丢弃数然后通过AXI-Lite寄存器暴露给主机读取。这样一个cat /dev/mem或者一段Python脚本就能在打流过程中实时看到FPGA内部每个环节的状态不用每次都插ILA重新布局布线效率完全不一样。这套流程走下来我的感觉是所谓100G UDP“移植”真正值钱的部分不是把代码编译过而是把“为什么这里要这样接、为什么这里要翻字节序、为什么这个参数必须这样配”全部弄明白。等到你把这些坑都踩过一遍回头看verilog-ethernet的源码整个数据通路的每一层就都通透。