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.
$ ./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.md)
You can also go back to the [CI dev main page](./ci_dev_home.md)
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.md)
You can also go back to the [CI dev main page](./ci_dev_home.md)
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.md)
You can also go back to the [CI dev main page](./ci_dev_home.md)
This page is valid on tags starting from **`2019.w09`**.
oai EPC is developed in a distinct project with it's own [documentation](https://github.com/OPENAIRINTERFACE/openair-cn/wiki) , it is not described here. OAI UE and eNodeB sources can be downloaded from the Eurecom [gitlab repository](./GET_SOURCES.md). Sources come with a build script [build_oai](../cmake_targets/build_oai) located at the root of the `openairinterface5g/cmake_targets` directory. This script is developed to build the oai binaries (executables,shared libraries) for different hardware platforms, and use cases.
# Soft Modem Build Script
the main oai binaries, which are tested by the Continuous Integration process are:
oai EPC is developed in a distinct project with it's own [documentation](https://github.com/OPENAIRINTERFACE/openair-cn/wiki) , it is not described here.
- The LTE UE: `lte-uesoftmodem`
OAI UE and eNodeB sources can be downloaded from the Eurecom [gitlab repository](./GET_SOURCES.md).
Sources come with a build script [build_oai](../cmake_targets/build_oai) located at the root of the `openairinterface5g/cmake_targets` directory. This script is developed to build the oai binaries (executables,shared libraries) for different hardware platforms, and use cases.
The main oai binaries, which are tested by the Continuous Integration process are:
- The LTE UE: `lte-uesoftmodem`
- The LTE eNodeB: `lte-softmodem`
- The LTE eNodeB: `lte-softmodem`
- The PHY simulators: `dlsim` and `ulsim`
-The PHY simulators: `dlsim` and `ulsim`
The build system for OAI uses [cmake](https://cmake.org/) which is a tool to generate makefiles. The `build_oai` script is a wrapper using cmake, make and standard linux shell commands to ease the oai build and use . The file describing how to build the executables from source files is the [CMakeLists.txt](../cmake_targets/CMakeLists.txt), it is used as input by cmake to generate the makefiles.
The build system for OAI uses [cmake](https://cmake.org/) which is a tool to generate makefiles. The `build_oai` script is a wrapper using cmake, make and standard linux shell commands to ease the oai build and use . The file describing how to build the executables from source files is the [CMakeLists.txt](../cmake_targets/CMakeLists.txt), it is used as input by cmake to generate the makefiles.
The oai softmodem supports many use cases, and new ones are regularly added. Most of them are accessible using the configuration file or the command line options and continuous effort is done to avoid introducing build options as it makes tests and usage more complicated than run-time options. The following functionalities, originally requiring a specific build are now accessible by configuration or command line options:
The oai softmodem supports many use cases, and new ones are regularly added. Most of them are accessible using the configuration file or the command line options and continuous effort is done to avoid introducing build options as it makes tests and usage more complicated than run-time options. The following functionalities, originally requiring a specific build are now accessible by configuration or command line options:
- s1, noS1
- s1, noS1
- all simulators, with exception of PHY simulators, which are distinct executables.
- all simulators, with exception of PHY simulators, which are distinct executables.
...
@@ -23,15 +40,13 @@ Calling the `build_oai` script with the -h option gives the list of all availabl
...
@@ -23,15 +40,13 @@ Calling the `build_oai` script with the -h option gives the list of all availabl
[table]:BUILD.md"`build_oai` options"
[table]:BUILD.md"`build_oai` options"
at the end of this page to know the status of `buid_oai` options which are not described hereafter.
At the end of this page to know the status of `buid_oai` options which are not described hereafter.
# Building PHY Simulators
Detailed information about these simulators can be found [in this dedicated page](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/OpenAirLTEPhySimul)
## building PHY simulators
# Building UE and eNodeB Executables
detailed information about these simulators can be found [in this dedicated page](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/OpenAirLTEPhySimul
## building UE and eNodeB executables
After downloading the source files, a single build command can be used to get the binaries supporting all the oai softmodem use cases (UE and eNodeB):
After downloading the source files, a single build command can be used to get the binaries supporting all the oai softmodem use cases (UE and eNodeB):
...
@@ -42,34 +57,32 @@ cd ../cmake_targets/
...
@@ -42,34 +57,32 @@ cd ../cmake_targets/
./build_oai -I -w USRP --eNB --UE
./build_oai -I -w USRP --eNB --UE
```
```
- The -I option is to install pre-requisites, you only need it the first time you build the softmodem or when some oai dependencies have changed.
- The `-I` option is to install pre-requisites, you only need it the first time you build the softmodem or when some oai dependencies have changed.
- The -w option is to select the radio head support you want to include in your build. Radio head support is provided via a shared library, which is called the "oai device" The build script creates a soft link from `liboai_device.so` to the true device which will be used at run-time (here the USRP one,`liboai_usrpdevif.so` . USRP is the only hardware tested today in the Continuous Integration process.
- The `-w` option is to select the radio head support you want to include in your build. Radio head support is provided via a shared library, which is called the "oai device" The build script creates a soft link from `liboai_device.so` to the true device which will be used at run-time (here the USRP one,`liboai_usrpdevif.so` . USRP is the only hardware tested today in the Continuous Integration process.
---eNB is to build the `lte-softmodem` executable and all required shared libraries
-`--eNB` is to build the `lte-softmodem` executable and all required shared libraries
---UE is to build the `lte-uesoftmodem` executable and all required shared libraries
-`--UE` is to build the `lte-uesoftmodem` executable and all required shared libraries
You can build the eNodeB and the UE separately, you may not need both of them depending on your oai usage.
You can build the eNodeB and the UE separately, you may not need both of them depending on your oai usage.
After completing the build, the binaries are available in the `cmake_targets/lte_build_oai/build` directory. A copy is also available in the `target/bin` directory, with all binaries suffixed by the 3GPP release number, today .Rel14 by default. It must be noticed that the option for building for a specific 3GPP release number is not tested by the CI and may be removed in the future.
After completing the build, the binaries are available in the `cmake_targets/lte_build_oai/build` directory. A copy is also available in the `target/bin` directory, with all binaries suffixed by the 3GPP release number, today .Rel14 by default. It must be noticed that the option for building for a specific 3GPP release number is not tested by the CI and may be removed in the future.
## building optional binaries
# Building Optional Binaries
### Telnet server
## Telnet Server
The telnet server can be built with the --build-telnet option, after building the softmodem or while building it.
The telnet server can be built with the --build-telnet option, after building the softmodem or while building it.
After you have [built the softmodem executables](BUILD.md) you can set your default directory to the build directory `cmake_targets/lte_build_oai/build/` and start testing some use cases. Below, the description of the different oai functionalities should help you choose the oai configuration that suits your need.
After you have [built the softmodem executables](BUILD.md) you can set your default directory to the build directory `cmake_targets/lte_build_oai/build/` and start testing some use cases. Below, the description of the different oai functionalities should help you choose the oai configuration that suits your need.
## rf simulator
# RF Simulator
The rf simulator is a oai device replacing the radio heads (for example the USRP device). It allows connecting the oai UE and the oai eNodeB through a network interface carrying the time-domain samples, getting rid of over the air unpredictable perturbations. This is the ideal tool to check signal processing algorithms and protocols implementation.
The rf simulator is a oai device replacing the radio heads (for example the USRP device). It allows connecting the oai UE and the oai eNodeB through a network interface carrying the time-domain samples, getting rid of over the air unpredictable perturbations. This is the ideal tool to check signal processing algorithms and protocols implementation.
It is planned to enhance this simulator with the following functionalities:
It is planned to enhance this simulator with the following functionalities:
...
@@ -14,15 +26,15 @@ It is planned to enhance this simulator with the following functionalities:
...
@@ -14,15 +26,15 @@ It is planned to enhance this simulator with the following functionalities:
This is an easy use-case to setup and test, as no specific hardware is required. The [rfsimulator page](../targets/ARCH/rfsimulator/README.md) contains the detailed documentation.
This is an easy use-case to setup and test, as no specific hardware is required. The [rfsimulator page](../targets/ARCH/rfsimulator/README.md) contains the detailed documentation.
## l2 nfapi simulator
# L2 nFAPI Simulator
This simulator connects a eNodeB and UEs through a nfapi interface, short-cutting the L1 layer. The objective of this simulator is to allow multi UEs simulation, with a large number of UEs (ideally up to 255 ) .Here to ease the platform setup, UEs are simulated via a single `lte-uesoftmodem` instance. Today the CI tests just with one UE and architecture has to be reviewed to allow a number of UE above about 16. This work is on-going.
This simulator connects a eNodeB and UEs through a nfapi interface, short-cutting the L1 layer. The objective of this simulator is to allow multi UEs simulation, with a large number of UEs (ideally up to 255 ) .Here to ease the platform setup, UEs are simulated via a single `lte-uesoftmodem` instance. Today the CI tests just with one UE and architecture has to be reviewed to allow a number of UE above about 16. This work is on-going.
As for the rf simulator, no specific hardware is required. The [L2 nfapi simlator page](L2NFAPI.md) contains the detailed documentation.
As for the rf simulator, no specific hardware is required. The [L2 nfapi simlator page](L2NFAPI.md) contains the detailed documentation.
## l1 simulator
# L1 Simulator
The l1 simulator is using the ethernet fronthaul protocol, as used to connect a RRU and a RAU to connect UEs and a eNodeB. UEs are simulated in a single `lte-uesoftmodem` process, as for the nfapi simulator.
The L1 simulator is using the ethernet fronthaul protocol, as used to connect a RRU and a RAU to connect UEs and a eNodeB. UEs are simulated in a single `lte-uesoftmodem` process, as for the nfapi simulator.
The [L1 simulator page](L1SIM.md) contains the detailed documentation.
The [L1 simulator page](L1SIM.md) contains the detailed documentation.
...
@@ -34,7 +46,7 @@ By default the noS1 mode is using linux tun interfaces to send or receive ip pac
...
@@ -34,7 +46,7 @@ By default the noS1 mode is using linux tun interfaces to send or receive ip pac
noS1 code has been revisited, it has been tested with the rf simulator, and tun interfaces. More tests are on going and CI will soon include noS1 tests.
noS1 code has been revisited, it has been tested with the rf simulator, and tun interfaces. More tests are on going and CI will soon include noS1 tests.
## Running with a true radio head
# Running with a true radio head
oai supports [number of deployment](FEATURE_SET.md) model, the following are tested in the CI:
oai supports [number of deployment](FEATURE_SET.md) model, the following are tested in the CI:
