PHYTEC Documentation

PHYTEC will provide a variety of hardware and software documentation for all of our products. This includes any or all of the following:

• Quickstart Guide: A short guide on how to set up and boot a phyCORE board along with brief information on building a BSP, the device tree, and accessing peripherals.
• Hardware Manual:  A detailed description of the System on Module and accompanying carrier board. 
• Yocto Manual:  A comprehensive guide for the Yocto version the phyCORE uses. This guide contains an overview of Yocto; introducing, installing, and customizing the PHYTEC BSP; how to work with programs like Poky and Bitbake; and much more.
• BSP Manual:  A manual specific to the BSP version of the phyCORE. Information such as how to build the BSP, booting, updating software, device tree, and accessing peripherals can be found here.
• Development Environment Guide:  This guide shows how to work with the Virtual Machine (VM) Host PHYTEC has developed and prepared to run various Development Environments. There are detailed step-by-step instructions for Eclipse and Qt Creator, which are included in the VM. There are instructions for running demo projects for these programs on a phyCORE product as well. Information on how to build a Linux host PC yourself is also a part of this guide.
• Pin Muxing Table:  phyCORE SOMs have an accompanying pin table (in Excel format). This table will show the complete default signal path, from the processor to the carrier board. The default device tree muxing option will also be included. This gives a developer all the information needed in one location to make muxing changes and design options when developing a specialized carrier board or adapting a PHYTEC phyCORE SOM to an application. 

On top of these standard manuals and guides, PHYTEC will also provide Product Change Notifications, Application Notes, and Technical Notes. These will be done on a case-by-case basis. Most of the documentation can be found on the applicable download page of our products.

Yocto OpenSTLinux Introduction

Our STM32MP1xx BSPs are based on OpenSTLinux Distribution: https://wiki.st.com/stm32mpu/wiki/OpenSTLinux_distribution

OpenSTLinux is a Linux distribution based on the OpenEmbedded build framework (https://wiki.st.com/stm32mpu/wiki/OpenEmbedded) and TheYoctoProject (https://www.yoctoproject.org/)

The OpenSTLinux version, as well as the associated Yocto version that we use for our STM32MP1xx BSPs is provided in our BSP release notes.

We currently use this Linux distribution for the following STM32MP1 SOMs+SBCs :

• phyCORE-STM32MP15x + phyBOARD-Sargas
• phyCORE-STM32MP13x + phyBOARD-Segin

Core Components

Some important tools or subprojects of the Yocto Project used by OpenSTLinux are:

• Bitbake: build engine, a task scheduler like make, interprets metadata
• OpenEmbedded-Core: a set of base layers, containing metadata of software, no sources

Vocabulary

Recipes

Recipes contain information about the software project (author, homepage, and license). A recipe is versioned, defines dependencies, contains the URL of the source code, and describes how to fetch, configure, and compile the sources. It describes how to package the software, e.g. into different .deb packages, which then contain the installation path. Recipes are written in Bitbake's programming language, which has a simple syntax. However, a recipe can contain Python as well as a bash code.

Classes

Classes combine functionality used inside recipes into reusable blocks.

Layers

A layer is a collection of recipes, classes, and configuration metadata. A layer can depend on other layers and can be included or excluded one by one. It encapsulates a specific functionality and fulfills a specific purpose. Each layer falls into a specific category:

• Base
• Machine (BSP)
• Software
• Distribution
• Miscellaneous

Yocto's versioning scheme is reflected in every layer as version branches. For each Yocto version, every layer has a named branch in its Git repository. You can add one or many layers of each category in your build.

A collection of OpenEmbedded layers can be found here. The search function is very helpful to see if a software package can be retrieved and integrated easily: http://layers.openembedded.org/layerindex/branch/kirkstone/layers/

Machine

Machines are configuration variables that describe the aspects of the target hardware.

Distribution (Distro)

Distribution describes the software configuration and comes with a set of software features.

Bitbake

Bitbake is the task scheduler. It is written in Python and interprets recipes that contain code in Bitbake's programming language, Python, and bash code. The official documentation can be found here: https://docs.yoctoproject.org/bitbake

PHYTEC OpenSTLinux Adaptation

In addition to the Yocto layers used by OpenSTLinux, we added the following PHYTEC Yocto layers:

• meta-st-openstlinux-phytec: This layer extends the functionality of the meta-st-openstlinux distribution layer to enable features provided by our boards. With this layer, we also provide custom distros and images based on the one from OpenSTlinux.
  
• meta-phytec: This layer contains all machines and common features for all our BSPs. It is PHYTEC's Yocto Board Support Package for all supported hardware. For STM32MP1, only the following meta-phytec content is used:
  • conf/machine: PHYTEC STM32MP1xx Yocto machines
  • wic: WIC configurations (config files for SD-card binary generation)
  • recipes-bsp/firmware: WIFI/Bluetooth firmware
  • dynamic-layer/stm-st-stm32mp: adapt the STMicroelectronics BSP layer (meta-st-stm32mp) for our boards. It contains patches for bootloaders (ARM Trusted Firmware + U-Boot), secure monitor (OP-TEE), and Linux kernel.

You can find those layers in our git server below:

https://git.phytec.de/meta-st-openstlinux-phytec/ -- PHYTEC adaptation layer of OpenSTLinux ST distro layer
https://git.phytec.de/meta-phytec/ -- official hardware support layer for PHYTEC Boards
https://git.phytec.de/meta-phytec/tree/dynamic-layers/stm-st-stm32mp -- PHYTEC dynamic layer inside meta-phytec dedicated to the STM32MP1 platforms

BSP Workspace Installation

• A modern Linux operating host system either natively or via a Virtual Machine.
• Ubuntu 20.04 LTS or 18.04 LTS (64-bit).
• VMWare Player and VirtualBox are possible solutions if you want to use a Virtual Machine.
• Virtual Machine (VM) configured for this BSP build environment can be found at phyCORE-STM32MP15x Product Page in the download section under the heading "VM"
• Root access to your Linux host PC. Some commands in this guide will not work if you do not have sudo access (e.g. package installation, formatting an SD card).
• At least 8GB of RAM (16GB or more is recommended).
• At least 100 GB of free space on the build partition of the host PC.
• An SD card reader, operational under Linux.
• An active internet connection.

For more details concerning Linux PC configuration, please refer to https://wiki.st.com/stm32mpu/wiki/PC_prerequisites

Building the BSP

This section will guide you through the general build process of the STM32MP1xx BSPs using our phyLinux script (based on the repo tool) and the OpenSTLinuxYocto environment.

Basic Set-Up

There are a few important steps that have to be done before the main build process.

• Setting up the host:  refer to OpenSTLinux documentation: https://wiki.st.com/stm32mpu/wiki/PC_prerequisites

Finding the Right Software Platform

The STM32MP1xx BSP is a unified BSP, which means in the future it will support a set of different PHYTEC carrier boards (CB) with different Systems on Module (SOMs). These hardware sets are called MACHINE.

If you need to figure out the corresponding machine name of your board, go to:

• for phyCORE-STM32MP15x: phyCORE-STM32MP15x Product Page(Downloads under the heading "Software / Yocto + Linux BSP-Releases") and click on the corresponding BSP release.
• for phyCORE-STM32MP13x: phyCORE-STM32MP13x Product Page (Downloads under the heading "Software / Yocto + Linux BSP-Releases") and click on the corresponding BSP release.

Choose a BSP OpenSTLinux Distribution

The phyCORE-STM32MP1xx BSP is based on OpenSTLinux which offers different distributions (DISTRO). When building the BSP, you have to choose one of them. The choice will depend on the features you want to get on your final application.

The available DISTROs are:

For more details on the OpenSTLinux distributions, please refer to https://wiki.st.com/stm32mpu/wiki/OpenSTLinux_distribution#Distros

For our examples in this document, we will use: <DISTRO>= openstlinux-weston

Choose a BSP Image to be Built and Deployed

Once you have chosen a DISTRO, you have to choose a BSP Image to build and deploy on target. The available images depend on the DISTRO that has been chosen before.

For more information regarding OpenSTLinux images and how to create your image, please refer to: https://wiki.st.com/stm32mpu/wiki/How_to_create_your_own_image

For our examples in this document, we will use: <BSP_IMAGE>=st-image-weston

Get and Initialize the BSP Environment

• Create a fresh project directory:

host:~$ mkdir ~/PHYTEC_STM32MP1_BSP

• Get and Initialize the BSP Yocto environment with our phyLinux script:

host:~$ cd ~/PHYTEC_STM32MP1_BSP
host:~/PHYTEC_STM32MP1_BSP$ wget https://download.phytec.de/Software/Linux/Yocto/Tools/phyLinux
host:~/PHYTEC_STM32MP1_BSP$ chmod +x phyLinux
host:~/PHYTEC_STM32MP1_BSP$ ./phyLinux init

• On the first initialization, the phyLinux script will ask you to install the Repo tool in your /usr/local/bin directory.
• During the execution of the init command, you first need to choose the  processor platform (SoC):

***************************************************
* Please choose one of the available SoC Platforms:
* 
*   1: am335x
*   2: am57x
*   3: am62ax
*   4: am62x
*   5: am64x
*   6: am68x
*   7: imx6
*   8: imx6ul
*   9: imx7
*   10: imx8
*   11: imx8m
*   12: imx8mm
*   13: imx8mp
*   14: imx8x
*   15: imx93
*   16: nightly
*   17: rk3288
*   18: stm32mp13x
*   19: stm32mp15x
*   20: topic
 *
$ 

• Enter the choice number corresponding to stm32mp13x (18) or  stm32mp15x (19).
• Then choose the PHYTEC's BSP release number:

***************************************************
* Please choose one of the available Releases:
*
*   1: PD-BSP-Yocto-OpenSTLinux-STM32MP1-ALPHA1
*   2: PD-BSP-Yocto-OpenSTLinux-STM32MP1-ALPHA2
*   3: PD-BSP-Yocto-OpenSTLinux-STM32MP1-PD20.1.0
*   4: PD-BSP-Yocto-OpenSTLinux-STM32MP1-PD21.1.0
*   5: PD-BSP-Yocto-OpenSTLinux-STM32MP1-PD21.1.1
*   6: PD-BSP-Yocto-OpenSTLinux-STM32MP1-PD21.2.0
*   7: PD-BSP-Yocto-OpenSTLinux-STM32MP1-PD21.2.1
*   7: BSP-Yocto-OpenSTLinux-STM32MP1-PD21.2.1
*   8: BSP-Yocto-OpenSTLinux-STM32MP1-PD22.1.0
*   9: BSP-Yocto-OpenSTLinux-STM32MP1-PD22.1.1
*   10: BSP-Yocto-OpenSTLinux-STM32MP1-PD23.1.0
*
$ 

• The repo initialization will start

• Once the repo initialization is finished, a popup will appear to ask you to choose the DISTRO:

Press 'space' to select and press 'enter' to validate.

• Once the DISTRO is chosen, another popup will appear and will ask you to choose the MACHINE among all available PHYTEC platforms:
  

You must select one of the supported "phycore-stm32mp1-x" machines (phyCORE-STM32MP15x) or "phyboard-segin-stm32mp13-x" machines (phyCORE-STM32MP13x).

• The STM32MP1xx BSP depends on packages and firmware that are covered by a software license agreement (SLA). You will be asked to read and accept this EULA:

• After accepting the EULA, the Shell Environment will be set up. The following message should appear:

[HOST DISTRIB check]
Linux Distrib: Ubuntu
Linux Release: 18.04

Required packages for Linux Distrib:
build-essential chrpath cpio debianutils diffstat gawk gcc-multilib git iputils-ping libegl1-mesa libgmp-dev libmpc-dev libsdl1.2-dev libssl-dev pylint3 python3 python3-git python3-jinja2 python3-pexpect python3-pip socat texinfo unzip wget xterm xz-utils

Check OK: all required packages are installed on host.

[DISTRO configuration]
Selected DISTRO: openstlinux-weston

[MACHINE configuration]
Selected MACHINE: phycore-stm32mp1-3

[source layers/openembedded-core/oe-init-build-env][from nothing]

[EULA configuration]

[Configure *.conf files]
[INFO] No 'site.conf.sample' file available at ~/PHYTEC_STM32MP1_BSP/layers/meta-st/scripts. Create default one...

Shell environment terminated. To activate the build environment in the current shell use:

    $ source openstlinux-init-phytec.sh


host:~/PHYTEC_STM32MP1_BSP$

OpenSTLinux Environment Setup

•  The build environment setup must be executed once per new terminal session, with the following command:

host:~/PHYTEC_STM32MP1_BSP$ source openstlinux-init-phytec.sh

A popup will appear to ask you to select one of the available Build directories:

You can choose to use one of the existing build environments (previously created) or you can choose to create a new build environment by selecting "NEW" (in case you want to use a new MACHINE and/or DISTRO)

• After having selected the build environment, the OpenSTLinux Environment will be set up and you should now be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>':

[HOST DISTRIB check]
Linux Distrib: Ubuntu
Linux Release: 18.04

Required packages for Linux Distrib:
build-essential chrpath cpio debianutils diffstat gawk gcc-multilib git iputils-ping libegl1-mesa libgmp-dev libmpc-dev libsdl1.2-dev libssl-dev pylint3 python3 python3-git python3-jinja2 python3-pexpect python3-pip socat texinfo unzip wget xterm xz-utils

Check OK: all required packages are installed on host.

[BUILD_DIR configuration]
Selected BUILD_DIR: build-openstlinuxweston-phycore-stm32mp1-3

[source layers/openembedded-core/oe-init-build-env][with previous config]

===========================================================================
Configuration files have been created for the following configuration:

    DISTRO            :  openstlinux-weston
    DISTRO_CODENAME   :  dunfell
    MACHINE           :  phycore-stm32mp1-3
    BB_NUMBER_THREADS :  <no-custom-config-set>
    PARALLEL_MAKE     :  <no-custom-config-set>

    BUILDDIR          :  build-openstlinuxweston-phycore-stm32mp1-3
    DOWNLOAD_DIR      :  <disable>
    SSTATE_DIR        :  <disable>

    SOURCE_MIRROR_URL :  <no-custom-config-set>
    SSTATE_MIRRORS    :  <disable>

    WITH_EULA_ACCEPTED:  YES

===========================================================================

Available images for OpenSTLinux layers are:

  - Official OpenSTLinux images:
      st-image-weston       -   OpenSTLinux weston image with basic Wayland support (if enable in distro)

  - Other OpenSTLinux images:
      - Supported images:
          st-image-core         -   OpenSTLinux core image


You can now run 'bitbake <image>'

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ 

Build Process

Now that the build environment is ready, you can start the first build process, using the following command:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ bitbake <BSP_IMAGE>

Example to build the "st-image-weston":

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ bitbake st-image-weston

Programming the Target

In this section, we explain how to use the STM32MPCubeProgrammer tool to flash the NOR, eMMC, NAND, or SD Card.

Install STM32CubeProgrammer Tool

Refer to https://wiki.st.com/stm32mpu/wiki/STM32CubeProgrammer for information on installing the STM32CubeProgrammer.

Using STM32CubeProgrammer

Prerequisite: To download the BSP via the DFU link, change the BOOT mode to UART/USB boot mode. Refer to the corresponding STM32MP1xx BSP manual for that.

• Go to the directory that contains the binaries and the flash layout files: 

host:~$ cd ~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/images/<MACHINE>

• Get the device port location for the USB link:

$ STM32_Programmer_CLI -l usb
      -------------------------------------------------------------------
                        STM32CubeProgrammer <tool version>                  
      -------------------------------------------------------------------

=====  DFU Interface   =====

Total number of available STM32 device in DFU mode: 1

  Device Index           : USB1
  USB Bus Number         : 001
  USB Address Number     : 001
  Product ID             : DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
  Serial number          : 003C00283338510C34383330
  Firmware version       : 0x0110
  Device ID              : 0x0500

• Use the flashing command:

$ STM32_Programmer_CLI -c port=<DEVICE_PORT_LOCATION> -w [<file.tsv>]
where 
 w:
     Write
 <file.tsv>:PathToFlashlayout/flashlayout.tsv file
         if Flashlayout and binaries are not in the same directory, then the path to the Flashlayout files must be precised.
 <DEVICE_PORT_LOCATION>:
         e.g. usb1 (case sensitive)

Flashing the SD Card (Boot from SD Card)

To flash the SD Card with STM32CubeProgrammer:

• Insert an SD Card in the SD Card connector.
• Use the flashing command with the following Flashlayout file:  /flashlayout_<IMAGE>/<BOOT_CHAIN>/FlashLayout_sdcard_<MACHINE>-<BOOT_CHAIN>.tsv
  

$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/trusted/FlashLayout_sdcard_phycore-stm32mp1-3-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message:

Flashing service completed successfully

Flashing the Target

Flashing the NOR and eMMC (Boot from NOR - only for phyCORE-STM32MP15x)

• Use the flashing command with the following Flashlayout file: /flashlayout_<BSP_IMAGE>/<BOOT_CHAIN>/FlashLayout_nor-emmc_<MACHINE>-<BOOT_CHAIN>.tsv

$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/FlashLayout_nor-emmc_phycore-stm32mp1-3-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message:

Flashing service completed successfully

Flashing eMMC (Boot from eMMC)

• Use the flashing command with the following Flashlayout file: /flashlayout_<BSP_IMAGE>/<BOOT_CHAIN>/FlashLayout_emmc_<MACHINE>-<BOOT_CHAIN>.tsv

$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/FlashLayout_emmc_phycore-stm32mp1-3-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message:

Flashing service completed successfully

Flashing NAND (Boot from NAND - only for phyCORE-STM32MP15x)

• Use the flashing command with the following Flashlayout file: /flashlayout_<BSP_IMAGE>/<BOOT_CHAIN>/FlashLayout_nand_<MACHINE>-<BOOT_CHAIN>tsv

$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/FlashLayout_nand-2-256_phycore-stm32mp1-3-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message:

Flashing service completed successfully

Create an SD Card Image (with PC Host SD Card Reader)

When booting from an SD card, another possibility (apart from using STM32CubeProgrammer) is to create an SD Card image that contains all BSP binary files in correctly preformatted partitions. This can be done from a .wic file or .raw file, as described below.

Using WIC file

For that, a WIC image (.wic file) is generated by default along with other binaries (under build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/images/<MACHINE>):

Example of WIC  file:st-image-weston-openstlinux-weston-phycore-stm32mp1-3.wic 

Using RAW file

Instead of using the WIC format, there is also the possibility to generate a RAW file (.raw) using the script create_sdcard_from_flashlayout.sh with the <FlashLayout file> = FlashLayout_sdcard_<MACHINE>-<BOOT_CHAIN>.tsv:

host:~$ cd build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/images/<MACHINE>/scripts
host:~$ ./create_sdcard_from_flashlayout.sh ../flashlayout_<built-image>/<BOOT_CHAIN>/<FlashLayout file>

Example:

host:~$ cd build-openstlinuxweston-phycore-stm32mp1-3/tmp-glibc/deploy/images/phycore-stm32mp1-3/scripts
host:~$ ./create_sdcard_from_flashlayout.sh ../flashlayout_st-image-weston/trusted/FlashLayout_sdcard_phycore-stm32mp1-3-trusted.tsv 

The script will generate the following SD Card image (raw file): in the binaries directory: .../flashlayout_<BSP_IMAGE>_FlashLayout_sdcard_<MACHINE>-<BOOT_CHAIN>.raw

Example : flashlayout_st-image-weston_FlashLayout_sdcard_phycore-stm32mp1-3-trusted.raw (in build-openstlinuxweston-phycore-stm32mp1-3/tmp-glibc/deploy/images/phycore-stm32mp1-3)

Populate SD Card

.wic or .raw images can be used to populate the SD Card with the Linux dd command :

• Insert the uSD Card in the PC Host
• Umount all the partitions associated with the uSD Card
• Populate the microSD card with the dd command:

host:~$ cd build-openstlinuxweston-phycore-stm32mp1-3/tmp-glibc/deploy/images/phycore-stm32mp1-3
host:~$ sudo dd if=st-image-weston-openstlinux-weston-phycore-stm32mp1-3.wic of=/dev/mmcblk0 bs=8MB conv=fdatasync

More details on the create_sdcard_from_flashlayout.sh script and the dd command can be found here: https://wiki.st.com/stm32mpu/wiki/How_to_populate_the_SD_card_with_dd_command

BSP Customization

Creating Custom Yocto Layer

Creating your layer should be one of the first tasks when customizing the BSP. In the following chapter, we have an embedded project called "racer" which we will implement using the OpenSTLinux distribution.

Create the Layer

First, we need to create a new layer. Yocto provides a script for that. If you set up the BSP and the shell is ready, type:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake-layers create-layer meta-racer

The default options are fine for now. Move the layer to the source directory:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ mv meta-racer ../layers/

Create a Git repository in this layer to track your changes:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ cd ../layers/meta-racer
host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ git init && git add . && git commit -s -m "create meta-racer"

Add the Layer to the BSP Build Dependency

Now you can add the layer directly to your build-<DISTRO>-<MACHINE>/conf/bblayers.conf:

BBLAYERS += "${OEROOT}/layers/meta-racer"

or with a script provided by Yocto:

host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ cd ../../build-<DISTRO>-<MACHINE>
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake-layers add-layer ../layers/meta-racer

Configure the Kernel through Menuconfig

The process of building a kernel has two parts: configuring the kernel options and building the source with those options. For your BSP customization, you may have to change the kernel options. This section describes how to do it.

• Start the Linux kernel configuration menu:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c menuconfig

• Navigate forward or backward directly between feature
  • un/select, modify feature(s) you want
  • When the configuration is OK: exit and save the new configuration

• After saving and exiting the menuconfig, the kernel modifications made are only temporary. Only the kernel configuration file (.config) in the kernel build directory is updated. It is located under:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/work/<MACHINE>-ostl-linux-gnueabi/linux-stm32mp/<x.y>-r0/build/

• Your modifications will be taken into account if the kernel is rebuilt from this point (without cleaning), but it will not be permanent (not in the Linux Kernel source directory). To save it, create a new configuration fragment that will contain only your configuration changes:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c diffconfig

• The fragment is generated under:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/work/phycore_stm32mp1_x-ostl-linux-gnueabi/linux-stm32mp/<x.y>-r0/fragment.cfg

• You can temporarily save and rename this fragment to your home folder (for example):

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ cp tmp-glibc/work/phycore_stm32mp1_x-ostl-linux-gnueabi/linux-stm32mp/<x.y>-r0/fragment.cfg ~/<custom-fragment>.cfg

• This configuration fragment file has to be added to the linux-stm32mp_%.bbappend yocto recipe (see Adding Kernel configuration fragment)
• Without using the new config fragment file, you can temporarily test your kernel configurations changes (build without clean) using the temporary method: Updating the kernel/device tree on running target (temporary method)
• If you need to remove/modify your kernel configuration changes previously made, you have to restart from a clean Linux Kernel build:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c cleansstate

With this clean, when using bitbake diffconfig command again, it will generate a new fragment comparing the new changes made from the default Linux Kernel configuration. 

Patch Kernel, Bootloader, or Trusted Firmware

Modify the Sources with devtool

Instead of using the standard PHYTEC versions of kernel, bootloader, or trusted firmware which are provided in the Yocto recipes, you can modify the source code to build your customized BSP.

Modifying the kernel device tree is necessary when customizing your application/baseboard (ex: pin muxing modification). 

Devtool is a set of helper scripts to enhance the user workflow of Yocto. It is available as soon as you set up your shell environment. Devtool can be used to:

• modify existing sources
• integrate software projects into your build setup
• build software and deploy software modifications to your target

Devtool command to modify an existing recipe:

devtool modify -x <recipename> [<directory>]

• <recipename>: corresponding recipe names for kernel, bootloader, or trusted firmware are: 

• <directory>: optional parameter to specify the path to the source files. If not specified, the following subdirectory will be created and used: ~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/workspace/sources

Example for modifying the kernel:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ devtool modify -x linux-stm32mp sources/linux-stm32mp

Devtool will create a new Yocto layer in /build-openstlinuxweston-<MACHINE>/workspace where you can see all modifications done by devtool. It will extract the sources corresponding to the recipe to the specified directory. In this example kernel sources will be extracted on the following local git directory: /build-openstlinuxweston-<MACHINE>/sources/linux-stm32mp

A bbappend file will be created in the workspace directing the SRC_URI to this directory. Building an image with Bitbake will now use the sources in this directory. Now you can do your kernel, u-boot, or trusted firmware modifications.

Example of modifying a kernel device tree file:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ vim sources/linux-stm32mp/arch/arm/boot/dts/phycore-stm32mp1-3.dtsi

Make a change in the dts file with your favorite code editor. When it is done, refer to the next sections for re-building the BSP:

• Re-build the kernel/BSP image, referring to the section Rebuilding the Kernel, Bootloader, or Trusted Firmware.
• For a quick test on a running target (temporary method), you can rebuild the kernel/device tree and only deploy the new device tree blob on target referring to Updating the kernel/device Tree on a Running Target (Temporary Method)

If you want to store your code changes permanently, it is advisable to create a patch from the changes, and then store and back up only the patch. You can go into the linux-stm32mp directory and create a patch with the method described in the section Creating Patches.

Updating the kernel/device Tree on a Running Target (Temporary Method)

After modifying the device tree kernel and/or kernel configuration, you can test your modifications on your running target with the following quick but temporary method (to use for prototyping only).

• Rebuild kernel/device tree:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp

This command will generate a new Kernel Image (uImage) and new device tree blob (<MACHINE>.dtb) under the binaries folder (tmp-glibc/deploy/images/<MACHINE>)

• Create an SSH connection between your PC and the running board with Ethernet or USB OTG (see Create an SSH Connection with USB OTG or Ethernet)
• For device tree update: copy the new device tree blob to the /boot directory of the target:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ scp tmp-glibc/deploy/images/<MACHINE>/<MACHINE>.dtb root@<Target_IP>:/boot

Example:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp$ scp tmp-glibc/deploy/images/phycore-stm32mp-3/phycore-stm32mp-3.dtb root@192.168.7.1:/boot

• For kernel update: copy the new kernel image (uImage) to the /boot directory of the target:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ scp tmp-glibc/deploy/images/<MACHINE>/uImage root@<Target_IP>:/boot

Example:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp$ scp tmp-glibc/deploy/images/phycore-stm32mp-3/uImage root@192.168.7.1:/boot

• Reboot the board with the following commands on target:

root@phycore-stm32mp1-3:~# cd /boot; sync; systemctl reboot

Rebuilding the Kernel, U-boot, OP-TEE or Trusted Firmware

Launch the following command to restart the BSP image build process (only the modules that have been modified will be re-generated; the kernel for example).

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake <BSP_IMAGE>

For quick build tests, you may also want to build only the module you have modified (kernel, bootloader, or trusted firmware), as described in the following sections.

Rebuild the Kernel (kernel image + device tree blob)

To rebuild the kernel only, launch the following command:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp

Rebuild u-boot

To rebuild the bootloader only, launch the following command:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake u-boot-stm3mp

Rebuild OP-TEE

To rebuild the bootloader only, launch the following command:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake optee-os-stm32mp

Rebuild the Trusted Firmware 

To rebuild the trusted firmware only, launch the following command:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake tf-a-stm32mp

Rebuild Kernel Device Tree Overlay

To rebuild the kernel device tree overlay, launch the following command:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake phytec-dt-overlays-stm32mp -c cleanall
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake phytec-dt-overlays-stm32mp

Creating Patches

You have to create the patch from the local git directory containing the modified source code (directory created by devtool).

Example to Create a Kernel Patch

• Enter to the <local git directory>:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ cd sources/linux-stm32mp 

host:<local git directory>$ cd sources/linux-stm32mp
host:<local git directory>$ git status                        # Show changes files
host:<local git directory>$ git diff                          # Show all the changes made compared to the previous commit
host:<local git directory>$ git add .                         # Add all modified file to the staging area
host:<local git directory>$ git commit -m "DTS modification"  # Creates a commit with a not so useful commit message
host:<local git directory>$ git format-patch -1 -o ~/         # Creates a patch of the last commit and saves it in you home directory
/home/<user>/0001-DTS-modification.patch

The created patch is the home directory: host:~/0001-DTS-modification.patch.

Applying Patches

The created patches can be used once you have validated your device tree modifications (using devtool for example) and you want to customize the BSP by adding a custom Yocto layer (how to create a Yocto layer is described in Creating Custom Yocto Layer). 

devtool reset linux-stm32mp

bitbake linux-stm32mp -c cleansstate

After you have created the kernel patch, you must create a .bbappend file in your custom layer. The locations for the append recipes are:

The following example is for the linux-stm32mp recipe. You have to adjust the paths:

• Create the folders and move the patch into it. Then create the bbappend file:

host:~/PHYTEC_STM32MP1_BSP/$ mkdir -p layers/meta-custom/recipes-kernel/linux/features                          # create the directories
host:~/PHYTEC_STM32MP1_BSP/$ cp ~/0001-DTS-modification.patch layers/meta-custom/recipes-kernel/linux/features  # copy patch in the features directory
host:~/PHYTEC_STM32MP1_BSP/$ touch layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend             # create a bbappend file

• Use your favorite editor to add the following lines into the bbappend file (layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend):

FILESEXTRAPATHS_prepend := "${THISDIR}/features:"
SRC_URI_append = " \
file://0001-DTS-modification.patch \
"

• Save the file, go back to the build directory, and rebuild the kernel recipe with:

host:~/PHYTEC_STM32MP1_BSP/$ cd build-<DISTRO>-<MACHINE>
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c cleansstate
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp

• If the build is successful, you can then rebuild the entire image (st-image-weston for example).

Adding Kernel Configuration Fragment

After creating one or more kernel configuration files (.cfg) with menuconfig and diffconfig bitbake commands (Configure the kernel through Menuconfig), you have to add them in the linux-stm32mp_%.bbappend recipe of your customer Yocto layer, so that it will be included in the final generated Kernel configuration file (.config file in the Kernel build directory).

• If not already done, you must create a linux-stm32mp_%.bbappend file in your custom layer:

Replace <x.y> below with the kernel version x.y (ex: 5.4).

host:~/PHYTEC_STM32MP1_BSP/$ mkdir -p layers/meta-custom/recipes-kernel/linux/features/<x.y>                     # create the directories
host:~/PHYTEC_STM32MP1_BSP/$ touch layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend             # create a bbappend file

• Copy your config fragment file (<custom-fragment>.cfg) into the features/<x.y> directory (ex: features/4.19):

host:~/PHYTEC_STM32MP1_BSP/$ cp ~/<custom-fragment>.cfg layers/meta-custom/recipes-kernel/linux/features/<x.y>  # copy fragment in the features directory

• Use your favorite editor to add the following lines into the bbappend file (layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend):

FILESEXTRAPATHS_prepend := "${THISDIR}/features:"

SRC_URI += "file://${LINUX_VERSION}/custom-fragment.cfg;subdir=fragments"
KERNEL_CONFIG_FRAGMENTS += "${WORKDIR}/fragments/${LINUX_VERSION}/custom-fragment.cfg"

• Save the file, go back to the build directory, and rebuild the kernel recipe with:

host:~/PHYTEC_STM32MP1_BSP/$ cd build-<DISTRO>-<MACHINE>
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp -c cleansstate
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp

• If the build is successful, you can then rebuild the st-image-bootfs partition (containing the kernel and device tree) or the entire image (st-image-weston for example).

OpenSTLinux Yocto SDK

When a Yocto distribution has been modified and validated on target, it is pertinent to build a new Software Development Kit that integrates the modifications and redistributes this SDK to developers. This chapter describes the procedure to build, install and use the SDK.

For  more details on the OpenSTLinux SDK, please refer to https://wiki.st.com/stm32mpu/wiki/SDK_for_OpenSTLinux_distribution

How to Build the SDK

To build the SDK, first, if not already done, initialize the OpenSTLinux Environment for the phyCORE-STM32MP1xx BSP (refer to OpenSTLinux Environment Setup). Then launch the following bitbake command:

bitbake -c populate_sdk <image>

With  <image> =  Image name (example: st-image-weston)

Example:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ bitbake -c populate_sdk st-image-weston

The SDK installation files  are deployed into the following output directory: build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/sdk/ :

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3$ cd tmp-glibc/deploy/sdk
host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3/tmp-glibc/deploy/sdk$ ls -l
total 955772
-rw-r--r-- 1 phyvm phyvm 11572 Feb 3 11:38 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.host.manifest
-rw-r--r-- 1 phyvm phyvm 21707 Feb 3 11:38 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.license
-rw-r--r-- 1 phyvm phyvm 575516 Feb 3 11:58 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot-license_content.html
-rwxr-xr-x 1 phyvm phyvm 977377750 Feb 3 11:57 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.sh
-rw-r--r-- 1 phyvm phyvm 157514 Feb 3 11:37 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.target.manifest
-rw-r--r-- 1 phyvm phyvm 549110 Feb 3 11:37 st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.testdata.json

The main final output is the cross-development toolchain installation shell script: <image>-<distro>-<machine>-<host machine>-toolchain-<Yocto release>-snapshot.sh

with:

• <host machine>: Host machine on which the SDK is generated: x86_64 (the only supported value)
• <Yocto release>: Release number of the Yocto Project; here it is Yocto 3.1 (Dunfell)

For more details, refer to: https://wiki.st.com/stm32mpu/wiki/How_to_create_an_SDK_for_OpenSTLinux_distribution

How to Install the SDK

Execute the cross-development toolchain installation shell script, as follows:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/sdk$ ./st-image-weston-openstlinux-weston-phycore-stm32mp1-3-x86_64-toolchain-3.1-snapshot.sh -d ../../../SDK

This will install the SDK into ~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/SDK, but it can be installed in any other location.

When the installation is successfully finished, the following log should appear:

ST OpenSTLinux - Weston - (A Yocto Project Based Distro) SDK installer version 3.1-snapshot
===========================================================================================
You are about to install the SDK to "<user_path>/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3/SDK". Proceed [Y/n]? y
Extracting SDK..................................................................................................................................................................................................................done
Setting it up...done
SDK has been successfully set up and is ready to be used.
Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
 $ . <user_path>/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-3/SDK/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi

How to Use the SDK in a Linux Terminal

If you want to cross-compile your application project into a Linux terminal, you have to start the SDK, using the following command:

host:$ source <SDK installation directory>/environment-setup-cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi

Note that the SDK environment setup script must be run once in each new working terminal in which you cross-compile.

The following checking list allows you to ensure that the environment is correctly set up:

• Check the target architecture:

host:$ echo $ARCH
arm

• Check the toolchain binary prefix for the target tools:

host:$ echo $CROSS_COMPILE
arm-ostl-linux-gnueabi-

• Check the C compiler version:

host:$ $CC --version
arm-ostl-linux-gnueabi-gcc (GCC) <GCC version>
[...]

• Check that the SDK version is the expected one:

host:$ echo $OECORE_SDK_VERSION
<expected SDK version>

If any of these commands fails or does not return the expected result, please try to reinstall the SDK.

How to Use the SDK with STM32CubeIDE

STM32CubeIDE can be used for Cortex-A7 or Cortex-M4 application development purposes.

For more details on the STM32CubeIDE tool, please refer to STM32CubeIDE Development Tool

To see how to use the SDK to debug Linux userspace applications, please refer to How to Debug a Linux Userspace Application (Cortex-A7)

The STM32CubeMX Tool

STM32CubeMX is an official STMicroelectronics graphical software configuration tool that allows, among other features:

• configure pin assignments, the clock tree, or internal peripherals
• generate the device tree for a Linux kernel, TF-A, and U-Boot firmware for Cortex-A7
• generate HAL initialization code for Cortex-M4

For more details on these and other features, go to https://wiki.st.com/stm32mpu/wiki/STM32CubeMX

To install the tool and get the user manual: https://www.st.com/en/development-tools/stm32cubemx.html

Using STM32CubeMX to Generate Device Tree

STM32CubeMX can be used to generate the device tree files for a given project:

• It generates one unique <soc>-<project>-mx.dts file (containing all the custom board DTS configurations) per software component (Kenel, U-boot, and TF-A). This .dts includes the upstream-specific SoC dtsi files (Soc, SoC extension, and SoC package Pincontrol).
• For U-boot, it also generates u-boot board specificdtsi file: <soc>-<project>-mx-u-boot.dtsi
• For TF-A, it also generates <soc>-<project>-mx-fw-config.dts used by TF-A Firmware Configuration Framework.
• For U-boot and TF-A, it also generates DDR configurationdtsi file: stm32mp15-mx.dtsi (included in <soc>-<project>-mx.dts for TF-A and in <soc>-<project>-mx-u-boot.dtsi for U-boot)

For more details of the generated dtsi files for each component, refer to https://wiki.st.com/stm32mpu/wiki/STM32_MPU_device_tree(STM32CubeMX generated device tree section).

 Procedure to create your own CubeMX project based on our phyCORE-STM32MP15x SOM (with or without phyBOARD-Sargas):

• Copy one of the projects (.ioc) that we provide (the one which fit best your needs) and rename the file to match your project: <project>.ioc. For example: myboard.ioc.
• Open this project with STM32CubeMX. Then save it. (the CubeMX project name is based on the .ioc file name and is updated as soon as you open and save the project).

Add phyCORE-STM32MP15x and phyBOARD Device Tree User Code Templates

As the generated device tree files do not contain all the necessary device tree properties (dependent on BSP drivers), some manual code ("User code") needs to be added in specific sections of the generated files.

To be able to build the BSP with the device tree generated from the phyCORE-STM32MP15x/phyBOARD-Sargas STM32CubeMX project, we also provide .dts templates. Those are the generated device tree from our STM32CubeMX projects in which we have added the necessary user code, (adding some device tree properties) to build the BSP image.

The templates that we provide are inside the downloaded STM32CubeMX-phytecpackage, under DeviceTree_templates directory. This directory contains .dts and .dtsi files that are the device tree templates.

The dts templates contain some user code sections like these:

In the device tree root:

/* USER CODE BEGIN root */
/* USER CODE END root */

In each device tree specific <node>:

/* USER CODE BEGIN <node> */
/* USER CODE END <node> */

Those different sections can be parsed by the STM32Cube generator and then be automatically added to the generated DTS files.

Build Yocto Machine from Generated Device Tree

Once a device tree is generated from STM32CubeMX, a corresponding Yocto machine can be quickly built, using our machine configuration file template "meta-phytec/conf/machine/phycore-stm32mp1-mx.conf".

This configuration file works with the "meta-st-stm32mp-addons" Yocto layer provided by ST for this purpose.

This layer allows you to build Yocto custom machines from STM32CubeMX projects containing generated device tree files. The following link describes this layer: https://wiki.st.com/stm32mpu/wiki/How_to_create_your_own_machine

For the phyCORE-STM32MP, the way to use this layer is a little bit from the one described in this ST wiki page for those two reasons:

• "meta-phytec/conf/machine/phycore-stm32mp1-mx.conf" must be used instead of"meta-st/meta-st-stm32mp-addons/conf/machine/stm32mp1-mx.conf"
• Yocto Build setup is a little bit different.

So, please follow the sections below instead. There are two different methods:

• Configure and build the phycore-stm32mp1-mx machine. This is useful for quick validation tests.
• Create a new machine (based on phycore-stm32mp1-mx.conf file).

Build Images for the phycore-stm32mp1-mx Machine Template

• First, choose an OpenSTLinux Distribution (<DISTRO>) fitting your needs. Please refer to Choose a BSP OpenSTLinux Distribution.
• If you already have fetched the BSP Yocto sources, initialized with any machine and distro, you can start configuring the phycore-stm32mp1-mx.conf fileas described below.
• Otherwise, please refer to Get and Initialize the BSP Environment, choosing the DISTRO fitting your project needs and selecting the MACHINE phycore-stm32mp1-mx.Youwill be asked to read and accept (or not) the EULA license (mandatory to support GPU and third-party content). After that, the build directory build-<DISTRO>-phycore-stm32mp1-mx will be created.

Customize the Yocto Machine

• Configure the machine feature to your need, editing "meta-phytec/conf/machine/phycore-stm32mp1-mx.conf" file.
• On this file, the changes that can be done are under "User machine customization":

• • M4 copro:
    
    • M4_BOARDS: Define specific board reference to use for M4 firmware (boards cherry-pick from m4projects-stm32mp1.bbapend recipe). Only one is available by default, ie:  "STM32MP15-phyBOARD-Sargas".
    • DEFAULT_COPRO_FIRMWARE: Define the name of default copro firmware that can be executed at boot time (name cherry-picked from a list defined in m4projects-stm32mp1.bbappendrecipe)

• • Boot Scheme: to select your boot scheme configuration(s), comment and uncomment the BOOTSCHEME_LABELS lines.

• • Boot Device Choice: select your boot device configuration(s), comment, and uncomment the BOOTDEVICE_LABELS lines.

• • Image config for NAND device: for 512MB and 128MB NAND boot devices, partition sizes must be redefined. For that, uncomment all the STM32MP_<PARTITION>_SIZE parametersas well as the MULTIUBI_BUILD_NAME parameter (either for the 512MB config or the 128MB config).

• • Support Feature Choice: select additional features to enable onboard, and uncomment the MACHINE_FEATURES proposed lines.

• • Specific firmware and kernel modules configuration: this section allows the user to configure some specificities 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 (this variable is empty for the standard phycore-stm32mp1-x machines).
    • BLUETOOTH_LIST: in case you enable the "Bluetooth" feature and need to use another firmware module for your hardware (the default one used is defined in include/phytec-machine-common-stm32mp.inc).
    • WIFI_LIST: in case you enable the "wifi" feature and need to use another firmware module for your hardware (the default one used is defined in include/phytec-machine-common-stm32mp.inc).

• • CubeMX Project config: You have to uncomment and configure the following variables to set your CubeMX project:
    • CUBEMX_DTB: must be set to the device tree name (without file extension)
    • CUBEMX_PROJECT: must be set to the Device tree path of CubeMX Board project (path relative to "meta-st/meta-st-stm32mp-addons" folder). For example, if the CubeMX project is located in "meta-phytec":

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree name (without file extension)
CUBEMX_DTB = "stm32mp157c-myboard-mx"
# Assign CubeMX Board project path (relative to "meta-st-stm32mp-addons" layer path folder)
CUBEMX_PROJECT = "../../meta-phytec/phycore-stm32mp1-myboard/CA7/DeviceTree/myboard"

Set Up the Build Environment

OpenSTLinux build environment can be set up with or without a Graphical User Interface (GUI).

1) Setup the build env without GUI:

• Launch the following command replacing <DISTRO> by your choice: MACHINE=phycore-stm32mp1-mx DISTRO=<DISTRO> source openstlinux-init-phytec.sh

Example:

host:~/PHYTEC_STM32MP1_BSP$ MACHINE=phycore-stm32mp1-mx DISTRO=openstlinux-eglfs source openstlinux-init-phytec.sh

• If the corresponding build directory build-<DISTRO>-phycore-stm32mp1-mx doesn't exist yet:

  • you will be asked to read and accept (or not) the EULA license (mandatory to support GPU and third-party content).
    
  • the following BUILD_DIR will be created: '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-phycore-stm32mp1-mx'.
• Build environment will be set up and you should now be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-phycore-stm32mp1-mx'.

2) Setup the build env with GUI:

• Removing the "MACHINE" and "DISTRO" parameters in the above command will open the GUI interface:

host:~/PHYTEC_STM32MP1_BSP$ source openstlinux-init-phytec.sh

• A popup will appear. Select " build-<DISTRO>-phycore-stm32mp1-mx" as BUILD_DIR. Otherwise, select "NEW" to create it, if it doesn't exist yet (Press 'space' to select and press 'enter' to validate).

• When selecting "NEW":

  • you will have to select the DISTRO and the MACHINE ("phycore-stm32mp1-mx" in our case).

  • you will be asked to read and accept (or not) the EULA license (mandatory to support GPU and third-party content).
    

  • the following BUILD_DIR will be created: '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-phycore-stm32mp1-mx'.

• Build environment will be set up and you should now be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-phycore-stm32mp1-mx'.

Build the Image

To build your BSP images, please follow the corresponding section: Build Process

Build Images for a New Custom Machine

If not already done, please refer to Get and Initialize the BSP Environment choosing the DISTRO fitting your project needs and any "phycore-stm32mp1-x" machine (the selected one does not matter at this step, because we will create a new machine). Youwill be asked to read and accept (or not) the EULA license (mandatory to support GPU and third-party content). After that, the build directory build-<DISTRO>-phycore-stm32mp1-x will be created.

A new machine can be created in different locations:

• into meta-phytec
• into your own meta layer (recommended method to manage the Yocto sources of your own projects without touching other layers)

Create a new machine into meta-phytec

• Copy the "meta-phytec/conf/machine/phycore-stm32mp-mx.conf" file and rename it (ex: "phycore-stm32mp1-myboard"):

host:~/PHYTEC_STM32MP1_BSP$ cd layers/meta-phytec/conf/machine
host:~/PHYTEC_STM32MP1_BSP/layers/meta-phytec/conf/machine$ cp phycore-stm32mp1-mx.conf phycore-stm32mp1-myboard.conf  

• Create a symbolic link to EULA for the new machine (necessary to support GPU and third-party content):

host:~/PHYTEC_STM32MP1_BSP/layers/meta-phytec/conf/machine$ cd ../eula
host:~/PHYTEC_STM32MP1_BSP/layers/meta-phytec/conf/eula$ ln -s ST_EULA_SLA phycore-stm32mp1-myboard

Before starting to build images for your new machine, you must configure it by editing the "meta-phytec/conf/machine/phycore-stm32mp1-myboard.conf" file:

• Modify the "NAME" and "DESCRIPTION" parameters, so that you can easily identify the machine to the Hardware. Example:

#@NAME: phycore-stm32mp1-myboard
#@DESCRIPTION: MyCompany MyBoard, phyCORE-STM32MP1, stm32mp157cac @650Mhz MPU, 3D GPU, 1GiB RAM, 8GiB eMMC, 16MB QSPI NOR

• Edit some machine parameters  located under the sections "User machine customization sections" as described in the previous section: Customize the Yocto machine
• Be sure to have set up correctly the two parameters of the "CubeMX Project Config" section:
  • CUBEMX_DTB: must be set to the device tree name (without file extension)
  • CUBEMX_PROJECT: must be set to the Device tree path of CubeMX Board project (path relative to "meta-st/meta-st-stm32mp-addons" folder). For example, if the CubeMX project is located in "~/PHYTEC_STM32MP1_BSP/":

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree name (without file extension)
CUBEMX_DTB = "stm32mp157c-myboard-mx"
# Assign CubeMX Board project path (relative to "meta-st-stm32mp-addons" layer path folder)
CUBEMX_PROJECT = "../../../phycore-stm32mp1-myboard/CA7/DeviceTree/myboard"

• The new machine is now ready. You can now set up the build environment and build your BSP image. See the corresponding next sections of this chapter.

Create a New Yocto Layer

The other option (recommended method) is to create your layer which will contain your custom machine.

• If not already done, create a new Yocto layer in the layers directory (we will call it "meta-racer" as an example), with the command below:

host:~/PHYTEC_STM32MP1_BSP$ cd build-<DISTRO>-<MACHINE>
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ ../layers/openembedded-core/bitbake/bin/bitbake-layers create-layer ../layers/meta-racer

• Then, create the two following directories in the new layer and copy the EULA file:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ cd ../layers/meta-racer
host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ mkdir conf/eula && mkdir conf/machine && cp ../meta-phytec/conf/eula/ST_EULA_SLA conf/eula 

• Edit the meta-racer/conf/layer.conf file, and set a new variable ("RACER_BASE for example)"  that will store your new layer location, adding the following line:

# Set a variable to get the racer layer location
RACER_BASE = "${LAYERDIR}"

Your custom layer is now ready for building custom machines. See the next section for adding a new machine (based on "phycore-stm32mp1-mx.conf") in this new layer.

Create a New Machine in the Created Layer

Now that our "meta-racer" is ready, we can create a new machine inside. We will call this machine "racer-board".

• Copy the "meta-phytec/conf/machine/phycore-stm32mp-mx.conf" file into the "conf/machine" directory of your layer (ex: "meta-racer") and rename it (ex: "racer-board"):

host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ cp ../meta-phytec/conf/machine/phycore-stm32mp1-mx.conf conf/machine/racer-board.conf  

• Create a symbolic link to EULA for the new machine (necessary to support GPU and third-party content):

host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ cd conf/eula
host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer/conf/eula$ ln -s ST_EULA_SLA racer-board

Before starting to build images for your new machine, you must configure it, by editing the "racer-board.conf" file:

• Modify the "@NAME" and "@DESCRIPTION" parameters, so that you can easily identify the machine to the Hardware. Example:

#@NAME: racer-board
#@DESCRIPTION: Racer RacerBoard,phyCORE-STM32MP1, stm32mp157cac @650Mhz MPU, 3D GPU, 1GiB RAM, 8GiB eMMC, 16MB QSPI NOR

• As opposed to the "phycore-stm32mp1-x" machines which are located in the meta-phytec layer, we must also modify the "@NEEDED_BSPLAYERS" by adding "layers/meta-phytec", otherwise the meta-phytec BSP dependency is not added automatically with the openSTLinux environment setup script.

#@NEEDED_BSPLAYERS: layers/meta-st/meta-st-stm32mp-addons layers/meta-phytec

• For EULA file location, modify the name of the variable "PHYCORE_STM32MP_BASE" by replacing it with the one created in your "meta-racer/layer.conf" ("RACER_BASE" in our example):

EULA_FILE_ST:stm32mpcommonmx = "${RACER_BASE}/conf/eula/${MACHINE}"

• Edit some machine parameters  located under the sections "User machine customization sections" as described in the previous section: Customize the Yocto machine
• Be sure to have set up correctly the two parameters of the "CubeMX Project Config" section:
  • CUBEMX_DTB: must be set to the device tree name (without file extension)
  • CUBEMX_PROJECT: must be set to the Device tree path of CubeMX Board project (path relative to "meta-st/meta-st-stm32mp-addons" folder).

It could be a good idea to store your CubeMX project with generated device tree files in your custom layer "meta-racer". In this case, CUBEMX_PROJECTwill be set this way:

# CubeMX Project Config
# =========================================================================
# Assign CubeMX Board devicetree name (without file extension)
CUBEMX_DTB = "stm32mp157c-racer-board-mx"
# Assign CubeMX Board project path (relative to "meta-st-stm32mp-addons" layer path folder)
CUBEMX_PROJECT = "../../meta-racer/racer-board/CA7/DeviceTree/racer-board"

• The new machine is now ready. You can now set up the build environment and build your BSP image. See the next sections.

Set Up the Build Environment

OpenSTLinux build environment can be set up with or without a Graphical User Interface (GUI).

1) Setup the build env without GUI:

• Run the following command (example for "racer-board" machine with EGLFS distro):

host:~/PHYTEC_STM32MP1_BSP$ MACHINE=racer-board DISTRO=openstlinux-eglfs source openstlinux-init-phytec.sh

• A popup will appear, and you will be asked to read and accept the EULA license.
• Build environment will be set up and you should now be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>' ("build-openstlinuxeglfs-racer-board" for example).

2) Setup the build env with GUI:

• Removing the "MACHINE" and "DISTRO" parameters in the above command will open the GUI interface:

host:~/PHYTEC_STM32MP1_BSP$ source openstlinux-init-phytec.sh

• A popup will appear to ask you to choose the BUIL_DIR. Select "NEW" (Press 'space' to select and press 'enter' to validate):

• Choose a DISTRO:

• Select your machine (for example: "racer-board")
  

• Build environment will be set up and you should now be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>'

Example of created build dir:'~/PHYTEC_STM32MP1_BSP/build-openstlinuxeglfs-racer-board'

Build the Image

To build your BSP images, please follow the corresponding section: Build Process

Revision History