(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 <my_proxy_host>:<port>
+ root@host:~ # setenv ftp_proxy <my_proxy_host>:<port>
+
+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/<port_location>
+
+#. make config-recursive
+
+#. make install
+
+#. make clean
+
+Each port location can be found using:
+
+.. code-block:: console
+
+ user@host:~ # whereis <port_name>
+
+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
------------------------------------------
* 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:
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=<target> CC=gcc48.
+To install and make the target, use "gmake install T=<target>".
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=<target> 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=<target> CC=gcc4.8".
Browsing the Installed Intel® DPDK Environment Target
-----------------------------------------------------
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
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
To avoid this error, reduce the number of buffers or the buffer size.
+.. _loading_nic_uio:
+
Loading the Intel® DPDK nic_uio Module
--------------------------------------
.. note::
- Currently loaded modules can be seen by using the kldstat command. A module
- can be removed from the running kernel by using kldunload <module_name>.
- 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 <module_name>".
-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:
::
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
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
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 <original_driver>
-kldunload <original_driver>
-
-.. 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 <original_driver>
- kldload nic_uio
-(if updating the list of associated network ports)
+ kldload nic_uio # optional
git.droids-corp.org / dpdk.git / blobdiff