Linux-2.6.12-rc2
[linux-2.6.git] / Documentation / kbuild / modules.txt
1
2 In this document you will find information about:
3 - how to build external modules
4 - how to make your module use kbuild infrastructure
5 - how kbuild will install a kernel
6 - how to install modules in a non-standard location
7
8 === Table of Contents
9
10         === 1 Introduction
11         === 2 How to build external modules
12            --- 2.1 Building external modules
13            --- 2.2 Available targets
14            --- 2.3 Available options
15            --- 2.4 Preparing the kernel tree for module build
16         === 3. Example commands
17         === 4. Creating a kbuild file for an external module
18         === 5. Include files
19            --- 5.1 How to include files from the kernel include dir
20            --- 5.2 External modules using an include/ dir
21         === 6. Module installation
22            --- 6.1 INSTALL_MOD_PATH
23            --- 6.2 INSTALL_MOD_DIR
24         === 7. Module versioning
25         === 8. Tips & Tricks
26            --- 8.1 Testing for CONFIG_FOO_BAR
27
28
29
30 === 1. Introduction
31
32 kbuild includes functionality for building modules both
33 within the kernel source tree and outside the kernel source tree.
34 The latter is usually referred to as external modules and is used
35 both during development and for modules that are not planned to be
36 included in the kernel tree.
37
38 What is covered within this file is mainly information to authors
39 of modules. The author of an external modules should supply
40 a makefile that hides most of the complexity so one only has to type
41 'make' to buld the module. A complete example will be present in
42 chapter ยค. Creating a kbuild file for an external module".
43
44
45 === 2. How to build external modules
46
47 kbuild offers functionality to build external modules, with the
48 prerequisite that there is a pre-built kernel available with full source.
49 A subset of the targets available when building the kernel is available
50 when building an external module.
51
52 --- 2.1 Building external modules
53
54         Use the following command to build an external module:
55
56                 make -C <path-to-kernel> M=`pwd`
57
58         For the running kernel use:
59                 make -C /lib/modules/`uname -r`/build M=`pwd`
60
61         For the above command to succeed the kernel must have been built with
62         modules enabled.
63
64         To install the modules that were just built:
65
66                 make -C <path-to-kernel> M=`pwd` modules_install
67
68         More complex examples later, the above should get you going.
69
70 --- 2.2 Available targets
71
72         $KDIR refers to path to kernel source top-level directory
73
74         make -C $KDIR M=`pwd`
75                 Will build the module(s) located in current directory.
76                 All output files will be located in the same directory
77                 as the module source.
78                 No attempts are made to update the kernel source, and it is
79                 a precondition that a successful make has been executed
80                 for the kernel.
81
82         make -C $KDIR M=`pwd` modules
83                 The modules target is implied when no target is given.
84                 Same functionality as if no target was specified.
85                 See description above.
86
87         make -C $KDIR M=$PWD modules_install
88                 Install the external module(s).
89                 Installation default is in /lib/modules/<kernel-version>/extra,
90                 but may be prefixed with INSTALL_MOD_PATH - see separate chater.
91
92         make -C $KDIR M=$PWD clean
93                 Remove all generated files for the module - the kernel
94                 source directory is not moddified.
95
96         make -C $KDIR M=`pwd` help
97                 help will list the available target when building external
98                 modules.
99
100 --- 2.3 Available options:
101
102         $KDIR refer to path to kernel src
103
104         make -C $KDIR
105                 Used to specify where to find the kernel source.
106                 '$KDIR' represent the directory where the kernel source is.
107                 Make will actually change directory to the specified directory
108                 when executed but change back when finished.
109
110         make -C $KDIR M=`pwd`
111                 M= is used to tell kbuild that an external module is
112                 being built.
113                 The option given to M= is the directory where the external
114                 module (kbuild file) is located.
115                 When an external module is being built only a subset of the
116                 usual targets are available.
117
118         make -C $KDIR SUBDIRS=`pwd`
119                 Same as M=. The SUBDIRS= syntax is kept for backwards
120                 compatibility.
121
122 --- 2.4 Preparing the kernel tree for module build
123
124         To make sure the kernel contains the information required to
125         build external modules the target 'modules_prepare' must be used.
126         'module_prepare' solely exists as a simple way to prepare
127         a kernel for building external modules.
128         Note: modules_prepare will not build Module.symvers even if
129               CONFIG_MODULEVERSIONING is set.
130               Therefore a full kernel build needs to be executed to make
131               module versioning work.
132
133
134 === 3. Example commands
135
136 This example shows the actual commands to be executed when building
137 an external module for the currently running kernel.
138 In the example below the distribution is supposed to use the
139 facility to locate output files for a kernel compile in a different
140 directory than the kernel source - but the examples will also work
141 when the source and the output files are mixed in the same directory.
142
143 # Kernel source
144 /lib/modules/<kernel-version>/source -> /usr/src/linux-<version>
145
146 # Output from kernel compile
147 /lib/modules/<kernel-version>/build -> /usr/src/linux-<version>-up
148
149 Change to the directory where the kbuild file is located and execute
150 the following commands to build the module:
151
152         cd /home/user/src/module
153         make -C /usr/src/`uname -r`/source            \
154                 O=/lib/modules/`uname-r`/build        \
155                 M=`pwd`
156
157 Then to install the module use the following command:
158
159         make -C /usr/src/`uname -r`/source            \
160                 O=/lib/modules/`uname-r`/build        \
161                 M=`pwd`                               \
162                 modules_install
163
164 If one looks closely you will see that this is the same commands as
165 listed before - with the directories spelled out.
166
167 The above are rather long commands, and the following chapter
168 lists a few tricks to make it all easier.
169
170
171 === 4. Creating a kbuild file for an external module
172
173 kbuild is the build system for the kernel, and external modules
174 must use kbuild to stay compatible with changes in the build system
175 and to pick up the right flags to gcc etc.
176
177 The kbuild file used as input shall follow the syntax described
178 in Documentation/kbuild/makefiles.txt. This chapter will introduce a few
179 more tricks to be used when dealing with external modules.
180
181 In the following a Makefile will be created for a module with the
182 following files:
183         8123_if.c
184         8123_if.h
185         8123_pci.c
186         8123_bin.o_shipped      <= Binary blob
187
188 --- 4.1 Shared Makefile for module and kernel
189
190         An external module always includes a wrapper Makefile supporting
191         building the module using 'make' with no arguments.
192         The Makefile provided will most likely include additional
193         functionality such as test targets etc. and this part shall
194         be filtered away from kbuild since it may impact kbuild if
195         name clashes occurs.
196
197         Example 1:
198                 --> filename: Makefile
199                 ifneq ($(KERNELRELEASE),)
200                 # kbuild part of makefile
201                 obj-m  := 8123.o
202                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
203
204                 else
205                 # Normal Makefile
206
207                 KERNELDIR := /lib/modules/`uname -r`/build
208                 all::
209                         $(MAKE) -C $KERNELDIR M=`pwd` $@
210
211                 # Module specific targets
212                 genbin:
213                         echo "X" > 8123_bini.o_shipped
214
215                 endif
216
217         In example 1 the check for KERNELRELEASE is used to separate
218         the two parts of the Makefile. kbuild will only see the two
219         assignments whereas make will see everything except the two
220         kbuild assignments.
221
222         In recent versions of the kernel, kbuild will look for a file named
223         Kbuild and as second option look for a file named Makefile.
224         Utilising the Kbuild file makes us split up the Makefile in example 1
225         into two files as shown in example 2:
226
227         Example 2:
228                 --> filename: Kbuild
229                 obj-m  := 8123.o
230                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
231
232                 --> filename: Makefile
233                 KERNELDIR := /lib/modules/`uname -r`/build
234                 all::
235                         $(MAKE) -C $KERNELDIR M=`pwd` $@
236
237                 # Module specific targets
238                 genbin:
239                         echo "X" > 8123_bin_shipped
240
241
242         In example 2 we are down to two fairly simple files and for simple
243         files as used in this example the split is questionable. But some
244         external modules use Makefiles of several hundred lines and here it
245         really pays off to separate the kbuild part from the rest.
246         Example 3 shows a backward compatible version.
247
248         Example 3:
249                 --> filename: Kbuild
250                 obj-m  := 8123.o
251                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
252
253                 --> filename: Makefile
254                 ifneq ($(KERNELRELEASE),)
255                 include Kbuild
256                 else
257                 # Normal Makefile
258
259                 KERNELDIR := /lib/modules/`uname -r`/build
260                 all::
261                         $(MAKE) -C $KERNELDIR M=`pwd` $@
262
263                 # Module specific targets
264                 genbin:
265                         echo "X" > 8123_bin_shipped
266
267                 endif
268
269                 The trick here is to include the Kbuild file from Makefile so
270                 if an older version of kbuild picks up the Makefile the Kbuild
271                 file will be included.
272
273 --- 4.2 Binary blobs included in a module
274
275         Some external modules needs to include a .o as a blob. kbuild
276         has support for this, but requires the blob file to be named
277         <filename>_shipped. In our example the blob is named
278         8123_bin.o_shipped and when the kbuild rules kick in the file
279         8123_bin.o is created as a simple copy off the 8213_bin.o_shipped file
280         with the _shipped part stripped of the filename.
281         This allows the 8123_bin.o filename to be used in the assignment to
282         the module.
283
284         Example 4:
285                 obj-m  := 8123.o
286                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
287
288         In example 4 there is no distinction between the ordinary .c/.h files
289         and the binary file. But kbuild will pick up different rules to create
290         the .o file.
291
292
293 === 5. Include files
294
295 Include files are a necessity when a .c file uses something from another .c
296 files (not strictly in the sense of .c but if good programming practice is
297 used). Any module that consist of more than one .c file will have a .h file
298 for one of the .c files. 
299 - If the .h file only describes a module internal interface then the .h file
300   shall be placed in the same directory as the .c files.
301 - If the .h files describe an interface used by other parts of the kernel
302   located in different directories, the .h files shall be located in
303   include/linux/ or other include/ directories as appropriate.
304
305 One exception for this rule is larger subsystems that have their own directory
306 under include/ such as include/scsi. Another exception is arch-specific
307 .h files which are located under include/asm-$(ARCH)/*.
308
309 External modules have a tendency to locate include files in a separate include/
310 directory and therefore needs to deal with this in their kbuild file.
311
312 --- 5.1 How to include files from the kernel include dir
313
314         When a module needs to include a file from include/linux/ then one
315         just uses:
316
317                 #include <linux/modules.h>
318
319         kbuild will make sure to add options to gcc so the relevant
320         directories are searched.
321         Likewise for .h files placed in the same directory as the .c file.
322
323                 #include "8123_if.h"
324
325         will do the job.
326
327 --- 5.2 External modules using an include/ dir
328
329         External modules often locate their .h files in a separate include/
330         directory although this is not usual kernel style. When an external
331         module uses an include/ dir then kbuild needs to be told so.
332         The trick here is to use either EXTRA_CFLAGS (take effect for all .c
333         files) or CFLAGS_$F.o (take effect only for a single file).
334
335         In our example if we move 8123_if.h to a subdirectory named include/
336         the resulting Kbuild file would look like:
337
338                 --> filename: Kbuild
339                 obj-m  := 8123.o
340
341                 EXTRA_CFLAGS := -Iinclude
342                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
343
344         Note that in the assingment there is no space between -I and the path.
345         This is a kbuild limitation and no space must be present.
346
347
348 === 6. Module installation
349
350 Modules which are included in the kernel is installed in the directory:
351
352         /lib/modules/$(KERNELRELEASE)/kernel
353
354 External modules are installed in the directory:
355
356         /lib/modules/$(KERNELRELEASE)/extra
357
358 --- 6.1 INSTALL_MOD_PATH
359
360         Above are the default directories, but as always some level of
361         customization is possible. One can prefix the path using the variable
362         INSTALL_MOD_PATH:
363
364                 $ make INSTALL_MOD_PATH=/frodo modules_install
365                 => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel
366
367         INSTALL_MOD_PATH may be set as an ordinary shell variable or as in the
368         example above be specified on the commandline when calling make.
369         INSTALL_MOD_PATH has effect both when installing modules included in
370         the kernel as well as when installing external modules.
371
372 --- 6.2 INSTALL_MOD_DIR
373
374         When installing external modules they are default installed in a
375         directory under /lib/modules/$(KERNELRELEASE)/extra, but one may wish
376         to locate modules for a specific functionality in a separate
377         directory. For this purpose one can use INSTALL_MOD_DIR to specify an
378         alternative name than 'extra'.
379
380                 $ make INSTALL_MOD_DIR=gandalf -C KERNELDIR \
381                         M=`pwd` modules_install
382                 => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf
383
384
385 === 7. Module versioning
386
387 Module versioning are enabled by the CONFIG_MODVERSIONS tag.
388
389 Module versioning is used as a simple ABI consistency check. The Module
390 versioning creates a CRC value of the full prototype for an exported symbol and
391 when a module is loaded/used then the CRC values contained in the kernel are
392 compared with similar values in the module. If they are not equal then the
393 kernel refuses to load the module.
394
395 During a kernel build a file named Module.symvers will be generated. This
396 file includes the symbol version of all symbols within the kernel. If the 
397 Module.symvers file is saved from the last full kernel compile one does not
398 have to do a full kernel compile to build a module version's compatible module.
399
400 === 8. Tips & Tricks
401
402 --- 8.1 Testing for CONFIG_FOO_BAR
403
404         Modules often needs to check for certain CONFIG_ options to decide if
405         a specific feature shall be included in the module. When kbuild is used
406         this is done by referencing the CONFIG_ variable directly.
407
408                 #fs/ext2/Makefile
409                 obj-$(CONFIG_EXT2_FS) += ext2.o
410
411                 ext2-y := balloc.o bitmap.o dir.o
412                 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
413
414         External modules have traditionally used grep to check for specific
415         CONFIG_ settings directly in .config. This usage is broken.
416         As introduced before external modules shall use kbuild when building
417         and therefore can use the same methods as in-kernel modules when testing
418         for CONFIG_ definitions.
419