1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright 2021 HiSilicon Limited 3 4DMA Device Library 5================== 6 7The DMA library provides a DMA device framework for management and provisioning 8of hardware and software DMA poll mode drivers, defining generic API which 9support a number of different DMA operations. 10 11 12Design Principles 13----------------- 14 15The DMA framework provides a generic DMA device framework which supports both 16physical (hardware) and virtual (software) DMA devices, as well as a generic DMA 17API which allows DMA devices to be managed and configured, and supports DMA 18operations to be provisioned on DMA poll mode driver. 19 20.. _figure_dmadev: 21 22.. figure:: img/dmadev.* 23 24The above figure shows the model on which the DMA framework is built on: 25 26 * The DMA controller could have multiple hardware DMA channels (aka. hardware 27 DMA queues), each hardware DMA channel should be represented by a dmadev. 28 * The dmadev could create multiple virtual DMA channels, each virtual DMA 29 channel represents a different transfer context. 30 * The DMA operation request must be submitted to the virtual DMA channel. 31 32 33Device Management 34----------------- 35 36Device Creation 37~~~~~~~~~~~~~~~ 38 39Physical DMA controllers are discovered during the PCI probe/enumeration of the 40EAL function which is executed at DPDK initialization, this is based on their 41PCI BDF (bus/bridge, device, function). Specific physical DMA controllers, like 42other physical devices in DPDK can be listed using the EAL command line options. 43 44The dmadevs are dynamically allocated by using the function 45``rte_dma_pmd_allocate`` based on the number of hardware DMA channels. 46 47 48Device Identification 49~~~~~~~~~~~~~~~~~~~~~ 50 51Each DMA device, whether physical or virtual is uniquely designated by two 52identifiers: 53 54- A unique device index used to designate the DMA device in all functions 55 exported by the DMA API. 56 57- A device name used to designate the DMA device in console messages, for 58 administration or debugging purposes. 59 60 61Device Features and Capabilities 62-------------------------------- 63 64DMA devices may support different feature sets. The ``rte_dma_info_get`` API 65can be used to get the device info and supported features. 66 67Silent mode is a special device capability which does not require the 68application to invoke dequeue APIs. 69 70.. _dmadev_enqueue_dequeue: 71 72 73Enqueue / Dequeue APIs 74~~~~~~~~~~~~~~~~~~~~~~ 75 76Enqueue APIs such as ``rte_dma_copy`` and ``rte_dma_fill`` can be used to 77enqueue operations to hardware. If an enqueue is successful, a ``ring_idx`` is 78returned. This ``ring_idx`` can be used by applications to track per operation 79metadata in an application-defined circular ring. 80 81The ``rte_dma_submit`` API is used to issue doorbell to hardware. 82Alternatively the ``RTE_DMA_OP_FLAG_SUBMIT`` flag can be passed to the enqueue 83APIs to also issue the doorbell to hardware. 84 85The following code demonstrates how to enqueue a burst of copies to the 86device and start the hardware processing of them: 87 88.. code-block:: C 89 90 struct rte_mbuf *srcs[DMA_BURST_SZ], *dsts[DMA_BURST_SZ]; 91 unsigned int i; 92 93 for (i = 0; i < RTE_DIM(srcs); i++) { 94 if (rte_dma_copy(dev_id, vchan, rte_pktmbuf_iova(srcs[i]), 95 rte_pktmbuf_iova(dsts[i]), COPY_LEN, 0) < 0) { 96 PRINT_ERR("Error with rte_dma_copy for buffer %u\n", i); 97 return -1; 98 } 99 } 100 rte_dma_submit(dev_id, vchan); 101 102There are two dequeue APIs ``rte_dma_completed`` and 103``rte_dma_completed_status``, these are used to obtain the results of the 104enqueue requests. ``rte_dma_completed`` will return the number of successfully 105completed operations. ``rte_dma_completed_status`` will return the number of 106completed operations along with the status of each operation (filled into the 107``status`` array passed by user). These two APIs can also return the last 108completed operation's ``ring_idx`` which could help user track operations within 109their own application-defined rings. 110 111 112Querying Device Statistics 113~~~~~~~~~~~~~~~~~~~~~~~~~~ 114 115The statistics from a dmadev device can be got via the statistics functions, 116i.e. ``rte_dma_stats_get()``. The statistics returned for each device instance are: 117 118* ``submitted``: The number of operations submitted to the device. 119* ``completed``: The number of operations which have completed (successful and failed). 120* ``errors``: The number of operations that completed with error. 121