Commit 5793210c authored by matt mooney's avatar matt mooney Committed by Michal Marek
Browse files

Documentation/kbuild: modules.txt cleanup 



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: default avatarmatt mooney <mfm@muteddisk.com>
Signed-off-by: default avatarMichal Marek <mmarek@suse.cz>
parent 9f02186c

Documentation/kbuild/modules.txt

+32 −30
Original line number Diff line number Diff line 
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



	=== 1 Introduction

	=== 2 How-to Build External Modules

	=== 2 How to Build External Modules

	   --- 2.1 Command Syntax

	   --- 2.2 Options

	   --- 2.3 Targets
@@ -48,9 +48,9 @@ easily accomplished, and a complete example will be presented in 
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.

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
@@ -69,19 +69,19 @@ executed to make module versioning work. 


	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

	due to the "M=<dir>" option given in the command.



	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

	"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
@@ -121,7 +121,7 @@ executed to make module versioning work. 


	modules_install

		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).



	clean
@@ -164,7 +164,7 @@ needed listing the files: 
NOTE: Further documentation describing the syntax used by kbuild is

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:



	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

	assignments, whereas "make" will see everything except these

	two assignments. This is due to two passes made on the file:

	the first pass is by the "make" instance run on the

	command line; the second pass is by the kbuild system, which is

	the first pass is by the "make" instance run on the command

	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



	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

	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



	kbuild supports building multiple modules with a single build

	file. For example, if you want to build two modules, foo and

	bar, the kbuild lines would be:

	file. For example, if you wanted to build two modules, foo.ko

	and bar.ko, the kbuild lines would be:



		obj-m := foo.o bar.o

		foo-y := <foo_srcs>
@@ -320,7 +320,7 @@ according to the following rule: 
	To include a header file located under include/linux/, simply

	use:



		#include <linux/modules.h>

		#include <linux/module.h>



	kbuild will add options to "gcc" so the relevant directories

	are searched.
@@ -330,7 +330,7 @@ according to the following rule: 
	External modules tend to place header files in a separate

	include/ directory where their source is located, although this

	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

	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

directory:



	/lib/modules/$(KERNELRELEASE)/kernel

	/lib/modules/$(KERNELRELEASE)/kernel/



And external modules are installed in:



	/lib/modules/$(KERNELRELEASE)/extra

	/lib/modules/$(KERNELRELEASE)/extra/



--- 5.1 INSTALL_MOD_PATH
@@ -403,7 +403,7 @@ And external modules are installed in: 
	installation path using the variable INSTALL_MOD_PATH:



		$ 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,

	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



	External modules are by default installed to a directory under

	/lib/modules/$(KERNELRELEASE)/extra, but you may wish to locate

	modules for a specific functionality in a separate directory.

	For this purpose, use INSTALL_MOD_DIR to specify an alternative

	name to "extra."

	/lib/modules/$(KERNELRELEASE)/extra/, but you may wish to

	locate modules for a specific functionality in a separate

	directory. For this purpose, use INSTALL_MOD_DIR to specify an

	alternative name to "extra."



		$ make INSTALL_MOD_DIR=gandalf -C $KDIR \

		       M=$PWD modules_install

		=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf

		=> Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/





=== 6. Module Versioning
@@ -478,9 +478,9 @@ build. 


	Use a top-level kbuild file

		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

		compiled in the same build. Consider following

		compiled in the same build. Consider the following

		directory layout:



		./foo/ <= contains foo.ko
@@ -491,10 +491,11 @@ build. 
		#./Kbuild (or ./Makefile):

			obj-y := foo/ bar/



		And executing:

		And executing



			$ 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.



	Use an extra Module.symvers file
@@ -512,10 +513,11 @@ build. 
	Use "make" variable KBUILD_EXTRA_SYMBOLS

		If it is impractical to copy Module.symvers from

		another module, you can assign a space separated list

		of files to KBUILD_EXTRA_SYMBOLS in your build

		file. These files will be loaded by modpost during the

		of files to KBUILD_EXTRA_SYMBOLS in your build file.

		These files will be loaded by modpost during the

		initialization of its symbol tables.





=== 7. Tips & Tricks



--- 7.1 Testing for CONFIG_FOO_BAR