diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2011-07-27 07:05:33 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2011-08-04 15:06:44 +0100 |
commit | bed9ff31b67ae4a00c46be2606e06fc3cb0d0e73 (patch) | |
tree | f9c4613fc2df74de8f296aa7e2a7498123521da6 /documentation | |
parent | 5492fa39a082aa15af48ce273353cba90b795f9b (diff) | |
download | ast2050-yocto-poky-bed9ff31b67ae4a00c46be2606e06fc3cb0d0e73.zip ast2050-yocto-poky-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')
-rw-r--r-- | documentation/dev-manual/dev-manual-cases.xml | 318 |
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 610412d..28d48d0 100644 --- a/documentation/dev-manual/dev-manual-cases.xml +++ b/documentation/dev-manual/dev-manual-cases.xml @@ -750,7 +750,7 @@ </section> </section> - <section id='modifying-a-kernel'> + <section id='modifying-a-kernel-kernel-example'> <title>Modifying a Kernel</title> <para> @@ -765,7 +765,7 @@ example that shows how to modify the kernel. </para> - <section id='yocto-project-kernel-overview'> + <section id='yocto-project-kernel'> <title>Yocto Project Kernel Overview</title> <para> @@ -782,10 +782,11 @@ branches represent diversions from more general code. For example, suppose two kernels are basically identical with the exception of a couple different features in each. - In the Yocto Project kernel Git repository a main branch can contain the common or shared + In the Yocto Project source repositories managed by Git a main branch can contain the + common or shared parts of the kernel source and two branches that diverge from that common branch can each contain the features specific to the respective kernel. - The result is a tree whose "leaves" represent the end of a specific path that yields + The result is a managed tree whose "leaves" represent the end of a specific path that yields a set of kernel source files necessary for a specific piece of hardware and its features. </para> @@ -797,11 +798,11 @@ <para> When you build the kernel on your development system all files needed for the build - are taken from the local tree (the Git repository) and gathered in a temporary work area + are taken from the Yocto Project source repositories pointed to by the + <filename>SRC_URI</filename> variable and gathered in a temporary work area where they are subsequently used to create the unique kernel. - Thus, in a sense, the process uses a local, all-inclusive source tree to generate - (or choose) the specific kernel source files you need for the build - a source - generator if you will. + Thus, in a sense, the process constructs a local source tree specific to your + kernel to generate the new kernel image - a source generator if you will. </para> <para> @@ -814,7 +815,8 @@ You can find a web interface to the Yocto Project source repository at <ulink url='http://git.yoctoproject.org/'></ulink>. Within the interface you will see groups of related source code, each of which can - be cloned using Git to result in a working Git repository on your local system. + be cloned using Git to result in a working Git repository on your local system + (referred to as the "local Yocto Project files" in this manual). The Yocto Project supports four types of kernels in its source repositories at <ulink url='http://git.yoctoproject.org/'></ulink>: <itemizedlist> @@ -836,15 +838,303 @@ <title>Modifying a Kernel Example</title> <para> - The remainder of this section presents a simple example that modifies a kernel. - For the purpose of this example we are going to base our new kernel on the current - Linux Yocto 2.6.37 release. + This section presents a simple example that illustrates kernel modification + based on the <filename>linux-yocto-2.6.37</filename> kernel. + The example uses the audio and mixer capabilities supported by the + <ulink url='http://www.alsa-project.org/main/index.php/Main_Page'>Advanced Linux + Sound Architecture (ALSA) Project</ulink>. + As the example progresses you will see how to do the following: + <itemizedlist> + <listitem><para>Iteratively modify a base kernel locally.</para></listitem> + <listitem><para>Provide a recipe-based solution for your modified kernel. + </para></listitem> + <listitem><para>Proved an "in-tree" solution for your modified kernel + (i.e. make the modifcations part of the Yocto Project).</para></listitem> + </itemizedlist> </para> - + + <para> + The example flows as follows: + </para> + + <para> + <itemizedlist> + <listitem><para>Be sure your host development system is set up to support + development using the Yocto Project. + See + <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#the-linux-distro'> + The Linux Distributions</ulink> section and + <ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#packages'> + The Packages</ulink> section both + in the Yocto Project Quick Start for requirements. + You will also need a release of Yocto Project installed on the host.</para></listitem> + <listitem><para>Set up your environment for optimal local kernel development. + </para></listitem> + <listitem><para>Create a layer to isolate your kernel work.</para></listitem> + <listitem><para>Next item.</para></listitem> + <listitem><para>Next item.</para></listitem> + <listitem><para>Next item.</para></listitem> + <listitem><para>Next item.</para></listitem> + </itemizedlist> + </para> + + <section id='setting-up-yocto-project-kernel-example'> + <title>Setting Up Yocto Project</title> + + <para> + You need to have the Yocto Project files available on your host system. + The process is identical to that described in getting the files in section + <xref linkend='setting-up-yocto-project'>"Setting Up Yocto Project"</xref> for + the BSP development case. + Be sure to either set up a local Git repository for <filename>poky</filename> + or download and unpack the Yocto Project release tarball. + </para> + </section> + + <section id='create-a-git-repository-of-poky-extras'> + <title>Create a Git Repository of <filename>poky-extras</filename></title> + + <para> + Everytime you change a configuration or add a recipe to the kernel you need to + do a fetch from the Linux Yocto kernel source repositories. + This can get tedious and time consuming if you need to fetch the entire + Linux Yocto 2.6.37 Git repository down from the Internet everytime you make a change + to the kernel. + </para> + + <para> + You can get around this by setting up a <filename>meta-kernel-dev</filename> + area on your local system. + This area contains "append" files for every kernel recipe, which also include + a <filename>KSRC</filename> statement that points to the kernel source files. + You can set up the environment so that the <filename>KSRC</filename> points to the + <filename>meta-kernel-dev</filename>, thus pulling source from a local area. + This setup can speed up development time. + </para> + + <para> + To get set up you need to do two things: create a local Git repository + of the <filename>poky-extras</filename> repository, and create a bare clone of the + Linux Yocto 2.6.37 kernel Git repository. + </para> + + <para> + The following transcript shows how to clone the <filename>poky-extras</filename> + Git repository into the current working directory, which is <filename>poky</filename> + in this example. + The command creates the repository in a directory named <filename>poky-extras</filename>: + <literallayout class='monospaced'> + $ git clone git://git.yoctoproject.org/poky-extras + Initialized empty Git repository in /home/scottrif/poky/poky-extras/.git/ + remote: Counting objects: 532, done. + remote: Compressing objects: 100% (472/472), done. + remote: Total 532 (delta 138), reused 307 (delta 39) + Receiving objects: 100% (532/532), 534.28 KiB | 362 KiB/s, done. + Resolving deltas: 100% (138/138), done. + </literallayout> + </para> + + <para> + This transcript shows how to clone a bare Git repository of the Linux Yocto + 2.6.37 kernel: + <literallayout class='monospaced'> + $ git clone --bare git://git.yoctoproject.org/linux-yocto-2.6.37 + Initialized empty Git repository in /home/scottrif/linux-yocto-2.6.37.git/ + remote: Counting objects: 1886034, done. + remote: Compressing objects: 100% (314326/314326), done. + remote: Total 1886034 (delta 1570202), reused 1870335 (delta 1554798) + Receiving objects: 100% (1886034/1886034), 401.51 MiB | 714 KiB/s, done. + Resolving deltas: 100% (1570202/1570202), done. + </literallayout> + </para> + + <para> + The bare clone of the Linux Yocto 2.6.37 kernel on your local system mirrors + the upstream repository of the kernel. + You can effectively point to this local clone now during development to avoid + having to fetch the entire Linux Yocto 2.6.37 kernel every time you make a + kernel change. + </para> + </section> + + <section id='create-a-layer-for-your-kernel-work'> + <title>Create a Layer for Your Kernel Work</title> + + <para> + It is always good to isolate your work using your own layer. + Doing so allows you to experiment and easily start over should things go wrong. + This example uses a layer named <filename>meta-amixer</filename>. + </para> + + <para> + When you set up a layer for kernel work you should follow the general layout + guidelines as described for BSP layers. + This layout is described in the + <ulink url='http://www.yoctoproject.org/docs/1.1/bsp-guide/bsp-guide.html#bsp-filelayout'> + Example Filesystem Layout</ulink> section of the Board Support Package (BSP) Development + Guide. + In the standard layout you will notice a suggested structure for recipes and + configuration information. + [WRITER'S NOTE: The <filename>meta-elc</filename> example uses an + <filename>images</filename> directory. + Currently, <filename>images</filename> is not part of the standard BSP layout. + I need to find out from Darren if this directory is required for kernel work.] + </para> + + <para> + [WRITER'S NOTE: I need a paragraph here describing how to set up the layer. + I am not sure if you should copy an existing BSP layer and modify from there. + Or, if you should just look at a BSP layer and then create your own files. + Email to Darren on this but no answer yet.] + </para> + </section> + + <section id='making-changes-to-your-kernel-layer'> + <title>Making Changes to Your Kernel Layer</title> + <para> + In the standard layer structure you have several areas that you need to examine or + modify. + For this example the layer contains four areas: + <itemizedlist> + <listitem><para><emphasis><filename>conf</filename></emphasis> - Contains the + <filename>layer.conf</filename> that identifies the location of the recipe files. + </para></listitem> + <listitem><para><emphasis><filename>images</filename></emphasis> - Contains the + image recipe file. + This recipe includes the base image you will be using and specifies other + packages the image might need.</para></listitem> + <listitem><para><emphasis><filename>recipes-bsp</filename></emphasis> - Contains + recipes specific to the hardware for which you are developing the kernel. + </para></listitem> + <listitem><para><emphasis><filename>recipes-kernel</filename></emphasis> - Contains the + "append" files that add information to the main recipe kernel. + </para></listitem> + </itemizedlist> + </para> + + <para> + Let's take a look at the <filename>layer.conf</filename> in the + <filename>conf</filename> directory first. + This configuration file enables the Yocto Project build system to locate and + use the information in your new layer. + </para> + + <para> + The variable <filename>BBPATH</filename> needs to include the path to your layer + as follows: + <literallayout class='monospaced'> + BBPATH := "${BBPATH}:${LAYERDIR}" + </literallayout> + And, the variable <filename>BBFILES</filename> needs to be modified to include your + recipe and append files: + <literallayout class='monospaced'> + BBFILES := "${BBFILES} ${LAYERDIR}/images/*.bb \ + ${LAYERDIR}/images/*.bbappend \ + ${LAYERDIR}/recipes-*/*/*.bb \ + ${LAYERDIR}/recipes-*/*/*.bbappend" + </literallayout> + Finally, you need to be sure to use your layer name in these variables at the + end of the file: + <literallayout class='monospaced'> + BBFILE_COLLECTIONS += "elc" + BBFILE_PATTERN_elc := "^${LAYERDIR}/" + BBFILE_PRIORITY_elc = "9" + </literallayout> + </para> + + <para> + The <filename>images</filename> directory contains an append file that helps + further define the image. + In our example, the base image is <filename>core-image-minimal</filename>. + The image does, however, need some additional modules that we are using + for this example. + These modules support the amixer functionality. + Here is the append file: + <literallayout class='monospaced'> + require recipes-core/images/poky-image-minimal.bb + + IMAGE_INSTALL += "dropbear alsa-utils-aplay alsa-utils-alsamixer" + IMAGE_INSTALL_append_qemux86 += " kernel-module-snd-ens1370 \ + kernel-module-snd-rawmidi kernel-module-loop kernel-module-nls-cp437 \ + kernel-module-nls-iso8859-1 qemux86-audio alsa-utils-amixer" + + LICENSE = "MIT" + </literallayout> + </para> + + <para> + While the focus of this example is not on the BSP, it is worth mentioning that the + <filename>recipes-bsp</filename> directory has the recipes and append files for + features that the hardware requires. + In this example, there is a script and a recipe to support the + <filename>amixer</filename> functionality in QEMU. + It is beyond the scope of this manual to go too deeply into the script. + Suffice it to say that the script tests for the presence of the mixer, sets up + default mixer values, enables the mixer, unmutes master and then + sets the volume to 100. + </para> + + <para> + The recipe <filename>qemu86-audio.bb</filename> installs and runs the + <filename>amixer</filename> when the system boots. + Here is the recipe: + <literallayout class='monospaced'> + SUMMARY = "Provide a basic init script to enable audio" + DESCRIPTION = "Set the volume and unmute the Front mixer setting during boot." + SECTION = "base" + LICENSE = "MIT" + LIC_FILES_CHKSUM = "file://${POKYBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58" + + PR = "r4" + + inherit update-rc.d + + RDEPENDS = "alsa-utils-amixer" + + SRC_URI = "file://qemux86-audio" + + INITSCRIPT_NAME = "qemux86-audio" + INITSCRIPT_PARAMS = "defaults 90" + + do_install() { + install -d ${D}${sysconfdir} \ + ${D}${sysconfdir}/init.d + install -m 0755 ${WORKDIR}/qemux86-audio ${D}${sysconfdir}/init.d + cat ${WORKDIR}/${INITSCRIPT_NAME} | \ + sed -e 's,/etc,${sysconfdir},g' \ + -e 's,/usr/sbin,${sbindir},g' \ + -e 's,/var,${localstatedir},g' \ + -e 's,/usr/bin,${bindir},g' \ + -e 's,/usr,${prefix},g' > ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME} + chmod 755 ${D}${sysconfdir}/init.d/${INITSCRIPT_NAME} + } + </literallayout> + </para> + + <para> + The last area to look at is <filename>recipes-kernel</filename>. + This area holds configuration fragments and kernel append files. + The append file must have the same name as the kernel recipe, which is + <filename>linux-yocto-2.6.37</filename> in this example. + The file can <filename>SRC_URI</filename> statements to point to configuration + fragments you might have in the layer. + The file can also contain <filename>KERNEL_FEATURES</filename> statements that specify + included kernel configurations that ship with the Yocto Project. + </para> + </section> + </section> + </section> +</section> +</chapter> + + + +<!-- + <para> [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel. @@ -895,6 +1185,8 @@ </para> </section> </chapter> +--> + <!-- vim: expandtab tw=80 ts=4 --> |