From: "Morten Brørup" <mb@smartsharesystems.com>
To: "Robert Sanford" <rsanford2@gmail.com>, <dev@dpdk.org>
Cc: <honnappa.nagarahalli@arm.com>, <konstantin.ananyev@intel.com>
Subject: RE: [PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ
Date: Wed, 22 Dec 2021 20:17:33 +0100 [thread overview]
Message-ID: <98CBD80474FA8B44BF855DF32C47DC35D86DA3@smartserver.smartshare.dk> (raw)
In-Reply-To: <1640190018-7025-1-git-send-email-rsanford@akamai.com>
> 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>
next prev parent reply other threads:[~2021-12-22 19:17 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-12-22 16:20 Robert Sanford
2021-12-22 19:17 ` Morten Brørup [this message]
2022-01-07 11:50 ` Bruce Richardson
2022-01-10 14:13 ` Ananyev, Konstantin
2022-02-05 17:09 ` David Marchand
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=98CBD80474FA8B44BF855DF32C47DC35D86DA3@smartserver.smartshare.dk \
--to=mb@smartsharesystems.com \
--cc=dev@dpdk.org \
--cc=honnappa.nagarahalli@arm.com \
--cc=konstantin.ananyev@intel.com \
--cc=rsanford2@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).