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