Commit d9a7ff66 authored by Jan Engelhardt's avatar Jan Engelhardt Committed by Sam Ravnborg

kbuild: linguistic fixes for Documentation/kbuild/modules.txt

I have done a look-through through Documentation/kbuild/ and my corrections
(proposed) are attached.

Cc'ed are original author Michael (responsible for comitting changes to
these files?), Sam (kbuild maintainer), Adrian (-trivial maintainer).
Signed-off-by: default avatarJan Engelhardt <jengelh@gmx.de>
Signed-off-by: default avatarSam Ravnborg <sam@ravnborg.org>
parent 83dcde4e
In this document you will find information about:
- how to build external modules
- how to make your module use kbuild infrastructure
- how to make your module use the kbuild infrastructure
- how kbuild will install a kernel
- how to install modules in a non-standard location
......@@ -36,13 +36,13 @@ In this document you will find information about:
kbuild includes functionality for building modules both
within the kernel source tree and outside the kernel source tree.
The latter is usually referred to as external modules and is used
both during development and for modules that are not planned to be
included in the kernel tree.
The latter is usually referred to as external or "out-of-tree"
modules and is used both during development and for modules that
are not planned to be included in the kernel tree.
What is covered within this file is mainly information to authors
of modules. The author of an external modules should supply
a makefile that hides most of the complexity so one only has to type
of 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. A complete example will be present in
chapter 4, "Creating a kbuild file for an external module".
......@@ -137,7 +137,7 @@ when building an external module.
module versioning work.
--- 2.5 Building separate files for a module
It is possible to build single files which is part of a module.
It is possible to build single files which are part of a module.
This works equal for the kernel, a module and even for external
modules.
Examples (module foo.ko, consist of bar.o, baz.o):
......@@ -151,7 +151,7 @@ when building an external module.
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
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.
......@@ -170,7 +170,7 @@ the following commands to build the module:
O=/lib/modules/`uname-r`/build \
M=`pwd`
Then to install the module use the following command:
Then, to install the module use the following command:
make -C /usr/src/`uname -r`/source \
O=/lib/modules/`uname-r`/build \
......@@ -230,7 +230,7 @@ following files:
endif
In example 1 the check for KERNELRELEASE is used to separate
In example 1, the check for KERNELRELEASE is used to separate
the two parts of the Makefile. kbuild will only see the two
assignments whereas make will see everything except the two
kbuild assignments.
......@@ -255,7 +255,7 @@ following files:
echo "X" > 8123_bin_shipped
In example 2 we are down to two fairly simple files and for simple
In example 2, we are down to two fairly simple files and for simple
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.
......@@ -282,9 +282,9 @@ following files:
endif
The trick here is to include the Kbuild file from Makefile so
if an older version of kbuild picks up the Makefile the Kbuild
file will be included.
The trick here is to include the Kbuild file from Makefile, so
if an older version of kbuild picks up the Makefile, the Kbuild
file will be included.
--- 4.2 Binary blobs included in a module
......@@ -301,18 +301,19 @@ following files:
obj-m := 8123.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
In example 4, there is no distinction between the ordinary .c/.h files
and the binary file. But kbuild will pick up different rules to create
the .o file.
=== 5. Include files
Include files are a necessity when a .c file uses something from another .c
files (not strictly in the sense of .c but if good programming practice is
used). Any module that consist of more than one .c file will have a .h file
Include files are a necessity when a .c file uses something from other .c
files (not strictly in the sense of C, but if good programming practice is
used). Any module that consists of more than one .c file will have a .h file
for one of the .c files.
- If the .h file only describes a module internal interface then the .h file
- If the .h file only describes a module internal interface, then the .h file
shall be placed in the same directory as the .c files.
- If the .h files describe an interface used by other parts of the kernel
located in different directories, the .h files shall be located in
......@@ -323,11 +324,11 @@ under include/ such as include/scsi. Another exception is arch-specific
.h files which are located under include/asm-$(ARCH)/*.
External modules have a tendency to locate include files in a separate include/
directory and therefore needs to deal with this in their kbuild file.
directory and therefore need to deal with this in their kbuild file.
--- 5.1 How to include files from the kernel include dir
When a module needs to include a file from include/linux/ then one
When a module needs to include a file from include/linux/, then one
just uses:
#include <linux/modules.h>
......@@ -348,7 +349,7 @@ directory and therefore needs to deal with this in their kbuild file.
The trick here is to use either EXTRA_CFLAGS (take effect for all .c
files) or CFLAGS_$F.o (take effect only for a single file).
In our example if we move 8123_if.h to a subdirectory named include/
In our example, if we move 8123_if.h to a subdirectory named include/
the resulting Kbuild file would look like:
--> filename: Kbuild
......@@ -362,9 +363,9 @@ directory and therefore needs to deal with this in their kbuild file.
--- 5.3 External modules using several directories
If an external module does not follow the usual kernel style but
decide to spread files over several directories then kbuild can
support this too.
If an external module does not follow the usual kernel style, but
decides to spread files over several directories, then kbuild can
handle this too.
Consider the following example:
......@@ -374,7 +375,7 @@ directory and therefore needs to deal with this in their kbuild file.
| +- hal/include/hardwareif.h
+- include/complex.h
To build a single module named complex.ko we then need the following
To build a single module named complex.ko, we then need the following
kbuild file:
Kbuild:
......@@ -387,12 +388,12 @@ directory and therefore needs to deal with this in their kbuild file.
kbuild knows how to handle .o files located in another directory -
although this is NOT reccommended practice. The syntax is to specify
although this is NOT recommended practice. The syntax is to specify
the directory relative to the directory where the Kbuild file is
located.
To find the .h files we have to explicitly tell kbuild where to look
for the .h files. When kbuild executes current directory is always
To find the .h files, we have to explicitly tell kbuild where to look
for the .h files. When kbuild executes, the current directory is always
the root of the kernel tree (argument to -C) and therefore we have to
tell kbuild how to find the .h files using absolute paths.
$(src) will specify the absolute path to the directory where the
......@@ -412,7 +413,7 @@ External modules are installed in the directory:
--- 6.1 INSTALL_MOD_PATH
Above are the default directories, but as always some level of
Above are the default directories, but as always, some level of
customization is possible. One can prefix the path using the variable
INSTALL_MOD_PATH:
......@@ -420,17 +421,17 @@ External modules are installed in the directory:
=> Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel
INSTALL_MOD_PATH may be set as an ordinary shell variable or as in the
example above be specified on the command line when calling make.
example above, can be specified on the command line when calling make.
INSTALL_MOD_PATH has effect both when installing modules included in
the kernel as well as when installing external modules.
--- 6.2 INSTALL_MOD_DIR
When installing external modules they are default installed in a
When installing external modules they are by default installed to a
directory under /lib/modules/$(KERNELRELEASE)/extra, but one may wish
to locate modules for a specific functionality in a separate
directory. For this purpose one can use INSTALL_MOD_DIR to specify an
alternative name than 'extra'.
directory. For this purpose, one can use INSTALL_MOD_DIR to specify an
alternative name to 'extra'.
$ make INSTALL_MOD_DIR=gandalf -C KERNELDIR \
M=`pwd` modules_install
......@@ -444,16 +445,16 @@ Module versioning is enabled by the CONFIG_MODVERSIONS tag.
Module versioning is used as a simple ABI consistency check. The Module
versioning creates a CRC value of the full prototype for an exported symbol and
when a module is loaded/used then the CRC values contained in the kernel are
compared with similar values in the module. If they are not equal then the
compared with similar values in the module. If they are not equal, then the
kernel refuses to load the module.
Module.symvers contains a list of all exported symbols from a kernel build.
--- 7.1 Symbols fron the kernel (vmlinux + modules)
During a kernel build a file named Module.symvers will be generated.
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 symbols the corresponding CRC value
compiled modules. For each symbols, the corresponding CRC value
is stored too.
The syntax of the Module.symvers file is:
......@@ -461,27 +462,27 @@ Module.symvers contains a list of all exported symbols from a kernel build.
Sample:
0x2d036834 scsi_remove_host drivers/scsi/scsi_mod
For a kernel build without CONFIG_MODVERSIONING enabled the crc
For a kernel build without CONFIG_MODVERSIONING enabled, the crc
would read: 0x00000000
Module.symvers serve two purposes.
1) It list all exported symbols both from vmlinux and all modules
2) It list CRC if CONFIG_MODVERSION is enabled
Module.symvers serves two purposes:
1) It lists all exported symbols both from vmlinux and all modules
2) It lists the CRC if CONFIG_MODVERSION is enabled
--- 7.2 Symbols and external modules
When building an external module the build system needs access to
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 and to obtain all
symbols modpost reads Module.symvers from the kernel.
symbols, modpost reads Module.symvers from the kernel.
If a Module.symvers file is present in the directory where
the external module is being build this file will be read too.
During the MODPOST step a new Module.symvers file will be written
containing all exported symbols that was not defined in the kernel.
the external module is being built, this file will be read too.
During the MODPOST step, a new Module.symvers file will be written
containing all exported symbols that were not defined in the kernel.
--- 7.3 Symbols from another external module
Sometimes one external module uses exported symbols from another
Sometimes, an external module uses exported symbols from another
external module. Kbuild needs to have full knowledge on all symbols
to avoid spitting out warnings about undefined symbols.
Two solutions exist to let kbuild know all symbols of more than
......@@ -490,9 +491,9 @@ Module.symvers contains a list of all exported symbols from a kernel build.
impractical in certain situations.
Use a top-level Kbuild file
If you have two modules: 'foo', 'bar' and 'foo' needs symbols
from 'bar' then one can use a common top-level kbuild file so
both modules are compiled in same build.
If you have two modules: 'foo' and 'bar', and 'foo' needs
symbols from 'bar', then one can use a common top-level kbuild
file so both modules are compiled in same build.
Consider following directory layout:
./foo/ <= contains the foo module
......@@ -509,15 +510,15 @@ Module.symvers contains a list of all exported symbols from a kernel build.
knowledge on symbols from both modules.
Use an extra Module.symvers file
When an external module is build a Module.symvers file is
When an external module is built, a Module.symvers file is
generated containing all exported symbols which are not
defined in the kernel.
To get access to symbols from module 'bar' one can copy the
To get access to symbols from module 'bar', one can copy the
Module.symvers file from the compilation of the 'bar' module
to the directory where the 'foo' module is build.
During the module build kbuild will read the Module.symvers
to the directory where the 'foo' module is built.
During the module build, kbuild will read the Module.symvers
file in the directory of the external module and when the
build is finished a new Module.symvers file is created
build is finished, a new Module.symvers file is created
containing the sum of all symbols defined and not part of the
kernel.
......@@ -525,7 +526,7 @@ Module.symvers contains a list of all exported symbols from a kernel build.
--- 8.1 Testing for CONFIG_FOO_BAR
Modules often needs to check for certain CONFIG_ options to decide if
Modules often need to check for certain CONFIG_ options to decide if
a specific feature shall be included in the module. When kbuild is used
this is done by referencing the CONFIG_ variable directly.
......@@ -537,7 +538,7 @@ Module.symvers contains a list of all exported symbols from a kernel build.
External modules have traditionally used grep to check for specific
CONFIG_ settings directly in .config. This usage is broken.
As introduced before external modules shall use kbuild when building
and therefore can use the same methods as in-kernel modules when testing
for CONFIG_ definitions.
As introduced before, external modules shall use kbuild when building
and therefore can use the same methods as in-kernel modules when
testing for CONFIG_ definitions.
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