X-LINUX-TSNSWCH expansion package

Applicable for

1. Article purpose[edit | edit source]

Purpose of this article is to:

introduce the X-LINUX-TSNSWCH expansion package,
define the hardware & software deliverables to use the X-LINUX-TSNSWCH expansion package,
describe all steps to integrate the X-LINUX-TSNSWCH expansion package.

TSNSWCH Expansion Package In STM32MPU Embedded Software.png

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

2.1. Overview[edit | edit source]

X-LINUX-TSNSWCH is an OpenSTLinux distribution expansion package that targets both the Time-Sensitive Networking (TSN) feature and the hardware Ethernet switch configuration in Linux^®.

Warning

It is possible to perform Time-Sensitive Networking (TSN) use cases without this expansion package (available by default in Yocto Distribution), using Ethernet endpoint see How_to_configure_TSN_endpoint

The X-LINUX-TSNSWCH expansion package is a Yocto layer which provides the necessary stuff to generate a series of software managing Time-Sensitive Networking and the hardware Ethernet switch, at userland and Linux^® kernel level. It will ease your development if you want to achieve one of the below goals :

Configure the hardware Ethernet switch and use it with TSN configurations.
Configure the hardware Ethernet switch (aka ETHSW internal peripheral) and use it without TSN configurations.
Bringing the necessary utilities to configure TSN endpoints.

By default, if you add this package to your Linux^® distribution, the hardware Ethernet switch will be ready to use, and the TSN tools to configure the different interfaces will be installed on the platform.

2.2. Main software modifications[edit | edit source]

2.2.1. Linux kernel[edit | edit source]

The X-LINUX-TSNSWCH expansion package provides:

2 additional kernel modules to enable the hardware for a standard Ethernet switch (compatible for Time-Sensitive Networking (TSN)):
- "st-stm32-deip" module to enable hardware clocks and regulators useful for TSNSWCH internal peripheral,
- "edge" module to enable the TSNSWCH internal peripheral.
a specific devicetree overlay for TSNSWCH definition.

2.2.2. User space additional stacks[edit | edit source]

The X-LINUX-TSNSWCH provides a series of userland tools and components for Time-Sensitive Networking (TSN).

See Ethernet switch overview for more details.

2.3. Versioning[edit | edit source]

The latest version of X-LINUX-TSNSWCH expansion package is v6.0.
The X-LINUX-TSNSWCH expansion package is based to be used with OpenSTLinux distribution ecosystem release v6.0.0 .

2.4. Associated licenses[edit | edit source]

See X-LINUX-TSNSWCH licenses to have in information on licenses applied to the X-LINUX-TSNSWCH expansion package.

3. Prerequisites[edit | edit source]

3.1. Hardware prerequisites[edit | edit source]

The X-LINUX-TSNSWCH is targeted to be demonstrated on the following target:

STM32MP257F-EV1

STM32MP257x-EV1 - hardware description

3.2. Software prerequisites[edit | edit source]

The X-LINUX-TSNSWCH expansion package runs with OpenSTLinux ecosystem release v6.0.0 .

As prerequisite, you need to get and install the STM32MPU Distribution Package. The way to proceed is given below:

The STM32MPU OpenSTLinux distribution is delivered through a manifest repository location and a manifest revision.
The installation relies on the repo command. In case the Repo tool (a Google-built repository management tool that runs on top of git) is not yet installed and configured on the host PC, refer to the PC prerequisites article.
The OpenSTLinux distribution is massively using open source software (OSS) packages that are downloaded from a variety of open source repositories; so it is required that the IT infrastructure proxies do not forbid such accesses. If some proxy-related issues are suspected, refer to the How to avoid proxy issues article.
Install the STM32MPU OpenSTLinux distribution: openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06

Important

Yocto is using absolute directory path to give names to intermediate files. If the path is too long, Yocto build fails because file names exceed the maximum size supported by the file system. In that case, installation directory path should be renamed to reduce the overall absolute path name.

STM32MPU Distribution Package OpenSTLinux distribution - STM32MPU-Ecosystem-6.0.0 release

Installation

Go to the host PC directory where to install the Distribution Package (<Distribution Package installation directory>). Example, if following the proposition to organize the working directory:

cd <working directory path>/Distribution-Package

Initialize repo in the current directory (More details on 'repo init' here).

Warning

Check first here, if a minor release based on this ecosystem release v6.0.0 is already published.
If a minor release exists, replace the tag used below, and in other wiki articles, by the tag provided with the minor release.

repo init -u https://github.com/STMicroelectronics/oe-manifest.git -b refs/tags/openstlinux-6.6-yocto-scarthgap-mpu-v24.11.06

Note: "ERROR 404" may appear during "repo init" command without any impact on the process

Synchronize the local project directories with the remote repositories specified in the manifest (more details on 'repo sync' here)

repo sync

Note: Distribution package needs around 140MB to be installed (and around 25GB once distribution package is compiled).

Release note

Details about the content of this software package are available in the associated STM32 MPU ecosystem release note.

If interested in previous releases, go through the archives of the ecosystem release note.

When installed, the OpenSTLinux Distribution Package is available with following tree structure:

Distribution-Package                      OpenSTLinux distribution
├── layers 
│    ├── meta-openembedded                Collection of layers for the OpenEmbedded-Core universe (OpenEmbedded standard)
│    ├── meta-st
│    │   ├── meta-st-openstlinux          STMicroelectronics layer that contains the frameworks and images settings for the OpenSTLinux distribution
│    │   ├── meta-st-stm32mp              STMicroelectronics layer that contains the description of the BSP for the STM32 MPU devices
│    │   │   ├── recipes-bsp
│    │   │   │   ├── alsa                 Recipes for ALSA control configuration
│    │   │   │   ├── ddr-firmware         Firmware for DDR PHY on STM32MP
│    │   │   │   ├── drivers              Recipes for Vivante GCNANO GPU kernel drivers
│    │   │   │   ├── fip-stm32mp          FIP generation
│    │   │   │   ├── trusted-firmware-a   Recipes for TF-A
│    │   │   │   ├── trusted-firmware-m   For STM32MP2 series - Recipes for TF-M
│    │   │   │   └── u-boot               Recipes for U-Boot
│    │   │   ├── recipes-connectivity
│    │   │   │   └── bluetooth            Systemd service to suspend/resume correctly bluetooth
│    │   │   ├── recipes-core
│    │   │   │   ├── [...]                bbappend recipes to update some core services
│    │   │   ├── recipes-extended
│    │   │   │   ├── external-dt          Recipes for providing device tree files for STM32 MPU devices outside of BSP components
│    │   │   │   ├── libb64               For STM32MP2 series - Library for base64 encoding/decoding data
│    │   │   │   ├── linux-examples       Recipes for Linux examples for STM32 MPU devices
│    │   │   │   ├── m33projects          For STM32MP2 series - Recipes for firmware examples for Cortex M33
│    │   │   │   ├── m4coredump           For STM32MP15x lines  only - Recipes for script to manage coredump of cortexM4
│    │   │   │   ├── m4projects           For STM32MP15x lines  only - Recipes for firmware examples for Cortex M4
│    │   │   │   └── stm32mp-g0           For STM32MP13x lines  only - Recipes for G0 USB firmware
│    │   │   ├── recipes-graphics
│    │   │   │   ├── gcnano-userland      Recipes for Vivante libraries OpenGL ES, OpenVG and EGL (multi backend)
│    │   │   │   └── [...]
│    │   │   ├── recipes-kernel
│    │   │   │   ├── linux                Recipes for Linux kernel
│    │   │   │   ├── linux-firmware       Recipes for Linux firmwares (example, Bluetooth firmware)
│    │   │   │   └── [...]
│    │   │   ├── recipes-security
│    │   │   │   └── optee                Recipes for OPTEE
│    │   │   ├── recipes-st
│    │   │   │   ├── images               Recipes for the bootfs and userfs partitions binaries
│    │   │   │   └── [...]
│    │   │   └── [...]
│    │   ├── meta-st-stm32mp-addons       STMicroelectronics layer that helps managing the STM32CubeMX integration
│    │   └── scripts
│    │       ├── envsetup.sh              Environment setup script for Distribution Package
│    │       └── [...]
│    └── openembedded-core                Core metadata for current versions of OpenEmbedded (standard)

4. Hardware setup[edit | edit source]

STM32MP257x-EV1 Evaluation board front side
STM32MP257F-EV1 shown here (picture is not contractual)

The Time-Sensitive Networking (TSN) switch is available via the two Ethernet ports indicated 31 and 32. Ethernet port indicated "30" can be used as TSN endpoint only.

On both 31 and 32 Ethernet ports, we can plug devices requiring accurate timing synchronization (providing by this X-LINUX-TSNSWCH expansion package through PTP protocol), and/or TSN capabilities (such as queuing discipline through Qdisc configuration). As explained in Overview chapter, you can also simply use it as an standard hardware Ethernet switch without taking care about TSN aspects.

5. Software setup[edit | edit source]

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

X-LINUX-TSNSWCH expansion package is only available as a Distribution package.
With the procedure described in next chapters, the complete distribution is regenerated by enabling the X-LINUX-TSNSWCH expansion package.

As defined in Software prerequisite, you have already installed the the STM32MPU Distribution Package

5.1.1. Install the X-LINUX-TSNSWCH distribution package[edit | edit source]

Clone the meta-st-stm32mp-tsn-swch git repositories

cd <Distribution Package installation directory>/layers/meta-st
git clone -b scarthgap https://github.com/STMicroelectronics/meta-st-stm32mp-tsn-swch.git
cd ../..

Source the build environment with the correct board and layer.

For STM32MP25x lines :

DISTRO=openstlinux-weston MACHINE=stm32mp2 source layers/meta-st/scripts/envsetup.sh
bitbake-layers add-layer ../layers/meta-st/meta-st-stm32mp-tsn-swch

5.1.2. Build the image[edit | edit source]

bitbake st-image-weston

Information

Note that building the image might take a long time depending on the host computer performance.

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

The build-<distro>-<machine>/tmp-glibc/deploy/images/<machine> directory receives complete file system images.

Build directory structure: images

Information

This is an example: the files that you will see in your build directory, might slightly differ

build-<distro>-<machine>/tmp-glibc/deploy
└── images
|   └── stm32mp1
|       ├── flashlayout_st-image-weston                                 Flash layout files (description of the partitions) for the supported flash devices
|       │   ├── FlashLayout_sdcard_stm32mp157c-dk2-optee.tsv            Flash layout file for microSD card and OP-TEE → STM32MP15 Discovery kits
|       │   ├── FlashLayout_sdcard_stm32mp157c-dk2-trusted.tsv          Flash layout file for microSD card and trusted boot chain (recommended setup) → STM32MP15 Discovery kits
|       │   ├── FlashLayout_sdcard_stm32mp157c-ev1-optee.tsv            Flash layout file for microSD card and OP-TEE → STM32MP15 Evaluation boards
|       │   ├── FlashLayout_sdcard_stm32mp157c-ev1-trusted.tsv          Flash layout file for microSD card and trusted boot chain (recommended setup) → STM32MP15 Evaluation boards
|       │   ├── [...]
|       │   ├── FlashLayout_sdcard_stm32mp135f-dk-optee.tsv             Flash layout file for microSD card and OP-TEE → STM32MP13 Discovery kits
|       │   └── [...]
|       ├── fip   FIP images to flash pointed by flashlayouts
|       │   ├── fip-stm32mp157c-dk2-optee.bin
|       │   ├── fip-stm32mp157c-dk2-trusted.bin
|       │   ├── fip-stm32mp157f-dk2-optee.bin   
|       │   ├── fip-stm32mp135f-dk-optee.bin
|       │   └── [...]
|       ├── scripts
|       │   └── create_sdcard_from_flashlayout.sh
|       ├── splash.bin                                                  U-Boot splash screen picture (file in BMP format with a .bin extension) for NOR Flash
|       ├── kernel
|       │   ├── uImage                                                      Linux kernel binary image file (with U-Boot wrapper) for bootfs partition
|       │   ├── vmlinux                                                     Debug symbol file for Linux kernel
|       │   └── [...]
|       ├── st-image-bootfs-openstlinux-weston-<machine>.ext4            Binary for bootfs partition
|       ├── st-image-userfs-openstlinux-weston-<machine>.ext4            Binary for userfs partition
|       ├── st-image-vendorfs-openstlinux-weston-<machine>.ext4          Binary for vendorfs partition
|       ├── st-image-weston-openstlinux-weston-<machine>.ext4            Binary for rootfs partition
|       └── [...]
└── [...]

The STM32CubeProgrammer tool is used to flash the STM32MPxx boards with the built image. It's assumed that this tool has been installed through the Starter Package associated with your board.

Depending on the board, several Flash devices (microSD, eMMC...) might be available. The microSD card is considered as the Flash device in the rest of this article.

The procedure to flash your board is explained in the Starter Package article that corresponds to your board (remember that all articles relative to Starter Packages are found in Category:Starter Package):

Once the flashing is terminated, the boot switches must be configured so that the Flash device (e.g. microSD card) on which the image has been flashed, is selected as the boot source:

5.3. How to run the X-LINUX-TSNSWCH package software[edit | edit source]

See How to configure Ethernet switch, How to configure TSN switch

5.4. How to trace and debug[edit | edit source]

See How to configure Ethernet switch , How to configure TSN switch

6. How to run use case[edit | edit source]

This part will be completed later.

In the meantime, you can find information in How to configure Ethernet switch , How to configure TSN switch