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).

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:

• 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.

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!

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

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

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.

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