Skip to content

# Modify the BSP

## Local or temporary modifications

On the first initialization a `local.conf` file is created in the `conf` directory of your build. This file is usually not tracked by git and is meant to be used only for local or temporary changes. Please check `local.conf` and read the comments in the file to find out about some default options.

The default `local.conf` file includes the `sourcecode-version.conf` and `user.conf` file if available. `sourcecode-version.conf` is meant to contain the sourcecode version number for all sourcecode compiled (can be used as software release number). It should be kept in sync with `repo.conf`.

Furthermore the `user.conf` file is meant to hold user specific settings that may be different between different developers. One such example is the URL variable for the package server (PACKAGE_FEED_URIS).

Warning

If you have changes in your `local.conf` that should not stay local, but need to be set as default for everyone who uses the build, then find a way to move these changes to the correct file. Some popular places in the meta layers are:

1. The image recipe in `recipes-core` for image-specific settings
2. The distro config in `conf/distro` for distro-specific settings
3. The machine config in `conf/machine` for machine-specific settings
4. Recipe of some package for package-specific settings

## Create your own layers

If you want to make modifications to the BSP, we suggest to create your own layers to keep your modifications reproducible and to separate them from other layers. For customer boards Kontron uses a `build-<CUSTOMER>` and a `meta-<CUSTOMER>` layer to keep the modifications for special customer boards.

The `build-<CUSTOMER>` layer describes which layers in which version are required to build the product. This is exactly the same as the build-stm32mp layer does for Kontron boards. So the build-stm32mp layer is a good blueprint for your own build layer.

The `meta-<CUSTOMER>` layer holds all adaptions for this board. This can be additional recipes or adaptions to some recipes, separate images, configurations and so on.

See also the Yocto documentation for creating layers.

## Device tree concept

For Kontron boards the device tree files are generated by different inclues. One file for:

- the SoM layer,
- the board layer and
- the housing layer

These includes are combined in the device tree file of the machine. For special cases some include files are obsolete (e.g. hosing include files) or are combined into the final device tree file for the machine. This structure is roughly used for all software components which use the device tree (tf-a, u-boot, linux kernel), except where they do not make sense (e.g. housing configuration for tf-a).

For example the device tree file `stm32mp-t1000-s-50.dts` for Kontron Demo-Kits consists of these device tree components:

dts file | Description | Includes
--- | --- | ---
stm32mp-t1000-s-50.dts | Board with display (housing) | stm32mp-housing-50.dtsi stm32mp-t1000-s.dts
stm32mp-t1000-s.dts | Board without display | stm32mp-board-s.dtsi stm32mp-som-t1000.dtsi stm32mp157c-t1000-s-mx.dts

- `stm32mp157c-t1000-s-mx.dts`
  Device tree file generated from CubeMX (maybe generated by user for his own baseboard). This is intended to do the pin multiplexing for the board. Contains all but also incomplete configuration for the board of:
  - clock settings
  - pinmux functions
  - DDR settings
- `stm32mp-som-t1000.dtsi`
  Include file for SoM component (fixed configurations for SoM)
  This is intended to fix parts which shouldn't be changed when using a SoM
  - overwirtes DDR settings
  - overwrites pinmux and functions implemented on SoM (e.g. DDR, ethernet, nand, nor, ...)
  - overwrites base clock domain settings (done in tf-a)
- `stm32mp-board-s.dtsi`
  Include file for baseboard (by user for his baseboard)
  - complete the device tree configuration for the board by adding nodes and properties
- `stm32mp-housing-50.dtsi`
  Include file for housing (optionally, by user for his board)
  This is intended to do settings which aren't parts of the baseboard so that these parts can be changed without changing the baseboard (e.g. display timings or touch controller settings)

The include file for the SoM component in tf-a (and u-boot) also defines default clock settings and default system partitioning settings (ETZPC, all set to DECPROT_NS_RW, DECPROT_UNLOCK). They overwrite the settings from the CubeMX device tree file. To prevent this, set `#define RCC_FROM_MX` or `#define ETZPC_FROM_MX` before including the SoM file.

If you want to create your own board, the best way is to start from a already existing CubeMX board configuration and modify it for your board.

## Create your own board

When you want to create your own board, we propose to execute these steps:

- Create your own build- and meta layer, if not already done
- Create your own machine description. Use one of the existing ones as blueprint
- Create an extlinux configuration for your board
- Create the devicetree files for your board

Depending on how far your design differs from Kontron Demo-Kits the creation of device tree files may vary a lot!

If your pin multiplexing and clock setting doesn't differ from the Demo-Kits you can use the device tree files for tf-a from this Demo-Kit. Else you have to start your own with CubeMX and integrate that in your device tree stack.

For u-boot you have to create your configurataion with your own device tree file which contains the name of your board in the compatible string. This string is used from extlinux to search the right board description. So your compatible string has to match the extlinux configuration.

Kontron provides CubeMX configurations and device tree files for all Demo-Kits and also for all bare SoM devices. The difference between these configuration is, that the Demo-Kits own a rich pin multiplexing. It is a good starting point if you only want to do small configuration changes.

In contrast, the configurations of SoM devices only contain configurations for the bare minimum peripherals. Normally this is limited to all recommended signals: serial console, SD card interface, USB host and OTG interface and LED on PA13. Also the not changeable interfaces are included (like NOR, NAND, Ethernet or GPIOs on some SoMs). All other pins are left in default configuration.

This way the configuration of the SoM device should boot on all baseboards with this SoM and the recommended signals implemented.

Important

Alhtough it is possible to change the pin multiplexing for SD card (SDMMC1), LED1 and serial console (UART4), it is highly recommended to leave these settings untouched for your board! When you change these recommended settings, you will have to modify various software parts (in case of console) or will loose the ability to boot from SD card with default otp settings. LED1 is also used by BOOTROM for signalling USB downloader state.

For this reason, these recommended pins are already configured in the bare minimum CubeMX configurations for your SoM.

## Modifying the kernel configuration

The kernel configuration can be modified using the following steps.

1) Make modifications to your configuration

    bitbake virtual/kernel -c menuconfig

Adapt the kernel configuration to your needs.

2) Rebuild the kernel for testing your new configuration

Now you can rebuild the kernel to test your modifications:

    bitbake virtual/kernel -C compile -f

Either you generate a new image and flash it on the device or you simply exchange the kernel image file `uImage` in the `/boot` directory of your device!

Hint

Be aware, this only works if no kernel modules are added or modified!

Test your changes and do some more modifications if needed.

3) Create new configuration and integrate in recipe

When the configuration matches your wishes, you should generate your modified configuration for the yocto recipe. If you want to have a complete defconfig file for your kernel configuration use the `savedefconfig` option:

     bitbake virtual/kernel -c savedefconfig

Else if you only want to generate a kernel configuraion fragment use the `diffconfig` option:

     bitbake virtual/kernel -c diffconfig

Attention

After you did a diffconfig with your kernel configuration, the kernel configuration in your source tree is reset to the defaults before your modifications. The modifications can now be found in your `fragment.cfg` file which has to be integrated in your kernel recipe.

Integrate your kernelconfig or kernelconfig fragment into your kernel recipe.

4) Rebuild kernel to test your recipe

Finally you should rebuild your kernel to validate your modified recipe:

    bitbake virtual/kernel

More informations can be found in STMicroelectronics Wiki

## Recompile kernel device tree

Sometimes it is required to change the device tree configuration of your setup and test it on your board. A possibility to do this without the complete Yocto bitbake process is to use the bitbake `devshell` command.

A simlpe workflow could be like this:

A prerequisite is that the linux kernel is already compiled. Then you can go to the source directory (maybe the workspace of a devtool workflow) and change your device tree files. Then start the bitbake devshell:

    bitbake virtual/kernel -c devshell

Now source `recipe.env` which contains the environment variables where the source code and the build output for the linux kernel is located. Then build your device tree

    > source recipe.env
    Output directory O=/home/user/[...]/build-stm32mp/tmp/work/stm32mp_t1000_s_multi-ktn-linux-gnueabi/linux-stm32mp/4.19-r0/linux-stm32mp-t1000-s-multi-standard-build
    Kernel source directory KDIR=/home/user/[...]/build-stm32mp/tmp/work/stm32mp_t1000_s_multi-ktn-linux-gnueabi/linux-stm32mp/4.19-r0/git
    Makeflags MF=-j6 ARCH=arm O=/home/user/[...]/build-stm32mp/tmp/work/stm32mp_t1000_s_multi-ktn-linux-gnueabi/linux-stm32mp/4.19-r0/linux-stm32mp-t1000-s-multi-standard-build CROSS_COMPILE=arm-ktn-linux-gnueabi- LOADADDR=0xC2000040
    CROSS_COMPILE=arm-ktn-linux-gnueabi-

    > makey stm32mp-t1000-s.dtb
    [...]

    > ls -l $O/arch/arm/boot/dts
    -rw-r--r-- 1 1000 1000 71560 Nov 14 16:26 stm32mp-t1000-s.dtb

Info

The 'makey' command is an alias and calls make with the appropriate directory parameters

## Modifying the u-boot configuration

The u-boot configuration is currently split into two concepts: In the past u-boot configuration was only done by setting configuration variables in header files for your board. Nowadays u-boot also contains a menuconfig interface to configure many aspects of u-boot functionality. Unfortunately not all configuration can be done with menuconfig.

Yocto doesn't provide the menuconfig way as easy as it is provided for the linux kernel. So a different workflow has to be used:

Fist start the devshell for the bootloader

    > bitbake virtual/bootloader -c devshell

Then try to source the `recipe.env` file:

    > source recipe.env
    ERROR: Set DEFCONFIG in your environment and source again!
    Currently available configs:
        export DEFCONFIG=stm32mp15_basic_defconfig
        export DEFCONFIG=stm32mp1-t1000_defconfig
        export DEFCONFIG=stm32mp1-t1000-evk50_defconfig
        export DEFCONFIG=stm32mp1-t1000-evk50sdcard_defconfig
        export DEFCONFIG=stm32mp1-t1000-evkmanualtest_defconfig
        export DEFCONFIG=stm32mp1-t1000-manualtestevk_defconfig
        export DEFCONFIG=stm32mp1-t1000-sdcard_defconfig
    bash: unalias: makey: not found

When you have multiple u-boot configurations the soucing fails and you have to select which u-boot configuration you want to change. Set the `DEFCONIG` variable to the appropriate value, source again and start the configuration GUI:

    > export DEFCONFIG=stm32mp1-t1000_defconfig
    > source recipe.env
    Output directory O=/home/user/[...]/build-stm32mp/tmp/work/stm32mp_t1000_s_multi-ktn-linux-gnueabi/u-boot-stm32mp/2018.11-r0/build/stm32mp1-t1000_defconfig
    Makeflags MF=-j6 ARCH=arm CROSS_COMPILE=arm-ktn-linux-gnueabi- O=/home/user/[...]build-stm32mp/tmp/work/stm32mp_t1000_s_multi-ktn-linux-gnueabi/u-boot-stm32mp/2018.11-r0/build/stm32mp1-t1000_defconfig
    CROSS_COMPILE=arm-ktn-linux-gnueabi-
    > makey menuconfig

After the configuration is finished, create a `defconfig` file:

    > makey savedefconfig
    make[1]: Entering directory '/home/user/[...]/build-stm32mp/tmp/work/stm32mp_t1000_s_multi-ktn-linux-gnueabi/u-boot-stm32mp/2018.11-r0/build/stm32mp1-t1000_defconfig'
      HOSTCC  scripts/kconfig/conf.o
      HOSTLD  scripts/kconfig/conf
    scripts/kconfig/conf  --savedefconfig=defconfig Kconfig
    make[1]: Leaving directory '/home/user/[...]/build-stm32mp/tmp/work/stm32mp_t1000_s_multi-ktn-linux-gnueabi/u-boot-stm32mp/2018.11-r0/build/stm32mp1-t1000_defconfig'

    > ls -l $O/defconfig
    -rw-rw-r-- 1 root root 2631 Nov 14 16:44 /home/user/[...]/build-stm32mp/tmp/work/stm32mp_t1000_s_multi-ktn-linux-gnueabi/u-boot-stm32mp/2018.11-r0/build/stm32mp1-t1000_defconfig/defconfig

This file now has to be integrated in the u-boot-stm32mp recipe of Yocto.

## Using devtool to work on source code

To work on the source code of any package it is most convenient to use the `devtool` utility. As an example we will show how to modify the kernel code.

Tip

For more information about the mighty `devtool`, please visit the Yocto Manual.

To start working on the `linux-stm32mp` code:

    devtool modify linux-stm32mp

A separate workspace layer will be created and the kernel source tree will be extracted there. Do your code changes and run a build with:

    bitbake linux-stm32mp

Test your changes and create patches if necessary. To reset to the previous state and build without the changes in the workspace run:

    devtool reset linux-stm32mp