diff options
Diffstat (limited to 'documentation')
| -rw-r--r-- | documentation/dev-manual/dev-manual-cases.xml | 446 |
1 files changed, 0 insertions, 446 deletions
diff --git a/documentation/dev-manual/dev-manual-cases.xml b/documentation/dev-manual/dev-manual-cases.xml deleted file mode 100644 index fc93b53..0000000 --- a/documentation/dev-manual/dev-manual-cases.xml +++ /dev/null @@ -1,446 +0,0 @@ -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> - -<chapter id='dev-manual-cases'> - -<title>Development Cases</title> - - <section id='modifying-a-kernel-kernel-example'> - <title>Modifying a Kernel</title> - - <para> - Kernel modification involves changing or adding configurations to an existing kernel, or - adding recipes to the kernel that are needed to support specific hardware features. - The process is similar to creating a Board Support Package (BSP) except that it does not - involve a BSP layer. - </para> - - <para> - This section presents a brief overview of the kernel structure and then provides a simple - example that shows how to modify the kernel. - </para> - - <section id='yocto-project-kernel'> - <title>Yocto Project Kernel Overview</title> - - <para> - When one thinks of the source files for a kernel they usually think of a fixed structure - of files that contain kernel patches. - The Yocto Project, however, employs mechanisims that in a sense result in a kernel source - generator. - </para> - - <para> - The Yocto Project uses the source code management (SCM) tool Git to manage and track Yocto - Project files. - Git employs branching strategies that effectively produce a tree-like structure whose - 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 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 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> - - <para> - A big advantage to this scheme is the sharing of common features by keeping them in - "larger" branches that are further up the tree. - This practice eliminates redundant storage of similar features shared among kernels. - </para> - - <para> - When you build the kernel on your development system all files needed for the build - 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 constructs a local source tree specific to your - kernel to generate the new kernel image - a source generator if you will. - </para> - - <para> - For a complete discussion of the Yocto Project kernel's architcture and its branching strategy, - see the <ulink url='http://www.yoctoproject.org/docs/1.1/kernel-manual/kernel-manual.html'> - The Yocto Project Kernel Architecture and Use Manual</ulink>. - </para> - - <para> - 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 - (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> - <listitem><para><emphasis><filename>linux-yocto-2.6.34</filename></emphasis> - The - stable Linux Yocto kernel that is based on the Linux 2.6.34 release.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-2.6.37</filename></emphasis> - The current - Linux Yocto kernel that is based on the Linux 2.6.37 release.</para></listitem> - <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development - kernel based on the Linux 2.6.39-rc1 release.</para></listitem> - <listitem><para><emphasis><filename>linux-2.6</filename></emphasis> - A kernel based on - minimal Linux mainline tracking. - [WRITER'S NOTE: I don't know which Git repository the user needs to clone to get this - repository on their development system.]</para></listitem> - </itemizedlist> - </para> - </section> - - <section id='modifying-a-kernel-example'> - <title>Modifying a Kernel Example</title> - - <para> - 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 the - <xref linkend='getting-setup'>"Getting Setup"</xref> section earlier in this - manual. - 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> - -</chapter> - - - - - -<!-- - - - <para> - [WRITER'S NOTE: This section is a second example that focuses on just modifying the kernel. - I don't have any information on this yet. - </para> - - <para> - Here are some points to consider though: - <itemizedlist> - <listitem><para>Reference Darren's presentation - <ulink url='http://events.linuxfoundation.org/events/embedded-linux-conference/hart'> - here</ulink></para></listitem> - <listitem><para>Reference <xref linkend='dev-manual-start'>Getting Started with the Yocto Project</xref> - section to get set up at minimum.</para></listitem> - <listitem><para>Are there extra steps I need specific to kernel development to get started?</para></listitem> - <listitem><para>What do I do to get set up? - Is it a matter of just installing YP and having some pieces together? - What are the pieces?</para></listitem> - <listitem><para>Where do I get the base kernel to start with?</para></listitem> - <listitem><para>Do I install the appropriate toolchain?</para></listitem> - <listitem><para>What kernel git repository do I use?</para></listitem> - <listitem><para>What is the conversion script? - What does it do?</para></listitem> - <listitem><para>What do I have to do to integrate the kernel layer?</para></listitem> - <listitem><para>What do I use to integrate the kernel layer? - HOB? - Do I just Bitbake it?</para></listitem> - <listitem><para>Using the System Image Creator.]</para></listitem> - </itemizedlist> - </para> - </section> - </section> -</section> - -<section id='user-application-development'> - <title>User Application Development</title> - - <para> - [WRITER'S NOTE: This section is the second major development case - developing an application. - Here are points to consider: - <itemizedlist> - <listitem><para>User-space Application Development scenario overview.</para></listitem> - <listitem><para>Using the Yocto Eclipse Plug-in.</para></listitem> - <listitem><para>Back-door support.</para></listitem> - <listitem><para>I feel there is more to this area than we have captured during our two - review meetings.]</para></listitem> - </itemizedlist> - </para> -</section> -</chapter> ---> - -<!-- -vim: expandtab tw=80 ts=4 ---> |
