1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright 2021 HiSilicon Limited 3 4Direct Memory Access (DMA) 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 122The dmadev library has support for displaying DMA device information 123through the Telemetry interface. Telemetry commands that can be used 124are shown below. 125 126#. Get the list of available DMA devices by ID:: 127 128 --> /dmadev/list 129 {"/dmadev/list": [0, 1]} 130 131#. Get general information from a DMA device by passing the device id as a parameter:: 132 133 --> /dmadev/info,0 134 {"/dmadev/info": {"name": "0000:00:01.0", "nb_vchans": 1, "numa_node": 0, "max_vchans": 1, "max_desc": 4096, 135 "min_desc": 32, "max_sges": 0, "capabilities": {"mem2mem": 1, "mem2dev": 0, "dev2mem": 0, ...}}} 136 137#. Get the statistics for a particular DMA device and virtual DMA channel by passing the device id and vchan id as parameters 138 (if a DMA device only has one virtual DMA channel you only need to pass the device id):: 139 140 --> /dmadev/stats,0,0 141 {"/dmadev/stats": {"submitted": 0, "completed": 0, "errors": 0}} 142 143For more information on how to use the Telemetry interface, see 144the :doc:`../howto/telemetry`. 145