doc/guides/nics/bnx2x.rst

   1 ..  BSD LICENSE
   2     Copyright (c) 2015 QLogic Corporation
   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 QLogic 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 BNX2X Poll Mode Driver
  32 ======================
  33
  34 The BNX2X poll mode driver library (**librte_pmd_bnx2x**) implements support
  35 for **QLogic 578xx** 10/20 Gbps family of adapters as well as their virtual
  36 functions (VF) in SR-IOV context. It is supported on several standard Linux
  37 distros like Red Hat 7.x and SLES12 OS. It is compile-tested under FreeBSD OS.
  38
  39 More information can be found at `QLogic Corporation's Official Website
  40 <http://www.qlogic.com>`_.
  41
  42 Supported Features
  43 ------------------
  44
  45 BNX2X PMD has support for:
  46
  47 - Base L2 features
  48 - Unicast/multicast filtering
  49 - Promiscuous mode
  50 - Port hardware statistics
  51 - SR-IOV VF
  52
  53 Non-supported Features
  54 ----------------------
  55
  56 The features not yet supported include:
  57
  58 - TSS (Transmit Side Scaling)
  59 - RSS (Receive Side Scaling)
  60 - LRO/TSO offload
  61 - Checksum offload
  62 - SR-IOV PF
  63 - Rx TX scatter gather
  64
  65 Co-existence considerations
  66 ---------------------------
  67
  68 - BCM578xx being a CNA can have both NIC and Storage personalities.
  69   However, coexistence with storage protocol drivers (cnic, bnx2fc and
  70   bnx2fi) is not supported on the same adapter. So storage personality
  71   has to be disabled on that adapter when used in DPDK applications.
  72
  73 - For SR-IOV case, bnx2x PMD will be used to bind to SR-IOV VF device and
  74   Linux native kernel driver (bnx2x) will be attached to SR-IOV PF.
  75
  76
  77 Supported QLogic NICs
  78 ---------------------
  79
  80 - 578xx
  81
  82 Prerequisites
  83 -------------
  84
  85 - Requires firmware version **7.2.51.0**. It is included in most of the
  86   standard Linux distros. If it is not available visit
  87   `QLogic Driver Download Center <http://driverdownloads.qlogic.com>`_
  88   to get the required firmware.
  89
  90 Pre-Installation Configuration
  91 ------------------------------
  92
  93 Config File Options
  94 ~~~~~~~~~~~~~~~~~~~
  95
  96 The following options can be modified in the ``.config`` file. Please note that
  97 enabling debugging options may affect system performance.
  98
  99 - ``CONFIG_RTE_LIBRTE_BNX2X_PMD`` (default **n**)
 100
 101   Toggle compilation of bnx2x driver. To use bnx2x PMD set this config parameter
 102   to 'y'. Also, in order for firmware binary to load user will need zlib devel
 103   package installed.
 104
 105 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG`` (default **n**)
 106
 107   Toggle display of generic debugging messages.
 108
 109 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_INIT`` (default **n**)
 110
 111   Toggle display of initialization related messages.
 112
 113 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_TX`` (default **n**)
 114
 115   Toggle display of transmit fast path run-time messages.
 116
 117 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_RX`` (default **n**)
 118
 119   Toggle display of receive fast path run-time messages.
 120
 121 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_PERIODIC`` (default **n**)
 122
 123   Toggle display of register reads and writes.
 124
 125
 126 .. _bnx2x_driver-compilation:
 127
 128 Driver Compilation
 129 ~~~~~~~~~~~~~~~~~~
 130
 131 BNX2X PMD for Linux x86_64 gcc target, run the following "make"
 132 command::
 133
 134    cd <DPDK-source-directory>
 135    make config T=x86_64-native-linuxapp-gcc install
 136
 137 To compile BNX2X PMD for Linux x86_64 clang target, run the following "make"
 138 command::
 139
 140    cd <DPDK-source-directory>
 141    make config T=x86_64-native-linuxapp-clang install
 142
 143 To compile BNX2X PMD for Linux i686 gcc target, run the following "make"
 144 command::
 145
 146    cd <DPDK-source-directory>
 147    make config T=i686-native-linuxapp-gcc install
 148
 149 To compile BNX2X PMD for Linux i686 gcc target, run the following "make"
 150 command:
 151
 152 .. code-block:: console
 153
 154    cd <DPDK-source-directory>
 155    make config T=i686-native-linuxapp-gcc install
 156
 157 To compile BNX2X PMD for FreeBSD x86_64 clang target, run the following "gmake"
 158 command::
 159
 160    cd <DPDK-source-directory>
 161    gmake config T=x86_64-native-bsdapp-clang install
 162
 163 To compile BNX2X PMD for FreeBSD x86_64 gcc target, run the following "gmake"
 164 command::
 165
 166    cd <DPDK-source-directory>
 167    gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc49 CC=gcc49
 168
 169 To compile BNX2X PMD for FreeBSD x86_64 gcc target, run the following "gmake"
 170 command:
 171
 172 .. code-block:: console
 173
 174    cd <DPDK-source-directory>
 175    gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=/usr/local/lib/gcc49 CC=gcc49
 176
 177 Linux
 178 -----
 179
 180 .. _bnx2x_Linux-installation:
 181
 182 Linux Installation
 183 ~~~~~~~~~~~~~~~~~~
 184
 185 Sample Application Notes
 186 ~~~~~~~~~~~~~~~~~~~~~~~~
 187
 188 This section demonstrates how to launch ``testpmd`` with QLogic 578xx
 189 devices managed by ``librte_pmd_bnx2x`` in Linux operating system.
 190
 191 #. Request huge pages:
 192
 193    .. code-block:: console
 194
 195       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
 196
 197 #. Load ``igb_uio`` or ``vfio-pci`` driver:
 198
 199    .. code-block:: console
 200
 201       insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 202
 203    or
 204
 205    .. code-block:: console
 206
 207       modprobe vfio-pci
 208
 209 #. Bind the QLogic adapters to ``igb_uio`` or ``vfio-pci`` loaded in the
 210    previous step::
 211
 212       ./tools/dpdk-devbind.py --bind igb_uio 0000:84:00.0 0000:84:00.1
 213
 214    or
 215
 216    Setup VFIO permissions for regular users and then bind to ``vfio-pci``:
 217
 218    .. code-block:: console
 219
 220       sudo chmod a+x /dev/vfio
 221
 222       sudo chmod 0666 /dev/vfio/*
 223
 224       ./tools/dpdk-devbind.py --bind vfio-pci 0000:84:00.0 0000:84:00.1
 225
 226 #. Start ``testpmd`` with basic parameters:
 227
 228    .. code-block:: console
 229
 230       ./x86_64-native-linuxapp-gcc/app/testpmd -c 0xf -n 4 -- -i
 231
 232    Example output:
 233
 234    .. code-block:: console
 235
 236       [...]
 237       EAL: PCI device 0000:84:00.0 on NUMA socket 1
 238       EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
 239       EAL:   PCI memory mapped at 0x7f14f6fe5000
 240       EAL:   PCI memory mapped at 0x7f14f67e5000
 241       EAL:   PCI memory mapped at 0x7f15fbd9b000
 242       EAL: PCI device 0000:84:00.1 on NUMA socket 1
 243       EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
 244       EAL:   PCI memory mapped at 0x7f14f5fe5000
 245       EAL:   PCI memory mapped at 0x7f14f57e5000
 246       EAL:   PCI memory mapped at 0x7f15fbd4f000
 247       Interactive-mode selected
 248       Configuring Port 0 (socket 0)
 249       PMD: bnx2x_dev_tx_queue_setup(): fp[00] req_bd=512, thresh=512,
 250                    usable_bd=1020, total_bd=1024,
 251                                 tx_pages=4
 252       PMD: bnx2x_dev_rx_queue_setup(): fp[00] req_bd=128, thresh=0,
 253                    usable_bd=510, total_bd=512,
 254                                 rx_pages=1, cq_pages=8
 255       PMD: bnx2x_print_adapter_info():
 256       [...]
 257       Checking link statuses...
 258       Port 0 Link Up - speed 10000 Mbps - full-duplex
 259       Port 1 Link Up - speed 10000 Mbps - full-duplex
 260       Done
 261       testpmd>
 262
 263 SR-IOV: Prerequisites and sample Application Notes
 264 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 265
 266 This section provides instructions to configure SR-IOV with Linux OS.
 267
 268 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
 269
 270    .. code-block:: console
 271
 272       lspci -s <slot> -vvv
 273
 274    Example output:
 275
 276    .. code-block:: console
 277
 278       [...]
 279       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 280       [...]
 281       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 282       [...]
 283       Kernel driver in use: igb_uio
 284
 285 #. Load the kernel module:
 286
 287    .. code-block:: console
 288
 289       modprobe bnx2x
 290
 291    Example output:
 292
 293    .. code-block:: console
 294
 295       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 296       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 297
 298 #. Bring up the PF ports:
 299
 300    .. code-block:: console
 301
 302       ifconfig ens5f0 up
 303       ifconfig ens5f1 up
 304
 305 #. Create VF device(s):
 306
 307    Echo the number of VFs to be created into "sriov_numvfs" sysfs entry
 308    of the parent PF.
 309
 310    Example output:
 311
 312    .. code-block:: console
 313
 314       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 315
 316
 317 #. Assign VF MAC address:
 318
 319    Assign MAC address to the VF using iproute2 utility. The syntax is:
 320    ip link set <PF iface> vf <VF id> mac <macaddr>
 321
 322    Example output:
 323
 324    .. code-block:: console
 325
 326       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 327
 328
 329 #. PCI Passthrough:
 330
 331    The VF devices may be passed through to the guest VM using virt-manager or
 332    virsh etc. bnx2x PMD should be used to bind the VF devices in the guest VM
 333    using the instructions outlined in the Application notes below.