doc/guides/dmadevs/idxd.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2021 Intel Corporation.
   3
   4 .. include:: <isonum.txt>
   5
   6 IDXD DMA Device Driver
   7 ======================
   8
   9 The ``idxd`` dmadev driver provides a poll-mode driver (PMD) for Intel\ |reg|
  10 Data Streaming Accelerator `(Intel DSA)
  11 <https://software.intel.com/content/www/us/en/develop/articles/intel-data-streaming-accelerator-architecture-specification.html>`_.
  12 This PMD can be used in conjunction with Intel\ |reg| DSA devices to offload
  13 data operations, such as data copies, to hardware, freeing up CPU cycles for
  14 other tasks.
  15
  16 Hardware Requirements
  17 ----------------------
  18
  19 The ``dpdk-devbind.py`` script, included with DPDK, can be used to show the
  20 presence of supported hardware. Running ``dpdk-devbind.py --status-dev dma``
  21 will show all the DMA devices on the system, including IDXD supported devices.
  22 Intel\ |reg| DSA devices, are currently (at time of writing) appearing
  23 as devices with type “0b25”, due to the absence of pci-id database entries for
  24 them at this point.
  25
  26 Compilation
  27 ------------
  28
  29 For builds using ``meson`` and ``ninja``, the driver will be built when the
  30 target platform is x86-based. No additional compilation steps are necessary.
  31
  32 Device Setup
  33 -------------
  34
  35 Intel\ |reg| DSA devices can use the IDXD kernel driver or DPDK-supported drivers,
  36 such as ``vfio-pci``. Both are supported by the IDXD PMD.
  37
  38 Intel\ |reg| DSA devices using IDXD kernel driver
  39 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  40
  41 To use an Intel\ |reg| DSA device bound to the IDXD kernel driver, the device must first be configured.
  42 The `accel-config <https://github.com/intel/idxd-config>`_ utility library can be used for configuration.
  43
  44 .. note::
  45         The device configuration can also be done by directly interacting with the sysfs nodes.
  46         An example of how this may be done can be seen in the script ``dpdk_idxd_cfg.py``
  47         included in the driver source directory.
  48
  49 There are some mandatory configuration steps before being able to use a device with an application.
  50 The internal engines, which do the copies or other operations,
  51 and the work-queues, which are used by applications to assign work to the device,
  52 need to be assigned to groups, and the various other configuration options,
  53 such as priority or queue depth, need to be set for each queue.
  54
  55 To assign an engine to a group::
  56
  57         $ accel-config config-engine dsa0/engine0.0 --group-id=0
  58
  59 To assign work queues to groups for passing descriptors to the engines a similar accel-config command can be used.
  60 However, the work queues also need to be configured depending on the use case.
  61 Some configuration options include:
  62
  63 * mode (Dedicated/Shared): Indicates whether a WQ may accept jobs from multiple queues simultaneously.
  64 * priority: WQ priority between 1 and 15. Larger value means higher priority.
  65 * wq-size: the size of the WQ. Sum of all WQ sizes must be less that the total-size defined by the device.
  66 * type: WQ type (kernel/mdev/user). Determines how the device is presented.
  67 * name: identifier given to the WQ.
  68
  69 Example configuration for a work queue::
  70
  71         $ accel-config config-wq dsa0/wq0.0 --group-id=0 \
  72            --mode=dedicated --priority=10 --wq-size=8 \
  73            --max-batch-size=512 --type=user --name=dpdk_app1
  74
  75 Once the devices have been configured, they need to be enabled::
  76
  77         $ accel-config enable-device dsa0
  78         $ accel-config enable-wq dsa0/wq0.0
  79
  80 Check the device configuration::
  81
  82         $ accel-config list
  83
  84 Every Intel\ |reg| DSA instance supports multiple queues and each should be similarly configured.
  85 As a further example, the following set of commands will configure and enable 4 queues on instance 0,
  86 giving each an equal share of resources::
  87
  88         # configure 4 groups, each with one engine
  89         accel-config config-engine dsa0/engine0.0 --group-id=0
  90         accel-config config-engine dsa0/engine0.1 --group-id=1
  91         accel-config config-engine dsa0/engine0.2 --group-id=2
  92         accel-config config-engine dsa0/engine0.3 --group-id=3
  93
  94         # configure 4 queues, putting each in a different group, so each
  95         # is backed by a single engine
  96         accel-config config-wq dsa0/wq0.0 --group-id=0 --type=user --wq-size=32 \
  97             --priority=10 --max-batch-size=1024 --mode=dedicated --name=dpdk_app1
  98         accel-config config-wq dsa0/wq0.1 --group-id=1 --type=user --wq-size=32 \
  99             --priority=10 --max-batch-size=1024 --mode=dedicated --name=dpdk_app1
 100         accel-config config-wq dsa0/wq0.2 --group-id=2 --type=user --wq-size=32 \
 101             --priority=10 --max-batch-size=1024 --mode=dedicated --name=dpdk_app1
 102         accel-config config-wq dsa0/wq0.3 --group-id=3 --type=user --wq-size=32 \
 103             --priority=10 --max-batch-size=1024 --mode=dedicated --name=dpdk_app1
 104
 105         # enable device and queues
 106         accel-config enable-device dsa0
 107         accel-config enable-wq dsa0/wq0.0 dsa0/wq0.1 dsa0/wq0.2 dsa0/wq0.3
 108
 109
 110 Devices using VFIO/UIO drivers
 111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 112
 113 The HW devices to be used will need to be bound to a user-space IO driver for use.
 114 The ``dpdk-devbind.py`` script can be used to view the state of the devices
 115 and to bind them to a suitable DPDK-supported driver, such as ``vfio-pci``.
 116 For example::
 117
 118         $ dpdk-devbind.py -b vfio-pci 6a:01.0
 119
 120 Device Probing and Initialization
 121 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 122
 123 For devices bound to a suitable DPDK-supported VFIO/UIO driver, the HW devices will
 124 be found as part of the device scan done at application initialization time without
 125 the need to pass parameters to the application.
 126
 127 For Intel\ |reg| DSA devices, DPDK will automatically configure the device with the
 128 maximum number of workqueues available on it, partitioning all resources equally
 129 among the queues.
 130 If fewer workqueues are required, then the ``max_queues`` parameter may be passed to
 131 the device driver on the EAL commandline, via the ``allowlist`` or ``-a`` flag e.g.::
 132
 133         $ dpdk-test -a <b:d:f>,max_queues=4
 134
 135 For devices bound to the IDXD kernel driver,
 136 the DPDK IDXD driver will automatically perform a scan for available workqueues
 137 to use. Any workqueues found listed in ``/dev/dsa`` on the system will be checked
 138 in ``/sys``, and any which have ``dpdk_`` prefix in their name will be automatically
 139 probed by the driver to make them available to the application.
 140 Alternatively, to support use by multiple DPDK processes simultaneously,
 141 the value used as the DPDK ``--file-prefix`` parameter may be used as a workqueue
 142 name prefix, instead of ``dpdk_``, allowing each DPDK application instance to only
 143 use a subset of configured queues.
 144
 145 Additionally, the -a (allowlist) or -b (blocklist) commandline parameters
 146 are also available to further restrict the device list that will be used.
 147 If the -a option is used, then any device that passes the ``dpdk_``
 148 or ``--file-prefix`` prefix condition must also be present in the allow list.
 149 Similarly, when the block list is used,
 150 any device that passes the prefix condition must not be in the block list.
 151 For example, to only use ``wq0.3``, assuming the name prefix condition is met::
 152
 153         $ dpdk-test -a wq0.3
 154
 155 Once probed successfully, irrespective of kernel driver, the device will appear as a ``dmadev``,
 156 that is a "DMA device type" inside DPDK, and can be accessed using APIs from the
 157 ``rte_dmadev`` library.
 158
 159 Using IDXD DMAdev Devices
 160 --------------------------
 161
 162 To use the devices from an application, the dmadev API can be used.
 163
 164 Device Configuration
 165 ~~~~~~~~~~~~~~~~~~~~~
 166
 167 IDXD configuration requirements:
 168
 169 * ``ring_size`` must be a power of two, between 64 and 4096.
 170 * Only one ``vchan`` is supported per device (work queue).
 171 * IDXD devices do not support silent mode.
 172 * The transfer direction must be set to ``RTE_DMA_DIR_MEM_TO_MEM`` to copy from memory to memory.
 173
 174 Once configured, the device can then be made ready for use by calling the
 175 ``rte_dma_start()`` API.
 176
 177 Performing Data Copies
 178 ~~~~~~~~~~~~~~~~~~~~~~~
 179
 180 Refer to the :ref:`Enqueue / Dequeue APIs <dmadev_enqueue_dequeue>` section of the dmadev library
 181 documentation for details on operation enqueue, submission and completion API usage.
 182
 183 It is expected that, for efficiency reasons, a burst of operations will be enqueued to the
 184 device via multiple enqueue calls between calls to the ``rte_dma_submit()`` function.
 185
 186 When gathering completions, ``rte_dma_completed()`` should be used, up until the point an error
 187 occurs in an operation. If an error was encountered, ``rte_dma_completed_status()`` must be used
 188 to kick the device off to continue processing operations and also to gather the status of each
 189 individual operations which is filled in to the ``status`` array provided as parameter by the
 190 application.
 191
 192 The following status codes are supported by IDXD:
 193
 194 * ``RTE_DMA_STATUS_SUCCESSFUL``: The operation was successful.
 195 * ``RTE_DMA_STATUS_INVALID_OPCODE``: The operation failed due to an invalid operation code.
 196 * ``RTE_DMA_STATUS_INVALID_LENGTH``: The operation failed due to an invalid data length.
 197 * ``RTE_DMA_STATUS_NOT_ATTEMPTED``: The operation was not attempted.
 198 * ``RTE_DMA_STATUS_ERROR_UNKNOWN``: The operation failed due to an unspecified error.
 199
 200 The following code shows how to retrieve the number of successfully completed
 201 copies within a burst and then using ``rte_dma_completed_status()`` to check
 202 which operation failed and kick off the device to continue processing operations:
 203
 204 .. code-block:: C
 205
 206    enum rte_dma_status_code status[COMP_BURST_SZ];
 207    uint16_t count, idx, status_count;
 208    bool error = 0;
 209
 210    count = rte_dma_completed(dev_id, vchan, COMP_BURST_SZ, &idx, &error);
 211
 212    if (error){
 213       status_count = rte_dma_completed_status(dev_id, vchan, COMP_BURST_SZ, &idx, status);
 214    }