From 436e82b78c471f08769cebbdf0abce243063c24f Mon Sep 17 00:00:00 2001 From: Robert Sanford Date: Wed, 22 Dec 2021 11:20:18 -0500 Subject: [PATCH] ring: update ring size doxygen comments MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit - 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 Acked-by: Morten Brørup Acked-by: Bruce Richardson Acked-by: Konstantin Ananyev --- 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 da17ed6d7c..ab6b4244c8 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 4bd016c110..fb1edc9aad 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.20.1