doc/guides/nics/mlx4.rst

   1 ..  BSD LICENSE
   2     Copyright 2012 6WIND S.A.
   3     Copyright 2015 Mellanox
   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 6WIND S.A. 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 MLX4 poll mode driver library
  32 =============================
  33
  34 The MLX4 poll mode driver library (**librte_pmd_mlx4**) implements support
  35 for **Mellanox ConnectX-3** and **Mellanox ConnectX-3 Pro** 10/40 Gbps adapters
  36 as well as their virtual functions (VF) in SR-IOV context.
  37
  38 Information and documentation about this family of adapters can be found on
  39 the `Mellanox website <http://www.mellanox.com>`_. Help is also provided by
  40 the `Mellanox community <http://community.mellanox.com/welcome>`_.
  41
  42 There is also a `section dedicated to this poll mode driver
  43 <http://www.mellanox.com/page/products_dyn?product_family=209&mtag=pmd_for_dpdk>`_.
  44
  45 .. note::
  46
  47    Due to external dependencies, this driver is disabled by default. It must
  48    be enabled manually by setting ``CONFIG_RTE_LIBRTE_MLX4_PMD=y`` and
  49    recompiling DPDK.
  50
  51 Implementation details
  52 ----------------------
  53
  54 Most Mellanox ConnectX-3 devices provide two ports but expose a single PCI
  55 bus address, thus unlike most drivers, librte_pmd_mlx4 registers itself as a
  56 PCI driver that allocates one Ethernet device per detected port.
  57
  58 For this reason, one cannot white/blacklist a single port without also
  59 white/blacklisting the others on the same device.
  60
  61 Besides its dependency on libibverbs (that implies libmlx4 and associated
  62 kernel support), librte_pmd_mlx4 relies heavily on system calls for control
  63 operations such as querying/updating the MTU and flow control parameters.
  64
  65 For security reasons and robustness, this driver only deals with virtual
  66 memory addresses. The way resources allocations are handled by the kernel
  67 combined with hardware specifications that allow it to handle virtual memory
  68 addresses directly ensure that DPDK applications cannot access random
  69 physical memory (or memory that does not belong to the current process).
  70
  71 This capability allows the PMD to coexist with kernel network interfaces
  72 which remain functional, although they stop receiving unicast packets as
  73 long as they share the same MAC address.
  74
  75 Compiling librte_pmd_mlx4 causes DPDK to be linked against libibverbs.
  76
  77 Features
  78 --------
  79
  80 - Multi arch support: x86_64 and POWER8.
  81 - Link state information is provided.
  82 - RX interrupts.
  83
  84 Configuration
  85 -------------
  86
  87 Compilation options
  88 ~~~~~~~~~~~~~~~~~~~
  89
  90 These options can be modified in the ``.config`` file.
  91
  92 - ``CONFIG_RTE_LIBRTE_MLX4_PMD`` (default **n**)
  93
  94   Toggle compilation of librte_pmd_mlx4 itself.
  95
  96 - ``CONFIG_RTE_LIBRTE_MLX4_DEBUG`` (default **n**)
  97
  98   Toggle debugging code and stricter compilation flags. Enabling this option
  99   adds additional run-time checks and debugging messages at the cost of
 100   lower performance.
 101
 102 - ``CONFIG_RTE_LIBRTE_MLX4_DEBUG_BROKEN_VERBS`` (default **n**)
 103
 104   Mellanox OFED versions earlier than 4.2 may return false errors from
 105   Verbs object destruction APIs after the device is plugged out.
 106   Enabling this option replaces assertion checks that cause the program
 107   to abort with harmless debugging messages as a workaround.
 108   Relevant only when CONFIG_RTE_LIBRTE_MLX4_DEBUG is enabled.
 109
 110 - ``CONFIG_RTE_LIBRTE_MLX4_TX_MP_CACHE`` (default **8**)
 111
 112   Maximum number of cached memory pools (MPs) per TX queue. Each MP from
 113   which buffers are to be transmitted must be associated to memory regions
 114   (MRs). This is a slow operation that must be cached.
 115
 116   This value is always 1 for RX queues since they use a single MP.
 117
 118 Run-time configuration
 119 ~~~~~~~~~~~~~~~~~~~~~~
 120
 121 - librte_pmd_mlx4 brings kernel network interfaces up during initialization
 122   because it is affected by their state. Forcing them down prevents packets
 123   reception.
 124
 125 - **ethtool** operations on related kernel interfaces also affect the PMD.
 126
 127 - ``port`` parameter [int]
 128
 129   This parameter provides a physical port to probe and can be specified multiple
 130   times for additional ports. All ports are probed by default if left
 131   unspecified.
 132
 133 Kernel module parameters
 134 ~~~~~~~~~~~~~~~~~~~~~~~~
 135
 136 The **mlx4_core** kernel module has several parameters that affect the
 137 behavior and/or the performance of librte_pmd_mlx4. Some of them are described
 138 below.
 139
 140 - **num_vfs** (integer or triplet, optionally prefixed by device address
 141   strings)
 142
 143   Create the given number of VFs on the specified devices.
 144
 145 - **log_num_mgm_entry_size** (integer)
 146
 147   Device-managed flow steering (DMFS) is required by DPDK applications. It is
 148   enabled by using a negative value, the last four bits of which have a
 149   special meaning.
 150
 151   - **-1**: force device-managed flow steering (DMFS).
 152   - **-7**: configure optimized steering mode to improve performance with the
 153     following limitation: VLAN filtering is not supported with this mode.
 154     This is the recommended mode in case VLAN filter is not needed.
 155
 156 Prerequisites
 157 -------------
 158
 159 This driver relies on external libraries and kernel drivers for resources
 160 allocations and initialization. The following dependencies are not part of
 161 DPDK and must be installed separately:
 162
 163 - **libibverbs**
 164
 165   User space verbs framework used by librte_pmd_mlx4. This library provides
 166   a generic interface between the kernel and low-level user space drivers
 167   such as libmlx4.
 168
 169   It allows slow and privileged operations (context initialization, hardware
 170   resources allocations) to be managed by the kernel and fast operations to
 171   never leave user space.
 172
 173 - **libmlx4**
 174
 175   Low-level user space driver library for Mellanox ConnectX-3 devices,
 176   it is automatically loaded by libibverbs.
 177
 178   This library basically implements send/receive calls to the hardware
 179   queues.
 180
 181 - **Kernel modules** (mlnx-ofed-kernel)
 182
 183   They provide the kernel-side verbs API and low level device drivers that
 184   manage actual hardware initialization and resources sharing with user
 185   space processes.
 186
 187   Unlike most other PMDs, these modules must remain loaded and bound to
 188   their devices:
 189
 190   - mlx4_core: hardware driver managing Mellanox ConnectX-3 devices.
 191   - mlx4_en: Ethernet device driver that provides kernel network interfaces.
 192   - mlx4_ib: InifiniBand device driver.
 193   - ib_uverbs: user space driver for verbs (entry point for libibverbs).
 194
 195 - **Firmware update**
 196
 197   Mellanox OFED releases include firmware updates for ConnectX-3 adapters.
 198
 199   Because each release provides new features, these updates must be applied to
 200   match the kernel modules and libraries they come with.
 201
 202 .. note::
 203
 204    Both libraries are BSD and GPL licensed. Linux kernel modules are GPL
 205    licensed.
 206
 207 Currently supported by DPDK:
 208
 209 - Mellanox OFED **4.1**.
 210 - Firmware version **2.36.5000** and above.
 211
 212 Getting Mellanox OFED
 213 ~~~~~~~~~~~~~~~~~~~~~
 214
 215 While these libraries and kernel modules are available on OpenFabrics
 216 Alliance's `website <https://www.openfabrics.org/>`_ and provided by package
 217 managers on most distributions, this PMD requires Ethernet extensions that
 218 may not be supported at the moment (this is a work in progress).
 219
 220 `Mellanox OFED
 221 <http://www.mellanox.com/page/products_dyn?product_family=26&mtag=linux_sw_drivers>`_
 222 includes the necessary support and should be used in the meantime. For DPDK,
 223 only libibverbs, libmlx4, mlnx-ofed-kernel packages and firmware updates are
 224 required from that distribution.
 225
 226 .. note::
 227
 228    Several versions of Mellanox OFED are available. Installing the version
 229    this DPDK release was developed and tested against is strongly
 230    recommended. Please check the `prerequisites`_.
 231
 232 Supported NICs
 233 --------------
 234
 235 * Mellanox(R) ConnectX(R)-3 Pro 40G MCX354A-FCC_Ax (2*40G)
 236
 237 Quick Start Guide
 238 -----------------
 239
 240 1. Download latest Mellanox OFED. For more info check the  `prerequisites`_.
 241
 242 2. Install the required libraries and kernel modules either by installing
 243    only the required set, or by installing the entire Mellanox OFED:
 244
 245    For bare metal use:
 246
 247    .. code-block:: console
 248
 249         ./mlnxofedinstall
 250
 251    For SR-IOV hypervisors use:
 252
 253    .. code-block:: console
 254
 255         ./mlnxofedinstall --enable-sriov -hypervisor
 256
 257    For SR-IOV virtual machine use:
 258
 259    .. code-block:: console
 260
 261         ./mlnxofedinstall --guest
 262
 263 3. Verify the firmware is the correct one:
 264
 265    .. code-block:: console
 266
 267         ibv_devinfo
 268
 269 4. Set all ports links to Ethernet, follow instructions on the screen:
 270
 271    .. code-block:: console
 272
 273         connectx_port_config
 274
 275    Or in the manual way:
 276
 277    .. code-block:: console
 278
 279         PCI=<NIC PCI address>
 280         echo eth > "/sys/bus/pci/devices/$PCI/mlx4_port0"
 281         echo eth > "/sys/bus/pci/devices/$PCI/mlx4_port1"
 282
 283 5. In case of bare metal or hypervisor, configure optimized steering mode
 284    by adding the following line to ``/etc/modprobe.d/mlx4_core.conf``:
 285
 286    .. code-block:: console
 287
 288         options mlx4_core log_num_mgm_entry_size=-7
 289
 290    .. note::
 291
 292         If VLAN filtering is used, set log_num_mgm_entry_size=-1.
 293         Performance degradation can occur on this case.
 294
 295 6. Restart the driver:
 296
 297    .. code-block:: console
 298
 299         /etc/init.d/openibd restart
 300
 301    or:
 302
 303    .. code-block:: console
 304
 305         service openibd restart
 306
 307 7. Compile DPDK and you are ready to go. See instructions on
 308    :ref:`Development Kit Build System <Development_Kit_Build_System>`
 309
 310 Performance tuning
 311 ------------------
 312
 313 1. Verify the optimized steering mode is configured:
 314
 315   .. code-block:: console
 316
 317         cat /sys/module/mlx4_core/parameters/log_num_mgm_entry_size
 318
 319 2. Use the CPU near local NUMA node to which the PCIe adapter is connected,
 320    for better performance. For VMs, verify that the right CPU
 321    and NUMA node are pinned according to the above. Run:
 322
 323    .. code-block:: console
 324
 325         lstopo-no-graphics
 326
 327    to identify the NUMA node to which the PCIe adapter is connected.
 328
 329 3. If more than one adapter is used, and root complex capabilities allow
 330    to put both adapters on the same NUMA node without PCI bandwidth degradation,
 331    it is recommended to locate both adapters on the same NUMA node.
 332    This in order to forward packets from one to the other without
 333    NUMA performance penalty.
 334
 335 4. Disable pause frames:
 336
 337    .. code-block:: console
 338
 339         ethtool -A <netdev> rx off tx off
 340
 341 5. Verify IO non-posted prefetch is disabled by default. This can be checked
 342    via the BIOS configuration. Please contact you server provider for more
 343    information about the settings.
 344
 345 .. note::
 346
 347         On some machines, depends on the machine integrator, it is beneficial
 348         to set the PCI max read request parameter to 1K. This can be
 349         done in the following way:
 350
 351         To query the read request size use:
 352
 353         .. code-block:: console
 354
 355                 setpci -s <NIC PCI address> 68.w
 356
 357         If the output is different than 3XXX, set it by:
 358
 359         .. code-block:: console
 360
 361                 setpci -s <NIC PCI address> 68.w=3XXX
 362
 363         The XXX can be different on different systems. Make sure to configure
 364         according to the setpci output.
 365
 366 Usage example
 367 -------------
 368
 369 This section demonstrates how to launch **testpmd** with Mellanox ConnectX-3
 370 devices managed by librte_pmd_mlx4.
 371
 372 #. Load the kernel modules:
 373
 374    .. code-block:: console
 375
 376       modprobe -a ib_uverbs mlx4_en mlx4_core mlx4_ib
 377
 378    Alternatively if MLNX_OFED is fully installed, the following script can
 379    be run:
 380
 381    .. code-block:: console
 382
 383       /etc/init.d/openibd restart
 384
 385    .. note::
 386
 387       User space I/O kernel modules (uio and igb_uio) are not used and do
 388       not have to be loaded.
 389
 390 #. Make sure Ethernet interfaces are in working order and linked to kernel
 391    verbs. Related sysfs entries should be present:
 392
 393    .. code-block:: console
 394
 395       ls -d /sys/class/net/*/device/infiniband_verbs/uverbs* | cut -d / -f 5
 396
 397    Example output:
 398
 399    .. code-block:: console
 400
 401       eth2
 402       eth3
 403       eth4
 404       eth5
 405
 406 #. Optionally, retrieve their PCI bus addresses for whitelisting:
 407
 408    .. code-block:: console
 409
 410       {
 411           for intf in eth2 eth3 eth4 eth5;
 412           do
 413               (cd "/sys/class/net/${intf}/device/" && pwd -P);
 414           done;
 415       } |
 416       sed -n 's,.*/\(.*\),-w \1,p'
 417
 418    Example output:
 419
 420    .. code-block:: console
 421
 422       -w 0000:83:00.0
 423       -w 0000:83:00.0
 424       -w 0000:84:00.0
 425       -w 0000:84:00.0
 426
 427    .. note::
 428
 429       There are only two distinct PCI bus addresses because the Mellanox
 430       ConnectX-3 adapters installed on this system are dual port.
 431
 432 #. Request huge pages:
 433
 434    .. code-block:: console
 435
 436       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
 437
 438 #. Start testpmd with basic parameters:
 439
 440    .. code-block:: console
 441
 442       testpmd -l 8-15 -n 4 -w 0000:83:00.0 -w 0000:84:00.0 -- --rxq=2 --txq=2 -i
 443
 444    Example output:
 445
 446    .. code-block:: console
 447
 448       [...]
 449       EAL: PCI device 0000:83:00.0 on NUMA socket 1
 450       EAL:   probe driver: 15b3:1007 librte_pmd_mlx4
 451       PMD: librte_pmd_mlx4: PCI information matches, using device "mlx4_0" (VF: false)
 452       PMD: librte_pmd_mlx4: 2 port(s) detected
 453       PMD: librte_pmd_mlx4: port 1 MAC address is 00:02:c9:b5:b7:50
 454       PMD: librte_pmd_mlx4: port 2 MAC address is 00:02:c9:b5:b7:51
 455       EAL: PCI device 0000:84:00.0 on NUMA socket 1
 456       EAL:   probe driver: 15b3:1007 librte_pmd_mlx4
 457       PMD: librte_pmd_mlx4: PCI information matches, using device "mlx4_1" (VF: false)
 458       PMD: librte_pmd_mlx4: 2 port(s) detected
 459       PMD: librte_pmd_mlx4: port 1 MAC address is 00:02:c9:b5:ba:b0
 460       PMD: librte_pmd_mlx4: port 2 MAC address is 00:02:c9:b5:ba:b1
 461       Interactive-mode selected
 462       Configuring Port 0 (socket 0)
 463       PMD: librte_pmd_mlx4: 0x867d60: TX queues number update: 0 -> 2
 464       PMD: librte_pmd_mlx4: 0x867d60: RX queues number update: 0 -> 2
 465       Port 0: 00:02:C9:B5:B7:50
 466       Configuring Port 1 (socket 0)
 467       PMD: librte_pmd_mlx4: 0x867da0: TX queues number update: 0 -> 2
 468       PMD: librte_pmd_mlx4: 0x867da0: RX queues number update: 0 -> 2
 469       Port 1: 00:02:C9:B5:B7:51
 470       Configuring Port 2 (socket 0)
 471       PMD: librte_pmd_mlx4: 0x867de0: TX queues number update: 0 -> 2
 472       PMD: librte_pmd_mlx4: 0x867de0: RX queues number update: 0 -> 2
 473       Port 2: 00:02:C9:B5:BA:B0
 474       Configuring Port 3 (socket 0)
 475       PMD: librte_pmd_mlx4: 0x867e20: TX queues number update: 0 -> 2
 476       PMD: librte_pmd_mlx4: 0x867e20: RX queues number update: 0 -> 2
 477       Port 3: 00:02:C9:B5:BA:B1
 478       Checking link statuses...
 479       Port 0 Link Up - speed 10000 Mbps - full-duplex
 480       Port 1 Link Up - speed 40000 Mbps - full-duplex
 481       Port 2 Link Up - speed 10000 Mbps - full-duplex
 482       Port 3 Link Up - speed 40000 Mbps - full-duplex
 483       Done
 484       testpmd>