summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml115
1 files changed, 114 insertions, 1 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 506a45ee11..d76580dd02 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -783,7 +783,119 @@ details.
783 <title>Incorporating Out-of-Tree Modules</title> 783 <title>Incorporating Out-of-Tree Modules</title>
784 784
785 <para> 785 <para>
786 While it is always preferable to work with sources integrated into the Linux 786 While it is always preferable to work with sources integrated
787 into the Linux kernel sources, if you need an external kernel
788 module, the <filename>hello-mod.bb</filename> recipe is available
789 as a template from which you can create your own out-of-tree
790 Linux kernel module recipe.
791 </para>
792
793 <para>
794 This template recipe is located in the
795 <filename>poky</filename> Git repository of the
796 Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
797 at:
798 <literallayout class="monospaced">
799 poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
800 </literallayout>
801 </para>
802
803 <para>
804 To get started, copy this recipe to your layer and give it a
805 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
806 In the same directory, create a directory named
807 <filename>files</filename> where you can store any source files,
808 patches, or other files necessary for building
809 the module that do not come with the sources.
810 Finally, update the recipe as appropriate for the module.
811 Typically you will need to set the following variables:
812 <itemizedlist>
813 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
814 </para></listitem>
815 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
816 </para></listitem>
817 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
818 </para></listitem>
819 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
820 </para></listitem>
821 </itemizedlist>
822 </para>
823
824 <para>
825 Depending on the build system used by the module sources, you might
826 need to make some adjustments.
827 For example, a typical module <filename>Makefile</filename> looks
828 much like the one provided with the <filename>hello-mod</filename>
829 template:
830 <literallayout class='monospaced'>
831 obj-m := hello.o
832
833 SRC := $(shell pwd)
834
835 all:
836 $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
837
838 modules_install:
839 $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
840 ...
841 </literallayout>
842 </para>
843
844 <para>
845 The important point to note here is the
846 <filename>KERNEL_SRC</filename> variable.
847 The module <filename>bbclass</filename> sets this variable,
848 as well as the <filename>KERNEL_PATH</filename> variable
849 to <filename>${STAGING_KERNEL_DIR}</filename> with the
850 necessary Linux kernel build information to build modules.
851 If your module <filename>Makefile</filename> uses a different
852 variable, you might want to override the
853 <filename>do_compile()</filename> step, or create a patch to
854 the <filename>Makefile</filename> to work with the more typical
855 <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
856 variables.
857 </para>
858
859 <para>
860 After you have prepared your recipe, you will likely want to
861 include the module in your images.
862 To do this, see the documentation for the following variables in
863 the Yocto Project Reference Manual and set one of them as
864 appropriate in your machine <filename>config</filename> file:
865 <itemizedlist>
866 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
867 </para></listitem>
868 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
869 </para></listitem>
870 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
871 </para></listitem>
872 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
873 </para></listitem>
874 </itemizedlist>
875 </para>
876
877 <para>
878 modules are often not required for boot and can be excluded from
879 certain build configurations.
880 The following allows for the most flexibility:
881 <literallayout class='monospaced'>
882 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
883 </literallayout>
884 Where the value is derived by appending the module filename without
885 the <filename>.ko</filename> extension to the string
886 "kernel-module-".
887 </para>
888
889 <para>
890 Because the variable is <filename>RRECOMMENDS</filename> and not
891 a <filename>RDEPENDS</filename> variable, the build will not fail
892 if this module is not available to include in the image.
893 </para>
894
895 <para>
896 Original Text:
897 <literallayout class='monospaced'>
898While it is always preferable to work with sources integrated into the Linux
787kernel sources, if you have need of an external kernel module, the hello-mod 899kernel sources, if you have need of an external kernel module, the hello-mod
788recipe is available as a template to create your own out-of-tree Linux kernel 900recipe is available as a template to create your own out-of-tree Linux kernel
789module recipe. It is available in the poky repository at: 901module recipe. It is available in the poky repository at:
@@ -844,6 +956,7 @@ extension to the string "kernel-module-".
844 956
845As it is an RRECOMMENDS (and not an RDEPENDS) variable, the build will not fail 957As it is an RRECOMMENDS (and not an RDEPENDS) variable, the build will not fail
846if this module is not available to include in the image. 958if this module is not available to include in the image.
959 </literallayout>
847 </para> 960 </para>
848 </section> 961 </section>
849</chapter> 962</chapter>