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 406BAA04B5; Tue, 27 Oct 2020 15:11:58 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 25233592C; Tue, 27 Oct 2020 15:11:57 +0100 (CET) Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) by dpdk.org (Postfix) with ESMTP id C820C5A0F for ; Tue, 27 Oct 2020 15:11:54 +0100 (CET) IronPort-SDR: 4YxySGlfZcR1qRM0F9VNdggaAfeT9hkAV5zuaJSOr8rSySg/WA97AVt1CKLoGum8yN3dMb5osl 4F7QMI0jlLtg== X-IronPort-AV: E=McAfee;i="6000,8403,9786"; a="185831039" X-IronPort-AV: E=Sophos;i="5.77,424,1596524400"; d="scan'208";a="185831039" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga003.fm.intel.com ([10.253.24.29]) by fmsmga101.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 27 Oct 2020 07:11:52 -0700 IronPort-SDR: 4B7Jj8B/VcKb3IWTM6ZKBc+vA76zDvk0b+rup9CMy7qz1dI/GGA+NbqK7TAu7AoQxNHozhZODU l6Y5RY4Rsw5A== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.77,424,1596524400"; d="scan'208";a="360755531" Received: from fmsmsx605.amr.corp.intel.com ([10.18.126.85]) by FMSMGA003.fm.intel.com with ESMTP; 27 Oct 2020 07:11:52 -0700 Received: from fmsmsx607.amr.corp.intel.com (10.18.126.87) by fmsmsx605.amr.corp.intel.com (10.18.126.85) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.1713.5; Tue, 27 Oct 2020 07:11:52 -0700 Received: from fmsmsx604.amr.corp.intel.com (10.18.126.84) by fmsmsx607.amr.corp.intel.com (10.18.126.87) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.1713.5; Tue, 27 Oct 2020 07:11:51 -0700 Received: from fmsedg602.ED.cps.intel.com (10.1.192.136) by fmsmsx604.amr.corp.intel.com (10.18.126.84) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id 15.1.1713.5 via Frontend Transport; Tue, 27 Oct 2020 07:11:51 -0700 Received: from NAM11-CO1-obe.outbound.protection.outlook.com (104.47.56.168) by edgegateway.intel.com (192.55.55.71) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.1.1713.5; Tue, 27 Oct 2020 07:11:51 -0700 ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Z2PW/KC80FtXeSTP0lUAbe7alNZFVHTtLg9lChHmEXEeQoUgjubmTZ+EyjVFq5V5oYY44cZgPKNTJbi8YxMnbLLtoPZQK/Qf/KY1nYu7zOuyphpJ+10cTZCMlr7f4AETZAOiK41UGmOXpm8ojy0XSgskhfKBk0zqaPG/VAEfTvR2gqcVNgBbp6ouQX2MGOYam6v2dW8Xt/IkCq3zc+TkzAzre1vmfyZLXuu+ODs/mvaBkvcr3ZinYzlVh6L0I+l4OWaofN+cd8icqLR2VKi2LZw7WyS0+rwLXI0vBsBIgkVZdjPp7qvD9QX8nzmLBqMPEfHpg37YdoP2YP0O63a+NA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=o9zSKozX3JmJH2Xk2yEjzkqbr6bMABFMETqfSTe8AEA=; b=kqsxB7GkxVfRKb8OsQI58h4I7plORYca/W9W200ET5IgUKquW6UhiepOr6BFNZ0yYooTinXPWlNrX+QRFM5LXtAOEtb74KoPPe6iRZz2g4XTfosPGpHqmo3FJ/ceqBwdjTFKuxmtU2GJLB3OIsoZFpjKnU2u8NPZaNqcM2RGc2ZIIdf9boV5DSMmlZdwyOPM6Pm49wY4OlPuHotQA6CKdnUuztFaWR5NrAKgJ6e+P0NTE18kRzg35rc/cLXn/vaBOdXhh5d57yIdT/GAZJRoFcWnx/kaS2kkIUqwBsqvq4Z1LKZfMfGMueZmOTjJP2Zavl8nln9vWqqTNPe34ZMbQw== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=intel.com; dmarc=pass action=none header.from=intel.com; dkim=pass header.d=intel.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=intel.onmicrosoft.com; s=selector2-intel-onmicrosoft-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=o9zSKozX3JmJH2Xk2yEjzkqbr6bMABFMETqfSTe8AEA=; b=gBHPkRQwYEq1Fr7RwjPPd2jWZqwUuVZOB8LTcUusJl8YcHXLys9OwWQNtAiZg09v2mlfqyAeVfjKa+Uw0AIbR+xi+J5IrpWxqK8UZxjeyhEpFS71FNKBkSEL8K+5KptdKwsfGHEcu9N1SdmO2TdOjGTqHnKR13SsATgpcXngkwM= Received: from BYAPR11MB3301.namprd11.prod.outlook.com (2603:10b6:a03:7f::26) by SJ0PR11MB5039.namprd11.prod.outlook.com (2603:10b6:a03:2da::22) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3499.18; Tue, 27 Oct 2020 14:11:51 +0000 Received: from BYAPR11MB3301.namprd11.prod.outlook.com ([fe80::f5a4:3f6b:ade3:296b]) by BYAPR11MB3301.namprd11.prod.outlook.com ([fe80::f5a4:3f6b:ade3:296b%3]) with mapi id 15.20.3499.018; Tue, 27 Oct 2020 14:11:50 +0000 From: "Ananyev, Konstantin" To: Honnappa Nagarahalli , "dev@dpdk.org" , "stephen@networkplumber.org" CC: "dharmik.thakkar@arm.com" , "ruifeng.wang@arm.com" , "olivier.matz@6wind.com" , "david.marchand@redhat.com" , "nd@arm.com" Thread-Topic: [PATCH v5 5/8] doc/ring: add zero copy peek APIs Thread-Index: AQHWqpIxnDmv4iydjk+X2llNcS5+e6mrgQJQ Date: Tue, 27 Oct 2020 14:11:50 +0000 Message-ID: References: <20200224203931.21256-1-honnappa.nagarahalli@arm.com> <20201025054556.14277-1-honnappa.nagarahalli@arm.com> <20201025054556.14277-6-honnappa.nagarahalli@arm.com> In-Reply-To: <20201025054556.14277-6-honnappa.nagarahalli@arm.com> Accept-Language: en-GB, en-US Content-Language: en-US X-MS-Has-Attach: X-MS-TNEF-Correlator: dlp-product: dlpe-windows dlp-reaction: no-action dlp-version: 11.5.1.3 authentication-results: arm.com; dkim=none (message not signed) header.d=none;arm.com; dmarc=none action=none header.from=intel.com; x-originating-ip: [46.7.39.127] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: d17773de-76f7-43e2-ee90-08d87a823feb x-ms-traffictypediagnostic: SJ0PR11MB5039: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:7219; x-ms-exchange-senderadcheck: 1 x-microsoft-antispam: BCL:0; x-microsoft-antispam-message-info: JP9nibi6ISyal8E3aZF9zkPofm2JMxIeuDgzNwpjFjSb1Rq83siLipyTNlVayx8yc/avBB67xkKR4CfInFj6uAsPW/U6ijdHmuwSttqvVbK4sHCQrlOXWo3S5/NSf2lFhK1+g9FkQ88Sjpt7afSONGtLJSZWI7YNmzvhvtod+/G/S3rz0Cs2vAIluvRUOROOcClYV+9NLk9uGjhS1qRiqQG5D1UccFE/ub/bQG+5uGk5MMCs52YZ8sV0FKNTOGp0LO37cDthNOWoYeUg2ee4c5TFpHKxjSMwaq5Sj9qkcPNw8JbkaVcq8/V1tbiEVEhJ x-forefront-antispam-report: CIP:255.255.255.255; CTRY:; LANG:en; SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:BYAPR11MB3301.namprd11.prod.outlook.com; PTR:; CAT:NONE; SFS:(4636009)(396003)(366004)(136003)(39860400002)(376002)(346002)(5660300002)(2906002)(76116006)(9686003)(8676002)(66476007)(26005)(8936002)(66946007)(66556008)(186003)(6506007)(64756008)(66446008)(83380400001)(7696005)(4326008)(71200400001)(52536014)(110136005)(86362001)(478600001)(54906003)(33656002)(316002)(55016002); DIR:OUT; SFP:1102; x-ms-exchange-antispam-messagedata: 96sITXqcIWA9I338catAxeQs5x43g5ZupwZkLtNhua+XyJKNSEXoRAeDknYS+gPm0vI0vsBIptg9PcezJnU7CsexqtDk8I7T45F1D0u5I8rWFvrEQB9oY3zvDlbzhVN4CwZkboKBXuQdbiKskODTOYGL1K3mNMrzEyZCwfgwiWMy57m0QJc2hjEE3bAqqKTFJ7d/+HAOT02HXlLOr7xmF119tZQSxaqSAVmpw4PQBHlU2I1OD8CUsRMZLDxng7BPhmLHwAdP4qKLDAwPN5PzN68HWSc4VpnpDPllzwGFT99WnpRw0Em8TM/WITz7gEd8dj9GbjoYDHNLCReDsuaKHm9JKNsj+bO3bFpiKTkv2LssNzR3i0e+IBk0+Gwsb3lPYbf+Q5eimsGmq3we/8alet9jo4hMLBJyf6a+iL0MJ+t9UrhKXDfY5QleveZRaNb7H8lHQIol94o6qMSChzcp9Pp7mKlrZ3YL09CNwL0tM9uMxyL6jFZH1F7VzoECTYEBxO0ziUTX02iXCksCuJbiCssnXyUy0UWOza9ak2AP/5fGTFinn6Rt90WmGgUZikNVqCszGSGKUhQPSyGY8AcyLdQEDsmhFr3+8AqYIGkXSqN39uA8mC+JvTqw7elj+yCkBHLEGnbNX5XX6785xd89qg== x-ms-exchange-transport-forked: True Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 X-MS-Exchange-CrossTenant-AuthAs: Internal X-MS-Exchange-CrossTenant-AuthSource: BYAPR11MB3301.namprd11.prod.outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: d17773de-76f7-43e2-ee90-08d87a823feb X-MS-Exchange-CrossTenant-originalarrivaltime: 27 Oct 2020 14:11:50.8489 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 46c98d88-e344-4ed4-8496-4ed7712e255d X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: Hj8PIJL8u+rT0fay6hc65iJvha2TYlm6doyO3Z+LANXL52ZqLLRIf68QKD1rUH0kByPgpaFy2xT+y08SivGHVQrOecbqN5DT8HZxr+x5opQ= X-MS-Exchange-Transport-CrossTenantHeadersStamped: SJ0PR11MB5039 X-OriginatorOrg: intel.com Subject: Re: [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" >=20 > Add zero copy peek API documentation. >=20 > 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(+) >=20 > diff --git a/doc/guides/prog_guide/ring_lib.rst b/doc/guides/prog_guide/r= ing_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 pro= ceed > with enqueue(/dequeue) operation till ``_finish_`` completes. >=20 > +Ring Peek Zero Copy API > +----------------------- > + > +Along with the advantages of the peek APIs, zero copy APIs provide the a= bility > +to copy the data to the ring memory directly without the need for tempor= ary > +storage (for ex: array of mbufs on the stack). > + > +These APIs make it possible to split public enqueue/dequeue API into 3 p= hases: > + > +* 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 mo= des. > +Following is an example of usage: > + > +.. code-block:: c > + > + /* Reserve space on the ring */ > + n =3D rte_ring_enqueue_zc_burst_start(r, 32, &zcd, NULL); > + /* Pkt I/O core polls packets from the NIC */ > + if (n !=3D 0) { > + nb_rx =3D rte_eth_rx_burst(portid, queueid, zcd->ptr1, zcd->n1); > + if (nb_rx =3D=3D zcd->n1 && n !=3D zcd->n1) > + nb_rx =3D 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 proce= ed > +with enqueue(/dequeue) operation till ``_finish_`` completes. > + > References > ---------- >=20 > diff --git a/doc/guides/rel_notes/release_20_11.rst b/doc/guides/rel_note= s/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. > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D >=20 > +* **Added zero copy APIs for rte_ring.** > + > + For rings with producer/consumer in ``RTE_RING_SYNC_ST``, ``RTE_RING_S= YNC_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 tempora= ry > + storage. > + > * **Added write combining store APIs.** >=20 > Added ``rte_write32_wc`` and ``rte_write32_wc_relaxed`` APIs > -- Acked-by: Konstantin Ananyev > 2.17.1