From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124]) by inbox.dpdk.org (Postfix) with ESMTP id 90538A034E; Wed, 22 Dec 2021 20:17:38 +0100 (CET) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id 3928240687; Wed, 22 Dec 2021 20:17:38 +0100 (CET) Received: from smartserver.smartsharesystems.com (smartserver.smartsharesystems.com [77.243.40.215]) by mails.dpdk.org (Postfix) with ESMTP id AB15B4003C for ; Wed, 22 Dec 2021 20:17:37 +0100 (CET) X-MimeOLE: Produced By Microsoft Exchange V6.5 Content-class: urn:content-classes:message MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable Subject: RE: [PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ Date: Wed, 22 Dec 2021 20:17:33 +0100 Message-ID: <98CBD80474FA8B44BF855DF32C47DC35D86DA3@smartserver.smartshare.dk> In-Reply-To: <1640190018-7025-1-git-send-email-rsanford@akamai.com> X-MS-Has-Attach: X-MS-TNEF-Correlator: Thread-Topic: [PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ Thread-Index: Adf3T+cPZJbl4ydPQB2ADrUOXnQCyAAGJX1A References: <1640190018-7025-1-git-send-email-rsanford@akamai.com> From: =?iso-8859-1?Q?Morten_Br=F8rup?= To: "Robert Sanford" , Cc: , X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org > From: Robert Sanford [mailto:rsanford2@gmail.com] > Sent: Wednesday, 22 December 2021 17.20 >=20 > - Add RING_F_EXACT_SZ description to rte_ring_init and > rte_ring_create param comments. > - Fix ring size comments. >=20 > Signed-off-by: Robert Sanford > --- > lib/ring/rte_ring.h | 24 ++++++++++++++++++++---- > lib/ring/rte_ring_elem.h | 2 +- > 2 files changed, 21 insertions(+), 5 deletions(-) >=20 > 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 >=20 Acked-by: Morten Br=F8rup