From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 1695AA0C53; Sat, 4 Sep 2021 12:17:47 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id E81B840E3C; Sat, 4 Sep 2021 12:17:46 +0200 (CEST) Received: from mail-il1-f182.google.com (mail-il1-f182.google.com [209.85.166.182]) by mails.dpdk.org (Postfix) with ESMTP id 221D440DDD for ; Sat, 4 Sep 2021 12:17:45 +0200 (CEST) Received: by mail-il1-f182.google.com with SMTP id x5so1545382ill.3 for ; Sat, 04 Sep 2021 03:17:45 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=BnMf7PqmxoE/KVCNHjOfyhD0Bs8qlF6M7TFRP/l+vs4=; b=FJIiFwSIHmlyTS/rGr7BtHtb6k6mviiNJas8kRD14JnAHq5pV+X4GyJUXmz2vuNJCP M9XIesv/Uk+xGmIa9iiTcXJaEQC96oMJIpbag3uJYJRxC6xOruF8tj7VNdCAhnetfV5m t0TFyn87ihtIm2XqR5YD9oL9ZrJX0cvmKx3oOYgpTsIiRKX/J9sZuhteCDVgFcPyH/SA UuZBcAcuNx1fuqzwBGJF1aRcaz36ZrPJp3iaVnZncy/XvG9uOaOEOsh4ctG9nzdQLDXi SSS5RbCq7xlL6NZYv070iwUrihOctz9c7MvtjQQqfu8MmFBCaArVmazGiWX1hMViSEEh DLww== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=BnMf7PqmxoE/KVCNHjOfyhD0Bs8qlF6M7TFRP/l+vs4=; b=ZNq0Lp5/gX9xKMCt5/vMVI+Nr7twHCUGuq4zuv13Xf1n124Ju5mhBDWQqL6jKeUKfZ hi2U8upLMWakckH1tvfkzlR4M1ysuRmymDIONiDI4RQugo2y9VBTN0NNLSusuutsFmWV HfotXgPwpDuihkA+OhFsqUrPBe9/FDL+tDBGbBk229twHDlUwEKSuDICKqRS7lxjxVbp OkEcEtmKf9YwSqjyxU70/9GnMHKVgdwGxB4vn1bXLwmx0kGV8vGcEuj8ow3cmQcUKUxt tolhwQBYXQg79xv9rHTiB7N3xPGVYs/45L+loUMWjJHV29Oji372ZHs/odgpRNsOabbK i86w== X-Gm-Message-State: AOAM531S4w+pOxucpiTxildEkgdF1RUNxSjG0Ej5cTRWsMGXpG9ProiD DpcsUDN4ZIT8Z/nyFRIRrVmo5GMUe6yuFbitInI= X-Google-Smtp-Source: ABdhPJxPJbDYvycJh+wrVh80JuDNxANfiUtbh8jmm8sryclDpwaYSdODRzTtn/wcGBNl6wLLQZ/uINVVsDj9OFU7i2E= X-Received: by 2002:a05:6e02:1a4f:: with SMTP id u15mr2203209ilv.251.1630750664336; Sat, 04 Sep 2021 03:17:44 -0700 (PDT) MIME-Version: 1.0 References: <1625231891-2963-1-git-send-email-fengchengwen@huawei.com> <20210904101027.43252-1-fengchengwen@huawei.com> <20210904101027.43252-6-fengchengwen@huawei.com> In-Reply-To: <20210904101027.43252-6-fengchengwen@huawei.com> From: Jerin Jacob Date: Sat, 4 Sep 2021 15:47:17 +0530 Message-ID: To: Chengwen Feng Cc: Thomas Monjalon , Ferruh Yigit , "Richardson, Bruce" , Jerin Jacob , Andrew Rybchenko , dpdk-dev , =?UTF-8?Q?Morten_Br=C3=B8rup?= , Nipun Gupta , Hemant Agrawal , Maxime Coquelin , Honnappa Nagarahalli , David Marchand , Satananda Burla , Prasun Kapoor , "Ananyev, Konstantin" , "Walsh, Conor" , "Laatz, Kevin" Content-Type: text/plain; charset="UTF-8" Subject: Re: [dpdk-dev] [PATCH v20 5/7] doc: add DMA device library guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On Sat, Sep 4, 2021 at 3:44 PM Chengwen Feng wrote: > > This patch adds dmadev library guide. > > Signed-off-by: Chengwen Feng > Acked-by: Conor Walsh > Reviewed-by: Kevin Laatz Acked-by: Jerin Jacob > --- > 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 > 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 @@ > + > + > + > + > + > + > + + 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"> > + + 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" /> > + + id="defs931"> > + + x="342.43954" > + y="106.56832" > + width="58.257381" > + height="137.82834" > + id="rect17873" /> > + > + + inkscape:label="Layer 1" > + inkscape:groupmode="layer" > + id="layer1" > + transform="translate(-0.13857517,-21.527306)"> > + + 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" /> > + + 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)"> + x="54.136707" > + y="18.045568" > + id="tspan1045">virtual DMA + x="54.136707" > + y="26.865018" > + id="tspan1047">channel > + + 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" /> > + + 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)"> + x="54.136707" > + y="18.045568" > + id="tspan1049">virtual DMA + x="54.136707" > + y="26.865018" > + id="tspan1051">channel > + + 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" /> > + + 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)"> + x="54.136707" > + y="18.045568" > + id="tspan1053">virtual DMA + x="54.136707" > + y="26.865018" > + id="tspan1055">channel > + + 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" /> > + + 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" /> > + + 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)"> + x="54.136707" > + y="18.045568" > + id="tspan1057">dmadev > + + 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" /> > + + 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)"> + x="54.136707" > + y="18.045568" > + id="tspan1059">hardware DMA + x="54.136707" > + y="26.865018" > + id="tspan1061">channel > + + 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" /> > + + 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)"> + x="54.136707" > + y="18.045568" > + id="tspan1063">hardware DMA + x="54.136707" > + y="26.865018" > + id="tspan1065">channel > + + 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" /> > + + 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)"> + x="54.136707" > + y="18.045568" > + id="tspan1067">hardware DMA + x="54.136707" > + y="26.865018" > + id="tspan1069">controller > + + 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" /> > + + 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)"> + x="54.136707" > + y="18.045568" > + id="tspan1071">dmadev > + + 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" /> > + + 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" /> > + + 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" /> > + + 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" /> > + + 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" /> > + + 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" /> > + + 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" /> > + > + > 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 >