简介这是一套基于 Docker 与 QEMU 的 Linux 内核学习、开发与测试环境面向希望快速上手内核实验的开发者、学生和运维人员省去手动搭建交叉编译与模拟器环境的繁琐流程。无论是课堂实验、毕业设计还是日常内核调试都能围绕内核编译、启动调试和驱动开发直接展开实践显著降低上手门槛。压缩包共368个文件约2.53MB以shell脚本、Makefile、Markdown文档、patch补丁、config配置为主辅以C/汇编源码、设备驱动示例与调试辅助文件脚本和文档分工明确目录结构清晰。目前已有131人学习/下载适合作为内核入门到进阶的动手实践素材。内容覆盖多版本内核如2.6.10、2.6.11.12的构建与启动脚本支持aarch64、virt、versatilepb、malta、riscv64等多种QEMU目标平台包含字符设备驱动示例与调试配置可帮助读者快速验证内核模块、跟踪启动流程并理解不同内核版本下设备驱动开发与配置裁剪的要点。1. 基于 Docker QEMU 的 Linux 实验环境为什么我把内核学习环境全搬进了容器学操作系统绕不开内核实验改调度器、写字符设备驱动、在内核里加一串 printk再看它在真实指令流里怎么跑。见过太多物理机翻车的例子新手直接在本机装内核一次 panic 后引导器也跟着搭进去一整晚都在抢救宿主系统实验却一个字没推进。这套基于 Docker QEMU 的 Linux 实验环境就是为了解决这个问题出现的Docker 封装编译器、依赖和内核源码QEMU 模拟出一台独立虚拟机内核改坏了最多重启一个 QEMU 进程宿主机毫发无损。社区把这套环境打包过免安装的随身 Linux Lab 系统盘插上普通电脑就能进实验环境。这篇笔记适合要做操作系统课程实验、写内核驱动、调试内核崩溃的开发者跟着走完你也会得到一套能反复折腾的 Lab。2. 环境准备与版本选型先把 Docker、QEMU 和内核三者的分工理清2.1 这套环境的层次关系Docker 提供编译环境QEMU 提供运行环境我第一次拿到这套环境的时候最困惑的不是命令怎么写而是三个东西到底谁管谁。理清楚之后再动手后面每一步都很顺。最底层是宿主机上的 Docker它负责提供一个干净的 Linux 编译环境。容器里预装了内核源码、工具链和一堆构建依赖你要做的就是进容器执行 make。为什么不用宿主机直接编译因为内核编译的依赖非常敏感gcc 版本、binutils 版本、make 版本、rsync、bc 这些小工具任何一个不对都可能让整个编译莫名其妙地失败这种依赖问题我当年排查过一整晚都没头绪。Docker 把这一层变成黑匣子容器坏了重新拉一个就好比在物理机上反复装环境省心得多。中间层是 QEMU它负责把编译好的内核“开机”跑起来。QEMU 是纯软件模拟的虚拟机不需要真实硬件也不吃 KVM 之类的加速器x86 和 aarch64 都能模拟。内核在 QEMU 里崩溃、死锁、panic都只影响那个虚拟机器宿主机完全无感。最上面才是你要研究的 Linux 内核本身。这套环境里预置了多份内核版本的工作区每份工作区里有对应的顶层 Makefile。你改的是内核源码编译出来的 bzImage 交给 QEMU调试时再用 gdb 连接 QEMU 的调试端口。三者各司其职出了问题能很快定位到是哪一层。组件在这套环境里的职责出问题时常见表现Docker隔离编译工具链与依赖make 报缺工具、版本不匹配QEMU模拟硬件并运行内核镜像无法启动、串口无输出、panicLinux 内核被编译、运行、修改的实验对象编译失败、加载模块失败gdb通过远程端口连接 QEMU 调试内核连接拒绝、符号未加载2.2 版本选型为什么实验环境里 2.6 系源码树和现代内核并存看这套环境的工作区会发现它同时保留了 Makefile.linux_v2.6.10 和 Makefile.linux_v2.6.11.12 两份入口。这不是巧合而是经过考虑的学习内核旧版本比新版本友好得多。2.6 时代的内核源码量级小编译快函数调用链短一个字符设备驱动的代码量可能只有新内核版本下的三分之一。初学者从这份源码入手读代码、改代码、重新编译、再跑 QEMU一轮循环十分钟内能完成非常适合反复实验。我一般建议新手先用 v2.6.10 起步把内核模块、字符设备、proc 文件系统这些基础概念过一遍时间成本很低。而 v2.6.11.12 这份 Makefile 对应的是同一系列里后续修订的版本更适合用来对比“同一功能在不同修订里怎么变化”。想接触现代驱动模型device tree、platform bus的话环境里也预留了对应的目录但编译时间会长很多不适合快速迭代。一句话学习用旧版深入用新版两个都不要删。2.3 预先认识这些文件Makefile、gdbinit.auto、config 和驱动示例进到环境目录之后你会看到一堆文件我先按用途给你分类免得对着列表发懵。Makefile.linux_v2.6.10 和 Makefile.linux_v2.6.11.12 是两套不同版本内核工作区的顶层构建入口。你不需要记复杂的内核配置流程直接指定其中一份 Makefile 执行即可环境已经把架构相关的参数调好了。gdbinit.auto 是内核调试的自动加载脚本里面封装了连接 QEMU、加载符号表、设置断点这些步骤。传统做法是每次启动 gdb 后手动输入一堆命令这套环境用脚本免掉了重复劳动。config.aarch64.virt.broken 是一个很有意思的文件它是一份标注了 broken 的 aarch64 虚拟平台配置。看到名字里带 broken 就应该明白这份配置是坏的不能直接用我后面会专门讲它为什么坏、以及坏配置怎么排查。backup 目录则是配置回退的后悔药改乱了的 config 可以从这里恢复。文件用途需要注意Makefile.linux_v2.6.102.6.10 工作区构建入口学习内核首选Makefile.linux_v2.6.11.122.6.11 系列修订版构建入口适合对比差异gdbinit.auto内核调试 gdb 自动脚本调试时必须配合 QEMU 的 -s 参数backup配置备份配置改坏了用它恢复config.aarch64.virt.brokenaarch64 配置示例(已损坏)不可直接使用剩下的就是驱动示例源码misc_loop_drv.c 是一个 misc 字符设备驱动的循环读写示例dio.c 演示直接 I/O 的用法ldt.c 和 ldt_plat_drv.c 分别对应 LDT本地描述符表相关操作和平台设备驱动。这些驱动代码量都不大配合内核源码阅读能快速理解从模块初始化到设备节点的完整链路。3. 搭建 Docker 编译环境从拉镜像到工具链一次装完3.1 创建带特权模式的容器拉镜像并进入交互 shell这套环境对 Docker 容器有一个特殊要求必须带特权模式或至少放开部分资源限制否则 QEMU 在容器里跑不起来。我见过有人在这一步图省事用普通 docker run 启动容器结果后面 qemu-system 一执行就报内存锁定失败排查到半夜才发现是容器权限不够。这里用一个 Debian 系的基础镜像做演示你换成自己习惯的发行版镜像也可以命令结构不变。先拉镜像再进容器docker pull debian:bookworm-slim docker run -it --name linux-lab \ --privileged \ --cap-addSYS_PTRACE \ debian:bookworm-slim /bin/bash--privileged 参数很关键它让容器内的 QEMU 能访问宿主机的 /dev/kvm、/dev/mem 等设备节点同时解除大部分资源限制。QEMU 在模拟硬件时需要锁定内存、映射设备区域普通容器默认不允许这些操作加上这个参数最省事。--cap-addSYS_PTRACE 是给 gdb 用的。内核调试时 gdb 要对 QEMU 进程做 ptrace 操作不加这个能力后续调试步骤会频繁报 Operation not permitted。container 名字随意但要记住后面 docker start 会用到。如果在公司内网用pull 镜像时可能需要先配置镜像加速这一步属于环境前置被卡住了就先解决网络再继续。3.2 装内核编译所需依赖缺哪个都过不了 make容器刚拉下来是干干净净的连 make 都没有。内核编译依赖的软件包我一次列全避免你装到一半报错又回去补。apt-get update apt-get install -y build-essential bc bison flex \ libssl-dev libncurses-dev pahole rsyncbuild-essential 提供 gcc 和 make这是编译的底子。bc 是内核构建脚本里大量使用的一个计算器工具缺了它会在链接阶段报找不到 bc我第一次编译就是因为这个翻了车。bison 和 flex 是内核解析 Kconfig 和生成语法分析器用的这两个缺失会在 make 早期阶段直接中断。libncurses-dev 是 make menuconfig 交互界面依赖的库如果你打算用可视化菜单配置内核就必须装。libssl-dev 是给模块签名和某些加密特性用的。pahole 用来生成 BTF 信息新版内核尤其是 5.x 以上缺了它会直接警告有的版本直接报错。rsync 用于内核构建时的文件同步别小看它缺少 rsync 时 modules_install 阶段一定会报错。这套依赖在 Debian / Ubuntu 系是完全够用的。如果你用的是 CentOS / Rocky包名会略有差异对应关系是 bc 不变ncurses-devel 替代 libncurses-devopenssl-devel 替代 libssl-dev这些都装好之后效果相同。我一般建议内核实验统一用 Debian 系镜像省去这些包名转换的麻烦。3.3 准备 aarch64 交叉编译工具链不是必须但环境里有这需求这套环境里既然放了 config.aarch64.virt.broken 和对应的平台驱动说明你早晚会碰 ARM 虚拟平台。在 x86 的容器里编译 ARM 内核必须用交叉编译工具链这一节把工具链先装好免得后面 make ARCHarm64 时卡在找不到编译器。apt-get install -y crossbuild-essential-arm64装完之后验证一下编译器是否就位aarch64-linux-gnu-gcc --version交叉编译的名字格式是前缀加 gcc前缀由 ARCH 架构决定。ARM 64 位的前缀是 aarch64-linux-gnu-对应工具链就是 crossbuild-essential-arm64。装好之后编译 ARM 内核时指定 ARCHarm64 和 CROSS_COMPILEaarch64-linux-gnu- 即可具体命令第四章会讲。如果你确定自己只研究 x86 内核这一步可以跳过不影响主流程。但既然环境里给你准备了 aarch64 的配置我建议还是装上因为它能帮你把 QEMU 的 virt 平台也跑起来多一种实验选择。3.4 把源码和 Makefile 放进容器目录挂载与文件权限环境里的内核源码和预置文件需要进到容器里。方式有两种按你的使用习惯选一个。第一种是直接把宿主机目录挂载进容器。适合源码在宿主机、又不想复制一份的场景docker run -it --name linux-lab --privileged \ -v /home/【你的用户名】/linux-lab:/opt/lab \ --cap-addSYS_PTRACE debian:bookworm-slim /bin/bash-v 参数把宿主机目录映射到容器内的 /opt/lab之后在容器里对 /opt/lab 做的修改会同步回宿主机。注意一个问题Docker 容器默认以 root 运行写出来的文件属主是 root你在宿主机上想用普通用户编辑这些文件时很别扭。解决的常规做法是在容器里同步一个和宿主 uid 一致的用户再切过去或者编译时统一用 root编译完再 chown 回来。图省事的话实验全程 root 也没问题反正是隔离环境。第二种是直接复制进容器适合不想动宿主机目录的情况docker cp linux-lab-source/. linux-lab:/opt/lab/docker cp 的源路径是宿主机上的源码目录目标路径冒号后面是容器内的路径。这条命令不改变文件权限复制的文件保持原 uid 和 gid一般源码在你自己的用户目录下进容器后 root 去读写这些文件偶尔会有权限冲突直接 chmod -R 777 或 chown -R root:root 处理一下即可。我自己的习惯是把源码留在宿主机、用 -v 挂载这样 docker 容器删除后源码和编译产物都不会丢。坏处是容器重建后要重新装工具链所以我会做一个带所有依赖的镜像提交后面只需要 docker run这个后面讲验证流程时顺带提。4. 编译 Linux 内核从顶层 Makefile 到可启动的 bzImage4.1 确认架构与工具链ARCH 和 CROSS_COMPILE 怎么传进入容器、确认源码已经放到 /opt/lab 之后第一步是环境变量和架构参数。这套环境的 x86 编译参数很简单但一定不能漏export ARCHx86_64 export CROSS_COMPILEARCH 告诉内核构建系统你现在要编译哪个架构x86_64 是 64 位 x86。CROSS_COMPILE 是交叉编译器的前缀x86 本地编译时这一项为空但最好显式 export 一下避免某些脚本从环境里读到旧的交叉编译前缀导致混乱。ARCH 和 CROSS_COMPILE 搭错是最常见的内核编译事故在 x86 机器上忘了设 ARCH内核默认读本机架构通常没事但如果你之前 export 过 arm64这次忘了改回来make 就会用 ARM 的配置去编译 x86 源码报出来的错误非常诡异。所以每次开始实验前我会强制自己先跑一遍这两个 export。确认好之后用环境预置的顶层 Makefile 进入对应版本工作区cd /opt/lab make -f Makefile.linux_v2.6.10 defconfig-f 参数指定使用名为 Makefile.linux_v2.6.10 的文件作为构建入口而不是默认的 Makefile这样能精确定位到你要的那份内核版本。defconfig 是一个目标动作它生成该架构下的默认配置.config 文件。这个默认配置覆盖了内核主要子系统驱动都编成模块对于学习实验来说够用且编译快。4.2 生成最小可用配置再编译defconfig、bzImage、vmlinux 三者的关系defconfig 之后工作目录里会多出一个 .config 文件这是内核编译的“总开关”。这个文件决定了哪些功能编进内核、哪些编成模块、哪些干脆不编。直接改 .config 容易改错内核构建系统也支持 make menuconfig 让你用交互菜单改这个前提是第三章里装的 libncurses-dev 生效了。接下来是最能体现“这套环境为什么适合学习”的一步——直接编译make -f Makefile.linux_v2.6.10 -j$(nproc) bzImage-j$(nproc) 表示用 CPU 的全部核心并行编译。2.6 系列源码在 8 核机器上一般三五分钟就编完新内核就要看机器性能了。bzImage 是编译的最终目标它是一个压缩过的内核镜像位于 arch/x86_64/boot/bzImageQEMU 启动用的就是它。编译过程的输出要留意最后几行正常结束会出现 Kernel: arch/x86_64/boot/bzImage is ready 字样说明镜像生成了。如果中间报错大概率是缺依赖回到 3.2 核对一遍。同时还要注意编译完成后工作区里会多出 vmlinux 这个文件。vmlinux 是未压缩的内核文件保留了符号表gdb 调试内核必须用它不能拿 bzImage 调试。这就是为什么我从不对新手说“编译完直接 gdb bzImage”符号没加载断点全打在空地址上。4.3 编译内核模块misc_loop_drv.c 这类驱动怎么编出来内核里许多驱动并不编进 bzImage而是编译成 .ko 模块文件运行时按需加载。这套环境里的 misc_loop_drv.c、dio.c、ldt.c 都是这种情况。要编译全部模块时make -f Makefile.linux_v2.6.10 -j$(nproc) modulesmodules 目标会把内核里所有配置为 m 的驱动都编译出 .ko 文件。但完整编译所有模块耗时较长实验时我们通常只编自己关心的那个驱动用 M 参数指定目录make -f Makefile.linux_v2.6.10 -j$(nproc) Mdrivers/charM 后面跟驱动源码所在的相对目录构建系统只编译这个目录下的模块。以 misc_loop_drv.c 为例如果它放在 drivers/char 下编译完会在同目录生成 misc_loop_drv.koinsmod 可以直接使用。只编译单个目录能省下大量时间这是做驱动开发时最高频的操作。4.4 尝试 aarch64 配置时要小心的那份 broken 文件前面我故意留着 config.aarch64.virt.broken 没讲现在来说明它为什么不能用。我第一次看到这个文件时直接把它复制成 .config 然后跑编译结果 Kconfig 解析阶段就刷屏报错什么 undefined symbol、unsupported option 一堆当时还以为是编译器的问题。后来才想明白文件名里的 broken 不是随意标注的这份配置原本对应某个特定版本的 ARM 虚拟平台但后来内核源码更新配置里引用的配置项有的被改名、有的被删除再拿它去做 defconfig 当然过不了。这类“过期配置”在真实项目里很常见维护跟不上内核更新就会这样。在环境里做 ARM 实验的正确做法是绕过它用内核自带的 defconfig 重新生成make ARCHarm64 CROSS_COMPILEaarch64-linux-gnu- defconfig make ARCHarm64 CROSS_COMPILEaarch64-linux-gnu- -j$(nproc) bzImage这样生成的 .config 是当前源码树对应版本的干净配置不会再报那些 Kconfig 的错。两份命令区别只在 ARCH 和 CROSS_COMPILE前一份是 x86 本地编译后一份是 ARM 交叉编译。ARM 编译产物在 arch/arm64/boot/ImageQEMU 启动 ARM 内核时用这个文件而不是 bzImage。那份 broken 配置文件也不是完全没用。它至少告诉你遇到环境里预置的配置报错时先怀疑配置是否过期而不是怀疑编译器或源码。排查顺序是配置、源码、工具链这个次序能省大量时间。5. 避坑这套 Docker QEMU 环境里我踩过的五个问题5.1 QEMU 在容器里启动报内存锁定失败现象执行 qemu-system-x86_64 命令启动内核进程立即退出终端输出 failed to set mlock、Operation not permitted 之类的报错。原因QEMU 为了提高性能会锁定部分内存页防止被系统换出。Docker 默认对容器的资源限制很严格没有放开 memlock 限额也没有给足特权QEMU 一执行锁定内存的操作就被拒绝。解决在创建容器时加 --privileged 参数或者更精细一点用 --ulimit memlock-1: -1 将 memlock 限制设为无限。如果你已经创建了容器但没加特权参数最快的处理是删掉容器重新创建docker rm -f linux-lab docker run -it --privileged --ulimit memlock-1 ...从那以后我每次创建容器都直接带上 memlock 限制不再赌默认配置。5.2 编译时报 include/generated/autoconf.h 不存在现象执行 make bzImage终端很快报错 fatal error: include/generated/autoconf.h: No such file or directory然后编译中断。原因这个 autoconf.h 是在 make defconfig 阶段由内核构建系统生成的它汇总了 .config 里的所有配置宏。如果你跳过了 defconfig 直接编译这个文件根本没被生成代码里 include 它的编译单元全部失败。解决回到 4.1 补上 defconfig 这一环节。注意不同源码树的配置不要混用在 v2.6.10 工作区里配了 config就不能直接切到 v2.6.11.12 去编译。每次切换版本工作区重新执行一次对应 Makefile 的 defconfig 是标准动作。这个错误对新手迷惑性很强报错信息跟实际原因隔了两层不看编译日志根本联想不到是少了 defconfig。5.3 直接使用 config.aarch64.virt.broken 导致 Kconfig 报错现象把 config.aarch64.virt.broken 复制为 .config 后执行 make ARCHarm64Kconfig 解析阶段大量报错包括 undefined symbol、unsupported option 等配置界面完全进不去。原因这份配置对应的内核版本与当前源码树不一致里面引用的多个 Kconfig 配置项在现有版本里已被改名或移除。我在 4.4 已经做过排查这里强调一个处理原则带 broken 标记的文件默认不要使用先看 backup 目录有没有可用回退没有就重新生成 defconfig。解决删除错误的 .config重新 make ARCHarm64 defconfig。如果这个配置文件对你确实有参考价值可以把它的有效配置项手动挑出来做到新的 .config 里注意逐条确认选项在当前源码树里存在工作量较大但不难。遇到这种情况别硬啃一份过期配置不值得花几个小时。5.4 insmod 报 version magic 不匹配现象把编译出的 misc_loop_drv.ko 用 insmod 加载时报错 version magic 2.6.10 mod_unload SMP should be 5.15.0-xxx-generic 之类的信息模块加载失败。原因模块编译时使用的内核源码版本与运行中的内核版本不一致。最常见的情况是在宿主机环境里直接编译了模块用的是宿主机自带的内核头文件而运行内核是 QEMU 里那份 2.6 系列的实验内核。内核模块对版本匹配检查非常严格这个字符串检查就是内核的防呆设计。解决回到这套环境里编译模块。确保在容器内、进入源码树、用与运行内核相同版本的 Makefile 编译cd /opt/lab make -f Makefile.linux_v2.6.10 Mdrivers/char misc_loop_drv.ko加载时确认运行内核的 uname 输出和模块编译版本一致。如果版本对不上再检查 QEMU 启动时用的是不是刚编译的 bzImage有时候内核还是旧的模块是新的也会触发这个报错。这个检查是内核模块开发里最日常的一环但几乎每个新手都踩过我见过有人为此重装整个系统其实只是版本没对上。5.5 gdb 连不上 QEMU 或断点打在空地址上现象启动 QEMU 后执行 gdb -x gdbinit.autogdb 显示 connection refused 或者 target remote 超时能连上但断点无效无法命中任何函数。原因两层。连接失败是因为 QEMU 启动时没有加 -s 参数这个参数让 QEMU 开启 1234 端口的 gdb 调试服务。断点无效则是因为 gdb 加载的是 vmlinux 还是 bzImage 的问题或者符号表路径不对gdb 里显示的地址全是偏移量。解决QEMU 启动命令补上 -sqemu-system-x86_64 -kernel arch/x86_64/boot/bzImage -s -append consolettyS0 -nographic然后在 gdb 里确认 target remote 指向 :1234并且加载的是带符号的 vmlinuxgdb vmlinux (gdb) target remote :1234gdbinit.auto 脚本一般会把这两步封装好但前提是启动 QEMU 时带了 -s。建议每次启动 QEMU 都把 -s 加上哪怕当前不需要调试后面要连的时候不用重启虚拟机。6. 装完怎么验证跑通QEMU 启动内核并用 gdb 调试第一个驱动6.1 用 QEMU 启动刚编译的内核并确认串口输出编译完成后验证的第一件事是让内核在 QEMU 里跑起来。终端执行qemu-system-x86_64 -kernel arch/x86_64/boot/bzImage \ -append consolettyS0 -nographic -s-kernel 指定内核镜像-append 把内核启动参数传给内核consolettyS0 让内核把输出日志打到串口配合 -nographic 让 QEMU 把串口映射到当前终端。启动后你会看到内核的启动日志刷屏最后停在控制台等待输入。看到这里你的编译产物已经能真实运行了整条链路跑通了一半。按 Ctrl-A 再按 X 可以退出 QEMU这个快捷键和普通终端不一样别用 Ctrl-C 去尝试容易把你的容器终端也搞乱。6.2 在 QEMU 里加载 misc_loop_drv.ko 并验证设备节点内核起来后验证模块功能。先确认模块文件存在然后加载insmod misc_loop_drv.ko ls /dev/misc_loopinsmod 执行后如果没有输出通常说明模块加载成功有 version magic 之类的报错就回到 5.4 排查。加载成功后ls 能看到 /dev/misc_loop 这个设备节点说明驱动的 init 函数执行了设备注册成功。再写个简单的读写测试用 dd 或 cat 对设备节点做一次读取能看到驱动里的 read 回调被触发。这一步做完驱动从注册到设备节点出现的完整链路就验证通了。6.3 用 gdbinit.auto 调试驱动加载过程最后一个验证是调试闭环这是这套环境最有价值的部分。确认 QEMU 带着 -s 参数运行然后在另一个终端进到源码目录gdb -x gdbinit.auto vmlinuxgdbinit.auto 脚本会自动连接 :1234 并加载符号表。接着在驱动初始化函数上打断点break misc_loop_init continue然后回到 QEMU 终端执行 insmod misc_loop_drv.kogdb 会立刻停在断点处你可以单步跟踪驱动的初始化流程查看寄存器、内存、调用栈。看到指令指针准确定位到源码行说明符号表构建、QEMU 调试端口、gdbserver 协议全链路都验证通过。从那以后我每次新装完这套环境都强制走一遍这条验证流程QEMU 启动内核、加载驱动、gdb 断点命中三步都过了才放心开始改代码。这个习惯帮我避开了无数次“改了半天才发现环境本身没跑通”的尴尬。希望帮到你。本文还有配套的精品资源点击获取
