Commit 35705578 authored by Raphael Defosseux's avatar Raphael Defosseux

Merge remote-tracking branch 'origin/develop-improved-doc' into develop_integration_2019_w17

parents ebb30df8 52023590
develop 1 128-ues 256_QAM_demod 2cw_fairRRscd 445-LDPC-implementation-on-GPU 459-pusch-based-ta-updates 464-ru_beamforming_in_gpu 464-ru_beamforming_in_gpu-CPUsubfunction 472-add-pusch-dmrs-modes 481-ldpc-decoder-on-gpu LTE_TRX_on_single_port NCTU_CS_ISIP NCTU_CS_ISIP_CPU NCTU_CS_ISIP_GPU NCTU_OpinConnect_LDPC NR-PHY-MAC-IF-multi-UE NRUE_usedlschparallel NR_10MHz NR_CSI_reporting NR_DCI_01 NR_DLUL_PF NR_DLUL_PF_4UL NR_DLUL_PF_rebased NR_DL_MIMO NR_DL_sched_fixes NR_DL_scheduler NR_FAPI_beamindex_SSB_RO NR_FDD_FIX NR_FR2_RA NR_FR2_RRC_SSB NR_MAC_CE_GlobalEdge NR_MAC_Multi_Rach_GlobalEdge NR_MAC_SSB_RO_GlobalEdge NR_MAC_SSB_RO_UE_IDCC NR_MAC_SSB_RO_merge NR_MAC_TCI_UCI_GlobalEdge NR_NGAP NR_PDCP_noS1 NR_PUCCH_MultiUE NR_RA_cleanup NR_RA_updates NR_RRCConfiguragion_FR2 NR_RRCConfiguration NR_RRCConfiguration_FR2 NR_RRCConfiguration_S1U NR_RRCConfiguration_merge_develop NR_RRCConfiguration_sync_source NR_RRCConfiguration_trx_thread NR_RRC_CP_bugfix NR_RRC_PDCP NR_RRC_PRACH_procedures NR_RRC_PRACH_procedures_todevelop NR_RRC_PUSCH NR_RRC_TA NR_RRC_X2AP_AMBR_Change_Global_edge NR_RRC_X2AP_RemoveHardcodings_GlobalEdge NR_RRC_config_simplified NR_RRC_harq NR_RRC_harq_b NR_RRC_harq_hacks NR_RRC_harq_newdcipdu NR_SA_F1AP_RFSIMULATOR NR_SA_F1AP_RFSIMULATOR2 NR_SA_F1AP_dev NR_SA_NGAP_RRC NR_SA_NGAP_RRC_wk42 NR_SA_itti_sim_wk48 NR_SA_itti_sim_wk48_hs NR_SA_itti_sim_wk48_hs1 NR_SCHED NR_SCHED_HARQ NR_SCHED_PDCCH_PUCCH_HARQ NR_SCHED_PDCCH_PUCCH_HARQ_rebased NR_SCHED_fixes NR_SRB_Config NR_TRX_on_single_port NR_TRX_on_single_port2 NR_UE_MAC_scheduler NR_UE_RA_fixes NR_UE_UL_DCI_improvements NR_UE_dlsch_bugfix NR_UE_enable_parallelization NR_UE_stability_fixes NR_UL_FAPI_programming NR_UL_scheduler NR_UL_scheduler_rebased NR_UL_scheduling NR_Wireshark NR_beam_simulation NR_beamforming_test NR_gNB_SCF_Indication NR_ipaccess_testing NR_mac_uci_functions_rework NR_msg2_phytest NR_scheduling_CSIRS NR_scheduling_request NR_scheduling_request2 NR_scheduling_request3 NR_test_S1U_RRC_PRACH_procedures NR_ue_dlsch_dmrs_cdm OpInConnect_ISIP PUSCH_TA_update RA_CI_test UE_DL_DCI_hotfix addoptions_nr_USRPdevice bch-fixes-bitmap benetel_5g_prach_fix benetel_driver_uldl_pf_merge benetel_driver_update benetel_phase_rotation benetel_phase_rotation_old bugfix-find-uci bugfix-minor-remove-wrong-log bugfix-nr-bands bugfix-nr-ldpc-post-processing bugfix-nr-ldpc-size-typo bugfix-nr-pdcp-sn-size bugfix-nr-rate-matching-assertion bugfix-x2-SgNBAdditionRequest bupt-sa-merge cce_indexing_fix cce_indexing_fix2 ci-deploy-asterix ci-deploy-docker-compose ci-rd-july-improvements ci-test ci-ul-iperf-from-trf-container ci-yacine clean-5G-scope-round2 cleanup_softmodem_main constant_power container_fix container_v1.2.2 debug_branch_init_sync develop-SA-RA develop-SnT develop-ci develop-large-scale-emulations develop-m2ap develop-multi-RRUs develop-nb-iot-merge develop-nb-iot-merge-w-conflicts develop-nb-iot-ntust develop-nr develop-nr-fr2 develop-nr-fr2-rework develop-nr_cppcheck develop-oriecpriupdates develop-sib1 develop-sib1-local develop-sib1-lts develop-sib1-update develop-sib1-update-test1 develop-sib1-update-ue develop-vco3 develop_ci develop_inria_ci_deployment develop_inria_ci_deployment_gp develop_inria_ci_deployment_gp_b4merge develop_integration_2019_w44 develop_integration_2020_w15 develop_integration_2020_w19 develop_integration_w08 develop_jenkins_replay develop_stable dfts_alternatives dlsch-all-dlslots dlsch_encode_mthread dlsch_parallel docupdate_tools dongzhanyi-zte-0001 dongzhanyi-zte-develop dongzhanyi-zte-develop2 dreibh/apt-auth-fix dreibh/device-load-fix dreibh/device-load-fix-develop-branch dual-connectivity dummy edrx extend_sharedlibusage extend_sharedlibusage2 fapi_for_dmrs_and_ptrs feature-368-channel-simulator feature-4g-sched feature-flexran-cm-s1ap feature-nr-4g-nfapi-modifications feature-support-clang-format feature/make-s1-mme-port-configurable feature/make-s1-mme-port-configurable-with-astyle-fixes feature_tm3 fembms-enb-ue finalize-oaicn-integration firas fix-ci-tun fix-clock-source fix-dirty-ue-same-machine fix-itti-segv fix-l2-sim fix-limeSDR-compile fix-softmodem-restart fix-warnings fix_NR_DLUL_PF fix_do_ra_data fix_pdsch_low_prb fix_rfsim_mimo fix_rrc_x2_ticking fixes-CE-RLC-PDU-size fixes-mac-sched-nfapi fixes-mac-sched-tun fixes-tun flexran-apps flexran-improvements flexran-repair-mme-mgmt flexran-report-split fr2-hw-test fujitsu_lte_contribution fujitsu_lte_contribution-128 generate_push_ptrs gnb-only-test harq-hotfix hotfix-minor-remove-nr-rlc-cppcheck-error hotfix-nr-rlc-tick hotfix-ocp-executable hotfix-ue-musim-compilation hotfix_usrp_lib improve_build_nr_lte_merge improve_nr_modulation improve_ue_stability initial-nfapi-PNF-fixes integration-develop-nr-2019w45 integration_2020_wk40 integration_2020_wk41 integration_2020_wk42_2 integration_2020_wk45 integration_2020_wk45_2 integration_2020_wk46 integration_2020_wk46_2 integration_2020_wk47 integration_2020_wk48 integration_2020_wk48_2 integration_2020_wk49 integration_2020_wk50 integration_2020_wk50_1 integration_2020_wk51 integration_2020_wk51_2 integration_2021_wk02 integration_2021_wk02_wMR988 integration_2021_wk04 integration_2021_wk05 inter-RRU inter-RRU-final inter-RRU-nr inter-RRU-oairu inter-rru-UE interoperability-test isip_nr itti-enhancement l2-fixes ldpc-dec-layering ldpc-decoder-codegen ldpc-decoder-codegen2 ldpc-decoder-improvements ldpc-offload ldpc_short_codeword_fixes load_gnb lte-m-ue_type lte-ulsch-bugfix lte_uplink_improvement mac-fixes-wk45_2 main_python master mbms-fix-develop-nr merging-2019-w51-to-develop-nr minor-fix-doc-basic-sim modify_fairRRscd_parallel mosaic5g-oai-ran mosaic5g-oai-sim mu_allocate multi-RRUs nasmesh_kernel_5.8 new-gtpu new_pdcp new_rlc new_rlc_2020 new_rlc_in_mbms nfapi-bugfix nfapi_nr_develop ngap-dlul ngap-support ngap-w48-merge2 ngap-wf ngap-wf-1120 ngap-wf-1120-srb ngap-wf-1120-srb-gtp ngap-wf-1120-srb-gtp-hs ngap-wf-1120-srb-gtp-hs1 ngap-wf-1120-srb-gtp-hs2 ngap-wf-1120-srb-gtp-yhz ngap-wf-1203-yunsdr ngap-wf-liuyu ngap_lfq_1120 ngap_merge noCore nr-coreset-bug-fix nr-dlsch-multi-thread nr-dlsch-thread nr-dual-connectivity nr-interdigital-test nr-ip-uplink-noS1 nr-mac-pdu-wireshark nr-mac-remove-ue-list nr-pdcp nr-pdsch-extraction-bugfix nr-physim-update nr-rlc-am-bugfix-w44 nr-rlc-bugfix-w44 nr-timing-measurement-merge nr-ue-buffer-status nr-uldci nrUE nrUE-hs nrUE-upper-layer nr_beamforming nr_bsr nr_csi_newbranch nr_dl_dmrs_type2 nr_dl_pf nr_dl_pf2 nr_dl_ul_ptrs nr_dlsch_parallel_measurements nr_fapi_for_push_tmp nr_fdd_if_fix nr_fix_easycppcheck nr_improve_build_procedures nr_increase_tp nr_pdcch_testing nr_polar_decoder_improvement nr_prach_fr2 nr_pucch nr_pucch2 nr_segmentation_fixes nr_tdd_configuration nr_ue_msg3 nr_ue_tti_cleanup nr_ul_pf nr_ul_scfdma nr_vcd nrue-multi-thread nrue_msg2_reception nsa-ue nsa_remove_band_hardcodings oai-sim oai-ubuntu-docker oai-ubuntu-docker-for-lmssdr oairu oairu-dockerfile-support oc-docker-october-improvements openxg/develop pdcp-benchmark pdsch-ch-est polar8 ptrs_rrc_config pusch-mthread-scaling-fix pusch-retrans-fix-ue ra-dl-ul release_v1_2_0_candidate remove_nos1_hack_pdcp remove_x2_gnb_hardcoding repair-TA revert_memcpy rh-ci-add-ue-parallelization rh_ci_fix_autoterminate rh_ci_fr1_update rh_ci_oc rh_ci_py rh_ci_ra_fr2 rh_ci_rfsim_ra rh_ci_ue_parallel rh_doc_update_3 rh_fr1_newjenkins rh_fr1_update rh_gnb_compile_fix rh_wk50_debug rhel77-build rlc-v2-bugfix-status-reporting rlc-v2-tick rlc_v2_coverity_fixes rrc-enb-phy-testmode ru-parallel-beamforming runel runel-reverse-test s1-subnormal_rewrite s1_subnormal s1_subnormal-robert s1ap-bugfix-rab_setup sa-demo sa-merge-rrc-srb sa-msg4 sa-msg4-rrc sa-msg4-rrc-yihz sa-msg4-rrc-yihz-hs sa_rrc_yihz small-bugfixes-w40 small-config-change smallcleanup softmodem_cleanup split73 testing_2symb_pdcch testing_with_external_txdata tools_5Gadapt tp-ota-test trx_thread_param trx_write_thread ue-csi ue-fixes ue-fixes-ota ue-updates-runel-test ue_beam_selection ue_dlsch_decoding_ldpc_offload ue_nfapi_mch uhd_priority_set_cleanup ul-freq-iq-samps-to-file ul_dl_dci_same_slot ul_harq ulsch_decode_mthread ulsim_changes usrp_fix_adc_shift_and_pps_sync usrp_gpio_test wireshark-T-hack-ueid wireshark-log-scheduling-requests x2-endc-processing x2_neighbor_6cells xiangwab xiangwan yihongzheng_srb zzs 2021.w04 2021.w02 2020.w51_2 2020.w51 2020.w50 2020.w49 2020.w48_2 2020.w48 2020.w47 2020.w46_2 2020.w46 2020.w45_2 2020.w45 2020.w44 2020.w42_2 2020.w42 2020.w41 2020.w39 2020.w38 2020.w37 2020.w36 2020.w34 2020.w33 2020.w31 2020.w30 2020.w29 2020.w28 2020.w26 2020.w25 2020.w24 2020.w23 2020.w22 2020.w19 2020.w17 2020.w16 2020.w15 2020.w11 2020.w09 2020.w06 2020.w05 2020.w04 2020.w03 2019.w51 2019.w44 2019.w41 2019.w36 2019.w30 2019.w28 2019.w27 2019.w25 2019.w23 2019.w21 2019.w17 v1.2.2 v1.2.1 v1.2.0 v1.1.1 v1.1.0 nr-ip-over-lte-v.1.5 nr-ip-over-lte-v.1.4 nr-ip-over-lte-v.1.3 nr-ip-over-lte-v.1.2 nr-ip-over-lte-v.1.1 nr-ip-over-lte-v.1.0 develop-nr-2020w03 develop-nr-2020w02 develop-nr-2019w51 develop-nr-2019w50 develop-nr-2019w48 develop-nr-2019w47 develop-nr-2019w45 develop-nr-2019w43 develop-nr-2019w42 develop-nr-2019w40 benetel_phase_rotation
No related merge requests found
<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.md)
* [How to deal with OAI source files](./vm_based_simulator_sources.md)
* [The main script](./vm_based_simulator_main_scripts.md)
* [How to create one or several VM instances](./vm_based_simulator_create.md)
* [How to build an OAI variant](./vm_based_simulator_build.md)
* [How the build is checked](./vm_based_simulator_check_build.md)
* [How to test an OAI variant](./vm_based_simulator_test.md)
* [How to destroy all VM instances](./vm_based_simulator_destroy.md)
Currently missing documentation:
* How to generate a build report
* How to generate a test report
---
<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 Test Environment: 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.md)
You can also go back to the [CI dev main page](./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 Virtual-Machine-based Test Environment: 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.md)
You can also go back to the [CI dev main page](./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 Virtual-Machine-based Test Environment: 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.md)
You can also go back to the [CI dev main page](./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 Virtual-Machine-based Test Environment: 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.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.md)
You can also go back to the [CI dev main page](./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 Virtual-Machine-based Test Environment: the 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.md)
You can also go back to the [CI dev main page](./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 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.md)
You can also go back to the [CI dev main page](./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 Virtual-Machine-based Test Environment: 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.md)
You can also go back to the [CI dev main page](./ci_dev_home.md)
# OAI build procedures
<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="./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 Build Procedures</font></b>
</td>
</tr>
</table>
## soft modem Build script
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 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 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
- 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
[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
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
# 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):
......@@ -42,34 +57,32 @@ cd ../cmake_targets/
./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 -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
- --UE is to build the `lte-uesoftmodem` executable and all required shared libraries
- 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.
- `--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
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.
## 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.
`./build_oai -I -w USRP --eNB --UE --build-telnetsrv`
or
or
`./build_oai --build-telnetsrv`
### USRP record player
​ The USRP record player today needs a specific build. Work to make it available as a run time option is under consideration
## USRP record player
The USRP record player today needs a specific build. Work to make it available as a run time option is under consideration
## `build_oai` options
# `build_oai` options
| Option | Status | Description |
| ----------------------------------------------------------- | ------------------------------------------- | :----------------------------------------------------------- |
......
......@@ -18,7 +18,7 @@
# OpenAirInterface Block diagram #
![Block Diagram](./oai_enb_block_diagram.png)
![Block Diagram](./images/oai_enb_block_diagram.png)
# OpenAirInterface eNB Feature Set #
......@@ -43,22 +43,26 @@ 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: 3.31 Mbits/s | COTS-UE Cat 4 (150/50 Mbps)
TDD UL: 10 MHz, 50 PRBS/ MCS **XX** | 2.0 Mbit/s | TM1: 7.25 Mbits/s | COTS-UE Cat 4 (150/50 Mbps)
TDD UL: 20 MHz, 100 PRBS/ MCS **XX** | 3.0 Mbit/s | TM1: 4.21 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 ##
......@@ -142,7 +146,7 @@ The X2AP layer is based on **3GPP 36.423** v14.6.0 and implements the following
- RAU: Radio-Access Unit
- RRU: Remote Radio-Unit
![Functional Split Architecture](./oai_lte_enb_func_split_arch.png)
![Functional Split Architecture](./images/oai_lte_enb_func_split_arch.png)
- IF4.5 / IF5 : similar to IEEE P1914.1
- FAPI (IF2) : specified by Small Cell Forum (open-nFAPI implementation)
......
# The OpenAirInterface repository
<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="./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">The OpenAirInterface repository: the sources</font></b>
</td>
</tr>
</table>
The OpenAirInterface software can be obtained from our gitLab
server. You will need a git client to get the sources. The repository
is currently used for main developments.
## Prerequisite
# Prerequisites
You need to install the subversion/git using the following commands:
......@@ -13,17 +25,23 @@ sudo apt-get update
sudo apt-get install subversion git
```
## Using EURECOM Gitlab
# Using EURECOM Gitlab
The [openairinterface5g repository](https://gitlab.eurecom.fr/oai/openairinterface5g.git)
holds the source code for (eNB RAN + UE RAN).
For legal issues (licenses), the core network (EPC) source code is now moved away from
the above openairinterface5g git repository. This EPC code is now splitted into two git
projects ([openair-cn](https://gitlab.eurecom.fr/oai/openair-cn.git) with apache license
and [xtables-addons-oai](https://gitlab.eurecom.fr/oai/xtables-addons-oai.git) with GPL license).
the above openairinterface5g git repository.
Configure git with your name/email address (only important if you are developer and want to checkin code to Git):
* A very old version of the EPC is located under the same GitLab Eurecom server (splitted into 2 Git repos):
* [openair-cn](https://gitlab.eurecom.fr/oai/openair-cn.git) with apache license
* [xtables-addons-oai](https://gitlab.eurecom.fr/oai/xtables-addons-oai.git) with GPL license
* **These repositories are no more maintained.**
* A more recent version is available under our GitHub domain:
* [OAI GitHub openair-cn](https://github.com/OPENAIRINTERFACE/openair-cn)
* Check its wiki pages for more details
Configure git with your name/email address (only important if you are developer and want to contribute/push code to Git Repository):
```shell
git config --global user.name "Your Name"
......@@ -42,42 +60,30 @@ echo -n | openssl s_client -showcerts -connect gitlab.eurecom.fr:443 2>/dev/null
git config --global http.sslverify false
```
### In order to checkout the Git repository (for OAI Users without login to gitlab server)
## In order to clone the Git repository (for OAI Users without login to gitlab server)
Checkout RAN repository (eNB RAN + UE RAN):
Cloning RAN repository (eNB RAN + UE RAN):
```shell
git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git
```
Checkout EPC (Core Network) repository:
```shell
git clone https://gitlab.eurecom.fr/oai/openair-cn.git
```
Optionally (openair-cn build script can install it for you):
```shell
git clone https://gitlab.eurecom.fr/oai/xtables-addons-oai.git
```
### In order to checkout the Git repository (for OAI Developers/admins with login to gitlab server)
## In order to contribute to the Git RAN repository (for OAI Developers/admins with login to gitlab server)
Please send email to {openair_tech (AT) eurecom (DOT) fr} to be added to the repository
Please send email to [contact@openairinterface.org](mailto:contact@openairinterface.org) to be added to the repository
as a developer (only important for users who want to commit code to the repository). If
you do not have account on gitlab.eurecom.fr, please register yourself to gitlab.eurecom.fr.
you do not have account on gitlab.eurecom.fr, please register yourself to gitlab.eurecom.fr and provide the identifiant in the email.
* Checkout with using ssh keys:
* Clone with using ssh keys:
* You will need to put your ssh keys in https://gitlab.eurecom.fr/profile/keys
to access to the git repo. Once that is done, checkout the git repository using:
to access to the git repo. Once that is done, clone the git repository using:
* `git clone git@gitlab.eurecom.fr:oai/openairinterface5g.git`
* Checkout with user name/password prompt:
* Clone with user name/password prompt:
* `git clone https://YOUR_USERNAME@gitlab.eurecom.fr/oai/openairinterface5g.git`
* `git clone https://YOUR_USERNAME@gitlab.eurecom.fr/oai/openair-cn.git`
* `git clone https://YOUR_USERNAME@gitlab.eurecom.fr/oai/xtables-addons-oai.git` (optional, openair-cn build script can do it for you)
## Which branch to checkout?
# Which branch to checkout?
On the RAN side:
......
# Running OAI softmodem
<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="./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">Running OAI Softmodem</font></b>
</td>
</tr>
</table>
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:
......@@ -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.
## 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.
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.
......@@ -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.
## 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:
......
doc/images/L2-sim-single-server-deployment.png

10.5 KB

Markdown is supported
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