Customizing the BSP

Note

There is no need at all to modify any existing files in the Yocto source directory to customize the BSP for your own hardware. Rather than that you should create a separate layer for your customizations where you can augment or override the original recipes.

This page describes how to add a custom layer to our Mainline BSP. You will also get an idea how Yocto recipes work and how you can create your own image.

Your possibilities with Yocto are endless - if you know how to use it. The sections below shall just give common examples and an easier entry.

Further information can be found in the Yocto Project Documentation.

Hint

All commands listed below are examples and have to be fitted to your needs.

Set up your build-directory with the desired machine and distro like explained in BSP Setup.

DISTRO=karo-minimal MACHINE=qsmp-1570 source karo-setup-release.sh -b build-qsmp-1570

You may optionally define a baseboard in your environment setup:

DISTRO=karo-minimal MACHINE=qsmp-1570 KARO_BASEBOARD=qsbase2 source karo-setup-release.sh -b build-qsmp-1570

This will enable the following changes:

  • U-Boot will use the ${MACHINE}-${KARO_BASEBOARD}_env.txt file instead of ${MACHINE}_env.txt for the initial env configuration.

  • U-Boot will use ${SOC_PREFIX}-${MACHINE}-${KARO_BASEBOARD}.dtb instead of ${SOC_PREFIX}-${MACHINE}.dtb as the DTB for the U-Boot internal device configuration.

Kernel & Devicetree

The following steps describe how Kernel and Devicetree can be modified.
You can use these steps to develop Kernel and Devicetree fitted to your needs.
Once you’re done you can read further to persist your changes.

Create Custom Layer

To persist your developed changes and extend our BSP the best way is to create your own layer.

E.g.:

MACHINE = "qsmp-1570"
KARO_BASEBOARD = "myboard"

will result in the following changes in the U-Boot configuration:

CONFIG_DEFAULT_ENV_FILE="qsmp-1570-myboard_env.txt"
CONFIG_DEFAULT_DEVICE_TREE="stm32mp157c-qsmp-1570-myboard"

Use bitbake-layers to create a new layer and add it to conf/bblayers.conf in your build-directory.

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

This creates an empty example layer for you:

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

3 directories, 4 files

Customizing the U-Boot Recipe

recipes-bsp/u-boot/u-boot-karo

Add a custom DTB

Customizing the U-Boot configuration

Customizing the U-Boot Default Environment

To customize the U-Boot default environment, you can either use ‘KARO_BASEBOARD’ as described above or overwrite the environment file from the yocto distribution with your own file by creating the file
‘’recipes-bsp/u-boot/u-boot-karo/env/${MACHINE}_env.txt’’ and adding
‘’recipes-bsp/u-boot/u-boot-karo_2020.04.bbappend’’ in your custom layer layer with something like:

FILESEXTRAPATHS:prepend := "${THISDIR}/${BP}:"

This will make sure, that “${MACHINE}_env.txt” is taken from your custom layer rather than meta-karo.

Customizing the Linux Kernel Recipe

You can remove the recipes-example folder inside your custom layer. Instead add a folder recipes-kernel with different subdirectories.

rm -rf ../layers/meta-custom/recipes-example/
mkdir -p ../layers/meta-custom/recipes-kernel/linux/linux-karo/patches
mkdir ../layers/meta-custom/recipes-kernel/linux/linux-karo/stm32mp1

Now create the *.bbappend file to extend the kernel recipe.

touch ../layers/meta-custom/recipes-kernel/linux/linux-karo_5.15.bbappend

The content of linux-karo_5.15.bbappend could be something like this:

 1FILESEXTRAPATHS:prepend := "${THISDIR}/${PN}/patches:${THISDIR}/${PN}:"
 2
 3SRC_URI:append = " \
 4    file://${KBUILD_DEFCONFIG} \
 5    file://0001-custom-magic-kernel-source.patch \
 6"
 7
 8SRC_URI:append:stm32mp1 = " \
 9    file://dts/stm32mp157c-qsmp-1570-customboard.dts;subdir=git/arch/arm/boot \
10"
11
12KERNEL_DEVICETREE:append:qsmp-1570 = " \
13    stm32mp157c-qsmp-1570-customboard.dtb \
14"

The files in your custom-layer then would look like this:

../layers/meta-custom/
├── conf
│   └── layer.conf
├── COPYING.MIT
├── README
└── recipes-kernel
    └── linux
        ├── linux-karo
        │   ├── patches
        │   │   └── 0001-custom-magic-kernel-source.patch
        │   └── stm32mp1
        │       ├── defconfig
        │       └── dts
        │           └── stm32mp157c-qsmp-1570-customboard.dts
        └── linux-karo_5.15.bbappend

7 directories, 7 files

Tip

Build your modified Kernel Recipe. 

bitbake linux

This will compile and deploy your modified Kernel and additionally the Devicetree you added.

Note

The way you expanded our kernel recipe, you can customize any recipe inside the BSP. You can use our layers as a reference if unsure what you can do.
You may also add new recipes.

Create Custom Image

To add a custom image you can add a new recipe under recipes-core/images. Your custom layer will then look like this:

../layers/meta-custom/
├── conf
│   └── layer.conf
├── COPYING.MIT
├── README
├── recipes-core
│   └── images
│       └── custom-image.bb
└── recipes-kernel
    └── linux
        ├── linux-karo
        │   ├── patches
        │   │   └── 0001-custom-magic-kernel-source.patch
        │   └── stm32mp1
        │       ├── defconfig
        │       └── dts
        │           └── stm32mp157c-qsmp-1570-customboard.dts
        └── linux-karo_%.bbappend

9 directories, 8 files

The custom-image.bb below would include the karo-image-weston as basis and additionally add the pip3 python package manager.

1SUMMARY = "A custom image with Weston desktop"
2
3require recipes-core/images/karo-image-weston.bb
4
5IMAGE_INSTALL:append = " \
6    python3-pip \
7"

Tip

Build your custom image.

bitbake custom-image

With this example you would get the desired weston desktop image with pip3 included.