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
--
2.34.1
