LLKMHT-IndivualModules3

15.3. SCSI Drivers

Detailed information about SCSI drivers is in SCSI-2.4-HOWTO .

Linux's SCSI function is implemented in three layers, and there are LKMs for all of them.

In the middle is the mid-level driver or SCSI core. This consists of the scsi_mod LKM. It does all those things that are common among SCSI devices regardless of what SCSI adapter you use and what class of device (disk, scanner, CD-ROM drive, etc.) it is.

LLKMHT-IndivualModules2

15.2. Block Device Drivers

15.2.1. floppy: floppy disk driver

This is the device driver for floppy disks. You need this in order to access a floppy disk in any way.

This LKM is documented in the file README.fd in the linux/drivers/block directory of the Linux source tree. For detailed up to date information refer directly to this file.

LLKMHT-IndivualModules

15. 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).

LLKMHT-Docs

Linux Loadable Kernel Module HOWTO

14. 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 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.

LLKMHT-Copyright

Linux Loadable Kernel Module HOWTO


13. Copyright Considerations With LKMs

A perennial question about LKMs is whether the terms of GPL apply to one, considering that the Linux kernel is distributed under GPL. For example, is it OK to ship an LKM in binary only form? This section covers the copyright issues surrounding LKMs, which are as interesting as they are complex. Fair warning: we don't reach a conclusion. The law is unsettled and there are plenty of good but conflicting arguments.

LLKMHT-Diff

Linux Loadable Kernel Module HOWTO


12. Differences Between Versions Of Linux

One thing that deserves mention in this section is the variety of Linux versions that exist in the world and what we call them. Unlike a proprietary software product where one company carefully controls the name and creates a small number of well defined releases, variations of Linux are developed by lots of different independent people and all of them are called Linux.

LLKMHT-WriteUOwn

Linux Loadable Kernel Module HOWTO 
11. Writing Your Own Loadable Kernel Module

The Linux Kernel Module Programming Guide by Peter J Salzman, Michael Burian, and Ori Pomerantz is a complete explanation of writing your own LKM. This book is also available in print. There are two versions of it: one for Linux 2.4, and another for 2.6.

At one time, the Linux 2.4 version of this document was rather out of date and contained an error or two.

LLKMHT-TechDetails

Linux Loadable Kernel Module HOWTO
10. Technical Details
----
10.1. How They Work
10.2. The .modinfo Section
10.3. The __ksymtab And .kstrtab Sections
10.4. Ksymoops Symbols
10.5. Other Symbols
10.6. Debugging Symbols
10.7. Memory Allocation For Loading
10.8. Linux internals
---

LLKMHT-PersistentDat

Linux Loadable Kernel Module HOWTO


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.

LLKMHT-AboutModuleParams

Linux Loadable Kernel Module HOWTO
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.

LLKMHT-HowtoBoot

Linux Loadable Kernel Module HOWTO

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 Prev 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 or Grub) 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.

Notes:

You probably know this type of disk as "IDE". Strictly speaking, IDE is an incorrect appelation. IDE refers to the "Integrated Drive Electronics" technology which all modern disk drives, notably including all SCSI disk drives, use. The first IDE drives in common usage were ATA, and the names kind of got confused. ATA, like SCSI, is a precise specification of electrical signals, commands, etc.

LLKMHT-UnresolveSym

Linux Loadable Kernel Module HOWTO
6. Unresolved Symbols

The most common and most frustrating failure in loading an LKM is a bunch of error messages about unresolved symbols, like this:

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

LLKMHT-Insert-Remove

Linux Loadable Kernel Module HOWTO


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

LLKMHT-Utilities

Linux Loadable Kernel Module HOWTO


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:

insmod

LLKMHT-MakingLKM

The Linux Loadable Kernel Module How-To

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

LLKMHT-Intro

Linux Loadable Kernel Module HOWTO 

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.

LLKMHT-Preface

Linux Loadable Kernel Module HOWTO 

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. You can get the current version of this HOWTO from the Linux Documentation Project .