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