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.

Create Custom Layer

It is recommended to create your own DISTRO based on one of the Ka-Ro provided DISTROs. To facilitate this, you should prefix your DISTRO name with ‘karo-custom-’ (e.g. ‘karo-custom-mydistro’) and name your custom layer directory ‘meta-mydistro’. This will ensure, that your own layer will automatically be added to conf/bblayers.conf in your build directory when using karo-setup-release.sh.

Your custom layer directory should have the following structure:

${BSPDIR}/layers/meta-mydistro:
  ├── conf
  │   └── layer.conf
  └── recipes-...

DISTRO=karo-custom-mydistro 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=qsbase1 source karo-setup-release.sh -b build-qsmp-1570

This will enable the following changes:

  • U-Boot will use the ${MACHINE}-${KARO_BASEBOARD}.env file instead of ${MACHINE}.env 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.

Creating your own baseboard settings

It will most probably be desirable to add your own baseboard setting to the yocto environment. The following steps are necessary to achieve this (replace ‘myboard’ in the subsequent statements with your own boardname):

  • Add:

KARO_BASEBOARDS += "myboard"

to your distro.conf file and set up the list of DTB overlays that are needed to support the features of your board as described in Adding overlays for a custom baseboard

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.

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’’ and adding
‘’recipes-bsp/u-boot/u-boot-karo_2022.04.bbappend’’ in your custom layer layer with something like:

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

This will make sure, that “${MACHINE}.env” 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_6.1.bbappend

The content of linux-karo_6.1.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_6.1.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.