On Sat, Sep 4, 2021 at 3:44 PM Chengwen Feng <fengcheng...@huawei.com> wrote: > > This patch adds dmadev library guide. > > Signed-off-by: Chengwen Feng <fengcheng...@huawei.com> > Acked-by: Conor Walsh <conor.wa...@intel.com> > Reviewed-by: Kevin Laatz <kevin.la...@intel.com>
Acked-by: Jerin Jacob <jer...@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 <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 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 >
