From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: <dev-bounces@dpdk.org> Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id BFC8CA00C5; Thu, 11 Jun 2020 08:38:16 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 1EE962C57; Thu, 11 Jun 2020 08:38:16 +0200 (CEST) Received: from mail-il1-f195.google.com (mail-il1-f195.google.com [209.85.166.195]) by dpdk.org (Postfix) with ESMTP id 4A9B12C4F; Thu, 11 Jun 2020 08:38:14 +0200 (CEST) Received: by mail-il1-f195.google.com with SMTP id a13so4409319ilh.3; Wed, 10 Jun 2020 23:38:14 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=psvsXpaAEbA5e8MtYxAWYfEnyw58hnCghOPy7ytKHtc=; b=stEnTFbf7yFhwdD7K6ZgIynzXa1RjByAGcE7fDgzXUsRaNCAXXAgBnw36yRljSGeld pYpPj7FNDqc+Sr8Gp3EZIMpcbPgACwKPpOUrja2dcELqQ4VBXqoVC1eZKSiSSgTpw5IQ OF5emar1eST5RoeRtQkcF14NM6EpwOpj1a8KZDE2eQgXn4y/zSdttL5rpRog0OK1GbhU RFW9yeJykjawnOGn5fKTHX+51e6Qa5sfYraIWJ5mHXs1IBtmrXSWtiSwwyx4VvnwHmEC KQb78hPXydVrEXorgEAOGhCKi73xNdKw+aO+MTNIeQbe+hsi0Vf8R1czw/dq8ekX/x7Q BQyQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=psvsXpaAEbA5e8MtYxAWYfEnyw58hnCghOPy7ytKHtc=; b=eaoTyi9n48vWxajhWXgVODJ4RsvGj7VLxb18HcBLTRx9dxLxaq8GPiFF20y/33WqA2 5WfDVTdJPWn3X+9EHk/cDi1sZVXQi5meGzwIlmLDEC2+NL48py/pw08N7MIibneKyf2U 5MhonQTExOSspbEalGVWDUY5Rk8rYYpj9r7xcaTNk11otwqoPTm/LzyVnLFDHdkobWDI n1ELHfLAl7I9QRRSQ5yGAviCtLgQs4Bli7/IOackorL+3sUa3Va4N1+w743B9c56vM4M RGgCKyDn1oqFuo/MYkpw1rkTsuMXpGgZw7Vqv7DIG0bKwXCHWXlYGjcWlGqy48xOjYry /rWA== X-Gm-Message-State: AOAM530QRRkwWC7/PidRESAUyLgc5FdfrOznrLN45M4FPiH/ruZqUNFp /e9v2b0iQAFtuo/NC1K4Kt49b0joAEiyYgbEhp8= X-Google-Smtp-Source: ABdhPJyzbYhwZRqPqzqCp2LVCF4J9/iRPWCSFFzLTtVXjGVfXHUWCj2zdJfi7uHRl5ASRlc1stv6/7tO/w5BKoTXoCo= X-Received: by 2002:a92:dc47:: with SMTP id x7mr6877994ilq.130.1591857493448; Wed, 10 Jun 2020 23:38:13 -0700 (PDT) MIME-Version: 1.0 References: <20200525212415.3173817-1-thomas@monjalon.net> <20200611063229.3591726-1-thomas@monjalon.net> In-Reply-To: <20200611063229.3591726-1-thomas@monjalon.net> From: Jerin Jacob <jerinjacobk@gmail.com> Date: Thu, 11 Jun 2020 12:07:57 +0530 Message-ID: <CALBAE1OfK12HaMLtwS-An+DPKuxvRkhe0mn6n2oLSaUGbcFuLw@mail.gmail.com> To: Thomas Monjalon <thomas@monjalon.net> Cc: dpdk-dev <dev@dpdk.org>, techboard@dpdk.org, Olivier Matz <olivier.matz@6wind.com>, John McNamara <john.mcnamara@intel.com>, Marko Kovacevic <marko.kovacevic@intel.com> Content-Type: text/plain; charset="UTF-8" Subject: Re: [dpdk-dev] [PATCH v2] mbuf: document guideline for new fields and flags X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 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 Sender: "dev" <dev-bounces@dpdk.org> On Thu, Jun 11, 2020 at 12:02 PM Thomas Monjalon <thomas@monjalon.net> 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 guideline 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 > > This decision was discussed in the Technical Board: > http://mails.dpdk.org/archives/dev/2020-June/169667.html > > Signed-off-by: Thomas Monjalon <thomas@monjalon.net> > Acked-by: Olivier Matz <olivier.matz@6wind.com> Acked-by: Jerin Jacob <jerinj@marvell.com> > --- > > v2: > - replace "rule" with "guideline" > - add few exception criterias > - add URL of the techboard minutes > > --- > doc/guides/contributing/design.rst | 16 ++++++++++++++++ > doc/guides/prog_guide/mbuf_lib.rst | 23 +++++++++++++++++++++++ > lib/librte_mbuf/rte_mbuf_core.h | 2 ++ > 3 files changed, 41 insertions(+) > > diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst > index d3dd694b65..4b9fb8a84d 100644 > --- a/doc/guides/contributing/design.rst > +++ b/doc/guides/contributing/design.rst > @@ -57,6 +57,22 @@ 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. > +The "dynamic" mbuf area is the default choice for the new features. > + > +The "dynamic" area is eating the remaining space in mbuf, > +and some existing "static" fields may need to become "dynamic". > + > +Adding a new static field or flag must be an exception matching many criterias > +like (non exhaustive): wide usage, performance, size. > + > + > 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 > +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 <rte_mbuf.h> instead. > + * > + * New fields and flags should fit in the "dynamic space". > */ > > #include <stdint.h> > -- > 2.26.2 >