From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail.droids-corp.org (zoll.droids-corp.org [94.23.50.67]) by dpdk.org (Postfix) with ESMTP id 32256292D for ; Mon, 25 Feb 2019 11:43:28 +0100 (CET) Received: from lfbn-1-5920-128.w90-110.abo.wanadoo.fr ([90.110.126.128] helo=droids-corp.org) by mail.droids-corp.org with esmtpsa (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gyDlP-0001PM-Ax; Mon, 25 Feb 2019 11:45:36 +0100 Received: by droids-corp.org (sSMTP sendmail emulation); Mon, 25 Feb 2019 11:43:22 +0100 Date: Mon, 25 Feb 2019 11:43:22 +0100 From: Olivier Matz To: Gage Eads Cc: dev@dpdk.org, arybchenko@solarflare.com, bruce.richardson@intel.com, konstantin.ananyev@intel.com, gavin.hu@arm.com, Honnappa.Nagarahalli@arm.com, nd@arm.com, thomas@monjalon.net Message-ID: <20190225104322.pxzf32gyhbeeq4tp@platinum> References: <20190222160655.3346-1-gage.eads@intel.com> <20190222160655.3346-2-gage.eads@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190222160655.3346-2-gage.eads@intel.com> User-Agent: NeoMutt/20170113 (1.7.2) Subject: Re: [dpdk-dev] [PATCH 1/7] stack: introduce rte stack library 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: , X-List-Received-Date: Mon, 25 Feb 2019 10:43:28 -0000 Hi Gage, Please find few comments below. On Fri, Feb 22, 2019 at 10:06:49AM -0600, Gage Eads wrote: > The rte_stack library provides an API for configuration and use of a > bounded stack of pointers. Push and pop operations are MT-safe, allowing > concurrent access, and the interface supports pushing and popping multiple > pointers at a time. > > The library's interface is modeled after another DPDK data structure, > rte_ring, and its lock-based implementation is derived from the stack > mempool handler. An upcoming commit will migrate the stack mempool handler > to rte_stack. > > Signed-off-by: Gage Eads [...] > --- /dev/null > +++ b/doc/guides/prog_guide/stack_lib.rst > @@ -0,0 +1,26 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright(c) 2019 Intel Corporation. > + > +Stack Library > +============= > + > +DPDK's stack library provides an API for configuration and use of a bounded stack of > +pointers. > + > +The stack library provides the following basic operations: > + > +* Create a uniquely named stack of a user-specified size and using a user-specified socket. > + > +* Push and pop a burst of one or more stack objects (pointers). These function are multi-threading safe. > + > +* Free a previously created stack. > + > +* Lookup a pointer to a stack by its name. > + > +* Query a stack's current depth and number of free entries. It seems the 80-cols limitation also applies to documentation: https://mails.dpdk.org/archives/dev/2019-February/124917.html [...] > --- /dev/null > +++ b/lib/librte_stack/rte_stack.h > @@ -0,0 +1,277 @@ > +/* SPDX-License-Identifier: BSD-3-Clause > + * Copyright(c) 2019 Intel Corporation > + */ > + > +/** > + * @file rte_stack.h > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * RTE Stack. > + * librte_stack provides an API for configuration and use of a bounded stack of > + * pointers. Push and pop operations are MT-safe, allowing concurrent access, > + * and the interface supports pushing and popping multiple pointers at a time. > + */ > + > +#ifndef _RTE_STACK_H_ > +#define _RTE_STACK_H_ > + > +#ifdef __cplusplus > +extern "C" { > +#endif > + > +#include > +#include > +#include > + > +#define RTE_TAILQ_STACK_NAME "RTE_STACK" > +#define RTE_STACK_MZ_PREFIX "STK_" > +/**< The maximum length of a stack name. */ > +#define RTE_STACK_NAMESIZE (RTE_MEMZONE_NAMESIZE - \ > + sizeof(RTE_STACK_MZ_PREFIX) + 1) > + > +/* Structure containing the LIFO, its current length, and a lock for mutual > + * exclusion. > + */ > +struct rte_lifo { > + rte_spinlock_t lock; /**< LIFO lock */ > + uint32_t len; /**< LIFO len */ > + void *objs[]; /**< LIFO pointer table */ > +}; > + > +/* The RTE stack structure contains the LIFO structure itself, plus metadata > + * such as its name and memzone pointer. > + */ > +struct rte_stack { > + /** Name of the stack. */ > + char name[RTE_STACK_NAMESIZE] __rte_cache_aligned; > + /** Memzone containing the rte_stack structure */ > + const struct rte_memzone *memzone; > + uint32_t capacity; /**< Usable size of the stack */ > + uint32_t flags; /**< Flags supplied at creation */ > + struct rte_lifo lifo; /**< LIFO structure */ > +} __rte_cache_aligned; > + > +/** > + * @warning > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * @internal Push several objects on the stack (MT-safe) > + * > + * @param s > + * A pointer to the stack structure. > + * @param obj_table > + * A pointer to a table of void * pointers (objects). > + * @param n > + * The number of objects to push on the stack from the obj_table. > + * @return > + * Actual number of objects pushed (either 0 or *n*). > + */ Minor: a dot is missing at the end of the title. There are few in this patch, and maybe in next ones. [...] > +/** > + * @warning > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * Return the number of used entries in a stack. > + * > + * @param s > + * A pointer to the stack structure. > + * @return > + * The number of used entries in the stack. > + */ > +static __rte_always_inline unsigned int __rte_experimental > +rte_stack_count(struct rte_stack *s) > +{ > + return (unsigned int)s->lifo.len; > +} The argument can be const. > + > +/** > + * @warning > + * @b EXPERIMENTAL: this API may change without prior notice > + * > + * Return the number of free entries in a stack. > + * > + * @param s > + * A pointer to the stack structure. > + * @return > + * The number of free entries in the stack. > + */ > +static __rte_always_inline unsigned int __rte_experimental > +rte_stack_free_count(struct rte_stack *s) > +{ > + return s->capacity - rte_stack_count(s); > +} Same here.