· 5 years ago · Feb 21, 2020, 01:58 PM
1Building External Modules
2=========================
3
4This document describes how to build an out-of-tree kernel module.
5
6.. Table of Contents
7
8 === 1 Introduction
9 === 2 How to Build External Modules
10 --- 2.1 Command Syntax
11 --- 2.2 Options
12 --- 2.3 Targets
13 --- 2.4 Building Separate Files
14 === 3. Creating a Kbuild File for an External Module
15 --- 3.1 Shared Makefile
16 --- 3.2 Separate Kbuild file and Makefile
17 --- 3.3 Binary Blobs
18 --- 3.4 Building Multiple Modules
19 === 4. Include Files
20 --- 4.1 Kernel Includes
21 --- 4.2 Single Subdirectory
22 --- 4.3 Several Subdirectories
23 === 5. Module Installation
24 --- 5.1 INSTALL_MOD_PATH
25 --- 5.2 INSTALL_MOD_DIR
26 === 6. Module Versioning
27 --- 6.1 Symbols From the Kernel (vmlinux + modules)
28 --- 6.2 Symbols and External Modules
29 --- 6.3 Symbols From Another External Module
30 === 7. Tips & Tricks
31 --- 7.1 Testing for CONFIG_FOO_BAR
32
33
34
351. Introduction
36===============
37
38"kbuild" is the build system used by the Linux kernel. Modules must use
39kbuild to stay compatible with changes in the build infrastructure and
40to pick up the right flags to "gcc." Functionality for building modules
41both in-tree and out-of-tree is provided. The method for building
42either is similar, and all modules are initially developed and built
43out-of-tree.
44
45Covered in this document is information aimed at developers interested
46in building out-of-tree (or "external") modules. The author of an
47external module should supply a makefile that hides most of the
48complexity, so one only has to type "make" to build the module. This is
49easily accomplished, and a complete example will be presented in
50section 3.
51
52
532. How to Build External Modules
54================================
55
56To build external modules, you must have a prebuilt kernel available
57that contains the configuration and header files used in the build.
58Also, the kernel must have been built with modules enabled. If you are
59using a distribution kernel, there will be a package for the kernel you
60are running provided by your distribution.
61
62An alternative is to use the "make" target "modules_prepare." This will
63make sure the kernel contains the information required. The target
64exists solely as a simple way to prepare a kernel source tree for
65building external modules.
66
67NOTE: "modules_prepare" will not build Module.symvers even if
68CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be
69executed to make module versioning work.
70
712.1 Command Syntax
72==================
73
74 The command to build an external module is::
75
76 $ make -C <path_to_kernel_src> M=$PWD
77
78 The kbuild system knows that an external module is being built
79 due to the "M=<dir>" option given in the command.
80
81 To build against the running kernel use::
82
83 $ make -C /lib/modules/`uname -r`/build M=$PWD
84
85 Then to install the module(s) just built, add the target
86 "modules_install" to the command::
87
88 $ make -C /lib/modules/`uname -r`/build M=$PWD modules_install
89
902.2 Options
91===========
92
93 ($KDIR refers to the path of the kernel source directory.)
94
95 make -C $KDIR M=$PWD
96
97 -C $KDIR
98 The directory where the kernel source is located.
99 "make" will actually change to the specified directory
100 when executing and will change back when finished.
101
102 M=$PWD
103 Informs kbuild that an external module is being built.
104 The value given to "M" is the absolute path of the
105 directory where the external module (kbuild file) is
106 located.
107
1082.3 Targets
109===========
110
111 When building an external module, only a subset of the "make"
112 targets are available.
113
114 make -C $KDIR M=$PWD [target]
115
116 The default will build the module(s) located in the current
117 directory, so a target does not need to be specified. All
118 output files will also be generated in this directory. No
119 attempts are made to update the kernel source, and it is a
120 precondition that a successful "make" has been executed for the
121 kernel.
122
123 modules
124 The default target for external modules. It has the
125 same functionality as if no target was specified. See
126 description above.
127
128 modules_install
129 Install the external module(s). The default location is
130 /lib/modules/<kernel_release>/extra/, but a prefix may
131 be added with INSTALL_MOD_PATH (discussed in section 5).
132
133 clean
134 Remove all generated files in the module directory only.
135
136 help
137 List the available targets for external modules.
138
1392.4 Building Separate Files
140===========================
141
142 It is possible to build single files that are part of a module.
143 This works equally well for the kernel, a module, and even for
144 external modules.
145
146 Example (The module foo.ko, consist of bar.o and baz.o)::
147
148 make -C $KDIR M=$PWD bar.lst
149 make -C $KDIR M=$PWD baz.o
150 make -C $KDIR M=$PWD foo.ko
151 make -C $KDIR M=$PWD ./
152
153
1543. Creating a Kbuild File for an External Module
155================================================
156
157In the last section we saw the command to build a module for the
158running kernel. The module is not actually built, however, because a
159build file is required. Contained in this file will be the name of
160the module(s) being built, along with the list of requisite source
161files. The file may be as simple as a single line::
162
163 obj-m := <module_name>.o
164
165The kbuild system will build <module_name>.o from <module_name>.c,
166and, after linking, will result in the kernel module <module_name>.ko.
167The above line can be put in either a "Kbuild" file or a "Makefile."
168When the module is built from multiple sources, an additional line is
169needed listing the files::
170
171 <module_name>-y := <src1>.o <src2>.o ...
172
173NOTE: Further documentation describing the syntax used by kbuild is
174located in Documentation/kbuild/makefiles.rst.
175
176The examples below demonstrate how to create a build file for the
177module 8123.ko, which is built from the following files::
178
179 8123_if.c
180 8123_if.h
181 8123_pci.c
182 8123_bin.o_shipped <= Binary blob
183
184--- 3.1 Shared Makefile
185
186 An external module always includes a wrapper makefile that
187 supports building the module using "make" with no arguments.
188 This target is not used by kbuild; it is only for convenience.
189 Additional functionality, such as test targets, can be included
190 but should be filtered out from kbuild due to possible name
191 clashes.
192
193 Example 1::
194
195 --> filename: Makefile
196 ifneq ($(KERNELRELEASE),)
197 # kbuild part of makefile
198 obj-m := 8123.o
199 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
200
201 else
202 # normal makefile
203 KDIR ?= /lib/modules/`uname -r`/build
204
205 default:
206 $(MAKE) -C $(KDIR) M=$$PWD
207
208 # Module specific targets
209 genbin:
210 echo "X" > 8123_bin.o_shipped
211
212 endif
213
214 The check for KERNELRELEASE is used to separate the two parts
215 of the makefile. In the example, kbuild will only see the two
216 assignments, whereas "make" will see everything except these
217 two assignments. This is due to two passes made on the file:
218 the first pass is by the "make" instance run on the command
219 line; the second pass is by the kbuild system, which is
220 initiated by the parameterized "make" in the default target.
221
2223.2 Separate Kbuild File and Makefile
223-------------------------------------
224
225 In newer versions of the kernel, kbuild will first look for a
226 file named "Kbuild," and only if that is not found, will it
227 then look for a makefile. Utilizing a "Kbuild" file allows us
228 to split up the makefile from example 1 into two files:
229
230 Example 2::
231
232 --> filename: Kbuild
233 obj-m := 8123.o
234 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
235
236 --> filename: Makefile
237 KDIR ?= /lib/modules/`uname -r`/build
238
239 default:
240 $(MAKE) -C $(KDIR) M=$$PWD
241
242 # Module specific targets
243 genbin:
244 echo "X" > 8123_bin.o_shipped
245
246 The split in example 2 is questionable due to the simplicity of
247 each file; however, some external modules use makefiles
248 consisting of several hundred lines, and here it really pays
249 off to separate the kbuild part from the rest.
250
251 The next example shows a backward compatible version.
252
253 Example 3::
254
255 --> filename: Kbuild
256 obj-m := 8123.o
257 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
258
259 --> filename: Makefile
260 ifneq ($(KERNELRELEASE),)
261 # kbuild part of makefile
262 include Kbuild
263
264 else
265 # normal makefile
266 KDIR ?= /lib/modules/`uname -r`/build
267
268 default:
269 $(MAKE) -C $(KDIR) M=$$PWD
270
271 # Module specific targets
272 genbin:
273 echo "X" > 8123_bin.o_shipped
274
275 endif
276
277 Here the "Kbuild" file is included from the makefile. This
278 allows an older version of kbuild, which only knows of
279 makefiles, to be used when the "make" and kbuild parts are
280 split into separate files.
281
2823.3 Binary Blobs
283----------------
284
285 Some external modules need to include an object file as a blob.
286 kbuild has support for this, but requires the blob file to be
287 named <filename>_shipped. When the kbuild rules kick in, a copy
288 of <filename>_shipped is created with _shipped stripped off,
289 giving us <filename>. This shortened filename can be used in
290 the assignment to the module.
291
292 Throughout this section, 8123_bin.o_shipped has been used to
293 build the kernel module 8123.ko; it has been included as
294 8123_bin.o::
295
296 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
297
298 Although there is no distinction between the ordinary source
299 files and the binary file, kbuild will pick up different rules
300 when creating the object file for the module.
301
3023.4 Building Multiple Modules
303=============================
304
305 kbuild supports building multiple modules with a single build
306 file. For example, if you wanted to build two modules, foo.ko
307 and bar.ko, the kbuild lines would be::
308
309 obj-m := foo.o bar.o
310 foo-y := <foo_srcs>
311 bar-y := <bar_srcs>
312
313 It is that simple!
314
315
3164. Include Files
317================
318
319Within the kernel, header files are kept in standard locations
320according to the following rule:
321
322 * If the header file only describes the internal interface of a
323 module, then the file is placed in the same directory as the
324 source files.
325 * If the header file describes an interface used by other parts
326 of the kernel that are located in different directories, then
327 the file is placed in include/linux/.
328
329 NOTE:
330 There are two notable exceptions to this rule: larger
331 subsystems have their own directory under include/, such as
332 include/scsi; and architecture specific headers are located
333 under arch/$(ARCH)/include/.
334
3354.1 Kernel Includes
336-------------------
337
338 To include a header file located under include/linux/, simply
339 use::
340
341 #include <linux/module.h>
342
343 kbuild will add options to "gcc" so the relevant directories
344 are searched.
345
3464.2 Single Subdirectory
347-----------------------
348
349 External modules tend to place header files in a separate
350 include/ directory where their source is located, although this
351 is not the usual kernel style. To inform kbuild of the
352 directory, use either ccflags-y or CFLAGS_<filename>.o.
353
354 Using the example from section 3, if we moved 8123_if.h to a
355 subdirectory named include, the resulting kbuild file would
356 look like::
357
358 --> filename: Kbuild
359 obj-m := 8123.o
360
361 ccflags-y := -Iinclude
362 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
363
364 Note that in the assignment there is no space between -I and
365 the path. This is a limitation of kbuild: there must be no
366 space present.
367
3684.3 Several Subdirectories
369--------------------------
370
371 kbuild can handle files that are spread over several directories.
372 Consider the following example::
373
374 .
375 |__ src
376 | |__ complex_main.c
377 | |__ hal
378 | |__ hardwareif.c
379 | |__ include
380 | |__ hardwareif.h
381 |__ include
382 |__ complex.h
383
384 To build the module complex.ko, we then need the following
385 kbuild file::
386
387 --> filename: Kbuild
388 obj-m := complex.o
389 complex-y := src/complex_main.o
390 complex-y += src/hal/hardwareif.o
391
392 ccflags-y := -I$(src)/include
393 ccflags-y += -I$(src)/src/hal/include
394
395 As you can see, kbuild knows how to handle object files located
396 in other directories. The trick is to specify the directory
397 relative to the kbuild file's location. That being said, this
398 is NOT recommended practice.
399
400 For the header files, kbuild must be explicitly told where to
401 look. When kbuild executes, the current directory is always the
402 root of the kernel tree (the argument to "-C") and therefore an
403 absolute path is needed. $(src) provides the absolute path by
404 pointing to the directory where the currently executing kbuild
405 file is located.
406
407
4085. Module Installation
409======================
410
411Modules which are included in the kernel are installed in the
412directory:
413
414 /lib/modules/$(KERNELRELEASE)/kernel/
415
416And external modules are installed in:
417
418 /lib/modules/$(KERNELRELEASE)/extra/
419
4205.1 INSTALL_MOD_PATH
421--------------------
422
423 Above are the default directories but as always some level of
424 customization is possible. A prefix can be added to the
425 installation path using the variable INSTALL_MOD_PATH::
426
427 $ make INSTALL_MOD_PATH=/frodo modules_install
428 => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/
429
430 INSTALL_MOD_PATH may be set as an ordinary shell variable or,
431 as shown above, can be specified on the command line when
432 calling "make." This has effect when installing both in-tree
433 and out-of-tree modules.
434
4355.2 INSTALL_MOD_DIR
436-------------------
437
438 External modules are by default installed to a directory under
439 /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to
440 locate modules for a specific functionality in a separate
441 directory. For this purpose, use INSTALL_MOD_DIR to specify an
442 alternative name to "extra."::
443
444 $ make INSTALL_MOD_DIR=gandalf -C $KDIR \
445 M=$PWD modules_install
446 => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/
447
448
4496. Module Versioning
450====================
451
452Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used
453as a simple ABI consistency check. A CRC value of the full prototype
454for an exported symbol is created. When a module is loaded/used, the
455CRC values contained in the kernel are compared with similar values in
456the module; if they are not equal, the kernel refuses to load the
457module.
458
459Module.symvers contains a list of all exported symbols from a kernel
460build.
461
4626.1 Symbols From the Kernel (vmlinux + modules)
463-----------------------------------------------
464
465 During a kernel build, a file named Module.symvers will be
466 generated. Module.symvers contains all exported symbols from
467 the kernel and compiled modules. For each symbol, the
468 corresponding CRC value is also stored.
469
470 The syntax of the Module.symvers file is::
471
472 <CRC> <Symbol> <module>
473
474 0x2d036834 scsi_remove_host drivers/scsi/scsi_mod
475
476 For a kernel build without CONFIG_MODVERSIONS enabled, the CRC
477 would read 0x00000000.
478
479 Module.symvers serves two purposes:
480
481 1) It lists all exported symbols from vmlinux and all modules.
482 2) It lists the CRC if CONFIG_MODVERSIONS is enabled.
483
4846.2 Symbols and External Modules
485--------------------------------
486
487 When building an external module, the build system needs access
488 to the symbols from the kernel to check if all external symbols
489 are defined. This is done in the MODPOST step. modpost obtains
490 the symbols by reading Module.symvers from the kernel source
491 tree. If a Module.symvers file is present in the directory
492 where the external module is being built, this file will be
493 read too. During the MODPOST step, a new Module.symvers file
494 will be written containing all exported symbols that were not
495 defined in the kernel.
496
497--- 6.3 Symbols From Another External Module
498
499 Sometimes, an external module uses exported symbols from
500 another external module. kbuild needs to have full knowledge of
501 all symbols to avoid spitting out warnings about undefined
502 symbols. Three solutions exist for this situation.
503
504 NOTE: The method with a top-level kbuild file is recommended
505 but may be impractical in certain situations.
506
507 Use a top-level kbuild file
508 If you have two modules, foo.ko and bar.ko, where
509 foo.ko needs symbols from bar.ko, you can use a
510 common top-level kbuild file so both modules are
511 compiled in the same build. Consider the following
512 directory layout::
513
514 ./foo/ <= contains foo.ko
515 ./bar/ <= contains bar.ko
516
517 The top-level kbuild file would then look like::
518
519 #./Kbuild (or ./Makefile):
520 obj-y := foo/ bar/
521
522 And executing::
523
524 $ make -C $KDIR M=$PWD
525
526 will then do the expected and compile both modules with
527 full knowledge of symbols from either module.
528
529 Use an extra Module.symvers file
530 When an external module is built, a Module.symvers file
531 is generated containing all exported symbols which are
532 not defined in the kernel. To get access to symbols
533 from bar.ko, copy the Module.symvers file from the
534 compilation of bar.ko to the directory where foo.ko is
535 built. During the module build, kbuild will read the
536 Module.symvers file in the directory of the external
537 module, and when the build is finished, a new
538 Module.symvers file is created containing the sum of
539 all symbols defined and not part of the kernel.
540
541 Use "make" variable KBUILD_EXTRA_SYMBOLS
542 If it is impractical to copy Module.symvers from
543 another module, you can assign a space separated list
544 of files to KBUILD_EXTRA_SYMBOLS in your build file.
545 These files will be loaded by modpost during the
546 initialization of its symbol tables.
547
548
5497. Tips & Tricks
550================
551
5527.1 Testing for CONFIG_FOO_BAR
553------------------------------
554
555 Modules often need to check for certain `CONFIG_` options to
556 decide if a specific feature is included in the module. In
557 kbuild this is done by referencing the `CONFIG_` variable
558 directly::
559
560 #fs/ext2/Makefile
561 obj-$(CONFIG_EXT2_FS) += ext2.o
562
563 ext2-y := balloc.o bitmap.o dir.o
564 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
565
566 External modules have traditionally used "grep" to check for
567 specific `CONFIG_` settings directly in .config. This usage is
568 broken. As introduced before, external modules should use
569 kbuild for building and can therefore use the same methods as
570 in-tree modules when testing for `CONFIG_` definitions.