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 and testing
 129 ------------------------------
 130
 131 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 132 for details.
 133
 134 SR-IOV: Prerequisites and sample Application Notes
 135 --------------------------------------------------
 136
 137 This section provides instructions to configure SR-IOV with Linux OS.
 138
 139 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
 140
 141    .. code-block:: console
 142
 143       lspci -s <slot> -vvv
 144
 145    Example output:
 146
 147    .. code-block:: console
 148
 149       [...]
 150       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 151       [...]
 152       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 153       [...]
 154       Kernel driver in use: igb_uio
 155
 156 #. Load the kernel module:
 157
 158    .. code-block:: console
 159
 160       modprobe bnx2x
 161
 162    Example output:
 163
 164    .. code-block:: console
 165
 166       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 167       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 168
 169 #. Bring up the PF ports:
 170
 171    .. code-block:: console
 172
 173       ifconfig ens5f0 up
 174       ifconfig ens5f1 up
 175
 176 #. Create VF device(s):
 177
 178    Echo the number of VFs to be created into "sriov_numvfs" sysfs entry
 179    of the parent PF.
 180
 181    Example output:
 182
 183    .. code-block:: console
 184
 185       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 186
 187 #. Assign VF MAC address:
 188
 189    Assign MAC address to the VF using iproute2 utility. The syntax is:
 190    ip link set <PF iface> vf <VF id> mac <macaddr>
 191
 192    Example output:
 193
 194    .. code-block:: console
 195
 196       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 197
 198 #. PCI Passthrough:
 199
 200    The VF devices may be passed through to the guest VM using virt-manager or
 201    virsh etc. bnx2x PMD should be used to bind the VF devices in the guest VM
 202    using the instructions outlined in the Application notes below.
 203
 204 #. Running testpmd:
 205
 206    Follow instructions available in the document
 207    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 208    to run testpmd.
 209
 210    Example output:
 211
 212    .. code-block:: console
 213
 214       [...]
 215       EAL: PCI device 0000:84:00.0 on NUMA socket 1
 216       EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
 217       EAL:   PCI memory mapped at 0x7f14f6fe5000
 218       EAL:   PCI memory mapped at 0x7f14f67e5000
 219       EAL:   PCI memory mapped at 0x7f15fbd9b000
 220       EAL: PCI device 0000:84:00.1 on NUMA socket 1
 221       EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
 222       EAL:   PCI memory mapped at 0x7f14f5fe5000
 223       EAL:   PCI memory mapped at 0x7f14f57e5000
 224       EAL:   PCI memory mapped at 0x7f15fbd4f000
 225       Interactive-mode selected
 226       Configuring Port 0 (socket 0)
 227       PMD: bnx2x_dev_tx_queue_setup(): fp[00] req_bd=512, thresh=512,
 228                    usable_bd=1020, total_bd=1024,
 229                                 tx_pages=4
 230       PMD: bnx2x_dev_rx_queue_setup(): fp[00] req_bd=128, thresh=0,
 231                    usable_bd=510, total_bd=512,
 232                                 rx_pages=1, cq_pages=8
 233       PMD: bnx2x_print_adapter_info():
 234       [...]
 235       Checking link statuses...
 236       Port 0 Link Up - speed 10000 Mbps - full-duplex
 237       Port 1 Link Up - speed 10000 Mbps - full-duplex
 238       Done
 239       testpmd>