Open Software License 3.0

技术解读

以下内容由 GitRead 中文社区 编辑团队基于项目 README 与官方资料整理, 结合中文开发者的常见使用场景补充技术选型建议。具体以项目官方文档为准。

项目背景与痛点

内核模块开发是 Linux 系统编程里门槛最高、资料最陈旧的一块。2010 年之后,几乎所有中文博客里的字符设备示例还在用 register_chrdev,定时器示例还在用 init_timer,这些 API 在 4.x 到 5.x 的演进中要么被废弃,要么签名彻底变了。经典的 Linux Device Drivers, 3rd Edition(LDD3)面向 2.6.10,示例代码在今天的发行版上基本编不过;KernelNewbies 之类的 wiki 又停留在知识点罗列,缺少可运行的闭环。

sysprog21/lkmpg 要解决的核心问题只有一个:让教程里的每一段代码,在 5.0+ 内核上真的能 make 通过、insmod 加载。它不是又一份"Hello World 讲解",而是一份把示例代码当作一等公民维护的活文档。

核心技术揭秘

这个项目的技术含量不在内核侧,而在文档工程。它把"教程"当成一个需要持续集成的软件产品来做,架构上有两条并行的数据流:

graph TD A[lkmpg.tex 单一源文件] --> B[pandoc 转换层] C[code 目录示例模块] --> D[kbuild 外部模块构建] B -->|"转 HTML"| E[在线教程] B -->|"转 PDF"| F[PDF 手册] B -->|"转 EPUB"| G[电子书] D --> H[GitHub Actions CI] B --> H H -->|"编译与渲染全部通过"| I[制品发布] H -->|"任一环节失败"| J[阻断合并]

第一条流是文档渲染。 全书以 LaTeX 为唯一信源,通过 pandoc 转出 HTML、PDF、EPUB 三种形态。这种"单一源 + 多目标"的做法避免了多份文档互相漂移的老问题——你在 PDF 里看到的章节顺序,和网页版永远是同一份内容。

第二条流是示例模块的构建。 每个章节对应一个独立示例目录,各自带 Makefile,走的是内核标准的外部模块编译路径(make -C $(KDIR) M=$(PWD) modules),而不是往内核树里塞代码。这意味着每个示例天然是"可插拔"的,读者可以单独拿某章去编译调试,不必理解整个仓库。

真正的难点在于同步。内核 API 的迁移是碎片化的:register_chrdev 拆成了 alloc_chrdev_region + cdev_add;create_proc_entry 变成 proc_create 并新增了 proc_ops 结构体;class_create 从返回 struct class * 改成返回指针且需要 IS_ERR 判断;定时器统一收口到 timer_setup 的回调签名。每修一处,都要求作者同时改 LaTeX 正文里的代码块和 code/ 下的真实文件,否则文档和可编译代码就会分叉。CI 在这里承担了守门员角色:只要有一个示例编不过,PR 就进不来。这是把"文档正确性"从人工承诺变成了流水线约束。

功能亮点与差异

对比 LDD3 和各类内核 wiki,lkmpg 的差异点很清晰:

  • 代码优先于叙述。每个概念都落到一个能跑的最小模块上,hello world 到中断下半部、RCU、per-CPU 变量,形成一条难度递增的阶梯。
  • 构建环境可复现。仓库提供容器化的构建方式,读者不用在自己的机器上折腾 xelatex 和整套内核头文件,CI 和本地执行的是同一套流程。
  • 面向现代内核写作。并发章节直接讲 mutex / spinlock / RCU 三者的取舍,而不是停在"锁是什么"。
  • 多格式阅读体验。移动端看 EPUB、桌面查 PDF、线上检索 HTML,覆盖了不同学习场景。

应用场景与落地建议

它最适合两类人:一是从零切入内核模块的工程师,把它当作"跑得起来的入门路径";二是需要把老驱动迁移到 5.x 内核的维护者,用它对照 API 的替代写法。

但不要直接把示例代码搬进生产。这些模块刻意裁剪了错误处理、引用计数管理和并发保护,目的是让概念清晰,而非健壮。生产驱动需要补上:module_get/module_put 的正确配对、设备号与 cdev 的完整生命周期、copy_to_user 的失败路径、以及针对具体内核配置(如 CONFIG_RCU_*)的条件编译。建议把它当"语法参考 + 心智模型",真正落地时对照目标内核版本的 Documentation/ 和实际子系统代码。

综合评价

优点:唯一一份把示例代码纳入 CI 持续验证的内核模块教程;单一源多格式的文档工程做得干净;章节组织由浅入深,适合自学;社区活跃,API 迁移响应快。

缺点:覆盖面偏"经典机制",对设备树、regmap、DMA engine、电源管理等现代驱动框架着墨有限;示例为了教学简洁牺牲了工程完整性,容易被初学者误当成最佳实践;对读者的内核基础有一定隐性要求,完全零基础会略感吃力。

一句话总结:它不是最全的内核书,但很可能是当下最不容易过时的那一本。

关于

GitHub 原始描述(英文)

The Linux Kernel Module Programming Guide (updated for 5.0+ kernels)

描述取自 GitHub 官方 API,保持仓库作者书写的原文。

简要分析

热度分
10031
价值分
5384
活跃状态
活跃

语言占比

Makefile
Shell
TeX

README

The Linux Kernel Module Programming Guide

This project keeps the Linux Kernel Module Programming Guide up to date, with working examples for recent 5.x and 6.x kernel versions. The guide has been around since 2001 and most copies of it on the web only describe old 2.6.x kernels.

The book can be freely accessed via https://sysprog21.github.io/lkmpg/ or latest PDF file. The original guide may be found at Linux Documentation Project. You may check other freely available programming books listed by The Free Ebook Foundation or Linux online books collected by The Online Books Page.

Getting Started

Summary

  1. Get the latest source code from the GitHub page.
  2. Install the prerequisites.
  3. Generate PDF and/or HTML documents.

Step 1: Get the latest source code

Make sure you can run git with an Internet connection.

$ git clone https://github.com/sysprog21/lkmpg.git && cd lkmpg

Step 2: Install the prerequisites

To generate the book from source, TeXLive (MacTeX) is required.

For Ubuntu Linux, macOS, and other Unix-like systems, run the following command(s):

# Debian / Ubuntu
$ sudo apt install make texlive-full

# Arch / Manjaro
$ sudo pacman -S make texlive-binextra texlive-bin

# macOS
$ brew install mactex
$ sudo tlmgr update --self

Note that latexmk is required to generate PDF, and it probably has been installed on your OS already. If not, please follow the installation guide.

In macOS systems, package Pygments may not be pre-installed. If not, please refer to the installation guide before generating documents.

Alternatively, using Docker is recommended, as it guarantees the same dependencies with our GitHub Actions workflow. After installing docker engine on your machine, pull the docker image twtug/lkmpg and run in isolated containers.

# pull docker image and run it as container
$ docker pull twtug/lkmpg
$ docker run --rm -it -v $(pwd):/workdir twtug/lkmpg

nerdctl is a Docker-compatible command line tool for containerd, and you can replace the above docker commands with nerdctl counterparts.

Step 3: Generate PDF and/or HTML documents

Now we could build document with following commands:

$ make all              # Generate PDF document
$ make html             # Convert TeX to HTML
$ make clean            # Delete generated files

License

The Linux Kernel Module Programming Guide is a free book; you may reproduce and/or modify it under the terms of the Open Software License. Use of this work is governed by a copyleft license that can be found in the LICENSE file.

The complementary sample code is licensed under GNU GPL version 2, the same as the Linux kernel.

评论

暂无评论