mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
synced 2025-01-01 10:43:43 +00:00
kbuild: doc: drop section numbering, use references in modules.rst
Do similar to commit 1a4c1c9df7 ("docs/kbuild/makefiles: drop section
numbering, use references").
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
This commit is contained in:
Masahiro Yamada
parent
7813cd68ea
commit
803d505952
@ -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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user