From patchwork Fri Jan 31 03:59:28 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 65406 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 3D531A0524; Fri, 31 Jan 2020 04:59:40 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 644101C065; Fri, 31 Jan 2020 04:59:39 +0100 (CET) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by dpdk.org (Postfix) with ESMTP id 48CFD1C043 for ; Fri, 31 Jan 2020 04:59:37 +0100 (CET) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 99AEA31B; Thu, 30 Jan 2020 19:59:36 -0800 (PST) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.14.48]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 8638F3F67D; Thu, 30 Jan 2020 19:59:36 -0800 (PST) From: Honnappa Nagarahalli To: olivier.matz@6wind.com, honnappa.nagarahalli@arm.com Cc: david.marchand@redhat.com, dev@dpdk.org, gavin.hu@arm.com, nd@arm.com Date: Thu, 30 Jan 2020 21:59:28 -0600 Message-Id: <20200131035929.2576-1-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 Subject: [dpdk-dev] [PATCH 1/2] lib/ring: fix documentation for rte_ring_xxx_elem apis X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Correct the documentation for obj_table in rte_ring_xxx_elem APIs. Fixes: cc4b218790f6 ("ring: support configurable element size") Signed-off-by: Honnappa Nagarahalli Reviewed-by: Gavin Hu --- lib/librte_ring/rte_ring_elem.h | 34 ++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/lib/librte_ring/rte_ring_elem.h b/lib/librte_ring/rte_ring_elem.h index 15d79bf2a..50ecc9c3d 100644 --- a/lib/librte_ring/rte_ring_elem.h +++ b/lib/librte_ring/rte_ring_elem.h @@ -392,7 +392,7 @@ dequeue_elems(struct rte_ring *r, uint32_t cons_head, void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects). + * A pointer to a table of objects. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -439,7 +439,7 @@ __rte_ring_do_enqueue_elem(struct rte_ring *r, const void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects). + * A pointer to a table of objects. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -490,7 +490,7 @@ __rte_ring_do_dequeue_elem(struct rte_ring *r, void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects). + * A pointer to a table of objects. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -519,7 +519,7 @@ rte_ring_mp_enqueue_bulk_elem(struct rte_ring *r, const void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects). + * A pointer to a table of objects. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -550,7 +550,7 @@ rte_ring_sp_enqueue_bulk_elem(struct rte_ring *r, const void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects). + * A pointer to a table of objects. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -655,7 +655,7 @@ rte_ring_enqueue_elem(struct rte_ring *r, void *obj, unsigned int esize) * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects) that will be filled. + * A pointer to a table of objects that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -682,7 +682,7 @@ rte_ring_mc_dequeue_bulk_elem(struct rte_ring *r, void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects) that will be filled. + * A pointer to a table of objects that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -714,7 +714,7 @@ rte_ring_sc_dequeue_bulk_elem(struct rte_ring *r, void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects) that will be filled. + * A pointer to a table of objects that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -744,7 +744,7 @@ rte_ring_dequeue_bulk_elem(struct rte_ring *r, void *obj_table, * @param r * A pointer to the ring structure. * @param obj_p - * A pointer to a void * pointer (object) that will be filled. + * A pointer to the object that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -768,7 +768,7 @@ rte_ring_mc_dequeue_elem(struct rte_ring *r, void *obj_p, * @param r * A pointer to the ring structure. * @param obj_p - * A pointer to a void * pointer (object) that will be filled. + * A pointer to the object that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -796,7 +796,7 @@ rte_ring_sc_dequeue_elem(struct rte_ring *r, void *obj_p, * @param r * A pointer to the ring structure. * @param obj_p - * A pointer to a void * pointer (object) that will be filled. + * A pointer to the object that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -822,7 +822,7 @@ rte_ring_dequeue_elem(struct rte_ring *r, void *obj_p, unsigned int esize) * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects). + * A pointer to a table of objects. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -851,7 +851,7 @@ rte_ring_mp_enqueue_burst_elem(struct rte_ring *r, const void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects). + * A pointer to a table of objects. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -882,7 +882,7 @@ rte_ring_sp_enqueue_burst_elem(struct rte_ring *r, const void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects). + * A pointer to a table of objects. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -914,7 +914,7 @@ rte_ring_enqueue_burst_elem(struct rte_ring *r, const void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects) that will be filled. + * A pointer to a table of objects that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -943,7 +943,7 @@ rte_ring_mc_dequeue_burst_elem(struct rte_ring *r, void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects) that will be filled. + * A pointer to a table of objects that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise @@ -974,7 +974,7 @@ rte_ring_sc_dequeue_burst_elem(struct rte_ring *r, void *obj_table, * @param r * A pointer to the ring structure. * @param obj_table - * A pointer to a table of void * pointers (objects) that will be filled. + * A pointer to a table of objects that will be filled. * @param esize * The size of ring element, in bytes. It must be a multiple of 4. * This must be the same value used while creating the ring. Otherwise From patchwork Fri Jan 31 03:59:29 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 65407 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 74EE7A0524; Fri, 31 Jan 2020 04:59:48 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 163101C0B3; Fri, 31 Jan 2020 04:59:43 +0100 (CET) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by dpdk.org (Postfix) with ESMTP id 906931C08C for ; Fri, 31 Jan 2020 04:59:39 +0100 (CET) Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 09FAB31B; Thu, 30 Jan 2020 19:59:39 -0800 (PST) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.14.48]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 020DB3F67D; Thu, 30 Jan 2020 19:59:39 -0800 (PST) From: Honnappa Nagarahalli To: olivier.matz@6wind.com, honnappa.nagarahalli@arm.com Cc: david.marchand@redhat.com, dev@dpdk.org, gavin.hu@arm.com, nd@arm.com Date: Thu, 30 Jan 2020 21:59:29 -0600 Message-Id: <20200131035929.2576-2-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200131035929.2576-1-honnappa.nagarahalli@arm.com> References: <20200131035929.2576-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH 2/2] doc: change prog guide to reflect rte_ring_xxx_elem apis X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Changed the rte_ring chapter in programmer's guide to reflect the addition of rte_ring_xxx_elem APIs. References to pointers as ring elements is changed to generic term 'objects'. Signed-off-by: Honnappa Nagarahalli Reviewed-by: Gavin Hu --- doc/guides/prog_guide/ring_lib.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/doc/guides/prog_guide/ring_lib.rst b/doc/guides/prog_guide/ring_lib.rst index 5a9b6137e..8cb2b2dd4 100644 --- a/doc/guides/prog_guide/ring_lib.rst +++ b/doc/guides/prog_guide/ring_lib.rst @@ -11,7 +11,9 @@ Instead of having a linked list of infinite size, the rte_ring has the following * FIFO -* Maximum size is fixed, the pointers are stored in a table +* Maximum size is fixed, the objects are stored in a table + +* Objects can be pointers or elements of multiple of 4 byte size * Lockless implementation @@ -29,19 +31,19 @@ Instead of having a linked list of infinite size, the rte_ring has the following The advantages of this data structure over a linked list queue are as follows: -* Faster; only requires a single Compare-And-Swap instruction of sizeof(void \*) instead of several double-Compare-And-Swap instructions. +* Faster; only requires a single 32 bit Compare-And-Swap instruction instead of several pointer size Compare-And-Swap instructions. * Simpler than a full lockless queue. * Adapted to bulk enqueue/dequeue operations. - As pointers are stored in a table, a dequeue of several objects will not produce as many cache misses as in a linked queue. + As objects are stored in a table, a dequeue of several objects will not produce as many cache misses as in a linked queue. Also, a bulk dequeue of many objects does not cost more than a dequeue of a simple object. The disadvantages: * Size is fixed -* Having many rings costs more in terms of memory than a linked list queue. An empty ring contains at least N pointers. +* Having many rings costs more in terms of memory than a linked list queue. An empty ring contains at least N objects. A simplified representation of a Ring is shown in with consumer and producer head and tail pointers to objects stored in the data structure. @@ -125,7 +127,7 @@ Enqueue Second Step The second step is to modify *ring->prod_head* in ring structure to point to the same location as prod_next. -A pointer to the added object is copied in the ring (obj4). +The added object is copied in the ring (obj4). .. _figure_ring-enqueue2: @@ -178,7 +180,7 @@ Dequeue Second Step The second step is to modify ring->cons_head in the ring structure to point to the same location as cons_next. -The pointer to the dequeued object (obj1) is copied in the pointer given by the user. +The dequeued object (obj1) is copied in the pointer given by the user. .. _figure_ring-dequeue2: @@ -298,7 +300,7 @@ Modulo 32-bit Indexes In the preceding figures, the prod_head, prod_tail, cons_head and cons_tail indexes are represented by arrows. In the actual implementation, these values are not between 0 and size(ring)-1 as would be assumed. -The indexes are between 0 and 2^32 -1, and we mask their value when we access the pointer table (the ring itself). +The indexes are between 0 and 2^32 -1, and we mask their value when we access the object table (the ring itself). 32-bit modulo also implies that operations on indexes (such as, add/subtract) will automatically do 2^32 modulo if the result overflows the 32-bit number range.