Creating a BSP Layer using yocto-bsp

What is a BSP layer?
A BSP layer contains a set of recipes which when built can result in an image that will run on a particular board.

Few examples for yocto BSP layers are
meta-fsl
meta-ti
meta-intel
meta-raspberrypi etc

Creating this layer has been made user-friendly with the help of yocto-bsp command.

To run the yocto-bsp command, export the yocto environment settings by sourcing the oe-init-build-env script.

The usage of the command is shown in the below image.

yocto-bsp help message

Before going into create learn what the command has to offer with its list subcommand.

If you run the command yocto-bsp help list you will get a detailed message with info on the list of architectures supported and the properties of the BSP.

To create a BSP for the arm architecture run the below command. The below commands are run in fido version of Yocto.

yocto-bsp create <bsp_name> arm

Note:
1) You can mention the directory in which the meta-bsp has to be created with the -o option.
2) You can pass the values of properties using a JSON file with the -i option.

Below is an example for ashversity BSP

ashversity BSP creation

The command first checks your git connectivity and provides you with the option whether or not to use the latest kernel. If you choose the option as yes then you will be prompted with the machine branch, but if you choose no you will be provided with the options shown in the below image.

List of Kernel choices

If your choice is other than custom you will be prompted regarding the next property. But if your choice is custom you will be prompted with further queries shown below.

If you choose no for remote git repo then you have to provide the path for the local git repo.

You can specify the branch and the commit id of your kernel. You will be prompted for kernel version, version extension and defconfig file's path.

You are presented with the following options, if your choice of kernel is other than custom.

Yocto kernel options

You can choose symmetric multi processing support if you need it.

There are a few more properties(common to custom and yocto kernel) that is needed by BSP. The properties are shown in the below image.

You have to mention the tuning optimization according to your arm architecture. The other options are self explanatory.

Finally your BSP is created and is ready for further customization. The contents of BSP and modifying it will be explained in the following post.

Creating a Patch File Using Quilt

What is  a patch file?

I quote the wiki here
" A patch file is a text file that consists of a list of differences and is produced by running the related diff program with the original and updated file as arguments"

Here I would explain a simple way to create a patch file using quilt.

1) The first step is to mention the name of the patch. That is done by running the below command.
quilt new <patch_name>

2) Next add the file which you are going to modify.
quilt add <file_name>

3) Make the changes you need to make.

4) Then run the below command to create the patch.
quilt refresh

The patch will be created in the patches directory by default. The patches directory will be created in the directory from which you run the quilt refresh command.

The quilt settings can be modified according to user preference by a quiltrc file. Some of the variables are listed below.
QUILT_DIFF_OPTS                        - options to be passed to gnu diff

QUILT_PATCHES                           - The patch directory which by default is patches.

QUILT_PATCHES_PREFIX           - The prefix to be added to patch name.

QUILT_NO_DIFF_INDEX              - To avoid prepending index.

QUILT_NO_DIFF_TIMESTAMPS -To avod including timestamps.

Steps involved in Yocto while building a package

The steps involved in building a package is almost similar to the steps involved in building a package manually with the addition of a few steps.

Manual Build:

The manual building of a package involves the below steps which are pretty straightforward.

1) Download

2) Extract

3) Patch ( If needed)

4) Configure

5) Compile

6) Install

Yocto Build:

In Yocto the following steps are usually involved in building a package. To know the exact list of tasks you can run the below command.

bitbake <packagename> -c listtasks

1) Fetch or download

The source of the package mentioned in the variable SRC_URI, in the recipe file is fetched. Depending on the source the method to fetch is determined ( wget, git, svn, ftp etc). The download directory is either the one created in the build directory or the one mentioned in the DL_DIR variable.

2) Unpack or Extract

The downloaded package is then extracted to the working directory.

3) Patch

The extracted source is patched if any patch is mentioned in the SRC_URI variable. The patch file is searched for in a set of directories in the location where the recipe is found. The default is files , then a combination of the package names. If you want to have the patches in a directory name of your choice it should be mentioned in the variable  FILESEXTRAPATHS_prepend.

4) Configure

The package is configured with all the necessary options and information such as CC, CXX etc.

The EXTRA_OECONF(autotools) or the EXTRA_OECMAKE(cmake) variable can be used to pass additional arguments to configure or the configure can be entirely overrided by implementing do_configure.

5) Compile

The package is compiled as per the configuration. EXTRA_OEMAKE passes additional options to the make command. The compile function can be overrioverrided by implementing do_compile.

6) Install

The compiled package is installed. Similar to configure and compile do_install can be used to implement our own install function.

7) Package and QA

In these steps the package is packaged as per the package class. Then it is checked for any future issues it may cause in the QA. Also the package status is added to cache file in package_setscene.

If the package needs to be added to the sysroot that would be done.

I hope I have shed some light into the steps involved in building a package in Yocto.

Why Choose Yocto?

Normally if you want to create the BSP for your board there are a number of choices available for you.

The good old way is doing everything manually, that is preparing the bootloader, kernel and rootfs ( which will contain a list of packages you need ). You can even prepare scripts to automate it. But the content that goes into that scripts require a lot of work. The procedure for cross compiling the bootloader, kernel is straightforward and simple, but bear in mind that does not apply to the add-on packages which you might require in your rootfs. There is no doubt that you may find the procedure for cross compiling few of the packages which are a basic necessity, but that might not be the case all the time. You may run into errors while cross compiling and to solve it you may have to find patches or you might have to fix it on your own. When I was doing it manually I learned a lot but it becomes a bit difficult for packages that have multiple dependencies. I found myself looking into yocto recipes for understanding the way to build the packages and using the patches available there to fix the issues I was facing. So there goes my reason for choosing yocto.

Yocto contains almost everything to help you create your own distribution. They are updating there recipes frequently so you stay current. The latest kernel, the latest packages you name it they provide it. The documentation they provide is quite detailed and easy to learn but it requires patience to master it. The initial build time and the space they occupy are the major cons that one may consider for opting other embedded Linux build sytems such as buildroot etc. But if you want to create BSP for multiple architectures and with a load of features than the pros of yocto outweighs the cons easily.

Buildroot also contains the makefiles and patches and automates the building process but it is meant for a simple system.

So according to me Yocto wins hands down.

Creating a New Yocto Recipe

What is Yocto ?

The Yocto Project is an open source collaboration project that provides templates, tools and methods to help you create custom Linux-based systems for embedded products regardless of the hardware architecture.

What is a recipe ?

The thing that comes to our mind when we hear the word recipe is a set of instructions for preparing a particular dish, including a list of the ingredients required. Similarly a recipe file in yocto is a set of instructions for building packages. A recipe describes where you get source code, which patches to apply, how to configure the source, how to compile it and so on. Recipes also describe dependencies for libraries or for other recipes. Recipes represent the logical unit of execution, the software to build, the images to build, and use the .bb file extension. The recipes are present in layers ( A collection of recipes representing the core, a BSP, or an application stack)

Creating a Recipe:

There are a number of meta-layers which provides recipes for a numerous packages but there may come a time where we have to get down and write a recipe for ourselves.

If you open a recipe you will see a number of entries, the entries you will encounter often are given below

SUMMARY, DESCRIPTION, HOMEPAGE, LICENSE, LIC_FILES_CHKSUM, SRC_URI,  SRC_URI[md5sum], SRC_URI[sha256sum], DEPENDS

Whenever it comes to creating a recipe most people tend to copy an existing recipe and alter the contents manually. There are tools provided by yocto to aid us in creating recipes. The following tools helps us in creating a recipe

• create-recipe
• recipetool

In my little experiments with these tools, I learnt that recipetool produces a buildable recipe. Below are the sample recipes of zlib-1.2.8 created using recipetool and create-recipe you can see the difference here

Sample recipe by recipetool:

recipetool create -o zlib_1.2.8.bb http://zlib.net/zlib-1.2.8.tar.gz

The usage of recipetool can be understood from the help message shown below:

usage: recipetool create [-h] -o OUTFILE [-m] [-x EXTRACTPATH] source

Creates a new recipe from a source tree

positional arguments:
source Path or URL to source

optional arguments:
-h, --help show this help message and exit
-o OUTFILE, --outfile OUTFILE
Specify filename for recipe to create
-m, --machine Make recipe machine-specific as opposed to
architecture-specific
-x EXTRACTPATH, --extract-to EXTRACTPATH
Assuming source is a URL, fetch it and extract it to
the directory specified as EXTRACTPATH

The contents of the recipe zlib_1.2.8.bb created as a result of the recipetool command is given below

 # Recipe created by recipetool
# This is the basis of a recipe and may need further editing in order to be fully functional.
# (Feel free to remove these comments when editing.)
#
# WARNING: the following LICENSE and LIC_FILES_CHKSUM values are best guesses - it is
# your responsibility to verify that the values are complete and correct.
LICENSE = "Unknown"
LIC_FILES_CHKSUM = "file://contrib/dotzlib/LICENSE_1_0.txt;md5=81543b22c36f10d20ac9712f8d80ef8d"

SRC_URI = "http://zlib.net/zlib-1.2.8.tar.gz "
SRC_URI[md5sum] = "44d667c142d7cda120332623eab69f40"
SRC_URI[sha256sum] = "36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d"

S = "${WORKDIR}/zlib-1.2.8"

inherit cmake

# Specify any options you want to pass to cmake using EXTRA_OECMAKE:
EXTRA_OECMAKE = ""

Sample recipe by create-recipe:

create-recipe http://zlib.net/zlib-1.2.8.tar.gz

The create-recipe command doesn't require the output file. By default it creates the recipe with the source link  provided.

The contents of the recipe zlib_1.2.8.bb created as a result of the create-recipe command is given below.

SUMMARY = "zlib compression library"
DESCRIPTION = "ZLIB DATA COMPRESSION LIBRARY

zlib 1.2.8 is a general purpose data compression library. All the code is
thread safe. The data format used by the zlib library is described by RFCs
(Request for Comments) 1950 to 1952 in the files
http://tools.ietf.org/html/rfc1950 (zlib format), rfc1951 (deflate format) and
rfc1952 (gzip format).
"
HOMEPAGE = ""
LICENSE = ""
LIC_FILES_CHKSUM = ""

SRC_URI = "http://zlib.net/zlib-1.2.8.tar.gz \
"

SRC_URI[md5sum] = "44d667c142d7cda120332623eab69f40"
SRC_URI[sha256sum] = "36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d"

Differences between recipetool & create-recipe

Both recipe creation tools provides the SRC_URI and its checksums. The create-recipe tool provides us with SUMMARY & DESCRIPTION which should be mentioned in a recipe but it doesn't carry weight when compared to the mention of source directory ( S )  and the class required to build the package ( inherit cmake).

Also create-recipe fails if the source doesn't provide a tarball. But recipetool can be used for git source too.

I use both the tools so the recipe would be similar to the standard yocto recipes. So use whichever tool suits you and enjoy creating recipes.  An another post will follow in creating-recipes which will explain creating recipes that require further customization.