aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/kbuild/modules.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/kbuild/modules.txt')
-rw-r--r--Documentation/kbuild/modules.txt419
1 files changed, 419 insertions, 0 deletions
diff --git a/Documentation/kbuild/modules.txt b/Documentation/kbuild/modules.txt
new file mode 100644
index 000000000000..c91caf7eb303
--- /dev/null
+++ b/Documentation/kbuild/modules.txt
@@ -0,0 +1,419 @@
1
2In 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
32kbuild includes functionality for building modules both
33within the kernel source tree and outside the kernel source tree.
34The latter is usually referred to as external modules and is used
35both during development and for modules that are not planned to be
36included in the kernel tree.
37
38What is covered within this file is mainly information to authors
39of modules. The author of an external modules should supply
40a 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
42chapter ¤. Creating a kbuild file for an external module".
43
44
45=== 2. How to build external modules
46
47kbuild offers functionality to build external modules, with the
48prerequisite that there is a pre-built kernel available with full source.
49A subset of the targets available when building the kernel is available
50when 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
136This example shows the actual commands to be executed when building
137an external module for the currently running kernel.
138In the example below the distribution is supposed to use the
139facility to locate output files for a kernel compile in a different
140directory than the kernel source - but the examples will also work
141when 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
149Change to the directory where the kbuild file is located and execute
150the 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
157Then 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
164If one looks closely you will see that this is the same commands as
165listed before - with the directories spelled out.
166
167The above are rather long commands, and the following chapter
168lists a few tricks to make it all easier.
169
170
171=== 4. Creating a kbuild file for an external module
172
173kbuild is the build system for the kernel, and external modules
174must use kbuild to stay compatible with changes in the build system
175and to pick up the right flags to gcc etc.
176
177The kbuild file used as input shall follow the syntax described
178in Documentation/kbuild/makefiles.txt. This chapter will introduce a few
179more tricks to be used when dealing with external modules.
180
181In the following a Makefile will be created for a module with the
182following 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
295Include files are a necessity when a .c file uses something from another .c
296files (not strictly in the sense of .c but if good programming practice is
297used). Any module that consist of more than one .c file will have a .h file
298for 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
305One exception for this rule is larger subsystems that have their own directory
306under include/ such as include/scsi. Another exception is arch-specific
307.h files which are located under include/asm-$(ARCH)/*.
308
309External modules have a tendency to locate include files in a separate include/
310directory 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
350Modules which are included in the kernel is installed in the directory:
351
352 /lib/modules/$(KERNELRELEASE)/kernel
353
354External 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
387Module versioning are enabled by the CONFIG_MODVERSIONS tag.
388
389Module versioning is used as a simple ABI consistency check. The Module
390versioning creates a CRC value of the full prototype for an exported symbol and
391when a module is loaded/used then the CRC values contained in the kernel are
392compared with similar values in the module. If they are not equal then the
393kernel refuses to load the module.
394
395During a kernel build a file named Module.symvers will be generated. This
396file includes the symbol version of all symbols within the kernel. If the
397Module.symvers file is saved from the last full kernel compile one does not
398have 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