diff --git a/3.16/LKMPG-3.16.html b/3.16/LKMPG-3.16.html index 81cdfd6..1f56d34 100644 --- a/3.16/LKMPG-3.16.html +++ b/3.16/LKMPG-3.16.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + The Linux Kernel Module Programming Guide @@ -264,182 +264,182 @@ for the JavaScript code in this tag.

Table of Contents

-
-

Introduction

-
+
+

Introduction

+

-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. +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 3.0.

@@ -459,18 +459,18 @@ If you publish or distribute this book commercially, donations, royalties, and/o

-
-

Authorship

-
+
+

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. Bob Mottram updated the examples for 3.8 and 3.16 kernels and modified or updated some chapters.

-
-

Versioning and Notes

-
+
+

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 3.16.x will address Linux kernel 3.16 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.

@@ -481,18 +481,18 @@ The source code and discussions should apply to most architectures, but I can't
-
-

Acknowledgements

-
+
+

Acknowledgements

+

The following people have contributed corrections or good suggestions: Ignacio Martin, David Porter, Daniele Paolo Scarpazza, Dimo Velev, Francois Audeon, Horst Schirmeier, Bob Mottram and Roman Lakeev.

-
-

What Is A Kernel Module?

-
+
+

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.

@@ -503,9 +503,9 @@ What exactly is a kernel module? Modules are pieces of code that can be loaded a
-
-

Kernel module package

-
+
+

Kernel module package

+

Linux distros provide the commands modprobe, insmod and depmod within a package.

@@ -521,9 +521,9 @@ On Debian:
-
-

What Modules are in my Kernel?

-
+
+

What Modules are in my Kernel?

+

To discover what modules are already loaded within your current kernel use the command lsmod.

@@ -553,17 +553,17 @@ This can be a long list, and you might prefer to search for something particular
-
-

Do I need to download and compile the kernel?

-
+
+

Do I need to download and compile the kernel?

+

For the purposes of following this guide you don't necessarily need to do that. However, it would be wise to run the examples within a test distro running on a virtual machine in order to avoid any possibility of messing up your system.

-
-

How Do I Install Modules Into The Kernel?

-
+
+

How Do I Install Modules Into The Kernel?

+

When the kernel needs a feature that is not currently resident in the kernel, the kernel module daemon kmod[1] runs the modprobe command to load it. modprobe is passed a string in one of two forms:

@@ -618,9 +618,9 @@ Now you know how modules get into the kernel. There's a bit more to the story if

-
-

Header files

-
+
+

Header files

+

Before you can compile anything you'll need the header files for your current kernel.

@@ -642,21 +642,25 @@ This will tell you what kernel header files are available. Then for example:
-
-

Before We Begin

-
+
+

Before We Begin

+

Before we delve into code, there are a few issues we need to cover. Everyone's system is different and everyone has their own groove. Getting your first "hello world" program to compile and load correctly can sometimes be a trick. Rest assured, after you get over the initial hurdle of doing it for the first time, it will be smooth sailing thereafter.

-
  • Modversioning
    +
      +
    • Modversioning
      +

      A module compiled for one kernel won't load if you boot a different kernel unless you enable CONFIG_MODVERSIONS in the kernel. We won't go into module versioning until later in this guide. Until we cover modversions, the examples in the guide may not work if you're running a kernel with modversioning turned on. However, most stock Linux distro kernels come with it turned on. If you're having trouble loading the modules because of versioning errors, compile a kernel with modversioning turned off.

      -
      • +
    +
    • -
  • Using X
    +
  • Using X
    +

    It is highly recommended that you type in, compile and load all the examples this guide discusses. It's also highly recommended you do this from a console. You should not be working on this stuff in X.

    @@ -664,9 +668,11 @@ It is highly recommended that you type in, compile and load all the examples thi

    Modules can't print to the screen like printf() can, but they can log information and warnings, which ends up being printed on your screen, but only on a console. If you insmod a module from an xterm, the information and warnings will be logged, but only to your log files. You won't see it unless you look through your log files. To have immediate access to this information, do all your work from the console.

    -
    • +
+ -
  • Compiling Issues and Kernel Version
    +
  • Compiling Issues and Kernel Version
    +

    Very often, Linux distros will distribute kernel source that has been patched in various non-standard ways, which may cause trouble.

    @@ -682,17 +688,20 @@ To avoid these two problems, I highly recommend that you download, compile and b

    Ironically, this can also cause a problem. By default, gcc on your system may look for the kernel headers in their default location rather than where you installed the new copy of the kernel (usually in usr/src. This can be fixed by using gcc's -I switch.

    -
    • +
    + +
    -
    -

    Hello World

    -
    -
    -

    Hello, World (part 1): The Simplest Module

    -
    +
    +

    Hello World

    +
    +
    +
    +

    Hello, World (part 1): The Simplest Module

    +

    Most people learning programming start out with some sort of "hello world" example. I don't know what happens to people who break with this tradition, but I think it's safer not to find out. We'll start with a series of hello world programs that demonstrate the different aspects of the basics of writing a kernel module.

    @@ -702,9 +711,9 @@ Here's the simplest module possible.

    -
    -

    Example: hello-1.c

    -
    +
    +

    Example: hello-1.c

    +

    Make a test directory:

    @@ -839,7 +848,9 @@ Lastly, every kernel module needs to include linux/module.h. We needed to includ

    -
    • Introducing printk()
      +
        +
      • Introducing printk()
        +

        Despite what you might think, printk() was not meant to communicate information to the user, even though we used it for exactly this purpose in hello-1! It happens to be a logging mechanism for the kernel, and is used to log information or give warnings. Therefore, each printk() statement comes with a priority, which is the <1> and KERN_ALERT you see. There are 8 priorities and the kernel has macros for them, so you don't have to use cryptic numbers, and you can view them (and their meanings) in linux/kernel.h. If you don't specify a priority level, the default priority, DEFAULT_MESSAGE_LOGLEVEL, will be used.

        @@ -851,9 +862,11 @@ Take time to read through the priority macros. The header file also describes wh

        If the priority is less than int console_loglevel, the message is printed on your current terminal. If both syslogd and klogd are running, then the message will also get appended to /var/log/messages, whether it got printed to the console or not. We use a high priority, like KERN_ALERT, to make sure the printk() messages get printed to your console rather than just logged to your logfile. When you write real modules, you'll want to use priorities that are meaningful for the situation at hand.

        -
        • +
      +
      • -
    • About Compiling
      +
    • About Compiling
      +

      Kernel modules need to be compiled a bit differently from regular userspace apps. Former kernel versions required us to care much about these settings, which are usually stored in Makefiles. Although hierarchically organized, many redundant settings accumulated in sublevel Makefiles and made them large and rather difficult to maintain. Fortunately, there is a new way of doing these things, called kbuild, and the build process for external loadable modules is now fully integrated into the standard kernel build mechanism. To learn more on how to compile modules which are not part of the official kernel (such as all the examples you'll find in this guide), see file linux/Documentation/kbuild/modules.txt.

      @@ -867,21 +880,23 @@ Additional details about Makefiles for kernel modules are available in linux/ Here's another exercise for the reader. See that comment above the return statement in init_module()? Change the return value to something negative, recompile and load the module again. What happens?

      -
    +
    + +
    -
    -

    Hello World (part 2): Hello and Goodbye

    -
    +
    +

    Hello World (part 2): Hello and Goodbye

    +

    In early kernel versions you had to use the init_module and cleanup_module functions, as in the first hello world example, but these days you can name those anything you want by using the module_init and module_exit macros. These macros are defined in linux/init.h. The only requirement is that your init and cleanup functions must be defined before calling the those macros, otherwise you'll get compilation errors. Here's an example of this technique:

    -
    -

    Example: hello-2.c

    -
    +
    +

    Example: hello-2.c

    +
    /*
  *  hello-2.c - Demonstrating the module_init() and module_exit() macros.
@@ -913,9 +928,9 @@ So now we have two real kernel modules under our belt. Adding another module is
    -
    -

    Example: Makefile for both our modules

    -
    +
    +

    Example: Makefile for both our modules

    +
    obj-m += hello-1.o
 obj-m += hello-2.o
@@ -936,9 +951,9 @@ you can see, some things get hardwired into the kernel (obj-y) but where are all
    -
    -

    Hello World (part 3): The __init and __exit Macros

    -
    +
    +

    Hello World (part 3): The __init and __exit Macros

    +

    This demonstrates a feature of kernel 2.2 and later. Notice the change in the definitions of the init and cleanup functions. The __init macro causes the init function to be discarded and its memory freed once the init function finishes for built-in drivers, but not loadable modules. If you think about when the init function is invoked, this makes perfect sense.

    @@ -956,9 +971,9 @@ These macros are defined in linux/init.h and serve to free up kernel memo

    -
    -

    Example: hello-3.c

    -
    +
    +

    Example: hello-3.c

    +
    /*
  *  hello-3.c - Illustrating the __init, __initdata and __exit macros.
@@ -988,9 +1003,9 @@ module_exit(hello_3_exit);
    -
    -

    Hello World (part 4): Licensing and Module Documentation

    -
    +
    +

    Hello World (part 4): Licensing and Module Documentation

    +

    Honestly, who loads or even cares about proprietary modules? If you do then you might have seen something like this:

    @@ -1012,9 +1027,9 @@ To reference what license you're using a macro is available called MODULE_LIC

    -
    -

    Example: hello-4.c

    -
    +
    +

    Example: hello-4.c

    +
    /*
  *  hello-4.c - Demonstrates module documentation.
@@ -1047,9 +1062,9 @@ module_exit(cleanup_hello_4);
    -
    -

    Passing Command Line Arguments to a Module

    -
    +
    +

    Passing Command Line Arguments to a Module

    +

    Modules can take command line arguments, but not with the argc/argv you might be used to.

    @@ -1092,9 +1107,9 @@ Lastly, there's a macro function, MODULE_PARM_DESC(), that is used to doc
    -
    -

    Example: hello-5.c

    -
    +
    +

    Example: hello-5.c

    +
    /*
  *  hello-5.c - Demonstrates command line argument passing to a module.
@@ -1205,9 +1220,9 @@ hello-5.o: invalid argument syntax for mylong: 'h'
    -
    -

    Modules Spanning Multiple Files

    -
    +
    +

    Modules Spanning Multiple Files

    +

    Sometimes it makes sense to divide a kernel module between several source files.

    @@ -1217,9 +1232,9 @@ Here's an example of such a kernel module.

    -
    -

    Example: start.c

    -
    +
    +

    Example: start.c

    +
    /*
  *  start.c - Illustration of multi filed modules
@@ -1243,9 +1258,9 @@ The next file:
    -
    -

    Example: stop.c

    -
    +
    +

    Example: stop.c

    +
    /*
  *  stop.c - Illustration of multi filed modules
@@ -1268,9 +1283,9 @@ And finally, the makefile:
    -
    -

    Example: Makefile

    -
    +
    +

    Example: Makefile

    +
    obj-m += hello-1.o
 obj-m += hello-2.o
@@ -1295,9 +1310,9 @@ This is the complete makefile for all the examples we've seen so far. The first
    -
    -

    Building modules for a precompiled kernel

    -
    +
    +

    Building modules for a precompiled kernel

    +

    Obviously, we strongly suggest you to recompile your kernel, so that you can enable a number of useful debugging features, such as forced module unloading (MODULE_FORCE_UNLOAD): when this option is enabled, you can force the kernel to unload a module even when it believes it is unsafe, via a sudo rmmod -f module command. This option can save you a lot of time and a number of reboots during the development of a module. If you don't want to recompile your kernel then you should consider running the examples within a test distro on a virtual machine. If you mess anything up then you can easily reboot or restore the VM.

    @@ -1389,12 +1404,13 @@ If you do not desire to actually compile the kernel, you can interrupt the build
    -
    -

    Preliminaries

    -
    -
    -

    How modules begin and end

    -
    +
    +

    Preliminaries

    +
    +
    +
    +

    How modules begin and end

    +

    A program usually begins with a main() function, executes a bunch of instructions and terminates upon completion of those instructions. Kernel modules work a bit differently. A module always begin with either the init_module or the function you specify with module_init call. This is the entry function for modules; it tells the kernel what functionality the module provides and sets up the kernel to run the module's functions when they're needed. Once it does this, entry function returns and the module does nothing until the kernel wants to do something with the code that the module provides.

    @@ -1409,9 +1425,9 @@ Every module must have an entry function and an exit function. Since there's mor
    -
    -

    Functions available to modules

    -
    +
    +

    Functions available to modules

    +

    Programmers use functions they don't define all the time. A prime example of this is printf(). You use these library functions which are provided by the standard C library, libc. The definitions for these functions don't actually enter your program until the linking stage, which insures that the code (for printf() for example) is available, and fixes the call instruction to point to that code.

    @@ -1449,9 +1465,9 @@ You can even write modules to replace the kernel's system calls, which we'll do
    -
    -

    User Space vs Kernel Space

    -
    +
    +

    User Space vs Kernel Space

    +

    A kernel is all about access to resources, whether the resource in question happens to be a video card, a hard drive or even memory. Programs often compete for the same resource. As I just saved this document, updatedb started updating the locate database. My vim session and updatedb are both using the hard drive concurrently. The kernel needs to keep things orderly, and not give users access to resources whenever they feel like it. To this end, a CPU can run in different modes. Each mode gives a different level of freedom to do what you want on the system. The Intel 80386 architecture had 4 of these modes, which were called rings. Unix uses only two rings; the highest ring (ring 0, also known as `supervisor mode' where everything is allowed to happen) and the lowest ring, which is called `user mode'.

    @@ -1462,9 +1478,9 @@ Recall the discussion about library functions vs system calls. Typically, you us
    -
    -

    Name Space

    -
    +
    +

    Name Space

    +

    When you write a small C program, you use variables which are convenient and make sense to the reader. If, on the other hand, you're writing routines which will be part of a bigger problem, any global variables you have are part of a community of other peoples' global variables; some of the variable names can clash. When a program has lots of global variables which aren't meaningful enough to be distinguished, you get namespace pollution. In large projects, effort must be made to remember reserved names, and to find ways to develop a scheme for naming unique variable names and symbols.

    @@ -1479,9 +1495,9 @@ The file /proc/kallsyms holds all the symbols that the kernel knows about
    -
    -

    Code space

    -
    +
    +

    Code space

    +

    Memory management is a very complicated subject — the majority of O'Reilly's "Understanding The Linux Kernel" is just on memory management! We're not setting out to be experts on memory managements, but we do need to know a couple of facts to even begin worrying about writing real modules.

    @@ -1500,15 +1516,17 @@ By the way, I would like to point out that the above discussion is true for any
    -
    -

    Device Drivers

    -
    +
    +

    Device Drivers

    +

    One class of module is the device driver, which provides functionality for hardware like a TV card or a serial port. On unix, each piece of hardware is represented by a file located in /dev named a device file which provides the means to communicate with the hardware. The device driver provides the communication on behalf of a user program. So the es1370.o sound card device driver might connect the /dev/sound device file to the Ensoniq IS1370 sound card. A userspace program like mp3blaster can use /dev/sound without ever knowing what kind of sound card is installed.

    -
    • Major and Minor Numbers
      +
        +
      • Major and Minor Numbers
        +

        Let's look at some device files. Here are device files which represent the first three partitions on the primary master IDE hard drive:

        @@ -1567,16 +1585,19 @@ brw-rw---- 1 root floppy 2, 44 Jul 5 2000 /dev/fd0u1680

        By now you can look at these two device files and know instantly that they are block devices and are handled by same driver (block major 2). You might even be aware that these both represent your floppy drive, even if you only have one floppy drive. Why two files? One represents the floppy drive with 1.44 MB of storage. The other is the same floppy drive with 1.68 MB of storage, and corresponds to what some people call a `superformatted' disk. One that holds more data than a standard formatted floppy. So here's a case where two device files with different minor number actually represent the same piece of physical hardware. So just be aware that the word `hardware' in our discussion can mean something very abstract.

        -
      +
      +
      • +
    -
    -

    Character Device drivers

    -
    -
    -

    The file_operations Structure

    -
    +
    +

    Character Device drivers

    +
    +
    +
    +

    The file_operations Structure

    +

    The file_operations structure is defined in linux/fs.h, and holds pointers to functions defined by the driver that perform various operations on the device. Each field of the structure corresponds to the address of some function defined by the driver to handle a requested operation.

    @@ -1661,9 +1682,9 @@ An instance of struct file_operations containing pointers to functions that are
    -
    -

    The file structure

    -
    +
    +

    The file structure

    +

    Each device is represented in the kernel by a file structure, which is defined in linux/fs.h. Be aware that a file is a kernel level structure and never appears in a user space program. It's not the same thing as a FILE, which is defined by glibc and would never appear in a kernel space function. Also, its name is a bit misleading; it represents an abstract open `file', not a file on a disk, which is represented by a structure named inode.

    @@ -1678,9 +1699,9 @@ Go ahead and look at the definition of file. Most of the entries you see, like s
    -
    -

    Registering A Device

    -
    +
    +

    Registering A Device

    +

    As discussed earlier, char devices are accessed through device files, usually located in /dev[7]. The major number tells you which driver handles which device file. The minor number is used only by the driver itself to differentiate which device it's operating on, just in case the driver handles more than one device.

    @@ -1708,9 +1729,9 @@ If you pass a major number of 0 to register_chrdev, the return value will be the
    -
    -

    Unregistering A Device

    -
    +
    +

    Unregistering A Device

    +

    We can't allow the kernel module to be rmmod'ed whenever root feels like it. If the device file is opened by a process and then we remove the kernel module, using the file would cause a call to the memory location where the appropriate function (read/write) used to be. If we're lucky, no other code was loaded there, and we'll get an ugly error message. If we're unlucky, another kernel module was loaded into the same location, which means a jump into the middle of another function within the kernel. The results of this would be impossible to predict, but they can't be very positive.

    @@ -1730,9 +1751,9 @@ It's important to keep the counter accurate; if you ever do lose track of the co
    -
    -

    chardev.c

    -
    +
    +

    chardev.c

    +

    The next code sample creates a char driver named chardev. You can cat its device file.

    @@ -1747,9 +1768,9 @@ The next code sample creates a char driver named chardev. You can cat its device

    -
    -

    Example: chardev.c

    -
    +
    +

    Example: chardev.c

    +
    /*
  *  chardev.c: Creates a read-only char device that says how many times
@@ -1923,9 +1944,9 @@ The next code sample creates a char driver named chardev. You can cat its device
    -
    -

    Writing Modules for Multiple Kernel Versions

    -
    +
    +

    Writing Modules for Multiple Kernel Versions

    +

    The system calls, which are the major interface the kernel shows to the processes, generally stay the same across versions. A new system call may be added, but usually the old ones will behave exactly like they used to. This is necessary for backward compatibility – a new kernel version is not supposed to break regular processes. In most cases, the device files will also remain the same. On the other hand, the internal interfaces within the kernel can and do change between versions.

    @@ -1949,9 +1970,9 @@ You might already have noticed that recent kernels look different. In case you h
    -
    -

    The /proc File System

    -
    +
    +

    The /proc File System

    +

    In Linux, there is an additional mechanism for the kernel and kernel modules to send information to processes — the /proc file system. Originally designed to allow easy access to information about processes (hence the name), it is now used by every bit of the kernel which has something interesting to report, such as /proc/modules which provides the list of modules and /proc/meminfo which stats memory usage statistics.

    @@ -1987,9 +2008,9 @@ HelloWorld!
    -
    -

    Example: procfs1.c

    -
    +
    +

    Example: procfs1.c

    +
    #include <linux/module.h>
 #include <linux/kernel.h>
@@ -2042,9 +2063,9 @@ HelloWorld!
    -
    -

    Read and Write a /proc File

    -
    +
    +

    Read and Write a /proc File

    +

    We have seen a very simple example for a /proc file where we only read the file /proc/helloworld. It's also possible to write in a /proc file. It works the same way as read, a function is called when the /proc file is written. But there is a little difference with read, data comes from user, so you have to import data from user space to kernel space (with copy_from_user or get_user)

    @@ -2058,9 +2079,9 @@ The only memory segment accessible to a process is its own, so when writing regu

    -
    -

    Example: procfs2.c

    -
    +
    +

    Example: procfs2.c

    +
    /**
  *  procfs2.c -  create a "file" in /proc
@@ -2166,9 +2187,9 @@ The only memory segment accessible to a process is its own, so when writing regu
    -
    -

    Manage /proc file with standard filesystem

    -
    +
    +

    Manage /proc file with standard filesystem

    +

    We have seen how to read and write a /proc file with the /proc interface. But it's also possible to manage /proc file with inodes. The main concern is to use advanced functions, like permissions.

    @@ -2186,9 +2207,9 @@ It's important to note that the standard roles of read and write are reversed in

    -
    -

    Example: procfs3.c

    -
    +
    +

    Example: procfs3.c

    +
    #include <linux/kernel.h>
 #include <linux/module.h>
@@ -2279,9 +2300,9 @@ Still hungry for procfs examples? Well, first of all keep in mind, there are rum
    -
    -

    Manage /proc file with seq_file

    -
    +
    +

    Manage /proc file with seq_file

    +

    As we have seen, writing a /proc file may be quite "complex". So to help people writting /proc file, there is an API named seq_file that helps @@ -2298,9 +2319,9 @@ BE CARREFUL: when a sequence is finished, another one starts. That means that at

    -
    -

    Figure: How seq_file works

    -
    +
    +

    Figure: How seq_file works

    +

    seq_file.png @@ -2321,9 +2342,9 @@ Seq_file provides basic functions for file_operations, as seq_read, seq_lseek, a

    -
    -

    Example: procfs4.c

    -
    +
    +

    Example: procfs4.c

    +
    /**
  *  procfs4.c -  create a "file" in /proc
@@ -2481,9 +2502,9 @@ You can also read the code of fs/seq_file.c in the linux kernel.
    -
    -

    sysfs: Interacting with your module

    -
    +
    +

    sysfs: Interacting with your module

    +

    sysfs allows you to interact with the running kernel by reading or setting variables inside of modules. This can be useful for debugging purposes, or just as an interface for userland applications or scripts.

    @@ -2493,9 +2514,9 @@ An example of a hello world module which includes a variable accessible via sysf

    -
    -

    Example: hello-sysfs.c

    -
    +
    +

    Example: hello-sysfs.c

    +
    /*
  * hello-sysfs.c sysfs example
@@ -2618,9 +2639,9 @@ Finally, remove the test module:
    -
    -

    Talking To Device Files

    -
    +
    +

    Talking To Device Files

    +

    Device files are supposed to represent physical devices. Most physical devices are used for output as well as input, so there has to be some mechanism for device drivers in the kernel to get the output to send to the device from processes. This is done by opening the device file for output and writing to it, just like writing to a file. In the following example, this is implemented by device_write.

    @@ -2642,9 +2663,9 @@ If you want to use ioctls in your own kernel modules, it is best to receive an o

    -
    -

    Example: chardev.c

    -
    +
    +

    Example: chardev.c

    +
    /*
  *  chardev.c - Create an input/output character device */
@@ -2926,9 +2947,9 @@ If you want to use ioctls in your own kernel modules, it is best to receive an o
    -
    -

    Example: chardev.h

    -
    +
    +

    Example: chardev.h

    +
    /*
  *  chardev.h - the header file with the ioctl definitions.
@@ -3001,9 +3022,9 @@ If you want to use ioctls in your own kernel modules, it is best to receive an o
    -
    -

    Example: ioctl.c

    -
    +
    +

    Example: ioctl.c

    +
    /*
  *  ioctl.c - the process to use ioctl's to control the kernel module
@@ -3111,9 +3132,9 @@ If you want to use ioctls in your own kernel modules, it is best to receive an o
    -
    -

    System Calls

    -
    +
    +

    System Calls

    +

    So far, the only thing we've done was to use well defined kernel mechanisms to register /proc files and device handlers. This is fine if you want to do something the kernel programmers thought you'd want, such as write a device driver. But what if you want to do something unusual, to change the behavior of the system in some way? Then, you're mostly on your own.

    @@ -3151,7 +3172,7 @@ The init_module function replaces the appropriate location in sys_call

    -Now, if B is removed first, everything will be well — it will simply restore the system call to A_open, which calls the original. However, if A is removed and then B is removed, the system will crash. A's removal will restore the system call to the original, sys_open, cutting B out of the loop. Then, when B is removed, it will restore the system call to what it thinks is the original, A_open, which is no longer in memory. At first glance, it appears we could solve this particular problem by checking if the system call is equal to our open function and if so not changing it at all (so that B won't change the system call when it's removed), but that will cause an even worse problem. When A is removed, it sees that the system call was changed to B_open so that it is no longer pointing to A_open, so it won't restore it to sys_open before it is removed from memory. Unfortunately, B_open will still try to call A_open which is no longer there, so that even without removing B the system would crash. +Now, if B is removed first, everything will be well—it will simply restore the system call to A_open, which calls the original. However, if A is removed and then B is removed, the system will crash. A's removal will restore the system call to the original, sys_open, cutting B out of the loop. Then, when B is removed, it will restore the system call to what it thinks is the original, A_open, which is no longer in memory. At first glance, it appears we could solve this particular problem by checking if the system call is equal to our open function and if so not changing it at all (so that B won't change the system call when it's removed), but that will cause an even worse problem. When A is removed, it sees that the system call was changed to B_open so that it is no longer pointing to A_open, so it won't restore it to sys_open before it is removed from memory. Unfortunately, B_open will still try to call A_open which is no longer there, so that even without removing B the system would crash.

    @@ -3159,9 +3180,9 @@ Note that all the related problems make syscall stealing unfeasiable for product

    -
    -

    Example: syscall.c

    -
    +
    +

    Example: syscall.c

    +
    /*
  *  syscall.c
@@ -3326,9 +3347,9 @@ asmlinkage int our
    -
    -

    Blocking Processes

    -
    +
    +

    Blocking Processes

    +

    What do you do when somebody asks you for something you can't do right away? If you're a human being and you're bothered by a human being, the only thing you can say is: "Not right now, I'm busy. Go away!". But if you're a kernel module and you're bothered by a process, you have another possibility. You can put the process to sleep until you can service it. After all, processes are being put to sleep by the kernel and woken up all the time (that's the way multiple processes appear to run on the same time on a single CPU).

    @@ -3379,9 +3400,9 @@ hostname:~/lkmpg-examples/09-BlockingProcesses#
    -
    -

    Example: sleep.c

    -
    +
    +

    Example: sleep.c

    +
    /*
  *  sleep.c - create a /proc file, and if several processes try to open it at
@@ -3653,9 +3674,9 @@ DECLARE_WAIT_QUEUE_HEAD(WaitQ);
    -
    -

    Example: cat_noblock.c

    -
    +
    +

    Example: cat_noblock.c

    +
    /* cat_noblock.c - open a file and display its contents, but exit rather than
  * wait for input */
@@ -3727,12 +3748,13 @@ DECLARE_WAIT_QUEUE_HEAD(WaitQ);
    -
    -

    Replacing Printks

    -
    -
    -

    Replacing printk

    -
    +
    +

    Replacing Printks

    +
    +
    +
    +

    Replacing printk

    +

    In Section 1.2.1.2, I said that X and kernel module programming don't mix. That's true for developing kernel modules, but in actual use, you want to be able to send messages to whichever tty[15] the command to load the module came from.

    @@ -3742,9 +3764,9 @@ The way this is done is by using current, a pointer to the currently running tas

    -
    -

    Example: print_string.c

    -
    +
    +

    Example: print_string.c

    +
    /*
  *  print_string.c - Send output to the tty we're running on, regardless if it's
@@ -3860,9 +3882,9 @@ module_exit(print_string_exit);
    -
    -

    Flashing keyboard LEDs

    -
    +
    +

    Flashing keyboard LEDs

    +

    In certain conditions, you may desire a simpler and more direct way to communicate to the external world. Flashing keyboard LEDs can be such a solution: It is an immediate way to attract attention or to display a status condition. Keyboard LEDs are present on every hardware, they are always visible, they do not need any setup, and their use is rather simple and non-intrusive, compared to writing to a tty or a file.

    @@ -3872,9 +3894,9 @@ The following source code illustrates a minimal kernel module which, when loaded

    -
    -

    Example: kbleds.c

    -
    +
    +

    Example: kbleds.c

    +
    /*
  *  kbleds.c - Blink keyboard leds until the module is unloaded.
@@ -3993,9 +4015,9 @@ it does not show up in production code.
    -
    -

    Scheduling Tasks

    -
    +
    +

    Scheduling Tasks

    +

    Very often, we have "housekeeping" tasks which have to be done at a certain time, or every so often. If the task is to be done by a process, we do it by putting it in the crontab file. If the task is to be done by a kernel module, we have two possibilities. The first is to put a process in the crontab file which will wake up the module by a system call when necessary, for example by opening a file. This is terribly inefficient, however – we run a new process off of crontab, read a new executable to memory, and all this just to wake up a kernel module which is in memory anyway.

    @@ -4009,9 +4031,9 @@ There's one more point we need to remember here. When a module is removed by rmm

    -
    -

    Example: sched.c

    -
    +
    +

    Example: sched.c

    +
    /*
  *  sched.c - scheduale a function to be called on every timer interrupt.
@@ -4183,12 +4205,13 @@ MODULE_LICENSE("GPL");
    -
    -

    Interrupt Handlers

    -
    -
    -

    Interrupt Handlers

    -
    +
    +

    Interrupt Handlers

    +
    +
    +
    +

    Interrupt Handlers

    +

    Except for the last chapter, everything we did in the kernel so far we've done as a response to a process asking for it, either by dealing with a special file, sending an ioctl(), or issuing a system call. But the job of the kernel isn't just to respond to process requests. Another job, which is every bit as important, is to speak to the hardware connected to the machine.

    @@ -4215,9 +4238,9 @@ Then, from within the interrupt handler, we communicate with the hardware and th
    -
    -

    Keyboards on the Intel Architecture

    -
    +
    +

    Keyboards on the Intel Architecture

    +

    The rest of this chapter is completely Intel specific. If you're not running on an Intel platform, it will not work. Don't even try to compile the code here. Move right along, nothing to see.

    @@ -4232,9 +4255,9 @@ used (the first seven bits of the scan code) and whether it has been pressed (if

    -
    -

    Example: intrpt.c

    -
    +
    +

    Example: intrpt.c

    +
    /*
  *  intrpt.c - An interrupt handler.
@@ -4356,35 +4379,35 @@ MODULE_LICENSE("GPL");
    -
    -

    Common Pitfalls

    -
    +
    +

    Common Pitfalls

    +

    Before I send you on your way to go out into the world and write kernel modules, there are a few things I need to warn you about. If I fail to warn you and something bad happens, please report the problem to me for a full refund of the amount I was paid for your copy of the book.

    -
    -

    Using standard libraries

    -
    +
    +

    Using standard libraries

    +

    You can't do that. In a kernel module you can only use kernel functions, which are the functions you can see in /proc/kallsyms.

    -
    -

    Disabling interrupts

    -
    +
    +

    Disabling interrupts

    +

    You might need to do this for a short time and that is OK, but if you don't enable them afterwards, your system will be stuck and you'll have to power it off.

    -
    -

    Sticking your head inside a large carnivore

    -
    +
    +

    Sticking your head inside a large carnivore

    +

    I probably don't have to warn you about this, but I figured I will anyway, just in case.

    @@ -4392,18 +4415,18 @@ I probably don't have to warn you about this, but I figured I will anyway, just
    -
    -

    Appendix A. Changes: 2.4 To 2.6

    -
    +
    +

    Appendix A. Changes: 2.4 To 2.6

    +

    I don't know the entire kernel well enough to document all of the changes. Some hints for porting can be found by comparing this version of the LKMPG with it's counterpart for kernel 2.4. Apart from that, anybody who needs to port drivers from 2.4 to 2.6 kernels might want to visit http://lwn.net/ Articles/driver-porting. If you still can't find an example that exactly meets your needs there, find a driver that's similar to your driver and present in both kernel versions. File comparison tools like xxdiff or meld can be a great help then. Also check if your driver is covered by docs in linux/Documentation/ . Before starting with porting and in case you're stuck it's a good idea to find an appropiate mailinglist and ask people there for pointers.

    -
    -

    Appendix B. Where To Go From Here?

    -
    +
    +

    Appendix B. Where To Go From Here?

    +

    I could easily have squeezed a few more chapters into this book. I could have added a chapter about creating new file systems, or about adding new protocol stacks (as if there's a need for that – you'd have to dig underground to find a protocol stack not supported by Linux). I could have added explanations of the kernel mechanisms we haven't touched upon, such as bootstrapping or the disk interface.

    @@ -4426,9 +4449,9 @@ If you'd like to contribute to this guide, please contact one the maintainers fo
    -
    -

    Notes

    -
    +
    +

    Notes

    +

    [1] In earlier versions of linux, this was known as kerneld. [2] If such a file exists. Note that the acual behavoir might be @@ -4497,9 +4520,9 @@ If you'd like to contribute to this guide, please contact one the maintainers fo

    -
    -

    Edits

    -
    +
    +

    Edits

    +

    linux/fs.h updated file_operations structure (see http://lwn.net/Articles/119652/) unregister_chrdev returns void @@ -4532,7 +4555,7 @@ Fixed sched.c

    -Back to top | E-mail me +Back to top | E-mail me
    diff --git a/3.16/LKMPG-3.16.org b/3.16/LKMPG-3.16.org index 2160a61..f4f4d18 100644 --- a/3.16/LKMPG-3.16.org +++ b/3.16/LKMPG-3.16.org @@ -5,7 +5,7 @@ #+OPTIONS: ^:nil * Introduction -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][http://opensource.org/licenses/osl.php]]. +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 3.0. 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. diff --git a/3.16/img/seq_file.png b/3.16/img/seq_file.png index 4d15a3a..9dbb479 100644 Binary files a/3.16/img/seq_file.png and b/3.16/img/seq_file.png differ diff --git a/3.8/LKMPG-3.8.html b/3.8/LKMPG-3.8.html index 6ab074c..6a1d167 100644 --- a/3.8/LKMPG-3.8.html +++ b/3.8/LKMPG-3.8.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + The Linux Kernel Module Programming Guide @@ -264,178 +264,178 @@ for the JavaScript code in this tag.

    Table of Contents

    -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. +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 3.0.

    @@ -486,12 +486,13 @@ The source code and discussions should apply to most architectures, but I can't The following people have contributed corrections or good suggestions: Ignacio Martin, David Porter, Daniele Paolo Scarpazza, Dimo Velev, Francois Audeon, Horst Schirmeier, Bob Mottram and Roman Lakeev.

    -
    -

    Introduction

    -
    -
    -

    What Is A Kernel Module?

    -
    +
    +

    Introduction

    +
    +
    +
    +

    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.

    @@ -502,9 +503,9 @@ What exactly is a kernel module? Modules are pieces of code that can be loaded a
    -
    -

    How Do Modules Get Into The Kernel?

    -
    +
    +

    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.

    @@ -573,9 +574,9 @@ Now you know how modules get into the kernel. There's a bit more to the story if

    -
    -

    Before We Begin

    -
    +
    +

    Before We Begin

    +

    Before we delve into code, there are a few issues we need to cover. Everyone's system is different and everyone has their own groove. Getting @@ -585,7 +586,9 @@ for the first time, it will be smooth sailing thereafter.

    -
    • Modversioning
      +
        +
      • Modversioning
        +

        A module compiled for one kernel won't load if you boot a different kernel unless you enable CONFIG_MODVERSIONS in the kernel. We won't go into module @@ -595,9 +598,11 @@ modversioning turned on. However, most stock Linux distro kernels come with it turned on. If you're having trouble loading the modules because of versioning errors, compile a kernel with modversioning turned off.

        -
        • +
      +
      • -
    • Using X
      +
    • Using X
      +

      It is highly recommended that you type in, compile and load all the examples this guide discusses. It's also highly recommended you do this from a @@ -612,9 +617,11 @@ warnings will be logged, but only to your log files. You won't see it unless you look through your log files. To have immediate access to this information, do all your work from the console.

      -
      • +
    + -
  • Compiling Issues and Kernel Version
    +
  • Compiling Issues and Kernel Version
    +

    Very often, Linux distros will distribute kernel source that has been patched in various non-standard ways, which may cause trouble. @@ -639,17 +646,20 @@ look for the kernel headers in their default location rather than where you installed the new copy of the kernel (usually in usr/src. This can be fixed by using gcc's -I switch.

    -
    • +
    + +
    -
    -

    Hello World

    -
    -
    -

    Hello, World (part 1): The Simplest Module

    -
    +
    +

    Hello World

    +
    +
    +
    +

    Hello, World (part 1): The Simplest Module

    +

    When the first caveman programmer chiseled the first program on the walls of the first cave computer, it was a program to paint the string `Hello, world' in Antelope pictures. Roman programming textbooks began with the `Salut, Mundi' program. I don't know what happens to people who break with this tradition, but I think it's safer not to find out. We'll start with a series of hello world programs that demonstrate the different aspects of the basics of writing a kernel module.

    @@ -659,9 +669,9 @@ Here's the simplest module possible. Don't compile it yet; we'll cover module co

    -
    -

    Example: hello-1.c

    -
    +
    +

    Example: hello-1.c

    +

    #+BEGIN_SRC: c /* @@ -717,9 +727,9 @@ Lastly, every kernel module needs to include linux/module.h. We needed to includ

    -
    -

    Introducing printk()

    -
    +
    +

    Introducing printk()

    +

    Despite what you might think, printk() was not meant to communicate information to the user, even though we used it for exactly this purpose in hello-1! It happens to be a logging mechanism for the kernel, and is used to log information or give warnings. Therefore, each printk() statement comes with a priority, which is the <1> and KERN_ALERT you see. There are 8 priorities and the kernel has macros for them, so you don't have to use cryptic numbers, and you can view them (and their meanings) in linux/kernel.h. If you don't specify a priority level, the default priority, DEFAULT_MESSAGE_LOGLEVEL, will be used. @@ -735,9 +745,9 @@ If the priority is less than int console_loglevel, the message is printed on you

    -
    -

    Compiling Kernel Modules

    -
    +
    +

    Compiling Kernel Modules

    +

    Kernel modules need to be compiled a bit differently from regular userspace apps. Former kernel versions required us to care much about these settings, which are usually stored in Makefiles. Although hierarchically organized, many redundant settings accumulated in sublevel Makefiles and made them large and rather difficult to maintain. Fortunately, there is a new way of doing these things, called kbuild, and the build process for external loadable modules is now fully integrated into the standard kernel build mechanism. To learn more on how to compile modules which are not part of the official kernel (such as all the examples you'll find in this guide), see file linux/ Documentation/kbuild/modules.txt.

    @@ -747,9 +757,9 @@ So, let's look at a simple Makefile for compiling a module named hello-1.c:

    -
    -

    Example: Makefile for a basic kernel module

    -
    +
    +

    Example: Makefile for a basic kernel module

    +
    obj-m += hello-1.o
 
@@ -846,17 +856,17 @@ Here's another exercise for the reader. See that comment above the return statem
    -
    -

    Hello World (part 2)

    -
    +
    +

    Hello World (part 2)

    +

    As of Linux 2.4, you can rename the init and cleanup functions of your modules; they no longer have to be called init_module() and cleanup_module() respectively. This is done with the module_init() and module_exit() macros. These macros are defined in linux/init.h. The only caveat is that your init and cleanup functions must be defined before calling the macros, otherwise you'll get compilation errors. Here's an example of this technique:

    -
    -

    Example: hello-2.c

    -
    +
    +

    Example: hello-2.c

    +

    #+BEGIN_SRC: c /* @@ -899,9 +909,9 @@ So now we have two real kernel modules under our belt. Adding another module is

    -
    -

    Example: Makefile for both our modules

    -
    +
    +

    Example: Makefile for both our modules

    +
    obj-m += hello-1.o
 obj-m += hello-2.o
@@ -922,9 +932,9 @@ you can see, some things get hardwired into the kernel (obj-y) but where are all
    -
    -

    Hello World (part 3): The __init and __exit Macros

    -
    +
    +

    Hello World (part 3): The __init and __exit Macros

    +

    This demonstrates a feature of kernel 2.2 and later. Notice the change in the definitions of the init and cleanup functions. The __init macro causes the init function to be discarded and its memory freed once the init function finishes for built-in drivers, but not loadable modules. If you think about when the init function is invoked, this makes perfect sense.

    @@ -942,9 +952,9 @@ These macros are defined in linux/init.h and serve to free up kernel memory. Whe

    -
    -

    Example: hello-3.c

    -
    +
    +

    Example: hello-3.c

    +

    #+BEGIN_SRC: c /* @@ -987,9 +997,9 @@ module_exit(hello_3_exit);

    -
    -

    Hello World (part 4): Licensing and Module Documentation

    -
    +
    +

    Hello World (part 4): Licensing and Module Documentation

    +

    If you're running kernel 2.4 or later, you might have noticed something like this when you loaded proprietary modules:

    @@ -1069,9 +1079,9 @@ Users of traditional Unix editors, like emacs or vi will also find tag files use
    -
    -

    Example: hello-4.c

    -
    +
    +

    Example: hello-4.c

    +

    #+BEGIN_SRC: c /* @@ -1158,9 +1168,9 @@ MODULE_SUPPORTED_DEVICE("testdevice");

    -
    -

    Passing Command Line Arguments to a Module

    -
    +
    +

    Passing Command Line Arguments to a Module

    +

    Modules can take command line arguments, but not with the argc/argv you might be used to.

    @@ -1207,9 +1217,9 @@ Lastly, there's a macro function, MODULE_PARM_DESC(), that is used to document a
    -
    -

    Example: hello-5.c

    -
    +
    +

    Example: hello-5.c

    +

    #+BEGIN_SRC: c /* @@ -1358,9 +1368,9 @@ hello-5.o: invalid argument syntax for mylong: 'h'

    -
    -

    Modules Spanning Multiple Files

    -
    +
    +

    Modules Spanning Multiple Files

    +

    Sometimes it makes sense to divide a kernel module between several source files.

    @@ -1370,9 +1380,9 @@ Here's an example of such a kernel module.

    -
    -

    Example: start.c

    -
    +
    +

    Example: start.c

    +

    #+BEGIN_SRC: c /* @@ -1405,9 +1415,9 @@ The next file:

    -
    -

    Example: stop.c

    -
    +
    +

    Example: stop.c

    +

    #+BEGIN_SRC: c /* @@ -1439,9 +1449,9 @@ And finally, the makefile:

    -
    -

    Example: Makefile

    -
    +
    +

    Example: Makefile

    +

    #+BEGIN_SRC: makefile obj-m += hello-1.o @@ -1474,9 +1484,9 @@ make what object files are part of that module.

    -
    -

    Building modules for a precompiled kernel

    -
    +
    +

    Building modules for a precompiled kernel

    +

    Obviously, we strongly suggest you to recompile your kernel, so that you can enable a number of useful debugging features, such as forced module unloading (MODULE_FORCE_UNLOAD): when this option is enabled, you can force the kernel to unload a module even when it believes it is unsafe, via a rmmod -f module command. This option can save you a lot of time and a number of reboots during the development of a module.

    @@ -1573,12 +1583,13 @@ If you do not desire to actually compile the kernel, you can interrupt the build
    -
    -

    Preliminaries

    -
    -
    -

    How modules begin and end

    -
    +
    +

    Preliminaries

    +
    +
    +
    +

    How modules begin and end

    +

    A program usually begins with a main() function, executes a bunch of instructions and terminates upon completion of those instructions. Kernel modules work a bit differently. A module always begin with either the init_module or the function you specify with module_init call. This is the entry function for modules; it tells the kernel what functionality the module provides and sets up the kernel to run the module's functions when they're needed. Once it does this, entry function returns and the module does nothing until the kernel wants to do something with the code that the module provides.

    @@ -1593,9 +1604,9 @@ Every module must have an entry function and an exit function. Since there's mor
    -
    -

    Functions available to modules

    -
    +
    +

    Functions available to modules

    +

    Programmers use functions they don't define all the time. A prime example of this is printf(). You use these library functions which are provided by the standard C library, libc. The definitions for these functions don't actually enter your program until the linking stage, which insures that the code (for printf() for example) is available, and fixes the call instruction to point to that code.

    @@ -1605,7 +1616,7 @@ Kernel modules are different here, too. In the hello world example, you might ha

    -One point to keep in mind is the difference between library functions and system calls. Library functions are higher level, run completely in user space and provide a more convenient interface for the programmer to the functions that do the real work—system calls. System calls run in kernel mode on the user's behalf and are provided by the kernel itself. The library function printf() may look like a very general printing function, but all it really does is format the data into strings and write the string data using the low-level system call write(), which then sends the data to standard output. +One point to keep in mind is the difference between library functions and system calls. Library functions are higher level, run completely in user space and provide a more convenient interface for the programmer to the functions that do the real work — system calls. System calls run in kernel mode on the user's behalf and are provided by the kernel itself. The library function printf() may look like a very general printing function, but all it really does is format the data into strings and write the string data using the low-level system call write(), which then sends the data to standard output.

    @@ -1615,6 +1626,9 @@ Would you like to see what system calls are made by printf()? It's easy! Compile

    #+BEGIN_SRC: c #include <stdio.h> +

    + +

    int main(void) { printf("hello"); @@ -1624,7 +1638,7 @@ int main(void)

    -with gcc -Wall -o hello hello.c. Run the exectable with strace ./hello. Are you impressed? Every line you see corresponds to a system call. strace[4] is a handy program that gives you details about what system calls a program is making, including which call is made, what its arguments are what it returns. It's an invaluable tool for figuring out things like what files a program is trying to access. Towards the end, you'll see a line which looks like write (1, "hello", 5hello). There it is. The face behind the printf() mask. You may not be familiar with write, since most people use library functions for file I/O (like fopen, fputs, fclose). If that's the case, try looking at man 2 write. The 2nd man section is devoted to system calls (like kill() and read (). The 3rd man section is devoted to library calls, which you would probably be more familiar with (like cosh() and random()). +with gcc -Wall -o hello hello.c. Run the exectable with strace ./hello. Are you impressed? Every line you see corresponds to a system call. strace[4] is a handy program that gives you details about what system calls a program is making, including which call is made, what its arguments are what it returns. It's an invaluable tool for figuring out things like what files a program is trying to access. Towards the end, you'll see a line which looks like write (1, "hello", 5hello). There it is. The face behind the printf() mask. You may not be familiar with write, since most people use library functions for file I/O (like fopen, fputs, fclose). If that's the case, try looking at man 2 write. The 2nd man section is devoted to system calls (like kill() and read()). The 3rd man section is devoted to library calls, which you would probably be more familiar with (like cosh() and random()).

    @@ -1633,9 +1647,9 @@ You can even write modules to replace the kernel's system calls, which we'll do

    -
    -

    User Space vs Kernel Space

    -
    +
    +

    User Space vs Kernel Space

    +

    A kernel is all about access to resources, whether the resource in question happens to be a video card, a hard drive or even memory. Programs often compete for the same resource. As I just saved this document, updatedb started updating the locate database. My vim session and updatedb are both using the hard drive concurrently. The kernel needs to keep things orderly, and not give users access to resources whenever they feel like it. To this end, a CPU can run in different modes. Each mode gives a different level of freedom to do what you want on the system. The Intel 80386 architecture has 4 of these modes, which are called rings. Unix uses only two rings; the highest ring (ring 0, also known as `supervisor mode' where everything is allowed to happen) and the lowest ring, which is called `user mode'.

    @@ -1646,9 +1660,9 @@ Recall the discussion about library functions vs system calls. Typically, you us
    -
    -

    Name Space

    -
    +
    +

    Name Space

    +

    When you write a small C program, you use variables which are convenient and make sense to the reader. If, on the other hand, you're writing routines which will be part of a bigger problem, any global variables you have are part of a community of other peoples' global variables; some of the variable names can clash. When a program has lots of global variables which aren't meaningful enough to be distinguished, you get namespace pollution. In large projects, effort must be made to remember reserved names, and to find ways to develop a scheme for naming unique variable names and symbols.

    @@ -1663,11 +1677,11 @@ The file /proc/kallsyms holds all the symbols that the kernel knows about
    -
    -

    Code space

    -
    +
    +

    Code space

    +

    -Memory management is a very complicated subject—the majority of O'Reilly's `Understanding The Linux Kernel' is just on memory management! We're not setting out to be experts on memory managements, but we do need to know a couple of facts to even begin worrying about writing real modules. +Memory management is a very complicated subject — the majority of O'Reilly's `Understanding The Linux Kernel' is just on memory management! We're not setting out to be experts on memory managements, but we do need to know a couple of facts to even begin worrying about writing real modules.

    @@ -1684,15 +1698,17 @@ By the way, I would like to point out that the above discussion is true for any

    -
    -

    Device Drivers

    -
    +
    +

    Device Drivers

    +

    One class of module is the device driver, which provides functionality for hardware like a TV card or a serial port. On unix, each piece of hardware is represented by a file located in /dev named a device file which provides the means to communicate with the hardware. The device driver provides the communication on behalf of a user program. So the es1370.o sound card device driver might connect the /dev/sound device file to the Ensoniq IS1370 sound card. A userspace program like mp3blaster can use /dev/sound without ever knowing what kind of sound card is installed.

    -
    • Major and Minor Numbers
      +
        +
      • Major and Minor Numbers
        +

        Let's look at some device files. Here are device files which represent the first three partitions on the primary master IDE hard drive:

        @@ -1756,16 +1772,19 @@ brw-rw-— 1 root floppy 2, 44 Jul 5 2000 /dev/fd0u1680

        By now you can look at these two device files and know instantly that they are block devices and are handled by same driver (block major 2). You might even be aware that these both represent your floppy drive, even if you only have one floppy drive. Why two files? One represents the floppy drive with 1.44 MB of storage. The other is the same floppy drive with 1.68 MB of storage, and corresponds to what some people call a `superformatted' disk. One that holds more data than a standard formatted floppy. So here's a case where two device files with different minor number actually represent the same piece of physical hardware. So just be aware that the word `hardware' in our discussion can mean something very abstract.

        -
      +
      +
      • +
    -
    -

    Character Device drivers

    -
    -
    -

    The file_operations Structure

    -
    +
    +

    Character Device drivers

    +
    +
    +
    +

    The file_operations Structure

    +

    The file_operations structure is defined in linux/fs.h, and holds pointers to functions defined by the driver that perform various operations on the device. Each field of the structure corresponds to the address of some function defined by the driver to handle a requested operation.

    @@ -1853,9 +1872,9 @@ An instance of struct file_operations containing pointers to functions that are
    -
    -

    The file structure

    -
    +
    +

    The file structure

    +

    Each device is represented in the kernel by a file structure, which is defined in linux/fs.h. Be aware that a file is a kernel level structure and never appears in a user space program. It's not the same thing as a FILE, which is defined by glibc and would never appear in a kernel space function. Also, its name is a bit misleading; it represents an abstract open `file', not a file on a disk, which is represented by a structure named inode.

    @@ -1870,9 +1889,9 @@ Go ahead and look at the definition of file. Most of the entries you see, like s
    -
    -

    Registering A Device

    -
    +
    +

    Registering A Device

    +

    As discussed earlier, char devices are accessed through device files, usually located in /dev[7]. The major number tells you which driver handles which device file. The minor number is used only by the driver itself to differentiate which device it's operating on, just in case the driver handles more than one device.

    @@ -1901,9 +1920,9 @@ If you pass a major number of 0 to register_chrdev, the return value will be the
    -
    -

    Unregistering A Device

    -
    +
    +

    Unregistering A Device

    +

    We can't allow the kernel module to be rmmod'ed whenever root feels like it. If the device file is opened by a process and then we remove the kernel module, using the file would cause a call to the memory location where the appropriate function (read/write) used to be. If we're lucky, no other code was loaded there, and we'll get an ugly error message. If we're unlucky, another kernel module was loaded into the same location, which means a jump into the middle of another function within the kernel. The results of this would be impossible to predict, but they can't be very positive.

    @@ -1924,9 +1943,9 @@ It's important to keep the counter accurate; if you ever do lose track of the co
    -
    -

    chardev.c

    -
    +
    +

    chardev.c

    +

    The next code sample creates a char driver named chardev. You can cat its device file.

    @@ -1942,9 +1961,9 @@ cat /proc/devices

    -
    -

    Example: chardev.c

    -
    +
    +

    Example: chardev.c

    +

    #+BEGIN_SRC: c /* @@ -2243,9 +2262,9 @@ device_write(struct file *filp, const char *buff, size_t len, loff_t * off)

    -
    -

    Writing Modules for Multiple Kernel Versions

    -
    +
    +

    Writing Modules for Multiple Kernel Versions

    +

    The system calls, which are the major interface the kernel shows to the processes, generally stay the same across versions. A new system call may be added, but usually the old ones will behave exactly like they used to. This is necessary for backward compatibility – a new kernel version is not supposed to break regular processes. In most cases, the device files will also remain the same. On the other hand, the internal interfaces within the kernel can and do change between versions.

    @@ -2269,9 +2288,9 @@ Update: What we've said above was true for kernels up to and including 2.6.10. Y
    -
    -

    The /proc File System

    -
    +
    +

    The /proc File System

    +

    In Linux, there is an additional mechanism for the kernel and kernel modules to send information to processes — the /proc file system. Originally designed to allow easy access to information about processes (hence the name), it is now used by every bit of the kernel which has something interesting to report, such as /proc/modules which provides the list of modules and /proc/meminfo which stats memory usage statistics.

    @@ -2308,9 +2327,9 @@ HelloWorld!

    -
    -

    Example: procfs1.c

    -
    +
    +

    Example: procfs1.c

    +

    #+BEGIN_SRC: c /* @@ -2474,9 +2493,9 @@ void cleanup_module()

    -
    -

    Read and Write a /proc File

    -
    +
    +

    Read and Write a /proc File

    +

    We have seen a very simple example for a /proc file where we only read the file /proc/helloworld. It's also possible to write in a /proc file. It works the same way as read, a function is called when the /proc file is written. But there is a little difference with read, data comes from user, so you have to import data from user space to kernel space (with copy_from_user or get_user)

    @@ -2490,9 +2509,9 @@ The only memory segment accessible to a process is its own, so when writing regu

    -
    -

    Example: procfs2.c

    -
    +
    +

    Example: procfs2.c

    +

    #+BEGIN_SRC: c /** @@ -2680,9 +2699,9 @@ void cleanup_module()

    -
    -

    Manage /proc file with standard filesystem

    -
    +
    +

    Manage /proc file with standard filesystem

    +

    We have seen how to read and write a /proc file with the /proc interface. But it's also possible to manage /proc file with inodes. The main interest is to use advanced function, like permissions.

    @@ -2700,9 +2719,9 @@ It's important to note that the standard roles of read and write are reversed in

    -
    -

    Example: procfs3.c

    -
    +
    +

    Example: procfs3.c

    +

    #+BEGIN_SRC: c /* @@ -3029,9 +3048,9 @@ Still hungry for procfs examples? Well, first of all keep in mind, there are rum

    -
    -

    Manage /proc file with seq_file

    -
    +
    +

    Manage /proc file with seq_file

    +

    As we have seen, writing a /proc file may be quite "complex". So to help people writting /proc file, there is an API named seq_file that helps @@ -3049,9 +3068,9 @@ BE CARREFUL: when a sequence is finished, another one starts. That means that at

    -
    -

    Figure: How seq_file works

    -
    +
    +

    Figure: How seq_file works

    +
    @@ -3072,9 +3091,9 @@ BE CARREFUL: when a sequence is finished, another one starts. That means that at -
    -

    Example: procfs4.c

    -
    +
    +

    Example: procfs4.c

    +

    #+BEGIN_SRC: c /** @@ -3301,12 +3320,13 @@ You can also read the code of fs/seq_file.c in the linux kernel.

    -
    -

    Using /proc For Input

    -
    -
    -

    TODO : Write a chapter about sysfs

    -
    +
    +

    Using /proc For Input

    +
    +
    +
    +

    TODO : Write a chapter about sysfs

    +

    This is just a placeholder for now. Finally I'd like to see a (yet to be written) chapter about sysfs instead here. If you are familiar with sysfs and would like to take part in writing this chapter, feel free to contact us (the LKMPG maintainers) for further details.

    @@ -3314,9 +3334,9 @@ This is just a placeholder for now. Finally I'd like to see a (yet to be written
    -
    -

    Talking To Device Files

    -
    +
    +

    Talking To Device Files

    +

    Device files are supposed to represent physical devices. Most physical devices are used for output as well as input, so there has to be some mechanism for device drivers in the kernel to get the output to send to the device from processes. This is done by opening the device file for output and writing to it, just like writing to a file. In the following example, this is implemented by device_write.

    @@ -3338,9 +3358,9 @@ If you want to use ioctls in your own kernel modules, it is best to receive an o

    -
    -

    Example: chardev.c

    -
    +
    +

    Example: chardev.c

    +

    #+BEGIN_SRC: c /* @@ -3818,9 +3838,9 @@ void cleanup_module()

    -
    -

    Example: chardev.h

    -
    +
    +

    Example: chardev.h

    +

    #+BEGIN_SRC: c /* @@ -3867,11 +3887,11 @@ void cleanup_module()

    */ -#define IOCTL_SET_MSG _IOR(MAJOR_NUM, 0, char ) +#define IOCTL_SET_MSG _IOW(MAJOR_NUM, 0, char ) /

      -
    • _IOR means that we're creating an ioctl command
      • +
    • _IOW means that we're creating an ioctl command
    • number for passing information from a user process
    • to the kernel module.
    • @@ -3950,9 +3970,9 @@ void cleanup_module()
    -
    -

    Example: ioctl.c

    -
    +
    +

    Example: ioctl.c

    +

    #+BEGIN_SRC: c /* @@ -4120,9 +4140,9 @@ ioctl_set_msg(file_desc, msg);

    -
    -

    System Calls

    -
    +
    +

    System Calls

    +

    So far, the only thing we've done was to use well defined kernel mechanisms to register /proc files and device handlers. This is fine if you want to do something the kernel programmers thought you'd want, such as write a device driver. But what if you want to do something unusual, to change the behavior of the system in some way? Then, you're mostly on your own.

    @@ -4160,7 +4180,7 @@ The init_module function replaces the appropriate location in sys_call_table and

    -Now, if B is removed first, everything will be well—it will simply restore the system call to A_open, which calls the original. However, if A is removed and then B is removed, the system will crash. A's removal will restore the system call to the original, sys_open, cutting B out of the loop. Then, when B is removed, it will restore the system call to what it thinks is the original, A_open, which is no longer in memory. At first glance, it appears we could solve this particular problem by checking if the system call is equal to our open function and if so not changing it at all (so that B won't change the system call when it's removed), but that will cause an even worse problem. When A is removed, it sees that the system call was changed to B_open so that it is no longer pointing to A_open, so it won't restore it to sys_open before it is removed from memory. Unfortunately, B_open will still try to call A_open which is no longer there, so that even without removing B the system would crash. +Now, if B is removed first, everything will be well — it will simply restore the system call to A_open, which calls the original. However, if A is removed and then B is removed, the system will crash. A's removal will restore the system call to the original, sys_open, cutting B out of the loop. Then, when B is removed, it will restore the system call to what it thinks is the original, A_open, which is no longer in memory. At first glance, it appears we could solve this particular problem by checking if the system call is equal to our open function and if so not changing it at all (so that B won't change the system call when it's removed), but that will cause an even worse problem. When A is removed, it sees that the system call was changed to B_open so that it is no longer pointing to A_open, so it won't restore it to sys_open before it is removed from memory. Unfortunately, B_open will still try to call A_open which is no longer there, so that even without removing B the system would crash.

    @@ -4168,9 +4188,9 @@ Note that all the related problems make syscall stealing unfeasiable for product

    -
    -

    Example: syscall.c

    -
    +
    +

    Example: syscall.c

    +

    #+BEGIN_SRC: c /* @@ -4446,9 +4466,9 @@ if (sys_call_table[__NR_open] != our_sys_open) {

    -
    -

    Blocking Processes

    -
    +
    +

    Blocking Processes

    +

    What do you do when somebody asks you for something you can't do right away? If you're a human being and you're bothered by a human being, the only thing you can say is: "Not right now, I'm busy. Go away!". But if you're a kernel module and you're bothered by a process, you have another possibility. You can put the process to sleep until you can service it. After all, processes are being put to sleep by the kernel and woken up all the time (that's the way multiple processes appear to run on the same time on a single CPU).

    @@ -4500,9 +4520,9 @@ hostname:~/lkmpg-examples/09-BlockingProcesses#

    -
    -

    Example: sleep.c

    -
    +
    +

    Example: sleep.c

    +

    #+BEGIN_SRC: c /* @@ -5044,9 +5064,9 @@ void cleanup_module()

    -
    -

    Example: cat_noblock.c

    -
    +
    +

    Example: cat_noblock.c

    +

    #+BEGIN_SRC: c /* cat_noblock.c - open a file and display its contents, but exit rather than @@ -5149,12 +5169,13 @@ if (bytes > 0) {

    -
    -

    Replacing Printks

    -
    -
    -

    Replacing printk

    -
    +
    +

    Replacing Printks

    +
    +
    +
    +

    Replacing printk

    +

    In Section 1.2.1.2, I said that X and kernel module programming don't mix. That's true for developing kernel modules, but in actual use, you want to be able to send messages to whichever tty[15] the command to load the module came from.

    @@ -5164,9 +5185,9 @@ The way this is done is by using current, a pointer to the currently running tas

    -
    -

    Example: print_string.c

    -
    +
    +

    Example: print_string.c

    +

    #+BEGIN_SRC: c /* @@ -5334,9 +5355,9 @@ module_exit(print_string_exit);

    -
    -

    Flashing keyboard LEDs

    -
    +
    +

    Flashing keyboard LEDs

    +

    In certain conditions, you may desire a simpler and more direct way to communicate to the external world. Flashing keyboard LEDs can be such a solution: It is an immediate way to attract attention or to display a status condition. Keyboard LEDs are present on every hardware, they are always visible, they do not need any setup, and their use is rather simple and non-intrusive, compared to writing to a tty or a file.

    @@ -5346,9 +5367,9 @@ The following source code illustrates a minimal kernel module which, when loaded

    -
    -

    Example: kbleds.c

    -
    +
    +

    Example: kbleds.c

    +

    #+BEGIN_SRC: c /* @@ -5513,9 +5534,9 @@ it does not show up in production code.

    -
    -

    Scheduling Tasks

    -
    +
    +

    Scheduling Tasks

    +

    Very often, we have "housekeeping" tasks which have to be done at a certain time, or every so often. If the task is to be done by a process, we do it by putting it in the crontab file. If the task is to be done by a kernel module, we have two possibilities. The first is to put a process in the crontab file which will wake up the module by a system call when necessary, for example by opening a file. This is terribly inefficient, however – we run a new process off of crontab, read a new executable to memory, and all this just to wake up a kernel module which is in memory anyway.

    @@ -5529,9 +5550,9 @@ There's one more point we need to remember here. When a module is removed by rmm

    -
    -

    Example: sched.c

    -
    +
    +

    Example: sched.c

    +

    #+BEGIN_SRC: c /* @@ -5846,12 +5867,13 @@ MODULE_LICENSE("GPL");

    -
    -

    Interrupt Handlers

    -
    -
    -

    Interrupt Handlers

    -
    +
    +

    Interrupt Handlers

    +
    +
    +
    +

    Interrupt Handlers

    +

    Except for the last chapter, everything we did in the kernel so far we've done as a response to a process asking for it, either by dealing with a special file, sending an ioctl(), or issuing a system call. But the job of the kernel isn't just to respond to process requests. Another job, which is every bit as important, is to speak to the hardware connected to the machine.

    @@ -5878,9 +5900,9 @@ Then, from within the interrupt handler, we communicate with the hardware and th
    -
    -

    Keyboards on the Intel Architecture

    -
    +
    +

    Keyboards on the Intel Architecture

    +

    The rest of this chapter is completely Intel specific. If you're not running on an Intel platform, it will not work. Don't even try to compile the code here.

    @@ -5896,9 +5918,9 @@ used (the first seven bits of the scan code) and whether it has been pressed (if

    -
    -

    Example: intrpt.c

    -
    +
    +

    Example: intrpt.c

    +

    #+BEGIN_SRC: c /* @@ -6104,9 +6126,9 @@ MODULE_LICENSE("GPL");

    -
    -

    Symmetric Multi Processing

    -
    +
    +

    Symmetric Multi Processing

    +

    One of the easiest and cheapest ways to improve hardware performance is to put more than one CPU on the board. This can be done either making the different CPU's take on different jobs (asymmetrical multi-processing) or by making them all run in parallel, doing the same job (symmetrical multi-processing, a.k.a. SMP). Doing asymmetrical multi-processing effectively requires specialized knowledge about the tasks the computer should do, which is unavailable in a general purpose operating system such as Linux. On the other hand, symmetrical multi-processing is relatively easy to implement.

    @@ -6129,35 +6151,35 @@ In version 2.2.x, several CPU's can be in the kernel at the same time. This is s
    -
    -

    Common Pitfalls

    -
    +
    +

    Common Pitfalls

    +

    Before I send you on your way to go out into the world and write kernel modules, there are a few things I need to warn you about. If I fail to warn you and something bad happens, please report the problem to me for a full refund of the amount I was paid for your copy of the book.

    -
    -

    Using standard libraries

    -
    +
    +

    Using standard libraries

    +

    You can't do that. In a kernel module you can only use kernel functions, which are the functions you can see in /proc/kallsyms.

    -
    -

    Disabling interrupts

    -
    +
    +

    Disabling interrupts

    +

    You might need to do this for a short time and that is OK, but if you don't enable them afterwards, your system will be stuck and you'll have to power it off.

    -
    -

    Sticking your head inside a large carnivore

    -
    +
    +

    Sticking your head inside a large carnivore

    +

    I probably don't have to warn you about this, but I figured I will anyway, just in case.

    @@ -6165,18 +6187,18 @@ I probably don't have to warn you about this, but I figured I will anyway, just
    -
    -

    Appendix A. Changes: 2.4 To 2.6

    -
    +
    +

    Appendix A. Changes: 2.4 To 2.6

    +

    I don't know the entire kernel well enough to document all of the changes. Some hints for porting can be found by comparing this version of the LKMPG with it's counterpart for kernel 2.4. Apart from that, anybody who needs to port drivers from 2.4 to 2.6 kernels might want to visit http://lwn.net/ Articles/driver-porting. If you still can't find an example that exactly meets your needs there, find a driver that's similar to your driver and present in both kernel versions. File comparison tools like xxdiff or meld can be a great help then. Also check if your driver is covered by docs in linux/Documentation/ . Before starting with porting and in case you're stuck it's a good idea to find an appropiate mailinglist and ask people there for pointers.

    -
    -

    Appendix B. Where To Go From Here?

    -
    +
    +

    Appendix B. Where To Go From Here?

    +

    I could easily have squeezed a few more chapters into this book. I could have added a chapter about creating new file systems, or about adding new protocol stacks (as if there's a need for that – you'd have to dig underground to find a protocol stack not supported by Linux). I could have added explanations of the kernel mechanisms we haven't touched upon, such as bootstrapping or the disk interface.

    @@ -6199,9 +6221,9 @@ If you'd like to contribute to this guide, please contact one the maintainers fo
    -
    -

    Notes

    -
    +
    +

    Notes

    +

    [1] In earlier versions of linux, this was known as kerneld. [2] If such a file exists. Note that the acual behavoir might be @@ -6270,9 +6292,9 @@ If you'd like to contribute to this guide, please contact one the maintainers fo

    -
    -

    Edits

    -
    +
    +

    Edits

    +

    linux/fs.h updated file_operations structure (see http://lwn.net/Articles/119652/) unregister_chrdev returns void @@ -6305,7 +6327,7 @@ Fixed sched.c

    -Back to top | E-mail me +Back to top | E-mail me
    diff --git a/3.8/LKMPG-3.8.org b/3.8/LKMPG-3.8.org index a227e15..3a6e660 100644 --- a/3.8/LKMPG-3.8.org +++ b/3.8/LKMPG-3.8.org @@ -5,7 +5,7 @@ #+OPTIONS: ^:nil #+STYLE: -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][http://opensource.org/licenses/osl.php]]. +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 3.0. 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. diff --git a/4.7.4/LKMPG-4.7.4.html b/4.7.4/LKMPG-4.7.4.html index 9136298..4cb72e7 100644 --- a/4.7.4/LKMPG-4.7.4.html +++ b/4.7.4/LKMPG-4.7.4.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + The Linux Kernel Module Programming Guide @@ -264,92 +264,92 @@ for the JavaScript code in this tag.

    Table of Contents

    -
    -

    Introduction

    -
    +
    +

    Introduction

    +

    -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. +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 3.0.

    @@ -369,18 +369,18 @@ If you publish or distribute this book commercially, donations, royalties, and/o

    -
    -

    Authorship

    -
    +
    +

    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. Bob Mottram updated the examples for 3.8 and 4.7.4 kernels and modified or updated some chapters.

    -
    -

    Versioning and Notes

    -
    +
    +

    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 4.7.x will address Linux kernel 4.7.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.

    @@ -391,18 +391,18 @@ The source code and discussions should apply to most architectures, but I can't
    -
    -

    Acknowledgements

    -
    +
    +

    Acknowledgements

    +

    The following people have contributed corrections or good suggestions: Ignacio Martin, David Porter, Daniele Paolo Scarpazza, Dimo Velev, Francois Audeon, Horst Schirmeier, Bob Mottram and Roman Lakeev.

    -
    -

    What Is A Kernel Module?

    -
    +
    +

    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.

    @@ -413,9 +413,9 @@ What exactly is a kernel module? Modules are pieces of code that can be loaded a
    -
    -

    Kernel module package

    -
    +
    +

    Kernel module package

    +

    Linux distros provide the commands modprobe, insmod and depmod within a package.

    @@ -440,9 +440,9 @@ On Parabola:
    -
    -

    What Modules are in my Kernel?

    -
    +
    +

    What Modules are in my Kernel?

    +

    To discover what modules are already loaded within your current kernel use the command lsmod.

    @@ -472,29 +472,33 @@ This can be a long list, and you might prefer to search for something particular
    -
    -

    Do I need to download and compile the kernel?

    -
    +
    +

    Do I need to download and compile the kernel?

    +

    For the purposes of following this guide you don't necessarily need to do that. However, it would be wise to run the examples within a test distro running on a virtual machine in order to avoid any possibility of messing up your system.

    -
    -

    Before We Begin

    -
    +
    +

    Before We Begin

    +

    Before we delve into code, there are a few issues we need to cover. Everyone's system is different and everyone has their own groove. Getting your first "hello world" program to compile and load correctly can sometimes be a trick. Rest assured, after you get over the initial hurdle of doing it for the first time, it will be smooth sailing thereafter.

    -
    • Modversioning
      +
        +
      • Modversioning
        +

        A module compiled for one kernel won't load if you boot a different kernel unless you enable CONFIG_MODVERSIONS in the kernel. We won't go into module versioning until later in this guide. Until we cover modversions, the examples in the guide may not work if you're running a kernel with modversioning turned on. However, most stock Linux distro kernels come with it turned on. If you're having trouble loading the modules because of versioning errors, compile a kernel with modversioning turned off.

        -
        • +
      +
      • -
    • Using X
      +
    • Using X
      +

      It is highly recommended that you type in, compile and load all the examples this guide discusses. It's also highly recommended you do this from a console. You should not be working on this stuff in X.

      @@ -502,13 +506,15 @@ It is highly recommended that you type in, compile and load all the examples thi

      Modules can't print to the screen like printf() can, but they can log information and warnings, which ends up being printed on your screen, but only on a console. If you insmod a module from an xterm, the information and warnings will be logged, but only to your systemd journal. You won't see it unless you look through your journalctl. To have immediate access to this information, do all your work from the console.

      -
    +
    + +
    -
    -

    Headers

    -
    +
    +

    Headers

    +

    Before you can build anything you'll need to install the header files for your kernel. On Parabola GNU/Linux:

    @@ -538,9 +544,9 @@ This will tell you what kernel header files are available. Then for example:
    -
    -

    Examples

    -
    +
    +

    Examples

    +

    All the examples from this document are available within the examples subdirectory. To test that they compile:

    @@ -556,12 +562,13 @@ If there are any compile errors then you might have a more recent kernel version

    -
    -

    Hello World

    -
    -
    -

    The Simplest Module

    -
    +
    +

    Hello World

    +
    +
    +
    +

    The Simplest Module

    +

    Most people learning programming start out with some sort of "hello world" example. I don't know what happens to people who break with this tradition, but I think it's safer not to find out. We'll start with a series of hello world programs that demonstrate the different aspects of the basics of writing a kernel module.

    @@ -704,7 +711,9 @@ Lastly, every kernel module needs to include linux/module.h. We needed to includ

    -
    • Introducing printk()
      +
        +
      • Introducing printk()
        +

        Despite what you might think, printk() was not meant to communicate information to the user, even though we used it for exactly this purpose in hello-1! It happens to be a logging mechanism for the kernel, and is used to log information or give warnings. Therefore, each printk() statement comes with a priority, which is the <1> and KERN_ALERT you see. There are 8 priorities and the kernel has macros for them, so you don't have to use cryptic numbers, and you can view them (and their meanings) in linux/kernel.h. If you don't specify a priority level, the default priority, DEFAULT_MESSAGE_LOGLEVEL, will be used.

        @@ -716,9 +725,11 @@ Take time to read through the priority macros. The header file also describes wh

        If the priority is less than int console_loglevel, the message is printed on your current terminal. If both syslogd and klogd are running, then the message will also get appended to the systemd journal, whether it got printed to the console or not. We use a high priority, like KERN_ALERT, to make sure the printk() messages get printed to your console rather than just logged to the journal. When you write real modules, you'll want to use priorities that are meaningful for the situation at hand.

        -
        • +
      +
      • -
    • About Compiling
      +
    • About Compiling
      +

      Kernel modules need to be compiled a bit differently from regular userspace apps. Former kernel versions required us to care much about these settings, which are usually stored in Makefiles. Although hierarchically organized, many redundant settings accumulated in sublevel Makefiles and made them large and rather difficult to maintain. Fortunately, there is a new way of doing these things, called kbuild, and the build process for external loadable modules is now fully integrated into the standard kernel build mechanism. To learn more on how to compile modules which are not part of the official kernel (such as all the examples you'll find in this guide), see file linux/Documentation/kbuild/modules.txt.

      @@ -732,12 +743,14 @@ Additional details about Makefiles for kernel modules are available in linux/ Here's another exercise for the reader. See that comment above the return statement in init_module()? Change the return value to something negative, recompile and load the module again. What happens?

      -
    +
    + +
    -
    -

    Hello and Goodbye

    -
    +
    +

    Hello and Goodbye

    +

    In early kernel versions you had to use the init_module and cleanup_module functions, as in the first hello world example, but these days you can name those anything you want by using the module_init and module_exit macros. These macros are defined in linux/init.h. The only requirement is that your init and cleanup functions must be defined before calling the those macros, otherwise you'll get compilation errors. Here's an example of this technique:

    @@ -789,9 +802,9 @@ Now have a look at linux/drivers/char/Makefile for a real world example. As you
    -
    -

    The __init and __exit Macros

    -
    +
    +

    The __init and __exit Macros

    +

    This demonstrates a feature of kernel 2.2 and later. Notice the change in the definitions of the init and cleanup functions. The __init macro causes the init function to be discarded and its memory freed once the init function finishes for built-in drivers, but not loadable modules. If you think about when the init function is invoked, this makes perfect sense.

    @@ -836,9 +849,9 @@ module_exit(hello_3_exit);
    -
    -

    Licensing and Module Documentation

    -
    +
    +

    Licensing and Module Documentation

    +

    Honestly, who loads or even cares about proprietary modules? If you do then you might have seen something like this:

    @@ -890,9 +903,9 @@ module_exit(cleanup_hello_4);
    -
    -

    Passing Command Line Arguments to a Module

    -
    +
    +

    Passing Command Line Arguments to a Module

    +

    Modules can take command line arguments, but not with the argc/argv you might be used to.

    @@ -1042,9 +1055,9 @@ hello-5.o: invalid argument syntax for mylong: 'h'
    -
    -

    Modules Spanning Multiple Files

    -
    +
    +

    Modules Spanning Multiple Files

    +

    Sometimes it makes sense to divide a kernel module between several source files.

    @@ -1115,9 +1128,9 @@ This is the complete makefile for all the examples we've seen so far. The first
    -
    -

    Building modules for a precompiled kernel

    -
    +
    +

    Building modules for a precompiled kernel

    +

    Obviously, we strongly suggest you to recompile your kernel, so that you can enable a number of useful debugging features, such as forced module unloading (MODULE_FORCE_UNLOAD): when this option is enabled, you can force the kernel to unload a module even when it believes it is unsafe, via a sudo rmmod -f module command. This option can save you a lot of time and a number of reboots during the development of a module. If you don't want to recompile your kernel then you should consider running the examples within a test distro on a virtual machine. If you mess anything up then you can easily reboot or restore the VM.

    @@ -1209,12 +1222,13 @@ If you do not desire to actually compile the kernel, you can interrupt the build
    -
    -

    Preliminaries

    -
    -
    -

    How modules begin and end

    -
    +
    +

    Preliminaries

    +
    +
    +
    +

    How modules begin and end

    +

    A program usually begins with a main() function, executes a bunch of instructions and terminates upon completion of those instructions. Kernel modules work a bit differently. A module always begin with either the init_module or the function you specify with module_init call. This is the entry function for modules; it tells the kernel what functionality the module provides and sets up the kernel to run the module's functions when they're needed. Once it does this, entry function returns and the module does nothing until the kernel wants to do something with the code that the module provides.

    @@ -1229,9 +1243,9 @@ Every module must have an entry function and an exit function. Since there's mor
    -
    -

    Functions available to modules

    -
    +
    +

    Functions available to modules

    +

    Programmers use functions they don't define all the time. A prime example of this is printf(). You use these library functions which are provided by the standard C library, libc. The definitions for these functions don't actually enter your program until the linking stage, which insures that the code (for printf() for example) is available, and fixes the call instruction to point to that code.

    @@ -1269,9 +1283,9 @@ You can even write modules to replace the kernel's system calls, which we'll do
    -
    -

    User Space vs Kernel Space

    -
    +
    +

    User Space vs Kernel Space

    +

    A kernel is all about access to resources, whether the resource in question happens to be a video card, a hard drive or even memory. Programs often compete for the same resource. As I just saved this document, updatedb started updating the locate database. My vim session and updatedb are both using the hard drive concurrently. The kernel needs to keep things orderly, and not give users access to resources whenever they feel like it. To this end, a CPU can run in different modes. Each mode gives a different level of freedom to do what you want on the system. The Intel 80386 architecture had 4 of these modes, which were called rings. Unix uses only two rings; the highest ring (ring 0, also known as `supervisor mode' where everything is allowed to happen) and the lowest ring, which is called `user mode'.

    @@ -1282,9 +1296,9 @@ Recall the discussion about library functions vs system calls. Typically, you us
    -
    -

    Name Space

    -
    +
    +

    Name Space

    +

    When you write a small C program, you use variables which are convenient and make sense to the reader. If, on the other hand, you're writing routines which will be part of a bigger problem, any global variables you have are part of a community of other peoples' global variables; some of the variable names can clash. When a program has lots of global variables which aren't meaningful enough to be distinguished, you get namespace pollution. In large projects, effort must be made to remember reserved names, and to find ways to develop a scheme for naming unique variable names and symbols.

    @@ -1299,9 +1313,9 @@ The file /proc/kallsyms holds all the symbols that the kernel knows about
    -
    -

    Code space

    -
    +
    +

    Code space

    +

    Memory management is a very complicated subject and the majority of O'Reilly's "Understanding The Linux Kernel" exclusively covers memory management! We're not setting out to be experts on memory managements, but we do need to know a couple of facts to even begin worrying about writing real modules.

    @@ -1320,15 +1334,17 @@ By the way, I would like to point out that the above discussion is true for any
    -
    -

    Device Drivers

    -
    +
    +

    Device Drivers

    +

    One class of module is the device driver, which provides functionality for hardware like a serial port. On unix, each piece of hardware is represented by a file located in /dev named a device file which provides the means to communicate with the hardware. The device driver provides the communication on behalf of a user program. So the es1370.o sound card device driver might connect the /dev/sound device file to the Ensoniq IS1370 sound card. A userspace program like mp3blaster can use /dev/sound without ever knowing what kind of sound card is installed.

    -
    • Major and Minor Numbers
      +
        +
      • Major and Minor Numbers
        +

        Let's look at some device files. Here are device files which represent the first three partitions on the primary master IDE hard drive:

        @@ -1387,16 +1403,19 @@ brw-rw---- 1 root floppy 2, 44 Jul 5 2000 /dev/fd0u1680

        By now you can look at these two device files and know instantly that they are block devices and are handled by same driver (block major 2). You might even be aware that these both represent your floppy drive, even if you only have one floppy drive. Why two files? One represents the floppy drive with 1.44 MB of storage. The other is the same floppy drive with 1.68 MB of storage, and corresponds to what some people call a `superformatted' disk. One that holds more data than a standard formatted floppy. So here's a case where two device files with different minor number actually represent the same piece of physical hardware. So just be aware that the word `hardware' in our discussion can mean something very abstract.

        -
      +
      +
      • +
    -
    -

    Character Device drivers

    -
    -
    -

    The file_operations Structure

    -
    +
    +

    Character Device drivers

    +
    +
    +
    +

    The file_operations Structure

    +

    The file_operations structure is defined in /usr/include/linux/fs.h, and holds pointers to functions defined by the driver that perform various operations on the device. Each field of the structure corresponds to the address of some function defined by the driver to handle a requested operation.

    @@ -1481,9 +1500,9 @@ An instance of struct file_operations containing pointers to functions that are
    -
    -

    The file structure

    -
    +
    +

    The file structure

    +

    Each device is represented in the kernel by a file structure, which is defined in linux/fs.h. Be aware that a file is a kernel level structure and never appears in a user space program. It's not the same thing as a FILE, which is defined by glibc and would never appear in a kernel space function. Also, its name is a bit misleading; it represents an abstract open `file', not a file on a disk, which is represented by a structure named inode.

    @@ -1498,9 +1517,9 @@ Go ahead and look at the definition of file. Most of the entries you see, like s
    -
    -

    Registering A Device

    -
    +
    +

    Registering A Device

    +

    As discussed earlier, char devices are accessed through device files, usually located in /dev4. The major number tells you which driver handles which device file. The minor number is used only by the driver itself to differentiate which device it's operating on, just in case the driver handles more than one device.

    @@ -1528,9 +1547,9 @@ If you pass a major number of 0 to register_chrdev, the return value will be the
    -
    -

    Unregistering A Device

    -
    +
    +

    Unregistering A Device

    +

    We can't allow the kernel module to be rmmod'ed whenever root feels like it. If the device file is opened by a process and then we remove the kernel module, using the file would cause a call to the memory location where the appropriate function (read/write) used to be. If we're lucky, no other code was loaded there, and we'll get an ugly error message. If we're unlucky, another kernel module was loaded into the same location, which means a jump into the middle of another function within the kernel. The results of this would be impossible to predict, but they can't be very positive.

    @@ -1550,9 +1569,9 @@ It's important to keep the counter accurate; if you ever do lose track of the co
    -
    -

    chardev.c

    -
    +
    +

    chardev.c

    +

    The next code sample creates a char driver named chardev. You can cat its device file.

    @@ -1738,9 +1757,9 @@ The next code sample creates a char driver named chardev. You can cat its device
    -
    -

    Writing Modules for Multiple Kernel Versions

    -
    +
    +

    Writing Modules for Multiple Kernel Versions

    +

    The system calls, which are the major interface the kernel shows to the processes, generally stay the same across versions. A new system call may be added, but usually the old ones will behave exactly like they used to. This is necessary for backward compatibility – a new kernel version is not supposed to break regular processes. In most cases, the device files will also remain the same. On the other hand, the internal interfaces within the kernel can and do change between versions.

    @@ -1764,9 +1783,9 @@ You might already have noticed that recent kernels look different. In case you h
    -
    -

    The /proc File System

    -
    +
    +

    The /proc File System

    +

    In Linux, there is an additional mechanism for the kernel and kernel modules to send information to processes — the /proc file system. Originally designed to allow easy access to information about processes (hence the name), it is now used by every bit of the kernel which has something interesting to report, such as /proc/modules which provides the list of modules and /proc/meminfo which stats memory usage statistics.

    @@ -1856,9 +1875,9 @@ HelloWorld!
    -
    -

    Read and Write a /proc File

    -
    +
    +

    Read and Write a /proc File

    +

    We have seen a very simple example for a /proc file where we only read the file /proc/helloworld. It's also possible to write in a /proc file. It works the same way as read, a function is called when the /proc file is written. But there is a little difference with read, data comes from user, so you have to import data from user space to kernel space (with copy_from_user or get_user)

    @@ -1975,9 +1994,9 @@ The only memory segment accessible to a process is its own, so when writing regu
    -
    -

    Manage /proc file with standard filesystem

    -
    +
    +

    Manage /proc file with standard filesystem

    +

    We have seen how to read and write a /proc file with the /proc interface. But it's also possible to manage /proc file with inodes. The main concern is to use advanced functions, like permissions.

    @@ -2087,9 +2106,9 @@ Still hungry for procfs examples? Well, first of all keep in mind, there are rum
    -
    -

    Manage /proc file with seq_file

    -
    +
    +

    Manage /proc file with seq_file

    +

    As we have seen, writing a /proc file may be quite "complex". So to help people writting /proc file, there is an API named seq_file that helps @@ -2279,9 +2298,9 @@ You can also read the code of fs/seq_file.c in the linux kernel.

    -
    -

    sysfs: Interacting with your module

    -
    +
    +

    sysfs: Interacting with your module

    +

    sysfs allows you to interact with the running kernel by reading or setting variables inside of modules. This can be useful for debugging purposes, or just as an interface for userland applications or scripts.

    @@ -2411,9 +2430,9 @@ Finally, remove the test module:
    -
    -

    Talking To Device Files

    -
    +
    +

    Talking To Device Files

    +

    Device files are supposed to represent physical devices. Most physical devices are used for output as well as input, so there has to be some mechanism for device drivers in the kernel to get the output to send to the device from processes. This is done by opening the device file for output and writing to it, just like writing to a file. In the following example, this is implemented by device_write.

    @@ -2894,9 +2913,9 @@ If you want to use ioctls in your own kernel modules, it is best to receive an o
    -
    -

    System Calls

    -
    +
    +

    System Calls

    +

    So far, the only thing we've done was to use well defined kernel mechanisms to register /proc files and device handlers. This is fine if you want to do something the kernel programmers thought you'd want, such as write a device driver. But what if you want to do something unusual, to change the behavior of the system in some way? Then, you're mostly on your own.

    @@ -3099,9 +3118,9 @@ asmlinkage int our
    -
    -

    Blocking Processes

    -
    +
    +

    Blocking Processes

    +

    What do you do when somebody asks you for something you can't do right away? If you're a human being and you're bothered by a human being, the only thing you can say is: "Not right now, I'm busy. Go away!". But if you're a kernel module and you're bothered by a process, you have another possibility. You can put the process to sleep until you can service it. After all, processes are being put to sleep by the kernel and woken up all the time (that's the way multiple processes appear to run on the same time on a single CPU).

    @@ -3491,12 +3510,13 @@ DECLARE_WAIT_QUEUE_HEAD(WaitQ);
    -
    -

    Replacing Printks

    -
    -
    -

    Replacing printk

    -
    +
    +

    Replacing Printks

    +
    +
    +
    +

    Replacing printk

    +

    In Section 1.2.1.2, I said that X and kernel module programming don't mix. That's true for developing kernel modules, but in actual use, you want to be able to send messages to whichever tty12 the command to load the module came from.

    @@ -3619,9 +3639,9 @@ module_exit(print_string_exit);
    -
    -

    Flashing keyboard LEDs

    -
    +
    +

    Flashing keyboard LEDs

    +

    In certain conditions, you may desire a simpler and more direct way to communicate to the external world. Flashing keyboard LEDs can be such a solution: It is an immediate way to attract attention or to display a status condition. Keyboard LEDs are present on every hardware, they are always visible, they do not need any setup, and their use is rather simple and non-intrusive, compared to writing to a tty or a file.

    @@ -3740,9 +3760,9 @@ While you have seen lots of stuff that can be used to aid debugging here, there
    -
    -

    Scheduling Tasks

    -
    +
    +

    Scheduling Tasks

    +

    Very often, we have "housekeeping" tasks which have to be done at a certain time, or every so often. If the task is to be done by a process, we do it by putting it in the crontab file. If the task is to be done by a kernel module, we have two possibilities. The first is to put a process in the crontab file which will wake up the module by a system call when necessary, for example by opening a file. This is terribly inefficient, however – we run a new process off of crontab, read a new executable to memory, and all this just to wake up a kernel module which is in memory anyway.

    @@ -3925,12 +3945,13 @@ MODULE_LICENSE("GPL");
    -
    -

    Interrupt Handlers

    -
    -
    -

    Interrupt Handlers

    -
    +
    +

    Interrupt Handlers

    +
    +
    +
    +

    Interrupt Handlers

    +

    Except for the last chapter, everything we did in the kernel so far we've done as a response to a process asking for it, either by dealing with a special file, sending an ioctl(), or issuing a system call. But the job of the kernel isn't just to respond to process requests. Another job, which is every bit as important, is to speak to the hardware connected to the machine.

    @@ -3957,9 +3978,9 @@ Then, from within the interrupt handler, we communicate with the hardware and th
    -
    -

    Keyboards on the Intel Architecture

    -
    +
    +

    Keyboards on the Intel Architecture

    +

    The rest of this chapter is completely Intel specific. If you're not running on an Intel platform, it will not work. Don't even try to compile the code here. Move right along, nothing to see.

    @@ -4093,35 +4114,35 @@ MODULE_LICENSE("GPL");
    -
    -

    Common Pitfalls

    -
    +
    +

    Common Pitfalls

    +

    Before I send you on your way to go out into the world and write kernel modules, there are a few things I need to warn you about. If I fail to warn you and something bad happens, please report the problem to me for a full refund of the amount I was paid for your copy of the book.

    -
    -

    Using standard libraries

    -
    +
    +

    Using standard libraries

    +

    You can't do that. In a kernel module you can only use kernel functions, which are the functions you can see in /proc/kallsyms.

    -
    -

    Disabling interrupts

    -
    +
    +

    Disabling interrupts

    +

    You might need to do this for a short time and that is OK, but if you don't enable them afterwards, your system will be stuck and you'll have to power it off.

    -
    -

    Sticking your head inside a large carnivore

    -
    +
    +

    Sticking your head inside a large carnivore

    +

    I probably don't have to warn you about this, but I figured I will anyway, just in case.

    @@ -4129,9 +4150,9 @@ I probably don't have to warn you about this, but I figured I will anyway, just
    -
    -

    Where To Go From Here?

    -
    +
    +

    Where To Go From Here?

    +

    I could easily have squeezed a few more chapters into this book. I could have added a chapter about creating new file systems, or about adding new protocol stacks (as if there's a need for that – you'd have to dig underground to find a protocol stack not supported by Linux). I could have added explanations of the kernel mechanisms we haven't touched upon, such as bootstrapping or the disk interface.

    @@ -4272,7 +4293,7 @@ more details, might want to do a web search for "APIC" now ;)
    -Back to top | E-mail me +Back to top | E-mail me
    diff --git a/4.7.4/LKMPG-4.7.4.org b/4.7.4/LKMPG-4.7.4.org index b03d05c..821b663 100644 --- a/4.7.4/LKMPG-4.7.4.org +++ b/4.7.4/LKMPG-4.7.4.org @@ -5,7 +5,7 @@ #+OPTIONS: ^:nil * Introduction -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][http://opensource.org/licenses/osl.php]]. +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 3.0. 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. diff --git a/4.7.4/img/seq_file.png b/4.7.4/img/seq_file.png index 4d15a3a..9dbb479 100644 Binary files a/4.7.4/img/seq_file.png and b/4.7.4/img/seq_file.png differ diff --git a/4.9.11/LKMPG-4.9.11.html b/4.9.11/LKMPG-4.9.11.html index a7ef25d..3ea59eb 100644 --- a/4.9.11/LKMPG-4.9.11.html +++ b/4.9.11/LKMPG-4.9.11.html @@ -3,7 +3,7 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - + The Linux Kernel Module Programming Guide @@ -264,99 +264,99 @@ for the JavaScript code in this tag.

    Table of Contents

    -
    -

    Introduction

    -
    +
    +

    Introduction

    +

    -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. +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 3.0.

    @@ -376,18 +376,18 @@ If you publish or distribute this book commercially, donations, royalties, and/o

    -
    -

    Authorship

    -
    +
    +

    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. Bob Mottram updated the examples for 3.8 and later kernels, added the sysfs chapter and modified or updated other chapters.

    -
    -

    Versioning and Notes

    -
    +
    +

    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 4.9.x will address Linux kernel 4.9.x 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.

    @@ -398,18 +398,18 @@ The source code and discussions should apply to most architectures, but I can't
    -
    -

    Acknowledgements

    -
    +
    +

    Acknowledgements

    +

    The following people have contributed corrections or good suggestions: Ignacio Martin, David Porter, Daniele Paolo Scarpazza, Dimo Velev, Francois Audeon, Horst Schirmeier, Bob Mottram and Roman Lakeev.

    -
    -

    What Is A Kernel Module?

    -
    +
    +

    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.

    @@ -420,9 +420,9 @@ What exactly is a kernel module? Modules are pieces of code that can be loaded a
    -
    -

    Kernel module package

    -
    +
    +

    Kernel module package

    +

    Linux distros provide the commands modprobe, insmod and depmod within a package.

    @@ -447,9 +447,9 @@ On Parabola:
    -
    -

    What Modules are in my Kernel?

    -
    +
    +

    What Modules are in my Kernel?

    +

    To discover what modules are already loaded within your current kernel use the command lsmod.

    @@ -479,33 +479,33 @@ This can be a long list, and you might prefer to search for something particular
    -
    -

    Do I need to download and compile the kernel?

    -
    +
    +

    Do I need to download and compile the kernel?

    +

    For the purposes of following this guide you don't necessarily need to do that. However, it would be wise to run the examples within a test distro running on a virtual machine in order to avoid any possibility of messing up your system.

    -
    -

    Before We Begin

    -
    +
    +

    Before We Begin

    +

    Before we delve into code, there are a few issues we need to cover. Everyone's system is different and everyone has their own groove. Getting your first "hello world" program to compile and load correctly can sometimes be a trick. Rest assured, after you get over the initial hurdle of doing it for the first time, it will be smooth sailing thereafter.

      -
    • Modversioning
      -
      +
    • Modversioning
      +

      A module compiled for one kernel won't load if you boot a different kernel unless you enable CONFIG_MODVERSIONS in the kernel. We won't go into module versioning until later in this guide. Until we cover modversions, the examples in the guide may not work if you're running a kernel with modversioning turned on. However, most stock Linux distro kernels come with it turned on. If you're having trouble loading the modules because of versioning errors, compile a kernel with modversioning turned off.

      • -
    • Using X
      -
      +
    • Using X
      +

      It is highly recommended that you type in, compile and load all the examples this guide discusses. It's also highly recommended you do this from a console. You should not be working on this stuff in X.

      @@ -519,9 +519,9 @@ Modules can't print to the screen like printf() can, but they can log informatio
    -
    -

    Headers

    -
    +
    +

    Headers

    +

    Before you can build anything you'll need to install the header files for your kernel. On Parabola GNU/Linux:

    @@ -551,9 +551,9 @@ This will tell you what kernel header files are available. Then for example:
    -
    -

    Examples

    -
    +
    +

    Examples

    +

    All the examples from this document are available within the examples subdirectory. To test that they compile:

    @@ -569,13 +569,13 @@ If there are any compile errors then you might have a more recent kernel version

    -
    -

    Hello World

    -
    +
    +

    Hello World

    +
    -
    -

    The Simplest Module

    -
    +
    +

    The Simplest Module

    +

    Most people learning programming start out with some sort of "hello world" example. I don't know what happens to people who break with this tradition, but I think it's safer not to find out. We'll start with a series of hello world programs that demonstrate the different aspects of the basics of writing a kernel module.

    @@ -719,8 +719,8 @@ Lastly, every kernel module needs to include linux/module.h. We needed to includ
      -
    • Introducing printk()
      -
      +
    • Introducing printk()
      +

      Despite what you might think, printk() was not meant to communicate information to the user, even though we used it for exactly this purpose in hello-1! It happens to be a logging mechanism for the kernel, and is used to log information or give warnings. Therefore, each printk() statement comes with a priority, which is the <1> and KERN_ALERT you see. There are 8 priorities and the kernel has macros for them, so you don't have to use cryptic numbers, and you can view them (and their meanings) in linux/kernel.h. If you don't specify a priority level, the default priority, DEFAULT_MESSAGE_LOGLEVEL, will be used.

      @@ -735,8 +735,8 @@ If the priority is less than int console_loglevel, the message is printed on you
      • -
    • About Compiling
      -
      +
    • About Compiling
      +

      Kernel modules need to be compiled a bit differently from regular userspace apps. Former kernel versions required us to care much about these settings, which are usually stored in Makefiles. Although hierarchically organized, many redundant settings accumulated in sublevel Makefiles and made them large and rather difficult to maintain. Fortunately, there is a new way of doing these things, called kbuild, and the build process for external loadable modules is now fully integrated into the standard kernel build mechanism. To learn more on how to compile modules which are not part of the official kernel (such as all the examples you'll find in this guide), see file linux/Documentation/kbuild/modules.txt.

      @@ -755,9 +755,9 @@ Here's another exercise for the reader. See that comment above the return statem
    -
    -

    Hello and Goodbye

    -
    +
    +

    Hello and Goodbye

    +

    In early kernel versions you had to use the init_module and cleanup_module functions, as in the first hello world example, but these days you can name those anything you want by using the module_init and module_exit macros. These macros are defined in linux/init.h. The only requirement is that your init and cleanup functions must be defined before calling the those macros, otherwise you'll get compilation errors. Here's an example of this technique:

    @@ -809,9 +809,9 @@ Now have a look at linux/drivers/char/Makefile for a real world example. As you
    -
    -

    The __init and __exit Macros

    -
    +
    +

    The __init and __exit Macros

    +

    This demonstrates a feature of kernel 2.2 and later. Notice the change in the definitions of the init and cleanup functions. The __init macro causes the init function to be discarded and its memory freed once the init function finishes for built-in drivers, but not loadable modules. If you think about when the init function is invoked, this makes perfect sense.

    @@ -856,9 +856,9 @@ module_exit(hello_3_exit);
    -
    -

    Licensing and Module Documentation

    -
    +
    +

    Licensing and Module Documentation

    +

    Honestly, who loads or even cares about proprietary modules? If you do then you might have seen something like this:

    @@ -910,9 +910,9 @@ module_exit(cleanup_hello_4);
    -
    -

    Passing Command Line Arguments to a Module

    -
    +
    +

    Passing Command Line Arguments to a Module

    +

    Modules can take command line arguments, but not with the argc/argv you might be used to.

    @@ -1062,9 +1062,9 @@ hello-5.o: invalid argument syntax for mylong: 'h'
    -
    -

    Modules Spanning Multiple Files

    -
    +
    +

    Modules Spanning Multiple Files

    +

    Sometimes it makes sense to divide a kernel module between several source files.

    @@ -1135,9 +1135,9 @@ This is the complete makefile for all the examples we've seen so far. The first
    -
    -

    Building modules for a precompiled kernel

    -
    +
    +

    Building modules for a precompiled kernel

    +

    Obviously, we strongly suggest you to recompile your kernel, so that you can enable a number of useful debugging features, such as forced module unloading (MODULE_FORCE_UNLOAD): when this option is enabled, you can force the kernel to unload a module even when it believes it is unsafe, via a sudo rmmod -f module command. This option can save you a lot of time and a number of reboots during the development of a module. If you don't want to recompile your kernel then you should consider running the examples within a test distro on a virtual machine. If you mess anything up then you can easily reboot or restore the VM.

    @@ -1229,13 +1229,13 @@ If you do not desire to actually compile the kernel, you can interrupt the build
    -
    -

    Preliminaries

    -
    +
    +

    Preliminaries

    +
    -
    -

    How modules begin and end

    -
    +
    +

    How modules begin and end

    +

    A program usually begins with a main() function, executes a bunch of instructions and terminates upon completion of those instructions. Kernel modules work a bit differently. A module always begin with either the init_module or the function you specify with module_init call. This is the entry function for modules; it tells the kernel what functionality the module provides and sets up the kernel to run the module's functions when they're needed. Once it does this, entry function returns and the module does nothing until the kernel wants to do something with the code that the module provides.

    @@ -1250,9 +1250,9 @@ Every module must have an entry function and an exit function. Since there's mor
    -
    -

    Functions available to modules

    -
    +
    +

    Functions available to modules

    +

    Programmers use functions they don't define all the time. A prime example of this is printf(). You use these library functions which are provided by the standard C library, libc. The definitions for these functions don't actually enter your program until the linking stage, which insures that the code (for printf() for example) is available, and fixes the call instruction to point to that code.

    @@ -1290,9 +1290,9 @@ You can even write modules to replace the kernel's system calls, which we'll do
    -
    -

    User Space vs Kernel Space

    -
    +
    +

    User Space vs Kernel Space

    +

    A kernel is all about access to resources, whether the resource in question happens to be a video card, a hard drive or even memory. Programs often compete for the same resource. As I just saved this document, updatedb started updating the locate database. My vim session and updatedb are both using the hard drive concurrently. The kernel needs to keep things orderly, and not give users access to resources whenever they feel like it. To this end, a CPU can run in different modes. Each mode gives a different level of freedom to do what you want on the system. The Intel 80386 architecture had 4 of these modes, which were called rings. Unix uses only two rings; the highest ring (ring 0, also known as `supervisor mode' where everything is allowed to happen) and the lowest ring, which is called `user mode'.

    @@ -1303,9 +1303,9 @@ Recall the discussion about library functions vs system calls. Typically, you us
    -
    -

    Name Space

    -
    +
    +

    Name Space

    +

    When you write a small C program, you use variables which are convenient and make sense to the reader. If, on the other hand, you're writing routines which will be part of a bigger problem, any global variables you have are part of a community of other peoples' global variables; some of the variable names can clash. When a program has lots of global variables which aren't meaningful enough to be distinguished, you get namespace pollution. In large projects, effort must be made to remember reserved names, and to find ways to develop a scheme for naming unique variable names and symbols.

    @@ -1320,9 +1320,9 @@ The file /proc/kallsyms holds all the symbols that the kernel knows about
    -
    -

    Code space

    -
    +
    +

    Code space

    +

    Memory management is a very complicated subject and the majority of O'Reilly's "Understanding The Linux Kernel" exclusively covers memory management! We're not setting out to be experts on memory managements, but we do need to know a couple of facts to even begin worrying about writing real modules.

    @@ -1341,17 +1341,17 @@ By the way, I would like to point out that the above discussion is true for any
    -
    -

    Device Drivers

    -
    +
    +

    Device Drivers

    +

    One class of module is the device driver, which provides functionality for hardware like a serial port. On unix, each piece of hardware is represented by a file located in /dev named a device file which provides the means to communicate with the hardware. The device driver provides the communication on behalf of a user program. So the es1370.o sound card device driver might connect the /dev/sound device file to the Ensoniq IS1370 sound card. A userspace program like mp3blaster can use /dev/sound without ever knowing what kind of sound card is installed.

      -
    • Major and Minor Numbers
      -
      +
    • Major and Minor Numbers
      +

      Let's look at some device files. Here are device files which represent the first three partitions on the primary master IDE hard drive:

      @@ -1416,13 +1416,13 @@ By now you can look at these two device files and know instantly that they are b
    -
    -

    Character Device drivers

    -
    +
    +

    Character Device drivers

    +
    -
    -

    The file_operations Structure

    -
    +
    +

    The file_operations Structure

    +

    The file_operations structure is defined in /usr/include/linux/fs.h, and holds pointers to functions defined by the driver that perform various operations on the device. Each field of the structure corresponds to the address of some function defined by the driver to handle a requested operation.

    @@ -1507,9 +1507,9 @@ An instance of struct file_operations containing pointers to functions that are
    -
    -

    The file structure

    -
    +
    +

    The file structure

    +

    Each device is represented in the kernel by a file structure, which is defined in linux/fs.h. Be aware that a file is a kernel level structure and never appears in a user space program. It's not the same thing as a FILE, which is defined by glibc and would never appear in a kernel space function. Also, its name is a bit misleading; it represents an abstract open `file', not a file on a disk, which is represented by a structure named inode.

    @@ -1524,9 +1524,9 @@ Go ahead and look at the definition of file. Most of the entries you see, like s
    -
    -

    Registering A Device

    -
    +
    +

    Registering A Device

    +

    As discussed earlier, char devices are accessed through device files, usually located in /dev4. The major number tells you which driver handles which device file. The minor number is used only by the driver itself to differentiate which device it's operating on, just in case the driver handles more than one device.

    @@ -1554,9 +1554,9 @@ If you pass a major number of 0 to register_chrdev, the return value will be the
    -
    -

    Unregistering A Device

    -
    +
    +

    Unregistering A Device

    +

    We can't allow the kernel module to be rmmod'ed whenever root feels like it. If the device file is opened by a process and then we remove the kernel module, using the file would cause a call to the memory location where the appropriate function (read/write) used to be. If we're lucky, no other code was loaded there, and we'll get an ugly error message. If we're unlucky, another kernel module was loaded into the same location, which means a jump into the middle of another function within the kernel. The results of this would be impossible to predict, but they can't be very positive.

    @@ -1576,9 +1576,9 @@ It's important to keep the counter accurate; if you ever do lose track of the co
    -
    -

    chardev.c

    -
    +
    +

    chardev.c

    +

    The next code sample creates a char driver named chardev. You can cat its device file.

    @@ -1766,9 +1766,9 @@ The next code sample creates a char driver named chardev. You can cat its device
    -
    -

    Writing Modules for Multiple Kernel Versions

    -
    +
    +

    Writing Modules for Multiple Kernel Versions

    +

    The system calls, which are the major interface the kernel shows to the processes, generally stay the same across versions. A new system call may be added, but usually the old ones will behave exactly like they used to. This is necessary for backward compatibility – a new kernel version is not supposed to break regular processes. In most cases, the device files will also remain the same. On the other hand, the internal interfaces within the kernel can and do change between versions.

    @@ -1792,9 +1792,9 @@ You might already have noticed that recent kernels look different. In case you h
    -
    -

    The /proc File System

    -
    +
    +

    The /proc File System

    +

    In Linux, there is an additional mechanism for the kernel and kernel modules to send information to processes — the /proc file system. Originally designed to allow easy access to information about processes (hence the name), it is now used by every bit of the kernel which has something interesting to report, such as /proc/modules which provides the list of modules and /proc/meminfo which stats memory usage statistics.

    @@ -1884,9 +1884,9 @@ HelloWorld!
    -
    -

    Read and Write a /proc File

    -
    +
    +

    Read and Write a /proc File

    +

    We have seen a very simple example for a /proc file where we only read the file /proc/helloworld. It's also possible to write in a /proc file. It works the same way as read, a function is called when the /proc file is written. But there is a little difference with read, data comes from user, so you have to import data from user space to kernel space (with copy_from_user or get_user)

    @@ -2003,9 +2003,9 @@ The only memory segment accessible to a process is its own, so when writing regu
    -
    -

    Manage /proc file with standard filesystem

    -
    +
    +

    Manage /proc file with standard filesystem

    +

    We have seen how to read and write a /proc file with the /proc interface. But it's also possible to manage /proc file with inodes. The main concern is to use advanced functions, like permissions.

    @@ -2115,9 +2115,9 @@ Still hungry for procfs examples? Well, first of all keep in mind, there are rum
    -
    -

    Manage /proc file with seq_file

    -
    +
    +

    Manage /proc file with seq_file

    +

    As we have seen, writing a /proc file may be quite "complex". So to help people writting /proc file, there is an API named seq_file that helps @@ -2307,9 +2307,9 @@ You can also read the code of fs/seq_file.c in the linux kernel.

    -
    -

    sysfs: Interacting with your module

    -
    +
    +

    sysfs: Interacting with your module

    +

    sysfs allows you to interact with the running kernel from userspace by reading or setting variables inside of modules. This can be useful for debugging purposes, or just as an interface for applications or scripts. You can find sysfs directories and files under the sys directory on your system.

    @@ -2444,9 +2444,9 @@ Finally, remove the test module:
    -
    -

    Talking To Device Files

    -
    +
    +

    Talking To Device Files

    +

    Device files are supposed to represent physical devices. Most physical devices are used for output as well as input, so there has to be some mechanism for device drivers in the kernel to get the output to send to the device from processes. This is done by opening the device file for output and writing to it, just like writing to a file. In the following example, this is implemented by device_write.

    @@ -2927,9 +2927,9 @@ If you want to use ioctls in your own kernel modules, it is best to receive an o
    -
    -

    System Calls

    -
    +
    +

    System Calls

    +

    So far, the only thing we've done was to use well defined kernel mechanisms to register /proc files and device handlers. This is fine if you want to do something the kernel programmers thought you'd want, such as write a device driver. But what if you want to do something unusual, to change the behavior of the system in some way? Then, you're mostly on your own.

    @@ -3135,9 +3135,9 @@ MODULE_LICENSE("GPL");
    -
    -

    Blocking Processes

    -
    +
    +

    Blocking Processes

    +

    What do you do when somebody asks you for something you can't do right away? If you're a human being and you're bothered by a human being, the only thing you can say is: "Not right now, I'm busy. Go away!". But if you're a kernel module and you're bothered by a process, you have another possibility. You can put the process to sleep until you can service it. After all, processes are being put to sleep by the kernel and woken up all the time (that's the way multiple processes appear to run on the same time on a single CPU).

    @@ -3527,13 +3527,13 @@ DECLARE_WAIT_QUEUE_HEAD(WaitQ);
    -
    -

    Replacing Printks

    -
    +
    +

    Replacing Printks

    +
    -
    -

    Replacing printk

    -
    +
    +

    Replacing printk

    +

    In Section 1.2.1.2, I said that X and kernel module programming don't mix. That's true for developing kernel modules, but in actual use, you want to be able to send messages to whichever tty12 the command to load the module came from.

    @@ -3656,9 +3656,9 @@ module_exit(print_string_exit);
    -
    -

    Flashing keyboard LEDs

    -
    +
    +

    Flashing keyboard LEDs

    +

    In certain conditions, you may desire a simpler and more direct way to communicate to the external world. Flashing keyboard LEDs can be such a solution: It is an immediate way to attract attention or to display a status condition. Keyboard LEDs are present on every hardware, they are always visible, they do not need any setup, and their use is rather simple and non-intrusive, compared to writing to a tty or a file.

    @@ -3777,9 +3777,9 @@ While you have seen lots of stuff that can be used to aid debugging here, there
    -
    -

    Scheduling Tasks

    -
    +
    +

    Scheduling Tasks

    +

    Very often, we have "housekeeping" tasks which have to be done at a certain time, or every so often. If the task is to be done by a process, we do it by putting it in the crontab file. If the task is to be done by a kernel module, we have two possibilities. The first is to put a process in the crontab file which will wake up the module by a system call when necessary, for example by opening a file. This is terribly inefficient, however – we run a new process off of crontab, read a new executable to memory, and all this just to wake up a kernel module which is in memory anyway.

    @@ -3962,9 +3962,9 @@ MODULE_LICENSE("GPL");
    -
    -

    The order of completion

    -
    +
    +

    The order of completion

    +

    Sometimes one thing should happen before another and a thread should wait until it is ready to run. Rather than using sleep commands the kernel has a simple way to do this which allows timeouts or interrupts to also happen.

    @@ -4067,13 +4067,13 @@ There are other variations upon the wait_for_completion function, which i

    -
    -

    Interrupt Handlers

    -
    +
    +

    Interrupt Handlers

    +
    -
    -

    Interrupt Handlers

    -
    +
    +

    Interrupt Handlers

    +

    Except for the last chapter, everything we did in the kernel so far we've done as a response to a process asking for it, either by dealing with a special file, sending an ioctl(), or issuing a system call. But the job of the kernel isn't just to respond to process requests. Another job, which is every bit as important, is to speak to the hardware connected to the machine.

    @@ -4096,9 +4096,9 @@ The way to implement this is to call request_irq() to get your interrupt
    -
    -

    Detecting button presses

    -
    +
    +

    Detecting button presses

    +

    Many popular single board computers, such as Raspberry Pis or Beagleboards, have a bunch of GPIO pins. Attaching buttons to those and then having a button press do something is a classic case in which you might need to use interrupts so that instead of having the CPU waste time and battery power polling for a change in input state it's better for the input to trigger the CPU to then run a particular handling function.

    @@ -4265,17 +4265,17 @@ MODULE_DESCRIPTION("Handle some GPIO interrupts"
    -
    -

    Crypto

    -
    +
    +

    Crypto

    +

    At the dawn of the internet everybody trusted everybody completely…but that didn't work out so well. When this guide was originally written it was a more innocent era in which almost nobody actually gave a damn about crypto - least of all kernel developers. That's certainly no longer the case now. To handle crypto stuff the kernel has its own API enabling common methods of encryption, decryption and your favourite hash functions.

    -
    -

    Hash functions

    -
    +
    +

    Hash functions

    +

    Calculating and checking the hashes of things is a common operation. Here is a demonstration of how to calculate a sha256 hash within a kernel module.

    @@ -4373,9 +4373,9 @@ Finally, remove the test module:
    -
    -

    Symmetric key encryption

    -
    +
    +

    Symmetric key encryption

    +

    Here is an example of symmetrically encrypting a string using the AES algorithm and a password.

    @@ -4566,35 +4566,35 @@ MODULE_LICENSE("GPL");
    -
    -

    Common Pitfalls

    -
    +
    +

    Common Pitfalls

    +

    Before I send you on your way to go out into the world and write kernel modules, there are a few things I need to warn you about. If I fail to warn you and something bad happens, please report the problem to me for a full refund of the amount I was paid for your copy of the book.

    -
    -

    Using standard libraries

    -
    +
    +

    Using standard libraries

    +

    You can't do that. In a kernel module you can only use kernel functions, which are the functions you can see in /proc/kallsyms.

    -
    -

    Disabling interrupts

    -
    +
    +

    Disabling interrupts

    +

    You might need to do this for a short time and that is OK, but if you don't enable them afterwards, your system will be stuck and you'll have to power it off.

    -
    -

    Sticking your head inside a large carnivore

    -
    +
    +

    Sticking your head inside a large carnivore

    +

    I probably don't have to warn you about this, but I figured I will anyway, just in case.

    @@ -4602,9 +4602,9 @@ I probably don't have to warn you about this, but I figured I will anyway, just
    -
    -

    Where To Go From Here?

    -
    +
    +

    Where To Go From Here?

    +

    I could easily have squeezed a few more chapters into this book. I could have added a chapter about creating new file systems, or about adding new protocol stacks (as if there's a need for that – you'd have to dig underground to find a protocol stack not supported by Linux). I could have added explanations of the kernel mechanisms we haven't touched upon, such as bootstrapping or the disk interface.

    diff --git a/4.9.11/LKMPG-4.9.11.org b/4.9.11/LKMPG-4.9.11.org index ec14d45..979e66f 100644 --- a/4.9.11/LKMPG-4.9.11.org +++ b/4.9.11/LKMPG-4.9.11.org @@ -5,7 +5,7 @@ #+OPTIONS: ^:nil * Introduction -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. +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 3.0. 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. diff --git a/LICENSE b/LICENSE index 9fdf3bc..b505681 100644 --- a/LICENSE +++ b/LICENSE @@ -1,161 +1,47 @@ - The Open Software License - v. 1.1 +The Open Software License 3.0 (OSL-3.0) -This Open Software License (the "License") applies to any original work of -authorship (the "Original Work") whose owner (the "Licensor") has placed the -following notice immediately following the copyright notice for the Original -Work: +This Open Software License (the "License") applies to any original work of authorship (the "Original Work") whose owner (the "Licensor") has placed the following licensing notice adjacent to the copyright notice for the Original Work: -Licensed under the Open Software License version 1.1 +Licensed under the Open Software License version 3.0 -1) Grant of Copyright License. Licensor hereby grants You a world-wide, -royalty-free, non-exclusive, perpetual, non-sublicenseable license to do the -following: +1) Grant of Copyright License. Licensor grants You a worldwide, royalty-free, non-exclusive, sublicensable license, for the duration of the copyright, to do the following: -a) to reproduce the Original Work in copies; +a) to reproduce the Original Work in copies, either alone or as part of a collective work; -b) to prepare derivative works ("Derivative Works") based upon the Original -Work; +b) to translate, adapt, alter, transform, modify, or arrange the Original Work, thereby creating derivative works ("Derivative Works") based upon the Original Work; -c) to distribute copies of the Original Work and Derivative Works to the -public, with the proviso that copies of Original Work or Derivative Works that -You distribute shall be licensed under the Open Software License; +c) to distribute or communicate copies of the Original Work and Derivative Works to the public, with the proviso that copies of Original Work or Derivative Works that You distribute or communicate shall be licensed under this Open Software License; d) to perform the Original Work publicly; and e) to display the Original Work publicly. -2) Grant of Patent License. Licensor hereby grants You a world-wide, -royalty-free, non-exclusive, perpetual, non-sublicenseable license, under -patent claims owned or controlled by the Licensor that are embodied in the -Original Work as furnished by the Licensor ("Licensed Claims") to make, use, -sell and offer for sale the Original Work. Licensor hereby grants You a -world-wide, royalty-free, non-exclusive, perpetual, non-sublicenseable license -under the Licensed Claims to make, use, sell and offer for sale Derivative Works. +2) Grant of Patent License. Licensor grants You a worldwide, royalty-free, non-exclusive, sublicensable license, under patent claims owned or controlled by the Licensor that are embodied in the Original Work as furnished by the Licensor, for the duration of the patents, to make, use, sell, offer for sale, have made, and import the Original Work and Derivative Works. -3) Grant of Source Code License. The term "Source Code" means the preferred -form of the Original Work for making modifications to it and all available -documentation describing how to modify the Original Work. Licensor hereby -agrees to provide a machine-readable copy of the Source Code of the Original -Work along with each copy of the Original Work that Licensor distributes. -Licensor reserves the right to satisfy this obligation by placing a -machine-readable copy of the Source Code in an information repository reasonably -calculated to permit inexpensive and convenient access by You for as long as - Licensor continues to distribute the Original Work, and by publishing the -address of that information repository in a notice immediately following the -copyright notice that applies to the Original Work. +3) Grant of Source Code License. The term "Source Code" means the preferred form of the Original Work for making modifications to it and all available documentation describing how to modify the Original Work. Licensor agrees to provide a machine-readable copy of the Source Code of the Original Work along with each copy of the Original Work that Licensor distributes. Licensor reserves the right to satisfy this obligation by placing a machine-readable copy of the Source Code in an information repository reasonably calculated to permit inexpensive and convenient access by You for as long as Licensor continues to distribute the Original Work. -4) Exclusions From License Grant. Nothing in this License shall be deemed to -grant any rights to trademarks, copyrights, patents, trade secrets or any -other intellectual property of Licensor except as expressly stated herein. No -patent license is granted to make, use, sell or offer to sell embodiments of -any patent claims other than the Licensed Claims defined in Section 2. No -right is granted to the trademarks of Licensor even if such marks are included -in the Original Work. Nothing in this License shall be interpreted to prohibit -Licensor from licensing under different terms from this License any Original -Work that Licensor otherwise would have a right to license. +4) Exclusions From License Grant. Neither the names of Licensor, nor the names of any contributors to the Original Work, nor any of their trademarks or service marks, may be used to endorse or promote products derived from this Original Work without express prior permission of the Licensor. Except as expressly stated herein, nothing in this License grants any license to Licensor's trademarks, copyrights, patents, trade secrets or any other intellectual property. No patent license is granted to make, use, sell, offer for sale, have made, or import embodiments of any patent claims other than the licensed claims defined in Section 2. No license is granted to the trademarks of Licensor even if such marks are included in the Original Work. Nothing in this License shall be interpreted to prohibit Licensor from licensing under terms different from this License any Original Work that Licensor otherwise would have a right to license. -5) External Deployment. The term "External Deployment" means the use or -distribution of the Original Work or Derivative Works in any way such that the -Original Work or Derivative Works may be used by anyone other than You, -whether the Original Work or Derivative Works are distributed to those persons -or made available as an application intended for use over a computer network. -As an express condition for the grants of license hereunder, You agree that -any External Deployment by You of a Derivative Work shall be deemed a -distribution and shall be licensed to all under the terms of this License, as -prescribed in section 1(c) herein. +5) External Deployment. The term "External Deployment" means the use, distribution, or communication of the Original Work or Derivative Works in any way such that the Original Work or Derivative Works may be used by anyone other than You, whether those works are distributed or communicated to those persons or made available as an application intended for use over a network. As an express condition for the grants of license hereunder, You must treat any External Deployment by You of the Original Work or a Derivative Work as a distribution under section 1(c). -6) Attribution Rights. You must retain, in the Source Code of any Derivative -Works that You create, all copyright, patent or trademark notices from the -Source Code of the Original Work, as well as any notices of licensing and any -descriptive text identified therein as an "Attribution Notice." You must cause -the Source Code for any Derivative Works that You create to carry a prominent -Attribution Notice reasonably calculated to inform recipients that You have -modified the Original Work. +6) Attribution Rights. You must retain, in the Source Code of any Derivative Works that You create, all copyright, patent, or trademark notices from the Source Code of the Original Work, as well as any notices of licensing and any descriptive text identified therein as an "Attribution Notice." You must cause the Source Code for any Derivative Works that You create to carry a prominent Attribution Notice reasonably calculated to inform recipients that You have modified the Original Work. -7) Warranty and Disclaimer of Warranty. Licensor warrants that the copyright -in and to the Original Work is owned by the Licensor or that the Original Work -is distributed by Licensor under a valid current license from the copyright -owner. Except as expressly stated in the immediately proceeding sentence, the -Original Work is provided under this License on an "AS IS" BASIS and WITHOUT -WARRANTY, either express or implied, including, without limitation, the -warranties of NON-INFRINGEMENT, MERCHANTABILITY or FITNESS FOR A PARTICULAR -PURPOSE. THE ENTIRE RISK AS TO THE QUALITY OF THE ORIGINAL WORK IS WITH YOU. -This DISCLAIMER OF WARRANTY constitutes an essential part of this License. No -license to Original Work is granted hereunder except under this disclaimer. +7) Warranty of Provenance and Disclaimer of Warranty. Licensor warrants that the copyright in and to the Original Work and the patent rights granted herein by Licensor are owned by the Licensor or are sublicensed to You under the terms of this License with the permission of the contributor(s) of those copyrights and patent rights. Except as expressly stated in the immediately preceding sentence, the Original Work is provided under this License on an "AS IS" BASIS and WITHOUT WARRANTY, either express or implied, including, without limitation, the warranties of non-infringement, merchantability or fitness for a particular purpose. THE ENTIRE RISK AS TO THE QUALITY OF THE ORIGINAL WORK IS WITH YOU. This DISCLAIMER OF WARRANTY constitutes an essential part of this License. No license to the Original Work is granted by this License except under this disclaimer. -8) Limitation of Liability. Under no circumstances and under no legal theory, -whether in tort (including negligence), contract, or otherwise, shall the -Licensor be liable to any person for any direct, indirect, special, incidental, -or consequential damages of any character arising as a result of this License -or the use of the Original Work including, without limitation, damages for -loss of goodwill, work stoppage, computer failure or malfunction, or any and -all other commercial damages or losses. This limitation of liability shall not -apply to liability for death or personal injury resulting from Licensor's -negligence to the extent applicable law prohibits such limitation. Some -jurisdictions do not allow the exclusion or limitation of incidental or -consequential damages, so this exclusion and limitation may not apply to You. +8) Limitation of Liability. Under no circumstances and under no legal theory, whether in tort (including negligence), contract, or otherwise, shall the Licensor be liable to anyone for any indirect, special, incidental, or consequential damages of any character arising as a result of this License or the use of the Original Work including, without limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses. This limitation of liability shall not apply to the extent applicable law prohibits such limitation. -9) Acceptance and Termination. If You distribute copies of the Original Work -or a Derivative Work, You must make a reasonable effort under the circumstances -to obtain the express and volitional assent of recipients to the terms of this -License. Nothing else but this License (or another written agreement between -Licensor and You) grants You permission to create Derivative Works based upon -the Original Work or to exercise any of the rights granted in Sections 1 herein, -and any attempt to do so except under the terms of this License (or another -written agreement between Licensor and You) is expressly prohibited by U.S. -copyright law, the equivalent laws of other countries, and by international -treaty. Therefore, by exercising any of the rights granted to You in Sections -1 herein, You indicate Your acceptance of this License and all of its terms and -conditions. This License shall terminate immediately and you may no longer -exercise any of the rights granted to You by this License upon Your failure to -honor the proviso in Section 1(c) herein. +9) Acceptance and Termination. If, at any time, You expressly assented to this License, that assent indicates your clear and irrevocable acceptance of this License and all of its terms and conditions. If You distribute or communicate copies of the Original Work or a Derivative Work, You must make a reasonable effort under the circumstances to obtain the express assent of recipients to the terms of this License. This License conditions your rights to undertake the activities listed in Section 1, including your right to create Derivative Works based upon the Original Work, and doing so without honoring these terms and conditions is prohibited by copyright law and international treaty. Nothing in this License is intended to affect copyright exceptions and limitations (including "fair use" or "fair dealing"). This License shall terminate immediately and You may no longer exercise any of the rights granted to You by this License upon your failure to honor the conditions in Section 1(c). -10) Mutual Termination for Patent Action. This License shall terminate -automatically and You may no longer exercise any of the rights granted to You -by this License if You file a lawsuit in any court alleging that any OSI -Certified open source software that is licensed under any license containing -this "Mutual Termination for Patent Action" clause infringes any patent claims -that are essential to use that software. +10) Termination for Patent Action. This License shall terminate automatically and You may no longer exercise any of the rights granted to You by this License as of the date You commence an action, including a cross-claim or counterclaim, against Licensor or any licensee alleging that the Original Work infringes a patent. This termination provision shall not apply for an action alleging patent infringement by combinations of the Original Work with other software or hardware. -11) Jurisdiction, Venue and Governing Law. Any action or suit relating to this -License may be brought only in the courts of a jurisdiction wherein the Licensor -resides or in which Licensor conducts its primary business, and under the laws -of that jurisdiction excluding its conflict-of-law provisions. The application -of the United Nations Convention on Contracts for the International Sale of -Goods is expressly excluded. Any use of the Original Work outside the scope of -this License or after its termination shall be subject to the requirements and -penalties of the U.S. Copyright Act, 17 U.S.C. å¤ 101 et seq., the equivalent -laws of other countries, and international treaty. This section shall survive -the termination of this License. +11) Jurisdiction, Venue and Governing Law. Any action or suit relating to this License may be brought only in the courts of a jurisdiction wherein the Licensor resides or in which Licensor conducts its primary business, and under the laws of that jurisdiction excluding its conflict-of-law provisions. The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded. Any use of the Original Work outside the scope of this License or after its termination shall be subject to the requirements and penalties of copyright or patent law in the appropriate jurisdiction. This section shall survive the termination of this License. -12) Attorneys Fees. In any action to enforce the terms of this License or -seeking damages relating thereto, the prevailing party shall be entitled to -recover its costs and expenses, including, without limitation, reasonable -attorneys' fees and costs incurred in connection with such action, including -any appeal of such action. This section shall survive the termination of this -License. +12) Attorneys' Fees. In any action to enforce the terms of this License or seeking damages relating thereto, the prevailing party shall be entitled to recover its costs and expenses, including, without limitation, reasonable attorneys' fees and costs incurred in connection with such action, including any appeal of such action. This section shall survive the termination of this License. -13) Miscellaneous. This License represents the complete agreement concerning -the subject matter hereof. If any provision of this License is held to be -unenforceable, such provision shall be reformed only to the extent necessary -to make it enforceable. +13) Miscellaneous. If any provision of this License is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. -14) Definition of "You" in This License. "You" throughout this License, -whether in upper or lower case, means an individual or a legal entity exercising -rights under, and complying with all of the terms of, this License. For legal -entities, "You" includes any entity that controls, is controlled by, or is under -common control with you. For purposes of this definition, "control" means (i) -the power, direct or indirect, to cause the direction or management of such -entity, whether by contract or otherwise, or (ii) ownership of fifty percent -(50%) or more of the outstanding shares, or (iii) beneficial ownership of such -entity. +14) Definition of "You" in This License. "You" throughout this License, whether in upper or lower case, means an individual or a legal entity exercising rights under, and complying with all of the terms of, this License. For legal entities, "You" includes any entity that controls, is controlled by, or is under common control with you. For purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. -15) Right to Use. You may use the Original Work in all ways not otherwise -restricted or conditioned by this License or by law, and Licensor promises not -to interfere with or be responsible for such uses by You. +15) Right to Use. You may use the Original Work in all ways not otherwise restricted or conditioned by this License or by law, and Licensor promises not to interfere with or be responsible for such uses by You. -This license is Copyright (C) 2002 Lawrence E. Rosen. All rights reserved. -Permission is hereby granted to copy and distribute this license without -modification. This license may not be modified without the express written -permission of its copyright owner. +16) Modification of This License. This License is Copyright © 2005 Lawrence Rosen. Permission is granted to copy, distribute, or communicate this License without modification. Nothing in this License permits You to modify this License as applied to the Original Work or to Derivative Works. However, You may modify the text of this License and copy, distribute or communicate your modified version (the "Modified License") and apply it to other original works of authorship subject to the following conditions: (i) You may not indicate in any way that your Modified License is the "Open Software License" or "OSL" and you may not use those names in the name of your Modified License; (ii) You must replace the notice specified in the first paragraph above with the notice "Licensed under " or with a notice of your own that is not confusingly similar to the notice in this License; and (iii) You may not claim that your original works are open source software unless your Modified License has been approved by Open Source Initiative (OSI) and You comply with its license review and certification process.