Embedded module TQMaRZG2x - YOCTO Linux BSP documentation

As preparation for this guide the default image core-image-hmi was build according to the Quickstart BSP instructions.

Add a package

Without an own yocto layer your changes will not be saved if you lost or have to recreate your build space. This option is only recommended for test or try out something.

When evaluating the STKaRZG2x sooner or later it comes to the moment that a required package is not present in the default image core-image-hmi. In the Yocto buildsystem package recipies are typically organized in Yocto layers. To find a specific recipe or layer the Openembedded layer index is a good starting point, it gives an overview about the existing layers and the corresponding recipes.

Rocko Layers
Rocko Recipes

Adding a package to the build, may require adding additional layer(s) to the build

A very simple approach to add a package recipe to the image build is the usage of the IMAGE_INSTALL_append variable in conf/local.conf file which is located in the build space.

The first thing is to open a new terminal on your development host and to move to the build directory. Afterwards initialize the build environment as described in the Quickstart BSP

$ cd ~/workspace/ci-meta-tq 
$ source setup-environment tqmarzg2x_build

As an example the editor nano will be added to the image. Open the conf/local.conf with an editor of your choice and add the following line at the end of the local.conf file.

IMAGE_INSTALL_append = " nano"

It is also possible to add multiple packages with the IMAGE_INSTALL_append variable, it is possible to add packages in one line or multiple lines. The leading space is important, because the variable IMAGE_INSTALL will be extended and the space separates the packages in the list.

IMAGE_INSTALL_append = " <recipe-name_1> <recipe-name_2>"

IMAGE_INSTALL_append = " \
                       <recipe-name_1> \
                       <recipe-name_2> \
                       "

After adding the desired package(s), the image build has to be started again by the command:

$ bitbake core-image-hmi

Customizations to the local.conf are only in available the actual build space, if the build space will get lost or must be recreated for some reason, changes to the local.conf will also get lost.

The common approach for customizations to meta-tq or other Yocto layers is to create a new custom layer, the next section describes how to create such a yocto layer. As an example the new layer meta-custom will be created in the sources folder of ci-meta-tq.

Creating a new Yocto Layer

Bitbake provides the bitbake-layers create-layer script that simplifies creating a new general layer, the following basic layer structure will be created:

├── conf
│   └── layer.conf
├── COPYING.MIT
├── README
└── recipes-example
    └── example
        └── example_0.1.bb

In ci-meta-tq the Yocto layers are located in /ci-meta-tq/sources the example layer meta-custom can be added by applying the commands below:

$ bitbake-layers create-layer <path/to/your_layer>

e.g.

$ bitbake-layers create-layer ../sources/meta-custom

Some actions are recommended, before starting to work with the new layer:

* Initialize the new layer as git repository 
* Editing the README template 
* Check and if necessary adjust the license of the layer
* Configuring the layer priority in layer.conf

Create a git repository for the new layer

Reversion control is good practice in modern software development, so we recommend initialize the newly created meta-custom layer as git repository.

Move to the root directory of the example layer meta-custom.

$ cd ~/workspace/ci-meta-tq/sources/meta-custom

Initialize the meta-custom layer as git repository and make the initial commit

$ git init
$ git add .
$ git commit -m "Initial Commit"

Editing README

The README file should give a brief overview of the layer.
Among other things the README should contain:

Description of the layer content
Dependencies to other layers e.g. meta-tq
A description how to use the layer

The README of the meta-tq layer can be taken as an example.

Layer license

By default the layer is licensed with the MIT license, the licensing must be updated according to the requirements.

Configure layer priority

The bitbake-layers create-layer script sets a layer priority of 6 by default, which is defined in the conf/layer.conf file. In this example the layer priority is set to a value of “10” to ensure that the meta-custom example layer has the highest priority.

BBFILE_PRIORITY_meta-custom = "10"

Ensure that priority of the new layer has a higher priorty than the layer that is used to build upon.

Adding the new layer to build

Before the new layer can be used for the build, it must be added to the conf/bblayers.conf file in your build directory.

$ echo 'BBLAYERS += "${BSPDIR}/sources/meta-custom"' >> conf/bblayers.conf

Adding a package to an existing image recipe

As described above as quick and simple way, it is possible to add a package via the local.conf. The common approach to add a package is to create a *.bbappend file to expand the original image recipe. For the STKaRZG2x evaluation the default image recipes are provided by the meta-rzg2 layer.

For the TQMaRZG2x it is recommended to build image core-image-hmi. It is located in …/ci-meta-tq/sources/meta-rzg2/recipe-images/core-image-hmi.bb

The corresponding core-image-hmi.bbappend in the custom layer has to be located in the same path as the orginal core-image-hmi.bb in the meta-rzg2 layer. The commands below show how to create the empty core-image-hmi.bbappend file for the default image recipe core-image-hmi.bb:

$ cd ci-meta-tq/sources/meta-custom
$ mkdir ./recipes-images/
$ cd recipes-images
$ touch core-image-hmi.bbappend

After creating add the following lines to the new and empty core-image-hmi.bbappend file to extend the search path and add the desired package. Please check that the meta-layer from which the recipe originates already exists in the sources directory and is listed in the bblayers.conf.

 IMAGE_INSTALL_append = " <recipe-name>"

For example the nano editor will be added:

 IMAGE_INSTALL_append = " nano"

Please keep in mind to remove the package from the local.conf file, if it was added to the build via the local.conf before. This can currupt the build and it cannot be ensured that the new .bbappend file works properly

Finally the image with the new package can be built again by the command:

$ bitbake core-image-hmi

Configuring the kernel

The Linux kernel configuration is provided by the linux kernel sources and is located within the source tree under /arch/arm64/configs/defconfig.
The meta-tq layer expands the kernel configuration defconfig by so-called kernel configuration fragments. These fragments are located in …/ci-meta-tq/sources/meta-tq/recipes-kernel/linux/linux-renesas/.

https://www.yoctoproject.org/docs/2.4.3/kernel-dev/kernel-dev.html#creating-config-fragments

Before creating the new configuration fragment the path that holds the configuration fragments has to be recreated in meta-custom.

$ cd ci-meta-tq/sources/meta-custom
$ mkdir -p ./recipes-kernel/linux/linux-renesas/

Afterwards navigate back to the build directory and start to create a new configuration fragment by entering the Linux kernel menuconfig with the the following command:

$ bitbake -c menuconfig virtual/kernel

Select or unselect the required/desired kernel options, afterwards save and exit the menuconfig. The new configuration fragment can now be created by:

$ bitbake -c diffconfig virtual/kernel

After applying diffconfig command the shell prints the configuration fragment storage path, something like the following:

Config fragment has been dumped into:
/home/embedded/workspace/rocko.TQMaRZG2x.BSP.SW.0010/ci-meta-tq/tqmarzg2x_build/tmp/work/tqmarzg2n_b_mbarzg2x-tq-linux/linux-renesas/4.19.140+gitAUTOINC+663fd93cd9-r1/fragment.cfg

Move the configuration fragment to the example layer meta-custom, a unique name with reference to the activated/deactivated options should be given to the config fragment in this case it is named example.cfg:

$ mv ~/workspace/rocko.TQMaRZG2x.BSP.SW.0010/ci-meta-tq/tqmarzg2x_build/tmp/work/tqmarzg2n_b_mbarzg2x-tq-linux/linux-renesas/4.19.140+gitAUTOINC+663fd93cd9-r1/fragment.cfg ~/workspace/rocko.TQMaRZG2x.BSP.SW.0010/ci-meta-tq/sources/meta-custom/recipes-kernel/linux/linux-renesas/example.cfg

The next step is to create linux-renesas_4.19.bbappend file for the kernel recipe located in recipes-kernel/linux/

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += "file://example.cfg"

The FILESEXTRAPATHS_prepend variable extends the search path of BitBake to include a directory named after the package that is being processed. in this case PN is “linux-renesas”. PN describes the package name under the current directory, THISDIR.

Finally the kernel has to be cleaned and rebuilt:

$ bitbake -c cleansstate virtual/kernel

$ bitbake core-image-hmi

Creating and adding Linux kernel patch

The Linux kernel source is provided as a git repository and available in the following path after building tq-image-weston with the Quickstart BSP

$ ~/workspace/rocko.TQMaRZG2x.BSP.SW.0010/ci-meta-tq/tqmarzg2x_build/tmp/work-shared/tqmarzg2n_b-mbarzg2x/kernel-source

Open a new terminal and navigate to the kernel sources used for the build

$ cd ~/workspace/rocko.TQMaRZG2x.BSP.SW.0010/ci-meta-tq/tqmarzg2x_build/tmp/work-shared/tqmarzg2n_b-mbarzg2x/kernel-source

Make your changes in the source code. For example change the model string in the device tree file tqmarzg2n_b.dtsi

e.g.

$ nano ~/workspace/rocko.TQMaRZG2x.BSP.SW.0010/tqmarzg2x_build/tmp/work-shared/tqmarzg2n_b-mbarzg2x/kernel-source/arch/arm64/boot/dts/renesas/tqmarzg2n_b.dtsi

Take the latest commit id from the output and execute git diff <latest commit> to see all changes, if you want to redirect the output to a patch file in the example layer …/ci-meta-tq/sources/meta-custom/recipes-kernel/linux-renesas/example.patch

e.g.

$ git log 
$ git diff <commit_id> 
$ git diff <commit_id> > ~/workspace/rocko.TQMaRZG2x.BSP.SW.0010/ci-meta-tq/sources/meta-tq/recipes-kernel/linux/linux-renesas/example.patch

Add patch to the build

Next step is to expand the SRC_URI variable of the Linux kernel recipe with the example.patch created before. For this purpose the linux-renesas_4.19.bbappend from the customize_linux_kernel_configuration section is reused, otherwise the file has to be created now.

If the linux-renesas_4.19.bbappend file has not been crated add the following to it:

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += "\
    file://example.patch \
    "

If the linux-renesas_4.19.bbappend file has been already created following this guide only the example.patch has to be added to the SRC_URI variable:

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI += "\
    file://example.cfg \
    file://example.patch \
    "

Now the kernel has to be cleaned and rebuilt via bitbake:

$ bitbake -c cleansstate virtual/kernel

$ bitbake core-image-hmi

Creating and using a local kernel repository

The best way for developing with an own mainboard is to use a own repository with the kernel sources.

Follow the first five steps on the Quickstart BSP Instruction and navigate to the build directory. Execute the following commands to clone the kernel sources to a local git repository.

$ mkdir -p ../local_repos/
$ git clone https://github.com/tq-systems/linux-tqmaxx.git
$ cd ../local_repos/linux-tqmaxx
$ git reset --hard
$ git clean -fdx
$ git checkout <label git_checkout>GIT_CHECKOUT</label>

Make your own branch in the git repository

$ git checkout -b custom-branch

Make your changes in the source code and commit them

$ e.g. nano <label example_dts_path>EXAMPLE_DTS_PATH</label>
edit and save
$ git commit -a -m "my changes"

Save the commit ID, you can also see them with the following commands:

To list all of the commits:
$ git log 
Get the latest commit id:
$ git rev-parse HEAD

Create a new yocto layer with the instructions from the Creating and Adding a new Yocto Layer section.

Navigate to the new layer and create the same directory structur as in meta-tq.

$ cd ci-meta-tq/sources/meta-custom
$ mkdir -p ./recipes-kernel/linux/linux-renesas/

The next step is to create linux-renesas_4.19.bbappend file for the kernel recipe located in meta-custom/recipes-kernel/linux/

SRC_URI_remove = "${TQ_GIT_BASEURL}/linux-tqmaxx.git;protocol=${TQ_GIT_PROTOCOL};branch=${SRCBRANCH}"
SRC_URI_append = "git://${BSPDIR}/local_repos/linux-tqmaxx;protocol=file;branch=${SRCBRANCH}"
SRCBRANCH = "custom-branch"
SRCREV = "Your commit ID of the changes"

Finally you can build your kernel with the following command

$ bitbake -c build virtual/kernel

To build the complete image you can use

$ bitbake core-image-hmi

Creating and adding U-Boot patch

after building the default image core-image-hmi the u-boot sources are located at …/tqma8xx_build/tmp/work/tqma8xqp_mba8xx-poky-linux/u-boot-imx-tq/2019.04-r0/git

Busybox can be configured by the following command:

$ bitbake -c menuconfig busybox

After saving and exiting the menuconfig a new diffconfig has to generated

Embedded module TQMaRZG2x - YOCTO Linux BSP documentation

Customize Yocto

Prerequisites

Without an own yocto meta layer

Add a package

Creating and Adding a new Yocto Layer