466 lines · plain
1=========================2Building External Modules3=========================4 5This document describes how to build an out-of-tree kernel module.6 7Introduction8============9 10"kbuild" is the build system used by the Linux kernel. Modules must use11kbuild to stay compatible with changes in the build infrastructure and12to pick up the right flags to the compiler. Functionality for building modules13both in-tree and out-of-tree is provided. The method for building14either is similar, and all modules are initially developed and built15out-of-tree.16 17Covered in this document is information aimed at developers interested18in building out-of-tree (or "external") modules. The author of an19external module should supply a makefile that hides most of the20complexity, so one only has to type "make" to build the module. This is21easily accomplished, and a complete example will be presented in22section `Creating a Kbuild File for an External Module`_.23 24 25How to Build External Modules26=============================27 28To build external modules, you must have a prebuilt kernel available29that contains the configuration and header files used in the build.30Also, the kernel must have been built with modules enabled. If you are31using a distribution kernel, there will be a package for the kernel you32are running provided by your distribution.33 34An alternative is to use the "make" target "modules_prepare." This will35make sure the kernel contains the information required. The target36exists solely as a simple way to prepare a kernel source tree for37building external modules.38 39NOTE: "modules_prepare" will not build Module.symvers even if40CONFIG_MODVERSIONS is set; therefore, a full kernel build needs to be41executed to make module versioning work.42 43Command Syntax44--------------45 46 The command to build an external module is::47 48 $ make -C <path_to_kernel_dir> M=$PWD49 50 The kbuild system knows that an external module is being built51 due to the "M=<dir>" option given in the command.52 53 To build against the running kernel use::54 55 $ make -C /lib/modules/`uname -r`/build M=$PWD56 57 Then to install the module(s) just built, add the target58 "modules_install" to the command::59 60 $ make -C /lib/modules/`uname -r`/build M=$PWD modules_install61 62Options63-------64 65 ($KDIR refers to the path of the kernel source directory, or the path66 of the kernel output directory if the kernel was built in a separate67 build directory.)68 69 make -C $KDIR M=$PWD70 71 -C $KDIR72 The directory that contains the kernel and relevant build73 artifacts used for building an external module.74 "make" will actually change to the specified directory75 when executing and will change back when finished.76 77 M=$PWD78 Informs kbuild that an external module is being built.79 The value given to "M" is the absolute path of the80 directory where the external module (kbuild file) is81 located.82 83Targets84-------85 86 When building an external module, only a subset of the "make"87 targets are available.88 89 make -C $KDIR M=$PWD [target]90 91 The default will build the module(s) located in the current92 directory, so a target does not need to be specified. All93 output files will also be generated in this directory. No94 attempts are made to update the kernel source, and it is a95 precondition that a successful "make" has been executed for the96 kernel.97 98 modules99 The default target for external modules. It has the100 same functionality as if no target was specified. See101 description above.102 103 modules_install104 Install the external module(s). The default location is105 /lib/modules/<kernel_release>/updates/, but a prefix may106 be added with INSTALL_MOD_PATH (discussed in section107 `Module Installation`_).108 109 clean110 Remove all generated files in the module directory only.111 112 help113 List the available targets for external modules.114 115Building Separate Files116-----------------------117 118 It is possible to build single files that are part of a module.119 This works equally well for the kernel, a module, and even for120 external modules.121 122 Example (The module foo.ko, consist of bar.o and baz.o)::123 124 make -C $KDIR M=$PWD bar.lst125 make -C $KDIR M=$PWD baz.o126 make -C $KDIR M=$PWD foo.ko127 make -C $KDIR M=$PWD ./128 129 130Creating a Kbuild File for an External Module131=============================================132 133In the last section we saw the command to build a module for the134running kernel. The module is not actually built, however, because a135build file is required. Contained in this file will be the name of136the module(s) being built, along with the list of requisite source137files. The file may be as simple as a single line::138 139 obj-m := <module_name>.o140 141The kbuild system will build <module_name>.o from <module_name>.c,142and, after linking, will result in the kernel module <module_name>.ko.143The above line can be put in either a "Kbuild" file or a "Makefile."144When the module is built from multiple sources, an additional line is145needed listing the files::146 147 <module_name>-y := <src1>.o <src2>.o ...148 149NOTE: Further documentation describing the syntax used by kbuild is150located in Documentation/kbuild/makefiles.rst.151 152The examples below demonstrate how to create a build file for the153module 8123.ko, which is built from the following files::154 155 8123_if.c156 8123_if.h157 8123_pci.c158 159Shared Makefile160---------------161 162 An external module always includes a wrapper makefile that163 supports building the module using "make" with no arguments.164 This target is not used by kbuild; it is only for convenience.165 Additional functionality, such as test targets, can be included166 but should be filtered out from kbuild due to possible name167 clashes.168 169 Example 1::170 171 --> filename: Makefile172 ifneq ($(KERNELRELEASE),)173 # kbuild part of makefile174 obj-m := 8123.o175 8123-y := 8123_if.o 8123_pci.o176 177 else178 # normal makefile179 KDIR ?= /lib/modules/`uname -r`/build180 181 default:182 $(MAKE) -C $(KDIR) M=$$PWD183 184 endif185 186 The check for KERNELRELEASE is used to separate the two parts187 of the makefile. In the example, kbuild will only see the two188 assignments, whereas "make" will see everything except these189 two assignments. This is due to two passes made on the file:190 the first pass is by the "make" instance run on the command191 line; the second pass is by the kbuild system, which is192 initiated by the parameterized "make" in the default target.193 194Separate Kbuild File and Makefile195---------------------------------196 197 Kbuild will first look for a file named "Kbuild", and if it is not198 found, it will then look for "Makefile". Utilizing a "Kbuild" file199 allows us to split up the "Makefile" from example 1 into two files:200 201 Example 2::202 203 --> filename: Kbuild204 obj-m := 8123.o205 8123-y := 8123_if.o 8123_pci.o206 207 --> filename: Makefile208 KDIR ?= /lib/modules/`uname -r`/build209 210 default:211 $(MAKE) -C $(KDIR) M=$$PWD212 213 The split in example 2 is questionable due to the simplicity of214 each file; however, some external modules use makefiles215 consisting of several hundred lines, and here it really pays216 off to separate the kbuild part from the rest.217 218Building Multiple Modules219-------------------------220 221 kbuild supports building multiple modules with a single build222 file. For example, if you wanted to build two modules, foo.ko223 and bar.ko, the kbuild lines would be::224 225 obj-m := foo.o bar.o226 foo-y := <foo_srcs>227 bar-y := <bar_srcs>228 229 It is that simple!230 231 232Include Files233=============234 235Within the kernel, header files are kept in standard locations236according to the following rule:237 238 * If the header file only describes the internal interface of a239 module, then the file is placed in the same directory as the240 source files.241 * If the header file describes an interface used by other parts242 of the kernel that are located in different directories, then243 the file is placed in include/linux/.244 245 NOTE:246 There are two notable exceptions to this rule: larger247 subsystems have their own directory under include/, such as248 include/scsi; and architecture specific headers are located249 under arch/$(SRCARCH)/include/.250 251Kernel Includes252---------------253 254 To include a header file located under include/linux/, simply255 use::256 257 #include <linux/module.h>258 259 kbuild will add options to the compiler so the relevant directories260 are searched.261 262Single Subdirectory263-------------------264 265 External modules tend to place header files in a separate266 include/ directory where their source is located, although this267 is not the usual kernel style. To inform kbuild of the268 directory, use either ccflags-y or CFLAGS_<filename>.o.269 270 Using the example from section 3, if we moved 8123_if.h to a271 subdirectory named include, the resulting kbuild file would272 look like::273 274 --> filename: Kbuild275 obj-m := 8123.o276 277 ccflags-y := -I $(src)/include278 8123-y := 8123_if.o 8123_pci.o279 280Several Subdirectories281----------------------282 283 kbuild can handle files that are spread over several directories.284 Consider the following example::285 286 .287 |__ src288 | |__ complex_main.c289 | |__ hal290 | |__ hardwareif.c291 | |__ include292 | |__ hardwareif.h293 |__ include294 |__ complex.h295 296 To build the module complex.ko, we then need the following297 kbuild file::298 299 --> filename: Kbuild300 obj-m := complex.o301 complex-y := src/complex_main.o302 complex-y += src/hal/hardwareif.o303 304 ccflags-y := -I$(src)/include305 ccflags-y += -I$(src)/src/hal/include306 307 As you can see, kbuild knows how to handle object files located308 in other directories. The trick is to specify the directory309 relative to the kbuild file's location. That being said, this310 is NOT recommended practice.311 312 For the header files, kbuild must be explicitly told where to313 look. When kbuild executes, the current directory is always the314 root of the kernel tree (the argument to "-C") and therefore an315 absolute path is needed. $(src) provides the absolute path by316 pointing to the directory where the currently executing kbuild317 file is located.318 319 320Module Installation321===================322 323Modules which are included in the kernel are installed in the324directory:325 326 /lib/modules/$(KERNELRELEASE)/kernel/327 328And external modules are installed in:329 330 /lib/modules/$(KERNELRELEASE)/updates/331 332INSTALL_MOD_PATH333----------------334 335 Above are the default directories but as always some level of336 customization is possible. A prefix can be added to the337 installation path using the variable INSTALL_MOD_PATH::338 339 $ make INSTALL_MOD_PATH=/frodo modules_install340 => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/341 342 INSTALL_MOD_PATH may be set as an ordinary shell variable or,343 as shown above, can be specified on the command line when344 calling "make." This has effect when installing both in-tree345 and out-of-tree modules.346 347INSTALL_MOD_DIR348---------------349 350 External modules are by default installed to a directory under351 /lib/modules/$(KERNELRELEASE)/updates/, but you may wish to352 locate modules for a specific functionality in a separate353 directory. For this purpose, use INSTALL_MOD_DIR to specify an354 alternative name to "updates."::355 356 $ make INSTALL_MOD_DIR=gandalf -C $KDIR \357 M=$PWD modules_install358 => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/359 360 361Module Versioning362=================363 364Module versioning is enabled by the CONFIG_MODVERSIONS tag, and is used365as a simple ABI consistency check. A CRC value of the full prototype366for an exported symbol is created. When a module is loaded/used, the367CRC values contained in the kernel are compared with similar values in368the module; if they are not equal, the kernel refuses to load the369module.370 371Module.symvers contains a list of all exported symbols from a kernel372build.373 374Symbols From the Kernel (vmlinux + modules)375-------------------------------------------376 377 During a kernel build, a file named Module.symvers will be378 generated. Module.symvers contains all exported symbols from379 the kernel and compiled modules. For each symbol, the380 corresponding CRC value is also stored.381 382 The syntax of the Module.symvers file is::383 384 <CRC> <Symbol> <Module> <Export Type> <Namespace>385 386 0xe1cc2a05 usb_stor_suspend drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL USB_STORAGE387 388 The fields are separated by tabs and values may be empty (e.g.389 if no namespace is defined for an exported symbol).390 391 For a kernel build without CONFIG_MODVERSIONS enabled, the CRC392 would read 0x00000000.393 394 Module.symvers serves two purposes:395 396 1) It lists all exported symbols from vmlinux and all modules.397 2) It lists the CRC if CONFIG_MODVERSIONS is enabled.398 399Symbols and External Modules400----------------------------401 402 When building an external module, the build system needs access403 to the symbols from the kernel to check if all external symbols404 are defined. This is done in the MODPOST step. modpost obtains405 the symbols by reading Module.symvers from the kernel source406 tree. During the MODPOST step, a new Module.symvers file will be407 written containing all exported symbols from that external module.408 409Symbols From Another External Module410------------------------------------411 412 Sometimes, an external module uses exported symbols from413 another external module. Kbuild needs to have full knowledge of414 all symbols to avoid spitting out warnings about undefined415 symbols. Two solutions exist for this situation.416 417 NOTE: The method with a top-level kbuild file is recommended418 but may be impractical in certain situations.419 420 Use a top-level kbuild file421 If you have two modules, foo.ko and bar.ko, where422 foo.ko needs symbols from bar.ko, you can use a423 common top-level kbuild file so both modules are424 compiled in the same build. Consider the following425 directory layout::426 427 ./foo/ <= contains foo.ko428 ./bar/ <= contains bar.ko429 430 The top-level kbuild file would then look like::431 432 #./Kbuild (or ./Makefile):433 obj-m := foo/ bar/434 435 And executing::436 437 $ make -C $KDIR M=$PWD438 439 will then do the expected and compile both modules with440 full knowledge of symbols from either module.441 442 Use "make" variable KBUILD_EXTRA_SYMBOLS443 If it is impractical to add a top-level kbuild file,444 you can assign a space separated list445 of files to KBUILD_EXTRA_SYMBOLS in your build file.446 These files will be loaded by modpost during the447 initialization of its symbol tables.448 449 450Tips & Tricks451=============452 453Testing for CONFIG_FOO_BAR454--------------------------455 456 Modules often need to check for certain `CONFIG_` options to457 decide if a specific feature is included in the module. In458 kbuild this is done by referencing the `CONFIG_` variable459 directly::460 461 #fs/ext2/Makefile462 obj-$(CONFIG_EXT2_FS) += ext2.o463 464 ext2-y := balloc.o bitmap.o dir.o465 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o466