X-LINUX-RT expansion package

Applicable for STM32MP13x lines, STM32MP15x lines

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

RT Expansion Package In STM32MPU Embedded Software.png

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.


Info white.png Information
This version is compatible with the Yocto Project® build system Mickledore. It is validated against the OpenSTLinux ecosystem release v5.0.0 More info.png on the following targets:
  • STM32MP157D-DK1 More info green.png
  • STM32MP157C-DK2 Warning.png and STM32MP157F-DK2 More info green.png
  • STM32MP157C-EV1 Warning.png , STM32MP157D-EV1 More info green.png and STM32MP157F-EV1 More info green.png
  • STM32MP135F-DK More info green.png

1.1 Main software modification

Moving to Linux RT impacts the kernel configuration:​

  • 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 More info.png
    • 650 MHz for STM32MP15x lines More info.png
  • High-resolution timers and periodic ticks must be used to have a precise tick.

2 Distribution Package: regenerate the X-LINUX-RT OpenSTLinux distribution

With the following procedure, the complete distribution is regenerated by enabling the X-LINUX-RT Expansion Package.

2.1 Download the STM32MP1 Distribution Package

For ecosystem release v5.0.0 More info.png :
Install the STM32MP1 Distribution Package v5.0.0.

2.2 Install the X-LINUX-RT environment

  • Clone the meta-st-x-linux-rt git repositories
 cd <Distribution Package installation directory>/layers/meta-st
 git clone -b mickledore https://github.com/STMicroelectronics/meta-st-x-linux-rt.git
 cd ../..
  • Source the build environment with the correct board and layer.

For STM32MP13x lines More info.png:

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

For STM32MP15x lines More info.png:

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

2.3 Build the image

 bitbake st-image-weston
Info white.png Information
Note that building the image might take a long time depending on the host computer performance.

2.4 Program the built image into the flash memory

Follow this link to see how to program the built image.

3 Developer Package: build the RT BSP with the SDK

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.

3.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 STM32MP1_Developer_Package#Installing_the_SDK chapter. Once the installation is done, a directory is present, containing the OpenSTLinux SDK.

3.2 Download the Developer Package

The STM32MP1 Developer Package, containing all the BSP source code, must be downloaded and extracted. To do this, follow only the STM32MP1_Developer_Package#Installing_the_OpenSTLinux_BSP_packages chapter (and not the sub-chapters).

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.

3.3 Download the X-LINUX-RT meta layer

  • Clone the meta-st-x-linux-rt git repository
cd <Developer Package installation directory>/stm32mp1-openstlinux-6.1-yocto-mickledore-mp1-v23.06.21/sources/arm-ostl-linux-gnueabi/
git clone -b mickledore https://github.com/STMicroelectronics/meta-st-x-linux-rt.git

3.4 Modify the BSP

As written above, to enable the RT feature, two BSP components must be modified.

3.4.1 Modify the Linux kernel

At this stage, follow the sub-chapter STM32MP1_Developer_Package#Building_and_deploying_the_Linux_kernel_for_the_first_time to prepare the Linux kernel.
The patches found in <Developer Package installation directory>/stm32mp1-openstlinux-6.1-yocto-mickledore-mp1-v23.06.21/sources/arm-ostl-linux-gnueabi/meta-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-mp1-v23.06.21/sources/arm-ostl-linux-gnueabi/meta-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-mp1-v23.06.21/sources/arm-ostl-linux-gnueabi/meta-st-x-linux-rt/recipes-kernel/linux/6.1/fragment-10-network-improvment.config
* <Developer Package installation directory>/stm32mp1-openstlinux-6.1-yocto-mickledore-mp1-v23.06.21/sources/arm-ostl-linux-gnueabi/meta-st-x-linux-rt/recipes-kernel/linux/6.1/fragment-11-no-psi.config

Additionnal fragment for STM32MP13x lines More info.png:

* <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 STM32MP1_Developer_Package#Building_and_deploying_the_Linux_kernel_for_the_first_time.

3.4.2 Modify the OP-TEE OS

To prepare the OP-TEE OS, follow the sub-chapter STM32MP1_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-mp1-v23.06.21/sources/arm-ostl-linux-gnueabi/meta-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-mp1-v23.06.21/sources/arm-ostl-linux-gnueabi/meta-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 STM32MP1_Developer_Package#Building_and_deploying_the_OP-TEE_for_the_first_time.

4 Validate the RT feature

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

4.1 Check the Linux kernel version

 uname -s -r -v
Without the RT feature
Linux 6.1.28 #1 SMP PREEMPT Thu May 11 14:04:52 UTC 2023
With the RT feature
Linux 6.1.28-rt10 #1 SMP PREEMPT_RT Thu May 11 14:04:52 UTC 2023

4.2 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[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 References