Commit 803d5059 authored by Masahiro Yamada's avatar Masahiro Yamada
Browse files

kbuild: doc: drop section numbering, use references in modules.rst 



Do similar to commit 1a4c1c9d ("docs/kbuild/makefiles: drop section
numbering, use references").

Signed-off-by: default avatarMasahiro Yamada <masahiroy@kernel.org>
parent 7813cd68

Documentation/kbuild/modules.rst

+51 −50
Original line number Diff line number Diff line
@@ -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