docs/manual/adding-packages-kernel-module.txt

   1 // -*- mode:doc; -*-
   2 // vim: set syntax=asciidoc:
   3
   4 === Infrastructure for packages building kernel modules
   5
   6 Buildroot offers a helper infrastructure to make it easy to write packages that
   7 build and install Linux kernel modules. Some packages only contain a kernel
   8 module, other packages contain programs and libraries in addition to kernel
   9 modules. Buildroot's helper infrastructure supports either case.
  10
  11 [[kernel-module-tutorial]]
  12 ==== +kernel-module+ tutorial
  13
  14 Let's start with an example on how to prepare a simple package that only
  15 builds a kernel module, and no other component:
  16
  17 ----
  18 01: ################################################################################
  19 02: #
  20 03: # foo
  21 04: #
  22 05: ################################################################################
  23 06:
  24 07: FOO_VERSION = 1.2.3
  25 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
  26 09: FOO_SITE = http://www.foosoftware.org/download
  27 10: FOO_LICENSE = GPLv2
  28 11: FOO_LICENSE_FILES = COPYING
  29 12:
  30 13: $(eval $(kernel-module))
  31 14: $(eval $(generic-package))
  32 ----
  33
  34 Lines 7-11 define the usual meta-data to specify the version, archive name,
  35 remote URI where to find the package source, licensing information.
  36
  37 On line 13, we invoke the +kernel-module+ helper infrastructure, that
  38 generates all the appropriate Makefile rules and variables to build
  39 that kernel module.
  40
  41 Finally, on line 14, we invoke the
  42 xref:generic-package-tutorial[+generic-package+ infrastructure].
  43
  44 The dependency on +linux+ is automatically added, so it is not needed to
  45 specify it in +FOO_DEPENDENCIES+.
  46
  47 What you may have noticed is that, unlike other package infrastructures,
  48 we explicitly invoke a second infrastructure. This allows a package to
  49 build a kernel module, but also, if needed, use any one of other package
  50 infrastructures to build normal userland components (libraries,
  51 executables...). Using the +kernel-module+ infrastructure on its own is
  52 not sufficient; another package infrastructure *must* be used.
  53
  54 Let's look at a more complex example:
  55
  56 ----
  57 01: ################################################################################
  58 02: #
  59 03: # foo
  60 04: #
  61 05: ################################################################################
  62 06:
  63 07: FOO_VERSION = 1.2.3
  64 08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz
  65 09: FOO_SITE = http://www.foosoftware.org/download
  66 10: FOO_LICENSE = GPLv2
  67 11: FOO_LICENSE_FILES = COPYING
  68 12:
  69 13: FOO_MODULE_SUBDIRS = driver/base
  70 14: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED)
  71 15:
  72 16: ifeq ($(BR2_PACKAGE_LIBBAR),y)
  73 17: FOO_DEPENDENCIES = libbar
  74 18: FOO_CONF_OPTS = --enable-bar
  75 19: FOO_MODULE_SUBDIRS += driver/bar
  76 20: else
  77 21: FOO_CONF_OPTS = --disable-bar
  78 22: endif
  79 23:
  80 24: $(eval $(kernel-module))
  81 26: $(eval $(autotools-package))
  82 ----
  83
  84 Here, we see that we have an autotools-based package, that also builds
  85 the kernel module located in sub-directory +driver/base+ and, if libbar
  86 is enabled, the kernel module located in sub-directory +driver/bar+, and
  87 defines the variable +KVERSION+ to be passed to the Linux buildsystem
  88 when building the module(s).
  89
  90
  91 [[kernel-module-reference]]
  92 ==== +kernel-module+ reference
  93
  94 The main macro for the  kernel module infrastructure is +kernel-module+.
  95 Unlike other package infrastructures, it is not stand-alone, and requires
  96 any of the other +*-package+ macros be called after it.
  97
  98 The +kernel-module+ macro defines post-build and post-target-install
  99 hooks to build the kernel modules. If the package's +.mk+ needs access
 100 to the built kernel modules, it should do so in a post-build hook,
 101 *registered after* the call to +kernel-module+. Similarly, if the
 102 package's +.mk+ needs access to the kernel module after it has been
 103 installed, it should do so in a post-install hook, *registered after*
 104 the call to +kernel-module+. Here's an example:
 105
 106 ----
 107 $(eval $(kernel-module))
 108
 109 define FOO_DO_STUFF_WITH_KERNEL_MODULE
 110     # Do something with it...
 111 endef
 112 FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE
 113
 114 $(eval $(generic-package))
 115 ----
 116
 117 Finally, unlike the other package infrastructures, there is no
 118 +host-kernel-module+ variant to build a host kernel module.
 119
 120 The following additional variables can optionally be defined to further
 121 configure 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]]
 132 You 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`...