This patch adds dmadev library guide. Signed-off-by: Chengwen Feng <fengcheng...@huawei.com> Acked-by: Conor Walsh <conor.wa...@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
diff --git a/MAINTAINERS b/MAINTAINERS index 22dcd12..3858aa7 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -499,6 +499,7 @@ F: doc/guides/prog_guide/rawdev.rst DMA device API - EXPERIMENTAL M: Chengwen Feng <fengcheng...@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 0000000..e47a164 --- /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 0000000..157d7eb --- /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 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
