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_net_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 Options
 107 ~~~~~~~~~~~~~~
 108
 109 The following option can be modified in the ``config/rte_config.h`` file.
 110
 111 - ``RTE_LIBRTE_QEDE_FW`` (default **""**)
 112
 113   Gives absolute path of firmware file.
 114   ``Eg: "/lib/firmware/qed/qed_init_values-8.40.33.0.bin"``
 115   Empty string indicates driver will pick up the firmware file
 116   from the default location /lib/firmware/qed.
 117   CAUTION this option is more for custom firmware, it is not
 118   recommended for use under normal condition.
 119
 120 The following options can be enabled with Meson flags.
 121
 122 - ``RTE_LIBRTE_QEDE_DEBUG_TX`` (default **disabled**)
 123
 124   Toggle display of transmit fast path run-time messages.
 125
 126 - ``RTE_LIBRTE_QEDE_DEBUG_RX`` (default **disabled**)
 127
 128   Toggle display of receive fast path run-time messages.
 129
 130 Config notes
 131 ~~~~~~~~~~~~
 132
 133 When there are multiple adapters and/or large number of Rx/Tx queues
 134 configured on the adapters, the default (2560) number of memzone
 135 descriptors may not be enough. Please increase the number of memzone
 136 descriptors to a higher number as needed. When sufficient number of
 137 memzone descriptors are not configured, user can potentially run into
 138 following error.
 139
 140    .. code-block:: console
 141
 142       EAL: memzone_reserve_aligned_thread_unsafe(): No more room in config
 143
 144 Driver compilation and testing
 145 ------------------------------
 146
 147 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 148 for details.
 149
 150 RTE Flow Support
 151 ----------------
 152
 153 QLogic FastLinQ QL4xxxx NICs has support for the following patterns and
 154 actions.
 155
 156 Patterns:
 157
 158 .. _table_qede_supported_flow_item_types:
 159
 160 .. table:: Item types
 161
 162    +----+--------------------------------+
 163    | #  | Pattern Type                   |
 164    +====+================================+
 165    | 1  | RTE_FLOW_ITEM_TYPE_IPV4        |
 166    +----+--------------------------------+
 167    | 2  | RTE_FLOW_ITEM_TYPE_IPV6        |
 168    +----+--------------------------------+
 169    | 3  | RTE_FLOW_ITEM_TYPE_UDP         |
 170    +----+--------------------------------+
 171    | 4  | RTE_FLOW_ITEM_TYPE_TCP         |
 172    +----+--------------------------------+
 173
 174 Actions:
 175
 176 .. _table_qede_supported_ingress_action_types:
 177
 178 .. table:: Ingress action types
 179
 180    +----+--------------------------------+
 181    | #  | Action Type                    |
 182    +====+================================+
 183    | 1  | RTE_FLOW_ACTION_TYPE_QUEUE     |
 184    +----+--------------------------------+
 185    | 2  | RTE_FLOW_ACTION_TYPE_DROP      |
 186    +----+--------------------------------+
 187
 188 SR-IOV: Prerequisites and Sample Application Notes
 189 --------------------------------------------------
 190
 191 This section provides instructions to configure SR-IOV with Linux OS.
 192
 193 **Note**: librte_net_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.
 194
 195 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 196
 197    .. code-block:: console
 198
 199       lspci -s <slot> -vvv
 200
 201    Example output:
 202
 203    .. code-block:: console
 204
 205       [...]
 206       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 207       [...]
 208       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 209       [...]
 210       Kernel driver in use: igb_uio
 211
 212 #. Load the kernel module:
 213
 214    .. code-block:: console
 215
 216       modprobe qede
 217
 218    Example output:
 219
 220    .. code-block:: console
 221
 222       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 223       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 224
 225 #. Bring up the PF ports:
 226
 227    .. code-block:: console
 228
 229       ifconfig ens5f0 up
 230       ifconfig ens5f1 up
 231
 232 #. Create VF device(s):
 233
 234    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 235    of the parent PF.
 236
 237    Example output:
 238
 239    .. code-block:: console
 240
 241       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 242
 243
 244 #. Assign VF MAC address:
 245
 246    Assign MAC address to the VF using iproute2 utility. The syntax is::
 247
 248       ip link set <PF iface> vf <VF id> mac <macaddr>
 249
 250    Example output:
 251
 252    .. code-block:: console
 253
 254       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 255
 256
 257 #. PCI Passthrough:
 258
 259    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 260    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 261    using the instructions from Driver compilation and testing section above.
 262
 263
 264 #. Running testpmd
 265    (Supply ``--log-level="pmd.net.qede.driver:info`` to view informational messages):
 266
 267    Refer to the document
 268    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 269    ``testpmd`` application.
 270
 271    Example output:
 272
 273    .. code-block:: console
 274
 275       dpdk-testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 276       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 277       --rss-ip --rss-udp
 278
 279       [...]
 280
 281     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 282     EAL:   probe driver: 1077:1634 rte_qede_pmd
 283     EAL:   Not managed by a supported kernel driver, skipped
 284     EAL: PCI device 0000:84:00.1 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:88:00.0 on NUMA socket 1
 288     EAL:   probe driver: 1077:1656 rte_qede_pmd
 289     EAL:   PCI memory mapped at 0x7f738b200000
 290     EAL:   PCI memory mapped at 0x7f738b280000
 291     EAL:   PCI memory mapped at 0x7f738b300000
 292     PMD: Chip details : BB1
 293     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 294     PMD: Firmware version : 8.7.7.0
 295     PMD: Management firmware version : 8.7.8.0
 296     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 297     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 298                                                         00:0e:1e:d2:09:9c
 299       [...]
 300     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 301                                                 tx_free_thresh 4068 socket 0
 302     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 303                                                 tx_free_thresh 4068 socket 0
 304     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 305                                                  tx_free_thresh 4068 socket 0
 306     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 307                                                  tx_free_thresh 4068 socket 0
 308     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 309                                                 rx_buf_size=2148 socket 0
 310     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 311                                                 rx_buf_size=2148 socket 0
 312     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 313                                                 rx_buf_size=2148 socket 0
 314     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 315                                                 rx_buf_size=2148 socket 0
 316     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 317     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 318       [...]
 319     Checking link statuses...
 320     Port 0 Link Up - speed 25000 Mbps - full-duplex
 321     Port 1 Link Up - speed 25000 Mbps - full-duplex
 322     Port 2 Link Up - speed 25000 Mbps - full-duplex
 323     Port 3 Link Up - speed 25000 Mbps - full-duplex
 324     Done
 325     testpmd>