How to create your own machine

Applicable for STM32MP13x lines, STM32MP15x lines


1 Introduction[edit]

For your own needs, you can add in the Yocto project a new machine reflecting your own board and your own features.
This article is reserved to Yocto experts or at least people who have already practiced with the Yocto environmment.

This section describes how to add and configure a machine that is similar to those that the OpenSTLinux Distribution Package already supports.
This customer machine is associated to STM32CubeMX tool which provides DeviceTree files per component (tf-a, u-boot and kernel).

We suppose here that all the material described below is done inside an existing STM32MP BSP layer 'addons'.
For reminder this addons layer is deployed here in our delivery : <path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/

2 Generate device tree[edit]

The principle is that the user generates device tree files from the STM32CubeMX tool.
With the STM32CubeMX tool, the user browses inside the OpenSTLinux Distribution Package file system until “mx” folder located into STM32MP BSP layer addons : <path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/mx/

  • 4 sub-folders are created and populated with generated device tree files :
- <ProjectName>/kernel
- <ProjectName>/optee-os
- <ProjectName>/tf-a
- <ProjectName>/u-boot

Where <ProjectName> is the “STM32CubeMX user project name”

Each directory of <ProjectName> contains device tree files associated to the component directory, here: kernel, optee-os, tf-a (Trusted Firmware-A) and u-boot.


3 Create a customer machine[edit]

Create a machine based on the one provided by ST and align some environment variables with the content of mx/<ProjectName> sub-folders

3.1 Create the new machine[edit]

  $> cd <path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/machine
  $> cp stm32mp1X-mx.conf stm32mp1-<ProjectName>.conf

3.2 Edit the new machine file: stm32mp1-<ProjectName>.conf[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.


3.3 Create symbolic link for EULA with new machine created[edit]

To support GPU and third party content, you need to accept the EULA. So a symbolic link must be created with the EULA existing file and the new machine :

  $> cd <path of STM32MP1_Distribution_Package>/layers/meta-st/meta-st-stm32mp-addons/conf/eula
  $> ln -s ST_EULA_SLA stm32mp1-<ProjectName>

4 Miscellaneous[edit]

4.1 STM32CubeMX class[edit]

A dedicated class is provided here :

<STM32MP BSP layer addons>/classes/cubemx-stm32mp.bbclass

The main goal of this class is to manage any change done by the customer in sub folders mx/<ProjectName>/...

So if a device tree file is updated for one or more of components, this change will be taken into account automatically during the next compilation done in the Distribution Package.

5 Compile your image with the yocto build process[edit]

 $> cd <path of yocto delivery>
 (directory which contains meta-st, openembedded-core, meta-openembedded)
$> MACHINE=stm32mp1-<ProjectName> DISTRO=openstlinux-weston source layers/meta-st/script/envsetup.sh Accept the term of EULA (if you agree with)
$> bitbake st-image-weston The generated images are available on build-openstlinuxweston-stm32mp1-<ProjectName>/tmp-glibc/deploy/images/stm32mp1-<ProjectName>
Warning white.png Warning
In case build fail for an error in the machine.conf, pay attention to do a -c cleanall prior to relaunch the build after correction