Building Yocto Scarthgap BSP Distribution

---

This document outlines the process used by Embedian to generate a customized build of STMicroelectronics’ official STM32MP25 OpenSTLinux Yocto Scarthgap BSP for the OSM-MP255-SF platform. The build workflow retrieves the required layers and metadata from Embedian’s GitHub repository and compiles the distribution using BitBake. This methodology is adopted to streamline parallel development and maintain alignment with upstream changes. The resulting build artifacts include bootable binary images, package feed repositories, and an SDK tailored for OSM-MP255-SF application and firmware development.

ST makes their STM32MP series official bsp build scripts available via the following GIT repository:

meta-st-openstlinux is a layer containing the framework metadata for current versions of OpenSTLinux.

meta-st-stm32mp BSP layer is a layer containing the STMicroelectronics bsp metadata for current versions of stm32mp.

STMicroelectronics Yocto layer providing additional recipes, configurations, and platform support for STM32MP devices.

Overview of the meta-embedian Yocto Layer

The supplied meta-embedian Yocto compliant layer has the following organization:

.
├── conf
│   ├── layer.conf
│   └── machine
│   ├── osmmp255-1g.conf
│   └── osmmp255.conf
├── COPYING.MIT
├── README
├── recipes-bsp
│   ├── tools
│   │   └── st-hostname
│   │   ├── st-hostname_%.bbappend
│   │   └── st-hostname.sh
│   ├── trusted-firmware-a
│   │   ├── tf-a-stm32mp
│   │   │   └── 0001-ARM-stm32mp2-add-Embedian-OSM-MP255-SF-support.patch
│   │   └── tf-a-stm32mp_2.10.bbappend
│   └── u-boot
│   ├── u-boot-stm32mp
│   │   └── 0001-board-stm32mp2-add-Embedian-OSM-MP255-SF-support.patch
│   └── u-boot-stm32mp_2023.10.bbappend
├── recipes-core
│   ├── base-files
│   │   ├── base-files
│   │   │   ├── issue
│   │   │   └── issue.net
│   │   └── base-files_%.bbappend
│   └── busybox
│   ├── busybox
│   │   └── ftpget.cfg
│   └── busybox_%.bbappend
├── recipes-devtools
│   └── sdcard-raw-tools
│   ├── sdcard-raw-tools
│   │   └── create_emmc_raw_from_flashlayout.sh
│   └── sdcard-raw-tools.bbappend
├── recipes-kernel
│   └── linux
│   ├── linux-stm32mp
│   │   ├── 6.6
│   │   │   └── 6.6.116
│   │   └── fragment-embedian-osm-mp255.config
│   └── linux-stm32mp_6.6.bbappend
└── recipes-security
└── optee
├── optee-os-stm32mp
│   └── 0001-plat-stm32mp2-add-Embedian-OSM-MP255-SF-support.patch
└── optee-os-stm32mp_4.0.0.bbappend

---

Setting Up the Tools and Build Environment

---

To build the latest ST STM32MP255C meta-bsp, you first need an Ubuntu 20.04 or 22.04 LTS installation. Since bitbake does not accept building images using root privileges, please do not login as a root user when performing the instructions in this section. 

Once you have Ubuntu 20.04 or 22.04 LTS running, install the additional required support packages using the following console command:

---

---

---

To get the BSP you need to have ’repo’ installed and use it as:

Install the ’repo’ utility:

---

---

Download the BSP Yocto Project Environment.

---

---

Download the Embedian Yocto build script and meta layer.

---

---

This script will create and bring you to ~/scarthgap-release/build-openstlinuxweston-osmmp255 directory.

Building the Target Platforms

---

To build Embedian/ST Yocto BSP, use the following commands:

---

---

Building Images with QT

---

To build Embedian/ST Yocto BSP with QT developer packages, use the following instructions.

---

---

---

Once it done, you can find all required images under ~/scarthgap-release/build-openstlinuxweston-<machine name>/tmp-glibc/deploy/images/<machine name>/

---

The file flashlayout_st-image-qt/optee/FlashLayout_sdcard_stm32mp255c-osm-optee.tsv is a OSM-MP255-SF SD-card flash layout configuration file used by the STM32MP25 OpenSTLinux / Yocto build system.

---

The file flashlayout_st-image-qt/optee/FlashLayout_emmc_stm32mp255c-osm-optee.tsv is a OSM-MP255-SF eMMC flash layout configuration file used by the STM32MP25 OpenSTLinux / Yocto build system.

---

deploy/images/<machine name>/kernel/Image

The kernel Image for OSM-MP255-SF.  

deploy/images/<machine name>/kernel/<device tree file>

All available DTB files are listed in the table below.

deploy/deb/*

This folder contains all the packages used to construct the root file system images. They are in deb format (similar format to Debian packages) and can be dynamically installed on the target platform via an apt-get install command.

---

deploy/licenses/*

A database of all licenses used in all packages built for the system.

---

Setup SD Card Automatically

This section explains how to automatically set up a bootable SD card.

---

First, we need to generate a raw image file for the SD card.

This will generate a file named FlashLayout_sdcard_stm32mp255c-osm-optee.raw, which is a bootable SD card image. Insert a microSD card into your host PC and run,

---

Set the boot switches to boot from the SD card (SW1 = 0111 on the pITX-OSM-MP255). The module will then boot from the SD card.

During the first boot, the system will automatically resize the partition to use the available storage space. This process may take a little longer than subsequent boots.

---

Install additional Packages

---

STM32MP25 OpenSTLinux provides the standard Debian APT package management mechanism, allowing users to update package indexes and install software packages using apt or apt-get.

For example:

The package repository configured by default is:
/etc/apt/sources.list.d/packages.openstlinux.st.com.list
with the following configuration:
deb http://packages.openstlinux.st.com/6.2 scarthgap main updates untested

This repository is not an official Debian repository. It is an STMicroelectronics-maintained package repository for the OpenSTLinux distribution.

Therefore, although apt/apt-get is used as the package management tool, the packages provided through this repository are maintained and published by STMicroelectronics and are intended for the STM32MP2/OpenSTLinux software environment.

Updating Package Information

To retrieve the latest package information from the configured ST repository:
$ apt-get update

Installing a Package

To install a package:
$ apt-get install

The availability and version of a package depend on the packages provided by the configured OpenSTLinux repository.

---

Writing Bitbake Recipes

---

In order to package your application and include it in the root filesystem image, you must write a BitBake recipe for it.

When starting from scratch, it is easiest to learn by example from existing recipes. 

Example HelloWorld recipe using autotools

For software that uses autotools (./configure; make; make install), writing recipes can be very simple:

---

DESCRIPTION = ”Hello World Recipe using autotools”
HOMEPAGE = ”http://www.embedian.com/”
SECTION = ”console/utils”
PRIORITY = ”optional”
LICENSE = ”GPL”
PR = ”r0”

SRC_URI = ”git://github.com/embedian/helloworld-autotools.git;protocol=https”
S = ”${WORKDIR}/git”

inherit autotools

---

SRC_URI specifies the location to download the source from. It can take the form of any standard URL using http://, ftp://, etc. It can also fetch from SCM systems, such as git in the example above.

PR is the package revision variable. Any time a recipe is updated that should require the package to be rebuilt, this variable should be incremented.

inherit autotools brings in support for the package to be built using autotools, and thus no other instructions on how to compile and install the software are needed unless something needs to be customized.

S is the source directory variable. This specifies where the source code will exist after it is fetched from SRC_URI and unpacked. The default value is ${WORKDIR}/${PN}-${PV}, where PN is the package name and PV is the package version. Both PN and PV are set by default using the filename of the recipe, where the filename has the format PN_PV.bb.

---

Example HelloWorld recipe using a single source file

This example shows a simple case of building a helloworld.c file directly using the default compiler (gcc). Since it isn’t using autotools or make, we have to tell BitBake how to build it explicitly.

---

DESCRIPTION = ”HelloWorld”
SECTION = ”examples”
LICENSE = ”GPL”

SRC_URI = ”file://helloworld.c”

S = ”${WORKDIR}”

do_compile() {
${CC} ${CFLAGS} ${LDFLAGS} helloworld.c -o helloworld
}

do_install() {
install -d ${D}${bindir}
install -m 0755 helloworld ${D}${bindir}
}

---

In this case, SRC_URI specifies a file that must exist locally with the recipe. Since there is no code to download and unpack, we set S to WORKDIR since that is where helloworld.c will be copied to before it is built.

WORKDIR is located at ${OETREE}/<build directory>/tmp/work/armv8a-poky-linux/<package name and version> for most packages. If the package is machine-specific (rather than generic for the armv8a architecture), it may be located in the smarcimx932g-poky-linux subdirectory depending on your hardware (this applies to kernel packages, images, etc).

do_compile defines how to compile the source. In this case, we just call gcc directly. If it isn’t defined, do_compile runs make in the source directory by default.

do_install defines how to install the application. This example runs install to create a bin directory where the application will be copied to and then copies the application there with permissions set to 755.

D is the destination directory where the application is installed to before it is packaged.

${bindir} is the directory where most binary applications are installed, typically /usr/bin.

For a more in-depth explanation of BitBake recipes, syntax, and variables, see the Recipe Chapter of the OpenEmbedded User Manual.

Setup eMMC

---

The eMMC setup is almost the same as the SD card setup. First, create an eMMC raw image and copy it to the SD card. Then, boot the device from the SD card and use dd to write the image to the eMMC.

A file FlashLayout_emmc_stm32mp255c-osm-optee.raw will be generated.

Copy this file and arm-trusted-firmware/tf-a-stm32mp255c-osm-optee-sdcard.stm32 to the rootfs partition of the bootable SD card created above. Unlike the SD card setup, the FlashLayout_emmc_stm32mp file needs to be written to both the eMMC Boot0 and Boot1 partitions.

---

Insert the SD card into the device and boot the device from the SD card. By default, the Linux kernel mounts eMMC hardware boot partitions as read-only for security. You can temporarily disable this restriction by modifying the kernel parameters:

---

---

---

Write eMMC raw image into eMMC.

---

Set the boot switches to boot from the eMMC card (SW1 = 0000 on the pITX-OSM-MP255). The module will then boot from the eMMC flash.

---

---

version 1.0a, 10/08/2026

Last updated 2026-10-08