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.