1*b36970f2SChengwen Feng.. SPDX-License-Identifier: BSD-3-Clause 2*b36970f2SChengwen Feng Copyright 2021 HiSilicon Limited 3*b36970f2SChengwen Feng 4*b36970f2SChengwen FengDMA Device Library 5*b36970f2SChengwen Feng================== 6*b36970f2SChengwen Feng 7*b36970f2SChengwen FengThe DMA library provides a DMA device framework for management and provisioning 8*b36970f2SChengwen Fengof hardware and software DMA poll mode drivers, defining generic API which 9*b36970f2SChengwen Fengsupport a number of different DMA operations. 10*b36970f2SChengwen Feng 11*b36970f2SChengwen Feng 12*b36970f2SChengwen FengDesign Principles 13*b36970f2SChengwen Feng----------------- 14*b36970f2SChengwen Feng 15*b36970f2SChengwen FengThe DMA framework provides a generic DMA device framework which supports both 16*b36970f2SChengwen Fengphysical (hardware) and virtual (software) DMA devices, as well as a generic DMA 17*b36970f2SChengwen FengAPI which allows DMA devices to be managed and configured, and supports DMA 18*b36970f2SChengwen Fengoperations to be provisioned on DMA poll mode driver. 19*b36970f2SChengwen Feng 20*b36970f2SChengwen Feng.. _figure_dmadev: 21*b36970f2SChengwen Feng 22*b36970f2SChengwen Feng.. figure:: img/dmadev.* 23*b36970f2SChengwen Feng 24*b36970f2SChengwen FengThe above figure shows the model on which the DMA framework is built on: 25*b36970f2SChengwen Feng 26*b36970f2SChengwen Feng * The DMA controller could have multiple hardware DMA channels (aka. hardware 27*b36970f2SChengwen Feng DMA queues), each hardware DMA channel should be represented by a dmadev. 28*b36970f2SChengwen Feng * The dmadev could create multiple virtual DMA channels, each virtual DMA 29*b36970f2SChengwen Feng channel represents a different transfer context. 30*b36970f2SChengwen Feng * The DMA operation request must be submitted to the virtual DMA channel. 31*b36970f2SChengwen Feng 32*b36970f2SChengwen Feng 33*b36970f2SChengwen FengDevice Management 34*b36970f2SChengwen Feng----------------- 35*b36970f2SChengwen Feng 36*b36970f2SChengwen FengDevice Creation 37*b36970f2SChengwen Feng~~~~~~~~~~~~~~~ 38*b36970f2SChengwen Feng 39*b36970f2SChengwen FengPhysical DMA controllers are discovered during the PCI probe/enumeration of the 40*b36970f2SChengwen FengEAL function which is executed at DPDK initialization, this is based on their 41*b36970f2SChengwen FengPCI BDF (bus/bridge, device, function). Specific physical DMA controllers, like 42*b36970f2SChengwen Fengother physical devices in DPDK can be listed using the EAL command line options. 43*b36970f2SChengwen Feng 44*b36970f2SChengwen FengThe dmadevs are dynamically allocated by using the function 45*b36970f2SChengwen Feng``rte_dma_pmd_allocate`` based on the number of hardware DMA channels. 46*b36970f2SChengwen Feng 47*b36970f2SChengwen Feng 48*b36970f2SChengwen FengDevice Identification 49*b36970f2SChengwen Feng~~~~~~~~~~~~~~~~~~~~~ 50*b36970f2SChengwen Feng 51*b36970f2SChengwen FengEach DMA device, whether physical or virtual is uniquely designated by two 52*b36970f2SChengwen Fengidentifiers: 53*b36970f2SChengwen Feng 54*b36970f2SChengwen Feng- A unique device index used to designate the DMA device in all functions 55*b36970f2SChengwen Feng exported by the DMA API. 56*b36970f2SChengwen Feng 57*b36970f2SChengwen Feng- A device name used to designate the DMA device in console messages, for 58*b36970f2SChengwen Feng administration or debugging purposes. 59