What You Will Learn

• Why some kernel features are better built as modules instead of being built-in
• How to invoke the Kbuild modules target for a cross-compiled kernel
• Where compiled .ko files land inside the source tree, and why that is inconvenient
• How to install modules into a staging root filesystem using INSTALL_MOD_PATH
• The difference between clean, mrproper, and distclean, and when to use each
• A small original demo module you can build, install, and load to see the whole pipeline work

Prerequisites

• A configured kernel source tree with a working .config (see our earlier lectures on Kconfig and menuconfig)
• A cross toolchain already on your PATH, for example arm-linux-gnueabihf-
• Basic familiarity with make targets from our Kbuild lecture

Why Build Drivers As Modules

A kernel module is object code that is linked into the running kernel image at run time rather than at build time. This matters for embedded work in a few concrete ways. First, it shortens your inner development loop — you can rebuild and reload one driver in seconds instead of reflashing an entire kernel image. Second, it keeps the base kernel image small on boot media that is limited, loading optional hardware support only when it is actually plugged in. Third, it lets you distribute a driver update to devices in the field without touching the bootloader or the rest of the kernel at all.

The trade-off is that modules add a small amount of complexity: the module has to be found and loaded by user space (or auto-loaded via udev/modprobe), and you now have a second artifact — the .ko file — that has to travel alongside your kernel image and match its exact version and configuration.

Compiling Kernel Modules With Kbuild

Once you have marked a feature as m in your configuration (through menuconfig, or directly in a defconfig fragment), Kbuild already knows to treat it as a module. You do not need a separate build step for “just the modules” versus “just the built-in pieces” — a normal kernel build compiles both. But if you have already built the kernel image and only want to rebuild the modules, Kbuild exposes a dedicated target for exactly that:

$ make -j$(nproc) ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- modules

This walks the dependency graph for every symbol configured as m and compiles only those object files, linking each one into its own .ko. On a large tree this is noticeably faster than a full rebuild if you have only changed a driver or two.

Notice the problem this diagram illustrates: modules are generated next to their source code, scattered across dozens of subdirectories. That layout is fine for kernel developers who know the tree, but it is not something you can hand to a root filesystem image builder as-is.

Installing Modules Into A Staging Filesystem

Kbuild solves the scattering problem with the modules_install target, which walks the tree, collects every compiled .ko, and copies them into a single directory structure keyed by kernel release string. Left alone, that target installs straight into /lib/modules on your build host — almost never what you want when cross-compiling for a separate target board. You redirect the destination with INSTALL_MOD_PATH:

$ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \
    INSTALL_MOD_PATH=$HOME/staging/rootfs modules_install

After this runs, every module is collected under a predictable path relative to the root you supplied:

$HOME/staging/rootfs/lib/modules/<kernel-release>/
├── kernel/drivers/net/ethernet/realtek/r8169.ko
├── kernel/drivers/mmc/host/sdhci-of-arasan.ko
├── modules.dep
├── modules.alias
└── modules.builtin

The <kernel-release> directory name comes from the kernel’s own version string (visible with make kernelrelease), and the accompanying modules.dep and modules.alias files are what let modprobe resolve dependencies and hardware aliases automatically once the board boots this filesystem.

Try It: A Minimal Original Module

To see the whole pipeline end to end, build a tiny module of your own. Save this as ep_hello.c in a scratch directory:

#include <linux/module.h>
#include <linux/kernel.h>
#include <linux/init.h>

static int __init ep_hello_init(void)
{
    pr_info("ep_hello: module loaded, hello from EmbeddedPathashala\n");
    return 0;
}

static void __exit ep_hello_exit(void)
{
    pr_info("ep_hello: module unloaded\n");
}

module_init(ep_hello_init);
module_exit(ep_hello_exit);

MODULE_LICENSE("GPL");
MODULE_AUTHOR("EmbeddedPathashala");
MODULE_DESCRIPTION("Minimal demo module for the modules lecture");

Pair it with a matching out-of-tree Makefile:

obj-m += ep_hello.o

all:
	$(MAKE) -C $(KDIR) M=$(PWD) modules

clean:
	$(MAKE) -C $(KDIR) M=$(PWD) clean

Build it against your kernel tree and load it:

$ make KDIR=/path/to/kernel-source
$ sudo insmod ep_hello.ko
$ dmesg | tail -n 2
[  132.114201] ep_hello: module loaded, hello from EmbeddedPathashala
$ sudo rmmod ep_hello
$ dmesg | tail -n 1
[  140.552017] ep_hello: module unloaded

Cleaning The Kernel Source Tree

After enough build iterations, a kernel tree accumulates object files, generated headers, and stray artifacts that can make a fresh build behave unpredictably. Kbuild gives you three progressively more aggressive cleaning targets.

A useful habit: run mrproper whenever a build fails in a confusing way after switching branches or applying a patch, then reconfigure from your saved defconfig. It removes an entire class of “stale generated header” bugs in one step.

Common Mistakes And Troubleshooting

• Forgetting ARCH/CROSS_COMPILE on modules_install: the install step still needs to know the target architecture, even though it is mostly copying files, because it strips and signs modules using the cross toolchain.
• Installing straight to /lib/modules on the host: always set INSTALL_MOD_PATH when cross-compiling, or you will pollute your development machine with a foreign-architecture module tree.
• Module refuses to load with “invalid module format”: the module’s kernel-release string does not match the running kernel’s uname -r exactly. Rebuild against the exact tree and config that produced the running image.
• Running mrproper without saving your .config first: copy your working config out with cp .config myboard_defconfig_backup before a destructive clean.

Best Practices

• Keep a saved defconfig per board in version control so an mrproper is never destructive to your actual work.
• Use the dedicated modules target for incremental driver work instead of a full image rebuild — it is dramatically faster.
• Always pair a cross-compiled modules_install with the matching INSTALL_MOD_PATH, and copy that staging tree into your root filesystem image as a distinct build step.
• Version your module tree alongside the kernel image you shipped it with, since a mismatch is a common field-support headache.

Summary And Key Takeaways

• The modules target compiles everything configured as m, producing .ko files scattered throughout the source tree.
• modules_install collects those .ko files into a version-keyed directory, and INSTALL_MOD_PATH redirects that collection into a staging root filesystem instead of the build host.
• clean, mrproper, and distclean offer three levels of tree cleanup, with mrproper being the one most embedded developers reach for when reconfiguring from scratch.

Conclusion

Modules give embedded Linux projects real flexibility: smaller boot images, faster driver iteration, and field-updatable hardware support. The mechanics are simple once you see the pipeline as a whole — compile with the modules target, collect with modules_install and INSTALL_MOD_PATH, and reset with mrproper whenever the tree gets into a confusing state. In the next lecture in this free linux device drivers course, we move from building to actually booting a kernel image on real hardware and inside QEMU.

Frequently Asked Questions