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