diff --git a/doc/guides/freebsd_gsg/build_dpdk.rst b/doc/guides/freebsd_gsg/build_dpdk.rst index 8f72a5ea3d..5fdab4472c 100644 --- a/doc/guides/freebsd_gsg/build_dpdk.rst +++ b/doc/guides/freebsd_gsg/build_dpdk.rst @@ -28,9 +28,92 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. _building_from_source: + Compiling the Intel® DPDK Target from Source ============================================ +.. note:: + + Testing has been performed using FreeBSD* 10.0-RELEASE (x86_64) and requires the + installation of the kernel sources, which should be included during the + installation of FreeBSD*. The Intel® DPDK also requires the use of FreeBSD* + ports to compile and function. + +System Requirements +------------------- + +The Intel® 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 Intel® DPDK, in which case it too must be installed prior to +compiling the Intel® DPDK. The installation of these tools is covered in this +section. + +Compiling the Intel® DPDK requires the FreeBSD kernel sources, which should be +included during the installation of FreeBSD* on the development platform. +The Intel® DPDK also requires the use of FreeBSD* ports to compile and function. + +To use the FreeBSD* ports system, it is required to update and extract the FreeBSD* +ports tree by issuing the following commands: + +.. code-block:: console + + root@host:~ # portsnap fetch + root@host:~ # portsnap extract + +If the environment requires proxies for external communication, these can be set +using: + +.. code-block:: console + + root@host:~ # setenv http_proxy : + root@host:~ # setenv ftp_proxy : + +The FreeBSD* ports below need to be installed prior to building the Intel® 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: + +.. code-block:: console + + user@host:~ # 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 Intel® DPDK with gcc, it too must be installed +from the ports collection: + +gcc: version 4.8 is recommended + /usr/ports/lang/gcc48 + (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 Intel® DPDK, the default options were used. + +.. note:: + + 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. + + Install the Intel® DPDK and Browse Sources ------------------------------------------ @@ -68,7 +151,7 @@ Where: * EXECENV is: bsdapp -* TOOLCHAIN is: gcc +* TOOLCHAIN is: gcc | clang The configuration files for the Intel® DPDK targets can be found in the DPDK/config directory in the form of: @@ -85,26 +168,20 @@ directory in the form of: on which it is built. For more information on this setting, and its possible values, see the *Intel® DPDK Programmers Guide*. -To install and make the target, use gmake install T= CC=gcc48. +To install and make the target, use "gmake install T=". For example to compile for FreeBSD* use: .. code-block:: console - gmake install T=x86_64-native-bsdapp-gcc CC=gcc48 + gmake install T=x86_64-native-bsdapp-clang -To prepare a target without building it, for example, if the configuration -changes need to be made before compilation, use the gmake config T= command: +.. note:: -.. code-block:: console - - gmake config T=x86_64-native-bsdapp-gcc CC=gcc48 - -To build after configuration, change directory to ./x86_64-native-bsdapp-gcc and use: - -.. code-block:: console - - gmake CC=gcc48 + 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.8, the command would need to be "gmake install T= CC=gcc4.8". Browsing the Installed Intel® DPDK Environment Target ----------------------------------------------------- @@ -120,13 +197,47 @@ contains the kernel modules to install: user@host:~/DPDK # ls x86_64-native-bsdapp-gcc app build hostapp include kmod lib Makefile + +.. _loading_contigmem: + Loading the Intel® DPDK contigmem Module ---------------------------------------- -To run any Intel® DPDK application, the contigmem module must be loaded into the -running kernel. The module is found in the kmod sub-directory of the Intel® DPDK -target directory. The module can be loaded using kldload (assuming that the -current directory is the Intel® DPDK target directory): +To run an Intel® 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 Intel® DPDK to use. The contigmem module must be loaded into the +running kernel before any Intel® DPDK is run. The module is found in the kmod +sub-directory of the Intel® DPDK target 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 + + root@host:~ # kenv hw.contigmem.num_buffers=n + root@host:~ # kenv hw.contigmem.buffer_size=m + +The kernel environment variables can also be specified during boot by placing the +following in /boot/loader.conf: + +:: + + hw.contigmem.num_buffers=n hw.contigmem.buffer_size=m + +The variables can be inspected using the following command: + +.. code-block:: console + + root@host:~ # sysctl -a hw.contigmem + +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 Intel® DPDK target directory): .. code-block:: console @@ -147,8 +258,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 kldload: can't load ./x86_64-native-bsdapp-gcc/kmod/contigmem.ko: -Exec format error, is generally attributed to not having enough contiguous memory +An error such as: + +.. code-block:: console + + kldload: can't load ./x86_64-native-bsdapp-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 @@ -157,6 +273,8 @@ available and can be verified via dmesg or /var/log/messages: To avoid this error, reduce the number of buffers or the buffer size. +.. _loading_nic_uio: + Loading the Intel® DPDK nic_uio Module -------------------------------------- @@ -171,15 +289,15 @@ directory is the Intel® DPDK target directory). .. note:: - Currently loaded modules can be seen by using the kldstat command. A module - can be removed from the running kernel by using kldunload . - While the nic_uio module can be loaded during boot, the module load order - cannot be guaranteed and in the case where only some ports are bound to - nic_uio and others remain in use by the original driver, it is necessary to - load nic_uio after booting into the kernel, specifically after the original - driver has been loaded. + If the ports to be used are currently bound to a existing kernel driver + then the hw.nic_uio.bdfs sysctl value will need to be set before loading the + module. Setting this value is described in the next section below. -To load the module during boot, copy the nic_uio module to /boot/kernel and place the following into /boot/loader.conf: +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: :: @@ -189,15 +307,21 @@ To load the module during boot, copy the nic_uio module to /boot/kernel and plac nic_uio_load="YES" must appear after the contigmem_load directive, if it exists. -Binding Network Ports to the nic_uio Module -------------------------------------------- - By default, the nic_uio module will take ownership of network ports if they are -recognized Intel® DPDK devices and are not owned by another module. +recognized Intel® DPDK devices and are not owned by another module. However, since +the FreeBSD kernel includes support, either built-in, or via a separate driver +module, for most network card devices, it is likely that the ports to be used are +already bound to a driver other than nic_uio. The following sub-section describe +how to query and modify the device ownership of the ports to be used by +Intel® DPDK applications. -Device ownership can be viewed using the pciconf -l command. +.. _binding_network_ports: -The example below shows four Intel® 82599 network ports under if_ixgbe module ownership. +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 @@ -232,7 +356,7 @@ kernel environment variable prior to loading nic_uio, as follows: Where a comma separated list of selectors is set, the list must not contain any whitespace. -For example to re-bind ix2@pci0:2:0:0 and ix3@pci0:2:0: to the nic_uio module +For example to re-bind "ix2\@pci0:2:0:0" and "ix3\@pci0:2:0:1" to the nic_uio module upon loading, use the following command: .. code-block:: console @@ -240,52 +364,39 @@ upon loading, use the following command: kenv hw.nic_uio.bdfs="2:0:0,2:0:1" The variable can also be specified during boot by placing the following into -/boot/loader.conf: +"/boot/loader.conf", before the previously-described "nic_uio_load" line - as +shown. :: hw.nic_uio.bdfs="2:0:0,2:0:1" + nic_uio_load="YES" -To restore the original device binding, it is necessary to reboot FreeBSD* if the -original driver has been compiled into the kernel. +Binding Network Ports Back to their Original Kernel Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For example to rebind some or all ports to the original driver: - -Update or remove the hw.nic_uio.bdfs entry in /boot/loader.conf if specified there -for persistency, then; - -.. code-block:: console - - reboot +If the original driver for a network port has been compiled into the kernel, +it is necessary to reboot FreeBSD* to restore the original device binding. Before +doing so, update or remove the "hw.nic_uio.bdfs" in "/boot/loader.conf". If rebinding to a driver that is a loadable module, the network port binding can -be reset without rebooting. This requires the unloading of the nic_uio module -and the original driver. +be reset without rebooting. To do so, unload both the target kernel module and the +nic_uio module, modify or clear the "hw.nic_uio.bdfs" kernel environment (kenv) +value, and reload the two drivers - first the original kernel driver, and then +the nic_uio driver. [The latter does not need to be reloaded unless there are +ports that are still to be bound to it]. -Update or remove the hw.nic_uio.bdfs entry from /boot/loader.conf if specified -there for persistency. +Example commands to perform these steps are shown below: .. code-block:: console kldunload nic_uio + kldunload -kldunload + kenv -u hw.nic_uio.bdfs # to clear the value completely -.. code-block:: console - - kenv -u hw.nic_uio.bdfs - -to remove all network ports from nic_uio and undefined this system variable OR - -.. code-block:: console - - kenv hw.nic_uio.bdfs="b:d:f,b:d:f,..." - -(to update nic_uio ports) - -.. code-block:: console + kenv hw.nic_uio.bdfs="b:d:f,b:d:f,..." # to update the list of ports to bind kldload - kldload nic_uio -(if updating the list of associated network ports) + kldload nic_uio # optional diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst index 3b2d0c1460..dd8c974a49 100644 --- a/doc/guides/freebsd_gsg/build_sample_apps.rst +++ b/doc/guides/freebsd_gsg/build_sample_apps.rst @@ -28,6 +28,8 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. _compiling_sample_apps: + Compiling and Running Sample Applications ========================================= @@ -38,7 +40,7 @@ Compiling a Sample Application ------------------------------ Once an Intel® DPDK target environment directory has been created (such as -x86_64-native-bsdapp-gcc), it contains all libraries and header files required +x86_64-native-bsdapp-clang), it contains all libraries and header files required to build an application. When compiling an application in the FreeBSD* environment on the Intel® DPDK, @@ -47,10 +49,13 @@ the following variables must be exported: * RTE_SDK - Points to the Intel® DPDK installation directory. * RTE_TARGET - Points to the Intel® DPDK target environment directory. - For FreeBSD*, this is the x86_64-native-bsdapp-gcc directory. + For FreeBSD*, this is the x86_64-native-bsdapp-clang or + x86_64-native-bsdapp-gcc directory. The following is an example of creating the helloworld application, which runs -in the Intel® DPDK FreeBSD* environment. This example may be found in the +in the Intel® DPDK FreeBSD* environment. While the example demonstrates compiling +using gcc version 4.8, 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 @@ -92,13 +97,15 @@ in the build directory. INSTALL-APP helloworld INSTALL-MAP helloworld.map +.. _running_sample_app: + Running a Sample Application ---------------------------- #. The contigmem and nic_uio modules must be set up prior to running an application. #. Any ports to be used by the application must be already bound to the nic_uio module, - as described in section Section 3.6, “ , ” prior to running the application. + as described in section :ref:`binding_network_ports`, prior to running the application. The application is linked with the Intel® DPDK target environment's Environment Abstraction Layer (EAL) library, which provides some options that are generic to every Intel® DPDK application. @@ -107,14 +114,13 @@ The following is the list of options that can be given to the EAL: .. code-block:: console - ./rte-app -c COREMASK -n NUM [-b ] [-m MB] [-r NUM] [-v] [--file-prefix] [--proc-type ] + ./rte-app -c COREMASK -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. The device and function separator used is - a ":" rather than "." as seen with pciconf on FreeBSD*. For example, a - FreeBSD* device selector of pci0:2:0:1 is referred to as 02:00.1 in EAL. + 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: @@ -174,6 +180,8 @@ are present and are to be used for running the application): in the *Intel® DPDK Sample Applications User Guide and the Intel® DPDK Programmers Guide* for more details. +.. _running_non_root: + Running Intel®DPDK Applications Without Root Privileges ------------------------------------------------------- diff --git a/doc/guides/freebsd_gsg/index.rst b/doc/guides/freebsd_gsg/index.rst index 90915a8610..f84c2f84c3 100644 --- a/doc/guides/freebsd_gsg/index.rst +++ b/doc/guides/freebsd_gsg/index.rst @@ -78,6 +78,6 @@ Copyright © 2014, Intel Corporation. All rights reserved. :numbered: intro - sys_reqs + install_from_ports build_dpdk build_sample_apps diff --git a/doc/guides/freebsd_gsg/install_from_ports.rst b/doc/guides/freebsd_gsg/install_from_ports.rst new file mode 100644 index 0000000000..c946c33c25 --- /dev/null +++ b/doc/guides/freebsd_gsg/install_from_ports.rst @@ -0,0 +1,162 @@ +.. BSD LICENSE + Copyright(c) 2010-2014 Intel Corporation. All rights reserved. + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + * Neither the name of Intel Corporation nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +.. _install_from_ports: + +Installing Intel® DPDK from the Ports Collection +================================================ + +The easiest way to get up and running with the Intel® 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 at: + + https://www.freebsd.org/doc/handbook/ports-using.html + +.. note:: + + Testing has been performed using FreeBSD* 10.0-RELEASE (x86_64) and requires the + installation of the kernel sources, which should be included during the + installation of FreeBSD*. + +Installing the Intel® DPDK FreeBSD Port +--------------------------------------- + +On a system with the ports collection installed in /usr/ports, the Intel® DPDK +can be installed using the commands: + +.. code-block:: console + + root@host:~ # cd /usr/ports/net/dpdk + + root@host:~ # make install + +After the installation of the Intel® DPDK port, instructions will be printed on +how to install the kernel modules required to use the Intel® 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 + + # reserve 2 x 1G blocks of contiguous memory using contigmem driver + hw.contigmem.num_buffers=2 + hw.contigmem.buffer_size=1073741824 + contigmem_load="YES" + # identify NIC devices for Intel® DPDK apps to use and load nic_uio driver + hw.nic_uio.bdfs="2:0:0,2:0:1" + nic_uio_load="YES" + +Compiling and Running the Example Applications +---------------------------------------------- + +When the Intel® 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: + +* RTE_SDK=/usr/local/share/dpdk + +* RTE_TARGET=x86_64-native-bsdapp-clang + +.. note:: + + To install a copy of the Intel® DPDK compiled using gcc, please download the + official Intel® DPDK package from http://dpdk.org/ and install manually using + 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 + + user@host:~$ export RTE_SDK=/usr/local/share/dpdk + + user@host:~$ export RTE_TARGET=x86_64-native-bsdapp-clang + + user@host:~$ cp -r /usr/local/share/dpdk/examples/helloworld . + + user@host:~$ cd helloworld/ + + user@host:~/helloworld$ gmake + CC main.o + LD helloworld + INSTALL-APP helloworld + INSTALL-MAP helloworld.map + + user@host:~/helloworld$ sudo ./build/helloworld -c F -n 2 + EAL: Contigmem driver has 2 buffers, each of size 1GB + EAL: Sysctl reports 8 cpus + EAL: Detected lcore 0 + EAL: Detected lcore 1 + EAL: Detected lcore 2 + EAL: Detected lcore 3 + EAL: Support maximum 64 logical core(s) by configuration. + EAL: Detected 4 lcore(s) + EAL: Setting up physically contiguous memory... + EAL: Mapped memory segment 1 @ 0x802400000: physaddr:0x40000000, len 1073741824 + EAL: Mapped memory segment 2 @ 0x842400000: physaddr:0x100000000, len 1073741824 + EAL: WARNING: clock_gettime cannot use CLOCK_MONOTONIC_RAW and HPET is not available - clock timings may be less accurate. + EAL: TSC frequency is ~3569023 KHz + EAL: PCI scan found 24 devices + EAL: Master core 0 is ready (tid=0x802006400) + EAL: Core 1 is ready (tid=0x802006800) + EAL: Core 3 is ready (tid=0x802007000) + EAL: Core 2 is ready (tid=0x802006c00) + EAL: PCI device 0000:01:00.0 on NUMA socket 0 + EAL: probe driver: 8086:10fb rte_ixgbe_pmd + EAL: PCI memory mapped at 0x80074a000 + EAL: PCI memory mapped at 0x8007ca000 + EAL: PCI device 0000:01:00.1 on NUMA socket 0 + EAL: probe driver: 8086:10fb rte_ixgbe_pmd + EAL: PCI memory mapped at 0x8007ce000 + EAL: PCI memory mapped at 0x80084e000 + EAL: PCI device 0000:02:00.0 on NUMA socket 0 + EAL: probe driver: 8086:10fb rte_ixgbe_pmd + EAL: PCI memory mapped at 0x800852000 + EAL: PCI memory mapped at 0x8008d2000 + EAL: PCI device 0000:02:00.1 on NUMA socket 0 + EAL: probe driver: 8086:10fb rte_ixgbe_pmd + EAL: PCI memory mapped at 0x801b3f000 + EAL: PCI memory mapped at 0x8008d6000 + hello from core 1 + hello from core 2 + hello from core 3 + hello from core 0 + +.. note:: + + To run an Intel® DPDK process as a non-root user, adjust the permissions on + the /dev/contigmem and /dev/uio device nodes as described in section + :ref:`running_non_root` + +.. note:: + For an explanation of the command-line parameters that can be passed to an + Intel® DPDK application, see section :ref:`running_sample_app`. diff --git a/doc/guides/freebsd_gsg/intro.rst b/doc/guides/freebsd_gsg/intro.rst index fc27ed01aa..59c17cffbb 100644 --- a/doc/guides/freebsd_gsg/intro.rst +++ b/doc/guides/freebsd_gsg/intro.rst @@ -33,7 +33,7 @@ Introduction This document contains instructions for installing and configuring the Intel® Data Plane Development Kit(Intel® DPDK) software. It is designed to get customers -up and running quickly. The document describes how to compile and run an Intel® +up and running quickly and describes how to compile and run an Intel® DPDK application in a FreeBSD* application (bsdapp) environment, without going deeply into detail. @@ -42,8 +42,15 @@ handbook is available from the FreeBSD* Documentation Project: `http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html `_ -DocumentationRoadmap --------------------- +.. note:: + + The Intel® 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 Intel® DPDK on FreeBSD, and is documented in the + next chapter, :ref:`install_from_ports`. + +Documentation Roadmap +--------------------- The following is a list of Intel® DPDK documents in the suggested reading order: diff --git a/doc/guides/freebsd_gsg/sys_reqs.rst b/doc/guides/freebsd_gsg/sys_reqs.rst deleted file mode 100644 index 8ce0ba48c5..0000000000 --- a/doc/guides/freebsd_gsg/sys_reqs.rst +++ /dev/null @@ -1,164 +0,0 @@ -.. BSD LICENSE - Copyright(c) 2010-2014 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - -System Requirements -=================== - -This chapter describes the packages required to compile the Intel® DPDK. - -Compilationofthe Intel® DPDK ----------------------------- - -.. note:: - - The Intel® DPDK and its applications requires the GNU make system (gmake) - and the GNU Compiler Collection (gcc) to build on FreeBSD*. The - installation of these tools is covered in this section. - -**Required Tools:** - -.. note:: - - Testing has been performed using FreeBSD* 9.2-RELEASE (x86_64), FreeBSD* - 10.0-RELEASE (x86_64) and requires the installation of the kernel sources, - which should be included during the installation of FreeBSD*. The Intel® - DPDK also requires the use of FreeBSD* ports to compile and function. - -To use the FreeBSD* ports system, it is required to update and extract the FreeBSD* -ports tree by issuing the following commands: - -.. code-block:: console - - root@host:~ # portsnap fetch - root@host:~ # portsnap extract - -If the environment requires proxies for external communication, these can be set -using: - -.. code-block:: console - - root@host:~ # setenv http_proxy : - root@host:~ # setenv ftp_proxy : - -The FreeBSD* ports below need to be installed prior to building the Intel® 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: - -.. code-block:: console - - user@host:~ # whereis - -The ports required and their locations are as follows: - -* dialog4ports - -* /usr/ports/ports-mgmt/dialog4ports - -* gcc: version 4.8 is recommended - -* /usr/ports/lang/gcc48 - -* Ensure that CPU_OPTS is selected (default is OFF) - -* GNU make(gmake) - -* Installed automatically with gcc48 - -* coreutils - -* /usr/ports/sysutils/coreutils - -* libexecinfo (Not required for FreeBSD* 10) - -* /usr/src/contrib/libexecinfo - -When running the make config-recursive command, a dialog may be presented to the -user. For the installation of the Intel® DPDK, the default options were used. - -.. note:: - - 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. - -Running Intel® DPDK Applications --------------------------------- - -To run an Intel® 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 Intel® DPDK to use. Section 3.4, “Loading the Intel® DPDK -Contigmem Module” on page 8 for details on the loading of this module. - -Using Intel® DPDK Contigmem Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The amount of physically contiguous memory along with the number of physically -contiguous blocks can be set at runtime and prior to module loading using: - -.. code-block:: console - - root@host:~ # kenv hw.contigmem.num_buffers=n - root@host:~ # kenv hw.contigmem.buffer_size=m - -The kernel environment variables can also be specified during boot by placing the -following in /boot/loader.conf: - -:: - - hw.contigmem.num_buffers=n hw.contigmem.buffer_size=m - -The variables can be inspected using the following command: - -.. code-block:: console - - root@host:~ # sysctl -a hw.contigmem - -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. - -.. note:: - - The /boot/loader.conf file may not exist, but can be created as a root user - and should be given permissions as follows: - -.. code-block:: console - - root@host:~ # chmod 644 /boot/loader.conf