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