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.
1. X-LINUX-RT[edit | edit source]
1.1. Main software modification[edit | edit source]
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
- 900 MHz for STM32MP13x 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[edit | edit source]
With the following procedure, the complete distribution is regenerated by enabling the X-LINUX-RT Expansion Package.
2.1. Download the STM32MP1 Distribution Package[edit | edit source]
For ecosystem release v5.0.0 
:
Install the STM32MP1 Distribution Package v5.0.0.
2.2. Install the X-LINUX-RT environment[edit | edit source]
- 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 :
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[edit | edit source]
bitbake st-image-weston
2.4. Program the built image into the flash memory[edit | edit source]
Follow this link to see how to program the built image.
3. Developer Package: build the RT BSP with the SDK[edit | 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.
3.1. Install the OpenSTLinux SDK[edit | 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 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[edit | edit source]
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[edit | edit source]
- 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[edit | edit source]
As written above, to enable the RT feature, two BSP components must be modified.
3.4.1. Modify the Linux kernel[edit | edit source]
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 :
* <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[edit | edit source]
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[edit | edit source]
To check that the RT feature is enabled and functional, the following commands can be executed.
4.1. Check the Linux kernel version[edit | edit source]
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[edit | 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. References[edit | edit source]