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