1. Preface

Copyright and license information, as well as credits, are at the end of this document.

This HOWTO is maintained by Bryan Henderson, bryanh@giraffe-data.com. It was released May 31, 2001. You can get the current version of this HOWTO from the Linux Documentation Project.

2. Introduction to Linux Loadable Kernel Modules

If you want to add code to a Linux kernel, the most basic way to do that is to add some source files to the kernel source tree and recompile the kernel. In fact, the kernel configuration process consists mainly of choosing which files to include in the kernel to be compiled.

But you can also add code to the Linux kernel while it is running. A chunk of code that you add in this way is called a loadable kernel module. These modules can do lots of things, but they typically are one of three things: 1) device drivers; 2) filesystem drivers; 3) system calls. The kernel isolates certain functions, including these, especially well so they don't have to be intricately wired into the rest of the kernel.

3. Making Loadable Kernel Modules

An LKM lives in a single ELF object file (normally named like "serial.o"). You typically keep all your LKM object files in a particular directory (near your base kernel image makes sense). When you use the insmod program to insert an LKM into the kernel, you give the name of that object file.

For the LKMs that are part of Linux, you build them as part of the same kernel build process that generates the base kernel image. See the README file in the Linux source tree. In short, after you make the base kernel image with a command such as make zImage, you will make all the LKMs with the command

make modules

This results in a bunch of LKM object files (*.o) throughout the Linux source tree. (In older versions of Linux, there would be symbolic links in the modules directory of the Linux source tree pointing to all those LKM object files). These LKMs are ready to load, but you probably want to install them in some appropriate directory. The conventional place is described in Section 5.5. The command make modules_install will copy them all over to the conventional locations.

Part of configuring the Linux kernel (at build time) is choosing which parts of the kernel to bind into the base kernel and which parts to generate as separate LKMs. In the basic question-and-answer configuration (make config), you are asked, for each optional part of the kernel, whether you want it bound into the kernel (a "Y" response), created as an LKM (an "M" response), or just skipped completely (an "N" response). Other configuration methods are similar.

As explained in Section 2.3, you should have only the bare minimum bound into the base kernel. And only skip completely the parts that you're sure you'll never want. There is very little to lose by building an LKM that you won't use. Some compile time, some disk space, some chance of a problem in the code killing the kernel build. That's it.

As part of the configuration dialog you also must choose whether to use symbol versioning or not. This choice affects building both the base kernel and the LKMs and it is crucial you get it right. See Section 6.

LKMs that are not part of Linux (i.e. not distributed with the Linux kernel) have their own build procedures which I will not cover. The goal of any such procedure, though, is always to end up with an ELF object file.

You don't necessarily have to rebuild all your LKMs and your base kernel image at the same time (e.g. you could build just the base kernel and use LKMs you built earlier with it) but it is always a good idea. See Section 6.

4. LKM Utilities

The programs you need to load and unload and otherwise work with LKMs are in the package modutils. You can find this package in this directory.

This package contains the following programs to help you use LKMs:

Changes to the kernel often require changes to modutils, so be sure you're using a current version of modutils whenever you upgrade your kernel. modutils is always backward compatible (it works with older kernels), so there's no such thing as having too new a modutils.

Warning: modprobe invokes insmod and has its location hardcoded as /sbin/insmod. There may be other instances in modutils of the PATH not being used to find programs. So either modify the source code of modutils before you build it, or make sure you install the programs in their conventional directories.

5. How To Insert And Remove LKMs

The basic programs for inserting and removing LKMs are insmod and rmmod. See their man pages for details.

Inserting an LKM is conceptually easy: Just type, as superuser, a command like

insmod serial.o

(serial.o contains the device driver for serial ports (UARTs)).

However, I would be misleading you if I said the command just works. It is very common, and rather maddening, for the command to fail either with a message about a module/kernel version mismatch or a pile of unresolved symbols.

If it does work, though, the way to prove to yourself that you know what you're doing is to look at /proc/modules as described in Section 5.4.

Now lets look at a more difficult insertion. If you try

insmod msdos.o

you will probably get a raft of error messages like:

msdos.o: unresolved symbol fat_date_unix2dos msdos.o: unresolved symbol fat_add_cluster1 msdos.o: unresolved symbol fat_put_super ...

This is because msdos.o contains external symbol references to the symbols mentioned and there are no such symbols exported by the kernel. To prove this, do a

cat /proc/ksyms

to list every symbol that is exported by the kernel (i.e. available for binding to LKMs). You will see that 'fat_date_unix2dos' is nowhere in the list.

How do you get it into the list? By loading another LKM, one which defines those symbols and exports them. In this case, it is the LKM in the file fat.o. So do

insmod fat.o

and then see that "fat_date_unix2dos" is in /proc/ksyms. Now redo the

insmod msdos.o

and it works. Look at /proc/modules and see that both LKMs are loaded and one depends on the other:

msdos 5632 0 (unused) fat 30400 0 [msdos]

How did I know fat.o was the module I was missing? Just a little ingenuity. A more robust way to address this problem is to use depmod and modprobe instead of insmod, as discussed below.

When your symbols look like "fat_date_unix2dos_R83fb36a1", the problem may be more complex than just getting prerequisite LKMs loaded. See Section 6.

When the error message is "kernel/module version mismatch," see Section 6.

Often, you need to pass parameters to the LKM when you insert it. For example, a device driver wants to know the address and IRQ of the device it is supposed to drive. Or the network driver wants to know how much diagnostic tracing you want it to do. Here is an example of that:

insmod ne.o io=0x300 irq=11

Here, I am loading the device driver for my NE2000-like Ethernet adapter and telling it to drive the Ethernet adapter at IO address 0x300, which generates interrupts on IRQ 11.

There are no standard parameters for LKMs and very few conventions. Each LKM author decides what parameters insmod will take for his LKM. Hence, you will find them documented in the documentation of the LKM. This HOWTO also compiles a lot of LKM parameter information in Section 13. For general information about LKM parameters, see Section 8.

To remove an LKM from the kernel, the command is like

rmmod ne

There is a command lsmod to list the currently loaded LKMs, but all it does is dump the contents of /proc/modules, with column headings, so you may just want to go to the horse's mouth and forget about lsmod.

serial                   24484   0

6. Unresolved Symbols

  msdos.o: unresolved symbol fat_date_unix2dos
  msdos.o: unresolved symbol fat_add_cluster1
  msdos.o: unresolved symbol fat_put_super
  ...

  #define register_chrdev register_chrdev_Rc8dc8350

7. How To Boot Without A Disk Device Driver

For most systems, the ATA disk device driver must be bound into the base kernel because the root filesystem is on an ATA disk [2] and the kernel cannot mount the root filesystem, much less read any LKMs from it, without the ATA disk driver. But if you really want the device driver for your root filesystem to be an LKM, here's how to do it with Initrd:

"Initrd" is the name of the "initial ramdisk" feature of Linux. With this, you have your loader (probably LILO) load a filesystem into memory (as a ramdisk) before starting the kernel. When it starts the kernel, it tells it to mount the ramdisk as the root filesystem. You put the disk device driver for your real root filesystem and all the software you need to load it in that ramdisk filesystem. Your startup programs (which live in the ramdisk) eventually mount the real (disk) filesystem as the root filesystem. Note that a ramdisk doesn't require any device driver.

This does not free you, however, from having to bind into the base kernel 1) the filesystem driver for the filesystem in your ramdisk, and 2) the executable interpreter for the programs in the ramdisk.

8. About Module Parameters

It is useful to compare parameters that get passed to LKMs and parameters that get passed to modules that are bound into the base kernel, especially since modules often can be run either way.

We've seen above that you pass parameters to an LKM by specifying something like io=0x300 on the insmod command. For a module that is bound into the base kernel, you pass parameters to it via the kernel boot parameters. One common way to specify kernel boot parameters is at a lilo boot prompt. Another is with an append statement in the lilo configuration file.

The kernel initializes an LKM at the time you load it. It initializes a bound-in module at boot time.

Since there is only one string of kernel boot parameters, you need some way within that string to identify which parameters go to which modules. The rule for this is that if there is a module named xyz, then a kernel boot parameter named xyz is for that module. The value of a kernel boot parameter is an arbitrary string that makes sense only to the module.

This is why you sometimes see an LKM whose only parameter is its own name. E.g. you load the Mitsumi CDROM driver with a command like

insmod mcd mcd=0x340

It seems ridiculous to have the parameter named mcd instead of, say, io, but this is done for consistency with the case where you bind mcd into the base kernel, in which case you would select the I/O port address with the characters mcd=0x340 in the kernel boot parameters.

9. Persistent Data

Some LKMs are set up to retain information from one load to the next. This is called persistent data. When you remove one of these LKMs with rmmod, rmmod extracts certain values from the LKM's working storage and stores them in a file. When you next insert the LKM with insmod, insmod reads the persistent data from the file and inserts it into the LKM.

See the --persist option on insmod and rmmod.

Persistent data was introduced in November 2000.

10. Technical Details

11. Writing Your Own Loadable Kernel Module

The Linux Kernel Module Programming Guide by Ori Pomerantz is a complete explanation of writing your own LKM. This book is also available in print.

It is, however, a little out of date and contains an error or two. Here are a few things about writing an LKM that aren't in there.

12. Related Documentation

For modules that are part of Linux (i.e. distributed with the base kernel), you can sometimes find documentation in the Documentation subdirectory of the Linux source code.

Many LKMs can be alternatively bound into the base kernel. If you do that, you will pass parameters to them via the kernel "command line," which in its most basic form means via a prompt at boot time. The BootPrompt HOWTO by Paul Gortmaker <Paul.Gortmaker@anu.edu.au> will help you with that. It is available from the Linux Documentation Project.

Don't forget that the source code of Linux and any LKM is always the documentation of last resort, and the most trustworthy.

13. Individual Modules

In this chapter, I document individual LKMs. Where possible, I do this by reference to more authoritative documentation for the particular LKM (probably maintained by the same person who maintains the LKM code).

14. Maintenance Of This Document

This HOWTO is enthusiastically maintained by Bryan Henderson <bryanh@giraffe-data.com>. If you find something incorrect or incomplete or can't understand something, Bryan wants to know so maybe the next reader can be saved the trouble you had.

The source for this document is DocBook SGML, and is available from the Linux Documentation Project.

15. History

I have derived this (in 2001) from the HOWTO of the same name by Laurie Tischler, dated 1997. While I have kept all of the information from that original document (where it is still useful), I have rewritten the presentation entirely and have added a lot of other information. The original HOWTO's primary purpose was to document LKM parameters.

The original HOWTO was first released (Release 1.0) June 20, 1996, with a second release (1.1) October 20, 1996.

The first release of Bryan's rewrite was in June 2001.

16. Copyright

Here is Lauri Tischler's copyright notice from the original document from which this is derived:

This document is Copyright 1996© by Lauri Tischler. Permisson is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided that this copyright notice is included exactly as in the original, and that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this document into another language, under the above conditions for modified versions.

Bryan Henderson, the current maintainer and contributing author of this document, licenses it under the same terms as above. His work is Copyright 2001©.