2In this document you will find information about:
   3- how to build external modules
   4- how to make your module use the kbuild infrastructure
   5- how kbuild will install a kernel
   6- how to install modules in a non-standard location
   8=== Table of Contents
  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           --- 2.5 Building separate files for a module
  17        === 3. Example commands
  18        === 4. Creating a kbuild file for an external module
  19        === 5. Include files
  20           --- 5.1 How to include files from the kernel include dir
  21           --- 5.2 External modules using an include/ dir
  22           --- 5.3 External modules using several directories
  23        === 6. Module installation
  24           --- 6.1 INSTALL_MOD_PATH
  25           --- 6.2 INSTALL_MOD_DIR
  26        === 7. Module versioning & Module.symvers
  27           --- 7.1 Symbols from the kernel (vmlinux + modules)
  28           --- 7.2 Symbols and external modules
  29           --- 7.3 Symbols from another external module
  30        === 8. Tips & Tricks
  31           --- 8.1 Testing for CONFIG_FOO_BAR
  35=== 1. Introduction
  37kbuild includes functionality for building modules both
  38within the kernel source tree and outside the kernel source tree.
  39The latter is usually referred to as external or "out-of-tree"
  40modules and is used both during development and for modules that
  41are not planned to be included in the kernel tree.
  43What is covered within this file is mainly information to authors
  44of modules. The author of an external module should supply
  45a makefile that hides most of the complexity, so one only has to type
  46'make' to build the module. A complete example will be presented in
  47chapter 4, "Creating a kbuild file for an external module".
  50=== 2. How to build external modules
  52kbuild offers functionality to build external modules, with the
  53prerequisite that there is a pre-built kernel available with full source.
  54A subset of the targets available when building the kernel is available
  55when building an external module.
  57--- 2.1 Building external modules
  59        Use the following command to build an external module:
  61                make -C <path-to-kernel> M=`pwd`
  63        For the running kernel use:
  65                make -C /lib/modules/`uname -r`/build M=`pwd`
  67        For the above command to succeed, the kernel must have been
  68        built with modules enabled.
  70        To install the modules that were just built:
  72                make -C <path-to-kernel> M=`pwd` modules_install
  74        More complex examples will be shown later, the above should
  75        be enough to get you started.
  77--- 2.2 Available targets
  79        $KDIR refers to the path to the kernel source top-level directory
  81        make -C $KDIR M=`pwd`
  82                Will build the module(s) located in current directory.
  83                All output files will be located in the same directory
  84                as the module source.
  85                No attempts are made to update the kernel source, and it is
  86                a precondition that a successful make has been executed
  87                for the kernel.
  89        make -C $KDIR M=`pwd` modules
  90                The modules target is implied when no target is given.
  91                Same functionality as if no target was specified.
  92                See description above.
  94        make -C $KDIR M=`pwd` modules_install
  95                Install the external module(s).
  96                Installation default is in /lib/modules/<kernel-version>/extra,
  97                but may be prefixed with INSTALL_MOD_PATH - see separate
  98                chapter.
 100        make -C $KDIR M=`pwd` clean
 101                Remove all generated files for the module - the kernel
 102                source directory is not modified.
 104        make -C $KDIR M=`pwd` help
 105                help will list the available target when building external
 106                modules.
 108--- 2.3 Available options:
 110        $KDIR refers to the path to the kernel source top-level directory
 112        make -C $KDIR
 113                Used to specify where to find the kernel source.
 114                '$KDIR' represent the directory where the kernel source is.
 115                Make will actually change directory to the specified directory
 116                when executed but change back when finished.
 118        make -C $KDIR M=`pwd`
 119                M= is used to tell kbuild that an external module is
 120                being built.
 121                The option given to M= is the directory where the external
 122                module (kbuild file) is located.
 123                When an external module is being built only a subset of the
 124                usual targets are available.
 126        make -C $KDIR SUBDIRS=`pwd`
 127                Same as M=. The SUBDIRS= syntax is kept for backwards
 128                compatibility.
 130--- 2.4 Preparing the kernel tree for module build
 132        To make sure the kernel contains the information required to
 133        build external modules the target 'modules_prepare' must be used.
 134        'modules_prepare' exists solely as a simple way to prepare
 135        a kernel source tree for building external modules.
 136        Note: modules_prepare will not build Module.symvers even if
 137        CONFIG_MODVERSIONS is set. Therefore a full kernel build
 138        needs to be executed to make module versioning work.
 140--- 2.5 Building separate files for a module
 141        It is possible to build single files which are part of a module.
 142        This works equally well for the kernel, a module and even for
 143        external modules.
 144        Examples (module foo.ko, consist of bar.o, baz.o):
 145                make -C $KDIR M=`pwd` bar.lst
 146                make -C $KDIR M=`pwd` bar.o
 147                make -C $KDIR M=`pwd` foo.ko
 148                make -C $KDIR M=`pwd` /
 151=== 3. Example commands
 153This example shows the actual commands to be executed when building
 154an external module for the currently running kernel.
 155In the example below, the distribution is supposed to use the
 156facility to locate output files for a kernel compile in a different
 157directory than the kernel source - but the examples will also work
 158when the source and the output files are mixed in the same directory.
 160# Kernel source
 161/lib/modules/<kernel-version>/source -> /usr/src/linux-<version>
 163# Output from kernel compile
 164/lib/modules/<kernel-version>/build -> /usr/src/linux-<version>-up
 166Change to the directory where the kbuild file is located and execute
 167the following commands to build the module:
 169        cd /home/user/src/module
 170        make -C /usr/src/`uname -r`/source            \
 171                O=/lib/modules/`uname-r`/build        \
 172                M=`pwd`
 174Then, to install the module use the following command:
 176        make -C /usr/src/`uname -r`/source            \
 177                O=/lib/modules/`uname-r`/build        \
 178                M=`pwd`                               \
 179                modules_install
 181If you look closely you will see that this is the same command as
 182listed before - with the directories spelled out.
 184The above are rather long commands, and the following chapter
 185lists a few tricks to make it all easier.
 188=== 4. Creating a kbuild file for an external module
 190kbuild is the build system for the kernel, and external modules
 191must use kbuild to stay compatible with changes in the build system
 192and to pick up the right flags to gcc etc.
 194The kbuild file used as input shall follow the syntax described
 195in Documentation/kbuild/makefiles.txt. This chapter will introduce a few
 196more tricks to be used when dealing with external modules.
 198In the following a Makefile will be created for a module with the
 199following files:
 200        8123_if.c
 201        8123_if.h
 202        8123_pci.c
 203        8123_bin.o_shipped      <= Binary blob
 205--- 4.1 Shared Makefile for module and kernel
 207        An external module always includes a wrapper Makefile supporting
 208        building the module using 'make' with no arguments.
 209        The Makefile provided will most likely include additional
 210        functionality such as test targets etc. and this part shall
 211        be filtered away from kbuild since it may impact kbuild if
 212        name clashes occurs.
 214        Example 1:
 215                --> filename: Makefile
 216                ifneq ($(KERNELRELEASE),)
 217                # kbuild part of makefile
 218                obj-m  := 8123.o
 219                8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 221                else
 222                # Normal Makefile
 224                KERNELDIR := /lib/modules/`uname -r`/build
 225                all::
 226                        $(MAKE) -C $(KERNELDIR) M=`pwd` $@
 228                # Module specific targets
 229                genbin:
 230                        echo "X" > 8123_bin.o_shipped
 232                endif
 234        In example 1, the check for KERNELRELEASE is used to separate
 235        the two parts of the Makefile. kbuild will only see the two
 236        assignments whereas make will see everything except the two
 237        kbuild assignments.
 239        In recent versions of the kernel, kbuild will look for a file named
 240        Kbuild and as second option look for a file named Makefile.
 241        Utilising the Kbuild file makes us split up the Makefile in example 1
 242        into two files as shown in example 2:
 244        Example 2:
 245                --> filename: Kbuild
 246                obj-m  := 8123.o
 247                8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 249                --> filename: Makefile
 250                KERNELDIR := /lib/modules/`uname -r`/build
 251                all::
 252                        $(MAKE) -C $(KERNELDIR) M=`pwd` $@
 254                # Module specific targets
 255                genbin:
 256                        echo "X" > 8123_bin.o_shipped
 259        In example 2, we are down to two fairly simple files and for simple
 260        files as used in this example the split is questionable. But some
 261        external modules use Makefiles of several hundred lines and here it
 262        really pays off to separate the kbuild part from the rest.
 263        Example 3 shows a backward compatible version.
 265        Example 3:
 266                --> filename: Kbuild
 267                obj-m  := 8123.o
 268                8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 270                --> filename: Makefile
 271                ifneq ($(KERNELRELEASE),)
 272                include Kbuild
 273                else
 274                # Normal Makefile
 276                KERNELDIR := /lib/modules/`uname -r`/build
 277                all::
 278                        $(MAKE) -C $KERNELDIR M=`pwd` $@
 280                # Module specific targets
 281                genbin:
 282                        echo "X" > 8123_bin.o_shipped
 284                endif
 286        The trick here is to include the Kbuild file from Makefile, so
 287        if an older version of kbuild picks up the Makefile, the Kbuild
 288        file will be included.
 290--- 4.2 Binary blobs included in a module
 292        Some external modules needs to include a .o as a blob. kbuild
 293        has support for this, but requires the blob file to be named
 294        <filename>_shipped. In our example the blob is named
 295        8123_bin.o_shipped and when the kbuild rules kick in the file
 296        8123_bin.o is created as a simple copy off the 8213_bin.o_shipped file
 297        with the _shipped part stripped of the filename.
 298        This allows the 8123_bin.o filename to be used in the assignment to
 299        the module.
 301        Example 4:
 302                obj-m  := 8123.o
 303                8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 305        In example 4, there is no distinction between the ordinary .c/.h files
 306        and the binary file. But kbuild will pick up different rules to create
 307        the .o file.
 310=== 5. Include files
 312Include files are a necessity when a .c file uses something from other .c
 313files (not strictly in the sense of C, but if good programming practice is
 314used). Any module that consists of more than one .c file will have a .h file
 315for one of the .c files.
 317- If the .h file only describes a module internal interface, then the .h file
 318  shall be placed in the same directory as the .c files.
 319- If the .h files describe an interface used by other parts of the kernel
 320  located in different directories, the .h files shall be located in
 321  include/linux/ or other include/ directories as appropriate.
 323One exception for this rule is larger subsystems that have their own directory
 324under include/ such as include/scsi. Another exception is arch-specific
 325.h files which are located under include/asm-$(ARCH)/*.
 327External modules have a tendency to locate include files in a separate include/
 328directory and therefore need to deal with this in their kbuild file.
 330--- 5.1 How to include files from the kernel include dir
 332        When a module needs to include a file from include/linux/, then one
 333        just uses:
 335                #include <linux/modules.h>
 337        kbuild will make sure to add options to gcc so the relevant
 338        directories are searched.
 339        Likewise for .h files placed in the same directory as the .c file.
 341                #include "8123_if.h"
 343        will do the job.
 345--- 5.2 External modules using an include/ dir
 347        External modules often locate their .h files in a separate include/
 348        directory although this is not usual kernel style. When an external
 349        module uses an include/ dir then kbuild needs to be told so.
 350        The trick here is to use either EXTRA_CFLAGS (take effect for all .c
 351        files) or CFLAGS_$F.o (take effect only for a single file).
 353        In our example, if we move 8123_if.h to a subdirectory named include/
 354        the resulting Kbuild file would look like:
 356                --> filename: Kbuild
 357                obj-m  := 8123.o
 359                EXTRA_CFLAGS := -Iinclude
 360                8123-y := 8123_if.o 8123_pci.o 8123_bin.o
 362        Note that in the assignment there is no space between -I and the path.
 363        This is a kbuild limitation:  there must be no space present.
 365--- 5.3 External modules using several directories
 367        If an external module does not follow the usual kernel style, but
 368        decides to spread files over several directories, then kbuild can
 369        handle this too.
 371        Consider the following example:
 373        |
 374        +- src/complex_main.c
 375        |   +- hal/hardwareif.c
 376        |   +- hal/include/hardwareif.h
 377        +- include/complex.h
 379        To build a single module named complex.ko, we then need the following
 380        kbuild file:
 382        Kbuild:
 383                obj-m := complex.o
 384                complex-y := src/complex_main.o
 385                complex-y += src/hal/hardwareif.o
 387                EXTRA_CFLAGS := -I$(src)/include
 388                EXTRA_CFLAGS += -I$(src)src/hal/include
 391        kbuild knows how to handle .o files located in another directory -
 392        although this is NOT recommended practice. The syntax is to specify
 393        the directory relative to the directory where the Kbuild file is
 394        located.
 396        To find the .h files, we have to explicitly tell kbuild where to look
 397        for the .h files. When kbuild executes, the current directory is always
 398        the root of the kernel tree (argument to -C) and therefore we have to
 399        tell kbuild how to find the .h files using absolute paths.
 400        $(src) will specify the absolute path to the directory where the
 401        Kbuild file are located when being build as an external module.
 402        Therefore -I$(src)/ is used to point out the directory of the Kbuild
 403        file and any additional path are just appended.
 405=== 6. Module installation
 407Modules which are included in the kernel are installed in the directory:
 409        /lib/modules/$(KERNELRELEASE)/kernel
 411External modules are installed in the directory:
 413        /lib/modules/$(KERNELRELEASE)/extra
 415--- 6.1 INSTALL_MOD_PATH
 417        Above are the default directories, but as always, some level of
 418        customization is possible. One can prefix the path using the variable
 419        INSTALL_MOD_PATH:
 421                $ make INSTALL_MOD_PATH=/frodo modules_install
 422                => Install dir: /frodo/lib/modules/$(KERNELRELEASE)/kernel
 424        INSTALL_MOD_PATH may be set as an ordinary shell variable or as in the
 425        example above, can be specified on the command line when calling make.
 426        INSTALL_MOD_PATH has effect both when installing modules included in
 427        the kernel as well as when installing external modules.
 429--- 6.2 INSTALL_MOD_DIR
 431        When installing external modules they are by default installed to a
 432        directory under /lib/modules/$(KERNELRELEASE)/extra, but one may wish
 433        to locate modules for a specific functionality in a separate
 434        directory. For this purpose, one can use INSTALL_MOD_DIR to specify an
 435        alternative name to 'extra'.
 437                $ make INSTALL_MOD_DIR=gandalf -C KERNELDIR \
 438                        M=`pwd` modules_install
 439                => Install dir: /lib/modules/$(KERNELRELEASE)/gandalf
 442=== 7. Module versioning & Module.symvers
 444Module versioning is enabled by the CONFIG_MODVERSIONS tag.
 446Module versioning is used as a simple ABI consistency check. The Module
 447versioning creates a CRC value of the full prototype for an exported symbol and
 448when a module is loaded/used then the CRC values contained in the kernel are
 449compared with similar values in the module. If they are not equal, then the
 450kernel refuses to load the module.
 452Module.symvers contains a list of all exported symbols from a kernel build.
 454--- 7.1 Symbols from the kernel (vmlinux + modules)
 456        During a kernel build, a file named Module.symvers will be generated.
 457        Module.symvers contains all exported symbols from the kernel and
 458        compiled modules. For each symbols, the corresponding CRC value
 459        is stored too.
 461        The syntax of the Module.symvers file is:
 462                <CRC>       <Symbol>           <module>
 463        Sample:
 464                0x2d036834  scsi_remove_host   drivers/scsi/scsi_mod
 466        For a kernel build without CONFIG_MODVERSIONS enabled, the crc
 467        would read: 0x00000000
 469        Module.symvers serves two purposes:
 470        1) It lists all exported symbols both from vmlinux and all modules
 471        2) It lists the CRC if CONFIG_MODVERSIONS is enabled
 473--- 7.2 Symbols and external modules
 475        When building an external module, the build system needs access to
 476        the symbols from the kernel to check if all external symbols are
 477        defined. This is done in the MODPOST step and to obtain all
 478        symbols, modpost reads Module.symvers from the kernel.
 479        If a Module.symvers file is present in the directory where
 480        the external module is being built, this file will be read too.
 481        During the MODPOST step, a new Module.symvers file will be written
 482        containing all exported symbols that were not defined in the kernel.
 484--- 7.3 Symbols from another external module
 486        Sometimes, an external module uses exported symbols from another
 487        external module. Kbuild needs to have full knowledge on all symbols
 488        to avoid spitting out warnings about undefined symbols.
 489        Three solutions exist to let kbuild know all symbols of more than
 490        one external module.
 491        The method with a top-level kbuild file is recommended but may be
 492        impractical in certain situations.
 494        Use a top-level Kbuild file
 495                If you have two modules: 'foo' and 'bar', and 'foo' needs
 496                symbols from 'bar', then one can use a common top-level kbuild
 497                file so both modules are compiled in same build.
 499                Consider following directory layout:
 500                ./foo/ <= contains the foo module
 501                ./bar/ <= contains the bar module
 502                The top-level Kbuild file would then look like:
 504                #./Kbuild: (this file may also be named Makefile)
 505                        obj-y := foo/ bar/
 507                Executing:
 508                        make -C $KDIR M=`pwd`
 510                will then do the expected and compile both modules with full
 511                knowledge on symbols from both modules.
 513        Use an extra Module.symvers file
 514                When an external module is built, a Module.symvers file is
 515                generated containing all exported symbols which are not
 516                defined in the kernel.
 517                To get access to symbols from module 'bar', one can copy the
 518                Module.symvers file from the compilation of the 'bar' module
 519                to the directory where the 'foo' module is built.
 520                During the module build, kbuild will read the Module.symvers
 521                file in the directory of the external module and when the
 522                build is finished, a new Module.symvers file is created
 523                containing the sum of all symbols defined and not part of the
 524                kernel.
 526        Use make variable KBUILD_EXTRA_SYMBOLS in the Makefile
 527                If it is impractical to copy Module.symvers from another
 528                module, you can assign a space separated list of files to
 529                KBUILD_EXTRA_SYMBOLS in your Makfile. These files will be
 530                loaded by modpost during the initialisation of its symbol
 531                tables.
 533=== 8. Tips & Tricks
 535--- 8.1 Testing for CONFIG_FOO_BAR
 537        Modules often need to check for certain CONFIG_ options to decide if
 538        a specific feature shall be included in the module. When kbuild is used
 539        this is done by referencing the CONFIG_ variable directly.
 541                #fs/ext2/Makefile
 542                obj-$(CONFIG_EXT2_FS) += ext2.o
 544                ext2-y := balloc.o bitmap.o dir.o
 545                ext2-$(CONFIG_EXT2_FS_XATTR) += xattr.o
 547        External modules have traditionally used grep to check for specific
 548        CONFIG_ settings directly in .config. This usage is broken.
 549        As introduced before, external modules shall use kbuild when building
 550        and therefore can use the same methods as in-kernel modules when
 551        testing for CONFIG_ definitions.