doc/guides/nics/qede.rst

   1 ..  BSD LICENSE
   2     Copyright (c) 2016 QLogic Corporation
   3     All rights reserved.
   4
   5     Redistribution and use in source and binary forms, with or without
   6     modification, are permitted provided that the following conditions
   7     are met:
   8
   9     * Redistributions of source code must retain the above copyright
  10     notice, this list of conditions and the following disclaimer.
  11     * Redistributions in binary form must reproduce the above copyright
  12     notice, this list of conditions and the following disclaimer in
  13     the documentation and/or other materials provided with the
  14     distribution.
  15     * Neither the name of QLogic Corporation nor the names of its
  16     contributors may be used to endorse or promote products derived
  17     from this software without specific prior written permission.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25     LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26     DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27     THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30
  31 QEDE Poll Mode Driver
  32 ======================
  33
  34 The QEDE poll mode driver library (**librte_pmd_qede**) implements support
  35 for **QLogic FastLinQ QL4xxxx 25G/40G/100G CNA** family of adapters as well
  36 as their virtual functions (VF) in SR-IOV context. It is supported on
  37 several standard Linux distros like RHEL7.x, SLES12.x and Ubuntu.
  38 It is compile-tested under FreeBSD OS.
  39
  40 More information can be found at `QLogic Corporation's Website
  41 <http://www.qlogic.com>`_.
  42
  43 Supported Features
  44 ------------------
  45
  46 - Unicast/Multicast filtering
  47 - Promiscuous mode
  48 - Allmulti mode
  49 - Port hardware statistics
  50 - Jumbo frames
  51 - VLAN offload - Filtering and stripping
  52 - Stateless checksum offloads (IPv4/TCP/UDP)
  53 - Multiple Rx/Tx queues
  54 - RSS (with RETA/hash table/key)
  55 - TSS
  56 - Multiple MAC address
  57 - Default pause flow control
  58 - SR-IOV VF
  59 - MTU change
  60 - Multiprocess aware
  61 - Scatter-Gather
  62
  63 Non-supported Features
  64 ----------------------
  65
  66 - SR-IOV PF
  67 - Tunneling offloads
  68
  69 Supported QLogic Adapters
  70 -------------------------
  71
  72 - QLogic FastLinQ QL4xxxx 25G/40G/100G CNAs.
  73
  74 Prerequisites
  75 -------------
  76
  77 - Requires firmware version **8.10.x.** and management firmware
  78   version **8.10.x or higher**. Firmware may be available
  79   inbox in certain newer Linux distros under the standard directory
  80   ``E.g. /lib/firmware/qed/qed_init_values-8.10.9.0.bin``
  81
  82 - If the required firmware files are not available then visit
  83   `QLogic Driver Download Center <http://driverdownloads.qlogic.com>`_.
  84
  85 Performance note
  86 ~~~~~~~~~~~~~~~~
  87
  88 - For better performance, it is recommended to use 4K or higher RX/TX rings.
  89
  90 Config File Options
  91 ~~~~~~~~~~~~~~~~~~~
  92
  93 The following options can be modified in the ``.config`` file. Please note that
  94 enabling debugging options may affect system performance.
  95
  96 - ``CONFIG_RTE_LIBRTE_QEDE_PMD`` (default **y**)
  97
  98   Toggle compilation of QEDE PMD driver.
  99
 100 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_INFO`` (default **n**)
 101
 102   Toggle display of generic debugging messages.
 103
 104 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_DRIVER`` (default **n**)
 105
 106   Toggle display of ecore related messages.
 107
 108 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_TX`` (default **n**)
 109
 110   Toggle display of transmit fast path run-time messages.
 111
 112 - ``CONFIG_RTE_LIBRTE_QEDE_DEBUG_RX`` (default **n**)
 113
 114   Toggle display of receive fast path run-time messages.
 115
 116 - ``CONFIG_RTE_LIBRTE_QEDE_FW`` (default **""**)
 117
 118   Gives absolute path of firmware file.
 119   ``Eg: "/lib/firmware/qed/qed_init_values_zipped-8.10.9.0.bin"``
 120   Empty string indicates driver will pick up the firmware file
 121   from the default location.
 122
 123 Driver Compilation
 124 ~~~~~~~~~~~~~~~~~~
 125
 126 To compile QEDE PMD for Linux x86_64 gcc target, run the following ``make``
 127 command::
 128
 129    cd <DPDK-source-directory>
 130    make config T=x86_64-native-linuxapp-gcc install
 131
 132 To compile QEDE PMD for Linux x86_64 clang target, run the following ``make``
 133 command::
 134
 135    cd <DPDK-source-directory>
 136    make config T=x86_64-native-linuxapp-clang install
 137
 138 To compile QEDE PMD for FreeBSD x86_64 clang target, run the following ``gmake``
 139 command::
 140
 141    cd <DPDK-source-directory>
 142    gmake config T=x86_64-native-bsdapp-clang install
 143
 144 To compile QEDE PMD for FreeBSD x86_64 gcc target, run the following ``gmake``
 145 command::
 146
 147    cd <DPDK-source-directory>
 148    gmake config T=x86_64-native-bsdapp-gcc install -Wl,-rpath=\
 149                                         /usr/local/lib/gcc49 CC=gcc49
 150
 151
 152 Sample Application Notes
 153 ~~~~~~~~~~~~~~~~~~~~~~~~
 154
 155 This section demonstrates how to launch ``testpmd`` with QLogic 4xxxx
 156 devices managed by ``librte_pmd_qede`` in Linux operating system.
 157
 158 #. Request huge pages:
 159
 160    .. code-block:: console
 161
 162       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/ \
 163                                                                 nr_hugepages
 164
 165 #. Load ``igb_uio`` driver:
 166
 167    .. code-block:: console
 168
 169       insmod ./x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
 170
 171 #. Bind the QLogic 4xxxx adapters to ``igb_uio`` loaded in the
 172    previous step:
 173
 174    .. code-block:: console
 175
 176       ./tools/dpdk-devbind.py --bind igb_uio 0000:84:00.0 0000:84:00.1 \
 177                                               0000:84:00.2 0000:84:00.3
 178
 179 #. Start ``testpmd`` with basic parameters:
 180    (Enable QEDE_DEBUG_INFO=y to view informational messages)
 181
 182    .. code-block:: console
 183
 184       testpmd -c 0xff1 -n 4 -- -i --nb-cores=8 --portmask=0xf --rxd=4096 \
 185       --txd=4096 --txfreet=4068 --enable-rx-cksum --rxq=4 --txq=4 \
 186       --rss-ip --rss-udp
 187
 188       [...]
 189
 190     EAL: PCI device 0000:84:00.0 on NUMA socket 1
 191     EAL:   probe driver: 1077:1634 rte_qede_pmd
 192     EAL:   Not managed by a supported kernel driver, skipped
 193     EAL: PCI device 0000:84:00.1 on NUMA socket 1
 194     EAL:   probe driver: 1077:1634 rte_qede_pmd
 195     EAL:   Not managed by a supported kernel driver, skipped
 196     EAL: PCI device 0000:88:00.0 on NUMA socket 1
 197     EAL:   probe driver: 1077:1656 rte_qede_pmd
 198     EAL:   PCI memory mapped at 0x7f738b200000
 199     EAL:   PCI memory mapped at 0x7f738b280000
 200     EAL:   PCI memory mapped at 0x7f738b300000
 201     PMD: Chip details : BB1
 202     PMD: Driver version : QEDE PMD 8.7.9.0_1.0.0
 203     PMD: Firmware version : 8.7.7.0
 204     PMD: Management firmware version : 8.7.8.0
 205     PMD: Firmware file : /lib/firmware/qed/qed_init_values_zipped-8.7.7.0.bin
 206     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_common_dev_init:macaddr \
 207                                                         00:0e:1e:d2:09:9c
 208       [...]
 209     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 0 num_desc 4096 \
 210                                                 tx_free_thresh 4068 socket 0
 211     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 1 num_desc 4096 \
 212                                                 tx_free_thresh 4068 socket 0
 213     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 2 num_desc 4096 \
 214                                                  tx_free_thresh 4068 socket 0
 215     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_tx_queue_setup:txq 3 num_desc 4096 \
 216                                                  tx_free_thresh 4068 socket 0
 217     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 0 num_desc 4096 \
 218                                                 rx_buf_size=2148 socket 0
 219     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 1 num_desc 4096 \
 220                                                 rx_buf_size=2148 socket 0
 221     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 2 num_desc 4096 \
 222                                                 rx_buf_size=2148 socket 0
 223     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_rx_queue_setup:rxq 3 num_desc 4096 \
 224                                                 rx_buf_size=2148 socket 0
 225     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:port 0
 226     [QEDE PMD: (84:00.0:dpdk-port-0)]qede_dev_start:link status: down
 227       [...]
 228     Checking link statuses...
 229     Port 0 Link Up - speed 25000 Mbps - full-duplex
 230     Port 1 Link Up - speed 25000 Mbps - full-duplex
 231     Port 2 Link Up - speed 25000 Mbps - full-duplex
 232     Port 3 Link Up - speed 25000 Mbps - full-duplex
 233     Done
 234     testpmd>
 235
 236
 237 SR-IOV: Prerequisites and Sample Application Notes
 238 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 239
 240 This section provides instructions to configure SR-IOV with Linux OS.
 241
 242 **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.
 243
 244 #. Verify SR-IOV and ARI capability is enabled on the adapter using ``lspci``:
 245
 246    .. code-block:: console
 247
 248       lspci -s <slot> -vvv
 249
 250    Example output:
 251
 252    .. code-block:: console
 253
 254       [...]
 255       Capabilities: [1b8 v1] Alternative Routing-ID Interpretation (ARI)
 256       [...]
 257       Capabilities: [1c0 v1] Single Root I/O Virtualization (SR-IOV)
 258       [...]
 259       Kernel driver in use: igb_uio
 260
 261 #. Load the kernel module:
 262
 263    .. code-block:: console
 264
 265       modprobe qede
 266
 267    Example output:
 268
 269    .. code-block:: console
 270
 271       systemd-udevd[4848]: renamed network interface eth0 to ens5f0
 272       systemd-udevd[4848]: renamed network interface eth1 to ens5f1
 273
 274 #. Bring up the PF ports:
 275
 276    .. code-block:: console
 277
 278       ifconfig ens5f0 up
 279       ifconfig ens5f1 up
 280
 281 #. Create VF device(s):
 282
 283    Echo the number of VFs to be created into ``"sriov_numvfs"`` sysfs entry
 284    of the parent PF.
 285
 286    Example output:
 287
 288    .. code-block:: console
 289
 290       echo 2 > /sys/devices/pci0000:00/0000:00:03.0/0000:81:00.0/sriov_numvfs
 291
 292
 293 #. Assign VF MAC address:
 294
 295    Assign MAC address to the VF using iproute2 utility. The syntax is::
 296
 297       ip link set <PF iface> vf <VF id> mac <macaddr>
 298
 299    Example output:
 300
 301    .. code-block:: console
 302
 303       ip link set ens5f0 vf 0 mac 52:54:00:2f:9d:e8
 304
 305
 306 #. PCI Passthrough:
 307
 308    The VF devices may be passed through to the guest VM using ``virt-manager`` or
 309    ``virsh``. QEDE PMD should be used to bind the VF devices in the guest VM
 310    using the instructions outlined in the Application notes above.