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 71Enqueue / Dequeue APIs 72~~~~~~~~~~~~~~~~~~~~~~ 73 74Enqueue APIs such as ``rte_dma_copy`` and ``rte_dma_fill`` can be used to 75enqueue operations to hardware. If an enqueue is successful, a ``ring_idx`` is 76returned. This ``ring_idx`` can be used by applications to track per operation 77metadata in an application-defined circular ring. 78 79The ``rte_dma_submit`` API is used to issue doorbell to hardware. 80Alternatively the ``RTE_DMA_OP_FLAG_SUBMIT`` flag can be passed to the enqueue 81APIs to also issue the doorbell to hardware. 82 83There are two dequeue APIs ``rte_dma_completed`` and 84``rte_dma_completed_status``, these are used to obtain the results of the 85enqueue requests. ``rte_dma_completed`` will return the number of successfully 86completed operations. ``rte_dma_completed_status`` will return the number of 87completed operations along with the status of each operation (filled into the 88``status`` array passed by user). These two APIs can also return the last 89completed operation's ``ring_idx`` which could help user track operations within 90their own application-defined rings. 91