summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml559
1 files changed, 559 insertions, 0 deletions
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
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-05-05 13:36:52 +0000