| Message ID | 5c16fb51d4dd1fdf8d5660ccc2121895f28ca17c.1433628825.git.yann.morin.1998@free.fr |
|---|---|
| State | Changes Requested |
| Headers | show |
On 06/07/15 00:20, Yann E. MORIN wrote: > Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> > Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com> > Cc: Samuel Martin <s.martin49@gmail.com> > --- > docs/manual/adding-packages-kernel-module.txt | 120 ++++++++++++++++++++++++++ > docs/manual/adding-packages.txt | 2 + > 2 files changed, 122 insertions(+) > create mode 100644 docs/manual/adding-packages-kernel-module.txt > > diff --git a/docs/manual/adding-packages-kernel-module.txt b/docs/manual/adding-packages-kernel-module.txt > new file mode 100644 > index 0000000..1fe359a > --- /dev/null > +++ b/docs/manual/adding-packages-kernel-module.txt > @@ -0,0 +1,120 @@ > +// -*- mode:doc; -*- > +// vim: set syntax=asciidoc: > + > +=== Infrastructure for packages building kernel modules > + > +Some packages, in addition to the usual user-space components it builds, > +may also need to build and install kernel modules. How about: Buildroot offers a helper infrastructure to make it easy to write packages that build and install Linux kernel modules. Some packages only contain a kernel module, other packages contain programs and libraries in addition to kernel modules. Buildroot's helper infrastructure supports either case. > + > +Buildroot offers a helper infrastructure to ease writing such packages. > + > +[[kernel-module-tutorial]] > +==== +kernel-module+ tutorial > + > +Let's start with an example on how to prepare a simple package that only > +builds a kernel module, and no other component: > + > +---- > +01: ################################################################################ > +02: # > +03: # foo > +04: # > +05: ################################################################################ > +06: > +07: FOO_VERSION = 1.2.3 > +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz > +09: FOO_SITE = http://www.foosoftware.org/download > +10: > +11: $(eval $(kernel-module)) > +12: $(eval $(generic-package)) > +---- > + > +Lines 7-9 define the usual meta-data to specify the version, archive name > +and remote URI where to find the package source. > + > +On line 11, we invoke the +kernel-module+ helper infrastructure, that > +generates all the appropriate Makefile rules and variables to build > +that kernel module. > + > +Finally, on line 12, we invoke the > +xref:generic-package-tutorial[+generic-package+ infrastructure]. > + > +The dependency on +linux+ is automatically added, so it is not needed to > +specify it in +FOO_DEPENDENCIES+. > + > +What you may have noticed is that, unlike other package infrastructures, > +we explicitly invoke a second infrastructure. This allows a package to > +build a kernel module, but also, if needed, use any one of other package > +inftrastructures to build normal userland components (libraries, infrastructures > +executables...). Using the +kernel-module+ infrastructure on its own is > +not sufficient; another package infrastructure *must* be used. It's a pity that it's not possible to add a check for that... > + > +Let's look at a more complex example: > + > +---- > +01: ################################################################################ > +02: # > +03: # foo > +04: # > +05: ################################################################################ > +06: > +07: FOO_VERSION = 1.2.3 > +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz > +09: FOO_SITE = http://www.foosoftware.org/download > +10: FOO_DEPENDENCIES = libbar > +11: > +12: FOO_CONF_OPTS = --enable-bar > +13: > +14: FOO_MODULE_SUBDIRS = driver-base driver-bar > +15: FOO_MODULE_MAKE_OPTS = FOO_STUFF=some-value I think this is a little too abstract to understand. Perhaps use a more concrete example, e.g. the one from ktap: FOO_MODULE_MAKE_OPTS = KVERSION=$(LINUX_VERSION_PROBED) (which is also an opportunity to talk about the otherwise undocumented but in this context important LINUX_VERSION_PROBED variable). > +16: > +17: $(eval $(kernel-module)) > +18: $(eval $(autotools-package)) > +---- > + > +Here, we see that we have an autotools-based package, that also builds > +kernel modules located into sub-directories +driver-base+ and +driver-bar+, > +and defines the variable +FOO_STUFF+ to be passed to the Linux buildsystem > +when building the module(s) (see below for the reference for those two > +variables). > + > + > +[[kernel-module-reference]] > +==== +kernel-module+ reference > + > +The main macro for the kernel module infrastructure is +kernel-module+. > +Unlike other package infrastructures, it is not stand-alone, and requires > +any of the other +*-package+ macro be called after it. ^^^^^ macros > + > +The +kernel-module+ macro defines post-build and post-target-install > +hooks to build the kernel modules. If the package's +.mk+ needs access > +to the built kernel modules, it should do so in a post-build hook, > +registered after the call to +kernel-module+. Similarly, if the package's > ++.mk+ needs access to the kernel module after it has been installed, it > +should do so in a post-install hook, registered after the call to > ++kernel-module+. Here's an example: > + > +---- > +$(eval $(kernel-module)) > + > +define FOO_DO_STUFF_WITH_KERNEL_MODULE > + # Do something with it... > +endef > +FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE > + > +$(eval $(generic-package)) > +---- > + > +Finally, unlike the other package infrastructures, there is no > ++host-kernel-module+ variant to build a host kernel module. > + > +Additional variable are available to further configure the build of > +the kernel module: The following additional variables can optionally be defined to further configure the build of the kernel module: Regards, Arnout > + > +* +FOO_MODULE_SUBDIRS+ may be set to one or more sub-directories (relative > + to the package source top-directory) where the kernel module sources are. > + If empty or not set, the sources for the kernel module(s) are considered > + to be located at the top of the package source tree. > + > +* +FOO_MODULE_MAKE_OPTS+ may be set to contain extra variable definitions > + to pass to the Linux buildsystem. > diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt > index b8674f8..721fe39 100644 > --- a/docs/manual/adding-packages.txt > +++ b/docs/manual/adding-packages.txt > @@ -29,6 +29,8 @@ include::adding-packages-kconfig.txt[] > > include::adding-packages-rebar.txt[] > > +include::adding-packages-kernel-module.txt[] > + > include::adding-packages-asciidoc.txt[] > > include::adding-packages-hooks.txt[] >
On 06/08/15 23:46, Arnout Vandecappelle wrote: > On 06/07/15 00:20, Yann E. MORIN wrote: >> Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> >> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com> >> Cc: Samuel Martin <s.martin49@gmail.com> >> --- >> docs/manual/adding-packages-kernel-module.txt | 120 ++++++++++++++++++++++++++ >> docs/manual/adding-packages.txt | 2 + >> 2 files changed, 122 insertions(+) >> create mode 100644 docs/manual/adding-packages-kernel-module.txt >> >> diff --git a/docs/manual/adding-packages-kernel-module.txt b/docs/manual/adding-packages-kernel-module.txt >> new file mode 100644 >> index 0000000..1fe359a >> --- /dev/null >> +++ b/docs/manual/adding-packages-kernel-module.txt >> @@ -0,0 +1,120 @@ >> +// -*- mode:doc; -*- >> +// vim: set syntax=asciidoc: >> + >> +=== Infrastructure for packages building kernel modules >> + >> +Some packages, in addition to the usual user-space components it builds, >> +may also need to build and install kernel modules. > > How about: > > Buildroot offers a helper infrastructure to make it easy to write packages that > build and install Linux kernel modules. Some packages only contain a kernel > module, other packages contain programs and libraries in addition to kernel > modules. Buildroot's helper infrastructure supports either case. > >> + >> +Buildroot offers a helper infrastructure to ease writing such packages. >> + >> +[[kernel-module-tutorial]] >> +==== +kernel-module+ tutorial >> + >> +Let's start with an example on how to prepare a simple package that only >> +builds a kernel module, and no other component: >> + >> +---- >> +01: ################################################################################ >> +02: # >> +03: # foo >> +04: # >> +05: ################################################################################ >> +06: >> +07: FOO_VERSION = 1.2.3 >> +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz >> +09: FOO_SITE = http://www.foosoftware.org/download One more thing: we want to encourage adding license info, so perhaps include in the example: FOO_LICENSE = GPLv2 FOO_LICENSE_FILES = COPYING Regards, Arnout >> +10: >> +11: $(eval $(kernel-module)) >> +12: $(eval $(generic-package)) >> +---- >> + [snip]
Arnout, All, On 2015-06-09 00:02 +0200, Arnout Vandecappelle spake thusly: > On 06/08/15 23:46, Arnout Vandecappelle wrote: > > On 06/07/15 00:20, Yann E. MORIN wrote: [--SNIP--] > >> +01: ################################################################################ > >> +02: # > >> +03: # foo > >> +04: # > >> +05: ################################################################################ > >> +06: > >> +07: FOO_VERSION = 1.2.3 > >> +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz > >> +09: FOO_SITE = http://www.foosoftware.org/download > > One more thing: we want to encourage adding license info, so perhaps include in > the example: > > FOO_LICENSE = GPLv2 > FOO_LICENSE_FILES = COPYING That and your previous comments acted upon. Thanks! :-) Regards, Yann E. MORIN.
diff --git a/docs/manual/adding-packages-kernel-module.txt b/docs/manual/adding-packages-kernel-module.txt new file mode 100644 index 0000000..1fe359a --- /dev/null +++ b/docs/manual/adding-packages-kernel-module.txt @@ -0,0 +1,120 @@ +// -*- mode:doc; -*- +// vim: set syntax=asciidoc: + +=== Infrastructure for packages building kernel modules + +Some packages, in addition to the usual user-space components it builds, +may also need to build and install kernel modules. + +Buildroot offers a helper infrastructure to ease writing such packages. + +[[kernel-module-tutorial]] +==== +kernel-module+ tutorial + +Let's start with an example on how to prepare a simple package that only +builds a kernel module, and no other component: + +---- +01: ################################################################################ +02: # +03: # foo +04: # +05: ################################################################################ +06: +07: FOO_VERSION = 1.2.3 +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz +09: FOO_SITE = http://www.foosoftware.org/download +10: +11: $(eval $(kernel-module)) +12: $(eval $(generic-package)) +---- + +Lines 7-9 define the usual meta-data to specify the version, archive name +and remote URI where to find the package source. + +On line 11, we invoke the +kernel-module+ helper infrastructure, that +generates all the appropriate Makefile rules and variables to build +that kernel module. + +Finally, on line 12, we invoke the +xref:generic-package-tutorial[+generic-package+ infrastructure]. + +The dependency on +linux+ is automatically added, so it is not needed to +specify it in +FOO_DEPENDENCIES+. + +What you may have noticed is that, unlike other package infrastructures, +we explicitly invoke a second infrastructure. This allows a package to +build a kernel module, but also, if needed, use any one of other package +inftrastructures to build normal userland components (libraries, +executables...). Using the +kernel-module+ infrastructure on its own is +not sufficient; another package infrastructure *must* be used. + +Let's look at a more complex example: + +---- +01: ################################################################################ +02: # +03: # foo +04: # +05: ################################################################################ +06: +07: FOO_VERSION = 1.2.3 +08: FOO_SOURCE = foo-$(FOO_VERSION).tar.xz +09: FOO_SITE = http://www.foosoftware.org/download +10: FOO_DEPENDENCIES = libbar +11: +12: FOO_CONF_OPTS = --enable-bar +13: +14: FOO_MODULE_SUBDIRS = driver-base driver-bar +15: FOO_MODULE_MAKE_OPTS = FOO_STUFF=some-value +16: +17: $(eval $(kernel-module)) +18: $(eval $(autotools-package)) +---- + +Here, we see that we have an autotools-based package, that also builds +kernel modules located into sub-directories +driver-base+ and +driver-bar+, +and defines the variable +FOO_STUFF+ to be passed to the Linux buildsystem +when building the module(s) (see below for the reference for those two +variables). + + +[[kernel-module-reference]] +==== +kernel-module+ reference + +The main macro for the kernel module infrastructure is +kernel-module+. +Unlike other package infrastructures, it is not stand-alone, and requires +any of the other +*-package+ macro be called after it. + +The +kernel-module+ macro defines post-build and post-target-install +hooks to build the kernel modules. If the package's +.mk+ needs access +to the built kernel modules, it should do so in a post-build hook, +registered after the call to +kernel-module+. Similarly, if the package's ++.mk+ needs access to the kernel module after it has been installed, it +should do so in a post-install hook, registered after the call to ++kernel-module+. Here's an example: + +---- +$(eval $(kernel-module)) + +define FOO_DO_STUFF_WITH_KERNEL_MODULE + # Do something with it... +endef +FOO_POST_BUILD_HOOKS += FOO_DO_STUFF_WITH_KERNEL_MODULE + +$(eval $(generic-package)) +---- + +Finally, unlike the other package infrastructures, there is no ++host-kernel-module+ variant to build a host kernel module. + +Additional variable are available to further configure the build of +the kernel module: + +* +FOO_MODULE_SUBDIRS+ may be set to one or more sub-directories (relative + to the package source top-directory) where the kernel module sources are. + If empty or not set, the sources for the kernel module(s) are considered + to be located at the top of the package source tree. + +* +FOO_MODULE_MAKE_OPTS+ may be set to contain extra variable definitions + to pass to the Linux buildsystem. diff --git a/docs/manual/adding-packages.txt b/docs/manual/adding-packages.txt index b8674f8..721fe39 100644 --- a/docs/manual/adding-packages.txt +++ b/docs/manual/adding-packages.txt @@ -29,6 +29,8 @@ include::adding-packages-kconfig.txt[] include::adding-packages-rebar.txt[] +include::adding-packages-kernel-module.txt[] + include::adding-packages-asciidoc.txt[] include::adding-packages-hooks.txt[]
Signed-off-by: "Yann E. MORIN" <yann.morin.1998@free.fr> Cc: Thomas Petazzoni <thomas.petazzoni@free-electrons.com> Cc: Samuel Martin <s.martin49@gmail.com> --- docs/manual/adding-packages-kernel-module.txt | 120 ++++++++++++++++++++++++++ docs/manual/adding-packages.txt | 2 + 2 files changed, 122 insertions(+) create mode 100644 docs/manual/adding-packages-kernel-module.txt