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