@@ -773,52 +773,16 @@ The ``pep8`` tool can be used for testing compliance with the guidelines.
Integrating with the Build System
---------------------------------
-DPDK supports being built in two different ways:
-
-* using ``make`` - or more specifically "GNU make", i.e. ``gmake`` on FreeBSD
-* using the tools ``meson`` and ``ninja``
+DPDK supports being built by using the tools ``meson`` and ``ninja``
Any new library or driver to be integrated into DPDK should support being
-built with both systems. While building using ``make`` is a legacy approach, and
-most build-system enhancements are being done using ``meson`` and ``ninja``
-there are no plans at this time to deprecate the legacy ``make`` build system.
+built with this system.
-Therefore all new component additions should include both a ``Makefile`` and a
-``meson.build`` file, and should be added to the component lists in both the
-``Makefile`` and ``meson.build`` files in the relevant top-level directory:
+Therefore all new component additions should include a ``meson.build`` file,
+and should be added to the component lists in the ``meson.build`` files in the
+relevant top-level directory:
either ``lib`` directory or a ``driver`` subdirectory.
-Makefile Contents
-~~~~~~~~~~~~~~~~~
-
-The ``Makefile`` for the component should be of the following format, where
-``<name>`` corresponds to the name of the library in question, e.g. hash,
-lpm, etc. For drivers, the same format of Makefile is used.
-
-.. code-block:: none
-
- # pull in basic DPDK definitions, including whether library is to be
- # built or not
- include $(RTE_SDK)/mk/rte.vars.mk
-
- # library name
- LIB = librte_<name>.a
-
- # any library cflags needed. Generally add "-O3 $(WERROR_FLAGS)"
- CFLAGS += -O3
- CFLAGS += $(WERROR_FLAGS)
-
- # the symbol version information for the library
- EXPORT_MAP := rte_<name>_version.map
-
- # all source filenames are stored in SRCS-y
- SRCS-$(CONFIG_RTE_LIBRTE_<NAME>) += rte_<name>.c
-
- # install includes
- SYMLINK-$(CONFIG_RTE_LIBRTE_<NAME>)-include += rte_<name>.h
-
- # pull in rules to build the library
- include $(RTE_SDK)/mk/rte.lib.mk
Meson Build File Contents - Libraries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -21,7 +21,7 @@ A file located in a subdir of "linux" is specific to this execution environment.
When absolutely necessary, there are several ways to handle specific code:
-* Use a ``#ifdef`` with the CONFIG option in the C code.
+* Use a ``#ifdef`` with a build definition macro 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:: c
@@ -32,30 +32,22 @@ When absolutely necessary, there are several ways to handle specific code:
titi();
#endif
-* 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.
-
-.. note::
-
- 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:
+The following macro 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.
+* ``RTE_ARCH`` is a string that contains the name of the architecture.
+* ``RTE_ARCH_I686``, ``RTE_ARCH_X86_64``, ``RTE_ARCH_X86_64_32`` or ``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:
+The following macro 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.
+* ``RTE_EXEC_ENV`` is a string that contains the name of the executive environment.
+* ``RTE_EXEC_ENV_FREEBSD`` or ``RTE_EXEC_ENV_LINUX`` are defined only if we are building for this execution environment.
Mbuf features
-------------
@@ -73,111 +65,6 @@ Adding a new static field or flag must be an exception matching many criteria
like (non exhaustive): wide usage, performance, size.
-Library Statistics
-------------------
-
-Description
-~~~~~~~~~~~
-
-This document describes the guidelines for DPDK library-level statistics counter
-support. This includes guidelines for turning library statistics on and off and
-requirements for preventing ABI changes when implementing statistics.
-
-
-Mechanism to allow the application to turn library statistics on and off
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Each library that maintains statistics counters should provide a single build
-time flag that decides whether the statistics counter collection is enabled or
-not. This flag should be exposed as a variable within the DPDK configuration
-file. When this flag is set, all the counters supported by current library are
-collected for all the instances of every object type provided by the library.
-When this flag is cleared, none of the counters supported by the current library
-are collected for any instance of any object type provided by the library:
-
-.. code-block:: console
-
- # 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.
-
-
-Prevention of ABI changes due to library statistics support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The layout of data structures and prototype of functions that are part of the
-library API should not be affected by whether the collection of statistics
-counters is turned on or off for the current library. In practical terms, this
-means that space should always be allocated in the API data structures for
-statistics counters and the statistics related API functions are always built
-into the code, regardless of whether the statistics counter collection is turned
-on or off for the current library.
-
-When the collection of statistics counters for the current library is turned
-off, the counters retrieved through the statistics related API functions should
-have a default value of zero.
-
-
-Motivation to allow the application to turn library statistics on and off
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-It is highly recommended that each library provides statistics counters to allow
-an application to monitor the library-level run-time events. Typical counters
-are: number of packets received/dropped/transmitted, number of buffers
-allocated/freed, number of occurrences for specific events, etc.
-
-However, the resources consumed for library-level statistics counter collection
-have to be spent out of the application budget and the counters collected by
-some libraries might not be relevant to the current application. In order to
-avoid any unwanted waste of resources and/or performance impacts, the
-application should decide at build time whether the collection of library-level
-statistics counters should be turned on or off for each library individually.
-
-Library-level statistics counters can be relevant or not for specific
-applications:
-
-* For Application A, counters maintained by Library X are always relevant and
- the application needs to use them to implement certain features, such as traffic
- accounting, logging, application-level statistics, etc. In this case,
- the application requires that collection of statistics counters for Library X is
- always turned on.
-
-* For Application B, counters maintained by Library X are only useful during the
- application debug stage and are not relevant once debug phase is over. In this
- case, the application may decide to turn on the collection of Library X
- statistics counters during the debug phase and at a later stage turn them off.
-
-* For Application C, counters maintained by Library X are not relevant at all.
- It might be that the application maintains its own set of statistics counters
- that monitor a different set of run-time events (e.g. number of connection
- requests, number of active users, etc). It might also be that the application
- uses multiple libraries (Library X, Library Y, etc) and it is interested in the
- statistics counters of Library Y, but not in those of Library X. In this case,
- the application may decide to turn the collection of statistics counters off for
- Library X and on for Library Y.
-
-The statistics collection consumes a certain amount of CPU resources (cycles,
-cache bandwidth, memory bandwidth, etc) that depends on:
-
-* Number of libraries used by the current application that have statistics
- counters collection turned on.
-
-* Number of statistics counters maintained by each library per object type
- instance (e.g. per port, table, pipeline, thread, etc).
-
-* Number of instances created for each object type supported by each library.
-
-* Complexity of the statistics logic collection for each counter: when only
- some occurrences of a specific event are valid, additional logic is typically
- needed to decide whether the current occurrence of the event should be counted
- or not. For example, in the event of packet reception, when only TCP packets
- with destination port within a certain range should be recorded, conditional
- 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
------------------------
@@ -222,25 +222,8 @@ Build commands
~~~~~~~~~~~~~~
The documentation is built using the standard DPDK build system.
-Some examples are shown below:
-* Generate all the documentation targets::
-
- make doc
-
-* Generate the Doxygen API documentation in Html::
-
- make doc-api-html
-
-* Generate the guides documentation in Html::
-
- make doc-guides-html
-
-* Generate the guides documentation in Pdf::
-
- make doc-guides-pdf
-
-The output of these commands is generated in the ``build`` directory::
+The output is generated in the ``build`` directory::
build/doc
|-- html
@@ -255,10 +238,6 @@ The output of these commands is generated in the ``build`` directory::
Make sure to fix any Sphinx or Doxygen warnings when adding or updating documentation.
-The documentation output files can be removed as follows::
-
- make doc-clean
-
Document Guidelines
-------------------
@@ -743,9 +722,5 @@ The following are some guidelines for use of Doxygen in the DPDK API documentati
/** Array of physical page addresses for the mempool buffer. */
phys_addr_t elt_pa[MEMPOOL_PG_NUM_DEFAULT];
-* Check for Doxygen warnings in new code by checking the API documentation build::
-
- make doc-api-html >/dev/null
-
* Read the rendered section of the documentation that you have added for correctness, clarity and consistency
with the surrounding text.
@@ -463,51 +463,6 @@ and the -r option allows the user specify a ``git log`` range.
Checking Compilation
--------------------
-Makefile System
-~~~~~~~~~~~~~~~
-
-Compilation of patches and changes should be tested using the ``test-build.sh`` script in the ``devtools``
-directory of the DPDK repo::
-
- devtools/test-build.sh x86_64-native-linux-gcc+next+shared
-
-The script usage is::
-
- test-build.sh [-h] [-jX] [-s] [config1 [config2] ...]]
-
-Where:
-
-* ``-h``: help, usage.
-* ``-jX``: use X parallel jobs in "make".
-* ``-s``: short test with only first config and without examples/doc.
-* ``config``: default config name plus config switches delimited with a ``+`` sign.
-
-Examples of configs are::
-
- x86_64-native-linux-gcc
- x86_64-native-linux-gcc+next+shared
- x86_64-native-linux-clang+shared
-
-The builds can be modified via the following environmental variables:
-
-* ``DPDK_BUILD_TEST_CONFIGS`` (target1+option1+option2 target2)
-* ``DPDK_BUILD_TEST_DIR``
-* ``DPDK_DEP_CFLAGS``
-* ``DPDK_DEP_LDFLAGS``
-* ``DPDK_DEP_PCAP`` (y/[n])
-* ``DPDK_NOTIFY`` (notify-send)
-
-These can be set from the command line or in the config files shown above in the :ref:`contrib_checkpatch`.
-
-The recommended configurations and options to test compilation prior to submitting patches are::
-
- x86_64-native-linux-gcc+shared+next
- x86_64-native-linux-clang+shared
- i686-native-linux-gcc
-
- export DPDK_DEP_ZLIB=y
- export DPDK_DEP_PCAP=y
- export DPDK_DEP_SSL=y
Meson System
~~~~~~~~~~~~