How to create your own machine

This message will disappear after all relevant tasks have been resolved.

Semantic MediaWiki

There are 1 incomplete or pending task to finish installation of Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.

1. Introduction[edit source]

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 source]

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[edit source]

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 source]

  $> 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[edit source]

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

Boot Scheme (default configuration is trusted)

To select your boot scheme configuration(s), comment and uncomment the BOOTSCHEME_LABELS lines.

Boot Device Choice (default configuration is sdcard)

For ecosystem release ≥ v1.2.0

To select your boot device configuration(s), comment and uncomment the BOOTDEVICE_LABELS lines.

For ecosystem release ≤ v1.1.0

To select your boot device configuration(s), comment and uncomment the FLASHLAYOUT_CONFIG_LABELS lines.

Board Type Choice (default configuration is stm32mp157c-ev1)

For ecosystem release ≥ v1.2.0

To select your original device tree configuration, comment and uncomment the 'CUBEMX_BOARD_REFERENCE lines.

For ecosystem release ≤ v1.1.0

To select your original device tree configuration, comment and uncomment the CUBEMX_DT_FILE_BASE lines.

CubeMX Project config (default configuration is empty)

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 inside mx folder (e.g. <ProjectName>)

You should get something like following example :

For ecosystem release ≥ v1.2.0

#@TYPE: Machine
#@NAME: stm32mp1-mx
#@DESCRIPTION: Configuration for STM32CubeMX generated project
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python

include conf/machine/include/st-machine-common-stm32mp.inc
include conf/machine/include/stm32mp1-mx-config.inc
include conf/machine/include/stm32mp1-mx-extlinux-config.inc
include conf/machine/include/stm32mp1-mx-common.inc

# =========================================================================
# CubeMX extra config
# =========================================================================
# Set specific path by components for DT file location
CUBEMX_DTB_PATH_TFA     = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/tf-a"
CUBEMX_DTB_PATH_UBOOT   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/u-boot"
CUBEMX_DTB_PATH_LINUX   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/kernel"
CUBEMX_DTB_PATH_OPTEEOS = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/optee-os"

# =========================================================================
# User customizing sections
# =========================================================================

# Boot Scheme
# =========================================================================
# DISCO / EVAL : basic, trusted or optee
# =========================================================================
#BOOTSCHEME_LABELS += "basic"
#BOOTSCHEME_LABELS += "trusted"
#BOOTSCHEME_LABELS += "optee"

# Boot Device Choice
# =========================================================================
# DISCO : sdcard
# EVAL  : sdcard, emmc, nand-4-256, nor-sdcard, nor-emmc or nor-nand-4-256
# =========================================================================
# Define the boot device supported
#BOOTDEVICE_LABELS += "sdcard"

# WARNING: configs below are only available with EVAL board
#BOOTDEVICE_LABELS += "emmc"
#BOOTDEVICE_LABELS += "nand-4-256"
#BOOTDEVICE_LABELS += "nor-emmc"
#BOOTDEVICE_LABELS += "nor-nand-4-256"
#BOOTDEVICE_LABELS += "nor-sdcard"

# Board Type Choice
# =========================================================================
# DISCO : stm32mp157a-dk1 or stm32mp157c-dk2
# EVAL  : stm32mp157c-ev1
# =========================================================================
# Define the board reference devicetree name
# WARNING: only one setting allowed
#CUBEMX_BOARD_REFERENCE = "stm32mp157a-dk1"
#CUBEMX_BOARD_REFERENCE = "stm32mp157c-dk2"
#CUBEMX_BOARD_REFERENCE = "stm32mp157c-ev1"

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree and project path name
#CUBEMX_DTB = "stm32mp157c-my-demo"
#CUBEMX_PROJECT = "STM32MP157C-EV1/my-demo/DeviceTree/my-demo"

For ecosystem release ≤ v1.1.0


#@TYPE: Machine
#@NAME: stm32mp1-mx
#@DESCRIPTION: Configuration for STM32CubeMX generated project
#@NEEDED_BSPLAYERS: layers/meta-openembedded/meta-oe layers/meta-openembedded/meta-python

include conf/machine/include/st-machine-common-stm32mp.inc
include conf/machine/include/stm32mp1-mx-config.inc
include conf/machine/include/stm32mp1-mx-extlinux-config.inc
include conf/machine/include/stm32mp1-mx-common.inc

# =========================================================================
# CubeMX extra config
# =========================================================================
# Set specific path by components for DT file location
CUBEMX_DTB_PATH_pn-tf-a-stm32mp     = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/tf-a"
CUBEMX_DTB_PATH_pn-u-boot-stm32mp   = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/u-boot"
CUBEMX_DTB_PATH_pn-linux-stm32mp    = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/kernel"
CUBEMX_DTB_PATH_pn-optee-os-stm32mp = "${STM32MP_MX_BASE}/mx/${CUBEMX_PROJECT}/optee-os"

# =========================================================================
# User customizing sections
# =========================================================================

# Boot Scheme
# =========================================================================
# DISCO / EVAL : basic, trusted or optee
# =========================================================================
#BOOTSCHEME_LABELS += "basic"
BOOTSCHEME_LABELS += "trusted"
#BOOTSCHEME_LABELS += "optee"

# Boot Device Choice
# =========================================================================
# DISCO : sdcard
# EVAL  : sdcard, emmc, nand-4-256, nor-sdcard, nor-emmc or nor-nand-4-256
# =========================================================================
# Define the config labels to use to generate flashlayout file
FLASHLAYOUT_CONFIG_LABELS += "sdcard"

# WARNING: configs below are only available with EVAL board
FLASHLAYOUT_CONFIG_LABELS += "emmc"
#FLASHLAYOUT_CONFIG_LABELS += "nand-4-256"
#FLASHLAYOUT_CONFIG_LABELS += "nor-sdcard"
#FLASHLAYOUT_CONFIG_LABELS += "nor-emmc"
#FLASHLAYOUT_CONFIG_LABELS += "nor-nand-4-256"

# Board Type Choice
# =========================================================================
# DISCO : stm32mp157a-dk1 or stm32mp157c-dk2
# EVAL  : stm32mp157c-ev1
# =========================================================================
# Define the board reference devicetree name
# WARNING: only one setting allowed
#CUBEMX_DT_FILE_BASE = "stm32mp157a-dk1"
#CUBEMX_DT_FILE_BASE = "stm32mp157c-dk2"
CUBEMX_DT_FILE_BASE = "stm32mp157c-ev1"

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree and project path name
CUBEMX_DTB = "stm32mp157c-<ProjectName>-mx"
CUBEMX_PROJECT = "<ProjectName>"

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

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 source]

4.1. STM32CubeMX class[edit source]

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 source]

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