modules.txt

linux 内核源代码

In this document you will find information about:
- how to build external modules
- how to make your module use the kbuild infrastructure
- how kbuild will install a kernel
- how to install modules in a non-standard location

=== Table of Contents

	=== 1 Introduction
	=== 2 How to build external modules
	   --- 2.1 Building external modules
	   --- 2.2 Available targets
	   --- 2.3 Available options
	   --- 2.4 Preparing the kernel tree for module build
	   --- 2.5 Building separate files for a module
	=== 3. Example commands
	=== 4. Creating a kbuild file for an external module
	=== 5. Include files
	   --- 5.1 How to include files from the kernel include dir
	   --- 5.2 External modules using an include/ dir
	   --- 5.3 External modules using several directories
	=== 6. Module installation
	   --- 6.1 INSTALL_MOD_PATH
	   --- 6.2 INSTALL_MOD_DIR
	=== 7. Module versioning & Module.symvers
	   --- 7.1 Symbols from the kernel (vmlinux + modules)
	   --- 7.2 Symbols and external modules
	   --- 7.3 Symbols from another external module
	=== 8. Tips & Tricks
	   --- 8.1 Testing for CONFIG_FOO_BAR



=== 1. Introduction

kbuild includes functionality for building modules both
within the kernel source tree and outside the kernel source tree.
The latter is usually referred to as external or "out-of-tree"
modules and is used both during development and for modules that
are not planned to be included in the kernel tree.

What is covered within this file is mainly information to authors
of modules. The author of an external module should supply
a makefile that hides most of the complexity, so one only has to type
'make' to build the module. A complete example will be presented in
chapter 4, "Creating a kbuild file for an external module".


=== 2. How to build external modules

kbuild offers functionality to build external modules, with the
prerequisite that there is a pre-built kernel available with full source.
A subset of the targets available when building the kernel is available
when building an external module.

--- 2.1 Building external modules

	Use the following command to build an external module:

		make -C <path-to-kernel> M=`pwd`

	For the running kernel use:

		make -C /lib/modules/`uname -r`/build M=`pwd`

	For the above command to succeed, the kernel must have been
	built with modules enabled.

	To install the modules that were just built:

		make -C <path-to-kernel> M=`pwd` modules_install

	More complex examples will be shown later, the above should
	be enough to get you started.

--- 2.2 Available targets

	$KDIR refers to the path to the kernel source top-level directory

	make -C $KDIR M=`pwd`
		Will build the module(s) located in current directory.
		All output files will be located in the same directory
		as the module source.
		No attempts are made to update the kernel source, and it is
		a precondition that a successful make has been executed
		for the kernel.

	make -C $KDIR M=`pwd` modules
		The modules target is implied when no target is given.
		Same functionality as if no target was specified.
		See description above.

	make -C $KDIR M=`pwd` modules_install
		Install the external module(s).
		Installation default is in /lib/modules/<kernel-version>/extra,
		but may be prefixed with INSTALL_MOD_PATH - see separate
		chapter.

	make -C $KDIR M=`pwd` clean
		Remove all generated files for the module - the kernel
		source directory is not modified.

	make -C $KDIR M=`pwd` help
		help will list the available target when building external
		modules.

--- 2.3 Available options:

	$KDIR refers to the path to the kernel source top-level directory

	make -C $KDIR
		Used to specify where to find the kernel source.
		'$KDIR' represent the directory where the kernel source is.
		Make will actually change directory to the specified directory
		when executed but change back when finished.

	make -C $KDIR M=`pwd`
		M= is used to tell kbuild that an external module is
		being built.
		The option given to M= is the directory where the external
		module (kbuild file) is located.
		When an external module is being built only a subset of the
		usual targets are available.

	make -C $KDIR SUBDIRS=`pwd`
		Same as M=. The SUBDIRS= syntax is kept for backwards
		compatibility.

--- 2.4 Preparing the kernel tree for module build

	To make sure the kernel contains the information required to
	build external modules the target 'modules_prepare' must be used.
	'modules_prepare' exists solely as a simple way to prepare
	a kernel source tree for building external modules.
	Note: modules_prepare will not build Module.symvers even if
	CONFIG_MODVERSIONS is set. Therefore a full kernel build
	needs to be executed to make module versioning work.

--- 2.5 Building separate files for a module
	It is possible to build single files which are part of a module.
	This works equally well for the kernel, a module and even for
	external modules.
	Examples (module foo.ko, consist of bar.o, baz.o):
		make -C $KDIR M=`pwd` bar.lst
		make -C $KDIR M=`pwd` bar.o
		make -C $KDIR M=`pwd` foo.ko
		make -C $KDIR M=`pwd` /


=== 3. Example commands

This example shows the actual commands to be executed when building
an external module for the currently running kernel.
In the example below, the distribution is supposed to use the
facility to locate output files for a kernel compile in a different
directory than the kernel source - but the examples will also work
when the source and the output files are mixed in the same directory.

# Kernel source
/lib/modules/<kernel-version>/source -> /usr/src/linux-<version>

# Output from kernel compile
/lib/modules/<kernel-version>/build -> /usr/src/linux-<version>-up

Change to the directory where the kbuild file is located and execute
the following commands to build the module:

	cd /home/user/src/module
	make -C /usr/src/`uname -r`/source            \
	        O=/lib/modules/`uname-r`/build        \
	        M=`pwd`

Then, to install the module use the following command:

	make -C /usr/src/`uname -r`/source            \
	        O=/lib/modules/`uname-r`/build        \
	        M=`pwd`                               \
		modules_install

If you look closely you will see that this is the same command as
listed before - with the directories spelled out.

The above are rather long commands, and the following chapter
lists a few tricks to make it all easier.


=== 4. Creating a kbuild file for an external module

kbuild is the build system for the kernel, and external modules
must use kbuild to stay compatible with changes in the build system
and to pick up the right flags to gcc etc.

The kbuild file used as input shall follow the syntax described
in Documentation/kbuild/makefiles.txt. This chapter will introduce a few
more tricks to be used when dealing with external modules.

In the following a Makefile will be created for a module with the
following files:
	8123_if.c
	8123_if.h
	8123_pci.c
	8123_bin.o_shipped	<= Binary blob

--- 4.1 Shared Makefile for module and kernel

	An external module always includes a wrapper Makefile supporting
	building the module using 'make' with no arguments.
	The Makefile provided will most likely include additional
	functionality such as test targets etc. and this part shall
	be filtered away from kbuild since it may impact kbuild if
	name clashes occurs.

	Example 1:
		--> filename: Makefile
		ifneq ($(KERNELRELEASE),)
		# kbuild part of makefile
		obj-m  := 8123.o
		8123-y := 8123_if.o 8123_pci.o 8123_bin.o

		else
		# Normal Makefile

		KERNELDIR := /lib/modules/`uname -r`/build
		all::
			$(MAKE) -C $(KERNELDIR) M=`pwd` $@

		# Module specific targets
		genbin:
			echo "X" > 8123_bin.o_shipped

		endif

	In example 1, the check for KERNELRELEASE is used to separate
	the two parts of the Makefile. kbuild will only see the two
	assignments whereas make will see everything except the two
	kbuild assignments.

	In recent versions of the kernel, kbuild will look for a file named
	Kbuild and as second option look for a file named Makefile.
	Utilising the Kbuild file makes us split up the Makefile in example 1
	into two files as shown in example 2:

	Example 2:
		--> filename: Kbuild
		obj-m  := 8123.o
		8123-y := 8123_if.o 8123_pci.o 8123_bin.o

		--> filename: Makefile
		KERNELDIR := /lib/modules/`uname -r`/build
		all::
			$(MAKE) -C $(KERNELDIR) M=`pwd` $@

		# Module specific targets
		genbin:
			echo "X" > 8123_bin_shipped


	In example 2, we are down to two fairly simple files and for simple
	files as used in this example the split is questionable. But some
	external modules use Makefiles of several hundred lines and here it
	really pays off to separate the kbuild part from the rest.
	Example 3 shows a backward compatible version.

	Example 3:
		--> filename: Kbuild
		obj-m  := 8123.o
		8123-y := 8123_if.o 8123_pci.o 8123_bin.o

		--> filename: Makefile
		ifneq ($(KERNELRELEASE),)
		include Kbuild
		else