doc/guides/nics/nfp.rst

   1 ..  BSD LICENSE
   2     Copyright(c) 2015 Netronome Systems, Inc. All rights reserved.
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of Intel Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 NFP poll mode driver library
  32 ============================
  33
  34 Netronome's sixth generation of flow processors pack 216 programmable
  35 cores and over 100 hardware accelerators that uniquely combine packet,
  36 flow, security and content processing in a single device that scales
  37 up to 400 Gbps.
  38
  39 This document explains how to use DPDK with the Netronome Poll Mode
  40 Driver (PMD) supporting Netronome's Network Flow Processor 6xxx
  41 (NFP-6xxx).
  42
  43 Currently the driver supports virtual functions (VFs) only.
  44
  45 Dependencies
  46 ------------
  47
  48 Before using the Netronome's DPDK PMD some NFP-6xxx configuration,
  49 which is not related to DPDK, is required. The system requires
  50 installation of **Netronome's BSP (Board Support Package)** which includes
  51 Linux drivers, programs and libraries.
  52
  53 If you have a NFP-6xxx device you should already have the code and
  54 documentation for doing this configuration. Contact
  55 **support@netronome.com** to obtain the latest available firmware.
  56
  57 The NFP Linux kernel drivers (including the required PF driver for the
  58 NFP) are available on Github at
  59 **https://github.com/Netronome/nfp-drv-kmods** along with build
  60 instructions.
  61
  62 DPDK runs in userspace and PMDs uses the Linux kernel UIO interface to
  63 allow access to physical devices from userspace. The NFP PMD requires
  64 the **igb_uio** UIO driver, available with DPDK, to perform correct
  65 initialization.
  66
  67 Building the software
  68 ---------------------
  69
  70 Netronome's PMD code is provided in the **drivers/net/nfp** directory.
  71 Although NFP PMD has Netronome´s BSP dependencies, it is possible to
  72 compile it along with other DPDK PMDs even if no BSP was installed before.
  73 Of course, a DPDK app will require such a BSP installed for using the
  74 NFP PMD.
  75
  76 Default PMD configuration is at **common_linuxapp configuration** file:
  77
  78 - **CONFIG_RTE_LIBRTE_NFP_PMD=y**
  79
  80 Once DPDK is built all the DPDK apps and examples include support for
  81 the NFP PMD.
  82
  83
  84 System configuration
  85 --------------------
  86
  87 Using the NFP PMD is not different to using other PMDs. Usual steps are:
  88
  89 #. **Configure hugepages:** All major Linux distributions have the hugepages
  90    functionality enabled by default. By default this allows the system uses for
  91    working with transparent hugepages. But in this case some hugepages need to
  92    be created/reserved for use with the DPDK through the hugetlbfs file system.
  93    First the virtual file system need to be mounted:
  94
  95    .. code-block:: console
  96
  97       mount -t hugetlbfs none /mnt/hugetlbfs
  98
  99    The command uses the common mount point for this file system and it needs to
 100    be created if necessary.
 101
 102    Configuring hugepages is performed via sysfs:
 103
 104    .. code-block:: console
 105
 106       /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
 107
 108    This sysfs file is used to specify the number of hugepages to reserve.
 109    For example:
 110
 111    .. code-block:: console
 112
 113       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
 114
 115    This will reserve 2GB of memory using 1024 2MB hugepages. The file may be
 116    read to see if the operation was performed correctly:
 117
 118    .. code-block:: console
 119
 120       cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
 121
 122    The number of unused hugepages may also be inspected.
 123
 124    Before executing the DPDK app it should match the value of nr_hugepages.
 125
 126    .. code-block:: console
 127
 128       cat /sys/kernel/mm/hugepages/hugepages-2048kB/free_hugepages
 129
 130    The hugepages reservation should be performed at system initialization and
 131    it is usual to use a kernel parameter for configuration. If the reservation
 132    is attempted on a busy system it will likely fail. Reserving memory for
 133    hugepages may be done adding the following to the grub kernel command line:
 134
 135    .. code-block:: console
 136
 137       default_hugepagesz=1M hugepagesz=2M hugepages=1024
 138
 139    This will reserve 2GBytes of memory using 2Mbytes huge pages.
 140
 141    Finally, for a NUMA system the allocation needs to be made on the correct
 142    NUMA node. In a DPDK app there is a master core which will (usually) perform
 143    memory allocation. It is important that some of the hugepages are reserved
 144    on the NUMA memory node where the network device is attached. This is because
 145    of a restriction in DPDK by which TX and RX descriptors rings must be created
 146    on the master code.
 147
 148    Per-node allocation of hugepages may be inspected and controlled using sysfs.
 149    For example:
 150
 151    .. code-block:: console
 152
 153       cat /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
 154
 155    For a NUMA system there will be a specific hugepage directory per node
 156    allowing control of hugepage reservation. A common problem may occur when
 157    hugepages reservation is performed after the system has been working for
 158    some time. Configuration using the global sysfs hugepage interface will
 159    succeed but the per-node allocations may be unsatisfactory.
 160
 161    The number of hugepages that need to be reserved depends on how the app uses
 162    TX and RX descriptors, and packets mbufs.
 163
 164 #. **Enable SR-IOV on the NFP-6xxx device:** The current NFP PMD works with
 165    Virtual Functions (VFs) on a NFP device. Make sure that one of the Physical
 166    Function (PF) drivers from the above Github repository is installed and
 167    loaded.
 168
 169    Virtual Functions need to be enabled before they can be used with the PMD.
 170    Before enabling the VFs it is useful to obtain information about the
 171    current NFP PCI device detected by the system:
 172
 173    .. code-block:: console
 174
 175       lspci -d19ee:
 176
 177    Now, for example, configure two virtual functions on a NFP-6xxx device
 178    whose PCI system identity is "0000:03:00.0":
 179
 180    .. code-block:: console
 181
 182       echo 2 > /sys/bus/pci/devices/0000:03:00.0/sriov_numvfs
 183
 184    The result of this command may be shown using lspci again:
 185
 186    .. code-block:: console
 187
 188       lspci -d19ee: -k
 189
 190    Two new PCI devices should appear in the output of the above command. The
 191    -k option shows the device driver, if any, that devices are bound to.
 192    Depending on the modules loaded at this point the new PCI devices may be
 193    bound to nfp_netvf driver.
 194
 195 #. **To install the uio kernel module (manually):** All major Linux
 196    distributions have support for this kernel module so it is straightforward
 197    to install it:
 198
 199    .. code-block:: console
 200
 201       modprobe uio
 202
 203    The module should now be listed by the lsmod command.
 204
 205 #. **To install the igb_uio kernel module (manually):** This module is part
 206    of DPDK sources and configured by default (CONFIG_RTE_EAL_IGB_UIO=y).
 207
 208    .. code-block:: console
 209
 210       modprobe igb_uio.ko
 211
 212    The module should now be listed by the lsmod command.
 213
 214    Depending on which NFP modules are loaded, it could be necessary to
 215    detach NFP devices from the nfp_netvf module. If this is the case the
 216    device needs to be unbound, for example:
 217
 218    .. code-block:: console
 219
 220       echo 0000:03:08.0 > /sys/bus/pci/devices/0000:03:08.0/driver/unbind
 221
 222       lspci -d19ee: -k
 223
 224    The output of lspci should now show that 0000:03:08.0 is not bound to
 225    any driver.
 226
 227    The next step is to add the NFP PCI ID to the IGB UIO driver:
 228
 229    .. code-block:: console
 230
 231       echo 19ee 6003 > /sys/bus/pci/drivers/igb_uio/new_id
 232
 233    And then to bind the device to the igb_uio driver:
 234
 235    .. code-block:: console
 236
 237       echo 0000:03:08.0 > /sys/bus/pci/drivers/igb_uio/bind
 238
 239       lspci -d19ee: -k
 240
 241    lspci should show that device bound to igb_uio driver.
 242
 243 #. **Using scripts to install and bind modules:** DPDK provides scripts which are
 244    useful for installing the UIO modules and for binding the right device to those
 245    modules avoiding doing so manually:
 246
 247    * **dpdk-setup.sh**
 248    * **dpdk-devbind.py**
 249
 250    Configuration may be performed by running dpdk-setup.sh which invokes
 251    dpdk-devbind.py as needed. Executing dpdk-setup.sh will display a menu of
 252    configuration options.