adding-packages-kernel-module.txt 5.0 KB

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