CI/DOC: more detailed documentation on how CI works

Signed-off-by: Raphael Defosseux <raphael.defosseux@eurecom.fr>

ci-scripts/doc/ci_dev_home.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="../../doc/images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OAI CI Dev documentation</font></b>
+    </td>
+  </tr>
+</table>
+
+VM-based RF-Less Environment:
+
+*  [How to setup your test env](vm_based_simulator_env)
+*  [How to deal with OAI source files](vm_based_simulator_sources)
+*  [The main script](vm_based_simulator_main_scripts)
+*  [How to create one or several VM instances](vm_based_simulator_create)
+*  [How to build an OAI variant](vm_based_simulator_build)
+*  [How the build is checked](vm_based_simulator_check_build)
+*  [How to test an OAI variant](vm_based_simulator_test)
+*  [How to destroy all VM instances](vm_based_simulator_destroy)
+
+Currently missing documentation:
+*  How to generate a build report
+*  How to generate a test report
+
+---
+

ci-scripts/doc/vm_based_simulator_check_build.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="../../doc/images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OAI CI Virtual-Machine-based: checking the build result</font></b>
+    </td>
+  </tr>
+</table>
+
+## Table of Contents ##
+
+1.  [Introduction](#1-introduction)
+2.  [Detailed Description](#2-detailed-description)
+
+# 1. Introduction #
+
+Function is called:
+
+- when building in foreground
+- when waiting for the background build process is finished
+
+# 2. Detailed Description #
+
+Source file concerned: `ci-scripts/waitBuildOnVM.sh`
+
+## 2.1. check_on_vm_build function ##
+
+*  Retrieve the build log files from the VM instance `ubuntu@$VM_IP_ADDR:/home/ubuntu/tmp/cmake_targets/log/*.txt`
+*  and copy them locally in the workspace at $ARCHIVES_LOC
+*  List all log files that match the pattern. Each should have
+   *  the `Built target` pattern (the library/executable SHALL link)
+*  The number of patterned log files SHALL match $NB_PATTERN_FILES defined in `ci-scripts/oai-ci-vm-tool` script for the variant
+
+---
+
+Next step: [how to test a function](vm_based_simulator_test)
+
+You can also go back to the [CI dev main page](./ci_dev_home)
+

ci-scripts/doc/vm_based_simulator_create.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="../../doc/images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OAI CI Virtual-Machine-based: create a VM instance</font></b>
+    </td>
+  </tr>
+</table>
+
+## Table of Contents ##
+
+1.  [Introduction](#1-introduction)
+2.  [Detailed Description](#2-detailed-description)
+3.  [Typical Usage](#3-typical-usage)
+
+# 1. Introduction #
+
+```bash
+$ cd /tmp/CI-raphael
+$ ./ci-scripts/oai-ci-vm-tool create --help
+OAI CI VM script
+   Original Author: Raphael Defosseux
+   Requirements:
+     -- uvtool uvtool-libvirt apt-cacher
+     -- xenial image already synced
+   Default:
+     -- eNB with USRP
+
+Usage:
+------
+    oai-ci-vm-tool create [OPTIONS]
+
+Mandatory Options:
+--------
+    --job-name #### OR -jn ####
+    Specify the name of the Jenkins job.
+
+    --build-id #### OR -id ####
+    Specify the build ID of the Jenkins job.
+
+ # OpenAirInterface Build Variants
+    --variant enb-usrp     OR -v1
+    --variant basic-sim    OR -v2
+    --variant phy-sim      OR -v3
+    --variant cppcheck     OR -v4
+    --variant enb-ethernet OR -v7
+    --variant ue-ethernet  OR -v8
+ # non-OSA Build Variants
+    --variant flexran-rtc  OR -v10
+ # OpenAirInterface Test Variants
+    --variant l1-sim       OR -v20
+    --variant rf-sim       OR -v21
+    --variant l2-sim       OR -v22
+    Specify the variant to build.
+
+    --help OR -h
+    Print this help message.
+```
+
+# 2. Detailed Description #
+
+Source file concerned: `ci-scripts/createVM.sh`
+
+## 2.1. create_vm function ##
+
+This is the function that is being called from the main oai-vm-tool script.
+
+The main purpose is to start a VM instance:
+
+```bash
+uvt-kvm create $VM_NAME release=xenial --memory $VM_MEMORY --cpu $VM_CPU --unsafe-caching --template ci-scripts/template-host.xml
+```
+
+Variables are set in the main script based on the options.
+
+`--unsafe-caching` option is used because our VM instances are throw-away's. 
+
+`--template ci-scripts/template-host.xml` is used to duplicate the CPU properties to the VM instance. **VERY IMPORTANT to build OAI**
+
+## 2.2. Lock / Unlock functions ##
+
+There are `acquire_vm_create_lock` and `release_vm_create_lock` functions.
+
+Creating Virtual Machines instances in parallel **creates a lot of stress** on the host server HW. If you launch creations in parallel (Jenkins pipeline could do it) or you are several people working on the same host server, this mechanism atomizes the creation process and wait until the previous VM creation is finished.
+
+# 3. Typical Usage #
+
+```bash
+$ cd /tmp/CI-raphael
+$ ./ci-scripts/oai-ci-vm-tool create --job-name raphael --build-id 1 --variant phy-sim
+# or a more **unique approach**
+$ ./ci-scripts/oai-ci-vm-tool create -jn toto -id 1 -v2
+```
+
+The Jenkins pipeline uses the master job name as `job-name` option and the job-build ID.
+
+Try to be unique if you are several developers working on the same host server.
+
+Finally, typically I never use the `create` command. I use directly the build command that checks if VM is created and if not, will create it. See next step.
+
+---
+
+Next step: [how to build an OAI variant](vm_based_simulator_build)
+
+You can also go back to the [CI dev main page](./ci_dev_home)
+

ci-scripts/doc/vm_based_simulator_destroy.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="../../doc/images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OAI CI Virtual-Machine-based: Properly Destroy all VM instances</font></b>
+    </td>
+  </tr>
+</table>
+
+## Table of Contents ##
+
+1.  [Introduction](#1-introduction)
+2.  [Detailed Description](#2-detailed-description)
+3.  [Typical Usage](#3-typical-usage)
+
+# 1. Introduction #
+
+```bash
+$ cd /tmp/CI-raphael
+$ ./ci-scripts/oai-ci-vm-tool destroy --help
+OAI CI VM script
+   Original Author: Raphael Defosseux
+   Requirements:
+     -- uvtool uvtool-libvirt apt-cacher
+
+Usage:
+------
+    oai-ci-vm-tool destroy [OPTIONS]
+
+Mandatory Options:
+--------
+    --job-name #### OR -jn ####
+    Specify the name of the Jenkins job.
+
+    --build-id #### OR -id ####
+    Specify the build ID of the Jenkins job.
+
+Options:
+--------
+    --help OR -h
+    Print this help message.
+```
+
+# 2. Detailed Description #
+
+Source file concerned: `ci-scripts/destroyAllRunningVM.sh`
+
+## 2.1. destroy_vm function ##
+
+This is the function that is being called from the main oai-vm-tool script.
+
+The main purpose is to destroy all VM instances whose name matches a pattern.
+
+It also cleans up the `.ssh/known_hosts` file.
+
+# 3. Typical Usage #
+
+```bash
+$ cd /tmp/CI-raphael
+$ ./ci-scripts/oai-ci-vm-tool destroy --job-name raphael --build-id 1
+```
+
+---
+
+You can go back to the [CI dev main page](./ci_dev_home)
+

ci-scripts/doc/vm_based_simulator_env.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="../../doc/images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OAI CI Virtual-Machine-based Simulator Test Environment</font></b>
+    </td>
+  </tr>
+</table>
+
+## Table of Contents ##
+
+1.  [Introduction](#1-introduction)
+2.  [Prerequisites](#2-prerequisites)
+    1.  [uvtool installation](#21-uvtool-installation)
+    2.  [apt-cacher-server installation](#22-apt-cacher-server-installation)
+
+# 1. Introduction #
+
+This document explains how the master pipeline works and how any developer could contribute to add testing.
+
+It is an extension to the wiki [page](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/ci/enb-master-job).
+
+The purpose of this master pipeline is to:
+
+*  Validate that a Merge Request is mergeable
+*  Validate that a Merge Request is following coding guidelines
+*  Validate that a Merge Request is not breaking any typical build variant
+*  Validate that a Merge Request is not breaking any legacy simulator-based test
+
+We will mainly focused on the 2 last items.
+
+Last point, this documentation is valid for all CI-supported branches:
+
+*  `master`
+*  `develop`
+*  `develop-nr`
+
+But the feature set may not be aligned. **The principles still apply.**
+
+# 2. Prerequisites #
+
+Some details are available on this wiki [section](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/ci/enb-ci-architecture#22-pipeline-executor).
+
+Currently we have a host server (`bellatrix`) with the current parameters:
+
+*  40 x Intel(R) Xeon(R) CPU E5-2640 v4 @ 2.40GHz
+*  64 Gbytes RAM
+*  Ubuntu 16.04.3 LTS (xenial)
+
+For you to replicate this environment, you need a strong server:
+
+*  At least 16 cores
+*  Ubuntu 16 (xenial) or higher (such as bionic, not tested)
+
+Also we are using a Virtual Machine (VM for the rest of document) based strategy for the moment.
+
+So you need to install 2 tools:
+
+*  uvt-kvm
+*  apt-cacher
+
+We are planning to also add:
+
+*  A Red Hat Linux Entreprise 7.6 host environment
+*  A Container-based strategy (such as Docket and Kubernetes)
+
+## 2.1. uvtool installation ##
+
+```bash
+$ sudo apt-get install uvtool
+# if you don't have already, create an ssh key
+$ ssh-keygen -b 2048
+# retrieve an image
+$ sudo uvt-simplestreams-libvirt sync arch=amd64 release=xenial
+# we might soon switch to an Ubuntu 18.04 version
+$ sudo uvt-simplestreams-libvirt sync arch=amd64 release=bionic
+$ uvt-simplestreams-libvirt query
+release=bionic arch=amd64 label=release (20190402)
+release=xenial arch=amd64 label=release (20190406)
+```
+
+On our server, I don't update (sync) that often (every 2-4 months).
+
+For more details:
+
+*  uvtool syntax is [here](http://manpages.ubuntu.com/manpages/trusty/man1/uvt-kvm.1.html)
+*  more readable tutorial is [here](https://help.ubuntu.com/lts/serverguide/cloud-images-and-uvtool.html)
+
+## 2.2. apt-cacher-server installation ##
+
+I recommend to follow to the letter this [tutorial](https://help.ubuntu.com/community/Apt-Cacher-Server).
+
+The reason: we are creating/using/destroying a lot of VM instances and we are always installing the same packages.
+This service allows to cache on the host and, doing so, **decreases the pressure on your internet bandwith usage**.
+It also optimizes time at build stage.
+
+```bash
+$ sudo apt-get install apt-cacher apache2
+$ sudo vi /etc/default/apt-cache
+$ sudo service apache2 restart
+
+# Server configuration
+$ sudo vi /etc/apt-cacher/apt-cacher.conf 
+ --> allowed_hosts = *
+ --> fix the installer_files_regexp
+$ sudo vi /etc/apt/apt.conf.d/01proxy
+--> add `Acquire::http::Proxy "http://<IP address or hostname of the apt-cacher server>:3142";`
+$ sudo service apt-cacher restart
+```
+
+This last file (/etc/apt/apt.conf.d/01proxy) is very important since it is tested in any CI script.
+
+---
+
+We can now switch to the next step: [how to deal with oai sources](./vm_based_simulator_sources)
+
+You can also go back to the [CI dev main page](./ci_dev_home)
+

ci-scripts/doc/vm_based_simulator_main_scripts.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="../../doc/images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OAI CI Virtual-Machine-based Main Script</font></b>
+    </td>
+  </tr>
+</table>
+
+## Table of Contents ##
+
+1.  [Introduction](#1-introduction)
+2.  [Sub BASH scripts](#2-sub-bash-scripts)
+3.  [Main script features](#3-main-script-features)
+
+# 1. Introduction #
+
+The file name is `./ci-scripts/oai-ci-vm-tool` from the workspace root.
+
+```bash
+$ cd /tmp/CI-raphael
+$ ./ci-scripts/oai-ci-vm-tool --help
+OAI CI VM script
+   Original Author: Raphael Defosseux
+   Requirements:
+     -- uvtool uvtool-libvirt apt-cacher
+     -- xenial image already synced
+
+Usage:
+------
+    oai-ci-vm-tool (-h|--help) {create,destroy,build,wait,test,report-build,report-test} ...
+
+```
+
+This is a **BASH** script.
+
+
+# 2. Sub BASH scripts #
+
+The main script is including a bunch of sub BASH scripts.
+
+*  ci-scripts/createVM.sh
+*  ci-scripts/buildOnVM.sh
+*  ci-scripts/waitBuildOnVM.sh
+*  ci-scripts/destroyAllRunningVM.sh
+*  ci-scripts/runTestOnVM.sh
+*  ci-scripts/reportBuildLocally.sh
+*  ci-scripts/reportTestLocally.sh
+
+**NOTE: ci-scripts/runTestOnVM.sh is getting big and will certainly be split to facilate maintenance. Start functions will be also factorized.**
+
+# 3. Main script features #
+
+The main purpose of the main script is decipher the options and launch the requested function.
+
+It is also **testing if uvtool and apt-cacher are installed.**
+
+It finally provides parameters to the requested functions. Parameter definition is centralized there.
+
+For example: 
+
+for VM instance creation:
+
+*  the instance name:  VM_NAME
+*  the RAM and number of CPUs: VM_MEMORY, VM_CPU
+
+for OAI variant build:
+
+*  build options: BUILD_OPTIONS
+*  build log file to parse: LOG_PATTERN
+*  the number of log files to parse: NB_PATTERN_FILES
+
+These last 2 variables are very important if you change the build options or if you modify the build system and add more targets to build (especially true for physical simulator).
+
+There are many more variables.
+
+---
+
+Next step: [how to create one or several VM instances](vm_based_simulator_create)
+
+You can also go back to the [CI dev main page](./ci_dev_home)
+

ci-scripts/doc/vm_based_simulator_sources.md

+<table style="border-collapse: collapse; border: none;">
+  <tr style="border-collapse: collapse; border: none;">
+    <td style="border-collapse: collapse; border: none;">
+      <a href="http://www.openairinterface.org/">
+         <img src="../../doc/images/oai_final_logo.png" alt="" border=3 height=50 width=150>
+         </img>
+      </a>
+    </td>
+    <td style="border-collapse: collapse; border: none; vertical-align: center;">
+      <b><font size = "5">OAI CI Virtual-Machine-based Simulator OAI source management</font></b>
+    </td>
+  </tr>
+</table>
+
+## Table of Contents ##
+
+1.  [Introduction](#1-introduction)
+2.  [Centralized Workspace](#2-centralized-workspace)
+3.  [Create the ZIP file](#3-create-the-zip-file)
+
+# 1. Introduction #
+
+The idea of this section is to optimize/uniform source management for several VM instances.
+
+If we were cloning the same repository in each VM we are creating, we would put so much pressure on the central GitLab repository.
+
+The solution:
+
+* clone/fetch on a given clean workspace and tar/zip only the source files without any artifacts.
+* we then copy the tar/zip file to each VM instance
+* and within each VM instance, unzip
+
+# 2. Centralized Workspace #
+
+You can create a brand new workspace by cloning:
+
+```bash
+$ mkdir /tmp/CI-raphael
+$ cd /tmp/CI-raphael
+$ git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git .
+$ git checkout develop
+```
+
+You can also use your current cloned workspace and any `develop`-based branch.
+
+```bash
+$ cd /home/raphael/openairinterface5g
+$ git fetch
+$ git checkout develop-improved-documentation
+# CAUTION: the following command will remove any file that has not already been added to GIT
+$ sudo git clean -x -d -ff
+$ git status
+On branch develop-improved-documentation
+Your branch is up-to-date with 'origin/develop-improved-documentation'.
+nothing to commit, working directory clean
+```
+
+You can also have modified files.
+
+**The main point is to have NO ARTIFACTS from a previous build in your workspace.**
+
+Last point, the workspace folder name is not necesseraly `openairinterface5g`. But all the following commands will be run for the root of the workspace.
+
+For clarity, I will always use `/tmp/CI-raphael` as $WORKSPACE.
+
+# 3. Create the ZIP file #
+
+```bash
+# go to root of workspace
+$ cd /tmp/CI-raphael
+$ zip -r -qq localZip.zip .
+```
+
+The **Jenkins Pipeline** performs automatically these operations.
+
+In addition, in case of a merge request, it tries to merge with the target branch and might create a dummy local commit.
+
+See [section](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/ci/enb-master-job#32-verify-guidelines-stage)
+
+---
+
+Next step: [the main scripts](vm_based_simulator_main_scripts)
+
+You can also go back to the [CI dev main page](./ci_dev_home)
+

doc/FEATURE_SET.md

@@ -43,22 +43,23 @@ The Physical layer implements **3GPP 36.211**, **36.212**, **36.213** and provid
 **Transmission Mode, Bandwidth** | **Expected Throughput** | **Measured Throughput** | **Measurement Conditions**
 -------------------------------- | ----------------------- | ------------------------| ----------------:
 FDD DL: 5 MHz, 25 PRBS/ MCS 28   | 16 - 17 Mbit/s          | TM1: 17.0 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
-FDD DL: 10 MHz, 50 PRBS/ MCS 28  | 34 - 35 Mbit/s          | TM1: 32.8 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
+FDD DL: 10 MHz, 50 PRBS/ MCS 28  | 34 - 35 Mbit/s          | TM1: 34.0 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
 FDD DL: 20 MHz, 100 PRBS/ MCS 28 | 70 Mbit/s               | TM1: 69.9 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
  |  |  | 
 FDD UL: 5 MHz, 25 PRBS/ MCS 20   | 9 Mbit/s                | TM1: 8.28 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
-FDD UL: 10 MHz, 50 PRBS/ MCS 20  | 17 Mbit/s               | TM1: 15.2 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
+FDD UL: 10 MHz, 50 PRBS/ MCS 20  | 17 Mbit/s               | TM1: 18.3 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
 FDD UL: 20 MHz, 100 PRBS/ MCS 20 | 35 Mbit/s               | TM1: 18.6 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
  |  | 
-TDD DL: 5 MHz, 25 PRBS/ MCS **XX**   | **TBC** Mbit/s | 3.33 Mbits/s | COTS-UE Cat 4 (150/50 Mbps)
-TDD DL: 10 MHz, 50 PRBS/ MCS **XX**  | **TBC** Mbit/s | 8.90 Mbits/s | COTS-UE Cat 4 (150/50 Mbps)
-TDD DL: 20 MHz, 100 PRBS/ MCS **XX** | **TBC** Mbit/s | N/A | COTS-UE Cat 4 (150/50 Mbps)
+TDD DL: 5 MHz, 25 PRBS/ MCS **XX**   | 6.5 Mbit/s          | TM1: 6.71 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
+TDD DL: 10 MHz, 50 PRBS/ MCS **XX**  | 13.5 Mbit/s         | TM1: 13.6 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
+TDD DL: 20 MHz, 100 PRBS/ MCS **XX** | 28.0 Mbit/s         | TM1: 27.2 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
  |  | | 
-TDD UL: 5 MHz, 25 PRBS/ MCS **XX**   | **TBC** Mbit/s | 1.66 Mbits/s | COTS-UE Cat 4 (150/50 Mbps)
-TDD UL: 10 MHz, 50 PRBS/ MCS **XX**  | **TBC** Mbit/s | 1.89 Mbits/s | COTS-UE Cat 4 (150/50 Mbps)
-TDD UL: 20 MHz, 100 PRBS/ MCS **XX** | **TBC** Mbit/s | N/A | COTS-UE Cat 4 (150/50 Mbps)
+TDD UL: 5 MHz, 25 PRBS/ MCS **XX**   | 2.0 Mbit/s          | TM1: 1.66 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
+TDD UL: 10 MHz, 50 PRBS/ MCS **XX**  | 2.0 Mbit/s          | TM1: 1.89 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
+TDD UL: 20 MHz, 100 PRBS/ MCS **XX** | 3.0 Mbit/s          | TM1: 2.70 Mbits/s       | COTS-UE Cat 4 (150/50 Mbps)
 
-- Number of supported UEs: **To Be Completed**
+- Number of supported UEs: 16 by default, up to 256 when compiling with dedicated compile flag
+                           Was tested with 40 COTS-UE
 
 ## eNB MAC Layer ##