From patchwork Sat Oct 24 16:11:09 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Honnappa Nagarahalli X-Patchwork-Id: 318948 Delivered-To: patch@linaro.org Received: by 2002:a92:d1d1:0:0:0:0:0 with SMTP id u17csp1344018ilg; Sat, 24 Oct 2020 09:13:35 -0700 (PDT) X-Google-Smtp-Source: ABdhPJz5KDeDQI3o2qH5u2rcXJGqAzRZKQy+3yomJ+ee/tGKTOzXtAitEKIdxPfsmyXg0pgAnFQc X-Received: by 2002:aa7:cacd:: with SMTP id l13mr7617408edt.177.1603556015390; Sat, 24 Oct 2020 09:13:35 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1603556015; cv=none; d=google.com; s=arc-20160816; b=V9PFRwEPJLoiNnHm5YLMvghc3jA54rA5SLRUqGLE82zEXQFk+Mttc9NC2svH47euWR 2K3/Am1Z+bIkAnvQrCNwqlOFIBNy005Z1VfLf0+7zBCVstpVdIpKz0tB0NmPTe5VKe9W CG6oDTTqRTxl9X/lZ0ASrgN9Qtwgupv/5eOGMJMokiTF0naWKKQMzZss7MPgVdPgYZhO Ez4t7H1PDkBHDoY3mMOeh1Lr2sVzj5lIalnPdVv40UurEDa1PAzF5MzMOkhh3iACUpoR VnTd6NlQf79kUSJi2Zvmk9cx0TwRZekBszdvbg176TfSm8QKewymuWUpAvq9IKvGLySh FQKA== 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=l2heutZddgbHFzUzOUpr/NN2ogV7NGsXBnpXuVZv4xn3XyTqgd0Ge/+C1EEPjZUr4Z VGhV/zvDT9vAxWhMfWC7elK0T0bh66xw2bWEgREE5836lONOVLMoEeVqvc12vQ0ntExQ MXINFEh3fkalU7J4sZAcrANVvrQvePdaet2FOFTWdejx1XztjvkLMEqmRIbZnyd7hS8B hgUUza/Nzq9fJQG+3KZgo2lDpbJ7nh/VSKTxhcWAIS4ntaTW2WvMProzKSYdmPx/7T2V 75PSQ3aseH3m0IdXH1LNwHnHP6IrLVOFOnC2eBMQf3MVfMJf5wWTE5P9EPpJuAb+RgwA icpA== 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 d12si4025635ejj.237.2020.10.24.09.13.33; Sat, 24 Oct 2020 09:13:35 -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 9FB9554AE; Sat, 24 Oct 2020 18:11:37 +0200 (CEST) Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by dpdk.org (Postfix) with ESMTP id 85EE729C8 for ; Sat, 24 Oct 2020 18:11:26 +0200 (CEST) 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 483F5142F; Sat, 24 Oct 2020 09:11:26 -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 369BB3F66B; Sat, 24 Oct 2020 09:11:26 -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: Sat, 24 Oct 2020 11:11:09 -0500 Message-Id: <20201024161112.13730-6-honnappa.nagarahalli@arm.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20201024161112.13730-1-honnappa.nagarahalli@arm.com> References: <20200224203931.21256-1-honnappa.nagarahalli@arm.com> <20201024161112.13730-1-honnappa.nagarahalli@arm.com> Subject: [dpdk-dev] [PATCH v4 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 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