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