1. Article purpose[edit source]
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
![RT Expansion Package In STM32MPU Embedded Software.png](/stm32mpu/nsfr_img_auth.php/f/f1/RT_Expansion_Package_In_STM32MPU_Embedded_Software.png)
2. X-LINUX-RT expansion package description[edit source]
2.1. Overview[edit source]
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[1].
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[edit source]
2.2.1. Linux kernel configuration[edit source]
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[edit source]
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.
2.3. Versioning[edit source]
The latest version of the X-LINUX-RT Expansion Package is If any, precise here the version of the X-LINUX-NAME expansion package to use
- X-LINUX-NAME package software
- names of software,
- revision number.
2.4. Associated licenses[edit source]
3. Prerequisites[edit source]
3.1. Hardware prerequisites[edit source]
- STM32 MPU Board
3.2. Software prerequisites[edit source]
The X-LINUX-RT Expansion Package runs with OpenSTLinux from ecosystem release v5.0.0 to v5.1.0
.
4. Software setup[edit source]
4.1. How to get software[edit source]
X-LINUX-RT Expansion Package is delivered in a git repository on Github.
4.1.1. How to install developer package[edit source]
Linux RT can be built with sources provided in the OpenSTLinux BSP packages in addition to patches and device tree files provided in X-LINUX-RT meta layer.
4.1.1.1. Install the OpenSTLinux SDK[edit source]
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[edit source]
The STM32MPU Developer Package, containing all the BSP source code, must be downloaded and extracted.
To do this, follow only the STM32MPU_Developer_Package#Installing_the_OpenSTLinux_BSP_packages chapter (and not the sub-chapters).
For ecosystem release v5.1.0 :
All BSP components are impacted:
- Linux kernel must be patched and configuration is different for the RT feature
- New DT files, present in external device tree, must be used
For ecosystem release v5.0.0 :
Two BSP components (OP-TEE OS and Linux kernel) must be modified for the RT feature. The procedure to modify them is explained in the next chapters.
4.1.1.3. Download the X-LINUX-RT meta layer[edit source]
- Clone the meta-st-x-linux-rt git repository
cd <Developer Package installation directory>/stm32mp1-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26/sources/arm-ostl-linux-gnueabi git clone -b mickledore https://github.com/STMicroelectronics/meta-st-x-linux-rt.git
4.1.1.4. Modify the BSP[edit source]
As written above, to enable the RT feature, one or two BSP components must be modified.
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.5. Modify the Linux kernel[edit source]
The patches found in <Developer Package installation directory>/stm32mp1-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26/sources/arm-ostl-linux-gnueabimeta-st-x-linux-rt/recipes-kernel/linux/6.1/6.1.28 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>/stm32mp1-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26/sources/arm-ostl-linux-gnueabimeta-st-x-linux-rt/recipes-kernel/linux/6.1/6.1.28/*.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.
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>/stm32mp1-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26/sources/arm-ostl-linux-gnueabimeta-st-x-linux-rt/recipes-kernel/linux/6.1/fragment-10-network-improvment.config * <Developer Package installation directory>/stm32mp1-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26/sources/arm-ostl-linux-gnueabimeta-st-x-linux-rt/recipes-kernel/linux/6.1/fragment-11-no-psi.config
Additionnal fragment for STM32MP13x lines :
* <Linux kernel source code directory>/arch/arm/configs/fragment-08-rt-mp13.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.6. External device tree[edit source]
For ecosystem release v5.1.0 .
The BSP component external device tree provides 4 device tree 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 openstlinux-6.1-yocto-mickledore-mpu-v24.06.26
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=/tmp/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=/tmp/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.1.7. Modify the OP-TEE OS[edit source]
For ecosystem release v5.0.0 only.
To prepare the OP-TEE OS, follow the sub-chapter STM32MPU_Developer_Package#Building_and_deploying_the_OP-TEE_for_the_first_time.
The patches found in <Developer Package installation directory>/stm32mp1-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26/sources/arm-ostl-linux-gnueabimeta-st-x-linux-rt/recipes-security/optee/optee-os must also be applied.
Enter the directory containing the OP-TEE OS sources and apply the patches
for p in `ls -1 <Developer Package installation directory>/stm32mp1-openstlinux-6.1-yocto-mickledore-mpu-v24.06.26/sources/arm-ostl-linux-gnueabimeta-st-x-linux-rt/recipes-security/optee/optee-os/*.patch`; do patch -p1 < $p; done
OP-TEE OS can now be built and deployed, as explained in STM32MPU_Developer_Package#Building_and_deploying_the_OP-TEE_for_the_first_time.
4.1.2. How to install distribution package[edit source]
4.1.2.1. Download the STM32MPU Distribution Package[edit source]
For ecosystem release v5.1.0 :
Install the STM32MPU Distribution Package v5.1.0.
For ecosystem release v5.0.0 :
Install the STM32MP1 Distribution Package v5.0.0.
4.1.2.2. Download the X-LINUX-RT meta layer[edit source]
- Clone the meta-st-x-linux-rt git repositories
For ecosystem release v5.1.0 :
pushd <Distribution Package installation directory>/layers/meta-st git clone -b mickledore https://github.com/STMicroelectronics/meta-st-x-linux-rt.git -b openstlinux-6.1-yocto-mickledore-mpu-v24.06.26 popd
For ecosystem release v5.0.0 only:
pushd <Distribution Package installation directory>/layers/meta-st git clone -b mickledore https://github.com/STMicroelectronics/meta-st-x-linux-rt.git b openstlinux-6.1-yocto-mickledore-mp1-v23.06.21 popd
- Source the build environment with the correct board and layer
DISTRO=openstlinux-weston MACHINE=stm32mp13-rt source layers/meta-st/scripts/envsetup.sh
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
![]() |
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[edit source]
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 run RT feature ...[edit source]
To check that the RT feature is enabled and functional, the following commands can be executed.
5.1. Use cases execution and expected results[edit source]
5.1.1. Cyclictest[edit source]
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[2].
For example, the following command can be used:
cyclictest --mlockall -t -a --priority=99 --interval=200 --distance=0 -l 1000
Without the RT feature |
policy: fifo: loadavg: 1.96 0.65 0.23 4/186 1671 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 |
policy: fifo: loadavg: 3.18 1.17 0.43 1/226 1776 T: 0 ( 1775) P:99 I:200 C: 1000 Min: 21 Act: 24 Avg: 28 Max: 90 T: 1 ( 1776) P:99 I:200 C: 842 Min: 20 Act: 42 Avg: 23 Max: 48 |
Note: OPTEE HSI cyclic calibration was desactivated for this test
5.2. Use case restrictions[edit source]
Latency can be improved by disabling some features or services:
* weston
* systemd
* netdata
* OPTEE HSI cyclic calibration
A new distribution named openstlinux-rt is provided. This distribution is using SysVInit instead of Systemd, no Weston, no OPTEE HSI cyclic calibration and no netdata services.
To select it, run following command:
DISTRO=openstlinux-rt MACHINE=<your machine> source layers/meta-st/scripts/envsetup.sh
RT performances are improved.
cyclictest --mlockall -t -a --priority=99 --interval=200 --distance=0 -l 1000 WARN: stat /dev/cpu_dma_latency failed: No such file or directory policy: fifo: loadavg: 0.55 0.62 0.36 1/133 648 T: 0 ( 647) P:99 I:200 C: 1000 Min: 17 Act: 18 Avg: 21 Max: 45 T: 1 ( 648) P:99 I:200 C: 781 Min: 17 Act: 23 Avg: 18 Max: 36
6. References[edit source]