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 2ABF1A034E; Wed, 22 Dec 2021 17:20:55 +0100 (CET) Received: from [217.70.189.124] (localhost [127.0.0.1]) by mails.dpdk.org (Postfix) with ESMTP id A03F940040; Wed, 22 Dec 2021 17:20:54 +0100 (CET) Received: from mail-qt1-f175.google.com (mail-qt1-f175.google.com [209.85.160.175]) by mails.dpdk.org (Postfix) with ESMTP id 61FD24003C for ; Wed, 22 Dec 2021 17:20:53 +0100 (CET) Received: by mail-qt1-f175.google.com with SMTP id q14so2356752qtx.10 for ; Wed, 22 Dec 2021 08:20:53 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:date:message-id; bh=nirkYtraLYweYWl0ePT+stf58JXZuP2XyDjXeqe7VLw=; b=PEBBLEQKIpGNEJ83I1+pBAswpKE57wd3nHkWeXC2vizvBoXBOu63CNh8vR3fyVDyUz y88Ee7WruaFJBji9P8fRAmrGuYOZGoikIf3C8gl8lGRa0tkvFWGNgmQ3bBsFlNx6gPtm 223Kjh6vfXuDmIqcioT9TYPxwS6ERDFaP7tmK8YxhDIxZSIviIedBqzYue0i0Qky+iox BP8zuMf3aYxa87grnEUrgeLanNnw44Fuo6Ilr+SiOHqce95+e7xoV1oWw11uVnyLZAOd x9/1Y10nGNX7gll8iBzXc4TB0Q3z3xY45obtz320ihm1+MPOfCfWdER95rUO49c3aQij vHWA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id; bh=nirkYtraLYweYWl0ePT+stf58JXZuP2XyDjXeqe7VLw=; b=DjeoIlmcQDTwxfGyzmqSHaTrON78CXUFGaDsooBlB+Ah1T5aLRR6+FtteX3E1aIiej qVAkeWLOGt+UR2ZZsvDK2YenWNCxFQkuR7SrhizKtbdge9S1E8EE5DRmE2CsKeJ9iWYU kMWsHBeNepIgByxPSS4E79XeerFYFSsmCNfqXhSR4q0riiC7x0ZgaP+9he8pRjZe+lXs eI5si3E+db25+xzYY/o9WyUg3Sk7ZTejBEfuwFLcu9eS3qldVLLBGJab7oqHuF52RftZ UG1PTb1GdQP2iyVsVzBF+1MzxESk7J10vEt4Uaqft6ygWUytuxtPwYzVm6kw47OaiBg+ Siyw== X-Gm-Message-State: AOAM531k3bwWxbF5jv58cPTeJgI+QggKTYoCJyg4gx7e6qo/bRGHK+9W w6sRs9+iUc6ixg8olBSacfcF4GS0BZewBg== X-Google-Smtp-Source: ABdhPJxYz1nrwOzPPgz8pBZ4Betby7TaqyLHeq1cDC4iuS53/tJ1wWzt2XPyHdBEXbULMk+krI3ERA== X-Received: by 2002:ac8:7fc5:: with SMTP id b5mr2756603qtk.492.1640190052548; Wed, 22 Dec 2021 08:20:52 -0800 (PST) Received: from ubuntu.localdomain (99-153-167-175.lightspeed.ftldfl.sbcglobal.net. [99.153.167.175]) by smtp.gmail.com with ESMTPSA id e20sm2109387qty.14.2021.12.22.08.20.51 (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Wed, 22 Dec 2021 08:20:52 -0800 (PST) From: Robert Sanford X-Google-Original-From: Robert Sanford To: dev@dpdk.org Cc: honnappa.nagarahalli@arm.com, konstantin.ananyev@intel.com Subject: [PATCH] ring: update Doxygen comments re RING_F_EXACT_SZ Date: Wed, 22 Dec 2021 11:20:18 -0500 Message-Id: <1640190018-7025-1-git-send-email-rsanford@akamai.com> X-Mailer: git-send-email 2.7.4 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 - 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 --- 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