From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 3D247A04BF; Thu, 3 Sep 2020 17:34:02 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 9A16E1C1D8; Thu, 3 Sep 2020 17:29:02 +0200 (CEST) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id AD3FC1C1D0 for ; Thu, 3 Sep 2020 17:29:00 +0200 (CEST) IronPort-SDR: 1Lh7JHbMj437XuZNqRFk2dUZXFJkjmqRF1VBYtCn9Lyz/Cejt92+X0rjOGTqNmD6yWhy+xaH4y 1FrVsf/jwh8Q== X-IronPort-AV: E=McAfee;i="6000,8403,9733"; a="145290730" X-IronPort-AV: E=Sophos;i="5.76,387,1592895600"; d="scan'208";a="145290730" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga006.jf.intel.com ([10.7.209.51]) by orsmga106.jf.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 03 Sep 2020 08:29:00 -0700 IronPort-SDR: L0d8yftMxj3+ygp+XggHqcNyNgEaoEO+2Uy3zUM4hD7lZkWeQwXOMyKex1W6NNyhlV99QeMA7Z Q5V/+7WAvH6A== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.76,387,1592895600"; d="scan'208";a="302244046" Received: from silpixa00399953.ir.intel.com (HELO silpixa00399953.ger.corp.intel.com) ([10.237.222.53]) by orsmga006.jf.intel.com with ESMTP; 03 Sep 2020 08:28:58 -0700 From: Ciara Power To: dev@dpdk.org Cc: Ciara Power , Louise Kilheeney , John McNamara , Marko Kovacevic Date: Thu, 3 Sep 2020 16:27:02 +0100 Message-Id: <20200903152717.42095-23-ciara.power@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200903152717.42095-1-ciara.power@intel.com> References: <20200807123009.21266-1-ciara.power@intel.com> <20200903152717.42095-1-ciara.power@intel.com> Subject: [dpdk-dev] [PATCH v3 22/37] doc: remove references to make in contributing guides X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Make is no longer supported for compiling DPDK, references are now removed in the documentation. Signed-off-by: Ciara Power Signed-off-by: Louise Kilheeney --- 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(-) diff --git a/doc/guides/contributing/coding_style.rst b/doc/guides/contributing/coding_style.rst index b55075eaa2..dc352d03ca 100644 --- a/doc/guides/contributing/coding_style.rst +++ b/doc/guides/contributing/coding_style.rst @@ -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 -```` 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_.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__version.map - - # all source filenames are stored in SRCS-y - SRCS-$(CONFIG_RTE_LIBRTE_) += rte_.c - - # install includes - SYMLINK-$(CONFIG_RTE_LIBRTE_)-include += rte_.h - - # pull in rules to build the library - include $(RTE_SDK)/mk/rte.lib.mk Meson Build File Contents - Libraries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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__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 \ + .//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. diff --git a/doc/guides/contributing/patches.rst b/doc/guides/contributing/patches.rst index 425bb874f8..bafa95be59 100644 --- a/doc/guides/contributing/patches.rst +++ b/doc/guides/contributing/patches.rst @@ -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 ~~~~~~~~~~~~ -- 2.17.1