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 .ko carries a vermagic string. Build it against the headers for the running kernel, or the load fails with “Invalid module format”. uname -r and modinfo -F vermagic should 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_stop sets 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 NULL and IS_ERR first, 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:

  • GPFSELn holds ten pins per register, three bits each. GPIO 17 lives in GPFSEL1 at bit 21.
  • GPSET0 and GPCLR0 turn a pin on and off. Writing a 1 to GPSET0 sets the pin; writing a 1 to GPCLR0 clears it.
  • Read and write MMIO with ioread32 and iowrite32, 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 -w in 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-kernel notes 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.