11. Writing Your Own Loadable Kernel Module
The Linux Kernel
Module Programming Guide by Ori Pomerantz (Lkmpg) is a
complete explanation of writing your own LKM. This book is also
available in print.
We will not duplicate information in that document, but here are
Here are a few things about writing an LKM that aren't in there.
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, 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/tty.h> /* console_print() interface */
/* Initialize the LKM */
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
/* Cleanup - undo whatever init_module did */
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
11.3. Rubini & Corbet: Linux Device Drivers
The most popular book on writing device drivers is O'Reilly's
Linux Device Drivers by Alessandro
Rubini and Jonathan Corbet.
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.
This book is available under the FDL. You can read it at
11.4. Improving On Use Counts
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.
Now, there is a more flexible alternative. 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.