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