Linux GPU KMD驱动开发环境搭建实战指南

写GPU驱动，尤其是KMD这一层，跟普通软件开发完全是两种体验。普通应用挂了一个panic还能输出日志，KMD里的GPU一旦卡死，往往先挂掉的是整个桌面和显示输出，你连看日志的机会都没有。这种“一着不慎满盘皆输”的开发模式，逼着你在环境搭建阶段就把基础设施做到位。我做GPU驱动开发这些年，见过太多次新人卡在环境上：模块编译不过、加载被拒、日志刷不出来、GPU挂死不知道从哪里入手。这一篇KMD开发环境搭建，就是要把整个系列动手实操前的最后一道工序做扎实。适合第一次接触内核GPU驱动的新手，也适合已经有内核开发基础、想深入GPU KMD路线的工程师。这里所有的操作都以Linux开源内核生态为主线展开，讲清楚环境是什么、为什么这么搭、出问题了怎么排查。

1. KMD环境搭建前必须搞清楚的三件事

1.1 KMD在GPU驱动栈里的位置

很多人以为GPU驱动就是装个厂商SDK，实际GPU驱动栈是一个分层明确的体系。最上层是应用API，比如Vulkan、OpenGL、DX，调用方是游戏引擎或图形库；中间是用户态驱动UMD，负责把图形命令翻译成硬件能理解的命令缓冲区，管理资源状态；最底层才是KMD，运行在内核态，负责PCIe设备枚举、显存管理、GPU命令提交、中断处理、电源管理这些事情。

KMD在整个链路里的位置很关键。它不直接画三角形，而是给上层提供稳定的执行通道。就像机场的塔台，你看到的飞机起落是道面上的事，但真正决定飞机能不能滑进跑道、停到哪个机位、会不会撞机的是塔台的调度规则。KMD就是这个塔台，出了问题，整个机场的航班节奏都会崩。

这个系列的前两节重点都在KMD开发基础，环境搭建自然也要围绕KMD的工作场景来准备。你后面要改的代码、要观测的状态、要调试的崩溃点，全部集中在内核态，所以环境不能照搬用户态那套IDE调试思路。

1.2 环境的核心组成与分类

把KMD开发环境拆开看，其实就四块东西：

• 宿主系统与内核：操作系统、内核版本、Secure Boot状态、内核模块加载策略
• 编译与构建体系：内核头文件、build目录、gcc、make，以及Kbuild的模块构建流程
• 运行与观测设施：dmesg、debugfs、tracefs、图形栈验证工具，负责确认驱动加载和行为
• 崩溃与深度调试装备：kdump、kgdb、串口、crash工具，处理GPU挂死这种极端场景

这四块是层层依赖的关系。宿主系统是地基，编译体系决定了你能不能生成一个合法的 .ko 文件，运行观测设施决定你加载后能不能看到效果，崩溃调试装备决定出大事时能不能找到现场。搭建的时候按这个顺序来，不要一上来就折腾内核源码编译，那是后面的事。

1.3 常见的环境搭建误区

我见过太多人死磕在环境上，原因基本是下面这几种：

第一，用了与目标内核版本不一致的头文件，编译时各种诡异报错，还以为是代码问题；第二，不关闭Secure Boot，模块加载被拒，只能反复重启改设置；第三，没有提前准备崩溃日志手段，GPU一挂只能拔电源，重启后什么线索都找不到；第四，在Windows上用闭源驱动开发，想改内核态逻辑但根本没有源码可看，最后进退两难。

这些问题看起来小，但在环境搭建阶段不解决，后面会把时间成倍地消耗在重复尝试上。这一节接下来的内容就是逐个把这些坑填平，给你一条可以直接走通的路径。

2. 硬件与操作系统准备：别在这一步省时间

2.1 GPU选型的三个原则

做KMD开发选显卡不是看性能跑分，而是看能不能拿到内核里那一层驱动的源代码。这一点决定了你后面能改什么、能学什么。目前主流的开源KMD方案有三条线：

• Intel核显：i915和xe驱动都在Linux内核源码树里，框架标准，文档多，适合新手入门
• AMD Radeon：amdgpu是Linux内核里最完整也最复杂的开源GPU驱动之一，功能覆盖全面，适合深入剖析
• NVIDIA：官方闭源驱动改不了，nouveau是社区逆向实现的，坑多但也能学到不少东西

个人建议，学习阶段优先选Intel核显或AMD入门卡，原因是你能在真实硬件上跑通完整链路。如果手头只有虚拟机环境，可以用virtio-gpu这类虚拟设备先熟悉驱动框架，但到了显存映射、GPU中断这些KMD核心点上，仍然需要真实GPU来验证。

2.2 主机环境的硬件底线

硬件配置方面，不需要追求顶级，但也不要太拮据。CPU建议x86_64架构的普通桌面或服务器芯片即可，核心数越多越好，因为你后面可能要完整编译内核。内存最少16GB，如果打算开虚拟机、跑图形测试外加编译内核，32GB会更舒服。

磁盘空间建议留出至少50GB。这个数字不是随便写的：Linux内核源码解压后大约10多GB，编译过程中还会生成大量中间文件，再加上Mesa源码、图形测试程序、系统本身占用的空间，50GB是一个比较稳妥的下限。

我遇到过一位学员用8GB内存的机器来搭环境，编译内核时直接OOM，最后不得不加Swap硬扛，整个过程非常痛苦。环境搭建这种一次性投入，宁可稍微多花点预算，也别让自己在后续开发中反复被性能卡脖子。

2.3 操作系统与内核版本锁定

操作系统建议直接用Ubuntu LTS版本，比如22.04或24.04。原因有两个：一是LTS内核带长期维护，官方仓库里的内核头文件和工具链版本匹配稳定；二是社区踩坑记录最多，任何环境问题都能搜到对应的解决方案。不要用太新的非LTS版本，也不要一上来就切到内核主线，除非你已经很熟悉内核开发流程。

安装好系统之后，有一件事必须做：锁定内核版本。不要随意执行系统升级，那可能会把内核换掉，导致你编译模块用的头文件与实际运行内核不匹配。具体来说，先执行uname -r确认当前内核版本，然后安装对应版本的linux-headers包：

uname -r sudo apt install -y linux-headers-$(uname -r)

如果要进行更深入的内核调试，比如改内核调度代码、加trace点，那就需要拉一套完整内核源码并自己编译安装。这个动作的耗时比编译单个模块大得多，但对后续学习极有价值，可以完全掌控内核版本和配置。

还有一个容易被忽略的点：Secure Boot。如果主板开启了Secure Boot，未签名的内核模块加载会被拒绝，报错类似“Module verification failed”。开发机上我一般直接关掉Secure Boot，省得每编一个模块就要处理签名问题。生产环境当然会有更严格的安全策略，但开发机图的就是快速迭代，没必要在签名上反复折腾。

3. 编译工具链与调试基础设施安装

3.1 内核模块编译的硬前置条件

KMD的本质是内核模块，所以编译环境首先必须是内核模块编译环境。这句话听起来像废话，但很多人第一次编译 .ko 文件时都会踩坑：直接用普通gcc编译一个包含linux/xxx.h的C文件，结果在include上崩溃。原因很简单，你没有用内核的构建系统来组织编译。

内核模块的编译不是自己写链接命令，而是通过make -C <内核build目录> M=<模块目录> modules的方式，让内核Kbuild系统处理好include路径、链接规则和各种依赖。所以前置条件其实就三个：编译器、make工具、内核build目录。

在Ubuntu上，安装基础工具的命令很直接：

sudo apt update sudo apt install -y build-essential linux-headers-$(uname -r) kmod dkms git curl

build-essential会带来gcc、make、binutils这些核心工具。kmod用于管理内核模块，dkms以后可以帮你处理外部驱动的自动重建。git和curl是拉代码、下载工具链用的，后面会频繁用到。

注意：内核模块的编译器版本要和编译内核时使用的gcc版本保持兼容，否则可能出现“version magic”不一致的报错。用系统自带的gcc配系统自带内核，这个组合最稳。

3.2 GPU驱动源码与图形栈依赖

KMD开发不是写个helloworld模块就结束，你会需要GPU驱动源码作为参照。开源GPU驱动通常就在内核源码树的drivers/gpu/drm目录下，amdgpu、i915、xe都在里面。如果你用发行版头文件方式编译模块，可以只针对单个子目录做模块构建；如果要改驱动本身的源码，建议拉一套完整内核源码。

图形栈验证也是KMD开发环境里重要的一环。用户在应用层跑Vulkan或者OpenGL，最终都会打到KMD上，所以环境里要准备一套可以运行图形API的工具。Ubuntu下的安装命令：

sudo apt install -y mesa-utils vulkan-tools libdrm-dev libwayland-dev libvulkan-dev

装完以后，用glxinfo和vulkaninfo能快速确认GPU设备是否被系统正确识别。这一步对KMD调试极其重要，因为KMD是否成功加载、是否注册了设备节点，最直观的信号就是图形API能不能列出GPU。

如果要直接查看GPU寄存器映射，可以装devmem工具。这个工具能直接读写物理地址，权限相当于root级别的操作，只建议在开发机上使用。我在排查KMD初始化失败时经常用它检查BAR空间里的寄存器值，效率很高，但一定要清楚自己访问的是什么地址。

3.3 必配的内核调试与崩溃分析工具

GPU KMD最容易出的问题就是整机卡死。GPU一旦挂掉，屏幕冻结、系统无响应，常规日志排查根本来不及做，必须提前把内核调试手段准备好。我推荐从环境搭建阶段就配置好下这些工具：

• ftrace/tracefs：追踪内核函数调用路径，适合分析命令提交和中断处理流程
• debugfs：很多驱动会把内部状态暴露到这里，比如显存使用、ringbuffer状态
• kgdb/kgdboc：通过串口外接调试机，在内核崩溃现场设断点
• kdump/crash：内核panic时抓取crash dump，离线分析
• pstore：把日志写入持久存储，重启后仍然可读

kgdb配置起来稍微麻烦一点，需要串口线和调试终端。但KMD开发场景里，这是最可靠的调试手段。没有kgdb的时候，GPU一挂你就只能干瞪眼；有kgdb，至少可以停下来看看内核栈、查变量。就算不常开，也要确保环境是配置好的。

4. 第一个可运行的PCI GPU KMD骨架

4.1 为什么先写骨架而不是直接读amdgpu

环境搭建完成之后，立刻进入核心实操，写一个最小的KMD骨架模块。很多教程一上来就让新人去读整个amdgpu源码，说这是“学习开源驱动”，结果面对几十万行代码和复杂的宏定义，新人根本不知道从哪里看起。

正确做法是先生成一个包含完整生命周期（加载、probe、remove、卸载）的模块框架，验证工具链和环境没有问题，再往上面挂真实GPU功能。骨架模块就像盖房子时的脚手架，先搭结构，再填充墙体。下面这个例子是一个标准的PCI GPU驱动骨架，包含pci_driver、设备ID表、probe和remove回调，结构跟你后面要读的任何真实GPU KMD都是一致的。

4.2 代码与Makefile

// tiny_gpu_kmd.c #include <linux/init.h> #include <linux/module.h> #include <linux/kernel.h> #include <linux/pci.h> #define DRIVER_NAME "tiny_gpu_kmd" static int tiny_gpu_probe(struct pci_dev *pdev, const struct pci_device_id *id) { int ret; ret = pci_enable_device(pdev); if (ret) { dev_err(&pdev->dev, "failed to enable device\n"); return ret; } pci_set_master(pdev); dev_info(&pdev->dev, "tiny GPU KMD probed, vendor=0x%04x device=0x%04x\n", pdev->vendor, pdev->device); return 0; } static void tiny_gpu_remove(struct pci_dev *pdev) { dev_info(&pdev->dev, "tiny GPU KMD removed\n"); pci_disable_device(pdev); } static const struct pci_device_id tiny_gpu_id_table[] = { { PCI_DEVICE(0x1234, 0x1111) }, { } }; MODULE_DEVICE_TABLE(pci, tiny_gpu_id_table); static struct pci_driver tiny_gpu_driver = { .name = DRIVER_NAME, .id_table = tiny_gpu_id_table, .probe = tiny_gpu_probe, .remove = tiny_gpu_remove, }; module_pci_driver(tiny_gpu_driver); MODULE_LICENSE("GPL"); MODULE_AUTHOR("KMD Learning"); MODULE_DESCRIPTION("A minimal PCI GPU KMD skeleton");

这段代码有三个核心点：pci_driver结构体的注册、设备ID表的匹配、probe/remove生命周期回调。真实驱动里这些都是同样结构，只是每个函数内部复杂得多。先把这三个点吃透，后面看任何厂商驱动都不会觉得陌生。

配套的Makefile也很简单：

# Makefile obj-m += tiny_gpu_kmd.o KERNELDIR ?= /lib/modules/$(shell uname -r)/build PWD := $(shell pwd) all: $(MAKE) -C $(KERNELDIR) M=$(PWD) modules clean: $(MAKE) -C $(KERNELDIR) M=$(PWD) clean

4.3 编译、加载与验证

把两个文件放在同一个目录下，执行编译：

make

如果没有报错，会生成tiny_gpu_kmd.ko。这个 .ko 文件就是你的第一个GPU KMD内核模块。编译时注意Kbuild输出里应该出现“Building modules, stage 2.”和“MODPOST”阶段，这说明整个构建流程正常走完。如果提示找不到build目录，说明linux-headers没装好，回到3.1节检查。

模块生成之后，加载验证：

sudo insmod tiny_gpu_kmd.ko dmesg | tail -n 10 sudo rmmod tiny_gpu_kmd dmesg | tail -n 10

第一次加载后，dmesg会显示模块被加载成功。由于这个骨架没有匹配的真实设备ID，probe回调一般不会被调用，日志里大概率只有module_init的输出，这是正常的。想让probe真正跑起来，要么开发机上挂一张vendor/device匹配的GPU，要么用QEMU模拟一个对应PCI设备，后者也适合在没有实体显卡的服务器上做KMD开发练习。

4.4 骨架之后的三条深入路径

骨架验证通过后，环境搭建主线就算完成了。接下来根据你的目标选深入方向：

• 内核框架路线：重点读drivers/gpu/drm下的公共框架，比如DRM、TTM、gem、scheduler子模块，先掌握通用抽象，再往KMD里填细节
• 厂商驱动路线：以amdgpu或i915为蓝本，对照设备树、显存BAR、MMIO寄存器，从一个功能点改起，比如加一个自定义寄存器读写接口
• 虚拟化路线：写一个virtio-gpu前端驱动，通过命令队列跟宿主机交互，适合对设备虚拟化感兴趣的开发者

我的建议是从DRM公共框架入手，因为这一层抽象了显存管理、fence、调度这些KMD通用的难题。掌握了它，再看任何真实驱动的实现都会觉得有章可循。

5. GPU专项调试环境：从用户态到硬件的全链路观测

5.1 debugfs与tracefs：看得见驱动内部状态

纯内核模块编译验证通过，只说明环境基本可用。真正的GPU KMD开发需要一套从用户态命令、到内核驱动、再到硬件响应的全链路观测手段。首当其冲的就是调试文件系统，把内核驱动的内部状态暴露出来。

挂载debugfs后，DRM子系统和各厂商驱动都会把状态放到 /sys/kernel/debug 下面：

sudo mount -t debugfs none /sys/kernel/debug cat /sys/kernel/debug/dri/0/state

以amdgpu为例，debugfs下还有umr、sensors、gpu_info等入口，可以查看GPU温度、功耗、寄存器状态。这些信息在做性能调优和故障排查时特别关键，比如你怀疑GPU频繁挂起，可以先看sensors里功耗和频率有没有异常，再结合tracefs里的调度函数调用去定位。

tracefs配合ftrace也是传统排查手段。ftrace可以跟踪内核函数调用，用一条命令把函数追踪打开，然后跑图形测试，就能看到KMD里哪些函数被反复执行。这个对定位命令提交路径是否正常非常有效。

5.2 图形验证工具集

KMD开发的验证不能只靠内核日志，最终还是要让GPU跑真实图形负载。下面这些工具是我平时会用的，按优先级排列：

• glxinfo / vulkaninfo：最基础的设备枚举和能力查询工具，确认GPU节点是否正常
• igt-gpu-tools：Intel GPU测试套件，覆盖显示、帧缓冲、电源管理等多类测试
• glmark2 / vkmark：跑图形负载压测，观察驱动稳定性
• renderdoc：帧级调试工具，可以抓取完整的GPU命令流
• perf：内核侧性能分析，定位驱动热路径和调度开销

这些工具不需要一次性配齐。先装glxinfo和vulkaninfo，确认系统能枚举到GPU设备。后面做到具体的驱动功能验证时，再根据测试目标补充。

5.3 崩溃现场：kdump与kgdb的准备

最后一个必须提前准备的装备，是KMD崩溃时的现场捕捉方案。很多做KMD开发的人，第一次遇到GPU挂死都很慌张：屏幕卡死、鼠标没了、远程可能也断了。如果环境里没有配置kdump或pstore，重启之后连日志都没有，只能靠猜。

我建议在环境搭建阶段就开启kdump并测试一次强行崩溃，确认crash dump能正常生成。在现代Linux上：

sudo apt install -y kdump-tools sudo systemctl enable kdump-tools

然后通过sysrq强制触发一次panic（只有开发机且没有未保存工作时才做）：

echo 1 | sudo tee /proc/sys/kernel/sysrq echo c | sudo tee /proc/sysrq-trigger

重启后检查/var/crash目录，看是否生成了vmcore文件。这个动作看起来麻烦，但真能救你无数次。KMD这类内核态代码，如果没有现场信息，排查效率几乎为零。

6. 高频报错与排查速查表

6.1 编译期问题

6.2 加载与运行期问题

6.3 独家排查技巧

环境搭建阶段的排查，有几条经验是常规文档里不会写的，我分享出来。

第一，调试初期不要依赖IDE断点，给模块加日志是最直接的手段。内核态打断点不现实，多用dev_info/pr_info输出关键路径的变量值，日志级别临时调到7（dmesg -n 7），排查完再调回去。KMD开发里“日志法”比想象中管用得多。

第二，用模块参数控制功能开关。在模块里定义module_param，比如控制是否启用调试输出、是否跳过某段初始化。这样就不用来回重编译模块，配合sysfs接口可以动态调整行为。这个做法调驱动时能省大量时间。

第三，遇到“看起来跟环境有关”的报错，优先重装对应版本的linux-headers再重新编译。很多所谓诡异编译错误，其实是内核头文件升级后ABI变了，模块用的还是旧缓存。

第四，开发机和日常用户态开发机最好分开。一旦混用，升级系统后内核版本一变，整个模块编译环境就崩了，排查成本非常高。

最后分享一个小诀窍：多给自己留一份内核配置备份。比如把编译模块时用的内核.config文件单独存一份，后面想要查某个配置项是否打开，直接grep就行，不用反复进menuconfig翻菜单。KMD这条路，环境搭得越扎实，后面踩的坑越少。走完今天这一步，下一节就可以开始往这个骨架里填真正的GPU功能了，那部分才是KMD最精彩的地方。