Last edited 3 weeks ago

X-LINUX-RT expansion package - v6.0.0

Applicable for STM32MP13x lines, STM32MP15x lines, STM32MP25x lines

This article describes the content of X-LINUX-RT expansion package release version v6.0.0, which can be applied on top of STM32 MPU ecosystem release note - v6.0.0.

1. Article purpose[edit | 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

2. X-LINUX-RT expansion package description[edit | edit source]

2.1. Overview[edit | 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 delivered as a new meta layer. The following chapters show how to build it with the OpenSTLinux Distribution Package.

2.2. Main software modifications[edit | edit source]

2.2.1. Linux kernel configuration[edit | 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 configuration[edit | edit source]

2.2.2.1. OP-TEE OS Profile[edit | edit source]

It is recommended to set OP-TEE OS in a system_services profile in order to optimize the system latency (Refer to STM32MPU_OP-TEE_profiles for more details about OP-TEE profiles).
It is configured by default in context of OpenSTLinux Distribution Package, and has to be considered in case of OpenSTLinux Developer Package as described in below chapters.

2.2.2.2. OP-TEE OS board device trees[edit | 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.

  • 900 MHz for STM32MP13x lines More info.png
  • 650 MHz for STM32MP15x lines More info.png
  • 1.2 GHz for STM32MP25x lines More info.png

2.3. Main restrictions[edit | edit source]

X-LINUX-RT is only available as a Distribution Package. There are no X-LINUX-RT Started package nor X-LINUX-RT Developer Package.

You can nevertheless learn how to install the X-LINUX-RT feature in your OpenSTLinux Developer Package.

2.4. Versioning[edit | edit source]

The latest version of the X-LINUX-RT expansion package is named openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06 and must be used with components delivered for ecosystem release v6.0.0 More info.png .

2.5. Associated licenses[edit | edit source]

This software package is licensed under a SOFTWARE LICENSE AGREEMENT FOR ST MATERIALS (SLA). Customers should only use this package in compliance with the software license agreement (SLA), STM32CubeMP15 licenses, and STM32CubeMP2 licenses.

3. Prerequisites[edit | edit source]

3.1. Hardware prerequisites[edit | edit source]

  • Below the list of supported STM32 MPU boards. Click on the associated links to jump to articles describing how to set up the boards: they explain how to assemble the boards, set the right power jumper configuration, connect the display to the board and connect the board to your development environment.

Boards should be assembled as defined in those articles.



3.2. Software prerequisites[edit | edit source]

Be familiar with:

  • Get the OpenSTLinux ecosystem release v6.0.0 More info.png (steps to follow described in chapters below).

4. Hardware Setup[edit | edit source]

Boards should be assembled as defined in #Hardware prerequisites.

5. Software setup[edit | edit source]

5.1. How to get software[edit | edit source]

X-LINUX-RT expansion package is delivered in a git repository on Github: https://github.com/STMicroelectronics/meta-st-x-linux-rt.git (Scarthgap branch for compatibility with this ecosystem release v6.0.0 More info.png )

It can be integrated using OpenSTLinux Distribution Package to build new OpenSTLinux images.

5.1.1. How to install the Distribution Package[edit | edit source]

5.1.1.1. Install the OpenSTLinux Distribution Package[edit | edit source]

Install the OpenSTLinux Distribution Package v6.0.0.

5.1.1.2. Download the X-LINUX-RT meta layer[edit | edit source]
  • Clone the meta-st-x-linux-rt git repositories
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.6-yocto-scarthgap-mpu-v24.11.06
popd
5.1.1.3. Build the Distribution Package[edit | edit source]
  • 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=stm32mp1-rt source layers/meta-st/scripts/envsetup.sh
For STM32MP2 series (for ecosystem release v6.0.0 More info.png ):
DISTRO=openstlinux-weston MACHINE=stm32mp2-rt source layers/meta-st/scripts/envsetup.sh
  • 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.

5.1.2. How to populate the flash memory with the image[edit | edit source]

You can refer to Flashing the built image to program your board with X-LINUX-RT binaries.


5.1.3. How to run X-LINUX-RT package software[edit | edit source]

To run X-LINUX-RT package software, just boot the image, loaded on the board, as explained in previous chapters.

5.2. How to check that RT feature is enabled[edit | edit source]

To check that the RT feature is enabled and functional, the following command can be executed when the board is running, to check the kernel version:

uname -s -r -v
Without the RT feature
Linux 6.6.48 #1 SMP PREEMPT Fri Mar 15 14:04:26 UTC 2024
With the RT feature
Linux 6.6.48-rt27 #1 SMP PREEMPT_RT Fri Mar 15 18:27:50 UTC 2024

6. How to run Cyclictest[edit | edit source]

6.1. Use cases execution and expected results[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 for one hour test: (--quiet option can be added to improve measurement)

cyclictest --mlockall --smp -p 99 -i 100 -d 0 -A 0 -D 1h
Without the RT feature
...
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
...
T: 0 ( 2131) P:99 I:100 C:36000000 Min:      7 Act:   10 Avg:   10 Max:      52
T: 1 ( 2132) P:99 I:100 C:36000000 Min:      7 Act:   11 Avg:   10 Max:      94
...

Note: OPTEE HSI cyclic calibration was deactivated for this test

6.2. Use case restrictions[edit | edit source]

None

7. How to go further[edit | edit source]

7.1. How to improve system latency in RT mode[edit | edit source]

To improve latency, a new DISTRO, named openstlinux-rt, is provided with the X-LINUX RT package.
This DISTRO is based on following characteristics:

  • it uses SysVinit instead of SystemD,
  • there is no Weston,
  • there is no OPTEE HSI cyclic calibration,
  • there is no Netdata services.

7.1.1. Build openstlinux-rt[edit | edit source]

If not done yet, set up the X-LINUX-RT Distribution Package as described #How to install the Distribution Package chapter.

To select the openstlinux-rt DISTRO, run following command:

DISTRO=openstlinux-rt MACHINE=<your machine> source layers/meta-st/scripts/envsetup.sh

Build the image

bitbake st-image-core

7.1.2. Flash openstlinux-rt[edit | edit source]

Then flash it, as explained here.

7.1.3. Performances measurement[edit | edit source]

RT performances should be improved. To check run cyclictest  :

cyclictest --mlockall --smp -p 99 -i 100 -d 0 -A 0 -D 1h
...
T: 0 ( 2131) P:99 I:100 C:36000000 Min:      7 Act:   10 Avg:   10 Max:      46
T: 1 ( 2132) P:99 I:100 C:36000000 Min:      7 Act:   11 Avg:   10 Max:      44
...

7.2. How to install X-LINUX-RT in the OpenSTLinux Developer Package[edit | edit source]

In order to build Linux RT, apply patches and device tree files provided in X-LINUX-RT meta layer on top of the OpenSTLinux BSP components.

7.2.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 STM32MPU_Developer_Package#Installing_the_SDK chapter).

Once the installation is done, a directory is present, containing the OpenSTLinux SDK.

7.2.2. Download the OpenSTLinux Developer Package[edit | edit source]

The OpenSTLinux Developer Package, containing all the BSP components source code, must be downloaded and extracted, refer

Warning DB.png Important
For STM32MP1 series the external device tree source is not delivered in the OpenSTLinux Developer Package, it should be downloaded directly from GitHub:
cd <Developer Package installation directory>
git clone https://github.com/STMicroelectronics/dt-stm32mp.git -b openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06

7.2.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>
git clone https://github.com/STMicroelectronics/meta-st-x-linux-rt.git -b openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06

7.2.4. Apply X-LINUX-RT delivery sources[edit | edit source]

All BSP components are impacted:

  • Linux kernel is patched and its configuration has been updated for the RT feature
  • New DT files are used. External DT repository has been patched and then new DT files are available
7.2.4.1. Apply patches on the Linux kernel and build Linux Kernel[edit | edit source]

The patches delivered in <Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.6/6.6.48 must be applied.

For that :

  • Enter into the directory containing the Linux kernel sources and apply the patches:
for p in `ls -1 <Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.6/*.patch`; do patch -p1 < $p; done
Once the patches applied, new fragments are present inside the Linux kernel source.

The Linux kernel source is ready to be configured before build:

  • Apply first the fragments now available from Linux kernel source as explained in the README.HOW_TO.txt helper file. This file is present in the Linux kernel installation directory.
  • Only for STM32MP13x lines More info.png, apply the fragment <Developer Package installation directory>/stm32mp1-openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06/sources/arm-ostl-linux-gnueabilinux-stm32mp-6.6.48-stm32mp-r1-r0/optional-fragment-06-nosmp.config as explained in the README.HOW_TO.txt helper file.
scripts/kconfig/merge_config -m -r -O ${OUTPUT_BUILD_DIR} ${OUTPUT_BUILD_DIR}/.config ../optional-fragment-06-nosmp.config
(yes  || true) | make oldconfig O="${OUTPUT_BUILD_DIR}"
  • Then, as explained in the README.HOW_TO.txt helper file, apply also following fragments:
<Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.6/fragment-10-network-improvment.config
<Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.6/fragment-11-no-psi.config
<Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.6/fragment-12-rt-optimization.config
for f in `ls -1 <Developer Package installation directory>/meta-st-x-linux-rt/recipes-kernel/linux/6.6/fragment-*.config`; do scripts/kconfig/merge_config -m -r -O ${OUTPUT_BUILD_DIR} ${OUTPUT_BUILD_DIR}/.config $f; done
(yes  || true) | make oldconfig O="${OUTPUT_BUILD_DIR}"
7.2.4.2. Apply patches on the external device tree, build bootloaders and generate FIP images[edit | edit source]

The patches delivered in <Developer Package installation directory>/meta-st-x-linux-rt/recipes-extended/external-dt/external-dt must be applied. For that:
Enter into the directory containing the external device tree sources and apply the patches:

for p in `ls -1 <Developer Package installation directory>/meta-st-x-linux-rt/recipes-extended/external-dt/external-dt/*.patch`; do patch -p1 < $p; done

Once the patches are applied, 5 new device tree files are provided to ease the configuration for RT feature:

  • stm32mp157f-dk2-rt.dts (for STM32MP157F-DK2 More info green.png) sets the CPU clock at 650MHz and disable secure IWDG1
  • stm32mp157f-ev1-rt.dts (forSTM32MP157F-EV1 More info green.png) sets the CPU clock at 650MHz and disable secure IWDG1
  • stm32mp135f-dk-rt.dts (for STM32MP135F-DK More info green.png) sets the CPU clock at 900MHz and disable secure IWDG1
  • stm32mp257f-dk-rt.dts (for STM32MP257F-DK More info green.png) disable secure IWDG1
  • stm32mp257f-ev1-rt.dts (for STM32MP257F-EV1 More info green.png) disable secure IWDG1

To enable the use of external device tree sources, as explains in the README.HOW_TO.txt helper file, export its path into the variable EXTDT_DIR

export EXTDT_DIR=$PWD

Define also a specific directory to store the build binaries and fip:

export FIP_DEPLOYDIR_ROOT=<Developer Package installation directory>/X-LINUX-RT-fip-binaries

Then OP-TEE OS, TF-A and U-Boot must be built with the chosen device tree following instruction from the respective README.HOW_TO.txt helper files.
Note that for X-LINUX-RT, the system_services profile for OP-TEE OS is recommended and should be by selected through opteemin configuration to build the components.

  • Example for stm32mp157f-dk2-rt.dts

The Makefile.sdk must be modified to enable external device tree. For that, 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

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_EXT_DTS=$(EXTDT_DIR)/optee

OP-TEE OS can now be built with the specific device tree

cd <directory to OP-TEE OS source code>
make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/optee CFG_EMBED_DTB_SOURCE_FILE=stm32mp157f-dk2-rt OPTEE_CONFIG=opteemin optee

The Makefile.sdk must be modified to enable external device tree. For that, 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

cd <directory to U-Boot source code>
make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/u-boot UBOOT_CONFIG=default UBOOT_DEFCONFIG=stm32mp15_defconfig UBOOT_BINARY=u-boot.dtb DEVICE_TREE=stm32mp157f-dk2-rt uboot

The Makefile.sdk must be modified to enable external device tree. For that, 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

cd <directory to TF-A source code>
make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/arm-trusted-firmware TF_A_DEVICETREE=stm32mp157f-dk2-rt TF_A_CONFIG=opteemin-sdcard ELF_DEBUG_ENABLE='1' stm32

Then generate the fip

make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/arm-trusted-firmware TF_A_DEVICETREE=stm32mp157f-dk2-rt TF_A_CONFIG=opteemin-sdcard ELF_DEBUG_ENABLE='1' fip
  • Example for stm32mp257f-ev1-rt.dts

OP-TEE OS can be built with the specific device tree

cd <directory to OP-TEE OS source code>
make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/optee CFG_EMBED_DTB_SOURCE_FILE=stm32mp257f-ev1-rt OPTEE_CONFIG=opteemin optee

U-Boot can be built with the specific device tree

cd <directory to U-Boot source code>
make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/u-boot UBOOT_CONFIG=default UBOOT_DEFCONFIG=stm32mp25_defconfig UBOOT_BINARY=u-boot.dtb DEVICE_TREE=stm32mp257f-ev1-rt uboot

TF-A can now built with the specific device tree

cd <directory to TF-A source code>
make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/arm-trusted-firmware TF_A_DEVICETREE=stm32mp257f-ev1-rt TF_A_CONFIG=opteemin-sdcard ELF_DEBUG_ENABLE='1' stm32

Then generate the fip

make -f $PWD/../Makefile.sdk DEPLOYDIR=${FIP_DEPLOYDIR_ROOT}/arm-trusted-firmware TF_A_DEVICETREE=stm32mp257f-ev1-rt TF_A_CONFIG=opteemin-sdcard ELF_DEBUG_ENABLE='1' fip

Then new TF-A and FIP binaries can now be deployed, as explained in Building and deploying the TF-A for the first time.

8. References[edit | edit source]