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.xml197
-rw-r--r--documentation/dev-manual/dev-manual-model.xml9
2 files changed, 118 insertions, 88 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 78c1f39e18..0215fcf21a 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1625,30 +1625,77 @@
1625 messages to appear on the emulator's console. 1625 messages to appear on the emulator's console.
1626 </para> 1626 </para>
1627 1627
1628 <section id='creating-the-patch'> 1628 <section id='create-a-layer-for-your-changes'>
1629 <title>Creating the Patch</title> 1629 <title>Create a Layer for your Changes</title>
1630 1630
1631 <para> 1631 <para>
1632 Describe how to find the source files in the build area. 1632 The first step is to isolate your changes into a layer:
1633 We are not assuming they are using their own kernel tree. 1633 <literallayout class='monospaced'>
1634 $cd ~/poky
1635 $mkdir meta-mylayer
1636 </literallayout>
1637 Creating a directory that follows the Yocto Project layer naming
1638 conventions sets up the area for your layer.
1639 The layer is where you place your configuration files, append
1640 files, and patch files.
1641 To learn more about creating a layer and filling it with the
1642 files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
1643 and Creating Layers</link>" section.
1644 </para>
1645 </section>
1646
1647 <section id='finding-the-kernel-source-code'>
1648 <title>Finding the Kernel Source Code</title>
1649
1650 <para>
1651 Each time you build a kernel image, the kernel source code is fetched
1652 and unpacked into a temporary location in the <link linkend='build-directory'>Build Directory</link>.
1653 See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
1654 section for a description of where the OpenEmbedded build system places
1655 kernel source files during a build.
1656 Following is where machine-specific source code is temporarily stored
1657 during the build:
1658 <literallayout class='monospaced'>
1659 ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}-${PV}-${PR}
1660 </literallayout>
1661 Assuming a recent build for the <filename>qemux86</filename> machine
1662 based on the Linux 3.4 kernel, a
1663 <link linkend='source-directory'>Source Directory</link> named <filename>poky</filename>, and
1664 the existence of a default <filename>build</filename> directory, the directory that
1665 holds the temporary source code would be here:
1666 <literallayout class='monospaced'>
1667 ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+5bdc...85f-r4.3
1668 </literallayout>
1669 Within the <filename>linux</filename> directory, you find the source directories.
1670 </para>
1634 1671
1672 <para>
1673 For this example, we are going to patch the <filename>init/calibrate.c</filename> file
1674 and add some simple console <filename>printk</filename> statements that we can
1675 see when we boot the image using QEMU.
1635 </para> 1676 </para>
1636 </section> 1677 </section>
1637 1678
1679 <section id='creating-the-patch'>
1680 <title>Creating the Patch</title>
1638 1681
1639 <section id='changing-the-source-code-and-pushing-it-to-the-bare-clone'> 1682 <para>
1640 <title>Changing the Source Code and Pushing it to the Bare Clone</title> 1683 Two methods exist by which you can create the patch: Git workflow and Quilt workflow.
1684 For kernel patches, the Git workflow is more appropriate.
1685 This section assumes the Git workflow.
1686 </para>
1641 1687
1642 <para> 1688 <para>
1643 The file you change in this example is named <filename>calibrate.c</filename> 1689 To create the patch for the <filename>calibrate.c</filename>, follow the steps
1644 and is located in the <filename>my-linux-yocto-3.4-work</filename> Git repository 1690 outlined in the
1645 (the copy of the bare clone) in <filename>init</filename>. 1691 "<link linkend='using-a-git-workflow'>Using a Git Workflow</link>"
1646 This example simply inserts several <filename>printk</filename> statements 1692 section.
1647 at the beginning of the <filename>calibrate_delay</filename> function. 1693 For the steps used to edit the source file, do the following:
1648 </para> 1694 </para>
1649 1695
1650 <para> 1696 <para>
1651 Here is the unaltered code at the start of this function: 1697 Locate the <filename>void __cpuinit calibrate_delay(void)</filename>
1698 function:
1652 <literallayout class='monospaced'> 1699 <literallayout class='monospaced'>
1653 void __cpuinit calibrate_delay(void) 1700 void __cpuinit calibrate_delay(void)
1654 { 1701 {
@@ -1660,12 +1707,11 @@
1660 . 1707 .
1661 . 1708 .
1662 . 1709 .
1663 </literallayout> 1710 </literallayout>
1664 </para> 1711 </para>
1665 1712
1666 <para> 1713 <para>
1667 Here is the altered code showing five new <filename>printk</filename> statements 1714 Alter the code as follows:
1668 near the top of the function:
1669 <literallayout class='monospaced'> 1715 <literallayout class='monospaced'>
1670 void __cpuinit calibrate_delay(void) 1716 void __cpuinit calibrate_delay(void)
1671 { 1717 {
@@ -1683,51 +1729,47 @@
1683 . 1729 .
1684 . 1730 .
1685 . 1731 .
1686 </literallayout> 1732 </literallayout>
1687 </para> 1733 </para>
1734 </section>
1688 1735
1689 <para> 1736 <section id='get-your-layer-setup-for-the-build'>
1690 After making and saving your changes, you need to stage them for the push. 1737 <title>Get Your Layer Setup for the Build</title>
1691 The following Git commands are one method of staging and committing your changes:
1692 <literallayout class='monospaced'>
1693 $ git add calibrate.c
1694 $ git commit --signoff
1695 </literallayout>
1696 </para>
1697 1738
1698 <para> 1739 <para>
1699 Once the source code has been modified, you need to use Git to push the changes to 1740 At this point, you have a patch file in the same directory as your original
1700 the bare clone. 1741 <filename>calibrate.c</filename>.
1701 If you do not push the changes, then the OpenEmbedded build system will not pick 1742 Move it to your layer and place it in a separate folder having the same
1702 up the changed source files. 1743 name as the recipe, which is <filename>linux-yocto</filename> in this case.
1703 </para> 1744 </para>
1704 1745
1705 <para> 1746 <para>
1706 The following command pushes the changes to the bare clone: 1747 Next, you need to set up your <filename>conf</filename> directory in your layer.
1748 Create the <filename>conf</filename> and create the <filename>layer.conf</filename>
1749 file.
1750 You can find information on this in the
1751 "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
1752 section.
1753 Here is what your <filename>layer.conf</filename> should look like for this
1754 example:
1707 <literallayout class='monospaced'> 1755 <literallayout class='monospaced'>
1708 $ git push origin standard-common-pc-base:standard/default/common-pc/base 1756 # We have a conf and classes directory, add to BBPATH
1709 </literallayout> 1757 BBPATH := "${LAYERDIR}:${BBPATH}"
1710 </para>
1711 </section>
1712 1758
1713 <section id='changing-build-parameters-for-your-build'> 1759 # We have a packages directory, add to BBFILES
1714 <title>Changing Build Parameters for Your Build</title> 1760 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
1761 ${LAYERDIR}/recipes-*/*/*.bbappend"
1715 1762
1716 <para> 1763 BBFILE_COLLECTIONS += "mylayer"
1717 At this point, the source has been changed and pushed. 1764 BBFILE_PATTERN_mylayer := "^${LAYERDIR}/"
1718 The example now defines some variables used by the OpenEmbedded build system 1765 BBFILE_PRIORITY_mylayer = "5"
1719 to locate your kernel source. 1766 </literallayout>
1720 You essentially need to identify where to find the kernel recipe and the changed source code.
1721 You also need to be sure some basic configurations are in place that identify the
1722 type of machine you are building and to help speed up the build should your host support
1723 multiple-core and thread capabilities.
1724 </para> 1767 </para>
1725 1768
1726 <para> 1769 <para>
1727 Do the following to make sure the build parameters are set up for the example. 1770 Do the following to make sure the build parameters are set up for the example.
1728 Once you set up these build parameters, they do not have to change unless you 1771 Once you set up these build parameters, they do not have to change unless you
1729 change the target architecture of the machine you are building or you move 1772 change the target architecture of the machine you are building:
1730 the bare clone, copy of the clone, or the <filename>poky-extras</filename> repository:
1731 <itemizedlist> 1773 <itemizedlist>
1732 <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The 1774 <listitem><para><emphasis>Build for the Correct Target Architecture:</emphasis> The
1733 <filename>local.conf</filename> file in the build directory defines the build's 1775 <filename>local.conf</filename> file in the build directory defines the build's
@@ -1745,15 +1787,16 @@
1745 If the host system has multiple cores then you can optimize build time 1787 If the host system has multiple cores then you can optimize build time
1746 by setting both these variables to twice the number of 1788 by setting both these variables to twice the number of
1747 cores.</para></listitem> 1789 cores.</para></listitem>
1748 <listitem><para><emphasis>Identify Your <filename>meta-kernel-dev</filename> 1790 <listitem><para><emphasis>Identify Your <filename>meta-mylayer</filename>
1749 Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the 1791 Layer:</emphasis> The <filename>BBLAYERS</filename> variable in the
1750 <filename>bblayers.conf</filename> file found in the 1792 <filename>bblayers.conf</filename> file found in the
1751 <filename>poky/build/conf</filename> directory needs to have the path to your local 1793 <filename>poky/build/conf</filename> directory needs to have the path to your local
1752 <filename>meta-kernel-dev</filename> layer. 1794 <filename>meta-mylayer</filename> layer.
1753 By default, the <filename>BBLAYERS</filename> variable contains paths to 1795 By default, the <filename>BBLAYERS</filename> variable contains paths to
1754 <filename>meta</filename> and <filename>meta-yocto</filename> in the 1796 <filename>meta</filename>, <filename>meta-yocto</filename>, and
1797 <filename>meta-yocto-bsp</filename> in the
1755 <filename>poky</filename> Git repository. 1798 <filename>poky</filename> Git repository.
1756 Add the path to your <filename>meta-kernel-dev</filename> location. 1799 Add the path to your <filename>meta-mylayer</filename> location.
1757 Be sure to substitute your user information in the statement. 1800 Be sure to substitute your user information in the statement.
1758 Here is an example: 1801 Here is an example:
1759 <literallayout class='monospaced'> 1802 <literallayout class='monospaced'>
@@ -1761,43 +1804,27 @@
1761 /home/scottrif/poky/meta \ 1804 /home/scottrif/poky/meta \
1762 /home/scottrif/poky/meta-yocto \ 1805 /home/scottrif/poky/meta-yocto \
1763 /home/scottrif/poky/meta-yocto-bsp \ 1806 /home/scottrif/poky/meta-yocto-bsp \
1764 /home/scottrif/poky/poky-extras/meta-kernel-dev \ 1807 /home/scottrif/poky/meta-mylayer \
1765 " 1808 "
1766 </literallayout></para></listitem> 1809 </literallayout></para></listitem>
1767 <listitem><para><emphasis>Identify Your Source Files:</emphasis> In the 1810 <listitem><para><emphasis>Create a bbappend File:</emphasis> You need to have
1768 <filename>linux-yocto_3.4.bbappend</filename> file located in the 1811 an append file to the main 3.4 kernel recipe.
1769 <filename>poky-extras/meta-kernel-dev/recipes-kernel/linux</filename> 1812 Locate the append file in your <filename>meta-mylayer</filename> layer.
1770 directory, you need to identify the location of the 1813 It needs to be in a <filename>meta-mylayer/recipes-kernel/linux</filename> directory.
1771 local source code, which in this example is the bare clone named 1814 Create the directory and use the following for the append file.
1772 <filename>linux-yocto-3.4.git</filename>. 1815 This example assumes patch file is named <filename>0001-documentation-calibrate.c.patch</filename>:
1773 To do this, set the <filename>KSRC_linux_yocto</filename> variable to point to your
1774 local <filename>linux-yocto-3.4.git</filename> Git repository by adding the
1775 following statement.
1776 Also, be sure the <filename>SRC_URI</filename> variable is pointing to
1777 your kernel source files by removing the comment.
1778 Finally, be sure to substitute your user information in the statement:
1779 <literallayout class='monospaced'> 1816 <literallayout class='monospaced'>
1780 KSRC_linux_yocto_3_4 ?= "/home/scottrif/linux-yocto-3.4.git" 1817 FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
1781 SRC_URI = "git://${KSRC_linux_yocto_3_4};protocol=file;nocheckout=1;branch=${KBRANCH},meta;name=machine,meta" 1818
1782 </literallayout></para></listitem> 1819 SRC_URI += "file://0001-documentation-calibrate.c.patch"
1820
1821 PRINC := "${@int(PRINC) + 1}"
1822 </literallayout>
1823 The <filename>FILESEXTRAPATHS</filename> and <filename>SRC_URI</filename>
1824 statements ensure the OpenEmbedded build system picks up the patch file.
1825 </para></listitem>
1783 </itemizedlist> 1826 </itemizedlist>
1784 </para> 1827 </para>
1785
1786 <note>
1787 <para>Before attempting to build the modified kernel, there is one more set of changes you
1788 need to make in the <filename>meta-kernel-dev</filename> layer.
1789 Because all the kernel <filename>.bbappend</filename> files are parsed during the
1790 build process regardless of whether you are using them or not, you should either
1791 comment out the <filename>COMPATIBLE_MACHINE</filename> statements in all
1792 unused <filename>.bbappend</filename> files, or simply remove (or rename) all the files
1793 except the one your are using for the build
1794 (i.e. <filename>linux-yocto_3.4.bbappend</filename> in this example).</para>
1795 <para>If you do not make one of these two adjustments, your machine will be compatible
1796 with all the kernel recipes in the <filename>meta-kernel-dev</filename> layer.
1797 When your machine is comapatible with all the kernel recipes, the build attempts
1798 to build all kernels in the layer.
1799 You could end up with build errors blocking your work.</para>
1800 </note>
1801 </section> 1828 </section>
1802 1829
1803 <section id='building-and-booting-the-modified-qemu-kernel-image'> 1830 <section id='building-and-booting-the-modified-qemu-kernel-image'>
@@ -1826,7 +1853,7 @@
1826 out previous builds.</note></para></listitem> 1853 out previous builds.</note></para></listitem>
1827 <listitem><para>Next, build the kernel image using this command: 1854 <listitem><para>Next, build the kernel image using this command:
1828 <literallayout class='monospaced'> 1855 <literallayout class='monospaced'>
1829 $ bitbake -k core-image-minimal 1856 $ bitbake -k linux-yocto
1830 </literallayout></para></listitem> 1857 </literallayout></para></listitem>
1831 <listitem><para>Finally, boot the modified image in the QEMU emulator 1858 <listitem><para>Finally, boot the modified image in the QEMU emulator
1832 using this command: 1859 using this command:
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index 9d73f8e4f5..03bb83096e 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -1688,7 +1688,8 @@ directory.</para></listitem>
1688 You need to be in the directory that has the temporary source code. 1688 You need to be in the directory that has the temporary source code.
1689 That directory is defined by the 1689 That directory is defined by the
1690 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink> 1690 <ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink>
1691 variable.</para></listitem> 1691 variable.
1692 For this discussion, assume that directory is <filename>linux</filename>.</para></listitem>
1692 <listitem><para><emphasis>Initialize a Git Repository:</emphasis> 1693 <listitem><para><emphasis>Initialize a Git Repository:</emphasis>
1693 Use the <filename>git init</filename> command to initialize a new local repository 1694 Use the <filename>git init</filename> command to initialize a new local repository
1694 that is based on the work directory: 1695 that is based on the work directory:
@@ -1739,9 +1740,11 @@ directory.</para></listitem>
1739 </literallayout></para></listitem> 1740 </literallayout></para></listitem>
1740 <listitem><para><emphasis>Stage the Modified Files:</emphasis> 1741 <listitem><para><emphasis>Stage the Modified Files:</emphasis>
1741 Use the <filename>git add</filename> command to stage the changed files so they 1742 Use the <filename>git add</filename> command to stage the changed files so they
1742 can be committed as follows: 1743 can be committed as follows.
1744 Again, for this discussion assume the files changed are in the <filename>linux</filename>
1745 directory:
1743 <literallayout class='monospaced'> 1746 <literallayout class='monospaced'>
1744 $ git add file1.c file2.c file3.c 1747 $ git add linux/file1.c linux/file2.c linux/file3.c
1745 </literallayout></para></listitem> 1748 </literallayout></para></listitem>
1746 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis> 1749 <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
1747 Use the <filename>git commit</filename> command to commit the changes to the 1750 Use the <filename>git commit</filename> command to commit the changes to the