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