Linux Kernel Module Development: A Complete Guide for 2026

1. What Is a Linux Kernel Module?

A Linux kernel module is a compiled piece of object code that can be dynamically loaded into  or unloaded from  the running Linux kernel without requiring a system reboot. Modules extend kernel functionality on demand: device drivers, filesystem support, network protocols, cryptographic subsystems, and custom hardware interfaces are all common use cases.

Unlike user-space programs that run in a sandboxed memory area with system call overhead, kernel modules execute in ring 0  the most privileged CPU mode  with direct access to hardware registers, kernel data structures, and memory-mapped I/O. This is precisely what makes Linux kernel module development both powerful and unforgiving: a single null-pointer dereference in a module causes a kernel panic, not a segmentation fault.

Kernel modules follow a clear lifecycle:

• Compiled as .ko (kernel object) files
• Inserted at runtime via insmod or modprobe
• Registered with the kernel’s internal subsystems
• Removed via rmmod when no longer needed

The Linux kernel maintains a module registry, exports specific symbols that modules can use, and enforces version checks to prevent ABI mismatches between modules and the running kernel.

2. Why Linux Kernel Module Development Matters in 2026

Linux powers over 96% of the world’s top one million web servers, virtually all Android devices, every major cloud hypervisor (AWS Nitro, Google Axion, Azure Cobalt), and most embedded systems from IoT sensors to autonomous vehicles. Understanding Linux at the kernel level is increasingly valuable across several critical domains:

• Custom hardware acceleration  Writing drivers for proprietary NICs, GPUs, FPGAs, or ASICs that lack upstream support. Mpiric’s Platform and Low-Level Systems Engineering service handles exactly this type of kernel-hardware integration.
• Performance-critical networking  Kernel bypass modules using DPDK or eBPF that eliminate user-space overhead for packet processing, a discipline directly covered by Linux Kernel Networking engineering.
• Security modules  LSM (Linux Security Module) extensions for custom mandatory access control policies  core work within Kernel Security and Hardening.
• Filesystems and storage drivers  Custom filesystem modules for specialized storage hardware, covered by Mpiric’s Filesystems and Storage development service.
• Virtualization  KVM (Kernel-based Virtual Machine) extensions for hypervisor tuning in production cloud infrastructure.

In 2026 specifically, the rise of eBPF has shifted some observability workloads, but classical loadable kernel modules remain irreplaceable for device drivers and deep subsystem integration that eBPF cannot reach.

3. Prerequisites Before You Write a Linux Kernel Module

Before diving into Linux kernel module development, ensure you have the following in place.

System Requirements:

• A Linux machine or VM running kernel 5.15+ (LTS recommended); kernel 6.6 or 6.12 LTS are the standard in 2026
• Root or sudo access
• A matching kernel headers package for your exact running kernel version

Knowledge Prerequisites:

• Solid C programming (pointers, structs, function pointers, memory management)
• Basic understanding of OS concepts: virtual memory, system calls, interrupts
• Familiarity with the Linux command line

Tools:

• gcc (GNU Compiler Collection) or clang
• make
• linux-headers package matching your exact kernel version
• dkms (optional, for Dynamic Kernel Module Support across kernel upgrades)

Verify your kernel version and confirm headers are installed:

uname -r

# Example output: 6.6.30-amd64

ls /lib/modules/$(uname -r)/build

# Should show the kernel build directory

Install headers on Debian/Ubuntu:

sudo apt update

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

On RHEL/Fedora/Rocky Linux:

sudo dnf install kernel-devel-$(uname -r) gcc make

4. Core Architecture: How the Linux Kernel Module System Works

Understanding the internals saves hours of debugging. Here is what happens when you write a Linux kernel module and insert it.

4.1 Symbol Tables and the Kernel Export Mechanism

The kernel exposes specific functions and variables to modules via EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). When you call printk(), kmalloc(), or copy_to_user() in your module, you are using symbols the kernel explicitly exports.

When a module is loaded, the kernel’s module loader (kernel/module.c) resolves these external references against the running kernel’s symbol table (/proc/kallsyms). If a required symbol is not exported  or is exported only to GPL-licensed modules (EXPORT_SYMBOL_GPL) and your module lacks a GPL license declaration  loading fails.

4.2 Module Versioning (VERMAGIC)

Every .ko file contains a vermagic string encoding:

• The exact kernel version it was compiled for
• Compiler version
• SMP (symmetric multiprocessing) support flag
• Whether preemption is enabled

The kernel checks vermagic on load. Mismatches cause ERROR: could not insert module: Invalid module format. This is why you must compile modules against headers matching your running kernel. This version sensitivity is one reason Mpiric’s Core Linux Kernel Development practice always maintains kernel-version-matched build environments.

4.3 The Module Lifecycle in the Kernel

insmod / modprobe

▼

sys_init_module (syscall)

▼

Module loaded into memory

Symbol resolution performed

Relocations applied

▼

module->init() called   ← your module_init function

▼

Module active in kernel

▼

rmmod / modprobe -r

▼

module->exit() called   ← your module_exit function

▼

Memory freed, module unregistered

6. Setting Up Your Development Environment

A safe Linux kernel module development workflow separates your build machine from your test machine to avoid crashing a production system. In 2026, the standard approaches are:

Option A  Virtual Machine (Recommended for Beginners) Use QEMU/KVM with a Linux guest. Install the same kernel version in the VM as your headers. Test crashes without affecting your host.

Option B  Docker with Privileged Access For simple module builds (not testing with insmod), a container works:

docker run –rm -it \

–privileged \

-v $(pwd):/module \

ubuntu:24.04 bash

Note: Loading modules inside Docker requires –privileged and a kernel that allows it.

Option C  Dedicated Test Machine For production driver development, a physical machine dedicated to testing is safest. Mpiric’s Platform and Low-Level Systems Engineering team always validates on real hardware targets before any production deployment.

Setting Up VSCode for Kernel Module Development:

Create a .vscode/c_cpp_properties.json file:

{

“configurations”: [

{

“name”: “Linux Kernel”,

“includePath”: [

“/usr/src/linux-headers-${kernelVersion}/include”,

“/usr/src/linux-headers-${kernelVersion}/arch/x86/include”

],

“defines”: [“__KERNEL__”, “MODULE”],

“compilerPath”: “/usr/bin/gcc”,

“cStandard”: “gnu11”

}

]

}

This gives proper IntelliSense for kernel headers  stopping the IDE from flagging printk and MODULE_LICENSE as unknown identifiers.

6. How to Write a Linux Kernel Module: Step-by-Step

6.1 The Minimal Module

Create a file named hello_module.c:

#include <linux/init.h>      /* __init, __exit macros */

#include <linux/module.h>    /* MODULE_LICENSE, MODULE_AUTHOR, etc. */

#include <linux/kernel.h>    /* printk, KERN_INFO */

MODULE_LICENSE(“GPL”);

MODULE_AUTHOR(“Mpiric Software <[email protected]>”);

MODULE_DESCRIPTION(“A minimal Linux kernel module for demonstration”);

MODULE_VERSION(“1.0”);

static int __init hello_init(void)

{

printk(KERN_INFO “hello_module: Module loaded successfully\n”);

return 0;   /* Non-zero return means init_module failed */

}

static void __exit hello_exit(void)

{

printk(KERN_INFO “hello_module: Module unloaded\n”);

}

module_init(hello_init);

module_exit(hello_exit);

6.2 Dissecting Every Line

#include <linux/init.h> Provides the __init and __exit macros. __init marks the function so the kernel can free its memory after initialization completes  a meaningful optimization in memory-constrained environments. __exit marks functions only used during module removal; if the module is compiled directly into the kernel, these are discarded entirely.

#include <linux/module.h> Mandatory for any kernel module. Provides module_init(), module_exit(), MODULE_LICENSE(), and related macros.

MODULE_LICENSE(“GPL”) Critical. Declaring a GPL-compatible license unlocks access to EXPORT_SYMBOL_GPL symbols. Without it, many core kernel functions are unavailable. Options: “GPL”, “GPL v2”, “Dual MIT/GPL”, “Dual BSD/GPL”. Proprietary modules use “Proprietary” but lose access to GPL-only symbols. Licensing strategy in kernel work is something Mpiric’s Upstreaming and Long-Term Maintainability practice navigates carefully for clients preparing code for mainline submission.

printk(KERN_INFO …) The kernel’s logging function. Unlike printf, it writes to the kernel ring buffer (viewable via dmesg). Log levels range from KERN_EMERG (system unusable) to KERN_DEBUG (debug messages). In modern kernels (5.15+), prefer pr_info(), pr_err(), pr_debug()  these wrappers automatically prepend the module name.

module_init() / module_exit() Macros that register your init and exit functions. The kernel calls hello_init during insmod and hello_exit during rmmod.

Return Value from init: Returning 0 signals success. Returning a negative errno value (e.g., -ENOMEM, -ENODEV) causes insmod to fail with the appropriate error code.

7. The Makefile: Building Your Module

The Linux kernel build system (kbuild) handles module compilation. Create a Makefile in the same directory as your source:

# Module name  must match your .c filename (without extension)

obj-m += hello_module.o

# If your module has multiple source files:

# hello_module-objs := file1.o file2.o

# Path to kernel headers

KDIR := /lib/modules/$(shell uname -r)/build

PWD  := $(shell pwd)

all:

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

clean:

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

Build the module:

make

Successful output produces hello_module.ko alongside intermediary files (hello_module.mod.c, hello_module.mod.o, Module.symvers, modules.order).

Understanding obj-m:

• obj-m  Build as a loadable module (.ko)
• obj-y  Build into the kernel itself (used in the kernel source tree, not external modules)

Loading, Verifying, and Unloading Modules

# Insert the module

sudo insmod hello_module.ko

# Verify it is loaded

lsmod | grep hello_module

# Read kernel log output

dmesg | tail -5

# Remove the module

sudo rmmod hello_module

# Confirm removal

dmesg | tail -3

Expected dmesg output:

[ 1234.567890] hello_module: Module loaded successfully

[ 1240.123456] hello_module: Module unloaded

insmod vs modprobe:

• insmod loads a specific .ko file directly; does not resolve dependencies automatically
• modprobe searches /lib/modules/$(uname -r)/ and automatically loads dependency modules listed in modules.dep

For production deployment, always use modprobe. For development iteration with a local .ko, insmod is faster.

Inspecting Module Metadata:

modinfo hello_module.ko

Output includes: filename, license, author, description, version, depends, vermagic.

9. Writing a Character Device Driver Module

A character device exposes a file-like interface (/dev/mydevice) that user-space programs can open(), read(), write(), and close(). This is the foundation of real Linux kernel module development for hardware drivers. Mpiric’s Core Linux Kernel Development team writes character device drivers like this regularly for custom silicon and peripheral hardware. Here is a complete, production-structured example:

#include <linux/init.h>

#include <linux/module.h>

#include <linux/kernel.h>

#include <linux/fs.h>           /* file_operations, register_chrdev */

#include <linux/uaccess.h>      /* copy_to_user, copy_from_user */

#include <linux/cdev.h>         /* cdev structure */

#include <linux/device.h>       /* class_create, device_create */

#define DEVICE_NAME “mpiric_dev”

#define CLASS_NAME  “mpiric”

#define BUFFER_SIZE 256

MODULE_LICENSE(“GPL”);

MODULE_AUTHOR(“Mpiric Software”);

MODULE_DESCRIPTION(“Character device driver example”);

MODULE_VERSION(“1.0”);

static int    major_number;

static char   message_buffer[BUFFER_SIZE] = {0};

static short  message_size;

static struct class  *mpiric_class  = NULL;

static struct device *mpiric_device = NULL;

static int     device_open(struct inode *, struct file *);

static int     device_release(struct inode *, struct file *);

static ssize_t device_read(struct file *, char __user *, size_t, loff_t *);

static ssize_t device_write(struct file *, const char __user *, size_t, loff_t *);

static struct file_operations fops = {

.owner   = THIS_MODULE,

.open    = device_open,

.release = device_release,

.read    = device_read,

.write   = device_write,

};

static int __init chardev_init(void)

{

major_number = register_chrdev(0, DEVICE_NAME, &fops);

if (major_number < 0) {

pr_err(“mpiric_dev: Failed to register major number\n”);

return major_number;

}

mpiric_class = class_create(CLASS_NAME);

if (IS_ERR(mpiric_class)) {

unregister_chrdev(major_number, DEVICE_NAME);

return PTR_ERR(mpiric_class);

}

mpiric_device = device_create(mpiric_class, NULL,

MKDEV(major_number, 0),

NULL, DEVICE_NAME);

if (IS_ERR(mpiric_device)) {

class_destroy(mpiric_class);

unregister_chrdev(major_number, DEVICE_NAME);

return PTR_ERR(mpiric_device);

}

pr_info(“mpiric_dev: Device created at /dev/%s\n”, DEVICE_NAME);

return 0;

}

static void __exit chardev_exit(void)

{

device_destroy(mpiric_class, MKDEV(major_number, 0));

class_unregister(mpiric_class);

class_destroy(mpiric_class);

unregister_chrdev(major_number, DEVICE_NAME);

pr_info(“mpiric_dev: Module unloaded\n”);

}

static int device_open(struct inode *inodep, struct file *filep)

{

pr_info(“mpiric_dev: Device opened\n”);

return 0;

}

static int device_release(struct inode *inodep, struct file *filep)

{

pr_info(“mpiric_dev: Device closed\n”);

return 0;

}

static ssize_t device_read(struct file *filep, char __user *buffer,

size_t len, loff_t *offset)

{

int error_count = copy_to_user(buffer, message_buffer, message_size);

if (error_count == 0) {

pr_info(“mpiric_dev: Sent %d characters to user\n”, message_size);

return (message_size = 0);

}

return -EFAULT;

}

static ssize_t device_write(struct file *filep, const char __user *buffer,

size_t len, loff_t *offset)

{

if (copy_from_user(message_buffer, buffer,

min(len, (size_t)(BUFFER_SIZE – 1))))

return -EFAULT;

message_size = min(len, (size_t)(BUFFER_SIZE – 1));

message_buffer[message_size] = ‘\0’;

return len;

}

module_init(chardev_init);

module_exit(chardev_exit);

9.1 Testing the Character Device

sudo insmod chardev_module.ko

ls -la /dev/mpiric_dev

echo “Hello from Mpiric” | sudo tee /dev/mpiric_dev

sudo cat /dev/mpiric_dev

dmesg | tail -10

The critical copy_to_user / copy_from_user rule: Never directly dereference a user-space pointer in kernel code. User pointers may be invalid, paged out, or pointing to malicious memory. These functions perform the necessary checks and return the number of bytes NOT copied  zero on success.

Kernel Module Parameters

Module parameters allow runtime configuration without recompilation:

#include <linux/moduleparam.h>

static int buffer_size = 256;

static char *device_name = “mpiric_dev”;

static bool debug_mode = false;

module_param(buffer_size, int, 0644);

MODULE_PARM_DESC(buffer_size, “Size of the internal buffer (default: 256)”);

module_param(device_name, charp, 0444);

MODULE_PARM_DESC(device_name, “Name of the character device”);

module_param(debug_mode, bool, 0644);

MODULE_PARM_DESC(debug_mode, “Enable verbose debug logging”);

Loading with parameters:

sudo insmod mymodule.ko buffer_size=512 debug_mode=1

# Change at runtime (if permissions allow):

echo 1024 | sudo tee /sys/module/mymodule/parameters/buffer_size

The third argument to module_param() is the sysfs permission: 0644 allows root to write, everyone to read. 0444 is read-only for everyone. 0000 hides the parameter from sysfs entirely.

11. Debugging Linux Kernel Modules

Debugging kernel code is fundamentally different from user-space debugging  there is no gdb attach for a running kernel module without special setup. Systematic testing and validation here connects directly to what Mpiric’s Fuzzing, Testing, and Validation service covers at production scale.

11.1 printk and Dynamic Debug

# Show all kernel messages in real time

sudo dmesg -w

# Enable debug messages for your module dynamically (no recompile needed)

echo “module hello_module +p” | sudo tee /sys/kernel/debug/dynamic_debug/control

# Enable all debug output for a specific file

echo “file hello_module.c +p” | sudo tee /sys/kernel/debug/dynamic_debug/control

11.2 KGDB  Kernel GNU Debugger

KGDB allows full GDB-style debugging of a running kernel via a serial connection or kgdboc. In a QEMU VM:

# Boot VM with: kgdboc=ttyS0,115200 kgdbwait

gdb vmlinux

(gdb) target remote /dev/ttyS0

(gdb) lx-symbols /path/to/module/dir

(gdb) break hello_init

(gdb) continue

11.3 KASAN  Kernel Address Sanitizer

Build your test kernel with CONFIG_KASAN=y to automatically catch use-after-free, out-of-bounds memory access, and similar memory safety bugs. In 2026, KASAN is standard in debugging kernels and heavily used as part of Fuzzing, Testing, and Validation workflows for production kernel code.

11.4 Ftrace  Function Tracing

echo ‘hello_*’ > /sys/kernel/debug/tracing/set_ftrace_filter

echo function > /sys/kernel/debug/tracing/current_tracer

echo 1 > /sys/kernel/debug/tracing/tracing_on

cat /sys/kernel/debug/tracing/trace

11.5 /proc Interface for Module Diagnostics

#include <linux/proc_fs.h>

#include <linux/seq_file.h>

static int mpiric_proc_show(struct seq_file *m, void *v)

{

seq_printf(m, “Buffer size: %d\n”, buffer_size);

seq_printf(m, “Debug mode: %s\n”, debug_mode ? “on” : “off”);

return 0;

}

/* Register in init: */

proc_create_single(“mpiric_status”, 0, NULL, mpiric_proc_show);

/* Remove in exit: */

remove_proc_entry(“mpiric_status”, NULL);

12. Security Hardening in Kernel Module Development

Security is not optional in Linux kernel module development  a vulnerable kernel module compromises the entire system at ring 0. Mpiric’s dedicated Kernel Security and Hardening practice applies exactly these principles to production systems, covering SELinux policy development, AppArmor, secure boot implementation, and vulnerability assessment.

12.1 Secure Coding Practices

Validate all inputs from user space:

if (len > BUFFER_SIZE || len == 0)

return -EINVAL;

Use kzalloc instead of kmalloc for security-sensitive buffers:

/* kzalloc zero-initializes  prevents information leaks from uninitialized memory */

char *buf = kzalloc(size, GFP_KERNEL);

if (!buf)

return -ENOMEM;

kfree(buf);

Never use strcpy or sprintf  use bounded versions:

strncpy(dest, src, sizeof(dest) – 1);

dest[sizeof(dest) – 1] = ‘\0’;

snprintf(buf, sizeof(buf), “Value: %d”, value);

12.2 Module Signing

Production kernels enforce module signature verification (CONFIG_MODULE_SIG):

# Generate a key pair (one-time setup)

openssl req -new -x509 -newkey rsa:4096 \

-keyout signing_key.pem -out signing_cert.pem \

-days 3650 -subj “/CN=Mpiric Module Signing/”

# Sign the module

/usr/src/linux-headers-$(uname -r)/scripts/sign-file \

sha256 signing_key.pem signing_cert.pem hello_module.ko

On Secure Boot systems, the signing certificate must also be enrolled in the Machine Owner Key (MOK) database. This signing workflow is a core part of responsible Kernel Security and Hardening for any production deployment.

12.3 Linux Security Modules (LSM) Integration

If building policy-enforcing modules, integrate with the LSM framework (which underpins SELinux, AppArmor, and Landlock) rather than bypassing it. The security_* hooks in <linux/security.h> provide the approved interception points for custom access control logic.

13. Kernel Module Development for Cloud and DevOps Pipelines

Modern teams integrating Linux kernel module development into CI/CD pipelines face a unique challenge: you cannot simply run unit tests in a container without a real kernel. Getting this right is a significant part of Fuzzing, Testing, and Validation work at enterprise scale.

13.1 DKMS  Dynamic Kernel Module Support

DKMS automatically recompiles your module whenever the kernel updates  critical for production systems:

sudo apt install dkms

# /usr/src/mpiric-1.0/dkms.conf

PACKAGE_NAME=”mpiric”

PACKAGE_VERSION=”1.0″

BUILT_MODULE_NAME[0]=”hello_module”

DEST_MODULE_LOCATION[0]=”/updates”

AUTOINSTALL=”yes”

sudo dkms add -m mpiric -v 1.0

sudo dkms build -m mpiric -v 1.0

sudo dkms install -m mpiric -v 1.0

13.2 CI/CD with QEMU Kernel Testing

# GitHub Actions example

– name: Build module

run: make

– name: Test with QEMU

run: |

qemu-system-x86_64 \

-kernel $KERNEL_IMAGE \

-initrd $INITRD \

-append “console=ttyS0 quiet” \

-serial stdio \

-no-reboot \

-nographic \

— insmod /modules/hello_module.ko && dmesg | grep hello

13.3 Upstreaming Your Module

If your module provides functionality that benefits the broader Linux ecosystem, consider upstreaming it to the mainline kernel. Mainlined code receives security patches, architecture support, and long-term maintenance from the global kernel community  dramatically reducing internal maintenance burden. Mpiric’s Upstreaming and Long-Term Maintainability service manages this process end-to-end. For teams engaged in open collaboration, Open Linux Kernel Engagements provides a structured path to upstream contribution.

13.4 eBPF as a Complement

For observability and network filtering use cases that previously required kernel modules, eBPF programs offer a safer, more portable alternative  verified by the kernel before execution. For performance-critical networking, Mpiric’s Linux Kernel Networking team applies eBPF alongside traditional modules based on what each use case requires.

14. Common Mistakes and How to Avoid Them

14.1 Forgetting to Free Resources on Error Paths

static int __init mymod_init(void)

{

major = register_chrdev(0, DEVICE_NAME, &fops);

if (major < 0) return major;

cls = class_create(CLASS_NAME);

if (IS_ERR(cls)) {

unregister_chrdev(major, DEVICE_NAME);        /* Undo step 1 */

return PTR_ERR(cls);

}

dev = device_create(cls, NULL, MKDEV(major, 0), NULL, DEVICE_NAME);

if (IS_ERR(dev)) {

class_destroy(cls);                           /* Undo step 2 */

unregister_chrdev(major, DEVICE_NAME);        /* Undo step 1 */

return PTR_ERR(dev);

}

return 0;

}

14.2 Race Conditions Without Proper Locking

#include <linux/mutex.h>

static DEFINE_MUTEX(mpiric_mutex);

static ssize_t device_write(…)

{

if (mutex_lock_interruptible(&mpiric_mutex))

return -ERESTARTSYS;

memcpy(message_buffer, buffer, len);   /* Protected critical section */

mutex_unlock(&mpiric_mutex);

return len;

}

Use spinlock_t for interrupt handlers where sleeping is not allowed. Use mutex in process context where sleeping is permitted.

14.3 Using GFP_KERNEL in Atomic Context

/* In an interrupt handler or atomic context: */

buf = kmalloc(size, GFP_ATOMIC);    /* Never sleeps */

/* In process context: */

buf = kmalloc(size, GFP_KERNEL);    /* Can sleep, preferred when possible */

14.4 Direct Access to User Pointers

/* WRONG */

memcpy(kernel_buf, user_ptr, len);

/* CORRECT */

if (copy_from_user(kernel_buf, user_ptr, len))

return -EFAULT;

14.5 Holding Spinlocks Across Sleeping Operations

Spinlocks disable preemption on the current CPU. Never call functions that can sleep (kmalloc(GFP_KERNEL), mutex_lock, copy_from_user, schedule()) while holding a spinlock. The kernel will warn or deadlock.

15. Quick Reference: Key Kernel APIs

Conclusion

Linux kernel module development occupies the deepest layer of systems programming  where your code runs with no safety net, full hardware access, and real consequences for bugs. In 2026, it remains essential for device drivers, performance-critical networking, filesystem engineering, security enforcement, and custom hardware integration.

The path from a minimal hello_module.ko to a production character device driver involves understanding symbol exports, the kbuild system, user-space boundaries enforced by copy_to_user, concurrency handled by locks, and security hardened by module signing  each layer building on the last.

Mpiric Software’s Linux Development practice covers this entire stack  from Core Linux Kernel Development and Kernel Security and Hardening to Filesystems and Storage, Linux Kernel Networking, and Upstreaming and Long-Term Maintainability. As a Linux Foundation Silver Member, the team brings both the depth and the community standing to deliver kernel work that lasts.

If your team needs expert guidance on Linux kernel module development, driver engineering, or kernel-level systems  get in touch or learn more about Mpiric.