maki/openairinterface5g
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Standardize documentation headings (remove multiple # H1)

Browse Source 
- Remove multiple single top-level (# H1) headings per file
 - Use (# H2 and ###### H6) sub-headings for consistency
 - Remove any trailing # in the headings
 - This ensures proper table of contents rendering in MkDocs.

 - Also removed RUN_NR_multiple_BWPs.md as it is moved to MAC usage
This commit is contained in:
Robert Schmidt
2026-01-22 10:55:05 +01:00
committed by Shubhika Garg
parent a9ba6290b9
commit 5c480ffd50
36 changed files with 489 additions and 482 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/ORAN_FHI7.2_Tutorial.md
+54 -54
View File
@@ -16,7 +16,7 @@
[[_TOC_]]
# Prerequisites
## Prerequisites
The hardware on which we have tried this tutorial:
@@ -87,14 +87,14 @@ Tested libxran releases:
**Note**: The libxran driver of OAI identifies the above E release version as "5.1.0" (E is fifth letter, then 1.0), and the above F release as "6.1.0".
## Configure your server
### Configure your server
1. Disable Hyperthreading (HT) in your BIOS. In all our servers HT is always disabled.
2. We recommend you to start with a fresh installation of OS (either RHEL or Ubuntu). You have to install realtime kernel on your OS (Operating System). Based on your OS you can search how to install realtime kernel.
3. Install realtime kernel for your OS
4. Change the boot commands based on the below section. They can be performed either via `tuned` or via manually building the kernel
### CPU allocation
#### CPU allocation
**This section is important to read, regardless of the operating system you are using.**
@@ -137,7 +137,7 @@ tuned-adm profile realtime
**Checkout anyway the examples below.**
### One NUMA Node
#### One NUMA Node
Below is the output of `/proc/cmdline` of a single NUMA node server,
@@ -153,7 +153,7 @@ isolcpus=0-15 nohz_full=0-15 rcu_nocbs=0-15 kthread_cpus=16-31 rcu_nocb_poll nos
Example taken for AMD EPYC 9374F 32-Core Processor
### Two NUMA Nodes
#### Two NUMA Nodes
Below is the output of `/proc/cmdline` of a two NUMA node server,
@@ -170,7 +170,7 @@ mitigations=off usbcore.autosuspend=-1 intel_iommu=on intel_iommu=pt selinux=0 e
Example taken for Intel(R) Xeon(R) Gold 6354 CPU @ 3.00GHz
### Common
#### Common
Configure your servers to maximum performance mode either via OS or in BIOS. If you want to disable CPU sleep state via OS then use the below command:
@@ -187,7 +187,7 @@ The above information we have gathered either from O-RAN documents or via our ow
2. [O-RAN Cloud Platform Reference Designs 2.0,O-RAN.WG6.CLOUD-REF-v02.00,February 2021](https://orandownloadsweb.azurewebsites.net/specifications)
## PTP configuration
### PTP configuration
**Note**: You may run OAI with O-RAN 7.2 Fronthaul without a RU attached (e.g. for benchmarking).
In such case, you can skip PTP configuration and go to DPDK section.
@@ -265,7 +265,7 @@ ExecStart=/usr/sbin/phc2sys $OPTIONS
WantedBy=multi-user.target
```
### Debugging PTP issues
#### Debugging PTP issues
You can see these steps in case your ptp logs have erorrs or `rms` reported in `ptp4l` logs is more than 100ms.
Beware that PTP issues may show up only when running OAI and XRAN. If you are using the `ptp4l` service, have a look back in time in the journal: `journalctl -u ptp4l.service -S <hours>:<minutes>:<seconds>`
@@ -283,7 +283,7 @@ timedatectl | grep NTP
timedatectl set-ntp false
```
## DPDK (Data Plane Development Kit)
### DPDK (Data Plane Development Kit)
Download DPDK version 20.11.9.
@@ -296,7 +296,7 @@ cd
wget http://fast.dpdk.org/rel/dpdk-20.11.9.tar.xz
```
### DPDK Compilation and Installation
#### DPDK Compilation and Installation
```bash
# Installing meson : it should pull ninja-build and compiler packages
@@ -311,7 +311,7 @@ ninja -C build
sudo ninja install -C build
```
### Verify the installation is complete
#### Verify the installation is complete
Check if the LD cache contains the DPDK Shared Objects after update:
@@ -365,7 +365,7 @@ export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib64/pkgconfig/
pkg-config --libs libdpdk --static
```
### If you want to de-install this version of DPDK
#### If you want to de-install this version of DPDK
Go back to the version folder you used to build and install
@@ -374,7 +374,7 @@ cd ~/dpdk-stable-20.11.9
sudo ninja deinstall -C build
```
# Build OAI-FHI gNB
## Build OAI-FHI gNB
Clone OAI code base in a suitable repository, here we are cloning in `~/openairinterface5g` directory,
@@ -383,11 +383,11 @@ git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git ~/openairinterfac
cd ~/openairinterface5g/
```
## Build ORAN Fronthaul Interface Library
### Build ORAN Fronthaul Interface Library
Download ORAN FHI DU library, checkout the correct version, and apply the correct patch (available in `oai_folder/cmake_targets/tools/oran_fhi_integration_patches`).
### E release
#### E release
```bash
git clone https://gerrit.o-ran-sc.org/r/o-du/phy.git ~/phy
cd ~/phy
@@ -395,7 +395,7 @@ git checkout oran_e_maintenance_release_v1.0
git apply ~/openairinterface5g/cmake_targets/tools/oran_fhi_integration_patches/E/oaioran_E.patch
```
### F release
#### F release
```bash
git clone https://gerrit.o-ran-sc.org/r/o-du/phy.git ~/phy
cd ~/phy
@@ -426,7 +426,7 @@ WIRELESS_SDK_TOOLCHAIN=gcc RTE_SDK=~/dpdk-stable-20.11.9/ XRAN_DIR=~/phy/fhi_lib
The shared library object `~/phy/fhi_lib/lib/build/libxran.so` must be present
before proceeding.
## For Arm targets only: Install the Arm RAN Acceleration library
### For Arm targets only: Install the Arm RAN Acceleration library
DU execution on Arm systems is yet not functional.
This feature is intended to enable experiments and future improvements on Arm systems.
@@ -451,7 +451,7 @@ Once ArmRAL is configured at your convenience and built, you can install it:
ninja install
```
## Build OAI gNB
### Build OAI gNB
You can now proceed building OAI. You build it the same way as for other
radios, providing option `-t oran_fhlib_5g`. Additionally, you need to provide
@@ -520,20 +520,20 @@ or with `cmake` like so
cmake .. -GNinja -DOAI_FHI72=ON -Dxran_LOCATION=$HOME/phy/fhi_lib/lib -DOAI_FHI72_USE_POLLING=ON
ninja oran_fhlib_5g
# Configuration
## Configuration
RU and DU configurations have a circular dependency: you have to configure DU MAC address in the RU configuration and the RU MAC address, VLAN and Timing advance parameters in the DU configuration.
**Note**: You may run OAI with O-RAN 7.2 Fronthaul without a RU attached (e.g. for benchmarking).
In such case, skip RU configuration and only configure Network Interfaces, DPDK VFs and OAI configuration by using arbitrary values for RU MAC addresses and VLAN tags.
## Configure the RU
### Configure the RU
Contact the RU vendor and get the configuration manual to understand the below commands. The below configuration only corresponds to the RU firmware version indicated at the start of this document. If your firmware version does not correspond to the indicated version, then please don't try these commands.
**NOTE**: Please understand all the changes you are doing at the RU, especially if you are manipulating anything related to output power.
### Benetel 650
#### Benetel 650
The OAI configuration file [`gnb-du.sa.band77.273prb.fhi72.4x4-benetel650.conf`](../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb-du.sa.band77.273prb.fhi72.4x4-benetel650.conf) corresponds to:
- TDD pattern `DDDSU`, 2.5ms
@@ -541,7 +541,7 @@ The OAI configuration file [`gnb-du.sa.band77.273prb.fhi72.4x4-benetel650.conf`]
- MTU 9600
- 4TX4R
#### RU configuration
##### RU configuration
After switching on the radio or rebooting, wait for the radio bring up to complete, which you can follow using `tail -f /tmp/logs/radio_status`. Once you will see `[INFO] Radio bringup complete`, you can configure the RU via editing `/etc/ru_config.cfg`
@@ -559,7 +559,7 @@ flexran_prach_workaround=disabled
dl_ul_tuning_special_slot=0xfd00000
```
### Benetel 550
#### Benetel 550
The OAI configuration file [`gnb.sa.band78.273prb.fhi72.4x4-benetel550.conf`](../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.273prb.fhi72.4x4-benetel550.conf) corresponds to:
- TDD pattern `DDDDDDDSUU`, 5ms
@@ -567,7 +567,7 @@ The OAI configuration file [`gnb.sa.band78.273prb.fhi72.4x4-benetel550.conf`](..
- MTU 9600
- 4TX4R
#### RU configuration
##### RU configuration
After switching on the radio or rebooting, wait for the radio bring up to complete, which you can follow using `tail -f /tmp/logs/radio_status`. Once you will see `[INFO] Radio bringup complete`, you can configure the RU via editing `/etc/ru_config.cfg`
@@ -585,7 +585,7 @@ flexran_prach_workaround=disabled
dl_tuning_special_slot=0x13b6
```
### LITEON
#### LITEON
The OAI configuration file [`gnb.sa.band78.273prb.fhi72.4x4-liteon.conf`](../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.273prb.fhi72.4x4-liteon.conf) corresponds to:
- TDD pattern `DDDSU`, 2.5ms
@@ -593,7 +593,7 @@ The OAI configuration file [`gnb.sa.band78.273prb.fhi72.4x4-liteon.conf`](../tar
- MTU 1500
- MTU 9600: v02.00.10
#### RU configuration
##### RU configuration
SSH to the unit as user `user`. Write `enable` in the terminal to enter the configuration console; the password should be in the user guide. Use the command `show oru-status` to check the RU status. The output should be similar to:
```bash
@@ -623,7 +623,7 @@ jumboframe 1 # enable jumbo frame
...
```
### VVDN LPRU
#### VVDN LPRU
**Version 3.x**
@@ -632,7 +632,7 @@ The OAI configuration file [`gnb.sa.band77.273prb.fhi72.4x4-vvdn.conf`](../targe
- Bandwidth 100MHz
- MTU 9600
#### RU configuration
##### RU configuration
Check in the RU user manual how to configure the center frequency. There are multiple ways to do it. We set the center frequency by editing `sysrepocfg` database. You can use `sysrepocfg --edit=vi -d running` to do the same. You can edit the `startup` database to make the center frequency change persistent.
@@ -676,7 +676,7 @@ mw.l a0050010 <YOUR-RU-VLAN>3 # e.g. VLAN = 4 => `mw.l a0050010 43`
sysrepocfg --edit=vi -d running
```
### Metanoia RU
#### Metanoia RU
**Version 2.0.6**
@@ -697,7 +697,7 @@ The RU configuration is stored in `/etc/rumanager.conf`. The required modificati
At this stage, RU must be rebooted so the changes apply.
### Foxconn RPQN RU
#### Foxconn RPQN RU
**Version v3.1.15q.551_rc10**
@@ -706,7 +706,7 @@ The OAI configuration file [`gnb.sa.band78.273prb.fhi72.4X4-foxconn.conf`](../ta
- Bandwidth 100MHz
- MTU 9600
#### RU configuration
##### RU configuration
After switching on or rebooting the RU, the `/home/root/test/init_rrh_config_enable_cuplane` script should be run.
@@ -731,7 +731,7 @@ RU must be rebooted so the changes apply.
- The measured throughput was **520 Mbps DL** and **40 Mbps UL**.
- With newer OAI versions, throughput degrades. This issue is currently under investigation.
## Configure Network Interfaces and DPDK VFs
### Configure Network Interfaces and DPDK VFs
The 7.2 fronthaul uses the xran library, which requires DPDK. In this step, we
need to configure network interfaces to send data to the RU, and configure DPDK
@@ -767,7 +767,7 @@ in the below command and configure VLAN on the switch as "access VLAN". In case
the MTU is different than 1500, you have to update the MTU on the switch
interface as well.
### Set maximum ring buffers:
#### Set maximum ring buffers:
As a first step, please set up the maximum allowed buffer size to your desired interface. To check the maximum value, please execute the following command:
```bash
@@ -782,7 +782,7 @@ MAX_RING_BUFFER_SIZE=<YOUR_PHYSICAL_INTERFACE_MAX_BUFFER_SIZE>
sudo ethtool -G $IF_NAME rx $MAX_RING_BUFFER_SIZE tx $MAX_RING_BUFFER_SIZE
```
### Set the maximum MTU in the physical interface:
#### Set the maximum MTU in the physical interface:
```bash
set -x
IF_NAME=<YOUR_PHYSICAL_INTERFACE_NAME>
@@ -791,9 +791,9 @@ MTU=<RU_MTU>
sudo ip link set $IF_NAME mtu $MTU
```
### (Re-)create VF(s)
#### (Re-)create VF(s)
#### one VF
##### one VF
```bash
set -x
@@ -808,7 +808,7 @@ sudo sh -c 'echo 1 > /sys/class/net/$IF_NAME/device/sriov_numvfs'
sudo ip link set $IF_NAME vf 0 mac $DU_CU_PLANE_MAC_ADD vlan $VLAN mtu $MTU spoofchk off # set CU planes PCI address
```
#### two VFs
##### two VFs
```bash
set -x
@@ -866,12 +866,12 @@ The hardware card `31:00.1` has two associated virtual functions `31:06.0` and
`31:06.1`.
</details>
### Bind VF(s)
#### Bind VF(s)
Now, unbind any pre-existing DPDK devices, load the "Virtual Function I/O"
driver `vfio_pci` or `mlx5_core`, and bind DPDK to these devices.
#### Bind one VF
##### Bind one VF
```bash
set -x
@@ -883,7 +883,7 @@ sudo modprobe $DRIVER
sudo /usr/local/bin/dpdk-devbind.py --bind $DRIVER $CU_PLANE_PCI_BUS_ADD
```
#### Bind two VFs
##### Bind two VFs
```bash
set -x
@@ -933,7 +933,7 @@ sudo /usr/local/bin/dpdk-devbind.py --bind $DRIVER $C_PLANE_PCI_BUS_ADD
## Configure OAI gNB
### Configure OAI gNB
**Beware in the following section to let in the range of isolated cores the parameters that should be (i.e. `L1s.L1_rx_thread_core`, `L1s.L1_tx_thread_core`, `RUs.ru_thread_core`, `fhi_72.io_core` and `fhi_72.worker_cores`)**
@@ -1026,7 +1026,7 @@ Layer mapping (eAxC offsets) happens as follows:
- At the moment, OAI is compatible with CAT A O-RU only. Therefore, SRS is not supported.
- XRAN retrieves DU MAC address with `rte_eth_macaddr_get()` function. Hence, `fhi_72.du_addr` parameter is not taken into account.
# Start and Operation of OAI gNB
## Start and Operation of OAI gNB
Run the `nr-softmodem` from the build directory:
```bash
@@ -1114,7 +1114,7 @@ not working, and UEs might not be able to attach or reach good performance.
Also, you can try to compile with polling (see [the build
section](.#build-oai-gnb)) to see if it resolves the problem.
# Operation with multiple RUs
## Operation with multiple RUs
It is possible to connect up to 4 RUs to one DU at the same time and operate
them either with a single antenna array or a distributed antenna array. This
@@ -1239,7 +1239,7 @@ Note the eight entries after `avg_IO`.
You should be able to connect a UE now.
# OAI Management Plane
## OAI Management Plane
In OAI gNB, we support:
* Configuration Management: interface(s) creation, configuration of RU CU-planes, Tx/Rx antennas, and Tx/Rx carriers.
* Performance Management: activation/deactivation of available RU performance measurements and its notification reception with 10s periodicity:
@@ -1251,10 +1251,10 @@ The reference specifications:
* `O-RAN.WG4.MP.0-R004-v16.01`
* `O-RAN.WG4.MP-YANGs-R004-v16.01`
## M-plane prerequisites
### M-plane prerequisites
Before proceeding, please make sure you have a support for 7.2 interface, as described in [Prerequisites](#prerequisites).
### DHCP server
#### DHCP server
The M-plane requires a DHCP server, where the M-plane connection can be established over untagged or tagged VLAN. We tested with untagged (the default VLAN is 1).
Please modify `/etc/dhcp/dhcpd.conf` configuration based on your testbed.
@@ -1301,7 +1301,7 @@ Please, configure the interface as:
sudo ip address add 192.168.80.1/24 dev <interface>
```
### Mandatory packages
#### Mandatory packages
* On Fedora (we haven't yet tested RHEL):
```bash
sudo dnf install pcre-devel libssh-devel libxml2-devel libyang2-devel libnetconf2-devel
@@ -1373,7 +1373,7 @@ If you would like to install these libraries in the custom path, please replace
## Benetel O-RU
Note: RAN550/650 v1.2.2 and v1.4.1 have been successfully tested.
### One time steps
#### One time steps
Connect to the RU as user `root`, enable the mplane service, and reboot:
```bash
ssh root@<ru-ip-address>
@@ -1398,7 +1398,7 @@ echo "<DU-pub-key>" >> ~/.ssh/authorized_keys
```
## gNB configuration
### gNB configuration
The reference gNB configuration file for one Benetel RAN550:
[`gnb.sa.band78.273prb.fhi72.4x4-benetel550-mplane.conf`](../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.273prb.fhi72.4x4-benetel550-mplane.conf)
The reference DU configuration file for two Benetel RAN650:
@@ -1481,7 +1481,7 @@ The following parameters are retrieved from the RU and forwarded to the xran:
* `IQ compression`: if RU supports multiple, the first value in the list is taken; please note that the same value is used for PxSCH/PRACH
* `PRACH offset`: hardcoded based on the RU vendor (i.e. for Benetel `max(Nrx,Ntx)`)
## Build and compile gNB
### Build and compile gNB
The following cmake options are available:
* `OAI_FHI72` = CUS support
* `OAI_FHI72_MPLANE` = M support
@@ -1490,7 +1490,7 @@ Compiled libraries:
* `OAI_FHI72` <=> `oran_fhlib_5g`
* `OAI_FHI72` && `OAI_FHI72_MPLANE` <=> `oran_fhlib_5g` (CUS) && `oran_fhlib_5g_mplane` (CUSM)
### Using build_oai script
#### Using build_oai script
```bash
git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git ~/openairinterface5g
cd ~/openairinterface5g/cmake_targets/
@@ -1501,7 +1501,7 @@ cd ~/openairinterface5g/cmake_targets/
PKG_CONFIG_PATH=/opt/mplane-v2/lib/pkgconfig ./build_oai --gNB --ninja -t oran_fhlib_5g_mplane --cmake-opt -Dxran_LOCATION=$HOME/phy/fhi_lib/lib
```
### Using cmake directly
#### Using cmake directly
```bash
git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git ~/openairinterface5g
cd ~/openairinterface5g/
@@ -1512,7 +1512,7 @@ PKG_CONFIG_PATH=/opt/mplane-v2/lib/pkgconfig cmake .. -GNinja -DOAI_FHI72=ON -DO
ninja nr-softmodem oran_fhlib_5g_mplane params_libconfig
```
## Start the gNB
### Start the gNB
Run the `nr-softmodem` from the build directory:
```bash
cd ~/openairinterface5g/cmake_targets/ran_build/build
@@ -3096,7 +3096,7 @@ sudo ./nr-softmodem -O <without-mplane-configuration file> --thread-pool <list o
```
# Contact in case of questions
## Contact in case of questions
You can ask your question on the [mailing lists](https://gitlab.eurecom.fr/oai/openairinterface5g/-/wikis/MailingList).