我追了一遍 Kbuild: 从一行 obj-m 到可以加载的 Linux 内核模块

先把实验钉在具体版本上#

我的实验环境如下：

内核和外部模块统一使用 GCC 15.2.0 与 GNU Binutils 2.46。正式构建也应复用目标内核的工具链、配置和构建目录，因为 Linux 不向外部模块提供稳定的内核内 ABI。

我用下面的源码固定分析基准：

1
git clone --depth 1 --branch v6.18 \
2
  https://github.com/torvalds/linux.git linux-6.18

Linux 6.18 是这里的机制快照。后续版本可能移动规则、拆分生成文件或改变命令行，所以文中的源码链接都锁在 v6.18 标签。

先做出一个真的 .ko#

目录只有 5 个输入文件：

1
pocket-sensor/
2
├── Kbuild
3
├── Makefile
4
├── core.c
5
├── stats.c
6
└── pocket_sensor.h

core.c 负责模块生命周期和参数：

1
#include <linux/init.h>
2
#include <linux/module.h>
3

4
#include "pocket_sensor.h"
5

6
static char *label = "desk";
7
module_param(label, charp, 0444);
8
MODULE_PARM_DESC(label, "Sensor label");
9

10
static unsigned int samples = 4;
11
module_param(samples, uint, 0444);
12
MODULE_PARM_DESC(samples, "Number of synthetic samples");
13

14
static int __init pocket_sensor_init(void)
15
{
16
  int ret;
17

18
  ret = pocket_stats_start(samples);
19
  if (ret)
20
    return ret;
21

22
  pr_info("pocket_sensor: loaded label=%s samples=%u\n",
23
    label, samples);
24
  return 0;
25
}
26

27
static void __exit pocket_sensor_exit(void)
28
{
29
  pr_info("pocket_sensor: unloaded samples=%u\n",
30
    pocket_stats_stop());
31
}
32

33
module_init(pocket_sensor_init);
34
module_exit(pocket_sensor_exit);
35

36
MODULE_AUTHOR("bfmhno3");
37
MODULE_DESCRIPTION("Small Kbuild experiment");
38
MODULE_LICENSE("GPL");

stats.c 提供第二个编译单元：

1
#include <linux/errno.h>
2
#include <linux/slab.h>
3
#include <linux/types.h>
4

5
#include "pocket_sensor.h"
6

7
static u32 *values;
8
static unsigned int value_count;
9

10
int pocket_stats_start(unsigned int count)
11
{
12
  unsigned int i;
13

14
  if (!count || count > 4096)
15
    return -EINVAL;
16

17
  values = kcalloc(count, sizeof(*values), GFP_KERNEL);
18
  if (!values)
19
    return -ENOMEM;
20

21
  for (i = 0; i < count; i++)
22
    values[i] = i;
23
  value_count = count;
24
  return 0;
25
}
26

27
unsigned int pocket_stats_stop(void)
28
{
29
  unsigned int count = value_count;
30

31
  kfree(values);
32
  values = NULL;
33
  value_count = 0;
34
  return count;
35
}

头文件只是两个编译单元之间的接口：

1
#ifndef POCKET_SENSOR_H
2
#define POCKET_SENSOR_H
3

4
int pocket_stats_start(unsigned int count);
5
unsigned int pocket_stats_stop(void);
6

7
#endif

真正交给 Kbuild 的文件只有两行：

1
obj-m += pocket_sensor.o
2
pocket_sensor-y := core.o stats.o

第一行声明最终模块，第二行声明组成这个模块的对象。pocket_sensor-y 里的 y 不是说整个模块内建；它表示这些对象无条件组成 pocket_sensor.o。最终走内建还是模块路径，仍由外层的 obj-y 或 obj-m 决定。

为了让目录里直接执行 make，我另外放一个很薄的包装 Makefile：

1
KDIR ?= /path/to/linux-6.18-build
2

3
.PHONY: all clean
4
all:
5
  $(MAKE) -C $(KDIR) M=$(CURDIR) modules
6

7
clean:
8
  $(MAKE) -C $(KDIR) M=$(CURDIR) clean

KDIR 指向已经配置并完成构建的 Linux 6.18 输出目录。只运行 modules_prepare 可以补齐很多生成头和脚本，但在 CONFIG_MODVERSIONS=y 时，它不会生成 Module.symvers。我这次完整构建了实验内核和 modules 目标，避免把缺失符号版本伪装成模块问题。

第一次构建输出是：

1
$ make
2
  CC [M]  core.o
3
  CC [M]  stats.o
4
  LD [M]  pocket_sensor.o
5
  MODPOST Module.symvers
6
  CC [M]  pocket_sensor.mod.o
7
  CC [M]  .module-common.o
8
  LD [M]  pocket_sensor.ko

干净构建耗时 1.78 秒，立刻再构建一次耗时 0.89 秒，第二次没有执行任何 CC、LD 或 MODPOST。这里的绝对时间包含启动多层 Make 的固定成本，不适合拿去跑编译器排行榜；有趣的是工作量从 7 个构建动作降到了 0。

5 个输入文件旁边出现了 19 个生成文件：

1
core.o
2
stats.o
3
pocket_sensor.mod
4
pocket_sensor.o
5
modules.order
6
Module.symvers
7
pocket_sensor.mod.c
8
pocket_sensor.mod.o
9
.module-common.o
10
pocket_sensor.ko
11
.core.o.cmd
12
.stats.o.cmd
13
.pocket_sensor.mod.cmd
14
.pocket_sensor.o.cmd
15
.pocket_sensor.mod.o.cmd
16
.pocket_sensor.ko.cmd

此外还有为 modules.order、Module.symvers 和 .module-common.o 保存命令的 3 个隐藏 .cmd 文件。连同上面的 16 项，总数是 19。Kbuild 很像一条留下完整货运单的装配线：.ko 是箱子，旁边这些小文件告诉它箱子为什么需要重新装。

成品大小为 6944 字节：

1
core.o               4064 bytes
2
stats.o              1608 bytes
3
pocket_sensor.o      5136 bytes
4
pocket_sensor.mod.o  2448 bytes
5
pocket_sensor.ko     6944 bytes

我还编译了一个只有单个 .c 的最小模块。它生成 4552 字节的 .ko 和 15 个派生文件；双文件实验生成 19 个派生文件。两个模块行为不同，所以 2392 字节的体积差不能全算作”多文件税”。真正由复合模块新增的关键动作，是把两个局部 .o 用 ld -r 合成最终的 pocket_sensor.o。

make -C ... M=... modules 为什么像走了两遍？#

命令是：

1
make -C "$KDIR" M="$PWD" modules

如果把包装逻辑和 Kbuild 声明写在同一个 Makefile，传统写法会检查 KERNELRELEASE：

1
ifneq ($(KERNELRELEASE),)
2
obj-m += pocket_sensor.o
3
pocket_sensor-y := core.o stats.o
4
else
5
KDIR ?= /path/to/linux-6.18-build
6
all:
7
  $(MAKE) -C $(KDIR) M=$(CURDIR) modules
8
endif

第一次读取时，普通 Make 看见 all 并调用内核。第二次进入 Kbuild 后，KERNELRELEASE 已经存在，于是同一文件只暴露 obj-m。我选择独立的 Kbuild 文件后，不再需要这个分支；Kbuild 会优先读取 Kbuild，找不到才读取 Makefile。

Linux 6.13 以后还支持 -f 入口，它不要求先切换工作目录：

1
make -f "$KDIR/Makefile" M="$PWD" modules

两种入口最终进入同一套规则。这里的”两遍”不是 GNU Make 神秘地重复编译，而是包装层和内核构建层各读一次自己负责的描述。

1
make -C "$KDIR" M="$PWD" MO="$PWD/out" modules

一行 obj-m 怎样进入 scripts/Makefile.build？#

上一篇文章已经追到这个入口：

1
build := -f $(srctree)/scripts/Makefile.build obj

内核随后用近似下面的子 Make 调用处理一个目录：

1
make -f scripts/Makefile.build obj=<current-directory>

Linux 6.18 的 scripts/Makefile.build 先清空 obj-y、obj-m、flags 等局部变量，再按顺序读入配置和规则：

这解释了为什么一个目录中的 Kbuild 可以非常短。公共文件已经定义了如何编译 .c、怎样保存命令、如何归档 built-in.a、怎样生成 modules.order。目录文件只声明输入图，不重复写编译器菜谱。

对这两行输入：

1
obj-m += pocket_sensor.o
2
pocket_sensor-y := core.o stats.o

Makefile.build 算出几组直接影响实验的集合：

1
obj-m       = pocket_sensor.o
2
multi-obj-m = pocket_sensor.o
3
real-obj-m  = core.o stats.o

multi-obj-m 是需要部分链接的复合模块。real-obj-m 是真正从源码生成的叶子对象。scripts/Makefile.lib 再通过 part-of-module 给叶子编译追加 -DMODULE、KBUILD_MODNAME 等 flags。我的 V=1 输出中，core.c 的命令确实带有：

1
-DMODULE
2
-DKBUILD_BASENAME='"core"'
3
-DKBUILD_MODNAME='"pocket_sensor"'

Kbuild 先生成一个内容只有两行的响应文件 pocket_sensor.mod：

1
./core.o
2
./stats.o

然后执行实质上的：

1
ld -r -o pocket_sensor.o @pocket_sensor.mod

-r 产生仍可重定位的合并对象，不把它链接成用户空间可执行文件。此时 core.o 对 pocket_stats_start() 的未解析引用由同一次部分链接中的 stats.o 满足。这个阶段像把两个零件焊成一个仍带接口的总成，内核符号的插头还留在外面，稍后加载器再接。

obj-y 和 obj-m 也可能错误地同时列出同一个对象。Linux 6.18 明确执行：

1
obj-m := $(filter-out $(obj-y),$(obj-m))

也就是内建版本优先，模块副本被移除。Kbuild 不会为同一个目标同时制造一份内建对象和一份 .ko，然后让我们猜哪份算数。

完整的模块前半段现在变成：

.cmd 才是增量构建的记忆#

core.o 构建后，.core.o.cmd 开头保存完整命令：

1
savedcmd_core.o := gcc ... -DMODULE ... -c -o core.o core.c
2
source_core.o := core.c

后面是一长串真实依赖。例如 core.c 包含的 linux/module.h 使用了模块开关，因此文件中出现：

1
$(wildcard include/config/MODULES)
2
$(wildcard include/config/MODULE_UNLOAD)

规则链是：

if_changed_dep 会在目标缺失、普通依赖更新或保存的命令变化时重建。fixdep 还会扫描依赖文件里出现的 CONFIG_FOO，把它转成 include/config/FOO 标记依赖。它并不完整解析 C；Linux 6.18 的源码注释甚至直说，注释中出现的 CONFIG_FOO 也会被抓到。多编一次可以接受，漏编一次不行。

我实际做了 4 轮增量实验：

配置依赖不需要额外造一个与模块无关的开关。后面的树内迁移直接用 CONFIG_POCKET_SENSOR 和 CONFIG_POCKET_SENSOR_STATS 验证：切换 n/m/y 后，Kbuild 会选择不编译、生成 .ko 或进入 vmlinux。目标内核配置或构建目录改变后，外部模块则应对匹配的新构建树做干净重建，不要复用旧 .o。

modpost 不是又一个链接器#

第一阶段结束时，我们已经有 pocket_sensor.o、pocket_sensor.mod 和 modules.order。modules.order 在这个实验里只有：

1
pocket_sensor.o

它记录 Kbuild 发现模块的顺序。随后 scripts/Makefile.modpost 调用主机程序 scripts/mod/modpost。modpost 主要做静态审查和元数据生成：

这里有一个很好用的失败实验。我最初只构建了 bzImage，没有构建内核的 modules 目标，于是目标输出树中缺少 Module.symvers。modpost 没有含糊地吐出一个坏 .ko，而是列出：

1
WARNING: .../Module.symvers is missing.
2
ERROR: modpost: "param_ops_uint" [pocket_sensor.ko] undefined!
3
ERROR: modpost: "__kmalloc_noprof" [pocket_sensor.ko] undefined!
4
ERROR: modpost: "kfree" [pocket_sensor.ko] undefined!
5
ERROR: modpost: "_printk" [pocket_sensor.ko] undefined!
6
ERROR: modpost: "param_ops_charp" [pocket_sensor.ko] undefined!

运行内核的 make modules 生成 Module.symvers 后，同一个模块通过。这正是 modpost 的价值：在 QEMU 启动前就指出内核符号账本不完整。

Linux 6.18 为我的模块生成了很短的 pocket_sensor.mod.c：

1
#include <linux/module.h>
2
#include <linux/export-internal.h>
3
#include <linux/compiler.h>
4

5
MODULE_INFO(name, KBUILD_MODNAME);
6

7
__visible struct module __this_module
8
__section(".gnu.linkonce.this_module") = {
9
  .name = KBUILD_MODNAME,
10
  .init = init_module,
11
#ifdef CONFIG_MODULE_UNLOAD
12
  .exit = cleanup_module,
13
#endif
14
  .arch = MODULE_ARCH_INIT,
15
};
16

17
MODULE_INFO(depends, "");

这段代码把模块名、入口、退出函数和依赖写成内核加载器认识的结构。它被编译为 pocket_sensor.mod.o。

旧文章常把 vermagic 也指向 <module>.mod.c。Linux 6.18 已经把公共部分放进 scripts/module-common.c，编译为 .module-common.o；其中包含：

1
MODULE_INFO(vermagic, VERMAGIC_STRING);

所以最终输入比常见简图多一个对象：

版本锁定在这里立刻有了价值。机制没变，但元数据从哪一个生成文件进入 .ko 已经变了。

.ko 仍然是一个可重定位 ELF#

scripts/Makefile.modfinal 最终执行近似下面的链接：

1
ld -r -T scripts/module.lds \
2
  -o pocket_sensor.ko \
3
  pocket_sensor.o pocket_sensor.mod.o .module-common.o

readelf -h pocket_sensor.ko 给出：

1
Class:   ELF64
2
Data:    little endian
3
Type:    REL (Relocatable file)
4
Machine: Advanced Micro Devices X86-64
5
Entry:   0x0

它没有用户程序那种固定入口地址，也还没有落到最终运行地址。readelf -SW 在 6944 字节中找到了 31 个 section，其中最关键的是：

1
.text
2
.init.text
3
.exit.text
4
.modinfo
5
__param
6
.gnu.linkonce.this_module
7
.rela.text
8
.rela.init.text
9
.rela.exit.text

__init 把初始化函数放进 .init.text，__exit 把退出函数放进 .exit.text。module_param() 产生 __param 数据，MODULE_* 宏向 .modinfo 填字符串，链接器保留 relocation section 等待内核处理。

readelf -Ws 还能看到尚未解析的内核符号：

1
UND param_ops_uint
2
UND __kmalloc_noprof
3
UND kfree
4
UND _printk
5
UND param_ops_charp

这不是链接失败留下的垃圾。模块必须调用当前内核提供的分配器、日志和参数实现，所以 .ko 有意保留这些外部引用。modpost 已用 Module.symvers 检查它们是否合法，内核加载器稍后给它们填入运行地址。

modinfo 则把 .modinfo 翻译成人容易读的结果：

1
filename:    pocket_sensor.ko
2
license:     GPL
3
description: Small Kbuild experiment
4
author:      bfmhno3
5
depends:
6
name:        pocket_sensor
7
vermagic:    6.18.0 mod_unload
8
parm:        label:Sensor label (charp)
9
parm:        samples:Number of synthetic samples (uint)

到这里，.ko 已经不神秘了。它是一个附带模块元数据、参数描述、未解析内核符号和重定位记录的 ELF relocatable object。

我把它真的装进了 Linux 6.18#

我没有向宿主机加载实验模块。宿主机是工作环境，不是祭坛。我构建了一个精简的 x86_64 Linux 6.18、一个 1,422,848 字节的 initramfs，然后用 QEMU 启动：

1
qemu-system-x86_64 \
2
  -machine accel=tcg \
3
  -cpu max \
4
  -m 256M \
5
  -smp 1 \
6
  -nographic \
7
  -no-reboot \
8
  -kernel arch/x86/boot/bzImage \
9
  -initrd initramfs.cpio \
10
  -append "console=ttyS0 rdinit=/init panic=-1"

/init 挂载 /proc 和 /sys，然后执行：

1
insmod /pocket_sensor.ko label=qemu samples=7
2
cat /sys/module/pocket_sensor/parameters/label
3
cat /sys/module/pocket_sensor/parameters/samples
4
rmmod pocket_sensor

串口日志是：

1
=== pocket_sensor experiment ===
2
pocket_sensor: loading out-of-tree module taints kernel.
3
pocket_sensor: loaded label=qemu samples=7
4
label=qemu
5
samples=7
6
pocket_sensor: unloaded samples=7
7
=== experiment complete ===

两个参数真的进入 /sys/module/pocket_sensor/parameters/，stats.c 分配的 7 个槽位在卸载时释放，初始化和退出日志各出现一次。外部模块 taint 也符合预期；它表示内核装入了树外代码，不表示实验失败。

4 类错误分别在说什么？#

模块错误经常只在终端留下一句短话，真正上下文在内核日志。我的排查顺序是先看 dmesg，再把错误放回加载链。

把 obj-m 换成 obj-y 会发生什么？#

模块路径现在完整了，但上一篇真正留下的问题还有一半：CONFIG_FOO=y 去了哪里？

对树内目录，父级 Makefile 写：

1
obj-$(CONFIG_POCKET_SENSOR) += pocket_sensor/

当值为 y，scripts/Makefile.build 递归进入目录，并把子目录的内建对象装进：

1
drivers/misc/pocket_sensor/built-in.a

Linux 6.18 使用：

1
ar cDPrST built-in.a ...

其中 T 创建 thin archive。它主要保存成员路径，不复制每个 .o 的完整内容。我的归档由两个成员组成：

1
drivers/misc/pocket_sensor/core.o
2
drivers/misc/pocket_sensor/stats.o

目录层级继续向上汇聚：

顶层 Makefile 用 KBUILD_VMLINUX_OBJS 生成 vmlinux.a，scripts/Makefile.vmlinux_o 通过 --whole-archive vmlinux.a 生成 vmlinux.o，scripts/link-vmlinux.sh 再完成架构相关的最终链接。y 状态不会生成或更新 pocket_sensor.ko；若刚从 m 切到 y，输出树里可能仍留着旧 .ko，它只是陈旧产物，make clean 才会移除。

modules.builtin 中仍会记录一个逻辑路径：

1
kernel/drivers/misc/pocket_sensor/pocket_sensor.ko

它告诉 modprobe 这个模块名已经内建，不表示磁盘上真的生成了那份 .ko。我的 System.map 则能找到 pocket_sensor_init、pocket_stats_start 和对应 initcall，证明代码已经进入 vmlinux。

我把外部模块迁回了内核树#

实验目录改为：

1
drivers/misc/pocket_sensor/
2
├── Kconfig
3
├── Makefile
4
├── core.c
5
├── stats.c
6
└── pocket_sensor.h

父级 drivers/misc/Kconfig 加一行：

1
source "drivers/misc/pocket_sensor/Kconfig"

配置文件为：

1
config POCKET_SENSOR
2
  tristate "Pocket sensor experiment"
3
  help
4
    Build the pocket sensor used to trace the Kbuild pipeline.
5

6
config POCKET_SENSOR_STATS
7
  bool "Pocket sensor statistics"
8
  depends on POCKET_SENSOR
9
  default y
10
  help
11
    Add the synthetic sample storage used by the experiment.

父级 drivers/misc/Makefile 决定是否进入目录：

1
obj-$(CONFIG_POCKET_SENSOR) += pocket_sensor/

子目录 Makefile 决定总成和可选零件：

1
obj-$(CONFIG_POCKET_SENSOR) += pocket_sensor.o
2
pocket_sensor-y := core.o
3
pocket_sensor-$(CONFIG_POCKET_SENSOR_STATS) += stats.o

当 statistics 关闭时，头文件提供不分配内存的 inline 实现；当它打开时，stats.o 进入复合对象。这样配置和链接图一致，不会让 core.o 留下无人提供的函数。

我在同一个 Linux 6.18 输出树里验证了 3 种状态：

y 状态的增量构建日志把路径完整打印出来：

1
CC      drivers/misc/pocket_sensor/core.o
2
CC      drivers/misc/pocket_sensor/stats.o
3
AR      drivers/misc/pocket_sensor/built-in.a
4
AR      drivers/misc/built-in.a
5
AR      drivers/built-in.a
6
AR      built-in.a
7
AR      vmlinux.a
8
LD      vmlinux.o
9
MODPOST vmlinux.symvers
10
LD      vmlinux.unstripped
11
OBJCOPY vmlinux

这也把两篇文章真正接上了：

外部模块和树内模块的维护边界#

两条路径共享 Kbuild 语法和大量编译规则，但维护契约不同。

DKMS 解决的是自动重编与安装流程，不会把不稳定的内核 ABI 变稳定。

树内也不是把目录复制到 drivers/ 就结束。正式驱动还要遵守子系统接口、代码风格、MAINTAINERS、文档与设备绑定规范，并写出准确的 Kconfig 依赖。我的 pocket_sensor 故意没有 platform bus、Device Tree、I2C 或真实寄存器访问；伪造硬件只会让 Kbuild 主线被一堆无意义的驱动样板淹没。

ARM64 工程只多哪一层？#

Kbuild 数据流不因架构改变。交叉构建 ARM64 外部模块时，通常在内核配置、内核构建和模块构建中保持同一组变量：

1
make O="$KOUT" \
2
  ARCH=arm64 \
3
  CROSS_COMPILE=aarch64-linux-gnu- \
4
  my_board_defconfig
5

6
make O="$KOUT" \
7
  ARCH=arm64 \
8
  CROSS_COMPILE=aarch64-linux-gnu- \
9
  -j"$(nproc)"
10

11
make -C "$KOUT" \
12
  M="$PWD" \
13
  ARCH=arm64 \
14
  CROSS_COMPILE=aarch64-linux-gnu- \
15
  modules

新增的是目标架构、交叉工具链和真实板卡的启动链，不是第二套 obj-m -> modpost -> .ko 机制。加载时仍要保证运行内核就是这份配置和符号账本对应的内核。

继续往下追#

这次我从 2 行 Kbuild 得到了一个 6944 字节的 ELF，在 QEMU 中给它传入 2 个参数，观察它分配 7 个样本槽位，再完整卸载。沿途最让我意外的不是链接器，而是那些小账本：.cmd 记住命令和依赖，pocket_sensor.mod 记住复合对象，modules.order 记住模块顺序，Module.symvers 记住内核可见符号，.mod.c 把入口写回 C。

如果继续向下走，下一站应该是真实总线和设备模型：让同一个模块不再凭 insmod 自说自话，而是由 Device Tree 描述硬件，由 platform 或 I2C core 完成匹配，再看 probe、defer 和 remove 如何与 Kbuild 产物相遇。到那时 .ko 已经不是神秘黑盒，只是驱动生命周期被装进 ELF 后的运输形态。

很好。我现在可以停止盯着 obj-m 猜 Make 的心情，开始给那块并不存在的传感器寻找一块真正的板子了。

参考资料#

• Linux 6.18: Building External Modules
• Linux 6.18: Linux Kernel Makefiles
• Linux 6.18: scripts/Kbuild.include
• Linux 6.18: scripts/Makefile.build
• Linux 6.18: scripts/Makefile.lib
• Linux 6.18: scripts/Makefile.modpost
• Linux 6.18: scripts/Makefile.modfinal
• Linux 6.18: scripts/module-common.c
• Linux 6.18: scripts/link-vmlinux.sh
• Linux 6.18: kernel/module/main.c
• Linux 6.18: Module signing facility