doc/guides/nics/bnx2x.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright (c) 2015 QLogic Corporation
   3
   4     Redistribution and use in source and binary forms, with or without
   5     modification, are permitted provided that the following conditions
   6     are met:
   7
   8     * Redistributions of source code must retain the above copyright
   9     notice, this list of conditions and the following disclaimer.
  10     * Redistributions in binary form must reproduce the above copyright
  11     notice, this list of conditions and the following disclaimer in
  12     the documentation and/or other materials provided with the
  13     distribution.
  14     * Neither the name of QLogic Corporation nor the names of its
  15     contributors may be used to endorse or promote products derived
  16     from this software without specific prior written permission.
  17
  18     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29
  30 BNX2X Poll Mode Driver
  31 ======================
  32
  33 The BNX2X poll mode driver library (**librte_pmd_bnx2x**) implements support
  34 for **QLogic 578xx** 10/20 Gbps family of adapters as well as their virtual
  35 functions (VF) in SR-IOV context. It is supported on several standard Linux
  36 distros like Red Hat 7.x and SLES12 OS. It is compile-tested under FreeBSD OS.
  37
  38 More information can be found at `QLogic Corporation's Official Website
  39 <http://www.qlogic.com>`_.
  40
  41 Supported Features
  42 ------------------
  43
  44 BNX2X PMD has support for:
  45
  46 - Base L2 features
  47 - Unicast/multicast filtering
  48 - Promiscuous mode
  49 - Port hardware statistics
  50 - SR-IOV VF
  51
  52 Non-supported Features
  53 ----------------------
  54
  55 The features not yet supported include:
  56
  57 - TSS (Transmit Side Scaling)
  58 - RSS (Receive Side Scaling)
  59 - LRO/TSO offload
  60 - Checksum offload
  61 - SR-IOV PF
  62 - Rx TX scatter gather
  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 included in most of the
  85   standard Linux distros. If it is not available visit
  86   `linux-firmware git repository <https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/plain/bnx2x/bnx2x-e2-7.2.51.0.fw>`_
  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 **n**)
  99
 100   Toggle compilation of bnx2x driver. To use bnx2x PMD set this config parameter
 101   to 'y'. Also, in order for firmware binary to load user will need zlib devel
 102   package installed.
 103
 104 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_TX`` (default **n**)
 105
 106   Toggle display of transmit fast path run-time messages.
 107
 108 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_RX`` (default **n**)
 109
 110   Toggle display of receive fast path run-time messages.
 111
 112 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_PERIODIC`` (default **n**)
 113
 114   Toggle display of register reads and writes.
 115
 116
 117 .. _bnx2x_driver-compilation:
 118
 119 Driver compilation and testing
 120 ------------------------------
 121
 122 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 123 for details.
 124
 125 SR-IOV: Prerequisites and sample Application Notes
 126 --------------------------------------------------
 127
 128 This section provides instructions to configure SR-IOV with Linux OS.
 129
 130 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
 131
 132    .. code-block:: console
 133
 134       lspci -s <slot> -vvv
 135
 136    Example output:
 137
 138    .. code-block:: console
 139
 140       [...]
 141       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 142       [...]
 143       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 144       [...]
 145       Kernel driver in use: igb_uio
 146
 147 #. Load the kernel module:
 148
 149    .. code-block:: console
 150
 151       modprobe bnx2x
 152
 153    Example output:
 154
 155    .. code-block:: console
 156
 157       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 158       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 159
 160 #. Bring up the PF ports:
 161
 162    .. code-block:: console
 163
 164       ifconfig ens5f0 up
 165       ifconfig ens5f1 up
 166
 167 #. Create VF device(s):
 168
 169    Echo the number of VFs to be created into "sriov_numvfs" sysfs entry
 170    of the parent PF.
 171
 172    Example output:
 173
 174    .. code-block:: console
 175
 176       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 177
 178 #. Assign VF MAC address:
 179
 180    Assign MAC address to the VF using iproute2 utility. The syntax is:
 181    ip link set <PF iface> vf <VF id> mac <macaddr>
 182
 183    Example output:
 184
 185    .. code-block:: console
 186
 187       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 188
 189 #. PCI Passthrough:
 190
 191    The VF devices may be passed through to the guest VM using virt-manager or
 192    virsh etc. bnx2x PMD should be used to bind the VF devices in the guest VM
 193    using the instructions outlined in the Application notes below.
 194
 195 #. Running testpmd:
 196    (Supply ``--log-level="pmd.net.bnx2x.driver",7`` to view informational messages):
 197
 198    Follow instructions available in the document
 199    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 200    to run testpmd.
 201
 202    Example output:
 203
 204    .. code-block:: console
 205
 206       [...]
 207       EAL: PCI device 0000:84:00.0 on NUMA socket 1
 208       EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
 209       EAL:   PCI memory mapped at 0x7f14f6fe5000
 210       EAL:   PCI memory mapped at 0x7f14f67e5000
 211       EAL:   PCI memory mapped at 0x7f15fbd9b000
 212       EAL: PCI device 0000:84:00.1 on NUMA socket 1
 213       EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
 214       EAL:   PCI memory mapped at 0x7f14f5fe5000
 215       EAL:   PCI memory mapped at 0x7f14f57e5000
 216       EAL:   PCI memory mapped at 0x7f15fbd4f000
 217       Interactive-mode selected
 218       Configuring Port 0 (socket 0)
 219       PMD: bnx2x_dev_tx_queue_setup(): fp[00] req_bd=512, thresh=512,
 220                    usable_bd=1020, total_bd=1024,
 221                                 tx_pages=4
 222       PMD: bnx2x_dev_rx_queue_setup(): fp[00] req_bd=128, thresh=0,
 223                    usable_bd=510, total_bd=512,
 224                                 rx_pages=1, cq_pages=8
 225       PMD: bnx2x_print_adapter_info():
 226       [...]
 227       Checking link statuses...
 228       Port 0 Link Up - speed 10000 Mbps - full-duplex
 229       Port 1 Link Up - speed 10000 Mbps - full-duplex
 230       Done
 231       testpmd>