From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
	by inbox.dpdk.org (Postfix) with ESMTP id 835F9A0548;
	Mon, 20 Sep 2021 12:36:46 +0200 (CEST)
Received: from [217.70.189.124] (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 0178D40DF7;
	Mon, 20 Sep 2021 12:36:46 +0200 (CEST)
Received: from mga17.intel.com (mga17.intel.com [192.55.52.151])
 by mails.dpdk.org (Postfix) with ESMTP id E12CC40DF5
 for <dev@dpdk.org>; Mon, 20 Sep 2021 12:36:44 +0200 (CEST)
X-IronPort-AV: E=McAfee;i="6200,9189,10112"; a="203259291"
X-IronPort-AV: E=Sophos;i="5.85,308,1624345200"; d="scan'208";a="203259291"
Received: from fmsmga003.fm.intel.com ([10.253.24.29])
 by fmsmga107.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384;
 20 Sep 2021 03:36:44 -0700
X-IronPort-AV: E=Sophos;i="5.85,308,1624345200"; d="scan'208";a="548654521"
Received: from bricha3-mobl.ger.corp.intel.com ([10.252.17.156])
 by fmsmga003-auth.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-SHA;
 20 Sep 2021 03:36:42 -0700
Date: Mon, 20 Sep 2021 11:36:39 +0100
From: Bruce Richardson <bruce.richardson@intel.com>
To: Kevin Laatz <kevin.laatz@intel.com>
Cc: dev@dpdk.org, fengchengwen@huawei.com, jerinj@marvell.com,
 conor.walsh@intel.com
Message-ID: <YUhkN6c0CgvILJ/H@bricha3-MOBL.ger.corp.intel.com>
References: <20210827172048.558704-1-kevin.laatz@intel.com>
 <20210917152437.3270330-1-kevin.laatz@intel.com>
 <20210917152437.3270330-11-kevin.laatz@intel.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20210917152437.3270330-11-kevin.laatz@intel.com>
Subject: Re: [dpdk-dev] [PATCH v5 10/16] dma/idxd: add data-path job
 completion functions
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org
Sender: "dev" <dev-bounces@dpdk.org>

On Fri, Sep 17, 2021 at 03:24:31PM +0000, Kevin Laatz wrote:
> Add the data path functions for gathering completed operations.
> 
> Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> Signed-off-by: Kevin Laatz <kevin.laatz@intel.com>
> Reviewed-by: Conor Walsh <conor.walsh@intel.com>
> 
> ---
> v2:
>    - fixed typo in docs
>    - add completion status for invalid opcode
> ---
>  doc/guides/dmadevs/idxd.rst      |  32 +++++
>  drivers/dma/idxd/idxd_common.c   | 235 +++++++++++++++++++++++++++++++
>  drivers/dma/idxd/idxd_internal.h |   5 +
>  3 files changed, 272 insertions(+)
> 
> diff --git a/doc/guides/dmadevs/idxd.rst b/doc/guides/dmadevs/idxd.rst
> index 7835461a22..f942a8aa44 100644
> --- a/doc/guides/dmadevs/idxd.rst
> +++ b/doc/guides/dmadevs/idxd.rst
> @@ -209,6 +209,38 @@ device and start the hardware processing of them:
>     }
>     rte_dma_submit(dev_id, vchan);
>  
> +To retrieve information about completed copies, ``rte_dma_completed()`` and
> +``rte_dma_completed_status()`` APIs should be used. ``rte_dma_completed()``
> +will return the number of completed operations, along with the index of the last
> +successful completed operation and whether or not an error was encountered. If an
> +error was encountered, ``rte_dma_completed_status()`` must be used to kick the
> +device off to continue processing operations and also to gather the status of each
> +individual operations which is filled in to the ``status`` array provided as
> +parameter by the application.
> +
> +The following status codes are supported by IDXD:
> +* ``RTE_DMA_STATUS_SUCCESSFUL``: The operation was successful.
> +* ``RTE_DMA_STATUS_INVALID_OPCODE``: The operation failed due to an invalid operation code.
> +* ``RTE_DMA_STATUS_INVALID_LENGTH``: The operation failed due to an invalid data length.
> +* ``RTE_DMA_STATUS_NOT_ATTEMPTED``: The operation was not attempted.
> +* ``RTE_DMA_STATUS_ERROR_UNKNOWN``: The operation failed due to an unspecified error.
> +
> +The following code shows how to retrieve the number of successfully completed
> +copies within a burst and then using ``rte_dma_completed_status()`` to check
> +which operation failed and kick off the device to continue processing operations:
> +
> +.. code-block:: C
> +
> +   enum rte_dma_status_code status[COMP_BURST_SZ];
> +   uint16_t count, idx, status_count;
> +   bool error = 0;
> +
> +   count = rte_dma_completed(dev_id, vchan, COMP_BURST_SZ, &idx, &error);
> +
> +   if (error){
> +      status_count = rte_dma_completed_status(dev_id, vchan, COMP_BURST_SZ, &idx, status);
> +   }
> +
As with some of the other documentation text, it should be checked for
overlap with the dmadev documentation, and merged with that if appropriate.

/Bruce