doc/guides/nics/qede.rst

   1 ..  BSD LICENSE
   2     Copyright (c) 2016 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 QEDE Poll Mode Driver
  32 ======================
  33
  34 The QEDE poll mode driver library (**librte_pmd_qede**) implements support
  35 for **QLogic FastLinQ QL4xxxx 25G/40G CNA** family of adapters as well
  36 as their virtual functions (VF) in SR-IOV context. It is supported on
  37 several standard Linux distros like RHEL7.x, SLES12.x and Ubuntu.
  38 It is compile-tested under FreeBSD OS.
  39
  40 More information can be found at `QLogic Corporation's Website
  41 <http://www.qlogic.com>`_.
  42
  43 Supported Features
  44 ------------------
  45
  46 - Unicast/Multicast filtering
  47 - Promiscuous mode
  48 - Allmulti mode
  49 - Port hardware statistics
  50 - Jumbo frames (using single buffer)
  51 - VLAN offload - Filtering and stripping
  52 - Stateless checksum offloads (IPv4/TCP/UDP)
  53 - Multiple Rx/Tx queues (queue-pairs)
  54 - RSS (with user configurable table/key)
  55 - TSS
  56 - Multiple MAC address
  57 - Default pause flow control
  58 - SR-IOV VF for 25G/40G modes
  59
  60 Non-supported Features
  61 ----------------------
  62
  63 - Scatter-Gather Rx/Tx frames
  64 - Unequal number of Rx/Tx queues
  65 - MTU change (dynamic)
  66 - SR-IOV PF
  67 - Tunneling offloads
  68 - Reload of the PMD after a non-graceful termination
  69
  70 Supported QLogic Adapters
  71 -------------------------
  72
  73 - QLogic FastLinQ QL4xxxx 25G/40G/100G CNAs.
  74
  75 Prerequisites
  76 -------------
  77
  78 - Requires firmware version **8.7.x.** and management firmware
  79   version **8.7.x or higher**. Firmware may be available
  80   inbox in certain newer Linux distros under the standard directory
  81   ``E.g. /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin``
  82
  83 - If the required firmware files are not available then visit
  84   `QLogic Driver Download Center <http://driverdownloads.qlogic.com>`_.
  85
  86 - This driver relies on external zlib library (-lz) for uncompressing
  87   the firmware file.
  88
  89 Performance note
  90 ~~~~~~~~~~~~~~~~
  91
  92 - For better performance, it is recommended to use 4K or higher RX/TX rings.
  93
  94 Config File Options
  95 ~~~~~~~~~~~~~~~~~~~
  96
  97 The following options can be modified in the ``.config`` file. Please note that
  98 enabling debugging options may affect system performance.
  99
 100 - ``CONFIG_RTE_LIBRTE_QEDE_PMD`` (default **y**)
 101
 102   Toggle compilation of QEDE PMD driver.
 103
 104 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_INFO`` (default **n**)
 105
 106   Toggle display of generic debugging messages.
 107
 108 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_DRIVER`` (default **n**)
 109
 110   Toggle display of ecore related messages.
 111
 112 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_TX`` (default **n**)
 113
 114   Toggle display of transmit fast path run-time messages.
 115
 116 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
 117
 118   Toggle display of receive fast path run-time messages.
 119
 120 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
 121
 122   Gives absolute path of firmware file.
 123   ``Eg: "/lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin"``
 124   Empty string indicates driver will pick up the firmware file
 125   from the default location.
 126
 127 Driver Compilation
 128 ~~~~~~~~~~~~~~~~~~
 129
 130 To compile QEDE PMD for Linux x86_64 gcc target, run the following ``make``
 131 command::
 132
 133    cd <DPDK-source-directory>
 134    make config T=x86_64-native-linuxapp-gcc install
 135
 136 To compile QEDE PMD for Linux x86_64 clang target, run the following ``make``
 137 command::
 138
 139    cd <DPDK-source-directory>
 140    make config T=x86_64-native-linuxapp-clang install
 141
 142 To compile QEDE PMD for FreeBSD x86_64 clang target, run the following ``gmake``
 143 command::
 144
 145    cd <DPDK-source-directory>
 146    gmake config T=x86_64-native-bsdapp-clang install
 147
 148 To compile QEDE PMD for FreeBSD x86_64 gcc target, run the following ``gmake``
 149 command::
 150
 151    cd <DPDK-source-directory>
 152    gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=\
 153                                         /usr/local/lib/gcc48 CC=gcc48
 154
 155
 156 Sample Application Notes
 157 ~~~~~~~~~~~~~~~~~~~~~~~~
 158
 159 This section demonstrates how to launch ``testpmd`` with QLogic 4xxxx
 160 devices managed by ``librte_pmd_qede`` in Linux operating system.
 161
 162 #. Request huge pages:
 163
 164    .. code-block:: console
 165
 166       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/ \
 167                                                                 nr_hugepages
 168
 169 #. Load ``igb_uio`` driver:
 170
 171    .. code-block:: console
 172
 173       insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 174
 175 #. Bind the QLogic 4xxxx adapters to ``igb_uio`` loaded in the
 176    previous step:
 177
 178    .. code-block:: console
 179
 180       ./tools/dpdk-devbind.py --bind igb_uio 0000:84:00.0 0000:84:00.1 \
 181                                               0000:84:00.2 0000:84:00.3
 182
 183 #. Start ``testpmd`` with basic parameters:
 184    (Enable QEDE_DEBUG_INFO=y to view informational messages)
 185
 186    .. code-block:: console
 187
 188       testpmd -c 0xff1 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 189       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 190       --rss-ip --rss-udp
 191
 192       [...]
 193
 194     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 195     EAL:   probe driver: 1077:1634 rte_qede_pmd
 196     EAL:   Not managed by a supported kernel driver, skipped
 197     EAL: PCI device 0000:84:00.1 on NUMA socket 1
 198     EAL:   probe driver: 1077:1634 rte_qede_pmd
 199     EAL:   Not managed by a supported kernel driver, skipped
 200     EAL: PCI device 0000:88:00.0 on NUMA socket 1
 201     EAL:   probe driver: 1077:1656 rte_qede_pmd
 202     EAL:   PCI memory mapped at 0x7f738b200000
 203     EAL:   PCI memory mapped at 0x7f738b280000
 204     EAL:   PCI memory mapped at 0x7f738b300000
 205     PMD: Chip details : BB1
 206     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 207     PMD: Firmware version : 8.7.7.0
 208     PMD: Management firmware version : 8.7.8.0
 209     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 210     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 211                                                         00:0e:1e:d2:09:9c
 212       [...]
 213     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 214                                                 tx_free_thresh 4068 socket 0
 215     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 216                                                 tx_free_thresh 4068 socket 0
 217     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 218                                                  tx_free_thresh 4068 socket 0
 219     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 220                                                  tx_free_thresh 4068 socket 0
 221     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 222                                                 rx_buf_size=2148 socket 0
 223     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 224                                                 rx_buf_size=2148 socket 0
 225     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 226                                                 rx_buf_size=2148 socket 0
 227     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 228                                                 rx_buf_size=2148 socket 0
 229     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 230     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 231       [...]
 232     Checking link statuses...
 233     Port 0 Link Up - speed 25000 Mbps - full-duplex
 234     Port 1 Link Up - speed 25000 Mbps - full-duplex
 235     Port 2 Link Up - speed 25000 Mbps - full-duplex
 236     Port 3 Link Up - speed 25000 Mbps - full-duplex
 237     Done
 238     testpmd>
 239
 240
 241 SR-IOV: Prerequisites and Sample Application Notes
 242 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 243
 244 This section provides instructions to configure SR-IOV with Linux OS.
 245
 246 **Note**: librte_pmd_qede will be used to bind to SR-IOV VF device and Linux native kernel driver (QEDE) will function as SR-IOV PF driver.
 247
 248 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 249
 250    .. code-block:: console
 251
 252       lspci -s <slot> -vvv
 253
 254    Example output:
 255
 256    .. code-block:: console
 257
 258       [...]
 259       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 260       [...]
 261       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 262       [...]
 263       Kernel driver in use: igb_uio
 264
 265 #. Load the kernel module:
 266
 267    .. code-block:: console
 268
 269       modprobe qede
 270
 271    Example output:
 272
 273    .. code-block:: console
 274
 275       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 276       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 277
 278 #. Bring up the PF ports:
 279
 280    .. code-block:: console
 281
 282       ifconfig ens5f0 up
 283       ifconfig ens5f1 up
 284
 285 #. Create VF device(s):
 286
 287    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 288    of the parent PF.
 289
 290    Example output:
 291
 292    .. code-block:: console
 293
 294       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 295
 296
 297 #. Assign VF MAC address:
 298
 299    Assign MAC address to the VF using iproute2 utility. The syntax is::
 300
 301       ip link set <PF iface> vf <VF id> mac <macaddr>
 302
 303    Example output:
 304
 305    .. code-block:: console
 306
 307       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 308
 309
 310 #. PCI Passthrough:
 311
 312    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 313    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 314    using the instructions outlined in the Application notes above.