Linux Loadable Kernel Module HOWTO Bryan Henderson 2006−09−24 Revision History Revision v1.09 2006−09−24 Revised by: bjh Fix typos. Revision v1.08 2006−03−03 Revised by: bjh Add copyright information. Revision v1.07 2005−07−20 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−01−12 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−01−05 Revised by: bjh Add information on module.h and −DMODULE. Fix tldb.org to tldp.org. Add information on kallsyms. Revision v1.04 2003−10−10 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−07−03 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−05−21 Revised by: bjh Correct explanation of symbol versioning. Correct author of Linux Device Drivers. Add info about memory allocation penalty of LKM vs bound−in. Add LKM−to−LKM symbol matching requirement. Add open source licensing issue in LKM symbol resolution. Add SMP symbol versioning info. Revision v1.01 2001−08−18 Revised by: bjh Add material on various features created in the last few years: kernel module loader, ksymoops symbols, kernel−version−dependent LKM file location. Revision v1.00 2001−06−14 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. Linux Loadable Kernel Module HOWTO 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 − Modprobe......................................................................................9 5.4. Automatic LKM Loading and Unloading.......................................................................................10 5.4.1. Automatic Loading................................................................................................................10 5.4.2. Automatic Unloading − 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......................................................................................18 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 i Linux Loadable Kernel Module HOWTO 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 − 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