Embedded module TQMLS1028A - YOCTO Linux BSP documentation
Customize Yocto
Prerequisites
In preparation for this guide, the MOD_NAME_HEAD BSP default image tq-image-generic-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 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.
Hardknott Layers
Hardknott 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 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> \ "
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
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 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"
You may repeat building your image now:
bitbake tq-image-generic-debug
Customize Linux kernel configuration
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-rt-lsdk-tq-5.4/tqmls1028a.
https://docs.yoctoproject.org/3.3.6/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-rt-lsdk-tq-5.4/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/hardknott-tqmls1028a/ci-meta-tq/tqmls1028a_build/tmp/work/tqmls1028a_mbls1028a-poky-linux/linux-rt-lsdk-tq/5.10-r0/build/.config
Move the defconfig file to the example layer meta-custom:
mv ~/workspace/hardknott-tqmls1028a/ci-meta-tq/tqmls1028a_build/tmp/work/tqmls1028a_mbls1028a-poky-linux/linux-rt-lsdk-tq/5.10-r0/build/.config ~/workspace/hardknott-tqmls1028a/ci-meta-tq/sources/meta-custom/recipes-kernel/linux/linux-rt-lsdk-tq-5.4/tqmls1028a/defconfig
The next step is to create a linux-rt-lsdk-tq_5.4.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-rt-lsdk-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-generic-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/hardknott-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/hardknott-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-mbls102a.dtsi
nano arch/arm64/boot/dts/freescale/tqmls1028a-mbls102a.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-rt-lsdk-tq-5.4/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-rt-lsdk-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:
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 zeus.TQMLS1028A.BSP.SW.0108 -b hardknott
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-mbls102a.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-rt-lsdk-tq-5.4/tqmls1028a
Now create the linux-rt-lsdk-tq_5.4.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