简介：这份资源是Mellanox Technologies发布的ConnectX系列可编程参考手册（PRM）修订版1.81，面向具备网络编程经验的技术人员，尤其是从事高性能计算、云计算与数据中心网络架构设计开发的专业人士。手册系统阐述ConnectX系列适配器的硬件与软件接口规范，覆盖InfiniBand、Ethernet、FCoE、VPI多协议支持，并深入讲解设备初始化、配置命令、数据传输机制、错误处理，以及VXLAN/NVGRE隧道、虚拟交换机、FCP-3、RDMA、多播与原子操作等性能优化与高级特性。资源包为单个PDF文件，共1个文件，大小约6.64MB，内容包含大量配置表、命令参数定义与示例，便于按需检索。目前已有75人学习下载。读者可借助它理解适配器工作原理、指导产品配置与故障排查，并为基于ConnectX的应用程序开发提供权威技术参考，从而充分利用硬件特性提升系统性能。
1. ConnectX 编程参考手册到底在讲什么：从 mlx5 驱动到多协议硬件特性的落地地图
如果你手里有一台装了 ConnectX-5/6/7 的服务器，lspci | grep Mellanox能看到设备，但ethtool -i出来的驱动版本和固件版本对不上，RDMA 的ibv_devinfo又只显示一个端口，那你大概率需要把 ConnectX 系列编程参考手册翻出来对着看。这份手册不是一本“读完就会”的教程，它更像一张硬件能力地图：哪些协议在硬件里卸载、哪些寄存器/固件参数控制行为、哪些特性需要驱动和固件版本同时满足。Mellanox Technologies 被 NVIDIA 收购后，文档体系分成两套——一套是面向驱动开发者的 PRM（Programming Reference Manual），一套是面向运维和集成的用户手册。标题里的“多协议支持与硬件特性详解”指向的是前者：RoCEv2、InfiniBand、Ethernet、NVMe-oF、SR-IOV、VirtIO 加速这些协议栈在 ConnectX ASIC 里怎么共存、怎么切换、怎么通过 mlx5 驱动暴露给上层。适合谁读？做 RDMA 应用调优的、做 DPU/IPU 卸载方案的、做高性能存储和 AI 训练网络的工程师。如果你只是想插上网卡能 ping 通，这份手册的深度会劝退你；但如果你要压榨 P99 延迟、排查roce_accl log_tx_psn_window这类底层日志，它就是绕不开的参考。
2. 多协议支持在硬件层怎么落地：从链路层到传输层的配置路径
2.1 协议共存不是软件开关，而是固件+驱动+端口模式的三方约定
ConnectX 系列一颗 ASIC 同时支持 InfiniBand 和 Ethernet 两种链路层，但同一物理端口在某一时刻只能跑一种。切换靠的是固件里的端口类型配置，不是驱动模块参数。常见做法是用 MFT（Mellanox Firmware Tools）里的mlxconfig改LINK_TYPE_P1，然后冷重启。很多人第一次翻车就在这里：mlxconfig -d /dev/mst/mt4123_pciconf0 set LINK_TYPE_P1=2执行成功，reboot之后ibstat却报IB device not found，因为固件默认可能把端口锁在 Ethernet 模式，而你的驱动只加载了 IB 栈。正确顺序是先确认固件当前配置，再改，再验证。
# 查看当前固件配置中与链路类型相关的项 mst start mst status mlxconfig -d /dev/mst/mt4123_pciconf0 query | grep -i link_type # 将端口1设为 Ethernet(2)，端口2保持 InfiniBand(1) mlxconfig -d /dev/mst/mt4123_pciconf0 set LINK_TYPE_P1=2 LINK_TYPE_P2=1 # 冷重启使固件配置生效（不是 reboot，部分机型需要下电） ipmitool power cycle逻辑说明：mst start启动 MFT 的寄存器访问通道，mst status列出可用的 PCI 设备名。mlxconfig query读的是固件 NVRAM 里的配置，不是运行时状态。set写入后必须冷重启，因为链路层类型在 ASIC 初始化阶段就固定了。参数上，LINK_TYPE_P1取值 1 是 IB，2 是 Ethernet，部分固件版本还支持 3 表示自动协商，但自动协商在混合组网里经常出玄学问题，生产环境建议显式指定。
2.2 RoCEv2 的硬件卸载点：从 QP 到拥塞控制
RoCEv2 把 IB 的传输层封装进 UDP，目的端口 4791。ConnectX 硬件里做卸载的关键位置有三个：QP（Queue Pair）上下文、拥塞控制表、以及 PSN 窗口管理。roce_accl log_tx_psn_window这个日志项就是硬件在发送侧维护 PSN 窗口时打的，出现频繁说明发送窗口被对端 ACK 拖住，通常是网络丢包或对端处理慢。调优时先看ethtool -S里的rx_pause、tx_pause和out_of_sequence计数，再决定是调tc qdisc还是改mlxconfig里的ROCE_CC参数。
# 查看 RoCE 相关硬件计数器 ethtool -S ens1f0 | grep -E "roce|pause|out_of_sequence|discard" # 查看当前拥塞控制算法和 ECN 配置 mlnx_qos -i ens1f0 cma_roce_mode -d mlx5_0 -p 1 # 开启 ECN 并设置 DCQCN 参数（需交换机配合） mlnx_qos -i ens1f0 --ecn=on echo 1 > /sys/class/net/ens1f0/ecn/roce_np/enable逻辑说明：ethtool -S读的是驱动从硬件计数器聚合上来的统计，out_of_sequence增长说明乱序到达，RoCEv2 对乱序敏感，会触发重传。mlnx_qos配置的是网卡侧的 QoS 和 ECN 标记，但 ECN 要端到端生效，交换机也得开。cma_roce_mode确认当前是 v1 还是 v2，v1 不支持 ECN，生产环境基本都用 v2。参数上，DCQCN 的clamp_tgt_rate和rate_reduce_monitor_period在mlxconfig里改，改完同样要冷重启。
2.3 SR-IOV 与多协议共存的资源划分
当一台物理机同时跑 IB 和 Ethernet 流量，又要给虚拟机分 VF，资源划分就变得棘手。ConnectX 的 SR-IOV 实现里，每个 PF 可以创建多个 VF，但 VF 的链路类型跟随 PF，不能单独改。常见做法是把两个物理端口分别配成 IB 和 Ethernet，各自开 SR-IOV，然后通过mlxconfig里的SRIOV_EN和NUM_OF_VFS控制数量。注意NUM_OF_VFS改大之后，lspci里 VF 的 BDF 会变，如果之前用 BDF 绑定了驱动或做了 udev 规则，需要同步更新。
# 查看 PF 的 SR-IOV 能力 lspci -vv -s 0000:03:00.0 | grep -i "Initial VFs\|Total VFs" # 设置 VF 数量（需固件支持，改完冷重启） mlxconfig -d /dev/mst/mt4123_pciconf0 set SRIOV_EN=1 NUM_OF_VFS=8 # 重启后在 PF 上创建 VF echo 8 > /sys/class/net/ens1f0/device/sriov_numvfs # 确认 VF 链路类型与 PF 一致 for vf in /sys/class/net/ens1f0/device/virtfn*/net/*; do echo "$vf: $(cat $vf/../dev_id 2>/dev/null)" done逻辑说明：mlxconfig设的是固件层最大 VF 数，sriov_numvfs是运行时实际创建数，两者取小。VF 的链路类型不能独立于 PF，所以多协议场景下通常按端口分工。参数上，NUM_OF_VFS最大值取决于固件版本和 ASIC 型号，ConnectX-5 常见上限 127，ConnectX-6 更高，但实际能创建多少还受 PCIe 资源限制。
3. 硬件特性详解：从 mlxlink 诊断到时间戳与加密卸载
3.1 用 mlxlink 做光模块与线缆诊断：-m 和 -c 参数怎么读
mlxlink是 MFT 里最实用的工具之一，比ethtool -m信息更全，能读 AOC/DAC 的厂商信息和实时误码率。热词里提到的-m是读模块信息，-c是读计数器。实操中先mst start，再mlxlink -d /dev/mst/mt4123_pciconf0 -p 1 -m，输出里重点看Vendor Name、Serial Number、Temperature和Rx Power。如果Rx Power低于 -10 dBm，链路可能降速或闪断。-c输出的是物理层计数器，Symbol Errors和Effective BER是关键，BER 高于 1e-12 就要查光纤或模块。
# 读模块信息（-m） mlxlink -d /dev/mst/mt4123_pciconf0 -p 1 -m # 读物理层计数器（-c），关注 Symbol Errors 和 BER mlxlink -d /dev/mst/mt4123_pciconf0 -p 1 -c # 同时看链路状态和速率协商结果 mlxlink -d /dev/mst/mt4123_pciconf0 -p 1 --show_module --show_counters逻辑说明：-d指定 MST 设备名，-p指定端口号。-m读的是模块 EEPROM，-c读的是 ASIC 物理层寄存器。参数上，--show_module和--show_counters可以组合，输出更紧凑。注意mlxlink读计数器不会清零，要对比前后差值，别只看绝对值。
3.2 硬件时间戳：PTP 和 free-running 计数器的取舍
ConnectX-5 以后支持硬件 PTP 时间戳，精度到纳秒级。编程参考手册里区分两种模式：一种是跟随外部 PTP 时钟同步，另一种是 free-running 计数器，只保证单调递增不保证绝对时间。金融交易和 5G 前传场景必须用同步模式，而做延迟测量可以用 free-running 省去外部时钟源。配置入口在mlxconfig的PTP_EN和驱动侧的ptp_clock设备。
# 确认硬件时间戳能力 ethtool -T ens1f0 # 查看 PTP 设备 ls /dev/ptp* # 用 testptp 读当前硬件时间 testptp -d /dev/ptp0 -g # 开启硬件时间戳（需固件支持） mlxconfig -d /dev/mst/mt4123_pciconf0 set PTP_EN=1逻辑说明：ethtool -T列出支持的 timestamp 类型，/dev/ptp*是字符设备，testptp -g读当前时间。参数上，PTP_EN开启后需要重新加载驱动或冷重启。注意 free-running 模式下硬件计数器会回绕，应用层要做 64 位扩展。
3.3 加密与压缩卸载：IPsec 和 NVMe-oF 的硬件路径
ConnectX-6 Dx 以后支持 IPsec 和 TLS 卸载，编程手册里叫crypto offload。配置分两步：固件里开CRYPTO_EN，驱动侧用mlx5的ipsec接口下发 SA。NVMe-oF 的硬件卸载则依赖nvme-rdma和mlx5的transport接口。常见坑是固件版本不够，mlxconfig里根本看不到CRYPTO_EN选项，这时候只能升级固件。
# 检查固件是否支持加密卸载 mlxconfig -d /dev/mst/mt4123_pciconf0 query | grep -i crypto # 开启 IPsec 卸载 mlxconfig -d /dev/mst/mt4123_pciconf0 set CRYPTO_EN=1 IPsec_EN=1 # 查看 NVMe-oF 卸载状态 cat /sys/class/nvme/nvme0/transport dmesg | grep -i "nvme-rdma\|mlx5"逻辑说明：mlxconfig query里没有CRYPTO_EN说明固件太老，需要先mlxfwmanager升级。IPsec_EN和CRYPTO_EN要同时开。NVMe-oF 卸载状态看transport和dmesg，如果显示rdma但吞吐上不去，检查mlx5的tx_steering计数器。
4. 避坑与排查：ConnectX 多协议配置里最容易翻车的五件事
4.1 现象：ibv_devinfo只显示一个端口，另一个端口消失
原因：LINK_TYPE_P2被设成了 0 或固件默认值，或者第二个端口在 PCI 枚举时被 BIOS 屏蔽。解决：先mlxconfig query确认两个端口的LINK_TYPE，再查 BIOS 里 PCIe 拆分和Above 4G Decoding是否开启。如果 BIOS 没问题，用mstflint -d /dev/mst/mt4123_pciconf0 q看固件是否完整。
4.2 现象：RoCEv2 能建链但吞吐只有线速一半
原因：ECN 没开或交换机没配，导致 DCQCN 不生效，发送窗口被 PSN 窗口限制。解决：mlnx_qos --ecn=on开网卡侧，交换机侧配WRED/ECN，然后用ethtool -S看out_of_sequence是否下降。如果还不行，检查roce_accl log_tx_psn_window日志频率，频繁出现说明对端 ACK 慢。
4.3 现象：mlxlink -m读不到模块信息，报Module not present
原因：模块没插紧、模块类型不被固件识别、或者端口处于 down 状态。解决：先mlxlink -d ... -p 1看链路状态，如果Physical state是Disable，检查mlxconfig里PHY_TYPE是否匹配。DAC 线要确认是 passive 还是 active，active 线需要固件支持。
4.4 现象：SR-IOV VF 创建后虚拟机里看不到网卡
原因：VF 的virtfn没绑定到vfio-pci，或者NUM_OF_VFS设了但sriov_numvfs没写。解决：lspci -vv确认 VF 存在，echo 8 > sriov_numvfs创建，然后driverctl set-override绑vfio-pci。注意NUM_OF_VFS改完必须冷重启，热重启不生效。
4.5 现象：PTP 时间戳读出来是 0 或跳变
原因：PTP_EN没开，或者/dev/ptp0对应的是错误设备。解决：ethtool -T确认hardware-transmit和hardware-receive都支持，testptp -g读时间。如果跳变，检查是否开了free-running模式但应用层没做回绕处理。
5. 进阶技巧：用 mlxconfig 批量下发和固件版本对齐
批量管理多台服务器时，逐台mlxconfig set效率太低。我一般先把目标配置导出成二进制，再用mlxconfig -d ... apply批量下发。导出命令是mlxconfig -d /dev/mst/mt4123_pciconf0 -e /tmp/cx5_config.bin，下发是mlxconfig -d /dev/mst/mt4123_pciconf0 -i /tmp/cx5_config.bin apply。注意apply不会自动冷重启，要配合ipmitool power cycle或mlxfwreset。mlxfwreset比冷重启快，但部分固件版本不支持，执行前先mlxfwreset -d ... q查询。
固件版本对齐是另一个血泪经验。同一集群里 ConnectX-5 的固件版本差两个小版本，RoCEv2 的 PSN 窗口行为就可能不一致，表现为部分节点吞吐正常、部分节点频繁重传。我习惯用mlxfwmanager --query列出所有网卡固件版本，再用mlxfwmanager -d ... -i fw.bin -u统一升级。升级前务必确认固件和驱动版本兼容矩阵，NVIDIA 的文档里有对应表，跨大版本升级（比如 16.x 到 22.x）通常需要先升驱动再升固件。
# 导出当前配置 mlxconfig -d /dev/mst/mt4123_pciconf0 -e /tmp/cx5_config.bin # 批量下发到另一台机器 mlxconfig -d /dev/mst/mt4123_pciconf0 -i /tmp/cx5_config.bin apply # 查询所有网卡固件版本 mlxfwmanager --query # 统一升级固件（需先下载对应 .bin） mlxfwmanager -d /dev/mst/mt4123_pciconf0 -i fw-16_35_2000.bin -u # 用 mlxfwreset 代替冷重启（先查询是否支持） mlxfwreset -d /dev/mst/mt4123_pciconf0 q mlxfwreset -d /dev/mst/mt4123_pciconf0 r逻辑说明：-e导出的是 NVRAM 配置的二进制镜像，-i加apply是写入。mlxfwmanager --query输出所有 MST 设备的固件版本和 PSID，PSID 不匹配的固件不能混刷。mlxfwreset的q是查询，r是执行 reset，比冷重启快但要求固件支持。参数上，-u是升级，-i指定固件文件，升级过程中不要断电。
最后说一个我自己的习惯：每次改完mlxconfig，先mlxconfig query确认写入值，再mlxfwreset或冷重启，重启后第一件事是mlxlink -c看物理层计数器有没有异常增长。这套流程帮我省过至少三次“配置写了但没生效”的后悔药。ConnectX 的硬件特性很多，手册里没写的边界条件更多，遇到玄学问题先怀疑固件版本和冷重启，再怀疑驱动参数。希望帮到你。
本文还有配套的精品资源，点击获取
