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