From patchwork Fri Jan 3 15:32:52 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 64192 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id C52C9A04F3; Fri, 3 Jan 2020 16:33:17 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 4196F1D44F; Fri, 3 Jan 2020 16:33:13 +0100 (CET) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id BE8A11D44B for ; Fri, 3 Jan 2020 16:33:10 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Jan 2020 07:33:10 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,391,1571727600"; d="scan'208";a="222192940" Received: from silpixa00399126.ir.intel.com (HELO silpixa00399126.ger.corp.intel.com) ([10.237.223.2]) by orsmga003.jf.intel.com with ESMTP; 03 Jan 2020 07:33:09 -0800 From: Bruce Richardson To: john.mcnamara@intel.com, marko.kovacevic@intel.com Cc: anatoly.burakov@intel.com, dev@dpdk.org, Bruce Richardson Date: Fri, 3 Jan 2020 15:32:52 +0000 Message-Id: <20200103153256.2895527-2-bruce.richardson@intel.com> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200103153256.2895527-1-bruce.richardson@intel.com> References: <20200103153256.2895527-1-bruce.richardson@intel.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH 1/5] doc: update intro to FreeBSD GSG 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" Update the introduction section note, to add in the fact that DPDK is now packaged in FreeBSD, i.e. available as a pre-built binary package, as well as being in the ports collection for manual building. Signed-off-by: Bruce Richardson --- Note: at this stage, DPDK is in the "latest" package snapshot, but has not yet made it's way into the quarterly snapshot used by default by stable releases. This is hopefully only a matter of time. --- doc/guides/freebsd_gsg/intro.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/guides/freebsd_gsg/intro.rst b/doc/guides/freebsd_gsg/intro.rst index e5611bca6..63160ce64 100644 --- a/doc/guides/freebsd_gsg/intro.rst +++ b/doc/guides/freebsd_gsg/intro.rst @@ -16,10 +16,9 @@ handbook is available from the FreeBSD Documentation Project: .. note:: - The DPDK is now available as part of the FreeBSD ports collection. - Installing via the ports collection infrastructure is now the recommended - way to install the DPDK on FreeBSD, and is documented in the - next chapter, :ref:`install_from_ports`. + DPDK is now available as part of the FreeBSD ports collection and as a pre-built package. + Installing via the ports collection or FreeBSD `pkg` infrastructure is now the recommended + way to install DPDK on FreeBSD, and is documented in the next chapter, :ref:`install_from_ports`. Documentation Roadmap --------------------- From patchwork Fri Jan 3 15:32:53 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 64193 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id E05BCA04F3; Fri, 3 Jan 2020 16:33:26 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id E27B81D455; Fri, 3 Jan 2020 16:33:14 +0100 (CET) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id D5CEA1D44C for ; Fri, 3 Jan 2020 16:33:12 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Jan 2020 07:33:12 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,391,1571727600"; d="scan'208";a="222192964" Received: from silpixa00399126.ir.intel.com (HELO silpixa00399126.ger.corp.intel.com) ([10.237.223.2]) by orsmga003.jf.intel.com with ESMTP; 03 Jan 2020 07:33:11 -0800 From: Bruce Richardson To: john.mcnamara@intel.com, marko.kovacevic@intel.com Cc: anatoly.burakov@intel.com, dev@dpdk.org, Bruce Richardson Date: Fri, 3 Jan 2020 15:32:53 +0000 Message-Id: <20200103153256.2895527-3-bruce.richardson@intel.com> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200103153256.2895527-1-bruce.richardson@intel.com> References: <20200103153256.2895527-1-bruce.richardson@intel.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH 2/5] doc: document installing from FreeBSD package 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" Update the FreeBSD GSG to cover installing from the pre-built package as well as installing from a port. Also, since the port is now based on meson, update the instructions for compiling and running the example applications. Signed-off-by: Bruce Richardson --- Note: at this stage, DPDK is in the "latest" package snapshot, but has not yet made it's way into the quarterly snapshot used by default by stable releases. This is hopefully only a matter of time. --- doc/guides/freebsd_gsg/install_from_ports.rst | 73 +++++++++---------- 1 file changed, 36 insertions(+), 37 deletions(-) diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst index 29f16cc6c..36dc4a417 100644 --- a/doc/guides/freebsd_gsg/install_from_ports.rst +++ b/doc/guides/freebsd_gsg/install_from_ports.rst @@ -7,29 +7,31 @@ Installing DPDK from the Ports Collection ========================================= The easiest way to get up and running with the DPDK on FreeBSD is to -install it from the ports collection. Details of getting and using the ports -collection are documented in the -`FreeBSD Handbook `_. +install it using the FreeBSD `pkg` utility or from the ports collection. +Details of installing applications from packages or the ports collection are documented in the +`FreeBSD Handbook `_, +chapter `Installing Applications: Packages and Ports `_. -Installing the DPDK FreeBSD Port --------------------------------- +.. note:: -On a system with the ports collection installed in ``/usr/ports``, the DPDK -can be installed using the commands: + Please ensure that the latest patches are applied to third party libraries + and software to avoid any known vulnerabilities. -.. code-block:: console - cd /usr/ports/net/dpdk +Installing the DPDK Package for FreeBSD +--------------------------------------- - make install +DPDK can be installed on FreeBSD using the command:: + + pkg install dpdk -After the installation of the DPDK port, instructions will be printed on +After the installation of the DPDK package, instructions will be printed on how to install the kernel modules required to use the DPDK. A more complete version of these instructions can be found in the sections :ref:`loading_contigmem` and :ref:`loading_nic_uio`. Normally, lines like those below would be added to the file ``/boot/loader.conf``. -.. code-block:: console +.. code-block:: shell # Reserve 2 x 1G blocks of contiguous memory using contigmem driver: hw.contigmem.num_buffers=2 @@ -40,24 +42,32 @@ those below would be added to the file ``/boot/loader.conf``. hw.nic_uio.bdfs="2:0:0,2:0:1" nic_uio_load="YES" -.. note:: - Please ensure that the latest patches are applied to third party libraries - and software to avoid any known vulnerabilities. +Installing the DPDK FreeBSD Port +-------------------------------- + +If so desired, the user can install DPDK using the ports collection rather than from +a pre-compiled binary package. +On a system with the ports collection installed in ``/usr/ports``, the DPDK +can be installed using the commands:: + + cd /usr/ports/net/dpdk + + make install Compiling and Running the Example Applications ---------------------------------------------- When the DPDK has been installed from the ports collection it installs -its example applications in ``/usr/local/share/dpdk/examples`` - also accessible via -symlink as ``/usr/local/share/examples/dpdk``. These examples can be compiled and -run as described in :ref:`compiling_sample_apps`. In this case, the required -environmental variables should be set as below: +its example applications in ``/usr/local/share/dpdk/examples``. +These examples can be compiled and run as described in :ref:`compiling_sample_apps`. -* ``RTE_SDK=/usr/local/share/dpdk`` +.. note:: -* ``RTE_TARGET=x86_64-native-freebsd-clang`` + DPDK example applications must be complied using `gmake` rather than + BSD `make`. To detect the installed DPDK libraries, `pkg-config` should + also be installed on the system. .. note:: @@ -66,25 +76,18 @@ environmental variables should be set as below: the instructions given in the next chapter, :ref:`building_from_source` An example application can therefore be copied to a user's home directory and -compiled and run as below: - -.. code-block:: console - - export RTE_SDK=/usr/local/share/dpdk - - export RTE_TARGET=x86_64-native-freebsd-clang +compiled and run as below, where we have 2 memory blocks of size 1G reserved +via the contigmem module, and 4 NIC ports bound to the nic_uio module:: cp -r /usr/local/share/dpdk/examples/helloworld . cd helloworld/ gmake - CC main.o - LD helloworld - INSTALL-APP helloworld - INSTALL-MAP helloworld.map + cc -O3 -I/usr/local/include -include rte_config.h -march=corei7 -D__BSD_VISIBLE main.c -o build/helloworld-shared -L/usr/local/lib -lrte_bpf -lrte_flow_classify -lrte_pipeline -lrte_table -lrte_port -lrte_fib -lrte_ipsec -lrte_stack -lrte_security -lrte_sched -lrte_reorder -lrte_rib -lrte_rcu -lrte_rawdev -lrte_pdump -lrte_member -lrte_lpm -lrte_latencystats -lrte_jobstats -lrte_ip_frag -lrte_gso -lrte_gro -lrte_eventdev -lrte_efd -lrte_distributor -lrte_cryptodev -lrte_compressdev -lrte_cfgfile -lrte_bitratestats -lrte_bbdev -lrte_acl -lrte_timer -lrte_hash -lrte_metrics -lrte_cmdline -lrte_pci -lrte_ethdev -lrte_meter -lrte_net -lrte_mbuf -lrte_mempool -lrte_ring -lrte_eal -lrte_kvargs + ln -sf helloworld-shared build/helloworld - sudo ./build//helloworld -l 0-3 + sudo ./build/helloworld -l 0-3 EAL: Sysctl reports 8 cpus EAL: Detected 8 lcore(s) EAL: Detected 1 NUMA nodes @@ -98,16 +101,12 @@ compiled and run as below: EAL: 0000:00:19.0 not managed by UIO driver, skipping EAL: PCI device 0000:01:00.0 on NUMA socket 0 EAL: probe driver: 8086:1572 net_i40e - EAL: 0000:01:00.0 not managed by UIO driver, skipping EAL: PCI device 0000:01:00.1 on NUMA socket 0 EAL: probe driver: 8086:1572 net_i40e - EAL: 0000:01:00.1 not managed by UIO driver, skipping EAL: PCI device 0000:01:00.2 on NUMA socket 0 EAL: probe driver: 8086:1572 net_i40e - EAL: 0000:01:00.2 not managed by UIO driver, skipping EAL: PCI device 0000:01:00.3 on NUMA socket 0 EAL: probe driver: 8086:1572 net_i40e - EAL: 0000:01:00.3 not managed by UIO driver, skipping hello from core 1 hello from core 2 hello from core 3 From patchwork Fri Jan 3 15:32:54 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 64194 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 6525CA04F3; Fri, 3 Jan 2020 16:33:35 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 5C54B1D508; Fri, 3 Jan 2020 16:33:17 +0100 (CET) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id E99B01D483 for ; Fri, 3 Jan 2020 16:33:14 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Jan 2020 07:33:14 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,391,1571727600"; d="scan'208";a="222192990" Received: from silpixa00399126.ir.intel.com (HELO silpixa00399126.ger.corp.intel.com) ([10.237.223.2]) by orsmga003.jf.intel.com with ESMTP; 03 Jan 2020 07:33:13 -0800 From: Bruce Richardson To: john.mcnamara@intel.com, marko.kovacevic@intel.com Cc: anatoly.burakov@intel.com, dev@dpdk.org, Bruce Richardson Date: Fri, 3 Jan 2020 15:32:54 +0000 Message-Id: <20200103153256.2895527-4-bruce.richardson@intel.com> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200103153256.2895527-1-bruce.richardson@intel.com> References: <20200103153256.2895527-1-bruce.richardson@intel.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH 3/5] doc: add meson install instructions for FreeBSD 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" Update the FreeBSD GSG doc with instructions for installing using meson and ninja rather than make. Signed-off-by: Bruce Richardson Acked-by: Anatoly Burakov --- doc/guides/freebsd_gsg/build_dpdk.rst | 164 +++++++------------------- 1 file changed, 40 insertions(+), 124 deletions(-) diff --git a/doc/guides/freebsd_gsg/build_dpdk.rst b/doc/guides/freebsd_gsg/build_dpdk.rst index 7abd85aa5..c5d5379f6 100644 --- a/doc/guides/freebsd_gsg/build_dpdk.rst +++ b/doc/guides/freebsd_gsg/build_dpdk.rst @@ -6,147 +6,63 @@ Compiling the DPDK Target from Source ===================================== -System Requirements -------------------- +Prerequisites +------------- -The DPDK and its applications require the GNU make system (gmake) -to build on FreeBSD. Optionally, gcc may also be used in place of clang -to build the DPDK, in which case it too must be installed prior to -compiling the DPDK. The installation of these tools is covered in this -section. +The following FreeBSD packages are required to build DPDK: -Compiling the DPDK requires the FreeBSD kernel sources, which should be -included during the installation of FreeBSD on the development platform. -The DPDK also requires the use of FreeBSD ports to compile and function. +* meson +* ninja +* pkgconf -To use the FreeBSD ports system, it is required to update and extract the FreeBSD -ports tree by issuing the following commands: +These can be installed using (as root):: -.. code-block:: console - - portsnap fetch - portsnap extract - -If the environment requires proxies for external communication, these can be set -using: - -.. code-block:: console - - setenv http_proxy : - setenv ftp_proxy : - -The FreeBSD ports below need to be installed prior to building the DPDK. -In general these can be installed using the following set of commands:: - - cd /usr/ports/ - - make config-recursive - - make install - - make clean - -Each port location can be found using:: - - whereis - -The ports required and their locations are as follows: - -* dialog4ports: ``/usr/ports/ports-mgmt/dialog4ports`` - -* GNU make(gmake): ``/usr/ports/devel/gmake`` - -* coreutils: ``/usr/ports/sysutils/coreutils`` - -For compiling and using the DPDK with gcc, the compiler must be installed -from the ports collection: - -* gcc: version 4.9 is recommended ``/usr/ports/lang/gcc49``. - Ensure that ``CPU_OPTS`` is selected (default is OFF). - -When running the make config-recursive command, a dialog may be presented to the -user. For the installation of the DPDK, the default options were used. - -.. note:: + pkg install meson pkgconf - To avoid multiple dialogs being presented to the user during make install, - it is advisable before running the make install command to re-run the - make config-recursive command until no more dialogs are seen. +To compile the required kernel modules for memory management and working +with physical NIC devices, the kernel sources for FreeBSD also +need to be installed. If not already present on the system, these can be +installed via commands like the following, for FreeBSD 12.1 on x86_64:: + fetch http://ftp.freebsd.org/pub/FreeBSD/releases/amd64/12.1-RELEASE/src.txz + tar -C / -xJvf src.txz -Install the DPDK and Browse Sources ------------------------------------ +To enable the telemetry library in DPDK, the jansson library also needs to +be installed, and can be installed via:: -First, uncompress the archive and move to the DPDK source directory: + pkg install jansson -.. code-block:: console - - unzip DPDK-.zip - cd DPDK- - -The DPDK is composed of several directories: - -* lib: Source code of DPDK libraries - -* app: Source code of DPDK applications (automatic tests) - -* examples: Source code of DPDK applications - -* config, buildtools, mk: Framework-related makefiles, scripts and configuration - -Installation of the DPDK Target Environments --------------------------------------------- - -The format of a DPDK target is:: - - ARCH-MACHINE-EXECENV-TOOLCHAIN - -Where: +Individual drivers may have additional requirements. Consult the relevant +driver guide for any driver-specific requirements of interest. -* ``ARCH`` is: ``x86_64`` +Building DPDK +------------- -* ``MACHINE`` is: ``native`` +The following commands can be used to build and install DPDK on a system. +The final, install, step generally needs to be run as root:: -* ``EXECENV`` is: ``freebsd`` + meson build + cd build + ninja + ninja install -* ``TOOLCHAIN`` is: ``gcc`` | ``clang`` - -The configuration files for the DPDK targets can be found in the DPDK/config -directory in the form of:: - - defconfig_ARCH-MACHINE-EXECENV-TOOLCHAIN +This will install the DPDK libraries and drivers to `/usr/local/lib` with a +pkg-config file `libdpdk.pc` installed to `/usr/local/lib/pkgconfig`. The +DPDK test applications, such as `dpdk-testpmd` are installed to +`/usr/local/bin`. To use these applications, it is recommended that the +`contigmem` and `nic_uio` kernel modules be loaded first, as described in +the next section. .. note:: - Configuration files are provided with the ``RTE_MACHINE`` optimization level set. - Within the configuration files, the ``RTE_MACHINE`` configuration value is set - to native, which means that the compiled software is tuned for the platform - on which it is built. For more information on this setting, and its - possible values, see the *DPDK Programmers Guide*. - -To make the target, use ``gmake install T=``. - -For example to compile for FreeBSD use: - -.. code-block:: console - - gmake install T=x86_64-native-freebsd-clang - -.. note:: - - If the compiler binary to be used does not correspond to that given in the - TOOLCHAIN part of the target, the compiler command may need to be explicitly - specified. For example, if compiling for gcc, where the gcc binary is called - gcc4.9, the command would need to be ``gmake install T= CC=gcc4.9``. - -Browsing the Installed DPDK Environment Target ----------------------------------------------- + It is recommended that pkg-config be used to query information + about the compiler and linker flags needed to build applications + against DPDK. In some cases, the path `/usr/local/lib/pkgconfig` + may not be in the default search paths for `.pc` files, which means + that queries for DPDK information may fail. This can be fixed by + setting the appropriate path in `PKG_CONFIG_PATH` environment + variable. -Once a target is created, it contains all the libraries and header files for the -DPDK environment that are required to build customer applications. -In addition, the test and testpmd applications are built under the build/app -directory, which may be used for testing. A kmod directory is also present that -contains the kernel modules to install. .. _loading_contigmem: From patchwork Fri Jan 3 15:32:55 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 64195 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 0F49EA04F3; Fri, 3 Jan 2020 16:33:44 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 197C21D50E; Fri, 3 Jan 2020 16:33:19 +0100 (CET) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id 07C2B1D505 for ; Fri, 3 Jan 2020 16:33:16 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Jan 2020 07:33:16 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,391,1571727600"; d="scan'208";a="222193021" Received: from silpixa00399126.ir.intel.com (HELO silpixa00399126.ger.corp.intel.com) ([10.237.223.2]) by orsmga003.jf.intel.com with ESMTP; 03 Jan 2020 07:33:15 -0800 From: Bruce Richardson To: john.mcnamara@intel.com, marko.kovacevic@intel.com Cc: anatoly.burakov@intel.com, dev@dpdk.org, Bruce Richardson Date: Fri, 3 Jan 2020 15:32:55 +0000 Message-Id: <20200103153256.2895527-5-bruce.richardson@intel.com> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200103153256.2895527-1-bruce.richardson@intel.com> References: <20200103153256.2895527-1-bruce.richardson@intel.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH 4/5] doc: update section on loading FreeBSD kernel modules 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" The kernel modules are now installed in the correct system location on install when using meson and ninja, so update the documentation to remove any references to the "kmod" directory. Also, make a few additional updates to improve clarity. Signed-off-by: Bruce Richardson --- doc/guides/freebsd_gsg/build_dpdk.rst | 65 ++++++++++++--------------- 1 file changed, 29 insertions(+), 36 deletions(-) diff --git a/doc/guides/freebsd_gsg/build_dpdk.rst b/doc/guides/freebsd_gsg/build_dpdk.rst index c5d5379f6..e31c966b9 100644 --- a/doc/guides/freebsd_gsg/build_dpdk.rst +++ b/doc/guides/freebsd_gsg/build_dpdk.rst @@ -73,26 +73,25 @@ To run a DPDK application, physically contiguous memory is required. In the absence of non-transparent superpages, the included sources for the contigmem kernel module provides the ability to present contiguous blocks of memory for the DPDK to use. The contigmem module must be loaded into the -running kernel before any DPDK is run. The module is found in the kmod -sub-directory of the DPDK target directory. +running kernel before any DPDK is run. Once DPDK is installed on the +system, the module can be found in the `/boot/modules` directory. The amount of physically contiguous memory along with the number of physically contiguous blocks to be reserved by the module can be set at runtime prior to -module loading using: - -.. code-block:: console +module loading using:: kenv hw.contigmem.num_buffers=n kenv hw.contigmem.buffer_size=m The kernel environment variables can also be specified during boot by placing the -following in ``/boot/loader.conf``:: +following in ``/boot/loader.conf``: - hw.contigmem.num_buffers=n hw.contigmem.buffer_size=m +.. code-block:: shell -The variables can be inspected using the following command: + hw.contigmem.num_buffers=n + hw.contigmem.buffer_size=m -.. code-block:: console +The variables can be inspected using the following command:: sysctl -a hw.contigmem @@ -100,18 +99,19 @@ Where n is the number of blocks and m is the size in bytes of each area of contiguous memory. A default of two buffers of size 1073741824 bytes (1 Gigabyte) each is set during module load if they are not specified in the environment. -The module can then be loaded using kldload (assuming that the current directory -is the DPDK target directory): - -.. code-block:: console +The module can then be loaded using kldload:: - kldload ./kmod/contigmem.ko + kldload contigmem It is advisable to include the loading of the contigmem module during the boot process to avoid issues with potential memory fragmentation during later system -up time. This can be achieved by copying the module to the ``/boot/kernel/`` -directory and placing the following into ``/boot/loader.conf``:: +up time. This can be achieved by placing lines similar to the following into +``/boot/loader.conf``: + +.. code-block:: shell + hw.contigmem.num_buffers=1 + hw.contigmem.buffer_size=1073741824 contigmem_load="YES" .. note:: @@ -120,17 +120,13 @@ directory and placing the following into ``/boot/loader.conf``:: ``hw.contigmem.num_buffers`` and ``hw.contigmem.buffer_size`` if the default values are not to be used. -An error such as: - -.. code-block:: console +An error such as:: kldload: can't load ./x86_64-native-freebsd-gcc/kmod/contigmem.ko: Exec format error is generally attributed to not having enough contiguous memory -available and can be verified via dmesg or ``/var/log/messages``: - -.. code-block:: console +available and can be verified via dmesg or ``/var/log/messages``:: kernel: contigmalloc failed for buffer @@ -142,13 +138,9 @@ Loading the DPDK nic_uio Module ------------------------------- After loading the contigmem module, the ``nic_uio`` module must also be loaded into the -running kernel prior to running any DPDK application. This module must -be loaded using the kldload command as shown below (assuming that the current -directory is the DPDK target directory). +running kernel prior to running any DPDK application, e.g. using:: -.. code-block:: console - - kldload ./kmod/nic_uio.ko + kldload nic_uio .. note:: @@ -159,8 +151,9 @@ directory is the DPDK target directory). Currently loaded modules can be seen by using the ``kldstat`` command and a module can be removed from the running kernel by using ``kldunload ``. -To load the module during boot, copy the ``nic_uio`` module to ``/boot/kernel`` -and place the following into ``/boot/loader.conf``:: +To load the module during boot place the following into ``/boot/loader.conf``: + +.. code-block:: shell nic_uio_load="YES" @@ -184,7 +177,7 @@ Binding Network Ports to the nic_uio Module Device ownership can be viewed using the pciconf -l command. The example below shows four Intel® 82599 network ports under ``if_ixgbe`` module ownership. -.. code-block:: console +.. code-block:: none pciconf -l ix0@pci0:1:0:0: class=0x020000 card=0x00038086 chip=0x10fb8086 rev=0x01 hdr=0x00 @@ -210,7 +203,7 @@ To avoid building a custom kernel, the ``nic_uio`` module can detach a network p from its current device driver. This is achieved by setting the ``hw.nic_uio.bdfs`` kernel environment variable prior to loading ``nic_uio``, as follows:: - hw.nic_uio.bdfs="b:d:f,b:d:f,..." + kenv hw.nic_uio.bdfs="b:d:f,b:d:f,..." Where a comma separated list of selectors is set, the list must not contain any whitespace. @@ -222,7 +215,9 @@ upon loading, use the following command:: The variable can also be specified during boot by placing the following into ``/boot/loader.conf``, before the previously-described ``nic_uio_load`` line - as -shown:: +shown: + +.. code-block:: shell hw.nic_uio.bdfs="2:0:0,2:0:1" nic_uio_load="YES" @@ -241,9 +236,7 @@ value, and reload the two drivers - first the original kernel driver, and then the ``nic_uio driver``. Note: the latter does not need to be reloaded unless there are ports that are still to be bound to it. -Example commands to perform these steps are shown below: - -.. code-block:: console +Example commands to perform these steps are shown below:: kldunload nic_uio kldunload From patchwork Fri Jan 3 15:32:56 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Bruce Richardson X-Patchwork-Id: 64196 X-Patchwork-Delegate: thomas@monjalon.net Return-Path: X-Original-To: patchwork@inbox.dpdk.org Delivered-To: patchwork@inbox.dpdk.org Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 29B60A04F3; Fri, 3 Jan 2020 16:33:55 +0100 (CET) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id CBC781D518; Fri, 3 Jan 2020 16:33:21 +0100 (CET) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) by dpdk.org (Postfix) with ESMTP id E2BBF1C436 for ; Fri, 3 Jan 2020 16:33:19 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Jan 2020 07:33:19 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.69,391,1571727600"; d="scan'208";a="222193049" Received: from silpixa00399126.ir.intel.com (HELO silpixa00399126.ger.corp.intel.com) ([10.237.223.2]) by orsmga003.jf.intel.com with ESMTP; 03 Jan 2020 07:33:17 -0800 From: Bruce Richardson To: john.mcnamara@intel.com, marko.kovacevic@intel.com Cc: anatoly.burakov@intel.com, dev@dpdk.org, Bruce Richardson Date: Fri, 3 Jan 2020 15:32:56 +0000 Message-Id: <20200103153256.2895527-6-bruce.richardson@intel.com> X-Mailer: git-send-email 2.24.1 In-Reply-To: <20200103153256.2895527-1-bruce.richardson@intel.com> References: <20200103153256.2895527-1-bruce.richardson@intel.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH 5/5] doc: update documentation on build and running FreeBSD apps 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" Update the documentation on building and running apps on FreeBSD, taking account of having used meson for building. We can also update the section on the command-line parameters, rather than claiming to be a complete list of parameters, it should describe how to get the complete list and only cover a few important ones. Signed-off-by: Bruce Richardson Acked-by: Anatoly Burakov --- doc/guides/freebsd_gsg/build_sample_apps.rst | 118 +++++-------------- 1 file changed, 27 insertions(+), 91 deletions(-) diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst index 0c1b9cb79..2a68f5fc3 100644 --- a/doc/guides/freebsd_gsg/build_sample_apps.rst +++ b/doc/guides/freebsd_gsg/build_sample_apps.rst @@ -12,68 +12,37 @@ environment. It also provides a pointer to where sample applications are stored. Compiling a Sample Application ------------------------------ -Once a DPDK target environment directory has been created (such as -``x86_64-native-freebsd-clang``), it contains all libraries and header files required -to build an application. +The DPDK example applications make use of the pkg-config file installed on +the system when DPDK is installed, and so can be built using GNU make. -When compiling an application in the FreeBSD environment on the DPDK, -the following variables must be exported: - -* ``RTE_SDK`` - Points to the DPDK installation directory. - -* ``RTE_TARGET`` - Points to the DPDK target environment directory. - For FreeBSD, this is the ``x86_64-native-freebsd-clang`` or - ``x86_64-native-freebsd-gcc`` directory. - -The following is an example of creating the ``helloworld`` application, which runs -in the DPDK FreeBSD environment. While the example demonstrates compiling -using gcc version 4.9, compiling with clang will be similar, except that the ``CC=`` -parameter can probably be omitted. The ``helloworld`` example may be found in the -``${RTE_SDK}/examples`` directory. - -The directory contains the ``main.c`` file. This file, when combined with the -libraries in the DPDK target environment, calls the various functions to -initialize the DPDK environment, then launches an entry point (dispatch -application) for each core to be utilized. By default, the binary is generated -in the build directory. - -.. code-block:: console - - setenv RTE_SDK /home/user/DPDK - cd $(RTE_SDK) - cd examples/helloworld/ - setenv RTE_SDK $HOME/DPDK - setenv RTE_TARGET x86_64-native-freebsd-gcc - - gmake CC=gcc49 - CC main.o - LD helloworld - INSTALL-APP helloworld - INSTALL-MAP helloworld.map +.. note:: - ls build/app - helloworld helloworld.map + BSD make cannot be used to compile the DPDK example applications. GNU + make can be installed using `pkg install gmake` if not already installed + on the FreeBSD system. -.. note:: +The following shows how to compile the helloworld example app, following +the installation of DPDK using `ninja install` as described previously:: - In the above example, ``helloworld`` was in the directory structure of the - DPDK. However, it could have been located outside the directory - structure to keep the DPDK structure intact. In the following case, - the ``helloworld`` application is copied to a new directory as a new starting - point. + $ export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig -.. code-block:: console + $ cd examples/helloworld/ - setenv RTE_SDK /home/user/DPDK - cp -r $(RTE_SDK)/examples/helloworld my_rte_app - cd my_rte_app/ - setenv RTE_TARGET x86_64-native-freebsd-gcc + $ gmake + cc -O3 -I/usr/local/include -include rte_config.h -march=native + -D__BSD_VISIBLE main.c -o build/helloworld-shared + -L/usr/local/lib -lrte_telemetry -lrte_bpf -lrte_flow_classify + -lrte_pipeline -lrte_table -lrte_port -lrte_fib -lrte_ipsec + -lrte_stack -lrte_security -lrte_sched -lrte_reorder -lrte_rib + -lrte_rcu -lrte_rawdev -lrte_pdump -lrte_member -lrte_lpm + -lrte_latencystats -lrte_jobstats -lrte_ip_frag -lrte_gso -lrte_gro + -lrte_eventdev -lrte_efd -lrte_distributor -lrte_cryptodev + -lrte_compressdev -lrte_cfgfile -lrte_bitratestats -lrte_bbdev + -lrte_acl -lrte_timer -lrte_hash -lrte_metrics -lrte_cmdline + -lrte_pci -lrte_ethdev -lrte_meter -lrte_net -lrte_mbuf + -lrte_mempool -lrte_ring -lrte_eal -lrte_kvargs + ln -sf helloworld-shared build/helloworld - gmake CC=gcc49 - CC main.o - LD helloworld - INSTALL-APP helloworld - INSTALL-MAP helloworld.map .. _running_sample_app: @@ -88,29 +57,15 @@ Running a Sample Application Abstraction Layer (EAL) library, which provides some options that are generic to every DPDK application. -The following is the list of options that can be given to the EAL: - -.. code-block:: console - - ./rte-app -l CORELIST [-n NUM] [-b ] \ - [-r NUM] [-v] [--proc-type ] - -.. note:: - - EAL has a common interface between all operating systems and is based on the - Linux notation for PCI devices. For example, a FreeBSD device selector of - ``pci0:2:0:1`` is referred to as ``02:00.1`` in EAL. - -The EAL options for FreeBSD are as follows: +A large number of options can be given to the EAL when running an +application. A full list of options can be got by passing `--help` to a +DPDK application. Some of the EAL options for FreeBSD are as follows: * ``-c COREMASK`` or ``-l CORELIST``: A hexadecimal bit mask of the cores to run on. Note that core numbering can change between platforms and should be determined beforehand. The corelist is a list of cores to use instead of a core mask. -* ``-n NUM``: - Number of memory channels per processor socket. - * ``-b ``: Blacklisting of ports; prevent EAL from using specified PCI device (multiple ``-b`` options are allowed). @@ -119,15 +74,9 @@ The EAL options for FreeBSD are as follows: Use the specified Ethernet device(s) only. Use comma-separate ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option. -* ``-r NUM``: - Number of memory ranks. - * ``-v``: Display version information on startup. -* ``--proc-type``: - The type of process instance. - * ``-m MB``: Memory to allocate from hugepages, regardless of processor socket. @@ -147,19 +96,6 @@ Other options, specific to Linux and are not supported under FreeBSD are as foll The ``-c`` or ``-l`` option is mandatory; the others are optional. -Copy the DPDK application binary to your target, then run the application -as follows (assuming the platform has four memory channels, and that cores 0-3 -are present and are to be used for running the application):: - - ./helloworld -l 0-3 -n 4 - -.. note:: - - The ``--proc-type`` and ``--file-prefix`` EAL options are used for running multiple - DPDK processes. See the "Multi-process Sample Application" chapter - in the *DPDK Sample Applications User Guide and the DPDK - Programmers Guide* for more details. - .. _running_non_root: Running DPDK Applications Without Root Privileges