11. Writing Your Own Loadable Kernel Module

11.1. Simpler hello.c

Lkmpg gives an example of the world's simplest LKM, hello-1.c. But it is not as simple as it could be and depends on your having kernel messaging set up a certain way on your system to see it work. Finally, the program requires you to include -D options on your compile command to work, because it does not define some macros in the source code, where the definitions belong.

Here is an improved world's simplest LKM, hello.c.

/* hello.c 
 * 
 * "Hello, world" - the loadable kernel module version. 
 *
 * Compile this with 
 *
 *          gcc -c hello.c -Wall
 */

/* Declare what kind of code we want from the header files */
#define __KERNEL__         /* We're part of the kernel */
#define MODULE             /* Not a permanent part, though. */

/* Standard headers for LKMs */
#include <linux/modversions.h> 
#include <linux/module.h>  

#include <linux/tty.h>      /* console_print() interface */

/* Initialize the LKM */
int init_module()
{
  console_print("Hello, world - this is the kernel speaking\n");
  /* More normal is printk(), but there's less that can go wrong with 
     console_print(), so let's start simple.
  */

  /* If we return a non zero value, it means that 
   * init_module failed and the LKM can't be loaded 
   */
  return 0;
}


/* Cleanup - undo whatever init_module did */
void cleanup_module()
{
  console_print("Short is the life of an LKM\n");
}

Compile this with the simple command

$ gcc -c -Wall -nostdinc -I /usr/src/linux/include hello.c

The -I above assumes that you have the source code from which your base kernel (the base kernel of the kernel into which you hope to load hello.c) was built in the conventional spot, /usr/src/linux. If you're masochistic enough to be using symbol versioning in your base kernel, then you better have run 'make dep' on that kernel source too, because that's what builds the .ver files that change the names of all your symbols.

But note that it's reasonably common not to have the kernel headers installed there, and often, the wrong headers are installed there. When you use a kernel that you loaded from a distribution CD, you often have to separately load the headers for it. To be safe, if you're playing with compiling LKMs, you really should compile your own kernel, so you know exactly what you're working with and can be absolutely sure you're working with matching header files.

The -nostdinc option isn't strictly necessary, but is the right thing to do. It will keep you out of trouble and also remind you that the services of the standard C library, which you may have melded in your mind with C itself, are not available to kernel code. -nostdinc says not to include "standard" directories in the include file search path. This means, most notably, /usr/include.

The -c option says you just want to create an object (.o) file, as opposed to gcc's default which is to create the object file, then link it with a few other standard object files to create something suitable for exec'ing in a user process. As you will not be exec'ing this module but rather adding it to the kernel, that link phase would be entirely inappropriate.

-Wall (which makes the compiler warn you about lots of kinds of questionable code) is obviously not necessary, but this program should not generate any warnings. If it does, you need to fix something.

11.2. Using the Kernel Build System

Lkmpg contains fine instructions for building (compiling) an LKM (except that the __KERNEL__ macro and usually the MODULE macro should be defined in the source code instead of with -D compiler options as Lkmpg suggests). But it deserves mention that some Linux kernel programmers believe that the only right way to build an LKM is to add it to a copy of the complete Linux source tree and build it with the existing Linux make files just like the LKMs that are part of Linux.

There are advantages to this. The biggest one is that when Linux programmers change the way LKMs interface with the rest of the kernel in a way that affects how you build an LKM, you're covered.

On the other hand, you will probably find from a code management point of view that you really have to keep your own code and Linux separate, and from a coding point of view, you really need to understand all the intricacies of how your code gets compiled, especially when it changes.

11.3. Rubini et al: Linux Device Drivers

The most popular book on writing device drivers is O'Reilly's Linux Device Drivers by Alessandro Rubini, Jonathan Corbet, and Greg Kroah-Hartman.

Even if you're writing an LKM that isn't a device driver, you can learn a lot from this book that will help you.

The first edition of this book covers Linux 2.0, with notes about differences in 2.2. The second edition (June 2001) covers Linux 2.4. The third edition (April 2005) covers Linux 2.6. Of course, if you know anything about Linux, you know that a book like this doesn't perfectly cover any release, because Linux changes frequently. Linux 2.6 as was current a month after the Third Edition was released had significant differences from the Linux 2.6 about which the book was written.

The second edition of this book is available under the FDL. You can read it at http://www.xml.com/ldd/chapter/book/. The third edition is available under the terms of the Creative Commons Attribution-ShareAlike license, and you'll find it at http://lwn.net/Kernel/LDD3/.

This book is also available in print in any decent technical book store.

11.4. Module Use Counts

It is essential that the kernel not try to reference the code of a module after it has been unloaded; i.e. you must not unload a module while it is in use. An example of in use is a device driver for which a device special file is open. Because there is an open file descriptor for it, a user might do a read of the device and to execute that read, the kernel would want to call a function that is in the device driver. You can see that there would be a problem if you unloaded that device driver module before the read -- the kernel would reuse the memory that used to contain the read subroutine and there's no telling what instructions the kernel would branch to when it thinks it's calling the read subroutine.

In the original design, the LKM increments and decrements its use count to tell the module manager whether it is OK to unload it. For example, if it's a filesystem driver, it would increment the use count when someone mounts a filesystem of the type it drives, and decrement it at unmount time.

Later a more flexible alternative was added. Your LKM can register a function that the module manager will call whenever it wants to know if it is OK to unload the module. If the function returns a true value, that means the LKM is busy and cannot be unloaded. If it returns a false value, the LKM is idle and can be unloaded. The module manager holds the big kernel lock from before calling the module-busy function until after its cleanup subroutine returns or sleeps, and unless you've done something odd, that should mean that your LKM cannot become busy between the time that you report "not busy" and the time you clean up.

So how do you register the module-busy function? By putting its address in the unfortunately named can_unload field in the module descriptor ("struct module"). The name is truly unfortunate because the boolean value it returns is the exact opposite of what "can unload" means: true if the module manager cannot unload the LKM.

The module manager ensures that it does not attempt to unload the module before its initialization subroutine has returned or sleeps, so you are safe in setting the can_unload field anywhere in the initialization subroutine except after a sleep.

can_unload is little known and rarely used. Starting with Linux 2.6, it no longer exists.

Whether you use traditional use counts of can_unload, there are cases where you cannot be sure that your module doesn't get unloaded while it is still in use. If your LKM creates a kernel thread that executes LKM code, it is just about impossible to be absolutely sure that thread is gone before the LKM gets unloaded. There are various other kernel services that you can give addresses within your LKM that won't properly let you know when they have forgotten them.

The problem used to be worse than it is now. For example, it used to be that if your LKM created a proc filesystem file, you couldn't stop the LKM from getting unloaded while some process was executing your read and write routines for the file. This and other instances of the problem have been fixed by having code outside the LKM understand that the address it's using might be in an LKM, and therefore increment and decrement the use count as necessary. Where this function is implemented, you often see a structure member named "owner" which is a handle for the LKM (i.e. a struct module address).

These problems may be fixed in future version of Linux. Until then, you can just cross your fingers. Some people believe these types of problems are so hard to fix that the proper design for Linux is just to make it impossible ever to unload an LKM. Starting with Linux 2.6, the CONFIG_MODULE_UNLOAD kernel build configuration option determines whether module unloading is allowed or not.