4. 内核模块编译环境搭建：内核头文件安装、Makefile编写、Kbuild系统、交叉编译注意事项

内核模块的编译环境与普通用户态程序有本质区别。模块必须与目标内核的符号版本、数据结构布局、宏定义完全一致，否则加载时会报 Invalid module format 或 Unknown symbol 错误。本章从零搭建编译环境，覆盖头文件安装、Makefile 模板、Kbuild 机制以及交叉编译的关键陷阱。

4.1 内核头文件安装

根据发行版和内核来源，安装方式分为以下三种场景：

安装完成后，/lib/modules/$(uname -r)/build/ 应包含以下关键子目录：

• include/ — 内核 API 头文件（linux/, asm-generic/, uapi/）
• arch/ — 体系结构相关代码（x86、arm64 等）
• scripts/ — Kbuild 辅助脚本（modpost, recordmcount 等）
• Module.symvers — 已导出符号的 CRC 校验表

4.2 Makefile 编写与 Kbuild 系统

Linux 内核模块使用 Kbuild（Kernel Build System）编译，而非传统的 Makefile 变量赋值。Kbuild 通过 obj-m 变量指定哪些 .c 文件编译为模块，内核源码树的顶层 Makefile 会递归处理这些目标。

4.2.1 最小 Makefile 模板

# Makefile — 单文件模块
obj-m := syscall_hook.o

KDIR  := /lib/modules/$(shell uname -r)/build
PWD   := $(shell pwd)

all:
	$(MAKE) -C $(KDIR) M=$(PWD) modules

clean:
	$(MAKE) -C $(KDIR) M=$(PWD) clean

关键变量说明：

• obj-m — 指定要编译的模块目标文件（不含路径，不含 .ko 后缀）
• KDIR — 指向内核构建树，Kbuild 在此查找顶层 Makefile 和配置文件
• -C $(KDIR) — 切换到内核源码目录执行 make
• M=$(PWD) — 告诉 Kbuild 返回当前目录编译模块

4.2.2 多文件模块

当模块由多个源文件组成时，需要额外定义模块名与源文件列表：

# Makefile — 多文件模块
obj-m := hook_main.o
hook_main-objs := main.o utils.o syscall_table.o

KDIR  := /lib/modules/$(shell uname -r)/build
PWD   := $(shell pwd)

all:
	$(MAKE) -C $(KDIR) M=$(PWD) modules

clean:
	$(MAKE) -C $(KDIR) M=$(PWD) clean

此时 hook_main-objs 列出所有 .o 文件，Kbuild 会将其链接为 hook_main.ko。

4.2.3 Kbuild 系统工作流程

4.3 交叉编译注意事项

当开发环境（x86_64）与目标运行环境（ARM64、ARM32、RISC-V 等）架构不同时，必须进行交叉编译。以下是必须调整的配置项：

4.3.1 交叉编译 Makefile 模板

# Makefile — 交叉编译版本
obj-m := syscall_hook.o

ARCH        ?= arm64
CROSS_COMPILE ?= aarch64-linux-gnu-
KDIR        ?= /path/to/linux-arm64
PWD         := $(shell pwd)

all:
	$(MAKE) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) \
		-C $(KDIR) M=$(PWD) modules

clean:
	$(MAKE) -C $(KDIR) M=$(PWD) clean

4.3.2 常见陷阱与解决方案

• 头文件路径错误： 必须使用目标架构的 build/include，而非本机 /usr/include。检查 KDIR 下的 arch/arm64/include 是否存在。
• 工具链不匹配： CROSS_COMPILE 前缀必须与已安装的交叉编译器一致。运行 aarch64-linux-gnu-gcc --version 验证。
• Module.symvers 缺失： 交叉编译时，目标内核的 Module.symvers 必须存在，否则模块加载会报 Unknown symbol。从目标设备复制或在内核编译时生成。
• 内核配置差异： 目标内核的 .config 必须启用 CONFIG_MODULES=y 和 CONFIG_KALLSYMS=y（系统调用表 Hook 必需）。

4.4 编译验证与模块信息

编译成功后，使用 modinfo 检查模块元数据：

$ modinfo syscall_hook.ko
filename:       /home/user/syscall_hook.ko
license:        GPL
description:    System call table hook demo
author:         Kernel Expert
depends:        
retpoline:      Y
name:           syscall_hook
vermagic:       5.15.0-91-generic SMP mod_unload modversions aarch64

vermagic 字段必须与目标内核的 uname -r 输出完全一致（包括 SMP、preempt 等标记），否则模块加载失败。