The Linux Kernel Module Programming Guide
Peter Jay Salzman
Michael Burian
Ori Pomerantz
Copyright © 2001 Peter Jay Salzman
2005−12−31 ver 2.6.3
The Linux Kernel Module Programming Guide is a free book; you may reproduce and/or modify it under the
terms of the Open Software License, version 1.1. You can obtain a copy of this license at
http://opensource.org/licenses/osl.php.
This book is distributed in the hope it will be useful, but without any warranty, without even the implied
warranty of merchantability or fitness for a particular purpose.
The author encourages wide distribution of this book for personal or commercial use, provided the above
copyright notice remains intact and the method adheres to the provisions of the Open Software License. In
summary, you may copy and distribute this book free of charge or for a profit. No explicit permission is
required from the author for reproduction of this book in any medium, physical or electronic.
Derivative works and translations of this document must be placed under the Open Software License, and the
original copyright notice must remain intact. If you have contributed new material to this book, you must
make the material and source code available for your revisions. Please make revisions and updates available
directly to the document maintainer, Peter Jay Salzman <p@dirac.org>. This will allow for the merging of
updates and provide consistent revisions to the Linux community.
If you publish or distribute this book commercially, donations, royalties, and/or printed copies are greatly
appreciated by the author and the Linux Documentation Project (LDP). Contributing in this way shows your
support for free software and the LDP. If you have questions or comments, please contact the address above.
Table of Contents
Foreword..............................................................................................................................................................1
1. Authorship...........................................................................................................................................1
2. Versioning and Notes...........................................................................................................................1
3. Acknowledgements..............................................................................................................................1
Chapter 1. Introduction......................................................................................................................................2
1.1. What Is A Kernel Module?...............................................................................................................2
1.2. How Do Modules Get Into The Kernel?...........................................................................................2
1.2.1. Before We Begin.....................................................................................................................3
Chapter 2. Hello World......................................................................................................................................5
2.1. Hello, World (part 1): The Simplest Module....................................................................................5
2.1.1. Introducing printk().................................................................................................................6
2.2. Compiling Kernel Modules..............................................................................................................6
2.3. Hello World (part 2)..........................................................................................................................7
2.4. Hello World (part 3): The __init and __exit Macros........................................................................8
2.5. Hello World (part 4): Licensing and Module Documentation..........................................................9
2.6. Passing Command Line Arguments to a Module...........................................................................11
2.7. Modules Spanning Multiple Files...................................................................................................13
2.8. Building modules for a precompiled kernel....................................................................................15
Chapter 3. Preliminaries..................................................................................................................................17
3.1. Modules vs Programs......................................................................................................................17
3.1.1. How modules begin and end.................................................................................................17
3.1.2. Functions available to modules.............................................................................................17
3.1.3. User Space vs Kernel Space..................................................................................................18
3.1.4. Name Space...........................................................................................................................18
3.1.5. Code space.............................................................................................................................19
3.1.6. Device Drivers.......................................................................................................................19
Chapter 4. Character Device Files..................................................................................................................21
4.1. Character Device Drivers................................................................................................................21
4.1.1. The file_operations Structure................................................................................................21
4.1.2. The file structure...................................................................................................................22
4.1.3. Registering A Device............................................................................................................22
4.1.4. Unregistering A Device.........................................................................................................23
4.1.5. chardev.c................................................................................................................................23
4.1.6. Writing Modules for Multiple Kernel Versions....................................................................26
Chapter 5. The /proc File System....................................................................................................................28
5.1. The /proc File System.....................................................................................................................28
5.2. Read and Write a /proc File............................................................................................................30
5.3. Manage /proc file with standard filesystem....................................................................................33
5.4. Manage /proc file with seq_file......................................................................................................37
Chapter 6. Using /proc For Input....................................................................................................................41
6.1. TODO: Write a chapter about sysfs................................................................................................41
The Linux Kernel Module Programming Guide
i
Table of Contents
Chapter 7. Talking To Device Files.................................................................................................................42
7.1. Talking to Device Files (writes and IOCTLs)................................................................................42
Chapter 8. System Calls...................................................................................................................................51
8.1. System Calls...................................................................................................................................51
Chapter 9. Blocking Processes.........................................................................................................................56
9.1. Blocking Processes.........................................................................................................................56
Chapter 10. Replacing Printks.........................................................................................................................64
10.1. Replacing printk............................................................................................................................64
10.2. Flashing keyboard LEDs...............................................................................................................66
Chapter 11. Scheduling Tasks.........................................................................................................................69
11.1. Scheduling Tasks..........................................................................................................................69
Chapter 12. Interrupt Handlers......................................................................................................................73
12.1. Interrupt Handlers.........................................................................................................................73
12.1.1. Interrupt Handlers................................................................................................................73
12.1.2. Keyboards on the Intel Architecture...................................................................................73
Chapter 13. Symmetric Multi Processing.......................................................................................................77
13.1. Symmetrical Multi−Processing.....................................................................................................77
Chapter 14. Common Pitfalls...........................................................................................................................78
14.1. Common Pitfalls...........................................................................................................................78
Appendix A. Changes: 2.0 To 2.2....................................................................................................................79
A.1. Changes between 2.4 and 2.6.........................................................................................................79
A.1.1. Changes between 2.4 and 2.6...............................................................................................79
Appendix B. Where To Go From Here...........................................................................................................80
B.1. Where From Here?.........................................................................................................................80
The Linux Kernel Module Programming Guide
ii
Foreword
1. Authorship
The Linux Kernel Module Programming Guide was originally written for the 2.2 kernels by Ori Pomerantz.
Eventually, Ori no longer had time to maintain the document. After all, the Linux kernel is a fast moving
target. Peter Jay Salzman took over maintenance and updated it for the 2.4 kernels. Eventually, Peter no
longer had time to follow developments with the 2.6 kernel, so Michael Burian became a co−maintainer to
update the document for the 2.6 kernels.
2. Versioning and Notes
The Linux kernel is a moving target. There has always been a question whether the LKMPG should remove
deprecated information or keep it around for historical sake. Michael Burian and I decided to create a new
branch of the LKMPG for each new stable kernel version. So version LKMPG 2.4.x will address Linux kernel
2.4 and LKMPG 2.6.x will address Linux kernel 2.6. No attempt will be made to archive historical
information; a person wishing this information should read the appropriately versioned LKMPG.
The source code and discussions should apply to most architectures, but I can't promise anything. One
exception is Chapter 12, Interrupt Handlers, which should not work on any architecture except for x86.
3. Acknowledgements
The following people have contributed corrections or good suggestions: Ignacio Martin, David Porter, Daniele
Paolo Scarpazza, Dimo Velev, Francois Audeon and Horst Schirmeier.
Foreword 1
Chapter 1. Introduction
1.1. What Is A Kernel Module?
So, you want to write a kernel module. You know C, you've written a few normal programs to run as
processes, and now you want to get to where the real action is, to where a single wild pointer can wipe out
your file system and a core dump means a reboot.
What exactly is a kernel module? Modules are pieces of code that can be loaded and unloaded into the kernel
upon demand. They extend the functionality of the kernel without the need to reboot the system. For example,
one type of module is the device driver, which allows the kernel to access hardware connected to the system.
Without modules, we would have to build monolithic kernels and add new functionality directly into the
kernel image. Besides having larger kernels, this has the disadvantage of requiring us to rebuild and reboot the
kernel every time we want new functionality.
1.2. How Do Modules Get Into The Kernel?
You can see what modules are already loaded into the kernel by running lsmod, which gets its information by
reading the file /proc/modules.
How do these modules find their way into the kernel? When the kernel needs a feature that is not resident in
the kernel, the kernel module daemon kmod[1] execs modprobe to load the module in. modprobe is passed a
string in one of two forms:
A module name like softdog or ppp.•
A more generic identifier like char−major−10−30.•
If modprobe is handed a generic identifier, it first looks for that string in the file
/etc/modprobe.conf.[2] If it finds an alias line like:
alias char−major−10−30 softdog
it knows that the generic identifier refers to the module softdog.ko.
Next, modprobe looks through the file /lib/modules/version/modules.dep, to see if other
modules must be loaded before the requested module may be loaded. This file is created by depmod −a and
contains module dependencies. For example, msdos.ko requires the fat.ko module to be already loaded
into the kernel. The requested module has a dependancy on another module if the other module defines
symbols (variables or functions) that the requested module uses.
Lastly, modprobe uses insmod to first load any prerequisite modules into the kernel, and then the requested
module. modprobe directs insmod to /lib/modules/version/[3], the standard directory for modules.
insmod is intended to be fairly dumb about the location of modules, whereas modprobe is aware of the default
location of modules, knows how to figure out the dependancies and load the modules in the right order. So for
example, if you wanted to load the msdos module, you'd have to either run:
insmod /lib/modules/2.6.11/kernel/fs/fat/fat.ko
insmod /lib/modules/2.6.11/kernel/fs/msdos/msdos.ko
Chapter 1. Introduction 2
