On Tue, Jul 27, 2021 at 9:13 AM Chengwen Feng <fengcheng...@huawei.com> wrote: > > This patch adds dmadev library guide. > > Signed-off-by: Chengwen Feng <fengcheng...@huawei.com> > --- > doc/guides/prog_guide/dmadev.rst | 123 > +++++++++++++++++++++++++++++++++++++++ > doc/guides/prog_guide/index.rst | 1 + > 2 files changed, 124 insertions(+) > create mode 100644 doc/guides/prog_guide/dmadev.rst > > diff --git a/doc/guides/prog_guide/dmadev.rst > b/doc/guides/prog_guide/dmadev.rst > new file mode 100644 > index 0000000..5bad598 > --- /dev/null > +++ b/doc/guides/prog_guide/dmadev.rst > @@ -0,0 +1,123 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright 2021 HiSilicon Limited > + > +DMA Device Library > +==================== > + > +The DMA library provides a DMA device framework for management and > provisioning > +of hardware and software DMA poll mode drivers, defining generic APIs which > +support a number of different DMA operations. > + > + > +Design Principles > +----------------- > + > +The DMA library follows the same basic principles as those used in DPDK's > +Ethernet Device framework and the RegEx framework. The DMA framework provides > +a generic DMA device framework which supports both physical (hardware) > +and virtual (software) DMA devices as well as a generic DMA API which allows > +DMA devices to be managed and configured and supports DMA operations to be > +provisioned on DMA poll mode driver. > + > +Figure below outlines the model of the DMA framework built on: > + > +.. code-block:: console > + > + +-------------+ +-------------+ +-------------+ > + | virtual DMA | | virtual DMA | | virtual DMA | > + | channel | | channel | | channel | > + +-------------+ +-------------+ +-------------+ > + | | | > + ------------------- | > + | | > + +----------+ +----------+ > + | dmadev | | dmadev | > + +----------+ +----------+ > + | | > + +--------------+ +--------------+ > + | hardware DMA | | hardware DMA | > + | channel | | channel | > + +--------------+ +--------------+ > + | | > + -------------------------------- > + | > + +--------------+ > + | hardware DMA | > + | controller | > + +--------------+
Please change to .svg file. See grep -ri "Inkscape" doc/guides/contributing/documentation.rst for guidelines. > + > + * The DMA controller could have multiple hardware DMA channels (aka. > hardware > + DMA queues), each hardware DMA channel should be represented by a dmadev. > + * The dmadev could create multiple virtual DMA channels, each virtual DMA > + channel represents a different transfer context. The DMA operation request > + must be submitted to the virtual DMA channel. e.g. Application could > create > + virtual DMA channel 0 for memory-to-memory transfer scenario, and create > + virtual DMA channel 1 for memory-to-device transfer scenario. > + > + > +Device Management > +----------------- > + > +Device Creation > +~~~~~~~~~~~~~~~ > + > +Physical DMA controller is discovered during the PCI probe/enumeration of the > +EAL function which is executed at DPDK initialization, based on their PCI > +device identifier, each unique PCI BDF (bus/bridge, device, function). > Specific > +physical DMA controller, like other physical devices in DPDK can be listed > using > +the EAL command line options. > + > +And then dmadevs are dynamically allocated by rte_dmadev_pmd_allocate() > based on > +the number of hardware DMA channels. > + > + > +Device Identification > +~~~~~~~~~~~~~~~~~~~~~ > + > +Each DMA device, whether physical or virtual is uniquely designated by two > +identifiers: > + > +- A unique device index used to designate the DMA device in all functions > + exported by the DMA API. > + > +- A device name used to designate the DMA device in console messages, for > + administration or debugging purposes. > + > + > +Device Configuration > +~~~~~~~~~~~~~~~~~~~~ > + > +The rte_dmadev_configure API is used to configure a DMA device. > + > +.. code-block:: c > + > + int rte_dmadev_configure(uint16_t dev_id, > + const struct rte_dmadev_conf *dev_conf); > + > +The ``rte_dmadev_conf`` structure is used to pass the configuration > parameters > +for the DMA device for example maximum number of virtual DMA channels, > +indication of whether to enable silent mode. > + > + > +Configuration of Virtual DMA Channels > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +The rte_dmadev_vchan_setup API is used to configure a virtual DMA channel. > + > +.. code-block:: c > + > + int rte_dmadev_vchan_setup(uint16_t dev_id, > + const struct rte_dmadev_vchan_conf > *conf); > + > +The ``rte_dmadev_vchan_conf`` structure is used to pass the configuration > +parameters for the virtual DMA channel for example transfer direction, > number of > +descriptor for the virtual DMA channel, source device access port parameter, > +destination device access port parameter. Looks good. Some other section really useful and it is specific to DMADEV could be added 1) ring_idx management, You can copy the texts from API header file or so 2) rte_dmadev_completed() management. 3) Talk about silent mode too.
