Skip to content
Snippets Groups Projects
Commit 151bbd08 authored by Raphael Defosseux's avatar Raphael Defosseux
Browse files

CI/DOC: more detailed documentation on how CI works 


Signed-off-by: default avatarRaphael Defosseux <raphael.defosseux@eurecom.fr>
parent 2774e516
No related branches found
No related tags found
4 merge requests!650Release v1.1.0 Candidate,!588Develop nr merge,!579Develop integration 2019 Week 17,!571WIP: improved documentation
Hide whitespace changes
Inline Side-by-side
Showing
with 1084 additions and 9 deletions
ci-scripts/doc/ci_dev_home.md 0 → 100644
+ 31
− 0
View file @ 151bbd08
<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_build.md 0 → 100644
+ 262
− 0
View file @ 151bbd08
<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: build an OAI variant</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
$ ls *.zip
localZip.zip
$ ./ci-scripts/oai-ci-vm-tool build --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 build [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.
--workspace #### OR -ws ####
Specify the workspace.
Options:
--------
# 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.
--keep-vm-alive OR -k
Keep the VM alive after the build.
--daemon OR -D
Run as daemon
--help OR -h
Print this help message.
```
# 2. Detailed Description #
Source file concerned: `ci-scripts/buildOnVM.sh`
## 2.1. build_on_vm function ##
* First check if the ZIP file is available and if the apt-cacher proxy configuration file is present. If not, it will stop.
* Check if the VM instance is alive. If not, create it.
* Once the VM is alive, retrieve the IP address with VM_IP_ADDR=`uvt-kvm ip $VM_NAME`
* We copy the ZIP file to the VM : `scp localZip.zip ubuntu@$VM_IP_ADDR:/home/ubuntu`
* apt-cacher proxy file: `scp etc/apt/apt.conf.d/01proxy ubuntu@$VM_IP_ADDR:/home/ubuntu`
Then we open a SSH session on the VM : `ssh ubuntu@$VM_IP_ADDR`
* We copy the apt-cacher proxy file to its destination space: `sudo cp 01proxy /etc/apt/apt.conf.d/`
* We create an hush login file to eliminate the ssh opening session messages.
* We unzip the ZIP file into `/home/ubuntu/tmp/` folder
* and we work from there.
# 3. Typical Usage #
## 3.1. Build in the foreground, check the results and destroy the VM at the end ##
```bash
$ cd /tmp/CI-raphael
$ ls *.zip
localZip.zip
$ ./ci-scripts/oai-ci-vm-tool build --workspace /tmp/CI-raphael --job-name RAN-CI-develop --build-id 47 --variant enb-usrp
############################################################
OAI CI VM script
############################################################
VM_NAME = RAN-CI-develop-b47-enb-usrp
VM_CMD_FILE = RAN-CI-develop-b47-enb-usrp_cmds.txt
JENKINS_WKSP = /var/jenkins/workspace/RAN-CI-develop
ARCHIVES_LOC = /var/jenkins/workspace/RAN-CI-develop/archives/enb_usrp
BUILD_OPTIONS = --eNB -w USRP --mu
VM_MEMORY = 2048 MBytes
VM_CPU = 4
############################################################
Creating VM (RAN-CI-develop-b47-enb-usrp) on Ubuntu Cloud Image base
############################################################
Waiting for VM to be started
Warning: Permanently added '192.168.122.2' (ECDSA) to the list of known hosts.
RAN-CI-develop-b47-enb-usrp has for IP addr = 192.168.122.2
############################################################
Copying GIT repo into VM (RAN-CI-develop-b47-enb-usrp)
############################################################
Warning: Permanently added '192.168.122.2' (ECDSA) to the list of known hosts.
############################################################
Running install and build script on VM (RAN-CI-develop-b47-enb-usrp)
############################################################
Welcome to Ubuntu 16.04.6 LTS (GNU/Linux 4.4.0-145-generic x86_64)
* Documentation: https://help.ubuntu.com
* Management: https://landscape.canonical.com
* Support: https://ubuntu.com/advantage
Get cloud support with Ubuntu Advantage Cloud Guest:
http://www.ubuntu.com/business/services/cloud
0 packages can be updated.
0 updates are security updates.
New release '18.04.2 LTS' available.
Run 'do-release-upgrade' to upgrade to it.
sudo apt-get --yes --quiet install zip subversion libboost-dev
unzip -qq -DD ../localZip.zip
cd /home/ubuntu/tmp
source oaienv
cd cmake_targets
./build_oai -I --eNB -w USRP --mu
# Here wait for a few minutes 8 to 12 minutes #
############################################################
Creating a tmp folder to store results and artifacts
############################################################
############################################################
Destroying VM
############################################################
# Host 192.168.122.2 found: line 19
/home/eurecom/.ssh/known_hosts updated.
Original contents retained as /home/eurecom/.ssh/known_hosts.old
############################################################
Checking build status
############################################################
STATUS seems OK
```
If you are adding the `-k` or `--keep-vm-alive` option, the VM instance will not be destroyed and you explore what happenned.
## 3.2. Build in the background ##
This is how it is done in the CI master job pipeline.
```bash
$ cd /tmp/CI-raphael
$ ls *.zip
localZip.zip
$ ./ci-scripts/oai-ci-vm-tool build --workspace /tmp/CI-raphael --job-name RAN-CI-develop --build-id 47 --variant phy-sim --daemon
12:44:24 ############################################################
12:44:24 OAI CI VM script
12:44:24 ############################################################
12:44:24 VM_NAME = RAN-CI-develop-b47-phy-sim
12:44:24 VM_CMD_FILE = RAN-CI-develop-b47-phy-sim_cmds.txt
12:44:24 JENKINS_WKSP = /var/jenkins/workspace/RAN-CI-develop
12:44:24 ARCHIVES_LOC = /var/jenkins/workspace/RAN-CI-develop/archives/phy_sim
12:44:24 BUILD_OPTIONS = --phy_simulators
12:44:24 VM_MEMORY = 2048 MBytes
12:44:24 VM_CPU = 4
12:44:24 ############################################################
12:44:24 Creating VM (RAN-CI-develop-b47-phy-sim) on Ubuntu Cloud Image base
12:44:24 ############################################################
12:44:27 Waiting for VM to be started
12:46:34 Warning: Permanently added '192.168.122.220' (ECDSA) to the list of known hosts.
12:46:34 RAN-CI-develop-b47-phy-sim has for IP addr = 192.168.122.220
12:46:34 ############################################################
12:46:34 Copying GIT repo into VM (RAN-CI-develop-b47-phy-sim)
12:46:34 ############################################################
12:46:34 Warning: Permanently added '192.168.122.220' (ECDSA) to the list of known hosts.
12:46:34 ############################################################
12:46:34 Running install and build script on VM (RAN-CI-develop-b47-phy-sim)
12:46:34 ############################################################
12:46:34 Welcome to Ubuntu 16.04.6 LTS (GNU/Linux 4.4.0-145-generic x86_64)
12:46:34
12:46:34 * Documentation: https://help.ubuntu.com
12:46:34 * Management: https://landscape.canonical.com
12:46:34 * Support: https://ubuntu.com/advantage
12:46:34
12:46:34 Get cloud support with Ubuntu Advantage Cloud Guest:
12:46:34 http://www.ubuntu.com/business/services/cloud
12:46:34
12:46:34 0 packages can be updated.
12:46:34 0 updates are security updates.
12:46:34
12:46:34 New release '18.04.2 LTS' available.
12:46:34 Run 'do-release-upgrade' to upgrade to it.
12:46:34
12:46:34
12:46:34 sudo apt-get --yes --quiet install zip daemon subversion libboost-dev
12:46:46 unzip -qq -DD ../localZip.zip
12:46:48 source oaienv
12:46:48 sudo -E daemon --inherit --unsafe --name=build_daemon --chdir=/home/ubuntu/tmp/cmake_targets -o /home/ubuntu/tmp/cmake_targets/log/install-build.txt ./my-vm-build.sh
12:46:48 STATUS seems OK
```
So here is 2.5 minutes, a VM was created, source files copied and the build process is started in the background.
```bash
$ cd /tmp/raphael
$ ./ci-scripts/oai-ci-vm-tool wait --workspace /var/jenkins/workspace/RAN-CI-develop --variant phy-sim --job-name RAN-CI-develop --build-id 47 --keep-vm-alive
12:49:14 ############################################################
12:49:14 OAI CI VM script
12:49:14 ############################################################
12:49:14 VM_NAME = RAN-CI-develop-b47-phy-sim
12:49:14 VM_CMD_FILE = RAN-CI-develop-b47-phy-sim_cmds.txt
12:49:14 JENKINS_WKSP = /var/jenkins/workspace/RAN-CI-develop
12:49:14 ARCHIVES_LOC = /var/jenkins/workspace/RAN-CI-develop/archives/phy_sim
12:49:14 BUILD_OPTIONS = --phy_simulators
12:49:15 Waiting for VM to be started
12:49:15 Warning: Permanently added '192.168.122.220' (ECDSA) to the list of known hosts.
12:49:16 RAN-CI-develop-b47-phy-sim has for IP addr = 192.168.122.220
12:49:16 ############################################################
12:49:16 Waiting build process to end on VM (RAN-CI-develop-b47-phy-sim)
12:49:16 ############################################################
12:49:16 ps -aux | grep build
12:54:23 ############################################################
12:54:23 Creating a tmp folder to store results and artifacts
12:54:23 ############################################################
12:54:23 ############################################################
12:54:23 Checking build status
12:54:23 ############################################################
12:54:23 STATUS seems OK
```
Here the `--keep-vm-alive` option is used to keep the VM alive and performs some testing.
---
Next step: [how the build is checked](vm_based_simulator_check_build)
You can also go back to the [CI dev main page](./ci_dev_home)
ci-scripts/doc/vm_based_simulator_check_build.md 0 → 100644
+ 44
− 0
View file @ 151bbd08
<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 0 → 100644
+ 111
− 0
View file @ 151bbd08
<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 0 → 100644
+ 71
− 0
View file @ 151bbd08
<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 0 → 100644
+ 123
− 0
View file @ 151bbd08
<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 0 → 100644
+ 87
− 0
View file @ 151bbd08
<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 0 → 100644
+ 85
− 0
View file @ 151bbd08
<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)
ci-scripts/doc/vm_based_simulator_test.md 0 → 100644
+ 260
− 0
View file @ 151bbd08
<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: Testing an OAI variant</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. [Testing the physical simulators](#31-testing-the-physicals-simulators)
2. [Testing the basic simulator](#32-testing-the-basic-simulator)
3. [Testing the RF simulator](#33-testing-the-rf-simulator)
4. [Testing the L2-nFAPI simulator](#33-testing-the-l2-nfapi-simulator)
# 1. Introduction #
Currently 2 build variants can be directly tested:
* Physical Simulators
* Basic Simulator
In addition, 2 build variants are used:
* OAI eNB with ETHERNET transport
* OAI UE with ETHERNET transport
for the following scenarios:
* L1 simulator w/ a channel simulator (NOT IMPLEMENTED)
* RF simulator : (IMPLEMENTED but not working as of 2019.w15)
* L2 nFAPI simulator
Tests are run sequentially in the Jenkins pipeline because:
* We want to mutualize the VM creation for an EPC
* We have seen performance issues when running in parallel.
```bash
./ci-scripts/oai-ci-vm-tool test --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 test [OPTIONS]
Options:
--------
--job-name #### OR -jn ####
Specify the name of the Jenkins job.
--build-id #### OR -id ####
Specify the build ID of the Jenkins job.
--workspace #### OR -ws ####
Specify the workspace.
# 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.
--keep-vm-alive OR -k
Keep the VM alive after the build.
--help OR -h
Print this help message.
```
# 2. Detailed Description #
Source file concerned: `ci-scripts/run_test_on_vm.sh`
**TBD when file is re-structured.**
# 3. Typical Usage #
## 3.1. Testing the physical simulators ##
```bash
$ ./ci-scripts/oai-ci-vm-tool test --workspace /var/jenkins/workspace/RAN-CI-develop --variant phy-sim --job-name RAN-CI-develop --build-id 47
12:54:29 ############################################################
12:54:29 OAI CI VM script
12:54:29 ############################################################
12:54:29 VM_NAME = RAN-CI-develop-b47-phy-sim
12:54:29 VM_CMD_FILE = RAN-CI-develop-b47-phy-sim_cmds.txt
12:54:29 JENKINS_WKSP = /var/jenkins/workspace/RAN-CI-develop
12:54:29 ARCHIVES_LOC = /var/jenkins/workspace/RAN-CI-develop/archives/phy_sim/test
12:54:29 ############################################################
12:54:29 Waiting for VM to be started
12:54:29 ############################################################
12:54:29 Warning: Permanently added '192.168.122.220' (ECDSA) to the list of known hosts.
12:54:30 RAN-CI-develop-b47-phy-sim has for IP addr = 192.168.122.220
...
13:04:48 Test Results are written to /home/ubuntu/tmp/cmake_targets/autotests/log/results_autotests.xml
13:05:00 ############################################################
13:05:00 Creating a tmp folder to store results and artifacts
13:05:00 ############################################################
13:05:00 /var/jenkins/workspace/RAN-CI-develop/archives/phy_sim/test /var/jenkins/workspace/RAN-CI-develop
13:05:04 /var/jenkins/workspace/RAN-CI-develop
13:05:04 ############################################################
13:05:04 Destroying VM
13:05:04 ############################################################
13:05:06 # Host 192.168.122.220 found: line 21
13:05:06 /home/eurecom/.ssh/known_hosts updated.
13:05:06 Original contents retained as /home/eurecom/.ssh/known_hosts.old
13:05:06 ############################################################
13:05:06 Checking run status
13:05:06 ############################################################
13:05:06 NB_FOUND_FILES = 1
13:05:06 NB_RUNS = 20
13:05:06 NB_FAILURES = 0
13:05:06 STATUS seems OK
```
Note that the VM instance is destroyed. You do that when you are sure your test is passing.
## 3.2. Testing the basic simulator ##
```bash
$ ./ci-scripts/oai-ci-vm-tool test --workspace /var/jenkins/workspace/RAN-CI-develop --variant basic-sim --job-name RAN-CI-develop --build-id 48
15:11:13 ############################################################
15:11:13 OAI CI VM script
15:11:13 ############################################################
15:11:13 VM_NAME = RAN-CI-develop-b48-basic-sim
15:11:13 VM_CMD_FILE = RAN-CI-develop-b48-basic-sim_cmds.txt
15:11:13 JENKINS_WKSP = /var/jenkins/workspace/RAN-CI-develop
15:11:13 ARCHIVES_LOC = /var/jenkins/workspace/RAN-CI-develop/archives/basic_sim/test
15:11:13 ############################################################
15:11:13 Waiting for VM to be started
15:11:13 ############################################################
15:11:14 Warning: Permanently added '192.168.122.29' (ECDSA) to the list of known hosts.
15:11:15 RAN-CI-develop-b48-basic-sim has for IP addr = 192.168.122.29
15:11:15 ############################################################
15:11:15 Test EPC on VM (RAN-CI-develop-b48-epc) will be using ltebox
15:11:15 ############################################################
15:11:15 EPC_VM_CMD_FILE = RAN-CI-develop-b48-epc_cmds.txt
15:11:15 ############################################################
15:11:15 Creating test EPC VM (RAN-CI-develop-b48-epc) on Ubuntu Cloud Image base
15:11:15 ############################################################
15:11:18 Waiting for VM to be started
15:13:25 Warning: Permanently added '192.168.122.156' (ECDSA) to the list of known hosts.
15:13:25 RAN-CI-develop-b48-epc has for IP addr = 192.168.122.156
15:13:25 Warning: Permanently added '192.168.122.156' (ECDSA) to the list of known hosts.
15:13:25 ls: cannot access '/opt/ltebox/tools/start_ltebox': No such file or directory
15:13:25 ############################################################
15:13:25 Copying ltebox archives into EPC VM (RAN-CI-develop-b48-epc)
15:13:25 ############################################################
15:13:25 ############################################################
15:13:25 Install EPC on EPC VM (RAN-CI-develop-b48-epc)
15:13:25 ############################################################
....
15:24:39 ############################################################
15:24:39 Terminate EPC
15:24:39 ############################################################
15:24:39 cd /opt/ltebox/tools
15:24:39 sudo ./stop_ltebox
15:24:40 sudo daemon --name=simulated_hss --stop
15:24:40 sudo killall --signal SIGKILL hss_sim
15:24:40 ############################################################
15:24:40 Destroying VMs
15:24:40 ############################################################
15:24:41 # Host 192.168.122.29 found: line 18
15:24:41 /home/eurecom/.ssh/known_hosts updated.
15:24:41 Original contents retained as /home/eurecom/.ssh/known_hosts.old
15:24:43 # Host 192.168.122.60 found: line 20
15:24:43 /home/eurecom/.ssh/known_hosts updated.
15:24:43 Original contents retained as /home/eurecom/.ssh/known_hosts.old
15:24:43 ############################################################
15:24:43 Checking run status
15:24:43 ############################################################
15:24:43 STATUS seems OK
```
## 3.3. Test the RF simulator ##
```bash
./ci-scripts/oai-ci-vm-tool test --workspace /var/jenkins/workspace/RAN-CI-develop --variant rf-sim --job-name RAN-CI-develop --build-id 48 --keep-vm-alive
15:24:45 Currently RF-Simulator Testing is not implemented / enabled
15:24:45 Comment out these lines in ./ci-scripts/oai-ci-vm-tool if you want to run it
15:24:45 STATUS seems OK
```
## 3.4. Testing the L2-nFAPI simulator
```bash
./ci-scripts/oai-ci-vm-tool test --workspace /var/jenkins/workspace/RAN-CI-develop --variant l2-sim --job-name RAN-CI-develop --build-id 48
15:24:47 ############################################################
15:24:47 OAI CI VM script
15:24:47 ############################################################
15:24:47 ENB_VM_NAME = RAN-CI-develop-b48-enb-ethernet
15:24:47 ENB_VM_CMD_FILE = RAN-CI-develop-b48-enb-ethernet_cmds.txt
15:24:47 UE_VM_NAME = RAN-CI-develop-b48-ue-ethernet
15:24:47 UE_VM_CMD_FILE = RAN-CI-develop-b48-ue-ethernet_cmds.txt
15:24:47 JENKINS_WKSP = /var/jenkins/workspace/RAN-CI-develop
15:24:47 ARCHIVES_LOC = /var/jenkins/workspace/RAN-CI-develop/archives/l2_sim/test
15:24:47 ############################################################
15:24:47 Waiting for ENB VM to be started
15:24:47 ############################################################
15:24:47 Warning: Permanently added '192.168.122.110' (ECDSA) to the list of known hosts.
15:24:48 RAN-CI-develop-b48-enb-ethernet has for IP addr = 192.168.122.110
15:24:48 ############################################################
15:24:48 Waiting for UE VM to be started
15:24:48 ############################################################
15:24:49 Warning: Permanently added '192.168.122.90' (ECDSA) to the list of known hosts.
15:24:50 RAN-CI-develop-b48-ue-ethernet has for IP addr = 192.168.122.90
15:24:50 ############################################################
15:24:50 Test EPC on VM (RAN-CI-develop-b48-epc) will be using ltebox
15:24:50 ############################################################
15:24:50 EPC_VM_CMD_FILE = RAN-CI-develop-b48-epc_cmds.txt
15:24:50 Waiting for VM to be started
15:24:50 Warning: Permanently added '192.168.122.156' (ECDSA) to the list of known hosts.
15:24:51 RAN-CI-develop-b48-epc has for IP addr = 192.168.122.156
...
15:42:44 ############################################################
15:42:44 Destroying VMs
15:42:44 ############################################################
15:42:46 # Host 192.168.122.110 found: line 18
15:42:46 /home/eurecom/.ssh/known_hosts updated.
15:42:46 Original contents retained as /home/eurecom/.ssh/known_hosts.old
15:42:47 # Host 192.168.122.90 found: line 18
15:42:47 /home/eurecom/.ssh/known_hosts updated.
15:42:47 Original contents retained as /home/eurecom/.ssh/known_hosts.old
15:42:47 ############################################################
15:42:47 Checking run status
15:42:47 ############################################################
15:42:47 STATUS failed?
```
---
Final step: [how to properly destroy all VM instances](vm_based_simulator_destroy)
You can also go back to the [CI dev main page](./ci_dev_home)
doc/FEATURE_SET.md
+ 10
− 9
View file @ 151bbd08
......@@ -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 ##
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment