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_TX`` (default **n**)
  91
  92   Toggle display of transmit fast path run-time messages.
  93
  94 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
  95
  96   Toggle display of receive fast path run-time messages.
  97
  98 - ``CONFIG_RTE_LIBRTE_QEDE_VF_TX_SWITCH`` (default **"y"**)
  99
 100   A knob to control per-VF Tx switching feature.
 101
 102 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
 103
 104   Gives absolute path of firmware file.
 105   ``Eg: "/lib/firmware/qed/qed_init_values-8.30.12.0.bin"``
 106   Empty string indicates driver will pick up the firmware file
 107   from the default location /lib/firmware/qed.
 108   CAUTION this option is more for custom firmware, it is not
 109   recommended for use under normal condition.
 110
 111 Driver compilation and testing
 112 ------------------------------
 113
 114 Refer to the document :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>`
 115 for details.
 116
 117 SR-IOV: Prerequisites and Sample Application Notes
 118 --------------------------------------------------
 119
 120 This section provides instructions to configure SR-IOV with Linux OS.
 121
 122 **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.
 123
 124 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 125
 126    .. code-block:: console
 127
 128       lspci -s <slot> -vvv
 129
 130    Example output:
 131
 132    .. code-block:: console
 133
 134       [...]
 135       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 136       [...]
 137       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 138       [...]
 139       Kernel driver in use: igb_uio
 140
 141 #. Load the kernel module:
 142
 143    .. code-block:: console
 144
 145       modprobe qede
 146
 147    Example output:
 148
 149    .. code-block:: console
 150
 151       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 152       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 153
 154 #. Bring up the PF ports:
 155
 156    .. code-block:: console
 157
 158       ifconfig ens5f0 up
 159       ifconfig ens5f1 up
 160
 161 #. Create VF device(s):
 162
 163    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 164    of the parent PF.
 165
 166    Example output:
 167
 168    .. code-block:: console
 169
 170       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 171
 172
 173 #. Assign VF MAC address:
 174
 175    Assign MAC address to the VF using iproute2 utility. The syntax is::
 176
 177       ip link set <PF iface> vf <VF id> mac <macaddr>
 178
 179    Example output:
 180
 181    .. code-block:: console
 182
 183       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 184
 185
 186 #. PCI Passthrough:
 187
 188    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 189    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 190    using the instructions from Driver compilation and testing section above.
 191
 192
 193 #. Running testpmd
 194    (Supply ``--log-level="pmd.qede.driver",7`` to view informational messages):
 195
 196    Refer to the document
 197    :ref:`compiling and testing a PMD for a NIC <pmd_build_and_test>` to run
 198    ``testpmd`` application.
 199
 200    Example output:
 201
 202    .. code-block:: console
 203
 204       testpmd -l 0,4-11 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 205       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 206       --rss-ip --rss-udp
 207
 208       [...]
 209
 210     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 211     EAL:   probe driver: 1077:1634 rte_qede_pmd
 212     EAL:   Not managed by a supported kernel driver, skipped
 213     EAL: PCI device 0000:84:00.1 on NUMA socket 1
 214     EAL:   probe driver: 1077:1634 rte_qede_pmd
 215     EAL:   Not managed by a supported kernel driver, skipped
 216     EAL: PCI device 0000:88:00.0 on NUMA socket 1
 217     EAL:   probe driver: 1077:1656 rte_qede_pmd
 218     EAL:   PCI memory mapped at 0x7f738b200000
 219     EAL:   PCI memory mapped at 0x7f738b280000
 220     EAL:   PCI memory mapped at 0x7f738b300000
 221     PMD: Chip details : BB1
 222     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 223     PMD: Firmware version : 8.7.7.0
 224     PMD: Management firmware version : 8.7.8.0
 225     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 226     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 227                                                         00:0e:1e:d2:09:9c
 228       [...]
 229     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 230                                                 tx_free_thresh 4068 socket 0
 231     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 232                                                 tx_free_thresh 4068 socket 0
 233     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 234                                                  tx_free_thresh 4068 socket 0
 235     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 236                                                  tx_free_thresh 4068 socket 0
 237     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 238                                                 rx_buf_size=2148 socket 0
 239     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 240                                                 rx_buf_size=2148 socket 0
 241     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 242                                                 rx_buf_size=2148 socket 0
 243     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 244                                                 rx_buf_size=2148 socket 0
 245     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 246     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 247       [...]
 248     Checking link statuses...
 249     Port 0 Link Up - speed 25000 Mbps - full-duplex
 250     Port 1 Link Up - speed 25000 Mbps - full-duplex
 251     Port 2 Link Up - speed 25000 Mbps - full-duplex
 252     Port 3 Link Up - speed 25000 Mbps - full-duplex
 253     Done
 254     testpmd>