@@ -1,11 +1,11 @@
Building External Modules
-This document describes how-to build an out-of-tree kernel module.
+This document describes how to build an out-of-tree kernel module.
=== Table of Contents
=== 1 Introduction
- === 2 How-to Build External Modules
+ === 2 How to Build External Modules
--- 2.1 Command Syntax
--- 2.2 Options
--- 2.3 Targets
@@ -48,9 +48,9 @@ easily accomplished, and a complete example will be presented in
section 3.
-=== 2. How-to Build External Modules
+=== 2. How to Build External Modules
-To build external modules, you must have a pre-built kernel available
+To build external modules, you must have a prebuilt kernel available
that contains the configuration and header files used in the build.
Also, the kernel must have been built with modules enabled. If you are
using a distribution kernel, there will be a package for the kernel you
@@ -69,19 +69,19 @@ executed to make module versioning work.
The command to build an external module is:
- make -C <path_to_kernel_src> M=$PWD
+ $ make -C <path_to_kernel_src> M=$PWD
The kbuild system knows that an external module is being built
due to the "M=<dir>" option given in the command.
To build against the running kernel use:
- make -C /lib/modules/`uname -r`/build M=$PWD
+ $ make -C /lib/modules/`uname -r`/build M=$PWD
Then to install the module(s) just built, add the target
"modules_install" to the command:
- make -C /lib/modules/`uname -r`/build M=$PWD modules_install
+ $ make -C /lib/modules/`uname -r`/build M=$PWD modules_install
--- 2.2 Options
@@ -121,7 +121,7 @@ executed to make module versioning work.
modules_install
Install the external module(s). The default location is
- /lib/modules/<kernel_release>/extra, but a prefix may
+ /lib/modules/<kernel_release>/extra/, but a prefix may
be added with INSTALL_MOD_PATH (discussed in section 5).
clean
@@ -164,7 +164,7 @@ needed listing the files:
NOTE: Further documentation describing the syntax used by kbuild is
located in Documentation/kbuild/makefiles.txt.
-The examples below demonstrate how-to create a build file for the
+The examples below demonstrate how to create a build file for the
module 8123.ko, which is built from the following files:
8123_if.c
@@ -205,14 +205,14 @@ module 8123.ko, which is built from the following files:
of the makefile. In the example, kbuild will only see the two
assignments, whereas "make" will see everything except these
two assignments. This is due to two passes made on the file:
- the first pass is by the "make" instance run on the
- command line; the second pass is by the kbuild system, which is
+ the first pass is by the "make" instance run on the command
+ line; the second pass is by the kbuild system, which is
initiated by the parameterized "make" in the default target.
--- 3.2 Separate Kbuild File and Makefile
In newer versions of the kernel, kbuild will first look for a
- file named "Kbuild", and only if that is not found, will it
+ file named "Kbuild," and only if that is not found, will it
then look for a makefile. Utilizing a "Kbuild" file allows us
to split up the makefile from example 1 into two files:
@@ -288,8 +288,8 @@ module 8123.ko, which is built from the following files:
--- 3.4 Building Multiple Modules
kbuild supports building multiple modules with a single build
- file. For example, if you want to build two modules, foo and
- bar, the kbuild lines would be:
+ file. For example, if you wanted to build two modules, foo.ko
+ and bar.ko, the kbuild lines would be:
obj-m := foo.o bar.o
foo-y := <foo_srcs>
@@ -320,7 +320,7 @@ according to the following rule:
To include a header file located under include/linux/, simply
use:
- #include <linux/modules.h>
+ #include <linux/module.h>
kbuild will add options to "gcc" so the relevant directories
are searched.
@@ -330,7 +330,7 @@ according to the following rule:
External modules tend to place header files in a separate
include/ directory where their source is located, although this
is not the usual kernel style. To inform kbuild of the
- directory use either ccflags-y or CFLAGS_<filename>.o.
+ directory, use either ccflags-y or CFLAGS_<filename>.o.
Using the example from section 3, if we moved 8123_if.h to a
subdirectory named include, the resulting kbuild file would
@@ -390,11 +390,11 @@ according to the following rule:
Modules which are included in the kernel are installed in the
directory:
- /lib/modules/$(KERNELRELEASE)/kernel
+ /lib/modules/$(KERNELRELEASE)/kernel/
And external modules are installed in:
- /lib/modules/$(KERNELRELEASE)/extra
+ /lib/modules/$(KERNELRELEASE)/extra/
--- 5.1 INSTALL_MOD_PATH
@@ -403,7 +403,7 @@ And external modules are installed in:
installation path using the variable INSTALL_MOD_PATH:
$ make INSTALL_MOD_PATH=/frodo modules_install
- => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel
+ => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/
INSTALL_MOD_PATH may be set as an ordinary shell variable or,
as shown above, can be specified on the command line when
@@ -413,14 +413,14 @@ And external modules are installed in:
--- 5.2 INSTALL_MOD_DIR
External modules are by default installed to a directory under
- /lib/modules/$(KERNELRELEASE)/extra, but you may wish to locate
- modules for a specific functionality in a separate directory.
- For this purpose, use INSTALL_MOD_DIR to specify an alternative
- name to "extra."
+ /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to
+ locate modules for a specific functionality in a separate
+ directory. For this purpose, use INSTALL_MOD_DIR to specify an
+ alternative name to "extra."
$ make INSTALL_MOD_DIR=gandalf -C $KDIR \
M=$PWD modules_install
- => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf
+ => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/
=== 6. Module Versioning
@@ -478,9 +478,9 @@ build.
Use a top-level kbuild file
If you have two modules, foo.ko and bar.ko, where
- foo.ko needs symbols from bar.ko, then you can use a
+ foo.ko needs symbols from bar.ko, you can use a
common top-level kbuild file so both modules are
- compiled in the same build. Consider following
+ compiled in the same build. Consider the following
directory layout:
./foo/ <= contains foo.ko
@@ -491,10 +491,11 @@ build.
#./Kbuild (or ./Makefile):
obj-y := foo/ bar/
- And executing:
+ And executing
+
$ make -C $KDIR M=$PWD
- Will then do the expected and compile both modules with
+ will then do the expected and compile both modules with
full knowledge of symbols from either module.
Use an extra Module.symvers file
@@ -512,10 +513,11 @@ build.
Use "make" variable KBUILD_EXTRA_SYMBOLS
If it is impractical to copy Module.symvers from
another module, you can assign a space separated list
- of files to KBUILD_EXTRA_SYMBOLS in your build
- file. These files will be loaded by modpost during the
+ of files to KBUILD_EXTRA_SYMBOLS in your build file.
+ These files will be loaded by modpost during the
initialization of its symbol tables.
+
=== 7. Tips & Tricks
--- 7.1 Testing for CONFIG_FOO_BAR