diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md deleted file mode 100644 index 5990557..0000000 --- a/DEPENDENCIES.md +++ /dev/null @@ -1,86 +0,0 @@ -# Software Dependencies - -If you are running from a compatible Intel-provided Yocto BSP & hardware, these -software dependencies would have already been installed. - -For compilation: -* [Custom linux kernel headers](https://github.com/intel/linux-intel-lts/tree/5.4/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 - -**NOTE** -Customized libbpf and libopen62541-iotg is a hard dependencies as per now (sorry). WIP to decouple tsn ref sw from the customized dependencies. -See below on how to install the customized libbpf and libopen62541-iotg. - -For run-time: -* [Custom linux kernel](https://github.com/intel/linux-intel-lts/tree/5.4/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. - -## Ubuntu based dependencies -In order to compile under Ubuntu, these packages need to be installed first: -* gcc -* autoconf -* libjson-c-dev -* gawk -* build-essential - -## Dependencies installer script -In order to ease the installation of the customized helper libraries needed, we have included a few installation scripts in a specific branch. -These scripts will check out a specific version of the libraries from upstream git and apply our patches on top of it. - -Branch name : **master** -Folder name : **depedencies** -The dependencies installer branch : https://github.com/intel/iotg_tsn_ref_sw - -Refer to the README.md to understand the differences between the scripts provided: - -https://github.com/intel/iotg_tsn_ref_sw/blob/master/dependencies/README.md - -Suggestion is to use the overwriting 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 variable 'txtime' 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; -}; - -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")** - - -# Hardware dependencies - -* Refer to compatible platform list. - -### 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. `` to open xterm -2. `` to resize window (using arrow keys) -3. `` to maximise vertical space -4. `` to move window -5. `` to move to the left, `rightarrow` for right -6. `` to show window list -7. `` to show window actions menu diff --git a/README.md b/README.md index bcdc1cb..74578a9 100644 --- a/README.md +++ b/README.md @@ -35,32 +35,185 @@ This project introduces **three applications**, each with their own set of _exam 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_ - -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. - -### Dependencies - -List of dependencies in [DEPENDENCIES.md](DEPENDENCIES.md) + * 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 ./.sh +``` + +## Dependencies + +### General + +#### *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 +``` + +### 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. `` to open xterm +2. `` to resize window (using arrow keys) +3. `` to maximise vertical space +4. `` to move window +5. `` to move to the left, `rightarrow` for right +6. `` to show window list +7. `` 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 + * gawk + * gcc + * gnuplot + * libelf-dev + * libjson-c-dev + * xterm + +NOTE: ensure your proxy settings are correct. +``` + +### IOTG Custom Libbpf & Open62541 + +#### *Installation script:* +``` +# In order to ease the installation of the customized helper libraries needed, we have provide a installation scripts to install libbpf and open62541. +# The scripts 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 overwriting 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 dependencies installer branch : https://github.com/intel/iotg_tsn_ref_sw +# Branch name : **master** +# Use the commands below to install the dependencies: + + cd dependencies + ./libbpf_open62541_installer.sh --overwrite + +# Currently the dependencies installer only support the overwrite installation. +# WIP to enhance the installer in a better way. +# 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 dependencies installers only serves to install dependencies for libbpf and open62541 + * This project is not for intended for production use. + * This project is intended to be used with specific platforms and bsp, other + hardware/software 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 +``` ## Build +``` +# To build tsn ref sw, we are currently providing a single script that will build all +# binaries (tsq, txrx-tsn and opcua-server). -To build tsn ref sw, we are currently providing a single script that will build all -binaries (tsq, txrx-tsn and opcua-server). - - ```sh + ``` cd ./build.sh ``` +# To explicitly disable Intel specific XDP+TBS support in tsn ref sw + + ``` + cd + ./build.sh -t + ``` +``` For further configuration details, check out [README_config.md](README_config.md) and [ShellConfig](README_shell.md#Config) +## Run +* For the details on how to run tsn ref sw, please refer to [Shell-based runner](README_shell.md) and [JSON-based runner](README_json.md) +--- + +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 ### Contents @@ -72,7 +225,6 @@ For further configuration details, check out [README_config.md](README_config.md * [Optimization](README_project.md#optimization) * [Role of run.sh](README_project.md#role-of-runsh) * [Installation](README_install.md) -* [Tsn Ref Sw Dependencies](DEPENDENCIES.md) * [File Structure & Conventions](README_project.md#file-structure-conventions) * [Configuration](README_config.md) * [Shell-based runner](README_shell.md) @@ -92,7 +244,8 @@ For further configuration details, check out [README_config.md](README_config.md * [Usage: 2-port](README_json.md#usage-2-port) * [FAQ](README_faq.md) -### Disclaimer + +## Disclaimer * This project only serves to demonstrate TSN functionality and its usage on supported platforms and their environments. @@ -109,7 +262,7 @@ For further configuration details, check out [README_config.md](README_config.md If you see an issue, include these details in your issue submission: * Hardware setup (Platform, Ethernet controller/NIC) -* Dependency version, refer to [DEPENDENCIES.md](DEPENDENCIES.md) +* Dependency version * OS or Linux distribution * Linux kernel version * Problem statement diff --git a/dependencies/README.md b/dependencies/README.md deleted file mode 100644 index 65ec06e..0000000 --- a/dependencies/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# IOTG TSN Reference Software Dependencies Installer for Linux and Ubuntu - -## Overview - -The dependencies installers are to install dependencies for libbpf and open62541. - -There are **three installer**, each with their own set of _examples_: - -* **install_dependencies.sh** - Install dependencies for libbpf and libopen62541 - * ./install_dependencies.sh - Install dependencies in custom directory. - * ./install_dependencies.sh --overwrite - Overwrite the original dependencies. - -* **install_libbpf_overwrite.sh** - Only install dependency for libbpf - * ./install_libbpf_overwrite.sh - Overwrite the original libbpf/ - -* **install_open62541_overwrite.sh** - Only install dependency for open62541 - * ./install_open62541_overwrite.sh - Overwrite the original open62541 - -## Compatibility - -Currently supported systems are: - -* Linux -* Ubuntu - -### Disclaimer - -* The dependencies installers only serves to install dependencies for libbpf and open62541 - -* This project is not for intended for production use. - -* This project is intended to be used with specific platforms and bsp, other - hardware/software 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 - diff --git a/dependencies/install_libbpf_overwrite.sh b/dependencies/deprecated/install_libbpf_overwrite.sh similarity index 100% rename from dependencies/install_libbpf_overwrite.sh rename to dependencies/deprecated/install_libbpf_overwrite.sh diff --git a/dependencies/install_open62541_overwrite.sh b/dependencies/deprecated/install_open62541_overwrite.sh similarity index 100% rename from dependencies/install_open62541_overwrite.sh rename to dependencies/deprecated/install_open62541_overwrite.sh diff --git a/dependencies/helpers.sh b/dependencies/helpers.sh index 6e845a8..893af99 100644 --- a/dependencies/helpers.sh +++ b/dependencies/helpers.sh @@ -40,7 +40,7 @@ LOCAL_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) check_distro(){ # Check OS distro - echo -e "\nINSTALL-DEPENDENCIES.SH: Checking OS Distro" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Checking OS Distro" os_distro=$(cat /etc/os-release | grep -w NAME | cut -c 6-) echo "OS Distro: $os_distro" } @@ -48,7 +48,7 @@ check_distro(){ config_proxy(){ # Configure proxy - echo -e "\nINSTALL-DEPENDENCIES.SH: Configuring proxy" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Configuring proxy" echo -e export https_proxy=http://proxy.png.intel.com:911 echo -e git config --global https.proxy http://proxy.jf.intel.com:911 export https_proxy=http://proxy.png.intel.com:911 @@ -58,7 +58,7 @@ config_proxy(){ check_xdp_tbs(){ # Check whether the kernel support XDP_TBS - echo -e "\nINSTALL-DEPENDENCIES.SH: Checking XDP+TBS Availability" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Checking XDP+TBS Availability" if [[ -f /usr/include/linux/if_xdp.h ]]; then txtime=$(cat /usr/include/linux/if_xdp.h | grep -i txtime > /dev/null && echo yes || echo no) @@ -98,18 +98,18 @@ clone_libbpf(){ # Git clone libbpf echo -e "\n=============================================" - echo -e "INSTALL-DEPENDENCIES.SH: Installing libbpf" + echo -e "LIBBPF_OPEN62541_INSTALLER.SH: Installing libbpf" echo -e "=============================================" cd libbpf rm -rf libbpf git clone https://github.com/libbpf/libbpf.git cd libbpf - echo -e "\nINSTALL-DEPENDENCIES.SH: Switching branch" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Switching branch" git checkout d1fd50d475779f64805fdc28f912547b9e3dee8a if [[ "$xdp_supported" == "yes" && "$txtime" == "yes" ]]; then - echo -e "\nINSTALL-DEPENDENCIES.SH: Applying patches to libbpf" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Applying patches to libbpf" EMAIL=root@localhost git am ../patches/*.patch fi } @@ -118,7 +118,7 @@ clone_open62541(){ # Git clone libopen62541 echo -e "\n=============================================" - echo -e "INSTALL-DEPENDENCIES.SH: Installing open62541" + echo -e "LIBBPF_OPEN62541_INSTALLER.SH: Installing open62541" echo -e "=============================================" cd $LOCAL_DIR cd open62541 @@ -126,15 +126,15 @@ clone_open62541(){ git clone https://github.com/open62541/open62541.git cd open62541 - echo -e "\nINSTALL-DEPENDENCIES.SH: Switching branch" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Switching branch" git checkout a77b20ff940115266200d31d30d3290d6f2d57bd # Apply patches for open62541 if [[ "$xdp_supported" == "yes" && "$txtime" == "yes" ]]; then - echo -e "\nINSTALL-DEPENDENCIES.SH: Applying patches with XDP_TBS to open62541" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Applying patches with XDP_TBS to open62541" EMAIL=root@localhost git am ../patches/patches_w_xdp_tbs/*.patch else - echo -e "\nINSTALL-DEPENDENCIES.SH: Applying patches without XDP_TBS to open62541" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Applying patches without XDP_TBS to open62541" EMAIL=root@localhost git am ../patches/patches_wo_xdp_tbs/*.patch fi } @@ -142,7 +142,7 @@ clone_open62541(){ compile_open62541(){ # Compile open62541 - echo -e "\nINSTALL-DEPENDENCIES.SH: Compiling open62541" + echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Compiling open62541" mkdir build cd build diff --git a/dependencies/install_dependencies.sh b/dependencies/libbpf_open62541_installer.sh similarity index 99% rename from dependencies/install_dependencies.sh rename to dependencies/libbpf_open62541_installer.sh index 3aabe72..f64eeea 100755 --- a/dependencies/install_dependencies.sh +++ b/dependencies/libbpf_open62541_installer.sh @@ -65,7 +65,7 @@ else sed -i 's/Cflags: -I${includedir}/Cflags: -I${includedir}\/bpf-iotg-custom/g' src/libbpf.pc.template fi -echo -e "\nINSTALL-DEPENDENCIES.SH: Compiling libbpf" +echo -e "\nLIBBPF_OPEN62541_INSTALLER.SH: Compiling libbpf" NO_PKG_CONFIG=1 make -j$(nproc) -C src DESTDIR=/ make install -j$(nproc) -C src ldconfig