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 CD69DA04AA; Tue, 8 Sep 2020 00:12:49 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id A559F1D169; Tue, 8 Sep 2020 00:08:10 +0200 (CEST) Received: from out1-smtp.messagingengine.com (out1-smtp.messagingengine.com [66.111.4.25]) by dpdk.org (Postfix) with ESMTP id E12081C2B7 for ; Tue, 8 Sep 2020 00:08:04 +0200 (CEST) Received: from compute7.internal (compute7.nyi.internal [10.202.2.47]) by mailout.nyi.internal (Postfix) with ESMTP id 93C2C5C00DA; Mon, 7 Sep 2020 18:08:04 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute7.internal (MEProxy); Mon, 07 Sep 2020 18:08:04 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=monjalon.net; h= from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; s=fm2; bh=3Ojjo6T8qmaLR vYmkL2Rvi9HLsdiRHJonV8KLUDf45o=; b=v+F+b0SyQtEREfEaItF8Fo49HXXb7 RaH8gYqLSaed3KPXOWvA3r+UvVT1jbei4GYUYQQJXHsvB1Qi7ybT5zcIpkJZtZQa Hk/3jvrYATOK03cSY+wOXPva1/lcZqfj1idv65boWb3dcI7p0vYVDnbuaGS9U9jg sH1E6r/1ex3X1LfUSR1F6hPUxMXRBbUkzLiYhDDG4bgZ5E5P9jfydfAGR09lU2iJ ROOD+8No3LuYva9A1R96RTsRu2lM2I1APa+h1HFOEWavBA/YR408FVaHkUvYVrNp +pcbQz/BBz677CqKsEy5RHy26U9hW0gQZJCGBA5P6bMUmDCOuW5BX3fSQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:date:from :in-reply-to:message-id:mime-version:references:subject:to :x-me-proxy:x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s= fm3; bh=3Ojjo6T8qmaLRvYmkL2Rvi9HLsdiRHJonV8KLUDf45o=; b=aGbY6RyG ukf4ITvhmtOKOAUuXGbX93Is5xQc1XHOxGom20uqa9zNp35L1CmaMq0ANQK0P1dK nOwALAN1Nt3E+SUKhHWo9S+rDInM4nhOibhukEbUr3hkdi3r0joOfIMm0MFqkmgx l4ZLpcwpbIAt//5WpKzD1Y/A03yj2HfhP3JrJ02exA4/ZpONfHn1a9q7VQu9zuzN S+M9nb/GUfk8M86/LH8qMAuRCp45BrkSzZpNBP/sSpW7LXCFtZvP52Xo/GohW79O FW8YkrUxHXM42p2YRmy5WFafGP9jTsq4ZwtQgs+8Ctd2I2ZHZHG1L+xEjthHnWik BUKM5yHsjOJMnw== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduiedrudehuddgtdefucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdfqfgfvpdfurfetoffkrfgpnffqhgen uceurghilhhouhhtmecufedttdenucesvcftvggtihhpihgvnhhtshculddquddttddmne cujfgurhephffvufffkffojghfggfgsedtkeertdertddtnecuhfhrohhmpefvhhhomhgr shcuofhonhhjrghlohhnuceothhhohhmrghssehmohhnjhgrlhhonhdrnhgvtheqnecugg ftrfgrthhtvghrnhepvdehgfeivdejgedtveehfefhteelfefgieevgfffveefjeegtdfg uedthedtgeevnecukfhppeejjedrudefgedrvddtfedrudekgeenucevlhhushhtvghruf hiiigvpedufeenucfrrghrrghmpehmrghilhhfrhhomhepthhhohhmrghssehmohhnjhgr lhhonhdrnhgvth X-ME-Proxy: Received: from xps.monjalon.net (184.203.134.77.rev.sfr.net [77.134.203.184]) by mail.messagingengine.com (Postfix) with ESMTPA id B06D3328005E; Mon, 7 Sep 2020 18:08:03 -0400 (EDT) From: Thomas Monjalon To: dev@dpdk.org Cc: david.marchand@redhat.com, bruce.richardson@intel.com, ciara.power@intel.com, Louise Kilheeney Date: Tue, 8 Sep 2020 00:07:11 +0200 Message-Id: <20200907220711.437405-32-thomas@monjalon.net> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200907220711.437405-1-thomas@monjalon.net> References: <20200903152717.42095-1-ciara.power@intel.com> <20200907220711.437405-1-thomas@monjalon.net> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH v4 31/31] doc: remove references to make from contributing guide 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" From: Ciara Power 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/design.rst | 127 ++-------------------- doc/guides/contributing/documentation.rst | 31 +----- 2 files changed, 13 insertions(+), 145 deletions(-) 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. -- 2.28.0