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 0E398A04A4; Tue, 26 May 2020 18:06:31 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id E7BBC1D613; Tue, 26 May 2020 18:06:29 +0200 (CEST) Received: from mail-wm1-f65.google.com (mail-wm1-f65.google.com [209.85.128.65]) by dpdk.org (Postfix) with ESMTP id B2D8D1D5FA for ; Tue, 26 May 2020 18:06:28 +0200 (CEST) Received: by mail-wm1-f65.google.com with SMTP id r9so77799wmh.2 for ; Tue, 26 May 2020 09:06:28 -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=pTYJs+7pUTOjiw4encUsYnWUa1PADouetQ9KtldWV64=; b=FhkDdVbBDo7UFp/twEpIOv3lYUG45gEahuwrOrvf9953bogs4/wqzlK06sFqV2K/1g HCVJvQ01A8kvgrwtMh6bZZXTNHgz49yFgZR2HKvAYBN+b94ROBgJbKPzD6UvKcsa7miK MEMNazfvvxvGciFD+jl2UUaqnaUDxSqIy4xC4NmwsOrULKNeu3vvhRKByf/MpFHn7d9T 1wJ/ud4cvSaHKMQwG1PDMqsEcw1BFR2nn/7uneyyvafVpUmwyGeeaEBzwbqTLtg2G6tO fIR3FYQIaLSu27bLnAl/upqoi67MTkKVTAgU/rXfIBFEBSoWlzaVZkHWrBilO+VIO9ZG 2xWA== 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=pTYJs+7pUTOjiw4encUsYnWUa1PADouetQ9KtldWV64=; b=bagySv1A4ShwNWLACUo7kt1yiDouh7iUwvzWUAWFWMsspQhZS63QIu2QIZQCF3c+DE yS0BoNz/GHnBi7dYtdn/ghZgPacqw8wOVGaRipFEyZpl6uYwxN2IlYUULgfl2sE5qqS+ EIUWBWgYDLaLHAsj20wfIGtRw3I/tCWH4nwvhA2AvW/gYJWc697HchYs9L9tEEALi2RV PSIPceEs9ehHr/jIzOSBMkJg7f05fj0VOuD+Cub5rbterwsOLCNBb9LAum0sLigxlfqF UrjOhfTrLaP1tTN2UhTx3cn9gWz/UltRg9ICHijTCdqYaa8Bh7kctniDw5EhimTurxqi eZLw== X-Gm-Message-State: AOAM531aos/+v4rnX1MEqMXFOT3TDsnuKYJ8fgPX2Xy+RFnOeC4zJyXw bdxd8dFiJJ9+F4l0fq1AUqJmAg== X-Google-Smtp-Source: ABdhPJwJhB6KKXvgXOh63b3x8gBEJgs6XljgT9HvMSum0OwdB2d6+a34tcBnIEFc8KCFLP5OwBK6Vg== X-Received: by 2002:a1c:7308:: with SMTP id d8mr2087wmb.6.1590509187293; Tue, 26 May 2020 09:06:27 -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 q128sm75404wma.38.2020.05.26.09.06.26 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 26 May 2020 09:06:26 -0700 (PDT) Date: Tue, 26 May 2020 18:06:26 +0200 From: Olivier Matz To: Jerin Jacob Cc: Thomas Monjalon , dpdk-dev , David Marchand , Jerin Jacob , Nithin Dabilpuram , Krzysztof Kanas , Andrew Rybchenko , Ferruh Yigit , "Richardson, Bruce" , John McNamara , Marko Kovacevic Message-ID: <20200526160626.GD2554@platinum> References: <20200525212415.3173817-1-thomas@monjalon.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.10.1 (2018-07-13) Subject: Re: [dpdk-dev] [PATCH] mbuf: document rule for new fields and flags 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, On Tue, May 26, 2020 at 01:09:37PM +0530, Jerin Jacob wrote: > On Tue, May 26, 2020 at 2:54 AM Thomas Monjalon wrote: > > > > Since dynamic fields and flags were added in 19.11, > > the idea was to use them for new features, not only PMD-specific. > > > > The rule is made more explicit in doxygen, in the mbuf guide, > > and in the contribution design guidelines. > > > > For more information about the original design, see the presentation > > https://www.dpdk.org/wp-content/uploads/sites/35/2019/10/DynamicMbuf.pdf > > > > Signed-off-by: Thomas Monjalon > > --- > > doc/guides/contributing/design.rst | 13 +++++++++++++ > > doc/guides/prog_guide/mbuf_lib.rst | 23 +++++++++++++++++++++++ > > lib/librte_mbuf/rte_mbuf_core.h | 2 ++ > > 3 files changed, 38 insertions(+) > > > > diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst > > index d3dd694b65..508115d5bd 100644 > > --- a/doc/guides/contributing/design.rst > > +++ b/doc/guides/contributing/design.rst > > @@ -57,6 +57,19 @@ The following config options can be used: > > * ``CONFIG_RTE_EXEC_ENV`` is a string that contains the name of the executive environment. > > * ``CONFIG_RTE_EXEC_ENV_FREEBSD`` or ``CONFIG_RTE_EXEC_ENV_LINUX`` are defined only if we are building for this execution environment. > > > > +Mbuf features > > +------------- > > + > > +The ``rte_mbuf`` structure must be kept small (128 bytes). > > + > > +In order to add new features without wasting buffer space for unused features, > > +some fields and flags can be registered dynamically in a shared area. > > I think, instead of "can", it should be "must" > > > +The "dynamic" mbuf area is the default choice for the new features. In my opinion, Thomas' proposal is correct, with the next sentence saying it is the default choice for new features. Giving guidelines is a good thing (thanks Thomas for documenting it), but I don't think we should be too strict: the door remains open for technical debate and exceptions. > > + > > +The "dynamic" area is eating the remaining space in mbuf, > > +and some existing "static" fields may need to become "dynamic". > > + > > + > > Library Statistics > > ------------------ > > > > diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst > > index 0d3223b081..c3dbfb9221 100644 > > --- a/doc/guides/prog_guide/mbuf_lib.rst > > +++ b/doc/guides/prog_guide/mbuf_lib.rst > > @@ -207,6 +207,29 @@ The list of flags and their precise meaning is described in the mbuf API > > documentation (rte_mbuf.h). Also refer to the testpmd source code > > (specifically the csumonly.c file) for details. > > > > +Dynamic fields and flags > > +~~~~~~~~~~~~~~~~~~~~~~~~ > > + > > +The size of the mbuf is constrained and limited; > > +while the amount of metadata to save for each packet is quite unlimited. > > +The most basic networking information already find their place > > +in the existing mbuf fields and flags. > > + > > +If new features need to be added, the new fields and flags should fit > > How about, instead of "should fit", must use the dynamic space. Same comment here, I think Thomas's original sentence is fine. > > > +in the "dynamic space", by registering some room in the mbuf structure: > > + > > +dynamic field > > + named area in the mbuf structure, > > + with a given size (at least 1 byte) and alignment constraint. > > + > > +dynamic flag > > + named bit in the mbuf structure, > > + stored in the field ``ol_flags``. > > + > > +The dynamic fields and flags are managed with the functions ``rte_mbuf_dyn*``. > > + > > +It is not possible to unregister fields or flags. > > + > > .. _direct_indirect_buffer: > > > > Direct and Indirect Buffers > > diff --git a/lib/librte_mbuf/rte_mbuf_core.h b/lib/librte_mbuf/rte_mbuf_core.h > > index b9a59c879c..22be41e520 100644 > > --- a/lib/librte_mbuf/rte_mbuf_core.h > > +++ b/lib/librte_mbuf/rte_mbuf_core.h > > @@ -12,6 +12,8 @@ > > * packet offload flags and some related macros. > > * For majority of DPDK entities, it is not recommended to include > > * this file directly, use include instead. > > + * > > + * New fields and flags should fit in the "dynamic space". > > must use. Same comment here. Acked-by: Olivier Matz