Add documentation for nFAPI

doc/MAC/mac-usage.md

@@ -145,8 +145,8 @@ In the last lines:
 
 ## Split-related options (running in a DU)
 
-See [nFAPI documentation](../L2NFAPI.md) or [Aerial
-tutorial](../Aerial_FAPI_Split_Tutorial.md) for information about the FAPI
+See [nFAPI documentation](../nfapi.md) or [Aerial
+tutorial](../Aerial_FAPI_Split_Tutorial.md) for information about the (n)FAPI
 split.
 
 See [F1 documentation](../F1-design.md) for information about the F1 split.

doc/README.md

@@ -57,7 +57,8 @@ There is some general information in the [OpenAirInterface Gitlab Wiki](https://
 - [How to use the L2 simulator](./L2NFAPI.md)
 - [How to use the OAI channel simulator](../openair1/SIMULATION/TOOLS/DOC/channel_simulation.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 run OAI-VNF and OAI-PNF](./nfapi.md): how to run the nFAPI split,
+  including some general remarks on FAPI/nFAPI.
 - [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)
 - [How to run with E2 agent](../openair2/E2AP/README.md)

doc/RUN_NR_NFAPI.md

-# Procedure to run nFAPI in 5G NR
-
-## Contributed by 5G Testbed IISc 
-
-### Developers: Gokul S, Mahesh A, Aniq U R
-
-## Procedure to Build gNB and UE
-
-The regular commands to build gNB and UE can be used
-```
-sudo ./build_oai --gNB --nrUE
-
-```
-## Procedure to run NR nFAPI using RF-Simulator
-
-### Bring up another loopback interface
-
-If running for the first time on your computer, or you have restarted your computer, bring up another loopback interface with this command:  
-
-sudo ifconfig lo: 127.0.0.2 netmask 255.0.0.0 up
-
-### VNF command
-```
-sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/rcc.band78.tm1.106PRB.nfapi.conf --nfapi VNF --noS1 --phy-test
-
-```
-### PNF command
-```
-sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/oaiL1.nfapi.usrpx300.conf --nfapi PNF --rfsim --phy-test --rfsimulator.serveraddr server
-
-```
-### UE command
-```
-sudo ./nr-uesoftmodem --rfsim --phy-test -d --rfsimulator.serveraddr 127.0.0.1
-
-```
-## Procedure to run NR nFAPI using Hardware (tested with USRP x310)
-
-### VNF command
-```
-sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/rcc.band78.tm1.106PRB.nfapi.conf --nfapi VNF --noS1 --phy-test
-
-```
-### PNF command
-```
-sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/oaiL1.nfapi.usrpx300.conf --nfapi PNF --phy-test
-
-```
-### UE command
-```
-sudo ./nr-uesoftmodem --usrp-args "addr=*USRP_ADDRESS*,clock_source=external,time_source=external" --phy-test
-
-```
-

doc/environment-variables.md

@@ -2,7 +2,7 @@
 
 OAI uses/supports a number of environment variables, documented in the following:
 
-- `NFAPI_TRACE_LEVEL`: set the nfapi custom logging framework's log level; can be one of `error`, `warn`, `note`, `info`, `debug`
+- `NFAPI_TRACE_LEVEL`: set the nfapi custom logging framework's log level; can be one of `error`, `warn`, `note`, `info`, `debug`. Default is `warn`.
 - `NR_AWGN_RESULTS_DIR`: directory containing BLER curves for L2simulator channel modelling in SISO case
 - `NR_MIMO2x2_AWGN_RESULTS_DIR`: directory containing BLER curves for L2simulator channel modelling in 2x2 MIMO case
 - `NVRAM_DIR`: directory to read/write NVRAM data in (5G) `nvram` tool; if not defined, will use `PWD` (working directory)

doc/nfapi.md

+This document describes the SmallCellForum (SCF) (n)FAPI split in 5G, i.e.,
+between the MAC/L2 and PHY/L1.
+
+The interested reader is recommended to read a copy of the SCF 222.10
+specification ("FAPI"). This includes information on what is P5, P7, and how
+FAPI works. The currently used version is SCF 222.10.02, with some messages
+upgraded to SCF 222.10.04 due to bugfixes in the spec. Further information
+about nFAPI can be found in SCF 225.2.0.
+
+# Quickstart
+
+Compile OAI as normal. Start the CN and make sure that the VNF configuration
+matches the PLMN/IP addresses. Then, run the VNF
+
+    sudo NFAPI_TRACE_LEVEL=info ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb-vnf.sa.band78.106prb.nfapi.conf --nfapi VNF
+
+Afterwards, start and connect the PNF
+
+    sudo NFAPI_TRACE_LEVEL=info ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb-pnf.band78.rfsim.conf --nfapi PNF --rfsim
+
+Finally, you can start the UE (observe the radio configuration info in the
+VNF!)
+
+    sudo ./nr-uesoftmodem -r 106 --numerology 1 --band 78 -C 3619200000 -O ue.conf
+
+You should not observe a difference between nFAPI split and monolithic.
+
+
+# Status
+
+All FAPI message can be transferred between VNF and PNF. This is because OAI
+uses FAPI with its corresponding messages internally, whether a split is in use
+or not.
+
+The nFAPI split mode supports any radio configuration that is also supported by
+the monolithic gNB, with the notable exceptions that only numerologies of 15kHz
+and 30kHz (mu=0 and mu=1, respectively) are supported.
+
+The VNF requests to be notified about every slot by the PNF. No delay
+management is employed as of now; instead, the PNF sends a Slot.indication to
+the VNF in every slot (in divergence from the nFAPI spec). 
+
+Currently, downlink transmissions work the same in monolithic and nFAPI. In
+uplink, we observe an increased number of retransmissions, which limits the MCS
+and hence the achievable throughput (which is limited to 10-20Mbps). We are still
+debugging the root cause of this.
+
+After stopping the PNF, you also have to restart the VNF.
+
+When using RFsim, the system might run slower than in monolithic. This is
+because the PNF needs to slow down the execution time of a specific slot,
+because it has to send a Slot.indication to the VNF for scheduling.
+
+# Configuration
+
+Both PNF and VNF are run through the `nr-softmodem` executable. The type of
+mode is switched through the `--nfapi` switch, with options `MONOLITHIC`
+(default if not provided), `VNF`, `PNF`.
+
+If the type is `VNF`, you have to modify the `MACRLCs.tr_s_preference`
+(transport south preference) to `nfapi`. Further, configure these options:
+
+- `MACRLCs.remote_s_address` (remote south address): IP of the PNF
+- `MACRLCs.local_s_address` (local south address): IP of the VNF
+- `MACRLCs.local_s_portc` (local south port for control): VNF's P5 local port
+- `MACRLCs.remote_s_portc` (remote south port for data): PNF's P5 remote port
+- `MACRLCs.local_s_portd` (local south port for control): VNF's P5 local port
+- `MACRLCs.remote_s_portd` (remote south port for data): PNF's P7 remote port
+
+Note that any L1-specific section (`L1s`, `RUs`,
+RFsimulator-specific/IF7.2-specific configuration or other radios, if
+necessary) will be ignored and can be deleted.
+
+If the type is `PNF`, you have to modify modify the `L1s.tr_n_preference`
+(transport north preference) to `nfapi`. Further, configure these options:
+
+- `L1s.remote_n_address` (remote north address): IP of the VNF
+- `L1s.local_n_address` (local north address): IP of the PNF
+- `L1s.local_n_portc` (local north port for control): PNF's P5 local port
+- `L1s.remote_n_portc` (remote north port for control): VNF's P5 remote port
+- `L1s.local_n_portd` (local north port for data): PNF's P7 local port
+- `L1s.remote_n_portd` (remote north port for data): VNF's P7 remote port
+
+Note that this file should contain additional, L1-specific sections (`L1s`,
+`RUs` RFsimulator-specific/IF7.2-specific configuration or other radios, if
+necessary).
+
+To split an existing config file `monolithic.conf` for nFAPI operation, you
+can proceed as follows:
+
+- copy `monolithic.conf`, which will be your VNF file (`vnf.conf`)
+- in `vnf.conf`
+  * modify `MACRLCs` section to configure south-bound nFAPI transport
+  * delete `L1s`, `RUs`, and radio-specific sections.
+  * in `gNBs` section, increase the `ra_ResponseWindow` by one to extend the RA
+    window: this is necessary because the PNF triggers the scheduler in the VNF
+    in advance, which might make the RA window more likely to run out
+- copy `monolithic.conf`, which will be your PNF file (`pnf.conf`)
+- in `pnf.conf`
+  * modify `L1s` section to configure north-bound nFAPI transport (make sure it
+    matches the `MACRLCs` section for `vnf.conf`
+  * delete all the `gNBs`, `MACRLCs`, `security` sections (they are not needed)
+- if you have root-level options in `monolithic.conf`, such as
+  `usrp-tx-thread-config` or `tune-offset`, make sure to to add them to
+  `pnf.conf`, or provide them on the command line for the PNF.
+- to run, proceed as described in the quick start above.
+
+Note: all L1-specific options have to be passed to the PNF, and remaining
+options to the VNF.
+
+# nFAPI logging system
+
+nFAPI has its own logging system, independent of OAI's. It can be activated by
+setting the `NFAPI_TRACE_LEVEL` environment variable to an appropriate value;
+see [the environment variables documentation](./environment-variables.md) for
+more info.
+
+To see the (any) periodical output at the PNF, define `NFAPI_TRACE_LEVEL=info`.
+This output shows:
+
+```
+41056.739654 [I] 3556767424: pnf_p7_slot_ind: [P7:1] msgs ontime 489 thr DL 0.06 UL 0.01 msg late 0 (vtime)
+```
+
+The first numbers are timestamps. `pnf_p7_slot_ind` is the name of the
+functions that prints the output. `[P7:1]` refers to the fact that these are
+information on P7, of PHY ID 1. Finally, `msgs ontime 489` means that in the
+last window (since the last print), 489 messages arrived at the PNF in total.
+The combined throughput of `TX_data.requests` (DL traffic) was 0.06 Mbps; note
+that this includes SIB1 and other periodical data channels. In UL, 0.01 Mbps
+have been sent through `RX_data.indication`. `msg late 0` means that 0 packets
+have been late. _This number is an aggregate over the total runtime_, unlike
+the other messages. Finally, `(vtime)` is a reminder that the calculations are
+done over virtual time, i.e., frames/slots as executed by the 5G Systems. For
+instance, these numbers might be slightly higher or slower in RFsim than in
+wall-clock time, depending if the system advances faster or slower than
+wall-clock time.