script: Update README.md and rename dependencies installer

Changes: 1. Update README.md to have clearer information 2. Merge and remove DEPENDENCIES.md and dependencies/README.md 3. Move two installer to deprecated 4. Rename install_dependencies.sh to libbpf_open62541_installer.sh Signed-off-by: Goh Wei Sheng <[email protected]>
intel · Dec 27, 2022 · 900b2bc · 900b2bc
1 parent 251090d
commit 900b2bc
Show file tree

Hide file tree

Showing 7 changed files with 183 additions and 162 deletions.
diff --git a/DEPENDENCIES.md b/DEPENDENCIES.md
diff --git 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 ./<script_name>.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. `<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
+	* 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 <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](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
diff --git a/dependencies/install_libbpf_overwrite.sh → ...es/deprecated/install_libbpf_overwrite.sh b/dependencies/install_libbpf_overwrite.sh → ...es/deprecated/install_libbpf_overwrite.sh
diff --git a/dependencies/install_open62541_overwrite.sh → ...deprecated/install_open62541_overwrite.sh b/dependencies/install_open62541_overwrite.sh → ...deprecated/install_open62541_overwrite.sh