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 Section 1.3, in Chapter 1. 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.^[4]

Before we deal with the roles of init_module and cleanup_module, however, we’ll write a Makefile that builds object code that the kernel can load.

First, we need to define the __KERNEL__ symbol in the preprocessor before we include any headers. This symbol is used to select which parts of the headers are actually used. Applications end up including kernel headers because libc includes them,^[5] but the applications don’t need all the kernel prototypes. Therefore, __KERNEL__ is used to mask the extra ones out via #ifdef. Exporting kernel symbols and macros to user-space programs would greatly contribute to program namespace pollution. If you are compiling for an SMP (Symmetric Multi-Processor) machine, you also need to define __SMP__ before including the kernel headers. This requirement may seem unfriendly, but is going to disappear as soon as the developers find the right way to be SMP-transparent.

Another important symbol is MODULE, which must be defined before including <linux/module.h>. This symbol is always defined, except when compiling drivers that are directly linked to the kernel image. Since none of the drivers covered in this book are directly linked to the kernel, they all define the symbol.

A module writer must also specify the -O flag to the compiler, because many functions are declared as inline in the header files. gcc doesn’t expand inlines unless optimization is enabled, but it can accept both the -g and -O options, allowing you to debug code that uses inline functions.^[6]

Finally, in order to prevent unpleasant errors, I suggest that you use the -Wall (all warnings) compiler flag, and also that you fix all errors in the code to eliminate all compiler warnings, even if this requires changing your usual programming style.

All the definitions and flags I’ve introduced so far are best located within the CFLAGS variable used by make.

In addition to a suitable CFLAGS, the Makefile being built needs a rule for joining different object files. The rule is needed only if the module is split into different source files, but that is not uncommon with modules. The modules are joined through the ld -r command, which is not really a linking operation, even though it uses the linker. This is because the output is another object file, which incorporates all the code from the input files. The -r option means ``relocatable''; the output file is relocatable because it doesn’t yet embed absolute addresses.

The following Makefile implements all the features described above, and it builds a module made up of two source files. If your module is made up of a single source file, just skip the entry containing ld -r.

# Change it here or specify it on the "make" commandline
INCLUDEDIR = /usr/include

CFLAGS = -D__KERNEL__ -DMODULE -O -Wall -I$(INCLUDEDIR)

# Extract version number from headers.
VER = $(shell awk -F" '/REL/ {print $$2}'
        $(INCLUDEDIR)/linux/version.h)

OBJS = skull.o

all: $(OBJS)

skull.o: skull_init.o skull_clean.o
	$(LD) -r $^ -o $@

install:
	install -d /lib/modules/$(VER)/misc /lib/modules/misc
	install -c skull.o /lib/modules/$(VER)/misc
	install -c skull.o /lib/modules/misc

clean:
	rm -f *.o *~ core

The tricky install rule in the file above is meant to install the module in a version-dependent directory, as explained below. The VER variable in Makefile is set to the correct version number, extracted from <linux/version.h>.

Next, after the module is built, it must be loaded into the kernel. As I’ve already suggested, insmod does the job for you. The program is like ld, as 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 the in-memory image. insmod accepts a number of command-line options (for details, see the man page), and it can change the value of integer and string variables in your module before linking the module 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 unfortunately is still used sometimes. Load-time configuration is explained in Section 2.6, later in this chapter.

Interested readers may want to look at how the kernel supports insmod: it relies on a few system calls defined in kernel/module.c. sys_create_module allocates kernel memory to hold a module (this memory is allocated with vmalloc; see Section 7.3 in Chapter 7), the system call get_kernel_syms returns the kernel symbol table in order to link the module, and sys_init_module copies the relocated object code to kernel space and calls the module’s initialization function.

If you actually look in the kernel source, you’ll find that the name of the system calls is prefixed with sys_. This is true for all system calls and no other functions; it’s useful to keep this in mind when grepping for the system calls in the sources.

#define __NO_VERSION__ /* don't define kernel_version in module.h */
#include <linux/module.h>
#include <linux/version.h>

char kernel_version [] = UTS_RELEASE;

#define VERSION_CODE(vers,rel,seq) (((vers)<<16) | ((rel)<<8) | (seq))