X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Ffreebsd_gsg%2Fbuild_dpdk.rst;h=5fdab4472c48b51131d60ff9576e0434bebfba86;hb=3e7b87dddbbf9c6bc27fcb7bbce41618853ad678;hp=8f72a5ea3da3e18e2f737a6360a0b7c6dc113d02;hpb=f9e2411af05c407d177dd92b4d18343ca3b269b6;p=dpdk.git 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 - -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: - -.. code-block:: console - - gmake config T=x86_64-native-bsdapp-gcc CC=gcc48 + gmake install T=x86_64-native-bsdapp-clang -To build after configuration, change directory to ./x86_64-native-bsdapp-gcc and use: - -.. code-block:: console +.. note:: - 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. + +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, 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. + +.. _binding_network_ports: -Device ownership can be viewed using the pciconf -l command. +Binding Network Ports to the nic_uio Module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The example below shows four Intel® 82599 network ports under if_ixgbe module ownership. +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. - -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 +Binding Network Ports Back to their Original Kernel Driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - 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 - -.. code-block:: console - - kenv -u hw.nic_uio.bdfs - -to remove all network ports from nic_uio and undefined this system variable OR + kenv -u hw.nic_uio.bdfs # to clear the value completely -.. 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