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