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