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 55415A034F; Thu, 29 Jul 2021 13:03:15 +0200 (CEST) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 1DE8840DFB; Thu, 29 Jul 2021 13:03:15 +0200 (CEST) Received: from mail-io1-f42.google.com (mail-io1-f42.google.com [209.85.166.42]) by mails.dpdk.org (Postfix) with ESMTP id 841F740687 for ; Thu, 29 Jul 2021 13:03:13 +0200 (CEST) Received: by mail-io1-f42.google.com with SMTP id r6so6542143ioj.8 for ; Thu, 29 Jul 2021 04:03:13 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=IdHhcAKHGRsNH2nnxGtc73lXUW5RvLmQdFSAoRHZIeo=; b=dp7BQx+7iDvQY3uu4EIyn5iNfa9MC/FP9F/gBd2JHdNhUTtQM//D5FyePjel+eCH1e /sUJlDpUNShx6aMZTzp/POUh524b/uuOh3ehTCLeUgcomfy+lPXJQ34gkYckLQ75kMTs uB49Yki0c8qEVY8T2AEvCTTYmbui5cQd5jzIzJWZA5fFF06MIw3wBbqh9/u7Nq486xG/ xAwLqJM7x1c4bhraNcFe5CQ0hzzYWJVXt5o6FhdPSNnA+8SBAeN88wqfWmYBXx5ce8QZ NUyqXLcDPqpPFC3iMBZY4J1zbUNIEYkT61n3WscsUjJDvx2q3T/MyoWJGFmt+V6dthb4 pMMQ== 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=IdHhcAKHGRsNH2nnxGtc73lXUW5RvLmQdFSAoRHZIeo=; b=EYxBFTzMtoMr0ub5o8WG2QDoskgGvyjPT/JScI1hEqQ6e35TjxvTaD52yxNUNF6CUn OFy033dSXZeLKkuOZnwtBuXIRHjuYV27ZoGokVTU7I5D2LWDhLRwT44XUi9rtCUNdHvd 8jhXOXxPhnHLbDWZxBn915nIjRA5sOcsFSMOyooakc5GlQ0kwo+WHbqljR2XY3p1Uwqu 4+IzavDGLHSIN5AN7dxEUdxMc5euPstb01MWUtxiayIla9ic07F3in6zBte+Fde440TH k32WTOTLieMV7J85zUT5ekT8kDF3MPUUiUaugRnltFSsSsJo/0sZPZ3g3W+LdFpVqdQZ njGA== X-Gm-Message-State: AOAM5302dN9eZOl7VouF3KGTgtcTkkMCIV817jT/6iGfuCHN7pCLaSvy vai4dajs3fcAUPCundgs/mGE4v6kLt5ipGl1Skk= X-Google-Smtp-Source: ABdhPJxE2gpkuVeXXCOLvdG7xSqTjhZh7NTNSp1Id0KcpP6veiP5ta63WwYTeU41YwXoYZrRJJjbASj/LsU5gKJJY+A= X-Received: by 2002:a6b:b5ce:: with SMTP id e197mr3606850iof.123.1627556592659; Thu, 29 Jul 2021 04:03:12 -0700 (PDT) MIME-Version: 1.0 References: <1625231891-2963-1-git-send-email-fengchengwen@huawei.com> <1627357200-15291-1-git-send-email-fengchengwen@huawei.com> <1627357200-15291-3-git-send-email-fengchengwen@huawei.com> In-Reply-To: <1627357200-15291-3-git-send-email-fengchengwen@huawei.com> From: Jerin Jacob Date: Thu, 29 Jul 2021 16:32:46 +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" Content-Type: text/plain; charset="UTF-8" Subject: Re: [dpdk-dev] [PATCH v11 2/2] doc: add dmadev 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 Tue, Jul 27, 2021 at 9:13 AM Chengwen Feng wrote: > > This patch adds dmadev library guide. > > Signed-off-by: Chengwen Feng > --- > doc/guides/prog_guide/dmadev.rst | 123 +++++++++++++++++++++++++++++++++++++++ > doc/guides/prog_guide/index.rst | 1 + > 2 files changed, 124 insertions(+) > create mode 100644 doc/guides/prog_guide/dmadev.rst > > diff --git a/doc/guides/prog_guide/dmadev.rst b/doc/guides/prog_guide/dmadev.rst > new file mode 100644 > index 0000000..5bad598 > --- /dev/null > +++ b/doc/guides/prog_guide/dmadev.rst > @@ -0,0 +1,123 @@ > +.. 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 below outlines the model of the DMA framework built on: > + > +.. code-block:: console > + > + +-------------+ +-------------+ +-------------+ > + | virtual DMA | | virtual DMA | | virtual DMA | > + | channel | | channel | | channel | > + +-------------+ +-------------+ +-------------+ > + | | | > + ------------------- | > + | | > + +----------+ +----------+ > + | dmadev | | dmadev | > + +----------+ +----------+ > + | | > + +--------------+ +--------------+ > + | hardware DMA | | hardware DMA | > + | channel | | channel | > + +--------------+ +--------------+ > + | | > + -------------------------------- > + | > + +--------------+ > + | hardware DMA | > + | controller | > + +--------------+ Please change to .svg file. See grep -ri "Inkscape" doc/guides/contributing/documentation.rst for guidelines. > + > + * 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. Looks good. Some other section really useful and it is specific to DMADEV could be added 1) ring_idx management, You can copy the texts from API header file or so 2) rte_dmadev_completed() management. 3) Talk about silent mode too.