doc/guides/vdpadevs/mlx5.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright 2019 Mellanox Technologies, Ltd
   3
   4 .. include:: <isonum.txt>
   5
   6 MLX5 vDPA Driver
   7 ================
   8
   9 The mlx5 vDPA (vhost data path acceleration) driver library
  10 (**librte_vdpa_mlx5**) provides support for **NVIDIA ConnectX-6**,
  11 **NVIDIA ConnectX-6 Dx**, **NVIDIA ConnectX-6 Lx**, **NVIDIA ConnectX7**,
  12 **NVIDIA BlueField** and **NVIDIA BlueField-2** families of
  13 10/25/40/50/100/200 Gb/s adapters as well as their virtual functions (VF) in
  14 SR-IOV context.
  15
  16 .. note::
  17
  18    This driver is enabled automatically when using "meson" build system which
  19    will detect dependencies.
  20
  21 See :doc:`../../platform/mlx5` guide for design details,
  22 and which PMDs can be combined with vDPA PMD.
  23
  24 Supported NICs
  25 --------------
  26
  27 * NVIDIA\ |reg| ConnectX\ |reg|-6 200G MCX654106A-HCAT (2x200G)
  28 * NVIDIA\ |reg| ConnectX\ |reg|-6 Dx EN 25G MCX621102AN-ADAT (2x25G)
  29 * NVIDIA\ |reg| ConnectX\ |reg|-6 Dx EN 100G MCX623106AN-CDAT (2x100G)
  30 * NVIDIA\ |reg| ConnectX\ |reg|-6 Dx EN 200G MCX623105AN-VDAT (1x200G)
  31 * NVIDIA\ |reg| ConnectX\ |reg|-6 Lx EN 25G MCX631102AN-ADAT (2x25G)
  32 * NVIDIA\ |reg| ConnectX\ |reg|-7 200G CX713106AE-HEA_QP1_Ax (2x200G)
  33 * NVIDIA\ |reg| BlueField SmartNIC 25G MBF1M332A-ASCAT (2x25G)
  34 * NVIDIA\ |reg| BlueField |reg|-2 SmartNIC MT41686 - MBF2H332A-AEEOT_A1 (2x25G)
  35
  36 Prerequisites
  37 -------------
  38
  39 - Mellanox OFED version: **5.0**
  40   See :ref:`mlx5 common prerequisites <mlx5_linux_prerequisites>` for more details.
  41
  42 Run-time configuration
  43 ~~~~~~~~~~~~~~~~~~~~~~
  44
  45 Driver options
  46 ^^^^^^^^^^^^^^
  47
  48 Please refer to :ref:`mlx5 common options <mlx5_common_driver_options>`
  49 for an additional list of options shared with other mlx5 drivers.
  50
  51 - ``event_mode`` parameter [int]
  52
  53   - 0, Completion queue scheduling will be managed by a timer thread which
  54     automatically adjusts its delays to the coming traffic rate.
  55
  56   - 1, Completion queue scheduling will be managed by a timer thread with fixed
  57     delay time.
  58
  59   - 2, Completion queue scheduling will be managed by interrupts. Each CQ burst
  60     arms the CQ in order to get an interrupt event in the next traffic burst.
  61
  62   - Default mode is 1.
  63
  64 - ``event_us`` parameter [int]
  65
  66   Per mode micro-seconds parameter - relevant only for event mode 0 and 1:
  67
  68   - 0, A nonzero value to set timer step in micro-seconds. The timer thread
  69     dynamic delay change steps according to this value. Default value is 1us.
  70
  71   - 1, A value to set fixed timer delay in micro-seconds. Default value is 0us.
  72
  73 - ``no_traffic_time`` parameter [int]
  74
  75   A nonzero value defines the traffic off time, in polling cycle time units,
  76   that moves the driver to no-traffic mode. In this mode the polling is stopped
  77   and interrupts are configured to the device in order to notify traffic for the
  78   driver. Default value is 16.
  79
  80 - ``event_core`` parameter [int]
  81
  82   CPU core number to set polling thread affinity to, default to control plane
  83   cpu.
  84
  85 - ``max_conf_threads`` parameter [int]
  86
  87   Allow the driver to use internal threads to obtain fast configuration.
  88   All the threads will be open on the same core of the event completion queue scheduling thread.
  89
  90   - 0, default, don't use internal threads for configuration.
  91
  92   - 1 - 256, number of internal threads in addition to the caller thread (8 is suggested).
  93     This value, if not 0, should be the same for all the devices;
  94     the first probing will take it with the ``event_core``
  95     for all the multi-thread configurations in the driver.
  96
  97 - ``hw_latency_mode`` parameter [int]
  98
  99   The completion queue moderation mode:
 100
 101   - 0, HW default.
 102
 103   - 1, Latency is counted from the first packet completion report.
 104
 105   - 2, Latency is counted from the last packet completion.
 106
 107 - ``hw_max_latency_us`` parameter [int]
 108
 109   - 1 - 4095, The maximum time in microseconds that packet completion report
 110     can be delayed.
 111
 112   - 0, HW default.
 113
 114 - ``hw_max_pending_comp`` parameter [int]
 115
 116   - 1 - 65535, The maximum number of pending packets completions in an HW queue.
 117
 118   - 0, HW default.
 119
 120 - ``queue_size`` parameter [int]
 121
 122   - 1 - 1024, Virtio queue depth for pre-creating queue resource to speed up
 123     first time queue creation. Set it together with ``queues`` parameter.
 124
 125   - 0, default value, no pre-create virtq resource.
 126
 127 - ``queues`` parameter [int]
 128
 129   - 1 - 128, Maximum number of virtio queue pair (including 1 Rx queue and 1 Tx queue)
 130     for pre-creating queue resource to speed up first time queue creation.
 131     Set it together with ``queue_size`` parameter.
 132
 133   - 0, default value, no pre-create virtq resource.
 134
 135 Error handling
 136 ^^^^^^^^^^^^^^
 137
 138 Upon potential hardware errors, mlx5 PMD try to recover, give up if failed 3
 139 times in 3 seconds, virtq will be put in disable state. User should check log
 140 to get error information, or query vdpa statistics counter to know error type
 141 and count report.
 142
 143 Statistics
 144 ^^^^^^^^^^
 145
 146 The device statistics counter persists in reconfiguration until the device gets
 147 removed. User can reset counters by calling function rte_vdpa_reset_stats().