1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2021 Intel Corporation. 3 4.. include:: <isonum.txt> 5 6IOAT DMA Device Driver 7======================= 8 9The ``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 11Acceleration Technology (`Intel I/OAT 12<https://www.intel.com/content/www/us/en/wireless-network/accel-technology.html>`_). 13This PMD, when used on supported hardware, allows data copies, for example, 14cloning packet data, to be accelerated by IOAT hardware rather than having to 15be done by software, freeing up CPU cycles for other tasks. 16 17Hardware Requirements 18---------------------- 19 20The ``dpdk-devbind.py`` script, included with DPDK, can be used to show the 21presence of supported hardware. Running ``dpdk-devbind.py --status-dev dma`` 22will show all the DMA devices on the system, IOAT devices are included in this 23list. 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 25absence 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 32Compilation 33------------ 34 35For builds using ``meson`` and ``ninja``, the driver will be built when the 36target platform is x86-based. No additional compilation steps are necessary. 37 38Device Setup 39------------- 40 41Intel\ |reg| IOAT devices will need to be bound to a suitable DPDK-supported 42user-space IO driver such as ``vfio-pci`` in order to be used by DPDK. 43 44The ``dpdk-devbind.py`` script can be used to view the state of the devices using:: 45 46 $ dpdk-devbind.py --status-dev dma 47 48The ``dpdk-devbind.py`` script can also be used to bind devices to a suitable driver. 49For example:: 50 51 $ dpdk-devbind.py -b vfio-pci 00:01.0 00:01.1 52 53Device Probing and Initialization 54~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 55 56For devices bound to a suitable DPDK-supported driver (``vfio-pci``), the HW 57devices will be found as part of the device scan done at application 58initialization time without the need to pass parameters to the application. 59 60If the application does not require all the devices available an allowlist can 61be used in the same way that other DPDK devices use them. 62 63For example:: 64 65 $ dpdk-test -a <b:d:f> 66 67Once 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 71Using IOAT DMAdev Devices 72-------------------------- 73 74To use IOAT devices from an application, the ``dmadev`` API can be used. 75 76Device Configuration 77~~~~~~~~~~~~~~~~~~~~~ 78 79IOAT 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 86Once configured, the device can then be made ready for use by calling the 87``rte_dma_start()`` API. 88 89Performing Data Copies 90~~~~~~~~~~~~~~~~~~~~~~~ 91 92Refer to the :ref:`Enqueue / Dequeue APIs <dmadev_enqueue_dequeue>` section of the dmadev library 93documentation for details on operation enqueue, submission and completion API usage. 94 95It is expected that, for efficiency reasons, a burst of operations will be enqueued to the 96device via multiple enqueue calls between calls to the ``rte_dma_submit()`` function. 97 98When gathering completions, ``rte_dma_completed()`` should be used, up until the point an error 99occurs with an operation. If an error was encountered, ``rte_dma_completed_status()`` must be used 100to reset the device and continue processing operations. This function will also gather the status 101of each individual operation which is filled in to the ``status`` array provided as parameter 102by the application. 103 104The 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 113The following code shows how to retrieve the number of successfully completed 114copies within a burst and then uses ``rte_dma_completed_status()`` to check 115which 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 } 128