[v20,5/7] doc: add DMA device library guide
Checks
Commit Message
This patch adds dmadev library guide.
Signed-off-by: Chengwen Feng <fengchengwen@huawei.com>
Acked-by: Conor Walsh <conor.walsh@intel.com>
Reviewed-by: Kevin Laatz <kevin.laatz@intel.com>
---
MAINTAINERS | 1 +
doc/guides/prog_guide/dmadev.rst | 125 ++++++++++++
doc/guides/prog_guide/img/dmadev.svg | 283 +++++++++++++++++++++++++++
doc/guides/prog_guide/index.rst | 1 +
4 files changed, 410 insertions(+)
create mode 100644 doc/guides/prog_guide/dmadev.rst
create mode 100644 doc/guides/prog_guide/img/dmadev.svg
Comments
On Sat, Sep 4, 2021 at 3:44 PM Chengwen Feng <fengchengwen@huawei.com> wrote:
>
> This patch adds dmadev library guide.
>
> Signed-off-by: Chengwen Feng <fengchengwen@huawei.com>
> Acked-by: Conor Walsh <conor.walsh@intel.com>
> Reviewed-by: Kevin Laatz <kevin.laatz@intel.com>
Acked-by: Jerin Jacob <jerinj@marvell.com>
> ---
> MAINTAINERS | 1 +
> doc/guides/prog_guide/dmadev.rst | 125 ++++++++++++
> doc/guides/prog_guide/img/dmadev.svg | 283 +++++++++++++++++++++++++++
> doc/guides/prog_guide/index.rst | 1 +
> 4 files changed, 410 insertions(+)
> create mode 100644 doc/guides/prog_guide/dmadev.rst
> create mode 100644 doc/guides/prog_guide/img/dmadev.svg
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 9885cc56b7..e237e9406b 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -499,6 +499,7 @@ F: doc/guides/prog_guide/rawdev.rst
> DMA device API - EXPERIMENTAL
> M: Chengwen Feng <fengchengwen@huawei.com>
> F: lib/dmadev/
> +F: doc/guides/prog_guide/dmadev.rst
>
>
> Memory Pool Drivers
> diff --git a/doc/guides/prog_guide/dmadev.rst b/doc/guides/prog_guide/dmadev.rst
> new file mode 100644
> index 0000000000..e47a164850
> --- /dev/null
> +++ b/doc/guides/prog_guide/dmadev.rst
> @@ -0,0 +1,125 @@
> +.. 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_dmadev:
> +
> +.. figure:: img/dmadev.*
> +
> +The above figure shows the model on which the DMA framework is built on:
> +
> + * 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 controllers are discovered during the PCI probe/enumeration of the
> +EAL function which is executed at DPDK initialization, this is based on their
> +PCI BDF (bus/bridge, device, function). Specific physical DMA controllers, like
> +other physical devices in DPDK can be listed using the EAL command line options.
> +
> +The dmadevs are dynamically allocated by using the API
> +``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 the number of virtual DMA channels to set up,
> +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, uint16_t vchan,
> + 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.
> +
> +
> +Device Features and Capabilities
> +--------------------------------
> +
> +DMA devices may support different feature sets. The ``rte_dmadev_info_get`` API
> +can be used to get the device info and supported features.
> +
> +Silent mode is a special device capability which does not require the
> +application to invoke dequeue APIs.
> +
> +
> +Enqueue / Dequeue APIs
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +Enqueue APIs such as ``rte_dmadev_copy`` and ``rte_dmadev_fill`` can be used to
> +enqueue operations to hardware. If an enqueue is successful, a ``ring_idx`` is
> +returned. This ``ring_idx`` can be used by applications to track per operation
> +metadata in an application-defined circular ring.
> +
> +The ``rte_dmadev_submit`` API is used to issue doorbell to hardware.
> +Alternatively the ``RTE_DMA_OP_FLAG_SUBMIT`` flag can be passed to the enqueue
> +APIs to also issue the doorbell to hardware.
> +
> +There are two dequeue APIs ``rte_dmadev_completed`` and
> +``rte_dmadev_completed_status``, these are used to obtain the results of
> +the enqueue requests. ``rte_dmadev_completed`` will return the number of
> +successfully completed operations. ``rte_dmadev_completed_status`` will return
> +the number of completed operations along with the status of each operation
> +(filled into the ``status`` array passed by user). These two APIs can also
> +return the last completed operation's ``ring_idx`` which could help user track
> +operations within their own application-defined rings.
> diff --git a/doc/guides/prog_guide/img/dmadev.svg b/doc/guides/prog_guide/img/dmadev.svg
> new file mode 100644
> index 0000000000..157d7eb7dc
> --- /dev/null
> +++ b/doc/guides/prog_guide/img/dmadev.svg
> @@ -0,0 +1,283 @@
> +<?xml version="1.0" encoding="UTF-8" standalone="no"?>
> +<!-- Created with Inkscape (http://www.inkscape.org/) -->
> +
> +<!-- SPDX-License-Identifier: BSD-3-Clause -->
> +<!-- Copyright(c) 2021 HiSilicon Limited -->
> +
> +<svg
> + width="128.64288mm"
> + height="95.477707mm"
> + viewBox="0 0 192.96433 143.21656"
> + version="1.1"
> + id="svg934"
> + inkscape:version="1.1 (c68e22c387, 2021-05-23)"
> + sodipodi:docname="dmadev.svg"
> + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
> + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
> + xmlns="http://www.w3.org/2000/svg"
> + xmlns:svg="http://www.w3.org/2000/svg">
> + <sodipodi:namedview
> + id="namedview936"
> + pagecolor="#ffffff"
> + bordercolor="#666666"
> + borderopacity="1.0"
> + inkscape:pageshadow="2"
> + inkscape:pageopacity="0.0"
> + inkscape:pagecheckerboard="0"
> + inkscape:document-units="mm"
> + showgrid="false"
> + fit-margin-top="0"
> + fit-margin-left="0"
> + fit-margin-right="0"
> + fit-margin-bottom="0"
> + inkscape:showpageshadow="false"
> + inkscape:zoom="1.332716"
> + inkscape:cx="335.03011"
> + inkscape:cy="143.69152"
> + inkscape:window-width="1920"
> + inkscape:window-height="976"
> + inkscape:window-x="-8"
> + inkscape:window-y="-8"
> + inkscape:window-maximized="1"
> + inkscape:current-layer="layer1"
> + scale-x="1.5"
> + units="mm" />
> + <defs
> + id="defs931">
> + <rect
> + x="342.43954"
> + y="106.56832"
> + width="58.257381"
> + height="137.82834"
> + id="rect17873" />
> + </defs>
> + <g
> + inkscape:label="Layer 1"
> + inkscape:groupmode="layer"
> + id="layer1"
> + transform="translate(-0.13857517,-21.527306)">
> + <rect
> + style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.296755"
> + id="rect31-9"
> + width="50"
> + height="28"
> + x="0.13857517"
> + y="21.527306"
> + ry="0" />
> + <text
> + xml:space="preserve"
> + style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
> + x="54.136707"
> + y="18.045568"
> + id="text803-1"
> + transform="translate(-49.110795,15.205683)"><tspan
> + x="54.136707"
> + y="18.045568"
> + id="tspan1045">virtual DMA </tspan><tspan
> + x="54.136707"
> + y="26.865018"
> + id="tspan1047">channel</tspan></text>
> + <rect
> + style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.296755"
> + id="rect31-9-5"
> + width="50"
> + height="28"
> + x="60.138577"
> + y="21.527306"
> + ry="0" />
> + <text
> + xml:space="preserve"
> + style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
> + x="54.136707"
> + y="18.045568"
> + id="text803-1-4"
> + transform="translate(10.512565,15.373298)"><tspan
> + x="54.136707"
> + y="18.045568"
> + id="tspan1049">virtual DMA </tspan><tspan
> + x="54.136707"
> + y="26.865018"
> + id="tspan1051">channel</tspan></text>
> + <rect
> + style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.296755"
> + id="rect31-9-5-3"
> + width="50"
> + height="28"
> + x="137.43863"
> + y="21.527306"
> + ry="0" />
> + <text
> + xml:space="preserve"
> + style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
> + x="54.136707"
> + y="18.045568"
> + id="text803-1-4-8"
> + transform="translate(88.79231,15.373299)"><tspan
> + x="54.136707"
> + y="18.045568"
> + id="tspan1053">virtual DMA </tspan><tspan
> + x="54.136707"
> + y="26.865018"
> + id="tspan1055">channel</tspan></text>
> + <text
> + xml:space="preserve"
> + transform="matrix(0.26458333,0,0,0.26458333,-0.04940429,21.408845)"
> + id="text17871"
> + style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;white-space:pre;shape-inside:url(#rect17873);fill:#000000;fill-opacity:1;stroke:none" />
> + <rect
> + style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.218145"
> + id="rect31-9-5-8"
> + width="38.34557"
> + height="19.729115"
> + x="36.138577"
> + y="64.827354"
> + ry="0" />
> + <text
> + xml:space="preserve"
> + style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
> + x="54.136707"
> + y="18.045568"
> + id="text803-1-4-3"
> + transform="translate(-13.394978,59.135217)"><tspan
> + x="54.136707"
> + y="18.045568"
> + id="tspan1057">dmadev</tspan></text>
> + <rect
> + style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.307089"
> + id="rect31-9-5-8-0"
> + width="60.902534"
> + height="24.616455"
> + x="25.196909"
> + y="98.47744"
> + ry="0" />
> + <text
> + xml:space="preserve"
> + style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
> + x="54.136707"
> + y="18.045568"
> + id="text803-1-4-3-76"
> + transform="translate(-24.485484,90.97883)"><tspan
> + x="54.136707"
> + y="18.045568"
> + id="tspan1059">hardware DMA </tspan><tspan
> + x="54.136707"
> + y="26.865018"
> + id="tspan1061">channel</tspan></text>
> + <rect
> + style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.307089"
> + id="rect31-9-5-8-0-6"
> + width="60.902534"
> + height="24.616455"
> + x="132.20036"
> + y="98.47744"
> + ry="0" />
> + <text
> + xml:space="preserve"
> + style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
> + x="54.136707"
> + y="18.045568"
> + id="text803-1-4-3-76-7"
> + transform="translate(82.950904,90.79085)"><tspan
> + x="54.136707"
> + y="18.045568"
> + id="tspan1063">hardware DMA </tspan><tspan
> + x="54.136707"
> + y="26.865018"
> + id="tspan1065">channel</tspan></text>
> + <rect
> + style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.307089"
> + id="rect31-9-5-8-0-4"
> + width="60.902534"
> + height="24.616455"
> + x="76.810928"
> + y="140.12741"
> + ry="0" />
> + <text
> + xml:space="preserve"
> + style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
> + x="54.136707"
> + y="18.045568"
> + id="text803-1-4-3-76-4"
> + transform="translate(27.032341,133.10574)"><tspan
> + x="54.136707"
> + y="18.045568"
> + id="tspan1067">hardware DMA </tspan><tspan
> + x="54.136707"
> + y="26.865018"
> + id="tspan1069">controller</tspan></text>
> + <rect
> + style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.218145"
> + id="rect31-9-5-8-5"
> + width="38.34557"
> + height="19.729115"
> + x="143.43863"
> + y="64.827354"
> + ry="0" />
> + <text
> + xml:space="preserve"
> + style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
> + x="54.136707"
> + y="18.045568"
> + id="text803-1-4-3-7"
> + transform="translate(94.92597,59.664385)"><tspan
> + x="54.136707"
> + y="18.045568"
> + id="tspan1071">dmadev</tspan></text>
> + <path
> + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
> + d="M 74.476373,49.527306 62.82407,64.827354"
> + id="path45308"
> + inkscape:connector-type="polyline"
> + inkscape:connector-curvature="0"
> + inkscape:connection-start="#rect31-9-5"
> + inkscape:connection-end="#rect31-9-5-8" />
> + <path
> + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
> + d="M 35.924309,49.527306 47.711612,64.827354"
> + id="path45310"
> + inkscape:connector-type="polyline"
> + inkscape:connector-curvature="0"
> + inkscape:connection-start="#rect31-9"
> + inkscape:connection-end="#rect31-9-5-8" />
> + <path
> + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
> + d="M 55.403414,84.556469 55.53332,98.47744"
> + id="path45312"
> + inkscape:connector-type="polyline"
> + inkscape:connector-curvature="0"
> + inkscape:connection-start="#rect31-9-5-8"
> + inkscape:connection-end="#rect31-9-5-8-0" />
> + <path
> + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
> + d="m 162.62241,84.556469 0.0155,13.920971"
> + id="path45320"
> + inkscape:connector-type="polyline"
> + inkscape:connector-curvature="0"
> + inkscape:connection-start="#rect31-9-5-8-5"
> + inkscape:connection-end="#rect31-9-5-8-0-6" />
> + <path
> + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
> + d="m 146.28317,123.09389 -22.65252,17.03352"
> + id="path45586"
> + inkscape:connector-type="polyline"
> + inkscape:connector-curvature="0"
> + inkscape:connection-start="#rect31-9-5-8-0-6"
> + inkscape:connection-end="#rect31-9-5-8-0-4" />
> + <path
> + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
> + d="m 70.900938,123.09389 21.108496,17.03352"
> + id="path45588"
> + inkscape:connector-type="polyline"
> + inkscape:connector-curvature="0"
> + inkscape:connection-start="#rect31-9-5-8-0"
> + inkscape:connection-end="#rect31-9-5-8-0-4" />
> + <path
> + style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
> + d="m 162.50039,49.527306 0.0675,15.300048"
> + id="path45956"
> + inkscape:connector-type="polyline"
> + inkscape:connector-curvature="0"
> + inkscape:connection-start="#rect31-9-5-3"
> + inkscape:connection-end="#rect31-9-5-8-5" />
> + </g>
> +</svg>
> diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst
> index 2dce507f46..0abea06b24 100644
> --- a/doc/guides/prog_guide/index.rst
> +++ b/doc/guides/prog_guide/index.rst
> @@ -29,6 +29,7 @@ Programmer's Guide
> regexdev
> rte_security
> rawdev
> + dmadev
> link_bonding_poll_mode_drv_lib
> timer_lib
> hash_lib
> --
> 2.33.0
>
@@ -499,6 +499,7 @@ F: doc/guides/prog_guide/rawdev.rst
DMA device API - EXPERIMENTAL
M: Chengwen Feng <fengchengwen@huawei.com>
F: lib/dmadev/
+F: doc/guides/prog_guide/dmadev.rst
Memory Pool Drivers
new file mode 100644
@@ -0,0 +1,125 @@
+.. 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_dmadev:
+
+.. figure:: img/dmadev.*
+
+The above figure shows the model on which the DMA framework is built on:
+
+ * 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 controllers are discovered during the PCI probe/enumeration of the
+EAL function which is executed at DPDK initialization, this is based on their
+PCI BDF (bus/bridge, device, function). Specific physical DMA controllers, like
+other physical devices in DPDK can be listed using the EAL command line options.
+
+The dmadevs are dynamically allocated by using the API
+``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 the number of virtual DMA channels to set up,
+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, uint16_t vchan,
+ 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.
+
+
+Device Features and Capabilities
+--------------------------------
+
+DMA devices may support different feature sets. The ``rte_dmadev_info_get`` API
+can be used to get the device info and supported features.
+
+Silent mode is a special device capability which does not require the
+application to invoke dequeue APIs.
+
+
+Enqueue / Dequeue APIs
+~~~~~~~~~~~~~~~~~~~~~~
+
+Enqueue APIs such as ``rte_dmadev_copy`` and ``rte_dmadev_fill`` can be used to
+enqueue operations to hardware. If an enqueue is successful, a ``ring_idx`` is
+returned. This ``ring_idx`` can be used by applications to track per operation
+metadata in an application-defined circular ring.
+
+The ``rte_dmadev_submit`` API is used to issue doorbell to hardware.
+Alternatively the ``RTE_DMA_OP_FLAG_SUBMIT`` flag can be passed to the enqueue
+APIs to also issue the doorbell to hardware.
+
+There are two dequeue APIs ``rte_dmadev_completed`` and
+``rte_dmadev_completed_status``, these are used to obtain the results of
+the enqueue requests. ``rte_dmadev_completed`` will return the number of
+successfully completed operations. ``rte_dmadev_completed_status`` will return
+the number of completed operations along with the status of each operation
+(filled into the ``status`` array passed by user). These two APIs can also
+return the last completed operation's ``ring_idx`` which could help user track
+operations within their own application-defined rings.
new file mode 100644
@@ -0,0 +1,283 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<!-- SPDX-License-Identifier: BSD-3-Clause -->
+<!-- Copyright(c) 2021 HiSilicon Limited -->
+
+<svg
+ width="128.64288mm"
+ height="95.477707mm"
+ viewBox="0 0 192.96433 143.21656"
+ version="1.1"
+ id="svg934"
+ inkscape:version="1.1 (c68e22c387, 2021-05-23)"
+ sodipodi:docname="dmadev.svg"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:svg="http://www.w3.org/2000/svg">
+ <sodipodi:namedview
+ id="namedview936"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageshadow="2"
+ inkscape:pageopacity="0.0"
+ inkscape:pagecheckerboard="0"
+ inkscape:document-units="mm"
+ showgrid="false"
+ fit-margin-top="0"
+ fit-margin-left="0"
+ fit-margin-right="0"
+ fit-margin-bottom="0"
+ inkscape:showpageshadow="false"
+ inkscape:zoom="1.332716"
+ inkscape:cx="335.03011"
+ inkscape:cy="143.69152"
+ inkscape:window-width="1920"
+ inkscape:window-height="976"
+ inkscape:window-x="-8"
+ inkscape:window-y="-8"
+ inkscape:window-maximized="1"
+ inkscape:current-layer="layer1"
+ scale-x="1.5"
+ units="mm" />
+ <defs
+ id="defs931">
+ <rect
+ x="342.43954"
+ y="106.56832"
+ width="58.257381"
+ height="137.82834"
+ id="rect17873" />
+ </defs>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ transform="translate(-0.13857517,-21.527306)">
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.296755"
+ id="rect31-9"
+ width="50"
+ height="28"
+ x="0.13857517"
+ y="21.527306"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
+ x="54.136707"
+ y="18.045568"
+ id="text803-1"
+ transform="translate(-49.110795,15.205683)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1045">virtual DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1047">channel</tspan></text>
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.296755"
+ id="rect31-9-5"
+ width="50"
+ height="28"
+ x="60.138577"
+ y="21.527306"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
+ x="54.136707"
+ y="18.045568"
+ id="text803-1-4"
+ transform="translate(10.512565,15.373298)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1049">virtual DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1051">channel</tspan></text>
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.296755"
+ id="rect31-9-5-3"
+ width="50"
+ height="28"
+ x="137.43863"
+ y="21.527306"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
+ x="54.136707"
+ y="18.045568"
+ id="text803-1-4-8"
+ transform="translate(88.79231,15.373299)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1053">virtual DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1055">channel</tspan></text>
+ <text
+ xml:space="preserve"
+ transform="matrix(0.26458333,0,0,0.26458333,-0.04940429,21.408845)"
+ id="text17871"
+ style="font-style:normal;font-weight:normal;font-size:40px;line-height:1.25;font-family:sans-serif;white-space:pre;shape-inside:url(#rect17873);fill:#000000;fill-opacity:1;stroke:none" />
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.218145"
+ id="rect31-9-5-8"
+ width="38.34557"
+ height="19.729115"
+ x="36.138577"
+ y="64.827354"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
+ x="54.136707"
+ y="18.045568"
+ id="text803-1-4-3"
+ transform="translate(-13.394978,59.135217)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1057">dmadev</tspan></text>
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.307089"
+ id="rect31-9-5-8-0"
+ width="60.902534"
+ height="24.616455"
+ x="25.196909"
+ y="98.47744"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
+ x="54.136707"
+ y="18.045568"
+ id="text803-1-4-3-76"
+ transform="translate(-24.485484,90.97883)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1059">hardware DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1061">channel</tspan></text>
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.307089"
+ id="rect31-9-5-8-0-6"
+ width="60.902534"
+ height="24.616455"
+ x="132.20036"
+ y="98.47744"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
+ x="54.136707"
+ y="18.045568"
+ id="text803-1-4-3-76-7"
+ transform="translate(82.950904,90.79085)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1063">hardware DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1065">channel</tspan></text>
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.307089"
+ id="rect31-9-5-8-0-4"
+ width="60.902534"
+ height="24.616455"
+ x="76.810928"
+ y="140.12741"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
+ x="54.136707"
+ y="18.045568"
+ id="text803-1-4-3-76-4"
+ transform="translate(27.032341,133.10574)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1067">hardware DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1069">controller</tspan></text>
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.218145"
+ id="rect31-9-5-8-5"
+ width="38.34557"
+ height="19.729115"
+ x="143.43863"
+ y="64.827354"
+ ry="0" />
+ <text
+ xml:space="preserve"
+ style="font-style:normal;font-weight:normal;font-size:7.05556px;line-height:1.25;font-family:sans-serif;white-space:pre;inline-size:70.1114;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.264583"
+ x="54.136707"
+ y="18.045568"
+ id="text803-1-4-3-7"
+ transform="translate(94.92597,59.664385)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1071">dmadev</tspan></text>
+ <path
+ style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="M 74.476373,49.527306 62.82407,64.827354"
+ id="path45308"
+ inkscape:connector-type="polyline"
+ inkscape:connector-curvature="0"
+ inkscape:connection-start="#rect31-9-5"
+ inkscape:connection-end="#rect31-9-5-8" />
+ <path
+ style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="M 35.924309,49.527306 47.711612,64.827354"
+ id="path45310"
+ inkscape:connector-type="polyline"
+ inkscape:connector-curvature="0"
+ inkscape:connection-start="#rect31-9"
+ inkscape:connection-end="#rect31-9-5-8" />
+ <path
+ style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="M 55.403414,84.556469 55.53332,98.47744"
+ id="path45312"
+ inkscape:connector-type="polyline"
+ inkscape:connector-curvature="0"
+ inkscape:connection-start="#rect31-9-5-8"
+ inkscape:connection-end="#rect31-9-5-8-0" />
+ <path
+ style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 162.62241,84.556469 0.0155,13.920971"
+ id="path45320"
+ inkscape:connector-type="polyline"
+ inkscape:connector-curvature="0"
+ inkscape:connection-start="#rect31-9-5-8-5"
+ inkscape:connection-end="#rect31-9-5-8-0-6" />
+ <path
+ style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 146.28317,123.09389 -22.65252,17.03352"
+ id="path45586"
+ inkscape:connector-type="polyline"
+ inkscape:connector-curvature="0"
+ inkscape:connection-start="#rect31-9-5-8-0-6"
+ inkscape:connection-end="#rect31-9-5-8-0-4" />
+ <path
+ style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 70.900938,123.09389 21.108496,17.03352"
+ id="path45588"
+ inkscape:connector-type="polyline"
+ inkscape:connector-curvature="0"
+ inkscape:connection-start="#rect31-9-5-8-0"
+ inkscape:connection-end="#rect31-9-5-8-0-4" />
+ <path
+ style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+ d="m 162.50039,49.527306 0.0675,15.300048"
+ id="path45956"
+ inkscape:connector-type="polyline"
+ inkscape:connector-curvature="0"
+ inkscape:connection-start="#rect31-9-5-3"
+ inkscape:connection-end="#rect31-9-5-8-5" />
+ </g>
+</svg>
@@ -29,6 +29,7 @@ Programmer's Guide
regexdev
rte_security
rawdev
+ dmadev
link_bonding_poll_mode_drv_lib
timer_lib
hash_lib