[dpdk-dev] [PATCH v13 5/6] doc: add DMA device library guide

[Jerin Jacob]

On Tue, Aug 3, 2021 at 5:03 PM 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        | 126 +++++++++++++++


doc build has following warning in my machine

ninja: Entering directory `build'
[2789/2813] Generating html_guides with a custom command
/export/dpdk.org/doc/guides/prog_guide/dmadev.rst:24: WARNING: Figure
caption must be a paragraph or empty comment.

.. 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.
[2813/2813] Linking target app/dpdk-test-pipeline

> new file mode 100644
> index 0000000..b305beb
> --- /dev/null
> +++ b/doc/guides/prog_guide/img/dmadev_i1.svg

why _i1 in the name?


> @@ -0,0 +1,278 @@
> +<?xml version="1.0" encoding="UTF-8" standalone="no"?>
> +<!-- Created with Inkscape (http://www.inkscape.org/) -->

You could add an SPDX license and your company copyright as well.
See other .svg files.


Rest looks good to me.


> +
> +<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
>