diff options
Diffstat (limited to 'Documentation/kbuild/modules.rst')
| -rw-r--r-- | Documentation/kbuild/modules.rst | 101 |
1 files changed, 51 insertions, 50 deletions
diff --git a/Documentation/kbuild/modules.rst b/Documentation/kbuild/modules.rst index 4f67e6a27afe..c4a0598aa276 100644 --- a/Documentation/kbuild/modules.rst +++ b/Documentation/kbuild/modules.rst @@ -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 |