net/bnxt: modify port DB to handle more info

[dpdk.git] / doc / guides / contributing / design.rst

diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst
index 04803ca..5fe7f63 100644 (file)
--- a/doc/guides/contributing/design.rst
+++ b/doc/guides/contributing/design.rst
@@ -1,57 +1,77 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright 2018 The DPDK contributors
+

 Design
 ======
 
 Environment or Architecture-specific Sources
 --------------------------------------------
 
 Design
 ======
 
 Environment or Architecture-specific Sources
 --------------------------------------------
 

-In DPDK and DPDK applications, some code is specific to an architecture (i686, x86_64) or to an executive environment (bsdapp or linuxapp) and so on.
+In DPDK and DPDK applications, some code is specific to an architecture (i686, x86_64) or to an executive environment (freebsd or linux) and so on.

 As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL.
 
 By convention, a file is common if it is not located in a directory indicating that it is specific.
 For instance, a file located in a subdir of "x86_64" directory is specific to this architecture.
 As far as is possible, all such instances of architecture or env-specific code should be provided via standard APIs in the EAL.
 
 By convention, a file is common if it is not located in a directory indicating that it is specific.
 For instance, a file located in a subdir of "x86_64" directory is specific to this architecture.

-A file located in a subdir of "linuxapp" is specific to this execution environment.
+A file located in a subdir of "linux" is specific to this execution environment.

 
 .. note::
 
 
 .. note::
 

-       Code in DPDK libraries and applications should be generic.
-       The correct location for architecture or executive environment specific code is in the EAL.
+   Code in DPDK libraries and applications should be generic.
+   The correct location for architecture or executive environment specific code is in the EAL.

 
 When absolutely necessary, there are several ways to handle specific code:
 
 * Use a ``#ifdef`` with the CONFIG option in the C code.
   This can be done when the differences are small and they can be embedded in the same C file:
 
 
 When absolutely necessary, there are several ways to handle specific code:
 
 * Use a ``#ifdef`` with the CONFIG option in the C code.
   This can be done when the differences are small and they can be embedded in the same C file:
 

-.. code-block: console
+  .. code-block:: c

 
 

-   #ifdef RTE_ARCH_I686
-   toto();
-   #else
-   titi();
-   #endif
+     #ifdef RTE_ARCH_I686
+     toto();
+     #else
+     titi();
+     #endif

 
 * Use the CONFIG option in the Makefile. This is done when the differences are more significant.
 
 * Use the CONFIG option in the Makefile. This is done when the differences are more significant.

-  In this case, the code is split into two separate files that are architecture or environment specific.  This should only apply inside the EAL library.
+  In this case, the code is split into two separate files that are architecture or environment specific.
+  This should only apply inside the EAL library.

 
 

-.. note:
+.. note::

 
 

-       As in the linux kernel, the "CONFIG_" prefix is not used in C code.
-       This is only needed in Makefiles or shell scripts.
+   As in the linux kernel, the ``CONFIG_`` prefix is not used in C code.
+   This is only needed in Makefiles or shell scripts.

 
 Per Architecture Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following config options can be used:
 
 
 Per Architecture Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following config options can be used:
 

-* CONFIG_RTE_ARCH is a string that contains the name of the architecture.
-* CONFIG_RTE_ARCH_I686, CONFIG_RTE_ARCH_X86_64, CONFIG_RTE_ARCH_X86_64_32 or CONFIG_RTE_ARCH_PPC_64 are defined only if we are building for those architectures.
+* ``CONFIG_RTE_ARCH`` is a string that contains the name of the architecture.
+* ``CONFIG_RTE_ARCH_I686``, ``CONFIG_RTE_ARCH_X86_64``, ``CONFIG_RTE_ARCH_X86_64_32`` or ``CONFIG_RTE_ARCH_PPC_64`` are defined only if we are building for those architectures.

 
 Per Execution Environment Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following config options can be used:
 
 
 Per Execution Environment Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 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_BSDAPP or CONFIG_RTE_EXEC_ENV_LINUXAPP are defined only if we are building for this execution environment.
+* ``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
 ------------------
 
 Library Statistics
 ------------------


@@ -77,8 +97,8 @@ are collected for any instance of any object type provided by the library:
 
 .. code-block:: console
 
 
 .. code-block:: console
 

-       # DPDK file config/common_linuxapp, config/common_bsdapp, etc.
-       CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n
+   # DPDK file config/common_linux, config/common_freebsd, etc.
+   CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n

 
 The default value for this DPDK configuration file variable (either "yes" or
 "no") is decided by each library.
 
 The default value for this DPDK configuration file variable (either "yes" or
 "no") is decided by each library.


@@ -157,3 +177,17 @@ cache bandwidth, memory bandwidth, etc) that depends on:
   branches are usually required. When processing a burst of packets that have been
   validated for header integrity, counting the number of bits set in a bitmask
   might be needed.
   branches are usually required. When processing a burst of packets that have been
   validated for header integrity, counting the number of bits set in a bitmask
   might be needed.

+
+PF and VF Considerations
+------------------------
+
+The primary goal of DPDK is to provide a userspace dataplane. Managing VFs from
+a PF driver is a control plane feature and developers should generally rely on
+the Linux Kernel for that.
+
+Developers should work with the Linux Kernel community to get the required
+functionality upstream. PF functionality should only be added to DPDK for
+testing and prototyping purposes while the kernel work is ongoing. It should
+also be marked with an "EXPERIMENTAL" tag. If the functionality isn't
+upstreamable then a case can be made to maintain the PF functionality in DPDK
+without the EXPERIMENTAL tag.