d/numam-dpdk
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

mbuf: document guideline for new fields and flags

Browse Source 
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>
This commit is contained in:
Thomas Monjalon 2020-06-11 08:32:29 +02:00
parent 5fd722308e
commit d1342ea419
3 changed files with 41 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/guides/contributing/design.rst
View File

@ -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 criteria
like (non exhaustive): wide usage, performance, size.
Library Statistics
------------------

23
doc/guides/prog_guide/mbuf_lib.rst
View File

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

2
lib/librte_mbuf/rte_mbuf_core.h
View File

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