summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2012-10-08 10:14:58 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-10-10 15:18:11 +0100
commite0f0335467cc5bf1fedac8ac053d4565f1664ca1 (patch)
treee84eb82d8ce84d7ba14866dc304b17e0f64d4240 /documentation
parent274095d4c21a8f617a41f85a364db78e96f7bf4d (diff)
downloadpoky-e0f0335467cc5bf1fedac8ac053d4565f1664ca1.tar.gz
documentation: dev-manual, bsp-guide - Removing/Moving Appendix A
The kernel example appendix is being removed. This broke a lot of links. For now I have moved the information into a new section called "Patching the Kernel". I have preserved the information by adding the old appendix file as kerne-appendix-orig.xml. (From yocto-docs rev: 994235a69362dfb0114ef9001ea7f2f2e2fdc5c3) 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/bsp-guide/bsp.xml4
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml559
-rw-r--r--documentation/dev-manual/dev-manual-kernel-appendix-orig.xml553
-rw-r--r--documentation/dev-manual/dev-manual-model.xml21
-rw-r--r--documentation/dev-manual/dev-manual.xml2
5 files changed, 1124 insertions, 15 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 7c63e4f24d..2fa016a969 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -618,10 +618,10 @@
618 <filename>meta</filename> branch for your BSP. 618 <filename>meta</filename> branch for your BSP.
619 The configuration options will likely end up in that location anyway if the BSP gets 619 The configuration options will likely end up in that location anyway if the BSP gets
620 added to the Yocto Project. 620 added to the Yocto Project.
621 For a better understanding of working with a local clone of the kernel repository 621<!-- For a better understanding of working with a local clone of the kernel repository
622 and a local bare clone of the kernel, see the 622 and a local bare clone of the kernel, see the
623 "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel-source-code'>Modifying the Kernel 623 "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel-source-code'>Modifying the Kernel
624 Source Code</ulink>" section also in the Yocto Project Development Manual. 624 Source Code</ulink>" section also in the Yocto Project Development Manual. -->
625 </para> 625 </para>
626 626
627 <para> 627 <para>
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 918d884681..4ce0a94873 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1590,6 +1590,565 @@
1590 </section> 1590 </section>
1591 </section> 1591 </section>
1592 1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604 <section id="patching-the-kernel">
1605 <title>Patching the Kernel</title>
1606
1607 <para>
1608 Kernel modification involves changing or adding configurations to an existing kernel,
1609 changing or adding recipes to the kernel that are needed to support specific hardware features,
1610 or even altering the source code itself.
1611 This appendix presents simple examples that modify the kernel source code,
1612 change the kernel configuration, and add a kernel source recipe.
1613 <note>
1614 You can use the <filename>yocto-kernel</filename> script
1615 found in the <link linkend='source-directory'>Source Directory</link>
1616 under <filename>scripts</filename> to manage kernel patches and configuration.
1617 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
1618 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
1619 more information.</note>
1620 </para>
1621
1622 <para>
1623 This example adds some simple QEMU emulator console output at boot time by
1624 adding <filename>printk</filename> statements to the kernel's
1625 <filename>calibrate.c</filename> source code file.
1626 Booting the modified image causes the added messages to appear on the emulator's
1627 console.
1628 </para>
1629
1630 <section id='understanding-the-files-you-need'>
1631 <title>Understanding the Files You Need</title>
1632
1633 <para>
1634 Before you modify the kernel, you need to know what Git repositories and file
1635 structures you need.
1636 Briefly, you need the following:
1637 <itemizedlist>
1638 <listitem><para>A local
1639 <link linkend='source-directory'>Source Directory</link> for the
1640 poky Git repository</para></listitem>
1641 <listitem><para>Local copies of the
1642 <link linkend='poky-extras-repo'><filename>poky-extras</filename></link>
1643 Git repository placed within the Source Directory.</para></listitem>
1644 <listitem><para>A bare clone of the
1645 <link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git
1646 repository to which you want to push your modifications.
1647 </para></listitem>
1648 <listitem><para>A copy of that bare clone in which you make your source
1649 modifications</para></listitem>
1650 </itemizedlist>
1651 </para>
1652
1653 <para>
1654 The following figure summarizes these four areas.
1655 Within each rectangular that represents a data structure, a
1656 host development directory pathname appears at the
1657 lower left-hand corner of the box.
1658 These pathnames are the locations used in this example.
1659 The figure also provides key statements and commands used during the kernel
1660 modification process:
1661 </para>
1662
1663 <para>
1664 <imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in"
1665 align="center" scale="100" />
1666 </para>
1667
1668 <para>
1669 Here is a brief description of the four areas:
1670 <itemizedlist>
1671 <listitem><para><emphasis>Local Source Directory:</emphasis>
1672 This area contains all the metadata that supports building images
1673 using the OpenEmbedded build system.
1674 In this example, the
1675 <link linkend='source-directory'>Source Directory</link> also
1676 contains the
1677 <link linkend='build-directory'>Build Directory</link>,
1678 which contains the configuration directory
1679 that lets you control the build.
1680 Also in this example, the Source Directory contains local copies of the
1681 <filename>poky-extras</filename> Git repository.</para>
1682 <para>See the bulleted item
1683 "<link linkend='local-yp-release'>Yocto Project Release</link>"
1684 for information on how to get these files on your local system.</para></listitem>
1685 <listitem><para><emphasis>Local copies of the&nbsp;<filename>poky-extras</filename>&nbsp;Git Repository:</emphasis>
1686 This area contains the <filename>meta-kernel-dev</filename> layer,
1687 which is where you make changes that append the kernel build recipes.
1688 You edit <filename>.bbappend</filename> files to locate your
1689 local kernel source files and to identify the kernel being built.
1690 This Git repository is a gathering place for extensions to the Yocto Project
1691 (or really any) kernel recipes that faciliate the creation and development
1692 of kernel features, BSPs or configurations.</para>
1693 <para>See the bulleted item
1694 "<link linkend='poky-extras-repo'>The
1695 <filename>poky-extras</filename> Git Repository</link>"
1696 for information on how to get these files.</para></listitem>
1697 <listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis>
1698 This bare Git repository tracks the upstream Git repository of the Linux
1699 Yocto kernel source code you are changing.
1700 When you modify the kernel you must work through a bare clone.
1701 All source code changes you make to the kernel must be committed and
1702 pushed to the bare clone using Git commands.
1703 As mentioned, the <filename>.bbappend</filename> file in the
1704 <filename>poky-extras</filename> repository points to the bare clone
1705 so that the build process can locate the locally changed source files.</para>
1706 <para>See the bulleted item
1707 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
1708 for information on how to set up the bare clone.
1709 </para></listitem>
1710 <listitem><para><emphasis>Copy of the Yocto Project Kernel Bare Clone:</emphasis>
1711 This Git repository contains the actual source files that you modify.
1712 Any changes you make to files in this location need to ultimately be pushed
1713 to the bare clone using the <filename>git push</filename> command.</para>
1714 <para>See the bulleted item
1715 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
1716 for information on how to set up the bare clone.
1717 <note>Typically, Git workflows follow a scheme where changes made to a local area
1718 are pulled into a Git repository.
1719 However, because the <filename>git pull</filename> command does not work
1720 with bare clones, this workflow pushes changes to the
1721 repository even though you could use other more complicated methods to
1722 get changes into the bare clone.</note>
1723 </para></listitem>
1724 </itemizedlist>
1725 </para>
1726 </section>
1727
1728 <section id='setting-up-the-local-yocto-project-files-git-repository'>
1729 <title>Setting Up the Local Source Directory</title>
1730
1731 <para>
1732 You can set up the
1733 <link linkend='source-directory'>Source Directory</link>
1734 through tarball extraction or by
1735 cloning the <filename>poky</filename> Git repository.
1736 This example uses <filename>poky</filename> as the root directory of the
1737 local Source Directory.
1738 See the bulleted item
1739 "<link linkend='local-yp-release'>Yocto Project Release</link>"
1740 for information on how to get these files.
1741 </para>
1742
1743 <para>
1744 Once you have Source Directory set up,
1745 you have many development branches from which you can work.
1746 From inside the local repository you can see the branch names and the tag names used
1747 in the upstream Git repository by using either of the following commands:
1748 <literallayout class='monospaced'>
1749 $ cd poky
1750 $ git branch -a
1751 $ git tag -l
1752 </literallayout>
1753 This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
1754 which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
1755 The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
1756 branch:
1757 <literallayout class='monospaced'>
1758 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
1759 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
1760 Switched to a new branch '&DISTRO_NAME;'
1761 </literallayout>
1762 </para>
1763 </section>
1764
1765 <section id='setting-up-the-poky-extras-git-repository'>
1766 <title>Setting Up the Local poky-extras Git Repository</title>
1767
1768 <para>
1769 This example creates a local copy of the <filename>poky-extras</filename> Git
1770 repository inside the <filename>poky</filename> Source Directory.
1771 See the bulleted item "<link linkend='poky-extras-repo'>The
1772 <filename>poky-extras</filename> Git Repository</link>"
1773 for information on how to set up a local copy of the
1774 <filename>poky-extras</filename> repository.
1775 </para>
1776
1777 <para>
1778 Because this example uses the Yocto Project &DISTRO; Release code
1779 named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename>
1780 branch in the repository, you need to be sure you are using that
1781 branch for <filename>poky-extras</filename>.
1782 The following commands create and checkout the local
1783 branch you are using for the <filename>&DISTRO_NAME;</filename>
1784 branch:
1785 <literallayout class='monospaced'>
1786 $ cd ~/poky/poky-extras
1787 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
1788 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
1789 Switched to a new branch '&DISTRO_NAME;'
1790 </literallayout>
1791 </para>
1792 </section>
1793
1794 <section id='setting-up-the-bare-clone-and-its-copy'>
1795 <title>Setting Up the Bare Clone and its Copy</title>
1796
1797 <para>
1798 This example modifies the <filename>linux-yocto-3.4</filename> kernel.
1799 Thus, you need to create a bare clone of that kernel and then make a copy of the
1800 bare clone.
1801 See the bulleted item
1802 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
1803 for information on how to do that.
1804 </para>
1805
1806 <para>
1807 The bare clone exists for the kernel build tools and simply as the receiving end
1808 of <filename>git push</filename>
1809 commands after you make edits and commits inside the copy of the clone.
1810 The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have
1811 a local branch created and checked out for your work.
1812 This example uses <filename>common-pc-base</filename> as the local branch.
1813 The following commands create and checkout the branch:
1814 <literallayout class='monospaced'>
1815 $ cd ~/my-linux-yocto-3.4-work
1816 $ git checkout -b standard-common-pc-base origin/standard/common-pc/base
1817 Branch standard-common-pc-base set up to track remote branch
1818 standard/common-pc/base from origin.
1819 Switched to a new branch 'standard-common-pc-base'
1820 </literallayout>
1821 </para>
1822 </section>
1823
1824 <section id='building-and-booting-the-default-qemu-kernel-image'>
1825 <title>Building and Booting the Default QEMU Kernel Image</title>
1826
1827 <para>
1828 Before we make changes to the kernel source files, this example first builds the
1829 default image and then boots it inside the QEMU emulator.
1830 <note>
1831 Because a full build can take hours, you should check two variables in the
1832 <filename>build</filename> directory that is created after you source the
1833 <filename>&OE_INIT_FILE;</filename> script.
1834 You can find these variables
1835 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
1836 in the <filename>build/conf</filename> directory in the
1837 <filename>local.conf</filename> configuration file.
1838 By default, these variables are commented out.
1839 If your host development system supports multi-core and multi-thread capabilities,
1840 you can uncomment these statements and set the variables to significantly shorten
1841 the full build time.
1842 As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and
1843 <filename>PARALLEL_MAKE</filename> to twice the number
1844 of cores your machine supports.
1845 </note>
1846 The following two commands <filename>source</filename> the build environment setup script
1847 and build the default <filename>qemux86</filename> image.
1848 If necessary, the script creates the build directory:
1849 <literallayout class='monospaced'>
1850 $ cd ~/poky
1851 $ source &OE_INIT_FILE;
1852 You had no conf/local.conf file. This configuration file has therefore been
1853 created for you with some default values. You may wish to edit it to use a
1854 different MACHINE (target hardware) or enable parallel build options to take
1855 advantage of multiple cores for example. See the file for more information as
1856 common configuration options are commented.
1857
1858 The Yocto Project has extensive documentation about OE including a reference manual
1859 which can be found at:
1860 http://yoctoproject.org/documentation
1861
1862 For more information about OpenEmbedded see their website:
1863 http://www.openembedded.org/
1864
1865 You had no conf/bblayers.conf file. The configuration file has been created for
1866 you with some default values. To add additional metadata layers into your
1867 configuration please add entries to this file.
1868
1869 The Yocto Project has extensive documentation about OE including a reference manual
1870 which can be found at:
1871 http://yoctoproject.org/documentation
1872
1873 For more information about OpenEmbedded see their website:
1874 http://www.openembedded.org/
1875
1876
1877
1878 ### Shell environment set up for builds. ###
1879
1880 You can now run 'bitbake &lt;target&gt;>'
1881
1882 Common targets are:
1883 core-image-minimal
1884 core-image-sato
1885 meta-toolchain
1886 meta-toolchain-sdk
1887 adt-installer
1888 meta-ide-support
1889
1890 You can also run generated qemu images with a command like 'runqemu qemux86'
1891 </literallayout>
1892 </para>
1893
1894 <para>
1895 The following <filename>bitbake</filename> command starts the build:
1896 <literallayout class='monospaced'>
1897 $ bitbake -k core-image-minimal
1898 </literallayout>
1899 <note>Be sure to check the settings in the <filename>local.conf</filename>
1900 before starting the build.</note>
1901 </para>
1902
1903 <para>
1904 After the build completes, you can start the QEMU emulator using the resulting image
1905 <filename>qemux86</filename> as follows:
1906 <literallayout class='monospaced'>
1907 $ runqemu qemux86
1908 </literallayout>
1909 </para>
1910
1911 <para>
1912 As the image boots in the emulator, console message and status output appears
1913 across the terminal window.
1914 Because the output scrolls by quickly, it is difficult to read.
1915 To examine the output, you log into the system using the
1916 login <filename>root</filename> with no password.
1917 Once you are logged in, issue the following command to scroll through the
1918 console output:
1919 <literallayout class='monospaced'>
1920 # dmesg | less
1921 </literallayout>
1922 </para>
1923
1924 <para>
1925 Take note of the output as you will want to look for your inserted print command output
1926 later in the example.
1927 </para>
1928 </section>
1929
1930 <section id='changing-the-source-code-and-pushing-it-to-the-bare-clone'>
1931 <title>Changing the Source Code and Pushing it to the Bare Clone</title>
1932
1933 <para>
1934 The file you change in this example is named <filename>calibrate.c</filename>
1935 and is located in the <filename>my-linux-yocto-3.4-work</filename> Git repository
1936 (the copy of the bare clone) in <filename>init</filename>.
1937 This example simply inserts several <filename>printk</filename> statements
1938 at the beginning of the <filename>calibrate_delay</filename> function.
1939 </para>
1940
1941 <para>
1942 Here is the unaltered code at the start of this function:
1943 <literallayout class='monospaced'>
1944 void __cpuinit calibrate_delay(void)
1945 {
1946 unsigned long lpj;
1947 static bool printed;
1948 int this_cpu = smp_processor_id();
1949
1950 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
1951 .
1952 .
1953 .
1954 </literallayout>
1955 </para>
1956
1957 <para>
1958 Here is the altered code showing five new <filename>printk</filename> statements
1959 near the top of the function:
1960 <literallayout class='monospaced'>
1961 void __cpuinit calibrate_delay(void)
1962 {
1963 unsigned long lpj;
1964 static bool printed;
1965 int this_cpu = smp_processor_id();
1966
1967 printk("*************************************\n");
1968 printk("* *\n");
1969 printk("* HELLO YOCTO KERNEL *\n");
1970 printk("* *\n");
1971 printk("*************************************\n");
1972
1973 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
1974 .
1975 .
1976 .
1977 </literallayout>
1978 </para>
1979
1980 <para>
1981 After making and saving your changes, you need to stage them for the push.
1982 The following Git commands are one method of staging and committing your changes:
1983 <literallayout class='monospaced'>
1984 $ git add calibrate.c
1985 $ git commit --signoff
1986 </literallayout>
1987 </para>
1988
1989 <para>
1990 Once the source code has been modified, you need to use Git to push the changes to
1991 the bare clone.
1992 If you do not push the changes, then the OpenEmbedded build system will not pick
1993 up the changed source files.
1994 </para>
1995
1996 <para>
1997 The following command pushes the changes to the bare clone:
1998 <literallayout class='monospaced'>
1999 $ git push origin standard-common-pc-base:standard/default/common-pc/base
2000 </literallayout>
2001 </para>
2002 </section>
2003
2004 <section id='changing-build-parameters-for-your-build'>
2005 <title>Changing Build Parameters for Your Build</title>
2006
2007 <para>
2008 At this point, the source has been changed and pushed.
2009 The example now defines some variables used by the OpenEmbedded build system
2010 to locate your kernel source.
2011 You essentially need to identify where to find the kernel recipe and the changed source code.
2012 You also need to be sure some basic configurations are in place that identify the
2013 type of machine you are building and to help speed up the build should your host support
2014 multiple-core and thread capabilities.
2015 </para>
2016
2017 <para>
2018 Do the following to make sure the build parameters are set up for the example.
2019 Once you set up these build parameters, they do not have to change unless you
2020 change the target architecture of the machine you are building or you move
2021 the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository:
2022 <itemizedlist>
2023 <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
2024 <filename>local.conf</filename> file in the build directory defines the build's
2025 target architecture.
2026 By default, <filename>MACHINE</filename> is set to
2027 <filename>qemux86</filename>, which specifies a 32-bit
2028 <trademark class='registered'>Intel</trademark> Architecture
2029 target machine suitable for the QEMU emulator.
2030 In this example, <filename>MACHINE</filename> is correctly configured.
2031 </para></listitem>
2032 <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
2033 <filename>local.conf</filename> file are two variables that can speed your
2034 build time if your host supports multi-core and multi-thread capabilities:
2035 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
2036 If the host system has multiple cores then you can optimize build time
2037 by setting both these variables to twice the number of
2038 cores.</para></listitem>
2039 <listitem><para><emphasis>Identify Your <filename>meta-kernel-dev</filename>
2040 Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
2041 <filename>bblayers.conf</filename> file found in the
2042 <filename>poky/build/conf</filename> directory needs to have the path to your local
2043 <filename>meta-kernel-dev</filename> layer.
2044 By default, the <filename>BBLAYERS</filename> variable contains paths to
2045 <filename>meta</filename> and <filename>meta-yocto</filename> in the
2046 <filename>poky</filename> Git repository.
2047 Add the path to your <filename>meta-kernel-dev</filename> location.
2048 Be sure to substitute your user information in the statement.
2049 Here is an example:
2050 <literallayout class='monospaced'>
2051 BBLAYERS = " \
2052 /home/scottrif/poky/meta \
2053 /home/scottrif/poky/meta-yocto \
2054 /home/scottrif/poky/meta-yocto-bsp \
2055 /home/scottrif/poky/poky-extras/meta-kernel-dev \
2056 "
2057 </literallayout></para></listitem>
2058 <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the
2059 <filename>linux-yocto_3.4.bbappend</filename> file located in the
2060 <filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename>
2061 directory, you need to identify the location of the
2062 local source code, which in this example is the bare clone named
2063 <filename>linux-yocto-3.4.git</filename>.
2064 To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your
2065 local <filename>linux-yocto-3.4.git</filename> Git repository by adding the
2066 following statement.
2067 Also, be sure the <filename>SRC_URI</filename> variable is pointing to
2068 your kernel source files by removing the comment.
2069 Finally, be sure to substitute your user information in the statement:
2070 <literallayout class='monospaced'>
2071 KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git"
2072 SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
2073 </literallayout></para></listitem>
2074 </itemizedlist>
2075 </para>
2076
2077 <note>
2078 <para>Before attempting to build the modified kernel, there is one more set of changes you
2079 need to make in the <filename>meta-kernel-dev</filename> layer.
2080 Because all the kernel <filename>.bbappend</filename> files are parsed during the
2081 build process regardless of whether you are using them or not, you should either
2082 comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all
2083 unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files
2084 except the one your are using for the build
2085 (i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para>
2086 <para>If you do not make one of these two adjustments, your machine will be compatible
2087 with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer.
2088 When your machine is comapatible with all the kernel recipes, the build attempts
2089 to build all kernels in the layer.
2090 You could end up with build errors blocking your work.</para>
2091 </note>
2092 </section>
2093
2094 <section id='building-and-booting-the-modified-qemu-kernel-image'>
2095 <title>Building and Booting the Modified QEMU Kernel Image</title>
2096
2097 <para>
2098 Next, you need to build the modified image.
2099 Do the following:
2100 <orderedlist>
2101 <listitem><para>Your environment should be set up since you previously sourced
2102 the <filename>&OE_INIT_FILE;</filename> script.
2103 If it isn't, source the script again from <filename>poky</filename>.
2104 <literallayout class='monospaced'>
2105 $ cd ~/poky
2106 $ source &OE_INIT_FILE;
2107 </literallayout>
2108 </para></listitem>
2109 <listitem><para>Be sure old images are cleaned out by running the
2110 <filename>cleanall</filename> BitBake task as follows from your build directory:
2111 <literallayout class='monospaced'>
2112 $ bitbake -c cleanall linux-yocto
2113 </literallayout></para>
2114 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
2115 directory insided the build directory.
2116 Always use the BitBake <filename>cleanall</filename> task to clear
2117 out previous builds.</note></para></listitem>
2118 <listitem><para>Next, build the kernel image using this command:
2119 <literallayout class='monospaced'>
2120 $ bitbake -k core-image-minimal
2121 </literallayout></para></listitem>
2122 <listitem><para>Finally, boot the modified image in the QEMU emulator
2123 using this command:
2124 <literallayout class='monospaced'>
2125 $ runqemu qemux86
2126 </literallayout></para></listitem>
2127 </orderedlist>
2128 </para>
2129
2130 <para>
2131 Log into the machine using <filename>root</filename> with no password and then
2132 use the following shell command to scroll through the console's boot output.
2133 <literallayout class='monospaced'>
2134 # dmesg | less
2135 </literallayout>
2136 </para>
2137
2138 <para>
2139 You should see the results of your <filename>printk</filename> statements
2140 as part of the output.
2141 </para>
2142 </section>
2143 </section>
2144
2145
2146
2147
2148
2149
2150
2151
1593 <section id="usingpoky-changes-updatingimages"> 2152 <section id="usingpoky-changes-updatingimages">
1594 <title>Updating Existing Images</title> 2153 <title>Updating Existing Images</title>
1595 2154
diff --git a/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml b/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml
new file mode 100644
index 0000000000..6ea77d030c
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-kernel-appendix-orig.xml
@@ -0,0 +1,553 @@
1<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
2"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
3[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
4
5<appendix id='dev-manual-kernel-appendix'>
6
7<title>Kernel Modification Example</title>
8
9 <para>
10 Kernel modification involves changing or adding configurations to an existing kernel,
11 changing or adding recipes to the kernel that are needed to support specific hardware features,
12 or even altering the source code itself.
13 This appendix presents simple examples that modify the kernel source code,
14 change the kernel configuration, and add a kernel source recipe.
15 <note>
16 You can use the <filename>yocto-kernel</filename> script
17 found in the <link linkend='source-directory'>Source Directory</link>
18 under <filename>scripts</filename> to manage kernel patches and configuration.
19 See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
20 section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
21 more information.</note>
22 </para>
23
24 <section id='modifying-the-kernel-source-code'>
25 <title>Modifying the Kernel Source Code</title>
26
27 <para>
28 This example adds some simple QEMU emulator console output at boot time by
29 adding <filename>printk</filename> statements to the kernel's
30 <filename>calibrate.c</filename> source code file.
31 Booting the modified image causes the added messages to appear on the emulator's
32 console.
33 </para>
34
35 <section id='understanding-the-files-you-need'>
36 <title>Understanding the Files You Need</title>
37
38 <para>
39 Before you modify the kernel, you need to know what Git repositories and file
40 structures you need.
41 Briefly, you need the following:
42 <itemizedlist>
43 <listitem><para>A local
44 <link linkend='source-directory'>Source Directory</link> for the
45 poky Git repository</para></listitem>
46 <listitem><para>Local copies of the
47 <link linkend='poky-extras-repo'><filename>poky-extras</filename></link>
48 Git repository placed within the Source Directory.</para></listitem>
49 <listitem><para>A bare clone of the
50 <link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git
51 repository to which you want to push your modifications.
52 </para></listitem>
53 <listitem><para>A copy of that bare clone in which you make your source
54 modifications</para></listitem>
55 </itemizedlist>
56 </para>
57
58 <para>
59 The following figure summarizes these four areas.
60 Within each rectangular that represents a data structure, a
61 host development directory pathname appears at the
62 lower left-hand corner of the box.
63 These pathnames are the locations used in this example.
64 The figure also provides key statements and commands used during the kernel
65 modification process:
66 </para>
67
68 <para>
69 <imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in"
70 align="center" scale="100" />
71 </para>
72
73 <para>
74 Here is a brief description of the four areas:
75 <itemizedlist>
76 <listitem><para><emphasis>Local Source Directory:</emphasis>
77 This area contains all the metadata that supports building images
78 using the OpenEmbedded build system.
79 In this example, the
80 <link linkend='source-directory'>Source Directory</link> also
81 contains the
82 <link linkend='build-directory'>Build Directory</link>,
83 which contains the configuration directory
84 that lets you control the build.
85 Also in this example, the Source Directory contains local copies of the
86 <filename>poky-extras</filename> Git repository.</para>
87 <para>See the bulleted item
88 "<link linkend='local-yp-release'>Yocto Project Release</link>"
89 for information on how to get these files on your local system.</para></listitem>
90 <listitem><para><emphasis>Local copies of the&nbsp;<filename>poky-extras</filename>&nbsp;Git Repository:</emphasis>
91 This area contains the <filename>meta-kernel-dev</filename> layer,
92 which is where you make changes that append the kernel build recipes.
93 You edit <filename>.bbappend</filename> files to locate your
94 local kernel source files and to identify the kernel being built.
95 This Git repository is a gathering place for extensions to the Yocto Project
96 (or really any) kernel recipes that faciliate the creation and development
97 of kernel features, BSPs or configurations.</para>
98 <para>See the bulleted item
99 "<link linkend='poky-extras-repo'>The
100 <filename>poky-extras</filename> Git Repository</link>"
101 for information on how to get these files.</para></listitem>
102 <listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis>
103 This bare Git repository tracks the upstream Git repository of the Linux
104 Yocto kernel source code you are changing.
105 When you modify the kernel you must work through a bare clone.
106 All source code changes you make to the kernel must be committed and
107 pushed to the bare clone using Git commands.
108 As mentioned, the <filename>.bbappend</filename> file in the
109 <filename>poky-extras</filename> repository points to the bare clone
110 so that the build process can locate the locally changed source files.</para>
111 <para>See the bulleted item
112 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
113 for information on how to set up the bare clone.
114 </para></listitem>
115 <listitem><para><emphasis>Copy of the Yocto Project Kernel Bare Clone:</emphasis>
116 This Git repository contains the actual source files that you modify.
117 Any changes you make to files in this location need to ultimately be pushed
118 to the bare clone using the <filename>git push</filename> command.</para>
119 <para>See the bulleted item
120 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
121 for information on how to set up the bare clone.
122 <note>Typically, Git workflows follow a scheme where changes made to a local area
123 are pulled into a Git repository.
124 However, because the <filename>git pull</filename> command does not work
125 with bare clones, this workflow pushes changes to the
126 repository even though you could use other more complicated methods to
127 get changes into the bare clone.</note>
128 </para></listitem>
129 </itemizedlist>
130 </para>
131 </section>
132
133 <section id='setting-up-the-local-yocto-project-files-git-repository'>
134 <title>Setting Up the Local Source Directory</title>
135
136 <para>
137 You can set up the
138 <link linkend='source-directory'>Source Directory</link>
139 through tarball extraction or by
140 cloning the <filename>poky</filename> Git repository.
141 This example uses <filename>poky</filename> as the root directory of the
142 local Source Directory.
143 See the bulleted item
144 "<link linkend='local-yp-release'>Yocto Project Release</link>"
145 for information on how to get these files.
146 </para>
147
148 <para>
149 Once you have Source Directory set up,
150 you have many development branches from which you can work.
151 From inside the local repository you can see the branch names and the tag names used
152 in the upstream Git repository by using either of the following commands:
153 <literallayout class='monospaced'>
154 $ cd poky
155 $ git branch -a
156 $ git tag -l
157 </literallayout>
158 This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
159 which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
160 The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
161 branch:
162 <literallayout class='monospaced'>
163 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
164 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
165 Switched to a new branch '&DISTRO_NAME;'
166 </literallayout>
167 </para>
168 </section>
169
170 <section id='setting-up-the-poky-extras-git-repository'>
171 <title>Setting Up the Local poky-extras Git Repository</title>
172
173 <para>
174 This example creates a local copy of the <filename>poky-extras</filename> Git
175 repository inside the <filename>poky</filename> Source Directory.
176 See the bulleted item "<link linkend='poky-extras-repo'>The
177 <filename>poky-extras</filename> Git Repository</link>"
178 for information on how to set up a local copy of the
179 <filename>poky-extras</filename> repository.
180 </para>
181
182 <para>
183 Because this example uses the Yocto Project &DISTRO; Release code
184 named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename>
185 branch in the repository, you need to be sure you are using that
186 branch for <filename>poky-extras</filename>.
187 The following commands create and checkout the local
188 branch you are using for the <filename>&DISTRO_NAME;</filename>
189 branch:
190 <literallayout class='monospaced'>
191 $ cd ~/poky/poky-extras
192 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
193 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
194 Switched to a new branch '&DISTRO_NAME;'
195 </literallayout>
196 </para>
197 </section>
198
199 <section id='setting-up-the-bare-clone-and-its-copy'>
200 <title>Setting Up the Bare Clone and its Copy</title>
201
202 <para>
203 This example modifies the <filename>linux-yocto-3.4</filename> kernel.
204 Thus, you need to create a bare clone of that kernel and then make a copy of the
205 bare clone.
206 See the bulleted item
207 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
208 for information on how to do that.
209 </para>
210
211 <para>
212 The bare clone exists for the kernel build tools and simply as the receiving end
213 of <filename>git push</filename>
214 commands after you make edits and commits inside the copy of the clone.
215 The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have
216 a local branch created and checked out for your work.
217 This example uses <filename>common-pc-base</filename> as the local branch.
218 The following commands create and checkout the branch:
219 <literallayout class='monospaced'>
220 $ cd ~/my-linux-yocto-3.4-work
221 $ git checkout -b standard-common-pc-base origin/standard/common-pc/base
222 Branch standard-common-pc-base set up to track remote branch
223 standard/common-pc/base from origin.
224 Switched to a new branch 'standard-common-pc-base'
225 </literallayout>
226 </para>
227 </section>
228
229 <section id='building-and-booting-the-default-qemu-kernel-image'>
230 <title>Building and Booting the Default QEMU Kernel Image</title>
231
232 <para>
233 Before we make changes to the kernel source files, this example first builds the
234 default image and then boots it inside the QEMU emulator.
235 <note>
236 Because a full build can take hours, you should check two variables in the
237 <filename>build</filename> directory that is created after you source the
238 <filename>&OE_INIT_FILE;</filename> script.
239 You can find these variables
240 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
241 in the <filename>build/conf</filename> directory in the
242 <filename>local.conf</filename> configuration file.
243 By default, these variables are commented out.
244 If your host development system supports multi-core and multi-thread capabilities,
245 you can uncomment these statements and set the variables to significantly shorten
246 the full build time.
247 As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and
248 <filename>PARALLEL_MAKE</filename> to twice the number
249 of cores your machine supports.
250 </note>
251 The following two commands <filename>source</filename> the build environment setup script
252 and build the default <filename>qemux86</filename> image.
253 If necessary, the script creates the build directory:
254 <literallayout class='monospaced'>
255 $ cd ~/poky
256 $ source &OE_INIT_FILE;
257 You had no conf/local.conf file. This configuration file has therefore been
258 created for you with some default values. You may wish to edit it to use a
259 different MACHINE (target hardware) or enable parallel build options to take
260 advantage of multiple cores for example. See the file for more information as
261 common configuration options are commented.
262
263 The Yocto Project has extensive documentation about OE including a reference manual
264 which can be found at:
265 http://yoctoproject.org/documentation
266
267 For more information about OpenEmbedded see their website:
268 http://www.openembedded.org/
269
270 You had no conf/bblayers.conf file. The configuration file has been created for
271 you with some default values. To add additional metadata layers into your
272 configuration please add entries to this file.
273
274 The Yocto Project has extensive documentation about OE including a reference manual
275 which can be found at:
276 http://yoctoproject.org/documentation
277
278 For more information about OpenEmbedded see their website:
279 http://www.openembedded.org/
280
281
282
283 ### Shell environment set up for builds. ###
284
285 You can now run 'bitbake &lt;target&gt;>'
286
287 Common targets are:
288 core-image-minimal
289 core-image-sato
290 meta-toolchain
291 meta-toolchain-sdk
292 adt-installer
293 meta-ide-support
294
295 You can also run generated qemu images with a command like 'runqemu qemux86'
296 </literallayout>
297 </para>
298
299 <para>
300 The following <filename>bitbake</filename> command starts the build:
301 <literallayout class='monospaced'>
302 $ bitbake -k core-image-minimal
303 </literallayout>
304 <note>Be sure to check the settings in the <filename>local.conf</filename>
305 before starting the build.</note>
306 </para>
307
308 <para>
309 After the build completes, you can start the QEMU emulator using the resulting image
310 <filename>qemux86</filename> as follows:
311 <literallayout class='monospaced'>
312 $ runqemu qemux86
313 </literallayout>
314 </para>
315
316 <para>
317 As the image boots in the emulator, console message and status output appears
318 across the terminal window.
319 Because the output scrolls by quickly, it is difficult to read.
320 To examine the output, you log into the system using the
321 login <filename>root</filename> with no password.
322 Once you are logged in, issue the following command to scroll through the
323 console output:
324 <literallayout class='monospaced'>
325 # dmesg | less
326 </literallayout>
327 </para>
328
329 <para>
330 Take note of the output as you will want to look for your inserted print command output
331 later in the example.
332 </para>
333 </section>
334
335 <section id='changing-the-source-code-and-pushing-it-to-the-bare-clone'>
336 <title>Changing the Source Code and Pushing it to the Bare Clone</title>
337
338 <para>
339 The file you change in this example is named <filename>calibrate.c</filename>
340 and is located in the <filename>my-linux-yocto-3.4-work</filename> Git repository
341 (the copy of the bare clone) in <filename>init</filename>.
342 This example simply inserts several <filename>printk</filename> statements
343 at the beginning of the <filename>calibrate_delay</filename> function.
344 </para>
345
346 <para>
347 Here is the unaltered code at the start of this function:
348 <literallayout class='monospaced'>
349 void __cpuinit calibrate_delay(void)
350 {
351 unsigned long lpj;
352 static bool printed;
353 int this_cpu = smp_processor_id();
354
355 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
356 .
357 .
358 .
359 </literallayout>
360 </para>
361
362 <para>
363 Here is the altered code showing five new <filename>printk</filename> statements
364 near the top of the function:
365 <literallayout class='monospaced'>
366 void __cpuinit calibrate_delay(void)
367 {
368 unsigned long lpj;
369 static bool printed;
370 int this_cpu = smp_processor_id();
371
372 printk("*************************************\n");
373 printk("* *\n");
374 printk("* HELLO YOCTO KERNEL *\n");
375 printk("* *\n");
376 printk("*************************************\n");
377
378 if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
379 .
380 .
381 .
382 </literallayout>
383 </para>
384
385 <para>
386 After making and saving your changes, you need to stage them for the push.
387 The following Git commands are one method of staging and committing your changes:
388 <literallayout class='monospaced'>
389 $ git add calibrate.c
390 $ git commit --signoff
391 </literallayout>
392 </para>
393
394 <para>
395 Once the source code has been modified, you need to use Git to push the changes to
396 the bare clone.
397 If you do not push the changes, then the OpenEmbedded build system will not pick
398 up the changed source files.
399 </para>
400
401 <para>
402 The following command pushes the changes to the bare clone:
403 <literallayout class='monospaced'>
404 $ git push origin standard-common-pc-base:standard/default/common-pc/base
405 </literallayout>
406 </para>
407 </section>
408
409 <section id='changing-build-parameters-for-your-build'>
410 <title>Changing Build Parameters for Your Build</title>
411
412 <para>
413 At this point, the source has been changed and pushed.
414 The example now defines some variables used by the OpenEmbedded build system
415 to locate your kernel source.
416 You essentially need to identify where to find the kernel recipe and the changed source code.
417 You also need to be sure some basic configurations are in place that identify the
418 type of machine you are building and to help speed up the build should your host support
419 multiple-core and thread capabilities.
420 </para>
421
422 <para>
423 Do the following to make sure the build parameters are set up for the example.
424 Once you set up these build parameters, they do not have to change unless you
425 change the target architecture of the machine you are building or you move
426 the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository:
427 <itemizedlist>
428 <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
429 <filename>local.conf</filename> file in the build directory defines the build's
430 target architecture.
431 By default, <filename>MACHINE</filename> is set to
432 <filename>qemux86</filename>, which specifies a 32-bit
433 <trademark class='registered'>Intel</trademark> Architecture
434 target machine suitable for the QEMU emulator.
435 In this example, <filename>MACHINE</filename> is correctly configured.
436 </para></listitem>
437 <listitem><para><emphasis>Optimize Build Time:</emphasis> Also in the
438 <filename>local.conf</filename> file are two variables that can speed your
439 build time if your host supports multi-core and multi-thread capabilities:
440 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>.
441 If the host system has multiple cores then you can optimize build time
442 by setting both these variables to twice the number of
443 cores.</para></listitem>
444 <listitem><para><emphasis>Identify Your <filename>meta-kernel-dev</filename>
445 Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
446 <filename>bblayers.conf</filename> file found in the
447 <filename>poky/build/conf</filename> directory needs to have the path to your local
448 <filename>meta-kernel-dev</filename> layer.
449 By default, the <filename>BBLAYERS</filename> variable contains paths to
450 <filename>meta</filename> and <filename>meta-yocto</filename> in the
451 <filename>poky</filename> Git repository.
452 Add the path to your <filename>meta-kernel-dev</filename> location.
453 Be sure to substitute your user information in the statement.
454 Here is an example:
455 <literallayout class='monospaced'>
456 BBLAYERS = " \
457 /home/scottrif/poky/meta \
458 /home/scottrif/poky/meta-yocto \
459 /home/scottrif/poky/meta-yocto-bsp \
460 /home/scottrif/poky/poky-extras/meta-kernel-dev \
461 "
462 </literallayout></para></listitem>
463 <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the
464 <filename>linux-yocto_3.4.bbappend</filename> file located in the
465 <filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename>
466 directory, you need to identify the location of the
467 local source code, which in this example is the bare clone named
468 <filename>linux-yocto-3.4.git</filename>.
469 To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your
470 local <filename>linux-yocto-3.4.git</filename> Git repository by adding the
471 following statement.
472 Also, be sure the <filename>SRC_URI</filename> variable is pointing to
473 your kernel source files by removing the comment.
474 Finally, be sure to substitute your user information in the statement:
475 <literallayout class='monospaced'>
476 KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git"
477 SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
478 </literallayout></para></listitem>
479 </itemizedlist>
480 </para>
481
482 <note>
483 <para>Before attempting to build the modified kernel, there is one more set of changes you
484 need to make in the <filename>meta-kernel-dev</filename> layer.
485 Because all the kernel <filename>.bbappend</filename> files are parsed during the
486 build process regardless of whether you are using them or not, you should either
487 comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all
488 unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files
489 except the one your are using for the build
490 (i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para>
491 <para>If you do not make one of these two adjustments, your machine will be compatible
492 with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer.
493 When your machine is comapatible with all the kernel recipes, the build attempts
494 to build all kernels in the layer.
495 You could end up with build errors blocking your work.</para>
496 </note>
497 </section>
498
499 <section id='building-and-booting-the-modified-qemu-kernel-image'>
500 <title>Building and Booting the Modified QEMU Kernel Image</title>
501
502 <para>
503 Next, you need to build the modified image.
504 Do the following:
505 <orderedlist>
506 <listitem><para>Your environment should be set up since you previously sourced
507 the <filename>&OE_INIT_FILE;</filename> script.
508 If it isn't, source the script again from <filename>poky</filename>.
509 <literallayout class='monospaced'>
510 $ cd ~/poky
511 $ source &OE_INIT_FILE;
512 </literallayout>
513 </para></listitem>
514 <listitem><para>Be sure old images are cleaned out by running the
515 <filename>cleanall</filename> BitBake task as follows from your build directory:
516 <literallayout class='monospaced'>
517 $ bitbake -c cleanall linux-yocto
518 </literallayout></para>
519 <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
520 directory insided the build directory.
521 Always use the BitBake <filename>cleanall</filename> task to clear
522 out previous builds.</note></para></listitem>
523 <listitem><para>Next, build the kernel image using this command:
524 <literallayout class='monospaced'>
525 $ bitbake -k core-image-minimal
526 </literallayout></para></listitem>
527 <listitem><para>Finally, boot the modified image in the QEMU emulator
528 using this command:
529 <literallayout class='monospaced'>
530 $ runqemu qemux86
531 </literallayout></para></listitem>
532 </orderedlist>
533 </para>
534
535 <para>
536 Log into the machine using <filename>root</filename> with no password and then
537 use the following shell command to scroll through the console's boot output.
538 <literallayout class='monospaced'>
539 # dmesg | less
540 </literallayout>
541 </para>
542
543 <para>
544 You should see the results of your <filename>printk</filename> statements
545 as part of the output.
546 </para>
547 </section>
548 </section>
549</appendix>
550
551<!--
552vim: expandtab tw=80 ts=4
553-->
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 844e0dc851..c96b2dda63 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -13,9 +13,6 @@
13 <listitem><para><emphasis>System Development:</emphasis> 13 <listitem><para><emphasis>System Development:</emphasis>
14 System Development covers Board Support Package (BSP) development and kernel 14 System Development covers Board Support Package (BSP) development and kernel
15 modification or configuration. 15 modification or configuration.
16 If you want to examine a specific example of the kernel modification and
17 configuration model,
18 see the "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" appendix.
19 For an example on how to create a BSP, see the 16 For an example on how to create a BSP, see the
20 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" 17 "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
21 section in the Yocto Project Board Support Package (BSP) Developer's Guide. 18 section in the Yocto Project Board Support Package (BSP) Developer's Guide.
@@ -234,9 +231,11 @@
234 kernel architecture and the steps to modify the kernel. 231 kernel architecture and the steps to modify the kernel.
235 For a complete discussion of the kernel, see the 232 For a complete discussion of the kernel, see the
236 <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>. 233 <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>.
237 You can reference the appendix 234 You can reference the
238 "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" 235 "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section
239 for a detailed example that changes the configuration of a kernel. 236 for an example that changes the source code of the kernel.
237 For information on how to configure the kernel, see the
238 "<link linkend='configuring-the-kernel'>Configuring the Kernel</link> section.
240 </para> 239 </para>
241 240
242 <section id='kernel-overview'> 241 <section id='kernel-overview'>
@@ -364,8 +363,8 @@
364 you work. 363 you work.
365 Once you make corrections, you must use Git to push the committed changes to the 364 Once you make corrections, you must use Git to push the committed changes to the
366 bare clone. 365 bare clone.
367 The example in <xref linkend='modifying-the-kernel-source-code'> 366<!-- The example in <xref linkend='modifying-the-kernel-source-code'>
368 Modifying the Kernel Source Code</xref> provides a detailed example. 367 Modifying the Kernel Source Code</xref> provides a detailed example. -->
369 </para> 368 </para>
370 369
371 <para> 370 <para>
@@ -394,7 +393,7 @@
394 branching strategy, see the 393 branching strategy, see the
395 <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>. 394 <ulink url='&YOCTO_DOCS_KERNEL_URL;'>Yocto Project Kernel Architecture and Use Manual</ulink>.
396 You can also reference the 395 You can also reference the
397 "<link linkend='modifying-the-kernel-source-code'>Modifying the Kernel Source Code</link>" 396 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
398 section for a detailed example that modifies the kernel. 397 section for a detailed example that modifies the kernel.
399 </para> 398 </para>
400 </section> 399 </section>
@@ -602,8 +601,8 @@
602 If your target architecture is similar to a supported architecture, you can 601 If your target architecture is similar to a supported architecture, you can
603 modify the kernel image before you build it. 602 modify the kernel image before you build it.
604 See the 603 See the
605 "<link linkend='dev-manual-kernel-appendix'>Kernel Modification Example</link>" 604 "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
606 appendix later in this manual for an example.</para></listitem> 605 section for an example.</para></listitem>
607 </itemizedlist></para> 606 </itemizedlist></para>
608 <para>For information on pre-built kernel image naming schemes for images 607 <para>For information on pre-built kernel image naming schemes for images
609 that can run on the QEMU emulator, see the 608 that can run on the QEMU emulator, see the
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
index a5856e0995..eff0dce1f0 100644
--- a/documentation/dev-manual/dev-manual.xml
+++ b/documentation/dev-manual/dev-manual.xml
@@ -80,8 +80,6 @@
80 80
81 <xi:include href="dev-manual-model.xml"/> 81 <xi:include href="dev-manual-model.xml"/>
82 82
83 <xi:include href="dev-manual-kernel-appendix.xml"/>
84
85</book> 83</book>
86<!-- 84<!--
87vim: expandtab tw=80 ts=4 85vim: expandtab tw=80 ts=4