Techwizz/kernel-fxtec-pro1x
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Documentation/kbuild: modules.txt cleanup

Browse source 
A few modifications done for consistency, such as adding the shell
prompt for command line examples and trailing slash for directories.
Also corrects the module include header and fixes a few grammar
issues that I introduced.

Signed-off-by: matt mooney <mfm@muteddisk.com>
Signed-off-by: Michal Marek <mmarek@suse.cz>
This commit is contained in:
matt mooney 2010-10-01 21:21:55 -07:00 committed by Michal Marek
parent 9f02186c23
commit 5793210cb1
1 changed files with 32 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

62
Documentation/kbuild/modules.txt
View file

@ -1,11 +1,11 @@
Building External Modules Building External Modules
This document describes how-to build an out-of-tree kernel module. This document describes how to build an out-of-tree kernel module.
=== Table of Contents === Table of Contents
=== 1 Introduction === 1 Introduction
=== 2 How-to Build External Modules === 2 How to Build External Modules
--- 2.1 Command Syntax --- 2.1 Command Syntax
--- 2.2 Options --- 2.2 Options
--- 2.3 Targets --- 2.3 Targets
@ -48,9 +48,9 @@ easily accomplished, and a complete example will be presented in
section 3. section 3.
=== 2. How-to Build External Modules === 2. How to Build External Modules
To build external modules, you must have a pre-built kernel available To build external modules, you must have a prebuilt kernel available
that contains the configuration and header files used in the build. that contains the configuration and header files used in the build.
Also, the kernel must have been built with modules enabled. If you are 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 using a distribution kernel, there will be a package for the kernel you
@ -69,19 +69,19 @@ executed to make module versioning work.
The command to build an external module is: The command to build an external module is:
make -C <path_to_kernel_src> M=$PWD $ make -C <path_to_kernel_src> M=$PWD
The kbuild system knows that an external module is being built The kbuild system knows that an external module is being built
due to the "M=<dir>" option given in the command. due to the "M=<dir>" option given in the command.
To build against the running kernel use: To build against the running kernel use:
make -C /lib/modules/`uname -r`/build M=$PWD $ make -C /lib/modules/`uname -r`/build M=$PWD
Then to install the module(s) just built, add the target Then to install the module(s) just built, add the target
"modules_install" to the command: "modules_install" to the command:
make -C /lib/modules/`uname -r`/build M=$PWD modules_install $ make -C /lib/modules/`uname -r`/build M=$PWD modules_install
--- 2.2 Options --- 2.2 Options
@ -121,7 +121,7 @@ executed to make module versioning work.
modules_install modules_install
Install the external module(s). The default location is Install the external module(s). The default location is
/lib/modules/<kernel_release>/extra, but a prefix may /lib/modules/<kernel_release>/extra/, but a prefix may
be added with INSTALL_MOD_PATH (discussed in section 5). be added with INSTALL_MOD_PATH (discussed in section 5).
clean clean
@ -164,7 +164,7 @@ needed listing the files:
NOTE: Further documentation describing the syntax used by kbuild is NOTE: Further documentation describing the syntax used by kbuild is
located in Documentation/kbuild/makefiles.txt. located in Documentation/kbuild/makefiles.txt.
The examples below demonstrate how-to create a build file for the The examples below demonstrate how to create a build file for the
module 8123.ko, which is built from the following files: module 8123.ko, which is built from the following files:
8123_if.c 8123_if.c
@ -205,14 +205,14 @@ module 8123.ko, which is built from the following files:
of the makefile. In the example, kbuild will only see the two of the makefile. In the example, kbuild will only see the two
assignments, whereas "make" will see everything except these assignments, whereas "make" will see everything except these
two assignments. This is due to two passes made on the file: two assignments. This is due to two passes made on the file:
the first pass is by the "make" instance run on the the first pass is by the "make" instance run on the command
command line; the second pass is by the kbuild system, which is line; the second pass is by the kbuild system, which is
initiated by the parameterized "make" in the default target. initiated by the parameterized "make" in the default target.
--- 3.2 Separate Kbuild File and Makefile --- 3.2 Separate Kbuild File and Makefile
In newer versions of the kernel, kbuild will first look for a In newer versions of the kernel, kbuild will first look for a
file named "Kbuild", and only if that is not found, will it file named "Kbuild," and only if that is not found, will it
then look for a makefile. Utilizing a "Kbuild" file allows us then look for a makefile. Utilizing a "Kbuild" file allows us
to split up the makefile from example 1 into two files: to split up the makefile from example 1 into two files:
@ -288,8 +288,8 @@ module 8123.ko, which is built from the following files:
--- 3.4 Building Multiple Modules --- 3.4 Building Multiple Modules
kbuild supports building multiple modules with a single build kbuild supports building multiple modules with a single build
file. For example, if you want to build two modules, foo and file. For example, if you wanted to build two modules, foo.ko
bar, the kbuild lines would be: and bar.ko, the kbuild lines would be:
obj-m := foo.o bar.o obj-m := foo.o bar.o
foo-y := <foo_srcs> foo-y := <foo_srcs>
@ -320,7 +320,7 @@ according to the following rule:
To include a header file located under include/linux/, simply To include a header file located under include/linux/, simply
use: use:
#include <linux/modules.h> #include <linux/module.h>
kbuild will add options to "gcc" so the relevant directories kbuild will add options to "gcc" so the relevant directories
are searched. are searched.
@ -330,7 +330,7 @@ according to the following rule:
External modules tend to place header files in a separate External modules tend to place header files in a separate
include/ directory where their source is located, although this include/ directory where their source is located, although this
is not the usual kernel style. To inform kbuild of the is not the usual kernel style. To inform kbuild of the
directory use either ccflags-y or CFLAGS_<filename>.o. directory, use either ccflags-y or CFLAGS_<filename>.o.
Using the example from section 3, if we moved 8123_if.h to a Using the example from section 3, if we moved 8123_if.h to a
subdirectory named include, the resulting kbuild file would subdirectory named include, the resulting kbuild file would
@ -390,11 +390,11 @@ according to the following rule:
Modules which are included in the kernel are installed in the Modules which are included in the kernel are installed in the
directory: directory:
/lib/modules/$(KERNELRELEASE)/kernel /lib/modules/$(KERNELRELEASE)/kernel/
And external modules are installed in: And external modules are installed in:
/lib/modules/$(KERNELRELEASE)/extra /lib/modules/$(KERNELRELEASE)/extra/
--- 5.1 INSTALL_MOD_PATH --- 5.1 INSTALL_MOD_PATH
@ -403,7 +403,7 @@ And external modules are installed in:
installation path using the variable INSTALL_MOD_PATH: installation path using the variable INSTALL_MOD_PATH:
$ make INSTALL_MOD_PATH=/frodo modules_install $ make INSTALL_MOD_PATH=/frodo modules_install
=> Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/
INSTALL_MOD_PATH may be set as an ordinary shell variable or, INSTALL_MOD_PATH may be set as an ordinary shell variable or,
as shown above, can be specified on the command line when as shown above, can be specified on the command line when
@ -413,14 +413,14 @@ And external modules are installed in:
--- 5.2 INSTALL_MOD_DIR --- 5.2 INSTALL_MOD_DIR
External modules are by default installed to a directory under External modules are by default installed to a directory under
/lib/modules/$(KERNELRELEASE)/extra, but you may wish to locate /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to
modules for a specific functionality in a separate directory. locate modules for a specific functionality in a separate
For this purpose, use INSTALL_MOD_DIR to specify an alternative directory. For this purpose, use INSTALL_MOD_DIR to specify an
name to "extra." alternative name to "extra."
$ make INSTALL_MOD_DIR=gandalf -C $KDIR \ $ make INSTALL_MOD_DIR=gandalf -C $KDIR \
M=$PWD modules_install M=$PWD modules_install
=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/
=== 6. Module Versioning === 6. Module Versioning
@ -478,9 +478,9 @@ build.
Use a top-level kbuild file Use a top-level kbuild file
If you have two modules, foo.ko and bar.ko, where If you have two modules, foo.ko and bar.ko, where
foo.ko needs symbols from bar.ko, then you can use a foo.ko needs symbols from bar.ko, you can use a
common top-level kbuild file so both modules are common top-level kbuild file so both modules are
compiled in the same build. Consider following compiled in the same build. Consider the following
directory layout: directory layout:
./foo/ <= contains foo.ko ./foo/ <= contains foo.ko
@ -491,10 +491,11 @@ build.
#./Kbuild (or ./Makefile): #./Kbuild (or ./Makefile):
obj-y := foo/ bar/ obj-y := foo/ bar/
And executing: And executing
$ make -C $KDIR M=$PWD $ make -C $KDIR M=$PWD
Will then do the expected and compile both modules with will then do the expected and compile both modules with
full knowledge of symbols from either module. full knowledge of symbols from either module.
Use an extra Module.symvers file Use an extra Module.symvers file
@ -512,10 +513,11 @@ build.
Use "make" variable KBUILD_EXTRA_SYMBOLS Use "make" variable KBUILD_EXTRA_SYMBOLS
If it is impractical to copy Module.symvers from If it is impractical to copy Module.symvers from
another module, you can assign a space separated list another module, you can assign a space separated list
of files to KBUILD_EXTRA_SYMBOLS in your build of files to KBUILD_EXTRA_SYMBOLS in your build file.
file. These files will be loaded by modpost during the These files will be loaded by modpost during the
initialization of its symbol tables. initialization of its symbol tables.
=== 7. Tips & Tricks === 7. Tips & Tricks
--- 7.1 Testing for CONFIG_FOO_BAR --- 7.1 Testing for CONFIG_FOO_BAR