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 E2BCCA04C0; Thu, 17 Sep 2020 16:25:33 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id C14A51D676; Thu, 17 Sep 2020 16:25:33 +0200 (CEST) Received: from mail-wr1-f68.google.com (mail-wr1-f68.google.com [209.85.221.68]) by dpdk.org (Postfix) with ESMTP id 94B8F1D668 for ; Thu, 17 Sep 2020 16:25:32 +0200 (CEST) Received: by mail-wr1-f68.google.com with SMTP id k15so2291443wrn.10 for ; Thu, 17 Sep 2020 07:25:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=6wind.com; s=google; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to:user-agent; bh=ZS2K8ZFZU+KpnFgv4ZjITX1ZDFyXYIMdbfy8PFnQs6U=; b=RUSgT+F6il9bJ1ieFcKk74PPCqlOQc76kFGEFB+TpMT8g36Is03DIoLm6ejKbuZW2Z x526MD5+EE9RpotVixBPlbTGEsvl6RD4QN1IT4MH7LS12UNNWeMqqmHUgCiSZDnfcm+r uUTkvkBC4jF8oBaX0JJzWW1VOje0gM5ELi16V9sXzi1cd19K5SXlssU/bYtOCFEKpnha yM34NhsFY/jehs4hjBUyUxqD84RJsewGqOYrubuSKtf3qEkFmj8MMdzrJUYLl4KG0pQl zQnGOfiiPLOQ7V/YDvrhV3wezUUGwmsf9FwQO3z6UjBWtEk2mIoOtUp72CrITlAA5b7U eN5g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to:user-agent; bh=ZS2K8ZFZU+KpnFgv4ZjITX1ZDFyXYIMdbfy8PFnQs6U=; b=kWyqZ7D9VJcSDa+yli/AkuclmQkGllWver5wIFxABtHzMJVsGHIdpkv2JK0cePuVVU G90ynXvam+24GD/44j5Epxo1W929nQLALd6uUxSaWWErqIgjtPHOuoajM/xDKFTrUxDI /2tHgxyqZvc5+kf2F9UOFIIi2+FoiaxrUMQtGcnviYk/IC4tXvo2cJU8HKGf2TQsPZiQ oON5szBzfjPiWm40a2fczbbNJY+2jBnQYHJ05GdRNsWz9ohSZrqvwUgTq4+w6DdU2WoO g4H51Ay/DXpULUCvICMLTYrAx954oqpUdlPfRqe2C6yeNYD7Vj4cIAqMdmQYSmJZ1P7b YI2A== X-Gm-Message-State: AOAM532avht73OdjabXITZRyW6CiBxCDSBkdDOGcvaVWCMhv78MmoYzb 0T1Jn0BO+dlBeAc6Ub73Bk8dtA== X-Google-Smtp-Source: ABdhPJyYE8iYr7NsDKQj23+wFPmG4oVsVqTbrzkdtBUtOch2P8fI99jK/MiU7XUC5yOKrQhp7vKyWw== X-Received: by 2002:adf:dd82:: with SMTP id x2mr34532210wrl.419.1600352732325; Thu, 17 Sep 2020 07:25:32 -0700 (PDT) Received: from 6wind.com (2a01cb0c0005a600345636f7e65ed1a0.ipv6.abo.wanadoo.fr. [2a01:cb0c:5:a600:3456:36f7:e65e:d1a0]) by smtp.gmail.com with ESMTPSA id t1sm10506958wmi.16.2020.09.17.07.25.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 17 Sep 2020 07:25:31 -0700 (PDT) Date: Thu, 17 Sep 2020 16:25:30 +0200 From: Olivier Matz To: Gage Eads Cc: dev@dpdk.org, arybchenko@solarflare.com, john.mcnamara@intel.com, marko.kovacevic@intel.com Message-ID: <20200917142530.GU21395@platinum> References: <20200811211015.29704-1-gage.eads@intel.com> <20200914211153.6725-1-gage.eads@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20200914211153.6725-1-gage.eads@intel.com> User-Agent: Mutt/1.10.1 (2018-07-13) Subject: Re: [dpdk-dev] [PATCH v3] doc: add stack mempool guide 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" Hi Gage, On Mon, Sep 14, 2020 at 04:11:53PM -0500, Gage Eads wrote: > This guide describes the two stack modes, their tradeoffs, and (via a > reference to the mempool guide) how to enable them. > > Signed-off-by: Gage Eads > --- > v3: Fixed "Title underline too short" warning > > v2: Added commit description > > doc/guides/mempool/index.rst | 1 + > doc/guides/mempool/stack.rst | 38 +++++++++++++++++++++++++++++++++++ > doc/guides/prog_guide/mempool_lib.rst | 2 ++ > doc/guides/prog_guide/stack_lib.rst | 4 ++++ > 4 files changed, 45 insertions(+) > create mode 100644 doc/guides/mempool/stack.rst > > diff --git a/doc/guides/mempool/index.rst b/doc/guides/mempool/index.rst > index bbd02fd81..a0e55467e 100644 > --- a/doc/guides/mempool/index.rst > +++ b/doc/guides/mempool/index.rst > @@ -14,3 +14,4 @@ application through the mempool API. > octeontx > octeontx2 > ring > + stack > diff --git a/doc/guides/mempool/stack.rst b/doc/guides/mempool/stack.rst > new file mode 100644 > index 000000000..bdf19cf04 > --- /dev/null > +++ b/doc/guides/mempool/stack.rst > @@ -0,0 +1,38 @@ > +.. SPDX-License-Identifier: BSD-3-Clause > + Copyright(c) 2020 Intel Corporation. > + > +Stack Mempool Driver > +==================== > + > +**rte_mempool_stack** is a pure software mempool driver based on the > +``rte_stack`` DPDK library. A stack-based mempool is often better suited to > +packet-processing workloads than a ring-based mempool, since its LIFO behavior > +results in better temporal locality and a minimal memory footprint even if the > +mempool is over-provisioned. Would it make sense to give an example of a use-case where the stack driver should be used in place of the standard ring-based one? In most run-to-completion applications, the mbufs stay in per-core caches, so changing the mempool driver won't have a big impact. However, I suspect that for applications using a pipeline model (ex: rx on core0, tx on core1), the stack model would be more efficient. Is it something that you measured? If yes, it would be useful to explain this in the documentation. > + > +The following modes of operation are available for the stack mempool driver and > +can be selected as described in :ref:`Mempool_Handlers`: > + > +- ``stack`` > + > + The underlying **rte_stack** operates in standard (lock-based) mode. > + For more information please refer to :ref:`Stack_Library_Std_Stack`. > + > +- ``lf_stack`` > + > + The underlying **rte_stack** operates in lock-free mode. For more > + information please refer to :ref:`Stack_Library_LF_Stack`. > + > +The standard stack outperforms the lock-free stack on average, however the > +standard stack is non-preemptive: if a mempool user is preempted while holding > +the stack lock, that thread will block all other mempool accesses until it > +returns and releases the lock. As a result, an application using the standard > +stack whose threads can be preempted can suffer from brief, infrequent > +performance hiccups. > + > +The lock-free stack, by design, is not susceptible to this problem; one thread can > +be preempted at any point during a push or pop operation and will not impede > +the progress of any other thread. > + > +For a more detailed description of the stack implementations, please refer to > +:doc:`../prog_guide/stack_lib`. > diff --git a/doc/guides/prog_guide/mempool_lib.rst b/doc/guides/prog_guide/mempool_lib.rst > index e3e1f940b..6f3c0067f 100644 > --- a/doc/guides/prog_guide/mempool_lib.rst > +++ b/doc/guides/prog_guide/mempool_lib.rst > @@ -105,6 +105,8 @@ These user-owned caches can be explicitly passed to ``rte_mempool_generic_put()` > The ``rte_mempool_default_cache()`` call returns the default internal cache if any. > In contrast to the default caches, user-owned caches can be used by unregistered non-EAL threads too. > > +.. _Mempool_Handlers: > + > Mempool Handlers > ------------------------ > > diff --git a/doc/guides/prog_guide/stack_lib.rst b/doc/guides/prog_guide/stack_lib.rst > index 8fe8804e3..3097cab0c 100644 > --- a/doc/guides/prog_guide/stack_lib.rst > +++ b/doc/guides/prog_guide/stack_lib.rst > @@ -28,6 +28,8 @@ Implementation > The library supports two types of stacks: standard (lock-based) and lock-free. > Both types use the same set of interfaces, but their implementations differ. > > +.. _Stack_Library_Std_Stack: > + > Lock-based Stack > ---------------- > > @@ -35,6 +37,8 @@ The lock-based stack consists of a contiguous array of pointers, a current > index, and a spinlock. Accesses to the stack are made multi-thread safe by the > spinlock. > > +.. _Stack_Library_LF_Stack: > + > Lock-free Stack > ------------------ > > -- > 2.13.6 >