How to create your own machine

1. Introduction

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

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/

• 3 sub-folders are created and populated with generated device tree files :

- <ProjectName>/kernel

- <ProjectName>/u-boot

- <ProjectName>/tf-a

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

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

3. Create a customer machine

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

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

3.2. Edit the new machine file: stm32mp1-<ProjectName>.conf

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. stm32mp157c-<ProjectName>-mx)

- CUBEMX_PROJECT path of CubeMX generated device tree files relative to layer path folder (e.g. mx/STM32MP157C-EV1/my-demo/DeviceTree/my-demo)

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

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

4.1. STM32CubeMX class

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

 $> 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

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

Board support package

Device Tree Binary (or Blob)

Graphics Processing Units