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 RHEL, SLES, Ubuntu etc.
  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
  51 - QLogic FastLinQ QL4xxxx CNAs support Ethernet, RDMA, iSCSI and FCoE
  52   functionalities. These functionalities are supported using
  53   QLogic Linux kernel drivers qed, qede, qedr, qedi and qedf. DPDK is
  54   supported on these adapters using qede PMD.
  55
  56 - When SR-IOV is not enabled on the adapter,
  57   QLogic Linux kernel drivers (qed, qede, qedr, qedi and qedf) and qede
  58   PMD can’t be attached to different PFs on a given QLogic FastLinQ
  59   QL4xxx adapter.
  60   A given adapter needs to be completely used by DPDK or Linux drivers
  61   Before binding DPDK driver to one or more PFs on the adapter,
  62   please make sure to unbind Linux drivers from all PFs of the adapter.
  63   If there are multiple adapters on the system, one or more adapters
  64   can be used by DPDK driver completely and other adapters can be used
  65   by Linux drivers completely.
  66
  67 - When SR-IOV is enabled on the adapter,
  68   Linux kernel drivers (qed, qede, qedr, qedi and qedf) can be bound
  69   to the PFs of a given adapter and either qede PMD or Linux drivers
  70   (qed and qede) can be bound to the VFs of the adapter.
  71
  72 Supported QLogic Adapters
  73 -------------------------
  74
  75 - QLogic FastLinQ QL4xxxx 10G/25G/40G/50G/100G Intelligent Ethernet Adapters (IEA) and Converged Network Adapters (CNA)
  76
  77 Prerequisites
  78 -------------
  79
  80 - Requires storm firmware version **8.37.7.0**. Firmware may be available
  81   inbox in certain newer Linux distros under the standard directory
  82   ``E.g. /lib/firmware/qed/qed_init_values-8.37.7.0.bin``.
  83   If the required firmware files are not available then download it from
  84   `linux-firmware git repository <http://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git/tree/qed>`_
  85   or `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  86   To download firmware file from QLogic website, select adapter category, model and DPDK Poll Mode Driver.
  87
  88 - Requires the NIC be updated minimally with **8.30.x.x** Management firmware(MFW) version supported for that NIC.
  89   It is highly recommended that the NIC be updated with the latest available management firmware version to get latest feature  set.
  90   Management Firmware and Firmware Upgrade Utility for Cavium FastLinQ(r) branded adapters can be downloaded from
  91   `Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  92   For downloading Firmware Upgrade Utility, select NIC category, model and Linux distro.
  93   To update the management firmware, refer to the instructions in the Firmware Upgrade Utility Readme document.
  94   For OEM branded adapters please follow the instruction provided by the OEM to update the Management Firmware on the NIC.
  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_TX`` (default **n**)
 118
 119   Toggle display of transmit fast path run-time messages.
 120
 121 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
 122
 123   Toggle display of receive fast path run-time messages.
 124
 125 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
 126
 127   Gives absolute path of firmware file.
 128   ``Eg: "/lib/firmware/qed/qed_init_values-8.37.7.0.bin"``
 129   Empty string indicates driver will pick up the firmware file
 130   from the default location /lib/firmware/qed.
 131   CAUTION this option is more for custom firmware, it is not
 132   recommended for use under normal condition.
 133
 134 Driver compilation and testing
 135 ------------------------------
 136
 137 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 138 for details.
 139
 140 SR-IOV: Prerequisites and Sample Application Notes
 141 --------------------------------------------------
 142
 143 This section provides instructions to configure SR-IOV with Linux OS.
 144
 145 **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.
 146
 147 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 148
 149    .. code-block:: console
 150
 151       lspci -s <slot> -vvv
 152
 153    Example output:
 154
 155    .. code-block:: console
 156
 157       [...]
 158       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 159       [...]
 160       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 161       [...]
 162       Kernel driver in use: igb_uio
 163
 164 #. Load the kernel module:
 165
 166    .. code-block:: console
 167
 168       modprobe qede
 169
 170    Example output:
 171
 172    .. code-block:: console
 173
 174       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 175       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 176
 177 #. Bring up the PF ports:
 178
 179    .. code-block:: console
 180
 181       ifconfig ens5f0 up
 182       ifconfig ens5f1 up
 183
 184 #. Create VF device(s):
 185
 186    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 187    of the parent PF.
 188
 189    Example output:
 190
 191    .. code-block:: console
 192
 193       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 194
 195
 196 #. Assign VF MAC address:
 197
 198    Assign MAC address to the VF using iproute2 utility. The syntax is::
 199
 200       ip link set <PF iface> vf <VF id> mac <macaddr>
 201
 202    Example output:
 203
 204    .. code-block:: console
 205
 206       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 207
 208
 209 #. PCI Passthrough:
 210
 211    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 212    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 213    using the instructions from Driver compilation and testing section above.
 214
 215
 216 #. Running testpmd
 217    (Supply ``--log-level="pmd.net.qede.driver:info`` to view informational messages):
 218
 219    Refer to the document
 220    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 221    ``testpmd`` application.
 222
 223    Example output:
 224
 225    .. code-block:: console
 226
 227       testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 228       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 229       --rss-ip --rss-udp
 230
 231       [...]
 232
 233     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 234     EAL:   probe driver: 1077:1634 rte_qede_pmd
 235     EAL:   Not managed by a supported kernel driver, skipped
 236     EAL: PCI device 0000:84:00.1 on NUMA socket 1
 237     EAL:   probe driver: 1077:1634 rte_qede_pmd
 238     EAL:   Not managed by a supported kernel driver, skipped
 239     EAL: PCI device 0000:88:00.0 on NUMA socket 1
 240     EAL:   probe driver: 1077:1656 rte_qede_pmd
 241     EAL:   PCI memory mapped at 0x7f738b200000
 242     EAL:   PCI memory mapped at 0x7f738b280000
 243     EAL:   PCI memory mapped at 0x7f738b300000
 244     PMD: Chip details : BB1
 245     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 246     PMD: Firmware version : 8.7.7.0
 247     PMD: Management firmware version : 8.7.8.0
 248     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 249     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 250                                                         00:0e:1e:d2:09:9c
 251       [...]
 252     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 253                                                 tx_free_thresh 4068 socket 0
 254     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 255                                                 tx_free_thresh 4068 socket 0
 256     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 257                                                  tx_free_thresh 4068 socket 0
 258     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 259                                                  tx_free_thresh 4068 socket 0
 260     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 261                                                 rx_buf_size=2148 socket 0
 262     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 263                                                 rx_buf_size=2148 socket 0
 264     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 265                                                 rx_buf_size=2148 socket 0
 266     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 267                                                 rx_buf_size=2148 socket 0
 268     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 269     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 270       [...]
 271     Checking link statuses...
 272     Port 0 Link Up - speed 25000 Mbps - full-duplex
 273     Port 1 Link Up - speed 25000 Mbps - full-duplex
 274     Port 2 Link Up - speed 25000 Mbps - full-duplex
 275     Port 3 Link Up - speed 25000 Mbps - full-duplex
 276     Done
 277     testpmd>