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: Jan Engelhardt <jengelh@gmx.de>
Signed-off-by: Sam Ravnborg <sam@ravnborg.org>
diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt
index 61fc079..a2a178d 100644
--- a/Documentation/kbuild/modules.txt
+++ b/Documentation/kbuild/modules.txt
@@ -1,7 +1,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
.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 @@
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 @@
--- 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 @@
| +- 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 @@
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 @@
--- 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 @@
=> 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 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 @@
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 @@
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 @@
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 @@
--- 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 @@
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.