doc/guides/dmadevs/ioat.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2021 Intel Corporation.
   3
   4 .. include:: <isonum.txt>
   5
   6 IOAT DMA Device Driver
   7 =======================
   8
   9 The ``ioat`` dmadev driver provides a poll-mode driver (PMD) for Intel\
  10 |reg| QuickData Technology which is part of part of Intel\ |reg| I/O
  11 Acceleration Technology (`Intel I/OAT
  12 <https://www.intel.com/content/www/us/en/wireless-network/accel-technology.html>`_).
  13 This PMD, when used on supported hardware, allows data copies, for example,
  14 cloning packet data, to be accelerated by IOAT hardware rather than having to
  15 be done by software, freeing up CPU cycles for other tasks.
  16
  17 Hardware Requirements
  18 ----------------------
  19
  20 The ``dpdk-devbind.py`` script, included with DPDK, can be used to show the
  21 presence of supported hardware. Running ``dpdk-devbind.py --status-dev dma``
  22 will show all the DMA devices on the system, IOAT devices are included in this
  23 list. For Intel\ |reg| IOAT devices, the hardware will often be listed as
  24 "Crystal Beach DMA", or "CBDMA" or on some newer systems '0b00' due to the
  25 absence of pci-id database entries for them at this point.
  26
  27 .. note::
  28         Error handling is not supported by this driver on hardware prior to
  29         Intel Ice Lake. Unsupported systems include Broadwell, Skylake and
  30         Cascade Lake.
  31
  32 Compilation
  33 ------------
  34
  35 For builds using ``meson`` and ``ninja``, the driver will be built when the
  36 target platform is x86-based. No additional compilation steps are necessary.
  37
  38 Device Setup
  39 -------------
  40
  41 Intel\ |reg| IOAT devices will need to be bound to a suitable DPDK-supported
  42 user-space IO driver such as ``vfio-pci`` in order to be used by DPDK.
  43
  44 The ``dpdk-devbind.py`` script can be used to view the state of the devices using::
  45
  46    $ dpdk-devbind.py --status-dev dma
  47
  48 The ``dpdk-devbind.py`` script can also be used to bind devices to a suitable driver.
  49 For example::
  50
  51         $ dpdk-devbind.py -b vfio-pci 00:01.0 00:01.1
  52
  53 Device Probing and Initialization
  54 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  55
  56 For devices bound to a suitable DPDK-supported driver (``vfio-pci``), the HW
  57 devices will be found as part of the device scan done at application
  58 initialization time without the need to pass parameters to the application.
  59
  60 If the application does not require all the devices available an allowlist can
  61 be used in the same way that other DPDK devices use them.
  62
  63 For example::
  64
  65         $ dpdk-test -a <b:d:f>
  66
  67 Once probed successfully, the device will appear as a ``dmadev``, that is a
  68 "DMA device type" inside DPDK, and can be accessed using APIs from the
  69 ``rte_dmadev`` library.
  70
  71 Using IOAT DMAdev Devices
  72 --------------------------
  73
  74 To use IOAT devices from an application, the ``dmadev`` API can be used.
  75
  76 Device Configuration
  77 ~~~~~~~~~~~~~~~~~~~~~
  78
  79 IOAT configuration requirements:
  80
  81 * ``ring_size`` must be a power of two, between 64 and 4096.
  82 * Only one ``vchan`` is supported per device.
  83 * Silent mode is not supported.
  84 * The transfer direction must be set to ``RTE_DMA_DIR_MEM_TO_MEM`` to copy from memory to memory.
  85
  86 Once configured, the device can then be made ready for use by calling the
  87 ``rte_dma_start()`` API.
  88
  89 Performing Data Copies
  90 ~~~~~~~~~~~~~~~~~~~~~~~
  91
  92 Refer to the :ref:`Enqueue / Dequeue APIs <dmadev_enqueue_dequeue>` section of the dmadev library
  93 documentation for details on operation enqueue, submission and completion API usage.
  94
  95 It is expected that, for efficiency reasons, a burst of operations will be enqueued to the
  96 device via multiple enqueue calls between calls to the ``rte_dma_submit()`` function.
  97
  98 When gathering completions, ``rte_dma_completed()`` should be used, up until the point an error
  99 occurs with an operation. If an error was encountered, ``rte_dma_completed_status()`` must be used
 100 to reset the device and continue processing operations. This function will also gather the status
 101 of each individual operation which is filled in to the ``status`` array provided as parameter
 102 by the application.
 103
 104 The status codes supported by IOAT are:
 105
 106 * ``RTE_DMA_STATUS_SUCCESSFUL``: The operation was successful.
 107 * ``RTE_DMA_STATUS_INVALID_SRC_ADDR``: The operation failed due to an invalid source address.
 108 * ``RTE_DMA_STATUS_INVALID_DST_ADDR``: The operation failed due to an invalid destination address.
 109 * ``RTE_DMA_STATUS_INVALID_LENGTH``: The operation failed due to an invalid descriptor length.
 110 * ``RTE_DMA_STATUS_DESCRIPTOR_READ_ERROR``: The device could not read the descriptor.
 111 * ``RTE_DMA_STATUS_ERROR_UNKNOWN``: The operation failed due to an unspecified error.
 112
 113 The following code shows how to retrieve the number of successfully completed
 114 copies within a burst and then uses ``rte_dma_completed_status()`` to check
 115 which operation failed and reset the device to continue processing operations:
 116
 117 .. code-block:: C
 118
 119    enum rte_dma_status_code status[COMP_BURST_SZ];
 120    uint16_t count, idx, status_count;
 121    bool error = 0;
 122
 123    count = rte_dma_completed(dev_id, vchan, COMP_BURST_SZ, &idx, &error);
 124
 125    if (error){
 126       status_count = rte_dma_completed_status(dev_id, vchan, COMP_BURST_SZ, &idx, status);
 127    }