The Hello World Kernel Module

printk() != printf()

To print Hello World on "the kernel debug log level", we'll need to use another, very old, function called printk(). Unlike the printf() commonly used in userspace applications, printk() is not designed to communicate to the user (or say hello to worlds). It's a logging mechanism used to give warnings and to log messages. This is why each printk() statement also comes with a priority. There are currently 8 defined priorities we can use ranging from KERN_DEBUG to KERN_EMERG. You can see them all, and their definitions, currently (version 5.7) in linux/kern_levels.h in the source code.

Pay attention to the single argument passed to printk(). Looking into the source code shows that printk(const char *ftm, ...) accepts only one string, with space to pass extra arguments to format the string if needed, for example, our "Hello World" statement from above, which doesn't need formatting and therefore passes no extra arguments:

printk(KERN_DEBUG "Hello World.\n");

The KERN_DEBUG macro will expand to "\001" "7", turning our statement into:

printk("\001" "7" "Hello World.\n");

Our C lexer will then combine the adjacent string literals to produce our formatted string for the kernel to log:

printk("\0017Hello World.\n");

Even though printk() is falling out of style with modern Linux maintainers, as we will see in later sections, there is a lot more to read about how to work with printk() and format specifiers in the kernel in the documentation here if you're into that kind of stuff.

Kbuild Makefile

Just like Makefiles in userspace, we can start a Kbuild Makefile by creating a new file called …wait for it… Makefile in the same folder as our hello-world.c module we made in the sections above.

$ ls -l
total 8
-rw-rw-r-- 1 me us 903 Jul  5 00:00 hello-world.c
-rw-rw-r-- 1 me us 167 Jul  5 00:00 Makefile

We can alternatively use the name Kbuild (not preferred) to indicate to other developers that the Makefile is intended to run using the kbuild system. However, while the Kbuild name is not preferred, interestingly, if both Makefile and Kbuild files exist in the same directory the Kbuild file will be used. (source)

Goal Definitions

The "heart" of the kbuild system uses lines called "goal definitions" to define all the various target files, special compilation options, and any sub-directories to enter. When we compile the kernel (with its thousands of Makefiles) the goal definitions are collected and used to build all the various, documentation files, modules, and other files we need for our particular kernel.

The simplest Kbuild Makefile we can write for our module contains a single line:

obj-m += hello-world.o

obj-m tells kbuild that our hello-world.o object file is a loadable kernel module (LKM) that can be loaded and unloaded at any time without needing to reboot the kernel. This line will also tell the kbuild system to look for files in our directory named hello-world.c or hello-world.S to compile into the hello-world.o object file, before building the kernel object file hello-world.ko we'll use to load into our kernel.

Convenience Targets

For the pure convenience of it, we can add extra phony targets to our Kbuild Makefile to easily compile our module for the kernel currently running on our computer, simplifying the task of compiling our module down to just typing make into our terminals:

all:
    ${MAKE} -C /lib/modules/$(shell uname -r)/build M=$(PWD) modules

And make clean to clean up everything afterwards:

clean:
    ${MAKE} -C /lib/modules/$(shell uname -r)/build M=$(PWD) clean

Both of these phony targets use the -C option to move out of our current directory and into our kernel's source directory. There make can find and use the top most kbuild Makefile, which takes the M option to locate the folder we are current working in, and build the files defined using the obj-m goal definition we setup above.

Installing the Module

With our hello-world.c module freshly compiled, we can insert it into our kernel using the insmod command as root or another user with sudo privileges:

$ sudo insmod hello-world.ko

Congratulations!, you have created your first kernel module! A quick inspection of the kernel's diagnostic messages, using dmesg, should show our Hello World. message:

$ dmesg | tail -1
[241745.247591] Hello World.

Removing the Module

After the well deserved pat-on-the-back and when you are ready to continue, we can uninstall our module with the rmmod command as root or someone with sudo privileges:

$ sudo rmmod hello_world

The only indication we've uninstalled our module will be in dmesg from our printk() statement in the cleanup_module() function.

$ dmesg | tail -1
[241751.401232] oh, the rest is silence.

Licensing & Documentation

One of the ways we can taint our kernels is by loading proprietary modules or modules that use licenses not compatible with the General Public License (GPL) (bit 0 in the tainting list). Modules that don't use the MODULE_LICENSE() macro will also be considered proprietary and taint our kernel, if loaded (this is why we saw the warning above).

There are many documentation macros, defined in linux/module.h, some of the basics I added are:

MODULE_LICENSE("MIT");
MODULE_AUTHOR("Bryan Brattlof <email@example.com>");
MODULE_DESCRIPTION("A Hello World Driver");
MODULE_SUPPORTED_DEVICE("testdevice");

Once we add our module's license, author and other information to the end of our hello-world.c module, when we compile our module again using make, the WARNING should be gone:

$ make
make -C /lib/modules/4.15.0-108-generic/build M=/home/me/src/eudyptula ...
make[1]: Entering directory '/usr/src/linux-headers-4.15.0-108-generic'
  CC [M]  /home/me/src/eudyptula/tasks/01/hello-world.o
  Building modules, stage 2.
  MODPOST 1 modules
  CC      /home/me/src/eudyptula/tasks/01/hello-world.mod.o
  LD [M]  /home/me/src/eudyptula/tasks/01/hello-world.ko
make[1]: Leaving directory '/usr/src/linux-headers-4.15.0-108-generic'

There where many reasons to add this system to the kernel. For example, it gives developers a way to easily find who maintains a module, describe what the module does, and what license the code is protected with. It also provides an easy method to inform users when they are using non open source software.

module_init() & module_exit()

Introduced in version 2.4 of the kernel, and defined in linux/init.h of the source code, we can now rename our "start" and "end" functions to whatever we wish. In this example, I've chosen to rename the "start" function to hello_world_init()

-int init_module(void)
+static int __init hello_world_init(void)
 {
         printk(KERN_DEBUG "Hello World.\n");
         return 0; /* init_module loaded successfully */
 }

And renamed the "exit" function hello_world_exit()

-void cleanup_module(void)
+static void __exit hello_world_exit(void)
 {
         printk(KERN_DEBUG "oh, the rest is silence.\n");
 }

The kernel will then use the module_init() macro to find the function to execute when the module is installed and module_exit() to find the function to cleanup before being removed.

module_init(hello_world_init);
module_exit(hello_world_exit);

To avoid compiling issues, both the module_init() and module_exit() macros must be defined below our newly named "start" and "end" functions.

__init & __exit

I also introduced two macros to our "start" and "end" functions above called __init and __exit. These macros, defined in linux/init.h of the source code, help reduce memory used by the kernel depending on how the module is installed.

For built-in modules, where our module cannot be removed from the kernel without recompiling and restarting, the __init keyword will tell our C lexer to place our module's "start" function into a special section inside the compiled kernel. After the module is loaded and our "start" function has finished, the kernel will never have to run the code again until reboot. So this special section can be freed, saving memory.

The same is true for the __exit macro. For built-in modules, the module cannot be removed from the kernel without recompiling and restarting. So the kernel will never need to run our module's "exit" function to safely remove it from the kernel. This means our C lexer can safely omit our "exit" function from the compiled kernel.

pr_debug()

In the beginning there was printk(), and the kernel's diagnostic messages structure was formless. The lack of any format for printk() messages is one of a number of reasons why developers are replacing printk() statements with their newer equivalents. Depending on what section of the kernel we are in, there are newer functions that have some benefits for us.

For example, the pr_debug() function, which has the benefit of being less syntactically verbose than printk(KERN_DEBUG ...) also allows us to take advantage of the dynamic debugging interface, which gives developers a uniform control interface for debugging kernel messages while avoiding cluttering the kernel.

 static int __init hello_world_init(void)
 {
-    printk(KERN_DEBUG "Hello World.\n");
+    pr_debug("Hello World.\n");
     return 0; /* means init_module loaded successfully */
 }

 static void __exit hello_world_exit(void)
 {
-    printk(KERN_DEBUG "oh, the rest is silence.\n");
+    pr_debug("oh, the rest is silence.\n");
 }