diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-06-03 10:51:09 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-06-18 10:30:44 +0100 |
commit | 65cf76cc1c3fde42104249cccb197f079df45aec (patch) | |
tree | c6413f502b86e9c7ab1d8bf8d188136bfb6c31bc /documentation/kernel-dev | |
parent | 3cb04638b46f26da61fc894221462b738ffeca0c (diff) | |
download | openembedded-core-contrib-65cf76cc1c3fde42104249cccb197f079df45aec.tar.gz |
kernel-dev: Added new "Building Out-of-Tree Modules on the Target" section.
Fixes [YOCTO #3729]
I have made an attempt at understanding this and creating
a section that describes the steps the user needs to take in
order to build out-of-tree modules on the target device when
running an SDK image. I created a new section called
"Building Out-of-Tree Modules on the Target". Basically,
the user needs to be on the target and change to a directory
and then create some scripts before attempting to build these
types of modules on the target.
(From yocto-docs rev: e0754ae6dbc5dc07fb6707fe4b71ecd95c8180dc)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/kernel-dev')
-rw-r--r-- | documentation/kernel-dev/kernel-dev-common.xml | 247 |
1 files changed, 147 insertions, 100 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml index 3adc648098..b3f4c438d7 100644 --- a/documentation/kernel-dev/kernel-dev-common.xml +++ b/documentation/kernel-dev/kernel-dev-common.xml @@ -625,55 +625,100 @@ </para> </section> - <section id='incorporating-out-of-tree-modules'> - <title>Incorporating Out-of-Tree Modules</title> + <section id='working-with-out-of-tree-modules'> + <title>Working with Out-of-Tree Modules</title> <para> - While it is always preferable to work with sources integrated - into the Linux kernel sources, if you need an external kernel - module, the <filename>hello-mod.bb</filename> recipe is available - as a template from which you can create your own out-of-tree - Linux kernel module recipe. + This section describes steps you need to take to be able + to build out-of-tree modules on your target and how to + incorporate out-of-tree modules in the build. </para> - <para> - This template recipe is located in the - <filename>poky</filename> Git repository of the - Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> - at: - <literallayout class="monospaced"> - poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb - </literallayout> - </para> + <section id='building-out-of-tree-modules-on-the-target'> + <title>Building Out-of-Tree Modules on the Target</title> - <para> - To get started, copy this recipe to your layer and give it a - meaningful name (e.g. <filename>mymodule_1.0.bb</filename>). - In the same directory, create a directory named - <filename>files</filename> where you can store any source files, - patches, or other files necessary for building - the module that do not come with the sources. - Finally, update the recipe as appropriate for the module. - Typically you will need to set the following variables: - <itemizedlist> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> - </para></listitem> - </itemizedlist> - </para> + <para> + If you want to be able to build out-of-tree modules on + the target, there are some steps you need to take + on the target that has your SDK image running. + Briefly, the <filename>kernel-dev</filename> package + is installed by default on all + <filename>*.sdk</filename> images. + However, you need to create some scripts prior to + attempting to build the out-of-tree modules on the target + that is running that image. + </para> - <para> - Depending on the build system used by the module sources, you might - need to make some adjustments. - For example, a typical module <filename>Makefile</filename> looks - much like the one provided with the <filename>hello-mod</filename> - template: - <literallayout class='monospaced'> + <para> + Prior to attempting to build the out-of-tree modules, + you need to be on the target as root and change to the + <filename>/usr/src/kernel</filename> directory and + then <filename>make</filename> the scripts: + <literallayout class='monospaced'> + # cd /usr/src/kernel + # make scripts + </literallayout> + Because all SDK image recipes include + <filename>dev-pkgs</filename> the + <filename>kernel-dev</filename> packages will be installed + as part of the SDK image. + The SDK uses the scripts when building out-of-tree + modules. + Once you have switched to that directory and created the + scripts, you should be able to build your out-of-tree modules + on the target. + </para> + </section> + + <section id='incorporating-out-of-tree-modules'> + <title>Incorporating Out-of-Tree Modules</title> + + <para> + While it is always preferable to work with sources integrated + into the Linux kernel sources, if you need an external kernel + module, the <filename>hello-mod.bb</filename> recipe is available + as a template from which you can create your own out-of-tree + Linux kernel module recipe. + </para> + + <para> + This template recipe is located in the + <filename>poky</filename> Git repository of the + Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink> + at: + <literallayout class="monospaced"> + poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb + </literallayout> + </para> + + <para> + To get started, copy this recipe to your layer and give it a + meaningful name (e.g. <filename>mymodule_1.0.bb</filename>). + In the same directory, create a directory named + <filename>files</filename> where you can store any source files, + patches, or other files necessary for building + the module that do not come with the sources. + Finally, update the recipe as appropriate for the module. + Typically you will need to set the following variables: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> + </para></listitem> + </itemizedlist> + </para> + + <para> + Depending on the build system used by the module sources, you might + need to make some adjustments. + For example, a typical module <filename>Makefile</filename> looks + much like the one provided with the <filename>hello-mod</filename> + template: + <literallayout class='monospaced'> obj-m := hello.o SRC := $(shell pwd) @@ -684,68 +729,70 @@ modules_install: $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install ... - </literallayout> - </para> - - <para> - The important point to note here is the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink> - variable. - The class <filename>module.bbclass</filename> sets this variable, - as well as the - <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink> - variable to - <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename> - with the necessary Linux kernel build information to build modules. - If your module <filename>Makefile</filename> uses a different - variable, you might want to override the - <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink> - step, or create a patch to - the <filename>Makefile</filename> to work with the more typical - <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename> - variables. - </para> - - <para> - After you have prepared your recipe, you will likely want to - include the module in your images. - To do this, see the documentation for the following variables in - the Yocto Project Reference Manual and set one of them as - appropriate in your machine configuration file: - <itemizedlist> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink> - </para></listitem> - <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink> - </para></listitem> - </itemizedlist> - </para> + </literallayout> + </para> - <para> - modules are often not required for boot and can be excluded from - certain build configurations. - The following allows for the most flexibility: - <literallayout class='monospaced'> + <para> + The important point to note here is the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink> + variable. + The class <filename>module.bbclass</filename> sets this variable, + as well as the + <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink> + variable to + <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename> + with the necessary Linux kernel build information to build modules. + If your module <filename>Makefile</filename> uses a different + variable, you might want to override the + <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink> + step, or create a patch to + the <filename>Makefile</filename> to work with the more typical + <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename> + variables. + </para> + + <para> + After you have prepared your recipe, you will likely want to + include the module in your images. + To do this, see the documentation for the following variables in + the Yocto Project Reference Manual and set one of them as + appropriate in your machine configuration file: + <itemizedlist> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink> + </para></listitem> + <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink> + </para></listitem> + </itemizedlist> + </para> + + <para> + modules are often not required for boot and can be excluded from + certain build configurations. + The following allows for the most flexibility: + <literallayout class='monospaced'> MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" - </literallayout> - Where the value is derived by appending the module filename without - the <filename>.ko</filename> extension to the string - "kernel-module-". - </para> + </literallayout> + Where the value is derived by appending the module filename without + the <filename>.ko</filename> extension to the string + "kernel-module-". + </para> - <para> - Because the variable is - <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> - and not a - <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> - variable, the build will not fail if this module is not available - to include in the image. - </para> + <para> + Because the variable is + <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> + and not a + <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> + variable, the build will not fail if this module is not available + to include in the image. + </para> + </section> </section> + <section id='inspecting-changes-and-commits'> <title>Inspecting Changes and Commits</title> |