1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc: 3 4=== Infrastructure for packages building kernel modules 5 6Buildroot offers a helper infrastructure to make it easy to write packages that 7build and install Linux kernel modules. Some packages only contain a kernel 8module, other packages contain programs and libraries in addition to kernel 9modules. Buildroot's helper infrastructure supports either case. 10 11[[kernel-module-tutorial]] 12==== +kernel-module+ tutorial 13 14Let's start with an example on how to prepare a simple package that only 15builds a kernel module, and no other component: 16 17---- 1801: ################################################################################ 1902: # 2003: # foo 2104: # 2205: ################################################################################ 2306: 2407: FOO_VERSION = 1.2.3 2508: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz 2609: FOO_SITE = http://www.foosoftware.org/download 2710: FOO_LICENSE = GPL-2.0 2811: FOO_LICENSE_FILES = COPYING 2912: 3013: $(eval $(kernel-module)) 3114: $(eval $(generic-package)) 32---- 33 34Lines 7-11 define the usual meta-data to specify the version, archive name, 35remote URI where to find the package source, licensing information. 36 37On line 13, we invoke the +kernel-module+ helper infrastructure, that 38generates all the appropriate Makefile rules and variables to build 39that kernel module. 40 41Finally, on line 14, we invoke the 42xref:generic-package-tutorial[+generic-package+ infrastructure]. 43 44The dependency on +linux+ is automatically added, so it is not needed to 45specify it in +FOO_DEPENDENCIES+. 46 47What you may have noticed is that, unlike other package infrastructures, 48we explicitly invoke a second infrastructure. This allows a package to 49build a kernel module, but also, if needed, use any one of other package 50infrastructures to build normal userland components (libraries, 51executables...). Using the +kernel-module+ infrastructure on its own is 52not sufficient; another package infrastructure *must* be used. 53 54Let's look at a more complex example: 55 56---- 5701: ################################################################################ 5802: # 5903: # foo 6004: # 6105: ################################################################################ 6206: 6307: FOO_VERSION = 1.2.3 6408: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz 6509: FOO_SITE = http://www.foosoftware.org/download 6610: FOO_LICENSE = GPL-2.0 6711: FOO_LICENSE_FILES = COPYING 6812: 6913: FOO_MODULE_SUBDIRS = driver/base 7014: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED) 7115: 7216: ifeq ($(BR2_PACKAGE_LIBBAR),y) 7317: FOO_DEPENDENCIES = libbar 7418: FOO_CONF_OPTS = --enable-bar 7519: FOO_MODULE_SUBDIRS += driver/bar 7620: else 7721: FOO_CONF_OPTS = --disable-bar 7822: endif 7923: 8024: $(eval $(kernel-module)) 8126: $(eval $(autotools-package)) 82---- 83 84Here, we see that we have an autotools-based package, that also builds 85the kernel module located in sub-directory +driver/base+ and, if libbar 86is enabled, the kernel module located in sub-directory +driver/bar+, and 87defines the variable +KVERSION+ to be passed to the Linux buildsystem 88when building the module(s). 89 90 91[[kernel-module-reference]] 92==== +kernel-module+ reference 93 94The main macro for the kernel module infrastructure is +kernel-module+. 95Unlike other package infrastructures, it is not stand-alone, and requires 96any of the other +*-package+ macros be called after it. 97 98The +kernel-module+ macro defines post-build and post-target-install 99hooks to build the kernel modules. If the package's +.mk+ needs access 100to the built kernel modules, it should do so in a post-build hook, 101*registered after* the call to +kernel-module+. Similarly, if the 102package's +.mk+ needs access to the kernel module after it has been 103installed, it should do so in a post-install hook, *registered after* 104the call to +kernel-module+. Here's an example: 105 106---- 107$(eval $(kernel-module)) 108 109define FOO_DO_STUFF_WITH_KERNEL_MODULE 110 # Do something with it... 111endef 112FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE 113 114$(eval $(generic-package)) 115---- 116 117Finally, unlike the other package infrastructures, there is no 118+host-kernel-module+ variant to build a host kernel module. 119 120The following additional variables can optionally be defined to further 121configure the build of the kernel module: 122 123* +FOO_MODULE_SUBDIRS+ may be set to one or more sub-directories (relative 124 to the package source top-directory) where the kernel module sources are. 125 If empty or not set, the sources for the kernel module(s) are considered 126 to be located at the top of the package source tree. 127 128* +FOO_MODULE_MAKE_OPTS+ may be set to contain extra variable definitions 129 to pass to the Linux buildsystem. 130 131[[kernel-variables]] 132You may also reference (but you may *not* set!) those variables: 133 134 * +LINUX_DIR+ contains the path to where the Linux kernel has been 135 extracted and built. 136 137 * +LINUX_VERSION+ contains the version string as configured by the user. 138 139 * +LINUX_VERSION_PROBED+ contains the real version string of the kernel, 140 retrieved with running `make -C $(LINUX_DIR) kernelrelease` 141 142 * +KERNEL_ARCH+ contains the name of the current architecture, like `arm`, 143 `mips`... 144