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: 183023 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp248334ile; Thu, 30 Jan 2020 19:59:41 -0800 (PST) X-Google-Smtp-Source: APXvYqzYYXFfsB83pVcdxQDV3sqB6R+0Us3PyBSW1cHM25btxIFVQLcejIUUqGwAaZMSlutLKmxV X-Received: by 2002:a5d:6b82:: with SMTP id n2mr6871053wrx.153.1580443181199; Thu, 30 Jan 2020 19:59:41 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1580443181; cv=none; d=google.com; s=arc-20160816; b=QVGghpIKL8LzajRuW60joUEA9Fq49yS9Nim53vVUsZw/A6DQO1FvGR7+cF9DPF+Buf v8R0Dgwc0qX7aZCLRJcQhwLqCHPbChc2DCFFuO3aranJG8d6gJN/xcGwj6xwtW5pDzwr DTUQphRiPgsHaZSCsXemLY6AfcaHBsvAKhZ1cw8/viTE7UL86U4o1oOxPH7WcSBZTh+7 3NQwxBgtcOtVHn4jbYZhROfu6SaD1oDim7QFUiPdGPY0Lt856Z5irbJfTYN8zabMYfeE /0K2wONXwSydB07P9kQZVe82TCl0Cfu9U0WSYBXCQa/4IJ83Mrvo3H9Ser5FA47PnvjJ +0Pg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:message-id:date:cc:to :from; bh=CLl1F2TWfHIlh/f5WBjVhD7FXrnmO33rkqol4seJtXU=; b=bB0iu0gttm/RHhi9B3RGCwokLH1CsfUMJYfJjhx/7da3mW9DAQ4t0Oem5SdSJlZbPV OBKZaj+S+kwY+B9iNeJyEXFvmngatu0uFtXhmFt2ig8amsr48oTPSSXbHlElGVF8K4fA vIPIVTrhVEh6z6Wpj26bZfc4HRgbT+QaEAF3le8Cm9QwIlRAk9v3Ds/JkZPnjRfLA9TG Ur9onAaUfzQLR5YtcT3kX4VIo0/YoUFS6n2wm3zoesA/MGZyFlA2q1jc5NmLPSlbpK7F 5PpspgnSey5JmgN9S/Icr6+rDoz8BskoAX3mEwKWNfwQvQkN4/1M0KovmOW/VFe6qfcK pZvw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Return-Path: Received: from dpdk.org (dpdk.org. [92.243.14.124]) by mx.google.com with ESMTP id c9si6577426wrp.501.2020.01.30.19.59.40; Thu, 30 Jan 2020 19:59:41 -0800 (PST) Received-SPF: pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) client-ip=92.243.14.124; Authentication-Results: mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org 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(-) -- 2.17.1 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: 183024 Delivered-To: patch@linaro.org Received: by 2002:a92:1f12:0:0:0:0:0 with SMTP id i18csp248431ile; Thu, 30 Jan 2020 19:59:48 -0800 (PST) X-Google-Smtp-Source: APXvYqwDU35KY6MbACUo0LlbDArSFyNKwi9cT+ixSPiodhHXSvf9Ki95Lug2tiWJYo0RwzmJeNfx X-Received: by 2002:a1c:545d:: with SMTP id p29mr9908864wmi.91.1580443188842; Thu, 30 Jan 2020 19:59:48 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1580443188; cv=none; d=google.com; s=arc-20160816; b=iCI7ohxd+lqpXtmDgFlbMdTQkNc4IK/Wugo2aqXvzlVuR+mxzahCL85akVH0ASfuhw BYv2ugGhLMp94+/IalYBGTuGrL7IplawZAStzXuIpebC4FtOJ9IGwjC5OT+/gdBmsXLE me9yefmi6DyvhjYWuCqO4CamieJ2RcsSBItz0Z7FcuByY2fSuvMsASvHyDTfCFwL3c+9 W0ffCnggzNramD3fGHegbYEK2OmH6H0S1VKFbybPBMR/UbPdGKlTAmcdCYX/I5o1gG/D dQHKtw2ghUV+nHe5QkqAiugHgVnOdAiPmyc/X4w3W/U47xJ4K9ZAzBE+Xg6lL+/sn1bP zsAQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject:references:in-reply-to :message-id:date:cc:to:from; bh=6sZmKHmXh5ppxoITNHHHfv8mvYyqt+1dZBbDtE6g6JE=; b=v37g0bWI3OoU1VZNV8wJTMETbivW4Ox89iAR51cLvVWOH4+uFJpzUN5Lt2tE4FaRmT 79BSvANT+k6iVvb0dh1Brot9AhnG3eaMsEs6tWWDiqux1i6xuqy/95zOZnn/L2N6G2h8 /saOoTePx7Vssadc8mZ4YfXUJD60rg4Rd940Ejf1zQRowx1S2lfONLDYPqdiN0swxycT la/4S38b7XiKRaxEe3OPjonMsDhxUT9ajYKjAJmL19UZADXuMZEF9BVHa9sepV/7TOBM jTG7sxZF51HF1e6m4nVtDd5XvSAg+vUUS0Ue3pXoXEoEWG32wIi4ZsnYeGUCJCoSVCF2 8aNw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org Return-Path: Received: from dpdk.org (dpdk.org. [92.243.14.124]) by mx.google.com with ESMTP id b15si6576694wmd.62.2020.01.30.19.59.48; Thu, 30 Jan 2020 19:59:48 -0800 (PST) Received-SPF: pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) client-ip=92.243.14.124; Authentication-Results: mx.google.com; spf=pass (google.com: domain of dev-bounces@dpdk.org designates 92.243.14.124 as permitted sender) smtp.mailfrom=dev-bounces@dpdk.org 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(-) -- 2.17.1 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.