X-LINUX-RT expansion package

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP25x lines

---

Important

This version of X-LINUX-RT expansion package is validated against the ecosystem release v5.1.0 . It has not been ported yet on ecosystem release v6.0.0 .

This article describes the content of X-LINUX-RT Expansion Package release version v5.1.0, which can be applied on top of STM32 MPU ecosystem release note - v5.1.0.

1. Article purpose

Purpose of this article is to:

• introduce the X-LINUX-RT expansion package
• define the hardware & software deliverables to use the X-LINUX-RT package,
• describe all steps to integrate the X-LINUX-RT package and associated expected results
• give some use case examples enabled by the X-LINUX-RT package

2. X-LINUX-RT expansion package description

2.1. Overview

X-LINUX-RT is an STM32 MPU OpenSTLinux Expansion Package that targets the real-time (RT) feature in the Linux^® kernel.
An RT system is a system that responds to a request in a time lapse and not as fast as possible. It targets​:

• Determinism​
• LATENCY but not SPEED

For a better understanding about real-time Linux, refer to the Linux RT foundation website.
The X-LINUX-RT Expansion Package is mainly designed to be used with Yocto and the OpenSTLinux Distribution Package. However, the following chapters show how to use it either with the OpenSTLinux Distribution Package or with the Developer Package.

2.2. Main software modifications

2.2.1. Linux kernel configuration

The Linux kernel configuration must be modified to enable:

• CONFIG_PREEMPT_RT : RT feature in kernel
• CONFIG_HIGH_RES_TIMERS : high resolution timer support

2.2.2. OP-TEE OS board device trees

Power management is not "compliant" with a real-time context as it changes the system behavior. Because there is no more frequency scaling, and to ensure an optimal lifetime for the microprocessor, the frequency is fixed following the recommended industrial profile.

• 900 MHz for STM32MP13x lines 
• 650 MHz for STM32MP15x lines 
• 1.2 GHz for STM32MP25x lines 

2.3. Versioning

The latest version of the X-LINUX-RT Expansion Package is named unknown revision and must be used with components delivered for ecosystem release v5.1.0 .

2.4. Associated licenses

None

3. Prerequisites

3.1. Hardware prerequisites

• List of supported STM32 MPU Boards

STM32MP257x-EV1 - hardware description

STM32MP157x-EV1 - hardware description

STM32MP157x-DKx - hardware description

STM32MP135x-DK - hardware description

3.2. Software prerequisites

The X-LINUX-RT Expansion Package runs with OpenSTLinux on board:

• STM32MP13x lines  and STM32MP15x lines 
• STM32MP25x lines 

4. Software setup

4.1. How to get software

X-LINUX-RT Expansion Package is delivered in a git repository on Github.

4.1.1. How to install developer package

In order to build Linux RT, apply patches and device tree files provided in X-LINUX-RT meta layer on top of the OpenSTLinux BSP packages.

4.1.1.1. Install the OpenSTLinux SDK

The OpenSTLinux SDK contains all the basis needed for the X-LINUX-RT Expansion Package.

It must be downloaded and installed (refer to the STM32MPU_Developer_Package#Installing_the_SDK chapter).

Once the installation is done, a directory is present, containing the OpenSTLinux SDK.

4.1.1.2. Download the STM32MPU Developer Package

The STM32MPU Developer Package, containing all the BSPs source code, must be downloaded and extracted.
For that, follow only the STM32MPU_Developer_Package#Installing_the_OpenSTLinux_BSP_packages chapter (and not the sub-chapters).

4.1.1.3. Download the X-LINUX-RT meta layer

Clone the meta-st-x-linux-rt git repository

cd <Developer Package installation directory>
git clone https://github.com/STMicroelectronics/meta-st-x-linux-rt.git -b unknown revision

4.1.1.4. Apply X-LINUX-RT delivery sources

All BSPs components are impacted:

• Linux kernel is patched and its configuration is updated for the RT feature
• New DT files, present in external device tree (new git repository containing device tree files for BSP components out from component tree files), are used

If not done yet, please follow chapter Installing the components to develop software running on Arm Cortex-A (OpenSTLinux distribution) and sub-chapters to install SDK and extract the developer package.

4.1.1.4.1. Modify the Linux kernel

The patches found in <Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.1/6.1.82 must also be applied.
Enter the directory containing the Linux kernel sources and apply the patches:

for p in `ls -1 <Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.1/6.1.82/*.patch`; do patch -p1 < $p; done

Once the patches are applied, new fragments are present inside the Linux kernel source.

Apply first the fragments as explained in the README.HOW_TO.txt helper file. This file is present in the Linux kernel installation directory.

To avoid unexpected kernel configuration, make sure to remove first the fragment <Linux kernel source code directory>/arch/arm/configs/fragment-08-rt-mp13.config.

rm <Linux kernel source code directory>/arch/arm/configs/fragment-08-rt-mp13.config

For STM32MP13x lines , apply the fragment <Developer Package installation directory>/unknown revisionunknown revision/optional-fragment-06-nosmp.config.

Then, add also the following fragments:

* <Linux kernel source code directory>/arch/arm/configs/fragment-07-rt.config
* <Linux kernel source code directory>/arch/arm/configs/fragment-07-rt-sysvinit.config
* <Developer Package installation directory/meta-st-x-linux-rt/recipes-kernel/linux/6.1/fragment-10-network-improvment.config
* <Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.1/fragment-11-no-psi.config

The Linux kernel can now be built and deployed, as explained in STM32MPU_Developer_Package#Building_and_deploying_the_Linux_kernel_for_the_first_time.

4.1.1.4.2. External device tree

The BSP component external device tree provides 4 device tree files to ease the configuration for RT feature:

• stm32mp157f-dk2-rt.dts (for STM32MP157F-DK2 ) sets the CPU clock at 650MHz and disable secure IWDG1
• stm32mp157f-ev1-rt.dts (forSTM32MP157F-EV1 ) sets the CPU clock at 650MHz and disable secure IWDG1
• stm32mp135f-dk-rt.dts (for STM32MP135F-DK ) sets the CPU clock at 900MHz and disable secure IWDG1
• stm32mp257f-ev1-rt.dts (for STM32MP257F-EV1 ) disable secure IWDG1

For STM32MP1 series

External device tree is not delivered in the developer package for STM32MP1 series.

It can be downloaded from GitHub.

git clone https://github.com/STMicroelectronics/dt-stm32mp.git -b unknown revision

Then export the path into the variable

export EXTDT_DIR=$PWD/dt-stm32mp

Define a directory for build binaries and fip

export FIP_DEPLOYDIR_ROOT=<Developer Package installation directory>/unknown revision/fipRT

Then OP-TEE OS, TF-A and U-Boot must be built with the chosen device tree.

For example for stm32mp157f-dk2-rt

• OP-TEE OS

The Makefile.sdk must be modified to enable external device tree. Change the line

EXTRA_OEMAKE = PLATFORM=stm32mp1 CROSS_COMPILE_core=arm-ostl-linux-gnueabi- CROSS_COMPILE_ta_arm64=arm-ostl-linux-gnueabi- ARCH=arm CFG_ARM32_core=y CROSS_COMPILE_ta_arm32=arm-ostl-linux-gnueabi- NOWERROR=1 LDFLAGS=  CFG_TEE_CORE_LOG_LEVEL=2 CFG_TEE_CORE_DEBUG=n  CFG_SCMI_SCPFW=n

into

EXTRA_OEMAKE = PLATFORM=stm32mp1 CROSS_COMPILE_core=arm-ostl-linux-gnueabi- CROSS_COMPILE_ta_arm64=arm-ostl-linux-gnueabi- ARCH=arm CFG_ARM32_core=y CROSS_COMPILE_ta_arm32=arm-ostl-linux-gnueabi- NOWERROR=1 LDFLAGS=  CFG_TEE_CORE_LOG_LEVEL=2 CFG_TEE_CORE_DEBUG=n  CFG_SCMI_SCPFW=n CFG_EXT_DTS=$(EXTDT_DIR)/optee

OP-TEE OS can now be built with the specific device tree

make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/optee CFG_EMBED_DTB_SOURCE_FILE=stm32mp157f-dk2-rt optee

• U-Boot

The Makefile.sdk must be modified to enable external device tree. Change the line

EXTERNAL_DT_OPTS =

into

EXTERNAL_DT_OPTS = EXT_DTS=$(EXTDT_DIR)/u-boot

U-Boot can now be built with the specific device tree

make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/u-boot UBOOT_CONFIG=default UBOOT_DEFCONFIG=stm32mp15_defconfig UBOOT_BINARY=u-boot.dtb DEVICETREE=stm32mp157f-dk2-rt uboot

• TF-A

The Makefile.sdk must be modified to enable external device tree. Change the line

EXTRA_OEMAKE ?=  PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 CROSS_COMPILE=arm-ostl-linux-gnueabi- DEBUG=1 LOG_LEVEL=40 

into

EXTRA_OEMAKE ?=  PLAT=stm32mp1 ARCH=aarch32 ARM_ARCH_MAJOR=7 CROSS_COMPILE=arm-ostl-linux-gnueabi- DEBUG=1 LOG_LEVEL=40 TFA_EXTERNAL_DT=$(EXTDT_DIR)/tf-a

TF-A can now be built with the specific device tree

make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/arm-trusted-firmware TF_A_DEVICETREE=stm32mp157f-dk2-rt TF_A_CONFIG=optee-sdcard ELF_DEBUG_ENABLE='1' stm32

Then generate the fip

make -f $PWD/../Makefile.sdk TF_A_DEVICETREE=stm32mp157f-dk2-rt TF_A_CONFIG=optee-sdcard ELF_DEBUG_ENABLE='1' DEPLOYDIR=${FIP_DEPLOYDIR_ROOT} fip

For STM32MP2 series

External device tree is delivered in the developer package for STM32MP2 series.

As written in its README.HOW_TO.txt, export its path into the variable

export EXTDT_DIR=$PWD
popd

Define a directory for build binaries and fip

export FIP_DEPLOYDIR_ROOT=<Developer Package installation directory>/unknown revision/fipRT

Then OP-TEE OS, TF-A and U-Boot must be built with the chosen device tree.

For example for stm32mp257f-ev1-rt

• OP-TEE OS

OP-TEE OS can be built with the specific device tree

make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/optee CFG_EMBED_DTB_SOURCE_FILE=stm32mp257f-ev1-rt optee

• U-Boot

U-Boot can be built with the specific device tree

make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/u-boot UBOOT_CONFIG=default UBOOT_DEFCONFIG=stm32mp25_defconfig UBOOT_BINARY=u-boot.dtb DEVICETREE=stm32mp257f-ev1-rt uboot

• TF-A

TF-A can now built with the specific device tree

make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/arm-trusted-firmware TF_A_DEVICETREE=stm32mp257f-ev1-rt TF_A_CONFIG=optee-sdcard ELF_DEBUG_ENABLE='1' stm32

Then generate the fip

make -f $PWD/../Makefile.sdk TF_A_DEVICETREE=stm32mp257f-ev1-rt TF_A_CONFIG=optee-sdcard ELF_DEBUG_ENABLE='1' DEPLOYDIR=${FIP_DEPLOYDIR_ROOT} fip

4.1.2. How to install distribution package

4.1.2.1. Download the STM32MPU Distribution Package

Install the STM32MPU Distribution Package v5.1.0.

4.1.2.2. Download the X-LINUX-RT meta layer

• Clone the meta-st-x-linux-rt git repositories

pushd <Distribution Package installation directory>/layers/meta-st
git clone -b mickledore https://github.com/STMicroelectronics/meta-st-x-linux-rt.git -b unknown revision
popd

• Source the build environment with the correct board and layer

For STM32MP13x lines :

DISTRO=openstlinux-weston MACHINE=stm32mp13-rt source layers/meta-st/scripts/envsetup.sh

For STM32MP15x lines :

DISTRO=openstlinux-weston MACHINE=stm32mp1-rt source layers/meta-st/scripts/envsetup.sh

For STM32MP2 series (for ecosystem release v5.1.0 ):

DISTRO=openstlinux-weston MACHINE=stm32mp2-rt source layers/meta-st/scripts/envsetup.sh

• Build the image

bitbake st-image-weston

Information

Note that building the image might take a long time depending on the host computer performance.

4.2. How to run the X-LINUX-RT package software

After the board has been programmed, simply start it and check the kernel version.

uname -s -r -v

Without the RT feature	Linux 6.1.82 #1 SMP PREEMPT Fri Mar 15 14:04:26 UTC 2024
With the RT feature	Linux 6.1.82-rt27 #1 SMP PREEMPT_RT Fri Mar 15 18:27:50 UTC 2024

5. How to validate RT feature enabling

To check that the RT feature is enabled and functional, the following commands can be executed.

5.1. Use cases execution and expected results

5.1.1. Cyclictest

Cyclictest accurately and repeatedly measures the difference between the time at which a thread is intended to wake up and the time at which it actually wakes up.
For a better understanding of cyclictest, refer to the cyclictest webpage in the Linux RT foundation website.

For example, the following command can be used for one hour test: (--quiet option can be added to improve measurement)

cyclictest --mlockall --smp -p 99 -i 100 -d 0 -A 0 -D 1h

Without the RT feature	... T: 0 ( 1667) P:99 I:200 C: 1000 Min: 21 Act: 40 Avg: 33 Max: 103 T: 1 ( 1668) P:99 I:200 C: 882 Min: 21 Act: 58 Avg: 42 Max: 187 ...
With the RT feature	... T: 0 ( 2131) P:99 I:100 C:36000000 Min: 7 Act: 10 Avg: 10 Max: 52 T: 1 ( 2132) P:99 I:100 C:36000000 Min: 7 Act: 11 Avg: 10 Max: 94 ...

Note: OPTEE HSI cyclic calibration was deactivated for this test

5.2. Use case restrictions

Latency can be improved by disabling some features or services:

* weston
* systemd
* netdata
* OPTEE HSI cyclic calibration

5.3. openstLinux-rt distribution

To improve latency, a new distribution named openstlinux-rt is provided.
This distribution is based on following characteristics:

• it's using SysVinit instead of SystemD
• there is no Weston
• there is no OPTEE HSI cyclic calibration
• there is no Netdata services.

5.3.1. Build openstLinux-rt

If not done yet, install the Distribution Package and clone the layer meta-st-x-linux-rt as described here.

To select the distribution openstLinux-rt, run following command:

DISTRO=openstLinux-rt MACHINE=<your machine> source layers/meta-st/scripts/envsetup.sh

Build the image

bitbake st-image-core

5.3.2. Flash openstLinux-rt

Then flash it, as explained here.

5.3.3. Performances

RT performances are improved.

cyclictest --mlockall --smp -p 99 -i 100 -d 0 -A 0 -D 1h
...
T: 0 ( 2131) P:99 I:100 C:36000000 Min:      7 Act:   10 Avg:   10 Max:      46
T: 1 ( 2132) P:99 I:100 C:36000000 Min:      7 Act:   11 Avg:   10 Max:      44
...

Real-time

Microprocessor unit

Linux^® is a registered trademark of Linus Torvalds.

Open portable trusted execution environment

Operating system

Board support package

Software development kit (A programming package that enables a programmer to develop applications for a specific platform.)c

Device tree

Central processing unit

Firmware image package is a packaging format used by TF-A

Trusted firmware for Arm^® Cortex^®-A

Das U-Boot -- the universal boot loader (see U-Boot)

Trusted execution environment

System control and management interface

Device tree source (in software context) or digital temperature sensor (in peripheral context)

Device tree binary (or Blob)

Executable and linkable file

Symetric multiprocessing

High speed internal oscillator (STM32 clock source) or High speed synchronous serial interface (MIPI^® Alliance standard)

Flash memory shortened to gain space in titles, tables and block diagrams

Real-time

Microprocessor unit

Linux^® is a registered trademark of Linus Torvalds.

Open portable trusted execution environment

Operating system

Board support package

Software development kit (A programming package that enables a programmer to develop applications for a specific platform.)c

Device tree

Central processing unit

Firmware image package is a packaging format used by TF-A

Trusted firmware for Arm^® Cortex^®-A

Das U-Boot -- the universal boot loader (see U-Boot)

Trusted execution environment

System control and management interface

Device tree source (in software context) or digital temperature sensor (in peripheral context)

Device tree binary (or Blob)

Executable and linkable file

Symetric multiprocessing

High speed internal oscillator (STM32 clock source) or High speed synchronous serial interface (MIPI^® Alliance standard)

Flash memory shortened to gain space in titles, tables and block diagrams

Arm^® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

Cortex^®

Mobile Industry Processor Interface, open membership organization that includes leading companies in the mobile industry that share the objective of defining and promoting open specifications for interfaces inside mobile terminals, see MIPI^® Alliance standard web site https://www.mipi.org

Flash memories combine high density and cost effectiveness of EPROMs with the electrical erasability of EEPROMs. For this reason, the Flash memory market is one of the most exciting areas of the semiconductor industry today and new applications requiring in system reprogramming, such as cellular telephones, automotive engine management systems, hard disk drives, PC BIOS software for Plug & Play, digital TV, set top boxes, fax and other modems, PC cards and multimedia CD-ROMs, offer the prospect of very high volume demand.