写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 Radeonamdgpu是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硬扛整个过程非常痛苦。环境搭建这种一次性投入宁可稍微多花点预算也别让自己在后续开发中反复被性能卡脖子。硬件最低建议舒适配置CPU4核x86_648核以上内存16GB32GB磁盘50GB可用空间100GB以上SSD2.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 curlbuild-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, vendor0x%04x device0x%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) clean4.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会显示模块被加载成功。由于这个骨架没有匹配的真实设备IDprobe回调一般不会被调用日志里大概率只有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-toolsIntel 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 编译期问题报错特征根因解决方式cannot find linux/xxx.h没有安装对应版本内核头文件安装linux-headers-$(uname -r)重新makeversion magic X doesnt match Y使用build目录与当前内核不一致确认KERNELDIR指向/lib/modules/$(uname -r)/buildNo rule to make target modules内核build目录缺失或损坏重装linux-headers或改用完整内核源码构建目录Operation not permittedSecure Boot或内核模块签名问题关闭Secure Boot或配置本地模块签名信任undefined reference to xxx引用未导出的内核符号检查内核配置与EXPORT_SYMBOL使用情况6.2 加载与运行期问题报错特征根因解决方式insmod后dmesg无输出模块日志级别被过滤执行dmesg -n 7后重新加载观察probe回调不执行PCI设备ID不匹配或设备已被占用用lspci -nn确认ID修改id_table检查其他驱动是否绑定设备系统直接卡死驱动访问非法MMIO或中断处理错误从骨架逐步增加功能配合kgdb或kdump定位vulkaninfo看不到GPUKMD加载不完整设备节点未创建lsmod确认模块检查/dev/dri节点看dmesg报错6.3 独家排查技巧环境搭建阶段的排查有几条经验是常规文档里不会写的我分享出来。第一调试初期不要依赖IDE断点给模块加日志是最直接的手段。内核态打断点不现实多用dev_info/pr_info输出关键路径的变量值日志级别临时调到7dmesg -n 7排查完再调回去。KMD开发里“日志法”比想象中管用得多。第二用模块参数控制功能开关。在模块里定义module_param比如控制是否启用调试输出、是否跳过某段初始化。这样就不用来回重编译模块配合sysfs接口可以动态调整行为。这个做法调驱动时能省大量时间。第三遇到“看起来跟环境有关”的报错优先重装对应版本的linux-headers再重新编译。很多所谓诡异编译错误其实是内核头文件升级后ABI变了模块用的还是旧缓存。第四开发机和日常用户态开发机最好分开。一旦混用升级系统后内核版本一变整个模块编译环境就崩了排查成本非常高。最后分享一个小诀窍多给自己留一份内核配置备份。比如把编译模块时用的内核.config文件单独存一份后面想要查某个配置项是否打开直接grep就行不用反复进menuconfig翻菜单。KMD这条路环境搭得越扎实后面踩的坑越少。走完今天这一步下一节就可以开始往这个骨架里填真正的GPU功能了那部分才是KMD最精彩的地方。