summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-07-27 07:05:33 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-08-04 15:06:44 +0100
commitbed9ff31b67ae4a00c46be2606e06fc3cb0d0e73 (patch)
treef9c4613fc2df74de8f296aa7e2a7498123521da6 /documentation/dev-manual
parent5492fa39a082aa15af48ce273353cba90b795f9b (diff)
downloadpoky-bed9ff31b67ae4a00c46be2606e06fc3cb0d0e73.tar.gz
documentation/dev-manual/dev-manual-cases.xml: partial - kernel section added
added the start of the kernel example. It is not complete. There are other various edits made throughout the chapter as well. (From yocto-docs rev: 39ba857b71aa643593a539d979186753fb7a9049) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-cases.xml318
1 files changed, 305 insertions, 13 deletions
diff --git a/documentation/dev-manual/dev-manual-cases.xml b/documentation/dev-manual/dev-manual-cases.xml
index 610412d166..28d48d0c9e 100644
--- a/documentation/dev-manual/dev-manual-cases.xml
+++ b/documentation/dev-manual/dev-manual-cases.xml
@@ -750,7 +750,7 @@
750 </section> 750 </section>
751 </section> 751 </section>
752 752
753 <section id='modifying-a-kernel'> 753 <section id='modifying-a-kernel-kernel-example'>
754 <title>Modifying a Kernel</title> 754 <title>Modifying a Kernel</title>
755 755
756 <para> 756 <para>
@@ -765,7 +765,7 @@
765 example that shows how to modify the kernel. 765 example that shows how to modify the kernel.
766 </para> 766 </para>
767 767
768 <section id='yocto-project-kernel-overview'> 768 <section id='yocto-project-kernel'>
769 <title>Yocto Project Kernel Overview</title> 769 <title>Yocto Project Kernel Overview</title>
770 770
771 <para> 771 <para>
@@ -782,10 +782,11 @@
782 branches represent diversions from more general code. 782 branches represent diversions from more general code.
783 For example, suppose two kernels are basically identical with the exception of a couple 783 For example, suppose two kernels are basically identical with the exception of a couple
784 different features in each. 784 different features in each.
785 In the Yocto Project kernel Git repository a main branch can contain the common or shared 785 In the Yocto Project source repositories managed by Git a main branch can contain the
786 common or shared
786 parts of the kernel source and two branches that diverge from that common branch can 787 parts of the kernel source and two branches that diverge from that common branch can
787 each contain the features specific to the respective kernel. 788 each contain the features specific to the respective kernel.
788 The result is a tree whose "leaves" represent the end of a specific path that yields 789 The result is a managed tree whose "leaves" represent the end of a specific path that yields
789 a set of kernel source files necessary for a specific piece of hardware and its features. 790 a set of kernel source files necessary for a specific piece of hardware and its features.
790 </para> 791 </para>
791 792
@@ -797,11 +798,11 @@
797 798
798 <para> 799 <para>
799 When you build the kernel on your development system all files needed for the build 800 When you build the kernel on your development system all files needed for the build
800 are taken from the local tree (the Git repository) and gathered in a temporary work area 801 are taken from the Yocto Project source repositories pointed to by the
802 <filename>SRC_URI</filename> variable and gathered in a temporary work area
801 where they are subsequently used to create the unique kernel. 803 where they are subsequently used to create the unique kernel.
802 Thus, in a sense, the process uses a local, all-inclusive source tree to generate 804 Thus, in a sense, the process constructs a local source tree specific to your
803 (or choose) the specific kernel source files you need for the build - a source 805 kernel to generate the new kernel image - a source generator if you will.
804 generator if you will.
805 </para> 806 </para>
806 807
807 <para> 808 <para>
@@ -814,7 +815,8 @@
814 You can find a web interface to the Yocto Project source repository at 815 You can find a web interface to the Yocto Project source repository at
815 <ulink url='http://git.yoctoproject.org/'></ulink>. 816 <ulink url='http://git.yoctoproject.org/'></ulink>.
816 Within the interface you will see groups of related source code, each of which can 817 Within the interface you will see groups of related source code, each of which can
817 be cloned using Git to result in a working Git repository on your local system. 818 be cloned using Git to result in a working Git repository on your local system
819 (referred to as the "local Yocto Project files" in this manual).
818 The Yocto Project supports four types of kernels in its source repositories at 820 The Yocto Project supports four types of kernels in its source repositories at
819 <ulink url='http://git.yoctoproject.org/'></ulink>: 821 <ulink url='http://git.yoctoproject.org/'></ulink>:
820 <itemizedlist> 822 <itemizedlist>
@@ -836,15 +838,303 @@
836 <title>Modifying a Kernel Example</title> 838 <title>Modifying a Kernel Example</title>
837 839
838 <para> 840 <para>
839 The remainder of this section presents a simple example that modifies a kernel. 841 This section presents a simple example that illustrates kernel modification
840 For the purpose of this example we are going to base our new kernel on the current 842 based on the <filename>linux-yocto-2.6.37</filename> kernel.
841 Linux Yocto 2.6.37 release. 843 The example uses the audio and mixer capabilities supported by the
844 <ulink url='http://www.alsa-project.org/main/index.php/Main_Page'>Advanced Linux
845 Sound Architecture (ALSA) Project</ulink>.
846 As the example progresses you will see how to do the following:
847 <itemizedlist>
848 <listitem><para>Iteratively modify a base kernel locally.</para></listitem>
849 <listitem><para>Provide a recipe-based solution for your modified kernel.
850 </para></listitem>
851 <listitem><para>Proved an "in-tree" solution for your modified kernel
852 (i.e. make the modifcations part of the Yocto Project).</para></listitem>
853 </itemizedlist>
842 </para> 854 </para>
843 855
856 <para>
857 The example flows as follows:
858 </para>
859
860 <para>
861 <itemizedlist>
862 <listitem><para>Be sure your host development system is set up to support
863 development using the Yocto Project.
864 See
865 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'>
866 The Linux Distributions</ulink> section and
867 <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'>
868 The Packages</ulink> section both
869 in the Yocto Project Quick Start for requirements.
870 You will also need a release of Yocto Project installed on the host.</para></listitem>
871 <listitem><para>Set up your environment for optimal local kernel development.
872 </para></listitem>
873 <listitem><para>Create a layer to isolate your kernel work.</para></listitem>
874 <listitem><para>Next item.</para></listitem>
875 <listitem><para>Next item.</para></listitem>
876 <listitem><para>Next item.</para></listitem>
877 <listitem><para>Next item.</para></listitem>
878 </itemizedlist>
879 </para>
880
881 <section id='setting-up-yocto-project-kernel-example'>
882 <title>Setting Up Yocto Project</title>
883
884 <para>
885 You need to have the Yocto Project files available on your host system.
886 The process is identical to that described in getting the files in section
887 <xref linkend='setting-up-yocto-project'>"Setting Up Yocto Project"</xref> for
888 the BSP development case.
889 Be sure to either set up a local Git repository for <filename>poky</filename>
890 or download and unpack the Yocto Project release tarball.
891 </para>
892 </section>
893
894 <section id='create-a-git-repository-of-poky-extras'>
895 <title>Create a Git Repository of <filename>poky-extras</filename></title>
896
897 <para>
898 Everytime you change a configuration or add a recipe to the kernel you need to
899 do a fetch from the Linux Yocto kernel source repositories.
900 This can get tedious and time consuming if you need to fetch the entire
901 Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change
902 to the kernel.
903 </para>
904
905 <para>
906 You can get around this by setting up a <filename>meta-kernel-dev</filename>
907 area on your local system.
908 This area contains "append" files for every kernel recipe, which also include
909 a <filename>KSRC</filename> statement that points to the kernel source files.
910 You can set up the environment so that the <filename>KSRC</filename> points to the
911 <filename>meta-kernel-dev</filename>, thus pulling source from a local area.
912 This setup can speed up development time.
913 </para>
914
915 <para>
916 To get set up you need to do two things: create a local Git repository
917 of the <filename>poky-extras</filename> repository, and create a bare clone of the
918 Linux Yocto 2.6.37 kernel Git repository.
919 </para>
920
921 <para>
922 The following transcript shows how to clone the <filename>poky-extras</filename>
923 Git repository into the current working directory, which is <filename>poky</filename>
924 in this example.
925 The command creates the repository in a directory named <filename>poky-extras</filename>:
926 <literallayout class='monospaced'>
927 $ git clone git://git.yoctoproject.org/poky-extras
928 Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/
929 remote: Counting objects: 532, done.
930 remote: Compressing objects: 100% (472/472), done.
931 remote: Total 532 (delta 138), reused 307 (delta 39)
932 Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done.
933 Resolving deltas: 100% (138/138), done.
934 </literallayout>
935 </para>
936
937 <para>
938 This transcript shows how to clone a bare Git repository of the Linux Yocto
939 2.6.37 kernel:
940 <literallayout class='monospaced'>
941 $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37
942 Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/
943 remote: Counting objects: 1886034, done.
944 remote: Compressing objects: 100% (314326/314326), done.
945 remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798)
946 Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done.
947 Resolving deltas: 100% (1570202/1570202), done.
948 </literallayout>
949 </para>
950
951 <para>
952 The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors
953 the upstream repository of the kernel.
954 You can effectively point to this local clone now during development to avoid
955 having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a
956 kernel change.
957 </para>
958 </section>
959
960 <section id='create-a-layer-for-your-kernel-work'>
961 <title>Create a Layer for Your Kernel Work</title>
962
963 <para>
964 It is always good to isolate your work using your own layer.
965 Doing so allows you to experiment and easily start over should things go wrong.
966 This example uses a layer named <filename>meta-amixer</filename>.
967 </para>
968
969 <para>
970 When you set up a layer for kernel work you should follow the general layout
971 guidelines as described for BSP layers.
972 This layout is described in the
973 <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'>
974 Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development
975 Guide.
976 In the standard layout you will notice a suggested structure for recipes and
977 configuration information.
978 [WRITER'S NOTE: The <filename>meta-elc</filename> example uses an
979 <filename>images</filename> directory.
980 Currently, <filename>images</filename> is not part of the standard BSP layout.
981 I need to find out from Darren if this directory is required for kernel work.]
982 </para>
983
984 <para>
985 [WRITER'S NOTE: I need a paragraph here describing how to set up the layer.
986 I am not sure if you should copy an existing BSP layer and modify from there.
987 Or, if you should just look at a BSP layer and then create your own files.
988 Email to Darren on this but no answer yet.]
989 </para>
990 </section>
991
992 <section id='making-changes-to-your-kernel-layer'>
993 <title>Making Changes to Your Kernel Layer</title>
844 994
995 <para>
996 In the standard layer structure you have several areas that you need to examine or
997 modify.
998 For this example the layer contains four areas:
999 <itemizedlist>
1000 <listitem><para><emphasis><filename>conf</filename></emphasis> - Contains the
1001 <filename>layer.conf</filename> that identifies the location of the recipe files.
1002 </para></listitem>
1003 <listitem><para><emphasis><filename>images</filename></emphasis> - Contains the
1004 image recipe file.
1005 This recipe includes the base image you will be using and specifies other
1006 packages the image might need.</para></listitem>
1007 <listitem><para><emphasis><filename>recipes-bsp</filename></emphasis> - Contains
1008 recipes specific to the hardware for which you are developing the kernel.
1009 </para></listitem>
1010 <listitem><para><emphasis><filename>recipes-kernel</filename></emphasis> - Contains the
1011 "append" files that add information to the main recipe kernel.
1012 </para></listitem>
1013 </itemizedlist>
1014 </para>
1015
1016 <para>
1017 Let's take a look at the <filename>layer.conf</filename> in the
1018 <filename>conf</filename> directory first.
1019 This configuration file enables the Yocto Project build system to locate and
1020 use the information in your new layer.
1021 </para>
1022
1023 <para>
1024 The variable <filename>BBPATH</filename> needs to include the path to your layer
1025 as follows:
1026 <literallayout class='monospaced'>
1027 BBPATH := "${BBPATH}:${LAYERDIR}"
1028 </literallayout>
1029 And, the variable <filename>BBFILES</filename> needs to be modified to include your
1030 recipe and append files:
1031 <literallayout class='monospaced'>
1032 BBFILES := "${BBFILES} ${LAYERDIR}/images/*.bb \
1033 ${LAYERDIR}/images/*.bbappend \
1034 ${LAYERDIR}/recipes-*/*/*.bb \
1035 ${LAYERDIR}/recipes-*/*/*.bbappend"
1036 </literallayout>
1037 Finally, you need to be sure to use your layer name in these variables at the
1038 end of the file:
1039 <literallayout class='monospaced'>
1040 BBFILE_COLLECTIONS += "elc"
1041 BBFILE_PATTERN_elc := "^${LAYERDIR}/"
1042 BBFILE_PRIORITY_elc = "9"
1043 </literallayout>
1044 </para>
1045
1046 <para>
1047 The <filename>images</filename> directory contains an append file that helps
1048 further define the image.
1049 In our example, the base image is <filename>core-image-minimal</filename>.
1050 The image does, however, need some additional modules that we are using
1051 for this example.
1052 These modules support the amixer functionality.
1053 Here is the append file:
1054 <literallayout class='monospaced'>
1055 require recipes-core/images/poky-image-minimal.bb
1056
1057 IMAGE_INSTALL += "dropbear alsa-utils-aplay alsa-utils-alsamixer"
1058 IMAGE_INSTALL_append_qemux86 += " kernel-module-snd-ens1370 \
1059 kernel-module-snd-rawmidi kernel-module-loop kernel-module-nls-cp437 \
1060 kernel-module-nls-iso8859-1 qemux86-audio alsa-utils-amixer"
1061
1062 LICENSE = "MIT"
1063 </literallayout>
1064 </para>
1065
1066 <para>
1067 While the focus of this example is not on the BSP, it is worth mentioning that the
1068 <filename>recipes-bsp</filename> directory has the recipes and append files for
1069 features that the hardware requires.
1070 In this example, there is a script and a recipe to support the
1071 <filename>amixer</filename> functionality in QEMU.
1072 It is beyond the scope of this manual to go too deeply into the script.
1073 Suffice it to say that the script tests for the presence of the mixer, sets up
1074 default mixer values, enables the mixer, unmutes master and then
1075 sets the volume to 100.
1076 </para>
1077
1078 <para>
1079 The recipe <filename>qemu86-audio.bb</filename> installs and runs the
1080 <filename>amixer</filename> when the system boots.
1081 Here is the recipe:
1082 <literallayout class='monospaced'>
1083 SUMMARY = "Provide a basic init script to enable audio"
1084 DESCRIPTION = "Set the volume and unmute the Front mixer setting during boot."
1085 SECTION = "base"
1086 LICENSE = "MIT"
1087 LIC_FILES_CHKSUM = "file://${POKYBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58"
1088
1089 PR = "r4"
1090
1091 inherit update-rc.d
1092
1093 RDEPENDS = "alsa-utils-amixer"
1094
1095 SRC_URI = "file://qemux86-audio"
1096
1097 INITSCRIPT_NAME = "qemux86-audio"
1098 INITSCRIPT_PARAMS = "defaults 90"
1099
1100 do_install() {
1101 install -d ${D}${sysconfdir} \
1102 ${D}${sysconfdir}/init.d
1103 install -m 0755 ${WORKDIR}/qemux86-audio ${D}${sysconfdir}/init.d
1104 cat ${WORKDIR}/${INITSCRIPT_NAME} | \
1105 sed -e 's,/etc,${sysconfdir},g' \
1106 -e 's,/usr/sbin,${sbindir},g' \
1107 -e 's,/var,${localstatedir},g' \
1108 -e 's,/usr/bin,${bindir},g' \
1109 -e 's,/usr,${prefix},g' > ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
1110 chmod 755 ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME}
1111 }
1112 </literallayout>
1113 </para>
1114
1115 <para>
1116 The last area to look at is <filename>recipes-kernel</filename>.
1117 This area holds configuration fragments and kernel append files.
1118 The append file must have the same name as the kernel recipe, which is
1119 <filename>linux-yocto-2.6.37</filename> in this example.
1120 The file can <filename>SRC_URI</filename> statements to point to configuration
1121 fragments you might have in the layer.
1122 The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify
1123 included kernel configurations that ship with the Yocto Project.
1124 </para>
1125 </section>
1126 </section>
1127 </section>
1128</section>
845 1129
1130</chapter>
846 1131
847 1132
1133
1134
1135
1136<!--
1137
848 1138
849 <para> 1139 <para>
850 [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel. 1140 [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel.
@@ -895,6 +1185,8 @@
895 </para> 1185 </para>
896</section> 1186</section>
897</chapter> 1187</chapter>
1188-->
1189
898<!-- 1190<!--
899vim: expandtab tw=80 ts=4 1191vim: expandtab tw=80 ts=4
900--> 1192-->