summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-06-17 10:09:06 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-06-18 10:30:50 +0100
commit45a1c42e7e1fd981027f0dcd9eae7a204a0d9f95 (patch)
tree3a4bd7a7551b7e526322d9cb844dfc17a40c177b /documentation
parent5112dbd23dba18e334f605fd1eec3c50f83e1d23 (diff)
downloadpoky-45a1c42e7e1fd981027f0dcd9eae7a204a0d9f95.tar.gz
kernel-dev: Edits to "Working with Out-of-Tree Modules"
Fixes [YOCTO #3729] I made an editing pass through this section. Found some minor corrections. (From yocto-docs rev: 314ec3a066de7328b6c6893ce33cc0e5faa8700a) 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.xml64
1 files changed, 33 insertions, 31 deletions
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index 3ab21e7077..555c8d8903 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -261,7 +261,7 @@
261 261
262<!-- 262<!--
263 <para> 263 <para>
264 <emphasis>AR - Darrren Hart:</emphasis> This section 264 <emphasis>AR - Darren Hart:</emphasis> This section
265 originated from the old Yocto Project Kernel Architecture 265 originated from the old Yocto Project Kernel Architecture
266 and Use Manual. 266 and Use Manual.
267 It was decided we need to put it in this section here. 267 It was decided we need to put it in this section here.
@@ -635,9 +635,9 @@
635 <title>Working with Out-of-Tree Modules</title> 635 <title>Working with Out-of-Tree Modules</title>
636 636
637 <para> 637 <para>
638 This section describes steps you need to take to be able 638 This section describes steps to build out-of-tree modules on
639 to build out-of-tree modules on your target and how to 639 your target and describes how to incorporate out-of-tree modules
640 incorporate out-of-tree modules in the build. 640 in the build.
641 </para> 641 </para>
642 642
643 <section id='building-out-of-tree-modules-on-the-target'> 643 <section id='building-out-of-tree-modules-on-the-target'>
@@ -646,7 +646,7 @@
646 <para> 646 <para>
647 If you want to be able to build out-of-tree modules on 647 If you want to be able to build out-of-tree modules on
648 the target, there are some steps you need to take 648 the target, there are some steps you need to take
649 on the target that has your SDK image running. 649 on the target that is running your SDK image.
650 Briefly, the <filename>kernel-dev</filename> package 650 Briefly, the <filename>kernel-dev</filename> package
651 is installed by default on all 651 is installed by default on all
652 <filename>*.sdk</filename> images. 652 <filename>*.sdk</filename> images.
@@ -657,15 +657,15 @@
657 657
658 <para> 658 <para>
659 Prior to attempting to build the out-of-tree modules, 659 Prior to attempting to build the out-of-tree modules,
660 you need to be on the target as root and change to the 660 you need to be on the target as root and you need to
661 <filename>/usr/src/kernel</filename> directory and 661 change to the <filename>/usr/src/kernel</filename> directory.
662 then <filename>make</filename> the scripts: 662 Next, <filename>make</filename> the scripts:
663 <literallayout class='monospaced'> 663 <literallayout class='monospaced'>
664 # cd /usr/src/kernel 664 # cd /usr/src/kernel
665 # make scripts 665 # make scripts
666 </literallayout> 666 </literallayout>
667 Because all SDK image recipes include 667 Because all SDK image recipes include
668 <filename>dev-pkgs</filename> the 668 <filename>dev-pkgs</filename>, the
669 <filename>kernel-dev</filename> packages will be installed 669 <filename>kernel-dev</filename> packages will be installed
670 as part of the SDK image. 670 as part of the SDK image.
671 The SDK uses the scripts when building out-of-tree 671 The SDK uses the scripts when building out-of-tree
@@ -682,9 +682,9 @@
682 <para> 682 <para>
683 While it is always preferable to work with sources integrated 683 While it is always preferable to work with sources integrated
684 into the Linux kernel sources, if you need an external kernel 684 into the Linux kernel sources, if you need an external kernel
685 module, the <filename>hello-mod.bb</filename> recipe is available 685 module, the <filename>hello-mod.bb</filename> recipe is
686 as a template from which you can create your own out-of-tree 686 available as a template from which you can create your
687 Linux kernel module recipe. 687 own out-of-tree Linux kernel module recipe.
688 </para> 688 </para>
689 689
690 <para> 690 <para>
@@ -700,12 +700,12 @@
700 <para> 700 <para>
701 To get started, copy this recipe to your layer and give it a 701 To get started, copy this recipe to your layer and give it a
702 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>). 702 meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
703 In the same directory, create a directory named 703 In the same directory, create a new directory named
704 <filename>files</filename> where you can store any source files, 704 <filename>files</filename> where you can store any source files,
705 patches, or other files necessary for building 705 patches, or other files necessary for building
706 the module that do not come with the sources. 706 the module that do not come with the sources.
707 Finally, update the recipe as appropriate for the module. 707 Finally, update the recipe as needed for the module.
708 Typically you will need to set the following variables: 708 Typically, you will need to set the following variables:
709 <itemizedlist> 709 <itemizedlist>
710 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink> 710 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
711 </para></listitem> 711 </para></listitem>
@@ -719,11 +719,11 @@
719 </para> 719 </para>
720 720
721 <para> 721 <para>
722 Depending on the build system used by the module sources, you might 722 Depending on the build system used by the module sources,
723 need to make some adjustments. 723 you might need to make some adjustments.
724 For example, a typical module <filename>Makefile</filename> looks 724 For example, a typical module <filename>Makefile</filename>
725 much like the one provided with the <filename>hello-mod</filename> 725 looks much like the one provided with the
726 template: 726 <filename>hello-mod</filename> template:
727 <literallayout class='monospaced'> 727 <literallayout class='monospaced'>
728 obj-m := hello.o 728 obj-m := hello.o
729 729
@@ -742,27 +742,29 @@
742 The important point to note here is the 742 The important point to note here is the
743 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink> 743 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
744 variable. 744 variable.
745 The class <filename>module.bbclass</filename> sets this variable, 745 The
746 as well as the 746 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink>
747 class sets this variable and the
747 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink> 748 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
748 variable to 749 variable to
749 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename> 750 <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
750 with the necessary Linux kernel build information to build modules. 751 with the necessary Linux kernel build information to build
752 modules.
751 If your module <filename>Makefile</filename> uses a different 753 If your module <filename>Makefile</filename> uses a different
752 variable, you might want to override the 754 variable, you might want to override the
753 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink> 755 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink>
754 step, or create a patch to 756 step, or create a patch to
755 the <filename>Makefile</filename> to work with the more typical 757 the <filename>Makefile</filename> to work with the more typical
756 <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename> 758 <filename>KERNEL_SRC</filename> or
757 variables. 759 <filename>KERNEL_PATH</filename> variables.
758 </para> 760 </para>
759 761
760 <para> 762 <para>
761 After you have prepared your recipe, you will likely want to 763 After you have prepared your recipe, you will likely want to
762 include the module in your images. 764 include the module in your images.
763 To do this, see the documentation for the following variables in 765 To do this, see the documentation for the following variables in
764 the Yocto Project Reference Manual and set one of them as 766 the Yocto Project Reference Manual and set one of them
765 appropriate in your machine configuration file: 767 appropriately for your machine configuration file:
766 <itemizedlist> 768 <itemizedlist>
767 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink> 769 <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
768 </para></listitem> 770 </para></listitem>
@@ -776,13 +778,13 @@
776 </para> 778 </para>
777 779
778 <para> 780 <para>
779 modules are often not required for boot and can be excluded from 781 Modules are often not required for boot and can be excluded from
780 certain build configurations. 782 certain build configurations.
781 The following allows for the most flexibility: 783 The following allows for the most flexibility:
782 <literallayout class='monospaced'> 784 <literallayout class='monospaced'>
783 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule" 785 MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
784 </literallayout> 786 </literallayout>
785 Where the value is derived by appending the module filename without 787 The value is derived by appending the module filename without
786 the <filename>.ko</filename> extension to the string 788 the <filename>.ko</filename> extension to the string
787 "kernel-module-". 789 "kernel-module-".
788 </para> 790 </para>
@@ -792,8 +794,8 @@
792 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink> 794 <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
793 and not a 795 and not a
794 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink> 796 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
795 variable, the build will not fail if this module is not available 797 variable, the build will not fail if this module is not
796 to include in the image. 798 available to include in the image.
797 </para> 799 </para>
798 </section> 800 </section>
799 </section> 801 </section>