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 185cd238effSMauro Carvalho Chehab--- 3.1 Shared Makefile 186cd238effSMauro Carvalho Chehab 187cd238effSMauro Carvalho Chehab An external module always includes a wrapper makefile that 188cd238effSMauro Carvalho Chehab supports building the module using "make" with no arguments. 189cd238effSMauro Carvalho Chehab This target is not used by kbuild; it is only for convenience. 190cd238effSMauro Carvalho Chehab Additional functionality, such as test targets, can be included 191cd238effSMauro Carvalho Chehab but should be filtered out from kbuild due to possible name 192cd238effSMauro Carvalho Chehab clashes. 193cd238effSMauro Carvalho Chehab 194cd238effSMauro Carvalho Chehab Example 1:: 195cd238effSMauro Carvalho Chehab 196cd238effSMauro Carvalho Chehab --> filename: Makefile 197cd238effSMauro Carvalho Chehab ifneq ($(KERNELRELEASE),) 198cd238effSMauro Carvalho Chehab # kbuild part of makefile 199cd238effSMauro Carvalho Chehab obj-m := 8123.o 200cd238effSMauro Carvalho Chehab 8123-y := 8123_if.o 8123_pci.o 8123_bin.o 201cd238effSMauro Carvalho Chehab 202cd238effSMauro Carvalho Chehab else 203cd238effSMauro Carvalho Chehab # normal makefile 204cd238effSMauro Carvalho Chehab KDIR ?= /lib/modules/`uname -r`/build 205cd238effSMauro Carvalho Chehab 206cd238effSMauro Carvalho Chehab default: 207cd238effSMauro Carvalho Chehab $(MAKE) -C $(KDIR) M=$$PWD 208cd238effSMauro Carvalho Chehab 209cd238effSMauro Carvalho Chehab # Module specific targets 210cd238effSMauro Carvalho Chehab genbin: 211cd238effSMauro Carvalho Chehab echo "X" > 8123_bin.o_shipped 212cd238effSMauro Carvalho Chehab 213cd238effSMauro Carvalho Chehab endif 214cd238effSMauro Carvalho Chehab 215cd238effSMauro Carvalho Chehab The check for KERNELRELEASE is used to separate the two parts 216cd238effSMauro Carvalho Chehab of the makefile. In the example, kbuild will only see the two 217cd238effSMauro Carvalho Chehab assignments, whereas "make" will see everything except these 218cd238effSMauro Carvalho Chehab two assignments. This is due to two passes made on the file: 219cd238effSMauro Carvalho Chehab the first pass is by the "make" instance run on the command 220cd238effSMauro Carvalho Chehab line; the second pass is by the kbuild system, which is 221cd238effSMauro Carvalho Chehab initiated by the parameterized "make" in the default target. 222cd238effSMauro Carvalho Chehab 223cd238effSMauro Carvalho Chehab3.2 Separate Kbuild File and Makefile 224cd238effSMauro Carvalho Chehab------------------------------------- 225cd238effSMauro Carvalho Chehab 226cd238effSMauro Carvalho Chehab In newer versions of the kernel, kbuild will first look for a 227cd238effSMauro Carvalho Chehab file named "Kbuild," and only if that is not found, will it 228cd238effSMauro Carvalho Chehab then look for a makefile. Utilizing a "Kbuild" file allows us 229cd238effSMauro Carvalho Chehab to split up the makefile from example 1 into two files: 230cd238effSMauro Carvalho Chehab 231cd238effSMauro Carvalho Chehab Example 2:: 232cd238effSMauro Carvalho Chehab 233cd238effSMauro Carvalho Chehab --> filename: Kbuild 234cd238effSMauro Carvalho Chehab obj-m := 8123.o 235cd238effSMauro Carvalho Chehab 8123-y := 8123_if.o 8123_pci.o 8123_bin.o 236cd238effSMauro Carvalho Chehab 237cd238effSMauro Carvalho Chehab --> filename: Makefile 238cd238effSMauro Carvalho Chehab KDIR ?= /lib/modules/`uname -r`/build 239cd238effSMauro Carvalho Chehab 240cd238effSMauro Carvalho Chehab default: 241cd238effSMauro Carvalho Chehab $(MAKE) -C $(KDIR) M=$$PWD 242cd238effSMauro Carvalho Chehab 243cd238effSMauro Carvalho Chehab # Module specific targets 244cd238effSMauro Carvalho Chehab genbin: 245cd238effSMauro Carvalho Chehab echo "X" > 8123_bin.o_shipped 246cd238effSMauro Carvalho Chehab 247cd238effSMauro Carvalho Chehab The split in example 2 is questionable due to the simplicity of 248cd238effSMauro Carvalho Chehab each file; however, some external modules use makefiles 249cd238effSMauro Carvalho Chehab consisting of several hundred lines, and here it really pays 250cd238effSMauro Carvalho Chehab off to separate the kbuild part from the rest. 251cd238effSMauro Carvalho Chehab 252cd238effSMauro Carvalho Chehab The next example shows a backward compatible version. 253cd238effSMauro Carvalho Chehab 254cd238effSMauro Carvalho Chehab Example 3:: 255cd238effSMauro Carvalho Chehab 256cd238effSMauro Carvalho Chehab --> filename: Kbuild 257cd238effSMauro Carvalho Chehab obj-m := 8123.o 258cd238effSMauro Carvalho Chehab 8123-y := 8123_if.o 8123_pci.o 8123_bin.o 259cd238effSMauro Carvalho Chehab 260cd238effSMauro Carvalho Chehab --> filename: Makefile 261cd238effSMauro Carvalho Chehab ifneq ($(KERNELRELEASE),) 262cd238effSMauro Carvalho Chehab # kbuild part of makefile 263cd238effSMauro Carvalho Chehab include Kbuild 264cd238effSMauro Carvalho Chehab 265cd238effSMauro Carvalho Chehab else 266cd238effSMauro Carvalho Chehab # normal makefile 267cd238effSMauro Carvalho Chehab KDIR ?= /lib/modules/`uname -r`/build 268cd238effSMauro Carvalho Chehab 269cd238effSMauro Carvalho Chehab default: 270cd238effSMauro Carvalho Chehab $(MAKE) -C $(KDIR) M=$$PWD 271cd238effSMauro Carvalho Chehab 272cd238effSMauro Carvalho Chehab # Module specific targets 273cd238effSMauro Carvalho Chehab genbin: 274cd238effSMauro Carvalho Chehab echo "X" > 8123_bin.o_shipped 275cd238effSMauro Carvalho Chehab 276cd238effSMauro Carvalho Chehab endif 277cd238effSMauro Carvalho Chehab 278cd238effSMauro Carvalho Chehab Here the "Kbuild" file is included from the makefile. This 279cd238effSMauro Carvalho Chehab allows an older version of kbuild, which only knows of 280cd238effSMauro Carvalho Chehab makefiles, to be used when the "make" and kbuild parts are 281cd238effSMauro Carvalho Chehab split into separate files. 282cd238effSMauro Carvalho Chehab 283cd238effSMauro Carvalho Chehab3.3 Binary Blobs 284cd238effSMauro Carvalho Chehab---------------- 285cd238effSMauro Carvalho Chehab 286cd238effSMauro Carvalho Chehab Some external modules need to include an object file as a blob. 287cd238effSMauro Carvalho Chehab kbuild has support for this, but requires the blob file to be 288cd238effSMauro Carvalho Chehab named <filename>_shipped. When the kbuild rules kick in, a copy 289cd238effSMauro Carvalho Chehab of <filename>_shipped is created with _shipped stripped off, 290cd238effSMauro Carvalho Chehab giving us <filename>. This shortened filename can be used in 291cd238effSMauro Carvalho Chehab the assignment to the module. 292cd238effSMauro Carvalho Chehab 293cd238effSMauro Carvalho Chehab Throughout this section, 8123_bin.o_shipped has been used to 294cd238effSMauro Carvalho Chehab build the kernel module 8123.ko; it has been included as 295cd238effSMauro Carvalho Chehab 8123_bin.o:: 296cd238effSMauro Carvalho Chehab 297cd238effSMauro Carvalho Chehab 8123-y := 8123_if.o 8123_pci.o 8123_bin.o 298cd238effSMauro Carvalho Chehab 299cd238effSMauro Carvalho Chehab Although there is no distinction between the ordinary source 300cd238effSMauro Carvalho Chehab files and the binary file, kbuild will pick up different rules 301cd238effSMauro Carvalho Chehab when creating the object file for the module. 302cd238effSMauro Carvalho Chehab 303cd238effSMauro Carvalho Chehab3.4 Building Multiple Modules 304cd238effSMauro Carvalho Chehab============================= 305cd238effSMauro Carvalho Chehab 306cd238effSMauro Carvalho Chehab kbuild supports building multiple modules with a single build 307cd238effSMauro Carvalho Chehab file. For example, if you wanted to build two modules, foo.ko 308cd238effSMauro Carvalho Chehab and bar.ko, the kbuild lines would be:: 309cd238effSMauro Carvalho Chehab 310cd238effSMauro Carvalho Chehab obj-m := foo.o bar.o 311cd238effSMauro Carvalho Chehab foo-y := <foo_srcs> 312cd238effSMauro Carvalho Chehab bar-y := <bar_srcs> 313cd238effSMauro Carvalho Chehab 314cd238effSMauro Carvalho Chehab It is that simple! 315cd238effSMauro Carvalho Chehab 316cd238effSMauro Carvalho Chehab 317cd238effSMauro Carvalho Chehab4. Include Files 318cd238effSMauro Carvalho Chehab================ 319cd238effSMauro Carvalho Chehab 320cd238effSMauro Carvalho ChehabWithin the kernel, header files are kept in standard locations 321cd238effSMauro Carvalho Chehabaccording to the following rule: 322cd238effSMauro Carvalho Chehab 323cd238effSMauro Carvalho Chehab * If the header file only describes the internal interface of a 324cd238effSMauro Carvalho Chehab module, then the file is placed in the same directory as the 325cd238effSMauro Carvalho Chehab source files. 326cd238effSMauro Carvalho Chehab * If the header file describes an interface used by other parts 327cd238effSMauro Carvalho Chehab of the kernel that are located in different directories, then 328cd238effSMauro Carvalho Chehab the file is placed in include/linux/. 329cd238effSMauro Carvalho Chehab 330cd238effSMauro Carvalho Chehab NOTE: 331cd238effSMauro Carvalho Chehab There are two notable exceptions to this rule: larger 332cd238effSMauro Carvalho Chehab subsystems have their own directory under include/, such as 333cd238effSMauro Carvalho Chehab include/scsi; and architecture specific headers are located 334cd238effSMauro Carvalho Chehab under arch/$(ARCH)/include/. 335cd238effSMauro Carvalho Chehab 336cd238effSMauro Carvalho Chehab4.1 Kernel Includes 337cd238effSMauro Carvalho Chehab------------------- 338cd238effSMauro Carvalho Chehab 339cd238effSMauro Carvalho Chehab To include a header file located under include/linux/, simply 340cd238effSMauro Carvalho Chehab use:: 341cd238effSMauro Carvalho Chehab 342cd238effSMauro Carvalho Chehab #include <linux/module.h> 343cd238effSMauro Carvalho Chehab 344cd238effSMauro Carvalho Chehab kbuild will add options to "gcc" so the relevant directories 345cd238effSMauro Carvalho Chehab are searched. 346cd238effSMauro Carvalho Chehab 347cd238effSMauro Carvalho Chehab4.2 Single Subdirectory 348cd238effSMauro Carvalho Chehab----------------------- 349cd238effSMauro Carvalho Chehab 350cd238effSMauro Carvalho Chehab External modules tend to place header files in a separate 351cd238effSMauro Carvalho Chehab include/ directory where their source is located, although this 352cd238effSMauro Carvalho Chehab is not the usual kernel style. To inform kbuild of the 353cd238effSMauro Carvalho Chehab directory, use either ccflags-y or CFLAGS_<filename>.o. 354cd238effSMauro Carvalho Chehab 355cd238effSMauro Carvalho Chehab Using the example from section 3, if we moved 8123_if.h to a 356cd238effSMauro Carvalho Chehab subdirectory named include, the resulting kbuild file would 357cd238effSMauro Carvalho Chehab look like:: 358cd238effSMauro Carvalho Chehab 359cd238effSMauro Carvalho Chehab --> filename: Kbuild 360cd238effSMauro Carvalho Chehab obj-m := 8123.o 361cd238effSMauro Carvalho Chehab 362cd238effSMauro Carvalho Chehab ccflags-y := -Iinclude 363cd238effSMauro Carvalho Chehab 8123-y := 8123_if.o 8123_pci.o 8123_bin.o 364cd238effSMauro Carvalho Chehab 365cd238effSMauro Carvalho Chehab Note that in the assignment there is no space between -I and 366cd238effSMauro Carvalho Chehab the path. This is a limitation of kbuild: there must be no 367cd238effSMauro Carvalho Chehab space present. 368cd238effSMauro Carvalho Chehab 369cd238effSMauro Carvalho Chehab4.3 Several Subdirectories 370cd238effSMauro Carvalho Chehab-------------------------- 371cd238effSMauro Carvalho Chehab 372cd238effSMauro Carvalho Chehab kbuild can handle files that are spread over several directories. 373cd238effSMauro Carvalho Chehab Consider the following example:: 374cd238effSMauro Carvalho Chehab 375cd238effSMauro Carvalho Chehab . 376cd238effSMauro Carvalho Chehab |__ src 377cd238effSMauro Carvalho Chehab | |__ complex_main.c 378cd238effSMauro Carvalho Chehab | |__ hal 379cd238effSMauro Carvalho Chehab | |__ hardwareif.c 380cd238effSMauro Carvalho Chehab | |__ include 381cd238effSMauro Carvalho Chehab | |__ hardwareif.h 382cd238effSMauro Carvalho Chehab |__ include 383cd238effSMauro Carvalho Chehab |__ complex.h 384cd238effSMauro Carvalho Chehab 385cd238effSMauro Carvalho Chehab To build the module complex.ko, we then need the following 386cd238effSMauro Carvalho Chehab kbuild file:: 387cd238effSMauro Carvalho Chehab 388cd238effSMauro Carvalho Chehab --> filename: Kbuild 389cd238effSMauro Carvalho Chehab obj-m := complex.o 390cd238effSMauro Carvalho Chehab complex-y := src/complex_main.o 391cd238effSMauro Carvalho Chehab complex-y += src/hal/hardwareif.o 392cd238effSMauro Carvalho Chehab 393cd238effSMauro Carvalho Chehab ccflags-y := -I$(src)/include 394cd238effSMauro Carvalho Chehab ccflags-y += -I$(src)/src/hal/include 395cd238effSMauro Carvalho Chehab 396cd238effSMauro Carvalho Chehab As you can see, kbuild knows how to handle object files located 397cd238effSMauro Carvalho Chehab in other directories. The trick is to specify the directory 398cd238effSMauro Carvalho Chehab relative to the kbuild file's location. That being said, this 399cd238effSMauro Carvalho Chehab is NOT recommended practice. 400cd238effSMauro Carvalho Chehab 401cd238effSMauro Carvalho Chehab For the header files, kbuild must be explicitly told where to 402cd238effSMauro Carvalho Chehab look. When kbuild executes, the current directory is always the 403cd238effSMauro Carvalho Chehab root of the kernel tree (the argument to "-C") and therefore an 404cd238effSMauro Carvalho Chehab absolute path is needed. $(src) provides the absolute path by 405cd238effSMauro Carvalho Chehab pointing to the directory where the currently executing kbuild 406cd238effSMauro Carvalho Chehab file is located. 407cd238effSMauro Carvalho Chehab 408cd238effSMauro Carvalho Chehab 409cd238effSMauro Carvalho Chehab5. Module Installation 410cd238effSMauro Carvalho Chehab====================== 411cd238effSMauro Carvalho Chehab 412cd238effSMauro Carvalho ChehabModules which are included in the kernel are installed in the 413cd238effSMauro Carvalho Chehabdirectory: 414cd238effSMauro Carvalho Chehab 415cd238effSMauro Carvalho Chehab /lib/modules/$(KERNELRELEASE)/kernel/ 416cd238effSMauro Carvalho Chehab 417cd238effSMauro Carvalho ChehabAnd external modules are installed in: 418cd238effSMauro Carvalho Chehab 419cd238effSMauro Carvalho Chehab /lib/modules/$(KERNELRELEASE)/extra/ 420cd238effSMauro Carvalho Chehab 421cd238effSMauro Carvalho Chehab5.1 INSTALL_MOD_PATH 422cd238effSMauro Carvalho Chehab-------------------- 423cd238effSMauro Carvalho Chehab 424cd238effSMauro Carvalho Chehab Above are the default directories but as always some level of 425cd238effSMauro Carvalho Chehab customization is possible. A prefix can be added to the 426cd238effSMauro Carvalho Chehab installation path using the variable INSTALL_MOD_PATH:: 427cd238effSMauro Carvalho Chehab 428cd238effSMauro Carvalho Chehab $ make INSTALL_MOD_PATH=/frodo modules_install 429cd238effSMauro Carvalho Chehab => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel/ 430cd238effSMauro Carvalho Chehab 431cd238effSMauro Carvalho Chehab INSTALL_MOD_PATH may be set as an ordinary shell variable or, 432cd238effSMauro Carvalho Chehab as shown above, can be specified on the command line when 433cd238effSMauro Carvalho Chehab calling "make." This has effect when installing both in-tree 434cd238effSMauro Carvalho Chehab and out-of-tree modules. 435cd238effSMauro Carvalho Chehab 436cd238effSMauro Carvalho Chehab5.2 INSTALL_MOD_DIR 437cd238effSMauro Carvalho Chehab------------------- 438cd238effSMauro Carvalho Chehab 439cd238effSMauro Carvalho Chehab External modules are by default installed to a directory under 440cd238effSMauro Carvalho Chehab /lib/modules/$(KERNELRELEASE)/extra/, but you may wish to 441cd238effSMauro Carvalho Chehab locate modules for a specific functionality in a separate 442cd238effSMauro Carvalho Chehab directory. For this purpose, use INSTALL_MOD_DIR to specify an 443cd238effSMauro Carvalho Chehab alternative name to "extra.":: 444cd238effSMauro Carvalho Chehab 445cd238effSMauro Carvalho Chehab $ make INSTALL_MOD_DIR=gandalf -C $KDIR \ 446cd238effSMauro Carvalho Chehab M=$PWD modules_install 447cd238effSMauro Carvalho Chehab => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf/ 448cd238effSMauro Carvalho Chehab 449cd238effSMauro Carvalho Chehab 450cd238effSMauro Carvalho Chehab6. Module Versioning 451cd238effSMauro Carvalho Chehab==================== 452cd238effSMauro Carvalho Chehab 453cd238effSMauro Carvalho ChehabModule versioning is enabled by the CONFIG_MODVERSIONS tag, and is used 454cd238effSMauro Carvalho Chehabas a simple ABI consistency check. A CRC value of the full prototype 455cd238effSMauro Carvalho Chehabfor an exported symbol is created. When a module is loaded/used, the 456cd238effSMauro Carvalho ChehabCRC values contained in the kernel are compared with similar values in 457cd238effSMauro Carvalho Chehabthe module; if they are not equal, the kernel refuses to load the 458cd238effSMauro Carvalho Chehabmodule. 459cd238effSMauro Carvalho Chehab 460cd238effSMauro Carvalho ChehabModule.symvers contains a list of all exported symbols from a kernel 461cd238effSMauro Carvalho Chehabbuild. 462cd238effSMauro Carvalho Chehab 463cd238effSMauro Carvalho Chehab6.1 Symbols From the Kernel (vmlinux + modules) 464cd238effSMauro Carvalho Chehab----------------------------------------------- 465cd238effSMauro Carvalho Chehab 466cd238effSMauro Carvalho Chehab During a kernel build, a file named Module.symvers will be 467cd238effSMauro Carvalho Chehab generated. Module.symvers contains all exported symbols from 468cd238effSMauro Carvalho Chehab the kernel and compiled modules. For each symbol, the 469cd238effSMauro Carvalho Chehab corresponding CRC value is also stored. 470cd238effSMauro Carvalho Chehab 471cd238effSMauro Carvalho Chehab The syntax of the Module.symvers file is:: 472cd238effSMauro Carvalho Chehab 473cb9b55d2SMatthias Maennich <CRC> <Symbol> <Namespace> <Module> <Export Type> 474cd238effSMauro Carvalho Chehab 475cb9b55d2SMatthias Maennich 0xe1cc2a05 usb_stor_suspend USB_STORAGE drivers/usb/storage/usb-storage EXPORT_SYMBOL_GPL 476cb9b55d2SMatthias Maennich 477cb9b55d2SMatthias Maennich The fields are separated by tabs and values may be empty (e.g. 478cb9b55d2SMatthias Maennich if no namespace is defined for an exported symbol). 479cd238effSMauro Carvalho Chehab 480cd238effSMauro Carvalho Chehab For a kernel build without CONFIG_MODVERSIONS enabled, the CRC 481cd238effSMauro Carvalho Chehab would read 0x00000000. 482cd238effSMauro Carvalho Chehab 483cd238effSMauro Carvalho Chehab Module.symvers serves two purposes: 484cd238effSMauro Carvalho Chehab 485cd238effSMauro Carvalho Chehab 1) It lists all exported symbols from vmlinux and all modules. 486cd238effSMauro Carvalho Chehab 2) It lists the CRC if CONFIG_MODVERSIONS is enabled. 487cd238effSMauro Carvalho Chehab 488cd238effSMauro Carvalho Chehab6.2 Symbols and External Modules 489cd238effSMauro Carvalho Chehab-------------------------------- 490cd238effSMauro Carvalho Chehab 491cd238effSMauro Carvalho Chehab When building an external module, the build system needs access 492cd238effSMauro Carvalho Chehab to the symbols from the kernel to check if all external symbols 493cd238effSMauro Carvalho Chehab are defined. This is done in the MODPOST step. modpost obtains 494cd238effSMauro Carvalho Chehab the symbols by reading Module.symvers from the kernel source 495cd238effSMauro Carvalho Chehab tree. If a Module.symvers file is present in the directory 496cd238effSMauro Carvalho Chehab where the external module is being built, this file will be 497cd238effSMauro Carvalho Chehab read too. During the MODPOST step, a new Module.symvers file 498cd238effSMauro Carvalho Chehab will be written containing all exported symbols that were not 499cd238effSMauro Carvalho Chehab defined in the kernel. 500cd238effSMauro Carvalho Chehab 501807f2105SAlex Gaynor6.3 Symbols From Another External Module 502807f2105SAlex Gaynor---------------------------------------- 503cd238effSMauro Carvalho Chehab 504cd238effSMauro Carvalho Chehab Sometimes, an external module uses exported symbols from 505*43496709SMasahiro Yamada another external module. Kbuild needs to have full knowledge of 506cd238effSMauro Carvalho Chehab all symbols to avoid spitting out warnings about undefined 507cd238effSMauro Carvalho Chehab symbols. Three solutions exist for this situation. 508cd238effSMauro Carvalho Chehab 509cd238effSMauro Carvalho Chehab NOTE: The method with a top-level kbuild file is recommended 510cd238effSMauro Carvalho Chehab but may be impractical in certain situations. 511cd238effSMauro Carvalho Chehab 512cd238effSMauro Carvalho Chehab Use a top-level kbuild file 513cd238effSMauro Carvalho Chehab If you have two modules, foo.ko and bar.ko, where 514cd238effSMauro Carvalho Chehab foo.ko needs symbols from bar.ko, you can use a 515cd238effSMauro Carvalho Chehab common top-level kbuild file so both modules are 516cd238effSMauro Carvalho Chehab compiled in the same build. Consider the following 517cd238effSMauro Carvalho Chehab directory layout:: 518cd238effSMauro Carvalho Chehab 519cd238effSMauro Carvalho Chehab ./foo/ <= contains foo.ko 520cd238effSMauro Carvalho Chehab ./bar/ <= contains bar.ko 521cd238effSMauro Carvalho Chehab 522cd238effSMauro Carvalho Chehab The top-level kbuild file would then look like:: 523cd238effSMauro Carvalho Chehab 524cd238effSMauro Carvalho Chehab #./Kbuild (or ./Makefile): 525*43496709SMasahiro Yamada obj-m := foo/ bar/ 526cd238effSMauro Carvalho Chehab 527cd238effSMauro Carvalho Chehab And executing:: 528cd238effSMauro Carvalho Chehab 529cd238effSMauro Carvalho Chehab $ make -C $KDIR M=$PWD 530cd238effSMauro Carvalho Chehab 531cd238effSMauro Carvalho Chehab will then do the expected and compile both modules with 532cd238effSMauro Carvalho Chehab full knowledge of symbols from either module. 533cd238effSMauro Carvalho Chehab 534cd238effSMauro Carvalho Chehab Use an extra Module.symvers file 535cd238effSMauro Carvalho Chehab When an external module is built, a Module.symvers file 536cd238effSMauro Carvalho Chehab is generated containing all exported symbols which are 537cd238effSMauro Carvalho Chehab not defined in the kernel. To get access to symbols 538cd238effSMauro Carvalho Chehab from bar.ko, copy the Module.symvers file from the 539cd238effSMauro Carvalho Chehab compilation of bar.ko to the directory where foo.ko is 540cd238effSMauro Carvalho Chehab built. During the module build, kbuild will read the 541cd238effSMauro Carvalho Chehab Module.symvers file in the directory of the external 542cd238effSMauro Carvalho Chehab module, and when the build is finished, a new 543cd238effSMauro Carvalho Chehab Module.symvers file is created containing the sum of 544cd238effSMauro Carvalho Chehab all symbols defined and not part of the kernel. 545cd238effSMauro Carvalho Chehab 546cd238effSMauro Carvalho Chehab Use "make" variable KBUILD_EXTRA_SYMBOLS 547cd238effSMauro Carvalho Chehab If it is impractical to copy Module.symvers from 548cd238effSMauro Carvalho Chehab another module, you can assign a space separated list 549cd238effSMauro Carvalho Chehab of files to KBUILD_EXTRA_SYMBOLS in your build file. 550cd238effSMauro Carvalho Chehab These files will be loaded by modpost during the 551cd238effSMauro Carvalho Chehab initialization of its symbol tables. 552cd238effSMauro Carvalho Chehab 553cd238effSMauro Carvalho Chehab 554cd238effSMauro Carvalho Chehab7. Tips & Tricks 555cd238effSMauro Carvalho Chehab================ 556cd238effSMauro Carvalho Chehab 557cd238effSMauro Carvalho Chehab7.1 Testing for CONFIG_FOO_BAR 558cd238effSMauro Carvalho Chehab------------------------------ 559cd238effSMauro Carvalho Chehab 560cd238effSMauro Carvalho Chehab Modules often need to check for certain `CONFIG_` options to 561cd238effSMauro Carvalho Chehab decide if a specific feature is included in the module. In 562cd238effSMauro Carvalho Chehab kbuild this is done by referencing the `CONFIG_` variable 563cd238effSMauro Carvalho Chehab directly:: 564cd238effSMauro Carvalho Chehab 565cd238effSMauro Carvalho Chehab #fs/ext2/Makefile 566cd238effSMauro Carvalho Chehab obj-$(CONFIG_EXT2_FS) += ext2.o 567cd238effSMauro Carvalho Chehab 568cd238effSMauro Carvalho Chehab ext2-y := balloc.o bitmap.o dir.o 569cd238effSMauro Carvalho Chehab ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o 570cd238effSMauro Carvalho Chehab 571cd238effSMauro Carvalho Chehab External modules have traditionally used "grep" to check for 572cd238effSMauro Carvalho Chehab specific `CONFIG_` settings directly in .config. This usage is 573cd238effSMauro Carvalho Chehab broken. As introduced before, external modules should use 574cd238effSMauro Carvalho Chehab kbuild for building and can therefore use the same methods as 575cd238effSMauro Carvalho Chehab in-tree modules when testing for `CONFIG_` definitions. 576