Skip to content

L
linux
Commit efdf02cf authored by matt mooney's avatar matt mooney Committed by Michal Marek
Browse files
Options

Documentation/kbuild: major edit of modules.txt sections 1-4 

Omit needless words and sentences; reorganize and tighten sentence structure;
swap sections 2.2 and 2.3 for a more logical flow; remove section 3, therefore
shifting 4->3; add to explanations; and add section on building multiple modules.
Signed-off-by: default avatarmatt mooney <mfm@muteddisk.com>
Signed-off-by: default avatarMichal Marek <mmarek@suse.cz>
parent 49ab7a39
Hide whitespace changes
Inline Side-by-side
Showing with 189 additions and 198 deletions
Documentation/kbuild/modules.txt
View file @ efdf02cf
Building External Modules
In this document you will find information about: This document describes how-to build an out-of-tree kernel module.
- 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 === Table of Contents
=== 1 Introduction === 1 Introduction
=== 2 How to build external modules === 2 How-to Build External Modules
--- 2.1 Building external modules --- 2.1 Command Syntax
--- 2.2 Available targets --- 2.2 Options
--- 2.3 Available options --- 2.3 Targets
--- 2.4 Preparing the kernel tree for module build --- 2.4 Building Separate Files
--- 2.5 Building separate files for a module === 3. Creating a Kbuild File for an External Module
=== 3. Example commands --- 3.1 Shared Makefile
=== 4. Creating a kbuild file for an external module --- 3.2 Separate Kbuild file and Makefile
=== 5. Include files --- 3.3 Binary Blobs
--- 5.1 How to include files from the kernel include dir --- 3.4 Building Multiple Modules
--- 5.2 External modules using an include/ dir === 4. Include files
--- 5.3 External modules using several directories --- 4.1 How to include files from the kernel include dir
=== 6. Module installation --- 4.2 External modules using an include/ dir
--- 6.1 INSTALL_MOD_PATH --- 4.3 External modules using several directories
--- 6.2 INSTALL_MOD_DIR === 5. Module installation
=== 7. Module versioning & Module.symvers --- 5.1 INSTALL_MOD_PATH
--- 7.1 Symbols from the kernel (vmlinux + modules) --- 5.2 INSTALL_MOD_DIR
--- 7.2 Symbols and external modules === 6. Module versioning & Module.symvers
--- 7.3 Symbols from another external module --- 6.1 Symbols from the kernel (vmlinux + modules)
=== 8. Tips & Tricks --- 6.2 Symbols and external modules
--- 8.1 Testing for CONFIG_FOO_BAR --- 6.3 Symbols from another external module
=== 7. Tips & Tricks
--- 7.1 Testing for CONFIG_FOO_BAR
=== 1. Introduction === 1. Introduction
kbuild includes functionality for building modules both "kbuild" is the build system used by the Linux kernel. Modules must use
within the kernel source tree and outside the kernel source tree. kbuild to stay compatible with changes in the build infrastructure and
The latter is usually referred to as external or "out-of-tree" to pick up the right flags to "gcc." Functionality for building modules
modules and is used both during development and for modules that both in-tree and out-of-tree is provided. The method for building
are not planned to be included in the kernel tree. either is similar, and all modules are initially developed and built
out-of-tree.
What is covered within this file is mainly information to authors Covered in this document is information aimed at developers interested
of modules. The author of an external module should supply in building out-of-tree (or "external") modules. The author of an
a makefile that hides most of the complexity, so one only has to type external module should supply a makefile that hides most of the
'make' to build the module. A complete example will be presented in complexity, so one only has to type "make" to build the module. This is
chapter 4, "Creating a kbuild file for an external module". easily accomplished, and a complete example will be presented in
section 3.
=== 2. How to build external modules === 2. How-to Build External Modules
kbuild offers functionality to build external modules, with the To build external modules, you must have a pre-built kernel available
prerequisite that there is a pre-built kernel available with full source. that contains the configuration and header files used in the build.
A subset of the targets available when building the kernel is available Also, the kernel must have been built with modules enabled. If you are
when building an external module. using a distribution kernel, there will be a package for the kernel you
are running provided by your distribution.
--- 2.1 Building external modules An alternative is to use the "make" target "modules_prepare." This will
make sure the kernel contains the information required. The target
exists solely as a simple way to prepare a kernel source tree for
building external modules.
Use the following command to build an external module: 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.
make -C <path-to-kernel> M=`pwd` --- 2.1 Command Syntax
For the running kernel use: The command to build an external module is:
make -C /lib/modules/`uname -r`/build M=`pwd` make -C <path_to_kernel_src> M=$PWD
For the above command to succeed, the kernel must have been The kbuild system knows that an external module is being built
built with modules enabled. due to the "M=<dir>" option given in the command.
To install the modules that were just built: To build against the running kernel use:
make -C <path-to-kernel> M=`pwd` modules_install make -C /lib/modules/`uname -r`/build M=$PWD
More complex examples will be shown later, the above should Then to install the module(s) just built, add the target
be enough to get you started. "modules_install" to the command:
--- 2.2 Available targets make -C /lib/modules/`uname -r`/build M=$PWD modules_install
$KDIR refers to the path to the kernel source top-level directory --- 2.2 Options
make -C $KDIR M=`pwd` ($KDIR refers to the path of the kernel source directory.)
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 make -C $KDIR M=$PWD
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 -C $KDIR
Install the external module(s). The directory where the kernel source is located.
Installation default is in /lib/modules/<kernel-version>/extra, "make" will actually change to the specified directory
but may be prefixed with INSTALL_MOD_PATH - see separate when executing and will change back when finished.
chapter.
make -C $KDIR M=`pwd` clean M=$PWD
Remove all generated files for the module - the kernel Informs kbuild that an external module is being built.
source directory is not modified. The value given to "M" is the absolute path of the
directory where the external module (kbuild file) is
located.
make -C $KDIR M=`pwd` help --- 2.3 Targets
help will list the available target when building external
modules.
--- 2.3 Available options: When building an external module, only a subset of the "make"
targets are available.
$KDIR refers to the path to the kernel source top-level directory make -C $KDIR M=$PWD [target]
make -C $KDIR The default will build the module(s) located in the current
Used to specify where to find the kernel source. directory, so a target does not need to be specified. All
'$KDIR' represent the directory where the kernel source is. output files will also be generated in this directory. No
Make will actually change directory to the specified directory attempts are made to update the kernel source, and it is a
when executed but change back when finished. precondition that a successful "make" has been executed for the
kernel.
make -C $KDIR M=`pwd` modules
M= is used to tell kbuild that an external module is The default target for external modules. It has the
being built. same functionality as if no target was specified. See
The option given to M= is the directory where the external description above.
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` modules_install
Same as M=. The SUBDIRS= syntax is kept for backwards Install the external module(s). The default location is
compatibility. /lib/modules/<kernel_release>/extra, but a prefix may
be added with INSTALL_MOD_PATH (discussed in section 5).
--- 2.4 Preparing the kernel tree for module build clean
Remove all generated files in the module directory only.
To make sure the kernel contains the information required to help
build external modules the target 'modules_prepare' must be used. List the available targets for external modules.
'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 --- 2.4 Building Separate Files
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 It is possible to build single files that are part of a module.
/lib/modules/<kernel-version>/build -> /usr/src/linux-<version>-up This works equally well for the kernel, a module, and even for
external modules.
Change to the directory where the kbuild file is located and execute
the following commands to build the module:
cd /home/user/src/module Example (The module foo.ko, consist of bar.o and baz.o):
make -C /usr/src/`uname -r`/source \ make -C $KDIR M=$PWD bar.lst
O=/lib/modules/`uname-r`/build \ make -C $KDIR M=$PWD baz.o
M=`pwd` make -C $KDIR M=$PWD foo.ko
make -C $KDIR M=$PWD /
Then, to install the module use the following command:
make -C /usr/src/`uname -r`/source \ === 3. Creating a Kbuild File for an External Module
O=/lib/modules/`uname-r`/build \
M=`pwd` \
modules_install
If you look closely you will see that this is the same command as In the last section we saw the command to build a module for the
listed before - with the directories spelled out. running kernel. The module is not actually built, however, because a
build file is required. Contained in this file will be the name of
the module(s) being built, along with the list of requisite source
files. The file may be as simple as a single line:
The above are rather long commands, and the following chapter obj-m := <module_name>.o
lists a few tricks to make it all easier.
The kbuild system will build <module_name>.o from <module_name>.c,
and, after linking, will result in the kernel module <module_name>.ko.
The above line can be put in either a "Kbuild" file or a "Makefile."
When the module is built from multiple sources, an additional line is
needed listing the files:
=== 4. Creating a kbuild file for an external module <module_name>-y := <src1>.o <src2>.o ...
kbuild is the build system for the kernel, and external modules NOTE: Further documentation describing the syntax used by kbuild is
must use kbuild to stay compatible with changes in the build system located in Documentation/kbuild/makefiles.txt.
and to pick up the right flags to gcc etc.
The kbuild file used as input shall follow the syntax described The examples below demonstrate how-to create a build file for the
in Documentation/kbuild/makefiles.txt. This chapter will introduce a few module 8123.ko, which is built from the following files:
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.c
8123_if.h 8123_if.h
8123_pci.c 8123_pci.c
8123_bin.o_shipped <= Binary blob 8123_bin.o_shipped <= Binary blob
--- 4.1 Shared Makefile for module and kernel --- 3.1 Shared Makefile
An external module always includes a wrapper Makefile supporting An external module always includes a wrapper makefile that
building the module using 'make' with no arguments. supports building the module using "make" with no arguments.
The Makefile provided will most likely include additional This target is not used by kbuild; it is only for convenience.
functionality such as test targets etc. and this part shall Additional functionality, such as test targets, can be included
be filtered away from kbuild since it may impact kbuild if but should be filtered out from kbuild due to possible name
name clashes occurs. clashes.
Example 1: Example 1:
--> filename: Makefile --> filename: Makefile
...@@ -219,11 +189,11 @@ following files: ...@@ -219,11 +189,11 @@ following files:
8123-y := 8123_if.o 8123_pci.o 8123_bin.o 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
else else
# Normal Makefile # normal makefile
KDIR ?= /lib/modules/`uname -r`/build
KERNELDIR := /lib/modules/`uname -r`/build default:
all:: $(MAKE) -C $(KDIR) M=$$PWD
$(MAKE) -C $(KERNELDIR) M=`pwd` $@
# Module specific targets # Module specific targets
genbin: genbin:
...@@ -231,15 +201,20 @@ following files: ...@@ -231,15 +201,20 @@ following files:
endif endif
In example 1, the check for KERNELRELEASE is used to separate The check for KERNELRELEASE is used to separate the two parts
the two parts of the Makefile. kbuild will only see the two of the makefile. In the example, kbuild will only see the two
assignments whereas make will see everything except the two assignments, whereas "make" will see everything except these
kbuild assignments. 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
initiated by the parameterized "make" in the default target.
In recent versions of the kernel, kbuild will look for a file named --- 3.2 Separate Kbuild File and Makefile
Kbuild and as second option look for a file named Makefile.
Utilising the Kbuild file makes us split up the Makefile in example 1 In newer versions of the kernel, kbuild will first look for a
into two files as shown in example 2: 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:
Example 2: Example 2:
--> filename: Kbuild --> filename: Kbuild
...@@ -247,20 +222,21 @@ following files: ...@@ -247,20 +222,21 @@ following files:
8123-y := 8123_if.o 8123_pci.o 8123_bin.o 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
--> filename: Makefile --> filename: Makefile
KERNELDIR := /lib/modules/`uname -r`/build KDIR ?= /lib/modules/`uname -r`/build
all::
$(MAKE) -C $(KERNELDIR) M=`pwd` $@ default:
$(MAKE) -C $(KDIR) M=$$PWD
# Module specific targets # Module specific targets
genbin: genbin:
echo "X" > 8123_bin.o_shipped echo "X" > 8123_bin.o_shipped
The split in example 2 is questionable due to the simplicity of
each file; however, some external modules use makefiles
consisting of several hundred lines, and here it really pays
off to separate the kbuild part from the rest.
In example 2, we are down to two fairly simple files and for simple The next example shows a backward compatible version.
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: Example 3:
--> filename: Kbuild --> filename: Kbuild
...@@ -269,13 +245,15 @@ following files: ...@@ -269,13 +245,15 @@ following files:
--> filename: Makefile --> filename: Makefile
ifneq ($(KERNELRELEASE),) ifneq ($(KERNELRELEASE),)
# kbuild part of makefile
include Kbuild include Kbuild
else else
# Normal Makefile # normal makefile
KDIR ?= /lib/modules/`uname -r`/build
KERNELDIR := /lib/modules/`uname -r`/build default:
all:: $(MAKE) -C $(KDIR) M=$$PWD
$(MAKE) -C $(KERNELDIR) M=`pwd` $@
# Module specific targets # Module specific targets
genbin: genbin:
...@@ -283,28 +261,41 @@ following files: ...@@ -283,28 +261,41 @@ following files:
endif endif
The trick here is to include the Kbuild file from Makefile, so Here the "Kbuild" file is included from the makefile. This
if an older version of kbuild picks up the Makefile, the Kbuild allows an older version of kbuild, which only knows of
file will be included. makefiles, to be used when the "make" and kbuild parts are
split into separate files.
--- 4.2 Binary blobs included in a module --- 3.3 Binary Blobs
Some external modules needs to include a .o as a blob. kbuild Some external modules need to include an object file as a blob.
has support for this, but requires the blob file to be named kbuild has support for this, but requires the blob file to be
<filename>_shipped. In our example the blob is named named <filename>_shipped. When the kbuild rules kick in, a copy
8123_bin.o_shipped and when the kbuild rules kick in the file of <filename>_shipped is created with _shipped stripped off,
8123_bin.o is created as a simple copy off the 8213_bin.o_shipped file giving us <filename>. This shortened filename can be used in
with the _shipped part stripped of the filename. the assignment to the module.
This allows the 8123_bin.o filename to be used in the assignment to
the module. Throughout this section, 8123_bin.o_shipped has been used to
build the kernel module 8123.ko; it has been included as
8123_bin.o.
Example 4:
obj-m := 8123.o
8123-y := 8123_if.o 8123_pci.o 8123_bin.o 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
In example 4, there is no distinction between the ordinary .c/.h files Although there is no distinction between the ordinary source
and the binary file. But kbuild will pick up different rules to create files and the binary file, kbuild will pick up different rules
the .o file. when creating the object file for the module.
--- 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:
obj-m := foo.o bar.o
foo-y := <foo_srcs>
bar-y := <bar_srcs>
It is that simple!
=== 5. Include files === 5. Include files
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7