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 A47C2A04B0; Fri, 7 Aug 2020 14:41:59 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 0A67C1C1AD; Fri, 7 Aug 2020 14:38:06 +0200 (CEST) Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by dpdk.org (Postfix) with ESMTP id 8AC6E1C18E for ; Fri, 7 Aug 2020 14:38:02 +0200 (CEST) IronPort-SDR: ROeJ9aoDboFtL4ft1W6SueAP2MsPlPggwjrST3myC1DNvp4eZEMMRb8HOJxCJnSINI9kpWVuW4 wL4a8Y56bHIg== X-IronPort-AV: E=McAfee;i="6000,8403,9705"; a="152298298" X-IronPort-AV: E=Sophos;i="5.75,445,1589266800"; d="scan'208";a="152298298" X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga001.jf.intel.com ([10.7.209.18]) by fmsmga103.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 07 Aug 2020 05:38:01 -0700 IronPort-SDR: UG9ZVeQ9HPQB9SxKyPTV/inyGzX7935FjjKEPgqDh6RSHCNk6MPRmv8GBBANWBH0fjkL6klJxg 5bv6p3zq3nZQ== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.75,445,1589266800"; d="scan'208";a="367914596" Received: from silpixa00399953.ir.intel.com (HELO silpixa00399953.ger.corp.intel.com) ([10.237.222.53]) by orsmga001.jf.intel.com with ESMTP; 07 Aug 2020 05:38:00 -0700 From: Ciara Power To: dev@dpdk.org Cc: bruce.richardson@intel.com, thomas@monjalon.net, Ciara Power Date: Fri, 7 Aug 2020 13:30:06 +0100 Message-Id: <20200807123009.21266-17-ciara.power@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200807123009.21266-1-ciara.power@intel.com> References: <20200807123009.21266-1-ciara.power@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] [PATCH 20.11 16/19] doc: remove references to make in prog 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 --- doc/guides/prog_guide/build_app.rst | 46 +--- .../prog_guide/dev_kit_build_system.rst | 218 +----------------- .../prog_guide/dev_kit_root_make_help.rst | 188 --------------- .../prog_guide/env_abstraction_layer.rst | 17 +- .../prog_guide/ext_app_lib_make_help.rst | 25 +- doc/guides/prog_guide/graph_lib.rst | 6 +- doc/guides/prog_guide/intro.rst | 2 +- .../prog_guide/ip_fragment_reassembly_lib.rst | 5 - .../link_bonding_poll_mode_drv_lib.rst | 5 - doc/guides/prog_guide/lto.rst | 13 +- doc/guides/prog_guide/mbuf_lib.rst | 4 +- doc/guides/prog_guide/mempool_lib.rst | 7 +- doc/guides/prog_guide/overview.rst | 12 +- doc/guides/prog_guide/profile_app.rst | 15 +- doc/guides/prog_guide/qos_framework.rst | 10 +- doc/guides/prog_guide/rcu_lib.rst | 7 +- doc/guides/prog_guide/source_org.rst | 23 +- doc/guides/prog_guide/trace_lib.rst | 3 +- .../prog_guide/writing_efficient_code.rst | 3 +- 19 files changed, 36 insertions(+), 573 deletions(-) delete mode 100644 doc/guides/prog_guide/dev_kit_root_make_help.rst diff --git a/doc/guides/prog_guide/build_app.rst b/doc/guides/prog_guide/build_app.rst index bffa55bbef..54e4283752 100644 --- a/doc/guides/prog_guide/build_app.rst +++ b/doc/guides/prog_guide/build_app.rst @@ -9,14 +9,11 @@ Building Your Own Application Compiling a Sample Application in the Development Kit Directory --------------------------------------------------------------- -When compiling a sample application (for example, hello world), the following variables must be exported: -RTE_SDK and RTE_TARGET. +To compile a sample application (for example, hello world): .. code-block:: console ~/DPDK$ cd examples/helloworld/ - ~/DPDK/examples/helloworld$ export RTE_SDK=/home/user/DPDK - ~/DPDK/examples/helloworld$ export RTE_TARGET=x86_64-native-linux-gcc ~/DPDK/examples/helloworld$ make CC main.o LD helloworld @@ -39,8 +36,6 @@ The sample application (Hello World) can be duplicated in a new directory as a s ~$ cp -r DPDK/examples/helloworld my_rte_app ~$ cd my_rte_app/ - ~/my_rte_app$ export RTE_SDK=/home/user/DPDK - ~/my_rte_app$ export RTE_TARGET=x86_64-native-linux-gcc ~/my_rte_app$ make CC main.o LD helloworld @@ -53,47 +48,10 @@ Customizing Makefiles Application Makefile ~~~~~~~~~~~~~~~~~~~~ -The default makefile provided with the Hello World sample application is a good starting point. It includes: - -* $(RTE_SDK)/mk/rte.vars.mk at the beginning - -* $(RTE_SDK)/mk/rte.extapp.mk at the end +The default makefile provided with the Hello World sample application is a good starting point. The user must define several variables: * APP: Contains the name of the application. * SRCS-y: List of source files (\*.c, \*.S). - -Library Makefile -~~~~~~~~~~~~~~~~ - -It is also possible to build a library in the same way: - -* Include $(RTE_SDK)/mk/rte.vars.mk at the beginning. - -* Include $(RTE_SDK)/mk/rte.extlib.mk at the end. - -The only difference is that APP should be replaced by LIB, which contains the name of the library. For example, libfoo.a. - -Customize Makefile Actions -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some variables can be defined to customize Makefile actions. The most common are listed below. Refer to -:ref:`Makefile Description ` section in -:ref:`Development Kit Build System ` - -chapter for details. - -* VPATH: The path list where the build system will search for sources. By default, - RTE_SRCDIR will be included in VPATH. - -* CFLAGS_my_file.o: The specific flags to add for C compilation of my_file.c. - -* CFLAGS: The flags to use for C compilation. - -* LDFLAGS: The flags to use for linking. - -* CPPFLAGS: The flags to use to provide flags to the C preprocessor (only useful when assembling .S files) - -* LDLIBS: A list of libraries to link with (for example, -L /path/to/libfoo - lfoo) diff --git a/doc/guides/prog_guide/dev_kit_build_system.rst b/doc/guides/prog_guide/dev_kit_build_system.rst index 74dba4dd16..91d2120e22 100644 --- a/doc/guides/prog_guide/dev_kit_build_system.rst +++ b/doc/guides/prog_guide/dev_kit_build_system.rst @@ -31,51 +31,17 @@ Each build directory contains include files, libraries, and applications. A build directory is specific to a configuration that includes architecture + execution environment + toolchain. It is possible to have several build directories sharing the same sources with different configurations. -For instance, to create a new build directory called my_sdk_build_dir using the default configuration template config/defconfig_x86_64-linux, -we use: - -.. code-block:: console - - cd ${RTE_SDK} - make config T=x86_64-native-linux-gcc O=my_sdk_build_dir - -This creates a new my_sdk_build_dir directory. After that, we can compile by doing: - -.. code-block:: console - - cd my_sdk_build_dir - make - -which is equivalent to: - -.. code-block:: console - - make O=my_sdk_build_dir - -Refer to -:ref:`Development Kit Root Makefile Help ` -for details about make commands that can be used from the root of DPDK. Building External Applications ------------------------------ Since DPDK is in essence a development kit, the first objective of end users will be to create an application using this SDK. -To compile an application, the user must set the RTE_SDK and RTE_TARGET environment variables. - -.. code-block:: console - export RTE_SDK=/opt/DPDK - export RTE_TARGET=x86_64-native-linux-gcc - cd /path/to/my_app - -For a new application, the user must create their own Makefile that includes some .mk files, such as -${RTE_SDK}/mk/rte.vars.mk, and ${RTE_SDK}/mk/ rte.app.mk. -This is described in +For a new application, the user must create their own Makefile. This is described in :ref:`Building Your Own Application `. -Depending on the chosen target (architecture, machine, executive environment, toolchain) defined in the Makefile or as an environment variable, -the applications and libraries will compile using the appropriate .h files and will link with the appropriate .a files. -These files are located in ${RTE_SDK}/arch-machine-execenv-toolchain, which is referenced internally by ${RTE_BIN_SDK}. +Depending on the chosen target (architecture, machine, executive environment, toolchain) defined, the applications and +libraries will compile using the appropriate .h files and will link with the appropriate .a files. To compile their application, the user just has to call make. The compilation result will be located in /path/to/my_app/build directory. @@ -90,92 +56,18 @@ Makefile Description General Rules For DPDK Makefiles ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In the DPDK, Makefiles always follow the same scheme: - -#. Include $(RTE_SDK)/mk/rte.vars.mk at the beginning. - -#. Define specific variables for RTE build system. - -#. Include a specific $(RTE_SDK)/mk/rte.XYZ.mk, where XYZ can be app, lib, extapp, extlib, obj, gnuconfigure, - and so on, depending on what kind of object you want to build. - :ref:`See Makefile Types ` below. - -#. Include user-defined rules and variables. +In the DPDK, Makefiles always define specific variables for RTE build system. The following is a very simple example of an external application Makefile: .. code-block:: make - include $(RTE_SDK)/mk/rte.vars.mk - # binary name APP = helloworld # all source are stored in SRCS-y SRCS-y := main.c - CFLAGS += -O3 - CFLAGS += $(WERROR_FLAGS) - - include $(RTE_SDK)/mk/rte.extapp.mk - -.. _Makefile_Types: - -Makefile Types -~~~~~~~~~~~~~~ - -Depending on the .mk file which is included at the end of the user Makefile, the Makefile will have a different role. -Note that it is not possible to build a library and an application in the same Makefile. -For that, the user must create two separate Makefiles, possibly in two different directories. - -In any case, the rte.vars.mk file must be included in the user Makefile as soon as possible. - -Application -^^^^^^^^^^^ - -These Makefiles generate a binary application. - -* rte.app.mk: Application in the development kit framework - -* rte.extapp.mk: External application - -* rte.hostapp.mk: prerequisite tool to build dpdk - -Library -^^^^^^^ - -Generate a .a library. - -* rte.lib.mk: Library in the development kit framework - -* rte.extlib.mk: external library - -* rte.hostlib.mk: host library in the development kit framework - -Install -^^^^^^^ - -* rte.install.mk: Does not build anything, it is only used to create links or copy files to the installation directory. - This is useful for including files in the development kit framework. - -Kernel Module -^^^^^^^^^^^^^ - -* rte.module.mk: Build a kernel module in the development kit framework. - -Objects -^^^^^^^ - -* rte.obj.mk: Object aggregation (merge several .o in one) in the development kit framework. - -* rte.extobj.mk: Object aggregation (merge several .o in one) outside the development kit framework. - -Misc -^^^^ - -* rte.gnuconfigure.mk: Build an application that is configure-based. - -* rte.subdir.mk: Build several directories in the development kit framework. .. _Internally_Generated_Build_Tools: @@ -220,112 +112,10 @@ hardware support of a given library or application. Useful Variables Provided by the Build System ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* RTE_SDK: The absolute path to the DPDK sources. - When compiling the development kit, this variable is automatically set by the framework. - It has to be defined by the user as an environment variable if compiling an external application. - -* RTE_SRCDIR: The path to the root of the sources. When compiling the development kit, RTE_SRCDIR = RTE_SDK. - When compiling an external application, the variable points to the root of external application sources. - -* RTE_OUTPUT: The path to which output files are written. - Typically, it is $(RTE_SRCDIR)/build, but it can be overridden by the O= option in the make command line. - -* RTE_TARGET: A string identifying the target for which we are building. - The format is arch-machine-execenv-toolchain. - When compiling the SDK, the target is deduced by the build system from the configuration (.config). - When building an external application, it must be specified by the user in the Makefile or as an environment variable. - -* RTE_SDK_BIN: References $(RTE_SDK)/$(RTE_TARGET). - * RTE_ARCH: Defines the architecture (i686, x86_64). - It is the same value as CONFIG_RTE_ARCH but without the double-quotes around the string. * RTE_MACHINE: Defines the machine. - It is the same value as CONFIG_RTE_MACHINE but without the double-quotes around the string. * RTE_TOOLCHAIN: Defines the toolchain (gcc , icc). - It is the same value as CONFIG_RTE_TOOLCHAIN but without the double-quotes around the string. * RTE_EXEC_ENV: Defines the executive environment (linux). - It is the same value as CONFIG_RTE_EXEC_ENV but without the double-quotes around the string. - -* RTE_KERNELDIR: This variable contains the absolute path to the kernel sources that will be used to compile the kernel modules. - The kernel headers must be the same as the ones that will be used on the target machine (the machine that will run the application). - By default, the variable is set to /lib/modules/$(shell uname -r)/build, - which is correct when the target machine is also the build machine. - -* RTE_DEVEL_BUILD: Stricter options (stop on warning). It defaults to y in a git tree. - -Variables that Can be Set/Overridden in a Makefile Only -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* VPATH: The path list that the build system will search for sources. By default, RTE_SRCDIR will be included in VPATH. - -* CFLAGS: Flags to use for C compilation. The user should use += to append data in this variable. - -* LDFLAGS: Flags to use for linking. The user should use += to append data in this variable. - -* ASFLAGS: Flags to use for assembly. The user should use += to append data in this variable. - -* CPPFLAGS: Flags to use to give flags to C preprocessor (only useful when assembling .S files). - The user should use += to append data in this variable. - -* LDLIBS: In an application, the list of libraries to link with (for example, -L /path/to/libfoo -lfoo ). - The user should use += to append data in this variable. - -* SRC-y: A list of source files (.c, .S, or .o if the source is a binary) in case of application, library or object Makefiles. - The sources must be available from VPATH. - -* INSTALL-y-$(INSTPATH): A list of files to be installed in $(INSTPATH). - The files must be available from VPATH and will be copied in $(RTE_OUTPUT)/$(INSTPATH). Can be used in almost any RTE Makefile. - -* SYMLINK-y-$(INSTPATH): A list of files to be installed in $(INSTPATH). - The files must be available from VPATH and will be linked (symbolically) in $(RTE_OUTPUT)/$(INSTPATH). - This variable can be used in almost any DPDK Makefile. - -* PREBUILD: A list of prerequisite actions to be taken before building. The user should use += to append data in this variable. - -* POSTBUILD: A list of actions to be taken after the main build. The user should use += to append data in this variable. - -* PREINSTALL: A list of prerequisite actions to be taken before installing. The user should use += to append data in this variable. - -* POSTINSTALL: A list of actions to be taken after installing. The user should use += to append data in this variable. - -* PRECLEAN: A list of prerequisite actions to be taken before cleaning. The user should use += to append data in this variable. - -* POSTCLEAN: A list of actions to be taken after cleaning. The user should use += to append data in this variable. - -* DEPDIRS-$(DIR): Only used in the development kit framework to specify if the build of the current directory depends on build of another one. - This is needed to support parallel builds correctly. - -Variables that can be Set/Overridden by the User on the Command Line Only -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some variables can be used to configure the build system behavior. They are documented in -:ref:`Development Kit Root Makefile Help ` and -:ref:`External Application/Library Makefile Help ` - - * WERROR_CFLAGS: By default, this is set to a specific value that depends on the compiler. - Users are encouraged to use this variable as follows: - - CFLAGS += $(WERROR_CFLAGS) - -This avoids the use of different cases depending on the compiler (icc or gcc). -Also, this variable can be overridden from the command line, which allows bypassing of the flags for testing purposes. - -Variables that Can be Set/Overridden by the User in a Makefile or Command Line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -* CFLAGS_my_file.o: Specific flags to add for C compilation of my_file.c. - -* LDFLAGS_my_app: Specific flags to add when linking my_app. - -* EXTRA_CFLAGS: The content of this variable is appended after CFLAGS when compiling. - -* EXTRA_LDFLAGS: The content of this variable is appended after LDFLAGS when linking. - -* EXTRA_LDLIBS: The content of this variable is appended after LDLIBS when linking. - -* EXTRA_ASFLAGS: The content of this variable is appended after ASFLAGS when assembling. - -* EXTRA_CPPFLAGS: The content of this variable is appended after CPPFLAGS when using a C preprocessor on assembly files. diff --git a/doc/guides/prog_guide/dev_kit_root_make_help.rst b/doc/guides/prog_guide/dev_kit_root_make_help.rst deleted file mode 100644 index a30db7d5b4..0000000000 --- a/doc/guides/prog_guide/dev_kit_root_make_help.rst +++ /dev/null @@ -1,188 +0,0 @@ -.. SPDX-License-Identifier: BSD-3-Clause - Copyright(c) 2010-2014 Intel Corporation. - -.. _Development_Kit_Root_Makefile_Help: - -Development Kit Root Makefile Help -================================== - -The DPDK provides a root level Makefile with targets for configuration, building, cleaning, testing, installation and others. -These targets are explained in the following sections. - -Configuration Targets ---------------------- - -The configuration target requires the name of the target, which is specified using T=mytarget and it is mandatory. -The list of available targets are in $(RTE_SDK)/config (remove the defconfig _ prefix). - -Configuration targets also support the specification of the name of the output directory, using O=mybuilddir. -This is an optional parameter, the default output directory is build. - -* Config - - This will create a build directory, and generates a configuration from a template. - A Makefile is also created in the new build directory. - - Example: - - .. code-block:: console - - make config O=mybuild T=x86_64-native-linux-gcc - -Build Targets -------------- - -Build targets support the optional specification of the name of the output directory, using O=mybuilddir. -The default output directory is build. - -* all, build or just make - - Build the DPDK in the output directory previously created by a make config. - - Example: - - .. code-block:: console - - make O=mybuild - -* clean - - Clean all objects created using make build. - - Example: - - .. code-block:: console - - make clean O=mybuild - -* %_sub - - Build a subdirectory only, without managing dependencies on other directories. - - Example: - - .. code-block:: console - - make lib/librte_eal_sub O=mybuild - -* %_clean - - Clean a subdirectory only. - - Example: - - .. code-block:: console - - make lib/librte_eal_clean O=mybuild - -Install Targets ---------------- - -* Install - - The list of available targets are in $(RTE_SDK)/config (remove the defconfig\_ prefix). - - The GNU standards variables may be used: - http://gnu.org/prep/standards/html_node/Directory-Variables.html and - http://gnu.org/prep/standards/html_node/DESTDIR.html - - Example: - - .. code-block:: console - - make install DESTDIR=myinstall prefix=/usr - -Test Targets ------------- - -* test - - Launch automatic tests for a build directory specified using O=mybuilddir. - It is optional, the default output directory is build. - - Example: - - .. code-block:: console - - make test O=mybuild - -Documentation Targets ---------------------- - -* doc - - Generate the documentation (API and guides). - -* doc-api-html - - Generate the Doxygen API documentation in html. - -* doc-guides-html - - Generate the guides documentation in html. - -* doc-guides-pdf - - Generate the guides documentation in pdf. - -Misc Targets ------------- - -* help - - Show a quick help. - -Other Useful Command-line Variables ------------------------------------ - -The following variables can be specified on the command line: - -* V= - - Enable verbose build (show full compilation command line, and some intermediate commands). - -* D= - - Enable dependency debugging. This provides some useful information about why a target is built or not. - -* EXTRA_CFLAGS=, EXTRA_LDFLAGS=, EXTRA_LDLIBS=, EXTRA_ASFLAGS=, EXTRA_CPPFLAGS= - - Append specific compilation, link or asm flags. - -* CROSS= - - Specify a cross toolchain header that will prefix all gcc/binutils applications. This only works when using gcc. - -Make in a Build Directory -------------------------- - -All targets described above are called from the SDK root $(RTE_SDK). -It is possible to run the same Makefile targets inside the build directory. -For instance, the following command: - -.. code-block:: console - - cd $(RTE_SDK) - make config O=mybuild T=x86_64-native-linux-gcc - make O=mybuild - -is equivalent to: - -.. code-block:: console - - cd $(RTE_SDK) - make config O=mybuild T=x86_64-native-linux-gcc - cd mybuild - - # no need to specify O= now - make - -Compiling for Debug -------------------- - -To compile the DPDK and sample applications with debugging information included and the optimization level set to 0, -the EXTRA_CFLAGS environment variable should be set before compiling as follows: - -.. code-block:: console - - export EXTRA_CFLAGS='-O0 -g' diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst b/doc/guides/prog_guide/env_abstraction_layer.rst index f64ae953d1..936c885081 100644 --- a/doc/guides/prog_guide/env_abstraction_layer.rst +++ b/doc/guides/prog_guide/env_abstraction_layer.rst @@ -201,16 +201,16 @@ each segment is strictly one physical page. It is possible to change the amount of virtual memory being preallocated at startup by editing the following config variables: -* ``CONFIG_RTE_MAX_MEMSEG_LISTS`` controls how many segment lists can DPDK have -* ``CONFIG_RTE_MAX_MEM_MB_PER_LIST`` controls how much megabytes of memory each +* ``RTE_MAX_MEMSEG_LISTS`` controls how many segment lists can DPDK have +* ``RTE_MAX_MEM_MB_PER_LIST`` controls how much megabytes of memory each segment list can address -* ``CONFIG_RTE_MAX_MEMSEG_PER_LIST`` controls how many segments each segment can +* ``RTE_MAX_MEMSEG_PER_LIST`` controls how many segments each segment can have -* ``CONFIG_RTE_MAX_MEMSEG_PER_TYPE`` controls how many segments each memory type +* ``RTE_MAX_MEMSEG_PER_TYPE`` controls how many segments each memory type can have (where "type" is defined as "page size + NUMA node" combination) -* ``CONFIG_RTE_MAX_MEM_MB_PER_TYPE`` controls how much megabytes of memory each +* ``RTE_MAX_MEM_MB_PER_TYPE`` controls how much megabytes of memory each memory type can address -* ``CONFIG_RTE_MAX_MEM_MB`` places a global maximum on the amount of memory +* ``RTE_MAX_MEM_MB`` places a global maximum on the amount of memory DPDK can reserve Normally, these options do not need to be changed. @@ -715,11 +715,6 @@ However, they can be used in configuration code. Refer to the rte_malloc() function description in the *DPDK API Reference* manual for more information. -Cookies -~~~~~~~ - -When CONFIG_RTE_MALLOC_DEBUG is enabled, the allocated memory contains -overwrite protection fields to help identify buffer overflows. Alignment and NUMA Constraints ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/guides/prog_guide/ext_app_lib_make_help.rst b/doc/guides/prog_guide/ext_app_lib_make_help.rst index 4312778dc9..681114239d 100644 --- a/doc/guides/prog_guide/ext_app_lib_make_help.rst +++ b/doc/guides/prog_guide/ext_app_lib_make_help.rst @@ -1,28 +1,11 @@ .. SPDX-License-Identifier: BSD-3-Clause Copyright(c) 2010-2014 Intel Corporation. -.. _External_Application/Library_Makefile_help: +.. _External_Application_Makefile_help: -External Application/Library Makefile help +External Application Makefile help ========================================== -External applications or libraries should include specific Makefiles from RTE_SDK, located in mk directory. -These Makefiles are: - -* ${RTE_SDK}/mk/rte.extapp.mk: Build an application - -* ${RTE_SDK}/mk/rte.extlib.mk: Build a static library - -* ${RTE_SDK}/mk/rte.extobj.mk: Build objects (.o) - -Prerequisites -------------- - -The following variables must be defined: - -* ${RTE_SDK}: Points to the root directory of the DPDK. - -* ${RTE_TARGET}: Reference the target to be used for compilation (for example, x86_64-native-linux-gcc). Build Targets ------------- @@ -32,7 +15,7 @@ This is optional; the default output directory is build. * all, "nothing" (meaning just make) - Build the application or the library in the specified output directory. + Build the application in the specified output directory. Example: @@ -93,6 +76,4 @@ It is possible to run the Makefile from another directory, by specifying the out .. code-block:: console - export RTE_SDK=/path/to/DPDK - export RTE_TARGET=x86_64-native-linux-icc make -f /path/to/my_app/Makefile S=/path/to/my_app O=/path/to/build_dir diff --git a/doc/guides/prog_guide/graph_lib.rst b/doc/guides/prog_guide/graph_lib.rst index 669d77c740..c922d10f3d 100644 --- a/doc/guides/prog_guide/graph_lib.rst +++ b/doc/guides/prog_guide/graph_lib.rst @@ -45,13 +45,11 @@ Performance tuning parameters ----------------------------- - Test with various burst size values (256, 128, 64, 32) using - CONFIG_RTE_GRAPH_BURST_SIZE config option. + RTE_GRAPH_BURST_SIZE config option. The testing shows, on x86 and arm64 servers, The sweet spot is 256 burst size. While on arm64 embedded SoCs, it is either 64 or 128. -- Disable node statistics (using ``CONFIG_RTE_LIBRTE_GRAPH_STATS`` config option) +- Disable node statistics (using ``RTE_LIBRTE_GRAPH_STATS`` config option) if not needed. -- Use arm64 optimized memory copy for arm64 architecture by - selecting ``CONFIG_RTE_ARCH_ARM64_MEMCPY``. Programming model ----------------- diff --git a/doc/guides/prog_guide/intro.rst b/doc/guides/prog_guide/intro.rst index 5b319d36d9..44877bd3e3 100644 --- a/doc/guides/prog_guide/intro.rst +++ b/doc/guides/prog_guide/intro.rst @@ -34,7 +34,7 @@ The following is a list of DPDK documents in the suggested reading order: specifically in a Linux* application (linux) environment * The content of the DPDK, the build system - (including the commands that can be used in the root DPDK Makefile to build the development kit and an application) + (including the commands that can be used in the root DPDK to build the development kit and an application) and guidelines for porting an application * Optimizations used in the software and those that should be considered for new development diff --git a/doc/guides/prog_guide/ip_fragment_reassembly_lib.rst b/doc/guides/prog_guide/ip_fragment_reassembly_lib.rst index 6ac1bba649..314d4adbb8 100644 --- a/doc/guides/prog_guide/ip_fragment_reassembly_lib.rst +++ b/doc/guides/prog_guide/ip_fragment_reassembly_lib.rst @@ -103,8 +103,3 @@ Debug logging and Statistics Collection The RTE_LIBRTE_IP_FRAG_TBL_STAT config macro controls statistics collection for the Fragment Table. This macro is not enabled by default. - -The RTE_LIBRTE_IP_FRAG_DEBUG controls debug logging of IP fragments processing and reassembling. -This macro is disabled by default. -Note that while logging contains a lot of detailed information, -it slows down packet processing and might cause the loss of a lot of packets. diff --git a/doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst b/doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst index 2459fd243e..c376ac5f74 100644 --- a/doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst +++ b/doc/guides/prog_guide/link_bonding_poll_mode_drv_lib.rst @@ -25,11 +25,6 @@ The librte_pmd_bond library exports a C API which provides an API for the creation of bonded devices as well as the configuration and management of the bonded device and its slave devices. -.. note:: - - The Link Bonding PMD Library is enabled by default in the build - configuration files, the library can be disabled by setting - ``CONFIG_RTE_LIBRTE_PMD_BOND=n`` and recompiling the DPDK. Link Bonding Modes Overview --------------------------- diff --git a/doc/guides/prog_guide/lto.rst b/doc/guides/prog_guide/lto.rst index 277a6f1090..efa0cec4a1 100644 --- a/doc/guides/prog_guide/lto.rst +++ b/doc/guides/prog_guide/lto.rst @@ -26,17 +26,8 @@ need to explicitly initialize variable in order to silence the compiler. Please note that turning LTO on causes considerable extension of build time. -When using make based build, link time optimization can be enabled for -the whole DPDK by setting: - -.. code-block:: console - - CONFIG_RTE_ENABLE_LTO=y - -in config file. - -For the meson based build it can be enabled by setting meson built-in -'b_lto' option: +For the meson based build link time optimization can be enabled by setting +meson built-in 'b_lto' option: .. code-block:: console diff --git a/doc/guides/prog_guide/mbuf_lib.rst b/doc/guides/prog_guide/mbuf_lib.rst index c3dbfb9221..2f190b40e4 100644 --- a/doc/guides/prog_guide/mbuf_lib.rst +++ b/doc/guides/prog_guide/mbuf_lib.rst @@ -266,8 +266,8 @@ can be found in several of the sample applications, for example, the IPv4 Multic Debug ----- -In debug mode (CONFIG_RTE_MBUF_DEBUG is enabled), -the functions of the mbuf library perform sanity checks before any operation (such as, buffer corruption, bad type, and so on). +In debug mode, the functions of the mbuf library perform sanity checks before any operation (such as, buffer corruption, +bad type, and so on). Use Cases --------- diff --git a/doc/guides/prog_guide/mempool_lib.rst b/doc/guides/prog_guide/mempool_lib.rst index e3e1f940be..f0bdcd3be1 100644 --- a/doc/guides/prog_guide/mempool_lib.rst +++ b/doc/guides/prog_guide/mempool_lib.rst @@ -17,14 +17,13 @@ This library is used by the :ref:`Mbuf Library `. Cookies ------- -In debug mode (CONFIG_RTE_LIBRTE_MEMPOOL_DEBUG is enabled), cookies are added at the beginning and end of allocated blocks. +In debug mode, cookies are added at the beginning and end of allocated blocks. The allocated objects then contain overwrite protection fields to help debugging buffer overflows. Stats ----- -In debug mode (CONFIG_RTE_LIBRTE_MEMPOOL_DEBUG is enabled), -statistics about get from/put in the pool are stored in the mempool structure. +In debug mode, statistics about get from/put in the pool are stored in the mempool structure. Statistics are per-lcore to avoid concurrent access to statistics counters. Memory Alignment Constraints on x86 architecture @@ -90,7 +89,7 @@ the speed at which a core can access its own cache for a specific memory pool wi The cache is composed of a small, per-core table of pointers and its length (used as a stack). This internal cache can be enabled or disabled at creation of the pool. -The maximum size of the cache is static and is defined at compilation time (CONFIG_RTE_MEMPOOL_CACHE_MAX_SIZE). +The maximum size of the cache is static and is defined at compilation time (RTE_MEMPOOL_CACHE_MAX_SIZE). :numref:`figure_mempool` shows a cache in operation. diff --git a/doc/guides/prog_guide/overview.rst b/doc/guides/prog_guide/overview.rst index 986c896908..537a568f1e 100644 --- a/doc/guides/prog_guide/overview.rst +++ b/doc/guides/prog_guide/overview.rst @@ -18,7 +18,7 @@ The framework creates a set of libraries for specific environments through the creation of an Environment Abstraction Layer (EAL), which may be specific to a mode of the Intel® architecture (32-bit or 64-bit), Linux* user space compilers or a specific platform. -These environments are created through the use of make files and configuration files. +These environments are created through the use of meson files and configuration files. Once the EAL library is created, the user may link with the library to create their own applications. Other libraries, outside of EAL, including the Hash, Longest Prefix Match (LPM) and rings libraries are also provided. @@ -38,21 +38,13 @@ Development Environment ----------------------- The DPDK project installation requires Linux and the associated toolchain, -such as one or more compilers, assembler, make utility, +such as one or more compilers, assembler, meson utility, editor and various libraries to create the DPDK components and libraries. Once these libraries are created for the specific environment and architecture, they may then be used to create the user's data plane application. When creating applications for the Linux user space, the glibc library is used. -For DPDK applications, two environmental variables (RTE_SDK and RTE_TARGET) -must be configured before compiling the applications. -The following are examples of how the variables can be set: - -.. code-block:: console - - export RTE_SDK=/home/user/DPDK - export RTE_TARGET=x86_64-native-linux-gcc See the *DPDK Getting Started Guide* for information on setting up the development environment. diff --git a/doc/guides/prog_guide/profile_app.rst b/doc/guides/prog_guide/profile_app.rst index e5d0e9079e..9394bb7b41 100644 --- a/doc/guides/prog_guide/profile_app.rst +++ b/doc/guides/prog_guide/profile_app.rst @@ -33,14 +33,6 @@ Refer to the for details about application profiling. -Profiling with VTune -~~~~~~~~~~~~~~~~~~~~ - -To allow VTune attaching to the DPDK application, reconfigure and recompile -the DPDK with ``CONFIG_RTE_ETHDEV_RXTX_CALLBACKS`` and -``CONFIG_RTE_ETHDEV_PROFILE_WITH_VTUNE`` enabled. - - Profiling on ARM64 ------------------ @@ -76,8 +68,7 @@ cycle counter for user space access by configuring the PMU from the privileged mode (kernel space). By default the ``rte_rdtsc()`` implementation uses a portable ``cntvct_el0`` -scheme. Application can choose the PMU based implementation with -``CONFIG_RTE_ARM_EAL_RDTSC_USE_PMU``. +scheme. The example below shows the steps to configure the PMU based cycle counter on an ARMv8 machine. @@ -88,10 +79,6 @@ an ARMv8 machine. cd armv8_pmu_cycle_counter_el0 make sudo insmod pmu_el0_cycle_counter.ko - cd $DPDK_DIR - make config T=arm64-armv8a-linux-gcc - echo "CONFIG_RTE_ARM_EAL_RDTSC_USE_PMU=y" >> build/.config - make .. warning:: diff --git a/doc/guides/prog_guide/qos_framework.rst b/doc/guides/prog_guide/qos_framework.rst index a159709450..4e4ea33ccb 100644 --- a/doc/guides/prog_guide/qos_framework.rst +++ b/doc/guides/prog_guide/qos_framework.rst @@ -1525,15 +1525,7 @@ Integration with the DPDK QoS Scheduler ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ RED functionality in the DPDK QoS scheduler is disabled by default. -To enable it, use the DPDK configuration parameter: - -:: - - CONFIG_RTE_SCHED_RED=y - -This parameter must be set to y. -The parameter is found in the build configuration files in the DPDK/config directory, -for example, DPDK/config/common_linux. +The parameter is found in the build configuration files in the DPDK/config directory. RED configuration parameters are specified in the rte_red_params structure within the rte_sched_port_params structure that is passed to the scheduler on initialization. RED parameters are specified separately for four traffic classes and three packet colors (green, yellow and red) diff --git a/doc/guides/prog_guide/rcu_lib.rst b/doc/guides/prog_guide/rcu_lib.rst index d142d0c79d..d0aef3bc16 100644 --- a/doc/guides/prog_guide/rcu_lib.rst +++ b/doc/guides/prog_guide/rcu_lib.rst @@ -186,10 +186,9 @@ they entered a quiescent state. This API checks if a writer has triggered a quiescent state query and update the state accordingly. The ``rte_rcu_qsbr_lock()`` and ``rte_rcu_qsbr_unlock()`` are empty functions. -However, when ``CONFIG_RTE_LIBRTE_RCU_DEBUG`` is enabled, these APIs aid -in debugging issues. One can mark the access to shared data structures on the -reader side using these APIs. The ``rte_rcu_qsbr_quiescent()`` will check if -all the locks are unlocked. +However, these APIs can aid in debugging issues. One can mark the access to +shared data structures on the reader side using these APIs. The +``rte_rcu_qsbr_quiescent()`` will check if all the locks are unlocked. Resource reclamation framework for DPDK --------------------------------------- diff --git a/doc/guides/prog_guide/source_org.rst b/doc/guides/prog_guide/source_org.rst index 31c153a1b7..8d531bd9ef 100644 --- a/doc/guides/prog_guide/source_org.rst +++ b/doc/guides/prog_guide/source_org.rst @@ -8,29 +8,10 @@ Source Organization This section describes the organization of sources in the DPDK framework. -Makefiles and Config --------------------- - -.. note:: - - In the following descriptions, - ``RTE_SDK`` is the environment variable that points to the base directory into which the tarball was extracted. - See - :ref:`Useful_Variables_Provided_by_the_Build_System` - for descriptions of other variables. - -Makefiles that are provided by the DPDK libraries and applications are located in ``$(RTE_SDK)/mk``. - -Config templates are located in ``$(RTE_SDK)/config``. The templates describe the options that are enabled for each target. -The config file also contains items that can be enabled and disabled for many of the DPDK libraries, -including debug options. -The user should look at the config file and become familiar with these options. -The config file is also used to create a header file, which will be located in the new build directory. - Libraries --------- -Libraries are located in subdirectories of ``$(RTE_SDK)/lib``. +Libraries are located in subdirectories of ``dpdk/lib``. By convention a library refers to any code that provides an API to an application. Typically, it generates an archive file (``.a``), but a kernel module would also go in the same directory. @@ -55,7 +36,7 @@ Applications ------------ Applications are source files that contain a ``main()`` function. -They are located in the ``$(RTE_SDK)/app`` and ``$(RTE_SDK)/examples`` directories. +They are located in the ``dpdk/app`` and ``dpdk/examples`` directories. The app directory contains sample applications that are used to test DPDK (such as autotests) or the Poll Mode Drivers (test-pmd). diff --git a/doc/guides/prog_guide/trace_lib.rst b/doc/guides/prog_guide/trace_lib.rst index 9bbfd165d8..fbadf9fde9 100644 --- a/doc/guides/prog_guide/trace_lib.rst +++ b/doc/guides/prog_guide/trace_lib.rst @@ -135,8 +135,7 @@ In order to avoid performance impact in fast path code, the library introduced the user must use ``RTE_TRACE_POINT_FP`` instead of ``RTE_TRACE_POINT``. ``RTE_TRACE_POINT_FP`` is compiled out by default and it can be enabled using -``CONFIG_RTE_ENABLE_TRACE_FP`` configuration parameter. -The ``enable_trace_fp`` option shall be used for the same for meson build. +the ``enable_trace_fp`` option for meson build. Event record mode ----------------- diff --git a/doc/guides/prog_guide/writing_efficient_code.rst b/doc/guides/prog_guide/writing_efficient_code.rst index 2639ef7bf6..db2f1ddbc2 100644 --- a/doc/guides/prog_guide/writing_efficient_code.rst +++ b/doc/guides/prog_guide/writing_efficient_code.rst @@ -258,8 +258,7 @@ For instance: Setting the Target CPU Type --------------------------- -The DPDK supports CPU microarchitecture-specific optimizations by means of CONFIG_RTE_MACHINE option -in the DPDK configuration file. +The DPDK supports CPU microarchitecture-specific optimizations by means of RTE_MACHINE option. The degree of optimization depends on the compiler's ability to optimize for a specific microarchitecture, therefore it is preferable to use the latest compiler versions whenever possible. -- 2.17.1