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