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