How to compile the device tree with the Distribution Package

Applicable for STM32MP13x lines, STM32MP15x lines

1 Introduction[edit]

This article is intended for Yocto experts, or people who have some practical experience of the Yocto environmment.

This section describes the steps needed to create and configure a demo layer using DeviceTree files from the STM32CubeMX tool, and to add and configure a machine similar to those already supported by the OpenSTLinux Distribution Package (in particular the machine delivered inside the existing STM32MP BSP layer 'addons').

Reminder: this addon-layer is deployed under the following path in the delivery : <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/

2 Creating a new open embedded layer for your demo[edit]

You first need to create a new layer. See the latest How to create a new open embedded layer

After creation, you have under <path of OpenSTLinux distribution delivery>/layers/meta-st/:

$ tree meta-my-demo-layer
meta-my-demo-layer
├── conf
│   └── layer.conf
├── recipes-example
│   └── example
│       └── example.bb
├── COPYING.MIT
└── README

3 directories, 4 files

2.1 Update layer.conf file[edit]

Open the layer.conf file and add the lines below for the licenses, demo layer path, and dependency with the STM32MP BSP layer 'addons' :

EULA_FILE_ST_stm32mpmydemo = "${LAYERDIR}/conf/eula/${MACHINE}"
EULA_FILE_ST_MD5SUM_stm32mpmydemo = "8b505090fb679839cefbcc784afe8ce9"

#Inform bitbake for adding another location to search for licenses
LICENSE_PATH += "${LAYERDIR}/files/licenses"

# Set a variable to get the STM32MP MX BSP location
STM32MP_MY_DEMO_BASE = "${LAYERDIR}"

# This should only be incremented on significant changes that may
# cause compatibility issues with other layers
LAYERVERSION_meta-my-demo-layer = "1"

LAYERDEPENDS_meta-my-demo-layer = "stm-st-stm32mp-mx"

# OpenEmbedded compatibility information
# This should only be incremented on significant changes that will
# cause compatibility issues with other layers
LAYERVERSION_meta-my-demo-layer = "1"
LAYERSERIES_COMPAT_meta-my-demo-layer = "dunfell"
Info white.png Information
LAYERSERIES_COMPAT must be aligned with the version of OpenEmbedded used.
Please refer to https://wiki.yoctoproject.org/wiki/Releases

2.2 Create the machine for your demo[edit]

2.2.1 Prepare the machine configuration file[edit]

  • Copy the machine delivered inside the existing STM32MP BSP layer 'addons' into your demo layer
$ cp <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/conf/machine/stm32mp1X-mx.conf <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/conf/machine/stm32mp1-demo.conf
  • Open stm32mp1-demo.conf and update the line below
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python layers/meta-st/meta-st-stm32mp-addons
  • Replace STM32MP_MX_BASE by STM32MP_MY_DEMO_BASE
  • Add these lines after the series of includes:
# Define specific common machine name
MACHINEOVERRIDES .= ":stm32mpmydemo"

2.2.2 Configure the machine configuration file for your demo[edit]

In the customer machine file, move to User machine customization sections paragraph to configure your machine:

  • Boot Scheme
To select your boot scheme configuration(s), comment and uncomment the BOOTSCHEME_LABELS lines.
  • Boot Device Choice
To select your boot device configuration(s), comment and uncomment the BOOTDEVICE_LABELS lines.
  • Support Feature Choice
To select additional features to enable on board, uncomment the "MACHINE_FEATURES" proposed lines.
  • Specific firmwares and kernel modules configuration
This section allows user to configure some specificites related to its board hardware.
- KERNEL_MODULE_AUTOLOAD you may need to feed this variable with the list of kernel modules that need to be loaded at boot time, such as 'goodix' for current touch-screen used on STM32MP157C-EV1 evaluation board.
- BLUETOOTH_LIST in case you enable the bluetooth feature for your machine, you should set, at least, the firmware module to use for your hardware (e.g. 'linux-firmware-bluetooth-bcm4343' for STM32MP157C-DK2 discovery board).
- WIFI_LIST in case you enable the wifi feature for your machine, you should set, at least, the firmware module to use for your hardware (e.g.'linux-firmware-bcm43430' for STM32MP157C-DK2 discovery board).
  • CubeMX Project config
You have to uncomment and configure the following variables to set your CubeMX project:
- CUBEMX_DTB name of CubeMX generated device tree files, without file extension (e.g. stm32mp135f-<ProjectName>-mx)
- CUBEMX_PROJECT path of CubeMX generated device tree files relative to layer path folder (e.g. mx/STM32MP135F-DK/my-demo/DeviceTree/my-demo)
- CUBEMX_SOC_PACKAGE indicates (in upper case) which STM32MP package is used:
- A: no crypt
- C: crypt
- D: no crypt, performance
- F: crypt, performance
This setting allows to set on Optee-os build the CFG_STM32_CRYP config switch to manage the presence of crypt hardware or not.
- CUBEMX_BOARD_DDR_SIZE indicates the size of DDR available on BOARD in MB unit:
- 512: 521MB size
- 1024: 1GB size
This setting allows to set on Optee-os build the CFG_DRAM_SIZE config switch.
- CUBEMX_SOC_DVFS_OFF indicates if you like to disable the DVFS which are activated by default.
- 0: Nothing specific done extra configuration switch defined
- 1: Manage extra config switch for Optee-os build

In order to give a better view on how to configure these variables, some machine samples are provided to show how to set-up a disco and eval board CubeMX machine: refer to conf/machine/examples from meta-st-stm32mp-addons layer.



2.3 Associate EULA with the new demo machine[edit]

Copy the eula folder delivered inside the existing STM32MP BSP layer 'addons' into your demo layer

$ cp -Rf <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-st-stm32mp-addons/conf/eula/ <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/conf/.

Cleanup unexpected symbolic links from eula folder newly populated:

$ find <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/conf/eula -type l -exec rm -f {} \;

Then create the symbolic link with the machine used for your demo:

$ cd <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/conf/eula
$ ln -sf ST_EULA_SLA stm32mp1-demo

2.4 Move DeviceTree files and project coming from STM32CubeMX tool[edit]

The principle is that the user generates devicetree files for the targeted demo from the STM32CubeMX tool.

Warning white.png Warning
Most of the time, generated devicetree files - mainly user sections - must be reworked by the end user for compilation and functional purposes. Each demo is delivered with an application note that describe changes applied on STM32CubeMX devicetree files

.

These files are then moved into the “mx” folder created into your demo layer  : <path of OpenSTLinux distribution delivery>/layers/meta-st/meta-my-demo-layer/mx/

Sub-folders are created and populated with the generated devicetree files:

mx/${CUBEMX_PROJECT}/kernel
mx/${CUBEMX_PROJECT}/u-boot
mx/${CUBEMX_PROJECT}/tf-a
mx/${CUBEMX_PROJECT}/optee-os

With CUBEMX_PROJECT that is equal to the value defined inside the machine used for the demo.

2.5 Update the README file[edit]

Please update the README file with the information needed for building and executing the demo.

2.6 Clean up useless content[edit]

You can delete the content of the recipes-example folder created by the create-layer command.

After making all of the updates, your demo layer should be similar to:

$ tree meta-my-demo-layer
meta-my-demo-layer
├── conf
│   ├── eula
│   │   ├── ST_EULA_SLA
│   │   ├── stm32mp1-demo -> ST_EULA_SLA
│   │   └──  ...
│   ├── machine
│   │   └── stm32mp1-demo.conf
│   └── layer.conf
├── mx
│   └── ${CUBEMX_PROJECT}
│            ├── kernel
│            │   └── stm32mp1XXx-my-demo-mx.dts
│            ├── optee-os
│            │   └── stm32mp1XXx-my-demo-mx.dts
│            ├── tf-a
│            │   ├── stm32mp1X-mx.dtsi
│            │   ├── stm32mp1XXx-my-demo-mx.dts
│            │   └── stm32mp1XXx-my-demo-mx-fw-config.dts
│            └── u-boot
│                ├── stm32mp1XXx-my-demo-mx.dts
│                └── stm32mp1XXx-my-demo-mx-u-boot.dtsi
├── COPYING.MIT
└── README

3 Adding specific recipes and content necessary for your demo[edit]

Examples of further add-on components:

  • Recipes for installing distro-specific configuration files
  • Any image recipes specific to user distribution
  • A psplash append file for a branded splash screen
  • Any other append files to make custom changes

Some other added components (*bb) are more specific: images, system services, and so on (a non-exhaustive list is shown below):

  • Recipes-core for psplash screen, systemd services
  • Recipes-samples for example images

...