> From: Robert Sanford [mailto:rsanfo...@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 <rsanf...@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 <m...@smartsharesystems.com>
