[PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ

[PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ

[Robert Sanford]

- Add RING_F_EXACT_SZ description to rte_ring_init and
  rte_ring_create param comments.
- Fix ring size comments.

Signed-off-by: Robert Sanford <rsanford@akamai.com>
---
 lib/ring/rte_ring.h      | 24 ++++++++++++++++++++----
 lib/ring/rte_ring_elem.h |  2 +-
 2 files changed, 21 insertions(+), 5 deletions(-)

diff --git a/lib/ring/rte_ring.h b/lib/ring/rte_ring.h
index da17ed6..ab6b424 100644
--- a/lib/ring/rte_ring.h
+++ b/lib/ring/rte_ring.h
@@ -68,7 +68,7 @@ ssize_t rte_ring_get_memsize(unsigned int count);
  *
  * The ring size is set to *count*, which must be a power of two. Water
  * marking is disabled by default. The real usable ring size is
- * *count-1* instead of *count* to differentiate a free ring from an
+ * *count-1* instead of *count* to differentiate a full ring from an
  * empty ring.
  *
  * The ring is not added in RTE_TAILQ_RING global list. Indeed, the
@@ -80,7 +80,8 @@ ssize_t rte_ring_get_memsize(unsigned int count);
  * @param name
  *   The name of the ring.
  * @param count
- *   The number of elements in the ring (must be a power of 2).
+ *   The number of elements in the ring (must be a power of 2,
+ *   unless RING_F_EXACT_SZ is set in flags).
  * @param flags
  *   An OR of the following:
  *   - One of mutually exclusive flags that define producer behavior:
@@ -107,6 +108,13 @@ ssize_t rte_ring_get_memsize(unsigned int count);
  *        is "multi-consumer HTS mode".
  *     If none of these flags is set, then default "multi-consumer"
  *     behavior is selected.
+ *   - RING_F_EXACT_SZ: If this flag is set, the ring will hold exactly the
+ *     requested number of entries, and the requested size will be rounded up
+ *     to the next power of two, but the usable space will be exactly that
+ *     requested. Worst case, if a power-of-2 size is requested, half the
+ *     ring space will be wasted.
+ *     Without this flag set, the ring size requested must be a power of 2,
+ *     and the usable space will be that size - 1.
  * @return
  *   0 on success, or a negative value on error.
  */
@@ -121,7 +129,7 @@ int rte_ring_init(struct rte_ring *r, const char *name, unsigned int count,
  *
  * The new ring size is set to *count*, which must be a power of
  * two. Water marking is disabled by default. The real usable ring size
- * is *count-1* instead of *count* to differentiate a free ring from an
+ * is *count-1* instead of *count* to differentiate a full ring from an
  * empty ring.
  *
  * The ring is added in RTE_TAILQ_RING list.
@@ -129,7 +137,8 @@ int rte_ring_init(struct rte_ring *r, const char *name, unsigned int count,
  * @param name
  *   The name of the ring.
  * @param count
- *   The size of the ring (must be a power of 2).
+ *   The size of the ring (must be a power of 2,
+ *   unless RING_F_EXACT_SZ is set in flags).
  * @param socket_id
  *   The *socket_id* argument is the socket identifier in case of
  *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
@@ -160,6 +169,13 @@ int rte_ring_init(struct rte_ring *r, const char *name, unsigned int count,
  *        is "multi-consumer HTS mode".
  *     If none of these flags is set, then default "multi-consumer"
  *     behavior is selected.
+ *   - RING_F_EXACT_SZ: If this flag is set, the ring will hold exactly the
+ *     requested number of entries, and the requested size will be rounded up
+ *     to the next power of two, but the usable space will be exactly that
+ *     requested. Worst case, if a power-of-2 size is requested, half the
+ *     ring space will be wasted.
+ *     Without this flag set, the ring size requested must be a power of 2,
+ *     and the usable space will be that size - 1.
  * @return
  *   On success, the pointer to the new allocated ring. NULL on error with
  *    rte_errno set appropriately. Possible errno values include:
diff --git a/lib/ring/rte_ring_elem.h b/lib/ring/rte_ring_elem.h
index 4bd016c..fb1edc9 100644
--- a/lib/ring/rte_ring_elem.h
+++ b/lib/ring/rte_ring_elem.h
@@ -51,7 +51,7 @@ ssize_t rte_ring_get_memsize_elem(unsigned int esize, unsigned int count);
  *
  * The new ring size is set to *count*, which must be a power of
  * two. Water marking is disabled by default. The real usable ring size
- * is *count-1* instead of *count* to differentiate a free ring from an
+ * is *count-1* instead of *count* to differentiate a full ring from an
  * empty ring.
  *
  * The ring is added in RTE_TAILQ_RING list.
-- 
2.7.4

RE: [PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ

[Morten Brørup]

> From: Robert Sanford [mailto:rsanford2@gmail.com]
> Sent: Wednesday, 22 December 2021 17.20
> 
> - Add RING_F_EXACT_SZ description to rte_ring_init and
>   rte_ring_create param comments.
> - Fix ring size comments.
> 
> Signed-off-by: Robert Sanford <rsanford@akamai.com>
> ---
>  lib/ring/rte_ring.h      | 24 ++++++++++++++++++++----
>  lib/ring/rte_ring_elem.h |  2 +-
>  2 files changed, 21 insertions(+), 5 deletions(-)
> 
> diff --git a/lib/ring/rte_ring.h b/lib/ring/rte_ring.h
> index da17ed6..ab6b424 100644
> --- a/lib/ring/rte_ring.h
> +++ b/lib/ring/rte_ring.h
> @@ -68,7 +68,7 @@ ssize_t rte_ring_get_memsize(unsigned int count);
>   *
>   * The ring size is set to *count*, which must be a power of two.
> Water
>   * marking is disabled by default. The real usable ring size is
> - * *count-1* instead of *count* to differentiate a free ring from an
> + * *count-1* instead of *count* to differentiate a full ring from an
>   * empty ring.
>   *
>   * The ring is not added in RTE_TAILQ_RING global list. Indeed, the
> @@ -80,7 +80,8 @@ ssize_t rte_ring_get_memsize(unsigned int count);
>   * @param name
>   *   The name of the ring.
>   * @param count
> - *   The number of elements in the ring (must be a power of 2).
> + *   The number of elements in the ring (must be a power of 2,
> + *   unless RING_F_EXACT_SZ is set in flags).
>   * @param flags
>   *   An OR of the following:
>   *   - One of mutually exclusive flags that define producer behavior:
> @@ -107,6 +108,13 @@ ssize_t rte_ring_get_memsize(unsigned int count);
>   *        is "multi-consumer HTS mode".
>   *     If none of these flags is set, then default "multi-consumer"
>   *     behavior is selected.
> + *   - RING_F_EXACT_SZ: If this flag is set, the ring will hold
> exactly the
> + *     requested number of entries, and the requested size will be
> rounded up
> + *     to the next power of two, but the usable space will be exactly
> that
> + *     requested. Worst case, if a power-of-2 size is requested, half
> the
> + *     ring space will be wasted.
> + *     Without this flag set, the ring size requested must be a power
> of 2,
> + *     and the usable space will be that size - 1.
>   * @return
>   *   0 on success, or a negative value on error.
>   */
> @@ -121,7 +129,7 @@ int rte_ring_init(struct rte_ring *r, const char
> *name, unsigned int count,
>   *
>   * The new ring size is set to *count*, which must be a power of
>   * two. Water marking is disabled by default. The real usable ring
> size
> - * is *count-1* instead of *count* to differentiate a free ring from
> an
> + * is *count-1* instead of *count* to differentiate a full ring from
> an
>   * empty ring.
>   *
>   * The ring is added in RTE_TAILQ_RING list.
> @@ -129,7 +137,8 @@ int rte_ring_init(struct rte_ring *r, const char
> *name, unsigned int count,
>   * @param name
>   *   The name of the ring.
>   * @param count
> - *   The size of the ring (must be a power of 2).
> + *   The size of the ring (must be a power of 2,
> + *   unless RING_F_EXACT_SZ is set in flags).
>   * @param socket_id
>   *   The *socket_id* argument is the socket identifier in case of
>   *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
> @@ -160,6 +169,13 @@ int rte_ring_init(struct rte_ring *r, const char
> *name, unsigned int count,
>   *        is "multi-consumer HTS mode".
>   *     If none of these flags is set, then default "multi-consumer"
>   *     behavior is selected.
> + *   - RING_F_EXACT_SZ: If this flag is set, the ring will hold
> exactly the
> + *     requested number of entries, and the requested size will be
> rounded up
> + *     to the next power of two, but the usable space will be exactly
> that
> + *     requested. Worst case, if a power-of-2 size is requested, half
> the
> + *     ring space will be wasted.
> + *     Without this flag set, the ring size requested must be a power
> of 2,
> + *     and the usable space will be that size - 1.
>   * @return
>   *   On success, the pointer to the new allocated ring. NULL on error
> with
>   *    rte_errno set appropriately. Possible errno values include:
> diff --git a/lib/ring/rte_ring_elem.h b/lib/ring/rte_ring_elem.h
> index 4bd016c..fb1edc9 100644
> --- a/lib/ring/rte_ring_elem.h
> +++ b/lib/ring/rte_ring_elem.h
> @@ -51,7 +51,7 @@ ssize_t rte_ring_get_memsize_elem(unsigned int esize,
> unsigned int count);
>   *
>   * The new ring size is set to *count*, which must be a power of
>   * two. Water marking is disabled by default. The real usable ring
> size
> - * is *count-1* instead of *count* to differentiate a free ring from
> an
> + * is *count-1* instead of *count* to differentiate a full ring from
> an
>   * empty ring.
>   *
>   * The ring is added in RTE_TAILQ_RING list.
> --
> 2.7.4
> 

Acked-by: Morten Brørup <mb@smartsharesystems.com>

Re: [PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ

[Bruce Richardson]

On Wed, Dec 22, 2021 at 11:20:18AM -0500, Robert Sanford wrote:
> - Add RING_F_EXACT_SZ description to rte_ring_init and
>   rte_ring_create param comments.
> - Fix ring size comments.
> 
> Signed-off-by: Robert Sanford <rsanford@akamai.com>
> ---
>  lib/ring/rte_ring.h      | 24 ++++++++++++++++++++----
>  lib/ring/rte_ring_elem.h |  2 +-
>  2 files changed, 21 insertions(+), 5 deletions(-)
> 
Acked-by: Bruce Richardson <bruce.richardson@intel.com>

RE: [PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ

[Ananyev, Konstantin]

> - Add RING_F_EXACT_SZ description to rte_ring_init and
>   rte_ring_create param comments.
> - Fix ring size comments.
> 
> Signed-off-by: Robert Sanford <rsanford@akamai.com>
> ---

Acked-by: Konstantin Ananyev <konstantin.ananyev@intel.com>

> 2.7.4

Re: [PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ

[David Marchand]

On Wed, Dec 22, 2021 at 5:21 PM Robert Sanford <rsanford2@gmail.com> wrote:
>
> - Add RING_F_EXACT_SZ description to rte_ring_init and
>   rte_ring_create param comments.
> - Fix ring size comments.
>
> Signed-off-by: Robert Sanford <rsanford@akamai.com>
Acked-by: Morten Brørup <mb@smartsharesystems.com>
Acked-by: Bruce Richardson <bruce.richardson@intel.com>
Acked-by: Konstantin Ananyev <konstantin.ananyev@intel.com>

Applied, thanks.


-- 
David Marchand