@@ -4,8 +4,8 @@ Building External Modules
This document describes how to build an out-of-tree kernel module.
-1. Introduction
-===============
+Introduction
+============
"kbuild" is the build system used by the Linux kernel. Modules must use
kbuild to stay compatible with changes in the build infrastructure and
@@ -19,11 +19,11 @@ in building out-of-tree (or "external") 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. This is
easily accomplished, and a complete example will be presented in
-section 3.
+section `Creating a Kbuild File for an External Module`_.
-2. How to Build External Modules
-================================
+How to Build External Modules
+=============================
To build external modules, you must have a prebuilt kernel available
that contains the configuration and header files used in the build.
@@ -40,8 +40,8 @@ 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.1 Command Syntax
-==================
+Command Syntax
+--------------
The command to build an external module is::
@@ -59,8 +59,8 @@ executed to make module versioning work.
$ make -C /lib/modules/`uname -r`/build M=$PWD modules_install
-2.2 Options
-===========
+Options
+-------
($KDIR refers to the path of the kernel source directory.)
@@ -77,8 +77,8 @@ executed to make module versioning work.
directory where the external module (kbuild file) is
located.
-2.3 Targets
-===========
+Targets
+-------
When building an external module, only a subset of the "make"
targets are available.
@@ -100,7 +100,8 @@ executed to make module versioning work.
modules_install
Install the external module(s). The default location is
/lib/modules/<kernel_release>/updates/, but a prefix may
- be added with INSTALL_MOD_PATH (discussed in section 5).
+ be added with INSTALL_MOD_PATH (discussed in section
+ `Module Installation`_).
clean
Remove all generated files in the module directory only.
@@ -108,8 +109,8 @@ executed to make module versioning work.
help
List the available targets for external modules.
-2.4 Building Separate Files
-===========================
+Building Separate Files
+-----------------------
It is possible to build single files that are part of a module.
This works equally well for the kernel, a module, and even for
@@ -123,8 +124,8 @@ executed to make module versioning work.
make -C $KDIR M=$PWD ./
-3. Creating a Kbuild File for an External Module
-================================================
+Creating a Kbuild File for an External Module
+=============================================
In the last section we saw the command to build a module for the
running kernel. The module is not actually built, however, because a
@@ -153,8 +154,8 @@ module 8123.ko, which is built from the following files::
8123_pci.c
8123_bin.o_shipped <= Binary blob
-3.1 Shared Makefile
--------------------
+Shared Makefile
+---------------
An external module always includes a wrapper makefile that
supports building the module using "make" with no arguments.
@@ -192,8 +193,8 @@ module 8123.ko, which is built from the following files::
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
--------------------------------------
+Separate Kbuild File and Makefile
+---------------------------------
Kbuild will first look for a file named "Kbuild", and if it is not
found, it will then look for "Makefile". Utilizing a "Kbuild" file
@@ -220,8 +221,8 @@ module 8123.ko, which is built from the following files::
consisting of several hundred lines, and here it really pays
off to separate the kbuild part from the rest.
-3.3 Binary Blobs
-----------------
+Binary Blobs
+------------
Some external modules need to include an object file as a blob.
kbuild has support for this, but requires the blob file to be
@@ -240,8 +241,8 @@ module 8123.ko, which is built from the following files::
files and the binary file, kbuild will pick up different rules
when creating the object file for the module.
-3.4 Building Multiple Modules
-=============================
+Building Multiple Modules
+-------------------------
kbuild supports building multiple modules with a single build
file. For example, if you wanted to build two modules, foo.ko
@@ -254,8 +255,8 @@ module 8123.ko, which is built from the following files::
It is that simple!
-4. Include Files
-================
+Include Files
+=============
Within the kernel, header files are kept in standard locations
according to the following rule:
@@ -273,8 +274,8 @@ according to the following rule:
include/scsi; and architecture specific headers are located
under arch/$(SRCARCH)/include/.
-4.1 Kernel Includes
--------------------
+Kernel Includes
+---------------
To include a header file located under include/linux/, simply
use::
@@ -284,8 +285,8 @@ according to the following rule:
kbuild will add options to "gcc" so the relevant directories
are searched.
-4.2 Single Subdirectory
------------------------
+Single Subdirectory
+-------------------
External modules tend to place header files in a separate
include/ directory where their source is located, although this
@@ -302,8 +303,8 @@ according to the following rule:
ccflags-y := -I $(src)/include
8123-y := 8123_if.o 8123_pci.o 8123_bin.o
-4.3 Several Subdirectories
---------------------------
+Several Subdirectories
+----------------------
kbuild can handle files that are spread over several directories.
Consider the following example::
@@ -342,8 +343,8 @@ according to the following rule:
file is located.
-5. Module Installation
-======================
+Module Installation
+===================
Modules which are included in the kernel are installed in the
directory:
@@ -354,8 +355,8 @@ And external modules are installed in:
/lib/modules/$(KERNELRELEASE)/updates/
-5.1 INSTALL_MOD_PATH
---------------------
+INSTALL_MOD_PATH
+----------------
Above are the default directories but as always some level of
customization is possible. A prefix can be added to the
@@ -369,8 +370,8 @@ And external modules are installed in:
calling "make." This has effect when installing both in-tree
and out-of-tree modules.
-5.2 INSTALL_MOD_DIR
--------------------
+INSTALL_MOD_DIR
+---------------
External modules are by default installed to a directory under
/lib/modules/$(KERNELRELEASE)/updates/, but you may wish to
@@ -383,8 +384,8 @@ And external modules are installed in:
=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/
-6. Module Versioning
-====================
+Module Versioning
+=================
Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used
as a simple ABI consistency check. A CRC value of the full prototype
@@ -396,8 +397,8 @@ module.
Module.symvers contains a list of all exported symbols from a kernel
build.
-6.1 Symbols From the Kernel (vmlinux + modules)
------------------------------------------------
+Symbols From the Kernel (vmlinux + modules)
+-------------------------------------------
During a kernel build, a file named Module.symvers will be
generated. Module.symvers contains all exported symbols from
@@ -421,8 +422,8 @@ build.
1) It lists all exported symbols from vmlinux and all modules.
2) It lists the CRC if CONFIG_MODVERSIONS is enabled.
-6.2 Symbols and External Modules
---------------------------------
+Symbols and External Modules
+----------------------------
When building an external module, the build system needs access
to the symbols from the kernel to check if all external symbols
@@ -431,8 +432,8 @@ build.
tree. During the MODPOST step, a new Module.symvers file will be
written containing all exported symbols from that external module.
-6.3 Symbols From Another External Module
-----------------------------------------
+Symbols From Another External Module
+------------------------------------
Sometimes, an external module uses exported symbols from
another external module. Kbuild needs to have full knowledge of
@@ -472,11 +473,11 @@ build.
initialization of its symbol tables.
-7. Tips & Tricks
-================
+Tips & Tricks
+=============
-7.1 Testing for CONFIG_FOO_BAR
-------------------------------
+Testing for CONFIG_FOO_BAR
+--------------------------
Modules often need to check for certain `CONFIG_` options to
decide if a specific feature is included in the module. In
Do similar to commit 1a4c1c9df72e ("docs/kbuild/makefiles: drop section numbering, use references"). Signed-off-by: Masahiro Yamada <masahiroy@kernel.org> --- Changes in v2: - New patch Documentation/kbuild/modules.rst | 101 ++++++++++++++++--------------- 1 file changed, 51 insertions(+), 50 deletions(-)