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