Build note
Kernel modules: no main(), and a thread bug that hung the load
Everything I had written until then ran as a process. It had a main(), it
printed to a terminal, and when it misbehaved I could kill it. A kernel module
has none of that. It is code the running kernel calls, so a mistake does not
crash one program, it takes the machine with it.
I worked through this in c-23-kernel in my C playground: a hello module, then
parameters, then kernel threads, then a GPIO driver. These are the parts that
changed how I write code, and the bugs that made the lessons stick.
There is no main()
A module declares two functions and hands them to the kernel:
static int __init hello_init(void) { pr_info("Hello Kernel World!\n"); return 0; }
static void __exit hello_exit(void) { pr_info("Goodbye Kernel World!\n"); }
module_init(hello_init);
module_exit(hello_exit);
module_init decides what runs when the module loads. module_exit decides what
runs when it unloads. There is no entry point you call yourself.
pr_info is the kernel’s printf, and it does not print to your terminal. It
writes to the kernel log ring buffer, which you read with dmesg. If you load a
module and see nothing, you are almost certainly looking at the wrong stream.
Two more things cost me time:
MODULE_LICENSE("GPL")is not decoration. Without it the kernel marks itself tainted and refuses to give you some symbols.- A
.kocarries avermagicstring. Build it against the headers for the running kernel, or the load fails with “Invalid module format”.uname -randmodinfo -F vermagicshould agree.
The Makefile is one line
obj-m += kernel_hello.o
That is the whole file. It names the object file, not the .ko, and the name has
to match the source. The kernel build system supplies the rest, which is why you
build it like this:
make -C /lib/modules/$(uname -r)/build M=$PWD modules
-C borrows the kernel’s own build rules. M=$PWD says the module lives here.
The output includes the .ko you load plus a pile of .o, .mod.c and .cmd
files that are machine-specific and should never be committed.
Load by path, or install by name
insmod takes a file. modprobe takes a name, and only looks in the kernel’s
module directories, so a module you just built is invisible to it until you file
it and rebuild the index:
sudo install -D -m 0644 kernel_hello.ko /lib/modules/$(uname -r)/misc/
sudo depmod -a
sudo modprobe kernel_hello
That depmod step is the one people forget. modprobe is a librarian: it can
only fetch books it has catalogued.
Parameters are almost free
static int my_value = 1978;
module_param(my_value, int, 0644);
MODULE_PARM_DESC(my_value, "An integer module parameter for demo purposes");
Three lines give you a load-time argument and a file under
/sys/module/<name>/parameters/. You can set it when loading with
my_value=999, read it with cat, and change it live by writing to the file.
With 0644 only root can write, which is the right default for anything that
touches hardware.
Threads, and the bug that hung the load
A kernel thread is created with kthread_run (create and start) or
kthread_create plus wake_up_process (create, then start when you are ready).
The thread function has a fixed shape:
static int worker(void *data)
{
while (!kthread_should_stop()) {
// do work
msleep(500);
}
return 0;
}
kthread_should_stop() is not optional. It is how kthread_stop() asks the
thread to finish, and a loop that ignores it will not unload cleanly.
My module hung on load. Init was waiting on a completion, and the thread only
signals that completion when it exits. Since the thread was meant to run until
the module was unloaded, the wait never ended, and insmod never returned.
The fix was to move the waiting out of init. Init creates the threads and
returns. exit calls kthread_stop and then waits, if it needs to:
kthread_stopsets the stop flag and wakes the thread. Do not call it from inside the thread it is stopping.- Only stop a thread that was actually created. Check for
NULLandIS_ERRfirst, or you are passing garbage to the kernel. - Stop threads in the reverse order of creation, and clear the pointer after.
- If thread two fails to start, stop thread one before returning the error. Otherwise init fails and leaves a thread running.
Two of my files still have MODULE_AUTHOR("Your Name") in them because I
started from a template. modinfo shows it. Copy-paste leaves fingerprints.
Talking to GPIO registers
The GPIO module maps the Pi’s register block with ioremap, then writes bits
directly:
GPFSELnholds ten pins per register, three bits each. GPIO 17 lives inGPFSEL1at bit 21.GPSET0andGPCLR0turn a pin on and off. Writing a 1 toGPSET0sets the pin; writing a 1 toGPCLR0clears it.- Read and write MMIO with
ioread32andiowrite32, not with a plain pointer.
The bug I hit was the register offset. The code had GPFSEL0 + reg where reg
was a register index. Offsets are in bytes, so it needs reg * 4. The write went
to the wrong register and the pin never changed. The source still carries the
comment FIXED: Multiply by 4 for byte offset! next to the line.
What I would tell myself before starting
- Read
dmesg -win a second terminal before loading anything. Watching the log turn a hang into a message is most of the debugging. - Build against
uname -r, and rebuild after a kernel update. ls /sys/module/<name>tells you whether the kernel thinks it is live, how many references it holds, and where its memory went.- Keep init short. Do the setup, start what needs starting, return.
- Every allocation in init needs a matching release in exit, including
iounmap. - Test in a VM or on a spare Pi. A module bug is a kernel bug.
How this was made
- Written by: Rupesh, from his own
c-23-kernelnotes and module source, with AI drafting and editing. - Numbers and register details: from the module source and the kernel documentation.
- AI-assisted sections: structure and copy editing.