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