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 RHEL and SLES. 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 - QLogic 578xx CNAs support Ethernet, iSCSI and FCoE functionalities.
  68   These functionalities are supported using QLogic Linux kernel
  69   drivers bnx2x, cnic, bnx2i and bnx2fc. DPDK is supported on these
  70   adapters using bnx2x PMD.
  71
  72 - When SR-IOV is not enabled on the adapter,
  73   QLogic Linux kernel drivers (bnx2x, cnic, bnx2i and bnx2fc) and bnx2x
  74   PMD can’t be attached to different PFs on a given QLogic 578xx
  75   adapter.
  76   A given adapter needs to be completely used by DPDK or Linux drivers.
  77   Before binding DPDK driver to one or more PFs on the adapter,
  78   please make sure to unbind Linux drivers from all PFs of the adapter.
  79   If there are multiple adapters on the system, one or more adapters
  80   can be used by DPDK driver completely and other adapters can be used
  81   by Linux drivers completely.
  82
  83 - When SR-IOV is enabled on the adapter,
  84   Linux kernel drivers (bnx2x, cnic, bnx2i and bnx2fc) can be bound
  85   to the PFs of a given adapter and either bnx2x PMD or Linux drivers
  86   bnx2x can be bound to the VFs of the adapter.
  87
  88 Supported QLogic NICs
  89 ---------------------
  90
  91 - 578xx
  92
  93 Prerequisites
  94 -------------
  95
  96 - Requires firmware version **7.2.51.0**. It is included in most of the
  97   standard Linux distros. If it is not available visit
  98   `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>`_
  99   to get the required firmware.
 100
 101 Pre-Installation Configuration
 102 ------------------------------
 103
 104 Config File Options
 105 ~~~~~~~~~~~~~~~~~~~
 106
 107 The following options can be modified in the ``.config`` file. Please note that
 108 enabling debugging options may affect system performance.
 109
 110 - ``CONFIG_RTE_LIBRTE_BNX2X_PMD`` (default **n**)
 111
 112   Toggle compilation of bnx2x driver. To use bnx2x PMD set this config parameter
 113   to 'y'. Also, in order for firmware binary to load user will need zlib devel
 114   package installed.
 115
 116 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_TX`` (default **n**)
 117
 118   Toggle display of transmit fast path run-time messages.
 119
 120 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_RX`` (default **n**)
 121
 122   Toggle display of receive fast path run-time messages.
 123
 124 - ``CONFIG_RTE_LIBRTE_BNX2X_DEBUG_PERIODIC`` (default **n**)
 125
 126   Toggle display of register reads and writes.
 127
 128
 129 .. _bnx2x_driver-compilation:
 130
 131 Driver compilation and testing
 132 ------------------------------
 133
 134 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 135 for details.
 136
 137 SR-IOV: Prerequisites and sample Application Notes
 138 --------------------------------------------------
 139
 140 This section provides instructions to configure SR-IOV with Linux OS.
 141
 142 #. Verify SR-IOV and ARI capabilities are enabled on the adapter using ``lspci``:
 143
 144    .. code-block:: console
 145
 146       lspci -s <slot> -vvv
 147
 148    Example output:
 149
 150    .. code-block:: console
 151
 152       [...]
 153       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 154       [...]
 155       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 156       [...]
 157       Kernel driver in use: igb_uio
 158
 159 #. Load the kernel module:
 160
 161    .. code-block:: console
 162
 163       modprobe bnx2x
 164
 165    Example output:
 166
 167    .. code-block:: console
 168
 169       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 170       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 171
 172 #. Bring up the PF ports:
 173
 174    .. code-block:: console
 175
 176       ifconfig ens5f0 up
 177       ifconfig ens5f1 up
 178
 179 #. Create VF device(s):
 180
 181    Echo the number of VFs to be created into "sriov_numvfs" sysfs entry
 182    of the parent PF.
 183
 184    Example output:
 185
 186    .. code-block:: console
 187
 188       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 189
 190 #. Assign VF MAC address:
 191
 192    Assign MAC address to the VF using iproute2 utility. The syntax is:
 193    ip link set <PF iface> vf <VF id> mac <macaddr>
 194
 195    Example output:
 196
 197    .. code-block:: console
 198
 199       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 200
 201 #. PCI Passthrough:
 202
 203    The VF devices may be passed through to the guest VM using virt-manager or
 204    virsh etc. bnx2x PMD should be used to bind the VF devices in the guest VM
 205    using the instructions outlined in the Application notes below.
 206
 207 #. Running testpmd:
 208    (Supply ``--log-level="pmd.net.bnx2x.driver",7`` to view informational messages):
 209
 210    Follow instructions available in the document
 211    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 212    to run testpmd.
 213
 214    Example output:
 215
 216    .. code-block:: console
 217
 218       [...]
 219       EAL: PCI device 0000:84:00.0 on NUMA socket 1
 220       EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
 221       EAL:   PCI memory mapped at 0x7f14f6fe5000
 222       EAL:   PCI memory mapped at 0x7f14f67e5000
 223       EAL:   PCI memory mapped at 0x7f15fbd9b000
 224       EAL: PCI device 0000:84:00.1 on NUMA socket 1
 225       EAL:   probe driver: 14e4:168e rte_bnx2x_pmd
 226       EAL:   PCI memory mapped at 0x7f14f5fe5000
 227       EAL:   PCI memory mapped at 0x7f14f57e5000
 228       EAL:   PCI memory mapped at 0x7f15fbd4f000
 229       Interactive-mode selected
 230       Configuring Port 0 (socket 0)
 231       PMD: bnx2x_dev_tx_queue_setup(): fp[00] req_bd=512, thresh=512,
 232                    usable_bd=1020, total_bd=1024,
 233                                 tx_pages=4
 234       PMD: bnx2x_dev_rx_queue_setup(): fp[00] req_bd=128, thresh=0,
 235                    usable_bd=510, total_bd=512,
 236                                 rx_pages=1, cq_pages=8
 237       PMD: bnx2x_print_adapter_info():
 238       [...]
 239       Checking link statuses...
 240       Port 0 Link Up - speed 10000 Mbps - full-duplex
 241       Port 1 Link Up - speed 10000 Mbps - full-duplex
 242       Done
 243       testpmd>