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