From 03b63257f206b703213ebf663dc580487743076a Mon Sep 17 00:00:00 2001 From: Robert Schmidt Date: Tue, 20 Feb 2024 16:33:03 +0100 Subject: [PATCH] Add documentation for nFAPI --- doc/MAC/mac-usage.md | 4 +- doc/README.md | 3 +- doc/RUN_NR_NFAPI.md | 54 -------------- doc/environment-variables.md | 2 +- doc/nfapi.md | 137 +++++++++++++++++++++++++++++++++++ 5 files changed, 142 insertions(+), 58 deletions(-) delete mode 100644 doc/RUN_NR_NFAPI.md create mode 100644 doc/nfapi.md diff --git a/doc/MAC/mac-usage.md b/doc/MAC/mac-usage.md index 31461f68eb..c3dbd6f199 100644 --- a/doc/MAC/mac-usage.md +++ b/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. diff --git a/doc/README.md b/doc/README.md index c4b24f39ec..2e84db217c 100644 --- a/doc/README.md +++ b/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) diff --git a/doc/RUN_NR_NFAPI.md b/doc/RUN_NR_NFAPI.md deleted file mode 100644 index 5b597aa326..0000000000 --- a/doc/RUN_NR_NFAPI.md +++ /dev/null @@ -1,54 +0,0 @@ -# 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 - -``` - diff --git a/doc/environment-variables.md b/doc/environment-variables.md index 31520b0a2d..9778665afe 100644 --- a/doc/environment-variables.md +++ b/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) diff --git a/doc/nfapi.md b/doc/nfapi.md new file mode 100644 index 0000000000..366b5fb4ac --- /dev/null +++ b/doc/nfapi.md @@ -0,0 +1,137 @@ +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.