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_LIBRTE_MLX4_DLOPEN_DEPS`` (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_LIBRTE_MLX4_DEBUG`` (default **n**)
  83
  84   Toggle debugging code and stricter compilation flags. Enabling this option
  85   adds additional run-time checks and debugging messages at the cost of
  86   lower performance.
  87
  88 - ``CONFIG_RTE_LIBRTE_MLX4_TX_MP_CACHE`` (default **8**)
  89
  90   Maximum number of cached memory pools (MPs) per TX queue. Each MP from
  91   which buffers are to be transmitted must be associated to memory regions
  92   (MRs). This is a slow operation that must be cached.
  93
  94   This value is always 1 for RX queues since they use a single MP.
  95
  96 Environment variables
  97 ~~~~~~~~~~~~~~~~~~~~~
  98
  99 - ``MLX4_GLUE_PATH``
 100
 101   A list of directories in which to search for the rdma-core "glue" plug-in,
 102   separated by colons or semi-colons.
 103
 104   Only matters when compiled with ``CONFIG_RTE_LIBRTE_MLX4_DLOPEN_DEPS``
 105   enabled and most useful when ``CONFIG_RTE_EAL_PMD_PATH`` is also set,
 106   since ``LD_LIBRARY_PATH`` has no effect in this case.
 107
 108 Run-time configuration
 109 ~~~~~~~~~~~~~~~~~~~~~~
 110
 111 - librte_pmd_mlx4 brings kernel network interfaces up during initialization
 112   because it is affected by their state. Forcing them down prevents packets
 113   reception.
 114
 115 - **ethtool** operations on related kernel interfaces also affect the PMD.
 116
 117 - ``port`` parameter [int]
 118
 119   This parameter provides a physical port to probe and can be specified multiple
 120   times for additional ports. All ports are probed by default if left
 121   unspecified.
 122
 123 Kernel module parameters
 124 ~~~~~~~~~~~~~~~~~~~~~~~~
 125
 126 The **mlx4_core** kernel module has several parameters that affect the
 127 behavior and/or the performance of librte_pmd_mlx4. Some of them are described
 128 below.
 129
 130 - **num_vfs** (integer or triplet, optionally prefixed by device address
 131   strings)
 132
 133   Create the given number of VFs on the specified devices.
 134
 135 - **log_num_mgm_entry_size** (integer)
 136
 137   Device-managed flow steering (DMFS) is required by DPDK applications. It is
 138   enabled by using a negative value, the last four bits of which have a
 139   special meaning.
 140
 141   - **-1**: force device-managed flow steering (DMFS).
 142   - **-7**: configure optimized steering mode to improve performance with the
 143     following limitation: VLAN filtering is not supported with this mode.
 144     This is the recommended mode in case VLAN filter is not needed.
 145
 146 Limitations
 147 -----------
 148
 149 - CRC stripping is supported by default and always reported as "true".
 150   The ability to enable/disable CRC stripping requires OFED version
 151   4.3-1.5.0.0 and above  or rdma-core version v18 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 .. _`RDMA core installation documentation`: https://raw.githubusercontent.com/linux-rdma/rdma-core/master/README.md
 215
 216 .. _Mellanox_OFED_as_a_fallback:
 217
 218 Mellanox OFED as a fallback
 219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 220
 221 - `Mellanox OFED`_ version: **4.2, 4.3**.
 222 - firmware version: **2.42.5000** and above.
 223
 224 .. _`Mellanox OFED`: http://www.mellanox.com/page/products_dyn?product_family=26&mtag=linux_sw_drivers
 225
 226 .. note::
 227
 228    Several versions of Mellanox OFED are available. Installing the version
 229    this DPDK release was developed and tested against is strongly
 230    recommended. Please check the `prerequisites`_.
 231
 232 Installing Mellanox OFED
 233 ^^^^^^^^^^^^^^^^^^^^^^^^
 234
 235 1. Download latest Mellanox OFED.
 236
 237 2. Install the required libraries and kernel modules either by installing
 238    only the required set, or by installing the entire Mellanox OFED:
 239
 240    For bare metal use:
 241
 242    .. code-block:: console
 243
 244         ./mlnxofedinstall --dpdk --upstream-libs
 245
 246    For SR-IOV hypervisors use:
 247
 248    .. code-block:: console
 249
 250         ./mlnxofedinstall --dpdk --upstream-libs --enable-sriov --hypervisor
 251
 252    For SR-IOV virtual machine use:
 253
 254    .. code-block:: console
 255
 256         ./mlnxofedinstall --dpdk --upstream-libs --guest
 257
 258 3. Verify the firmware is the correct one:
 259
 260    .. code-block:: console
 261
 262         ibv_devinfo
 263
 264 4. Set all ports links to Ethernet, follow instructions on the screen:
 265
 266    .. code-block:: console
 267
 268         connectx_port_config
 269
 270 5. Continue with :ref:`section 2 of the Quick Start Guide <QSG_2>`.
 271
 272 Supported NICs
 273 --------------
 274
 275 * Mellanox(R) ConnectX(R)-3 Pro 40G MCX354A-FCC_Ax (2*40G)
 276
 277 .. _qsg:
 278
 279 Quick Start Guide
 280 -----------------
 281
 282 1. Set all ports links to Ethernet
 283
 284    .. code-block:: console
 285
 286         PCI=<NIC PCI address>
 287         echo eth > "/sys/bus/pci/devices/$PCI/mlx4_port0"
 288         echo eth > "/sys/bus/pci/devices/$PCI/mlx4_port1"
 289
 290    .. note::
 291
 292         If using Mellanox OFED one can permanently set the port link
 293         to Ethernet using connectx_port_config tool provided by it.
 294         :ref:`Mellanox_OFED_as_a_fallback`:
 295
 296 .. _QSG_2:
 297
 298 2. 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 3. 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 4. 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 the CPU near local NUMA node to which the PCIe adapter is connected,
 335    for better performance. For VMs, verify that the right CPU
 336    and NUMA node are pinned according to the above. Run:
 337
 338    .. code-block:: console
 339
 340         lstopo-no-graphics
 341
 342    to identify the NUMA node to which the PCIe adapter is connected.
 343
 344 3. If more than one adapter is used, and root complex capabilities allow
 345    to put both adapters on the same NUMA node without PCI bandwidth degradation,
 346    it is recommended to locate both adapters on the same NUMA node.
 347    This in order to forward packets from one to the other without
 348    NUMA performance penalty.
 349
 350 4. Disable pause frames:
 351
 352    .. code-block:: console
 353
 354         ethtool -A <netdev> rx off tx off
 355
 356 5. Verify IO non-posted prefetch is disabled by default. This can be checked
 357    via the BIOS configuration. Please contact you server provider for more
 358    information about the settings.
 359
 360 .. note::
 361
 362         On some machines, depends on the machine integrator, it is beneficial
 363         to set the PCI max read request parameter to 1K. This can be
 364         done in the following way:
 365
 366         To query the read request size use:
 367
 368         .. code-block:: console
 369
 370                 setpci -s <NIC PCI address> 68.w
 371
 372         If the output is different than 3XXX, set it by:
 373
 374         .. code-block:: console
 375
 376                 setpci -s <NIC PCI address> 68.w=3XXX
 377
 378         The XXX can be different on different systems. Make sure to configure
 379         according to the setpci output.
 380
 381 Usage example
 382 -------------
 383
 384 This section demonstrates how to launch **testpmd** with Mellanox ConnectX-3
 385 devices managed by librte_pmd_mlx4.
 386
 387 #. Load the kernel modules:
 388
 389    .. code-block:: console
 390
 391       modprobe -a ib_uverbs mlx4_en mlx4_core mlx4_ib
 392
 393    Alternatively if MLNX_OFED is fully installed, the following script can
 394    be run:
 395
 396    .. code-block:: console
 397
 398       /etc/init.d/openibd restart
 399
 400    .. note::
 401
 402       User space I/O kernel modules (uio and igb_uio) are not used and do
 403       not have to be loaded.
 404
 405 #. Make sure Ethernet interfaces are in working order and linked to kernel
 406    verbs. Related sysfs entries should be present:
 407
 408    .. code-block:: console
 409
 410       ls -d /sys/class/net/*/device/infiniband_verbs/uverbs* | cut -d / -f 5
 411
 412    Example output:
 413
 414    .. code-block:: console
 415
 416       eth2
 417       eth3
 418       eth4
 419       eth5
 420
 421 #. Optionally, retrieve their PCI bus addresses for whitelisting:
 422
 423    .. code-block:: console
 424
 425       {
 426           for intf in eth2 eth3 eth4 eth5;
 427           do
 428               (cd "/sys/class/net/${intf}/device/" && pwd -P);
 429           done;
 430       } |
 431       sed -n 's,.*/\(.*\),-w \1,p'
 432
 433    Example output:
 434
 435    .. code-block:: console
 436
 437       -w 0000:83:00.0
 438       -w 0000:83:00.0
 439       -w 0000:84:00.0
 440       -w 0000:84:00.0
 441
 442    .. note::
 443
 444       There are only two distinct PCI bus addresses because the Mellanox
 445       ConnectX-3 adapters installed on this system are dual port.
 446
 447 #. Request huge pages:
 448
 449    .. code-block:: console
 450
 451       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
 452
 453 #. Start testpmd with basic parameters:
 454
 455    .. code-block:: console
 456
 457       testpmd -l 8-15 -n 4 -w 0000:83:00.0 -w 0000:84:00.0 -- --rxq=2 --txq=2 -i
 458
 459    Example output:
 460
 461    .. code-block:: console
 462
 463       [...]
 464       EAL: PCI device 0000:83:00.0 on NUMA socket 1
 465       EAL:   probe driver: 15b3:1007 librte_pmd_mlx4
 466       PMD: librte_pmd_mlx4: PCI information matches, using device "mlx4_0" (VF: false)
 467       PMD: librte_pmd_mlx4: 2 port(s) detected
 468       PMD: librte_pmd_mlx4: port 1 MAC address is 00:02:c9:b5:b7:50
 469       PMD: librte_pmd_mlx4: port 2 MAC address is 00:02:c9:b5:b7:51
 470       EAL: PCI device 0000:84:00.0 on NUMA socket 1
 471       EAL:   probe driver: 15b3:1007 librte_pmd_mlx4
 472       PMD: librte_pmd_mlx4: PCI information matches, using device "mlx4_1" (VF: false)
 473       PMD: librte_pmd_mlx4: 2 port(s) detected
 474       PMD: librte_pmd_mlx4: port 1 MAC address is 00:02:c9:b5:ba:b0
 475       PMD: librte_pmd_mlx4: port 2 MAC address is 00:02:c9:b5:ba:b1
 476       Interactive-mode selected
 477       Configuring Port 0 (socket 0)
 478       PMD: librte_pmd_mlx4: 0x867d60: TX queues number update: 0 -> 2
 479       PMD: librte_pmd_mlx4: 0x867d60: RX queues number update: 0 -> 2
 480       Port 0: 00:02:C9:B5:B7:50
 481       Configuring Port 1 (socket 0)
 482       PMD: librte_pmd_mlx4: 0x867da0: TX queues number update: 0 -> 2
 483       PMD: librte_pmd_mlx4: 0x867da0: RX queues number update: 0 -> 2
 484       Port 1: 00:02:C9:B5:B7:51
 485       Configuring Port 2 (socket 0)
 486       PMD: librte_pmd_mlx4: 0x867de0: TX queues number update: 0 -> 2
 487       PMD: librte_pmd_mlx4: 0x867de0: RX queues number update: 0 -> 2
 488       Port 2: 00:02:C9:B5:BA:B0
 489       Configuring Port 3 (socket 0)
 490       PMD: librte_pmd_mlx4: 0x867e20: TX queues number update: 0 -> 2
 491       PMD: librte_pmd_mlx4: 0x867e20: RX queues number update: 0 -> 2
 492       Port 3: 00:02:C9:B5:BA:B1
 493       Checking link statuses...
 494       Port 0 Link Up - speed 10000 Mbps - full-duplex
 495       Port 1 Link Up - speed 40000 Mbps - full-duplex
 496       Port 2 Link Up - speed 10000 Mbps - full-duplex
 497       Port 3 Link Up - speed 40000 Mbps - full-duplex
 498       Done
 499       testpmd>