patch 'dmadev: clarify reported completion index' has been queued to stable release 24.11.7

[luca.boccassi at gmail.com]

Hi,

FYI, your patch has been queued to stable release 24.11.7

Note it hasn't been pushed to http://dpdk.org/browse/dpdk-stable yet.
It will be pushed if I get no objections before 07/22/26. So please
shout if anyone has objections.

Also note that after the patch there's a diff of the upstream commit vs the
patch applied to the branch. This will indicate if there was any rebasing
needed to apply to the stable branch. If there were code changes for rebasing
(ie: not only metadata diffs), please double check that the rebase was
correctly done.

Queued patches are on a temporary branch at:
https://github.com/bluca/dpdk-stable

This queued commit can be viewed at:
https://github.com/bluca/dpdk-stable/commit/25ad1008d259ed1afe282167dfe6f5d0a6201dd1

Thanks.

Luca Boccassi

---
>From 25ad1008d259ed1afe282167dfe6f5d0a6201dd1 Mon Sep 17 00:00:00 2001
From: Raghavendra Ningoji <raghavendra.ningoji at amd.com>
Date: Wed, 15 Jul 2026 16:19:34 +0530
Subject: [PATCH] dmadev: clarify reported completion index

[ upstream commit 4756202a474d9862583283ac51db06feada0e89e ]

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.

Refresh the full documentation of both functions to remove the
ambiguity and make the behaviour explicit.

Fixes: 91e581e5c924 ("dmadev: add data plane API")

Signed-off-by: Raghavendra Ningoji <raghavendra.ningoji at amd.com>
Acked-by: Bruce Richardson <bruce.richardson at intel.com>
Reviewed-by: Chengwen Feng <fengchengwen at huawei.com>
---
 .mailmap                |  1 +
 lib/dmadev/rte_dmadev.h | 66 +++++++++++++++++++++++++++--------------
 2 files changed, 45 insertions(+), 22 deletions(-)

diff --git a/.mailmap b/.mailmap
index fb3730ff3a..cf8faee2fc 100644
--- a/.mailmap
+++ b/.mailmap
@@ -1300,6 +1300,7 @@ Radu Bulie <radu-andrei.bulie at nxp.com>
 Radu Nicolau <radu.nicolau at intel.com>
 Rafael Ávila de Espíndola <espindola at scylladb.com>
 Rafal Kozik <rk at semihalf.com>
+Raghavendra Ningoji <raghavendra.ningoji at amd.com>
 Ragothaman Jayaraman <rjayaraman at caviumnetworks.com>
 Rahul Bhansali <rbhansali at marvell.com>
 Rahul Gupta <rahul.gupta at broadcom.com>
diff --git a/lib/dmadev/rte_dmadev.h b/lib/dmadev/rte_dmadev.h
index e2c861530c..b901bb7a0e 100644
--- a/lib/dmadev/rte_dmadev.h
+++ b/lib/dmadev/rte_dmadev.h
@@ -1015,26 +1015,41 @@ rte_dma_submit(int16_t dev_id, uint16_t vchan)
 }
 
 /**
- * Return the number of operations that have been successfully completed.
- * Once an operation has been reported as completed, the results of that
- * operation will be visible to all cores on the system.
+ * 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 virtual DMA channel.
+ *   The identifier of the virtual DMA channel.
  * @param nb_cpls
- *   The maximum number of completed operations that can be processed.
+ *   The maximum number of completed operations to report.
  * @param[out] last_idx
- *   The last completed operation's ring_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
- *   Indicates if there are transfer 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
- *   must be less than or equal to the value of nb_cpls.
+ *   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,
@@ -1074,30 +1089,37 @@ rte_dma_completed(int16_t dev_id, uint16_t vchan, const uint16_t nb_cpls,
 }
 
 /**
- * Return the number of operations that have been completed, and the operations
- * result may succeed or fail.
- * Once an operation has been reported as completed successfully, the results of that
- * operation will be visible to all cores on the system.
+ * 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 virtual DMA channel.
+ *   The identifier of the virtual DMA channel.
  * @param nb_cpls
- *   Indicates the size of status array.
+ *   The size of the status array,
+ *   i.e. the maximum number of completed operations to report.
  * @param[out] last_idx
- *   The last completed operation's ring_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
- *   This is a pointer to an array of length 'nb_cpls' that holds the completion
- *   status code of each operation.
+ *   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 must be less
- *   than or equal to the value of nb_cpls.
- *   If this number is greater than zero (assuming n), then n values in the
- *   status array are also set.
+ *   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,
-- 
2.47.3

---
  Diff of the applied patch vs upstream commit (please double-check if non-empty:
---
--- -	2026-07-20 18:03:26.294251560 +0100
+++ 0021-dmadev-clarify-reported-completion-index.patch	2026-07-20 18:03:25.520443499 +0100
@@ -1 +1 @@
-From 4756202a474d9862583283ac51db06feada0e89e Mon Sep 17 00:00:00 2001
+From 25ad1008d259ed1afe282167dfe6f5d0a6201dd1 Mon Sep 17 00:00:00 2001
@@ -5,0 +6,2 @@
+[ upstream commit 4756202a474d9862583283ac51db06feada0e89e ]
+
@@ -25 +26,0 @@
-Cc: stable at dpdk.org
@@ -36 +37 @@
-index 9e8ca978a8..2c48c9f3df 100644
+index fb3730ff3a..cf8faee2fc 100644
@@ -39 +40 @@
-@@ -1365,6 +1365,7 @@ Radu Bulie <radu-andrei.bulie at nxp.com>
+@@ -1300,6 +1300,7 @@ Radu Bulie <radu-andrei.bulie at nxp.com>
@@ -48 +49 @@
-index 81dfe187e2..8d318b8860 100644
+index e2c861530c..b901bb7a0e 100644
@@ -51 +52 @@
-@@ -1327,26 +1327,41 @@ rte_dma_submit(int16_t dev_id, uint16_t vchan)
+@@ -1015,26 +1015,41 @@ rte_dma_submit(int16_t dev_id, uint16_t vchan)
@@ -102 +103 @@
-@@ -1385,30 +1400,37 @@ rte_dma_completed(int16_t dev_id, uint16_t vchan, const uint16_t nb_cpls,
+@@ -1074,30 +1089,37 @@ rte_dma_completed(int16_t dev_id, uint16_t vchan, const uint16_t nb_cpls,