Your First Kernel Module: Hello, World

The Linux kernel is a monolithic kernel, which means — at first glance — that all of the kernel's code runs in a single, enormous address space at ring 0. But monolithic does not mean static. Linux supports loadable kernel modules (LKMs): ELF shared-object files (.ko files — kernel object) that are linked into the running kernel image on demand.

Think of the kernel as a city. The city has a permanent skyline — the core kernel built at compile time (vmlinux). Modules are like prefabricated buildings that get craned in and bolted on while the city is fully occupied and running. When you no longer need a building, you crane it back out. The city never shuts down.

Technically: a .ko file is a relocatable ELF object (type ET_REL). It is not a self-contained executable. When you call insmod or modprobe, the kernel's module loader reads the ELF sections, performs kernel-space relocation (adjusting symbol references to match where the kernel's own symbols actually live in memory), allocates a region in the module memory area (historically near the kernel text in x86-64 to satisfy 32-bit RIP-relative calls), and then calls your init function. This is analogous to dlopen() in userspace, but with none of the safety nets.

Key consequences:

• Your module code runs at ring 0 — the same privilege level as the scheduler. A bug in your module is a bug in the kernel.
• Your module shares the kernel's virtual address space. You can call any exported kernel function directly.
• There is no separate heap. malloc does not exist. You use kmalloc, vmalloc, or slab caches.
• There is no page fault handler for kernel NULL dereferences (on most configs) — it is an immediate kernel panic or oops.

# Check if your kernel supports modules (almost always yes)
grep CONFIG_MODULES /boot/config-$(uname -r)
# Should print: CONFIG_MODULES=y

# See currently loaded modules
lsmod | head -20

# Inspect a .ko file as ELF (after you build one)
readelf -h hello.ko        # ELF type should be ET_REL
readelf -s hello.ko        # symbol table
readelf -S hello.ko        # section headers

A minimal kernel module has exactly four required elements:

1. #include guards — the kernel has its own header tree under include/ and arch/*/include/. You never include <stdio.h> or <stdlib.h>. Everything you need lives under <linux/...>.
2. MODULE_LICENSE — this is not optional boilerplate. The kernel uses this macro to decide whether to mark itself as tainted when your module loads. A tainted kernel is a kernel that is running non-GPL code; many kernel developers will refuse to investigate a bug report from a tainted kernel. Use "GPL" (or "GPL v2", "Dual MIT/GPL", etc.).
3. An init function tagged with module_init()** — called when the module is inserted. Returns 0 on success, negative errno on failure.
4. An exit function tagged with module_exit()** — called when the module is removed. Returns void — by the time this runs, the module is already being torn down; there is no way to abort.

The __init and __exit annotations are important but subtle. __init tells the linker to place the function in the .init.text ELF section. For built-in kernel code (compiled directly into vmlinux, not a module), the kernel frees this section after boot — the init code is literally thrown away to reclaim memory. For modules, __init is less critical but still conventional; it signals intent and future-proofs your code if someone ever merges it into the core kernel.

The __exit annotation similarly goes into .exit.text. For built-in code, this section is never linked — there is no unloading a built-in. For modules it is retained and called on rmmod.

// hello.c — a complete, correct, minimal kernel module
#include <linux/init.h>    // __init, __exit macros
#include <linux/module.h>  // module_init, module_exit, MODULE_* macros
#include <linux/kernel.h>  // KERN_INFO, printk

MODULE_LICENSE("GPL");           // required; taints kernel if missing/non-GPL
MODULE_AUTHOR("Your Name");
MODULE_DESCRIPTION("Hello, kernel world");
MODULE_VERSION("0.1");

static int __init hello_init(void)
{
    printk(KERN_INFO "hello: module loaded\n");
    return 0;  // 0 = success; negative errno = failure, module won't load
}

static void __exit hello_exit(void)
{
    printk(KERN_INFO "hello: module unloaded\n");
    // void return — no way to abort at this point
}

module_init(hello_init);
module_exit(hello_exit);

The Linux kernel does not use a plain Makefile — it uses Kbuild, a sophisticated recursive make infrastructure that has been evolving since before most readers of this module were born. When you build a module, you are hooking into Kbuild, not replacing it.

The critical insight: your Makefile does not actually do the compilation. Your Makefile tells Kbuild what object files make up your module, and then Kbuild — running inside the kernel source tree — handles all compiler flags, CFLAGS, ABI checks, and ELF magic.

Here is what the two-phase Makefile trick does:

• Phase 1 (first make invocation): KERNELDIR is not set, so the all target runs. It calls make again, but this time changes directory to the kernel build tree ($(KERNELDIR)) and passes M=$(PWD) back. M tells Kbuild "look in this external directory for the module source".
• Phase 2 (Kbuild running in the kernel tree): Kbuild reads your Makefile again, but this time KERNELDIR is set (it is the current directory), so it skips the outer branch and only sees the obj-m assignment. obj-m := hello.o means "build hello.o as a module object".

The obj-m syntax is Kbuild's object list. If your module had multiple source files (hello_core.c, hello_proc.c), you would write:

hello-objs := hello_core.o hello_proc.o
obj-m := hello.o

Kbuild links hello_core.o and hello_proc.o into hello.ko automatically.

The -C $(KERNELDIR) flag is essential: it gives Kbuild access to the kernel's .config, the generated headers (include/generated/), the module symbol map (Module.symvers), and all the ABI/version magic that ensures your module will actually load into this kernel and not some incompatible version.

# Makefile (place in same directory as hello.c)

# The kernel build directory. On a Debian/Ubuntu system this is
# /lib/modules/<kernel-version>/build, which is a symlink to the
# actual kernel headers/source used to build the running kernel.
KERNELDIR ?= /lib/modules/$(shell uname -r)/build

# obj-m tells Kbuild: build hello.o as a module (.ko)
obj-m := hello.o

# Default target: invoke Kbuild from the kernel tree,
# pointing M back at our source directory.
all:
	$(MAKE) -C $(KERNELDIR) M=$(PWD) modules

# Clean: again delegate to Kbuild
clean:
	$(MAKE) -C $(KERNELDIR) M=$(PWD) clean

# Install the module into the running kernel's module tree
install:
	$(MAKE) -C $(KERNELDIR) M=$(PWD) modules_install

"Out-of-tree" (OOT) means your module source lives outside the kernel source tree. This is the standard workflow for driver development and for learning: you do not need to download the full 30 GB kernel repository. You only need the kernel headers for the running kernel.

Prerequisites on Debian/Ubuntu:

sudo apt install linux-headers-$(uname -r) build-essential

This installs the headers package, which contains the Kbuild infrastructure and generated headers (but not all kernel source files). It is enough to build out-of-tree modules.

What make produces:

After a successful build you will see several files. The important ones are:

• hello.ko — the final kernel object. This is what you load.
• hello.o — the compiled object file before module-specific processing.
• hello.mod.c — auto-generated C file that contains module metadata: the version magic string, the license, parameter descriptors, and symbol version checksums. You did not write this file — Kbuild generates it.
• hello.mod.o — compiled version of hello.mod.c.
• Module.symvers — a map of exported symbols and their CRC checksums. Critical when one module depends on another.
• .hello.ko.cmd — a tiny file recording the exact compiler invocation. Useful for debugging build issues.

The version magic is the most important build artifact you cannot see directly. Run modinfo hello.ko and look at the vermagic field. It will look like 6.1.0-21-amd64 SMP preempt mod_unload modversions aarch64. This string must exactly match the running kernel's vermagic, or insmod will refuse to load the module with an Invalid module format error. This is a safety check: a module built against the 6.1 headers will have a different ABI than the 6.6 kernel, and loading it could corrupt data structures.

# Full build and inspection workflow

# 1. Install prerequisites (Debian/Ubuntu)
sudo apt install linux-headers-$(uname -r) build-essential

# 2. Build
make
# Output: hello.ko (among others)

# 3. Inspect the module metadata — no root needed
modinfo hello.ko
# filename:       /path/to/hello.ko
# description:    Hello, kernel world
# author:         Your Name
# license:        GPL
# version:        0.1
# vermagic:       6.1.0-21-amd64 SMP preempt mod_unload modversions x86_64

# 4. Check the ELF type (should be ET_REL, a relocatable object)
readelf -h hello.ko | grep Type
# Type: REL (Relocatable file)

# 5. See which kernel symbols your module references
nm hello.ko | grep " U "   # U = undefined, resolved at load time
# e.g.:  U printk
#        U __this_module

There are two userspace tools for loading modules: insmod and modprobe. They are not the same.

insmod path/to/hello.ko — the dumb loader. It reads the file you point it at, hands the raw ELF bytes to the init_module(2) system call, and the kernel does all the heavy lifting: relocation, symbol resolution, version magic check, and calling your init function. insmod has no awareness of dependencies between modules.

modprobe module_name — the smart loader. It reads /lib/modules/$(uname -r)/modules.dep (a dependency graph built by depmod) and automatically loads all prerequisite modules in the right order before loading yours. For production drivers you always use modprobe. For development you often use insmod directly because you have not yet run depmod to register your new module.

What happens inside the kernel during insmod:

1. The finit_module(2) syscall (modern kernels) or init_module(2) receives the module's ELF bytes.
2. The kernel calls load_module() in kernel/module/main.c.
3. ELF sections are parsed and validated.
4. The module's vermagic is checked against the running kernel.
5. A memory region is allocated in module space using module_alloc().
6. Relocations are applied: every U (undefined) symbol reference in your .ko is resolved against the kernel's exported symbol table (/proc/kallsyms).
7. If CONFIG_MODVERSIONS is enabled, symbol CRCs are checked.
8. Your __init function is called. If it returns 0, the module is live. If it returns non-zero, the kernel calls your exit function immediately and frees everything.

rmmod hello — calls delete_module(2). The kernel checks that no other module depends on yours and that your module's reference count is zero (no one is actively using it). Then it calls your __exit function and frees the module's memory region.

# Load the module (requires root / CAP_SYS_MODULE)
sudo insmod ./hello.ko

# Verify it is loaded
lsmod | grep hello
# hello                  16384  0
# (name, size in bytes, reference count)

# See it in /proc/modules (raw format)
grep hello /proc/modules

# See it in /sys/module/ (structured sysfs tree)
ls /sys/module/hello/
# coresize  holders  initsize  notes  parameters  refcnt  sections  taint

# Unload
sudo rmmod hello

# If rmmod fails with "Module is in use":
# Someone holds a reference. Find out who:
cat /sys/module/hello/holders/   # lists dependent modules

# Using modprobe for a module that's been depmod-registered:
sudo cp hello.ko /lib/modules/$(uname -r)/extra/
sudo depmod -a
sudo modprobe hello

Inside the kernel, printf does not exist. There is no stdout, no FILE*, no libc. Instead you have printk() — the kernel's internal logging function, one of the most important functions in all of kernel code.

printk writes messages into the kernel ring buffer (/dev/kmsg, also readable via dmesg). The ring buffer is a circular, fixed-size buffer in kernel memory (default 512 KB, configurable via CONFIG_LOG_BUF_SHIFT). When it fills up, old messages are overwritten. This is why on a busy system with verbose logging you can miss messages.

Log levels. Every printk call should specify a log level as a prefix string. These are defined in <linux/kern_levels.h> and are simply 2-character string literals ("\001" + digit) that printk's format parser extracts:

Messages at or above the console log level (/proc/sys/kernel/printk first field, default 7 = WARNING) are also printed to the system console in real time. Messages below that level go only to the ring buffer and must be read via dmesg.

pr_info, pr_err, dev_info, etc. Modern kernel code almost never calls printk directly. Instead it uses wrapper macros: pr_info(fmt, ...), pr_err(fmt, ...), pr_debug(fmt, ...). These expand to printk(KERN_INFO fmt, ...) etc., but also prepend the module name automatically via the pr_fmt macro. Driver code uses dev_info(dev, fmt, ...) which additionally prepends the device path — crucial for disambiguation in production.

pr_debug is special: it compiles to a no-op unless DEBUG is defined or CONFIG_DYNAMIC_DEBUG is enabled. Always use pr_debug for verbose tracing, never pr_info, so you do not flood production logs.

// Modern printk usage in a real module

// Define pr_fmt BEFORE including linux/module.h
// This prefix appears on every pr_*() message from this file
#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt

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

MODULE_LICENSE("GPL");

static int __init hello_init(void)
{
    pr_info("module loaded\n");          // KERN_INFO with module prefix
    pr_warn("this is a warning\n");      // KERN_WARNING
    pr_debug("only visible with DEBUG\n"); // no-op unless DEBUG defined

    // Raw printk — valid but old-style
    printk(KERN_INFO "raw printk message\n");

    // Print numeric values — same format specifiers as printf,
    // PLUS kernel-specific ones:
    printk(KERN_INFO "pointer: %p, kernel ptr safe: %pK\n",
           &hello_init, &hello_init);

    return 0;
}

static void __exit hello_exit(void)
{
    pr_info("module unloaded\n");
}

module_init(hello_init);
module_exit(hello_exit);

// --- Reading the ring buffer ---
// dmesg | tail -5
// dmesg -w          (follow, like tail -f)
// dmesg --level=err,warn   (filter by level)
// cat /dev/kmsg     (raw, includes timestamps and sequence numbers)

Hard-coded values in kernel modules are rarely useful. module_param() is the mechanism that lets you pass arguments to a module at load time — analogous to argv for userspace programs, but type-safe and also accessible via sysfs after loading.

The three-argument macro:

module_param(name, type, permissions);

• name — the name of a static variable in your module (must be declared before the macro).
• type — one of: bool, int, uint, long, ulong, charp (char pointer), short, ushort.
• permissions — an octal bitmask for the sysfs file that will be created under /sys/module/<name>/parameters/. Use 0 to not create a sysfs entry, 0444 for read-only, 0644 for read-write (allows changing the parameter while the module is loaded!).

You must also call MODULE_PARM_DESC() — this is not optional for good kernel code. It populates the description shown by modinfo and is the only documentation for your parameter that users will see without reading your source.

Array parameters use module_param_array(name, type, nump, permissions) where nump is a pointer to an int that receives the number of elements actually provided by the user.

Security note: Be careful with 0644 permissions on parameters that affect kernel behavior in security-sensitive ways. An unprivileged read of /sys/module/your_module/parameters/secret_key is a real attack surface.

#define pr_fmt(fmt) KBUILD_MODNAME ": " fmt
#include <linux/init.h>
#include <linux/module.h>
#include <linux/kernel.h>

MODULE_LICENSE("GPL");
MODULE_AUTHOR("You");
MODULE_DESCRIPTION("Hello with parameters");

// Declare the variables FIRST
static char *whom = "world";   // default value
static int  howmany = 1;

// Register them as module parameters
module_param(whom,    charp, 0444);  // read-only from sysfs
module_param(howmany, int,   0644);  // read-write from sysfs

MODULE_PARM_DESC(whom,    "Who to greet (default: world)");
MODULE_PARM_DESC(howmany, "How many greetings (default: 1)");

static int __init hello_init(void)
{
    int i;
    if (howmany <= 0 || howmany > 100) {
        pr_err("howmany must be 1-100, got %d\n", howmany);
        return -EINVAL;  // standard errno: invalid argument
    }
    for (i = 0; i < howmany; i++)
        pr_info("Hello, %s! (greeting %d/%d)\n", whom, i + 1, howmany);
    return 0;
}

static void __exit hello_exit(void)
{
    pr_info("Goodbye, %s\n", whom);
}

module_init(hello_init);
module_exit(hello_exit);

// --- Usage ---
// sudo insmod hello.ko whom="kernel" howmany=3
// modinfo hello.ko   # shows parm: lines
// cat /sys/module/hello/parameters/howmany  # read current value
// echo 5 | sudo tee /sys/module/hello/parameters/howmany  # change live

Kernel development does not have a comfortable REPL. Your loop is: edit → build → load → observe → unload → repeat. Mastering this loop efficiently is one of the most valuable skills in kernel development.

The inner loop:

edit hello.c  →  make  →  sudo insmod hello.ko  →  dmesg | tail  →  sudo rmmod hello

Using a VM. For anything beyond hello-world, always develop inside a virtual machine. A kernel oops in a VM is a 10-second reboot. A kernel panic on your laptop means losing unsaved work across your desktop. QEMU with KVM is the standard choice. Tools like virtme-ng or syzkaller's VM harness make spinning up a test kernel trivial.

Reading kernel oops messages. When your module causes a kernel oops (a recoverable fault — the kernel logs the error but tries to continue), you will see a block like:

[  142.301924] BUG: kernel NULL pointer dereference, address: 0000000000000000
[  142.301926] RIP: 0010:hello_init+0x12/0x20 [hello]
[  142.301929] Call Trace:
[  142.301930]  do_one_initcall+0x41/0x1c0

The RIP line tells you: the fault was at hello_init + 0x12 bytes offset inside the hello module. Use objdump -d hello.ko to disassemble and find that offset.

addr2line and faddr2line. The kernel provides scripts/faddr2line to translate a function+offset into a source line number:

./scripts/faddr2line hello.ko hello_init+0x12

Dynamic debug. Once you move beyond hello-world, pr_debug messages can be enabled at runtime without recompiling:

echo 'module hello +p' | sudo tee /sys/kernel/debug/dynamic_debug/control

This is one of the most powerful kernel debugging tools available.

#!/bin/bash
# A simple development helper script — save as dev.sh
# Usage: ./dev.sh [build|load|unload|reload|log]

MOD=hello
KO=./${MOD}.ko

case "$1" in
  build)
    make && modinfo $KO | grep -E 'vermagic|license|description'
    ;;
  load)
    sudo insmod $KO "${@:2}" && echo "Loaded" && dmesg | tail -5
    ;;
  unload)
    sudo rmmod $MOD && echo "Unloaded" && dmesg | tail -3
    ;;
  reload)
    sudo rmmod $MOD 2>/dev/null; sudo insmod $KO "${@:2}" && dmesg | tail -5
    ;;
  log)
    # Follow the kernel log live — Ctrl-C to stop
    dmesg -w
    ;;
  *)
    echo "Usage: $0 {build|load|unload|reload|log}"
    ;;
esac

# One-liner debug build with pr_debug enabled:
# make ccflags-y=-DDEBUG && sudo insmod hello.ko && dmesg | tail

The MODULE_LICENSE() macro is not just metadata — it has real mechanical consequences inside the kernel.

When the kernel loads a module, it inspects the license string. If the license is not a recognized open-source license (GPL, GPL v2, GPL and additional rights, Dual MIT/GPL, Dual BSD/GPL, etc.), the kernel sets a taint flag in tainted (readable at /proc/sys/kernel/tainted). A tainted kernel means:

1. Many kernel developers will ignore your bug reports.
2. WARN_ON macros may suppress output.
3. Some kernel subsystems refuse to operate in tainted mode.
4. Crash dumps submitted to distributions are deprioritized.

More importantly: the kernel exports two classes of symbols — EXPORT_SYMBOL and EXPORT_SYMBOL_GPL. GPL-only symbols (the majority of interesting ones: usb_register, request_irq, alloc_netdev, etc.) are only accessible to modules with a GPL-compatible license. If your module declares MODULE_LICENSE("Proprietary") and tries to use a GPL-only symbol, insmod will fail with ERROR: insmod: FATAL: Module hello not permitted to use GPL-only symbol 'xyz'.

This is a deliberate policy decision by Linus Torvalds and the kernel maintainers. The kernel's exported ABI is considered part of a GPL-licensed work, and they use EXPORT_SYMBOL_GPL to enforce that commercial vendors who want to ship proprietary kernel modules cannot simply call into the kernel's core infrastructure without a GPL-compatible license.

For learning and contributing: always use MODULE_LICENSE("GPL") or MODULE_LICENSE("GPL v2"). It is the right choice technically and philosophically.

// Illustration of what tainting looks like
// DO NOT use "Proprietary" in real code

MODULE_LICENSE("Proprietary");  // sets TAINT_PROPRIETARY_MODULE bit

// After insmod:
// $ cat /proc/sys/kernel/tainted
// 4096   (bit 12 = TAINT_UNSIGNED_MODULE or similar)
//
// $ dmesg | grep taint
// hello: module license 'Proprietary' taints kernel.
// Disabling lock debugging due to kernel taint

// --- Checking exported symbol class ---
// GPL-only symbols have '\t[gpl]' in /proc/kallsyms:
// grep request_irq /proc/kallsyms
// ffffffff813abc00 T request_irq   <- GPL-only in some kernel versions

// The correct declaration for a learning/contribution module:
MODULE_LICENSE("GPL v2");