On Thu, Jun 11, 2020 at 12:02 PM Thomas Monjalon <tho...@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 <tho...@monjalon.net> > Acked-by: Olivier Matz <olivier.m...@6wind.com>
Acked-by: Jerin Jacob <jer...@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 >
