|SUCCESS| ring: fix zero-copy burst API documentation

[dpdklab at iol.unh.edu]

Test-Label: ai-code-review
Test-Status: SUCCESS
https://dpdk.org/patch/164136

_AI Code Review_

=== Patch Review: series.patch (via Claude) ===
Review date: 2026-05-19

Reviewing the patch for DPDK coding standards and guidelines compliance.

Git SHA: 47bec9a5ca9f
Author: jinzhiguang <jinzhiguang at kylinos.cn>
Subject: [PATCH] ring: fix zero-copy burst API documentation

This patch updates the documentation for the ring zero-copy burst APIs to
clarify that they return the actual number of objects processed rather
than "either 0 or n". This better reflects the RTE_RING_QUEUE_VARIABLE
behavior.

> diff --git a/.mailmap b/.mailmap
> index 4d26d9c286..a4f91f2131 100644
> --- a/.mailmap
> +++ b/.mailmap
> @@ -756,6 +756,7 @@ Jing Chen <jing.d.chen at intel.com>
>  Jingguo Fu <jingguox.fu at intel.com>
>  Jingjing Wu <jingjing.wu at intel.com>
>  Jingzhao Ni <jingzhao.ni at arm.com>
> +jinzhiguang <jinzhiguang at kylinos.cn>
>  Jiri Slaby <jslaby at suse.cz>
>  Job Abraham <job.abraham at intel.com>
>  Jochen Behrens <jochen.behrens at broadcom.com> <jbehrens at 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.
>   */

Does this documentation accurately describe what
rte_ring_enqueue_zc_burst_elem_start() returns? The function name
includes "_start" suggesting it begins an operation rather than
completing it. Looking at the zero-copy pattern, doesn't this function
only reserve space and return the number of objects that *can be*
enqueued, while the actual enqueue happens when the caller copies data
and calls the corresponding finish function?

The same concern applies to all four modified return value descriptions.
Are these functions actually enqueuing/dequeuing objects, or are they
just starting the zero-copy operation by reserving space?

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