[v3,22/37] doc: remove references to make in contributing guides
Checks
Commit Message
Make is no longer supported for compiling DPDK, references are now
removed in the documentation.
Signed-off-by: Ciara Power <ciara.power@intel.com>
Signed-off-by: Louise Kilheeney <louise.kilheeney@intel.com>
---
doc/guides/contributing/coding_style.rst | 46 +-------
doc/guides/contributing/design.rst | 127 ++--------------------
doc/guides/contributing/documentation.rst | 31 +-----
doc/guides/contributing/patches.rst | 45 --------
4 files changed, 18 insertions(+), 231 deletions(-)
Comments
On Thu Sep 3, 2020 at 6:27 PM CEST, Ciara Power wrote:
> --- a/doc/guides/contributing/coding_style.rst
> +++ b/doc/guides/contributing/coding_style.rst
> -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``
We can simply say "DPDK *is* built".
I will add a final dot at the end of the sentence.
> 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.
I think this paragraph does not make sense anymore.
> -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.
[...]
> --- a/doc/guides/contributing/design.rst
> +++ b/doc/guides/contributing/design.rst
> 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.
If removing this last item, there are no "several ways" anymore.
I think we should keep it (reworded) because we still have
files compiled depending on the target architecture.
[...]
> -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.
I think the ABI part is still relevant.
[...]
> -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.
Hi Thomas,
One comment inline.
Thanks,
Ciara
>-----Original Message-----
>From: Thomas Monjalon <thomas@monjalon.net>
>Sent: Monday 7 September 2020 11:21
>To: Power, Ciara <ciara.power@intel.com>; dev@dpdk.org
>Cc: Kilheeney, Louise <louise.kilheeney@intel.com>; Mcnamara, John
><john.mcnamara@intel.com>; Kovacevic, Marko
><marko.kovacevic@intel.com>
>Subject: Re: [dpdk-dev] [PATCH v3 22/37] doc: remove references to make in
>contributing guides
>
<snip>
>[...]
>> -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.
>
>I think the ABI part is still relevant.
Looking for some clarification on this. Which parts (if any) of the library statistics section should be
added back in for the ABI section below to make sense being included? Or what do you suggest doing here?
>[...]
>> -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.
17/09/2020 15:44, Power, Ciara:
> Hi Thomas,
>
> One comment inline.
>
> Thanks,
> Ciara
>
>
> >-----Original Message-----
> >From: Thomas Monjalon <thomas@monjalon.net>
> >Sent: Monday 7 September 2020 11:21
> >To: Power, Ciara <ciara.power@intel.com>; dev@dpdk.org
> >Cc: Kilheeney, Louise <louise.kilheeney@intel.com>; Mcnamara, John
> ><john.mcnamara@intel.com>; Kovacevic, Marko
> ><marko.kovacevic@intel.com>
> >Subject: Re: [dpdk-dev] [PATCH v3 22/37] doc: remove references to make in
> >contributing guides
> >
>
> <snip>
>
> >[...]
> >> -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.
> >
> >I think the ABI part is still relevant.
>
> Looking for some clarification on this. Which parts (if any) of the library statistics section should be
> added back in for the ABI section below to make sense being included? Or what do you suggest doing here?
I think we can consider we still have the ability to turn stats off
because of the #ifdef still being there.
Cristian, do you think we should remove this doc?
Is on/off still possible in the new pipeline libs?
> >[...]
> >> -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.
> -----Original Message-----
> From: Thomas Monjalon <thomas@monjalon.net>
> Sent: Monday, September 21, 2020 5:15 PM
> To: Power, Ciara <ciara.power@intel.com>; Dumitrescu, Cristian
> <cristian.dumitrescu@intel.com>
> Cc: dev@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>;
> Kovacevic, Marko <marko.kovacevic@intel.com>; Richardson, Bruce
> <bruce.richardson@intel.com>
> Subject: Re: [dpdk-dev] [PATCH v3 22/37] doc: remove references to make in
> contributing guides
>
> 17/09/2020 15:44, Power, Ciara:
> > Hi Thomas,
> >
> > One comment inline.
> >
> > Thanks,
> > Ciara
> >
> >
> > >-----Original Message-----
> > >From: Thomas Monjalon <thomas@monjalon.net>
> > >Sent: Monday 7 September 2020 11:21
> > >To: Power, Ciara <ciara.power@intel.com>; dev@dpdk.org
> > >Cc: Kilheeney, Louise <louise.kilheeney@intel.com>; Mcnamara, John
> > ><john.mcnamara@intel.com>; Kovacevic, Marko
> > ><marko.kovacevic@intel.com>
> > >Subject: Re: [dpdk-dev] [PATCH v3 22/37] doc: remove references to
> make in
> > >contributing guides
> > >
> >
> > <snip>
> >
> > >[...]
> > >> -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.
> > >
> > >I think the ABI part is still relevant.
> >
> > Looking for some clarification on this. Which parts (if any) of the library
> statistics section should be
> > added back in for the ABI section below to make sense being included? Or
> what do you suggest doing here?
>
> I think we can consider we still have the ability to turn stats off
> because of the #ifdef still being there.
> Cristian, do you think we should remove this doc?
> Is on/off still possible in the new pipeline libs?
>
Hi Ciara and Thomas,
IMO this section is still relevant and it is unrelated to the topic of this patch set, why do we want to remove it?
From the make removal point of view, we only need the following change, and everything else is still logically valid:
- # DPDK file config/common_linux, config/common_freebsd, etc.
- CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n
+ /* Library API header file. */
+ #define RTE_<LIBRARY_NAME>_STATS_COLLECT
On the larger stats topic, I think the section is still relevant, especially from the point of view of avoiding ABI breakage due to stats, which is applicable to several libraries, so I suggest to keep it.
In the new pipeline libs (rte_swx_pipeline.h API), all the stats are enabled by default.
Regards,
Cristian
>
> > >[...]
> > >> -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.
>
>
Hi Cristian, Thomas,
>-----Original Message-----
>From: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>
>Sent: Monday 21 September 2020 20:14
>To: Thomas Monjalon <thomas@monjalon.net>; Power, Ciara
><ciara.power@intel.com>
>Cc: dev@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>; Kovacevic,
>Marko <marko.kovacevic@intel.com>; Richardson, Bruce
><bruce.richardson@intel.com>
>Subject: RE: [dpdk-dev] [PATCH v3 22/37] doc: remove references to make in
>contributing guides
>
<snip>
>> > >[...]
>> > >> -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.
>> > >
>> > >I think the ABI part is still relevant.
>> >
>> > Looking for some clarification on this. Which parts (if any) of the
>> > library
>> statistics section should be
>> > added back in for the ABI section below to make sense being
>> > included? Or
>> what do you suggest doing here?
>>
>> I think we can consider we still have the ability to turn stats off
>> because of the #ifdef still being there.
>> Cristian, do you think we should remove this doc?
>> Is on/off still possible in the new pipeline libs?
>>
>
>Hi Ciara and Thomas,
>
>IMO this section is still relevant and it is unrelated to the topic of this patch
>set, why do we want to remove it?
>
>From the make removal point of view, we only need the following change,
>and everything else is still logically valid:
>- # DPDK file config/common_linux, config/common_freebsd, etc.
>- CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n
>+ /* Library API header file. */
>+ #define RTE_<LIBRARY_NAME>_STATS_COLLECT
>
>On the larger stats topic, I think the section is still relevant, especially from
>the point of view of avoiding ABI breakage due to stats, which is applicable to
>several libraries, so I suggest to keep it.
>
>In the new pipeline libs (rte_swx_pipeline.h API), all the stats are enabled by
>default.
>
>Regards,
>Cristian
>
I agree the Library Statistics is still relevant, having looked at it again since sending v1.
I sent a v5 of this patchset yesterday just before your feedback here, and kept the full
section but modified the instructions on how to enable/disable, removing the mention
of CONFIG options. Please have a look at those changes here: https://patchwork.dpdk.org/patch/78208/
Thanks,
Ciara
> -----Original Message-----
> From: Power, Ciara <ciara.power@intel.com>
> Sent: Tuesday, September 22, 2020 9:40 AM
> To: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>; Thomas Monjalon
> <thomas@monjalon.net>
> Cc: dev@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>;
> Kovacevic, Marko <marko.kovacevic@intel.com>; Richardson, Bruce
> <bruce.richardson@intel.com>
> Subject: RE: [dpdk-dev] [PATCH v3 22/37] doc: remove references to make in
> contributing guides
>
> Hi Cristian, Thomas,
>
>
> >-----Original Message-----
> >From: Dumitrescu, Cristian <cristian.dumitrescu@intel.com>
> >Sent: Monday 21 September 2020 20:14
> >To: Thomas Monjalon <thomas@monjalon.net>; Power, Ciara
> ><ciara.power@intel.com>
> >Cc: dev@dpdk.org; Mcnamara, John <john.mcnamara@intel.com>;
> Kovacevic,
> >Marko <marko.kovacevic@intel.com>; Richardson, Bruce
> ><bruce.richardson@intel.com>
> >Subject: RE: [dpdk-dev] [PATCH v3 22/37] doc: remove references to make
> in
> >contributing guides
> >
>
> <snip>
>
> >> > >[...]
> >> > >> -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.
> >> > >
> >> > >I think the ABI part is still relevant.
> >> >
> >> > Looking for some clarification on this. Which parts (if any) of the
> >> > library
> >> statistics section should be
> >> > added back in for the ABI section below to make sense being
> >> > included? Or
> >> what do you suggest doing here?
> >>
> >> I think we can consider we still have the ability to turn stats off
> >> because of the #ifdef still being there.
> >> Cristian, do you think we should remove this doc?
> >> Is on/off still possible in the new pipeline libs?
> >>
> >
> >Hi Ciara and Thomas,
> >
> >IMO this section is still relevant and it is unrelated to the topic of this patch
> >set, why do we want to remove it?
> >
> >From the make removal point of view, we only need the following change,
> >and everything else is still logically valid:
> >- # DPDK file config/common_linux, config/common_freebsd, etc.
> >- CONFIG_RTE_<LIBRARY_NAME>_STATS_COLLECT=y/n
> >+ /* Library API header file. */
> >+ #define RTE_<LIBRARY_NAME>_STATS_COLLECT
> >
> >On the larger stats topic, I think the section is still relevant, especially from
> >the point of view of avoiding ABI breakage due to stats, which is applicable
> to
> >several libraries, so I suggest to keep it.
> >
> >In the new pipeline libs (rte_swx_pipeline.h API), all the stats are enabled
> by
> >default.
> >
> >Regards,
> >Cristian
> >
>
> I agree the Library Statistics is still relevant, having looked at it again since
> sending v1.
> I sent a v5 of this patchset yesterday just before your feedback here, and
> kept the full
> section but modified the instructions on how to enable/disable, removing
> the mention
> of CONFIG options. Please have a look at those changes here:
> https://patchwork.dpdk.org/patch/78208/
>
> Thanks,
> Ciara
>
Cool with me, thanks Ciara.
@@ -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,14 @@ Build commands
~~~~~~~~~~~~~~
The documentation is built using the standard DPDK build system.
-Some examples are shown below:
-* Generate all the documentation targets::
+To enable doc building::
- make doc
+ meson configure -Denable_docs=true
-* Generate the Doxygen API documentation in Html::
+See :doc:`../linux_gsg/build_dpdk` for more detail on compiling DPDK with meson.
- 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 +244,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
-------------------
@@ -308,7 +293,7 @@ Line Length
Long literal command lines can be shown wrapped with backslashes. For
example::
- testpmd -l 2-3 -n 4 \
+ dpdk-testpmd -l 2-3 -n 4 \
--vdev=virtio_user0,path=/dev/vhost-net,queues=2,queue_size=1024 \
-- -i --tx-offloads=0x0000002c --enable-lro --txq=2 --rxq=2 \
--txd=1024 --rxd=1024
@@ -460,7 +445,7 @@ Code and Literal block sections
For long literal lines that exceed that limit try to wrap the text at sensible locations.
For example a long command line could be documented like this and still work if copied directly from the docs::
- build/app/testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0 \
+ ./<build_dir>/app/dpdk-testpmd -l 0-2 -n3 --vdev=net_pcap0,iface=eth0 \
--vdev=net_pcap1,iface=eth1 \
-- -i --nb-cores=2 --nb-ports=2 \
--total-num-mbufs=2048
@@ -743,9 +728,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.
@@ -464,51 +464,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
~~~~~~~~~~~~