X-LINUX-RT expansion package

Applicable for

STM32MP13x lines, STM32MP15x lines, STM32MP25x lines

---

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

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.

3. Prerequisites

3.1. Hardware prerequisites

• STM32 MPU Board

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 ecosystem release v5.0.0 to v5.1.0 .

4. Software setup

4.1. How to get software

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

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
cd meta-st-x-linux-rt
git reset --hard 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
cd meta-st-x-linux-rt
git reset --hard openstlinux-6.1-yocto-mickledore-mp1-v23.06.21
popd

5. How to run RT feature ...

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. Check the Linux 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.1.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.

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

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

Real-time

Microprocessor unit

Linux^® is a registered trademark of Linus Torvalds.

Operating system

Symetric multiprocessing

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