summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-06-03 10:51:09 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-06-18 10:30:44 +0100
commit65cf76cc1c3fde42104249cccb197f079df45aec (patch)
treec6413f502b86e9c7ab1d8bf8d188136bfb6c31bc /documentation
parent3cb04638b46f26da61fc894221462b738ffeca0c (diff)
downloadpoky-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')
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml247
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 @@
625 </para> 625 </para>
626 </section> 626 </section>
627 627
628 <section id='incorporating-out-of-tree-modules'> 628 <section id='working-with-out-of-tree-modules'>
629 <title>Incorporating Out-of-Tree Modules</title> 629 <title>Working with Out-of-Tree Modules</title>
630 630
631 <para> 631 <para>
632 While it is always preferable to work with sources integrated 632 This section describes steps you need to take to be able
633 into the Linux kernel sources, if you need an external kernel 633 to build out-of-tree modules on your target and how to
634 module, the <filename>hello-mod.bb</filename> recipe is available 634 incorporate out-of-tree modules in the build.
635 as a template from which you can create your own out-of-tree
636 Linux kernel module recipe.
637 </para> 635 </para>
638 636
639 <para> 637 <section id='building-out-of-tree-modules-on-the-target'>
640 This template recipe is located in the 638 <title>Building Out-of-Tree Modules on the Target</title>
641 <filename>poky</filename> Git repository of the
642 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
643 at:
644 <literallayout class="monospaced">
645 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
646 </literallayout>
647 </para>
648 639
649 <para> 640 <para>
650 To get started, copy this recipe to your layer and give it a 641 If you want to be able to build out-of-tree modules on
651 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>). 642 the target, there are some steps you need to take
652 In the same directory, create a directory named 643 on the target that has your SDK image running.
653 <filename>files</filename> where you can store any source files, 644 Briefly, the <filename>kernel-dev</filename> package
654 patches, or other files necessary for building 645 is installed by default on all
655 the module that do not come with the sources. 646 <filename>*.sdk</filename> images.
656 Finally, update the recipe as appropriate for the module. 647 However, you need to create some scripts prior to
657 Typically you will need to set the following variables: 648 attempting to build the out-of-tree modules on the target
658 <itemizedlist> 649 that is running that image.
659 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> 650 </para>
660 </para></listitem>
661 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
662 </para></listitem>
663 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
664 </para></listitem>
665 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
666 </para></listitem>
667 </itemizedlist>
668 </para>
669 651
670 <para> 652 <para>
671 Depending on the build system used by the module sources, you might 653 Prior to attempting to build the out-of-tree modules,
672 need to make some adjustments. 654 you need to be on the target as root and change to the
673 For example, a typical module <filename>Makefile</filename> looks 655 <filename>/usr/src/kernel</filename> directory and
674 much like the one provided with the <filename>hello-mod</filename> 656 then <filename>make</filename> the scripts:
675 template: 657 <literallayout class='monospaced'>
676 <literallayout class='monospaced'> 658 # cd /usr/src/kernel
659 # make scripts
660 </literallayout>
661 Because all SDK image recipes include
662 <filename>dev-pkgs</filename> the
663 <filename>kernel-dev</filename> packages will be installed
664 as part of the SDK image.
665 The SDK uses the scripts when building out-of-tree
666 modules.
667 Once you have switched to that directory and created the
668 scripts, you should be able to build your out-of-tree modules
669 on the target.
670 </para>
671 </section>
672
673 <section id='incorporating-out-of-tree-modules'>
674 <title>Incorporating Out-of-Tree Modules</title>
675
676 <para>
677 While it is always preferable to work with sources integrated
678 into the Linux kernel sources, if you need an external kernel
679 module, the <filename>hello-mod.bb</filename> recipe is available
680 as a template from which you can create your own out-of-tree
681 Linux kernel module recipe.
682 </para>
683
684 <para>
685 This template recipe is located in the
686 <filename>poky</filename> Git repository of the
687 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
688 at:
689 <literallayout class="monospaced">
690 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
691 </literallayout>
692 </para>
693
694 <para>
695 To get started, copy this recipe to your layer and give it a
696 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
697 In the same directory, create a directory named
698 <filename>files</filename> where you can store any source files,
699 patches, or other files necessary for building
700 the module that do not come with the sources.
701 Finally, update the recipe as appropriate for the module.
702 Typically you will need to set the following variables:
703 <itemizedlist>
704 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
705 </para></listitem>
706 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
707 </para></listitem>
708 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
709 </para></listitem>
710 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
711 </para></listitem>
712 </itemizedlist>
713 </para>
714
715 <para>
716 Depending on the build system used by the module sources, you might
717 need to make some adjustments.
718 For example, a typical module <filename>Makefile</filename> looks
719 much like the one provided with the <filename>hello-mod</filename>
720 template:
721 <literallayout class='monospaced'>
677 obj-m := hello.o 722 obj-m := hello.o
678 723
679 SRC := $(shell pwd) 724 SRC := $(shell pwd)
@@ -684,68 +729,70 @@
684 modules_install: 729 modules_install:
685 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install 730 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
686 ... 731 ...
687 </literallayout> 732 </literallayout>
688 </para> 733 </para>
689
690 <para>
691 The important point to note here is the
692 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
693 variable.
694 The class <filename>module.bbclass</filename> sets this variable,
695 as well as the
696 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
697 variable to
698 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
699 with the necessary Linux kernel build information to build modules.
700 If your module <filename>Makefile</filename> uses a different
701 variable, you might want to override the
702 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink>
703 step, or create a patch to
704 the <filename>Makefile</filename> to work with the more typical
705 <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
706 variables.
707 </para>
708
709 <para>
710 After you have prepared your recipe, you will likely want to
711 include the module in your images.
712 To do this, see the documentation for the following variables in
713 the Yocto Project Reference Manual and set one of them as
714 appropriate in your machine configuration file:
715 <itemizedlist>
716 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
717 </para></listitem>
718 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
719 </para></listitem>
720 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
721 </para></listitem>
722 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
723 </para></listitem>
724 </itemizedlist>
725 </para>
726 734
727 <para> 735 <para>
728 modules are often not required for boot and can be excluded from 736 The important point to note here is the
729 certain build configurations. 737 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
730 The following allows for the most flexibility: 738 variable.
731 <literallayout class='monospaced'> 739 The class <filename>module.bbclass</filename> sets this variable,
740 as well as the
741 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
742 variable to
743 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
744 with the necessary Linux kernel build information to build modules.
745 If your module <filename>Makefile</filename> uses a different
746 variable, you might want to override the
747 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink>
748 step, or create a patch to
749 the <filename>Makefile</filename> to work with the more typical
750 <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
751 variables.
752 </para>
753
754 <para>
755 After you have prepared your recipe, you will likely want to
756 include the module in your images.
757 To do this, see the documentation for the following variables in
758 the Yocto Project Reference Manual and set one of them as
759 appropriate in your machine configuration file:
760 <itemizedlist>
761 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
762 </para></listitem>
763 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
764 </para></listitem>
765 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
766 </para></listitem>
767 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
768 </para></listitem>
769 </itemizedlist>
770 </para>
771
772 <para>
773 modules are often not required for boot and can be excluded from
774 certain build configurations.
775 The following allows for the most flexibility:
776 <literallayout class='monospaced'>
732 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" 777 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
733 </literallayout> 778 </literallayout>
734 Where the value is derived by appending the module filename without 779 Where the value is derived by appending the module filename without
735 the <filename>.ko</filename> extension to the string 780 the <filename>.ko</filename> extension to the string
736 "kernel-module-". 781 "kernel-module-".
737 </para> 782 </para>
738 783
739 <para> 784 <para>
740 Because the variable is 785 Because the variable is
741 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> 786 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
742 and not a 787 and not a
743 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> 788 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
744 variable, the build will not fail if this module is not available 789 variable, the build will not fail if this module is not available
745 to include in the image. 790 to include in the image.
746 </para> 791 </para>
792 </section>
747 </section> 793 </section>
748 794
795
749 <section id='inspecting-changes-and-commits'> 796 <section id='inspecting-changes-and-commits'>
750 <title>Inspecting Changes and Commits</title> 797 <title>Inspecting Changes and Commits</title>
751 798