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