Using Yocto Project with BeagleBone Black

These are the core tools and packages that are required to build Yocto Project. These include a GNU compiler, versioning control system, and other packages that are required to build an environment on host. Here's the command to get the essentials:

$  sudo apt-get install gawk wget git-core diffstat unzip texinfo gcc-multilib \
     build-essential chrpath

If you want to use graphics support or you intend to use Eclipse IDE, then you need to install these packages:

$  sudo apt-get install libsdl1.2-dev xterm

These packages are required if you want to build a Yocto Project documentation:

$  sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto

These packages are required only if you want to build an Application Development Kit (ADK):

$ sudo apt-get install autoconf automake libtool libglib2.0-dev

If you are using any distribution other than those previously listed, you will find similar commands can be used on Debian distributions, as well. For other supported distributions, consult the Yocto Project Reference Manual.

First, we will encounter the following two options, which are related to each other. These options are here to tune the level of parallelism used by BitBake, the actual driver behind Yocto Project. The two options are:

You will find these variables twice in this file: once in the preceding form and once in the following form:

#BB_NUMBER_THREADS ?= "4"
#PARALLEL_MAKE ?= "-j 4"

We are telling BitBake about the maximum number of threads it should use for the job and the maximum of jobs run in parallel. Most of the Yocto Project manuals and blogs say both of these should be equal to the number of cores available on your system. However, my experience has proven that the following formula gives the maximum throughput, that is, the minimum time of execution:

BB_NUMBER_THREADS ?= "1.5 * Number of cores"
PARALLEL_MAKE ?= "-j 2 * Number of cores"

On a 16-core server, we will use the combinations of 24 and 32, whereas on an 8-core machine we will use 12 and 16. For a 4-core machine, we will use 6 and 8 as follows:

BB_NUMBER_THREADS ?= "6"
PARALLEL_MAKE ?= "-j 8"

Next, we need to select the machine. Here, we will set BeagleBone, which is already available to us. So, we will uncomment it and comment out the default selection, which is the qemux86 selection. Commenting out an existing selection is not strictly necessary since it is assigned using the ?? operator, which we will discuss in the upcoming chapters.

MACHINE ?= "beaglebone"
#MACHINE ??= "qemux86"

Next, we will set our downloads directory. This directory will be used to download sources for packages. The available configuration variable to set this configuration is DL_DIR. If we don't set this, its default value would be used as our build directory. So, we will have this directory created under the build directory. We usually don't care much in case of Board Support Packages (BSPs) running rm-rf on our build directory to start a fresh build. In such cases, not caring about this variable can cause regrets, as it will download all the sources again and again, causing longer build times. We set it up in the top-level directory, which contains the poky directory itself, so that we don't ever accidentally delete it with other expendable stuff.

DL_DIR ?= "${TOPDIR}/../../downloads"

Next, we have SSTATE_DIR, TMPDIR, and DISTRO, which we will leave unchanged for now. SSTATE_DIR is related to the shared state feature of Yocto Project. Yocto Project has a mechanism to check whether some package is already built and available, it uses the existing package and doesn't build it. TMPDIR is the directory that contains a lot of build stuff. We will go through its contents in the upcoming chapters. Then, we have PACKAGE_CLASSES, as follow:

PACKAGE_CLASSES ?= "package_ipk"

We will leave the remaining variables unchanged.

We can use a lot other options in this file as well. We will learn about some of these options in the upcoming chapters.

As the name suggests, bblayers.conf is there to provide us with a mechanism to configure our Yocto Project layers. This file has configurations related to layers. We can add extra layers to this file to use the metadata available in these layers. This file further classifies layers into removable and non-removable ones, as you can see in the following code snippet:

BBLAYERSBBLAYERSBBLAYERS ?= " \
  /home/irfan/yocto/poky/meta \
  /home/irfan/yocto/poky/meta-yocto \
  /home/irfan/yocto/poky/meta-yocto-bsp \
  "
BBLAYERS_NON_REMOVABLE ?= " \
  /home/irfan/yocto/poky/meta \
  /home/irfan/yocto/poky/meta-yocto \
  "

Since we are not using any extra layers, we will leave this file unchanged.

This file is optional. You won't find it created by the build environment creation script. We mostly use system-wide or other configurations common across different builds and targets are put in this file. For example, we would use the toolchain path if we were using an external toolchain. Another option could be specifying mirror sites, we case it for this purpose. If we have this file created, BitBake looks for it and uses common configurations from this file. We override any configuration that we want modified in conf/local.conf.

This is an optional file. Just like the previous file, you won't find it created by the build environment creation script. We can use this file to set our custom options so that we don't have to modify local.conf manually. In most of the cases, this file is used by build systems such as Jenkins. For example, if we don't want our build directory size to explode due to space constraints, we could use the following code file in the local.conf or auto.conf file:

INHERIT += "rm_work"

For now, we don't need to set this. I am just mentioning it here to elaborate the preceding point. Since we will analyze the contents of the tmp/work directory in the upcoming chapters, I would suggest that you do not use this option for the time being.

Now that we have set all the configurations, let's start our build. You can choose any of the images to build. I will prefer core-image-sato:

$  bitbake core-image-sato

Building images for our desired target may take some time, depending on network speed and processing power. After the build is complete, you will have your images ready at tmp/deploy/images/beaglebone/ under your build directory, as shown in the following screenshot. This contains first-level bootloader MLO, second-level bootloader u-boot, kernel image, device tree blobs, a root filesystem archive, and a modules archive.

Here, you will notice that we have symbolic links as well as full names of the files, with time stamp information in most of the cases. Symbolic links always point to the latest file created. We should always try to use a symbolic link for copying to avoid any confusion.

Now that we have our images created by Yocto Project, we are ready to verify these images on our BeagleBone board:

Images directory contents

In case of other images, such as core-image-minimal, core-image-base, and core-image-sdk, the content shown in this screenshot will contain files related to those images instead of core-image-sato.

You won't find a file with this name. Here, machine is a placeholder for the target board we are preparing our images for. For example, in our case, this file is beaglebone.conf and in the preceding configuration, it is available as beaglebone.conf in the poky/meta-yocto-bsp/conf/machine/ directory.

All of the machine- specific configurations are done in this file. We need to know about it and have some basic understanding of its contents so that we can modify it, if required. Let's go through it. The top-level header contains information in tags for documentation:

#@TYPE: Machine
#@NAME: Beaglebone machine
#@DESCRIPTION: Machine configuration for http://beagleboard.org/bone and http://beagleboard.org/black boards

The preferred xserver can be used:

PREFERRED_PROVIDER_virtual/xserver ?= "xserver-xorg"
XSERVER ?= "xserver-xorg \
           xf86-input-evdev \
           xf86-input-mouse \
           xf86-video-fbdev \
           xf86-input-keyboard"

What extra recipes need to be built? These are built here:

MACHINE_EXTRA_RRECOMMENDS = " kernel-modules kernel-devicetree"

Set image dependencies:

EXTRA_IMAGEDEPENDS += "u-boot"

Architecture-specific configurations are found in tune files. Here, we will set the available one that will fulfill our requirements:

DEFAULTTUNE ?= "cortexa8hf-neon"
include conf/machine/include/tune-cortexa8.inc

These tune files are present under Poky on the path that we are using in include directive.

Here, we will specify the type of filesystem images we want to create for our machine. There are other options to choose from. Also, here, we will set extra image commands in the case of the jffs2 image:

IMAGE_FSTYPES += "tar.bz2 jffs2"
EXTRA_IMAGECMD_jffs2 = "-lnp "

One of the most important options is the serial debug console. Here, we are defining our eyes with which to peek inside the board:

SERIAL_CONSOLE = "115200 ttyO0"

Here, we are tweaking our kernel options to see what recipe should be used for kernel compilation and what version of kernel needs to be built. For this, we will use the Yocto Project keywords, PREFERRED_PROVIDER and PREFERRED_VERSION:

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

We can also create another kernel image, zImage. Since this is a generic machine for BeagleBone Black and White versions, we will create device tree binary files for both of the target. You can opt not to build DTB for BeagleBone White, but this won't make much difference in terms of build time or cleanliness, if you are considering such things. Also, we can set any extra arguments that need to be passed to KERNEL:

KERNEL_IMAGETYPE = "uImage"
KERNEL_DEVICETREE = "am335x-bone.dtb am335x-boneblack.dtb"
KERNEL_EXTRA_ARGS += "LOADADDR=${UBOOT_ENTRYPOINT}"

Here, we will configure most of the aspects of our bootloaders. We will set MLO as the binary name for stage-one bootloader so that we will have it created as MLO, as we saw in the images directory. We will specify a u-boot suffix, img, to be used so that we have the u-boot.img file created. Other options are also related to u-boot, such as these:

SPL_BINARY = "MLO"
UBOOT_SUFFIX = "img"
UBOOT_MACHINE = "am335x_evm_config"
UBOOT_ENTRYPOINT = "0x80008000"
UBOOT_LOADADDRESS = "0x80008000"

Now, we will determine the features that we want our machine to support or, more precisely, the features it has the ability to support. We will also determine which features we want turn on:

MACHINE_FEATURES = "usbgadget usbhost vfat alsa" 

As the name signifies, this file is related to BitBake, the real engine behind Yocto Project, which is responsible for the simplification of our build process. This file is parsed first and then the rest of the configuration files listed in it are parsed. This file is found under poky/meta/conf/ as bitbake.conf. This is not a small file, so we cannot go through it line by line. It contains more than 700 lines of configuration and metadata. Almost all the metadata used in our recipes is defined in this file.

It is not a standalone file. Instead, it includes other files from the conf directory. We can find all the files that were described earlier in it. So, bitbake.conf uses these files and the metadata definitions in them. For example, if you remember, we used some variables such as DL_DIR, TOPDIR, and TMPDIR, You can find all these variables in this file, along with their default values. This file has all the metadata arranged in different sections. It contains about 20 different sections. Variables defined in one section are used in other sections. Let's have a brief look at some of these sections.