Embedded module TQMLS1028A - YOCTO Linux BSP documentation

In preparation for this guide, the TQMLS1028A BSP default image tq-image-generic-debug was built according to the Quickstart BSP instructions.

Add a package

The changes described here will affect your local build space only. They will not remain whenever your build space is lost or needs to be recreated.
This method is recommended for testing/evaluation purposes only.

During the evaluation of STK_NAME the odds are you will face a package missing from the default image tq-image-generic-debug. 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.

Kirkstone Layers
Kirkstone Recipes

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

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 tqmls1028a_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> \
                       "

CAUTION: The leading space in front of the first package is important.
IMAGE_INSTALL_append will extend IMAGE_INSTALL, therefore a space separating the contents of both character strings is required.

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

bitbake tq-image-generic-debug

Note here again, that changes to the local.conf only affect your current build space. They will get lost when your buildspace is resetted.
Create a custom yocto layer for a proper implementation.

The next section shows how to create a new custom layer on the example of meta-custom, which will be created in ci-meta-tq/sources.

Creating a new yocto layer

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

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 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 tqmls1028A module it's recommended to build a tq-image-generic-debug. Its recipe is located in …/ci-meta-tq/sources/meta-dumpling/recipe-images/images/tq-image-generic-debug.bb.

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

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

Now continue to add the following lines to the new tq-image-generic-debug.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"

For your .bbappend file to work properly, please keep in mind that you should remove the package from the local.conf file if it was added to the build there before.

You may repeat building your image now:

bitbake tq-image-generic-debug

Configuring the kernel

The meta-tq layer provides the kernel configuration defconfig file, it is located in …/ci-meta-tq/sources/meta-tq/recipes-kernel/linux/linux-imx-tq-5.15/tqmls1028a.

https://docs.yoctoproject.org/4.0.11/kernel-dev/common.html#creating-a-defconfig-file

Before creating the new defconfig file, the path that holds the defconfig has to be recreated in meta-custom.

cd ci-meta-tq/sources/meta-custom
mkdir -p ./recipes-kernel/linux/linux-imx-tq-5.15/tqmls1028a

Afterwards navigate back to the build directory and start to create a new defconfig by entering 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 savedefconfig virtual/kernel

After applying savedefconfig command, the path of the new defconfig is printed to the shell. This should look like so:

Config fragment has been dumped into:
/home/embedded/workspace/kirkstone-tqmls1028a/ci-meta-tq/tqmls1028a_build/tmp/work/tqmls1028a_mbls1028a-poky-linux/linux-imx-tq/5.15-r0/build/.config

Move the defconfig file to the example layer meta-custom:

mv ~/workspace/kirkstone-tqmls1028a/ci-meta-tq/tqmls1028a_build/tmp/work/tqmls1028a_mbls1028a-poky-linux/linux-imx-tq/5.15-r0/build/.config ~/workspace/kirkstone-tqmls1028a/ci-meta-tq/sources/meta-custom/recipes-kernel/linux/linux-imx-tq-5.15/tqmls1028a/defconfig

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

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
SRC_URI = "file://defconfig"

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.15”. 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-generic-debug

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/kirkstone-tqmls1028A/ci-meta-tq/tqmls1028A_build/tmp/work-shared/tqmls1028a-mbls1028a/kernel-source

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

cd ~/workspace/kirkstone-tqmls1028A/ci-meta-tq/tqmls1028A_build/tmp/work-shared/tqmls1028a-mbls1028a/kernel-source

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

nano arch/arm64/boot/dts/freescale/tqmls1028a-mbls1028a.dtsi

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.15/example.patch.

Add patch to the build

Now expand the SRC_URISRC_URI_EXTENSION variable in the Linux kernel recipe by the .patch file created before.
For this purpose, the linux-imx-tq_5.15.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<label src_uri_extension>SRC_URI_EXTENSION</label> += "\
    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<label src_uri_extension>SRC_URI_EXTENSION</label> += "\
    file://example.cfg \
    file://example.patch \
    "

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

bitbake -c cleansstate virtual/kernel

bitbake tq-image-generic-debug

Creating and using a local kernel repository

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 kirkstone.TQMLS1028A.BSP.SW.0109 -b kirkstone

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/tqmls1028a-mbls1028a.dtsi
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.15/tqmls1028a

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

SRC_URI_remove<label src_uri_extension>SRC_URI_EXTENSION</label> = "${TQ_GIT_BASEURL}/linux-tqmaxx.git;protocol=${TQ_GIT_PROTOCOL};branch=${SRCBRANCH}"
SRC_URI_append<label src_uri_extension>SRC_URI_EXTENSION</label> = "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-generic-debug

Embedded module TQMLS1028A - YOCTO Linux BSP documentation

Customize Yocto

Prerequisites

Without the creation of a custom yocto layer

Add a package

Creating and adding a new yocto layer

Creating a new yocto layer

Create a git repository for the new layer

Editing README

Layer license

Configure layer priority

Adding the new layer to build

Adding a package to an existing image recipe

Customize Linux kernel configuration

Configuring the kernel

Creating and adding Linux kernel patch

Creating and adding Linux kernel patch

Add patch to the build

Creating and using a local kernel repository