简介：面向成都海光网卡用户与系统管理员的专用驱动安装包，用于解决操作系统无法识别网卡、网络性能无法充分发挥的问题，覆盖主流操作系统环境下的驱动部署与故障排查。包内共22个文件，压缩包仅146KB，以14个C源文件与3个头文件为主体，辅以Makefile、Shell脚本、readme说明及mk配置，属于源码级驱动资源，用户可依据实际系统环境自行编译与集成。目前已有658人学习下载，适合运维人员、嵌入式开发者及对驱动原理感兴趣的读者参考。通过阅读源码与编译脚本，可以掌握网卡设备与操作系统的交互方式、驱动安装流程以及常见编译问题的处理思路；说明文档与配置工具可帮助快速搭建编译环境、验证驱动效果，是一份便于按需修改和二次开发的轻量实用资料。
1. 成都海光网卡驱动安装包：为什么你拿到手的第一件事不是双击安装
做过国产化服务器交付的人大概率都经历过这一幕：设备上架、系统装好、IP 配完，结果ping网关不通，ip link一看网卡状态是DOWN，lspci能认出设备，但系统里根本没有对应的eth接口。这时候手边若是有一份“成都海光网卡驱动安装包”，问题通常能解决大半——但前提是你得知道这个包该怎么用、装哪个版本、在什么内核上装、装完还要做什么。它不是一个双击就完事的安装器，而是一套需要你理解驱动源码 + 固件 + 依赖工具链三者关系的交付物。这篇文章要解决的，正是从拿到安装包到网卡真正跑满线速的完整链路：它是什么、里面有什么、怎么编译、怎么装、报错怎么查、性能怎么调。适合正在做信创服务器交付、机房扩容、或是刚接手国产化网络设备的运维工程师，新手能顺着步骤走完，熟手也能借此核对一遍自己容易忽略的边界参数。
2. 驱动安装包的本质与选型：先搞清楚你装的是哪个“海光网卡”
2.1 安装包里其实有三样东西：源码、固件、依赖工具
“成都海光网卡驱动安装包”这个标题听起来像一个文件，但你解压之后通常会看到三个目录：driver/（内核模块源码）、firmware/（网卡固件，通常是.bin文件）、tools/（诊断与配置工具，比如ethtool的定制版或厂商自己的链路检测工具）。这三者的作用完全不同，缺一不可。驱动源码负责让 Linux 内核认识这个 PCIe 设备并创建网络接口，固件负责网卡内部的报文处理逻辑——很多“装上驱动但不稳定”的问题，根源其实是固件没更新。而tools/里的东西，往往是你排查“为什么光模块协商不上”时最趁手的武器。
选型的第一条原则：驱动版本必须和内核版本、网卡硬件版本同时匹配。某厂商在发布安装包时通常会写明支持的内核区间，例如3.10.x到5.4.x，如果你用的是更新的发行版内核，编译时大概率会遇到结构体成员变更导致的报错。我一般会先执行uname -r确认内核版本，再去安装包里的README或RELEASE文件里核对支持范围，而不是直接make。第二条原则：确认网卡具体型号，哪怕是同一个厂商，万兆和二十五万兆的驱动源码往往是分开的，混用会出现加载成功但dmesg报Unknown device的情况。
2.2 怎么确认你的网卡确实需要这个安装包
在动手装之前，先花两分钟确认设备确实“需要”这份驱动。执行lspci -nnk | grep -i ethernet，看输出里是否有一个厂商 ID 和设备 ID 都能对上你手里网卡型号的记录。如果lspci能列出设备但dmesg | grep -i eth里看不到驱动加载信息，说明内核自带驱动不覆盖此设备，或者驱动被blacklist了。这时候才轮到安装包登场。如果你是虚拟机环境，或者你的系统是某些云镜像，那lspci可能直接看不到物理网卡，这时候装驱动是没意义的，得先确认硬件透传配置。
2.3 选择离线包还是在线编译包：机房没有外网时的取舍
安装包常见的两种形态：一种是预编译的.ko文件加安装脚本，另一种是完整源码包。前者适合内网环境、内核版本和安装包构建环境完全一致的场景，insmod或modprobe即可加载；后者适合你需要针对当前内核重新编译的场景。我的建议是：如果环境允许，优先用源码包自己编，因为预编译.ko对内核vermagic非常敏感，uname -r差一个小版本都可能insmod失败。某公司交付的安装包里如果只有ko文件，你modinfo看一下其中的vermagic字段，大概率和你当前内核对不上，这时候就得走源码编译路线。另外，源码包通常还带了dkms支持，能在内核升级后自动重建模块，省去每次升级内核后手动重编的麻烦。
2.4 三个必查的边界条件：内核头文件、GCC 版本、UEFI 安全启动
编译源码包前，先确认三件事。第一，/lib/modules/$(uname -r)/build这个软链接必须存在，它指向内核头文件目录，不存在的话make第一行就会报错。如果头文件没装，用发行版自带的安装源补上，例如某些系统上需要安装kernel-devel或linux-headers包。第二，GCC 版本不能和编译内核时用的版本差距过大，否则会有gcc: error: unrecognized command line option之类的问题。第三，如果你的机器开了 UEFI 安全启动，而驱动没有签名，内核会拒绝加载，报Required key not available，这个坑在国产化服务器上特别常见——很多机器出厂默认开安全启动，装完驱动重启直接翻车。处理方式是去 BIOS 里关掉安全启动，或者用mokutil导入签名，但后者流程繁琐，机房交付场景下我通常直接建议关闭。
3. 在本地复现安装流程：从解压到modprobe的最小命令集
3.1 解压并核对安装包目录结构
拿到安装包后，先不要急着tar -zxvf后直接make。我习惯先解压到/opt或/home下，然后把目录结构打印出来，对照README看它说明的安装路径是否符合预期。下面是一段最小流程示意：
mkdir -p /opt/driver_pkg && tar -xzf hi_some_net_driver.tar.gz -C /opt/driver_pkg cd /opt/driver_pkg ls -la # 预期看到 driver/ firmware/ tools/ 三个目录和 README 文件 cat README | head -n 50这里的重点是先看README而不是直接执行里面的脚本。很多坑其实都在README里写了，比如“需要先make clean再make”“固件需要手动拷贝到/lib/firmware”。把目录结构确认清楚，能避免后续编译到一半发现源码缺失或版本不对的问题。
3.2 编译驱动的标准步骤与关键参数
进入驱动源码目录后，最常见的是make加make install两步，也可能有./install.sh一键脚本。我给出一个兼容性较高的手动编译流程：
cd /opt/driver_pkg/driver make clean # 务必执行，避免上一次编译的中间产物干扰 make -j$(nproc) # 并行编译，注意观察是否有 error make install modinfo hi_net.ko | head -n 20 # 安装后立即查看模块信息make clean这一步不是可有可无的。曾遇到过某开发者在已经编译过同一份源码的机器上直接重新make，结果.o文件是旧内核版本的产物，导致生成的ko文件vermagic混乱，modprobe时直接报Invalid module format。-j$(nproc)可以加速编译，但如果源码本身有并行编译问题，可以去掉-j改为单线程编译，保险起见我第一次编译时通常不加-j，确认无误后再并行。modinfo看的是vermagic字段是否与当前内核一致，同时也看depends字段，确认它依赖的其他模块是否已经加载。
3.3 加载驱动并验证接口是否创建
编译安装完成后，加载驱动并确认网络接口出现：
modprobe hi_net dmesg | tail -n 20 # 查看驱动加载日志，注意有没有 ERROR 或 failed ip link show ethtool -i eth0 # 假设接口名是 eth0如果ip link show里看不到新接口，先别急着reboot。多数情况是驱动的参数不对，或者设备被系统识别成了另一个名字。dmesg里如果有probe failed或firmware not found，那就要回到firmware/目录，把.bin文件拷贝到/lib/firmware下并确保文件名和驱动源码里请求的完全一致。ethtool -i的输出会告诉你driver名称、firmware-version和bus-info，这是验证驱动是否真的接管了设备的最直接证据。
3.4 用dkms注册驱动，让内核升级后不再返工
如果你用的是长期维护的发行版，强烈建议把驱动注册进dkms。这样以后系统升级内核，模块会被自动重编，不用每次手动make。流程如下：
cp -r /opt/driver_pkg/driver /usr/src/hi_net-1.0.0 cd /usr/src/hi_net-1.0.0 # 创建 dkms.conf，内容参考如下 cat > dkms.conf << EOF PACKAGE_NAME="hi_net" PACKAGE_VERSION="1.0.0" BUILT_MODULE_NAME[0]="hi_net" DEST_MODULE_LOCATION[0]="/kernel/drivers/net/ethernet/hi" AUTOINSTALL="yes" EOF dkms add -m hi_net -v 1.0.0 dkms build -m hi_net -v 1.0.0 dkms install -m hi_net -v 1.0.0dkms.conf里的DEST_MODULE_LOCATION决定了模块安装到内核模块树的哪个子目录，这会影响depmod能否正确建立依赖关系。AUTOINSTALL="yes"是让它在未来内核升级后自动重编，但前提是系统里有新内核对应的头文件包。如果你的环境是精简安装、没有自动安装头文件的习惯，那dkms一样会失败，所以这个方案更适合有标准软件源且允许安装开发包的环境。
4. 避坑指南：海光网卡驱动安装的 5 个血泪教训
4.1 报错Unknown symbol：往往是内核配置选项未开启
现象：modprobe时报Unknown symbol in module, or unknown symbol version。原因：驱动源码里用到了一些内核本身未编译的功能，例如CONFIG_PCI_MSI或CONFIG_IOMMU_SUPPORT未开启。解决：grep CONFIG_PCI_MSI /boot/config-$(uname -r)查一下，确认内核配置里有没有开启该选项；如果没有，常见做法是换一个带标准服务器内核的发行版安装，或联系某厂商获取为当前内核定制过的驱动补丁。
4.2 加载成功但网卡灯不亮：固件没到位是头号嫌疑
现象：ip link显示接口 UP，但物理链路对端指示灯不亮，ethtool eth0显示Link detected: no。原因：驱动加载了，但网卡内部的 PHY 固件没有正确加载，网卡不知道如何协商速率。解决：回到安装包的firmware/目录，把.bin文件拷到/lib/firmware，文件名要严格匹配，然后modprobe -r hi_net && modprobe hi_net重新加载，再看dmesg有没有Loaded firmware的提示。
4.3 重启后网卡消失：没有做depmod或没加入modules-load
现象：驱动加载后一切正常，但重启后ip link里没有网卡，dmesg里也没有任何驱动加载记录。原因：make install只把.ko文件放到了模块目录，但没有重建modules.dep文件，系统启动时无法定位依赖。解决：手动执行depmod -a，并把hi_net写入/etc/modules-load.d/hi_net.conf。这样开机时会强制加载该模块，而不是依赖udev触发。
4.4 编译报错struct xxx has no member：内核源码接口变了
现象：make时报error: ‘struct pci_dev’ has no member named ‘msi_enabled’这类错误。原因：新版内核改了结构体字段名，而驱动源码是针对旧内核写的。解决：先看 README 里声明的支持内核版本；如果确实需要在新内核上编译，常见做法是在源码里用#ifdef包一层兼容代码，或者找厂商要适配新内核的补丁。网上有人建议改CFLAGS强制忽略错误，这基本是饮鸩止渴，拉起来的模块跑起来也是定时炸弹。
4.5 多网口机器只能识别一个口：中断和内存资源冲突
现象：四口网卡，只有第一个口出现了eth接口，其余几个口在lspci里看得到，但ip link里没有。原因：驱动默认的 MSI-X 中断数量不够，或者 IOMMU 开启后设备没能分配到足够的中断向量。解决：查驱动模块参数，常见的是modprobe hi_net msix_vectors=4或者调整 BIOS 里的SR-IOV设置；也可以把iommu=pt加到内核 cmdline 里，让设备直接使用物理中断，而不是走虚拟化重映射。这个问题的排查方向比较隐蔽，一般先看dmesg里有没有Can't allocate MSI-X字样，有的话基本就锁定方向了。
5. 验证驱动是否真正可用：从链路协商到压测的完整检查单
5.1 用ethtool核对速率、双工与自协商状态
驱动装上、接口起来，这只是开始。要确认驱动真正“可用”，第一关是用ethtool看物理层状态。命令如下：
ethtool eth0 ethtool -S eth0 | head -n 30 ethtool -p eth0 3 # 亮灯定位物理端口，确认对应关系ethtool eth0的核心输出项是Speed、Duplex、Auto-negotiation。如果显示Speed: Unknown!，说明协商失败，多半是光模块兼容性问题或固件没加载对。ethtool -S看的是驱动层的统计计数，rx_errors、tx_errors和rx_dropped这几项如果持续增长，那就要回头检查中断配置或 ring buffer 大小了。ethtool -p用于物理端口定位，在有多端口设备时特别有用，避免把 A 口的线插到 B 口上查半天。
5.2 用iperf3做双向吞吐验证，驱动才算是过了关
单纯链路 UP 不代表性能达标。我通常会起一个iperf3服务端和客户端，分别做上行、下行、双向三种测试，命令如下：
# 服务端（假设 IP 为 192.168.10.2） iperf3 -s -p 5201 # 客户端（假设本机为 192.168.10.1） iperf3 -c 192.168.10.2 -t 30 -P 4 iperf3 -c 192.168.10.2 -t 30 -P 4 -R # 反向测试万兆网卡的单流性能通常在 5-7Gbps 左右，多流-P 4能跑满 9.4Gbps 以上；如果多流测试也上不去，问题多半不在驱动，而在中断绑定或 PCIe 通道带宽。-R反向测试用来验证收包方向，很多驱动在 TX 方向做了优化但 RX 路径有瓶颈，irqbalance没开或者队列没拉开就会出现 RX 吞吐远低于 TX 的情况。
5.3 检查中断分布：确认多队列真的在干活
高性能网卡驱动都支持多队列，但要确认队列是否真的分散到了多个 CPU 上。用以下方式检查：
cat /proc/interrupts | grep -i hi_net cat /proc/irq/$(cat /proc/interrupts | grep -i hi_net | awk '{print $1}' | tr -d ':')/smp_affinity_list如果所有中断都落在同一个 CPU 上，那多队列等于没生效。常规做法是用irqbalance自动均衡，或者手动把每个队列的中断绑到不同的核上。手动绑定时要注意smp_affinity_list写的是 CPU 编号列表，比如0-3代表 CPU0 到 CPU3。如果驱动支持ethtool -L eth0 combined 4这样的命令，可以用它调整队列数，但要先确认驱动的最大队列数，不是想设多少就设多少。
5.4 查看关键日志：驱动有没有在后台反复重置
最后一个容易被忽略的验证点是dmesg里有没有周期性报错。有些驱动在链路抖动或协商异常时会悄悄进行内部复位，表现出来就是网络闪断几秒然后恢复，dmesg会有reset或link down的痕迹。建议执行dmesg -T | grep -i "hi_net\|eth0"看一下，如果发现了周期性错误，结合固件版本和交换机端设置来排查，通常优先更新固件，其次再检查交换机侧的光模块兼容性。这个环节虽然简单，但往往是“装完能用、过几天就掉线”类问题的最早预警信号。
6. 固件升级与参数调优：让驱动从“能通”到“跑满线速”的关键两步
6.1 固件升级的正确姿势：不是覆盖文件就完事
很多人在网卡工作正常后就不再碰固件，但驱动跑了一段时间后出现偶发丢包，排查到最后大概率是固件版本太老，某些已知硬件 bug 没有被修复。升级固件的常见做法是使用安装包里tools/下的烧录工具，例如fw_update或nvmupdate。操作前务必确认两件事：第一，确认当前固件版本，执行ethtool -i eth0看firmware-version字段；第二，确认升级工具的-f参数指定的是正确的.bin文件，不要拿别的型号的固件强刷。刷写过程中断电是致命的，建议接上 UPS 或确保机房供电稳定再操作。升级完成后必须执行一次完整的断电重启，部分网卡的固件只有在冷启动后才会真正生效。
6.2 调整 ring buffer，减少高峰期的丢包
网卡默认的 ring buffer 大小通常是 256 或 512，在高并发小包场景下很容易出现rx_dropped增长。可以通过以下命令调大：
ethtool -G eth0 rx 4096 tx 4096 ethtool -g eth0 # 查看当前 ring 参数但要注意，-G设置的是当前会话的参数，重启后会恢复默认值，要持久化得借助systemd服务或者在网络脚本里加post-up钩子。调大 ring buffer 的代价是占用更多内存，对绝大多数服务器场景来说 4096 是安全的，但要先看驱动是否支持这么大的值，如果设置超出驱动上限，ethtool会直接报错。一个判断标准是：如果rx_dropped在压测时不增长，就说明 buffer 够用，不需要无限调大。
6.3 关闭 offload 特性，兼容特定抓包和 DPDK 场景
如果你需要在网卡上跑抓包工具或者打算接 DPDK，那必须调整 offload 设置。驱动默认开启的 checksum offload 和 TCP segmentation offload 会导致抓到的包不是原始报文，而在 DPDK 场景下，这些 offload 反而会干扰硬件队列的分配。常见做法是关掉这几个特性：
ethtool -K eth0 tx off rx off ethtool -K eth0 tso off gso off gro off lro off ethtool -k eth0 # 查看当前 offload 状态这里要提醒一句：lro在很多驱动里默认是关闭的，如果你的ethtool -k输出里显示lro: off，那就不用特意去动它。关闭tso/gso/gro会轻微降低大包吞吐，但换来的是 CPU 占用降低和报文可观测性提升，在做网络排查时是值得的。如果只是正常业务使用，建议保持 offload 开启，不要为了“性能”盲目关掉默认配置，很多人在这个环节做了反向优化，反而让 CPU 负载飙升。
6.4 习惯性检查：让安装包目录变成日后的排障手册
最后说一个我自己的习惯：安装完成后，不着急删掉解压出来的安装包目录。我会把README里记录的移植说明、已知问题、参数列表打印出来放在/opt/driver_pkg下，当作这份驱动的本地档案，并在dmesg里出现异常时第一时间翻它。某次某开发者遇到“双口网卡第二口无法协商 25G”，查遍网络无果，最后翻到安装包里的一个说明文档，里面明确写着“第二口若连接 25G 设备，需在交换机侧关闭 FEC”。这就是安装包的价值上限——它不只是驱动，而是这块网卡在这个平台上的完整交付说明。希望这篇笔记能帮你把这份安装包用得比厂商预设的还顺手，少走几步弯路。
本文还有配套的精品资源，点击获取
翻译器实战指南)
