From: Thomas Monjalon <thomas@monjalon.net>
To: dev@dpdk.org
Cc: david.marchand@redhat.com, olivier.matz@6wind.com,
jerinj@marvell.com, ndabilpuram@marvell.com, kkanas@marvell.com,
arybchenko@solarflare.com, ferruh.yigit@intel.com,
bruce.richardson@intel.com,
John McNamara <john.mcnamara@intel.com>,
Marko Kovacevic <marko.kovacevic@intel.com>
Subject: [dpdk-dev] [PATCH] mbuf: document rule for new fields and flags
Date: Mon, 25 May 2020 23:24:15 +0200 [thread overview]
Message-ID: <20200525212415.3173817-1-thomas@monjalon.net> (raw)
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.
+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
+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
next reply other threads:[~2020-05-25 21:24 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-25 21:24 Thomas Monjalon [this message]
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 ` [dpdk-dev] [PATCH v2] mbuf: document guideline " Thomas Monjalon
2020-06-11 6:37 ` 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:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200525212415.3173817-1-thomas@monjalon.net \
--to=thomas@monjalon.net \
--cc=arybchenko@solarflare.com \
--cc=bruce.richardson@intel.com \
--cc=david.marchand@redhat.com \
--cc=dev@dpdk.org \
--cc=ferruh.yigit@intel.com \
--cc=jerinj@marvell.com \
--cc=john.mcnamara@intel.com \
--cc=kkanas@marvell.com \
--cc=marko.kovacevic@intel.com \
--cc=ndabilpuram@marvell.com \
--cc=olivier.matz@6wind.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).