X-LINUX-TSNSWCH expansion package

Applicable for

STM32MP25x lines

---

1. Article purpose

The purpose of this article is to:

• Introduce the X-LINUX-TSNSWCH expansion package
• Define the hardware and software deliverables to use the X-LINUX-TSNSWCH expansion package
• Describe all steps to integrate the X-LINUX-TSNSWCH expansion package

2. X-LINUX-TSNSWCH expansion package description

2.1. Overview

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 for details.

The X-LINUX-TSNSWCH expansion package is a Yocto layer that provides the necessary resources to generate software for managing time-sensitive networking and the hardware Ethernet switch, at both userland and Linux^® kernel levels. It simplifies development to achieve one of the following goals:

• Configure the hardware Ethernet switch and use it with TSN configurations
• Configure the hardware Ethernet switch (also known as the ETHSW internal peripheral) and use it without TSN configurations
• Provide the necessary utilities to configure TSN endpoints

By default, adding this package to your Linux^® distribution makes the hardware Ethernet switch ready to use and installs the TSN configuration tools.

2.2. Main software modifications

2.2.1. Linux^® kernel

The X-LINUX-TSNSWCH expansion package provides:

• Two additional kernel modules to enable the hardware for a standard Ethernet switch (compatible for time-sensitive networking):
  • The "st-stm32-deip" module to enable hardware clocks and regulators useful for the TSNSWCH internal peripheral
  • The "edge" module to enable the TSNSWCH internal peripheral
• A specific device tree overlay for TSNSWCH definition

2.2.2. User space additional stacks

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

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

2.4. Associated licenses

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

3. Prerequisites

3.1. Hardware prerequisites

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

• STM32MP257F-EV1
  

The hardware description for the STM32MP257x-EV1 is available in a dedicated wiki page here.

3.2. Software prerequisites

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

Prerequisite: You need to get and install the STM32MPU Distribution Package. The instructions, repeated from the dedicated wiki page, are provided 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>). For 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

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

The time-sensitive networking (TSN) switch is available via the two Ethernet ports labeled 31 and 32. The Ethernet port labeled "30" can be used only as a TSN endpoint.

Ethernet Ports 31 and 32:

• These ports can be used to connect devices requiring accurate timing synchronization, provided by the X-LINUX-TSNSWCH expansion package through the PTP protocol.
• They also support TSN capabilities, such as queuing discipline through Qdisc configuration.
• As explained in the Overview chapter, these ports can also function as standard hardware Ethernet switches without utilizing TSN features.

5. Software setup

5.1. How to get software

The X-LINUX-TSNSWCH expansion package is only available as a Distribution package.
By following the procedure described in the next sections, you can regenerate the complete distribution by enabling the X-LINUX-TSNSWCH expansion package.

As presented in Software prerequisites, it is assumed that you have already installed the STM32MPU Distribution Package.

5.1.1. Install the X-LINUX-TSNSWCH distribution package

• 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.
  

(Example of the 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

bitbake st-image-weston

Information

Note that building the image might take a significant amount of time, depending on the performance of the host computer.

5.2. How to populate the flash memory with the image

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

Expand

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 program the STM32MPU boards with the built image. It is assumed that this tool has been installed through the Starter Package associated with your board.

Depending on the board, several flash memory 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:

• Boot switches on the STM32MP135x-DK Discovery kit
• Boot switches on the STM32MP157x-DK Discovery kit
• Boot switches on the STM32MP157x-EV1 Evaluation board
• Boot switches on the STM32MP257x-EV1 Evaluation board

5.3. How to run the X-LINUX-TSNSWCH package software

See How to configure Ethernet switch and How to configure TSN switch.

5.4. How to trace and debug

See How to configure Ethernet switch and How to configure TSN switch.

6. How to run use case

This part will be completed later.

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

Linux^® is a registered trademark of Linus Torvalds.

Time-Sensitive Networking

Open source software

Board support package

Microprocessor unit

Advanced Linux sound architecture

Doubledata rate (memory domain)

Physical layer protocol

Graphics processing units

Firmware image package is a packaging format used by TF-A

Trusted firmware for Arm^® Cortex^®-A

Das U-Boot -- the universal boot loader (see U-Boot)

Cortex^®

Open graphics library (see http://www.opengl.org/ for more details)

Open vector graphics (see http://www.khronos.org/openvg/ for more details)

Khronos native platform graphics interface (See http://www.khronos.org/egl/ for more details)

Precision Time Protocol

Flash memory shortened to gain space in titles, tables and block diagrams

Open portable trusted execution environment

Former spelling for e•MMC ('e' in italic)

Linux^® is a registered trademark of Linus Torvalds.

Time-Sensitive Networking

Open source software

Board support package

Microprocessor unit

Advanced Linux sound architecture

Doubledata rate (memory domain)

Physical layer protocol

Graphics processing units

Firmware image package is a packaging format used by TF-A

Trusted firmware for Arm^® Cortex^®-A

Das U-Boot -- the universal boot loader (see U-Boot)

Cortex^®

Open graphics library (see http://www.opengl.org/ for more details)

Open vector graphics (see http://www.khronos.org/openvg/ for more details)

Khronos native platform graphics interface (See http://www.khronos.org/egl/ for more details)

Precision Time Protocol

Flash memory shortened to gain space in titles, tables and block diagrams

Open portable trusted execution environment

Former spelling for e•MMC ('e' in italic)

Arm^® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

Flash memories combine high density and cost effectiveness of EPROMs with the electrical erasability of EEPROMs. For this reason, the Flash memory market is one of the most exciting areas of the semiconductor industry today and new applications requiring in system reprogramming, such as cellular telephones, automotive engine management systems, hard disk drives, PC BIOS software for Plug & Play, digital TV, set top boxes, fax and other modems, PC cards and multimedia CD-ROMs, offer the prospect of very high volume demand.

Multimedia card