doc/guides/nics/qede.rst

   1 ..  BSD LICENSE
   2     Copyright (c) 2016 QLogic Corporation
   3     Copyright (c) 2017 Cavium Inc.
   4     All rights reserved.
   5
   6     Redistribution and use in source and binary forms, with or without
   7     modification, are permitted provided that the following conditions
   8     are met:
   9
  10     * Redistributions of source code must retain the above copyright
  11     notice, this list of conditions and the following disclaimer.
  12     * Redistributions in binary form must reproduce the above copyright
  13     notice, this list of conditions and the following disclaimer in
  14     the documentation and/or other materials provided with the
  15     distribution.
  16     * Neither the name of QLogic Corporation nor the names of its
  17     contributors may be used to endorse or promote products derived
  18     from this software without specific prior written permission.
  19
  20     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31
  32 QEDE Poll Mode Driver
  33 ======================
  34
  35 The QEDE poll mode driver library (**librte_pmd_qede**) implements support
  36 for **QLogic FastLinQ QL4xxxx 10G/25G/40G/50G/100G Intelligent Ethernet Adapters (IEA) and Converged Network Adapters (CNA)** family of adapters as well as SR-IOV virtual functions (VF). 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 - Multiple MAC address
  52 - MTU change
  53 - Default pause flow control
  54 - Multiprocess aware
  55 - Scatter-Gather
  56 - Multiple Rx/Tx queues
  57 - RSS (with RETA/hash table/key)
  58 - TSS
  59 - Stateless checksum offloads (IPv4/IPv6/TCP/UDP)
  60 - LRO/TSO
  61 - VLAN offload - Filtering and stripping
  62 - N-tuple filter and flow director (limited support)
  63 - NPAR (NIC Partitioning)
  64 - SR-IOV VF
  65 - VXLAN tunneling offload
  66 - MPLSoUDP Tx tunnel offload
  67
  68 Non-supported Features
  69 ----------------------
  70
  71 - SR-IOV PF
  72 - GENEVE and NVGRE Tunneling offloads
  73
  74 Supported QLogic Adapters
  75 -------------------------
  76
  77 - QLogic FastLinQ QL4xxxx 10G/25G/40G/50G/100G Intelligent Ethernet Adapters (IEA) and Converged Network Adapters (CNA)
  78
  79 Prerequisites
  80 -------------
  81
  82 - Requires storm firmware version **8.30.12.0**. Firmware may be available
  83   inbox in certain newer Linux distros under the standard directory
  84   ``E.g. /lib/firmware/qed/qed_init_values-8.30.12.0.bin``
  85   If the required firmware files are not available then download it from
  86   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  87   For downloading firmware file, select adapter category, model and DPDK Poll Mode Driver.
  88
  89 - Requires management firmware (MFW) version **8.30.x.x** or higher to be
  90   flashed on to the adapter. If the required management firmware is not
  91   available then download from
  92   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  93   For downloading firmware upgrade utility, select adapter category, model and Linux distro.
  94   To flash the management firmware refer to the instructions in the QLogic Firmware Upgrade Utility Readme document.
  95
  96 - SR-IOV requires Linux PF driver version **8.20.x.x** or higher.
  97   If the required PF driver is not available then download it from
  98   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  99   For downloading PF driver, select adapter category, model and Linux distro.
 100
 101
 102 Performance note
 103 ~~~~~~~~~~~~~~~~
 104
 105 - For better performance, it is recommended to use 4K or higher RX/TX rings.
 106
 107 Config File Options
 108 ~~~~~~~~~~~~~~~~~~~
 109
 110 The following options can be modified in the ``.config`` file. Please note that
 111 enabling debugging options may affect system performance.
 112
 113 - ``CONFIG_RTE_LIBRTE_QEDE_PMD`` (default **y**)
 114
 115   Toggle compilation of QEDE PMD driver.
 116
 117 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_INFO`` (default **n**)
 118
 119   Toggle display of generic debugging messages.
 120
 121 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_DRIVER`` (default **n**)
 122
 123   Toggle display of ecore related messages.
 124
 125 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_TX`` (default **n**)
 126
 127   Toggle display of transmit fast path run-time messages.
 128
 129 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
 130
 131   Toggle display of receive fast path run-time messages.
 132
 133 - ``CONFIG_RTE_LIBRTE_QEDE_VF_TX_SWITCH`` (default **"y"**)
 134
 135   A knob to control per-VF Tx switching feature.
 136
 137 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
 138
 139   Gives absolute path of firmware file.
 140   ``Eg: "/lib/firmware/qed/qed_init_values-8.30.12.0.bin"``
 141   Empty string indicates driver will pick up the firmware file
 142   from the default location /lib/firmware/qed.
 143   CAUTION this option is more for custom firmware, it is not
 144   recommended for use under normal condition.
 145
 146 Driver compilation and testing
 147 ------------------------------
 148
 149 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 150 for details.
 151
 152 SR-IOV: Prerequisites and Sample Application Notes
 153 --------------------------------------------------
 154
 155 This section provides instructions to configure SR-IOV with Linux OS.
 156
 157 **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.
 158
 159 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 160
 161    .. code-block:: console
 162
 163       lspci -s <slot> -vvv
 164
 165    Example output:
 166
 167    .. code-block:: console
 168
 169       [...]
 170       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 171       [...]
 172       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 173       [...]
 174       Kernel driver in use: igb_uio
 175
 176 #. Load the kernel module:
 177
 178    .. code-block:: console
 179
 180       modprobe qede
 181
 182    Example output:
 183
 184    .. code-block:: console
 185
 186       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 187       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 188
 189 #. Bring up the PF ports:
 190
 191    .. code-block:: console
 192
 193       ifconfig ens5f0 up
 194       ifconfig ens5f1 up
 195
 196 #. Create VF device(s):
 197
 198    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 199    of the parent PF.
 200
 201    Example output:
 202
 203    .. code-block:: console
 204
 205       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 206
 207
 208 #. Assign VF MAC address:
 209
 210    Assign MAC address to the VF using iproute2 utility. The syntax is::
 211
 212       ip link set <PF iface> vf <VF id> mac <macaddr>
 213
 214    Example output:
 215
 216    .. code-block:: console
 217
 218       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 219
 220
 221 #. PCI Passthrough:
 222
 223    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 224    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 225    using the instructions from Driver compilation and testing section above.
 226
 227
 228 #. Running testpmd
 229    (Enable QEDE_DEBUG_INFO=y to view informational messages):
 230
 231    Refer to the document
 232    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 233    ``testpmd`` application.
 234
 235    Example output:
 236
 237    .. code-block:: console
 238
 239       testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 240       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 241       --rss-ip --rss-udp
 242
 243       [...]
 244
 245     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 246     EAL:   probe driver: 1077:1634 rte_qede_pmd
 247     EAL:   Not managed by a supported kernel driver, skipped
 248     EAL: PCI device 0000:84:00.1 on NUMA socket 1
 249     EAL:   probe driver: 1077:1634 rte_qede_pmd
 250     EAL:   Not managed by a supported kernel driver, skipped
 251     EAL: PCI device 0000:88:00.0 on NUMA socket 1
 252     EAL:   probe driver: 1077:1656 rte_qede_pmd
 253     EAL:   PCI memory mapped at 0x7f738b200000
 254     EAL:   PCI memory mapped at 0x7f738b280000
 255     EAL:   PCI memory mapped at 0x7f738b300000
 256     PMD: Chip details : BB1
 257     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 258     PMD: Firmware version : 8.7.7.0
 259     PMD: Management firmware version : 8.7.8.0
 260     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 261     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 262                                                         00:0e:1e:d2:09:9c
 263       [...]
 264     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 265                                                 tx_free_thresh 4068 socket 0
 266     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 267                                                 tx_free_thresh 4068 socket 0
 268     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 269                                                  tx_free_thresh 4068 socket 0
 270     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 271                                                  tx_free_thresh 4068 socket 0
 272     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 273                                                 rx_buf_size=2148 socket 0
 274     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 275                                                 rx_buf_size=2148 socket 0
 276     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 277                                                 rx_buf_size=2148 socket 0
 278     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 279                                                 rx_buf_size=2148 socket 0
 280     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 281     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 282       [...]
 283     Checking link statuses...
 284     Port 0 Link Up - speed 25000 Mbps - full-duplex
 285     Port 1 Link Up - speed 25000 Mbps - full-duplex
 286     Port 2 Link Up - speed 25000 Mbps - full-duplex
 287     Port 3 Link Up - speed 25000 Mbps - full-duplex
 288     Done
 289     testpmd>