IOTG TSN Reference Software for Linux

Overview

This project is a set of C-applications and scripts used to showcase different Ethernet-TSN features in Linux on specific Intel IOTG platform/software.

These serve as a practical example for those interested in developing TSN-capable software.

This project introduces three applications, each with their own set of examples:

TSQ - Time Synchronization Quality Measurement
- tsq1 showcases the nanosecond-precision time synchronization between platforms using pulse-per-second (PPS) output & auxiliary timestamping (AUX_TS) input pins.
TXRX-TSN - AF_PACKET & AF_XDP socket-based application
- vs1 showcases the bounded low-latency transmission/reception achievable via AF_PACKET & AF_XDP standard linux socket interfaces, while leveraging various device-specific Ethernet-TSN features.
OPCUA-SERVER - AF_PACKET & AF_XDP OPCUA-based application
- opcua-pkt1 showcases the bounded low-latency transmission/reception achievable via AF_PACKET over libopen62541 (an OPC-UA-based library) APIs, while leveraging various device-specific Ethernet-TSN features over a single-ethernet connection. This application uses JSON files as an input.
- opcua-pkt2 & opcua-xdp2 showcases the bounded low-latency transmission/reception achievable via AF_PACKET & AF_XDP over libopen62541 (an OPC-UA-based library) APIs, while leveraging various device-specific Ethernet-TSN features over two ethernet connection. This application uses JSON files as an input and require platforms with at least 2 Ethernet-TSN ports (e.g. EHL).
- opcua-pkt3 & opcua-xdp3 is the same as opcua-*2 but with iperf3 background traffic.

Compatibility

Currently supported hardwares are:

	* Intel Atom XXX - (formerly Elkhart Lake) with its integrated Ethernet controller
	* Intel Core XXX - (formerly Tiger Lake UP3) with its integrated Ethernet controller

Currently supported systems are:

	* Yocto
	* Ubuntu

Important

# Execute all the scripts in "root user"/"super user" privilege mode.
# There are two method to execute all the scripts in "root user"/"super user" privilege mode.

Method 1:
# Enter into "root user"/"super user" privilege mode using command below:
	sudo su

Method 2:
# Execute all the scripts using command below:
	sudo ./<script_name>.sh

Dependencies

General

For system clock:

# Please ensure the system clock is set to current date before using the installer script to install the required dependencies.
# Otherwise the installation will failed.
# Set the system clock to current date using command below:
	date -s YY/MM/DD

For system shell:

# Bash are required as system shell in order to compile and run TSN Reference Software.
# Install bash using command below:
	sudo apt-get install bash

Packages Installer:

# All the TSN Ref Sw App required dependencies can be install by using the packages installer below:

IMPORTANCE: Please read and follow the instruction below before using the packages installer!

# In order to ease the installation of generic packages and IOTG customized helper libraries (libbpf-iotg and sopen62541-iotg) needed,
# we have provide a installation script.
# The script will check out a specific version of the libraries from upstream git and apply our patches on top of it.

# Suggestion is to use the installer script (after having kept the original libbpf and libopen62541 in a safe place).
# This will ensure the tsn ref sw will be able to find/use correct libraries.

NOTE: If your kernel support for Intel XDP+TBS, please ensure the '__u64 txtime' descriptor is available in struct xdp_desc() in /usr/include/linux/if_xdp.h as example below:

/* Rx/Tx descriptor */
struct xdp_desc {
        __u64 addr;
        __u32 len;
        __u32 options;
        __u64 txtime;
};

WARNING: You are able to install libbpf & open62541 without the 'txtime' descriptor but you might facing error/failure during the tests.

# The packages installer branch : https://github.com/intel/iotg_tsn_ref_sw
# Branch name : **master**
# Use the commands below to install the packages:

	cd dependencies
	./packages_installer.sh --proxy=<your.proxy.if.necessary.com> --git-proxy=<your.git.proxy.if.necessary.com>

# NOTE: The proxy and git-proxy are optional arguments, provide if necessary.
# NOTE: The packages installer only support the overwrite installation.
# NOTE: Refer to the below

# NOTE: If you are installing the libbpf and libopen62541-iotg manually, there is a chance the related open62541-iotg.pc file is not there.
# Hence, you might have to comment out this line in **configure.ac**.

**AM_CONDITIONAL([WITH_OPCUA], [test "x$no_open62541_iotg_fork" = "x0"] && test "x${HAVE_XDP}" = "xyes")**

# Disclaimer
	* The packages installers only serves to install dependencies for TSN Ref Sw App.
	* This project is not for intended for production use.
	* This project is intended to be used with specific platforms and bsp, other HW/SW combinations YMMV
	* Users are responsible for their own products' functionality and performance.

# FAQ

	If git clone fail, try the solution below:
	* Please configure the proxy according to your proxy setting before git clone
	* Please configure the system date up-to-date before git clone
	* Please reboot your system before git clone

Yocto

For compilation:

# If you are running from a compatible Intel-provided Yocto BSP & hardware, these
# software dependencies would have already been installed.

	* [Custom linux kernel headers](https://github.com/intel/linux-intel-lts/tree/5.*/preempt-rt)
  	- Include support for Intel XDP+TBS implementation
	* [Custom linux-libc-headers](https://github.com/intel/iotg-yocto-ese-bsp/tree/master/recipes-kernel/linux-libc-headers/linux-libc-headers)
  	- Include support for Intel XDP+TBS implementation
	* [Custom libopen62541-iotg](https://github.com/intel/iotg-yocto-ese-main/tree/master/recipes-connectivity/open62541)
  	- Include support for kernel implementation of Intel XDP+TBS (if_xdp.h change required)
	* [Custom libbpf](https://github.com/intel/iotg-yocto-ese-main/tree/master/recipes-connectivity/libbpf)
  	- Include support for kernel implementation of Intel XDP+TBS (if_xdp.h change required)
	* libelf
	* libjson-c

For run-time:

	* [Custom linux kernel](https://github.com/intel/linux-intel-lts/tree/5.*/preempt-rt)
	* shell tools including awk/sed
	* iproute2-ss200127
	* linuxptp [v3.0](https://github.com/richardcochran/linuxptp/releases/tag/v3.0)
	* Python 3.8.2
	* gnuplot 5.2
	* IceWM - Any GUI/window manager can be used, required to display graphs.

IceWM:

# If you're using a compatible intel-developed Yocto BSP, IceWM is its default
# window manager. Here are some keyboard shortcuts, in case a mouse is not available.

# Notation: C is control, M is meta/alt, S is shift, s is super

1. `<C-M-t>` to open xterm
2. `<M-f8>` to resize window (using arrow keys)
3. `<M-S-f10>` to maximise vertical space
4. `<M-f7>` to move window
5. `<C-M-leftarrow>` to move to the left, `rightarrow` for right
6. `<C-M-esc>` to show window list
7. `<M-space>` to show window actions menu

Ubuntu

Ubuntu based dependencies:

# In order to compile under Ubuntu, these packages need to be installed first (using sudo apt-get install ....) :
	* autoconf
	* build-essential
	* cmake
	* gawk
	* gcc
	* gnuplot
	* pkg-config
	* zlib1g
	* zlib1g-dev
	* libelf-dev
	* libjson-c-dev
	* xterm
	* iperf3
	* linuxptp

NOTE: ensure your proxy settings are correct.
NOTE: All the packages can be install by using the packages_installer.sh above.

For run-time:

	* [Real-Time Ubuntu 22.04](https://ubuntu.com/real-time)
	* iproute2 v5.15.0 [with real-time patches](https://github.com/intel/iotg-yocto-ese-main/tree/master/recipes-connectivity/iproute2/iproute2)
	* [ethtool](https://salsa.debian.org/kernel-team/ethtool) [with real-time patches](https://github.com/intel/iotg-yocto-ese-main/tree/master/recipes-extended/ethtool/ethtool)
	* linuxptp [v3.0 or later](https://github.com/richardcochran/linuxptp/releases/tag/v3.0)
	* Python 3.8.2

Build

# To build tsn ref sw, we are currently providing a single script that will build all
# binaries (tsq, txrx-tsn and opcua-server).

    ```
    cd <tsn_ref_sw_directory>
    ./build.sh
    ```

# To explicitly disable Intel specific XDP+TBS support in tsn ref sw

    ```
    cd <tsn_ref_sw_directory>
    ./build.sh -t
    ```

For further configuration details, check out README_config.md and ShellConfig

Run

For the details on how to run tsn ref sw, please refer to Shell-based runner and JSON-based runner

This project is optimized to run on the supported hardware list and their respective bundled softwares (IFWI, BSP, preempt-rt kernel) which has been optimized for each platform's capabilities.

For details information please refer to the documentation below:

Documentation

Disclaimer

This project only serves to demonstrate TSN functionality and its usage on supported platforms and their environments.
This project is not for intended for production use.
This project is intended to be used with specific platforms and bsp, other HW/SW combinations YMMV
Users are responsible for their own products' functionality and performance.

Report Issues

If you see an issue, include these details in your issue submission:

Hardware setup (Platform, Ethernet controller/NIC)
Dependency version
OS or Linux distribution
Linux kernel version
Problem statement
Steps to reproduce
Images/Screenshots

Contribute

Refer to CONTRIBUTING.md

License

Refer to LICENSE.md

FAQ

For tips on how to run tsn ref sw, please refer to README_faq.md It contains example of certain frequently seen run-time error.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

IOTG TSN Reference Software for Linux

Overview

Compatibility

Important

Dependencies

General

For system clock:

For system shell:

Packages Installer:

Yocto

For compilation:

For run-time:

IceWM:

Ubuntu

Ubuntu based dependencies:

For run-time:

Build

Run

Documentation

Contents

Disclaimer

Report Issues

Contribute

License

FAQ

Files

README.md

Latest commit

History

README.md

File metadata and controls

IOTG TSN Reference Software for Linux

Overview

Compatibility

Important

Dependencies

General

For system clock:

For system shell:

Packages Installer:

Yocto

For compilation:

For run-time:

IceWM:

Ubuntu

Ubuntu based dependencies:

For run-time:

Build

Run

Documentation

Contents

Disclaimer

Report Issues

Contribute

License

FAQ