doc/guides/bbdevs/fpga_5gnr_fec.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2019 Intel Corporation
   3
   4 Intel(R) FPGA 5GNR FEC Poll Mode Driver
   5 =======================================
   6
   7 The BBDEV FPGA 5GNR FEC poll mode driver (PMD) supports an FPGA implementation of a VRAN
   8 LDPC Encode / Decode 5GNR wireless acceleration function, using Intel's PCI-e and FPGA
   9 based Vista Creek device.
  10
  11 Features
  12 --------
  13
  14 FPGA 5GNR FEC PMD supports the following features:
  15
  16 - 8 VFs per PF (physical device)
  17 - Maximum of 32 UL queues per VF
  18 - Maximum of 32 DL queues per VF
  19 - PCIe Gen-3 x8 Interface
  20 - MSI-X
  21 - SR-IOV
  22
  23 Limitations
  24 -----------
  25
  26 FPGA 5GNR FEC does not support the following:
  27
  28 - Scatter-Gather function
  29
  30
  31 Installation
  32 ------------
  33
  34 Section 3 of the DPDK manual provides instuctions on installing and compiling DPDK. The
  35 default set of bbdev compile flags may be found in config/common_base, where for example
  36 the flag to build the FPGA 5GNR FEC device, ``CONFIG_RTE_LIBRTE_PMD_BBDEV_FPGA_5GNR_FEC``,
  37 is already set. It is assumed DPDK has been compiled using for instance:
  38
  39 .. code-block:: console
  40
  41   make install T=x86_64-native-linuxapp-gcc
  42
  43
  44 DPDK requires hugepages to be configured as detailed in section 2 of the DPDK manual.
  45 The bbdev test application has been tested with a configuration 40 x 1GB hugepages. The
  46 hugepage configuration of a server may be examined using:
  47
  48 .. code-block:: console
  49
  50    grep Huge* /proc/meminfo
  51
  52
  53 Initialization
  54 --------------
  55
  56 When the device first powers up, its PCI Physical Functions (PF) can be listed through this command:
  57
  58 .. code-block:: console
  59
  60   sudo lspci -vd8086:0d8f
  61
  62 The physical and virtual functions are compatible with Linux UIO drivers:
  63 ``vfio`` and ``igb_uio``. However, in order to work the FPGA 5GNR FEC device firstly needs
  64 to be bound to one of these linux drivers through DPDK.
  65
  66
  67 Bind PF UIO driver(s)
  68 ~~~~~~~~~~~~~~~~~~~~~
  69
  70 Install the DPDK igb_uio driver, bind it with the PF PCI device ID and use
  71 ``lspci`` to confirm the PF device is under use by ``igb_uio`` DPDK UIO driver.
  72
  73 The igb_uio driver may be bound to the PF PCI device using one of three methods:
  74
  75
  76 1. PCI functions (physical or virtual, depending on the use case) can be bound to
  77 the UIO driver by repeating this command for every function.
  78
  79 .. code-block:: console
  80
  81   cd <dpdk-top-level-directory>
  82   insmod ./build/kmod/igb_uio.ko
  83   echo "8086 0d8f" > /sys/bus/pci/drivers/igb_uio/new_id
  84   lspci -vd8086:0d8f
  85
  86
  87 2. Another way to bind PF with DPDK UIO driver is by using the ``dpdk-devbind.py`` tool
  88
  89 .. code-block:: console
  90
  91   cd <dpdk-top-level-directory>
  92   ./usertools/dpdk-devbind.py -b igb_uio 0000:06:00.0
  93
  94 where the PCI device ID (example: 0000:06:00.0) is obtained using lspci -vd8086:0d8f
  95
  96
  97 3. A third way to bind is to use ``dpdk-setup.sh`` tool
  98
  99 .. code-block:: console
 100
 101   cd <dpdk-top-level-directory>
 102   ./usertools/dpdk-setup.sh
 103
 104   select 'Bind Ethernet/Crypto/Baseband device to IGB UIO module'
 105   or
 106   select 'Bind Ethernet/Crypto/Baseband device to VFIO module' depending on driver required
 107   enter PCI device ID
 108   select 'Display current Ethernet/Crypto/Baseband device settings' to confirm binding
 109
 110
 111 In the same way the FPGA 5GNR FEC PF can be bound with vfio, but vfio driver does not
 112 support SR-IOV configuration right out of the box, so it will need to be patched.
 113
 114
 115 Enable Virtual Functions
 116 ~~~~~~~~~~~~~~~~~~~~~~~~
 117
 118 Now, it should be visible in the printouts that PCI PF is under igb_uio control
 119 "``Kernel driver in use: igb_uio``"
 120
 121 To show the number of available VFs on the device, read ``sriov_totalvfs`` file..
 122
 123 .. code-block:: console
 124
 125   cat /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_totalvfs
 126
 127   where 0000\:<b>\:<d>.<f> is the PCI device ID
 128
 129
 130 To enable VFs via igb_uio, echo the number of virtual functions intended to
 131 enable to ``max_vfs`` file..
 132
 133 .. code-block:: console
 134
 135   echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/max_vfs
 136
 137
 138 Afterwards, all VFs must be bound to appropriate UIO drivers as required, same
 139 way it was done with the physical function previously.
 140
 141 Enabling SR-IOV via vfio driver is pretty much the same, except that the file
 142 name is different:
 143
 144 .. code-block:: console
 145
 146   echo <num-of-vfs> > /sys/bus/pci/devices/0000\:<b>\:<d>.<f>/sriov_numvfs