Apart from the comment for the last_idx field, I think the others also
need to be updated.
Based on your v2, I have refreshed the comments for these two functions.
/**
* Return the number of operations that have completed successfully,
* starting from the current ring position.
*
* This function reports a contiguous run of successfully completed
* operations. It stops at the first operation that either failed or
* has not yet completed. Once an operation is reported as successfully
* completed, the results of that operation are visible to all cores
* on the system.
*
* @param dev_id
* The identifier of the device.
* @param vchan
* The identifier of the virtual DMA channel.
* @param nb_cpls
* The maximum number of completed operations to report.
* @param[out] last_idx
* The ring_idx of the last successfully completed operation reported
* by this call. The function stops at the first failed or incomplete
* operation, and reports at most nb_cpls operations, so this may not
* be the last successful operation the device has actually completed.
* If not required, NULL can be passed in.
* @param[out] has_error
* When set to true, a failed operation was encountered among the
* completed operations on the device (within the nb_cpls limit),
* causing the function to stop early. The returned count covers
* only the successful completions preceding that first failure.
* When false, all operations reported by this call succeeded;
* the function stopped either because nb_cpls operations have been
* reported, or because no more completed operations are available on
* the device.
* If not required, NULL can be passed in.
*
* @return
* The number of operations that successfully completed. This
* return value is less than or equal to the value of nb_cpls.
*/
static inline uint16_t
rte_dma_completed(int16_t dev_id, uint16_t vchan, const uint16_t nb_cpls,
uint16_t *last_idx, bool *has_error)
/**
* Return the number of operations that have completed (successfully
* or with error), starting from the current ring position.
*
* This function reports all completed operations up to nb_cpls,
* regardless of whether each individual operation succeeded or
* failed. Once an operation has been reported as completed
* successfully, the results of that operation are visible to all
* cores on the system.
*
* @param dev_id
* The identifier of the device.
* @param vchan
* The identifier of the virtual DMA channel.
* @param nb_cpls
* The size of the status array, i.e. the maximum number of
* completed operations to report.
* @param[out] last_idx
* The ring_idx of the last completed operation reported by this
* call, whether successful or failed. The function reports up to
* nb_cpls completed operations without stopping on errors, so this
* may not be the last operation the device has actually completed.
* If not required, NULL can be passed in.
* @param[out] status
* Pointer to an array of length 'nb_cpls' that receives the
* completion status code of each reported operation.
* @see enum rte_dma_status_code
*
* @return
* The number of operations that completed. This return value is
* less than or equal to the value of nb_cpls.
* If this number is n (n > 0), the first n entries in the status
* array are valid.
*/
static inline uint16_t
rte_dma_completed_status(int16_t dev_id, uint16_t vchan,
const uint16_t nb_cpls, uint16_t *last_idx,
enum rte_dma_status_code *status)
You can send a v3 version based on this.
Thanks
On 7/15/2026 2:06 PM, 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.
>
> In both cases only up to nb_cpls operations are reported per call, so
> last_idx is the ring_idx of the last reported operation, which may not
> be the last operation the device has actually completed.
>
> Clarify both descriptions to remove the ambiguity.
>
> Fixes: 91e581e5c924 ("dmadev: add data plane API")
>
> Signed-off-by: Raghavendra Ningoji <[email protected]>
> ---
> v2:
> - Clarify (per Bruce Richardson) that last_idx is the ring_idx of the
> last operation reported by the call, bounded by nb_cpls, which may not
> be the last operation the device has actually completed.
>
> lib/dmadev/rte_dmadev.h | 9 +++++++--
> 1 file changed, 7 insertions(+), 2 deletions(-)
>
> diff --git a/lib/dmadev/rte_dmadev.h b/lib/dmadev/rte_dmadev.h
> index 81dfe187e2..76b0dd6a1b 100644
> --- a/lib/dmadev/rte_dmadev.h
> +++ b/lib/dmadev/rte_dmadev.h
> @@ -1338,7 +1338,9 @@ 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 ring_idx of the last successfully completed operation reported by
> + * this call (at most nb_cpls operations are reported, so this may not be
> + * the last operation the device has actually completed).
> * If not required, NULL can be passed in.
> * @param[out] has_error
> * Indicates if there are transfer error.
> @@ -1397,7 +1399,10 @@ 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 ring_idx of the last operation reported by this call, regardless of
> + * whether it completed successfully or with an error (at most nb_cpls
> + * operations are reported, so this may not be the last operation the
> + * device has actually completed).
> * 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
