From patchwork Sun Oct 25 05:45:53 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 318958 Delivered-To: patch@linaro.org Received: by 2002:a92:d1d1:0:0:0:0:0 with SMTP id u17csp1695711ilg; Sat, 24 Oct 2020 22:47:57 -0700 (PDT) X-Google-Smtp-Source: ABdhPJx5ZxAP6lUwdGAZ5UBWObwfPduMxdNadRWj89lhQg7UsLOzMpfywCWlEfh91PyTwjMjampu X-Received: by 2002:a17:906:8244:: with SMTP id f4mr10096256ejx.236.1603604877516; Sat, 24 Oct 2020 22:47:57 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1603604877; cv=none; d=google.com; s=arc-20160816; b=EoiETgxYDrxrNJb0C9lafHlnzRDgVtTIw/zeK4ldtKOmbG4C9dXUJ73vv6nsMOPKWv yVqNsBOB1AgfifLb8ceR4OINyn4JfW4r8ZQsp/R+rl//ileSQLTuwHulZP1Rn0KPnPrH p+romQCzIvGt5jEadeCYzwUF/m2thw/lgNktm3OT5mxmXhUzZDsgJB3vp3wOiR1AM9q8 sQILpcz7fGZ/JJPGwRQ4KUxwHuCdRxaCc+nePRFSFH9qW+dlI5ZlLH4xUGx8vJNsSF69 37+54Ssgvlw9AsJo36LT9fbxgd8tqycSquCMAWnh2hR1OV2dqvKRsynFYiv8pU1mLpYT 66vA== 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=4fK7FgJNF+UIso6tVDxvzeZQ7QcuxXimK5+svhNpr3U=; b=B93fqWysJQZp817s1ec13jYw0kek7/uqmd2dWbYLhfekXx7c8W9oWl/wvL1/yuVVed xGVlchtacy/PY4KDTfloZf8YFgft6ap9MyCbLnLEN7y5tFbHYeIBjVfRWJGrVrxM4nLw Pih6NbKDmlg0DTJmY470OmaEFvRlWZFqfVCbIuYlzHzJ4kV96+iH5SqZ7VWfm12BdMGs bbewN7o9utR85WhvFIwt0MxC2cDCyB0CgYPW6HeaHh9zPZ+qFGlY3Hi0QYUUAuR/XYun Sa65U4c/dcQ7a6Y5YnFu/ocE08FaDnhG346K1mvacnCmo58/InWwhMHs3KR4B8SnRzAZ oZcQ== 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; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=arm.com Return-Path: Received: from dpdk.org (dpdk.org. [92.243.14.124]) by mx.google.com with ESMTP id p10si4867007ejy.70.2020.10.24.22.47.57; Sat, 24 Oct 2020 22:47:57 -0700 (PDT) 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; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=arm.com Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id CEA4A2BC7; Sun, 25 Oct 2020 06:46:20 +0100 (CET) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by dpdk.org (Postfix) with ESMTP id 01E352B81 for ; Sun, 25 Oct 2020 06:46:12 +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 6A871143D; Sat, 24 Oct 2020 22:46:10 -0700 (PDT) Received: from qc2400f-1.austin.arm.com (qc2400f-1.austin.arm.com [10.118.12.27]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 5901C3F66B; Sat, 24 Oct 2020 22:46:10 -0700 (PDT) From: Honnappa Nagarahalli To: dev@dpdk.org, honnappa.nagarahalli@arm.com, konstantin.ananyev@intel.com, stephen@networkplumber.org Cc: dharmik.thakkar@arm.com, ruifeng.wang@arm.com, olivier.matz@6wind.com, david.marchand@redhat.com, nd@arm.com Date: Sun, 25 Oct 2020 00:45:53 -0500 Message-Id: <20201025054556.14277-6-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20201025054556.14277-1-honnappa.nagarahalli@arm.com> References: <20200224203931.21256-1-honnappa.nagarahalli@arm.com> <20201025054556.14277-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v5 5/8] doc/ring: add zero copy peek 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" Add zero copy peek API documentation. Signed-off-by: Honnappa Nagarahalli --- doc/guides/prog_guide/ring_lib.rst | 41 ++++++++++++++++++++++++++ doc/guides/rel_notes/release_20_11.rst | 9 ++++++ 2 files changed, 50 insertions(+) -- 2.17.1 Acked-by: Konstantin Ananyev diff --git a/doc/guides/prog_guide/ring_lib.rst b/doc/guides/prog_guide/ring_lib.rst index 895484d95..247646d38 100644 --- a/doc/guides/prog_guide/ring_lib.rst +++ b/doc/guides/prog_guide/ring_lib.rst @@ -452,6 +452,47 @@ selected. As an example of usage: Note that between ``_start_`` and ``_finish_`` none other thread can proceed with enqueue(/dequeue) operation till ``_finish_`` completes. +Ring Peek Zero Copy API +----------------------- + +Along with the advantages of the peek APIs, zero copy APIs provide the ability +to copy the data to the ring memory directly without the need for temporary +storage (for ex: array of mbufs on the stack). + +These APIs make it possible to split public enqueue/dequeue API into 3 phases: + +* enqueue/dequeue start + +* copy data to/from the ring + +* enqueue/dequeue finish + +Note that this API is available only for two sync modes: + +* Single Producer/Single Consumer (SP/SC) + +* Multi-producer/Multi-consumer with Head/Tail Sync (HTS) + +It is a user responsibility to create/init ring with appropriate sync modes. +Following is an example of usage: + +.. code-block:: c + + /* Reserve space on the ring */ + n = rte_ring_enqueue_zc_burst_start(r, 32, &zcd, NULL); + /* Pkt I/O core polls packets from the NIC */ + if (n != 0) { + nb_rx = rte_eth_rx_burst(portid, queueid, zcd->ptr1, zcd->n1); + if (nb_rx == zcd->n1 && n != zcd->n1) + nb_rx = rte_eth_rx_burst(portid, queueid, zcd->ptr2, + n - zcd->n1); + /* Provide packets to the packet processing cores */ + rte_ring_enqueue_zc_finish(r, nb_rx); + } + +Note that between ``_start_`` and ``_finish_`` no other thread can proceed +with enqueue(/dequeue) operation till ``_finish_`` completes. + References ---------- diff --git a/doc/guides/rel_notes/release_20_11.rst b/doc/guides/rel_notes/release_20_11.rst index d8ac359e5..fdc78b3da 100644 --- a/doc/guides/rel_notes/release_20_11.rst +++ b/doc/guides/rel_notes/release_20_11.rst @@ -55,6 +55,15 @@ New Features Also, make sure to start the actual text at the margin. ======================================================= +* **Added zero copy APIs for rte_ring.** + + For rings with producer/consumer in ``RTE_RING_SYNC_ST``, ``RTE_RING_SYNC_MT_HTS`` + modes, these APIs split enqueue/dequeue operation into three phases + (enqueue/dequeue start, copy data to/from ring, enqueue/dequeue finish). + Along with the advantages of the peek APIs, these provide the ability to + copy the data to the ring memory directly without the need for temporary + storage. + * **Added write combining store APIs.** Added ``rte_write32_wc`` and ``rte_write32_wc_relaxed`` APIs