Merge remote-tracking branch 'origin/doc-l1sim-rfsim' into integration_2024_w01

doc/L1SIM.md

@@ -12,23 +12,29 @@
   </tr>
 </table>
 
-This page is valid for the develop branch
+**Note: unless you know what you are doing, you likely do not need this!
+Rather, you are probably looking for the
+[RFsimulator](../radio/rfsimulator/README.md)!**
 
-**Table of Contents**
+oaisim has been scraped and replaced by the same programs that are used for the
+real-time operation, `lte-softmodem` and `lte-uesoftmodem`. This uses the IF4p5
+fronthaul protocol to achieve the communication.
 
-[[_TOC_]]
-
-The old oaisim is dead! Long live oaisim! :)
+Context: oaisim used to be a simulation mode inside OAI to emulate an eNB and
+multiple UEs.
 
-If you are looking for a description of the old oaisim (which is still available in some branches/tags), please see [here](OpenAirLTEEmulation) and [here](how-to-run-oaisim-with-multiple-ue).
+[[_TOC_]]
 
-oaisim has been scraped and replaced by the same programs that are used for the real-time operation, `lte-softmodem` and `lte-uesoftmodem`. The latter also now includes an optional channel model, just like oaisim did. 
+# Build
 
-# <a name="build">[How to build the eNB and the UE](BUILD.md)</a>
+Build eNB/UE as normal, as also described in [How to build the eNB and the UE](./BUILD.md):
+```bash
+./build_oai -c --ninja --eNB --UE
+```
 
-The following paragraph explains how to run the L1 simulator in noS1 mode and using the oai kernel modules. 
+# How to run an eNB with the noS1 option
 
-# <a name="run-noS1-eNB">How to run an eNB with the noS1 option</a>
+The following paragraph(s) explains how to run the L1 simulator in noS1 mode and using the oai kernel modules.
 
 Modify the configuration file for IF4p5 fronthaul, `/openairinterface5g/ci-scripts/conf_files/rcc.band7.nos1.simulator.conf`, and replace the loopback interface with a physical ethernet interface and the IP addresses to work on your network. Copy your modifications to a new file, let's call YYY.conf the resulting configuration file.
 
@@ -42,7 +48,7 @@ $ cd ../ran_build/build
 $ sudo -E ./lte-softmodem -O YYY.conf --noS1 --nokrnmod 0
 ```
 
-# <a name="run-noS1-UE">How to run a UE with the noS1 option</a>
+# How to run a UE with the noS1 option
 
 Similarly modify the example configuration file in `/openairinterface5g/ci-scripts/conf_files/rru.band7.nos1.simulator.conf` and replace loopback interface and IP addresses. Copy your modifications to a new file, let's call XXX.conf the resulting configuration file.
 
@@ -58,38 +64,17 @@ $ sudo ./lte-uesoftmodem -O XXX.conf -r 25 --siml1 --noS1 --nokrnmod 0
 
 That should give you equivalent functionality to what you had with oaisim including noise and RF channel emulation (path loss / fading, etc.). You should also be able to run multiple UEs. 
 
-# <a name="CInote">Continuous Integration notes</a>
-The CI currently tests the noS1 build option with one eNB and one UE in the following scenarios:
-* pinging one UE from one eNB
-* pinging one eNB from one UE
-* iperf download between one eNB and one UE
-* iperf upload between one eNB and one UE
-* all the above tests are done in FDD 5Mhz mode.
-
-# <a name="noS1-pinging">How to ping an eNB from a UE and vice versa (with the noS1 option)</a>
+# How to ping an eNB from a UE and vice versa (with the noS1 option)
 
 Once your eNB and UE (built with the noS1 option) are running and synchronised, you can ping the eNB from the UE with the following command:
 
 ```bash
 ping -I oai0 -c 20 $eNB_ip_addr
 ```
-where $eNB_ip_addr is the IP address of your eNB.
+where `$eNB_ip_addr` is the IP address of your eNB.
 
 Similarly, you can ping the UE from the eNB.
 
-The IP adresses of the eNB and the UE are set up by the init_nas_nos1 program and should have the following values:
-* eNB_ip_addr set to 20 10.0.1.1
-* ue_ip_addr set to 20 10.0.1.2
-
-
-
-
-
-
-
-[oai wiki home](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/home)
-
-[oai softmodem features](FEATURE_SET.md)
-
-[oai softmodem build procedure](BUILD.md)
-
+The IP adresses of the eNB and the UE are set up by the `init_nas_nos1` program and should have the following values:
+* `$eNB_ip_addr` set to 10.0.1.1
+* `ue_ip_addr` set to 10.0.1.2

doc/RUNMODEM.md

@@ -7,12 +7,18 @@
       </a>
     </td>
     <td style="border-collapse: collapse; border: none; vertical-align: center;">
-      <b><font size = "5">Running OAI Softmodems</font></b>
+      <b><font size = "5">Running OAI 5G Softmodems</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/ran_build/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. 
+This document explains some options for running 5G executables.
+
+After you have [built the softmodem executables](BUILD.md) you can set your
+default directory  to the build directory `cmake_targets/ran_build/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.
 
 [[_TOC_]]
 
@@ -20,28 +26,27 @@ After you have [built the softmodem executables](BUILD.md) you can set your defa
 
 ## RFsimulator
 
-The RF simulator is an OAI device replacing the radio heads (for example the USRP device). It allows connecting the oai UE (LTE or 5G) and respectively the oai eNodeB or gNodeB 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 has some preliminary support for channel modeling.
+The RFsimulator is an OAI device replacing the radio heads (for example the
+USRP device). It allows connecting the oai UE (LTE or 5G) and respectively the
+oai eNodeB or gNodeB 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 RFsimulator has some preliminary support for channel modeling.
 
 It is planned to enhance this simulator with the following functionalities:
 
 - Support for multiple eNodeB's or gNodeB's for hand-over tests
 
-This is an easy use-case to setup and test, as no specific hardware is required. The [rfsimulator page](../radio/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](../radio/rfsimulator/README.md) contains the detailed documentation.
 
 ## 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 simulator page](L2NFAPI.md) contains the detailed documentation.
-
-## L1 Simulator
-
-**This information might be outdated. We recommend to use the RFsimulator as
-shown above.**
+This simulator connects an eNodeB and UEs through an 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).
 
-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.
+As for the RFsimulator, no specific hardware is required. The [L2 nfapi
+simulator page](./L2NFAPI.md) contains the detailed documentation.
 
 # Running with a true radio head
 
@@ -89,7 +94,7 @@ At the UE the --sa flag will:
   4) 5G-NR RRC Reconfiguration
   5) Start Downlink and Uplink Data Transfer
 
-Command line parameters for UE in --sa mode:
+Command line parameters for UE in `--sa` mode:
 - `-C` : downlink carrier frequency in Hz (default value 0)
 - `--CO` : uplink frequency offset for FDD in Hz (default value 0)
 - `--numerology` : numerology index (default value 1)
@@ -104,7 +109,7 @@ sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band
 sudo ./nr-uesoftmodem -r 106 --numerology 1 --band 78 -C 3619200000 --ssb 516 --sa
 ```
 
-With the RF simulator (on the same machine):
+With the RFsimulator (on the same machine):
 
 ```bash
 sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.usrpb210.conf --gNBs.[0].min_rxtxtime 6 --rfsim --sa
@@ -117,11 +122,15 @@ Additionally, at UE side `--uecap_file` option can be used to pass the UE Capabi
 
 Some other useful paramters of the UE are
 
- - --ue-fo-compensation: enables the frequency offset compenstation at the UE. This is useful when running over the air and/or without an external clock/time source
- - --usrp-args: this is the equivalend paramter of sdr_addrs field in the gNB config file and can be used to identify the USRP and set some basic paramters (like the clock source)
- - --clock-source: sets the clock-source (internal or external). 
- - --time-source: sets the time-source (internal or external). 
+- `--ue-fo-compensation`: enables the frequency offset compenstation at the UE. This is useful when running over the air and/or without an external clock/time source
+- `--usrp-args`: this is the equivalend paramter of `sdr_addrs` field in the gNB config file and can be used to identify the USRP and set some basic paramters (like the clock source)
+- `--clock-source`: sets the clock-source (internal or external).
+- `--time-source`: sets the time-source (internal or external).
 
+You can see all options by typing
+```
+./nr-uesoftmodem --help
+```
 
 # Specific OAI modes
 
@@ -154,9 +163,31 @@ In phy-test mode it is possible to mimic the reception of UE Capabilities at gNB
 
 ## noS1 setup with OAI UE
 
-Instead of randomly generated payload, in the phy-test mode we can also inject/receive user-plane traffic over a TUN interface. This is the so-called noS1 mode. 
+Instead of randomly generated payload, in the phy-test mode we can also
+inject/receive user-plane traffic over a TUN interface. This is the so-called
+noS1 mode.
 
-This setup is described in the [rfsimulator page](../radio/rfsimulator/README.md#5g-case). In theory this should also work with the real hardware target although this has yet to be tested.
+The noS1 mode is applicable to both gNB/UE, and enabled by passing `--noS1` as
+an option. The gNB/UE will open a TUN interface which the interface names and
+IP addresses `oaitun_enb1`/10.0.1.1, and `oaitun_ue1`/10.0.1.2, respectively.
+You can then use these interfaces to send traffic, e.g.,
+```bash
+iperf -sui1 -B 10.0.1.2
+```
+to open an iperf server on the UE side, and
+```bash
+iperf -uc 10.0.1.2 -B 10.0.1.1 -i1 -t10 -b1M
+```
+to send data from the gNB down to the UE.
+
+Note that this does not work if both interfaces are on the same host. We
+recommend to use two different hosts, or at least network namespaces, to route
+traffic through the gNB/UE tunnel.
+
+This option is only really helpful for phy-test/do-ra (see below) modes, in
+which the UE does not connect to a core network. If the UE connects to a core
+network, it receives an IP address for which it automatically opens a network
+interface.
 
 ## do-ra setup with OAI
 
@@ -244,7 +275,3 @@ The DL logical antenna port configuration can be selected through configuration
 Finally the number of TX physical antenna in the RU part of the configuration file, `nb_tx`, should be equal or larger than the total number of PDSCH logical antenna ports.
 
 [Example of configuration file with parameters for 2-layer MIMO](https://gitlab.eurecom.fr/oai/openairinterface5g/-/blob/develop/targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band77.fr1.273PRB.2x2.usrpn300.conf)
-
-# Additional links
-
-[Selecting an alternative ldpc implementation at run time](../openair1/PHY/CODING/DOC/LDPCImplementation.md)