Embedded module TQMa93xxLA - YOCTO Linux BSP documentation
Customize Yocto
Prerequisites
In preparation for this guide, the TQMa93xxLA BSP default image tq-image-weston-debug was built according to the Quickstart BSP instructions.
Without the creation of a custom yocto layer
Add a package
This method is recommended for testing/evaluation purposes only.
During the evaluation of STKa93xxLA the odds are you will face a package missing from the default image tq-image-weston-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
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 tqma93xxla_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> \ "
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-weston-debug
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 and adding a new yocto layer
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
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"
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 STKa93xxLA evaluation, the default image recipes are provided by the meta-dumpling layer.
For the tqma93xxla module it's recommended to build a tq-image-weston-debug. Its recipe is located in …/ci-meta-tq/sources/meta-tq/meta-dumpling/recipe-images/images/tq-image-weston-debug.bb.
The corresponding tq-image-weston-debug.bbappend in the custom layer has to be located in the same path as the orginal tq-image-weston-debug.bb in the meta-dumpling layer.
The commands below demonstrate, how to create an empty tq-image-weston-debug.bbappend file for the default image recipe tq-image-weston-debug.bb:
cd ci-meta-tq/sources/meta-custom mkdir -p ./recipes-images/images cd recipes-images/images nano tq-image-weston-debug.bbappend
Now continue to add the following lines to the new tq-image-weston-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"
You may repeat building your image now:
bitbake tq-image-weston-debug
Customize Linux kernel configuration
Configuring the kernel
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.15/tqma8.
https://www.yoctoproject.org/docs/4.0.10/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.15/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/Kirkstone-tqma93xxla/ci-meta-tq/tqma93xxla_build/tmp/work/tqma93xxla_mba9xxla-poky-linux/linux-imx-tq/5.15-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/Kirkstone-tqma93xxla/ci-meta-tq/tqma93xxla_build/tmp/work/tqma93xxla_mba9xxla-poky-linux/linux-imx-tq/5.15-r0/build/fragment.cfg ~/workspace/Kirkstone-tqma93xxla/ci-meta-tq/sources/meta-custom/recipes-kernel/linux/linux-imx-tq-5.15/tqma8/example.cfg
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_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.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-weston-debug
Creating and adding Linux kernel patch
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-tqma93xxla/ci-meta-tq/tqma93xxla_build/tmp/work-shared/tqma03xxla-mba93xxla/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/tqma03xxla-mba93xxla/kernel-source
Make your changes in the source code, e.g. in the device tree file arch/arm64/boot/dts/freescale/imx93-tqma9352-mba93xxla.dts
nano arch/arm64/boot/dts/freescale/imx93-tqma9352-mba93xxla.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.15example.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.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:
Now, finally the kernel has to be cleaned and rebuilt:
bitbake -c cleansstate virtual/kernel
bitbake tq-image-weston-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.TQM.ARM.BSP.0007 -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/imx93-tqma9352-mba93xxla.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.15/tqma8
Now create the linux-imx-tq_5.15.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-debug
Customize U-Boot configuration
Creating and adding U-Boot patch
after building the default image tq-image-weston-debug the u-boot sources are located at …/tqma8xx_build/tmp/work/tqma8xqp_mba8xx-poky-linux/u-boot-imx-tq/2019.04-r0/git
Creating a hello world recipe
Customize busybox configuration
Busybox can be configured by the following command:
bitbake -c menuconfig busybox
After saving and exiting the menuconfig a new diffconfig has to generated