summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml322
1 files changed, 8 insertions, 314 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 48d86fac25..78c1f39e18 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -315,7 +315,7 @@
315 <literallayout class='monospaced'> 315 <literallayout class='monospaced'>
316 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:" 316 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
317 317
318 PRINC = "1" 318 PRINC := "${@int(PRINC) + 1}"
319 </literallayout> 319 </literallayout>
320 This example adds or overrides files in 320 This example adds or overrides files in
321 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> 321 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
@@ -1605,7 +1605,7 @@
1605 <title>Patching the Kernel</title> 1605 <title>Patching the Kernel</title>
1606 1606
1607 <para> 1607 <para>
1608 Kernel modification involves changing or adding configurations to an existing kernel, 1608 Patching the kernel 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, 1609 changing or adding recipes to the kernel that are needed to support specific hardware features,
1610 or even altering the source code itself. 1610 or even altering the source code itself.
1611 <note> 1611 <note>
@@ -1618,15 +1618,15 @@
1618 </para> 1618 </para>
1619 1619
1620 <para> 1620 <para>
1621 This example adds some simple QEMU emulator console output at boot time by 1621 This example creates a simple patch by adding some QEMU emulator console
1622 adding <filename>printk</filename> statements to the kernel's 1622 output at boot time through <filename>printk</filename> statements in the kernel's
1623 <filename>calibrate.c</filename> source code file. 1623 <filename>calibrate.c</filename> source code file.
1624 Booting the modified image causes the added messages to appear on the emulator's 1624 Applying the patch and booting the modified image causes the added
1625 console. 1625 messages to appear on the emulator's console.
1626 </para> 1626 </para>
1627 1627
1628 <section id='finding-the-kernel-source-files'> 1628 <section id='creating-the-patch'>
1629 <title>Finding the Kernel Source Files</title> 1629 <title>Creating the Patch</title>
1630 1630
1631 <para> 1631 <para>
1632 Describe how to find the source files in the build area. 1632 Describe how to find the source files in the build area.
@@ -1635,305 +1635,6 @@
1635 </para> 1635 </para>
1636 </section> 1636 </section>
1637 1637
1638 <section id='understanding-the-files-you-need'>
1639 <title>Understanding the Files You Need</title>
1640
1641 <para>
1642 Before you modify the kernel, you need to know what Git repositories and file
1643 structures you need.
1644 Briefly, you need the following:
1645 <itemizedlist>
1646 <listitem><para>A local
1647 <link linkend='source-directory'>Source Directory</link> for the
1648 poky Git repository</para></listitem>
1649 <listitem><para>Local copies of the
1650 <link linkend='poky-extras-repo'><filename>poky-extras</filename></link>
1651 Git repository placed within the Source Directory.</para></listitem>
1652 <listitem><para>A bare clone of the
1653 <link linkend='local-kernel-files'>Yocto Project Kernel</link> upstream Git
1654 repository to which you want to push your modifications.
1655 </para></listitem>
1656 <listitem><para>A copy of that bare clone in which you make your source
1657 modifications</para></listitem>
1658 </itemizedlist>
1659 </para>
1660
1661 <para>
1662 The following figure summarizes these four areas.
1663 Within each rectangular that represents a data structure, a
1664 host development directory pathname appears at the
1665 lower left-hand corner of the box.
1666 These pathnames are the locations used in this example.
1667 The figure also provides key statements and commands used during the kernel
1668 modification process:
1669 </para>
1670
1671 <para>
1672 <imagedata fileref="figures/kernel-example-repos-generic.png" width="7in" depth="5in"
1673 align="center" scale="100" />
1674 </para>
1675
1676 <para>
1677 Here is a brief description of the four areas:
1678 <itemizedlist>
1679 <listitem><para><emphasis>Local Source Directory:</emphasis>
1680 This area contains all the metadata that supports building images
1681 using the OpenEmbedded build system.
1682 In this example, the
1683 <link linkend='source-directory'>Source Directory</link> also
1684 contains the
1685 <link linkend='build-directory'>Build Directory</link>,
1686 which contains the configuration directory
1687 that lets you control the build.
1688 Also in this example, the Source Directory contains local copies of the
1689 <filename>poky-extras</filename> Git repository.</para>
1690 <para>See the bulleted item
1691 "<link linkend='local-yp-release'>Yocto Project Release</link>"
1692 for information on how to get these files on your local system.</para></listitem>
1693 <listitem><para><emphasis>Local copies of the&nbsp;<filename>poky-extras</filename>&nbsp;Git Repository:</emphasis>
1694 This area contains the <filename>meta-kernel-dev</filename> layer,
1695 which is where you make changes that append the kernel build recipes.
1696 You edit <filename>.bbappend</filename> files to locate your
1697 local kernel source files and to identify the kernel being built.
1698 This Git repository is a gathering place for extensions to the Yocto Project
1699 (or really any) kernel recipes that faciliate the creation and development
1700 of kernel features, BSPs or configurations.</para>
1701 <para>See the bulleted item
1702 "<link linkend='poky-extras-repo'>The
1703 <filename>poky-extras</filename> Git Repository</link>"
1704 for information on how to get these files.</para></listitem>
1705 <listitem><para><emphasis>Bare Clone of the Yocto Project kernel:</emphasis>
1706 This bare Git repository tracks the upstream Git repository of the Linux
1707 Yocto kernel source code you are changing.
1708 When you modify the kernel you must work through a bare clone.
1709 All source code changes you make to the kernel must be committed and
1710 pushed to the bare clone using Git commands.
1711 As mentioned, the <filename>.bbappend</filename> file in the
1712 <filename>poky-extras</filename> repository points to the bare clone
1713 so that the build process can locate the locally changed source files.</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 </para></listitem>
1718 <listitem><para><emphasis>Copy of the Yocto Project Kernel Bare Clone:</emphasis>
1719 This Git repository contains the actual source files that you modify.
1720 Any changes you make to files in this location need to ultimately be pushed
1721 to the bare clone using the <filename>git push</filename> command.</para>
1722 <para>See the bulleted item
1723 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
1724 for information on how to set up the bare clone.
1725 <note>Typically, Git workflows follow a scheme where changes made to a local area
1726 are pulled into a Git repository.
1727 However, because the <filename>git pull</filename> command does not work
1728 with bare clones, this workflow pushes changes to the
1729 repository even though you could use other more complicated methods to
1730 get changes into the bare clone.</note>
1731 </para></listitem>
1732 </itemizedlist>
1733 </para>
1734 </section>
1735
1736 <section id='setting-up-the-local-yocto-project-files-git-repository'>
1737 <title>Setting Up the Local Source Directory</title>
1738
1739 <para>
1740 You can set up the
1741 <link linkend='source-directory'>Source Directory</link>
1742 through tarball extraction or by
1743 cloning the <filename>poky</filename> Git repository.
1744 This example uses <filename>poky</filename> as the root directory of the
1745 local Source Directory.
1746 See the bulleted item
1747 "<link linkend='local-yp-release'>Yocto Project Release</link>"
1748 for information on how to get these files.
1749 </para>
1750
1751 <para>
1752 Once you have Source Directory set up,
1753 you have many development branches from which you can work.
1754 From inside the local repository you can see the branch names and the tag names used
1755 in the upstream Git repository by using either of the following commands:
1756 <literallayout class='monospaced'>
1757 $ cd poky
1758 $ git branch -a
1759 $ git tag -l
1760 </literallayout>
1761 This example uses the Yocto Project &DISTRO; Release code named "&DISTRO_NAME;",
1762 which maps to the <filename>&DISTRO_NAME;</filename> branch in the repository.
1763 The following commands create and checkout the local <filename>&DISTRO_NAME;</filename>
1764 branch:
1765 <literallayout class='monospaced'>
1766 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
1767 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
1768 Switched to a new branch '&DISTRO_NAME;'
1769 </literallayout>
1770 </para>
1771 </section>
1772
1773 <section id='setting-up-the-poky-extras-git-repository'>
1774 <title>Setting Up the Local poky-extras Git Repository</title>
1775
1776 <para>
1777 This example creates a local copy of the <filename>poky-extras</filename> Git
1778 repository inside the <filename>poky</filename> Source Directory.
1779 See the bulleted item "<link linkend='poky-extras-repo'>The
1780 <filename>poky-extras</filename> Git Repository</link>"
1781 for information on how to set up a local copy of the
1782 <filename>poky-extras</filename> repository.
1783 </para>
1784
1785 <para>
1786 Because this example uses the Yocto Project &DISTRO; Release code
1787 named "&DISTRO_NAME;", which maps to the <filename>&DISTRO_NAME;</filename>
1788 branch in the repository, you need to be sure you are using that
1789 branch for <filename>poky-extras</filename>.
1790 The following commands create and checkout the local
1791 branch you are using for the <filename>&DISTRO_NAME;</filename>
1792 branch:
1793 <literallayout class='monospaced'>
1794 $ cd ~/poky/poky-extras
1795 $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
1796 Branch &DISTRO_NAME; set up to track remote branch &DISTRO_NAME; from origin.
1797 Switched to a new branch '&DISTRO_NAME;'
1798 </literallayout>
1799 </para>
1800 </section>
1801
1802 <section id='setting-up-the-bare-clone-and-its-copy'>
1803 <title>Setting Up the Bare Clone and its Copy</title>
1804
1805 <para>
1806 This example modifies the <filename>linux-yocto-3.4</filename> kernel.
1807 Thus, you need to create a bare clone of that kernel and then make a copy of the
1808 bare clone.
1809 See the bulleted item
1810 "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
1811 for information on how to do that.
1812 </para>
1813
1814 <para>
1815 The bare clone exists for the kernel build tools and simply as the receiving end
1816 of <filename>git push</filename>
1817 commands after you make edits and commits inside the copy of the clone.
1818 The copy (<filename>my-linux-yocto-3.4-work</filename> in this example) has to have
1819 a local branch created and checked out for your work.
1820 This example uses <filename>common-pc-base</filename> as the local branch.
1821 The following commands create and checkout the branch:
1822 <literallayout class='monospaced'>
1823 $ cd ~/my-linux-yocto-3.4-work
1824 $ git checkout -b standard-common-pc-base origin/standard/common-pc/base
1825 Branch standard-common-pc-base set up to track remote branch
1826 standard/common-pc/base from origin.
1827 Switched to a new branch 'standard-common-pc-base'
1828 </literallayout>
1829 </para>
1830 </section>
1831
1832 <section id='building-and-booting-the-default-qemu-kernel-image'>
1833 <title>Building and Booting the Default QEMU Kernel Image</title>
1834
1835 <para>
1836 Before we make changes to the kernel source files, this example first builds the
1837 default image and then boots it inside the QEMU emulator.
1838 <note>
1839 Because a full build can take hours, you should check two variables in the
1840 <filename>build</filename> directory that is created after you source the
1841 <filename>&OE_INIT_FILE;</filename> script.
1842 You can find these variables
1843 <filename>BB_NUMBER_THREADS</filename> and <filename>PARALLEL_MAKE</filename>
1844 in the <filename>build/conf</filename> directory in the
1845 <filename>local.conf</filename> configuration file.
1846 By default, these variables are commented out.
1847 If your host development system supports multi-core and multi-thread capabilities,
1848 you can uncomment these statements and set the variables to significantly shorten
1849 the full build time.
1850 As a guideline, set both <filename>BB_NUMBER_THREADS</filename> and
1851 <filename>PARALLEL_MAKE</filename> to twice the number
1852 of cores your machine supports.
1853 </note>
1854 The following two commands <filename>source</filename> the build environment setup script
1855 and build the default <filename>qemux86</filename> image.
1856 If necessary, the script creates the build directory:
1857 <literallayout class='monospaced'>
1858 $ cd ~/poky
1859 $ source &OE_INIT_FILE;
1860 You had no conf/local.conf file. This configuration file has therefore been
1861 created for you with some default values. You may wish to edit it to use a
1862 different MACHINE (target hardware) or enable parallel build options to take
1863 advantage of multiple cores for example. See the file for more information as
1864 common configuration options are commented.
1865
1866 The Yocto Project has extensive documentation about OE including a reference manual
1867 which can be found at:
1868 http://yoctoproject.org/documentation
1869
1870 For more information about OpenEmbedded see their website:
1871 http://www.openembedded.org/
1872
1873 You had no conf/bblayers.conf file. The configuration file has been created for
1874 you with some default values. To add additional metadata layers into your
1875 configuration please add entries to this file.
1876
1877 The Yocto Project has extensive documentation about OE including a reference manual
1878 which can be found at:
1879 http://yoctoproject.org/documentation
1880
1881 For more information about OpenEmbedded see their website:
1882 http://www.openembedded.org/
1883
1884
1885
1886 ### Shell environment set up for builds. ###
1887
1888 You can now run 'bitbake &lt;target&gt;>'
1889
1890 Common targets are:
1891 core-image-minimal
1892 core-image-sato
1893 meta-toolchain
1894 meta-toolchain-sdk
1895 adt-installer
1896 meta-ide-support
1897
1898 You can also run generated qemu images with a command like 'runqemu qemux86'
1899 </literallayout>
1900 </para>
1901
1902 <para>
1903 The following <filename>bitbake</filename> command starts the build:
1904 <literallayout class='monospaced'>
1905 $ bitbake -k core-image-minimal
1906 </literallayout>
1907 <note>Be sure to check the settings in the <filename>local.conf</filename>
1908 before starting the build.</note>
1909 </para>
1910
1911 <para>
1912 After the build completes, you can start the QEMU emulator using the resulting image
1913 <filename>qemux86</filename> as follows:
1914 <literallayout class='monospaced'>
1915 $ runqemu qemux86
1916 </literallayout>
1917 </para>
1918
1919 <para>
1920 As the image boots in the emulator, console message and status output appears
1921 across the terminal window.
1922 Because the output scrolls by quickly, it is difficult to read.
1923 To examine the output, you log into the system using the
1924 login <filename>root</filename> with no password.
1925 Once you are logged in, issue the following command to scroll through the
1926 console output:
1927 <literallayout class='monospaced'>
1928 # dmesg | less
1929 </literallayout>
1930 </para>
1931
1932 <para>
1933 Take note of the output as you will want to look for your inserted print command output
1934 later in the example.
1935 </para>
1936 </section>
1937 1638
1938 <section id='changing-the-source-code-and-pushing-it-to-the-bare-clone'> 1639 <section id='changing-the-source-code-and-pushing-it-to-the-bare-clone'>
1939 <title>Changing the Source Code and Pushing it to the Bare Clone</title> 1640 <title>Changing the Source Code and Pushing it to the Bare Clone</title>
@@ -2150,13 +1851,6 @@
2150 </section> 1851 </section>
2151 </section> 1852 </section>
2152 1853
2153
2154
2155
2156
2157
2158
2159
2160 <section id="usingpoky-changes-updatingimages"> 1854 <section id="usingpoky-changes-updatingimages">
2161 <title>Updating Existing Images</title> 1855 <title>Updating Existing Images</title>
2162 1856