doc/guides/nics/nfp.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2015-2017 Netronome Systems, Inc. All rights reserved.
   3     All rights reserved.
   4
   5 NFP poll mode driver library
   6 ============================
   7
   8 Netronome's sixth generation of flow processors pack 216 programmable
   9 cores and over 100 hardware accelerators that uniquely combine packet,
  10 flow, security and content processing in a single device that scales
  11 up to 400-Gb/s.
  12
  13 This document explains how to use DPDK with the Netronome Poll Mode
  14 Driver (PMD) supporting Netronome's Network Flow Processor 6xxx
  15 (NFP-6xxx), Netronome's Network Flow Processor 4xxx (NFP-4xxx) and
  16 Netronome's Network Flow Processor 38xx (NFP-38xx).
  17
  18 NFP is a SRIOV capable device and the PMD supports the physical
  19 function (PF) and the virtual functions (VFs).
  20
  21 Dependencies
  22 ------------
  23
  24 Before using the Netronome's DPDK PMD some NFP configuration,
  25 which is not related to DPDK, is required. The system requires
  26 installation of **Netronome's BSP (Board Support Package)** along
  27 with a specific NFP firmware application. Netronome's NSP ABI
  28 version should be 0.20 or higher.
  29
  30 If you have a NFP device you should already have the code and
  31 documentation for this configuration. Contact
  32 **support@netronome.com** to obtain the latest available firmware.
  33
  34 The NFP Linux netdev kernel driver for VFs has been a part of the
  35 vanilla kernel since kernel version 4.5, and support for the PF
  36 since kernel version 4.11. Support for older kernels can be obtained
  37 on Github at
  38 **https://github.com/Netronome/nfp-drv-kmods** along with the build
  39 instructions.
  40
  41 NFP PMD needs to be used along with UIO ``igb_uio`` or VFIO (``vfio-pci``)
  42 Linux kernel driver.
  43
  44 Building the software
  45 ---------------------
  46
  47 Netronome's PMD code is provided in the **drivers/net/nfp** directory.
  48 Although NFP PMD has Netronome´s BSP dependencies, it is possible to
  49 compile it along with other DPDK PMDs even if no BSP was installed previously.
  50 Of course, a DPDK app will require such a BSP installed for using the
  51 NFP PMD, along with a specific NFP firmware application.
  52
  53 Once the DPDK is built all the DPDK apps and examples include support for
  54 the NFP PMD.
  55
  56
  57 Driver compilation and testing
  58 ------------------------------
  59
  60 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
  61 for details.
  62
  63 Using the PF
  64 ------------
  65
  66 NFP PMD supports using the NFP PF as another DPDK port, but it does not
  67 have any functionality for controlling VFs. In fact, it is not possible to use
  68 the PMD with the VFs if the PF is being used by DPDK, that is, with the NFP PF
  69 bound to ``igb_uio`` or ``vfio-pci`` kernel drivers. Future DPDK versions will
  70 have a PMD able to work with the PF and VFs at the same time and with the PF
  71 implementing VF management along with other PF-only functionalities/offloads.
  72
  73 The PMD PF has extra work to do which will delay the DPDK app initialization
  74 like uploading the firmware and configure the Link state properly when starting or
  75 stopping a PF port. Since DPDK 18.05 the firmware upload happens when
  76 a PF is initialized, which was not always true with older DPDK versions.
  77
  78 Depending on the Netronome product installed in the system, firmware files
  79 should be available under ``/lib/firmware/netronome``. DPDK PMD supporting the
  80 PF looks for a firmware file in this order:
  81
  82         1) First try to find a firmware image specific for this device using the
  83            NFP serial number:
  84
  85                 serial-00-15-4d-12-20-65-10-ff.nffw
  86
  87         2) Then try the PCI name:
  88
  89                 pci-0000:04:00.0.nffw
  90
  91         3) Finally try the card type and media:
  92
  93                 nic_AMDA0099-0001_2x25.nffw
  94
  95 Netronome's software packages install firmware files under ``/lib/firmware/netronome``
  96 to support all the Netronome's SmartNICs and different firmware applications.
  97 This is usually done using file names based on SmartNIC type and media and with a
  98 directory per firmware application. Options 1 and 2 for firmware filenames allow
  99 more than one SmartNIC, same type of SmartNIC or different ones, and to upload a
 100 different firmware to each SmartNIC.
 101
 102    .. Note::
 103       Currently the NFP PMD supports using the PF with Agilio Firmware with NFD3
 104       and Agilio Firmware with NFDk. See https://help.netronome.com/support/solutions
 105       for more information on the various firmwares supported by the Netronome
 106       Agilio CX smartNIC.
 107
 108 PF multiport support
 109 --------------------
 110
 111 The NFP PMD can work with up to 8 ports on the same PF device. The number of
 112 available ports is firmware and hardware dependent, and the driver looks for a
 113 firmware symbol during initialization to know how many can be used.
 114
 115 DPDK apps work with ports, and a port is usually a PF or a VF PCI device.
 116 However, with the NFP PF multiport there is just one PF PCI device. Supporting
 117 this particular configuration requires the PMD to create ports in a special way,
 118 although once they are created, DPDK apps should be able to use them as normal
 119 PCI ports.
 120
 121 NFP ports belonging to same PF can be seen inside PMD initialization with a
 122 suffix added to the PCI ID: wwww:xx:yy.z_portn. For example, a PF with PCI ID
 123 0000:03:00.0 and four ports is seen by the PMD code as:
 124
 125    .. code-block:: console
 126
 127       0000:03:00.0_port0
 128       0000:03:00.0_port1
 129       0000:03:00.0_port2
 130       0000:03:00.0_port3
 131
 132    .. Note::
 133
 134       There are some limitations with multiport support: RX interrupts and
 135       device hot-plugging are not supported.
 136
 137 PF multiprocess support
 138 -----------------------
 139
 140 Due to how the driver needs to access the NFP through a CPP interface, which implies
 141 to use specific registers inside the chip, the number of secondary processes with PF
 142 ports is limited to only one.
 143
 144 This limitation will be solved in future versions but having basic multiprocess support
 145 is important for allowing development and debugging through the PF using a secondary
 146 process which will create a CPP bridge for user space tools accessing the NFP.
 147
 148
 149 System configuration
 150 --------------------
 151
 152 #. **Enable SR-IOV on the NFP device:** The current NFP PMD supports the PF and
 153    the VFs on a NFP device. However, it is not possible to work with both at the
 154    same time because the VFs require the PF being bound to the NFP PF Linux
 155    netdev driver.  Make sure you are working with a kernel with NFP PF support or
 156    get the drivers from the above Github repository and follow the instructions
 157    for building and installing it.
 158
 159    VFs need to be enabled before they can be used with the PMD.
 160    Before enabling the VFs it is useful to obtain information about the
 161    current NFP PCI device detected by the system:
 162
 163    .. code-block:: console
 164
 165       lspci -d19ee:
 166
 167    Now, for example, configure two virtual functions on a NFP-6xxx device
 168    whose PCI system identity is "0000:03:00.0":
 169
 170    .. code-block:: console
 171
 172       echo 2 > /sys/bus/pci/devices/0000:03:00.0/sriov_numvfs
 173
 174    The result of this command may be shown using lspci again:
 175
 176    .. code-block:: console
 177
 178       lspci -d19ee: -k
 179
 180    Two new PCI devices should appear in the output of the above command. The
 181    -k option shows the device driver, if any, that devices are bound to.
 182    Depending on the modules loaded at this point the new PCI devices may be
 183    bound to nfp_netvf driver.