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