diff mbox series

[v2] mbuf: document guideline for new fields and flags

Message ID 20200611063229.3591726-1-thomas@monjalon.net (mailing list archive)
State Accepted, archived
Headers show
Series [v2] mbuf: document guideline for new fields and flags | expand

Checks

Context Check Description
ci/Intel-compilation fail apply issues
ci/iol-testing success Testing PASS
ci/iol-mellanox-Performance success Performance Testing PASS
ci/iol-nxp-Performance success Performance Testing PASS
ci/iol-intel-Performance success Performance Testing PASS
ci/iol-broadcom-Performance success Performance Testing PASS
ci/travis-robot success Travis build: passed
ci/checkpatch success coding style OK

Commit Message

Thomas Monjalon June 11, 2020, 6:32 a.m. UTC
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>
---

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(+)

Comments

Jerin Jacob June 11, 2020, 6:37 a.m. UTC | #1
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
>
Thomas Monjalon June 11, 2020, 7:30 a.m. UTC | #2
11/06/2020 08:37, Jerin Jacob:
> 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>

Applied
diff mbox series

Patch

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>