Yocto Project Board Support Package Developer's Guide

You can find these files in the BSP Layer at:

     meta-bsp_name/bsp_license_file
                

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 eMenlow BSP all licensing requirements are handled with the COPYING.MIT file.

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.

You can find this file in the BSP Layer at:

     meta-bsp_name/README
                

This file provides information on how to boot the live images that are optionally included in the binary/ directory. The README file also provides special information needed for building the image.

At a minimum, the README 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.

You can find this file in the BSP Layer at:

     meta-bsp_name/README.sources
                

This file provides information on where to locate the BSP source files used to build the images (if any) that reside in meta-bsp_name/binary. Images in the binary would be images released with the BSP. The information in the README.sources file also helps you find the Metadata used to generate the images that ship with the BSP.

You can find these files in the BSP Layer at:

     meta-bsp_name/binary/bootable_images
                

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 Yocto Project website. You can use these kernels and images to get a system running and quickly get started on development tasks.

The exact types of binaries present are highly hardware-dependent. The README file should be present in the BSP Layer and it will explain how to use the images with the target hardware. Additionally, the README.sources file should be present to locate the sources used to build the images and provide information on the Metadata.

You can find this file in the BSP Layer at:

     meta-bsp_name/conf/layer.conf
                

The conf/layer.conf 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 "bsp" and "_bsp" with the actual name of the BSP (i.e. bsp_name from the example template).

     # 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 += "bsp"
     BBFILE_PATTERN_bsp = "^${LAYERDIR}/"
     BBFILE_PRIORITY_bsp = "6"

     LAYERDEPENDS_bsp = "intel"
                

To illustrate the string substitutions, here are the corresponding statements from the eEmenlow conf/layer.conf file:

     # 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 += "emenlow"
     BBFILE_PATTERN_emenlow := "^${LAYERDIR}/"
     BBFILE_PRIORITY_emenlow = "6"

     LAYERDEPENDS_emenlow = "intel"
                

This file simply makes BitBake aware of the recipes and configuration directories. The file must exist so that the OpenEmbedded build system can recognize the BSP.

You can find these files in the BSP Layer at:

     meta-bsp_name/conf/machine/*.conf
                

The machine files bind together all the information contained elsewhere in the BSP into a format that the build system can understand. If the BSP supports multiple machines, multiple machine configuration files can be present. These filenames correspond to the values to which users have set the MACHINE variable.

These files define things such as the kernel package to use (PREFERRED_PROVIDER of virtual/kernel), 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.

Each BSP Layer requires at least one machine file. However, you can supply more than one file.

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.

Tuning files are found in the meta/conf/machine/include directory within the Source Directory. For example, the ia32-base.inc file resides in the meta/conf/machine/include directory.

To use an include file, you simply include them in the machine configuration file. For example, the eEmenlow BSP emenlow-noemgd.conf contains the following statements:

     require conf/machine/include/intel-core2-32-common.inc
     require conf/machine/include/intel-common-pkgarch.inc
     require conf/machine/include/meta-intel.inc
                

You can find these files in the BSP Layer at:

     meta-bsp_name/recipes-bsp/*
                

This optional directory contains miscellaneous recipe files for the BSP. Most notably would be the formfactor files. For example, in the eMenlow BSP there is the formfactor_0.0.bbappend 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 machconfig file further down in the directory. In the eMenlow example, the machconfig file supports the Video Electronics Standards Association (VESA) graphics driver:

     # Assume a USB mouse and keyboard are connected
     HAVE_TOUCHSCREEN=0
     HAVE_KEYBOARD=1
                

You can find these files in the BSP Layer at:

     meta-bsp_name/recipes-graphics/*
                

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. For example, the meta-emenlow layer, which supports the eMenlow platform consisting of the Intel® Atom™ Z5xx processor with the Intel® System Controller Hub US15W, uses these files for supporting the Video Electronics Standards Association (VESA) graphics:

     meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
     meta-emenlow/recipes-graphics/xorg-xserver/xserver-xf86-config/emenlow-noemgd/xorg.conf
                

You can find these files in the BSP Layer at:

     meta-bsp_name/recipes-kernel/linux/linux-yocto*.bbappend
                

These files append your specific changes to the main kernel recipe you are using.

For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the Source Directory at meta/recipes-kernel/linux. You can append your specific changes to the kernel recipe by using a similarly named append file, which is located in the BSP Layer (e.g. the meta-bsp_name/recipes-kernel/linux directory).

Suppose you are using the linux-yocto_3.14.bb recipe to build the kernel. In other words, you have selected the kernel in your bsp_name.conf file by adding these types of statements:

     PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
     PREFERRED_VERSION_linux-yocto ?= "3.14%"
                

You would use the linux-yocto_3.14.bbappend file to append specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.

As an example, look at the existing eMenlow BSP. The append file used is:

     meta-emenlow/recipes-kernel/linux/linux-yocto_3.14.bbappend
                

The following listing shows the file. Be aware that the actual commit ID strings in this example listing might be different than the actual strings in the file from the meta-intel Git source repository.

     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

     COMPATIBLE_MACHINE_emenlow-noemgd = "emenlow-noemgd"
     KMACHINE_emenlow-noemgd = "emenlow"
     KBRANCH_emenlow-noemgd = "standard/base"
     KERNEL_FEATURES_append_emenlow-noemgd = " features/drm-gma500/drm-gma500.scc"

     LINUX_VERSION_emenlow-noemgd = "3.14.19"
     SRCREV_machine_emenlow-noemgd = "902f34d36102a4b2008b776ecae686f80d307e12"
     SRCREV_meta_emenlow-noemgd = "28e39741b8b3018334021d981369d3fd61f18f5b"
                

This append file contains statements used to support the eMenlow BSP. The file defines machines using the COMPATIBLE_MACHINE variable and uses the KMACHINE variable to ensure the machine name used by the OpenEmbedded build system maps to the machine name used by the Linux Yocto kernel. The file also uses the optional KBRANCH variable to ensure the build process uses the standard/emenlow kernel branch. The KERNEL_FEATURES variable enables features specific to the kernel (e.g. Intel GMA-500 DRM Driver in this case). The append file points to specific commits in the Source Directory Git repository and the meta Git repository branches to identify the exact kernel needed to build the eMenlow BSP.

One thing missing in this particular BSP, which you will typically need when developing a BSP, is the kernel configuration file (.config) for your BSP. When developing a BSP, you probably have a kernel configuration file or a set of kernel configuration files that, when taken together, define the kernel configuration for your BSP. You can accomplish this definition by putting the configurations in a file or a set of files inside a directory located at the same level as your kernel's append file and having the same name as the kernel's main recipe file. With all these conditions met, simply reference those files in the SRC_URI statement in the append file.

For example, suppose you had some configuration options in a file called network_configs.cfg. You can place that file inside a directory named linux-yocto and then add a SRC_URI statement such as the following to the append file. When the OpenEmbedded build system builds the kernel, the configuration options are picked up and applied.

     SRC_URI += "file://network_configs.cfg"
                

To group related configurations into multiple files, you perform a similar procedure. Here is an example that groups separate configurations specifically for Ethernet and graphics into their own files and adds the configurations by using a SRC_URI statement like the following in your append file:

     SRC_URI += "file://myconfig.cfg \
            file://eth.cfg \
            file://gfx.cfg"
                

The FILESEXTRAPATHS variable is in boilerplate form in the previous example in order to make it easy to do that. This variable must be in your layer or BitBake will not find the patches or configurations even if you have them in your SRC_URI. The FILESEXTRAPATHS variable enables the build process to find those configuration files.

Before looking at BSP requirements, you should consider the following:

Following are the requirements for a released BSP that conforms to the Yocto Project:

Following are recommendations for a released BSP that conforms to the Yocto Project:

Designed to have a command interface somewhat like Git, each tool is structured as a set of sub-commands under a top-level command. The top-level command (yocto-bsp or yocto-kernel) itself does nothing but invoke or provide help on the sub-commands it supports.

Both tools reside in the scripts/ subdirectory of the Source Directory. Consequently, to use the scripts, you must source the environment just as you would when invoking a build:

     $ source oe-init-build-env build_dir
                    

The most immediately useful function is to get help on both tools. The built-in help system makes it easy to drill down at any time and view the syntax required for any specific command. Simply enter the name of the command with the help switch:

     $ yocto-bsp help
     Usage:

      Create a customized Yocto BSP layer.

      usage: yocto-bsp [--version] [--help] COMMAND [ARGS]

      Current 'yocto-bsp' commands are:
         create            Create a new Yocto BSP
         list              List available values for options and BSP properties

      See 'yocto-bsp help COMMAND' for more information on a specific command.


     Options:
       --version    show program's version number and exit
       -h, --help   show this help message and exit
       -D, --debug  output debug information
                    

Similarly, entering just the name of a sub-command shows the detailed usage for that sub-command:

     $ yocto-bsp create

     Usage:

      Create a new Yocto BSP

      usage: yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
             [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]

      This command creates a Yocto BSP based on the specified parameters.
      The new BSP will be a new Yocto BSP layer contained by default within
      the top-level directory specified as 'meta-bsp-name'.  The -o option
      can be used to place the BSP layer in a directory with a different
      name and location.

      ...
                    

For any sub-command, you can use the word "help" option just before the sub-command to get more extensive documentation:

     $ yocto-bsp help create

     NAME
         yocto-bsp create - Create a new Yocto BSP

     SYNOPSIS
         yocto-bsp create <bsp-name> <karch> [-o <DIRNAME> | --outdir <DIRNAME>]
             [-i <JSON PROPERTY FILE> | --infile <JSON PROPERTY_FILE>]

     DESCRIPTION
         This command creates a Yocto BSP based on the specified
         parameters.  The new BSP will be a new Yocto BSP layer contained
         by default within the top-level directory specified as
         'meta-bsp-name'.  The -o option can be used to place the BSP layer
         in a directory with a different name and location.

         The value of the 'karch' parameter determines the set of files
         that will be generated for the BSP, along with the specific set of
         'properties' that will be used to fill out the BSP-specific
         portions of the BSP.  The possible values for the 'karch' parameter
         can be listed via 'yocto-bsp list karch'.

         ...
                    

Now that you know where these two commands reside and how to access information on them, you should find it relatively straightforward to discover the commands necessary to create a BSP and perform basic kernel maintenance on that BSP using the tools.

The next sections provide a concrete starting point to expand on a few points that might not be immediately obvious or that could use further explanation.

The yocto-bsp script creates a new BSP layer for any architecture supported by the Yocto Project, as well as QEMU versions of the same. The default mode of the script's operation is to prompt you for information needed to generate the BSP layer.

For the current set of BSPs, the script prompts you for various important parameters such as:

You use the yocto-bsp create sub-command to create a new BSP layer. This command requires you to specify a particular kernel architecture (karch) on which to base the BSP. Assuming you have sourced the environment, you can use the yocto-bsp list karch sub-command to list the architectures available for BSP creation as follows:

     $ yocto-bsp list karch
     Architectures available:
         qemu
         mips64
         powerpc
         x86_64
         arm
         mips
         i386
                    

The remainder of this section presents an example that uses myarm as the machine name and qemu as the machine architecture. Of the available architectures, qemu is the only architecture that causes the script to prompt you further for an actual architecture. In every other way, this architecture is representative of how creating a BSP for an actual machine would work. The reason the example uses this architecture is because it is an emulated architecture and can easily be followed without requiring actual hardware.

As the yocto-bsp create command runs, default values for the prompts appear in brackets. Pressing enter without supplying anything on the command line or pressing enter with an invalid response causes the script to accept the default value. Once the script completes, the new meta-myarm BSP layer is created in the current working directory. This example assumes you have sourced the oe-init-build-env setup script.

Following is the complete example:

     $ yocto-bsp create myarm qemu
     Checking basic git connectivity...
     Done.
     Which qemu architecture would you like to use? [default: i386]
         1) i386    (32-bit)
         2) x86_64  (64-bit)
         3) ARM     (32-bit)
         4) PowerPC (32-bit)
         5) MIPS    (32-bit)
         6) MIPS64  (64-bit)
     3
     Would you like to use the default (3.19) kernel? (y/n) [default: y] y
     Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]
     Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.19.git...
     Please choose a machine branch to base your new BSP branch on: [default: standard/base]
         1) standard/arm-versatile-926ejs
         2) standard/base
         3) standard/beagleboard
         4) standard/beaglebone
         5) standard/ck
         6) standard/common-pc
         7) standard/crownbay
         8) standard/edgerouter
         9) standard/fsl-mpc8315e-rdb
         10) standard/mti-malta32
         11) standard/mti-malta64
         12) standard/qemuarm64
         13) standard/qemuppc
     1
     Would you like SMP support? (y/n) [default: y]
     Does your BSP have a touchscreen? (y/n) [default: n]
     Does your BSP have a keyboard? (y/n) [default: y]
     New qemu BSP created in meta-myarm
                    

Take a closer look at the example now:

Once the BSP Layer is created, you must add it to your bblayers.conf file. Here is an example:

     BBLAYERS = ? " \
        /usr/local/src/yocto/meta \
        /usr/local/src/yocto/meta-yocto \
        /usr/local/src/yocto/meta-yocto-bsp \
        /usr/local/src/yocto/meta-myarm \
        "

     BBLAYERS_NON_REMOVABLE ?= " \
        /usr/local/src/yocto/meta \
        /usr/local/src/yocto/meta-yocto \
        "
                    

Adding the layer to this file allows the build system to build the BSP and the yocto-kernel tool to be able to find the layer and other Metadata it needs on which to operate.

Assuming you have created a BSP Layer using yocto-bsp and you added it to your BBLAYERS variable in the bblayers.conf file, you can now use the yocto-kernel script to add patches and configuration items to the BSP's kernel.

The yocto-kernel script allows you to add, remove, and list patches and kernel config settings to a BSP's kernel .bbappend file. All you need to do is use the appropriate sub-command. Recall that the easiest way to see exactly what sub-commands are available is to use the yocto-kernel built-in help as follows:

     $ yocto-kernel --help
     Usage:
      Modify and list Yocto BSP kernel config items and patches.
      usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
      Current 'yocto-kernel' commands are:
        config list       List the modifiable set of bare kernel config options for a BSP
        config add        Add or modify bare kernel config options for a BSP
        config rm         Remove bare kernel config options from a BSP
        patch list        List the patches associated with a BSP
        patch add         Patch the Yocto kernel for a BSP
        patch rm          Remove patches from a BSP
        feature list      List the features used by a BSP
        feature add       Have a BSP use a feature
        feature rm        Have a BSP stop using a feature
        features list     List the features available to BSPs
        feature describe  Describe a particular feature
        feature create    Create a new BSP-local feature
        feature destroy   Remove a BSP-local feature
      See 'yocto-kernel help COMMAND' for more information on a specific command.
     Options:
       --version    show program's version number and exit
       -h, --help   show this help message and exit
       -D, --debug  output debug information
                    

The yocto-kernel patch add sub-command allows you to add a patch to a BSP. The following example adds two patches to the myarm BSP:

     $ yocto-kernel patch add myarm ~/test.patch
     Added patches:
       test.patch

     $ yocto-kernel patch add myarm ~/yocto-testmod.patch
     Added patches:
       yocto-testmod.patch
                    

You can verify patches have been added by using the yocto-kernel patch list sub-command. Here is an example:

     $ yocto-kernel patch list myarm
     The current set of machine-specific patches for myarm is:
       1) test.patch
       2) yocto-testmod.patch
                    

You can also use the yocto-kernel script to remove a patch using the yocto-kernel patch rm sub-command. Here is an example:

     $ yocto-kernel patch rm myarm
     Specify the patches to remove:
       1) test.patch
       2) yocto-testmod.patch
     1
     Removed patches:
       test.patch
                    

Again, using the yocto-kernel patch list sub-command, you can verify that the patch was in fact removed:

     $ yocto-kernel patch list myarm
     The current set of machine-specific patches for myarm is:
       1) yocto-testmod.patch
                    

In a completely similar way, you can use the yocto-kernel config add sub-command to add one or more kernel config item settings to a BSP. The following commands add a couple of config items to the myarm BSP:

     $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
     Added item:
       CONFIG_MISC_DEVICES=y

     $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y
     Added item:
       CONFIG_YOCTO_TESTMOD=y
                    

You can list the config items now associated with the BSP. Doing so shows you the config items you added as well as others associated with the BSP:

     $ yocto-kernel config list myarm
     The current set of machine-specific kernel config items for myarm is:
             1) CONFIG_MISC_DEVICES=y
             2) CONFIG_YOCTO_TESTMOD=y
                    

Finally, you can remove one or more config items using the yocto-kernel config rm sub-command in a manner completely analogous to yocto-kernel patch rm.