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