ceph/src/spdk/dpdk/doc/guides/nics/qede.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2016 QLogic Corporation
   3     Copyright(c) 2017 Cavium, Inc
   4
   5 QEDE Poll Mode Driver
   6 ======================
   7
   8 The QEDE poll mode driver library (**librte_pmd_qede**) implements support
   9 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
  10 several standard Linux distros like RHEL7.x, SLES12.x and Ubuntu.
  11 It is compile-tested under FreeBSD OS.
  12
  13 More information can be found at `QLogic Corporation's Website
  14 <http://www.qlogic.com>`_.
  15
  16 Supported Features
  17 ------------------
  18
  19 - Unicast/Multicast filtering
  20 - Promiscuous mode
  21 - Allmulti mode
  22 - Port hardware statistics
  23 - Jumbo frames
  24 - Multiple MAC address
  25 - MTU change
  26 - Default pause flow control
  27 - Multiprocess aware
  28 - Scatter-Gather
  29 - Multiple Rx/Tx queues
  30 - RSS (with RETA/hash table/key)
  31 - TSS
  32 - Stateless checksum offloads (IPv4/IPv6/TCP/UDP)
  33 - LRO/TSO
  34 - VLAN offload - Filtering and stripping
  35 - N-tuple filter and flow director (limited support)
  36 - NPAR (NIC Partitioning)
  37 - SR-IOV VF
  38 - GRE Tunneling offload
  39 - GENEVE Tunneling offload
  40 - VXLAN Tunneling offload
  41 - MPLSoUDP Tx Tunneling offload
  42
  43 Non-supported Features
  44 ----------------------
  45
  46 - SR-IOV PF
  47
  48 Co-existence considerations
  49 ---------------------------
  50 - QLogic FastLinQ QL4xxxx CNAs can have both NIC and Storage personalities. However, coexistence with storage protocol drivers (qedi and qedf) is not supported on the same adapter. So storage personality has to be disabled on that adapter when used in DPDK applications.
  51 - For SR-IOV case, qede PMD will be used to bind to SR-IOV VF device and Linux native kernel driver (qede) will be attached to SR-IOV PF.
  52
  53 Supported QLogic Adapters
  54 -------------------------
  55
  56 - QLogic FastLinQ QL4xxxx 10G/25G/40G/50G/100G Intelligent Ethernet Adapters (IEA) and Converged Network Adapters (CNA)
  57
  58 Prerequisites
  59 -------------
  60
  61 - Requires storm firmware version **8.37.7.0**. Firmware may be available
  62   inbox in certain newer Linux distros under the standard directory
  63   ``E.g. /lib/firmware/qed/qed_init_values-8.37.7.0.bin``.
  64   If the required firmware files are not available then download it from
  65   `linux-firmware git repository <http://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/qed>`_
  66   or `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  67   To download firmware file from QLogic website, select adapter category, model and DPDK Poll Mode Driver.
  68
  69 - Requires the NIC be updated minimally with **8.30.x.x** Management firmware(MFW) version supported for that NIC.
  70   It is highly recommended that the NIC be updated with the latest available management firmware version to get latest feature  set.
  71   Management Firmware and Firmware Upgrade Utility for Cavium FastLinQ(r) branded adapters can be downloaded from
  72   `Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  73   For downloading Firmware Upgrade Utility, select NIC category, model and Linux distro.
  74   To update the management firmware, refer to the instructions in the Firmware Upgrade Utility Readme document.
  75   For OEM branded adapters please follow the instruction provided by the OEM to update the Management Firmware on the NIC.
  76
  77 - SR-IOV requires Linux PF driver version **8.20.x.x** or higher.
  78   If the required PF driver is not available then download it from
  79   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  80   For downloading PF driver, select adapter category, model and Linux distro.
  81
  82
  83 Performance note
  84 ~~~~~~~~~~~~~~~~
  85
  86 - For better performance, it is recommended to use 4K or higher RX/TX rings.
  87
  88 Config File Options
  89 ~~~~~~~~~~~~~~~~~~~
  90
  91 The following options can be modified in the ``.config`` file. Please note that
  92 enabling debugging options may affect system performance.
  93
  94 - ``CONFIG_RTE_LIBRTE_QEDE_PMD`` (default **y**)
  95
  96   Toggle compilation of QEDE PMD driver.
  97
  98 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_TX`` (default **n**)
  99
 100   Toggle display of transmit fast path run-time messages.
 101
 102 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
 103
 104   Toggle display of receive fast path run-time messages.
 105
 106 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
 107
 108   Gives absolute path of firmware file.
 109   ``Eg: "/lib/firmware/qed/qed_init_values-8.37.7.0.bin"``
 110   Empty string indicates driver will pick up the firmware file
 111   from the default location /lib/firmware/qed.
 112   CAUTION this option is more for custom firmware, it is not
 113   recommended for use under normal condition.
 114
 115 Driver compilation and testing
 116 ------------------------------
 117
 118 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 119 for details.
 120
 121 SR-IOV: Prerequisites and Sample Application Notes
 122 --------------------------------------------------
 123
 124 This section provides instructions to configure SR-IOV with Linux OS.
 125
 126 **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.20.x.x or higher.
 127
 128 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 129
 130    .. code-block:: console
 131
 132       lspci -s <slot> -vvv
 133
 134    Example output:
 135
 136    .. code-block:: console
 137
 138       [...]
 139       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 140       [...]
 141       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 142       [...]
 143       Kernel driver in use: igb_uio
 144
 145 #. Load the kernel module:
 146
 147    .. code-block:: console
 148
 149       modprobe qede
 150
 151    Example output:
 152
 153    .. code-block:: console
 154
 155       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 156       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 157
 158 #. Bring up the PF ports:
 159
 160    .. code-block:: console
 161
 162       ifconfig ens5f0 up
 163       ifconfig ens5f1 up
 164
 165 #. Create VF device(s):
 166
 167    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 168    of the parent PF.
 169
 170    Example output:
 171
 172    .. code-block:: console
 173
 174       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 175
 176
 177 #. Assign VF MAC address:
 178
 179    Assign MAC address to the VF using iproute2 utility. The syntax is::
 180
 181       ip link set <PF iface> vf <VF id> mac <macaddr>
 182
 183    Example output:
 184
 185    .. code-block:: console
 186
 187       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 188
 189
 190 #. PCI Passthrough:
 191
 192    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 193    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 194    using the instructions from Driver compilation and testing section above.
 195
 196
 197 #. Running testpmd
 198    (Supply ``--log-level="pmd.net.qede.driver:info`` to view informational messages):
 199
 200    Refer to the document
 201    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 202    ``testpmd`` application.
 203
 204    Example output:
 205
 206    .. code-block:: console
 207
 208       testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 209       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 210       --rss-ip --rss-udp
 211
 212       [...]
 213
 214     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 215     EAL:   probe driver: 1077:1634 rte_qede_pmd
 216     EAL:   Not managed by a supported kernel driver, skipped
 217     EAL: PCI device 0000:84:00.1 on NUMA socket 1
 218     EAL:   probe driver: 1077:1634 rte_qede_pmd
 219     EAL:   Not managed by a supported kernel driver, skipped
 220     EAL: PCI device 0000:88:00.0 on NUMA socket 1
 221     EAL:   probe driver: 1077:1656 rte_qede_pmd
 222     EAL:   PCI memory mapped at 0x7f738b200000
 223     EAL:   PCI memory mapped at 0x7f738b280000
 224     EAL:   PCI memory mapped at 0x7f738b300000
 225     PMD: Chip details : BB1
 226     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 227     PMD: Firmware version : 8.7.7.0
 228     PMD: Management firmware version : 8.7.8.0
 229     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 230     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 231                                                         00:0e:1e:d2:09:9c
 232       [...]
 233     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 234                                                 tx_free_thresh 4068 socket 0
 235     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 236                                                 tx_free_thresh 4068 socket 0
 237     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 238                                                  tx_free_thresh 4068 socket 0
 239     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 240                                                  tx_free_thresh 4068 socket 0
 241     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 242                                                 rx_buf_size=2148 socket 0
 243     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 244                                                 rx_buf_size=2148 socket 0
 245     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 246                                                 rx_buf_size=2148 socket 0
 247     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 248                                                 rx_buf_size=2148 socket 0
 249     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 250     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 251       [...]
 252     Checking link statuses...
 253     Port 0 Link Up - speed 25000 Mbps - full-duplex
 254     Port 1 Link Up - speed 25000 Mbps - full-duplex
 255     Port 2 Link Up - speed 25000 Mbps - full-duplex
 256     Port 3 Link Up - speed 25000 Mbps - full-duplex
 257     Done
 258     testpmd>