Linux上用DKMS构建驱动需要哪些准备,怎样确认模块编译成功
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 |
| 编译器和 Make | gcc --version、make --version | 日志出现 command not found |
| DKMS | dkms --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



