doc/guides/nics/mlx4.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2012 6WIND S.A.
   3     Copyright 2015 Mellanox Technologies, Ltd
   4
   5 MLX4 poll mode driver library
   6 =============================
   7
   8 The MLX4 poll mode driver library (**librte_pmd_mlx4**) implements support
   9 for **Mellanox ConnectX-3** and **Mellanox ConnectX-3 Pro** 10/40 Gbps adapters
  10 as well as their virtual functions (VF) in SR-IOV context.
  11
  12 Information and documentation about this family of adapters can be found on
  13 the `Mellanox website <http://www.mellanox.com>`_. Help is also provided by
  14 the `Mellanox community <http://community.mellanox.com/welcome>`_.
  15
  16 There is also a `section dedicated to this poll mode driver
  17 <http://www.mellanox.com/page/products_dyn?product_family=209&mtag=pmd_for_dpdk>`_.
  18
  19 .. note::
  20
  21    Due to external dependencies, this driver is disabled by default. It must
  22    be enabled manually by setting ``CONFIG_RTE_LIBRTE_MLX4_PMD=y`` and
  23    recompiling DPDK.
  24
  25 Implementation details
  26 ----------------------
  27
  28 Most Mellanox ConnectX-3 devices provide two ports but expose a single PCI
  29 bus address, thus unlike most drivers, librte_pmd_mlx4 registers itself as a
  30 PCI driver that allocates one Ethernet device per detected port.
  31
  32 For this reason, one cannot white/blacklist a single port without also
  33 white/blacklisting the others on the same device.
  34
  35 Besides its dependency on libibverbs (that implies libmlx4 and associated
  36 kernel support), librte_pmd_mlx4 relies heavily on system calls for control
  37 operations such as querying/updating the MTU and flow control parameters.
  38
  39 For security reasons and robustness, this driver only deals with virtual
  40 memory addresses. The way resources allocations are handled by the kernel
  41 combined with hardware specifications that allow it to handle virtual memory
  42 addresses directly ensure that DPDK applications cannot access random
  43 physical memory (or memory that does not belong to the current process).
  44
  45 This capability allows the PMD to coexist with kernel network interfaces
  46 which remain functional, although they stop receiving unicast packets as
  47 long as they share the same MAC address.
  48
  49 Compiling librte_pmd_mlx4 causes DPDK to be linked against libibverbs.
  50
  51 Configuration
  52 -------------
  53
  54 Compilation options
  55 ~~~~~~~~~~~~~~~~~~~
  56
  57 These options can be modified in the ``.config`` file.
  58
  59 - ``CONFIG_RTE_LIBRTE_MLX4_PMD`` (default **n**)
  60
  61   Toggle compilation of librte_pmd_mlx4 itself.
  62
  63 - ``CONFIG_RTE_IBVERBS_LINK_DLOPEN`` (default **n**)
  64
  65   Build PMD with additional code to make it loadable without hard
  66   dependencies on **libibverbs** nor **libmlx4**, which may not be installed
  67   on the target system.
  68
  69   In this mode, their presence is still required for it to run properly,
  70   however their absence won't prevent a DPDK application from starting (with
  71   ``CONFIG_RTE_BUILD_SHARED_LIB`` disabled) and they won't show up as
  72   missing with ``ldd(1)``.
  73
  74   It works by moving these dependencies to a purpose-built rdma-core "glue"
  75   plug-in which must either be installed in a directory whose name is based
  76   on ``CONFIG_RTE_EAL_PMD_PATH`` suffixed with ``-glue`` if set, or in a
  77   standard location for the dynamic linker (e.g. ``/lib``) if left to the
  78   default empty string (``""``).
  79
  80   This option has no performance impact.
  81
  82 - ``CONFIG_RTE_IBVERBS_LINK_STATIC`` (default **n**)
  83
  84   Embed static flavour of the dependencies **libibverbs** and **libmlx4**
  85   in the PMD shared library or the executable static binary.
  86
  87 - ``CONFIG_RTE_LIBRTE_MLX4_DEBUG`` (default **n**)
  88
  89   Toggle debugging code and stricter compilation flags. Enabling this option
  90   adds additional run-time checks and debugging messages at the cost of
  91   lower performance.
  92
  93 Environment variables
  94 ~~~~~~~~~~~~~~~~~~~~~
  95
  96 - ``MLX4_GLUE_PATH``
  97
  98   A list of directories in which to search for the rdma-core "glue" plug-in,
  99   separated by colons or semi-colons.
 100
 101   Only matters when compiled with ``CONFIG_RTE_IBVERBS_LINK_DLOPEN``
 102   enabled and most useful when ``CONFIG_RTE_EAL_PMD_PATH`` is also set,
 103   since ``LD_LIBRARY_PATH`` has no effect in this case.
 104
 105 Run-time configuration
 106 ~~~~~~~~~~~~~~~~~~~~~~
 107
 108 - librte_pmd_mlx4 brings kernel network interfaces up during initialization
 109   because it is affected by their state. Forcing them down prevents packets
 110   reception.
 111
 112 - **ethtool** operations on related kernel interfaces also affect the PMD.
 113
 114 - ``port`` parameter [int]
 115
 116   This parameter provides a physical port to probe and can be specified multiple
 117   times for additional ports. All ports are probed by default if left
 118   unspecified.
 119
 120 Kernel module parameters
 121 ~~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 The **mlx4_core** kernel module has several parameters that affect the
 124 behavior and/or the performance of librte_pmd_mlx4. Some of them are described
 125 below.
 126
 127 - **num_vfs** (integer or triplet, optionally prefixed by device address
 128   strings)
 129
 130   Create the given number of VFs on the specified devices.
 131
 132 - **log_num_mgm_entry_size** (integer)
 133
 134   Device-managed flow steering (DMFS) is required by DPDK applications. It is
 135   enabled by using a negative value, the last four bits of which have a
 136   special meaning.
 137
 138   - **-1**: force device-managed flow steering (DMFS).
 139   - **-7**: configure optimized steering mode to improve performance with the
 140     following limitation: VLAN filtering is not supported with this mode.
 141     This is the recommended mode in case VLAN filter is not needed.
 142
 143 Limitations
 144 -----------
 145
 146 - CRC stripping is supported by default and always reported as "true".
 147   The ability to enable/disable CRC stripping requires OFED version
 148   4.3-1.5.0.0 and above  or rdma-core version v18 and above.
 149
 150 - TSO (Transmit Segmentation Offload) is supported in OFED version
 151   4.4 and above.
 152
 153 Prerequisites
 154 -------------
 155
 156 This driver relies on external libraries and kernel drivers for resources
 157 allocations and initialization. The following dependencies are not part of
 158 DPDK and must be installed separately:
 159
 160 - **libibverbs** (provided by rdma-core package)
 161
 162   User space verbs framework used by librte_pmd_mlx4. This library provides
 163   a generic interface between the kernel and low-level user space drivers
 164   such as libmlx4.
 165
 166   It allows slow and privileged operations (context initialization, hardware
 167   resources allocations) to be managed by the kernel and fast operations to
 168   never leave user space.
 169
 170 - **libmlx4** (provided by rdma-core package)
 171
 172   Low-level user space driver library for Mellanox ConnectX-3 devices,
 173   it is automatically loaded by libibverbs.
 174
 175   This library basically implements send/receive calls to the hardware
 176   queues.
 177
 178 - **Kernel modules**
 179
 180   They provide the kernel-side verbs API and low level device drivers that
 181   manage actual hardware initialization and resources sharing with user
 182   space processes.
 183
 184   Unlike most other PMDs, these modules must remain loaded and bound to
 185   their devices:
 186
 187   - mlx4_core: hardware driver managing Mellanox ConnectX-3 devices.
 188   - mlx4_en: Ethernet device driver that provides kernel network interfaces.
 189   - mlx4_ib: InifiniBand device driver.
 190   - ib_uverbs: user space driver for verbs (entry point for libibverbs).
 191
 192 - **Firmware update**
 193
 194   Mellanox OFED releases include firmware updates for ConnectX-3 adapters.
 195
 196   Because each release provides new features, these updates must be applied to
 197   match the kernel modules and libraries they come with.
 198
 199 .. note::
 200
 201    Both libraries are BSD and GPL licensed. Linux kernel modules are GPL
 202    licensed.
 203
 204 Depending on system constraints and user preferences either RDMA core library
 205 with a recent enough Linux kernel release (recommended) or Mellanox OFED,
 206 which provides compatibility with older releases.
 207
 208 Current RDMA core package and Linux kernel (recommended)
 209 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 210
 211 - Minimal Linux kernel version: 4.14.
 212 - Minimal RDMA core version: v15 (see `RDMA core installation documentation`_).
 213
 214 - Starting with rdma-core v21, static libraries can be built::
 215
 216     cd build
 217     CFLAGS=-fPIC cmake -DIN_PLACE=1 -DENABLE_STATIC=1 -GNinja ..
 218     ninja
 219
 220 .. _`RDMA core installation documentation`: https://raw.githubusercontent.com/linux-rdma/rdma-core/master/README.md
 221
 222 If rdma-core libraries are built but not installed, DPDK makefile can link them,
 223 thanks to these environment variables:
 224
 225    - ``EXTRA_CFLAGS=-I/path/to/rdma-core/build/include``
 226    - ``EXTRA_LDFLAGS=-L/path/to/rdma-core/build/lib``
 227    - ``PKG_CONFIG_PATH=/path/to/rdma-core/build/lib/pkgconfig``
 228
 229 .. _Mellanox_OFED_as_a_fallback:
 230
 231 Mellanox OFED as a fallback
 232 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 233
 234 - `Mellanox OFED`_ version: **4.4, 4.5**.
 235 - firmware version: **2.42.5000** and above.
 236
 237 .. _`Mellanox OFED`: http://www.mellanox.com/page/products_dyn?product_family=26&mtag=linux_sw_drivers
 238
 239 .. note::
 240
 241    Several versions of Mellanox OFED are available. Installing the version
 242    this DPDK release was developed and tested against is strongly
 243    recommended. Please check the `prerequisites`_.
 244
 245 Installing Mellanox OFED
 246 ^^^^^^^^^^^^^^^^^^^^^^^^
 247
 248 1. Download latest Mellanox OFED.
 249
 250 2. Install the required libraries and kernel modules either by installing
 251    only the required set, or by installing the entire Mellanox OFED:
 252
 253    For bare metal use:
 254
 255    .. code-block:: console
 256
 257         ./mlnxofedinstall --dpdk --upstream-libs
 258
 259    For SR-IOV hypervisors use:
 260
 261    .. code-block:: console
 262
 263         ./mlnxofedinstall --dpdk --upstream-libs --enable-sriov --hypervisor
 264
 265    For SR-IOV virtual machine use:
 266
 267    .. code-block:: console
 268
 269         ./mlnxofedinstall --dpdk --upstream-libs --guest
 270
 271 3. Verify the firmware is the correct one:
 272
 273    .. code-block:: console
 274
 275         ibv_devinfo
 276
 277 4. Set all ports links to Ethernet, follow instructions on the screen:
 278
 279    .. code-block:: console
 280
 281         connectx_port_config
 282
 283 5. Continue with :ref:`section 2 of the Quick Start Guide <QSG_2>`.
 284
 285 Supported NICs
 286 --------------
 287
 288 * Mellanox(R) ConnectX(R)-3 Pro 40G MCX354A-FCC_Ax (2*40G)
 289
 290 .. _qsg:
 291
 292 Quick Start Guide
 293 -----------------
 294
 295 1. Set all ports links to Ethernet
 296
 297    .. code-block:: console
 298
 299         PCI=<NIC PCI address>
 300         echo eth > "/sys/bus/pci/devices/$PCI/mlx4_port0"
 301         echo eth > "/sys/bus/pci/devices/$PCI/mlx4_port1"
 302
 303    .. note::
 304
 305         If using Mellanox OFED one can permanently set the port link
 306         to Ethernet using connectx_port_config tool provided by it.
 307         :ref:`Mellanox_OFED_as_a_fallback`:
 308
 309 .. _QSG_2:
 310
 311 2. In case of bare metal or hypervisor, configure optimized steering mode
 312    by adding the following line to ``/etc/modprobe.d/mlx4_core.conf``:
 313
 314    .. code-block:: console
 315
 316         options mlx4_core log_num_mgm_entry_size=-7
 317
 318    .. note::
 319
 320         If VLAN filtering is used, set log_num_mgm_entry_size=-1.
 321         Performance degradation can occur on this case.
 322
 323 3. Restart the driver:
 324
 325    .. code-block:: console
 326
 327         /etc/init.d/openibd restart
 328
 329    or:
 330
 331    .. code-block:: console
 332
 333         service openibd restart
 334
 335 4. Compile DPDK and you are ready to go. See instructions on
 336    :ref:`Development Kit Build System <Development_Kit_Build_System>`
 337
 338 Performance tuning
 339 ------------------
 340
 341 1. Verify the optimized steering mode is configured:
 342
 343   .. code-block:: console
 344
 345         cat /sys/module/mlx4_core/parameters/log_num_mgm_entry_size
 346
 347 2. Use the CPU near local NUMA node to which the PCIe adapter is connected,
 348    for better performance. For VMs, verify that the right CPU
 349    and NUMA node are pinned according to the above. Run:
 350
 351    .. code-block:: console
 352
 353         lstopo-no-graphics
 354
 355    to identify the NUMA node to which the PCIe adapter is connected.
 356
 357 3. If more than one adapter is used, and root complex capabilities allow
 358    to put both adapters on the same NUMA node without PCI bandwidth degradation,
 359    it is recommended to locate both adapters on the same NUMA node.
 360    This in order to forward packets from one to the other without
 361    NUMA performance penalty.
 362
 363 4. Disable pause frames:
 364
 365    .. code-block:: console
 366
 367         ethtool -A <netdev> rx off tx off
 368
 369 5. Verify IO non-posted prefetch is disabled by default. This can be checked
 370    via the BIOS configuration. Please contact you server provider for more
 371    information about the settings.
 372
 373 .. note::
 374
 375         On some machines, depends on the machine integrator, it is beneficial
 376         to set the PCI max read request parameter to 1K. This can be
 377         done in the following way:
 378
 379         To query the read request size use:
 380
 381         .. code-block:: console
 382
 383                 setpci -s <NIC PCI address> 68.w
 384
 385         If the output is different than 3XXX, set it by:
 386
 387         .. code-block:: console
 388
 389                 setpci -s <NIC PCI address> 68.w=3XXX
 390
 391         The XXX can be different on different systems. Make sure to configure
 392         according to the setpci output.
 393
 394 6. To minimize overhead of searching Memory Regions:
 395
 396    - '--socket-mem' is recommended to pin memory by predictable amount.
 397    - Configure per-lcore cache when creating Mempools for packet buffer.
 398    - Refrain from dynamically allocating/freeing memory in run-time.
 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>