From a8b55e03fd50772af2e491634c8288a69dc1f4b1 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 | 130 ++++++++++++++++++ docs/how-to/index.md | 2 + 2 files changed, 132 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..ff0b45a --- /dev/null +++ b/docs/how-to/develop-customise/build-kernel-module.md @@ -0,0 +1,130 @@ +--- +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 +{manpage}`dkms(8)` instead. +``` + +## Prerequisites + +- The kernel version for which you are rebuilding the module must match the + running kernel (`uname -r`). +- The driver patch you intent 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 in the previous step, then retry rerunning 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 +``` + +Test and verify that your patch is working as intended. diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 533e245..69e0e2e 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -20,6 +20,7 @@ Send patches to the mailing-list Build an Ubuntu Linux kernel Build an Ubuntu Linux kernel snap Test pre-release Ubuntu kernels +Rebuild a single kernel module 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