From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id F0B94A04B5; Sun, 25 Oct 2020 06:47:52 +0100 (CET) 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(+) 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 -- 2.17.1