| <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" |
| [<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] > |
| |
| <chapter id='bsp'> |
| |
| <title>Board Support Packages (BSP) - Developer's Guide</title> |
| |
| <para> |
| A Board Support Package (BSP) is a collection of information that |
| defines how to support a particular hardware device, set of devices, or |
| hardware platform. |
| The BSP includes information about the hardware features |
| present on the device and kernel configuration information along with any |
| additional hardware drivers required. |
| The BSP also lists any additional software |
| components required in addition to a generic Linux software stack for both |
| essential and optional platform features. |
| </para> |
| |
| <para> |
| This guide presents information about BSP layers, defines a structure for components |
| so that BSPs follow a commonly understood layout, discusses how to customize |
| a recipe for a BSP, addresses BSP licensing, and provides information that |
| shows you how to create a |
| <link linkend='bsp-layers'>BSP Layer</link> using the |
| <link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></link> |
| tool. |
| </para> |
| |
| <section id='bsp-layers'> |
| <title>BSP Layers</title> |
| |
| <para> |
| A BSP consists of a file structure inside a base directory. |
| Collectively, you can think of the base directory, its file structure, |
| and the contents as a <firstterm>BSP layer</firstterm>. |
| Although not a strict requirement, BSP layers in the Yocto Project |
| use the following well-established naming convention: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable> |
| </literallayout> |
| The string "meta-" is prepended to the machine or platform name, which is |
| <replaceable>bsp_root_name</replaceable> in the above form. |
| <note><title>Tip</title> |
| Because the BSP layer naming convention is well-established, |
| it is advisable to follow it when creating layers. |
| Technically speaking, a BSP layer name does not need to |
| start with <filename>meta-</filename>. |
| However, various scripts and tools in the Yocto Project |
| development environment assume this convention. |
| </note> |
| </para> |
| |
| <para> |
| To help understand the BSP layer concept, consider the BSPs that the |
| Yocto Project supports and provides with each release. |
| You can see the layers in the |
| <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>Yocto Project Source Repositories</ulink> |
| through a web interface at |
| <ulink url='&YOCTO_GIT_URL;'></ulink>. |
| If you go to that interface, you will find a list of repositories |
| under "Yocto Metadata Layers". |
| <note> |
| Layers that are no longer actively supported as part of the |
| Yocto Project appear under the heading "Yocto Metadata Layer |
| Archive." |
| </note> |
| Each repository is a BSP layer supported by the Yocto Project |
| (e.g. <filename>meta-raspberrypi</filename> and |
| <filename>meta-intel</filename>). |
| Each of these layers is a repository unto itself and clicking on |
| the layer name displays two URLs from which you can |
| clone the layer's repository to your local system. |
| Here is an example that clones the Raspberry Pi BSP layer: |
| <literallayout class='monospaced'> |
| $ git clone git://git.yoctoproject.org/meta-raspberrypi |
| </literallayout> |
| </para> |
| |
| <para> |
| In addition to BSP layers, the |
| <filename>meta-yocto-bsp</filename> layer is part of the |
| shipped <filename>poky</filename> repository. |
| The <filename>meta-yocto-bsp</filename> layer maintains several |
| "reference" BSPs including the ARM-based Beaglebone, MIPS-based |
| EdgeRouter, and generic versions of |
| both 32-bit and 64-bit IA machines. |
| </para> |
| |
| <para> |
| For information on typical BSP development workflow, see the |
| "<link linkend='developing-a-board-support-package-bsp'>Developing a Board Support Package (BSP)</link>" |
| section. |
| For more information on how to set up a local copy of source files |
| from a Git repository, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#locating-yocto-project-source-files'>Locating Yocto Project Source Files</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para> |
| |
| <para> |
| The BSP layer's base directory |
| (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>) |
| is the root directory of that Layer. |
| This directory is what you add to the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> |
| variable in the <filename>conf/bblayers.conf</filename> file found in your |
| <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, |
| which is established after you run the OpenEmbedded build environment |
| setup script (i.e. |
| <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). |
| Adding the root directory allows the |
| <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> |
| to recognize the BSP layer and from it build an image. |
| Here is an example: |
| <literallayout class='monospaced'> |
| BBLAYERS ?= " \ |
| /usr/local/src/yocto/meta \ |
| /usr/local/src/yocto/meta-poky \ |
| /usr/local/src/yocto/meta-yocto-bsp \ |
| /usr/local/src/yocto/meta-mylayer \ |
| " |
| </literallayout> |
| <note><title>Tip</title> |
| Ordering and |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink> |
| for the layers listed in <filename>BBLAYERS</filename> |
| matter. |
| For example, if multiple layers define a machine |
| configuration, the OpenEmbedded build system uses |
| the last layer searched given similar layer |
| priorities. |
| The build system works from the top-down through |
| the layers listed in <filename>BBLAYERS</filename>. |
| </note> |
| </para> |
| |
| <para> |
| Some BSPs require or depend on additional layers |
| beyond the BSP's root layer in order to be functional. |
| In this case, you need to specify these layers in the |
| <filename>README</filename> "Dependencies" section of the |
| BSP's root layer. |
| Additionally, if any build instructions exist for the |
| BSP, you must add them to the "Dependencies" section. |
| </para> |
| |
| <para> |
| Some layers function as a layer to hold other BSP layers. |
| These layers are knows as |
| "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>". |
| An example of this type of layer is OpenEmbedded's |
| <ulink url='https://github.com/openembedded/meta-openembedded'><filename>meta-openembedded</filename></ulink> |
| layer. |
| The <filename>meta-openembedded</filename> layer contains |
| many <filename>meta-*</filename> layers. |
| In cases like this, you need to include the names of the actual |
| layers you want to work with, such as: |
| <literallayout class='monospaced'> |
| BBLAYERS ?= " \ |
| /usr/local/src/yocto/meta \ |
| /usr/local/src/yocto/meta-poky \ |
| /usr/local/src/yocto/meta-yocto-bsp \ |
| /usr/local/src/yocto/meta-mylayer \ |
| .../meta-openembedded/meta-oe \ |
| .../meta-openembedded/meta-perl \ |
| .../meta-openembedded/meta-networking \ |
| " |
| </literallayout> |
| and so on. |
| </para> |
| |
| <para> |
| For more information on layers, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" |
| section of the Yocto Project Development Tasks Manual. |
| </para> |
| </section> |
| |
| <section id='preparing-your-build-host-to-work-with-bsp-layers'> |
| <title>Preparing Your Build Host to Work With BSP Layers</title> |
| |
| <para> |
| This section describes how to get your build host ready |
| to work with BSP layers. |
| Once you have the host set up, you can create the layer |
| as described in the |
| "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</link>" |
| section. |
| <note> |
| For structural information on BSPs, see the |
| <link linkend='bsp-filelayout'>Example Filesystem Layout</link> |
| section. |
| </note> |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Set Up the Build Environment:</emphasis> |
| Be sure you are set up to use BitBake in a shell. |
| See the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" |
| section in the Yocto Project Development Tasks Manual for information |
| on how to get a build host ready that is either a native |
| Linux machine or a machine that uses CROPS. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Clone the <filename>poky</filename> Repository:</emphasis> |
| You need to have a local copy of the Yocto Project |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| (i.e. a local <filename>poky</filename> repository). |
| See the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#cloning-the-poky-repository'>Cloning the <filename>poky</filename> Repository</ulink>" |
| and possibly the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out by Branch in Poky</ulink>" |
| or |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#checkout-out-by-tag-in-poky'>Checking Out by Tag in Poky</ulink>" |
| sections all in the Yocto Project Development Tasks Manual for |
| information on how to clone the <filename>poky</filename> |
| repository and check out the appropriate branch for your work. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Determine the BSP Layer You Want:</emphasis> |
| The Yocto Project supports many BSPs, which are maintained in |
| their own layers or in layers designed to contain several |
| BSPs. |
| To get an idea of machine support through BSP layers, you can |
| look at the |
| <ulink url='&YOCTO_RELEASE_DL_URL;/machines'>index of machines</ulink> |
| for the release. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Optionally Clone the |
| <filename>meta-intel</filename> BSP Layer:</emphasis> |
| If your hardware is based on current Intel CPUs and devices, |
| you can leverage this BSP layer. |
| For details on the <filename>meta-intel</filename> BSP layer, |
| see the layer's |
| <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/meta-intel/tree/README'><filename>README</filename></ulink> |
| file. |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Navigate to Your Source Directory:</emphasis> |
| Typically, you set up the |
| <filename>meta-intel</filename> Git repository |
| inside the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| (e.g. <filename>poky</filename>). |
| <literallayout class='monospaced'> |
| $ cd /home/<replaceable>you</replaceable>/poky |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Clone the Layer:</emphasis> |
| <literallayout class='monospaced'> |
| $ git clone git://git.yoctoproject.org/meta-intel.git |
| Cloning into 'meta-intel'... |
| remote: Counting objects: 15585, done. |
| remote: Compressing objects: 100% (5056/5056), done. |
| remote: Total 15585 (delta 9123), reused 15329 (delta 8867) |
| Receiving objects: 100% (15585/15585), 4.51 MiB | 3.19 MiB/s, done. |
| Resolving deltas: 100% (9123/9123), done. |
| Checking connectivity... done. |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Check Out the Proper Branch:</emphasis> |
| The branch you check out for |
| <filename>meta-intel</filename> must match the same |
| branch you are using for the Yocto Project release |
| (e.g. &DISTRO_NAME_NO_CAP;): |
| <literallayout class='monospaced'> |
| $ cd meta-intel |
| $ git checkout -b &DISTRO_NAME_NO_CAP; remotes/origin/&DISTRO_NAME_NO_CAP; |
| Branch &DISTRO_NAME_NO_CAP; set up to track remote branch &DISTRO_NAME_NO_CAP; from origin. |
| Switched to a new branch '&DISTRO_NAME_NO_CAP;' |
| </literallayout> |
| <note> |
| To see the available branch names in a cloned repository, |
| use the <filename>git branch -al</filename> command. |
| See the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#checking-out-by-branch-in-poky'>Checking Out By Branch in Poky</ulink>" |
| section in the Yocto Project Development Tasks |
| Manual for more information. |
| </note> |
| </para></listitem> |
| </orderedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Optionally Set Up an Alternative BSP Layer:</emphasis> |
| If your hardware can be more closely leveraged to an |
| existing BSP not within the <filename>meta-intel</filename> |
| BSP layer, you can clone that BSP layer.</para> |
| |
| <para>The process is identical to the process used for the |
| <filename>meta-intel</filename> layer except for the layer's |
| name. |
| For example, if you determine that your hardware most |
| closely matches the <filename>meta-raspberrypi</filename>, |
| clone that layer: |
| <literallayout class='monospaced'> |
| $ git clone git://git.yoctoproject.org/meta-raspberrypi |
| Cloning into 'meta-raspberrypi'... |
| remote: Counting objects: 4743, done. |
| remote: Compressing objects: 100% (2185/2185), done. |
| remote: Total 4743 (delta 2447), reused 4496 (delta 2258) |
| Receiving objects: 100% (4743/4743), 1.18 MiB | 0 bytes/s, done. |
| Resolving deltas: 100% (2447/2447), done. |
| Checking connectivity... done. |
| </literallayout> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Initialize the Build Environment:</emphasis> |
| While in the root directory of the Source Directory (i.e. |
| <filename>poky</filename>), run the |
| <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink> |
| environment setup script to define the OpenEmbedded |
| build environment on your build host. |
| <literallayout class='monospaced'> |
| $ source &OE_INIT_FILE; |
| </literallayout> |
| Among other things, the script creates the |
| <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, |
| which is <filename>build</filename> in this case |
| and is located in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. |
| After the script runs, your current working directory |
| is set to the <filename>build</filename> directory. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id="bsp-filelayout"> |
| <title>Example Filesystem Layout</title> |
| |
| <para> |
| Defining a common BSP directory structure allows |
| end-users to understand and become familiar with |
| that standard. |
| A common format also encourages standardization |
| of software support for hardware. |
| </para> |
| |
| <para> |
| The proposed form described in this section does |
| have elements that are specific to the OpenEmbedded |
| build system. |
| It is intended that developers can use this structure |
| with other build systems besides the OpenEmbedded build |
| system. |
| It is also intended that it will be be simple to extract |
| information and convert it to other formats if required. |
| The OpenEmbedded build system, through its standard |
| <ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>layers mechanism</ulink>, |
| can directly accept the format described as a layer. |
| The BSP layer captures all the hardware-specific details |
| in one place using a standard format, which is useful |
| for any person wishing to use the hardware platform |
| regardless of the build system they are using. |
| </para> |
| |
| <para> |
| The BSP specification does not include a build system |
| or other tools - the specification is concerned with |
| the hardware-specific components only. |
| At the end-distribution point, you can ship the BSP |
| layer combined with a build system and other tools. |
| Realize that it is important to maintain the distinction |
| that the BSP layer, a build system, and tools are |
| separate components that could be combined in |
| certain end products. |
| </para> |
| |
| <para> |
| Before looking at the recommended form for the directory structure |
| inside a BSP layer, you should be aware that some |
| requirements do exist in order for a BSP layer to |
| be considered <firstterm>compliant</firstterm> with the Yocto Project. |
| For that list of requirements, see the |
| "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>" |
| section. |
| </para> |
| |
| <para> |
| Below is the typical directory structure for a BSP layer. |
| While this basic form represents the standard, |
| realize that the actual layout for individual |
| BSPs could differ. |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/ |
| meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable> |
| meta-<replaceable>bsp_root_name</replaceable>/README |
| meta-<replaceable>bsp_root_name</replaceable>/README.sources |
| meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable> |
| meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf |
| meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf |
| meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/* |
| meta-<replaceable>bsp_root_name</replaceable>/recipes-core/* |
| meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/* |
| meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend |
| </literallayout> |
| </para> |
| |
| <para> |
| Below is an example of the Raspberry Pi BSP |
| layer that is available from the |
| <ulink url='&YOCTO_GIT_URL;'>Source Respositories</ulink>: |
| <literallayout class='monospaced'> |
| meta-raspberrypi/COPYING.MIT |
| meta-raspberrypi/README.md |
| meta-raspberrypi/classes |
| meta-raspberrypi/classes/sdcard_image-rpi.bbclass |
| meta-raspberrypi/conf/ |
| meta-raspberrypi/conf/layer.conf |
| meta-raspberrypi/conf/machine/ |
| meta-raspberrypi/conf/machine/raspberrypi-cm.conf |
| meta-raspberrypi/conf/machine/raspberrypi-cm3.conf |
| meta-raspberrypi/conf/machine/raspberrypi.conf |
| meta-raspberrypi/conf/machine/raspberrypi0-wifi.conf |
| meta-raspberrypi/conf/machine/raspberrypi0.conf |
| meta-raspberrypi/conf/machine/raspberrypi2.conf |
| meta-raspberrypi/conf/machine/raspberrypi3-64.conf |
| meta-raspberrypi/conf/machine/raspberrypi3.conf |
| meta-raspberrypi/conf/machine/include |
| meta-raspberrypi/conf/machine/include/rpi-base.inc |
| meta-raspberrypi/conf/machine/include/rpi-default-providers.inc |
| meta-raspberrypi/conf/machine/include/rpi-default-settings.inc |
| meta-raspberrypi/conf/machine/include/rpi-default-versions.inc |
| meta-raspberrypi/conf/machine/include/tune-arm1176jzf-s.inc |
| meta-raspberrypi/docs |
| meta-raspberrypi/docs/Makefile |
| meta-raspberrypi/docs/conf.py |
| meta-raspberrypi/docs/contributing.md |
| meta-raspberrypi/docs/extra-apps.md |
| meta-raspberrypi/docs/extra-build-config.md |
| meta-raspberrypi/docs/index.rst |
| meta-raspberrypi/docs/layer-contents.md |
| meta-raspberrypi/docs/readme.md |
| meta-raspberrypi/files |
| meta-raspberrypi/files/custom-licenses |
| meta-raspberrypi/files/custom-licenses/Broadcom |
| meta-raspberrypi/recipes-bsp |
| meta-raspberrypi/recipes-bsp/bootfiles |
| meta-raspberrypi/recipes-bsp/bootfiles/bcm2835-bootfiles.bb |
| meta-raspberrypi/recipes-bsp/bootfiles/rpi-config_git.bb |
| meta-raspberrypi/recipes-bsp/common |
| meta-raspberrypi/recipes-bsp/common/firmware.inc |
| meta-raspberrypi/recipes-bsp/formfactor |
| meta-raspberrypi/recipes-bsp/formfactor/formfactor |
| meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi |
| meta-raspberrypi/recipes-bsp/formfactor/formfactor/raspberrypi/machconfig |
| meta-raspberrypi/recipes-bsp/formfactor/formfactor_0.0.bbappend |
| meta-raspberrypi/recipes-bsp/rpi-u-boot-src |
| meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files |
| meta-raspberrypi/recipes-bsp/rpi-u-boot-src/files/boot.cmd.in |
| meta-raspberrypi/recipes-bsp/rpi-u-boot-src/rpi-u-boot-scr.bb |
| meta-raspberrypi/recipes-bsp/u-boot |
| meta-raspberrypi/recipes-bsp/u-boot/u-boot |
| meta-raspberrypi/recipes-bsp/u-boot/u-boot/*.patch |
| meta-raspberrypi/recipes-bsp/u-boot/u-boot_%.bbappend |
| meta-raspberrypi/recipes-connectivity |
| meta-raspberrypi/recipes-connectivity/bluez5 |
| meta-raspberrypi/recipes-connectivity/bluez5/bluez5 |
| meta-raspberrypi/recipes-connectivity/bluez5/bluez5/*.patch |
| meta-raspberrypi/recipes-connectivity/bluez5/bluez5/BCM43430A1.hcd |
| meta-raspberrypi/recipes-connectivity/bluez5/bluez5brcm43438.service |
| meta-raspberrypi/recipes-connectivity/bluez5/bluez5_%.bbappend |
| meta-raspberrypi/recipes-core |
| meta-raspberrypi/recipes-core/images |
| meta-raspberrypi/recipes-core/images/rpi-basic-image.bb |
| meta-raspberrypi/recipes-core/images/rpi-hwup-image.bb |
| meta-raspberrypi/recipes-core/images/rpi-test-image.bb |
| meta-raspberrypi/recipes-core/packagegroups |
| meta-raspberrypi/recipes-core/packagegroups/packagegroup-rpi-test.bb |
| meta-raspberrypi/recipes-core/psplash |
| meta-raspberrypi/recipes-core/psplash/files |
| meta-raspberrypi/recipes-core/psplash/files/psplash-raspberrypi-img.h |
| meta-raspberrypi/recipes-core/psplash/psplash_git.bbappend |
| meta-raspberrypi/recipes-core/udev |
| meta-raspberrypi/recipes-core/udev/udev-rules-rpi |
| meta-raspberrypi/recipes-core/udev/udev-rules-rpi/99-com.rules |
| meta-raspberrypi/recipes-core/udev/udev-rules-rpi.bb |
| meta-raspberrypi/recipes-devtools |
| meta-raspberrypi/recipes-devtools/bcm2835 |
| meta-raspberrypi/recipes-devtools/bcm2835/bcm2835_1.52.bb |
| meta-raspberrypi/recipes-devtools/pi-blaster |
| meta-raspberrypi/recipes-devtools/pi-blaster/files |
| meta-raspberrypi/recipes-devtools/pi-blaster/files/*.patch |
| meta-raspberrypi/recipes-devtools/pi-blaster/pi-blaster_git.bb |
| meta-raspberrypi/recipes-devtools/python |
| meta-raspberrypi/recipes-devtools/python/python-rtimu |
| meta-raspberrypi/recipes-devtools/python/python-rtimu/*.patch |
| meta-raspberrypi/recipes-devtools/python/python-rtimu_git.bb |
| meta-raspberrypi/recipes-devtools/python/python-sense-hat_2.2.0.bb |
| meta-raspberrypi/recipes-devtools/python/rpi-gpio |
| meta-raspberrypi/recipes-devtools/python/rpi-gpio/*.patch |
| meta-raspberrypi/recipes-devtools/python/rpi-gpio_0.6.3.bb |
| meta-raspberrypi/recipes-devtools/python/rpio |
| meta-raspberrypi/recipes-devtools/python/rpio/*.patch |
| meta-raspberrypi/recipes-devtools/python/rpio_0.10.0.bb |
| meta-raspberrypi/recipes-devtools/wiringPi |
| meta-raspberrypi/recipes-devtools/wiringPi/files |
| meta-raspberrypi/recipes-devtools/wiringPi/files/*.patch |
| meta-raspberrypi/recipes-devtools/wiringPi/wiringpi_git.bb |
| meta-raspberrypi/recipes-graphics |
| meta-raspberrypi/recipes-graphics/eglinfo |
| meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-fb_%.bbappend |
| meta-raspberrypi/recipes-graphics/eglinfo/eglinfo-x11_%.bbappend |
| meta-raspberrypi/recipes-graphics/mesa |
| meta-raspberrypi/recipes-graphics/mesa/mesa-gl_%.bbappend |
| meta-raspberrypi/recipes-graphics/mesa/mesa_%.bbappend |
| meta-raspberrypi/recipes-graphics/userland |
| meta-raspberrypi/recipes-graphics/userland/userland |
| meta-raspberrypi/recipes-graphics/userland/userland/*.patch |
| meta-raspberrypi/recipes-graphics/userland/userland_git.bb |
| meta-raspberrypi/recipes-graphics/vc-graphics |
| meta-raspberrypi/recipes-graphics/vc-graphics/files |
| meta-raspberrypi/recipes-graphics/vc-graphics/files/egl.pc |
| meta-raspberrypi/recipes-graphics/vc-graphics/files/vchiq.sh |
| meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics-hardfp.bb |
| meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.bb |
| meta-raspberrypi/recipes-graphics/vc-graphics/vc-graphics.inc |
| meta-raspberrypi/recipes-graphics/wayland |
| meta-raspberrypi/recipes-graphics/wayland/weston_%.bbappend |
| meta-raspberrypi/recipes-graphics/xorg-xserver |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/10-evdev.conf |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/98-pitft.conf |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config/rpi/xorg.conf.d/99-calibration.conf |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend |
| meta-raspberrypi/recipes-graphics/xorg-xserver/xserver-xorg_%.bbappend |
| meta-raspberrypi/recipes-kernel |
| meta-raspberrypi/recipes-kernel/linux-firmware |
| meta-raspberrypi/recipes-kernel/linux-firmware/files |
| meta-raspberrypi/recipes-kernel/linux-firmware/files/brcmfmac43430-sdio.bin |
| meta-raspberrypi/recipes-kernel/linux-firmware/files/brcfmac43430-sdio.txt |
| meta-raspberrypi/recipes-kernel/linux-firmware/linux-firmware_%.bbappend |
| meta-raspberrypi/recipes-kernel/linux |
| meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi-dev.bb |
| meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi.inc |
| meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.14.bb |
| meta-raspberrypi/recipes-kernel/linux/linux-raspberrypi_4.9.bb |
| meta-raspberrypi/recipes-multimedia |
| meta-raspberrypi/recipes-multimedia/gstreamer |
| meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx |
| meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx/*.patch |
| meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx_%.bbappend |
| meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-plugins-bad_%.bbappend |
| meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12 |
| meta-raspberrypi/recipes-multimedia/gstreamer/gstreamer1.0-omx-1.12/*.patch |
| meta-raspberrypi/recipes-multimedia/omxplayer |
| meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer |
| meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer/*.patch |
| meta-raspberrypi/recipes-multimedia/omxplayer/omxplayer_git.bb |
| meta-raspberrypi/recipes-multimedia/x264 |
| meta-raspberrypi/recipes-multimedia/x264/x264_git.bbappend |
| meta-raspberrypi/wic |
| meta-raspberrypi/wic/sdimage-raspberrypi.wks |
| </literallayout> |
| </para> |
| |
| <para> |
| The following sections describe each part of the proposed |
| BSP format. |
| </para> |
| |
| <section id="bsp-filelayout-license"> |
| <title>License Files</title> |
| |
| <para> |
| You can find these files in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable> |
| </literallayout> |
| </para> |
| |
| <para> |
| These optional files satisfy licensing requirements |
| for the BSP. |
| The type or types of files here can vary depending |
| on the licensing requirements. |
| For example, in the Raspberry Pi BSP, all licensing |
| requirements are handled with the |
| <filename>COPYING.MIT</filename> file. |
| </para> |
| |
| <para> |
| Licensing files can be MIT, BSD, GPLv*, and so forth. |
| These files are recommended for the BSP but are |
| optional and totally up to the BSP developer. |
| For information on how to maintain license |
| compliance, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>" |
| section in the Yocto Project Development Tasks |
| Manual. |
| </para> |
| </section> |
| |
| <section id="bsp-filelayout-readme"> |
| <title>README File</title> |
| |
| <para> |
| You can find this file in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/README |
| </literallayout> |
| </para> |
| |
| <para> |
| This file provides information on how to boot the live |
| images that are optionally included in the |
| <filename>binary/</filename> directory. |
| The <filename>README</filename> file also provides |
| information needed for building the image. |
| </para> |
| |
| <para> |
| At a minimum, the <filename>README</filename> file must |
| contain a list of dependencies, such as the names of |
| any other layers on which the BSP depends and the name of |
| the BSP maintainer with his or her contact information. |
| </para> |
| </section> |
| |
| <section id="bsp-filelayout-readme-sources"> |
| <title>README.sources File</title> |
| |
| <para> |
| You can find this file in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/README.sources |
| </literallayout> |
| </para> |
| |
| <para> |
| This file provides information on where to locate the BSP |
| source files used to build the images (if any) that |
| reside in |
| <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>. |
| Images in the <filename>binary</filename> would be images |
| released with the BSP. |
| The information in the <filename>README.sources</filename> |
| file also helps you find the |
| <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink> |
| used to generate the images that ship with the BSP. |
| <note> |
| If the BSP's <filename>binary</filename> directory is |
| missing or the directory has no images, an existing |
| <filename>README.sources</filename> file is |
| meaningless and usually does not exist. |
| </note> |
| </para> |
| </section> |
| |
| <section id="bsp-filelayout-binary"> |
| <title>Pre-built User Binaries</title> |
| |
| <para> |
| You can find these files in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable> |
| </literallayout> |
| </para> |
| |
| <para> |
| This optional area contains useful pre-built kernels |
| and user-space filesystem images released with the |
| BSP that are appropriate to the target system. |
| This directory typically contains graphical (e.g. Sato) |
| and minimal live images when the BSP tarball has been |
| created and made available in the |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> |
| website. |
| You can use these kernels and images to get a system |
| running and quickly get started on development tasks. |
| </para> |
| |
| <para> |
| The exact types of binaries present are highly |
| hardware-dependent. |
| The |
| <link linkend='bsp-filelayout-readme'><filename>README</filename></link> |
| file should be present in the BSP Layer and it |
| explains how to use the images with the target hardware. |
| Additionally, the |
| <link linkend='bsp-filelayout-readme-sources'><filename>README.sources</filename></link> |
| file should be present to locate the sources used to |
| build the images and provide information on the |
| Metadata. |
| </para> |
| </section> |
| |
| <section id='bsp-filelayout-layer'> |
| <title>Layer Configuration File</title> |
| |
| <para> |
| You can find this file in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf |
| </literallayout> |
| </para> |
| |
| <para> |
| The <filename>conf/layer.conf</filename> file |
| identifies the file structure as a layer, |
| identifies the contents of the layer, and |
| contains information about how the build system should |
| use it. |
| Generally, a standard boilerplate file such as the |
| following works. |
| In the following example, you would replace |
| <replaceable>bsp</replaceable> with the actual |
| name of the BSP (i.e. |
| <replaceable>bsp_root_name</replaceable> from the example |
| template). |
| </para> |
| |
| <para> |
| <literallayout class='monospaced'> |
| # We have a conf and classes directory, add to BBPATH |
| BBPATH .= ":${LAYERDIR}" |
| |
| # We have a recipes directory, add to BBFILES |
| BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ |
| ${LAYERDIR}/recipes-*/*/*.bbappend" |
| |
| BBFILE_COLLECTIONS += "<replaceable>bsp</replaceable>" |
| BBFILE_PATTERN_<replaceable>bsp</replaceable> = "^${LAYERDIR}/" |
| BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6" |
| |
| LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel" |
| </literallayout> |
| </para> |
| |
| <para> |
| To illustrate the string substitutions, here are |
| the corresponding statements from the Raspberry |
| Pi <filename>conf/layer.conf</filename> file: |
| <literallayout class='monospaced'> |
| # We have a conf and classes directory, append to BBPATH |
| BBPATH .= ":${LAYERDIR}" |
| |
| # We have a recipes directory containing .bb and .bbappend files, add to BBFILES |
| BBFILES += "${LAYERDIR}/recipes*/*/*.bb \ |
| ${LAYERDIR}/recipes*/*/*.bbappend" |
| |
| BBFILE_COLLECTIONS += "raspberrypi" |
| BBFILE_PATTERN_raspberrypi := "^${LAYERDIR}/" |
| BBFILE_PRIORITY_raspberrypi = "9" |
| |
| # Additional license directories. |
| LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" |
| . |
| . |
| . |
| </literallayout> |
| </para> |
| |
| <para> |
| This file simply makes |
| <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink> |
| aware of the recipes and configuration directories. |
| The file must exist so that the OpenEmbedded build system |
| can recognize the BSP. |
| </para> |
| </section> |
| |
| <section id="bsp-filelayout-machine"> |
| <title>Hardware Configuration Options</title> |
| |
| <para> |
| You can find these files in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf |
| </literallayout> |
| </para> |
| |
| <para> |
| The machine files bind together all the information |
| contained elsewhere in the BSP into a format that |
| the build system can understand. |
| Each BSP Layer requires at least one machine file. |
| If the BSP supports multiple machines, multiple |
| machine configuration files can exist. |
| These filenames correspond to the values to which |
| users have set the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. |
| </para> |
| |
| <para> |
| These files define things such as the kernel package |
| to use |
| (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> |
| of |
| <ulink url='&YOCTO_DOCS_DEV_URL;#metadata-virtual-providers'>virtual/kernel</ulink>), |
| the hardware drivers to include in different types |
| of images, any special software components that are |
| needed, any bootloader information, and also any |
| special image format requirements. |
| </para> |
| |
| <para> |
| This configuration file could also include a hardware |
| "tuning" file that is commonly used to define the |
| package architecture and specify optimization flags, |
| which are carefully chosen to give best performance |
| on a given processor. |
| </para> |
| |
| <para> |
| Tuning files are found in the |
| <filename>meta/conf/machine/include</filename> |
| directory within the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. |
| For example, many <filename>tune-*</filename> files |
| (e.g. <filename>tune-arm1136jf-s.inc</filename>, |
| <filename>tune-1586-nlp.inc</filename>, and so forth) |
| reside in the |
| <filename>poky/meta/conf/machine/include</filename> |
| directory. |
| </para> |
| |
| <para> |
| To use an include file, you simply include them in the |
| machine configuration file. |
| For example, the Raspberry Pi BSP |
| <filename>raspberrypi3.conf</filename> contains the |
| following statement: |
| <literallayout class='monospaced'> |
| include conf/machine/include/rpi-base.inc |
| </literallayout> |
| </para> |
| </section> |
| |
| <section id='bsp-filelayout-misc-recipes'> |
| <title>Miscellaneous BSP-Specific Recipe Files</title> |
| |
| <para> |
| You can find these files in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/* |
| </literallayout> |
| </para> |
| |
| <para> |
| This optional directory contains miscellaneous recipe |
| files for the BSP. |
| Most notably would be the formfactor files. |
| For example, in the Raspberry Pi BSP, there is the |
| <filename>formfactor_0.0.bbappend</filename> file, |
| which is an append file used to augment the recipe |
| that starts the build. |
| Furthermore, there are machine-specific settings used |
| during the build that are defined by the |
| <filename>machconfig</filename> file further down in |
| the directory. |
| Here is the <filename>machconfig</filename> file for |
| the Raspberry Pi BSP: |
| <literallayout class='monospaced'> |
| HAVE_TOUCHSCREEN=0 |
| HAVE_KEYBOARD=1 |
| |
| DISPLAY_CAN_ROTATE=0 |
| DISPLAY_ORIENTATION=0 |
| DISPLAY_DPI=133 |
| </literallayout> |
| </para> |
| |
| <note><para> |
| If a BSP does not have a formfactor entry, defaults |
| are established according to the formfactor |
| configuration file that is installed by the main |
| formfactor recipe |
| <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, |
| which is found in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. |
| </para></note> |
| </section> |
| |
| <section id='bsp-filelayout-recipes-graphics'> |
| <title>Display Support Files</title> |
| |
| <para> |
| You can find these files in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/* |
| </literallayout> |
| </para> |
| |
| <para> |
| This optional directory contains recipes for the |
| BSP if it has special requirements for graphics |
| support. |
| All files that are needed for the BSP to support |
| a display are kept here. |
| </para> |
| </section> |
| |
| <section id='bsp-filelayout-kernel'> |
| <title>Linux Kernel Configuration</title> |
| |
| <para> |
| You can find these files in the BSP Layer at: |
| <literallayout class='monospaced'> |
| meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend |
| meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb |
| </literallayout> |
| </para> |
| |
| <para> |
| Append files (<filename>*.bbappend</filename>) modify |
| the main kernel recipe being used to build the image. |
| The <filename>*.bb</filename> files would be a |
| developer-supplied kernel recipe. |
| This area of the BSP hierarchy can contain both these |
| types of files although, in practice, it is likely that |
| you would have one or the other. |
| </para> |
| |
| <para> |
| For your BSP, you typically want to use an existing Yocto |
| Project kernel recipe found in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| at <filename>meta/recipes-kernel/linux</filename>. |
| You can append machine-specific changes to the |
| kernel recipe by using a similarly named append |
| file, which is located in the BSP Layer for your |
| target device (e.g. the |
| <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory). |
| </para> |
| |
| <para> |
| Suppose you are using the |
| <filename>linux-yocto_4.4.bb</filename> recipe to |
| build the kernel. |
| In other words, you have selected the kernel in your |
| <replaceable>bsp_root_name</replaceable><filename>.conf</filename> |
| file by adding |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> |
| and |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink> |
| statements as follows: |
| <literallayout class='monospaced'> |
| PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
| PREFERRED_VERSION_linux-yocto ?= "4.4%" |
| </literallayout> |
| <note> |
| When the preferred provider is assumed by |
| default, the |
| <filename>PREFERRED_PROVIDER</filename> |
| statement does not appear in the |
| <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file. |
| </note> |
| You would use the |
| <filename>linux-yocto_4.4.bbappend</filename> |
| file to append specific BSP settings to the kernel, |
| thus configuring the kernel for your particular BSP. |
| </para> |
| |
| <para> |
| You can find more information on what your append file |
| should contain in the |
| "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-the-append-file'>Creating the Append File</ulink>" |
| section in the Yocto Project Linux Kernel Development |
| Manual. |
| </para> |
| |
| <para> |
| An alternate scenario is when you create your own |
| kernel recipe for the BSP. |
| A good example of this is the Raspberry Pi BSP. |
| If you examine the |
| <filename>recipes-kernel/linux</filename> directory |
| you see the following: |
| <literallayout class='monospaced'> |
| linux-raspberrypi-dev.bb |
| linux-raspberrypi.inc |
| linux-raspberrypi_4.14.bb |
| linux-raspberrypi_4.9.bb |
| </literallayout> |
| The directory contains three kernel recipes and a |
| common include file. |
| </para> |
| </section> |
| </section> |
| |
| <section id='developing-a-board-support-package-bsp'> |
| <title>Developing a Board Support Package (BSP)</title> |
| |
| <para> |
| This section describes the high-level procedure you can |
| follow to create a BSP. |
| Although not required for BSP creation, the |
| <filename>meta-intel</filename> repository, which |
| contains many BSPs supported by the Yocto Project, |
| is part of the example. |
| </para> |
| |
| <para> |
| For an example that shows how to create a new |
| layer using the tools, see the |
| "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>" |
| section. |
| </para> |
| |
| <para> |
| The following illustration and list summarize the BSP |
| creation general workflow. |
| </para> |
| |
| <para> |
| <imagedata fileref="figures/bsp-dev-flow.png" width="7in" depth="5in" align="center" scalefit="1" /> |
| </para> |
| |
| <para> |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Set up Your Host Development System |
| to Support Development Using the Yocto |
| Project</emphasis>: |
| See the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-preparing-the-build-host'>Preparing the Build Host</ulink>" |
| section in the Yocto Project Development Tasks |
| Manual for options on how to get a system ready |
| to use the Yocto Project. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Establish the |
| <filename>meta-intel</filename> |
| Repository on Your System:</emphasis> |
| Having local copies of these supported BSP layers |
| on your system gives you access to layers you |
| might be able to leverage when creating your BSP. |
| For information on how to get these files, see the |
| "<link linkend='preparing-your-build-host-to-work-with-bsp-layers'>Preparing Your Build Host to Work with BSP Layers</link>" |
| section. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Create Your Own BSP Layer Using the |
| <filename>bitbake-layers</filename> |
| Script:</emphasis> |
| Layers are ideal for isolating and storing work |
| for a given piece of hardware. |
| A layer is really just a location or area in which you |
| place the recipes and configurations for your BSP. |
| In fact, a BSP is, in itself, a special type of layer. |
| The simplest way to create a new BSP layer that is |
| compliant with the Yocto Project is to use the |
| <filename>bitbake-layers</filename> script. |
| For information about that script, see the |
| "<link linkend='creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</link>" |
| section.</para> |
| |
| <para>Another example that illustrates a layer |
| is an application. |
| Suppose you are creating an application that has |
| library or other dependencies in order for it to |
| compile and run. |
| The layer, in this case, would be where all the |
| recipes that define those dependencies are kept. |
| The key point for a layer is that it is an |
| isolated area that contains all the relevant |
| information for the project that the |
| OpenEmbedded build system knows about. |
| For more information on layers, see the |
| "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>" |
| section in the Yocto Project Overview and Concepts |
| Manual. |
| You can also reference the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" |
| section in the Yocto Project Development Tasks |
| Manual. |
| For more information on BSP layers, see the |
| "<link linkend='bsp-layers'>BSP Layers</link>" |
| section. |
| <note><title>Notes</title> |
| <itemizedlist> |
| <listitem><para> |
| Five hardware reference BSPs exist |
| that are part of the Yocto Project release |
| and are located in the |
| <filename>poky/meta-yocto-bsp</filename> BSP |
| layer: |
| <itemizedlist> |
| <listitem><para> |
| Texas Instruments Beaglebone |
| (<filename>beaglebone-yocto</filename>) |
| </para></listitem> |
| <listitem><para> |
| Ubiquiti Networks EdgeRouter Lite |
| (<filename>edgerouter</filename>) |
| </para></listitem> |
| <listitem><para> |
| Two general IA platforms |
| (<filename>genericx86</filename> and |
| <filename>genericx86-64</filename>) |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| Three core Intel BSPs exist as part of |
| the Yocto Project release in the |
| <filename>meta-intel</filename> layer: |
| <itemizedlist> |
| <listitem><para> |
| <filename>intel-core2-32</filename>, |
| which is a BSP optimized for the Core2 |
| family of CPUs as well as all CPUs |
| prior to the Silvermont core. |
| </para></listitem> |
| <listitem><para> |
| <filename>intel-corei7-64</filename>, |
| which is a BSP optimized for Nehalem |
| and later Core and Xeon CPUs as well |
| as Silvermont and later Atom CPUs, |
| such as the Baytrail SoCs. |
| </para></listitem> |
| <listitem><para> |
| <filename>intel-quark</filename>, |
| which is a BSP optimized for the |
| Intel Galileo gen1 & gen2 |
| development boards. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| </itemizedlist> |
| </note></para> |
| |
| <para>When you set up a layer for a new BSP, |
| you should follow a standard layout. |
| This layout is described in the |
| "<link linkend='bsp-filelayout'>Example Filesystem Layout</link>" |
| section. |
| In the standard layout, notice the suggested |
| structure for recipes and configuration |
| information. |
| You can see the standard layout for a BSP |
| by examining any supported BSP found in the |
| <filename>meta-intel</filename> layer inside |
| the Source Directory. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Make Configuration Changes to Your New |
| BSP Layer:</emphasis> |
| The standard BSP layer structure organizes the |
| files you need to edit in |
| <filename>conf</filename> and several |
| <filename>recipes-*</filename> directories |
| within the BSP layer. |
| Configuration changes identify where your new |
| layer is on the local system and identifies the |
| kernel you are going to use. |
| When you run the |
| <filename>bitbake-layers</filename> script, |
| you are able to interactively configure many |
| things for the BSP (e.g. keyboard, touchscreen, |
| and so forth). |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Make Recipe Changes to Your New BSP |
| Layer:</emphasis> |
| Recipe changes include altering recipes |
| (<filename>*.bb</filename> files), removing |
| recipes you do not use, and adding new recipes |
| or append files (<filename>.bbappend</filename>) |
| that support your hardware. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Prepare for the Build:</emphasis> |
| Once you have made all the changes to your BSP |
| layer, there remains a few things you need to |
| do for the OpenEmbedded build system in order |
| for it to create your image. |
| You need to get the build environment ready by |
| sourcing an environment setup script |
| (i.e. <filename>oe-init-build-env</filename>) |
| and you need to be sure two key configuration |
| files are configured appropriately: the |
| <filename>conf/local.conf</filename> and the |
| <filename>conf/bblayers.conf</filename> file. |
| You must make the OpenEmbedded build system aware |
| of your new layer. |
| See the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>" |
| section in the Yocto Project Development Tasks Manual |
| for information on how to let the build system |
| know about your new layer. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Build the Image:</emphasis> |
| The OpenEmbedded build system uses the BitBake tool |
| to build images based on the type of image you want to |
| create. |
| You can find more information about BitBake in the |
| <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. |
| </para> |
| |
| <para>The build process supports several types of |
| images to satisfy different needs. |
| See the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" |
| chapter in the Yocto Project Reference Manual for |
| information on supported images. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='requirements-and-recommendations-for-released-bsps'> |
| <title>Requirements and Recommendations for Released BSPs</title> |
| |
| <para> |
| Certain requirements exist for a released BSP to be |
| considered compliant with the Yocto Project. |
| Additionally, recommendations also exist. |
| This section describes the requirements and |
| recommendations for released BSPs. |
| </para> |
| |
| <section id='released-bsp-requirements'> |
| <title>Released BSP Requirements</title> |
| |
| <para> |
| Before looking at BSP requirements, you should consider |
| the following: |
| <itemizedlist> |
| <listitem><para> |
| The requirements here assume the BSP layer |
| is a well-formed, "legal" layer that can be |
| added to the Yocto Project. |
| For guidelines on creating a layer that meets |
| these base requirements, see the |
| "<link linkend='bsp-layers'>BSP Layers</link>" |
| section in this manual and the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers"</ulink>" |
| section in the Yocto Project Development Tasks |
| Manual. |
| </para></listitem> |
| <listitem><para> |
| The requirements in this section apply |
| regardless of how you package a BSP. |
| You should consult the packaging and distribution |
| guidelines for your specific release process. |
| For an example of packaging and distribution |
| requirements, see the |
| "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>" |
| wiki page. |
| </para></listitem> |
| <listitem><para> |
| The requirements for the BSP as it is made |
| available to a developer are completely |
| independent of the released form of the BSP. |
| For example, the BSP Metadata can be contained |
| within a Git repository and could have a directory |
| structure completely different from what appears |
| in the officially released BSP layer. |
| </para></listitem> |
| <listitem><para> |
| It is not required that specific packages or |
| package modifications exist in the BSP layer, |
| beyond the requirements for general |
| compliance with the Yocto Project. |
| For example, no requirement exists dictating |
| that a specific kernel or kernel version be |
| used in a given BSP. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| Following are the requirements for a released BSP |
| that conform to the Yocto Project: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Layer Name:</emphasis> |
| The BSP must have a layer name that follows |
| the Yocto Project standards. |
| For information on BSP layer names, see the |
| "<link linkend='bsp-layers'>BSP Layers</link>" section. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>File System Layout:</emphasis> |
| When possible, use the same directory names |
| in your BSP layer as listed in the |
| <filename>recipes.txt</filename> file, which |
| is found in <filename>poky/meta</filename> |
| directory of the |
| <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> |
| or in the OpenEmbedded-Core Layer |
| (<filename>openembedded-core</filename>) at |
| <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>. |
| </para> |
| |
| <para>You should place recipes |
| (<filename>*.bb</filename> files) and recipe |
| modifications (<filename>*.bbappend</filename> |
| files) into <filename>recipes-*</filename> |
| subdirectories by functional area as outlined |
| in <filename>recipes.txt</filename>. |
| If you cannot find a category in |
| <filename>recipes.txt</filename> to fit a |
| particular recipe, you can make up your own |
| <filename>recipes-*</filename> subdirectory. |
| </para> |
| |
| <para>Within any particular |
| <filename>recipes-*</filename> category, the |
| layout should match what is found in the |
| OpenEmbedded-Core Git repository |
| (<filename>openembedded-core</filename>) |
| or the Source Directory (<filename>poky</filename>). |
| In other words, make sure you place related |
| files in appropriately-related |
| <filename>recipes-*</filename> subdirectories |
| specific to the recipe's function, or within |
| a subdirectory containing a set of closely-related |
| recipes. |
| The recipes themselves should follow the general |
| guidelines for recipes used in the Yocto Project |
| found in the |
| "<ulink url='http://openembedded.org/wiki/Styleguide'>OpenEmbedded Style Guide</ulink>". |
| </para></listitem> |
| <listitem><para> |
| <emphasis>License File:</emphasis> |
| You must include a license file in the |
| <filename>meta-</filename><replaceable>bsp_root_name</replaceable> |
| directory. |
| This license covers the BSP Metadata as a whole. |
| You must specify which license to use since no |
| default license exists when one is not specified. |
| See the |
| <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/COPYING.MIT'><filename>COPYING.MIT</filename></ulink> |
| file for the Raspberry Pi BSP in the |
| <filename>meta-raspberrypi</filename> BSP layer |
| as an example. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>README File:</emphasis> |
| You must include a <filename>README</filename> |
| file in the |
| <filename>meta-</filename><replaceable>bsp_root_name</replaceable> |
| directory. |
| See the |
| <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README.md'><filename>README.md</filename></ulink> |
| file for the Raspberry Pi BSP in the |
| <filename>meta-raspberrypi</filename> BSP layer |
| as an example.</para> |
| |
| <para>At a minimum, the <filename>README</filename> |
| file should contain the following: |
| <itemizedlist> |
| <listitem><para> |
| A brief description of the target hardware. |
| </para></listitem> |
| <listitem><para> |
| A list of all the dependencies of the BSP. |
| These dependencies are typically a list |
| of required layers needed to build the |
| BSP. |
| However, the dependencies should also |
| contain information regarding any other |
| dependencies the BSP might have. |
| </para></listitem> |
| <listitem><para> |
| Any required special licensing information. |
| For example, this information includes |
| information on special variables needed |
| to satisfy a EULA, or instructions on |
| information needed to build or distribute |
| binaries built from the BSP Metadata. |
| </para></listitem> |
| <listitem><para> |
| The name and contact information for the |
| BSP layer maintainer. |
| This is the person to whom patches and |
| questions should be sent. |
| For information on how to find the right |
| person, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>Submitting a Change to the Yocto Project</ulink>" |
| section in the Yocto Project Development |
| Tasks Manual. |
| </para></listitem> |
| <listitem><para> |
| Instructions on how to build the BSP using |
| the BSP layer. |
| </para></listitem> |
| <listitem><para> |
| Instructions on how to boot the BSP build |
| from the BSP layer. |
| </para></listitem> |
| <listitem><para> |
| Instructions on how to boot the binary |
| images contained in the |
| <filename>binary</filename> directory, |
| if present. |
| </para></listitem> |
| <listitem><para> |
| Information on any known bugs or issues |
| that users should know about when either |
| building or booting the BSP binaries. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>README.sources File:</emphasis> |
| If you BSP contains binary images in the |
| <filename>binary</filename> directory, you must |
| include a <filename>README.sources</filename> |
| file in the |
| <filename>meta-</filename><replaceable>bsp_root_name</replaceable> |
| directory. |
| This file specifies exactly where you can find |
| the sources used to generate the binary images. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Layer Configuration File:</emphasis> |
| You must include a |
| <filename>conf/layer.conf</filename> file in |
| the |
| <filename>meta-</filename><replaceable>bsp_root_name</replaceable> |
| directory. |
| This file identifies the |
| <filename>meta-</filename><replaceable>bsp_root_name</replaceable> |
| BSP layer as a layer to the build system. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Machine Configuration File:</emphasis> |
| You must include one or more |
| <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename> |
| files in the |
| <filename>meta-</filename><replaceable>bsp_root_name</replaceable> |
| directory. |
| These configuration files define machine targets |
| that can be built using the BSP layer. |
| Multiple machine configuration files define |
| variations of machine configurations that the |
| BSP supports. |
| If a BSP supports multiple machine variations, |
| you need to adequately describe each variation |
| in the BSP <filename>README</filename> file. |
| Do not use multiple machine configuration files |
| to describe disparate hardware. |
| If you do have very different targets, you should |
| create separate BSP layers for each target. |
| <note> |
| It is completely possible for a developer to |
| structure the working repository as a |
| conglomeration of unrelated BSP files, and to |
| possibly generate BSPs targeted for release |
| from that directory using scripts or some |
| other mechanism |
| (e.g. <filename>meta-yocto-bsp</filename> layer). |
| Such considerations are outside the scope of |
| this document. |
| </note> |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='released-bsp-recommendations'> |
| <title>Released BSP Recommendations</title> |
| |
| <para> |
| Following are recommendations for released BSPs that |
| conform to the Yocto Project: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Bootable Images:</emphasis> |
| Released BSPs can contain one or more bootable |
| images. |
| Including bootable images allows users to easily |
| try out the BSP using their own hardware.</para> |
| |
| <para>In some cases, it might not be convenient |
| to include a bootable image. |
| If so, you might want to make two versions of the |
| BSP available: one that contains binary images, and |
| one that does not. |
| The version that does not contain bootable images |
| avoids unnecessary download times for users not |
| interested in the images.</para> |
| |
| <para>If you need to distribute a BSP and include |
| bootable images or build kernel and filesystems |
| meant to allow users to boot the BSP for evaluation |
| purposes, you should put the images and artifacts |
| within a |
| <filename>binary/</filename> subdirectory located |
| in the |
| <filename>meta-</filename><replaceable>bsp_root_name</replaceable> |
| directory. |
| <note> |
| If you do include a bootable image as part |
| of the BSP and the image was built by software |
| covered by the GPL or other open source licenses, |
| it is your responsibility to understand |
| and meet all licensing requirements, which could |
| include distribution of source files. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Use a Yocto Linux Kernel:</emphasis> |
| Kernel recipes in the BSP should be based on a |
| Yocto Linux kernel. |
| Basing your recipes on these kernels reduces |
| the costs for maintaining the BSP and increases |
| its scalability. |
| See the <filename>Yocto Linux Kernel</filename> |
| category in the |
| <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> |
| for these kernels. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| </section> |
| |
| <section id='customizing-a-recipe-for-a-bsp'> |
| <title>Customizing a Recipe for a BSP</title> |
| |
| <para> |
| If you plan on customizing a recipe for a particular BSP, |
| you need to do the following: |
| <itemizedlist> |
| <listitem><para> |
| Create a <filename>*.bbappend</filename> file for |
| the modified recipe. |
| For information on using append files, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files in Your Layer</ulink>" |
| section in the Yocto Project Development Tasks |
| Manual. |
| </para></listitem> |
| <listitem><para> |
| Ensure your directory structure in the BSP layer |
| that supports your machine is such that the |
| OpenEmbedded build system can find it. |
| See the example later in this section for more |
| information. |
| </para></listitem> |
| <listitem><para> |
| Put the append file in a directory whose name matches |
| the machine's name and is located in an appropriate |
| sub-directory inside the BSP layer (i.e. |
| <filename>recipes-bsp</filename>, |
| <filename>recipes-graphics</filename>, |
| <filename>recipes-core</filename>, and so forth). |
| </para></listitem> |
| <listitem><para> |
| Place the BSP-specific files in the proper |
| directory inside the BSP layer. |
| How expansive the layer is affects where you must |
| place these files. |
| For example, if your layer supports several |
| different machine types, you need to be sure your |
| layer's directory structure includes hierarchy |
| that separates the files according to machine. |
| If your layer does not support multiple machines, |
| the layer would not have that additional hierarchy |
| and the files would obviously not be able to reside |
| in a machine-specific directory. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| Following is a specific example to help you better understand |
| the process. |
| This example customizes customizes a recipe by adding a |
| BSP-specific configuration file named |
| <filename>interfaces</filename> to the |
| <filename>init-ifupdown_1.0.bb</filename> recipe for machine |
| "xyz" where the BSP layer also supports several other |
| machines: |
| <orderedlist> |
| <listitem><para> |
| Edit the |
| <filename>init-ifupdown_1.0.bbappend</filename> file |
| so that it contains the following: |
| <literallayout class='monospaced'> |
| FILESEXTRAPATHS_prepend := "${THISDIR}/files:" |
| </literallayout> |
| The append file needs to be in the |
| <filename>meta-xyz/recipes-core/init-ifupdown</filename> |
| directory. |
| </para></listitem> |
| <listitem><para> |
| Create and place the new |
| <filename>interfaces</filename> configuration file in |
| the BSP's layer here: |
| <literallayout class='monospaced'> |
| meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces |
| </literallayout> |
| <note> |
| If the <filename>meta-xyz</filename> layer did |
| not support multiple machines, you would place |
| the <filename>interfaces</filename> configuration |
| file in the layer here: |
| <literallayout class='monospaced'> |
| meta-xyz/recipes-core/init-ifupdown/files/interfaces |
| </literallayout> |
| </note> |
| The |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> |
| variable in the append files extends the search path |
| the build system uses to find files during the build. |
| Consequently, for this example you need to have the |
| <filename>files</filename> directory in the same |
| location as your append file. |
| </para></listitem> |
| </orderedlist> |
| </para> |
| </section> |
| |
| <section id='bsp-licensing-considerations'> |
| <title>BSP Licensing Considerations</title> |
| |
| <para> |
| In some cases, a BSP contains separately-licensed |
| Intellectual Property (IP) for a component or components. |
| For these cases, you are required to accept the terms |
| of a commercial or other type of license that requires |
| some kind of explicit End User License Agreement (EULA). |
| Once you accept the license, the OpenEmbedded build system |
| can then build and include the corresponding component |
| in the final BSP image. |
| If the BSP is available as a pre-built image, you can |
| download the image after agreeing to the license or EULA. |
| </para> |
| |
| <para> |
| You could find that some separately-licensed components |
| that are essential for normal operation of the system might |
| not have an unencumbered (or free) substitute. |
| Without these essential components, the system would be |
| non-functional. |
| Then again, you might find that other licensed components |
| that are simply 'good-to-have' or purely elective do have |
| an unencumbered, free replacement component that you can |
| use rather than agreeing to the separately-licensed |
| component. |
| Even for components essential to the system, you might |
| find an unencumbered component that is not identical but |
| will work as a less-capable version of the licensed version |
| in the BSP recipe. |
| </para> |
| |
| <para> |
| For cases where you can substitute a free component and |
| still maintain the system's functionality, the "DOWNLOADS" |
| selection from the "SOFTWARE" tab on the |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink> |
| makes available de-featured BSPs that are completely free |
| of any IP encumbrances. |
| For these cases, you can use the substitution directly and |
| without any further licensing requirements. |
| If present, these fully de-featured BSPs are named |
| appropriately different as compared to the names of their |
| respective encumbered BSPs. |
| If available, these substitutions are your simplest and |
| most preferred options. |
| Obviously, use of these substitutions assumes the resulting |
| functionality meets system requirements. |
| <note> |
| If however, a non-encumbered version is unavailable or |
| it provides unsuitable functionality or quality, you can |
| use an encumbered version. |
| </note> |
| </para> |
| |
| <para> |
| A couple different methods exist within the OpenEmbedded |
| build system to satisfy the licensing requirements for an |
| encumbered BSP. |
| The following list describes them in order of preference: |
| <orderedlist> |
| <listitem><para> |
| <emphasis>Use the |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink> |
| Variable to Define the Recipes that Have Commercial |
| or Other Types of Specially-Licensed Packages:</emphasis> |
| For each of those recipes, you can specify a |
| matching license string in a |
| <filename>local.conf</filename> variable named |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>. |
| Specifying the matching license string signifies |
| that you agree to the license. |
| Thus, the build system can build the corresponding |
| recipe and include the component in the image. |
| See the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-commercially-licensed-recipes'>Enabling Commercially Licensed Recipes</ulink>" |
| section in the Yocto Project Development Tasks |
| Manual for details on how to use these variables. |
| </para> |
| |
| <para>If you build as you normally would, without |
| specifying any recipes in the |
| <filename>LICENSE_FLAGS_WHITELIST</filename>, the |
| build stops and provides you with the list of recipes |
| that you have tried to include in the image that |
| need entries in the |
| <filename>LICENSE_FLAGS_WHITELIST</filename>. |
| Once you enter the appropriate license flags into |
| the whitelist, restart the build to continue where |
| it left off. |
| During the build, the prompt will not appear again |
| since you have satisfied the requirement.</para> |
| |
| <para>Once the appropriate license flags are on the |
| white list in the |
| <filename>LICENSE_FLAGS_WHITELIST</filename> variable, |
| you can build the encumbered image with no change |
| at all to the normal build process. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Get a Pre-Built Version of the BSP:</emphasis> |
| You can get this type of BSP by selecting the |
| "DOWNLOADS" item from the "SOFTWARE" tab on the |
| <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>. |
| You can download BSP tarballs that contain |
| proprietary components after agreeing to the |
| licensing requirements of each of the individually |
| encumbered packages as part of the download process. |
| Obtaining the BSP this way allows you to access an |
| encumbered image immediately after agreeing to the |
| click-through license agreements presented by the |
| website. |
| If you want to build the image yourself using |
| the recipes contained within the BSP tarball, |
| you will still need to create an appropriate |
| <filename>LICENSE_FLAGS_WHITELIST</filename> |
| to match the encumbered recipes in the BSP. |
| </para></listitem> |
| </orderedlist> |
| <note> |
| Pre-compiled images are bundled with a time-limited |
| kernel that runs for a predetermined amount of time |
| (10 days) before it forces the system to reboot. |
| This limitation is meant to discourage direct |
| redistribution of the image. |
| You must eventually rebuild the image if you want |
| to remove this restriction. |
| </note> |
| </para> |
| </section> |
| |
| <section id='creating-a-new-bsp-layer-using-the-bitbake-layers-script'> |
| <title>Creating a new BSP Layer Using the <filename>bitbake-layers</filename> Script</title> |
| |
| <para> |
| The <filename>bitbake-layers create-layer</filename> script |
| automates creating a BSP layer. |
| What makes a layer a "BSP layer" is the presence of at least one machine |
| configuration file. |
| Additionally, a BSP layer usually has a kernel recipe |
| or an append file that leverages off an existing kernel recipe. |
| The primary requirement, however, is the machine configuration. |
| </para> |
| |
| <para> |
| Use these steps to create a BSP layer: |
| <itemizedlist> |
| <listitem><para> |
| <emphasis>Create a General Layer:</emphasis> |
| Use the <filename>bitbake-layers</filename> script with the |
| <filename>create-layer</filename> subcommand to create a |
| new general layer. |
| For instructions on how to create a general layer using the |
| <filename>bitbake-layers</filename> script, see the |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</ulink>" |
| section in the Yocto Project Development Tasks Manual. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Create a Layer Configuration File:</emphasis> |
| Every layer needs a layer configuration file. |
| This configuration file establishes locations for the |
| layer's recipes, priorities for the layer, and so forth. |
| You can find examples of <filename>layer.conf</filename> |
| files in the Yocto Project |
| <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>. |
| To get examples of what you need in your configuration |
| file, locate a layer (e.g. "meta-ti") and examine the |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/layer.conf'></ulink> |
| file. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Create a Machine Configuration File:</emphasis> |
| Create a <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename> |
| file. |
| See |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf/machine'><filename>meta-yocto-bsp/conf/machine</filename></ulink> |
| for sample |
| <replaceable>bsp_root_name</replaceable><filename>.conf</filename> |
| files. |
| Other samples such as |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-ti/tree/conf/machine'><filename>meta-ti</filename></ulink> |
| and |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/conf/machine'><filename>meta-freescale</filename></ulink> |
| exist from other vendors that have more specific machine |
| and tuning examples. |
| </para></listitem> |
| <listitem><para> |
| <emphasis>Create a Kernel Recipe:</emphasis> |
| Create a kernel recipe in <filename>recipes-kernel/linux</filename> |
| by either using a kernel append file or a new custom kernel |
| recipe file (e.g. <filename>yocto-linux_4.12.bb</filename>). |
| The BSP layers mentioned in the previous step also contain different |
| kernel examples. |
| See the |
| "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#modifying-an-existing-recipe'>Modifying an Existing Recipe</ulink>" |
| section in the Yocto Project Linux Kernel Development Manual |
| for information on how to create a custom kernel. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| |
| <para> |
| The remainder of this section provides a description of |
| the Yocto Project reference BSP for Beaglebone, which |
| resides in the |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp'><filename>meta-yocto-bsp</filename></ulink> |
| layer. |
| </para> |
| |
| <section id='bsp-layer-configuration-example'> |
| <title>BSP Layer Configuration Example</title> |
| |
| <para> |
| The layer's <filename>conf</filename> directory |
| contains the <filename>layer.conf</filename> |
| configuration file. |
| In this example, the |
| <filename>conf/layer.conf</filename> is the |
| following: |
| <literallayout class='monospaced'> |
| # We have a conf and classes directory, add to BBPATH |
| BBPATH .= ":${LAYERDIR}" |
| |
| # We have recipes-* directories, add to BBFILES |
| BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ |
| ${LAYERDIR}/recipes-*/*/*.bbappend" |
| |
| BBFILE_COLLECTIONS += "yoctobsp" |
| BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/" |
| BBFILE_PRIORITY_yoctobsp = "5" |
| LAYERVERSION_yoctobsp = "4" |
| LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;" |
| </literallayout> |
| The variables used in this file configure the |
| layer. |
| A good way to learn about layer configuration |
| files is to examine various files for BSP from |
| the |
| <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink>. |
| </para> |
| |
| <para> |
| For a detailed description of this particular |
| layer configuration file, see |
| "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-layer-config-file-description'>step 3</ulink> |
| in the discussion that describes how to create |
| layers in the Yocto Project Development Tasks Manual. |
| </para> |
| </section> |
| |
| <section id='bsp-machine-configuration-example'> |
| <title>BSP Machine Configuration Example</title> |
| |
| <para> |
| As mentioned earlier in this section, the existence |
| of a machine configuration file is what makes a |
| layer a BSP layer as compared to a general or |
| kernel layer. |
| </para> |
| |
| <para> |
| One or more machine configuration files exist in the |
| <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename> |
| directory of the layer: |
| <literallayout class='monospaced'> |
| <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine1</replaceable><filename>.conf</filename> |
| <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine2</replaceable><filename>.conf</filename> |
| <replaceable>bsp_layer</replaceable><filename>/conf/machine/</filename><replaceable>machine3</replaceable><filename>.conf</filename> |
| ... more ... |
| </literallayout> |
| For example, the machine configuration file for the |
| <ulink url='http://beagleboard.org/bone'>BeagleBone and BeagleBone Black development boards</ulink> |
| is located in the layer |
| <filename>poky/meta-yocto-bsp/conf/machine</filename> |
| and is named <filename>beaglebone-yocto.conf</filename>: |
| <literallayout class='monospaced'> |
| #@TYPE: Machine |
| #@NAME: Beaglebone-yocto machine |
| #@DESCRIPTION: Reference machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards |
| |
| PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg" |
| XSERVER ?= "xserver-xorg \ |
| xf86-video-modesetting \ |
| " |
| |
| MACHINE_EXTRA_RRECOMMENDS = "kernel-modules kernel-devicetree" |
| |
| EXTRA_IMAGEDEPENDS += "u-boot" |
| |
| DEFAULTTUNE ?= "cortexa8hf-neon" |
| include conf/machine/include/tune-cortexa8.inc |
| |
| IMAGE_FSTYPES += "tar.bz2 jffs2 wic wic.bmap" |
| EXTRA_IMAGECMD_jffs2 = "-lnp " |
| WKS_FILE ?= "beaglebone-yocto.wks" |
| IMAGE_INSTALL_append = " kernel-devicetree kernel-image-zimage" |
| do_image_wic[depends] += "mtools-native:do_populate_sysroot dosfstools-native:do_populate_sysroot" |
| |
| SERIAL_CONSOLES ?= "115200;ttyS0 115200;ttyO0" |
| SERIAL_CONSOLES_CHECK = "${SERIAL_CONSOLES}" |
| |
| PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
| PREFERRED_VERSION_linux-yocto ?= "5.0%" |
| |
| KERNEL_IMAGETYPE = "zImage" |
| KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" |
| KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}" |
| |
| SPL_BINARY = "MLO" |
| UBOOT_SUFFIX = "img" |
| UBOOT_MACHINE = "am335x_evm_defconfig" |
| UBOOT_ENTRYPOINT = "0x80008000" |
| UBOOT_LOADADDRESS = "0x80008000" |
| |
| MACHINE_FEATURES = "usbgadget usbhost vfat alsa" |
| |
| IMAGE_BOOT_FILES ?= "u-boot.${UBOOT_SUFFIX} MLO zImage am335x-bone.dtb am335x-boneblack.dtb am335x-bonegreen.dtb" |
| </literallayout> |
| The variables used to configure the machine define |
| machine-specific properties; |
| for example, machine-dependent packages, machine |
| tunings, the type of kernel to build, and |
| U-Boot configurations. |
| </para> |
| |
| <para> |
| The following list provides some explanation |
| for the statements found in the example reference |
| machine configuration file for the BeagleBone |
| development boards. |
| Realize that much more can be defined as part of |
| a machine's configuration file. |
| In general, you can learn about related variables |
| that this example does not have by locating the |
| variables in the |
| "<ulink url='&YOCTO_DOCS_REF_URL;#ref-variables-glos'>Yocto Project Variables Glossary</ulink>" |
| in the Yocto Project Reference Manual. |
| <itemizedlist> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/xserver</filename></ulink>: |
| The recipe that provides "virtual/xserver" when |
| more than one provider is found. |
| In this case, the recipe that provides |
| "virtual/xserver" is "xserver-xorg", which |
| exists in |
| <filename>poky/meta/recipes-graphics/xorg-xserver</filename>. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>: |
| The packages that should be installed to provide |
| an X server and drivers for the machine. |
| In this example, the "xserver-xorg" and |
| "xf86-video-modesetting" are installed. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>: |
| A list of machine-dependent packages |
| not essential for booting the image. |
| Thus, the build does not fail if the packages |
| do not exist. |
| However, the packages are required for a |
| fully-featured image. |
| <note><title>Tip</title> |
| Many <filename>MACHINE*</filename> variables |
| exist that help you configure a particular |
| piece of hardware. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGEDEPENDS'><filename>EXTRA_IMAGEDEPENDS</filename></ulink>: |
| Recipes to build that do not provide packages |
| for installing into the root filesystem |
| but building the image depends on the |
| recipes. |
| Sometimes a recipe is required to build |
| the final image but is not needed in the |
| root filesystem. |
| In this case, the U-Boot recipe must be |
| built for the image. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>: |
| Machines use tunings to optimize machine, |
| CPU, and application performance. |
| These features, which are collectively known |
| as "tuning features", exist in the |
| <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink> |
| layer (e.g. |
| <filename>poky/meta/conf/machine/include</filename>). |
| In this example, the default tunning file is |
| "cortexa8hf-neon". |
| <note> |
| The <filename>include</filename> statement |
| that pulls in the |
| <filename>conf/machine/include/tune-cortexa8.inc</filename> |
| file provides many tuning possibilities. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>: |
| The formats the OpenEmbedded build system |
| uses during the build when creating the |
| root filesystem. |
| In this example, four types of images are |
| supported. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGECMD'><filename>EXTRA_IMAGECMD</filename></ulink>: |
| Specifies additional options for image |
| creation commands. |
| In this example, the "-lnp " option is used |
| when creating the |
| <ulink url='https://en.wikipedia.org/wiki/JFFS2'>JFFS2</ulink> |
| image. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE'><filename>WKS_FILE</filename></ulink>: |
| The location of the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>Wic kickstart</ulink> |
| file used by the OpenEmbedded build system to |
| create a partitioned image (image.wic). |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>: |
| Specifies packages to install into an image |
| through the |
| <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink> |
| class. |
| Recipes use the <filename>IMAGE_INSTALL</filename> |
| variable. |
| </para></listitem> |
| <listitem><para> |
| <filename>do_image_wic[depends]</filename>: |
| A task that is constructed during the build. |
| In this example, the task depends on specific tools |
| in order to create the sysroot when buiding a Wic |
| image. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>: |
| Defines a serial console (TTY) to enable using |
| getty. |
| In this case, the baud rate is "115200" and the |
| device name is "ttyO0". |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER_virtual/kernel</filename></ulink>: |
| Specifies the recipe that provides |
| "virtual/kernel" when more than one provider |
| is found. |
| In this case, the recipe that provides |
| "virtual/kernel" is "linux-yocto", which |
| exists in the layer's |
| <filename>recipes-kernel/linux</filename> directory. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION_linux-yocto</filename></ulink>: |
| Defines the version of the recipe used |
| to build the kernel, which is "5.0" in this |
| case. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></ulink>: |
| The type of kernel to build for the device. |
| In this case, the OpenEmbedded build system |
| creates a "zImage" image type. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_DEVICETREE'><filename>KERNEL_DEVICETREE</filename></ulink>: |
| The names of the generated Linux kernel device |
| trees (i.e. the <filename>*.dtb</filename>) files. |
| All the device trees for the various BeagleBone |
| devices are included. |
| <!-- |
| You have to include some *.inc files according to the definition of KERNEL_DEVICETREE. |
| I don't see where these are being provided. |
| --> |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_EXTRA_ARGS'><filename>KERNEL_EXTRA_ARGS</filename></ulink>: |
| Additional <filename>make</filename> |
| command-line arguments the OpenEmbedded build |
| system passes on when compiling the kernel. |
| In this example, "LOADADDR=${UBOOT_ENTRYPOINT}" |
| is passed as a command-line argument. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SPL_BINARY'><filename>SPL_BINARY</filename></ulink>: |
| Defines the Secondary Program Loader (SPL) binary |
| type. |
| In this case, the SPL binary is set to |
| "MLO", which stands for Multimedia card LOader. |
| </para> |
| |
| <para>The BeagleBone development board requires an |
| SPL to boot and that SPL file type must be MLO. |
| Consequently, the machine configuration needs to |
| define <filename>SPL_BINARY</filename> as "MLO". |
| <note> |
| For more information on how the SPL variables |
| are used, see the |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-bsp/u-boot/u-boot.inc'><filename>u-boot.inc</filename></ulink> |
| include file. |
| </note> |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_*</filename></ulink>: |
| Defines various U-Boot configurations needed |
| to build a U-Boot image. |
| In this example, a U-Boot image is required |
| to boot the BeagleBone device. |
| See the following variables for more information: |
| <itemizedlist> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_SUFFIX'><filename>UBOOT_SUFFIX</filename></ulink>: |
| Points to the generated U-Boot extension. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_MACHINE'><filename>UBOOT_MACHINE</filename></ulink>: |
| Specifies the value passed on the make command line when building a U-Boot image. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_ENTRYPOINT'><filename>UBOOT_ENTRYPOINT</filename></ulink>: |
| Specifies the entry point for the U-Boot image. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-UBOOT_LOADADDRESS'><filename>UBOOT_LOADADDRESS</filename></ulink>: |
| Specifies the load address for the U-Boot image. |
| </para></listitem> |
| </itemizedlist> |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>: |
| Specifies the list of hardware features the |
| BeagleBone device is capable of supporting. |
| In this case, the device supports |
| "usbgadget usbhost vfat alsa". |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_BOOT_FILES'><filename>IMAGE_BOOT_FILES</filename></ulink>: |
| Files installed into the device's boot partition |
| when preparing the image using the Wic tool |
| with the <filename>bootimg-partition</filename> |
| source plugin. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| |
| <section id='bsp-kernel-recipe-example'> |
| <title>BSP Kernel Recipe Example</title> |
| |
| <para> |
| The kernel recipe used to build the kernel image |
| for the BeagleBone device was established in the |
| machine configuration: |
| <literallayout class='monospaced'> |
| PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto" |
| PREFERRED_VERSION_linux-yocto ?= "5.0%" |
| </literallayout> |
| The <filename>meta-yocto-bsp/recipes-kernel/linux</filename> |
| directory in the layer contains metadata used |
| to build the kernel. |
| In this case, a kernel append file (i.e. |
| <filename>linux-yocto_5.0.bbappend</filename>) is used to |
| override an established kernel recipe (i.e. |
| <filename>linux-yocto_5.0.bb</filename>), which is |
| located in |
| <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/recipes-kernel/linux'></ulink>. |
| </para> |
| |
| <para> |
| Following is the contents of the append file: |
| <literallayout class='monospaced'> |
| KBRANCH_genericx86 = "v5.0/standard/base" |
| KBRANCH_genericx86-64 = "v5.0/standard/base" |
| KBRANCH_edgerouter = "v5.0/standard/edgerouter" |
| KBRANCH_beaglebone-yocto = "v5.0/standard/beaglebone" |
| |
| KMACHINE_genericx86 ?= "common-pc" |
| KMACHINE_genericx86-64 ?= "common-pc-64" |
| KMACHINE_beaglebone-yocto ?= "beaglebone" |
| |
| SRCREV_machine_genericx86 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" |
| SRCREV_machine_genericx86-64 ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" |
| SRCREV_machine_edgerouter ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" |
| SRCREV_machine_beaglebone-yocto ?= "3df4aae6074e94e794e27fe7f17451d9353cdf3d" |
| |
| COMPATIBLE_MACHINE_genericx86 = "genericx86" |
| COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64" |
| COMPATIBLE_MACHINE_edgerouter = "edgerouter" |
| COMPATIBLE_MACHINE_beaglebone-yocto = "beaglebone-yocto" |
| |
| LINUX_VERSION_genericx86 = "5.0.3" |
| LINUX_VERSION_genericx86-64 = "5.0.3" |
| LINUX_VERSION_edgerouter = "5.0.3" |
| LINUX_VERSION_beaglebone-yocto = "5.0.3" |
| </literallayout> |
| This particular append file works for all the |
| machines that are part of the |
| <filename>meta-yocto-bsp</filename> layer. |
| The relevant statements are appended with |
| the "beaglebone-yocto" string. |
| The OpenEmbedded build system uses these |
| statements to override similar statements |
| in the kernel recipe: |
| <itemizedlist> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>: |
| Identifies the kernel branch that is validated, |
| patched, and configured during the build. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>: |
| Identifies the machine name as known by the |
| kernel, which is sometimes a different name |
| than what is known by the OpenEmbedded build |
| system. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>: |
| Identifies the revision of the source code used |
| to build the image. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>: |
| A regular expression that resolves to one or |
| more target machines with which the recipe |
| is compatible. |
| </para></listitem> |
| <listitem><para> |
| <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>: |
| The Linux version from kernel.org used by |
| the OpenEmbedded build system to build the |
| kernel image. |
| </para></listitem> |
| </itemizedlist> |
| </para> |
| </section> |
| </section> |
| </chapter> |