Linux Loadable Kernel Module HOWTO
Prev		Next

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.

5.1. Could Not Find Kernel Version...

A common error is to try to insert an object file which is not an LKM. For example, you configure your kernel to have the USB core module bound into the base kernel instead of generated as an LKM. In that case, you end up with a file usbcore.o, which looks pretty much the same as the usbcore.o you would get if you built it as an LKM. But you can't insmod that file.

So do you get an error message telling you that you should have configured the kernel to make USB core function an LKM? Of course not. This is Unix, and explanatory error messages are seen as a sign of weakness. The error message is
$ insmod usbcore.o usbcore.o: couldn't find the kernel version this module was compiled for

What insmod is telling you is that it looked in usbcore.o for a piece of information any legitimate LKM would have -- the kernel version with which the LKM was intended to be used -- and it didn't find it. We know now that the reason it didn't find it is that the file isn't an LKM. See Section 10.2.

5.2. Intelligent Loading Of LKMs - Modprobe

Once you have module loading and unloading figured out using insmod and rmmod, you can let the system do more of the work for you by using the higher level program modprobe. See the modprobe man page for details.

The main thing that modprobe does is automatically load the prerequisites of an LKM you request. It does this with the help of a file that you create with depmod and keep on your system.

Example:
modprobe msdos

This performs an insmod of msdos.o, but before that does an insmod of fat.o, since you have to have fat.o loaded before you can load msdos.o.

The other major thing modprobe does for you is to find the object module containing the LKM given just the name of the LKM. For example, modprobe msdos might load /lib/2.4.2-2/fs/msdos.o. Check out the man pages for modprobe and the configuration file modules.conf (usually /etc/modules.conf) for details on the search rules modprobe uses.

depmod scans your LKM object files (typically all the .o files in the appropriate /lib/modules subdirectory) and figures out which LKMs prerequire (refer to symbols in) other LKMs. It generates a dependency file (typically named modules.dep), which you normally keep in /lib/modules for use by modprobe.

You can use modprobe to remove stacks of LKMs as well.

Via the LKM configuration file (typically /etc/modules.conf), you can fine tune the dependencies and do other fancy things to control LKM selections. And you can specify programs to run when you insert and remove LKMs, for example to initialize a device driver.

If you are maintaining one system and memory is not in short supply, it is probably easier to avoid modprobe and the various files and directories it needs, and just do raw insmods in a startup script.

5.3. Automatic LKM Loading and Unloading

5.3.1. Automatic Loading

You can cause an LKM to be loaded automatically when the kernel first needs it. You do this with either a kerneld daemon or with the more recent invention, the kernel module loader, which is part of Linux.

As an example, let's say you run a program that executes an open system call for a file in an MS-DOS filesystem. But you don't have a filesystem driver for the MS-DOS filesystem either bound into your base kernel or loaded as an LKM. So the kernel does not know how to access the file you're opening on the disk.

The kernel recognizes that it has no filesystem driver for MS-DOS, but that one of the two automatic module loading facilities are available and uses it to cause the LKM to be loaded. The kernel then proceeds with the open.

Both kerneld and the kernel module loader use modprobe, ergo insmod, to insert LKMs.

5.3.1.1. Kerneld

kerneld is explained at length in the Kerneld mini-HOWTO, available from the Linux Documentation Project.

kerneld is a user process, which runs the kerneld program from the modutils package. kerneld sets up an IPC message channel with the kernel. When the kernel needs an LKM, it sends a message on that channel to kerneld and kerneld runs modprobe to load the LKM, then sends a message back to the kernel to say that it is done.

5.3.1.2. Kernel Module Loader

There is some documentation of the kernel module loader in the file Documentation/kmod.txt in the Linux source tree. As of this writing, this section is more complete and accurate than that file. You can also look at its source code in kernel/kmod.c.

The kernel module loader is an optional part of the Linux kernel. You get it if you select the CONFIG_KMOD feature when you configure the kernel at build time.

When a kernel that has the kernel module loader needs an LKM, it creates a user process (owned by the superuser, though) that executes modprobe to load the LKM, then exits. By default, it finds modprobe as /sbin/modprobe, but you can set up any program you like as modprobe by writing its file name to /proc/sys/kernel/modprobe. For example:
$ echo "sbin/mymodprobe" >/proc/sys/kernel/modprobe

The kernel module loader passes the following arguments to modprobe: Argument Zero is the full file name of modprobe. The regular arguments are -s, -k, and the name of the LKM that the kernel wants. -s is the user-hostile form of --syslog; -k is the cryptic way to say --autoclean. I.e. messages from modprobe will go to syslog and the loaded LKM will have the "autoclean" flag set.

The kernel module loader runs modprobe with the following environment variables (only): HOME=/; TERM=linux; PATH=/sbin:/usr/sbin:/bin:/usr/bin.

The kernel module loader was new in Linux 2.2 and was designed to take the place of kerneld. It does not, however, have all the features of kerneld.

In Linux 2.2, the kernel module loader creates the above mentioned process directly. In Linux 2.4, the kernel module loader submits the module loading work to Keventd and it runs as a child process of Keventd.

The kernel module loader is a pretty strange beast. It violates layering as Unix programmers generally understand it and consequently is inflexible, hard to understand, and not robust. Many system designers would bristle just at the fact that it has the PATH hardcoded. You may prefer to use kerneld instead, or not bother with automatic loading of LKMs at all.

5.3.2. Automatic Unloading - Autoclean

5.3.2.1. The Autoclean Flag

Each loaded LKM has an autoclean flag which can be set or unset. You control this flag with parameters to the init_module system call. Assuming you do that via insmod, you use the --autoclean option.

You can see the state of the autoclean flag in /proc/modules. Any LKM that has the flag set has the legend autoclean next to it.

5.3.2.2. Removing The Autoclean LKMs

The purpose of the autoclean flag is to be let you automatically remove LKMs that haven't been used in a while (typically 1 minute). So by using automatic module loading and unloading, you can keep only parts of the kernel that are presently needed loaded, and save memory.

This is less important than it once was, with memory being much cheaper. If you don't need to save memory, you shouldn't bother with the complexity of module loader processes. Just load everything you might need via an initialization script and keep it loaded.

There is a form of the delete_module system call that says, "remove all LKMs that have the autoclean flag set and haven't been used in a while." Kerneld typically calls this once per minute. You can call it explicitly with an rmmod --all command.

As the kernel module loader does not do any removing of LKMs, if you use that you might want to have a cron job that does a rmmod --all periodically.

5.4. /proc/modules

To see the presently loaded LKMs, do
cat /proc/modules

You see a line like

serial                   24484   0

The left column is the name of the LKM, which is normally the name of the object file from which you loaded it, minus the ".o" suffix. You can, however, choose any name you like with an option on insmod.

The "24484" is the size in bytes of the LKM in memory.

The "0" is the use count. It tells how many things presently depend on the LKM being loaded. Typical "things" are open devices or mounted fileystems. It is important because you cannot remove an LKM unless the use count is zero. The LKM itself maintains this count, but the module manager uses it to decide whether to permit an unload.

There is an exception to the above description of the use count. You may see -1 in the use count column. What that means is that this LKM does not use use counts to determine when it is OK to unload. Instead, the LKM has registered a subroutine that the module manager can call that will return an indication of whether or not it is OK to unload the LKM. In this case, the LKM ought to provide you with some custom interface, and some documentation, to determine when the LKM is free to be unloaded.

5.5. Where Are My LKM Files On My System?

The LKM world is flexible enough that the files you need to load could live just about anywhere on your system, but there is a convention that most systems follow: The LKM .o files are in the directory /lib/modules, divided into subdirectories. There is one subdirectory for each version of the kernel, since LKMs are specific to a kernel (see Section 6). Each subdirectory contains a complete set of LKMs.

The subdirectory name is the value you get from the uname --release command, for example 2.2.19. Section 6.3 tells how you control that value.

When you build Linux, a standard make modules and make modules_install should install all the LKMs that are part of Linux in the proper release subdirectory.

If you build a lot of kernels, another organization may be more helpful: keep the LKMs together with the base kernel and other kernel-related files in a subdirectory of /boot. The only drawback of this is that you cannot have /boot reside on a tiny disk partition. In some systems, /boot is on a special tiny "boot partition" and contains only enough files to get the system up to the point that it can mount other filesystems.

Prev	Home	Next
LKM Utilities		Unresolved Symbols