mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
561 lines
17 KiB
561 lines
17 KiB
========================= |
|
Building External Modules |
|
========================= |
|
|
|
This document describes how to build an out-of-tree kernel module. |
|
|
|
.. Table of Contents |
|
|
|
=== 1 Introduction |
|
=== 2 How to Build External Modules |
|
--- 2.1 Command Syntax |
|
--- 2.2 Options |
|
--- 2.3 Targets |
|
--- 2.4 Building Separate Files |
|
=== 3. Creating a Kbuild File for an External Module |
|
--- 3.1 Shared Makefile |
|
--- 3.2 Separate Kbuild file and Makefile |
|
--- 3.3 Binary Blobs |
|
--- 3.4 Building Multiple Modules |
|
=== 4. Include Files |
|
--- 4.1 Kernel Includes |
|
--- 4.2 Single Subdirectory |
|
--- 4.3 Several Subdirectories |
|
=== 5. Module Installation |
|
--- 5.1 INSTALL_MOD_PATH |
|
--- 5.2 INSTALL_MOD_DIR |
|
=== 6. Module Versioning |
|
--- 6.1 Symbols From the Kernel (vmlinux + modules) |
|
--- 6.2 Symbols and External Modules |
|
--- 6.3 Symbols From Another External Module |
|
=== 7. Tips & Tricks |
|
--- 7.1 Testing for CONFIG_FOO_BAR |
|
|
|
|
|
|
|
1. 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 |
|
to pick up the right flags to "gcc." Functionality for building modules |
|
both in-tree and out-of-tree is provided. The method for building |
|
either is similar, and all modules are initially developed and built |
|
out-of-tree. |
|
|
|
Covered in this document is information aimed at developers interested |
|
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. |
|
|
|
|
|
2. 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. |
|
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 |
|
are running provided by your distribution. |
|
|
|
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. |
|
|
|
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 |
|
================== |
|
|
|
The command to build an external module is:: |
|
|
|
$ 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 |
|
|
|
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 |
|
|
|
2.2 Options |
|
=========== |
|
|
|
($KDIR refers to the path of the kernel source directory.) |
|
|
|
make -C $KDIR M=$PWD |
|
|
|
-C $KDIR |
|
The directory where the kernel source is located. |
|
"make" will actually change to the specified directory |
|
when executing and will change back when finished. |
|
|
|
M=$PWD |
|
Informs kbuild that an external module is being built. |
|
The value given to "M" is the absolute path of the |
|
directory where the external module (kbuild file) is |
|
located. |
|
|
|
2.3 Targets |
|
=========== |
|
|
|
When building an external module, only a subset of the "make" |
|
targets are available. |
|
|
|
make -C $KDIR M=$PWD [target] |
|
|
|
The default will build the module(s) located in the current |
|
directory, so a target does not need to be specified. All |
|
output files will also be generated in this directory. No |
|
attempts are made to update the kernel source, and it is a |
|
precondition that a successful "make" has been executed for the |
|
kernel. |
|
|
|
modules |
|
The default target for external modules. It has the |
|
same functionality as if no target was specified. See |
|
description above. |
|
|
|
modules_install |
|
Install the external module(s). The default location is |
|
/lib/modules/<kernel_release>/extra/, but a prefix may |
|
be added with INSTALL_MOD_PATH (discussed in section 5). |
|
|
|
clean |
|
Remove all generated files in the module directory only. |
|
|
|
help |
|
List the available targets for external modules. |
|
|
|
2.4 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 |
|
external modules. |
|
|
|
Example (The module foo.ko, consist of bar.o and baz.o):: |
|
|
|
make -C $KDIR M=$PWD bar.lst |
|
make -C $KDIR M=$PWD baz.o |
|
make -C $KDIR M=$PWD foo.ko |
|
make -C $KDIR M=$PWD ./ |
|
|
|
|
|
3. 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 |
|
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:: |
|
|
|
obj-m := <module_name>.o |
|
|
|
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:: |
|
|
|
<module_name>-y := <src1>.o <src2>.o ... |
|
|
|
NOTE: Further documentation describing the syntax used by kbuild is |
|
located in Documentation/kbuild/makefiles.rst. |
|
|
|
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 |
|
8123_if.h |
|
8123_pci.c |
|
8123_bin.o_shipped <= Binary blob |
|
|
|
3.1 Shared Makefile |
|
------------------- |
|
|
|
An external module always includes a wrapper makefile that |
|
supports building the module using "make" with no arguments. |
|
This target is not used by kbuild; it is only for convenience. |
|
Additional functionality, such as test targets, can be included |
|
but should be filtered out from kbuild due to possible name |
|
clashes. |
|
|
|
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 |
|
KDIR ?= /lib/modules/`uname -r`/build |
|
|
|
default: |
|
$(MAKE) -C $(KDIR) M=$$PWD |
|
|
|
# Module specific targets |
|
genbin: |
|
echo "X" > 8123_bin.o_shipped |
|
|
|
endif |
|
|
|
The check for KERNELRELEASE is used to separate the two parts |
|
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 |
|
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 |
|
then look for a makefile. Utilizing a "Kbuild" file allows us |
|
to split up the makefile from example 1 into two files: |
|
|
|
Example 2:: |
|
|
|
--> filename: Kbuild |
|
obj-m := 8123.o |
|
8123-y := 8123_if.o 8123_pci.o 8123_bin.o |
|
|
|
--> filename: Makefile |
|
KDIR ?= /lib/modules/`uname -r`/build |
|
|
|
default: |
|
$(MAKE) -C $(KDIR) M=$$PWD |
|
|
|
# Module specific targets |
|
genbin: |
|
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. |
|
|
|
The next example 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),) |
|
# kbuild part of makefile |
|
include Kbuild |
|
|
|
else |
|
# normal makefile |
|
KDIR ?= /lib/modules/`uname -r`/build |
|
|
|
default: |
|
$(MAKE) -C $(KDIR) M=$$PWD |
|
|
|
# Module specific targets |
|
genbin: |
|
echo "X" > 8123_bin.o_shipped |
|
|
|
endif |
|
|
|
Here the "Kbuild" file is included from the makefile. This |
|
allows an older version of kbuild, which only knows of |
|
makefiles, to be used when the "make" and kbuild parts are |
|
split into separate files. |
|
|
|
3.3 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 |
|
named <filename>_shipped. When the kbuild rules kick in, a copy |
|
of <filename>_shipped is created with _shipped stripped off, |
|
giving us <filename>. This shortened filename can 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:: |
|
|
|
8123-y := 8123_if.o 8123_pci.o 8123_bin.o |
|
|
|
Although there is no distinction between the ordinary source |
|
files and the binary file, kbuild will pick up different rules |
|
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 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> |
|
bar-y := <bar_srcs> |
|
|
|
It is that simple! |
|
|
|
|
|
4. Include Files |
|
================ |
|
|
|
Within the kernel, header files are kept in standard locations |
|
according to the following rule: |
|
|
|
* If the header file only describes the internal interface of a |
|
module, then the file is placed in the same directory as the |
|
source files. |
|
* If the header file describes an interface used by other parts |
|
of the kernel that are located in different directories, then |
|
the file is placed in include/linux/. |
|
|
|
NOTE: |
|
There are two notable exceptions to this rule: larger |
|
subsystems have their own directory under include/, such as |
|
include/scsi; and architecture specific headers are located |
|
under arch/$(SRCARCH)/include/. |
|
|
|
4.1 Kernel Includes |
|
------------------- |
|
|
|
To include a header file located under include/linux/, simply |
|
use:: |
|
|
|
#include <linux/module.h> |
|
|
|
kbuild will add options to "gcc" so the relevant directories |
|
are searched. |
|
|
|
4.2 Single Subdirectory |
|
----------------------- |
|
|
|
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. |
|
|
|
Using the example from section 3, if we moved 8123_if.h to a |
|
subdirectory named include, the resulting kbuild file would |
|
look like:: |
|
|
|
--> filename: Kbuild |
|
obj-m := 8123.o |
|
|
|
ccflags-y := -Iinclude |
|
8123-y := 8123_if.o 8123_pci.o 8123_bin.o |
|
|
|
Note that in the assignment there is no space between -I and |
|
the path. This is a limitation of kbuild: there must be no |
|
space present. |
|
|
|
4.3 Several Subdirectories |
|
-------------------------- |
|
|
|
kbuild can handle files that are spread over several directories. |
|
Consider the following example:: |
|
|
|
. |
|
|__ src |
|
| |__ complex_main.c |
|
| |__ hal |
|
| |__ hardwareif.c |
|
| |__ include |
|
| |__ hardwareif.h |
|
|__ include |
|
|__ complex.h |
|
|
|
To build the module complex.ko, we then need the following |
|
kbuild file:: |
|
|
|
--> filename: Kbuild |
|
obj-m := complex.o |
|
complex-y := src/complex_main.o |
|
complex-y += src/hal/hardwareif.o |
|
|
|
ccflags-y := -I$(src)/include |
|
ccflags-y += -I$(src)/src/hal/include |
|
|
|
As you can see, kbuild knows how to handle object files located |
|
in other directories. The trick is to specify the directory |
|
relative to the kbuild file's location. That being said, this |
|
is NOT recommended practice. |
|
|
|
For the header files, kbuild must be explicitly told where to |
|
look. When kbuild executes, the current directory is always the |
|
root of the kernel tree (the argument to "-C") and therefore an |
|
absolute path is needed. $(src) provides the absolute path by |
|
pointing to the directory where the currently executing kbuild |
|
file is located. |
|
|
|
|
|
5. Module Installation |
|
====================== |
|
|
|
Modules which are included in the kernel are installed in the |
|
directory: |
|
|
|
/lib/modules/$(KERNELRELEASE)/kernel/ |
|
|
|
And external modules are installed in: |
|
|
|
/lib/modules/$(KERNELRELEASE)/extra/ |
|
|
|
5.1 INSTALL_MOD_PATH |
|
-------------------- |
|
|
|
Above are the default directories but as always some level of |
|
customization is possible. A prefix can be added to the |
|
installation path using the variable INSTALL_MOD_PATH:: |
|
|
|
$ make INSTALL_MOD_PATH=/frodo modules_install |
|
=> 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 |
|
calling "make." This has effect when installing both in-tree |
|
and out-of-tree modules. |
|
|
|
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.":: |
|
|
|
$ make INSTALL_MOD_DIR=gandalf -C $KDIR \ |
|
M=$PWD modules_install |
|
=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/ |
|
|
|
|
|
6. 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 |
|
for an exported symbol is created. When a module is loaded/used, the |
|
CRC values contained in the kernel are compared with similar values in |
|
the module; if they are not equal, the kernel refuses to load the |
|
module. |
|
|
|
Module.symvers contains a list of all exported symbols from a kernel |
|
build. |
|
|
|
6.1 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 |
|
the kernel and compiled modules. For each symbol, the |
|
corresponding CRC value is also stored. |
|
|
|
The syntax of the Module.symvers file is:: |
|
|
|
<CRC> <Symbol> <Module> <Export Type> <Namespace> |
|
|
|
0xe1cc2a05 usb_stor_suspend drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL USB_STORAGE |
|
|
|
The fields are separated by tabs and values may be empty (e.g. |
|
if no namespace is defined for an exported symbol). |
|
|
|
For a kernel build without CONFIG_MODVERSIONS enabled, the CRC |
|
would read 0x00000000. |
|
|
|
Module.symvers serves two purposes: |
|
|
|
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 |
|
-------------------------------- |
|
|
|
When building an external module, the build system needs access |
|
to the symbols from the kernel to check if all external symbols |
|
are defined. This is done in the MODPOST step. modpost obtains |
|
the symbols by reading Module.symvers from the kernel source |
|
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 |
|
---------------------------------------- |
|
|
|
Sometimes, an external module uses exported symbols from |
|
another external module. Kbuild needs to have full knowledge of |
|
all symbols to avoid spitting out warnings about undefined |
|
symbols. Two solutions exist for this situation. |
|
|
|
NOTE: The method with a top-level kbuild file is recommended |
|
but may be impractical in certain situations. |
|
|
|
Use a top-level kbuild file |
|
If you have two modules, foo.ko and bar.ko, where |
|
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 the following |
|
directory layout:: |
|
|
|
./foo/ <= contains foo.ko |
|
./bar/ <= contains bar.ko |
|
|
|
The top-level kbuild file would then look like:: |
|
|
|
#./Kbuild (or ./Makefile): |
|
obj-m := foo/ bar/ |
|
|
|
And executing:: |
|
|
|
$ make -C $KDIR M=$PWD |
|
|
|
will then do the expected and compile both modules with |
|
full knowledge of symbols from either module. |
|
|
|
Use "make" variable KBUILD_EXTRA_SYMBOLS |
|
If it is impractical to add a top-level kbuild file, |
|
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 |
|
initialization of its symbol tables. |
|
|
|
|
|
7. Tips & Tricks |
|
================ |
|
|
|
7.1 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 |
|
kbuild this is done by referencing the `CONFIG_` variable |
|
directly:: |
|
|
|
#fs/ext2/Makefile |
|
obj-$(CONFIG_EXT2_FS) += ext2.o |
|
|
|
ext2-y := balloc.o bitmap.o dir.o |
|
ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o |
|
|
|
External modules have traditionally used "grep" to check for |
|
specific `CONFIG_` settings directly in .config. This usage is |
|
broken. As introduced before, external modules should use |
|
kbuild for building and can therefore use the same methods as |
|
in-tree modules when testing for `CONFIG_` definitions.
|
|
|