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