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