DPDK patches and discussions
 help / color / mirror / Atom feed
From: Thomas Monjalon <thomas@monjalon.net>
To: dev@dpdk.org
Cc: techboard@dpdk.org, Olivier Matz <olivier.matz@6wind.com>,
	John McNamara <john.mcnamara@intel.com>,
	Marko Kovacevic <marko.kovacevic@intel.com>
Subject: [dpdk-dev] [PATCH v2] mbuf: document guideline for new fields and flags
Date: Thu, 11 Jun 2020 08:32:29 +0200
Message-ID: <20200611063229.3591726-1-thomas@monjalon.net> (raw)
In-Reply-To: <20200525212415.3173817-1-thomas@monjalon.net>

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

This decision was discussed in the Technical Board:

Signed-off-by: Thomas Monjalon <thomas@monjalon.net>
Acked-by: Olivier Matz <olivier.matz@6wind.com>

	- 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>

  parent reply	other threads:[~2020-06-11  6:32 UTC|newest]

Thread overview: 15+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-25 21:24 [dpdk-dev] [PATCH] mbuf: document rule " Thomas Monjalon
2020-05-26  7:39 ` Jerin Jacob
2020-05-26 16:06   ` Olivier Matz
2020-05-26 16:29     ` Jerin Jacob
2020-05-27  7:09       ` Olivier Matz
2020-05-27  7:31         ` Jerin Jacob
2020-05-27  9:51           ` Thomas Monjalon
2020-05-27 11:43             ` Jerin Jacob
2020-05-27 11:56               ` Thomas Monjalon
2020-05-27 12:07                 ` Jerin Jacob
2020-05-27 12:23                   ` Olivier Matz
2020-05-27 12:34                     ` Jerin Jacob
2020-06-11  6:32 ` Thomas Monjalon [this message]
2020-06-11  6:37   ` [dpdk-dev] [PATCH v2] mbuf: document guideline " Jerin Jacob
2020-06-11  7:30     ` Thomas Monjalon

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200611063229.3591726-1-thomas@monjalon.net \
    --to=thomas@monjalon.net \
    --cc=dev@dpdk.org \
    --cc=john.mcnamara@intel.com \
    --cc=marko.kovacevic@intel.com \
    --cc=olivier.matz@6wind.com \
    --cc=techboard@dpdk.org \


* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

DPDK patches and discussions

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://inbox.dpdk.org/dev/0 dev/git/0.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 dev dev/ https://inbox.dpdk.org/dev \
	public-inbox-index dev

Example config snippet for mirrors.
Newsgroup available over NNTP:

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git