[dpdk-dev] [PATCH v11 2/2] doc: add dmadev library guide

[Jerin Jacob]

On Tue, Jul 27, 2021 at 9:13 AM Chengwen Feng <fengchengwen at huawei.com> wrote:
>
> This patch adds dmadev library guide.
>
> Signed-off-by: Chengwen Feng <fengchengwen at 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.