Linux Loadable Kernel Module HOWTO

You don't have the latest version of Adobe Flash Player.

Please update your flash player.

Please login or register to make a comment!

Linux Loadable Kernel Module HOWTO Bryan Henderson 2006 209 224 Revision History Revision v1.09 2006 209 224 Revised by: bjh Fix typos. Revision v1.08 2006 203 203 Revised by: bjh Add copyright information. Revision v1.07 2005 207 220 Revised by: bjh Add some 2.6 info and disclaimers.

Update references to Linux Device Drivers book, Linux Kernel Module Programming Guide. Revision v1.06 2005 201 212 Revised by: bjh Cover Linux 2.6 briefly. Update hello.c and reference to Lkmpg.

Add information about perils of unloading. Mention dmesg as way to see kernel messages. Revision v1.05 2004 201 205 Revised by: bjh Add information on module.h and 2DMODULE.

Fix tldb.org to tldp.org. Add information on kallsyms. Revision v1.04 2003 210 210 Revised by: bjh Fix typo: AHA154x should be AHA152x Add information on what module names the kernel module loader calls for.

Add information on what an LKM does when you first load it. Add information on loop module. Change linuxdoc.org to tldp.org.

Revision v1.03 2003 207 203 Revised by: bjh Update on kernels that don't load into vmalloc space. Add explanation of "deleted" state of an LKM. Explain GPLONLY.

Revision v1.02 2002 205 221 Revised by: bjh Correct explanation of symbol versioning. Correct author of Linux Device Drivers. ... more. less.

Add info about memory allocation penalty of LKM vs bound 2in. Add LKM 2to 2LKM symbol matching requirement. Add open source licensing issue in LKM symbol resolution. Add SMP symbol versioning info. Revision v1.01 2001 208 218 Revised by: bjh Add material on various features created in the last few years: kernel module loader, ksymoops symbols, kernel 2version 2dependent LKM file location. Revision v1.00 2001 206 214 Revised by: bjh Initial release. This is the HOWTO for Linux loadable kernel modules (LKMs). It explains what they are and how to use and create them. It also includes documentation of parameters and other details of use of some particular modules. Table of Contents 1. Preface..................................................................................................................... .........................................1 2. Introduction to Linux Loadable Kernel Modules............................................................................... .........2 2.1. Terminology............................................................................................................... .......................2 2.2. History of Loadable Kernel Modules........................................................................................ .......2 2.3. The Case For Loadable Kernel Modules...................................................................................... ....3 2.4. What LKMs Can't Do........................................................................................................ ...............3 2.5. What LKMs Are Used For.................................................................................................... ............3 3. Making Loadable Kernel Modules.............................................................................................. ..................5 4. LKM Utilities............................................................................................................... ....................................6 5. How To Insert And Remove LKMs............................................................................................... ...............7 5.1. Could Not Find Kernel Version............................................................................................. ...........8 5.2. What Happens When An LKM Loads............................................................................................ ..9 5.3. Intelligent Loading Of LKMs 2 Modprobe.................................................................................... ..9 5.4. Automatic LKM Loading and Unloading....................................................................................... 10 5.4.1. Automatic Loading....................................................................................................... .........10 5.4.2. Automatic Unloading 2 Autoclean.......................................................................................12 5.5. /proc/modules............................................................................................................. .....................12 5.6. Where Are My LKM Files On My System?...................................................................................14 6. Unresolved Symbols.......................................................................................................... ............................15 6.1. Some LKMs Prerequire Other LKMs........................................................................................... ..15 6.2. An LKM Must Match The Base Kernel......................................................................................... 15 6.3. If You Run Multiple Kernels............................................................................................... ...........16 6.4. SMP symbols............................................................................................................... ...................17 6.5. You Are Not Licensed To Access The Symbol..............................................................................17 6.6. An LKM Must Match Prerequisite LKMs......................................................................................1 8 7. How To Boot Without A Disk Device Driver.................................................................................... .........19 8. About Module Parameters..................................................................................................... ......................20 9. Persistent Data............................................................................................................. .................................21 10. Technical Details.......................................................................................................... ...............................22 10.1. How They Work............................................................................................................ ...............22 10.2. The .modinfo Section..................................................................................................... ...............23 10.3. The __ksymtab And .kstrtab Sections...................................................................................... ....23 10.4. Ksymoops Symbols......................................................................................................... .............23 10.5. Other Symbols............................................................................................................ ..................24 10.6. Debugging Symbols........................................................................................................ ..............25 10.7. Memory Allocation For Loading............................................................................................ ......25 10.8. Linux internals.......................................................................................................... ....................26 Linux Loadable Kernel Module HOWTO i Table of Contents 11. Writing Your Own Loadable Kernel Module.................................................................................... ......27 11.1. Simpler hello.c.......................................................................................................... ....................27 11.2. Using the Kernel Build System............................................................................................ ........28 11.3. Rubini et al: Linux Device Drivers....................................................................................... ........29 11.4. Module Use Counts........................................................................................................ ..............29 12. Differences Between Versions Of Linux...................................................................................... .............31 12.1. Linux 2.4 2 Linux 2.6.................................................................................................... ...............31 12.1.1. Linking Done In Kernel................................................................................................. .....31 12.1.2. No Module Busy Function................................................................................................ ..32 12.1.3. CONFIG_MODULE_UNLOAD........................................................................................32 12.1.4. Reference Counting..................................................................................................... ........32 13. Copyright Considerations With LKMs......................................................................................... ...........33 14. Related Documentation...................................................................................................... ........................36 15. Individual Modules......................................................................................................... ............................37 15.1. Executable Interpreters.................................................................................................. ...............37 15.1.1. binfmt_aout: executable interpreter for a.out format..........................................................37 15.1.2. binfmt_elf: executable interpreter for ELF format..............................................................37 15.1.3. binfmt_java: executable interpreter for Java bytecode........................................................38 15.2. Block Device Drivers..................................................................................................... ...............38 15.2.1. floppy: floppy disk driver............................................................................................. .......38 15.2.2. loop: loop device driver............................................................................................... ........41 15.2.3. linear: linear (non 2RAID) disk array device driver............................................................42 15.2.4. raid0: RAID 20 device driver............................................................................................ ...42 15.2.5. rd: ramdisk device driver.............................................................................................. .......43 15.2.6. xd: XT disk device driver.............................................................................................. ......43 15.3. SCSI Drivers............................................................................................................. ....................43 15.3.1. scsi_mod: SCSI mid 2level driver.......................................................................................4 4 15.3.2. sd_mod: SCSI high 2level driver for disk devices...............................................................44 15.3.3. st: SCSI high 2level driver for tape devices.........................................................................45 15.3.4. sr_mod: SCSI high 2level driver for CD 2ROM drives.......................................................45 15.3.5. sg: SCSI high 2level driver for generic SCSI devices.........................................................45 15.3.6. wd7000: SCSI low 2level driver for 7000FASST...............................................................45 15.3.7. aha152x: SCSI low 2level driver for Adaptec AHA152X/2825..........................................45 15.3.8. aha1542: SCSI low 2level driver for Adaptec AHA1542....................................................46 15.3.9. aha1740: SCSI low 2level driver for Adaptec AHA1740 EISA..........................................46 15.3.10. aic7xxx: SCSI low 2level driver for Adaptec AHA274X/284X/294X..............................46 15.3.11. advansys: SCSI low 2level driver for AdvanSys/Connect.com.........................................46 15.3.12. in2000: SCSI low 2level driver for Always IN2000..........................................................47 15.3.13. BusLogic: SCSI low 2level driver for BusLogic...............................................................47 15.3.14. dtc: SCSI low 2level driver for DTC3180/3280................................................................47 15.3.15. eata: SCSI low 2level driver for EATA ISA/EISA............................................................47 15.3.16. eata_dma: SCSI low 2level driver for EATA 2DMA.........................................................48 15.3.17. eata_pio: SCSI low 2level driver for EATA 2PIO.............................................................48 15.3.18. fdomain: SCSI low 2level driver for Future Domain 16xx...............................................48 Linux Loadable Kernel Module HOWTO ii Table of Contents 15. Individual Modules 15.3.19. NCR5380: SCSI low 2level driver for NCR5380/53c400.................................................48 15.3.20. NCR53c406a: SCSI low 2level driver for NCR53c406a...................................................49 15.3.21. 53c7,8xx.o: SCSI low 2level driver for NCR53c7,8xx.....................................................49 15.3.22. ncr53c8xx: SCSI low 2level driver for PCI 2SCS NCR538xx family...............................49 15.3.23. ppa: low 2level SCSI driver for IOMEGA parallel port ZIP drive....................................49 15.3.24. pas16: SCSI low 2level driver for PAS16.........................................................................50 15.3.25. qlogicfas: SCSI low 2level driver for Qlogic FAS............................................................50 15.3.26. qlogicisp: SCSI low 2level driver for Qlogic ISP..............................................................50 15.3.27. seagate: SCSI low 2level driver for Seagate, Future Domain............................................50 15.3.28. t128: SCSI low 2level driver for Trantor T128/T128F/T228............................................51 15.3.29. u14 234f: SCSI low 2level driver for UltraStor 14F/34F...................................................51 15.3.30. ultrastor: low 2level SCSI driver for UltraStor..................................................................51 15.4. Network Device Drivers................................................................................................... ............51 15.4.1. bsd_comp: optional BSD compressor for PPP....................................................................51 15.4.2. slhc: SLHC compressor for PPP.........................................................................................5 1 15.4.3. dummy: Dummy network interface driver..........................................................................52 15.4.4. eql: serial line load balancer......................................................................................... .......52 15.4.5. dlci: frame relay DLCI driver.......................................................................................... ....52 15.4.6. sdla: Sangoma S502A FRAD driver...................................................................................53 15.4.7. plip: PLIP network interface driver.................................................................................... .53 15.4.8. ppp: PPP network protocol driver....................................................................................... 53 15.4.9. slip: SLIP network protocol driver..................................................................................... .54 15.4.10. baycom: BAYCOM AX.25 amateur radio driver.............................................................54 15.4.11. strip: STRIP (Metricom starmode radio IP) driver...........................................................55 15.4.12. wavelan: WaveLAN driver............................................................................................... 55 15.4.13. wic: WIC Radio IP bridge driver......................................................................................5 5 15.4.14. scc: Z8530 SCC kiss emulation driver..............................................................................56 15.4.15. 8390: General NS8390 Ethernet driver core.....................................................................56 15.4.16. ne: NE2000/NE1000 driver.............................................................................................. .56 15.4.17. ne2k 2pci: NE2000 PCI Driver..........................................................................................5 7 15.4.18. 3c501: 3COM 3c501 Ethernet driver................................................................................57 15.4.19. 3c503: 3COM 3c503 driver.............................................................................................. .58 15.4.20. 3c505: 3COM 3c505 driver.............................................................................................. .58 15.4.21. 3c507: 3COM 3c507 driver.............................................................................................. .59 15.4.22. 3c509: 3COM 3c509/3c579 driver....................................................................................59 15.4.23. 3c59x: 3COM 3c590 series "Vortex" driver.....................................................................59 15.4.24. wd: Western Digital/SMC WD80*3 driver.......................................................................60 15.4.25. smc 2ultra: SMC Ultra/EtherEZ driver..............................................................................61 15.4.26. smc9194: SMC 9194 driver.............................................................................................. 61 15.4.27. at1700: AT1700 driver................................................................................................. .....62 15.4.28. e2100: Cabletron E21xx driver......................................................................................... 62 15.4.29. depca: DEPCA, DE10x, DE200, DE201, DE202, DE422 driver.....................................62 15.4.30. ewrk3: EtherWORKS 3 (DE203, DE204, DE205) driver.................................................63 15.4.31. eexpress: EtherExpress 16 driver...................................................................................... 63 15.4.32. eepro: EtherExpressPro driver......................................................................................... ..63 15.4.33. fmv18k: Fujitsu FMV 2181/182/183/184 driver...............................................................64 15.4.34. hp 2plus: HP PCLAN+ (27247B and 27252A) driver.......................................................64 Linux Loadable Kernel Module HOWTO iii Table of Contents 15. Individual Modules 15.4.35. hp: HP PCLAN (27245, 27xxx) driver.............................................................................64 15.4.36. hp100: HP 10/100VG PCLAN (ISA, EISA, PCI) driver..................................................65 15.4.37. eth16i: ICL EtherTeam 16i/32 driver................................................................................65 15.4.38. ni52: NI5210 driver................................................................................................... ........65 15.4.39. ac3200: Ansel Communications EISA 3200 driver..........................................................65 15.4.40. apricot: Apricot Xen 2II on board ethernet driver.............................................................66 15.4.41. de4x5: DE425, DE434, DE435, DE450, DE500 driver....................................................66 15.4.42. tulip: DECchip Tulip (dc21x4x) PCI driver......................................................................66 15.4.43. dgrs: Digi Intl RightSwitch SE 2X driver..........................................................................66 15.4.44. de600: D 2Link DE600 pocket adapter driver...................................................................67 15.4.45. de620: D 2Link DE620 pocket adapter driver...................................................................67 15.4.46. ibmtr: Tropic chipset based token ring adapter driver......................................................68 15.4.47. arcnet: ARCnet driver................................................................................................. ......68 15.4.48. isdn: basic ISDN functions............................................................................................ ....69 15.4.49. icn: ICN 2B and 4B driver............................................................................................. ...69 15.4.50. pcbit: PCBIT 2D driver................................................................................................. .....69 15.4.51. teles: Teles/NICCY1016PC/Creatix driver.......................................................................70 15.5. CDROM Device Drivers..................................................................................................... ..........70 15.5.1. aztcd: Aztech/Orchid/Okano/Wearnes/TXC/CDROM driver.............................................71 15.5.2. gscd: Goldstar R420 CDROM driver..................................................................................71 15.5.3. sbpcd: Sound Blaster CDROM driver.................................................................................71 15.5.4. mcd: Mitsumi CDROM driver............................................................................................72 15.5.5. mcdx: Mitsumi XA/MultiSession driver.............................................................................72 15.5.6. optcd: Optics Storage DOLPHIN 8000AT CDROM driver...............................................72 15.5.7. cm206: Philips/LMS CM206 CDROM driver....................................................................72 15.5.8. sjcd: Sanyo CDR 2H94A CDROM driver...........................................................................73 15.5.9. isp16: ISP16/MAD16/Mozart soft configurable cdrom driver...........................................73 15.5.10. cdu31a: Sony CDU31A/CDU33A CDROM driver..........................................................73 15.5.11. sonycd535: Sony CDU535 CDROM driver......................................................................74 15.6. Filesystem Drivers....................................................................................................... .................74 15.6.1. minix: Minix filesystem driver......................................................................................... ...74 15.6.2. ext: "Extended" filesystem driver...................................................................................... ..74 15.6.3. ext2: "Second extended" filessystem driver........................................................................74 15.6.4. xiafs: xiafs filesystem driver......................................................................................... ......74 15.6.5. fat: DOS FAT filesystem functions.....................................................................................7 4 15.6.6. msdos: MSDOS filesystem driver.......................................................................................75 15.6.7. vfat: VFAT (Windows 295) filesystem driver.....................................................................75 15.6.8. umsdos: UMSDOS filesystem driver..................................................................................75 15.6.9. nfs: NFS filesystem driver............................................................................................. ......75 15.6.10. smbfs: SMB filesystem driver.......................................................................................... .75 15.6.11. ncpfs: NCP (Netware) filesystem driver...........................................................................76 15.6.12. isofs: ISO 9660 (CDROM) filesystem driver....................................................................76 15.6.13. hpfs: OS/2 HPFS filesystem driver...................................................................................76 15.6.14. sysv: System V and Coherent filesystem driver................................................................76 15.6.15. affs: Amiga FFS filesystem driver....................................................................................7 7 15.6.16. ufs: UFS filesystem driver............................................................................................ .....77 15.7. Miscellaneous Device Driver.............................................................................................. ..........77 Linux Loadable Kernel Module HOWTO iv Table of Contents 15. Individual Modules 15.7.1. misc: device driver for "miscellaneous" character devices.................................................77 15.8. Serial Device Drivers.................................................................................................... ................77 15.8.1. serial: serial communication port (UART) device driver....................................................77 15.8.2. cyclades: Cyclades async mux device driver......................................................................78 15.8.3. stallion: Stallion EasyIO or EC8/32 device driver..............................................................78 15.8.4. istallion: Stallion EC8/64, ONboard, Brumby device driver..............................................78 15.8.5. riscom8: SDL RISCom/8 card device driver......................................................................78 15.9. Parallel Device Drivers.................................................................................................. ...............79 15.9.1. lp: Parallel printer device driver..................................................................................... .....79 15.10. Bus Mouse Device Drivers................................................................................................ .........79 15.10.1. atixlmouse: ATIXL busmouse driver................................................................................79 15.10.2. busmouse: Logitech busmouse driver...............................................................................79 15.10.3. msbusmouse: Microsoft busmouse driver.........................................................................79 15.10.4. psaux: PS/2 mouse (aka "auxiliary device") driver...........................................................79 15.11. Tape Device Drivers..................................................................................................... ..............80 15.11.1. ftape: floppy tape (QIC 280/Travan) device driver...........................................................80 15.12. Watchdog Timers......................................................................................................... ...............80 15.12.1. WDT: WDT Watchdog timer device driver......................................................................80 15.12.2. softdog: Software Watchdog Timer..................................................................................81 15.12.3. pcwd: Berkshire Products PC Watchdog Driver...............................................................81 15.13. Sound Device Drivers.................................................................................................... .............81 16. Maintenance Of This Document............................................................................................... .................82 17. History.................................................................................................................... ......................................83 18. Copyright.................................................................................................................. ...................................84 Notes.......................................................................................................................... ............................84 Linux Loadable Kernel Module HOWTO v 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 2data.com. You can get the current version of this HOWTO from the Linux Documentation Project. This document is mainly geared toward Linux 2.4. It covers secondarily earlier Linux. It covers newer Linux only partially, but the author's goal to cover it completely in a future release. See in particular Section 12. The subject changed quite a bit over the course of Linux 2.5 releases, and this document ignores 2.5, since the 2.5 releases were not considered production releases. Instead, the document treats all the changes in 2.5 releases as if they were new with Linux 2.6. See Section 17 for a history of the document. 1. Preface 1 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. 2.1. Terminology Loadable kernel modules are often called just kernel modules or just modules, but those are rather misleading terms because there are lots of kinds of modules in the world and various pieces built into the base kernel can easily be called modules. We use the term loadable kernel module or LKM for the particular kinds of modules this HOWTO is about. Some people think of LKMs as outside of the kernel. They speak of LKMs communicating with the kernel. This is a mistake; LKMs (when loaded) are very much part of the kernel. The correct term for the part of the kernel that is bound into the image that you boot, i.e. all of the kernel except the LKMs, is "base kernel." LKMs communicate with the base kernel. In some other operating systems, the equivalent of a Linux LKM is called a "kernel extension." Now what is "Linux"? Well, first of all, the name is used for two entirely different things, and only one of them is really relevant here: The kernel and related items distributed as a package by Linus Torvalds. 1. A class of operating systems that traditionally are based on the Linux kernel. 2. Only the first of these is really useful in discussing LKMs. But even choosing this definition, people are often confused when it comes to LKMs. Is an LKM part of Linux or not? Though an LKM is always part of the kernel, it is part of Linux if it is distributed in the Linux kernel package, and not otherwise. Thus, if you have loaded into your kernel a device driver LKM that came with your device, you can't, strictly speaking, say that your kernel is Linux. Rather, it's a slight extension of Linux. As you might expect, it is commonplace to use the name "Linux" approximately 2 2 Lots of variations on Linux are in use and are widely distributed, and referred to as "Linux." In this document, though, we will stick to the strictest definition in the interest of clarity. 2.2. History of Loadable Kernel Modules LKMs did not exist in Linux in the beginning. Anything we use an LKM for today was built into the base kernel at kernel build time instead. LKMs have been around at least since Linux 1.2 (1995). Device drivers and such were always quite modular, though. When LKMs were invented, only a small amount of work was needed on these modules to make them buildable as LKMs. However, it had to be done on each and every one, so it took some time. Since about 2000, virtually everything that makes sense as an LKM has 2. Introduction to Linux Loadable Kernel Modules 2 at least had the option of being an LKM. 2.3. The Case For Loadable Kernel Modules You often have a choice between putting a module into the kernel by loading it as an LKM or binding it into the base kernel. LKMs have a lot of advantages over binding into the base kernel and I recommend them wherever possible. One advantage is that you don't have to rebuild your kernel as often. This saves you time and spares you the possibility of introducing an error in rebuilding and reinstalling the base kernel. Once you have a working base kernel, it is good to leave it untouched as long as possible. Another advantage is that LKMs help you diagnose system problems. A bug in a device driver which is bound into the kernel can stop your system from booting at all. And it can be really hard to tell which part of the base kernel caused the trouble. If the same device driver is an LKM, though, the base kernel is up and running before the device driver even gets loaded. If your system dies after the base kernel is up and running, it's an easy matter to track the problem down to the trouble 2making device driver and just not load that device driver until you fix the problem. LKMs can save you memory, because you have to have them loaded only when you're actually using them. All parts of the base kernel stay loaded all the time. And in real storage, not just virtual storage. LKMs are much faster to maintain and debug. What would require a full reboot to do with a filesystem driver built into the kernel, you can do with a few quick commands with LKMs. You can try out different parameters or even change the code repeatedly in rapid succession, without waiting for a boot. LKMs are not slower, by the way, than base kernel modules. Calling either one is simply a branch to the memory location where it resides. [1] Sometimes you have to build something into the base kernel instead of making it an LKM. Anything that is necessary to get the system up far enough to load LKMs must obviously be built into the base kernel. For example, the driver for the disk drive that contains the root filesystem must be built into the base kernel. 2.4. What LKMs Can't Do There is a tendency to think of LKMs like user space programs. They do share a lot of their properties, but LKMs are definitely not user space programs. They are part of the kernel. As such, they have free run of the system and can easily crash it. 2.5. What LKMs Are Used For There are six main things LKMs are used for: Device drivers. A device driver is designed for a specific piece of hardware. The kernel uses it to communicate with that piece of hardware without having to know any details of how the hardware works. For example, there is a device driver for ATA disk drives. There is one for NE2000 compatible Ethernet cards. To use any device, the kernel must contain a device driver for it. " Filesystem drivers. A filesystem driver interprets the contents of a filesystem (which is typically the contents of a disk drive) as files and directories and such. There are lots of different ways of storing " Linux Loadable Kernel Module HOWTO 2. Introduction to Linux Loadable Kernel Modules 3 files and directories and such on disk drives, on network servers, and in other ways. For each way, you need a filesystem driver. For example, there's a filesystem driver for the ext2 filesystem type used almost universally on Linux disk drives. There is one for the MS 2DOS filesystem too, and one for NFS. System calls. User space programs use system calls to get services from the kernel. For example, there are system calls to read a file, to create a new process, and to shut down the system. Most system calls are integral to the system and very standard, so are always built into the base kernel (no LKM option). But you can invent a system call of your own and install it as an LKM. Or you can decide you don't like the way Linux does something and override an existing system call with an LKM of your own. " Network drivers. A network driver interprets a network protocol. It feeds and consumes data streams at various layers of the kernel's networking function. For example, if you want an IPX link in your network, you would use the IPX driver. " TTY line disciplines. These are essentially augmentations of device drivers for terminal devices. " Executable interpreters. An executable interpreter loads and runs an executable. Linux is designed to be able to run executables in various formats, and each must have its own executable interpreter. " Linux Loadable Kernel Module HOWTO 2. Introduction to Linux Loadable Kernel Modules 4 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.6. 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 2and 2answer 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. 3. Making Loadable Kernel Modules 5 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 Insert an LKM into the kernel. rmmod Remove an LKM from the kernel. depmod Determine interdependencies between LKMs. kerneld Kerneld daemon program ksyms Display symbols that are exported by the kernel for use by new LKMs. lsmod List currently loaded LKMs. modinfo Display contents of .modinfo section in an LKM object file. modprobe Insert or remove an LKM or set of LKMs intelligently. For example, if you must load A before loading B, Modprobe will automatically load A when you tell it to load B. 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. 4. LKM Utilities 6 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.5. Note that the examples in this section are from Linux 2.4. In Linux 2.6, the technical aspects of loading LKMs are considerably different, and the most visible manifestation of this is that the LKM file has a suffix of ".ko" instead of ".o". From the user point of view, it looks quite similar, though. 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. (In Linux 2.6, there is no /proc/ksyms . Use /proc/kallsyms instead; the format is like the output of nm : look for symbols labelled "t"). 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. 5. How To Insert And Remove LKMs 7 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 2like 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 15. 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 2 2 the kernel version with which the LKM was intended to be used 2 2 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 for information on how you can see what insmod is seeing and confirm that the file is not in fact an LKM. If this is a module you created yourself with the intention of it being an LKM, the next question you have is: Why isn't an LKM? The most usual cause of this is that you did not include linux/module.h at the top of your source code and/or did not define the MODULE> macro. MODULE is intended to be set via the compile command ( 2DMODULE ) and determine whether the compilation produces an LKM or an object file for binding into the base kernel. If your module is like most modern modules and can be built only as an LKM, then you should just define it in your source code ( #define MODULE ) before you include include/module.h . Linux Loadable Kernel Module HOWTO 5. How To Insert And Remove LKMs 8 5.2. What Happens When An LKM Loads So you've successfully loaded an LKM, and verified that via /proc/modules . But how do you know it's working? That's up to the LKM, and varies according to what kind of LKM it is, but here are some of the more common actions of an LKM upon being loaded. The first thing a device driver LKM does after loading (which is what the module would do at boot time if it were bound into the base kernel) is usually to search the system for a device it knows how to drive. Just how it does this search varies from one driver to the next, and can usually be controlled by module parameters. But in any case, if the driver doesn't find any device it is capable of driving, it causes the load to fail. Otherwise, the driver registers itself as the driver for a particular major number and you can start using the device it found via a device special file that specifies that major number. It may also register itself as the handler for the interrupt level that the device uses. It may also send setup commands to the device, so you may see lights blink or something like that. You can see that a device driver has registered itself in the file /proc/devices . You can see that the device driver is handling the device's interrupts in /proc/interrupts . A nice device driver issues kernel messages telling what devices it found and is prepared to drive. (Kernel messages in most systems end up on the console and in the file /var/log/messages . You can also display recent ones with the dmesg program). Some drivers, however, are silent. A nice device driver also gives you (in kernel messages) some details of its search when it fails to find a device, but many just fail the load without explanation, and what you get is a list of guesses from insmod as to what the problem might have been. A network device (interface) driver works similarly, except that the LKM registers a device name of its choosing (e.g. eth0 ) rather than a major number. You can see the currently registered network device names in /proc/net/dev A filesystem driver, upon loading, registers itself as the driver for a filesystem type of a certain name. For example, the msdos driver registers itself as the driver for the filesystem type named msdos . (LKM authors typically name the LKM the same as the filesystem type it will drive). 5.3. Intelligent Loading Of LKMs 2 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 . Linux Loadable Kernel Module HOWTO 5. How To Insert And Remove LKMs 9 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 22/fs/msdos.o . In fact, modprobe 's argument may be a totally symbolic name that you have associated with some actual module. For example, modprobe eth0 loads the appropriate network device driver to create and drive your eth0 device, assuming you set that up properly in modules.conf . 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. modprobe is especially important because it is by default the program that the kernel module loader uses to load an LKM on demand. So if you use automatic module loading, you will need to set up modules.conf properly or things will not work. See Section 5.4. 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 insmod s in a startup script. 5.4. Automatic LKM Loading and Unloading 5.4.1. Automatic Loading You can cause an LKM to be loaded automatically when the kernel first needs it. You do this with either the kernel module loader, which is part of the Linux kernel, or the older version of it, a kerneld daemon. As an example, let's say you run a program that executes an open system call for a file in an MS 2DOS filesystem. But you don't have a filesystem driver for the MS 2DOS 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 2DOS, 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. Automatic kernel module loading is really not worth the complexity in most modern systems. It may make sense in a very small memory system, because you can keep parts of the kernel in memory only when you need them. But the amount of memory these modules uses is so cheap today that you will normally be a lot better off just loading all the modules you might need via startup scripts and leaving them loaded. Red Hat Linux uses automatic module loading via the kernel module loader. Both the kernel module loader and kerneld use modprobe , ergo insmod , to insert LKMs. See Section 5.3. Linux Loadable Kernel Module HOWTO 5. How To Insert And Remove LKMs 10 5.4.1.1. Kernel Module Loader There is some documentation of the kernel module loader in the file Documentation/kmod.txt in the Linux 2.4 source tree. 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 the modprobe : Argument Zero is the full file name of modprobe . The regular arguments are 2s , 2k , and the name of the LKM that the kernel wants. 2s is the user 2hostile form of 2 2syslog ; 2k is the cryptic way to say 2 2autoclean . I.e. messages from modprobe will go to syslog and the loaded LKM will have the "autoclean" flag set. The most important part of the modprobe invocation is, of course, the module name. Note that the "module name" argument to modprobe is not necessarily a real module name. It is often a symbolic name representing the role that module plays and you use an alias statement in modules.conf to tell what LKM gets loaded. For example, if your Ethernet adapter requires the 3c59x LKM, you would have probably need the line alias eth0 3c59x in /etc/modules.conf . Here is what the kernel module loader uses for a module name in some of the more popular cases (there are about 20 cases in which the kernel calls on the kernel module loader to load a module): When you try access a device and no device driver has registered to serve that device's major number, the kernel requests the module by the name block 2major 2N or char 2major 2N where N is the major number in decimal without leading zeroes. " When you try to access a network interface (maybe by running ifconfig against it) and no network device driver has registered to serve an interface by that name, the kernel requests the module named the same as the interface name (e.g. eth0 ). This applies to drivers for non 2physical interfaces such as ppp0 as well. " When you try to access a socket in a protocol family which no protocol driver has registered to drive, the kernel requests the module named net 2pf 2N , where N is the protocol family number (in decimal without leading zeroes). " When you try to NFS export a directory or otherwise access the NFS server via the NFS system call, the kernel requests the module named nfsd . " The ATA device driver (named ide ) loads the relevant drivers for classes of ATA devices by the names: ide 2disk , ide 2cd , ide 2floppy , ide 2tape , and ide 2scsi . " 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 . Linux Loadable Kernel Module HOWTO 5. How To Insert And Remove LKMs 11 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.4.1.2. Kerneld kerneld is explained at length in the Kerneld mini 2HOWTO, 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.4.2. Automatic Unloading 2 Autoclean 5.4.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 2 2autoclean 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.4.2.2. Removing The Autoclean LKMs The purpose of the autoclean flag is to 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 loaded only parts of the kernel that are presently needed, 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 2 2all 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 2 2all periodically. 5.5. /proc/modules To see the presently loaded LKMs, do Linux Loadable Kernel Module HOWTO 5. How To Insert And Remove LKMs 12 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 21 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. Do not confuse use count with "dependencies", which are described below. Here is another example, with more information: lp 5280 0 (unused) parport_pc 7552 1 parport 7600 1 [lp parport_pc] The stuff in square brackets ("[lp parport_pc]") describes dependencies. Here, the modules lp and parport_pc both refer to addresses within module parport (via external symbols that parport exports). So lp and parport_pc are "dependent" on (and are "dependencies of") parport . You cannot unload an LKM that has dependencies. But you can remove those dependencies by unloading the dependent LKMs. The "(unused)" legend means the LKM has never been used, i.e. it has never been in a state where it could not be unloaded. The kernel tracks this information for one simple reason: to assist in automatic LKM unloading policy. In a system where LKMs are loaded and unloaded automatically (see Section 5.4), you don't want to automatically load an LKM and then, before the guy who needed it loaded has a chance to use it, unload it because it is not in use. Here is something you won't normally see: mydriver 8154 0 (deleted) This is an LKM that is in "deleted" state. It's something of a misnomer 2 2 what it means is that the LKM is in the process of being unloaded. You can no longer load LKMs that depend on it, but it's still present in the system. Unloading an LKM is usually close to instantaneous, so if you see this status, you probably have a broken LKM. Its cleanup routine probably got into an infinite loop or stall or crashed (causing a kernel oops). If that's the case, the only way to clear this status is to reboot. There are similar statuses "initializing" and "uninitialized". Linux Loadable Kernel Module HOWTO 5. How To Insert And Remove LKMs 13 The legend "(autoclean)" refers to the autoclean flag, discussed in Section 5.4. 5.6. 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 2 2release 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 2related 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. Linux Loadable Kernel Module HOWTO 5. How To Insert And Remove LKMs 14 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 ... There are actually a bunch of different problems that result in this symptom. In any case, you can get closer to the problem by looking at /proc/ksyms and confirming that the symbols in the message are indeed not in the list. 6.1. Some LKMs Prerequire Other LKMs One reason you get this is because you have not loaded another LKM that contains instructions or data that your LKM needs to access. A primary purpose of modprobe is to avoid this failure. See Section 5.3. 6.2. An LKM Must Match The Base Kernel The designers of loadable kernel modules realized there would be a problem with having the kernel in multiple files, possibly distributed independently of one another. What if the LKM mydriver.o was written and compiled to work with the Linux 1.2.1 base kernel, and then someone tried to load it into a Linux 1.2.2 kernel? What if there was a change between 1.2.1 and 1.2.2 in the way a kernel subroutine that mydriver.o calls works? These are internal kernel subroutines, so what's to stop them from changing from one release to the next? You could end up with a broken kernel. To address this problem, the creators of LKMs endowed them with a kernel version number. The special .modinfo section of the mydriver.o object file in this example has "1.2.1" in it because it was compiled using header files from Linux 1.2.1. Try to load it into a 1.2.2 kernel and insmod notices the mismatch and fails, telling you you have a kernel version mismatch. But wait. What's the chance that there really is an incompatibility between Linux 1.2.1 and 1.2.2 that will affect mydriver.o ? mydriver.o only calls a few subroutines and accesses a few data structures. Surely they don't change with every minor release. Must we recompile every LKM against the header files for the particular kernel into which we

less