Chapter 2
Building and Running Modules
Contents:
It's high time now to begin programming. This chapter introduces all
the essential concepts about modules and kernel programming. In these
few pages, we build and run a complete module. Developing such
expertise is an essential foundation for any kind of modularized
driver. To avoid throwing in too many concepts at once, this chapter
talks only about modules, without referring to any specific device
class.
All the kernel items (functions, variables, header files, and macros)
that are introduced here are described in a reference section at the
end of the chapter.
For the impatient reader, the following code is a complete "Hello,
World" module (which does nothing in particular). This code will
compile and run under Linux kernel versions 2.0 through
2.4.[4]
The source file shown earlier can be loaded and unloaded as shown only
if the running kernel has module version support disabled; however,
most distributions preinstall versioned kernels (versioning is
discussed in "Version Control in Modules" in Chapter 11, "kmod and Advanced Modularization"). Although older
modutils allowed loading nonversioned
modules to versioned kernels, this is no longer possible. To solve the
problem with hello.c, the source in the
misc-modules directory of the sample code
includes a few more lines to be able to run both under versioned and
nonversioned kernels. However, we strongly suggest you compile and
run your own kernel (without version support) before you run the
sample code.[5]
root# gcc -c hello.c
root# insmod ./hello.o
Hello, world
root# rmmod hello
Goodbye cruel world
root#
According to the mechanism your system uses to deliver the message
lines, your output may be different. In particular, the previous
screen dump was taken from a text console; if you are running
insmod and rmmodfrom an xterm, you won't see anything on
your TTY. Instead, it may go to one of the system log files, such as
/var/log/messages (the name of the actual file
varies between Linux distributions). The mechanism used to deliver
kernel messages is described in "How Messages Get Logged" in
Chapter 4, "Debugging Techniques".
As you can see, writing a module is not as difficult as you might
expect. The hard part is understanding your device and how to maximize
performance. We'll go deeper into modularization throughout this
chapter and leave device-specific issues to later chapters.
Whereas an application performs a single task from beginning to end, a
module registers itself in order to serve future requests, and its
"main" function terminates immediately. In other words, the task of
the function init_module (the module's entry
point) is to prepare for later invocation of the module's functions;
it's as though the module were saying, "Here I am, and this is what I
can do." The second entry point of a module,
cleanup_module, gets invoked just before the
module is unloaded. It should tell the kernel, "I'm not there
anymore; don't ask me to do anything else." The ability to unload a
module is one of the features of modularization that you'll most
appreciate, because it helps cut down development time; you can test
successive versions of your new driver without going through the
lengthy shutdown/reboot cycle each time.
The last difference between kernel programming and application
programming is in how each environment handles faults: whereas a
segmentation fault is harmless during application development and a
debugger can always be used to trace the error to the problem in the
source code, a kernel fault is fatal at least for the current process,
if not for the whole system. We'll see how to trace kernel errors in
Chapter 4, "Debugging Techniques", in the section "Debugging System Faults".
Every modern processor is able to enforce this behavior. The chosen
approach is to implement different operating modalities (or levels) in
the CPU itself. The levels have different roles, and some operations
are disallowed at the lower levels; program code can switch from one
level to another only through a limited number of gates. Unix systems
are designed to take advantage of this hardware feature, using two
such levels. All current processors have at least two protection
levels, and some, like the x86 family, have more levels; when several
levels exist, the highest and lowest levels are used. Under Unix, the
kernel executes in the highest level (also called supervisor
mode), where everything is allowed, whereas applications
execute in the lowest level (the so-called user
mode), where the processor regulates direct access to
hardware and unauthorized access to memory.
We usually refer to the execution modes as kernel
space and user space. These terms
encompass not only the different privilege levels inherent in the two
modes, but also the fact that each mode has its own memory
mapping -- its own address space -- as well.
Unix transfers execution from user space to kernel space whenever an
application issues a system call or is suspended by a hardware
interrupt. Kernel code executing a system call is working in the
context of a process -- it operates on behalf of the calling
process and is able to access data in the process's address
space. Code that handles interrupts, on the other hand, is
asynchronous with respect to processes and is not related to any
particular process.
The role of a module is to extend kernel functionality; modularized
code runs in kernel space. Usually a driver performs both the tasks
outlined previously: some functions in the module are executed as part
of system calls, and some are in charge of interrupt handling.
One way in which device driver programming differs greatly from (most)
application programming is the issue of concurrency. An application
typically runs sequentially, from the beginning to the end, without
any need to worry about what else might be happening to change its
environment. Kernel code does not run in such a simple world and must
be written with the idea that many things can be happening at once.
There are a few sources of concurrency in kernel programming.
Naturally, Linux systems run multiple processes, more than one of
which can be trying to use your driver at the same time. Most devices
are capable of interrupting the processor; interrupt handlers run
asynchronously and can be invoked at the same time that your driver is
trying to do something else. Several software abstractions (such as
kernel timers, introduced in Chapter 6, "Flow of Time") run
asynchronously as well. Moreover, of course, Linux can run on
symmetric multiprocessor (SMP) systems, with the result that your
driver could be executing concurrently on more than one CPU.
As a result, Linux kernel code, including driver code, must be
reentrant -- it must be capable of running
in more than one context at the same time. Data structures must be
carefully designed to keep multiple threads of execution separate, and
the code must take care to access shared data in ways that prevent
corruption of the data. Writing code that handles concurrency and
avoids race conditions (situations in which an unfortunate order of
execution causes undesirable behavior) requires thought and can be
tricky. Every sample driver in this book has been written with
concurrency in mind, and we will explain the techniques we use as we
come to them.
A common mistake made by driver programmers is
to assume that
concurrency is not a problem as long as a particular segment of code
does not go to sleep (or "block"). It is true that the Linux kernel
is nonpreemptive; with the important exception of servicing
interrupts, it will not take the processor away from kernel code that
does not yield willingly. In past times, this nonpreemptive behavior
was enough to prevent unwanted concurrency most of the time. On SMP
systems, however, preemption is not required to cause concurrent
execution.
If your code assumes that it will not be preempted, it will not run
properly on SMP systems. Even if you do not have such a system, others
who run your code may have one. In the future, it is also possible
that the kernel will move to a preemptive mode of operation, at which
point even uniprocessor systems will have to deal with concurrency
everywhere (some variants of the kernel already implement it). Thus, a
prudent programmer will always program as if he or she were working on
an SMP system.
Although kernel modules don't execute sequentially as applications do,
most actions performed by the kernel are related to a specific
process. Kernel code can know the current process driving it by
accessing the global item current, a pointer to
struct task_struct, which as of version 2.4 of the
kernel is declared in ,
included by . The
current pointer refers to the user process
currently executing. During the execution of a system call, such as
open or read, the current
process is the one that invoked the call. Kernel code can use
process-specific information by using current, if
it needs to do so. An example of this technique is presented in
"Access Control on a Device File", in Chapter 5, "Enhanced Char Driver Operations".
Actually, current is not properly a global variable
any more, like it was in the first Linux kernels. The developers
optimized access to the structure describing the current process by
hiding it in the stack page. You can look at the details of
current in
. While the code you'll look
at might seem hairy, we must keep in mind that Linux is an
SMP-compliant system, and a global variable simply won't work when you
are dealing with multiple CPUs. The details of the implementation
remain hidden to other kernel subsystems though, and a device driver
can just include and refer to
the current process.
From a module's point of view, current is just like
the external reference printk. A module can
refer to current wherever it sees fit. For
example, the following statement prints the process ID and the command
name of the current process by accessing certain fields in
struct task_struct:
printk("The process is \"%s\" (pid %i)\n",
current->comm, current->pid);
The command name stored in current->comm is the
base name of the program file that is being executed by the current
process.
The rest of this chapter is devoted to writing a
complete, though
typeless, module. That is, the module will not belong to any of the
classes listed in "Classes of Devices and Modules" in Chapter 1, "An
Introduction to Device Drivers". The sample driver shown in this
chapter is called
skull, short for Simple Kernel Utility for
Loading Localities. You can reuse the
skull source to load your own local code to
the kernel, after removing the sample functionality it
offers.[8]
You may also need to check that the compiler you are running matches
the kernel you are compiling against, referring to the file
Documentation/Changes in the kernel source
tree. The kernel and the compiler are developed at the same time,
though by different groups, so sometimes changes in one tool reveal
bugs in the other. Some distributions ship a version of the compiler
that is too new to reliably build the kernel. In this case, they will
usually provide a separate package (often called
kgcc) with a compiler intended for kernel
compilation.
Finally, in order to prevent unpleasant errors, we suggest that you
use the -Wall (all warnings) compiler flag,
and also that you fix all features in your code that cause compiler
warnings, even if this requires changing your usual programming
style. When writing kernel code, the preferred coding style is
undoubtedly Linus's own style.
Documentation/CodingStyle is amusing reading and
a mandatory lesson for anyone interested in kernel hacking.
If you are not familiar with make, you may
wonder why no .c file and no compilation rule
appear in the makefile shown. These declarations are unnecessary
because make is smart enough to turn
.c into .o without being
instructed to, using the current (or default) choice for the compiler,
$(CC), and its flags, $(CFLAGS).
After the module is built, the next step is loading it into the
kernel. As we've already suggested, insmoddoes the job for you. The program is like
ld, in that it links any unresolved symbol
in the module to the symbol table of the running kernel. Unlike the
linker, however, it doesn't modify the disk file, but rather an
in-memory copy. insmod accepts a number of
command-line options (for details, see the manpage), and it can assign
values to integer and string variables in your module before linking
it to the current kernel. Thus, if a module is correctly designed, it
can be configured at load time; load-time configuration gives the user
more
flexibility than compile-time configuration, which is still used
sometimes. Load-time configuration is explained in "Automatic and Manual Configuration" later in this chapter.
Bear in mind that your module's code has to be recompiled for each
version of the kernel that it will be linked to. Each module defines a
symbol called __module_kernel_version,
which insmod matches against the version
number of the current kernel. This symbol is placed in the
.modinfo Executable Linking and Format (ELF)
section, as explained in detail in Chapter 11, "kmod and Advanced Modularization". Please
note that this description of the internals applies only to versions
2.2 and 2.4 of the kernel; Linux 2.0 did the same job in a different
way.
In case of version mismatch, you can still try to load a module
against a different kernel version by specifying the
-f ("force") switch to
insmod, but this operation isn't safe and
can fail. It's also difficult to tell in advance what will
happen. Loading can fail because of mismatching symbols, in which case
you'll get an error message, or it can fail because of an internal
change in the kernel. If that happens, you'll get serious errors at
runtime and possibly a system panic -- a good reason to be wary of
version mismatches. Version mismatches can be handled more gracefully
by using versioning in the kernel (a topic that is more advanced and
is introduced in "Version Control in Modules" in Chapter 11, "kmod and Advanced Modularization").
If you want to compile your module for a particular kernel version,
you have to include the specific header files for that kernel (for
example, by declaring a different KERNELDIR) in the
makefile given previously. This situation is not uncommon when playing
with the kernel sources, as most of the time you'll end up with
several versions of the source tree. All of the sample modules
accompanying this book use the KERNELDIR variable
to point to the correct kernel sources; it can be set in your
environment or passed on the command line of
make.
When asked to load a module, insmod follows
its own search path to look for the object file, looking in
version-dependent directories under /lib/modules.
Although older versions of the program looked in the current directory,
first, that behavior is now disabled for security reasons (it's the
same problem of the PATH environment
variable). Thus, if you need to load a module from the current
directory you should use ./module.o, which works
with all known versions of the tool.
Sometimes, you'll encounter kernel interfaces that behave differently
between versions 2.0.x and
2.4.x of Linux. In this case you'll need to
resort to the macros defining the version number of the current source
tree, which are defined in the header
. We will point out cases
where interfaces have changed as we come to them, either within the
chapter or in a specific section about version dependencies at the
end, to avoid complicating a 2.4-specific discussion.
-
-
-
This is the macro used to build a "kernel_version_code"
from the individual numbers that build up a version number.
For example, KERNEL_VERSION(2,3,48) expands to 131888.
This macro is very useful when you need to compare the current
version and a known checkpoint. We'll use this macro several
times throughout the book.
Each computer platform has its peculiarities, and kernel designers are
free to exploit all the peculiarities to achieve better performance in
the target object file.
Unlike application developers, who must link their code with
precompiled libraries and stick to conventions on parameter passing,
kernel developers can dedicate some processor registers to specific
roles, and they have done so. Moreover, kernel code can be optimized
for a specific processor in a CPU family to get the best from the
target platform: unlike applications that are often distributed in
binary format, a custom compilation of the kernel can be optimized for
a specific computer set.
Modularized code, in order to be interoperable with the kernel, needs
to be compiled using the same options used in compiling the kernel
(i.e., reserving the same registers for special use and performing the
same optimizations). For this reason, our top-level
Rules.make includes a platform-specific file that
complements the makefiles with extra definitions. All of those files
are called
Makefile.platform and
assign suitable values to make variables
according to the current kernel configuration.
New modules can use symbols exported by your module, and you can stack
new modules on top of other modules. Module stacking is implemented in
the mainstream kernel sources as well: the
msdos filesystem relies on symbols exported
by the fat module, and each input USB
device module stacks on the usbcore and
input modules.
Module stacking is useful in complex projects. If a new abstraction is
implemented in the form of a device driver, it might offer a plug for
hardware-specific implementations. For example, the video-for-linux
set of drivers is split into a generic module that exports symbols
used by lower-level device drivers for specific hardware. According to
your setup, you load the generic video module and the specific module
for your installed hardware. Support for parallel ports and the wide
variety of attachable devices is handled in the same way, as is the
USB kernel subsystem. Stacking in the parallel port subsystem is shown
in Figure 2-2; the arrows show the communications
between the modules (with some example functions and data structures)
and with the kernel programming interface.
When using stacked modules, it is helpful to be aware of the
modprobeutility. modprobe functions in much the
same way as insmod, but it also loads any
other modules that are required by the module you want to
load. Thus, one modprobe command can
sometimes replace several invocations of
insmod (although you'll still need
insmod when loading your own modules from
the current directory, because modprobeonly looks in the tree of installed modules).
Layered modularization can help reduce development time by simplifying
each layer. This is similar to the separation between mechanism and
policy that we discussed in Chapter 1, "An Introduction to Device Drivers".
The items that can be registered exceed the list of device types
mentioned in Chapter 1, "An Introduction to Device Drivers". They include serial ports,
miscellaneous devices, /proc files, executable
domains, and line disciplines. Many of those registrable items
support functions that aren't directly related to hardware but remain
in the "software abstractions" field. Those items can be registered
because they are integrated into the driver's functionality anyway
(like /proc files and line disciplines for
example).
If any errors occur when you register utilities, you must undo any
registration activities performed before the failure. An error can
happen, for example, if there isn't enough memory in the system to
allocate a new data structure or because a resource being requested is
already being used by other drivers. Though unlikely, it might happen,
and good program code must be prepared to handle this event.
Obviously, cleanup_module must undo any
registration performed by init_module, and it is
customary (but not mandatory) to unregister facilities in the reverse
order used to register them:
If your initialization and cleanup are more complex than dealing with
a few items, the goto approach may become difficult
to manage, because all the cleanup code must be repeated within
init_module, with several labels
intermixed. Sometimes, therefore, a different layout of the code
proves more successful.
What you'd do to minimize code duplication and keep everything
streamlined is to call cleanup_module from within
init_module whenever an error occurs. The cleanup
function, then, must check the status of each item before undoing its
registration. In its simplest form, the code looks like the
following:
The system keeps a usage count for every module in order to determine
whether the module can be safely removed. The system needs this
information because a module can't be unloaded if it is busy: you
can't remove a filesystem type while the filesystem is mounted, and
you can't drop a char device while a process is using it, or you'll
experience some sort of segmentation fault or kernel panic when wild
pointers get dereferenced.
-
Increments the count for the current module
-
-
The macros are defined in ,
and they act on internal data structures that shouldn't be accessed
directly by the programmer. The internals of module management changed
a lot during 2.1 development and were completely rewritten in 2.1.18,
but the use of these macros did not change.
You won't be able to unload a module if you lose track of the usage
count. This situation may very well happen during development, so you
should keep it in mind. For example, if a process gets destroyed
because your driver dereferenced a NULL pointer, the driver won't be
able to close the device, and the usage count won't fall back to zero.
One possible solution is to completely disable the usage count during
the debugging cycle by redefining both
MOD_INC_USE_COUNT and
MOD_DEC_USE_COUNT to no-ops. Another solution
is to
use some other method to force the counter to zero (you'll see this
done in the section "Using the ioctl Argument" in Chapter 5, "Enhanced
Char Driver Operations"). Sanity checks should never be circumvented in
a
production module. For debugging, however, sometimes a brute-force
attitude helps save development time and is therefore acceptable.
The current value of the usage count is found in the third field of
each entry in /proc/modules. This file shows the modules
currently loaded in the system, with one entry for each module. The
fields are the name of the module, the number of bytes of memory it
uses, and the current usage count. This is a typical
/proc/modules file:
The use of __init (and
__initdata for data items) can reduce the
amount of memory used by the kernel. There is no harm in marking
module initialization functions with
__init, even though currently there is no
benefit either. Management of initialization sections has not been
implemented yet for modules, but it's a possible enhancement for the
future.
As a programmer, you are already accustomed to managing memory
allocation; writing kernel code is no different in this regard. Your
program obtains a memory area using kmalloc and
releases it using kfree. These functions behave
like malloc and free, except
that kmalloc takes an additional argument, the
priority. Usually, a priority of GFP_KERNEL or
GFP_USER will do. The GFP
acronym stands for "get free page." (Memory allocation is covered in
detail in Chapter 7, "Getting Hold of Memory".)
Unfortunately, not all bus architectures offer a clean way to identify
I/O regions belonging to each device, and sometimes the driver must
guess where its I/O regions live, or even probe for the devices by
reading and writing to "possible" address ranges. This problem is
especially true of the ISA bus, which is still in use for simple
devices to plug in a personal computer and is very popular in the
industrial world in its PC/104 implementation (see "PC/104 and PC/104+" in Chapter 15, "Overview of Peripheral Buses").
Despite the features (or lack of features) of the bus being used by a
hardware device, the device driver should be guaranteed exclusive
access to its I/O regions in order to prevent interference from other
drivers. For example, if a module probing for its hardware should
happen to write to ports owned by another device, weird things would
undoubtedly happen.
The developers of Linux chose to implement a request/free mechanism
for I/O regions, mainly as a way to prevent collisions between
different devices. The mechanism has long been in use for I/O ports
and was recently generalized to manage resource allocation at large.
Note that this mechanism is just a software abstraction that helps
system housekeeping, and may or may not be enforced by hardware
features. For example, unauthorized access to I/O ports doesn't
produce any error condition equivalent to "segmentation
fault" -- the hardware can't enforce port registration.
Information about registered resources is available in text form in
the files /proc/ioports and
/proc/iomem, although the latter was only
introduced during 2.3 development.
We'll discuss version 2.4 now, introducing portability issues at
the end of the chapter.
Each entry in the file specifies (in hexadecimal) a range of ports
locked by a driver or owned by a hardware device. In earlier versions
of the kernel the file had the same format, but without the
"layered" structure that is shown through indentation.
The file can be used to avoid port collisions when a new device is
added to the system and an I/O range must be selected by moving
jumpers: the user can check what ports are already in use and set up
the new device to use an available I/O range. Although you might
object that most modern hardware doesn't use jumpers any more, the
issue is still relevant for custom devices and industrial components.
But what is more important than the ioports file
itself is the data structure behind it. When the software driver for a
device initializes itself, it can know what port ranges are already in
use; if the driver needs to probe I/O ports to detect the new device,
it will be able to avoid probing those ports that are already in use
by other drivers.
The typical sequence for registering ports is the following, as it
appears in the skull sample driver. (The
function skull_probe_hw is not shown here because
it contains device-specific code.)
This code first looks to see if the required range of ports is
available; if the ports cannot be allocated, there is no point in
looking for the hardware. The actual allocation of the ports is
deferred until after the device is known to exist. The
request_region call should never fail; the kernel
only loads a single module at a time, so there should not be a problem
with other modules slipping in and stealing the ports during the
detection phase. Paranoid code can check, but bear in mind that
kernels prior to 2.4 define request_region as
returning void.
The current resource allocation mechanism was introduced in Linux
2.3.11 and provides a flexible way of controlling system resources.
This section briefly describes the mechanism. However, the basic
resource allocation functions (request_region and
the rest) are still implemented (via macros) and are still universally
used because they are backward compatible with earlier kernel
versions. Most module programmers will not need to know about what is
really happening under the hood, but those working on more complex
drivers may be interested.
Linux resource management is able to control arbitrary resources, and
it can do so in a hierarchical manner. Globally known resources (the
range of I/O ports, say) can be subdivided into smaller
subsets -- for example, the resources associated with a particular
bus slot. Individual drivers can then further subdivide their range if
need be.
Subranges of a given resource may be created with
allocate_resource. For example, during PCI
initialization a new resource is created for a region that is actually
assigned to a physical device. When the PCI code reads those port or
memory assignments, it creates a new resource for just those regions,
and allocates them under ioport_resource or
iomem_resource.
A driver can then request a subset of a particular resource (actually
a subrange of a global resource) and mark it as busy by calling
__request_region, which returns a pointer
to a new struct resource data structure that
describes the resource being requested (or returns
NULL in case of error). The structure is already
part of the global resource tree, and the driver is not allowed to use
it at will.
Several parameters that a driver needs to know can change from system
to system. For instance, the driver must know the hardware's actual
I/O addresses, or memory range (this is not a problem with
well-designed bus interfaces and only applies to ISA
devices). Sometimes you'll need to pass parameters to a driver to help
it in finding its own device or to enable/disable specific features.
Depending on the device, there may be other parameters in addition to
the I/O address that affect the driver's behavior, such as device
brand and release number. It's essential for the driver to know the
value of these parameters in order to work correctly. Setting up the
driver with the correct values (i.e., configuring it) is one of the
tricky tasks that need to be performed during driver initialization.
Basically, there are two ways to obtain the correct values: either
the user specifies them explicitly or the driver autodetects them.
Although autodetection is undoubtedly the best approach to driver
configuration, user configuration is much easier to implement. A
suitable trade-off for a driver writer is to implement automatic
configuration whenever possible, while allowing user configuration as
an option to override autodetection. An additional advantage of this
approach to configuration is that the initial development can be done
without autodetection, by specifying the parameters at load time, and
autodetection can be implemented later.
Five types are currently supported for module parameters:
b, one byte; h, a short (two
bytes); i, an integer; l, a
long; and s, a string. In the case of string
values, a pointer variable should be declared;
insmod will allocate the memory for the
user-supplied parameter and set the variable accordingly. An integer
value preceding the type indicates an array of a given length; two
numbers, separated by a hyphen, give a minimum and maximum number of
values. If you want to find the author's description of this feature,
you should refer to the header file
.
All module parameters should be given a default value;
insmod will change the value only if
explicitly told to by the user. The module can check for explicit
parameters by testing parameters against their default
values. Automatic configuration, then, can be designed to work this
way: if the configuration variables have the default value, perform
autodetection; otherwise, keep the current value. In order for this
technique to work, the "default" value should be one that the user
would never actually want to specify at load time.
The following code shows how skullautodetects the port address of a device. In this example,
autodetection is used to look for multiple devices, while manual
configuration is restricted to a single device. The function
skull_detect occurred earlier, in "Ports"," while skull_init_board is
in charge of device-specific initialization and thus is not shown.
/*
* port ranges: the device can reside between
* 0x280 and 0x300, in steps of 0x10. It uses 0x10 ports.
*/
#define SKULL_PORT_FLOOR 0x280
#define SKULL_PORT_CEIL 0x300
#define SKULL_PORT_RANGE 0x010
/*
* the following function performs autodetection, unless a specific
* value was assigned by insmod to "skull_port_base"
*/
static int skull_port_base=0; /* 0 forces autodetection */
MODULE_PARM (skull_port_base, "i");
MODULE_PARM_DESC (skull_port_base, "Base I/O port for skull");
static int skull_find_hw(void) /* returns the # of devices */
{
/* base is either the load-time value or the first trial */
int base = skull_port_base ? skull_port_base
: SKULL_PORT_FLOOR;
int result = 0;
/* loop one time if value assigned; try them all if autodetecting */
do {
if (skull_detect(base, SKULL_PORT_RANGE) == 0) {
skull_init_board(base);
result++;
}
base += SKULL_PORT_RANGE; /* prepare for next trial */
}
while (skull_port_base == 0 && base < SKULL_PORT_CEIL);
return result;
}
For completeness, there are three other macros that place
documentation into the object file. They are as follows:
-
-
- MODULE_SUPPORTED_DEVICE (dev)
-
Places an entry describing what device is supported by this
module. Comments in the kernel source suggest that this parameter may
eventually be used to help with automated module loading, but no such
use is made at this time.
A Unix programmer who's addressing kernel issues for the first time
might well be nervous about writing a module. Writing a user program
that reads and writes directly to the device ports is much easier.
Indeed, there are some arguments in favor of user-space programming,
and sometimes writing a so-called user-space device driver is a wise
alternative to kernel hacking.
An example of a user-space driver is the X server: it knows exactly
what the hardware can do and what it can't, and it offers the graphic
resources to all X clients. Note, however, that there is a slow but
steady drift toward frame-buffer-based graphics environments, where
the X server acts only as a server based on a real kernel-space device
driver for actual graphic manipulation.
Usually, the writer of a user-space driver implements a server
process, taking over from the kernel the task of being the single
agent in charge of hardware control. Client applications can then
connect to the server to perform actual communication with the device;
a smart driver process can thus allow concurrent access to the device.
This is exactly how the X server works.
Another example of a user-space driver is the
gpm mouse server: it performs arbitration
of the mouse device between clients, so that several mouse-sensitive
applications can run on different virtual consoles.
Sometimes, though, the user-space driver grants device access to a
single program. This is how libsvga works. The
library, which turns a TTY into a graphics display, gets linked to the
application, thus supplementing the application's capabilities without
resorting to a central authority (e.g., a server). This approach
usually gives you better performance because it skips the
communication overhead, but it requires the application to run as a
privileged user (this is one of the problems being solved by the frame
buffer device driver running in kernel space).
But the user-space approach to device driving has a number of
drawbacks. The most important are as follows:
As you see, user-space drivers can't do that much after
all. Interesting applications nonetheless exist: for example, support
for SCSI scanner devices (implemented by the
SANE package) and CD writers (implemented
by cdrecord and other tools). In both
cases, user-level device drivers rely on the "SCSI generic" kernel
driver, which exports low-level SCSI functionality to user-space
programs so they can drive their own hardware.
In order to write a user-space driver, some hardware knowledge is
sufficient, and there's no need to understand the subtleties of kernel
software. We won't discuss user-space drivers any further in this
book, but will concentrate on kernel code instead.
The Linux kernel is a moving target -- many things change over time
as new features are developed. The interface that we have described in
this chapter is that provided by the 2.4 kernel; if your code needs to
work on older releases, you will need to take various steps to make
that happen.
This is the first of many "backward compatibility" sections in this
book. At the end of each chapter we'll cover the things that have
changed since version 2.0 of the kernel, and what needs to be done to
make your code portable.
The new resource management scheme brings in a few portability
problems if you want to write a driver that can run with kernel
versions older than 2.4. This section discusses the portability
problems you'll encounter and how the sysdep.hheader tries to hide them.
If you do need to export symbols from your module, you will need to
create a symbol table structure describing these symbols. Filling a
Linux 2.0 symbol table structure is a tricky task, but kernel
developers have provided header files to simplify things. The
following lines of code show how a symbol table is declared and
exported using the facilities offered by the headers of Linux 2.0:
Writing portable code that controls symbol visibility takes an
explicit effort from the device driver programmer. This is a case
where it is not sufficient to define a few compatibility macros;
instead, portability requires a fair amount of conditional
preprocessor code, but the concepts are simple. The first step is to
identify the kernel version in use and to define some symbols
accordingly. What we chose to do in sysdep.h is
define a macro REGISTER_SYMTAB() that expands to
nothing on version 2.2 and later and expands to
register_symtab on version 2.0. Also,
__USE_OLD_SYMTAB__ is defined if
the old code must be used.
This section summarizes the kernel functions, variables, macros, and
/proc files that we've touched on in this
chapter. It is meant to act as a reference. Each item is listed after
the relevant header file, if any. A similar section appears at the end
of every chapter from here on, summarizing the new symbols introduced
in the chapter.
- __KERNEL__
- MODULE
-
-
-
-
-
-
-
The list of currently loaded modules. Entries contain
the module name, the amount of memory each module occupies, and the
usage count. Extra strings are appended to each line to
specify flags that are currently active for the
module.
-
-
-
-
-
-
- MODULE_SUPPORTED_DEVICE(device);
-
Place documentation on the module in the object file.
-
-
-
-
-
- struct task_struct *current;
-
The current process.
- current->pid
- current->comm
-
The process ID and command name for the current process.
-
-
-
-
-
-
The list of ports used by installed devices.
-
