Embedded module TQMa8xx - YOCTO Linux BSP documentation

During the evaluation of STK_NAME the odds are you will face a package missing from the default image tq-image-weston. In the Yocto build system, package recipies are organized in so called Yocto layers. To find specific recipes or layers, the OpenEmbedded layer index is a good place to start looking. It lists existing layers and corresponding recipes.

Zeus Layers
Zeus Recipes

The easiest approach to add a package recipe to the image, is the usage of the IMAGE_INSTALL_append variable in conf/local.conf file which is located in the build space.

At first, open a new terminal on the development host and to move into the build directory. Continue to initialize the build environment as described in Quickstart BSP

cd ~/workspace/ci-meta-tq 
source setup-environment tqma8xx_build

The example below demonstrates how to add the editor nano to your build. Open conf/local.conf with an editor of your choice and insert the following lines at the end of file:

IMAGE_INSTALL_append = " nano"

You may want add multiple packages using the IMAGE_INSTALL_append variable. This can be done in one line or multiple lines, demonstrated by the following two code-examples.
Multiple packages are always separated by spaces.

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

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

You have added your desired package(s) and may repeat building your image now:

bitbake tq-image-weston

Bitbake provides a script for simplyfying the process of creating new layers. It creates a template layer with the following basic structure:

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

To add a template layer to /ci-meta-tq/sources, like meta-custom in this example, use the bitbake-layers create-layer script:

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

for example…

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

Before making changes to the new layer, it's recommended to perform the following actions:

* 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

Revision control is good practice in modern software development, therefore we recommend to initialize a git-repository for the new yocto layer.

Move into the directory of the new custom layer:

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

Initialize the directory as git repository and make an 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

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"

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

As previously described, it is possible to add packages in a quick and dirty like manner by modifying the local.conf.
The more sensible approach is, to add a packages by creating *.bbappend files to expand the original image recipe. For the STK_NAME evaluation, the default image recipes are provided by the meta-dumpling layer.

For the tqma8xx module it's recommended to build a tq-image-weston. Its recipe is located in …/ci-meta-tq/sources/meta-tq/meta-dumpling/recipe-images/images/tq-image-weston.bb.

The corresponding tq-image-weston.bbappend in the custom layer has to be located in the same path as the orginal tq-image-weston.bb in the meta-dumpling layer.
The commands below demonstrate, how to create an empty tq-image-weston.bbappend file for the default image recipe tq-image-weston.bb:

cd ci-meta-tq/sources/meta-custom
mkdir - p ./recipes-images/images
cd recipes-images/images
nano tq-image-weston.bbappend

Now continue to add the following lines to the new tq-image-weston.bbappend file.
This will extend the search path and add the desired package(s). Make sure the meta-layer, from which the recipe originates, already exists in the sources directory. It also needs to be listed in bblayers.conf.

IMAGE_INSTALL_append = " <recipe-name>"

For example the nano editor will be added:

 IMAGE_INSTALL_append = " nano"

You may repeat building your image now:

bitbake tq-image-weston

The Linux kernel configuration is provided by the linux kernel sources and is located in the source tree at /arch/arm64/configs/imx_v8_defconfig.
The meta-tq layer expands the kernel configuration imx_v8_defconfig by so-called kernel configuration fragments. These fragments are located in …/ci-meta-tq/sources/meta-tq/meta-tq/recipes-kernel/linux/linux-imx-tq-5.4/tqma8.

https://docs.yoctoproject.org/3.3.6/kernel-dev/common.html#creating-configuration-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-imx-tq-5.4/tqma8

Continue to navigate back to the build directory. To begin creating a new configuration fragment, enter the Linux kernel menuconfig with the the following command:

bitbake -c menuconfig virtual/kernel

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

bitbake -c diffconfig virtual/kernel 

After applying the diffconfig command, the path of the new config fragment is printed to the shell. This should look like so:

Config fragment has been dumped into:
/home/embedded/workspace/Zeus-tqma8xx/ci-meta-tq/tqma8xx_build/tmp/work/tqma8xqp_mba8xx-poky-linux/linux-imx-tq/5.4-r0/build/fragment.cfg

Move the configuration fragment to the example layer meta-custom. Here it is good practice, to give the fragment a unique name with reference to the options it activates/deactivates.
For this example, it will simply be named example.cfg:

mv ~/workspace/Zeus-tqma8xx/ci-meta-tq/tqma8xx_build/tmp/work/tqma8xqp_mba8xx-poky-linux/linux-imx-tq/5.4-r0/build/fragment.cfg ~/workspace/zeus-tqma8xx/ci-meta-tq/sources/meta-custom/recipes-kernel/linux/linux-imx-tq-5.4/tqma8/example.cfg

The next step is to create a linux-imx-tq_5.4.bbappend file for the kernel recipe located in recipes-kernel/linux/

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI_mx8 += "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, the package name (PN) is “linux-imx-tq-5.4”. The PN describes the package name under the current directory THISDIR.

Finally the Linux kernel has to be cleaned and the image rebuilt:

bitbake -c cleansstate virtual/kernel 

bitbake tq-image-weston

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/zeus-tqma8xx/ci-meta-tq/tqma8xx_build/tmp/work-shared/tqma8xqp-1gb-mba8xx/kernel-source

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

cd ~/workspace/ci-meta-tq/tqma8xx_build/tmp/work-shared/tqma8xqp-1gb-mba8xx/kernel-source

Make your changes in the source code, e.g. in the device tree file arch/arm64/boot/dts/freescale/imx8qxp-mba8xx.dts

nano arch/arm64/boot/dts/freescale/imx8qxp-mba8xx.dts

Check the status of the repository with git status command

git log 

Take the latest commit from the output and execute git diff <latest commit> to see all changes.

Redirect the output to a patch file in the example layer …/ci-meta-tq/sources/meta-custom/recipes-kernel/linux-imx-tq-5.4/example.patch.

Add patch to the build

Now expand the SRC_URI_mx8 variable in the Linux kernel recipe by the .patch file created before.
For this purpose, the linux-imx-tq_5.4.bbappend file from the Customize linux kernel configuration section can be reused.
If the file wasn't created yet, do so now.

You created the file just now -> add this:

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

You created the file before, following this guide -> add only the example.patch to the ''SRC_URI'' variable:

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

Now, finally the kernel has to be cleaned and rebuilt:

bitbake -c cleansstate virtual/kernel 

bitbake tq-image-weston

The best way to develope using your own mainboard, is to create a new repository with kernel sources.

Follow the first five steps from the Quickstart BSP guide and navigate to the build directory.
Now clone the kernel sources to a local git repository:

mkdir -p ../local_repos/
https://github.com/tq-systems/linux-tqmaxx.git
cd ../local_repos/linux-tqmaxx
git reset --hard
git clean -fdx
git checkout zeus.TQMa8Xx.BSP.SW.0055 -b zeus 

Make your own branch in the git repository

git checkout -b custom-branch

Make your changes in the source code and make a commit:

e.g. nano arch/arm64/boot/dts/freescale/imx8qxp-mba8xx.dts
edit and save
git commit -a -m "my changes"

Save the commit ID, you can print them using one of 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 by following the steps previously described.

Navigate into the new layer and recreate the path structure of meta-tq.

cd ci-meta-tq/sources/meta-custom
mkdir -p ./recipes-kernel/linux/linux-imx-tq-5.4/tqma8

Now create the linux-imx-tq_5.4.bbappend file for the kernel recipe located in meta-custom/recipes-kernel/linux/

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

Finally rebuild your kernel using the following command:

bitbake -c build virtual/kernel

You may repeat building your image now

bitbake tq-image-weston