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