From eb5c51a97d31e9a84289a9ca68259888b8099e71 Mon Sep 17 00:00:00 2001 From: Tim Whisonant Date: Fri, 26 Jun 2026 15:11:51 -0700 Subject: [PATCH] docs: add how-to for rebuilding a single kernel module Migrates and modernises the content from the deprecated Ubuntu wiki page at https://wiki.ubuntu.com/Kernel/Dev/KernelModuleRebuild into the kernel-docs how-to structure. Changes from the original wiki content: - Replace the deprecated SUBDIRS= make parameter with the current M= form (SUBDIRS was removed in Linux 3.8; M= / KBUILD_EXTMOD is the correct modern equivalent). - Add a 'make O=... M=scripts' step that produces the scripts/mod/ helpers required for building external modules. - Add explicit modprobe -r / modprobe load-and-test steps. - Add a note guiding readers toward DKMS for sustained cross-upgrade use. - Format the guide consistently with the MyST/Sphinx conventions used elsewhere in kernel-docs (code-block directives, note/important admonitions, cross-references to related pages). The new page is placed at how-to/develop-customise/build-kernel-module.md, alongside the existing build-kernel.md and build-kernel-snap.md guides, and is linked into the toctree and body of how-to/index.md. Signed-off-by: Tim Whisonant --- .../develop-customise/build-kernel-module.md | 127 ++++++++++++++++++ docs/how-to/index.md | 2 + 2 files changed, 129 insertions(+) create mode 100644 docs/how-to/develop-customise/build-kernel-module.md diff --git a/docs/how-to/develop-customise/build-kernel-module.md b/docs/how-to/develop-customise/build-kernel-module.md new file mode 100644 index 0000000..6a34f66 --- /dev/null +++ b/docs/how-to/develop-customise/build-kernel-module.md @@ -0,0 +1,127 @@ +--- +myst: + html_meta: + description: "How to rebuild a single Ubuntu kernel module out-of-tree to quickly test a patch, without rebuilding the entire kernel." +--- + +# How to rebuild a single kernel module + +If you have a patch for a specific kernel driver and want to test it quickly, +you can rebuild just that module out-of-tree instead of rebuilding the entire +kernel. This approach is significantly faster and is well suited for iterating +on a driver fix. + +```{important} +Modules built using this method are not intended for use in production. +For managing kernel modules across kernel upgrades, consider using +[DKMS](https://manpages.ubuntu.com/manpages/noble/en/man8/dkms.8.html) instead. +``` + +## Prerequisites + +- The kernel version for which you are rebuilding the module must match the + running kernel (`uname -r`). +- You need the patch you intend to apply. + +### Install required packages + +```{code-block} shell +sudo apt update && sudo apt install -y linux-source build-essential +``` + +## Obtain and patch the kernel source + +Install the kernel source package and extract it to your working directory: + +```{code-block} shell +sudo apt install -y linux-source +tar xjf /usr/src/linux-source-$(uname -r | cut -d- -f1).tar.bz2 +``` + +```{note} +The tarball name uses the base kernel version (e.g. `linux-source-6.8.0.tar.bz2`), +not the full ABI version string reported by `uname -r`. +``` + +Apply your patch to the extracted source tree: + +```{code-block} shell +cd linux-source-$(uname -r | cut -d- -f1) +patch -p1 < /path/to/your.patch +``` + +## Set up the out-of-tree build directory + +Create a separate build directory and populate it with the build artefacts from +the running kernel: + +```{code-block} shell +cd ~ +mkdir build_module + +cp /lib/modules/$(uname -r)/build/.config ./build_module/ +cp /lib/modules/$(uname -r)/build/Module.symvers ./build_module/ +cp /lib/modules/$(uname -r)/build/Makefile ./build_module/ +``` + +## Prepare the build environment + +From inside the kernel source tree, prepare the out-of-tree build directory: + +```{code-block} shell +cd linux-source-$(uname -r | cut -d- -f1) + +make O=../build_module outputmakefile +make O=../build_module archprepare +``` + +```{note} +If `archprepare` fails with an error, run `make mrproper` in the source +directory, re-copy the three files from `/lib/modules/$(uname -r)/build/` +as shown above, then retry from `make O=../build_module outputmakefile`. +``` + +Complete the build preparation: + +```{code-block} shell +make O=../build_module prepare +make O=../build_module M=scripts +``` + +## Build the module + +Build only the driver subdirectory containing your change. Replace +`drivers/` with the actual path relative to the kernel source +root (for example, `drivers/net/ethernet/intel/e1000e`): + +```{code-block} shell +make O=../build_module M=drivers/ modules +``` + +The compiled module file (`.ko`) will appear inside +`build_module/drivers//`. + +## Install the module + +Copy the new `.ko` file over the existing one in the live module tree: + +```{code-block} shell +sudo cp build_module/drivers//.ko \ + /lib/modules/$(uname -r)/kernel/drivers// +``` + +## Load and test the module + +Unload the old module if it is currently loaded, then load the new one: + +```{code-block} shell +sudo modprobe -r +sudo modprobe +``` + +Confirm the module loaded successfully: + +```{code-block} shell +lsmod | grep +dmesg | tail -20 +``` diff --git a/docs/how-to/index.md b/docs/how-to/index.md index d2af1f7..ce6d40a 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -19,6 +19,7 @@ Obtain and manage kernel source for an Ubuntu release using Git Build an Ubuntu Linux kernel Build an Ubuntu Linux kernel snap +Rebuild a single kernel module Test kernels in -proposed Contribute to kernel docs ``` @@ -38,6 +39,7 @@ The steps to build a kernel is similar but may have slightly difference configur - {doc}`Build an Ubuntu Linux kernel ` - {doc}`Build an Ubuntu Linux kernel snap ` +- {doc}`Rebuild a single kernel module ` ## Testing and verification