On Tue, Jul 14, 2026 at 01:19:54PM +0530, Raghavendra Ningoji wrote:
> The last_idx output parameter was documented identically for
> rte_dma_completed() and rte_dma_completed_status(), even though the two
> APIs have different semantics:
>
> - rte_dma_completed() only reports operations that completed
> successfully and stops at the first error, so its last_idx is the
> ring_idx of the last successfully completed operation.
> - rte_dma_completed_status() reports all completed operations regardless
> of status, so its last_idx is the last completed operation's ring_idx
> irrespective of success or failure.
>
> Clarify both descriptions to remove the ambiguity.
>
> Fixes: 91e581e5c924 ("dmadev: add data plane API")
>
> Signed-off-by: Raghavendra Ningoji <[email protected]>
> ---
> lib/dmadev/rte_dmadev.h | 5 +++--
> 1 file changed, 3 insertions(+), 2 deletions(-)
>
> diff --git a/lib/dmadev/rte_dmadev.h b/lib/dmadev/rte_dmadev.h
> index 81dfe187e2..394ee8bfdc 100644
> --- a/lib/dmadev/rte_dmadev.h
> +++ b/lib/dmadev/rte_dmadev.h
> @@ -1338,7 +1338,7 @@ rte_dma_submit(int16_t dev_id, uint16_t vchan)
> * @param nb_cpls
> * The maximum number of completed operations that can be processed.
> * @param[out] last_idx
> - * The last completed operation's ring_idx.
> + * The last successfully completed operation's ring_idx.
> * If not required, NULL can be passed in.
> * @param[out] has_error
> * Indicates if there are transfer error.
> @@ -1397,7 +1397,8 @@ rte_dma_completed(int16_t dev_id, uint16_t vchan, const
> uint16_t nb_cpls,
> * @param nb_cpls
> * Indicates the size of status array.
> * @param[out] last_idx
> - * The last completed operation's ring_idx.
> + * The last completed operation's ring_idx, regardless of whether it
> + * completed successfully or with an error.
Just wondering if completed is ambiguous here. The index is that of the
last reported operation, right? So if we request completed status of e.g.
32 operations, but 64 are actually completed, we only get returned the
index of the 32nd op AFAIK.
/Bruce
> * If not required, NULL can be passed in.
> * @param[out] status
> * This is a pointer to an array of length 'nb_cpls' that holds the
> completion
> --
> 2.34.1
>
