Linux上用DKMS构建驱动需要哪些准备,怎样确认模块编译成功

发布人:A5数据发布时间:2026-11-07 13:41阅读量:80

Linux 上用 DKMS 构建驱动,核心准备是与目标内核完全匹配的内核头文件或内核开发包、编译工具链、DKMS 软件包,以及包含有效 dkms.conf 的驱动源代码。首次部署时,建议先针对当前正在运行的内核执行构建,再分别确认“已经编译”“已经安装”“能够加载”三个状态,不要只看 DKMS 命令是否返回成功。

需要注意,驱动文件生成并不等于驱动已经生效。dkms status 显示 built,只能说明模块编译完成;显示 installed,说明模块已经复制到内核模块目录;只有 modinfo 能读取模块信息、modprobe 能加载且内核日志没有报错,才能认为当前内核具备使用该驱动的条件。

一、明确目标内核和驱动信息

以下步骤以名为 vendor_driver、版本为 1.2.3 的示例驱动说明。实际操作时,应将模块包名、版本号和模块名替换为驱动供应方提供的值。

先查看发行版、内核版本、CPU 架构和当前 DKMS 状态:

cat /etc/os-release
uname -r
uname -m
dkms status

常见输出可能类似:

6.8.0-31-generic
x86_64

其中,uname -r 的完整结果必须作为目标内核版本使用。例如当前内核为 6.8.0-31-generic,就不能只安装 6.8 或其他内核版本的头文件。

确认当前内核是否存在可用的构建目录:

一、明确目标内核和驱动信息配图

KERNEL="$(uname -r)"
ls -ld "/lib/modules/$KERNEL/build"
readlink -f "/lib/modules/$KERNEL/build"

正常情况下,/lib/modules/<内核版本>/build 会指向内核头文件或内核开发包目录。如果提示文件不存在,说明当前内核缺少构建环境,暂时不应执行 dkms build。

构建前需要满足的条件

条件核对内容不满足时的表现
目标内核uname -r 与构建目录版本一致找不到头文件或生成 invalid module format
编译器和 Makegcc --version、make --version日志出现 command not found
DKMSdkms --version无法执行 dkms add、dkms build
驱动源代码目录内存在 dkms.conf无法识别模块名和构建规则
存储空间/var/lib/dkms、/lib/modules 所在文件系统有空间编译中途出现写入失败
Secure Boot 状态mokutil --sb-state模块可编译,但加载时被内核拒绝

建议使用具有 sudo 权限的运维账号操作。驱动源代码、DKMS 状态目录和模块安装目录通常需要 root 权限。

Linux服务器上的驱动构建与运行,离不开相匹配的硬件资源。A5idc数据提供中国香港、美国、日本、韩国、中国台湾、新加坡和马来西亚等地区的物理服务器,涵盖常规计算、AMD平台、GPU及存储型配置,可为网站、业务后台、计算任务和数据服务提供不同的服务器资源基础。

二、安装编译环境

Debian、Ubuntu 系列

在 Debian、Ubuntu 及其衍生发行版中,可以为当前运行的内核安装对应头文件:

sudo apt-get update
sudo apt-get install -y dkms build-essential "linux-headers-$(uname -r)"

安装完成后检查:

dkms --version
gcc --version | head -n 1
make --version | head -n 1
test -e "/lib/modules/$(uname -r)/build" && echo "kernel build tree: OK"

预期至少能看到 DKMS、GCC 和 GNU Make 的版本,并输出:

kernel build tree: OK

RHEL、Rocky Linux、AlmaLinux 系列

这类发行版通常使用 dnf 安装 DKMS、编译器和当前内核的开发包:

sudo dnf install -y dkms gcc make elfutils-libelf-devel \
  "kernel-devel-$(uname -r)" "kernel-headers-$(uname -r)"

然后检查开发包实际提供的构建目录:

KERNEL="$(uname -r)"
rpm -q dkms gcc make "kernel-devel-$KERNEL"
ls -ld "/lib/modules/$KERNEL/build"

如果 kernel-devel-$(uname -r) 不存在,先确认当前运行的是否为自定义内核、旧内核或云厂商定制内核:

uname -r
rpm -qa | grep -E '^(kernel|kernel-devel|kernel-headers)'

对于自定义内核,应使用与该内核源码和配置匹配的构建目录,不要用其他版本的 kernel-devel 强行替代。

检查空间和构建能力

DKMS 通常会在 /var/lib/dkms 中保存源代码、编译中间文件和日志,在 /lib/modules/<内核版本> 中安装最终模块。首次构建前可以检查空间:

df -h / /var /lib/modules
free -h

这里的空间数值不需要固定达到某个标准,但应避免根分区或 /var 分区接近满载。驱动源代码较大、需要编译多个内核版本时,/var/lib/dkms 占用量会明显增加。

三、检查驱动源代码和 DKMS 配置

DKMS 通常要求驱动源代码放在以下目录格式中:

/usr/src/<模块包名>-<版本号>/

例如:

/usr/src/vendor_driver-1.2.3/

该目录至少应包含 dkms.conf 和驱动源文件。若供应方已经提供完整的 DKMS 源代码包,可按其目录结构复制到 /usr/src:

sudo install -d /usr/src/vendor_driver-1.2.3
sudo cp -a ./vendor_driver_source/. /usr/src/vendor_driver-1.2.3/

检查文件是否完整:

sudo test -f /usr/src/vendor_driver-1.2.3/dkms.conf \
  && echo "dkms.conf: OK"

sudo find /usr/src/vendor_driver-1.2.3 -maxdepth 2 -type f | sort | head -n 30

读取关键配置项:

sudo grep -E \
  '^(PACKAGE_NAME|PACKAGE_VERSION|BUILT_MODULE_NAME|BUILT_MODULE_NAME\[|DEST_MODULE_LOCATION|AUTOINSTALL)' \
  /usr/src/vendor_driver-1.2.3/dkms.conf

需要区分两个名称:

  • PACKAGE_NAME 是 DKMS 管理用的包名,通常用于 dkms -m 参数。
  • BUILT_MODULE_NAME 是最终生成的内核模块名,通常用于 modprobe 和 modinfo。
  • 包名可能包含连字符,模块名通常使用下划线。例如包名为 vendor-driver,模块名可能是 vendor_driver。

如果 dkms.conf 使用了数组形式,例如 BUILT_MODULE_NAME[0],应以配置中实际列出的模块名为准。不要仅凭源代码目录名称猜测 modprobe 参数。

四、注册源代码并执行构建

1. 记录变更前状态

首次执行前,建议保存当前 DKMS 状态,便于回滚或比较:

dkms status | tee "$HOME/dkms-status-before.txt"

如果驱动包已经存在同版本的 DKMS 记录,也先查看其状态:

sudo dkms status -m vendor_driver -v 1.2.3

不要直接删除 /var/lib/dkms 下的目录来“清理”状态。DKMS 的记录、源代码和已安装模块之间存在关联,手动删除可能造成状态不一致。

2. 将驱动加入 DKMS

sudo dkms add -m vendor_driver -v 1.2.3

正常情况下,输出会包含创建源代码链接或添加模块版本的信息。随后检查:

sudo dkms status -m vendor_driver -v 1.2.3

刚完成添加但还没有编译时,状态通常类似:

vendor_driver/1.2.3: added

如果提示该版本已经添加,不需要重复执行 add,应继续检查当前状态并直接进入构建步骤。

3. 针对当前内核执行编译

使用当前内核的完整版本号进行构建:

MODULE="vendor_driver"
VERSION="1.2.3"
KERNEL="$(uname -r)"

sudo dkms build -m "$MODULE" -v "$VERSION" -k "$KERNEL"

构建过程可能持续数秒到数分钟,具体时间取决于源代码规模、CPU 性能和是否需要编译多个模块。命令返回成功后,先查看状态:

sudo dkms status -m "$MODULE" -v "$VERSION" -k "$KERNEL"

预期状态类似:

vendor_driver/1.2.3, 6.8.0-31-generic, x86_64: built

这里的 built 是确认编译成功的第一个关键证据。如果仍然是 added,通常表示编译没有完成,或者查看的内核版本与实际构建目标不一致。

4. 查看编译日志和生成文件

即使命令显示成功,也建议检查 make.log:

sudo find "/var/lib/dkms/$MODULE/$VERSION" \
  -type f -name make.log -print

找到日志后查看末尾内容:

sudo tail -n 80 /var/lib/dkms/vendor_driver/1.2.3/*/*/log/make.log

不同 DKMS 版本的日志目录层级可能不同。如果上面的通配路径不匹配,使用 find 输出的实际路径替换。

检查目标内核目录下是否已经生成 .ko、.ko.xz 或 .ko.zst 文件:

sudo find "/var/lib/dkms/$MODULE/$VERSION/$KERNEL" \
  -type f \( -name '*.ko' -o -name '*.ko.xz' -o -name '*.ko.zst' \) -print

此处能找到模块文件,说明编译产物已经生成,但还不能说明它已安装到当前内核的模块目录。

五、安装模块并验证加载条件

1. 将已编译模块安装到内核模块目录

确认 build 阶段成功后再执行安装:

MODULE="vendor_driver"
VERSION="1.2.3"
KERNEL="$(uname -r)"

sudo dkms install -m "$MODULE" -v "$VERSION" -k "$KERNEL"
sudo depmod -a "$KERNEL"

dkms install 会将模块复制到类似下面的目录:

/lib/modules/<内核版本>/updates/dkms/

实际目录可能因发行版和 DKMS 配置不同而变化。depmod -a 会重新生成模块依赖关系和别名缓存,影响范围是指定内核的模块索引,不会改变驱动源代码。

再次查看状态:

sudo dkms status -m "$MODULE" -v "$VERSION" -k "$KERNEL"

理想状态类似:

vendor_driver/1.2.3, 6.8.0-31-generic, x86_64: installed

2. 使用 modinfo 验证模块文件

先用模块名查询文件路径:

modinfo -F filename vendor_driver

正常情况下会返回类似:

/lib/modules/6.8.0-31-generic/updates/dkms/vendor_driver.ko

再查看模块版本、内核版本标记和签名信息:

modinfo vendor_driver | grep -E \
  '^(filename|version|vermagic|signer|sig_id):'

如果 modinfo 能读取 filename 和 vermagic,说明模块已经被当前系统的模块索引识别。若显示的 vermagic 与 uname -r 对应的内核构建信息不一致,加载时可能出现 Invalid module format。

3. 先进行干运行,再决定是否加载

在实际加载前,可以查看 modprobe 将执行的操作:

sudo modprobe -n -v vendor_driver

如果输出包含模块路径或 insmod 操作,说明模块解析基本正常。如果没有输出或提示找不到模块,应回到 modinfo、depmod 和安装路径检查。

加载驱动可能会改变网卡、存储控制器、显卡或其他硬件的工作状态。对于承载 SSH、根文件系统或业务数据的设备,应先安排维护窗口,确认已有驱动没有依赖关系后再执行:

sudo modprobe vendor_driver

加载后检查:

lsmod | grep -E '^vendor_driver([[:space:]]|$)'
sudo journalctl -k -b --no-pager | grep -iE 'vendor_driver|firmware|module'

lsmod 中能看到模块,只能说明模块已经进入当前内核。还应根据驱动类型检查实际设备,例如 PCI 设备可以查看:

lspci -k

网络驱动可以查看:

ip link

如果是 USB 设备,可以结合:

lsusb -t

不同硬件驱动的最终验收指标不同,不能仅用“模块已加载”代替设备功能验证。

六、怎样判断到底是哪一步成功

可以按以下层级判断:

六、怎样判断到底是哪一步成功配图

检查层级命令或证据说明
源代码已登记dkms status 显示 added只完成 DKMS 注册,尚未证明能编译
模块已编译dkms status 显示 built,并存在 .ko 文件编译阶段完成
模块已安装显示 installed,modinfo 能返回 filename当前内核模块目录已包含该模块
模块可加载modprobe 返回成功,lsmod 能看到模块已进入内核
驱动正常工作内核日志无错误,设备绑定正确,功能测试通过才能作为部署验收结果

因此,回答“模块编译成功”时,至少应同时提供以下三类证据:

sudo dkms status -m vendor_driver -v 1.2.3 -k "$(uname -r)"
sudo find "/var/lib/dkms/vendor_driver/1.2.3" \
  -type f \( -name '*.ko' -o -name '*.ko.xz' -o -name '*.ko.zst' \) -print
modinfo vendor_driver

如果只看到 dkms build 命令结束,没有 built 状态、模块文件或 make.log 中的成功结果,证据还不完整。

七、常见失败及处理方式

缺少内核头文件或开发包

典型错误包括:

Your kernel headers for kernel ... cannot be found

或者:

/lib/modules/<内核版本>/build: No such file or directory

先核对版本:

KERNEL="$(uname -r)"
ls -ld "/lib/modules/$KERNEL/build"
make -sC "/lib/modules/$KERNEL/build" kernelrelease

make 输出的内核版本应与 uname -r 一致。Debian、Ubuntu 重新安装:

sudo apt-get install --reinstall "linux-headers-$(uname -r)"

RHEL 系列重新安装:

sudo dnf reinstall "kernel-devel-$(uname -r)" "kernel-headers-$(uname -r)"

如果当前运行的是自定义内核,应安装该内核对应的源码和配置,不要用发行版默认内核的开发包代替。

dkms.conf 缺失或模块名称不匹配

如果出现 dkms.conf 找不到、PACKAGE_NAME 不一致或构建后找不到模块,检查:

sudo find /usr/src/vendor_driver-1.2.3 -maxdepth 2 -name dkms.conf -print
sudo grep -E 'PACKAGE_NAME|PACKAGE_VERSION|BUILT_MODULE_NAME' \
  /usr/src/vendor_driver-1.2.3/dkms.conf

dkms add 使用的参数应与 PACKAGE_NAME、PACKAGE_VERSION 对应;modprobe 和 modinfo 则应使用 BUILT_MODULE_NAME。如果供应方提供了多个模块,必须分别核对配置中的数组项。

编译日志出现内核 API 或符号错误

常见信息包括:

error: implicit declaration of function
error: unknown field
ERROR: Kernel configuration is invalid

这通常表示驱动源代码版本与目标内核版本不兼容,而不只是缺少一个命令。查看完整日志:

sudo find /var/lib/dkms/vendor_driver/1.2.3 \
  -type f -name make.log -exec tail -n 120 {} \;

应优先使用供应方针对该内核版本发布的驱动源代码或补丁,不建议直接删除错误检查、强制忽略编译错误或使用 --force 掩盖问题。

已编译但 modinfo 找不到模块

依次检查安装状态、文件路径和模块索引:

sudo dkms status -m vendor_driver -v 1.2.3 -k "$(uname -r)"
sudo find "/lib/modules/$(uname -r)" \
  -type f \( -name 'vendor_driver.ko*' -o -name 'vendor-driver.ko*' \) -print
sudo depmod -a "$(uname -r)"
modinfo vendor_driver

如果文件在 DKMS 的构建目录中,但不在 /lib/modules/$(uname -r) 下,说明只完成了 build,还没有完成 install。

七、常见失败及处理方式配图

modprobe 报 Invalid module format 或 Unknown symbol

先查看当前内核日志:

sudo journalctl -k -b --no-pager | tail -n 120

再核对模块的 vermagic:

uname -r
modinfo vendor_driver | grep -E '^(filename|vermagic):'

这类错误可能由以下原因造成:

  • 模块针对其他内核版本构建;
  • 当前内核配置与驱动要求不一致;
  • 依赖模块未加载或版本不匹配;
  • 驱动使用了目标内核不再提供的符号。

应重新指定正确的 -k 参数构建,并根据日志解决依赖或版本兼容问题。

Secure Boot 阻止模块加载

检查 Secure Boot 状态:

mokutil --sb-state
modinfo vendor_driver | grep -E '^(signer|sig_id):'

模块可以正常编译,但在 Secure Boot 开启时,未被系统信任密钥签名的模块可能在加载阶段被拒绝。此时应使用供应方提供的签名模块,或按照发行版的密钥管理流程完成签名和信任配置。不要把“关闭 Secure Boot”作为默认修复措施,尤其是在有明确启动安全要求的服务器上。

八、验收与回滚检查项

验收清单

首次部署完成后,至少确认以下项目:

  • uname -r 已记录,且内核构建目录与该版本一致;
  • dkms status 显示目标版本为 built 或 installed;
  • make.log 末尾没有编译错误;
  • /lib/modules/$(uname -r) 下存在对应的模块文件;
  • modinfo <模块名> 能读取 filename 和 vermagic;
  • modprobe -n -v <模块名> 能解析到正确路径;
  • 在维护窗口内加载模块后,lsmod 能看到模块;
  • journalctl -k -b 中没有 Unknown symbol、Invalid module format 或签名拒绝信息;
  • 按设备类型完成 PCI、USB、网络或其他实际功能检查;
  • 已保存变更前的 dkms status 和驱动源代码版本信息。

回滚前的影响确认

卸载模块可能影响正在使用该驱动的网卡、磁盘、显卡或其他硬件。尤其不要在根文件系统依赖的存储驱动、当前 SSH 链路使用的网卡驱动上直接执行卸载。

先查看模块是否正在使用:

lsmod | grep -E '^vendor_driver([[:space:]]|$)'

只有在确认没有业务依赖、设备处于维护状态时,才考虑卸载已加载模块:

sudo modprobe -r vendor_driver

如果模块仍被其他模块或设备占用,命令可能失败。此时不要强行使用高风险参数,应先停止相关业务或安排重启。

仅回滚当前内核的 DKMS 安装

如果需要移除当前内核下的该版本模块,可以指定精确内核版本:

MODULE="vendor_driver"
VERSION="1.2.3"
KERNEL="$(uname -r)"

sudo dkms remove -m "$MODULE" -v "$VERSION" -k "$KERNEL"
sudo depmod -a "$KERNEL"

该操作会删除指定内核下由 DKMS 安装的模块文件,不会删除其他内核的同版本模块。若要删除该版本在所有内核中的 DKMS 安装,命令范围更大:

sudo dkms remove -m vendor_driver -v 1.2.3 --all

执行 --all 前,应确认已经保存驱动源代码,并确认其他内核不再依赖该版本。不要直接删除 /var/lib/dkms/vendor_driver 或 /usr/src/vendor_driver-1.2.3,否则可能无法使用 DKMS 状态恢复。

恢复原有版本

如果服务器原先使用的是旧版驱动,应保留旧版本源代码并重新针对当前内核安装:

sudo dkms install -m vendor_driver -v 1.1.8 -k "$(uname -r)"
sudo depmod -a "$(uname -r)"

确认旧版本可被识别后,再在维护窗口内加载:

modinfo vendor_driver
sudo modprobe vendor_driver
lsmod | grep -E '^vendor_driver([[:space:]]|$)'

如果回滚依赖重启,例如原驱动已被加载、设备绑定状态尚未释放或内核模块依赖复杂,应先确认控制台或带外管理可用,再安排重启。回滚的验收标准仍然是:旧版本模块能够被 modinfo 识别、能够正常加载,并且对应设备恢复工作。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/8105.html

相关推荐