From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <dev-bounces@dpdk.org>
Received: from mails.dpdk.org (mails.dpdk.org [217.70.189.124])
	by inbox.dpdk.org (Postfix) with ESMTP id B7B2A424F3;
	Mon,  4 Sep 2023 20:11:01 +0200 (CEST)
Received: from mails.dpdk.org (localhost [127.0.0.1])
	by mails.dpdk.org (Postfix) with ESMTP id 6217A402E9;
	Mon,  4 Sep 2023 20:11:01 +0200 (CEST)
Received: from EUR02-AM0-obe.outbound.protection.outlook.com
 (mail-am0eur02on2083.outbound.protection.outlook.com [40.107.247.83])
 by mails.dpdk.org (Postfix) with ESMTP id 8D156402C1
 for <dev@dpdk.org>; Mon,  4 Sep 2023 20:11:00 +0200 (CEST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; 
 s=selector2-armh-onmicrosoft-com;
 h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck;
 bh=eDYCLc4nsY4QvhHnttzknPzFySi/Fc9OUVejx3aXWZg=;
 b=CYl13rGIpT8KcAZC8VvvhGXfSgo8sFJAd2rFEEZ99ZP4O5ziz9N9UGYqPk5V2tPZva2ic3zOuPkp0SBJC0lWo0IqePMMB4lDh6VKseNKCgtNvWMTnlz0TUUOnyoOvSK3xxalJySHY3j3hivoBkfQ6Fe+7ZLNYwIi0EK7QZ8f1N8=
Received: from DUZPR01CA0176.eurprd01.prod.exchangelabs.com
 (2603:10a6:10:4b3::12) by DB5PR08MB9997.eurprd08.prod.outlook.com
 (2603:10a6:10:4a2::22) with Microsoft SMTP Server (version=TLS1_2,
 cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6745.33; Mon, 4 Sep
 2023 18:10:57 +0000
Received: from DBAEUR03FT003.eop-EUR03.prod.protection.outlook.com
 (2603:10a6:10:4b3:cafe::e0) by DUZPR01CA0176.outlook.office365.com
 (2603:10a6:10:4b3::12) with Microsoft SMTP Server (version=TLS1_2,
 cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6745.33 via Frontend
 Transport; Mon, 4 Sep 2023 18:10:57 +0000
X-MS-Exchange-Authentication-Results: spf=pass (sender IP is 63.35.35.123)
 smtp.mailfrom=arm.com; dkim=pass (signature was verified)
 header.d=armh.onmicrosoft.com;dmarc=pass action=none header.from=arm.com;
Received-SPF: Pass (protection.outlook.com: domain of arm.com designates
 63.35.35.123 as permitted sender) receiver=protection.outlook.com;
 client-ip=63.35.35.123; helo=64aa7808-outbound-1.mta.getcheckrecipient.com;
 pr=C
Received: from 64aa7808-outbound-1.mta.getcheckrecipient.com (63.35.35.123) by
 DBAEUR03FT003.mail.protection.outlook.com (100.127.142.89) with
 Microsoft
 SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id
 15.20.6768.25 via Frontend Transport; Mon, 4 Sep 2023 18:10:57 +0000
Received: ("Tessian outbound 0b7d6027328f:v175");
 Mon, 04 Sep 2023 18:10:57 +0000
X-CheckRecipientChecked: true
X-CR-MTA-CID: f74b7a444d82cf3f
X-CR-MTA-TID: 64aa7808
Received: from eeb399264f00.1
 by 64aa7808-outbound-1.mta.getcheckrecipient.com id
 762276B7-7956-4AB4-AD06-6ED31F437C98.1; 
 Mon, 04 Sep 2023 18:10:46 +0000
Received: from EUR02-AM0-obe.outbound.protection.outlook.com
 by 64aa7808-outbound-1.mta.getcheckrecipient.com with ESMTPS id eeb399264f00.1
 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384);
 Mon, 04 Sep 2023 18:10:46 +0000
ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none;
 b=eBBVWSg9bEzJdO55EwFXEKEDMSHHYiVYaqfsXEY2AtDHZfRg5F28MhWcjXfeudI0GzqcCi1DL/Zlv6kK09NphMd5+xWaKD64vuaaAOfcMl23smXsbtvEfu1WsrA9RyVP73TZdFYVAmmyFURZsIYN1e3u1RW9/HEPDc6bVsbm7IpXW80T/6m8uJMeNo+QMPJPLI9OsolBx9WmZ4a32TuLny8IThD6JKGCJlsEBjLBOKd0L/oppedd/nh1hWxdzI3LujozadYp1rPJeMo+t0jVUy5zJ6XcLczEKu5koHx1O1yd7OSM73dy1fEtPQAEr+yV8TZQqD/cMmhOKnPsUySnQw==
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-AntiSpam-MessageData-ChunkCount:X-MS-Exchange-AntiSpam-MessageData-0:X-MS-Exchange-AntiSpam-MessageData-1;
 bh=eDYCLc4nsY4QvhHnttzknPzFySi/Fc9OUVejx3aXWZg=;
 b=lNE3KJWG/GO1QnVSvJ6jmB78UalcxTaLAzzu4RUvCLWOYhVmFNatjPucboyhNvJyDyRGYDfKDlhF41IK2k1LOR87Rflgs40CnosT9yOaxg3pe0p9W/OaRLj/tq2qP9f8m/9rmrKwHeYj2Y43N0Lg6fOP/JDVYvyel7WN/UphZdOGMYDo/r6rLiMHXfhaEDbXSKJSw2NBua0EC/fZcPO6cW8IlmoVTcxWKx62F6H1nrUqbVP8XNiQpfkrgLnfDqC4bhbWW998kRkfP2ZHUWZp2YTGR/a5/BSOjLFOIEg1qft55H55SevGBKpuhMXd4jeQv9TQjR42QHxGDmKs+zpNFg==
ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass
 smtp.mailfrom=arm.com; dmarc=pass action=none header.from=arm.com; dkim=pass
 header.d=arm.com; arc=none
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=armh.onmicrosoft.com; 
 s=selector2-armh-onmicrosoft-com;
 h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck;
 bh=eDYCLc4nsY4QvhHnttzknPzFySi/Fc9OUVejx3aXWZg=;
 b=CYl13rGIpT8KcAZC8VvvhGXfSgo8sFJAd2rFEEZ99ZP4O5ziz9N9UGYqPk5V2tPZva2ic3zOuPkp0SBJC0lWo0IqePMMB4lDh6VKseNKCgtNvWMTnlz0TUUOnyoOvSK3xxalJySHY3j3hivoBkfQ6Fe+7ZLNYwIi0EK7QZ8f1N8=
Received: from DBAPR08MB5814.eurprd08.prod.outlook.com (2603:10a6:10:1b1::6)
 by GV2PR08MB9928.eurprd08.prod.outlook.com (2603:10a6:150:be::10) with
 Microsoft SMTP Server (version=TLS1_2,
 cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.6745.30; Mon, 4 Sep
 2023 18:10:43 +0000
Received: from DBAPR08MB5814.eurprd08.prod.outlook.com
 ([fe80::8f02:b46d:fbae:bae4]) by DBAPR08MB5814.eurprd08.prod.outlook.com
 ([fe80::8f02:b46d:fbae:bae4%4]) with mapi id 15.20.6745.030; Mon, 4 Sep 2023
 18:10:43 +0000
From: Honnappa Nagarahalli <Honnappa.Nagarahalli@arm.com>
To: Konstantin Ananyev <konstantin.ananyev@huawei.com>, "jackmin@nvidia.com"
 <jackmin@nvidia.com>, "konstantin.v.ananyev@yandex.ru"
 <konstantin.v.ananyev@yandex.ru>
CC: "dev@dpdk.org" <dev@dpdk.org>, Ruifeng Wang <Ruifeng.Wang@arm.com>, Aditya
 Ambadipudi <Aditya.Ambadipudi@arm.com>, Wathsala Wathawana Vithanage
 <wathsala.vithanage@arm.com>, nd <nd@arm.com>, nd <nd@arm.com>
Subject: RE: [RFC] lib/st_ring: add single thread ring
Thread-Topic: [RFC] lib/st_ring: add single thread ring
Thread-Index: AQHZ3xhij5UOZIDmtU+IXup+eth44bAK9evA
Date: Mon, 4 Sep 2023 18:10:43 +0000
Message-ID: <DBAPR08MB5814A8BD041D6EBA0AE2EAEC98E9A@DBAPR08MB5814.eurprd08.prod.outlook.com>
References: <20230821060420.3509667-1-honnappa.nagarahalli@arm.com>
 <0273f48a522f4d2f854596e0d7e6d835@huawei.com>
In-Reply-To: <0273f48a522f4d2f854596e0d7e6d835@huawei.com>
Accept-Language: en-US
Content-Language: en-US
X-MS-Has-Attach: 
X-MS-TNEF-Correlator: 
x-ts-tracking-id: 9A9416C546EE304B8CE5068761D6C50B.0
Authentication-Results-Original: dkim=none (message not signed)
 header.d=none;dmarc=none action=none header.from=arm.com;
x-ms-traffictypediagnostic: DBAPR08MB5814:EE_|GV2PR08MB9928:EE_|DBAEUR03FT003:EE_|DB5PR08MB9997:EE_
X-MS-Office365-Filtering-Correlation-Id: 1ce939c3-2875-4c10-f7d3-08dbad72499b
x-checkrecipientrouted: true
nodisclaimer: true
X-MS-Exchange-SenderADCheck: 1
X-MS-Exchange-AntiSpam-Relay: 0
X-Microsoft-Antispam-Untrusted: BCL:0;
X-Microsoft-Antispam-Message-Info-Original: h5TUW+SiDd1u7f/r4wmxWonLDil4CS1ujz1FkTTtPXtmb2qikPTe6I76vRp4Njfn66zc8V69kj+bE7BEQGIdT98o/72BsG9/Ytqmu/osC4PROKxZHhyN4XBoNnQKebYDcNxFB7CZ4YbA1NbRJs4DsFs4sfZ+9bT5d5RpHL56ktISZZY6E0bdzEEG7Qx2tbxbtnVUk8L18ol5t+JOdV+n3JdhTaVy33PrZo3QoJrXwfmxuUbLrBWoZAxtxhrP00YgTSvi4s7QQRtqus/So3BJ3BElbvSNhqd+0mdVcrHFtq4caNDaMhBBlVAbvy0xJbE+ufAko9lTlkqUYoYEdYraCM6jHXUcc9Tox4lTtDkDZq0DAQ3AGlzZb0zU+3pNK+jpXGLZwKMIcwCZomzYzE4uabXxmZW+eM9UVYRDB7QjvXHCl0u3DHfN+1fr+L6EIXoecSLNrIaxq7IlpYMHVgHx4bAebS6wdCI0ShGmKbVSj1LdGn0HQO5hCIHuid+gaic1aAZ8xTpLqxPq/tZQ6JYla3Oi7yZdFDDkTnmSEC7Ue0d6ncGsNOE+Ku1J6EjjRkxzxmbAzM5NDNMre7m32CHYzl0P+33gE3Q27gEjrT3Ip2p6rV3ZmPhpsJRakwZj6ifj8AjtUyH+JBLoV8PE9N8CAQ==
X-Forefront-Antispam-Report-Untrusted: CIP:255.255.255.255; CTRY:; LANG:en;
 SCL:1; SRV:; IPV:NLI; SFV:NSPM; H:DBAPR08MB5814.eurprd08.prod.outlook.com;
 PTR:; CAT:NONE;
 SFS:(13230031)(376002)(396003)(136003)(346002)(39860400002)(366004)(186009)(1800799009)(451199024)(41300700001)(53546011)(71200400001)(122000001)(38100700002)(26005)(33656002)(86362001)(38070700005)(966005)(478600001)(83380400001)(55016003)(7696005)(6506007)(9686003)(8676002)(76116006)(66476007)(66446008)(110136005)(54906003)(66556008)(2906002)(316002)(30864003)(64756008)(66946007)(8936002)(5660300002)(4326008)(52536014)(23180200003)(579004);
 DIR:OUT; SFP:1101; 
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
MIME-Version: 1.0
X-MS-Exchange-Transport-CrossTenantHeadersStamped: GV2PR08MB9928
Original-Authentication-Results: dkim=none (message not signed)
 header.d=none;dmarc=none action=none header.from=arm.com;
X-EOPAttributedMessage: 0
X-MS-Exchange-Transport-CrossTenantHeadersStripped: DBAEUR03FT003.eop-EUR03.prod.protection.outlook.com
X-MS-PublicTrafficType: Email
X-MS-Office365-Filtering-Correlation-Id-Prvs: 13239d22-3e17-41a8-6297-08dbad7240f7
X-Microsoft-Antispam: BCL:0;
X-Microsoft-Antispam-Message-Info: aNWW466/dE2Y/D2C7y3+CcXyWl/Md9YtKhrHx4MeKZQFa7JH2W0ctUKLAFhYuiNTi6dfsiit42cTnFhiN35/XMAlqiLauffJRmx9tM9sYrejLPsmVM3FcX+G9LcGvMqE2QNCeI138++9gJM2wFM+z1f6HNGUSDqwoIYRjfr3V5kGKTsIJrEVi0STUk+aSxak4Q9enW3MhzR9jz6Uj5fOyDTPPAkk3I9Ripy7CV5S2w3cHXhZjc2/QnRj9safYrxnJweDGWsl/dE9RzkBWtU8GaxtfKgVH77ntnoYnLtGNGdLag3u1ts6quuCu+RJZPQRIKeYhhgy/VtgzU6vGlcAsS70WWQIwD6FOGjv+5yeZgYAJTDm0GwAhpxpFT7PC/fS7yjTOd9KNbk1/liRC+b1tWHzSxcVwuaODBfKK/ciHvzMrm9YNktJ4NgGdxqNAu/jyb1M4aH3dnHYCfKMuWTqd9Til2KYwnxbvBOK1C0a9hqvHUkKJFcvtOemhD4OxDwfn2Cd66a8mpdtFFcYss1JN6W5Dg190e2ayFYDmuyVSwY62gf5oVWXX1216LaX7LDNQVXOwAzaAWxnl1xheV7dqNvla/UnF31Lvo0CTk/rqypkIZjH41XVyvThpWys08T1GnQOAuXEdX/H2Gx4XSfHNeCjuJHzes3OUzTytYQHtcEUVYmlKjM4ni/EV4jK0LdFxbd81gHoVOt5EPRTN/UGZS3YPE5Cxv9z9RVluUtFGFOVmWuKVoQUk3Jj3fpaCMUR
X-Forefront-Antispam-Report: CIP:63.35.35.123; CTRY:IE; LANG:en; SCL:1; SRV:;
 IPV:CAL; SFV:NSPM; H:64aa7808-outbound-1.mta.getcheckrecipient.com;
 PTR:ec2-63-35-35-123.eu-west-1.compute.amazonaws.com; CAT:NONE;
 SFS:(13230031)(4636009)(39860400002)(136003)(396003)(346002)(376002)(82310400011)(1800799009)(186009)(451199024)(36840700001)(40470700004)(46966006)(36860700001)(40460700003)(47076005)(2906002)(30864003)(33656002)(86362001)(81166007)(356005)(82740400003)(40480700001)(55016003)(52536014)(4326008)(8936002)(8676002)(26005)(5660300002)(53546011)(110136005)(7696005)(70206006)(41300700001)(9686003)(70586007)(54906003)(316002)(6506007)(336012)(83380400001)(966005)(478600001)(23180200003);
 DIR:OUT; SFP:1101; 
X-OriginatorOrg: arm.com
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 04 Sep 2023 18:10:57.5736 (UTC)
X-MS-Exchange-CrossTenant-Network-Message-Id: 1ce939c3-2875-4c10-f7d3-08dbad72499b
X-MS-Exchange-CrossTenant-Id: f34e5979-57d9-4aaa-ad4d-b122a662184d
X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=f34e5979-57d9-4aaa-ad4d-b122a662184d; Ip=[63.35.35.123];
 Helo=[64aa7808-outbound-1.mta.getcheckrecipient.com]
X-MS-Exchange-CrossTenant-AuthSource: DBAEUR03FT003.eop-EUR03.prod.protection.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Anonymous
X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem
X-MS-Exchange-Transport-CrossTenantHeadersStamped: DB5PR08MB9997
X-BeenThere: dev@dpdk.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: DPDK patches and discussions <dev.dpdk.org>
List-Unsubscribe: <https://mails.dpdk.org/options/dev>,
 <mailto:dev-request@dpdk.org?subject=unsubscribe>
List-Archive: <http://mails.dpdk.org/archives/dev/>
List-Post: <mailto:dev@dpdk.org>
List-Help: <mailto:dev-request@dpdk.org?subject=help>
List-Subscribe: <https://mails.dpdk.org/listinfo/dev>,
 <mailto:dev-request@dpdk.org?subject=subscribe>
Errors-To: dev-bounces@dpdk.org



> -----Original Message-----
> From: Konstantin Ananyev <konstantin.ananyev@huawei.com>
> Sent: Monday, September 4, 2023 5:13 AM
> To: Honnappa Nagarahalli <Honnappa.Nagarahalli@arm.com>;
> jackmin@nvidia.com; konstantin.v.ananyev@yandex.ru
> Cc: dev@dpdk.org; Ruifeng Wang <Ruifeng.Wang@arm.com>; Aditya
> Ambadipudi <Aditya.Ambadipudi@arm.com>; Wathsala Wathawana Vithanage
> <wathsala.vithanage@arm.com>; nd <nd@arm.com>
> Subject: RE: [RFC] lib/st_ring: add single thread ring
>=20
>=20
>=20
> > Add a single thread safe and multi-thread unsafe ring data structure.
> > This library provides an simple and efficient alternative to
> > multi-thread safe ring when multi-thread safety is not required.
>=20
> Just a thought: do we really need whole new library for that?
> From what I understand all we need right now just one extra function:
> rte_ring_mt_unsafe_prod_deque(...)
> Sorry for ugly name :)
> To dequeue N elems from prod.tail.
> Or you think there would be some extra advantages in ST version of the ri=
ng:
> extra usages, better performance, etc.?
There are multiple implementations of the ST ring being used in other parts=
 of DPDK. Mattias Ronnblom pointed out some (distributed scheduler, eth RX =
adapter, cmdline) [1] existing ones which will be replaced by this one.
This implementation will not use atomic instructions, head and tail indices=
 will be in the same cache line and it will be a double ended queue. So, I =
am expecting better perf and more use cases (some might not be applicable c=
urrently).

[1] https://mails.dpdk.org/archives/dev/2023-August/275003.html

>=20
> >
> > Signed-off-by: Honnappa Nagarahalli <honnappa.nagarahalli@arm.com>
> > ---
> > v1:
> > 1) The code is very prelimnary and is not even compiled
> > 2) This is intended to show the APIs and some thoughts on
> > implementation
> > 3) More APIs and the rest of the implementation will come in subsequent
> >    versions
> >
> >  lib/st_ring/rte_st_ring.h | 567
> > ++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 567 insertions(+)
> >  create mode 100644 lib/st_ring/rte_st_ring.h
> >
> > diff --git a/lib/st_ring/rte_st_ring.h b/lib/st_ring/rte_st_ring.h new
> > file mode 100644 index 0000000000..8cb8832591
> > --- /dev/null
> > +++ b/lib/st_ring/rte_st_ring.h
> > @@ -0,0 +1,567 @@
> > +/* SPDX-License-Identifier: BSD-3-Clause
> > + * Copyright(c) 2023 Arm Limited
> > + */
> > +
> > +#ifndef _RTE_ST_RING_H_
> > +#define _RTE_ST_RING_H_
> > +
> > +/**
> > + * @file
> > + * RTE Signle Thread Ring (ST Ring)
> > + *
> > + * The ST Ring is a fixed-size queue intended to be accessed
> > + * by one thread at a time. It does not provide concurrent access to
> > + * multiple threads. If there are multiple threads accessing the ST
> > +ring,
> > + * then the threads have to use locks to protect the ring from
> > + * getting corrupted.
> > + *
> > + * - FIFO (First In First Out)
> > + * - Maximum size is fixed; the pointers are stored in a table.
> > + * - Consumer and producer part of same thread.
> > + * - Multi-thread producers and consumers need locking.
> > + * - Single/Bulk/burst dequeue at Tail or Head
> > + * - Single/Bulk/burst enqueue at Head or Tail
> > + *
> > + */
> > +
> > +#ifdef __cplusplus
> > +extern "C" {
> > +#endif
> > +
> > +#include <rte_st_ring_core.h>
> > +#include <rte_st_ring_elem.h>
> > +
> > +/**
> > + * Calculate the memory size needed for a ST ring
> > + *
> > + * This function returns the number of bytes needed for a ST ring,
> > +given
> > + * the number of elements in it. This value is the sum of the size of
> > + * the structure rte_st_ring and the size of the memory needed by the
> > + * elements. The value is aligned to a cache line size.
> > + *
> > + * @param count
> > + *   The number of elements in the ring (must be a power of 2).
> > + * @return
> > + *   - The memory size needed for the ST ring on success.
> > + *   - -EINVAL if count is not a power of 2.
> > + */
> > +ssize_t rte_st_ring_get_memsize(unsigned int count);
> > +
> > +/**
> > + * Initialize a ST ring structure.
> > + *
> > + * Initialize a ST ring structure in memory pointed by "r". The size
> > +of the
> > + * memory area must be large enough to store the ring structure and
> > +the
> > + * object table. It is advised to use rte_st_ring_get_memsize() to
> > +get the
> > + * appropriate size.
> > + *
> > + * The ST ring size is set to *count*, which must be a power of two.
> > + * The real usable ring size is *count-1* instead of *count* to
> > + * differentiate a full ring from an empty ring.
> > + *
> > + * The ring is not added in RTE_TAILQ_ST_RING global list. Indeed,
> > +the
> > + * memory given by the caller may not be shareable among dpdk
> > + * processes.
> > + *
> > + * @param r
> > + *   The pointer to the ring structure followed by the elements table.
> > + * @param name
> > + *   The name of the ring.
> > + * @param count
> > + *   The number of elements in the ring (must be a power of 2,
> > + *   unless RTE_ST_RING_F_EXACT_SZ is set in flags).
> > + * @param flags
> > + *   An OR of the following:
> > + *   - RTE_ST_RING_F_EXACT_SZ: If this flag is set, the ring will hold
> > + *     exactly the requested number of entries, and the requested size
> > + *     will be rounded up to the next power of two, but the usable spa=
ce
> > + *     will be exactly that requested. Worst case, if a power-of-2 siz=
e is
> > + *     requested, half the ring space will be wasted.
> > + *     Without this flag set, the ring size requested must be a power =
of 2,
> > + *     and the usable space will be that size - 1.
> > + * @return
> > + *   0 on success, or a negative value on error.
> > + */
> > +int rte_st_ring_init(struct rte_st_ring *r, const char *name,
> > +	unsigned int count, unsigned int flags);
> > +
> > +/**
> > + * Create a new ST ring named *name* in memory.
> > + *
> > + * This function uses ``memzone_reserve()`` to allocate memory. Then
> > +it
> > + * calls rte_st_ring_init() to initialize an empty ring.
> > + *
> > + * The new ring size is set to *count*, which must be a power of two.
> > + * The real usable ring size is *count-1* instead of *count* to
> > + * differentiate a full ring from an empty ring.
> > + *
> > + * The ring is added in RTE_TAILQ_ST_RING list.
> > + *
> > + * @param name
> > + *   The name of the ring.
> > + * @param count
> > + *   The size of the ring (must be a power of 2,
> > + *   unless RTE_ST_RING_F_EXACT_SZ is set in flags).
> > + * @param socket_id
> > + *   The *socket_id* argument is the socket identifier in case of
> > + *   NUMA. The value can be *SOCKET_ID_ANY* if there is no NUMA
> > + *   constraint for the reserved zone.
> > + * @param flags
> > + *   - RTE_ST_RING_F_EXACT_SZ: If this flag is set, the ring will hold=
 exactly
> the
> > + *     requested number of entries, and the requested size will be rou=
nded up
> > + *     to the next power of two, but the usable space will be exactly =
that
> > + *     requested. Worst case, if a power-of-2 size is requested, half =
the
> > + *     ring space will be wasted.
> > + *     Without this flag set, the ring size requested must be a power =
of 2,
> > + *     and the usable space will be that size - 1.
> > + * @return
> > + *   On success, the pointer to the new allocated ring. NULL on error =
with
> > + *    rte_errno set appropriately. Possible errno values include:
> > + *    - E_RTE_NO_CONFIG - function could not get pointer to rte_config
> structure
> > + *    - EINVAL - count provided is not a power of 2
> > + *    - ENOSPC - the maximum number of memzones has already been
> allocated
> > + *    - EEXIST - a memzone with the same name already exists
> > + *    - ENOMEM - no appropriate memory area found in which to create
> memzone
> > + */
> > +struct rte_st_ring *rte_st_ring_create(const char *name, unsigned int =
count,
> > +				 int socket_id, unsigned int flags);
> > +
> > +/**
> > + * De-allocate all memory used by the ring.
> > + *
> > + * @param r
> > + *   Ring to free.
> > + *   If NULL then, the function does nothing.
> > + */
> > +void rte_st_ring_free(struct rte_st_ring *r);
> > +
> > +/**
> > + * Dump the status of the ring to a file.
> > + *
> > + * @param f
> > + *   A pointer to a file for output
> > + * @param r
> > + *   A pointer to the ring structure.
> > + */
> > +void rte_st_ring_dump(FILE *f, const struct rte_st_ring *r);
> > +
> > +/**
> > + * Enqueue fixed number of objects on a ST ring.
> > + *
> > + * This function copies the objects at the head of the ring and
> > + * moves the head index.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_table
> > + *   A pointer to a table of void * pointers (objects).
> > + * @param n
> > + *   The number of objects to add in the ring from the obj_table.
> > + * @param free_space
> > + *   if non-NULL, returns the amount of space in the ring after the
> > + *   enqueue operation has finished.
> > + * @return
> > + *   The number of objects enqueued, either 0 or n
> > + */
> > +static __rte_always_inline unsigned int
> > +rte_st_ring_enqueue_bulk(struct rte_st_ring *r, void * const *obj_tabl=
e,
> > +		      unsigned int n, unsigned int *free_space) {
> > +	return rte_st_ring_enqueue_bulk_elem(r, obj_table, sizeof(void *),
> > +			n, free_space);
> > +}
> > +
> > +/**
> > + * Enqueue upto a maximum number of objects on a ST ring.
> > + *
> > + * This function copies the objects at the head of the ring and
> > + * moves the head index.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_table
> > + *   A pointer to a table of void * pointers (objects).
> > + * @param n
> > + *   The number of objects to add in the ring from the obj_table.
> > + * @param free_space
> > + *   if non-NULL, returns the amount of space in the ring after the
> > + *   enqueue operation has finished.
> > + * @return
> > + *   - n: Actual number of objects enqueued.
> > + */
> > +static __rte_always_inline unsigned int
> > +rte_st_ring_enqueue_burst(struct rte_st_ring *r, void * const *obj_tab=
le,
> > +		      unsigned int n, unsigned int *free_space) {
> > +	return rte_st_ring_enqueue_burst_elem(r, obj_table, sizeof(void *),
> > +			n, free_space);
> > +}
> > +
> > +/**
> > + * Enqueue one object on a ST ring.
> > + *
> > + * This function copies one object at the head of the ring and
> > + * moves the head index.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj
> > + *   A pointer to the object to be added.
> > + * @return
> > + *   - 0: Success; objects enqueued.
> > + *   - -ENOBUFS: Not enough room in the ring to enqueue; no object is
> enqueued.
> > + */
> > +static __rte_always_inline int
> > +rte_st_ring_enqueue(struct rte_st_ring *r, void *obj) {
> > +	return rte_st_ring_enqueue_elem(r, &obj, sizeof(void *)); }
> > +
> > +/**
> > + * Enqueue fixed number of objects on a ST ring at the tail.
> > + *
> > + * This function copies the objects at the tail of the ring and
> > + * moves the tail index (backwards).
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_table
> > + *   A pointer to a table of void * pointers (objects).
> > + * @param n
> > + *   The number of objects to add in the ring from the obj_table.
> > + * @param free_space
> > + *   if non-NULL, returns the amount of space in the ring after the
> > + *   enqueue operation has finished.
> > + * @return
> > + *   The number of objects enqueued, either 0 or n
> > + */
> > +static __rte_always_inline unsigned int
> > +rte_st_ring_enqueue_at_tail_bulk(struct rte_st_ring *r,
> > +				 void * const *obj_table, unsigned int n,
> > +				 unsigned int *free_space)
> > +{
> > +	return rte_st_ring_enqueue_at_tail_bulk_elem(r, obj_table,
> > +			sizeof(void *), n, free_space);
> > +}
> > +
> > +/**
> > + * Enqueue upto a maximum number of objects on a ST ring at the tail.
> > + *
> > + * This function copies the objects at the tail of the ring and
> > + * moves the tail index (backwards).
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_table
> > + *   A pointer to a table of void * pointers (objects).
> > + * @param n
> > + *   The number of objects to add in the ring from the obj_table.
> > + * @param free_space
> > + *   if non-NULL, returns the amount of space in the ring after the
> > + *   enqueue operation has finished.
> > + * @return
> > + *   - n: Actual number of objects enqueued.
> > + */
> > +static __rte_always_inline unsigned int
> > +rte_st_ring_enqueue_at_tail_burst(struct rte_st_ring *r,
> > +				  void * const *obj_table, unsigned int n,
> > +				  unsigned int *free_space)
> > +{
> > +	return rte_st_ring_enqueue_at_tail_burst_elem(r, obj_table,
> > +			sizeof(void *), n, free_space);
> > +}
> > +
> > +/**
> > + * Enqueue one object on a ST ring at tail.
> > + *
> > + * This function copies one object at the tail of the ring and
> > + * moves the tail index (backwards).
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj
> > + *   A pointer to the object to be added.
> > + * @return
> > + *   - 0: Success; objects enqueued.
> > + *   - -ENOBUFS: Not enough room in the ring to enqueue; no object is
> enqueued.
> > + */
> > +static __rte_always_inline int
> > +rte_st_ring_enqueue_at_tail(struct rte_st_ring *r, void *obj) {
> > +	return rte_st_ring_enqueue_at_tail_elem(r, &obj, sizeof(void *)); }
> > +
> > +/**
> > + * Dequeue a fixed number of objects from a ST ring.
> > + *
> > + * This function copies the objects from the tail of the ring and
> > + * moves the tail index.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_table
> > + *   A pointer to a table of void * pointers (objects) that will be fi=
lled.
> > + * @param n
> > + *   The number of objects to dequeue from the ring to the obj_table.
> > + * @param available
> > + *   If non-NULL, returns the number of remaining ring entries after t=
he
> > + *   dequeue has finished.
> > + * @return
> > + *   The number of objects dequeued, either 0 or n
> > + */
> > +static __rte_always_inline unsigned int
> > +rte_st_ring_dequeue_bulk(struct rte_st_ring *r, void **obj_table, unsi=
gned
> int n,
> > +		unsigned int *available)
> > +{
> > +	return rte_st_ring_dequeue_bulk_elem(r, obj_table, sizeof(void *),
> > +			n, available);
> > +}
> > +
> > +/**
> > + * Dequeue upto a maximum number of objects from a ST ring.
> > + *
> > + * This function copies the objects from the tail of the ring and
> > + * moves the tail index.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_table
> > + *   A pointer to a table of void * pointers (objects) that will be fi=
lled.
> > + * @param n
> > + *   The number of objects to dequeue from the ring to the obj_table.
> > + * @param available
> > + *   If non-NULL, returns the number of remaining ring entries after t=
he
> > + *   dequeue has finished.
> > + * @return
> > + *   - Number of objects dequeued
> > + */
> > +static __rte_always_inline unsigned int
> > +rte_st_ring_dequeue_burst(struct rte_st_ring *r, void **obj_table,
> > +		unsigned int n, unsigned int *available) {
> > +	return rte_st_ring_dequeue_burst_elem(r, obj_table, sizeof(void *),
> > +			n, available);
> > +}
> > +
> > +/**
> > + * Dequeue one object from a ST ring.
> > + *
> > + * This function copies one object from the tail of the ring and
> > + * moves the tail index.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_p
> > + *   A pointer to a void * pointer (object) that will be filled.
> > + * @return
> > + *   - 0: Success, objects dequeued.
> > + *   - -ENOENT: Not enough entries in the ring to dequeue, no object i=
s
> > + *     dequeued.
> > + */
> > +static __rte_always_inline int
> > +rte_st_ring_dequeue(struct rte_st_ring *r, void **obj_p) {
> > +	return rte_st_ring_dequeue_elem(r, obj_p, sizeof(void *)); }
> > +
> > +/**
> > + * Dequeue a fixed number of objects from a ST ring from the head.
> > + *
> > + * This function copies the objects from the head of the ring and
> > + * moves the head index (backwards).
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_table
> > + *   A pointer to a table of void * pointers (objects) that will be fi=
lled.
> > + * @param n
> > + *   The number of objects to dequeue from the ring to the obj_table.
> > + * @param available
> > + *   If non-NULL, returns the number of remaining ring entries after t=
he
> > + *   dequeue has finished.
> > + * @return
> > + *   The number of objects dequeued, either 0 or n
> > + */
> > +static __rte_always_inline unsigned int
> > +rte_st_ring_dequeue_at_head_bulk(struct rte_st_ring *r, void **obj_tab=
le,
> unsigned int n,
> > +		unsigned int *available)
> > +{
> > +	return rte_st_ring_dequeue_bulk_elem(r, obj_table, sizeof(void *),
> > +			n, available);
> > +}
> > +
> > +/**
> > + * Dequeue upto a maximum number of objects from a ST ring from the
> head.
> > + *
> > + * This function copies the objects from the head of the ring and
> > + * moves the head index (backwards).
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_table
> > + *   A pointer to a table of void * pointers (objects) that will be fi=
lled.
> > + * @param n
> > + *   The number of objects to dequeue from the ring to the obj_table.
> > + * @param available
> > + *   If non-NULL, returns the number of remaining ring entries after t=
he
> > + *   dequeue has finished.
> > + * @return
> > + *   - Number of objects dequeued
> > + */
> > +static __rte_always_inline unsigned int
> > +rte_st_ring_dequeue_at_head_burst(struct rte_st_ring *r, void
> **obj_table,
> > +		unsigned int n, unsigned int *available) {
> > +	return rte_st_ring_dequeue_burst_elem(r, obj_table, sizeof(void *),
> > +			n, available);
> > +}
> > +
> > +/**
> > + * Dequeue one object from a ST ring from the head.
> > + *
> > + * This function copies the objects from the head of the ring and
> > + * moves the head index (backwards).
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @param obj_p
> > + *   A pointer to a void * pointer (object) that will be filled.
> > + * @return
> > + *   - 0: Success, objects dequeued.
> > + *   - -ENOENT: Not enough entries in the ring to dequeue, no object i=
s
> > + *     dequeued.
> > + */
> > +static __rte_always_inline int
> > +rte_st_ring_at_head_dequeue(struct rte_st_ring *r, void **obj_p) {
> > +	return rte_st_ring_dequeue_elem(r, obj_p, sizeof(void *)); }
> > +
> > +/**
> > + * Flush a ST ring.
> > + *
> > + * This function flush all the elements in a ST ring
> > + *
> > + * @warning
> > + * Make sure the ring is not in use while calling this function.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + */
> > +void
> > +rte_st_ring_reset(struct rte_st_ring *r);
> > +
> > +/**
> > + * Return the number of entries in a ST ring.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @return
> > + *   The number of entries in the ring.
> > + */
> > +static inline unsigned int
> > +rte_st_ring_count(const struct rte_st_ring *r) {
> > +	uint32_t count =3D (r->head - r->tail) & r->mask;
> > +	return count;
> > +}
> > +
> > +/**
> > + * Return the number of free entries in a ST ring.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @return
> > + *   The number of free entries in the ring.
> > + */
> > +static inline unsigned int
> > +rte_st_ring_free_count(const struct rte_st_ring *r) {
> > +	return r->capacity - rte_st_ring_count(r); }
> > +
> > +/**
> > + * Test if a ST ring is full.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @return
> > + *   - 1: The ring is full.
> > + *   - 0: The ring is not full.
> > + */
> > +static inline int
> > +rte_st_ring_full(const struct rte_st_ring *r) {
> > +	return rte_st_ring_free_count(r) =3D=3D 0; }
> > +
> > +/**
> > + * Test if a ST ring is empty.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @return
> > + *   - 1: The ring is empty.
> > + *   - 0: The ring is not empty.
> > + */
> > +static inline int
> > +rte_st_ring_empty(const struct rte_st_ring *r) {
> > +	return r->tail =3D=3D r->head;
> > +}
> > +
> > +/**
> > + * Return the size of the ring.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @return
> > + *   The size of the data store used by the ring.
> > + *   NOTE: this is not the same as the usable space in the ring. To qu=
ery that
> > + *   use ``rte_st_ring_get_capacity()``.
> > + */
> > +static inline unsigned int
> > +rte_st_ring_get_size(const struct rte_st_ring *r) {
> > +	return r->size;
> > +}
> > +
> > +/**
> > + * Return the number of elements which can be stored in the ring.
> > + *
> > + * @param r
> > + *   A pointer to the ring structure.
> > + * @return
> > + *   The usable size of the ring.
> > + */
> > +static inline unsigned int
> > +rte_st_ring_get_capacity(const struct rte_st_ring *r) {
> > +	return r->capacity;
> > +}
> > +
> > +/**
> > + * Dump the status of all rings on the console
> > + *
> > + * @param f
> > + *   A pointer to a file for output
> > + */
> > +void rte_st_ring_list_dump(FILE *f);
> > +
> > +/**
> > + * Search a ST ring from its name
> > + *
> > + * @param name
> > + *   The name of the ring.
> > + * @return
> > + *   The pointer to the ring matching the name, or NULL if not found,
> > + *   with rte_errno set appropriately. Possible rte_errno values inclu=
de:
> > + *    - ENOENT - required entry not available to return.
> > + */
> > +struct rte_st_ring *rte_st_ring_lookup(const char *name);
> > +
> > +#ifdef __cplusplus
> > +}
> > +#endif
> > +
> > +#endif /* _RTE_ST_RING_H_ */
> > --
> > 2.25.1
> >