doc/guides/nics/mlx5.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2015 6WIND S.A.
   3     Copyright 2015 Mellanox Technologies, Ltd
   4
   5 MLX5 poll mode driver
   6 =====================
   7
   8 The MLX5 poll mode driver library (**librte_pmd_mlx5**) provides support
   9 for **Mellanox ConnectX-4**, **Mellanox ConnectX-4 Lx** , **Mellanox
  10 ConnectX-5** and **Mellanox Bluefield** families of 10/25/40/50/100 Gb/s
  11 adapters as well as their virtual functions (VF) in SR-IOV context.
  12
  13 Information and documentation about these adapters can be found on the
  14 `Mellanox website <http://www.mellanox.com>`__. Help is also provided by the
  15 `Mellanox community <http://community.mellanox.com/welcome>`__.
  16
  17 There is also a `section dedicated to this poll mode driver
  18 <http://www.mellanox.com/page/products_dyn?product_family=209&mtag=pmd_for_dpdk>`__.
  19
  20 .. note::
  21
  22    Due to external dependencies, this driver is disabled by default. It must
  23    be enabled manually by setting ``CONFIG_RTE_LIBRTE_MLX5_PMD=y`` and
  24    recompiling DPDK.
  25
  26 Implementation details
  27 ----------------------
  28
  29 Besides its dependency on libibverbs (that implies libmlx5 and associated
  30 kernel support), librte_pmd_mlx5 relies heavily on system calls for control
  31 operations such as querying/updating the MTU and flow control parameters.
  32
  33 For security reasons and robustness, this driver only deals with virtual
  34 memory addresses. The way resources allocations are handled by the kernel
  35 combined with hardware specifications that allow it to handle virtual memory
  36 addresses directly ensure that DPDK applications cannot access random
  37 physical memory (or memory that does not belong to the current process).
  38
  39 This capability allows the PMD to coexist with kernel network interfaces
  40 which remain functional, although they stop receiving unicast packets as
  41 long as they share the same MAC address.
  42 This means legacy linux control tools (for example: ethtool, ifconfig and
  43 more) can operate on the same network interfaces that owned by the DPDK
  44 application.
  45
  46 Enabling librte_pmd_mlx5 causes DPDK applications to be linked against
  47 libibverbs.
  48
  49 Features
  50 --------
  51
  52 - Multi arch support: x86_64, POWER8, ARMv8.
  53 - Multiple TX and RX queues.
  54 - Support for scattered TX and RX frames.
  55 - IPv4, IPv6, TCPv4, TCPv6, UDPv4 and UDPv6 RSS on any number of queues.
  56 - Several RSS hash keys, one for each flow type.
  57 - Configurable RETA table.
  58 - Support for multiple MAC addresses.
  59 - VLAN filtering.
  60 - RX VLAN stripping.
  61 - TX VLAN insertion.
  62 - RX CRC stripping configuration.
  63 - Promiscuous mode.
  64 - Multicast promiscuous mode.
  65 - Hardware checksum offloads.
  66 - Flow director (RTE_FDIR_MODE_PERFECT, RTE_FDIR_MODE_PERFECT_MAC_VLAN and
  67   RTE_ETH_FDIR_REJECT).
  68 - Flow API.
  69 - Multiple process.
  70 - KVM and VMware ESX SR-IOV modes are supported.
  71 - RSS hash result is supported.
  72 - Hardware TSO for generic IP or UDP tunnel, including VXLAN and GRE.
  73 - Hardware checksum Tx offload for generic IP or UDP tunnel, including VXLAN and GRE.
  74 - RX interrupts.
  75 - Statistics query including Basic, Extended and per queue.
  76 - Rx HW timestamp.
  77 - Tunnel types: VXLAN, L3 VXLAN, VXLAN-GPE, GRE, MPLSoGRE, MPLSoUDP.
  78 - Tunnel HW offloads: packet type, inner/outer RSS, IP and UDP checksum verification.
  79
  80 Limitations
  81 -----------
  82
  83 - For secondary process:
  84
  85   - Forked secondary process not supported.
  86   - All mempools must be initialized before rte_eth_dev_start().
  87
  88 - Flow pattern without any specific vlan will match for vlan packets as well:
  89
  90   When VLAN spec is not specified in the pattern, the matching rule will be created with VLAN as a wild card.
  91   Meaning, the flow rule::
  92
  93         flow create 0 ingress pattern eth / vlan vid is 3 / ipv4 / end ...
  94
  95   Will only match vlan packets with vid=3. and the flow rules::
  96
  97         flow create 0 ingress pattern eth / ipv4 / end ...
  98
  99   Or::
 100
 101         flow create 0 ingress pattern eth / vlan / ipv4 / end ...
 102
 103   Will match any ipv4 packet (VLAN included).
 104
 105 - A multi segment packet must have less than 6 segments in case the Tx burst function
 106   is set to multi-packet send or Enhanced multi-packet send. Otherwise it must have
 107   less than 50 segments.
 108
 109 - Count action for RTE flow is **only supported in Mellanox OFED**.
 110
 111 - Flows with a VXLAN Network Identifier equal (or ends to be equal)
 112   to 0 are not supported.
 113
 114 - VXLAN TSO and checksum offloads are not supported on VM.
 115
 116 - L3 VXLAN and VXLAN-GPE tunnels cannot be supported together with MPLSoGRE and MPLSoUDP.
 117
 118 - VF: flow rules created on VF devices can only match traffic targeted at the
 119   configured MAC addresses (see ``rte_eth_dev_mac_addr_add()``).
 120
 121 .. note::
 122
 123    MAC addresses not already present in the bridge table of the associated
 124    kernel network device will be added and cleaned up by the PMD when closing
 125    the device. In case of ungraceful program termination, some entries may
 126    remain present and should be removed manually by other means.
 127
 128 - When Multi-Packet Rx queue is configured (``mprq_en``), a Rx packet can be
 129   externally attached to a user-provided mbuf with having EXT_ATTACHED_MBUF in
 130   ol_flags. As the mempool for the external buffer is managed by PMD, all the
 131   Rx mbufs must be freed before the device is closed. Otherwise, the mempool of
 132   the external buffers will be freed by PMD and the application which still
 133   holds the external buffers may be corrupted.
 134
 135 Statistics
 136 ----------
 137
 138 MLX5 supports various of methods to report statistics:
 139
 140 Port statistics can be queried using ``rte_eth_stats_get()``. The port statistics are through SW only and counts the number of packets received or sent successfully by the PMD.
 141
 142 Extended statistics can be queried using ``rte_eth_xstats_get()``. The extended statistics expose a wider set of counters counted by the device. The extended port statistics counts the number of packets received or sent successfully by the port. As Mellanox NICs are using the :ref:`Bifurcated Linux Driver <linux_gsg_linux_drivers>` those counters counts also packet received or sent by the Linux kernel. The counters with ``_phy`` suffix counts the total events on the physical port, therefore not valid for VF.
 143
 144 Finally per-flow statistics can by queried using ``rte_flow_query`` when attaching a count action for specific flow. The flow counter counts the number of packets received successfully by the port and match the specific flow.
 145
 146 Configuration
 147 -------------
 148
 149 Compilation options
 150 ~~~~~~~~~~~~~~~~~~~
 151
 152 These options can be modified in the ``.config`` file.
 153
 154 - ``CONFIG_RTE_LIBRTE_MLX5_PMD`` (default **n**)
 155
 156   Toggle compilation of librte_pmd_mlx5 itself.
 157
 158 - ``CONFIG_RTE_LIBRTE_MLX5_DLOPEN_DEPS`` (default **n**)
 159
 160   Build PMD with additional code to make it loadable without hard
 161   dependencies on **libibverbs** nor **libmlx5**, which may not be installed
 162   on the target system.
 163
 164   In this mode, their presence is still required for it to run properly,
 165   however their absence won't prevent a DPDK application from starting (with
 166   ``CONFIG_RTE_BUILD_SHARED_LIB`` disabled) and they won't show up as
 167   missing with ``ldd(1)``.
 168
 169   It works by moving these dependencies to a purpose-built rdma-core "glue"
 170   plug-in which must either be installed in a directory whose name is based
 171   on ``CONFIG_RTE_EAL_PMD_PATH`` suffixed with ``-glue`` if set, or in a
 172   standard location for the dynamic linker (e.g. ``/lib``) if left to the
 173   default empty string (``""``).
 174
 175   This option has no performance impact.
 176
 177 - ``CONFIG_RTE_LIBRTE_MLX5_DEBUG`` (default **n**)
 178
 179   Toggle debugging code and stricter compilation flags. Enabling this option
 180   adds additional run-time checks and debugging messages at the cost of
 181   lower performance.
 182
 183 Environment variables
 184 ~~~~~~~~~~~~~~~~~~~~~
 185
 186 - ``MLX5_GLUE_PATH``
 187
 188   A list of directories in which to search for the rdma-core "glue" plug-in,
 189   separated by colons or semi-colons.
 190
 191   Only matters when compiled with ``CONFIG_RTE_LIBRTE_MLX5_DLOPEN_DEPS``
 192   enabled and most useful when ``CONFIG_RTE_EAL_PMD_PATH`` is also set,
 193   since ``LD_LIBRARY_PATH`` has no effect in this case.
 194
 195 - ``MLX5_PMD_ENABLE_PADDING``
 196
 197   Enables HW packet padding in PCI bus transactions.
 198
 199   When packet size is cache aligned and CRC stripping is enabled, 4 fewer
 200   bytes are written to the PCI bus. Enabling padding makes such packets
 201   aligned again.
 202
 203   In cases where PCI bandwidth is the bottleneck, padding can improve
 204   performance by 10%.
 205
 206   This is disabled by default since this can also decrease performance for
 207   unaligned packet sizes.
 208
 209 - ``MLX5_SHUT_UP_BF``
 210
 211   Configures HW Tx doorbell register as IO-mapped.
 212
 213   By default, the HW Tx doorbell is configured as a write-combining register.
 214   The register would be flushed to HW usually when the write-combining buffer
 215   becomes full, but it depends on CPU design.
 216
 217   Except for vectorized Tx burst routines, a write memory barrier is enforced
 218   after updating the register so that the update can be immediately visible to
 219   HW.
 220
 221   When vectorized Tx burst is called, the barrier is set only if the burst size
 222   is not aligned to MLX5_VPMD_TX_MAX_BURST. However, setting this environmental
 223   variable will bring better latency even though the maximum throughput can
 224   slightly decline.
 225
 226 Run-time configuration
 227 ~~~~~~~~~~~~~~~~~~~~~~
 228
 229 - librte_pmd_mlx5 brings kernel network interfaces up during initialization
 230   because it is affected by their state. Forcing them down prevents packets
 231   reception.
 232
 233 - **ethtool** operations on related kernel interfaces also affect the PMD.
 234
 235 - ``rxq_cqe_comp_en`` parameter [int]
 236
 237   A nonzero value enables the compression of CQE on RX side. This feature
 238   allows to save PCI bandwidth and improve performance. Enabled by default.
 239
 240   Supported on:
 241
 242   - x86_64 with ConnectX-4, ConnectX-4 LX, ConnectX-5 and Bluefield.
 243   - POWER8 and ARMv8 with ConnectX-4 LX, ConnectX-5 and Bluefield.
 244
 245 - ``mprq_en`` parameter [int]
 246
 247   A nonzero value enables configuring Multi-Packet Rx queues. Rx queue is
 248   configured as Multi-Packet RQ if the total number of Rx queues is
 249   ``rxqs_min_mprq`` or more and Rx scatter isn't configured. Disabled by
 250   default.
 251
 252   Multi-Packet Rx Queue (MPRQ a.k.a Striding RQ) can further save PCIe bandwidth
 253   by posting a single large buffer for multiple packets. Instead of posting a
 254   buffers per a packet, one large buffer is posted in order to receive multiple
 255   packets on the buffer. A MPRQ buffer consists of multiple fixed-size strides
 256   and each stride receives one packet. MPRQ can improve throughput for
 257   small-packet tarffic.
 258
 259   When MPRQ is enabled, max_rx_pkt_len can be larger than the size of
 260   user-provided mbuf even if DEV_RX_OFFLOAD_SCATTER isn't enabled. PMD will
 261   configure large stride size enough to accommodate max_rx_pkt_len as long as
 262   device allows. Note that this can waste system memory compared to enabling Rx
 263   scatter and multi-segment packet.
 264
 265 - ``mprq_log_stride_num`` parameter [int]
 266
 267   Log 2 of the number of strides for Multi-Packet Rx queue. Configuring more
 268   strides can reduce PCIe tarffic further. If configured value is not in the
 269   range of device capability, the default value will be set with a warning
 270   message. The default value is 4 which is 16 strides per a buffer, valid only
 271   if ``mprq_en`` is set.
 272
 273   The size of Rx queue should be bigger than the number of strides.
 274
 275 - ``mprq_max_memcpy_len`` parameter [int]
 276
 277   The maximum length of packet to memcpy in case of Multi-Packet Rx queue. Rx
 278   packet is mem-copied to a user-provided mbuf if the size of Rx packet is less
 279   than or equal to this parameter. Otherwise, PMD will attach the Rx packet to
 280   the mbuf by external buffer attachment - ``rte_pktmbuf_attach_extbuf()``.
 281   A mempool for external buffers will be allocated and managed by PMD. If Rx
 282   packet is externally attached, ol_flags field of the mbuf will have
 283   EXT_ATTACHED_MBUF and this flag must be preserved. ``RTE_MBUF_HAS_EXTBUF()``
 284   checks the flag. The default value is 128, valid only if ``mprq_en`` is set.
 285
 286 - ``rxqs_min_mprq`` parameter [int]
 287
 288   Configure Rx queues as Multi-Packet RQ if the total number of Rx queues is
 289   greater or equal to this value. The default value is 12, valid only if
 290   ``mprq_en`` is set.
 291
 292 - ``txq_inline`` parameter [int]
 293
 294   Amount of data to be inlined during TX operations. Improves latency.
 295   Can improve PPS performance when PCI back pressure is detected and may be
 296   useful for scenarios involving heavy traffic on many queues.
 297
 298   Because additional software logic is necessary to handle this mode, this
 299   option should be used with care, as it can lower performance when back
 300   pressure is not expected.
 301
 302 - ``txqs_min_inline`` parameter [int]
 303
 304   Enable inline send only when the number of TX queues is greater or equal
 305   to this value.
 306
 307   This option should be used in combination with ``txq_inline`` above.
 308
 309   On ConnectX-4, ConnectX-4 LX, ConnectX-5 and Bluefield without
 310   Enhanced MPW:
 311
 312         - Disabled by default.
 313         - In case ``txq_inline`` is set recommendation is 4.
 314
 315   On ConnectX-5 and Bluefield with Enhanced MPW:
 316
 317         - Set to 8 by default.
 318
 319 - ``txq_mpw_en`` parameter [int]
 320
 321   A nonzero value enables multi-packet send (MPS) for ConnectX-4 Lx and
 322   enhanced multi-packet send (Enhanced MPS) for ConnectX-5 and Bluefield.
 323   MPS allows the TX burst function to pack up multiple packets in a
 324   single descriptor session in order to save PCI bandwidth and improve
 325   performance at the cost of a slightly higher CPU usage. When
 326   ``txq_inline`` is set along with ``txq_mpw_en``, TX burst function tries
 327   to copy entire packet data on to TX descriptor instead of including
 328   pointer of packet only if there is enough room remained in the
 329   descriptor. ``txq_inline`` sets per-descriptor space for either pointers
 330   or inlined packets. In addition, Enhanced MPS supports hybrid mode -
 331   mixing inlined packets and pointers in the same descriptor.
 332
 333   This option cannot be used with certain offloads such as ``DEV_TX_OFFLOAD_TCP_TSO,
 334   DEV_TX_OFFLOAD_VXLAN_TNL_TSO, DEV_TX_OFFLOAD_GRE_TNL_TSO, DEV_TX_OFFLOAD_VLAN_INSERT``.
 335   When those offloads are requested the MPS send function will not be used.
 336
 337   It is currently only supported on the ConnectX-4 Lx, ConnectX-5 and Bluefield
 338   families of adapters. Enabled by default.
 339
 340 - ``txq_mpw_hdr_dseg_en`` parameter [int]
 341
 342   A nonzero value enables including two pointers in the first block of TX
 343   descriptor. This can be used to lessen CPU load for memory copy.
 344
 345   Effective only when Enhanced MPS is supported. Disabled by default.
 346
 347 - ``txq_max_inline_len`` parameter [int]
 348
 349   Maximum size of packet to be inlined. This limits the size of packet to
 350   be inlined. If the size of a packet is larger than configured value, the
 351   packet isn't inlined even though there's enough space remained in the
 352   descriptor. Instead, the packet is included with pointer.
 353
 354   Effective only when Enhanced MPS is supported. The default value is 256.
 355
 356 - ``tx_vec_en`` parameter [int]
 357
 358   A nonzero value enables Tx vector on ConnectX-5 and Bluefield NICs if the number of
 359   global Tx queues on the port is lesser than MLX5_VPMD_MIN_TXQS.
 360
 361   This option cannot be used with certain offloads such as ``DEV_TX_OFFLOAD_TCP_TSO,
 362   DEV_TX_OFFLOAD_VXLAN_TNL_TSO, DEV_TX_OFFLOAD_GRE_TNL_TSO, DEV_TX_OFFLOAD_VLAN_INSERT``.
 363   When those offloads are requested the MPS send function will not be used.
 364
 365   Enabled by default on ConnectX-5 and Bluefield.
 366
 367 - ``rx_vec_en`` parameter [int]
 368
 369   A nonzero value enables Rx vector if the port is not configured in
 370   multi-segment otherwise this parameter is ignored.
 371
 372   Enabled by default.
 373
 374 - ``vf_nl_en`` parameter [int]
 375
 376   A nonzero value enables Netlink requests from the VF to add/remove MAC
 377   addresses or/and enable/disable promiscuous/all multicast on the Netdevice.
 378   Otherwise the relevant configuration must be run with Linux iproute2 tools.
 379   This is a prerequisite to receive this kind of traffic.
 380
 381   Enabled by default, valid only on VF devices ignored otherwise.
 382
 383 - ``l3_vxlan_en`` parameter [int]
 384
 385   A nonzero value allows L3 VXLAN and VXLAN-GPE flow creation. To enable
 386   L3 VXLAN or VXLAN-GPE, users has to configure firmware and enable this
 387   parameter. This is a prerequisite to receive this kind of traffic.
 388
 389   Disabled by default.
 390
 391 Firmware configuration
 392 ~~~~~~~~~~~~~~~~~~~~~~
 393
 394 - L3 VXLAN and VXLAN-GPE destination UDP port
 395
 396    .. code-block:: console
 397
 398      mlxconfig -d <mst device> set IP_OVER_VXLAN_EN=1
 399      mlxconfig -d <mst device> set IP_OVER_VXLAN_PORT=<udp dport>
 400
 401   Verify configurations are set:
 402
 403    .. code-block:: console
 404
 405      mlxconfig -d <mst device> query | grep IP_OVER_VXLAN
 406      IP_OVER_VXLAN_EN                    True(1)
 407      IP_OVER_VXLAN_PORT                  <udp dport>
 408
 409 Prerequisites
 410 -------------
 411
 412 This driver relies on external libraries and kernel drivers for resources
 413 allocations and initialization. The following dependencies are not part of
 414 DPDK and must be installed separately:
 415
 416 - **libibverbs**
 417
 418   User space Verbs framework used by librte_pmd_mlx5. This library provides
 419   a generic interface between the kernel and low-level user space drivers
 420   such as libmlx5.
 421
 422   It allows slow and privileged operations (context initialization, hardware
 423   resources allocations) to be managed by the kernel and fast operations to
 424   never leave user space.
 425
 426 - **libmlx5**
 427
 428   Low-level user space driver library for Mellanox
 429   ConnectX-4/ConnectX-5/Bluefield devices, it is automatically loaded
 430   by libibverbs.
 431
 432   This library basically implements send/receive calls to the hardware
 433   queues.
 434
 435 - **Kernel modules**
 436
 437   They provide the kernel-side Verbs API and low level device drivers that
 438   manage actual hardware initialization and resources sharing with user
 439   space processes.
 440
 441   Unlike most other PMDs, these modules must remain loaded and bound to
 442   their devices:
 443
 444   - mlx5_core: hardware driver managing Mellanox
 445     ConnectX-4/ConnectX-5/Bluefield devices and related Ethernet kernel
 446     network devices.
 447   - mlx5_ib: InifiniBand device driver.
 448   - ib_uverbs: user space driver for Verbs (entry point for libibverbs).
 449
 450 - **Firmware update**
 451
 452   Mellanox OFED releases include firmware updates for
 453   ConnectX-4/ConnectX-5/Bluefield adapters.
 454
 455   Because each release provides new features, these updates must be applied to
 456   match the kernel modules and libraries they come with.
 457
 458 .. note::
 459
 460    Both libraries are BSD and GPL licensed. Linux kernel modules are GPL
 461    licensed.
 462
 463 Installation
 464 ~~~~~~~~~~~~
 465
 466 Either RDMA Core library with a recent enough Linux kernel release
 467 (recommended) or Mellanox OFED, which provides compatibility with older
 468 releases.
 469
 470 RMDA Core with Linux Kernel
 471 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 472
 473 - Minimal kernel version : v4.14 or the most recent 4.14-rc (see `Linux installation documentation`_)
 474 - Minimal rdma-core version: v15+ commit 0c5f5765213a ("Merge pull request #227 from yishaih/tm")
 475   (see `RDMA Core installation documentation`_)
 476
 477 .. _`Linux installation documentation`: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git/plain/Documentation/admin-guide/README.rst
 478 .. _`RDMA Core installation documentation`: https://raw.githubusercontent.com/linux-rdma/rdma-core/master/README.md
 479
 480 Mellanox OFED
 481 ^^^^^^^^^^^^^
 482
 483 - Mellanox OFED version: **4.2, 4.3**.
 484 - firmware version:
 485
 486   - ConnectX-4: **12.21.1000** and above.
 487   - ConnectX-4 Lx: **14.21.1000** and above.
 488   - ConnectX-5: **16.21.1000** and above.
 489   - ConnectX-5 Ex: **16.21.1000** and above.
 490   - Bluefield: **18.99.3950** and above.
 491
 492 While these libraries and kernel modules are available on OpenFabrics
 493 Alliance's `website <https://www.openfabrics.org/>`__ and provided by package
 494 managers on most distributions, this PMD requires Ethernet extensions that
 495 may not be supported at the moment (this is a work in progress).
 496
 497 `Mellanox OFED
 498 <http://www.mellanox.com/page/products_dyn?product_family=26&mtag=linux>`__
 499 includes the necessary support and should be used in the meantime. For DPDK,
 500 only libibverbs, libmlx5, mlnx-ofed-kernel packages and firmware updates are
 501 required from that distribution.
 502
 503 .. note::
 504
 505    Several versions of Mellanox OFED are available. Installing the version
 506    this DPDK release was developed and tested against is strongly
 507    recommended. Please check the `prerequisites`_.
 508
 509 Supported NICs
 510 --------------
 511
 512 * Mellanox(R) ConnectX(R)-4 10G MCX4111A-XCAT (1x10G)
 513 * Mellanox(R) ConnectX(R)-4 10G MCX4121A-XCAT (2x10G)
 514 * Mellanox(R) ConnectX(R)-4 25G MCX4111A-ACAT (1x25G)
 515 * Mellanox(R) ConnectX(R)-4 25G MCX4121A-ACAT (2x25G)
 516 * Mellanox(R) ConnectX(R)-4 40G MCX4131A-BCAT (1x40G)
 517 * Mellanox(R) ConnectX(R)-4 40G MCX413A-BCAT (1x40G)
 518 * Mellanox(R) ConnectX(R)-4 40G MCX415A-BCAT (1x40G)
 519 * Mellanox(R) ConnectX(R)-4 50G MCX4131A-GCAT (1x50G)
 520 * Mellanox(R) ConnectX(R)-4 50G MCX413A-GCAT (1x50G)
 521 * Mellanox(R) ConnectX(R)-4 50G MCX414A-BCAT (2x50G)
 522 * Mellanox(R) ConnectX(R)-4 50G MCX415A-GCAT (2x50G)
 523 * Mellanox(R) ConnectX(R)-4 50G MCX416A-BCAT (2x50G)
 524 * Mellanox(R) ConnectX(R)-4 50G MCX416A-GCAT (2x50G)
 525 * Mellanox(R) ConnectX(R)-4 50G MCX415A-CCAT (1x100G)
 526 * Mellanox(R) ConnectX(R)-4 100G MCX416A-CCAT (2x100G)
 527 * Mellanox(R) ConnectX(R)-4 Lx 10G MCX4121A-XCAT (2x10G)
 528 * Mellanox(R) ConnectX(R)-4 Lx 25G MCX4121A-ACAT (2x25G)
 529 * Mellanox(R) ConnectX(R)-5 100G MCX556A-ECAT (2x100G)
 530 * Mellanox(R) ConnectX(R)-5 Ex EN 100G MCX516A-CDAT (2x100G)
 531
 532 Quick Start Guide on OFED
 533 -------------------------
 534
 535 1. Download latest Mellanox OFED. For more info check the  `prerequisites`_.
 536
 537
 538 2. Install the required libraries and kernel modules either by installing
 539    only the required set, or by installing the entire Mellanox OFED:
 540
 541    .. code-block:: console
 542
 543         ./mlnxofedinstall --upstream-libs --dpdk
 544
 545 3. Verify the firmware is the correct one:
 546
 547    .. code-block:: console
 548
 549         ibv_devinfo
 550
 551 4. Verify all ports links are set to Ethernet:
 552
 553    .. code-block:: console
 554
 555         mlxconfig -d <mst device> query | grep LINK_TYPE
 556         LINK_TYPE_P1                        ETH(2)
 557         LINK_TYPE_P2                        ETH(2)
 558
 559    Link types may have to be configured to Ethernet:
 560
 561    .. code-block:: console
 562
 563         mlxconfig -d <mst device> set LINK_TYPE_P1/2=1/2/3
 564
 565         * LINK_TYPE_P1=<1|2|3> , 1=Infiniband 2=Ethernet 3=VPI(auto-sense)
 566
 567    For hypervisors verify SR-IOV is enabled on the NIC:
 568
 569    .. code-block:: console
 570
 571         mlxconfig -d <mst device> query | grep SRIOV_EN
 572         SRIOV_EN                            True(1)
 573
 574    If needed, set enable the set the relevant fields:
 575
 576    .. code-block:: console
 577
 578         mlxconfig -d <mst device> set SRIOV_EN=1 NUM_OF_VFS=16
 579         mlxfwreset -d <mst device> reset
 580
 581 5. Restart the driver:
 582
 583    .. code-block:: console
 584
 585         /etc/init.d/openibd restart
 586
 587    or:
 588
 589    .. code-block:: console
 590
 591         service openibd restart
 592
 593    If link type was changed, firmware must be reset as well:
 594
 595    .. code-block:: console
 596
 597         mlxfwreset -d <mst device> reset
 598
 599    For hypervisors, after reset write the sysfs number of virtual functions
 600    needed for the PF.
 601
 602    To dynamically instantiate a given number of virtual functions (VFs):
 603
 604    .. code-block:: console
 605
 606         echo [num_vfs] > /sys/class/infiniband/mlx5_0/device/sriov_numvfs
 607
 608 6. Compile DPDK and you are ready to go. See instructions on
 609    :ref:`Development Kit Build System <Development_Kit_Build_System>`
 610
 611 Performance tuning
 612 ------------------
 613
 614 1. Configure aggressive CQE Zipping for maximum performance:
 615
 616   .. code-block:: console
 617
 618         mlxconfig -d <mst device> s CQE_COMPRESSION=1
 619
 620   To set it back to the default CQE Zipping mode use:
 621
 622   .. code-block:: console
 623
 624         mlxconfig -d <mst device> s CQE_COMPRESSION=0
 625
 626 2. In case of virtualization:
 627
 628    - Make sure that hypervisor kernel is 3.16 or newer.
 629    - Configure boot with ``iommu=pt``.
 630    - Use 1G huge pages.
 631    - Make sure to allocate a VM on huge pages.
 632    - Make sure to set CPU pinning.
 633
 634 3. Use the CPU near local NUMA node to which the PCIe adapter is connected,
 635    for better performance. For VMs, verify that the right CPU
 636    and NUMA node are pinned according to the above. Run:
 637
 638    .. code-block:: console
 639
 640         lstopo-no-graphics
 641
 642    to identify the NUMA node to which the PCIe adapter is connected.
 643
 644 4. If more than one adapter is used, and root complex capabilities allow
 645    to put both adapters on the same NUMA node without PCI bandwidth degradation,
 646    it is recommended to locate both adapters on the same NUMA node.
 647    This in order to forward packets from one to the other without
 648    NUMA performance penalty.
 649
 650 5. Disable pause frames:
 651
 652    .. code-block:: console
 653
 654         ethtool -A <netdev> rx off tx off
 655
 656 6. Verify IO non-posted prefetch is disabled by default. This can be checked
 657    via the BIOS configuration. Please contact you server provider for more
 658    information about the settings.
 659
 660 .. note::
 661
 662         On some machines, depends on the machine integrator, it is beneficial
 663         to set the PCI max read request parameter to 1K. This can be
 664         done in the following way:
 665
 666         To query the read request size use:
 667
 668         .. code-block:: console
 669
 670                 setpci -s <NIC PCI address> 68.w
 671
 672         If the output is different than 3XXX, set it by:
 673
 674         .. code-block:: console
 675
 676                 setpci -s <NIC PCI address> 68.w=3XXX
 677
 678         The XXX can be different on different systems. Make sure to configure
 679         according to the setpci output.
 680
 681 7. To minimize overhead of searching Memory Regions:
 682
 683    - '--socket-mem' is recommended to pin memory by predictable amount.
 684    - Configure per-lcore cache when creating Mempools for packet buffer.
 685    - Refrain from dynamically allocating/freeing memory in run-time.
 686
 687 Notes for testpmd
 688 -----------------
 689
 690 Compared to librte_pmd_mlx4 that implements a single RSS configuration per
 691 port, librte_pmd_mlx5 supports per-protocol RSS configuration.
 692
 693 Since ``testpmd`` defaults to IP RSS mode and there is currently no
 694 command-line parameter to enable additional protocols (UDP and TCP as well
 695 as IP), the following commands must be entered from its CLI to get the same
 696 behavior as librte_pmd_mlx4:
 697
 698 .. code-block:: console
 699
 700    > port stop all
 701    > port config all rss all
 702    > port start all
 703
 704 Usage example
 705 -------------
 706
 707 This section demonstrates how to launch **testpmd** with Mellanox
 708 ConnectX-4/ConnectX-5/Bluefield devices managed by librte_pmd_mlx5.
 709
 710 #. Load the kernel modules:
 711
 712    .. code-block:: console
 713
 714       modprobe -a ib_uverbs mlx5_core mlx5_ib
 715
 716    Alternatively if MLNX_OFED is fully installed, the following script can
 717    be run:
 718
 719    .. code-block:: console
 720
 721       /etc/init.d/openibd restart
 722
 723    .. note::
 724
 725       User space I/O kernel modules (uio and igb_uio) are not used and do
 726       not have to be loaded.
 727
 728 #. Make sure Ethernet interfaces are in working order and linked to kernel
 729    verbs. Related sysfs entries should be present:
 730
 731    .. code-block:: console
 732
 733       ls -d /sys/class/net/*/device/infiniband_verbs/uverbs* | cut -d / -f 5
 734
 735    Example output:
 736
 737    .. code-block:: console
 738
 739       eth30
 740       eth31
 741       eth32
 742       eth33
 743
 744 #. Optionally, retrieve their PCI bus addresses for whitelisting:
 745
 746    .. code-block:: console
 747
 748       {
 749           for intf in eth2 eth3 eth4 eth5;
 750           do
 751               (cd "/sys/class/net/${intf}/device/" && pwd -P);
 752           done;
 753       } |
 754       sed -n 's,.*/\(.*\),-w \1,p'
 755
 756    Example output:
 757
 758    .. code-block:: console
 759
 760       -w 0000:05:00.1
 761       -w 0000:06:00.0
 762       -w 0000:06:00.1
 763       -w 0000:05:00.0
 764
 765 #. Request huge pages:
 766
 767    .. code-block:: console
 768
 769       echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages/nr_hugepages
 770
 771 #. Start testpmd with basic parameters:
 772
 773    .. code-block:: console
 774
 775       testpmd -l 8-15 -n 4 -w 05:00.0 -w 05:00.1 -w 06:00.0 -w 06:00.1 -- --rxq=2 --txq=2 -i
 776
 777    Example output:
 778
 779    .. code-block:: console
 780
 781       [...]
 782       EAL: PCI device 0000:05:00.0 on NUMA socket 0
 783       EAL:   probe driver: 15b3:1013 librte_pmd_mlx5
 784       PMD: librte_pmd_mlx5: PCI information matches, using device "mlx5_0" (VF: false)
 785       PMD: librte_pmd_mlx5: 1 port(s) detected
 786       PMD: librte_pmd_mlx5: port 1 MAC address is e4:1d:2d:e7:0c:fe
 787       EAL: PCI device 0000:05:00.1 on NUMA socket 0
 788       EAL:   probe driver: 15b3:1013 librte_pmd_mlx5
 789       PMD: librte_pmd_mlx5: PCI information matches, using device "mlx5_1" (VF: false)
 790       PMD: librte_pmd_mlx5: 1 port(s) detected
 791       PMD: librte_pmd_mlx5: port 1 MAC address is e4:1d:2d:e7:0c:ff
 792       EAL: PCI device 0000:06:00.0 on NUMA socket 0
 793       EAL:   probe driver: 15b3:1013 librte_pmd_mlx5
 794       PMD: librte_pmd_mlx5: PCI information matches, using device "mlx5_2" (VF: false)
 795       PMD: librte_pmd_mlx5: 1 port(s) detected
 796       PMD: librte_pmd_mlx5: port 1 MAC address is e4:1d:2d:e7:0c:fa
 797       EAL: PCI device 0000:06:00.1 on NUMA socket 0
 798       EAL:   probe driver: 15b3:1013 librte_pmd_mlx5
 799       PMD: librte_pmd_mlx5: PCI information matches, using device "mlx5_3" (VF: false)
 800       PMD: librte_pmd_mlx5: 1 port(s) detected
 801       PMD: librte_pmd_mlx5: port 1 MAC address is e4:1d:2d:e7:0c:fb
 802       Interactive-mode selected
 803       Configuring Port 0 (socket 0)
 804       PMD: librte_pmd_mlx5: 0x8cba80: TX queues number update: 0 -> 2
 805       PMD: librte_pmd_mlx5: 0x8cba80: RX queues number update: 0 -> 2
 806       Port 0: E4:1D:2D:E7:0C:FE
 807       Configuring Port 1 (socket 0)
 808       PMD: librte_pmd_mlx5: 0x8ccac8: TX queues number update: 0 -> 2
 809       PMD: librte_pmd_mlx5: 0x8ccac8: RX queues number update: 0 -> 2
 810       Port 1: E4:1D:2D:E7:0C:FF
 811       Configuring Port 2 (socket 0)
 812       PMD: librte_pmd_mlx5: 0x8cdb10: TX queues number update: 0 -> 2
 813       PMD: librte_pmd_mlx5: 0x8cdb10: RX queues number update: 0 -> 2
 814       Port 2: E4:1D:2D:E7:0C:FA
 815       Configuring Port 3 (socket 0)
 816       PMD: librte_pmd_mlx5: 0x8ceb58: TX queues number update: 0 -> 2
 817       PMD: librte_pmd_mlx5: 0x8ceb58: RX queues number update: 0 -> 2
 818       Port 3: E4:1D:2D:E7:0C:FB
 819       Checking link statuses...
 820       Port 0 Link Up - speed 40000 Mbps - full-duplex
 821       Port 1 Link Up - speed 40000 Mbps - full-duplex
 822       Port 2 Link Up - speed 10000 Mbps - full-duplex
 823       Port 3 Link Up - speed 10000 Mbps - full-duplex
 824       Done
 825       testpmd>