diff mbox series

[v4,31/31] doc: remove references to make from contributing guide

Message ID 20200907220711.437405-32-thomas@monjalon.net (mailing list archive)
State Superseded, archived
Delegated to: Thomas Monjalon
Headers show
Series remove make support in DPDK | expand

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/iol-testing warning Testing issues

Commit Message

Thomas Monjalon Sept. 7, 2020, 10:07 p.m. UTC
From: Ciara Power <ciara.power@intel.com>

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/design.rst        | 127 ++--------------------
 doc/guides/contributing/documentation.rst |  31 +-----
 2 files changed, 13 insertions(+), 145 deletions(-)

Comments

Thomas Monjalon Sept. 8, 2020, 10:16 a.m. UTC | #1
On Tue Sep 8, 2020 at 2:07 AM CEST, Thomas Monjalon wrote:
> From: Ciara Power <ciara.power@intel.com>
> 
> 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/design.rst | 127 ++--------------------
> doc/guides/contributing/documentation.rst | 31 +-----
> 2 files changed, 13 insertions(+), 145 deletions(-)

As reported by David, an update is missing in patches.rst:
	devtools/test-build.sh reference should be removed
diff mbox series

Patch

diff --git a/doc/guides/contributing/design.rst b/doc/guides/contributing/design.rst
index 5fe7f63942..6ce0de97ac 100644
--- a/doc/guides/contributing/design.rst
+++ b/doc/guides/contributing/design.rst
@@ -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
 ------------------------
 
diff --git a/doc/guides/contributing/documentation.rst b/doc/guides/contributing/documentation.rst
index 375ea64ba8..768453126f 100644
--- a/doc/guides/contributing/documentation.rst
+++ b/doc/guides/contributing/documentation.rst
@@ -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.