X-LINUX-RT OpenSTLinux 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.

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.

1 X-LINUX-RT

Information

This version is compatible with the Yocto Project® build system Kirkstone. It is validated against the OpenSTLinux ecosystem release v4.1.0 on the following targets: STM32MP157D-DK1 STM32MP157C-DK2 and STM32MP157F-DK2 STM32MP157C-EV1 , STM32MP157D-EV1 and STM32MP157F-EV1 STM32MP135F-DK

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 
  • 650 MHz for STM32MP15x lines 
• 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 v4.1.0 :
Install the STM32MP1 Distribution Package v4.1.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 https://github.com/STMicroelectronics/meta-st-x-linux-rt.git
 cd ../..

• 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=stm32mp15-rt source layers/meta-st/scripts/envsetup.sh

2.3 Build the image

 bitbake st-image-weston

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-5.15-yocto-kirkstone-mp1-v22.11.23/sources/arm-ostl-linux-gnueabi/
git clone 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-5.15-yocto-kirkstone-mp1-v22.11.23/sources/arm-ostl-linux-gnueabi/meta-st-x-linux-rt/recipes-kernel/linux/5.15/5.15.67 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-5.15-yocto-kirkstone-mp1-v22.11.23/sources/arm-ostl-linux-gnueabi/meta-st-x-linux-rt/recipes-kernel/linux/5.15/5.15.67/*.patch`; do patch -p1 < $p; done

Once the patches are applied, new fragments are present inside the Linux kernel source. Apply 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:

For STM32MP13x lines :

* arch/arm/configs/fragment-07-rt.config
* arch/arm/configs/fragment-07-rt-sysvinit.config
* arch/arm/configs/fragment-08-rt-mp13.config

For STM32MP15x lines :

* arch/arm/configs/fragment-07-rt.config
* arch/arm/configs/fragment-07-rt-sysvinit.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-5.15-yocto-kirkstone-mp1-v22.11.23/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-5.15-yocto-kirkstone-mp1-v22.11.23/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 5.15.67 #1 SMP PREEMPT Thu Sep 8 10:32:54 UTC 2022
With the RT feature	Linux 5.15.67-rt49 #1 SMP PREEMPT_RT Thu Sep 8 10:32:54 UTC 2022

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.

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: 0.03 0.08 0.08 1/173 8476 T: 0 ( 8475) P:99 I:200 C: 1000 Min: 15 Act: 71 Avg: 32 Max: 100 T: 1 ( 8476) P:99 I:200 C: 853 Min: 15 Act: 48 Avg: 31 Max: 65
With the RT feature	policy: fifo: loadavg: 0.29 0.32 0.24 1/211 3815 T: 0 ( 3814) P:99 I:200 C: 1000 Min: 15 Act: 21 Avg: 23 Max: 60 T: 1 ( 3815) P:99 I:200 C: 795 Min: 16 Act: 32 Avg: 20 Max: 59