[dpdk-dev] [PATCH v13 5/6] doc: add DMA device library guide
Chengwen Feng
fengchengwen at huawei.com
Tue Aug 3 13:29:48 CEST 2021
This patch adds dmadev library guide.
Signed-off-by: Chengwen Feng <fengchengwen at huawei.com>
---
doc/guides/prog_guide/dmadev.rst | 126 +++++++++++++++
doc/guides/prog_guide/img/dmadev_i1.svg | 278 ++++++++++++++++++++++++++++++++
doc/guides/prog_guide/index.rst | 1 +
3 files changed, 405 insertions(+)
create mode 100644 doc/guides/prog_guide/dmadev.rst
create mode 100644 doc/guides/prog_guide/img/dmadev_i1.svg
diff --git a/doc/guides/prog_guide/dmadev.rst b/doc/guides/prog_guide/dmadev.rst
new file mode 100644
index 0000000..c6327db
--- /dev/null
+++ b/doc/guides/prog_guide/dmadev.rst
@@ -0,0 +1,126 @@
+.. 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_i1:
+
+.. figure:: img/dmadev_i1.*
+
+ The model of the DMA framework 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 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.
+
+
+Device Features and Capabilities
+--------------------------------
+
+DMA devices may support different feature set. In order to get the supported PMD
+features ``rte_dmadev_info_get`` API which returns the info of the device and
+it's supported features.
+
+A special device capability is silent mode which application don't required to
+invoke dequeue APIs.
+
+
+Enqueue / Dequeue APIs
+~~~~~~~~~~~~~~~~~~~~~~
+
+The enqueue APIs include like ``rte_dmadev_copy`` and ``rte_dmadev_fill``, if
+enqueue successful, an uint16_t 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 was used to issue doorbell to hardware, and also
+there are flags (``RTE_DMA_OP_FLAG_SUBMIT``) parameter of the enqueue APIs
+could do the same work.
+
+There are two dequeue APIs (``rte_dmadev_completed`` and
+``rte_dmadev_completed_status``) could used to obtain the result of request.
+The first API returns the number of operation requests completed successfully,
+the second API returns the number of operation requests completed which may
+successfully or failed and also with meaningful status code. Also these two
+APIs could return the last completed operation's ring_idx which will help to
+track application-defined circular ring.
diff --git a/doc/guides/prog_guide/img/dmadev_i1.svg b/doc/guides/prog_guide/img/dmadev_i1.svg
new file mode 100644
index 0000000..b305beb
--- /dev/null
+++ b/doc/guides/prog_guide/img/dmadev_i1.svg
@@ -0,0 +1,278 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ width="206.19344mm"
+ height="168.97479mm"
+ viewBox="0 0 206.19344 168.97479"
+ version="1.1"
+ id="svg934"
+ inkscape:version="1.1 (c68e22c387, 2021-05-23)"
+ sodipodi:docname="dmadev_i1.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="0.66635802"
+ inkscape:cx="396.93377"
+ inkscape:cy="480.22233"
+ inkscape:window-width="1920"
+ inkscape:window-height="1017"
+ inkscape:window-x="1914"
+ inkscape:window-y="-8"
+ inkscape:window-maximized="1"
+ inkscape:current-layer="layer1" />
+ <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="tspan1277">virtual DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1279">channel</tspan></text>
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.296755"
+ id="rect31-9-5"
+ width="50"
+ height="28"
+ x="60.820271"
+ y="21.69492"
+ 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(11.570899,15.373298)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1281">virtual DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1283">channel</tspan></text>
+ <rect
+ style="fill:#c9c9ff;fill-opacity:1;stroke-width:0.296755"
+ id="rect31-9-5-3"
+ width="50"
+ height="28"
+ x="150.74168"
+ y="21.694923"
+ 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(101.49231,15.373299)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1285">virtual DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1287">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="35.854393"
+ y="79.215172"
+ 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,72.893551)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1289">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="24.763887"
+ y="117.93796"
+ 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,111.61634)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1291">hardware DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1293">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="145.42947"
+ y="117.74998"
+ 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(96.180071,111.42836)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1295">hardware DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1297">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="87.923386"
+ y="165.88565"
+ 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(38.674008,159.56408)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1299">hardware DMA </tspan><tspan
+ x="54.136707"
+ y="26.865018"
+ id="tspan1301">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="156.87534"
+ y="79.215179"
+ 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(107.62597,72.893552)"><tspan
+ x="54.136707"
+ y="18.045568"
+ id="tspan1303">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 77.744878,49.69492 60.71719,79.215172"
+ 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 32.952235,49.527306 16.56935,29.687866"
+ 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.072222,98.944286 0.08673,18.993674"
+ 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 176.00783,98.944294 -0.0768,18.805686"
+ 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 161.17651,142.36643 -28.09763,23.51922"
+ 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 71.42827,142.55441 30.73327,23.33124"
+ 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 175.82205,49.694923 0.16945,29.520256"
+ 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 2dce507..0abea06 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.8.1
More information about the dev
mailing list