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