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.richard...@intel.com>
> Signed-off-by: Kevin Laatz <kevin.la...@intel.com>
> Reviewed-by: Conor Walsh <conor.wa...@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
