What is a Yocto image and how can I modify it?

This is a continuation of a previous blog post. Here I will add some things to the image and modify existing elements of the image.

If you're brand new at this Yocto thing and are completely overwhelmed with documentation to read through, this blog post is meant to be an axillary bare-bones starting guide. Some quick tips that you can try to get results right away. That is the hope, anyway. So here are a few topics I think are most important to know about when you're just starting.

local.conf/bblayers.conf

After you initialize and run the setup-environment script, you'll notice a ~/fido/core-image-sato/conf folder. In this are two important files, bblayers.conf and local.conf. bblayers.conf tells bitbake what layers are present in the sources directory located at ~/fido/sources/ and local.conf is a configuration file where you can set build specific last-minute additions or tweaks. For this demo, I'll add the package gstreamer to the image. This will install gstreamer on the image as the gstreamer recipe is available in the ~/fido/sources/poky/ directory and that directory is specified in bblayers.conf.

Add the following line to the end of ~/fido/core-image-sato/conf/local.conf:

IMAGE_INSTALL_append += "gstreamer"

The IMAGE_INSTALL variable lists all packages that this particular image includes. Any variable with _append following it is a separate variable that simply appends more information to that variable. There is also a _prepend variable which prepends information to that particular variable. You can read more about these variables and syntax in the short cheat sheet here or in the in-depth chapter in the manual here.

Now go back and re-build core-image-sato and it should have the gstreamer package installed:

~$ cd ~/fido/ ~/fido$ MACHINE=nitrogen6x . setup-environment core-image-sato ~/fido/core-image-sato$ bitbake core-image-sato

It's important to note that you need to re-run the setup-environment script line once per terminal session. That is to say if you have 5 bash terminals open, you need to run that command in each one of those terminals if you intend on running the bitbake command within that terminal. Doing it more than once is harmless.

Add your own layer

If you take a look at our Yocto Fido blog post you'll notice I included a meta-boundary-example layer and some instructions on how to include it. This layer is a bit simple, but shows how easy it can be to deploy some particular files to your image's root file system. In that example I just deployed two simple desktop icons and two simple scripts to particular locations in the root file system of the image to add gstreamer desktop icon launchers for our camera modules.

For the purposes of this tutorial, we'll construct a different layer that does some more interesting things.

conf/layer.conf

Every bitbake source layer needs a configuration file to define where the recipes are. So lets create our layer and that configuration file like this:

~$ cd ~/fido/sources/ ~/fido/sources$ mkdir meta-boundary-tutorial ~/fido/sources$ cd meta-boundary-tutorial ~/fido/sources/meta-boundary-tutorial$ mkdir conf ~/fido/sources/meta-boundary-tutorial$ cd conf ~/fido/sources/meta-boundary-tutorial/conf$ vi layer.conf

The layer.conf file needs to look like this:

BBPATH .= ":${LAYERDIR}" BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \ ${LAYERDIR}/recipes-*/*/*.bbappend" BBFILE_COLLECTIONS += "boundary-tutorial" BBFILE_PATTERN_boundary-tutorial := "^${LAYERDIR}/"

Now you're ready to create recipes and put them in your layer. Categorize your recipes with some sort of name, it can be anything so try and be descriptive. sources/meta-boundary-tutorial/recipes-kernel for example to collect recipes related to and for building kernels. Or sources/meta-boundary-tutorial/recipes-boundary-example for some boundary devices example recipes.

Patch Recipe

So one of the more common recipes you might make is to simply patch something. Lets say some particular piece of software in the distribution is broken and needs fixing. Or maybe you want to make some modifications to some other piece of software. Well, in this instance you'd want to "append" to that software's recipe and include patch files. Any .patch file in the SRC_URI variable will automatically be applied to the source code of the project, so this recipe is particularly easy.

So for a practical example, lets say you have our Nitrogen6_Max board and want to enable the RS485 serial port on uart5. Well that UART is defined in the device tree here and as you can see the rs485-mode is off, to enable it you'd need to patch this file. The patch is rather simple and looks like this:

From 1e9d092394584c83ed3217339c593171be57b103 Mon Sep 17 00:00:00 2001 From: Ian Coolidge Date: Mon, 31 Aug 2015 14:26:59 -0700 Subject: [PATCH 1/1] imx6qdl-nitrogen6_max.dtsi: Enable RS485 on uart5 --- arch/arm/boot/dts/imx6qdl-nitrogen6_max.dtsi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arch/arm/boot/dts/imx6qdl-nitrogen6_max.dtsi b/arch/arm/boot/dts/imx6qdl-nitrogen6_max.dtsi index 11c0856..e7649e2 100644 --- a/arch/arm/boot/dts/imx6qdl-nitrogen6_max.dtsi +++ b/arch/arm/boot/dts/imx6qdl-nitrogen6_max.dtsi @@ -946,7 +946,7 @@ rs485_txen_mask = <0x3>; rs485_txen_levels = ; uart-has-rs485-half-duplex; - rs485-mode = <0>; /* 1 to enable */ + rs485-mode = <1>; /* 1 to enable */ status = "okay"; }; -- 1.9.1

As you can see, we simply just changed the value there. So to create a recipe that appends that patch file to our linux-boundary_3.10.53.bb recipe you would do the following:

~$ cd ~/fido/sources/meta-boundary-tutorial/ ~/fido/sources/meta-boundary-tutorial$ mkdir -p recipes-kernel/linux/files/ ~/fido/sources/meta-boundary-tutorial$ cd recipes-kernel/linux ~/fido/sources/meta-boundary-tutorial/recipes-kernel/linux$ vi linux-boundary_3.10.53.bbappend

This recipe would look like this:

FILESEXTRAPATHS_prepend := "${THISDIR}/files:" SRC_URI += "file://0001-imx6qdl-nitrogen6_max.dtsi-Add-rs485-support-on-uart.patch"

That recipe requires that the 0001-imx6qdl-nitrogen6_max.dtsi-Add-rs485-support-on-uart.patch file described above be put in ~/fido/sources/meta-boundary-tutorial/recipes-kernel/linux/files/.

Now if you add the meta-boundary-tutorial layer to the end of your ~/fido/core-image-sato/conf/bblayers.conf file, then your layer will be added to bitbake's path and your append recipe will be applied during compilation. To add that, simply add this line to the end of the BBLAYERS block in bblayers.conf:

${BSPDIR}/sources/meta-boundary-tutorial \

Now if you re-run the bitbake process, you'll notice the linux-boundary recipe is re-built from scratch and your patch will be applied in linux-boundary_3.10.53.bb's do_patch stage.

~$ cd ~/fido/ ~/fido$ MACHINE=nitrogen6x . setup-environment core-image-sato ~/fido/core-image-sato$ bitbake core-image-sato

 Customize Kernel

Sometimes we get requests for modified kernel configurations in standard images we release. Even though the kernel recipe calls out for a specific defconfig file, we can re-run the kernel build manually and select our own configuration by running the task do_menuconfig for the kernel recipe. Then you would run the do_compile and do_install tasks manually to compile and deploy the newly built kernel.

~/fido/core-image-sato$ bitbake -c menuconfig virtual/kernel (select configuration and save) ~/fido/core-image-sato$ bitbake -c compile virtual/kernel ~/fido/core-image-sato$ bitbake -c install virtual/kernel

If you wanted to use that configuration instead of the default, you could create a defconfig file and replace the one the recipe uses.

~/fido/core-image-sato$ bitbake -c savedefconfig virtual/kernel ~/fido/core-image-sato$ cp ~/fido/core-image-sato/tmp/work/nitrogen6x-poky-linux-gnueabi/linux-boundary/3.10.53-r0/build/defconfig ~/fido/sources/meta-fsl-arm-extra/recipes-kernel/linux/linux-boundary-3.10.53/defconfig

In the next blog post we will talk about creating your own recipes for your own software projects.