diff --git a/doc/RUNMODEM.md b/doc/RUNMODEM.md index e5adde0010..6fcf415364 100644 --- a/doc/RUNMODEM.md +++ b/doc/RUNMODEM.md @@ -1,143 +1,250 @@ -# Running OAI 5G Softmodems +# Running the OAI 5G gNB (nr-softmodem) -This document explains some options for running 5G executables. +This document is a general overview of running `nr-softmodem`, the OAI 5G +gNodeB executable. For build instructions see [BUILD.md](BUILD.md). For UE +documentation see [runmodem-nrue.md](runmodem-nrue.md). -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. -> **Note:** UE documentation previously found in this document has been moved -> to [a separate page](./runtmodem-nrue.md) - -> **Note:** NTN-specific configuration steps previously found in this document -> have been moved to [a separate page](./ntn-configuration.md) [[_TOC_]] -## Simulators +## Modes of operation + +`nr-softmodem` supports several deployment modes. The default is "standalone" +mode. + +| Option | Mode | Description | +|----------|------------|-------------| +| _none_ | standalone | Run gNB in SA mode (no flag). | +| `--nsa` | NSA | Non-standalone mode, requires an LTE eNB, see [NSA documentation](TESTING_OAI_NSA_COTS_UE.md). | +| phy-test | `--phy-test` | Test modes without random access, see [nrUE page](runmodem-nrue.md). | +| do-ra | `--do-ra` | Test mode without a core network or RRC connection, see [nrUE page](runmodem-nrue.md). | +| noS1 | `--noS1` | Manually inject traffic, suitable for phy-test/do-ra without core network. | + +## Basic invocation + +From the build directory (with `build_oai`, by default `cmake_targets/ran_build/build/`): + +```bash +sudo ./nr-softmodem -O [options] +``` + +Example with a USRP B210: +```bash +sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.usrpb210.conf -E --continuous-tx +``` + +CI-tested sample configuration files are in `ci-scripts/conf_files/`. Sample +configuration files for various hardware can be found under +`targets/PROJECTS/GENERIC-NR-5GC/CONF/`. + +## Configuration file + +The configuration file can use either libconfig (`.conf`) or YAML (`.yaml`) +syntax, based on the file ending. The main sections are: + +- `gNBs`: cell identity, PLMN, physical cell parameters, AMF address +- `MACRLCs`: MAC/RLC layer settings +- `L1s`: L1 layer settings and thread pinning +- `RUs`: radio unit configuration (device selection, antennas, gains) +- `security`: ciphering and integrity algorithm preferences +- `log_config`: per-module log levels + +Individual parameters can be overridden on the command line using the +`--Section.[index].param value` syntax, e.g. +`--gNBs.[0].min_rxtxtime 6`. + +### Core network connectivity + +In the `gNBs` section, set the following to connect to a 5G core (AMF): + +``` +gNBs = ( +{ + tracking_area_code = 1; + plmn_list = ({ mcc = 001; mnc = 01; mnc_length = 2; snssaiList = ({ sst = 1; sd = 0xffffff; }) }); + nr_cellid = 12345678L; + + amf_ip_address = ({ ipv4 = "192.168.70.132"; }); + + NETWORK_INTERFACES : + { + GNB_IPV4_ADDRESS_FOR_NG_AMF = "192.168.70.129"; // N2 interface + GNB_IPV4_ADDRESS_FOR_NGU = "192.168.70.129"; // N3 interface + GNB_PORT_FOR_S1U = 2152; + }; +}); +``` + +- `plmn_list` must match the PLMN configured in the AMF. +- `amf_ip_address` is the IP address of the AMF. +- `GNB_IPV4_ADDRESS_FOR_NG_AMF` is the local IP address of the gNB's N2 interface. +- `GNB_IPV4_ADDRESS_FOR_NGU` is the local IP address of the gNB's N3 interface. + +### MAC configuration + +In the `MACRLCs` section, configure MAC parameters. See the [MAC user +documentation](MAC/mac-usage.md) for more information. + +### L1 configuration + +The `L1s` section configures the L1 (physical layer) processing pipeline. + +- `tr_n_preference`: transport to the MAC layer. Normally `local_mac` (shared + memory). Set to `nfapi` for a networked L1/MAC split; see [nFAPI docs](nfapi.md). +- `prach_dtx_threshold`: energy threshold (in dB x10) for PRACH preamble detection. Lower + values increase sensitivity but may cause false detections. Typical range: + 60–200. +- `pucch0_dtx_threshold`: energy threshold for PUCCH format 0 (SR/HARQ-ACK) + detection. Similar trade-off as `prach_dtx_threshold`. Typical range: 10–100. +- `pusch_dtx_threshold`: energy threshold for PUSCH detection. Similar + trade-off as `prach_dtx_threshold`. Typical range: 10–100. +- `ofdm_offset_divisor`: controls a small timing advance applied to the OFDM + signal to ensure samples arrive before the processing deadline. Set to + `UINT_MAX` (i.e., `4294967295`) for zero offset; a value of `8` gives an + offset of `frame_length / 8`. The default value of `8` works well in most + cases. +- `max_ldpc_iterations`: maximum number of LDPC decoder iterations. Fewer + iterations reduce CPU load at the cost of UL error rate. Default is 8, but + might be as high as 20 or more.. +- `L1_rx_thread_core` / `L1_tx_thread_core`: pin the L1 RX and TX threads to + specific isolated CPU cores. Recommended for real-time performance, especially + with O-RAN 7.2 fronthaul. +- `phase_compensation` (FHI 7.2 only): set to `0` if phase compensation is done + in the O-RU, `1` if it should be done in the DU (software). Must match the + O-RU configuration. +- `tx_amp_backoff_dB` (FHI 7.2 only): output amplitude backoff in dB relative + to full scale. Must be set according to the O-RU vendor documentation to avoid + exceeding the RU's power limits. + +### RU configuration + +The `RUs` section describes the radio unit, i.e., either an integrated RF device +(split 8 radio) or a remote RU connected via a fronthaul interface (e.g., O-RU). + +- `local_rf`: `"yes"` for a locally attached RF device (USRP, etc.), `"no"` + for a remote RU (e.g., O-RAN 7.2 fronthaul). +- `nb_tx` / `nb_rx`: number of TX and RX antenna ports. Must be consistent with + the antenna port configuration in `gNBs` (see [MIMO section](#5g-gnb-mimo-configuration)). +- `att_tx` / `att_rx`: software attenuation applied to TX/RX samples in dB. + Used to reduce signal levels in software before they reach the RF device. +- `bands`: list of NR band numbers this RU operates on, e.g. `[78]`. +- `max_pdschReferenceSignalPower`: maximum PDSCH reference signal power in dBm. + Used by the UE for path loss estimation. Should match the actual transmit + power level. +- `max_rxgain`: maximum RX gain of the RF device in dB. This is the hardware + gain limit; the actual gain used may be lower. +- `clock_src`: clock reference source. `"internal"` uses the device's own + oscillator; `"external"` expects an external 10 MHz reference; `"gpsdo"` + uses a GPS-disciplined oscillator. Applicable only for USRP. +- `sdr_addrs`: device address string passed to the RF driver. Used notably with + USRP and BladeRF devices. +- `ru_thread_core`: CPU core for the RU fronthaul thread. Should + be an isolated core (FHI 7.2 only). + +### Frequency and cell configuration + +Key parameters in `servingCellConfigCommon`: + +- `absoluteFrequencySSB` / `dl_absoluteFrequencyPointA`: DL frequency in NR-ARFCN for SSB and PointA +- `dl_frequencyBand` / `ul_frequencyBand`: NR band number +- `dl_carrierBandwidth` / `ul_carrierBandwidth`: bandwidth in PRBs +- `dl_subcarrierSpacing`: subcarrier spacing (0=15 kHz, 1=30 kHz, 2=60 kHz, 3=120 kHz) +- `ssPBCH_BlockPower`: SSB transmit power in dBm (EPRE of SSB resource elements) +- `prach_ConfigurationIndex`, `prach_msg1_FrequencyStart`: PRACH configuration + +For a reference of frequency parameters and band configurations see +[gNB frequency setup](gNB_frequency_setup.md). + +### Security + +The `security` section controls NAS/AS security algorithm selection: + +``` +security = { + # preferred ciphering algorithms + # the first one of the list that an UE supports in chosen + # valid values: nea0, nea1, nea2, nea3 + ciphering_algorithms = ( "nea0" ); + + # preferred integrity algorithms + # the first one of the list that an UE supports in chosen + # valid values: nia0, nia1, nia2, nia3 + integrity_algorithms = ( "nia2", "nia0" ); + + # setting 'drb_ciphering' to "no" disables ciphering for DRBs, no matter + # what 'ciphering_algorithms' configures; same thing for 'drb_integrity' + drb_ciphering = "yes"; + drb_integrity = "no"; +}; +``` + +## Common radio devices ### RFsimulator -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. +The RFsimulator replaces the radio device with a virtual radio, allowing +gNB and UE to run without hardware. Built by default. Ideal for testing, +debugging, and development. Add `--rfsim` to the command line. -It is planned to enhance this simulator with the following functionalities: +See the [RFsimulator documentation](../radio/rfsimulator/README.md). -- Support for multiple eNodeB's or gNodeB's for hand-over tests +### USRP (B2xx, N3xx, X3xx, x4xx) -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. +Build with `build_oai -w USRP`/`cmake -DOAI_USRP=ON`. The device is selected +automatically. Common per-device recommendations: -### L2 nFAPI Simulator - -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). - -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 - -OAI supports different radio heads, the following are tested in the CI: - -1. [Monolithic eNodeB](https://gitlab.eurecom.fr/oai/openairinterface5g/wikis/HowToConnectCOTSUEwithOAIeNBNew) where the whole signal processing is performed in a single process -2. IF4P5 mode, where frequency domain samples are carried over ethernet, from the RRU which implement part of L1(FFT,IFFT,part of PRACH), to a RAU -3. Monolithic gNodeB: see next section, or the [standalone tutorial](NR_SA_Tutorial_COTS_UE.md) - - -## 5G NR - -### NSA setup - -Please refer to the [corresponding page](./TESTING_OAI_NSA_COTS_UE.md) for more -information on how to run in NSA mode: - -### SA setup with OAI NR-UE - -The standalone mode is the default mode. - -Before tag `2024.w45`, the default mode was NSA. Thus, in the past, to run -either the gNB or the UE in standalone mode, it was necessary to provide the -`--sa` flag in the command line. This is not the case anymore. If provided -the softmodem exits reporting that it does not know this option. - -The default (SA) mode does the following: -- At the gNB: -* The RRC encodes SIB1 according to the configuration file and transmits it through NR-BCCH-DL-SCH. - -- At the UE: -* Decode SIB1 and starts the 5G NR Initial Access Procedure for SA: - 1) 5G-NR RRC Connection Setup - 2) NAS Authentication and Security - 3) 5G-NR AS Security Procedure - 4) 5G-NR RRC Reconfiguration - 5) Start Downlink and Uplink Data Transfer - -### Other/Special modes to run with OAI NR-UE - -The gNB/nrUE support a number of special modes (phy-test, do-ra, noS1) that -cannot be used with COTS UE. As they specifically require the use of the OAI -nrUE, these modes are described [on the UE page](./runmodem-nrue.md). - -### Common gNB and NR UE command line options - -#### Three-quarter sampling - -The command line option `-E` can be used to enable three-quarter sampling for split 8 sample rate. Required for certain radios (e.g., 40MHz with B210). If used on the gNB, it is a good idea to use for the UE as well (and vice versa). - -#### Run OAI with SDAP & Custom DRBs - -SDAP is enabled by default. To disable SDAP, include `--gNBs.[0].enable_sdap 0` to the binary's arguments. - -The DRB creation is dependent on the 5QI. -If the 5QI corresponds to a GBR Flow it assigns a dedicated data radio bearer. -The Non-GBR flows use a shared data radio bearer. - -To hardcode the DRBs for testing purposes, simply add `--gNBs.[0].drbs x` to the binary's arguements, where `x` is the number of DRBs, along with SDAP. -The hardcoded DRBs will be treated like GBR Flows. Due to code limitations at this point the max. number of DRBs is 4. - -### IF setup with OAI - -OAI is also compatible with Intermediate Frequency (IF) equipment, allowing the -use of RF front-ends operating on arbitrary frequency bands that do not conform -to the standardized 3GPP NR bands. - -### OAIUE configuration -To configure IF frequencies on the UE side, provide the following command-line -options: -- `if_freq`: DL frequency in Hz -- `if_freq_off`: UL frequency offset in Hz - -### gNB configuration -On the gNB side, the corresponding parameters must be set in the RUs section of -the configuration file: -- `if_freq`: DL frequency in Hz -- `if_offset`: UL frequency offset in Hz - -> Note: When using a libconfig-based configuration file for the gNB, ensure that -> `if_freq` numeric value is suffixed with "L" so it is correctly parsed as -> 64-bit integer. - -#### Run OAI with custom DL/UL arbitrary frequencies - -The following example uses DL frequency 2169.080 MHz and UL frequency offset --400 MHz, with a configuration file for band 66 (FDD) at gNB side. - -On two separate machines with USRPs, run: +- B210: use `-E --continuous-tx`; limited to ~40 MHz bandwidth +- N3xx/X3xx: use `--usrp-tx-thread-config 1`; consider `--tune-offset` or + `ul_prbblacklist` for DC noise at high bandwidth +For network tuning of 10G USRP devices (N300, X300): +```bash +sudo ethtool -G tx 4096 rx 4096 +sudo sysctl -w net.core.wmem_max=62500000 +sudo sysctl -w net.core.rmem_max=62500000 ``` -sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-LTE-EPC/CONF/gnb.band66.tm1.106PRB.usrpx300.conf -sudo ./nr-uesoftmodem --if_freq 2169080000 --if_freq_off -400000000 + +See also the [COTS UE tutorial](NR_SA_Tutorial_COTS_UE.md) and +[performance tuning guide](tuning_and_security.md). + +### O-RAN 7.2 Fronthaul (FHI) + +For O-RAN split 7.2 with an O-RU, build with `build_oai -t +oran_fhlib_5g`/`cmake -DOAI_FHI72=ON`. Configuration requires a `fhi_72` +section and DPDK setup. See the [O-RAN FHI 7.2 tutorial](ORAN_FHI7.2_Tutorial.md). + +## Higher-layer splits + +### CU/DU (F1) and CU-CP/CU-UP (E1) splits + +F1 splits the gNB into a CU (RRC/PDCP/SDAP) and one or more DUs (RLC/MAC/L1). +See [F1AP docs](F1AP/F1-design.md). The CU and DU connect via F1AP over SCTP. +The DU configuration specifies the CU IP address. + +To run a split gNB, start a CU and one or more DUs separately: + +```bash +# CU +sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/cu_gnb.conf + +# DU +sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/du_gnb.conf ``` +E1 splits the CU into a CU-CP (RRC) and one or more CU-UPs (PDCP/SDAP) (and +therefore also requires F1). See [E1AP docs](E1AP/E1-design.md). + +### FAPI/nFAPI splits + +FAPI splits the L1 and MAC. It is used internally by the monolithic gNB. It is +possible to separate L1 and L2 into separate processes and use shared memory +between both. It is further possible use networked FAPI (nFAPI) to separate L1 +and L2 into separate processes on different hosts and use socket-based +communication. See the [FAPI/nFAPI documentation](nfapi.md) + ## 5G gNB MIMO configuration In order to enable DL-MIMO in OAI 5G softmodem, the prerequisite is to have `do_CSIRS = 1` in the configuration file. This allows the gNB to schedule CSI reference signal and to acquire from the UE CSI measurements to be able to schedule DLSCH with MIMO. @@ -157,3 +264,19 @@ Finally the number of TX physical antenna in the RU part of the configuration fi It is possible to limit the number supported DL MIMO layers via RRC configuration, e.g. to a value lower than the number of logical antenna ports configured, by using the configuration file parameter `maxMIMO_layers`. [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) + +## IF (Intermediate Frequency) equipment + +OAI supports RF front-ends operating on arbitrary frequencies outside standard +3GPP NR bands. Configure in the `RUs` section of the gNB config file: + +- `if_freq`: DL frequency in Hz (suffix with `L` in libconfig, e.g. `2169080000L`) +- `if_offset`: UL frequency offset in Hz + +## Related documentation + +Further documentation not referenced above: + +- [Build instructions](BUILD.md) +- [NR SA tutorial with OAI nrUE](NR_SA_Tutorial_OAI_nrUE.md) +- [NTN configuration](ntn-configuration.md)