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