summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide/bsp.xml
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-03-27 15:01:41 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-05-24 17:16:05 +0100
commitfe1419631c597a2f088454fe97ead333838e61e1 (patch)
tree7a7fced278c193e6cf479146d279fe4ef15682e0 /documentation/bsp-guide/bsp.xml
parent424f544ecdce7a904c02afccc6d603a0feaad075 (diff)
downloadpoky-fe1419631c597a2f088454fe97ead333838e61e1.tar.gz
bsp-guide: Added new section for creating layer using bitbake-layers
Created detailed example using the BeagleBone BSP. (From yocto-docs rev: 7701dc2bd94ae7ee3e4aee37ac97174ad445d286) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/bsp-guide/bsp.xml')
-rw-r--r--documentation/bsp-guide/bsp.xml546
1 files changed, 488 insertions, 58 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index f9455ed861..24bbeb6628 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -1746,25 +1746,20 @@
1746 <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title> 1746 <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title>
1747 1747
1748 <para> 1748 <para>
1749 [INTRODUCE THE PROCEDURE AND LINK BACK TO <link linkend='bsp-layers'>BSP layer</link>. 1749 The <filename>bitbake-layers create-layer</filename> script
1750 IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET 1750 automates creating a BSP layer.
1751 UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.] 1751 What makes a layer a "BSP layer", is the presence of a machine
1752 <itemizedlist> 1752 configuration file.
1753 <listitem><para>[PARAMETER 1]</para></listitem> 1753 Additionally, a BSP layer usually has a kernel recipe
1754 <listitem><para>[PARAMETER 2]</para></listitem> 1754 or an append file that leverages off an existing kernel recipe.
1755 <listitem><para>[PARAMETER 3]</para></listitem> 1755 The primary requirement, however, is the machine configuration.
1756 <listitem><para>[PARAMETER 4]</para></listitem>
1757 <listitem><para>[PARAMETER 5]</para></listitem>
1758 <listitem><para>[PARAMETER 6]</para></listitem>
1759 <listitem><para>[PARAMETER 7]</para></listitem>
1760 </itemizedlist>
1761 </para> 1756 </para>
1762 1757
1763 <para> 1758 <para>
1764 The following procedure creates a BSP layer: 1759 Use these steps to create a BSP layer:
1765 <itemizedlist> 1760 <itemizedlist>
1766 <listitem><para> 1761 <listitem><para>
1767 <emphasis>Create General Layer:</emphasis> 1762 <emphasis>Create a General Layer:</emphasis>
1768 Use the <filename>bitbake-layers</filename> script with the 1763 Use the <filename>bitbake-layers</filename> script with the
1769 <filename>create-layer</filename> subcommand to create a 1764 <filename>create-layer</filename> subcommand to create a
1770 new general layer. 1765 new general layer.
@@ -1774,25 +1769,41 @@
1774 section in the Yocto Project Development Tasks Manual. 1769 section in the Yocto Project Development Tasks Manual.
1775 </para></listitem> 1770 </para></listitem>
1776 <listitem><para> 1771 <listitem><para>
1772 <emphasis>Create a Layer Configuration File:</emphasis>
1773 Every layer needs a layer configuration file.
1774 This configuration file establishes locations for the
1775 layer's recipes, priorities for the layer, and so forth.
1776 You can find examples of <filename>layer.conf</filename>
1777 files in the Yocto Project
1778 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
1779 To get examples of what you need in your configuration
1780 file, locate a layer (e.g. "meta-ti") and examine the
1781 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink>
1782 file.
1783 </para></listitem>
1784 <listitem><para>
1777 <emphasis>Create a Machine Configuration File:</emphasis> 1785 <emphasis>Create a Machine Configuration File:</emphasis>
1778 Create a <filename>conf/machine/&gt;machine&lt;.conf</filename> 1786 Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1779 file. 1787 file.
1780 See <filename>meta-yocto-bsp/conf/machine</filename> for sample 1788 See
1781 <filename>&gt;machine.conf&lt;</filename> files. 1789 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink>
1782 Other samples exist from other vendors such as 1790 for sample
1783 <filename>meta-intel</filename>, <filename>meta-ti</filename>, 1791 <replaceable>bsp_root_name</replaceable><filename>.conf</filename>
1784 and <filename>meta-freescale</filename> that have more specific machine 1792 files.
1793 Other samples such as
1794 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink>
1795 and
1796 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink>
1797 exist from other vendors that have more specific machine
1785 and tuning examples. 1798 and tuning examples.
1786 </para></listitem> 1799 </para></listitem>
1787 <listitem><para> 1800 <listitem><para>
1788 <emphasis>Create a Kernel Recipe:</emphasis> 1801 <emphasis>Create a Kernel Recipe:</emphasis>
1789 Create a kernel recipe in <filename>recipes-kernel/linux</filename> 1802 Create a kernel recipe in <filename>recipes-kernel/linux</filename>
1790 either using a linux-yocto kernel with a <filename>.bbappend</filename> 1803 by either using a kernel append file or a new custom kernel
1791 file or a new custom kernel recipe file (i.e. <filename>.bb</filename> 1804 recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>).
1792 file).
1793 The BSP layers mentioned in the previous step also contain different 1805 The BSP layers mentioned in the previous step also contain different
1794 kernel examples. 1806 kernel examples.
1795 You can start with the linux-yocto or use a custom kernel.
1796 See the 1807 See the
1797 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>" 1808 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>"
1798 section in the Yocto Project Linux Kernel Development Manual 1809 section in the Yocto Project Linux Kernel Development Manual
@@ -1802,43 +1813,462 @@
1802 </para> 1813 </para>
1803 1814
1804 <para> 1815 <para>
1805 [THERE IS MORE INFORMATION THAT NEEDS TO BE FILLED IN HERE. THIS NEEDS TO 1816 The remainder of this section provides a description of
1806 BE PROVIDED BY ENGINEERS.] 1817 the Yocto Project reference BSP for Beaglebone, which
1818 resides in the
1819 <ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>Container Layer</ulink>
1820 (i.e.
1821 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink>).
1807 </para> 1822 </para>
1808 1823
1809 <para> 1824 <section id='bsp-layer-configuration-example'>
1810 The remainder of this section presents an example that uses 1825 <title>BSP Layer Configuration Example</title>
1811 <filename>myarm</filename> as the machine name and <filename>qemu</filename>
1812 as the machine architecture.
1813 Of the available architectures, <filename>qemu</filename> is the only architecture
1814 that causes the script to prompt you further for an actual architecture.
1815 In every other way, this architecture is representative of how creating a BSP for
1816 an actual machine would work.
1817 The reason the example uses this architecture is because it is an emulated architecture
1818 and can easily be followed without requiring actual hardware.
1819 </para>
1820 1826
1821 <para> 1827 <para>
1822 Following is a complete example: 1828 The layer's <filename>conf</filename> directory
1823 <literallayout class='monospaced'> 1829 contains the <filename>layer.conf</filename>
1824 [INSERT EXAMPLE - NEED EXAMPLE] 1830 configuration file.
1825 </literallayout> 1831 In this example, the
1826 </para> 1832 <filename>conf/layer.conf</filename> is the
1833 following:
1834 <literallayout class='monospaced'>
1835 # We have a conf and classes directory, add to BBPATH
1836 BBPATH .= ":${LAYERDIR}"
1827 1837
1828 <para> 1838 # We have recipes-* directories, add to BBFILES
1829 Once the BSP Layer is created, you must add it to your 1839 BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
1830 <filename>bblayers.conf</filename> file. 1840 ${LAYERDIR}/recipes-*/*/*.bbappend"
1831 Here is an example: 1841
1832 <literallayout class='monospaced'> 1842 BBFILE_COLLECTIONS += "yoctobsp"
1833 BBLAYERS = ? " \ 1843 BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
1834 /usr/local/src/yocto/meta \ 1844 BBFILE_PRIORITY_yoctobsp = "5"
1835 /usr/local/src/yocto/meta-poky \ 1845 LAYERVERSION_yoctobsp = "4"
1836 /usr/local/src/yocto/meta-yocto-bsp \ 1846 LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
1837 /usr/local/src/yocto/meta-myarm \ 1847 </literallayout>
1838 " 1848 The variables used in this file configure the
1839 </literallayout> 1849 layer.
1840 Adding the layer to this file allows the build system to build the BSP and 1850 A good way to learn about layer configuration
1841 find the layer along with other Metadata it needs. 1851 files is to examine various files for BSP from
1842 </para> 1852 the
1853 <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>.
1854 </para>
1855
1856 <para>
1857 For a detailed description of this particular
1858 layer configuration file, see
1859 "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink>
1860 in the discussion that describes how to create
1861 layers in the Yocto Project Development Tasks Manual.
1862 </para>
1863 </section>
1864
1865 <section id='bsp-machine-configuration-example'>
1866 <title>BSP Machine Configuration Example</title>
1867
1868 <para>
1869 As mentioned earlier in this section, the existence
1870 of a machine configuration file is what makes a
1871 layer a BSP layer as compared to a general or
1872 kernel layer.
1873 </para>
1874
1875 <para>
1876 Machine configuration files exist in the
1877 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename>
1878 directory of the layer:
1879 <literallayout class='monospaced'>
1880 <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine</replaceable><filename>.conf</filename>
1881 </literallayout>
1882 For example, the machine configuration file for the
1883 <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink>
1884 is located in the container layer
1885 <filename>poky/meta-yocto-bsp/conf/machine</filename>
1886 and is named <filename>beaglebone-yocto.conf</filename>:
1887 <literallayout class='monospaced'>
1888 #@TYPE: Machine
1889 #@NAME: Beaglebone-yocto machine
1890 #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards
1891
1892 PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
1893 XSERVER ?= "xserver-xorg \
1894 xf86-video-modesetting \
1895 "
1896
1897 MACHINE_EXTRA_RRECOMMENDS = " kernel-modules kernel-devicetree"
1898
1899 EXTRA_IMAGEDEPENDS += "u-boot"
1900
1901 DEFAULTTUNE ?= "cortexa8hf-neon"
1902 include conf/machine/include/tune-cortexa8.inc
1903
1904 IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap"
1905 EXTRA_IMAGECMD_jffs2 = "-lnp "
1906 WKS_FILE ?= "beaglebone-yocto.wks"
1907 IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage"
1908 do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot"
1909
1910 SERIAL_CONSOLE = "115200 ttyO0"
1911
1912 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
1913 PREFERRED_VERSION_linux-yocto ?= "4.12%"
1914
1915 KERNEL_IMAGETYPE = "zImage"
1916 KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb"
1917 KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"
1918
1919 SPL_BINARY = "MLO"
1920 UBOOT_SUFFIX = "img"
1921 UBOOT_MACHINE = "am335x_boneblack_config"
1922 UBOOT_ENTRYPOINT = "0x80008000"
1923 UBOOT_LOADADDRESS = "0x80008000"
1924
1925 MACHINE_FEATURES = "usbgadget usbhost vfat alsa"
1926
1927 IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO"
1928 </literallayout>
1929 The variables used to configure the machine define
1930 machine-specific properties.
1931 For example, machine-dependent packages, machine
1932 tunings, the type of kernel to build, and
1933 U-Boot configurations.
1934 </para>
1935
1936 <para>
1937 The following list provides some explanation
1938 for the statements found in the example reference
1939 machine configuration file for the BeagleBone
1940 development boards.
1941 Realize that much more can be defined as part of
1942 a machines configuration file.
1943 In general, you can learn about related variables
1944 that this example does not have by locating the
1945 variables in the
1946 "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>"
1947 in the Yocto Project Reference Manual.
1948 <itemizedlist>
1949 <listitem><para>
1950 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>:
1951 The recipe that provides "virtual/xserver" when
1952 more than one provider is found.
1953 In this case, the recipe that provides
1954 "virtual/xserver" is "xserver-xorg", which
1955 exists in
1956 <filename>poky/meta/recipes-graphics/xserver-xorg</filename>.
1957 </para></listitem>
1958 <listitem><para>
1959 <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>:
1960 The packages that should be installed to provide
1961 an X server and drivers for the machine.
1962 In this example, the "xserver-xorg" and
1963 "xf86-video-modesetting" are installed.
1964 </para></listitem>
1965 <listitem><para>
1966 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>:
1967 A list of machine-dependent packages
1968 not essential for booting the image.
1969 Thus, the build does not fail if the packages
1970 do not exist.
1971 However, the packages are required for a
1972 fully-featured image.
1973 <note><title>Tip</title>
1974 Many <filename>MACHINE*</filename> variables
1975 exist that help you configure a particular
1976 piece of hardware.
1977 </note>
1978 </para></listitem>
1979 <listitem><para>
1980 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>:
1981 Recipes to build that do not provide packages
1982 for installing into the root filesystem
1983 but building the image depends on the
1984 recipes.
1985 Sometimes a recipe is required to build
1986 the final image but is not needed in the
1987 root filesystem.
1988 In this case, the U-Boot recipe must be
1989 built for the image.
1990 </para></listitem>
1991 <listitem><para>
1992 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>:
1993 Machines use tunings to optimize machine,
1994 CPU, and application performance.
1995 These features, which are collectively known
1996 as "tuning features", exist in the
1997 <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded Core (OE-Core)</ulink>
1998 layer (e.g.
1999 <filename>poky/meta/conf/machine/include</filename>).
2000 In this example, the default tunning file is
2001 "cortexa8hf-neon".
2002 <note>
2003 The <filename>include</filename> statement
2004 that pulls in the
2005 <filename>conf/machine/include/tune-cortexa8.inc</filename>
2006 file provides many tuning possibilities.
2007 </note>
2008 </para></listitem>
2009 <listitem><para>
2010 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>:
2011 The formats the OpenEmbedded build system
2012 uses during the build when creating the
2013 root filesystem.
2014 In this example, four types of images are
2015 supported.
2016 </para></listitem>
2017 <listitem><para>
2018 <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>:
2019 Specifies additional options for image
2020 creation commands.
2021 In this example, the "-lnp " option is used
2022 when creating the
2023 <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink>
2024 image.
2025 </para></listitem>
2026 <listitem><para>
2027 <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>:
2028 The location of the
2029 <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink>
2030 file used by the OpenEmbedded build system to
2031 create a partitioned image (image.wic).
2032 </para></listitem>
2033 <listitem><para>
2034 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
2035 Specifies packages to install into an image
2036 through the
2037 <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
2038 class.
2039 Recipes use the <filename>IMAGE_INSTALL</filename>
2040 variable.
2041 </para></listitem>
2042 <listitem><para>
2043 <filename>do_image_wic[depends]</filename>:
2044 A task that is constructed during the build.
2045 In this example, the task depends on specific tools
2046 in order to create the sysroot when buiding a Wic
2047 image.
2048 </para></listitem>
2049 <listitem><para>
2050 <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></ulink>:
2051 Defines a serial console (TTY) to enable using
2052 getty.
2053 In this case, the baud rate is "115200" and the
2054 device name is "ttyO0".
2055 </para></listitem>
2056 <listitem><para>
2057 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>:
2058 Specifies the recipe that provides
2059 "virtual/kernel" when more than one provider
2060 is found.
2061 In this case, the recipe that provides
2062 "virtual/kernel" is "linux-yocto", which
2063 exists in the layer's
2064 <filename>recipes-kernel/linux</filename> directory.
2065 </para></listitem>
2066 <listitem><para>
2067 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>:
2068 Defines the version of the recipe used
2069 to build the kernel, which is "4.12" in this
2070 case.
2071 </para></listitem>
2072 <listitem><para>
2073 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>:
2074 The type of kernel to build for the device.
2075 In this case, the OpenEmbedded build system
2076 creates a "zImage" image type.
2077 </para></listitem>
2078 <listitem><para>
2079 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>:
2080 The name of the generated Linux kernel device
2081 tree (i.e. the <filename>.dtb</filename>) file.
2082 All the device trees for the various BeagleBone
2083 devices are included.
2084<!--
2085 You have to include some *.inc files according to the definition of KERNEL_DEVICETREE.
2086 I don't see where these are being provided.
2087-->
2088 </para></listitem>
2089 <listitem><para>
2090 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>:
2091 Additional <filename>make</filename>
2092 command-line arguments the OpenEmbedded build
2093 system passes on when compiling the kernel.
2094 In this example, "LOADADDR=${UBOOT_ENTRYPOINT}"
2095 is passed as a command-line argument.
2096 </para></listitem>
2097 <listitem><para>
2098 <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>:
2099 Defines the Secondary Program Loader (SPL) binary
2100 type.
2101 In this case, the SPL binary is set to
2102 "MLO", which stands for Multimedia card LOader.
2103 </para>
2104
2105 <para>The BeagleBone development board requires a
2106 MLO file in order to boot.
2107 Consequently, the machine configuration needs to
2108 define the SPL as an MLO type file and use it
2109 as the Xloader.
2110 <note>
2111 For more information on how the SPL variables
2112 are used, see the
2113 <ulink url='&YOCTO_GIT_URL;#/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink>
2114 include file.
2115 </note>
2116 </para></listitem>
2117<!--
2118 There is an SPL Framework documented here - http://git.denx.de/?p=u-boot.git;a=blob;f=doc/README.SPL;hb=HEAD.
2119 SPL is the "secondary program loader." Here is some stuff from the
2120 poky/meta/recipes-bsp/u-boot/u-boot.inc file:
2121-->
2122 <listitem><para>
2123 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>:
2124 Defines various U-Boot configurations needed
2125 to build a U-Boot image.
2126 In this example, a U-Boot image is required
2127 to boot the BeagleBone device.
2128 See the following variables for more information:
2129 <itemizedlist>
2130 <listitem><para>
2131 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>:
2132 Points to the generated U-Boot extension.
2133 </para></listitem>
2134 <listitem><para>
2135 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>:
2136 Specifies the value passed on the make command line when building a U-Boot image.
2137 </para></listitem>
2138 <listitem><para>
2139 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>:
2140 Specifies the entry point for the U-Boot image.
2141 </para></listitem>
2142 <listitem><para>
2143 <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>:
2144 Specifies the load address for the U-Boot image.
2145 </para></listitem>
2146 </itemizedlist>
2147 </para></listitem>
2148 <listitem><para>
2149 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>:
2150 Specifies the list of hardware features the
2151 BeagleBone device is capable of supporting.
2152 In this case, the device supports
2153 "usbgadget usbhost vfat alsa".
2154 </para></listitem>
2155 <listitem><para>
2156 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>:
2157 Files installed into the device's boot partition
2158 when preparing the image using the Wic tool
2159 with the <filename>bootimg-partition</filename>
2160 source plugin.
2161 In this case, the "u-boot.${UBOOT_SUFFIX}" and
2162 "MLO" files are installed.
2163 </para></listitem>
2164 </itemizedlist>
2165 </para>
2166 </section>
2167
2168 <section id='bsp-kernel-recipe-example'>
2169 <title>BSP Kernel Recipe Example</title>
2170
2171 <para>
2172 The kernel recipe used to build the kernel image
2173 for the BeagleBone device was established in the
2174 machine configuration:
2175 <literallayout class='monospaced'>
2176 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
2177 PREFERRED_VERSION_linux-yocto ?= "4.12%"
2178 </literallayout>
2179 The <filename>meta-yocto-bsp/recipes-kernel/linux</filename>
2180 directory in the layer contains metadata used
2181 to build the kernel.
2182 In this case, a kernel append file is used to
2183 override an established kernel recipe, which is
2184 located in
2185 <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>
2186 and named
2187 <filename>linux-yocto_4.12.bb</filename>.
2188 </para>
2189
2190 <para>
2191 Following is the contents of the append file:
2192 <literallayout class='monospaced'>
2193 KBRANCH_genericx86 = "standard/base"
2194 KBRANCH_genericx86-64 = "standard/base"
2195
2196 KMACHINE_genericx86 ?= "common-pc"
2197 KMACHINE_genericx86-64 ?= "common-pc-64"
2198 KBRANCH_edgerouter = "standard/edgerouter"
2199 KBRANCH_beaglebone-yocto = "standard/beaglebone"
2200 KMACHINE_beaglebone-yocto = "beaglebone"
2201 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
2202
2203 SRCREV_machine_genericx86 ?= "1c4ad569af3e23a77994235435040e322908687f"
2204 SRCREV_machine_genericx86-64 ?= "1c4ad569af3e23a77994235435040e322908687f"
2205 SRCREV_machine_edgerouter ?= "257f843ea367744620f1d92910afd2f454e31483"
2206 SRCREV_machine_beaglebone-yocto ?= "257f843ea367744620f1d92910afd2f454e31483"
2207 SRCREV_machine_mpc8315e-rdb ?= "014560874f9eb2a86138c9cc35046ff1720485e1"
2208
2209
2210 COMPATIBLE_MACHINE_genericx86 = "genericx86"
2211 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
2212 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
2213 COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto"
2214 COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
2215
2216 LINUX_VERSION_genericx86 = "4.12.20"
2217 LINUX_VERSION_genericx86-64 = "4.12.20"
2218 LINUX_VERSION_edgerouter = "4.12.19"
2219 LINUX_VERSION_beaglebone-yocto = "4.12.19"
2220 LINUX_VERSION_mpc8315e-rdb = "4.12.19"
2221 </literallayout>
2222 This particular append file works for all the
2223 machines that are part of the
2224 <filename>meta-yocto-bsp</filename> container
2225 layer.
2226 The relevant statements are appended with
2227 the "beaglebone-yocto" string.
2228 The OpenEmbedded build system uses these
2229 statements to override similar statements
2230 in the kernel recipe:
2231 <itemizedlist>
2232 <listitem><para>
2233 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>:
2234 Identifies the kernel branch that is validated,
2235 patched, and configured during the build.
2236 </para></listitem>
2237 <listitem><para>
2238 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>:
2239 Identifies the machine name as known by the
2240 kernel, which is sometimes a different name
2241 than what is known by the OpenEmbedded build
2242 system.
2243 </para></listitem>
2244 <listitem><para>
2245 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
2246 Identifies the revision of the source code used
2247 to build the image.
2248<!--
2249 You find out about that point in the kernel source tree by
2250 doing the following command:
2251
2252 git log &dash;&dash;decorate 257f843ea367744620f1d92910afd2f454e31483
2253
2254 Returns information about the commit, which is usually
2255 that it is a merge point for a stable kernel release.
2256-->
2257 </para></listitem>
2258 <listitem><para>
2259 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
2260 A regular expression that resolves to one or
2261 more target machines with which the recipe
2262 is compatible.
2263 </para></listitem>
2264 <listitem><para>
2265 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
2266 The Linux version from kernel.org used by
2267 the OpenEmbedded build system to build the
2268 kernel image.
2269 </para></listitem>
2270 </itemizedlist>
2271 </para>
2272 </section>
1843</section> 2273</section>
1844</chapter> 2274</chapter>