ceph/src/seastar/dpdk/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 - N-tuple filter and flow director (limited support)
  64 - LRO/TSO
  65
  66 Non-supported Features
  67 ----------------------
  68
  69 - SR-IOV PF
  70 - GENEVE and NVGRE Tunneling offloads
  71 - NPAR
  72
  73 Supported QLogic Adapters
  74 -------------------------
  75
  76 - QLogic FastLinQ QL4xxxx 10G/25G/40G/50G/100G CNAs.
  77
  78 Prerequisites
  79 -------------
  80
  81 - Requires firmware version **8.18.x.** and management firmware
  82   version **8.18.x or higher**. 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.18.9.0.bin``
  85
  86 - If the required firmware files are not available then visit
  87   `QLogic Driver Download Center <http://driverdownloads.qlogic.com>`_.
  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.18.9.0.bin"``
 124   Empty string indicates driver will pick up the firmware file
 125   from the default location.
 126
 127 Driver compilation and testing
 128 ------------------------------
 129
 130 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 131 for details.
 132
 133 SR-IOV: Prerequisites and Sample Application Notes
 134 --------------------------------------------------
 135
 136 This section provides instructions to configure SR-IOV with Linux OS.
 137
 138 **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.
 139
 140 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 141
 142    .. code-block:: console
 143
 144       lspci -s <slot> -vvv
 145
 146    Example output:
 147
 148    .. code-block:: console
 149
 150       [...]
 151       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 152       [...]
 153       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 154       [...]
 155       Kernel driver in use: igb_uio
 156
 157 #. Load the kernel module:
 158
 159    .. code-block:: console
 160
 161       modprobe qede
 162
 163    Example output:
 164
 165    .. code-block:: console
 166
 167       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 168       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 169
 170 #. Bring up the PF ports:
 171
 172    .. code-block:: console
 173
 174       ifconfig ens5f0 up
 175       ifconfig ens5f1 up
 176
 177 #. Create VF device(s):
 178
 179    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 180    of the parent PF.
 181
 182    Example output:
 183
 184    .. code-block:: console
 185
 186       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 187
 188
 189 #. Assign VF MAC address:
 190
 191    Assign MAC address to the VF using iproute2 utility. The syntax is::
 192
 193       ip link set <PF iface> vf <VF id> mac <macaddr>
 194
 195    Example output:
 196
 197    .. code-block:: console
 198
 199       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 200
 201
 202 #. PCI Passthrough:
 203
 204    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 205    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 206    using the instructions from Driver compilation and testing section above.
 207
 208
 209 #. Running testpmd
 210    (Enable QEDE_DEBUG_INFO=y to view informational messages):
 211
 212    Refer to the document
 213    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 214    ``testpmd`` application.
 215
 216    Example output:
 217
 218    .. code-block:: console
 219
 220       testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 221       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 222       --rss-ip --rss-udp
 223
 224       [...]
 225
 226     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 227     EAL:   probe driver: 1077:1634 rte_qede_pmd
 228     EAL:   Not managed by a supported kernel driver, skipped
 229     EAL: PCI device 0000:84:00.1 on NUMA socket 1
 230     EAL:   probe driver: 1077:1634 rte_qede_pmd
 231     EAL:   Not managed by a supported kernel driver, skipped
 232     EAL: PCI device 0000:88:00.0 on NUMA socket 1
 233     EAL:   probe driver: 1077:1656 rte_qede_pmd
 234     EAL:   PCI memory mapped at 0x7f738b200000
 235     EAL:   PCI memory mapped at 0x7f738b280000
 236     EAL:   PCI memory mapped at 0x7f738b300000
 237     PMD: Chip details : BB1
 238     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 239     PMD: Firmware version : 8.7.7.0
 240     PMD: Management firmware version : 8.7.8.0
 241     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 242     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 243                                                         00:0e:1e:d2:09:9c
 244       [...]
 245     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 246                                                 tx_free_thresh 4068 socket 0
 247     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 248                                                 tx_free_thresh 4068 socket 0
 249     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 250                                                  tx_free_thresh 4068 socket 0
 251     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 252                                                  tx_free_thresh 4068 socket 0
 253     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 254                                                 rx_buf_size=2148 socket 0
 255     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 256                                                 rx_buf_size=2148 socket 0
 257     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 258                                                 rx_buf_size=2148 socket 0
 259     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 260                                                 rx_buf_size=2148 socket 0
 261     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 262     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 263       [...]
 264     Checking link statuses...
 265     Port 0 Link Up - speed 25000 Mbps - full-duplex
 266     Port 1 Link Up - speed 25000 Mbps - full-duplex
 267     Port 2 Link Up - speed 25000 Mbps - full-duplex
 268     Port 3 Link Up - speed 25000 Mbps - full-duplex
 269     Done
 270     testpmd>