[PATCH] ring: fix zero-copy burst API documentation

[PATCH] ring: fix zero-copy burst API documentation

[jinzhiguang]

These are burst APIs relying on RTE_RING_QUEUE_VARIABLE behavior, they
operate on a best-effort basis and return the actual number of
objects processed (between 0 and n).

Update description to match implementation.

Fixes: 47bec9a5ca9f ("ring: add zero copy API")

Signed-off-by: jinzhiguang <jinzhiguang@kylinos.cn>
---
Cc: honnappa.nagarahalli@arm.com
Cc: stable@dpdk.org
---
 .mailmap                    | 1 +
 lib/ring/rte_ring_peek_zc.h | 8 ++++----
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/.mailmap b/.mailmap
index 4d26d9c286..a4f91f2131 100644
--- a/.mailmap
+++ b/.mailmap
@@ -756,6 +756,7 @@ Jing Chen <jing.d.chen@intel.com>
 Jingguo Fu <jingguox.fu@intel.com>
 Jingjing Wu <jingjing.wu@intel.com>
 Jingzhao Ni <jingzhao.ni@arm.com>
+jinzhiguang <jinzhiguang@kylinos.cn>
 Jiri Slaby <jslaby@suse.cz>
 Job Abraham <job.abraham@intel.com>
 Jochen Behrens <jochen.behrens@broadcom.com> <jbehrens@vmware.com>
diff --git a/lib/ring/rte_ring_peek_zc.h b/lib/ring/rte_ring_peek_zc.h
index 3254fe0481..fa566e8e0d 100644
--- a/lib/ring/rte_ring_peek_zc.h
+++ b/lib/ring/rte_ring_peek_zc.h
@@ -235,7 +235,7 @@ rte_ring_enqueue_zc_bulk_start(struct rte_ring *r, unsigned int n,
  *   If non-NULL, returns the amount of space in the ring after the
  *   reservation operation has finished.
  * @return
- *   The number of objects that can be enqueued, either 0 or n
+ *   Actual number of objects enqueued.
  */
 static __rte_always_inline unsigned int
 rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
@@ -265,7 +265,7 @@ rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
  *   If non-NULL, returns the amount of space in the ring after the
  *   reservation operation has finished.
  * @return
- *   The number of objects that can be enqueued, either 0 or n.
+ *   Actual number of objects enqueued.
  */
 static __rte_always_inline unsigned int
 rte_ring_enqueue_zc_burst_start(struct rte_ring *r, unsigned int n,
@@ -442,7 +442,7 @@ rte_ring_dequeue_zc_bulk_start(struct rte_ring *r, unsigned int n,
  *   If non-NULL, returns the number of remaining ring entries after the
  *   dequeue has finished.
  * @return
- *   The number of objects that can be dequeued, either 0 or n.
+ *   Actual number of objects dequeued.
  */
 static __rte_always_inline unsigned int
 rte_ring_dequeue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
@@ -471,7 +471,7 @@ rte_ring_dequeue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
  *   If non-NULL, returns the number of remaining ring entries after the
  *   dequeue has finished.
  * @return
- *   The number of objects that can be dequeued, either 0 or n.
+ *   Actual number of objects dequeued.
  */
 static __rte_always_inline unsigned int
 rte_ring_dequeue_zc_burst_start(struct rte_ring *r, unsigned int n,
-- 
2.53.0

RE: [PATCH] ring: fix zero-copy burst API documentation

[Konstantin Ananyev]

> These are burst APIs relying on RTE_RING_QUEUE_VARIABLE behavior, they
> operate on a best-effort basis and return the actual number of
> objects processed (between 0 and n).
> 
> Update description to match implementation.
> 
> Fixes: 47bec9a5ca9f ("ring: add zero copy API")
> 
> Signed-off-by: jinzhiguang <jinzhiguang@kylinos.cn>
> ---
> Cc: honnappa.nagarahalli@arm.com
> Cc: stable@dpdk.org
> ---
>  .mailmap                    | 1 +
>  lib/ring/rte_ring_peek_zc.h | 8 ++++----
>  2 files changed, 5 insertions(+), 4 deletions(-)
> 
> diff --git a/.mailmap b/.mailmap
> index 4d26d9c286..a4f91f2131 100644
> --- a/.mailmap
> +++ b/.mailmap
> @@ -756,6 +756,7 @@ Jing Chen <jing.d.chen@intel.com>
>  Jingguo Fu <jingguox.fu@intel.com>
>  Jingjing Wu <jingjing.wu@intel.com>
>  Jingzhao Ni <jingzhao.ni@arm.com>
> +jinzhiguang <jinzhiguang@kylinos.cn>
>  Jiri Slaby <jslaby@suse.cz>
>  Job Abraham <job.abraham@intel.com>
>  Jochen Behrens <jochen.behrens@broadcom.com> <jbehrens@vmware.com>
> diff --git a/lib/ring/rte_ring_peek_zc.h b/lib/ring/rte_ring_peek_zc.h
> index 3254fe0481..fa566e8e0d 100644
> --- a/lib/ring/rte_ring_peek_zc.h
> +++ b/lib/ring/rte_ring_peek_zc.h
> @@ -235,7 +235,7 @@ rte_ring_enqueue_zc_bulk_start(struct rte_ring *r,
> unsigned int n,
>   *   If non-NULL, returns the amount of space in the ring after the
>   *   reservation operation has finished.
>   * @return
> - *   The number of objects that can be enqueued, either 0 or n
> + *   Actual number of objects enqueued.

Here and in other places, probably better:
The actual number of objects that can be enqueued.
Acked-by: Konstantin Ananyev <konstantin.ananyev@huawei.com>

>   */
>  static __rte_always_inline unsigned int
>  rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
> @@ -265,7 +265,7 @@ rte_ring_enqueue_zc_burst_elem_start(struct rte_ring
> *r, unsigned int esize,
>   *   If non-NULL, returns the amount of space in the ring after the
>   *   reservation operation has finished.
>   * @return
> - *   The number of objects that can be enqueued, either 0 or n.
> + *   Actual number of objects enqueued.
>   */
>  static __rte_always_inline unsigned int
>  rte_ring_enqueue_zc_burst_start(struct rte_ring *r, unsigned int n,
> @@ -442,7 +442,7 @@ rte_ring_dequeue_zc_bulk_start(struct rte_ring *r,
> unsigned int n,
>   *   If non-NULL, returns the number of remaining ring entries after the
>   *   dequeue has finished.
>   * @return
> - *   The number of objects that can be dequeued, either 0 or n.
> + *   Actual number of objects dequeued.
>   */
>  static __rte_always_inline unsigned int
>  rte_ring_dequeue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
> @@ -471,7 +471,7 @@ rte_ring_dequeue_zc_burst_elem_start(struct rte_ring
> *r, unsigned int esize,
>   *   If non-NULL, returns the number of remaining ring entries after the
>   *   dequeue has finished.
>   * @return
> - *   The number of objects that can be dequeued, either 0 or n.
> + *   Actual number of objects dequeued.
>   */
>  static __rte_always_inline unsigned int
>  rte_ring_dequeue_zc_burst_start(struct rte_ring *r, unsigned int n,
> --
> 2.53.0

Re: Re: [PATCH] ring: fix zero-copy burst API documentation

[jinzhiguang]

>> diff --git a/lib/ring/rte_ring_peek_zc.h b/lib/ring/rte_ring_peek_zc.h
>> index 3254fe0481..fa566e8e0d 100644
>> --- a/lib/ring/rte_ring_peek_zc.h
>> +++ b/lib/ring/rte_ring_peek_zc.h
>> @@ -235,7 +235,7 @@ rte_ring_enqueue_zc_bulk_start(struct rte_ring *r,
>> unsigned int n,
>>    *   If non-NULL, returns the amount of space in the ring after the
>>    *   reservation operation has finished.
>>    * @return
>> - *   The number of objects that can be enqueued, either 0 or n
>> + *   Actual number of objects enqueued.
> Here and in other places, probably better:
> The actual number of objects that can be enqueued.
> Acked-by: Konstantin Ananyev <konstantin.ananyev@huawei.com>
Thank you for the review. I will update it and send a v2.
>>    */
>>   static __rte_always_inline unsigned int
>>   rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
>>

[PATCH v3] ring: fix zero-copy burst API documentation

[jinzhiguang]

These are burst APIs relying on RTE_RING_QUEUE_VARIABLE behavior, they
operate on a best-effort basis and return the actual number of
objects processed (between 0 and n).

Update description to match implementation.

Fixes: 47bec9a5ca9f ("ring: add zero copy API")

Acked-by: Konstantin Ananyev <konstantin.ananyev@huawei.com>
Signed-off-by: jinzhiguang <jinzhiguang@kylinos.cn>
---
Cc: honnappa.nagarahalli@arm.com
Cc: stable@dpdk.org
---
V3:
  - Resend properly threaded to the v1 patch. (No code/text changes)
v2:
  - Update description to match actual behavior per Maintainer's suggestion.

 .mailmap                    | 1 +
 lib/ring/rte_ring_peek_zc.h | 8 ++++----
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/.mailmap b/.mailmap
index 4d26d9c286..a4f91f2131 100644
--- a/.mailmap
+++ b/.mailmap
@@ -756,6 +756,7 @@ Jing Chen <jing.d.chen@intel.com>
 Jingguo Fu <jingguox.fu@intel.com>
 Jingjing Wu <jingjing.wu@intel.com>
 Jingzhao Ni <jingzhao.ni@arm.com>
+jinzhiguang <jinzhiguang@kylinos.cn>
 Jiri Slaby <jslaby@suse.cz>
 Job Abraham <job.abraham@intel.com>
 Jochen Behrens <jochen.behrens@broadcom.com> <jbehrens@vmware.com>
diff --git a/lib/ring/rte_ring_peek_zc.h b/lib/ring/rte_ring_peek_zc.h
index 3254fe0481..43d6a53075 100644
--- a/lib/ring/rte_ring_peek_zc.h
+++ b/lib/ring/rte_ring_peek_zc.h
@@ -235,7 +235,7 @@ rte_ring_enqueue_zc_bulk_start(struct rte_ring *r, unsigned int n,
  *   If non-NULL, returns the amount of space in the ring after the
  *   reservation operation has finished.
  * @return
- *   The number of objects that can be enqueued, either 0 or n
+ *   The actual number of objects that can be enqueued.
  */
 static __rte_always_inline unsigned int
 rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
@@ -265,7 +265,7 @@ rte_ring_enqueue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
  *   If non-NULL, returns the amount of space in the ring after the
  *   reservation operation has finished.
  * @return
- *   The number of objects that can be enqueued, either 0 or n.
+ *   The actual number of objects that can be enqueued.
  */
 static __rte_always_inline unsigned int
 rte_ring_enqueue_zc_burst_start(struct rte_ring *r, unsigned int n,
@@ -442,7 +442,7 @@ rte_ring_dequeue_zc_bulk_start(struct rte_ring *r, unsigned int n,
  *   If non-NULL, returns the number of remaining ring entries after the
  *   dequeue has finished.
  * @return
- *   The number of objects that can be dequeued, either 0 or n.
+ *   The actual number of objects that can be dequeued.
  */
 static __rte_always_inline unsigned int
 rte_ring_dequeue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
@@ -471,7 +471,7 @@ rte_ring_dequeue_zc_burst_elem_start(struct rte_ring *r, unsigned int esize,
  *   If non-NULL, returns the number of remaining ring entries after the
  *   dequeue has finished.
  * @return
- *   The number of objects that can be dequeued, either 0 or n.
+ *   The actual number of objects that can be dequeued.
  */
 static __rte_always_inline unsigned int
 rte_ring_dequeue_zc_burst_start(struct rte_ring *r, unsigned int n,
-- 
2.53.0

Re: [PATCH v3] ring: fix zero-copy burst API documentation

[Thomas Monjalon]

19/05/2026 15:38, jinzhiguang:
> --- a/.mailmap
> +++ b/.mailmap
> @@ -756,6 +756,7 @@ Jing Chen <jing.d.chen@intel.com>
>  Jingguo Fu <jingguox.fu@intel.com>
>  Jingjing Wu <jingjing.wu@intel.com>
>  Jingzhao Ni <jingzhao.ni@arm.com>
> +jinzhiguang <jinzhiguang@kylinos.cn>

Maybe you want to insert a space? What is your first name and family name?
Please use capital letters where appropriate.