Merge remote-tracking branch 'origin/doc-ci' into integration_2023_w13

README.md

@@ -4,8 +4,12 @@
 
 <p align="center">
     <a href="https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-OAI--Public--V1.1-blue" alt="License"></a>
-    <a href="https://releases.ubuntu.com/18.04/"><img src="https://img.shields.io/badge/OS-Ubuntu18-Green" alt="Supported OS"></a>
-    <a href="https://www.redhat.com/en/enterprise-linux-8"><img src="https://img.shields.io/badge/OS-RHEL8-Green" alt="Supported OS"></a>
+    <a href="https://releases.ubuntu.com/18.04/"><img src="https://img.shields.io/badge/OS-Ubuntu18-Green" alt="Supported OS Ubuntu 18"></a>
+    <a href="https://releases.ubuntu.com/20.04/"><img src="https://img.shields.io/badge/OS-Ubuntu20-Green" alt="Supported OS Ubuntu 20"></a>
+    <a href="https://releases.ubuntu.com/22.04/"><img src="https://img.shields.io/badge/OS-Ubuntu22-Green" alt="Supported OS Ubuntu 22"></a>
+    <a href="https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux"><img src="https://img.shields.io/badge/OS-RHEL8-Green" alt="Supported OS RHEL8"></a>
+    <a href="https://www.redhat.com/en/technologies/linux-platforms/enterprise-linux"><img src="https://img.shields.io/badge/OS-RHEL9-Green" alt="Supported OS RELH9"></a>
+    <a href="https://getfedora.org/en/workstation/"><img src="https://img.shields.io/badge/OS-Fedore37-Green" alt="Supported OS Fedora 37"></a>
 </p>
 
 <p align="center">
@@ -13,10 +17,10 @@
 </p>
 
 <p align="center">
-  <a href="https://hub.docker.com/r/rdefosseoai/oai-enb"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/rdefosseoai/oai-enb?label=eNB%20docker%20pulls"></a>
-  <a href="https://hub.docker.com/r/rdefosseoai/oai-lte-ue"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/rdefosseoai/oai-lte-ue?label=LTE-UE%20docker%20pulls"></a>
-  <a href="https://hub.docker.com/r/rdefosseoai/oai-gnb"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/rdefosseoai/oai-gnb?label=gNB%20docker%20pulls"></a>
-  <a href="https://hub.docker.com/r/rdefosseoai/oai-nr-ue"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/rdefosseoai/oai-nr-ue?label=NR-UE%20docker%20pulls"></a>
+  <a href="https://hub.docker.com/r/oaisoftwarealliance/oai-gnb"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/oaisoftwarealliance/oai-gnb?label=gNB%20docker%20pulls"></a>
+  <a href="https://hub.docker.com/r/oaisoftwarealliance/oai-nr-ue"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/oaisoftwarealliance/oai-nr-ue?label=NR-UE%20docker%20pulls"></a>
+  <a href="https://hub.docker.com/r/oaisoftwarealliance/oai-enb"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/oaisoftwarealliance/oai-enb?label=eNB%20docker%20pulls"></a>
+  <a href="https://hub.docker.com/r/oaisoftwarealliance/oai-lte-ue"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/oaisoftwarealliance/oai-lte-ue?label=LTE-UE%20docker%20pulls"></a>
 </p>
 
 # OpenAirInterface License #
@@ -32,12 +36,12 @@ Please see [NOTICE](NOTICE.md) file for third party software that is included in
 
 # Where to Start #
 
+ *  [General overview of documentation](./doc/README.md)
  *  [The implemented features](./doc/FEATURE_SET.md)
  *  [How to build](./doc/BUILD.md)
  *  [How to run the modems](./doc/RUNMODEM.md)
 
-More information and documentation can be found in the [doc folder](./doc).
-Unfortunately, not all information is available there, and information for
+Not all information is available in a central place, and information for
 specific sub-systems might be available in the corresponding sub-directories.
 To find all READMEs, this command might be handy:
 
@@ -51,52 +55,20 @@ The OpenAirInterface (OAI) software is composed of the following parts:
 
 ```
 openairinterface5g
+├── charts
 ├── ci-scripts        : Meta-scripts used by the OSA CI process. Contains also configuration files used day-to-day by CI.
+├── CMakeLists.txt    : Top-level CMakeLists.txt for building
 ├── cmake_targets     : Build utilities to compile (simulation, emulation and real-time platforms), and generated build files.
-├── common            : Some common OAI utilities, other tools can be found at openair2/UTILS.
-├── doc               : Contains an up-to-date feature set list and starting tutorials.
-├── executables       : Top-level executable source files.
-├── LICENSE           : License file.
+├── common            : Some common OAI utilities, some other tools can be found at openair2/UTILS.
+├── doc               : Documentation
+├── docker            : Dockerfiles to build for Ubuntu and RHEL
+├── executables       : Top-level executable source files (gNB, eNB, ...)
 ├── maketags          : Script to generate emacs tags.
-├── nfapi             : Contains the NFAPI code. A local Readme file provides more details.
+├── nfapi             : (n)FAPI code for MAC-PHY interface
 ├── openair1          : 3GPP LTE Rel-10/12 PHY layer / 3GPP NR Rel-15 layer. A local Readme file provides more details.
-│   ├── PHY
-│   ├── SCHED
-│   ├── SCHED_NBIOT
-│   ├── SCHED_NR
-│   ├── SCHED_NR_UE
-│   ├── SCHED_UE
-│   └── SIMULATION    : PHY RF simulation.
 ├── openair2          : 3GPP LTE Rel-10 RLC/MAC/PDCP/RRC/X2AP + LTE Rel-14 M2AP implementation. Also 3GPP NR Rel-15 RLC/MAC/PDCP/RRC/X2AP.
-│   ├── COMMON
-│   ├── DOCS
-│   ├── ENB_APP
-│   ├── F1AP
-│   ├── GNB_APP
-│   ├── LAYER2/RLC/   : with the following subdirectories: UM_v9.3.0, TM_v9.3.0, and AM_v9.3.0.
-│   ├── LAYER2/PDCP/PDCP_v10.1.0
-│   ├── M2AP
-│   ├── MCE_APP
-│   ├── NETWORK_DRIVER
-│   ├── NR_PHY_INTERFACE
-│   ├── NR_UE_PHY_INTERFACE
-│   ├── PHY_INTERFACE
-│   ├── RRC
-│   ├── UTIL
-│   └── X2AP
 ├── openair3          : 3GPP LTE Rel10 for S1AP, NAS GTPV1-U for both ENB and UE.
-│   ├── COMMON
-│   ├── DOCS
-│   ├── GTPV1-U
-│   ├── M3AP
-│   ├── MME_APP
-│   ├── NAS
-│   ├── S1AP
-│   ├── SCTP
-│   ├── SECU
-│   ├── TEST
-│   ├── UDP
-│   └── UTILS
-├── radio             : drivers for various radios such as USRP, AW2S, RFsim, ...
-└── targets           : Top-level wrappers for unitary simulation for PHY channels, system-level emulation (eNB-UE with and without S1), and realtime eNB and UE and RRH GW.
+├── openshift         : OpenShift helm charts for some deployment options of OAI
+├── radio             : Drivers for various radios such as USRP, AW2S, RFsim, ...
+└── targets           : Some configuration files; only historical relevance, and might be deleted in the future
 ```

ci-scripts/cls_containerize.py

@@ -1559,17 +1559,6 @@ class Containerize():
 			mySSH.close()
 		if svrName == 'nepes':
 			mySSH.open(ipAddr, userName, password)
-			# Check if route to porcepix epc exists: not necessary, is on same host
-			#mySSH.command('ip route | grep --colour=never "192.168.61.192/26"', '\$', 10)
-			#result = re.search('172.21.16.136', mySSH.getBefore())
-			#if result is None:
-			#	mySSH.command('echo ' + password + ' | sudo -S ip route add 192.168.61.192/26 via 172.21.16.136 dev enp0s31f6', '\$', 10)
-			# Check if X2 route to obelix enb exists: not necessary, gnb is on ofqot
-			#mySSH.command('ip route | grep --colour=never "192.168.68.128/26"', '\$', 10)
-			#result = re.search('172.21.16.128', mySSH.getBefore())
-			#if result is None:
-			#	mySSH.command('echo ' + password + ' | sudo -S ip route add 192.168.68.128/26 via 172.21.16.128 dev enp0s31f6', '\$', 10)
-			# Check if forwarding is enabled
 			# Check if route to ofqot gnb exists
 			mySSH.command('ip route | grep --colour=never "192.168.68.192/26"', '\$', 10)
 			result = re.search('172.21.16.109', mySSH.getBefore())

doc/GET_SOURCES.md

@@ -25,7 +25,7 @@ git config --global user.email "Your email address"
 
 ## In order to clone the Git repository (for OAI Users without login to gitlab server)
 
-Cloning RAN repository (eNB RAN + UE RAN):
+Cloning RAN repository:
 
 ```shell
 git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git
@@ -35,22 +35,18 @@ git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git
 
 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 and provide the identifiant in the email.
+you do not have account on gitlab.eurecom.fr, please register yourself to gitlab.eurecom.fr and provide the login name in the email.
 
-# Which branch to checkout?
-
-On the RAN side:
-
-* **master**: This branch is targeted for the user community. Since January 2019, it is also subject to a Continuous Integration process. The update frequency is about once every 2-3 months. We are also performing bug fixes on this branch.
-* **develop**: This branch contains recent commits that are tested on our CI test bench. The update frequency is about once a week.
+More information can be found in [a separate page](../CONTRIBUTING.md).
 
-Please see the work flow and policies page:
+# Which branch to checkout?
 
-https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/oai-policies-home
+`develop`: contains recent commits that are tested on our CI test bench. The update frequency is about once a week. 5G is only in this branch. It is the recommended  and default branch.
+`master`: contains a stable version of 4G, and will be updated in the future with 5G.
 
-you can find the latest stable tag release here:
+Please see the work flow and policies page: https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/oai-policies-home
 
-https://gitlab.eurecom.fr/oai/openairinterface5g/tags
+You can find the latest stable tag release here: https://gitlab.eurecom.fr/oai/openairinterface5g/tags
 
 The tag naming conventions are:
 
@@ -60,4 +56,3 @@ The tag naming conventions are:
 - On `develop` branch **`yyyy`.w`xx`**
   * `yyyy` is the calendar year
   * `xx` the week number within the year
-

doc/README.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="./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">OpenAirInterface documentation overview</font></b>
+    </td>
+  </tr>
+</table>
+
+[[_TOC_]]
+
+# General
+
+- [FEATURE_SET.md](./FEATURE_SET.md): lists supported features
+- [GET_SOURCES.md](./GET_SOURCES.md): how to download the sources
+- [BUILD.md](./BUILD.md): how to build the sources
+- [clang-format.md](./clang-format.md): how to format the code
+
+There is some general information in the [OpenAirInterface Gitlab Wiki](https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/home)
+
+# Tutorials
+
+- Step-by-step tutorials to set up 5G:
+  * [OAI 5GC](./NR_SA_Tutorial_OAI_CN5G.md)
+  * [OAI gNB with COTS UE](./NR_SA_Tutorial_COTS_UE.md)
+  * [OAI NR-UE](./NR_SA_Tutorial_OAI_nrUE.md)
+- [RUNMODEM.md](./RUNMODEM.md): Generic information on how to
+  * Run simulators
+  * Run with hardware
+  * Specific OAI modes (phy-test, do-ra, noS1)
+  * (5G) Using SDAP and custom DRBs
+  * IF setups and arbitrary frequencies
+  * MIMO
+- [How to run a 5G-SA setup](./TESTING_5GSA_setup.md)
+- [How to run a 5G-NSA setup](./TESTING_GNB_W_COTS_UE.md)
+- [How to run a 4G setup using L1 simulator](./L1SIM.md) _Note: we recommend the RFsimulator_
+- [How to use the L2 simulator](./L2NFAPI.md)
+- [How to use multiple BWPs](./RUN_NR_multiple_BWPs.md)
+- [How to run OAI-VNF and OAI-PNF](./RUN_NR_NFAPI.md) _Note: does not work currently_
+- [How to use the positioning reference signal (PRS)](./RUN_NR_PRS.md)
+- [How to use device-to-device communication (D2D, 4G)](./d2d_emulator_setup.txt)
+
+Legacy unmaintained files:
+- `L2NFAPI_NOS1.md`, `L2NFAPI_S1.md`: old L2simulator, not valid anymore
+- `SystemX-tutorial-design.md`
+- `UL_MIMO.txt`
+
+# Designs
+
+- General software architecture notes: [SW_archi.md](./SW_archi.md)
+- [Information on E1](./E1-design.md)
+- [Information on F1](./F1-design.md)
+- [Information on how NR nFAPI works](./NR_NFAPI_archi.md)
+- [Flow graph of the L1 in gNB](SW-archi-graph.md)
+- [L1 threads in NR-UE](./nr-ue-design.md)
+
+Legacy unmaintained files:
+- 5Gnas.md
+
+# Building and running from images
+
+- [How to build images](../docker/README.md)
+- [How to run 5G with the RFsimulator from images](../ci-scripts/yaml_files/5g_rfsimulator/README.md)
+- [How to run 4G with the RFsimulator from images](../ci-scripts/yaml_files/4g_rfsimulator_fdd_05MHz/README.md)
+- [How to run 5G with the L2simulator from images](../ci-scripts/yaml_files/5g_l2sim_tdd/README.md)
+- [How to run images in OpenShift](../openshift/README.md)
+
+# Libraries
+
+## General
+
+- The [T tracer](https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/T/): a generic tracing tool (VCD, Wireshark, GUI, to save for later, ...)
+- [OPT](../openair2/UTIL/OPT/README.txt): how to trace to wireshark
+- The [configuration module](../common/config/DOC/config.md)
+- The [logging module](../common/utils/LOG/DOC/log.md)
+- The [shared object loader](../common/utils/DOC/loader.md)
+- The [threadpool](../common/utils/threadPool/thread-pool.md) used in L1
+
+## SDRs
+
+Some directories under `radio` contain READMEs:
+
+- [RFsimulator](../radio/rfsimulator/README.md)
+- [USRP](../radio/USRP/README.md)
+- [BladeRF](../radio/BLADERF/README)
+- [IQPlayer](../radio/iqplayer/DOC/iqrecordplayer_usage.md)
+
+The other SDRs (AW2S, LimeSDR, ...) have no READMEs.
+
+## Special-purpose libraries
+
+- OAI comes with an integrated [telnet server](../common/utils/telnetsrv/DOC/telnethelp.md) to monitor and control
+- OAI comes with an integrated [web server](../common/utils/websrv/DOC/websrv.md)
+
+# CI
+
+- [TESTBenches.md](./TESTBenches.md) lists the CI setup and links to pipelines

doc/TESTING_GNB_W_COTS_UE.md

@@ -395,18 +395,3 @@ The following parts have been validated with FR1 COTS UE:
     DL traffic : 3Mbps  
     UL traffic : 1Mbps  
     some packet losses might still occur even in ideal channel conditions  
-
-
-## CI integration  
-The automation scripts are available on ILIADE.  
-The end-to-end test is integrated in the CI flow in a semi-automated manner, comprising 3 steps:  
-- update a YAML file comprising the IT resources definition, branch and commit number the test has to run on   
-- run the python script that generates the test from the YAML file  
-```
-python3 obj_build_from_yaml.py py_params_template.yaml fr1.sh
-```
-- run the test (fr1.sh)
-
-At the date of writing, the test comprises the deployment of the components (epc, eNB, gNB, cots ue) and the execution of 2 pings procedures (20 pings in 20sec, then 5 pings in 1sec)  
-
-This automation is run for every integration branch to be merged into develop.

doc/testbenches_doc_resources/5g-nsa-faraday-bench.tex

@@ -15,27 +15,24 @@
 
   \node[faraday, label={[anchor=south east]above right:Faraday cage}] (faraday) {};
 
-  \node[above left=0cm and 2.8cm of faraday, label=above:obelix] (obelix)
+  \node[above left=-0.50cm and 2.8cm of faraday, label=above:nepes] (nepes)
     {\includegraphics[width=1.2cm]{server}};
-  \node[right=0.3cm of obelix, label=above:B200-mini] (b210o)
-    {\includegraphics[width=1.2cm]{b200-mini}} edge (obelix);
+  \node[right=0.3cm of nepes, label=above:B200-mini] (b210o)
+    {\includegraphics[width=1.2cm]{b200-mini}} edge (nepes);
   \node[below right=0.35cm of faraday.north west] (anto)
     {\includegraphics[width=0.3cm]{antenna}};
   \draw (b210o) -| node [pos=0.2, duplexer] {B7} (anto);
 
-  \node[below left=0cm and 2.8cm of faraday, label=above:nepes] (nepes)
+  \node[below left=-0.50cm and 2.8cm of faraday, label=below:ofqot] (ofqot)
     {\includegraphics[width=1.2cm]{server}};
-  \node[right=0.3cm of nepes, label=above:B200-mini] (b210n)
-    {\includegraphics[width=1.2cm]{b200-mini}} edge (nepes);
-  \draw (obelix) -- (b210o);
+  \node[right=0.3cm of ofqot, label=above:B200-mini] (b210n)
+    {\includegraphics[width=1.2cm]{b200-mini}} edge (ofqot);
+  \draw (nepes) -- (b210o);
   \node[above right=0.35cm of faraday.south west] (antn)
     {\includegraphics[width=0.3cm]{antenna}};
   \draw (b210n) -| node [pos=0.2, duplexer] {n78} (antn);
 
-  \node[left=5cm of faraday, label=above:porcepix] (porcepix)
-    {\includegraphics[width=1.2cm]{server}};
-  \draw (obelix) -- (porcepix);
-  \draw (nepes) -- (porcepix);
+  \draw (nepes) -- (ofqot);
 
   \node[right=1.5cm of faraday, label=above:RM500Q-GL] (quectel)
     {\includegraphics[height=1.2cm]{quectel}};

doc/testbenches_doc_resources/5g-ota-bench.tex

@@ -16,7 +16,7 @@
   \node[label=above:porcepix] (porcepix)
     {\includegraphics[width=1.2cm]{server}};
 
-  \node[above right=1cm and 2cm of porcepix, label=above:asterix] (asterix)
+  \node[above right=-0.4cm and 2cm of porcepix, label=above:asterix] (asterix)
     {\includegraphics[width=1.2cm]{server}}
     edge (porcepix);
   \node[right=0.3cm of asterix, label=above:N310] (n310a)
@@ -27,7 +27,7 @@
   \node[above right=-0.1cm and 0.35cm of b78o.east] (anto2)
     {\includegraphics[width=0.3cm]{antenna}} edge (b78o);
 
-  \node[right=2cm of porcepix, label=above:obelix] (obelix)
+  \node[below right=-0.4cm and 2cm of porcepix, label=above:obelix] (obelix)
     {\includegraphics[width=1.2cm]{server}}
     edge (porcepix);
   \node[above right=-0.5cm and 0.3cm of obelix, label=above:N310] (n310o)
@@ -45,7 +45,7 @@
   \node[above right=-0.1cm and 0.35cm of b78o.east] (anto2)
     {\includegraphics[width=0.3cm]{antenna}} edge (b78o);
 
-  \node[above right=-1.3cm and 5.0cm of n310a.east, label=above:RM500Q-GL] (quectel)
+  \node[above right=-0.5cm and 5.0cm of n310o.east, label=above:RM500Q-GL] (quectel)
     {\includegraphics[height=1.2cm]{quectel}};
   \node[above left=-0.1cm and 0.8cm of quectel.west] (aq2)
     {\includegraphics[width=0.3cm]{antenna}} edge (quectel);
@@ -59,10 +59,5 @@
     {\includegraphics[width=1.2cm]{server}}
     edge (quectel);
 
-  \node[above right=-0.3cm and 5.0cm of x310o.east, label=above:amariue] (amariue)
-    {\includegraphics[height=1.2cm]{server}};
-  \node[left=0.8cm of amariue.west] (aa1)
-    {\includegraphics[width=0.3cm]{antenna}} edge (amariue);
-
 \end{tikzpicture}
 \end{document}