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.33.12.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.33.12.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 management firmware (MFW) version **8.34.x.x** or higher to be
  70   flashed on to the adapter. If the required management firmware is not
  71   available then download from
  72   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  73   For downloading firmware upgrade utility, select adapter category, model and Linux distro.
  74   To flash the management firmware refer to the instructions in the QLogic Firmware Upgrade Utility Readme document.
  75
  76 - SR-IOV requires Linux PF driver version **8.20.x.x** or higher.
  77   If the required PF driver is not available then download it from
  78   `QLogic Driver Download Center <http://driverdownloads.qlogic.com/QLogicDriverDownloads_UI/DefaultNewSearch.aspx>`_.
  79   For downloading PF driver, select adapter category, model and Linux distro.
  80
  81
  82 Performance note
  83 ~~~~~~~~~~~~~~~~
  84
  85 - For better performance, it is recommended to use 4K or higher RX/TX rings.
  86
  87 Config File Options
  88 ~~~~~~~~~~~~~~~~~~~
  89
  90 The following options can be modified in the ``.config`` file. Please note that
  91 enabling debugging options may affect system performance.
  92
  93 - ``CONFIG_RTE_LIBRTE_QEDE_PMD`` (default **y**)
  94
  95   Toggle compilation of QEDE PMD driver.
  96
  97 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_TX`` (default **n**)
  98
  99   Toggle display of transmit fast path run-time messages.
 100
 101 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
 102
 103   Toggle display of receive fast path run-time messages.
 104
 105 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
 106
 107   Gives absolute path of firmware file.
 108   ``Eg: "/lib/firmware/qed/qed_init_values-8.33.12.0.bin"``
 109   Empty string indicates driver will pick up the firmware file
 110   from the default location /lib/firmware/qed.
 111   CAUTION this option is more for custom firmware, it is not
 112   recommended for use under normal condition.
 113
 114 Driver compilation and testing
 115 ------------------------------
 116
 117 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 118 for details.
 119
 120 SR-IOV: Prerequisites and Sample Application Notes
 121 --------------------------------------------------
 122
 123 This section provides instructions to configure SR-IOV with Linux OS.
 124
 125 **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.
 126
 127 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 128
 129    .. code-block:: console
 130
 131       lspci -s <slot> -vvv
 132
 133    Example output:
 134
 135    .. code-block:: console
 136
 137       [...]
 138       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 139       [...]
 140       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 141       [...]
 142       Kernel driver in use: igb_uio
 143
 144 #. Load the kernel module:
 145
 146    .. code-block:: console
 147
 148       modprobe qede
 149
 150    Example output:
 151
 152    .. code-block:: console
 153
 154       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 155       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 156
 157 #. Bring up the PF ports:
 158
 159    .. code-block:: console
 160
 161       ifconfig ens5f0 up
 162       ifconfig ens5f1 up
 163
 164 #. Create VF device(s):
 165
 166    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 167    of the parent PF.
 168
 169    Example output:
 170
 171    .. code-block:: console
 172
 173       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 174
 175
 176 #. Assign VF MAC address:
 177
 178    Assign MAC address to the VF using iproute2 utility. The syntax is::
 179
 180       ip link set <PF iface> vf <VF id> mac <macaddr>
 181
 182    Example output:
 183
 184    .. code-block:: console
 185
 186       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 187
 188
 189 #. PCI Passthrough:
 190
 191    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 192    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 193    using the instructions from Driver compilation and testing section above.
 194
 195
 196 #. Running testpmd
 197    (Supply ``--log-level="pmd.net.qede.driver:info`` to view informational messages):
 198
 199    Refer to the document
 200    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 201    ``testpmd`` application.
 202
 203    Example output:
 204
 205    .. code-block:: console
 206
 207       testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 208       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 209       --rss-ip --rss-udp
 210
 211       [...]
 212
 213     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 214     EAL:   probe driver: 1077:1634 rte_qede_pmd
 215     EAL:   Not managed by a supported kernel driver, skipped
 216     EAL: PCI device 0000:84:00.1 on NUMA socket 1
 217     EAL:   probe driver: 1077:1634 rte_qede_pmd
 218     EAL:   Not managed by a supported kernel driver, skipped
 219     EAL: PCI device 0000:88:00.0 on NUMA socket 1
 220     EAL:   probe driver: 1077:1656 rte_qede_pmd
 221     EAL:   PCI memory mapped at 0x7f738b200000
 222     EAL:   PCI memory mapped at 0x7f738b280000
 223     EAL:   PCI memory mapped at 0x7f738b300000
 224     PMD: Chip details : BB1
 225     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 226     PMD: Firmware version : 8.7.7.0
 227     PMD: Management firmware version : 8.7.8.0
 228     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 229     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 230                                                         00:0e:1e:d2:09:9c
 231       [...]
 232     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 233                                                 tx_free_thresh 4068 socket 0
 234     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 235                                                 tx_free_thresh 4068 socket 0
 236     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 237                                                  tx_free_thresh 4068 socket 0
 238     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 239                                                  tx_free_thresh 4068 socket 0
 240     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 241                                                 rx_buf_size=2148 socket 0
 242     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 243                                                 rx_buf_size=2148 socket 0
 244     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 245                                                 rx_buf_size=2148 socket 0
 246     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 247                                                 rx_buf_size=2148 socket 0
 248     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 249     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 250       [...]
 251     Checking link statuses...
 252     Port 0 Link Up - speed 25000 Mbps - full-duplex
 253     Port 1 Link Up - speed 25000 Mbps - full-duplex
 254     Port 2 Link Up - speed 25000 Mbps - full-duplex
 255     Port 3 Link Up - speed 25000 Mbps - full-duplex
 256     Done
 257     testpmd>