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 4BFDEA04A4;
	Tue, 26 May 2020 09:39:56 +0200 (CEST)
Received: from [92.243.14.124] (localhost [127.0.0.1])
	by dpdk.org (Postfix) with ESMTP id B9A391D970;
	Tue, 26 May 2020 09:39:55 +0200 (CEST)
Received: from mail-io1-f66.google.com (mail-io1-f66.google.com
 [209.85.166.66]) by dpdk.org (Postfix) with ESMTP id EEB591D95F
 for <dev@dpdk.org>; Tue, 26 May 2020 09:39:54 +0200 (CEST)
Received: by mail-io1-f66.google.com with SMTP id f3so20960321ioj.1
 for <dev@dpdk.org>; Tue, 26 May 2020 00:39:54 -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=Oo2ri8E6oGgY+IWy/56nNkBANtZX46Lx4h8v4NA0Vcw=;
 b=hGcK0aX3weF1+YZXkAo6iM29/i3dhzueLlqP8QylVNdHLKIyfTYvKJpFlhaxL29ai8
 aVkb4ttP3eDgrZ8utacRwrMmLycBwhasqrvMtoVqlMF1rVgBKUfp3KL5mMUmd7mId7IU
 uafWoyOh9/tjjjCodcT7Gnekb8f8TxmSaj59Rvn5nO0ETyRI49VXprW6A8SjZqm3BnQK
 4krUNADXqA+UviQ9fW2YynC0q5lyaIR3/MLG623XF4Y20m9wEzPMUEcrl373p4aUwHYt
 0rxO7pPqEZdqmAYQyBkNawT7otfKx0y8s1ir1ZA5b1bQ3O6ligb4uTq8gaTz4hkXNlRm
 gdBQ==
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=Oo2ri8E6oGgY+IWy/56nNkBANtZX46Lx4h8v4NA0Vcw=;
 b=Weq5eEAdII7Mz9Kl3ALsG+JYQhiSX0x0BOif/D/PY26fqlfQoZiu++yK2TuJQ7Y7uh
 gRq7FrpCZ5JQPOMvQyIbcYdvtZ624YPwsb4CphozXvixpWrQ4FVccrLRVCTdxtNb1Y8/
 QApXAsy45BUjj5iOnvqUP+MeKH6aJgVlJtXiKHE4BxgdZ+vk7BIKV7Awpn/boxsSwTZ2
 U0lHVMaHcV2vVzOLT/IGW8yxNGxDWIEqbEMO8jdda5/+XzfTFJgIYgHN9nEcS65g5TS0
 XQrJrKXs+ZTVOVeiqNfl/7jFsLDEhRGDMU4Z1bMxxp7gwMZ89Qqh26fdW3bECz2gl5No
 wQ8g==
X-Gm-Message-State: AOAM533oxhjrIAFXyZryeK7/UClclH1UB33praDOhySdNqHWAd3FlGG8
 8DCu2CwEIw6tVaKn03iniSpjcxG793MtUYpD0Hk=
X-Google-Smtp-Source: ABdhPJxmSb1mfa8KabtWU02NsuHaHm4mFEL+CRwj2oRNRmV8DTXhapuKcqLvWZv4XzvEY4ubD7xoSjx4tAeCqQWPZXY=
X-Received: by 2002:a02:6d0a:: with SMTP id m10mr14158525jac.133.1590478793748; 
 Tue, 26 May 2020 00:39:53 -0700 (PDT)
MIME-Version: 1.0
References: <20200525212415.3173817-1-thomas@monjalon.net>
In-Reply-To: <20200525212415.3173817-1-thomas@monjalon.net>
From: Jerin Jacob <jerinjacobk@gmail.com>
Date: Tue, 26 May 2020 13:09:37 +0530
Message-ID: <CALBAE1MTmsO=_N3Ui2SY_z57k6gKpPORVLZ4EwaZ9vpHRHXomg@mail.gmail.com>
To: Thomas Monjalon <thomas@monjalon.net>
Cc: dpdk-dev <dev@dpdk.org>, David Marchand <david.marchand@redhat.com>, 
 Olivier Matz <olivier.matz@6wind.com>, Jerin Jacob <jerinj@marvell.com>, 
 Nithin Dabilpuram <ndabilpuram@marvell.com>,
 Krzysztof Kanas <kkanas@marvell.com>, 
 Andrew Rybchenko <arybchenko@solarflare.com>,
 Ferruh Yigit <ferruh.yigit@intel.com>, 
 "Richardson, Bruce" <bruce.richardson@intel.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] 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 <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 Tue, May 26, 2020 at 2:54 AM 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 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 <thomas@monjalon.net>
> ---
>  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.
> +
> +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.

> +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".

must use.

>   */
>
>  #include <stdint.h>
> --
> 2.26.2
>