1b36970f2SChengwen Feng.. SPDX-License-Identifier: BSD-3-Clause 2b36970f2SChengwen Feng Copyright 2021 HiSilicon Limited 3b36970f2SChengwen Feng 4b36970f2SChengwen FengDMA Device Library 5b36970f2SChengwen Feng================== 6b36970f2SChengwen Feng 7b36970f2SChengwen FengThe DMA library provides a DMA device framework for management and provisioning 8b36970f2SChengwen Fengof hardware and software DMA poll mode drivers, defining generic API which 9b36970f2SChengwen Fengsupport a number of different DMA operations. 10b36970f2SChengwen Feng 11b36970f2SChengwen Feng 12b36970f2SChengwen FengDesign Principles 13b36970f2SChengwen Feng----------------- 14b36970f2SChengwen Feng 15b36970f2SChengwen FengThe DMA framework provides a generic DMA device framework which supports both 16b36970f2SChengwen Fengphysical (hardware) and virtual (software) DMA devices, as well as a generic DMA 17b36970f2SChengwen FengAPI which allows DMA devices to be managed and configured, and supports DMA 18b36970f2SChengwen Fengoperations to be provisioned on DMA poll mode driver. 19b36970f2SChengwen Feng 20b36970f2SChengwen Feng.. _figure_dmadev: 21b36970f2SChengwen Feng 22b36970f2SChengwen Feng.. figure:: img/dmadev.* 23b36970f2SChengwen Feng 24b36970f2SChengwen FengThe above figure shows the model on which the DMA framework is built on: 25b36970f2SChengwen Feng 26b36970f2SChengwen Feng * The DMA controller could have multiple hardware DMA channels (aka. hardware 27b36970f2SChengwen Feng DMA queues), each hardware DMA channel should be represented by a dmadev. 28b36970f2SChengwen Feng * The dmadev could create multiple virtual DMA channels, each virtual DMA 29b36970f2SChengwen Feng channel represents a different transfer context. 30b36970f2SChengwen Feng * The DMA operation request must be submitted to the virtual DMA channel. 31b36970f2SChengwen Feng 32b36970f2SChengwen Feng 33b36970f2SChengwen FengDevice Management 34b36970f2SChengwen Feng----------------- 35b36970f2SChengwen Feng 36b36970f2SChengwen FengDevice Creation 37b36970f2SChengwen Feng~~~~~~~~~~~~~~~ 38b36970f2SChengwen Feng 39b36970f2SChengwen FengPhysical DMA controllers are discovered during the PCI probe/enumeration of the 40b36970f2SChengwen FengEAL function which is executed at DPDK initialization, this is based on their 41b36970f2SChengwen FengPCI BDF (bus/bridge, device, function). Specific physical DMA controllers, like 42b36970f2SChengwen Fengother physical devices in DPDK can be listed using the EAL command line options. 43b36970f2SChengwen Feng 44b36970f2SChengwen FengThe dmadevs are dynamically allocated by using the function 45b36970f2SChengwen Feng``rte_dma_pmd_allocate`` based on the number of hardware DMA channels. 46b36970f2SChengwen Feng 47b36970f2SChengwen Feng 48b36970f2SChengwen FengDevice Identification 49b36970f2SChengwen Feng~~~~~~~~~~~~~~~~~~~~~ 50b36970f2SChengwen Feng 51b36970f2SChengwen FengEach DMA device, whether physical or virtual is uniquely designated by two 52b36970f2SChengwen Fengidentifiers: 53b36970f2SChengwen Feng 54b36970f2SChengwen Feng- A unique device index used to designate the DMA device in all functions 55b36970f2SChengwen Feng exported by the DMA API. 56b36970f2SChengwen Feng 57b36970f2SChengwen Feng- A device name used to designate the DMA device in console messages, for 58b36970f2SChengwen Feng administration or debugging purposes. 59e0180db1SChengwen Feng 60e0180db1SChengwen Feng 61e0180db1SChengwen FengDevice Features and Capabilities 62e0180db1SChengwen Feng-------------------------------- 63e0180db1SChengwen Feng 64e0180db1SChengwen FengDMA devices may support different feature sets. The ``rte_dma_info_get`` API 65e0180db1SChengwen Fengcan be used to get the device info and supported features. 66e0180db1SChengwen Feng 67e0180db1SChengwen FengSilent mode is a special device capability which does not require the 68e0180db1SChengwen Fengapplication to invoke dequeue APIs. 69*91e581e5SChengwen Feng 70*91e581e5SChengwen Feng 71*91e581e5SChengwen FengEnqueue / Dequeue APIs 72*91e581e5SChengwen Feng~~~~~~~~~~~~~~~~~~~~~~ 73*91e581e5SChengwen Feng 74*91e581e5SChengwen FengEnqueue APIs such as ``rte_dma_copy`` and ``rte_dma_fill`` can be used to 75*91e581e5SChengwen Fengenqueue operations to hardware. If an enqueue is successful, a ``ring_idx`` is 76*91e581e5SChengwen Fengreturned. This ``ring_idx`` can be used by applications to track per operation 77*91e581e5SChengwen Fengmetadata in an application-defined circular ring. 78*91e581e5SChengwen Feng 79*91e581e5SChengwen FengThe ``rte_dma_submit`` API is used to issue doorbell to hardware. 80*91e581e5SChengwen FengAlternatively the ``RTE_DMA_OP_FLAG_SUBMIT`` flag can be passed to the enqueue 81*91e581e5SChengwen FengAPIs to also issue the doorbell to hardware. 82*91e581e5SChengwen Feng 83*91e581e5SChengwen FengThere are two dequeue APIs ``rte_dma_completed`` and 84*91e581e5SChengwen Feng``rte_dma_completed_status``, these are used to obtain the results of the 85*91e581e5SChengwen Fengenqueue requests. ``rte_dma_completed`` will return the number of successfully 86*91e581e5SChengwen Fengcompleted operations. ``rte_dma_completed_status`` will return the number of 87*91e581e5SChengwen Fengcompleted operations along with the status of each operation (filled into the 88*91e581e5SChengwen Feng``status`` array passed by user). These two APIs can also return the last 89*91e581e5SChengwen Fengcompleted operation's ``ring_idx`` which could help user track operations within 90*91e581e5SChengwen Fengtheir own application-defined rings. 91