feat(nrLDPC_coding_interface): Documentation
This commit is contained in:
Romain Beurdouche
@@ -74,11 +74,6 @@ If DPDK library was installed into custom path, you have to point to the right d
|
||||
```
|
||||
export PKG_CONFIG_PATH=/opt/dpdk-t2/lib64/pkgconfig/:$PKG_CONFIG_PATH
|
||||
```
|
||||
## Setup of T2-related DPDK EAL parameters
|
||||
To configure T2-related DPDK Environment Abstraction Layer (EAL) parameters, you can set the following parameters via the command line:
|
||||
- `ldpc_offload.dpdk_dev` - **mandatory** parameter, specifies PCI address of the T2 card. PCI address of the T2 card can be detected by `lspci | grep "Xilinx"` command.
|
||||
- `ldpc_offload.dpdk_cores_list` - CPU cores assigned to DPDK for T2 processing, by default set to *11-12*. Ensure that the CPU cores specified in *ldpc_offload.dpdk_cores_list* are available and not used by other processes to avoid conflicts.
|
||||
- `ldpc_offload.dpdk_prefix` - DPDK shared data file prefix, by default set to *b6*
|
||||
|
||||
# OAI Build
|
||||
OTA deployment is precisely described in the following tutorial:
|
||||
@@ -106,14 +101,35 @@ Shared object file *libldpc_t2.so* is created during the compilation. This objec
|
||||
|
||||
*Required poll mode driver has to be present on the host machine and required DPDK version has to be installed on the host, prior to the build of OAI*
|
||||
|
||||
# Setup of T2-related DPDK EAL parameters
|
||||
To configure T2-related DPDK Environment Abstraction Layer (EAL) parameters, you can set the following parameters via the command line of PHY simulators or softmodem:
|
||||
- `nrLDPC_coding_t2.dpdk_dev` - **mandatory** parameter, specifies PCI address of the T2 card. PCI address of the T2 card can be detected by `lspci | grep "Xilinx"` command.
|
||||
- `nrLDPC_coding_t2.dpdk_core_list` - **mandatory** parameter, specifies CPU cores assigned to DPDK for T2 processing. Ensure that the CPU cores specified in *nrLDPC_coding_t2.dpdk_core_list* are available and not used by other processes to avoid conflicts.
|
||||
- `nrLDPC_coding_t2.dpdk_prefix` - DPDK shared data file prefix, by default set to *b6*.
|
||||
|
||||
**Note:** These parameters can also be provided in a configuration file:
|
||||
```
|
||||
nrLDPC_coding_t2 : {
|
||||
dpdk_dev : "41:00.0";
|
||||
dpdk_core_list : "14-15";
|
||||
};
|
||||
|
||||
loader : {
|
||||
ldpc : {
|
||||
shlibversion : "_t2";
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
# 5G PHY simulators
|
||||
|
||||
## nr_ulsim test
|
||||
Offload of the channel decoding to the T2 card is in nr_ulsim specified by *-o* option. Example command for running nr_ulsim with LDPC decoding offload to the T2 card:
|
||||
Offload of the channel decoding to the T2 card is in nr_ulsim specified by *--loader.ldpc.shlibversion _t2* option. Example command for running nr_ulsim with LDPC decoding offload to the T2 card:
|
||||
```
|
||||
cd ~/openairinterface5g
|
||||
source oaienv
|
||||
cd cmake_targets/ran_build/build
|
||||
sudo ./nr_ulsim -n100 -s20 -m20 -r273 -R273 -o --ldpc_offload.dpdk_dev 01:00.0
|
||||
sudo ./nr_ulsim -n100 -s20 -m20 -r273 -R273 --loader.ldpc.shlibversion _t2 --nrLDPC_coding_t2.dpdk_dev 01:00.0 --nrLDPC_coding_t2.dpdk_core_list 0-1
|
||||
```
|
||||
## nr_dlsim test
|
||||
Offload of the channel encoding to the AMD Xilinx T2 card is in nr_dlsim specified by *-c* option. Example command for running nr_dlsim with LDPC encoding offload to the T2 card:
|
||||
@@ -121,18 +137,18 @@ Offload of the channel encoding to the AMD Xilinx T2 card is in nr_dlsim specifi
|
||||
cd ~/openairinterface5g
|
||||
source oaienv
|
||||
cd cmake_targets/ran_build/build
|
||||
sudo ./nr_dlsim -n300 -s30 -R 106 -e 27 -c --ldpc_offload.dpdk_dev 01:00.0
|
||||
sudo ./nr_dlsim -n300 -s30 -R 106 -e 27 --loader.ldpc.shlibversion _t2 --nrLDPC_coding_t2.dpdk_dev 01:00.0 --nrLDPC_coding_t2.dpdk_core_list 0-1
|
||||
```
|
||||
|
||||
# OTA test
|
||||
Offload of the channel encoding and decoding to the AMD Xilinx T2 card is enabled by *--ldpc-offload-enable* option.
|
||||
Offload of the channel encoding and decoding to the AMD Xilinx T2 card is enabled by *--loader.ldpc.shlibversion _t2* option.
|
||||
|
||||
## Run OAI gNB with USRP B210
|
||||
```
|
||||
cd ~/openairinterface5g
|
||||
source oaienv
|
||||
cd cmake_targets/ran_build/build
|
||||
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.usrpb210.conf --ldpc-offload-enable --ldpc_offload.dpdk_dev 01:00.0
|
||||
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.usrpb210.conf --loader.ldpc.shlibversion _t2 --nrLDPC_coding_t2.dpdk_dev 01:00.0 --nrLDPC_coding_t2.dpdk_core_list 0-1
|
||||
```
|
||||
|
||||
# Limitations
|
||||
|
||||
@@ -0,0 +1,161 @@
|
||||
# LDPC offload with the XDMA driver
|
||||
|
||||
[TOC]
|
||||
|
||||
This documentation aims to provide a tutorial for using Xilinx PCIe-XDMA based FPGA LDPC decoding within OAI. LDPC decoding is offloaded to FPGA.
|
||||
|
||||
## XDMA Driver Build & Install
|
||||
|
||||
- Get XDMA driver source
|
||||
```bash
|
||||
git clone https://github.com/Xilinx/dma_ip_drivers.git
|
||||
cd dma_ip_drivers/XDMA/linux-kernel
|
||||
```
|
||||
The *xdma_driver* directory contains the following:
|
||||
|
||||
```bash
|
||||
dma_ip_drivers/XDMA/linux-kernel/
|
||||
├── COPYING
|
||||
├── include
|
||||
├── LICENSE
|
||||
├── readme.txt
|
||||
├── RELEASE
|
||||
├── tests
|
||||
├── tools
|
||||
└── xdma
|
||||
```
|
||||
|
||||
Before building the driver, ensure that your system recognizes the Xilinx device. You can check this using the `lspci` command:
|
||||
|
||||
```bash
|
||||
$ lspci | grep Xilinx
|
||||
01:00.0 Serial controller: Xilinx Corporation Device 8038
|
||||
```
|
||||
|
||||
Building and Installing the Driver
|
||||
|
||||
```bash
|
||||
cd ~/dma_ip_drivers/XDMA/linux-kernel/xdma
|
||||
make clean
|
||||
make
|
||||
# install to make the driver loading automatically at system startup
|
||||
sudo make install
|
||||
```
|
||||
|
||||
Load the Driver
|
||||
|
||||
```bash
|
||||
cd ~/dma_ip_drivers/XDMA/linux-kernel/tests
|
||||
sudo ./load_driver.sh
|
||||
```
|
||||
|
||||
## OAI Build
|
||||
|
||||
```bash
|
||||
# Get openairinterface5g source code
|
||||
git clone https://gitlab.eurecom.fr/oai/openairinterface5g.git ~/openairinterface5g
|
||||
cd ~/openairinterface5g
|
||||
|
||||
# Install OAI dependencies
|
||||
cd ~/openairinterface5g/cmake_targets
|
||||
./build_oai -I
|
||||
|
||||
# Build OAI gNB & UE
|
||||
cd ~/openairinterface5g
|
||||
source oaienv
|
||||
cd cmake_targets
|
||||
./build_oai --ninja -w SIMU --gNB --nrUE -P --build-lib "ldpc_xdma" -C -c
|
||||
```
|
||||
|
||||
Shared object file *libldpc_xdma.so* is created during the compilation. This object is conditionally compiled. Selection of the library to compile is done using `--build-lib ldpc_xdma`.
|
||||
|
||||
## 5G PHY simulators
|
||||
|
||||
The simulated test uses the option `--loader.ldpc.shlibversion _xdma` to select the XDMA version for loading into the LDPC interface. Additionally, the option `--nrLDPC_coding_xdma.num_threads_prepare` is used to specify the number of threads for preparing data before the LDPC processing, specifically for the deinterleaving and rate matching parts.
|
||||
|
||||
Another way to activate the feature is to add the `xdma.conf` file with the following content:
|
||||
|
||||
```
|
||||
nrLDPC_coding_xdma : {
|
||||
num_threads_prepare : 2;
|
||||
};
|
||||
|
||||
loader : {
|
||||
ldpc : {
|
||||
shlibversion : "_xdma";
|
||||
};
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
and use option `-O xdma.conf`.
|
||||
|
||||
### nr_ulsim test
|
||||
|
||||
Example command for running nr_ulsim with LDPC decoding offload to the FPGA:
|
||||
|
||||
```bash
|
||||
cd ~/openairinterface5g/cmake_targets/ran_build/build
|
||||
sudo ./nr_ulsim -n100 -m28 -r273 -R273 -s22 -I10 -C8 -P --loader.ldpc.shlibversion _xdma --nrLDPC_coding_xdma.num_threads_prepare 2
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
sudo ./nr_ulsim -n100 -m28 -r273 -R273 -s22 -I10 -C8 -P -O xdma.conf
|
||||
```
|
||||
|
||||
## Run
|
||||
|
||||
Both gNB and nrUE use the option `--loader.ldpc.shlibversion _xdma` to select the XDMA version for loading into the LDPC interface and `--nrLDPC_coding_xdma.num_threads_prepare` to specify the number of threads for preparing data before the LDPC processing, specifically for the deinterleaving and rate matching parts.
|
||||
|
||||
Another way to activate the feature is to add the following content to the `.conf` file you want to use:
|
||||
|
||||
```
|
||||
nrLDPC_coding_xdma : {
|
||||
num_threads_prepare : 2;
|
||||
};
|
||||
|
||||
loader : {
|
||||
ldpc : {
|
||||
shlibversion : "_xdma";
|
||||
};
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
and use option `-O *.conf`.
|
||||
|
||||
### gNB
|
||||
|
||||
Example command using rfsim:
|
||||
|
||||
```bash
|
||||
cd ~/openairinterface5g/cmake_targets/ran_build/build
|
||||
sudo ./nr-softmodem --rfsim --log_config.global_log_options level,nocolor,time -O ../../../ci-scripts/conf_files/gnb.sa.band78.106prb.rfsim.conf --loader.ldpc.shlibversion _xdma --nrLDPC_coding_xdma.num_threads_prepare 2
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
sudo ./nr-softmodem --rfsim --log_config.global_log_options level,nocolor,time -O ../../../ci-scripts/conf_files/gnb.sa.band78.106prb.rfsim.conf
|
||||
```
|
||||
|
||||
if you have added the configuration to the `.conf` file.
|
||||
|
||||
### UE
|
||||
|
||||
Example command using rfsim:
|
||||
|
||||
```bash
|
||||
cd ~/openairinterface5g/cmake_targets/ran_build/build
|
||||
sudo ./nr-uesoftmodem --rfsim -r 106 --numerology 1 --band 78 -C 3319680000 --ue-nb-ant-tx 1 --ue-nb-ant-rx 1 -O ../../../ci-scripts/conf_files/nrue1.uicc.cluCN.conf --rfsimulator.serveraddr 10.201.1.100 --loader.ldpc.shlibversion _xdma --nrLDPC_coding_xdma.num_threads_prepare 2
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```bash
|
||||
sudo ./nr-uesoftmodem --rfsim -r 106 --numerology 1 --band 78 -C 3319680000 --ue-nb-ant-tx 1 --ue-nb-ant-rx 1 -O ../../../ci-scripts/conf_files/nrue1.uicc.cluCN.conf --rfsimulator.serveraddr 10.201.1.100
|
||||
```
|
||||
|
||||
if you have added the configuration to the `.conf` file.
|
||||
Reference in New Issue
Block a user