Documentation/kbuild/modules.txt

   1
   2 In this document you will find information about:
   3 - how to build external modules
   4 - how to make your module use kbuild infrastructure
   5 - how kbuild will install a kernel
   6 - how to install modules in a non-standard location
   7
   8 === Table of Contents
   9
  10         === 1 Introduction
  11         === 2 How to build external modules
  12            --- 2.1 Building external modules
  13            --- 2.2 Available targets
  14            --- 2.3 Available options
  15            --- 2.4 Preparing the kernel tree for module build
  16         === 3. Example commands
  17         === 4. Creating a kbuild file for an external module
  18         === 5. Include files
  19            --- 5.1 How to include files from the kernel include dir
  20            --- 5.2 External modules using an include/ dir
  21         === 6. Module installation
  22            --- 6.1 INSTALL_MOD_PATH
  23            --- 6.2 INSTALL_MOD_DIR
  24         === 7. Module versioning
  25         === 8. Tips & Tricks
  26            --- 8.1 Testing for CONFIG_FOO_BAR
  27
  28
  29
  30 === 1. Introduction
  31
  32 kbuild includes functionality for building modules both
  33 within the kernel source tree and outside the kernel source tree.
  34 The latter is usually referred to as external modules and is used
  35 both during development and for modules that are not planned to be
  36 included in the kernel tree.
  37
  38 What is covered within this file is mainly information to authors
  39 of modules. The author of an external modules should supply
  40 a makefile that hides most of the complexity so one only has to type
  41 'make' to buld the module. A complete example will be present in
  42 chapter ¤. Creating a kbuild file for an external module".
  43
  44
  45 === 2. How to build external modules
  46
  47 kbuild offers functionality to build external modules, with the
  48 prerequisite that there is a pre-built kernel available with full source.
  49 A subset of the targets available when building the kernel is available
  50 when building an external module.
  51
  52 --- 2.1 Building external modules
  53
  54         Use the following command to build an external module:
  55
  56                 make -C <path-to-kernel> M=`pwd`
  57
  58         For the running kernel use:
  59                 make -C /lib/modules/`uname -r`/build M=`pwd`
  60
  61         For the above command to succeed the kernel must have been built with
  62         modules enabled.
  63
  64         To install the modules that were just built:
  65
  66                 make -C <path-to-kernel> M=`pwd` modules_install
  67
  68         More complex examples later, the above should get you going.
  69
  70 --- 2.2 Available targets
  71
  72         $KDIR refers to path to kernel source top-level directory
  73
  74         make -C $KDIR M=`pwd`
  75                 Will build the module(s) located in current directory.
  76                 All output files will be located in the same directory
  77                 as the module source.
  78                 No attempts are made to update the kernel source, and it is
  79                 a precondition that a successful make has been executed
  80                 for the kernel.
  81
  82         make -C $KDIR M=`pwd` modules
  83                 The modules target is implied when no target is given.
  84                 Same functionality as if no target was specified.
  85                 See description above.
  86
  87         make -C $KDIR M=$PWD modules_install
  88                 Install the external module(s).
  89                 Installation default is in /lib/modules/<kernel-version>/extra,
  90                 but may be prefixed with INSTALL_MOD_PATH - see separate chater.
  91
  92         make -C $KDIR M=$PWD clean
  93                 Remove all generated files for the module - the kernel
  94                 source directory is not moddified.
  95
  96         make -C $KDIR M=`pwd` help
  97                 help will list the available target when building external
  98                 modules.
  99
 100 --- 2.3 Available options:
 101
 102         $KDIR refer to path to kernel src
 103
 104         make -C $KDIR
 105                 Used to specify where to find the kernel source.
 106                 '$KDIR' represent the directory where the kernel source is.
 107                 Make will actually change directory to the specified directory
 108                 when executed but change back when finished.
 109
 110         make -C $KDIR M=`pwd`
 111                 M= is used to tell kbuild that an external module is
 112                 being built.
 113                 The option given to M= is the directory where the external
 114                 module (kbuild file) is located.
 115                 When an external module is being built only a subset of the
 116                 usual targets are available.
 117
 118         make -C $KDIR SUBDIRS=`pwd`
 119                 Same as M=. The SUBDIRS= syntax is kept for backwards
 120                 compatibility.
 121
 122 --- 2.4 Preparing the kernel tree for module build
 123
 124         To make sure the kernel contains the information required to
 125         build external modules the target 'modules_prepare' must be used.
 126         'module_prepare' solely exists as a simple way to prepare
 127         a kernel for building external modules.
 128         Note: modules_prepare will not build Module.symvers even if
 129               CONFIG_MODULEVERSIONING is set.
 130               Therefore a full kernel build needs to be executed to make
 131               module versioning work.
 132
 133
 134 === 3. Example commands
 135
 136 This example shows the actual commands to be executed when building
 137 an external module for the currently running kernel.
 138 In the example below the distribution is supposed to use the
 139 facility to locate output files for a kernel compile in a different
 140 directory than the kernel source - but the examples will also work
 141 when the source and the output files are mixed in the same directory.
 142
 143 # Kernel source
 144 /lib/modules/<kernel-version>/source -> /usr/src/linux-<version>
 145
 146 # Output from kernel compile
 147 /lib/modules/<kernel-version>/build -> /usr/src/linux-<version>-up
 148
 149 Change to the directory where the kbuild file is located and execute
 150 the following commands to build the module:
 151
 152         cd /home/user/src/module
 153         make -C /usr/src/`uname -r`/source            \
 154                 O=/lib/modules/`uname-r`/build        \
 155                 M=`pwd`
 156
 157 Then to install the module use the following command:
 158
 159         make -C /usr/src/`uname -r`/source            \
 160                 O=/lib/modules/`uname-r`/build        \
 161                 M=`pwd`                               \
 162                 modules_install
 163
 164 If one looks closely you will see that this is the same commands as
 165 listed before - with the directories spelled out.
 166
 167 The above are rather long commands, and the following chapter
 168 lists a few tricks to make it all easier.
 169
 170
 171 === 4. Creating a kbuild file for an external module
 172
 173 kbuild is the build system for the kernel, and external modules
 174 must use kbuild to stay compatible with changes in the build system
 175 and to pick up the right flags to gcc etc.
 176
 177 The kbuild file used as input shall follow the syntax described
 178 in Documentation/kbuild/makefiles.txt. This chapter will introduce a few
 179 more tricks to be used when dealing with external modules.
 180
 181 In the following a Makefile will be created for a module with the
 182 following files:
 183         8123_if.c
 184         8123_if.h
 185         8123_pci.c
 186         8123_bin.o_shipped      <= Binary blob
 187
 188 --- 4.1 Shared Makefile for module and kernel
 189
 190         An external module always includes a wrapper Makefile supporting
 191         building the module using 'make' with no arguments.
 192         The Makefile provided will most likely include additional
 193         functionality such as test targets etc. and this part shall
 194         be filtered away from kbuild since it may impact kbuild if
 195         name clashes occurs.
 196
 197         Example 1:
 198                 --> filename: Makefile
 199                 ifneq ($(KERNELRELEASE),)
 200                 # kbuild part of makefile
 201                 obj-m  := 8123.o
 202                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 203
 204                 else
 205                 # Normal Makefile
 206
 207                 KERNELDIR := /lib/modules/`uname -r`/build
 208                 all::
 209                         $(MAKE) -C $KERNELDIR M=`pwd` $@
 210
 211                 # Module specific targets
 212                 genbin:
 213                         echo "X" > 8123_bini.o_shipped
 214
 215                 endif
 216
 217         In example 1 the check for KERNELRELEASE is used to separate
 218         the two parts of the Makefile. kbuild will only see the two
 219         assignments whereas make will see everything except the two
 220         kbuild assignments.
 221
 222         In recent versions of the kernel, kbuild will look for a file named
 223         Kbuild and as second option look for a file named Makefile.
 224         Utilising the Kbuild file makes us split up the Makefile in example 1
 225         into two files as shown in example 2:
 226
 227         Example 2:
 228                 --> filename: Kbuild
 229                 obj-m  := 8123.o
 230                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 231
 232                 --> filename: Makefile
 233                 KERNELDIR := /lib/modules/`uname -r`/build
 234                 all::
 235                         $(MAKE) -C $KERNELDIR M=`pwd` $@
 236
 237                 # Module specific targets
 238                 genbin:
 239                         echo "X" > 8123_bin_shipped
 240
 241
 242         In example 2 we are down to two fairly simple files and for simple
 243         files as used in this example the split is questionable. But some
 244         external modules use Makefiles of several hundred lines and here it
 245         really pays off to separate the kbuild part from the rest.
 246         Example 3 shows a backward compatible version.
 247
 248         Example 3:
 249                 --> filename: Kbuild
 250                 obj-m  := 8123.o
 251                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 252
 253                 --> filename: Makefile
 254                 ifneq ($(KERNELRELEASE),)
 255                 include Kbuild
 256                 else
 257                 # Normal Makefile
 258
 259                 KERNELDIR := /lib/modules/`uname -r`/build
 260                 all::
 261                         $(MAKE) -C $KERNELDIR M=`pwd` $@
 262
 263                 # Module specific targets
 264                 genbin:
 265                         echo "X" > 8123_bin_shipped
 266
 267                 endif
 268
 269                 The trick here is to include the Kbuild file from Makefile so
 270                 if an older version of kbuild picks up the Makefile the Kbuild
 271                 file will be included.
 272
 273 --- 4.2 Binary blobs included in a module
 274
 275         Some external modules needs to include a .o as a blob. kbuild
 276         has support for this, but requires the blob file to be named
 277         <filename>_shipped. In our example the blob is named
 278         8123_bin.o_shipped and when the kbuild rules kick in the file
 279         8123_bin.o is created as a simple copy off the 8213_bin.o_shipped file
 280         with the _shipped part stripped of the filename.
 281         This allows the 8123_bin.o filename to be used in the assignment to
 282         the module.
 283
 284         Example 4:
 285                 obj-m  := 8123.o
 286                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 287
 288         In example 4 there is no distinction between the ordinary .c/.h files
 289         and the binary file. But kbuild will pick up different rules to create
 290         the .o file.
 291
 292
 293 === 5. Include files
 294
 295 Include files are a necessity when a .c file uses something from another .c
 296 files (not strictly in the sense of .c but if good programming practice is
 297 used). Any module that consist of more than one .c file will have a .h file
 298 for one of the .c files.
 299 - If the .h file only describes a module internal interface then the .h file
 300   shall be placed in the same directory as the .c files.
 301 - If the .h files describe an interface used by other parts of the kernel
 302   located in different directories, the .h files shall be located in
 303   include/linux/ or other include/ directories as appropriate.
 304
 305 One exception for this rule is larger subsystems that have their own directory
 306 under include/ such as include/scsi. Another exception is arch-specific
 307 .h files which are located under include/asm-$(ARCH)/*.
 308
 309 External modules have a tendency to locate include files in a separate include/
 310 directory and therefore needs to deal with this in their kbuild file.
 311
 312 --- 5.1 How to include files from the kernel include dir
 313
 314         When a module needs to include a file from include/linux/ then one
 315         just uses:
 316
 317                 #include <linux/modules.h>
 318
 319         kbuild will make sure to add options to gcc so the relevant
 320         directories are searched.
 321         Likewise for .h files placed in the same directory as the .c file.
 322
 323                 #include "8123_if.h"
 324
 325         will do the job.
 326
 327 --- 5.2 External modules using an include/ dir
 328
 329         External modules often locate their .h files in a separate include/
 330         directory although this is not usual kernel style. When an external
 331         module uses an include/ dir then kbuild needs to be told so.
 332         The trick here is to use either EXTRA_CFLAGS (take effect for all .c
 333         files) or CFLAGS_$F.o (take effect only for a single file).
 334
 335         In our example if we move 8123_if.h to a subdirectory named include/
 336         the resulting Kbuild file would look like:
 337
 338                 --> filename: Kbuild
 339                 obj-m  := 8123.o
 340
 341                 EXTRA_CFLAGS := -Iinclude
 342                 8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 343
 344         Note that in the assingment there is no space between -I and the path.
 345         This is a kbuild limitation and no space must be present.
 346
 347
 348 === 6. Module installation
 349
 350 Modules which are included in the kernel is installed in the directory:
 351
 352         /lib/modules/$(KERNELRELEASE)/kernel
 353
 354 External modules are installed in the directory:
 355
 356         /lib/modules/$(KERNELRELEASE)/extra
 357
 358 --- 6.1 INSTALL_MOD_PATH
 359
 360         Above are the default directories, but as always some level of
 361         customization is possible. One can prefix the path using the variable
 362         INSTALL_MOD_PATH:
 363
 364                 $ make INSTALL_MOD_PATH=/frodo modules_install
 365                 => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel
 366
 367         INSTALL_MOD_PATH may be set as an ordinary shell variable or as in the
 368         example above be specified on the commandline when calling make.
 369         INSTALL_MOD_PATH has effect both when installing modules included in
 370         the kernel as well as when installing external modules.
 371
 372 --- 6.2 INSTALL_MOD_DIR
 373
 374         When installing external modules they are default installed in a
 375         directory under /lib/modules/$(KERNELRELEASE)/extra, but one may wish
 376         to locate modules for a specific functionality in a separate
 377         directory. For this purpose one can use INSTALL_MOD_DIR to specify an
 378         alternative name than 'extra'.
 379
 380                 $ make INSTALL_MOD_DIR=gandalf -C KERNELDIR \
 381                         M=`pwd` modules_install
 382                 => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf
 383
 384
 385 === 7. Module versioning
 386
 387 Module versioning are enabled by the CONFIG_MODVERSIONS tag.
 388
 389 Module versioning is used as a simple ABI consistency check. The Module
 390 versioning creates a CRC value of the full prototype for an exported symbol and
 391 when a module is loaded/used then the CRC values contained in the kernel are
 392 compared with similar values in the module. If they are not equal then the
 393 kernel refuses to load the module.
 394
 395 During a kernel build a file named Module.symvers will be generated. This
 396 file includes the symbol version of all symbols within the kernel. If the
 397 Module.symvers file is saved from the last full kernel compile one does not
 398 have to do a full kernel compile to build a module version's compatible module.
 399
 400 === 8. Tips & Tricks
 401
 402 --- 8.1 Testing for CONFIG_FOO_BAR
 403
 404         Modules often needs to check for certain CONFIG_ options to decide if
 405         a specific feature shall be included in the module. When kbuild is used
 406         this is done by referencing the CONFIG_ variable directly.
 407
 408                 #fs/ext2/Makefile
 409                 obj-$(CONFIG_EXT2_FS) += ext2.o
 410
 411                 ext2-y := balloc.o bitmap.o dir.o
 412                 ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
 413
 414         External modules have traditionally used grep to check for specific
 415         CONFIG_ settings directly in .config. This usage is broken.
 416         As introduced before external modules shall use kbuild when building
 417         and therefore can use the same methods as in-kernel modules when testing
 418         for CONFIG_ definitions.
 419