From: Bruce Richardson Date: Mon, 24 Nov 2014 15:48:56 +0000 (+0000) Subject: doc: adjust line lengths in freebsd guide X-Git-Tag: spdx-start~9978 X-Git-Url: http://git.droids-corp.org/?a=commitdiff_plain;h=f9e2411af05c407d177dd92b4d18343ca3b269b6;p=dpdk.git doc: adjust line lengths in freebsd guide The FreeBSD GSG rst files had very inconsistent line lengths for text within paragraph blocks. Sometimes a line would be very short, while often lines would be quite long. This patch adjusts the formatting of the rst files so that lines break at approx the 80-character mark, as is standard in the DPDK source code. Signed-off-by: Bruce Richardson Acked-by: Bernard Iremonger --- diff --git a/doc/guides/freebsd_gsg/build_dpdk.rst b/doc/guides/freebsd_gsg/build_dpdk.rst index 9b788408cc..8f72a5ea3d 100644 --- a/doc/guides/freebsd_gsg/build_dpdk.rst +++ b/doc/guides/freebsd_gsg/build_dpdk.rst @@ -70,7 +70,8 @@ Where: * TOOLCHAIN is: gcc -The configuration files for the Intel® DPDK targets can be found in the DPDK/config directory in the form of: +The configuration files for the Intel® DPDK targets can be found in the DPDK/config +directory in the form of: :: @@ -79,10 +80,10 @@ The configuration files for the Intel® DPDK targets can be found in the DPDK/co .. 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 *Intel® DPDK Programmers Guide*. + 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 *Intel® DPDK Programmers Guide*. To install and make the target, use gmake install T= CC=gcc48. @@ -92,9 +93,8 @@ For example to compile for FreeBSD* use: 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: +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 @@ -106,13 +106,14 @@ To build after configuration, change directory to ./x86_64-native-bsdapp-gcc and gmake CC=gcc48 -Browsing the Installed Intel®DPDK Environment Target ----------------------------------------------------- +Browsing the Installed Intel® DPDK Environment Target +----------------------------------------------------- -Once a target is created, it contains all the libraries -and header files for the Intel® 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: +Once a target is created, it contains all the libraries and header files for the +Intel® 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: .. code-block:: console @@ -122,17 +123,19 @@ A kmod directory is also present that contains the kernel modules to install: 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 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): .. code-block:: console kldload ./kmod/contigmem.ko -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: +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: :: @@ -140,11 +143,13 @@ This can be achieved by copying the module to the /boot/kernel/ directory and pl .. note:: - The contigmem_load directive should be placed after any definitions of hw.contigmem.num_buffers - and hw.contigmem.buffer_size if the default values are not to be used. + The contigmem_load directive should be placed after any definitions of + 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 available and can be verified via dmesg or /var/log/messages: +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 +available and can be verified via dmesg or /var/log/messages: .. code-block:: console @@ -155,8 +160,10 @@ To avoid this error, reduce the number of buffers or the buffer size. Loading the Intel® DPDK nic_uio Module -------------------------------------- -After loading the contigmem module, the nic_uio must also be loaded into the running kernel prior to running any Intel® DPDK application. -This module must be loaded using the kldload command as shown below (assuming that the current directory is the Intel® DPDK target directory). +After loading the contigmem module, the nic_uio must also be loaded into the +running kernel prior to running any Intel® DPDK application. This module must +be loaded using the kldload command as shown below (assuming that the current +directory is the Intel® DPDK target directory). .. code-block:: console @@ -164,12 +171,13 @@ This module must be loaded using the kldload command as shown below (assuming th .. 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. + 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. To load the module during boot, copy the nic_uio module to /boot/kernel and place the following into /boot/loader.conf: @@ -184,8 +192,8 @@ To load the module during boot, copy the nic_uio module to /boot/kernel and plac 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. +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. Device ownership can be viewed using the pciconf -l command. @@ -209,45 +217,53 @@ The first column constitutes three components: Where no driver is associated with a device, the device name will be none. -By default, the FreeBSD* kernel will include built-in drivers for the most common devices; -a kernel rebuild would normally be required to either remove the drivers or configure them as loadable modules. +By default, the FreeBSD* kernel will include built-in drivers for the most common +devices; a kernel rebuild would normally be required to either remove the drivers +or configure them as loadable modules. -To avoid building a custom kernel, the nic_uio module can detach a network port 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: +To avoid building a custom kernel, the nic_uio module can detach a network port +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,..." -Where a comma separated list of selectors is set, the list must not contain any whitespace. +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 upon loading, use the following command: +For example to re-bind ix2@pci0:2:0:0 and ix3@pci0:2:0: 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: +The variable can also be specified during boot by placing the following into +/boot/loader.conf: :: hw.nic_uio.bdfs="2:0:0,2:0:1" -To restore the original device binding, -it is necessary to reboot FreeBSD* if the original driver has been compiled into the kernel. +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; +Update or remove the hw.nic_uio.bdfs entry in /boot/loader.conf if specified there +for persistency, then; .. code-block:: console reboot -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. +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. -Update or remove the hw.nic_uio.bdfs entry from /boot/loader.conf if specified there for persistency. +Update or remove the hw.nic_uio.bdfs entry from /boot/loader.conf if specified +there for persistency. .. code-block:: console diff --git a/doc/guides/freebsd_gsg/build_sample_apps.rst b/doc/guides/freebsd_gsg/build_sample_apps.rst index 7e85467805..3b2d0c1460 100644 --- a/doc/guides/freebsd_gsg/build_sample_apps.rst +++ b/doc/guides/freebsd_gsg/build_sample_apps.rst @@ -31,14 +31,15 @@ Compiling and Running Sample Applications ========================================= -The chapter describes how to compile and run applications in an Intel® DPDK environment. -It also provides a pointer to where sample applications are stored. +The chapter describes how to compile and run applications in an Intel® DPDK +environment. It also provides a pointer to where sample applications are stored. 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 to build an 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 +to build an application. When compiling an application in the FreeBSD* environment on the Intel® DPDK, the following variables must be exported: @@ -48,15 +49,15 @@ the following variables must be exported: * RTE_TARGET - Points to the Intel® DPDK target environment directory. For FreeBSD*, this is the 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 ${RTE_SDK}/examples 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 +${RTE_SDK}/examples directory. -The directory contains the main.c file. -This file, when combined with the libraries in the Intel® DPDK target environment, -calls the various functions to initialize the Intel® 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. +The directory contains the main.c file. This file, when combined with the +libraries in the Intel® DPDK target environment, calls the various functions to +initialize the Intel® 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 @@ -73,9 +74,11 @@ By default, the binary is generated in the build directory. .. note:: - In the above example, helloworld was in the directory structure of the Intel® DPDK. - However, it could have been located outside the directory structure to keep the Intel® DPDK structure intact. - In the following case, the helloworld application is copied to a new directory as a new starting point. + In the above example, helloworld was in the directory structure of the + Intel® DPDK. However, it could have been located outside the directory + structure to keep the Intel® DPDK structure intact. In the following case, + the helloworld application is copied to a new directory as a new starting + point. .. code-block:: console @@ -96,8 +99,9 @@ Running a Sample 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. - 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. + 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. The following is the list of options that can be given to the EAL: @@ -107,25 +111,27 @@ The following is the list of options that can be given to the EAL: .. 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. + 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. The EAL options for FreeBSD* are as follows: * -c COREMASK - : A hexadecimal bit mask of the cores to run on. - Note that core numbering can change between platforms and should be determined beforehand. + : A hexadecimal bit mask of the cores to run on. Note that core numbering + can change between platforms and should be determined beforehand. * -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). + : blacklisting of ports; prevent EAL from using specified PCI device + (multiple -b options are allowed). * --use-device - : use the specified ethernet device(s) only. - Use comma-separate <[domain:]bus:devid.func> values. Cannot be used with -b option. + : 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. @@ -153,9 +159,9 @@ Other options, specific to Linux* and are not supported under FreeBSD* are as fo The -c and the -n options are mandatory; the others are optional. -Copy the Intel® 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): +Copy the Intel® 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): .. code-block:: console @@ -163,18 +169,20 @@ and that cores 0-3 are present and are to be used for running the application): .. note:: - The --proc-type and --file-prefix EAL options are used for running multiple Intel® DPDK processes. - See the “Multi-process Sample Application” chapter in the - *Intel® DPDK Sample Applications User Guide and the Intel® DPDK Programmers Guide* for more details. + The --proc-type and --file-prefix EAL options are used for running multiple + Intel® DPDK processes. See the “Multi-process Sample Application” chapter + in the *Intel® DPDK Sample Applications User Guide and the Intel® DPDK + Programmers Guide* for more details. Running Intel®DPDK Applications Without Root Privileges ------------------------------------------------------- -Although applications using the Intel® DPDK use network ports and other hardware resources directly, -with a number of small permission adjustments, -it is possible to run these applications as a user other than “root”. -To do so, the ownership, or permissions, on the following file system objects should be adjusted to ensure -that the user account being used to run the Intel® DPDK application has access to them: +Although applications using the Intel® DPDK use network ports and other hardware +resources directly, with a number of small permission adjustments, it is possible +to run these applications as a user other than “root”. To do so, the ownership, +or permissions, on the following file system objects should be adjusted to ensure +that the user account being used to run the Intel® DPDK application has access +to them: * The userspace-io device files in /dev, for example, /dev/uio0, /dev/uio1, and so on diff --git a/doc/guides/freebsd_gsg/intro.rst b/doc/guides/freebsd_gsg/intro.rst index bb19615f4c..fc27ed01aa 100644 --- a/doc/guides/freebsd_gsg/intro.rst +++ b/doc/guides/freebsd_gsg/intro.rst @@ -31,12 +31,14 @@ 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® DPDK application in a FreeBSD* application (bsdapp) environment, -without going deeply into detail. +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® +DPDK application in a FreeBSD* application (bsdapp) environment, without going +deeply into detail. -For a comprehensive guide to installing and using FreeBSD*, the following handbook is available from the FreeBSD* Documentation Project: +For a comprehensive guide to installing and using FreeBSD*, the following +handbook is available from the FreeBSD* Documentation Project: `http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/index.html `_ @@ -45,30 +47,36 @@ DocumentationRoadmap The following is a list of Intel® DPDK documents in the suggested reading order: -* **Release Notes** : Provides release-specific information, including supported features, limitations, fixed issues, known issues and so on. - Also, provides the answers to frequently asked questions in FAQ format. +* **Release Notes** : Provides release-specific information, including supported + features, limitations, fixed issues, known issues and so on. Also, provides the + answers to frequently asked questions in FAQ format. -* **Getting Started Guide** (this document): Describes how to install and configure the Intel® DPDK; - designed to get users up and running quickly with the software. +* **Getting Started Guide** (this document): Describes how to install and + configure the Intel® DPDK; designed to get users up and running quickly with the + software. * **Programmer's Guide**: Describes: - * The software architecture and how to use it (through examples), specifically in a Linux* application (linuxapp) environment + * The software architecture and how to use it (through examples), + specifically in a Linux* application (linuxapp) environment - * The content of the Intel® DPDK, the build system - (including the commands that can be used in the root Intel® DPDK Makefile to build the development kit and an application) - and guidelines for porting an application + * The content of the Intel® DPDK, the build system (including the commands + that can be used in the root Intel® DPDK Makefile 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 + * Optimizations used in the software and those that should be considered + for new development A glossary of terms is also provided. -* **API Reference**: Provides detailed information about Intel® DPDK functions, data structures and other programming constructs. +* **API Reference**: Provides detailed information about Intel® DPDK functions, + data structures and other programming constructs. * **Sample Applications User Guide**: Describes a set of sample applications. - Each chapter describes a sample application that showcases specific functionality and provides instructions on how to compile, - run and use the sample application. + Each chapter describes a sample application that showcases specific functionality + and provides instructions on how to compile, run and use the sample application. .. note:: - These documents are available for download as a separate documentation package at the same location as the Intel® DPDK code package. + These documents are available for download as a separate documentation + package at the same location as the Intel® DPDK code package. diff --git a/doc/guides/freebsd_gsg/sys_reqs.rst b/doc/guides/freebsd_gsg/sys_reqs.rst index 2314f3951b..8ce0ba48c5 100644 --- a/doc/guides/freebsd_gsg/sys_reqs.rst +++ b/doc/guides/freebsd_gsg/sys_reqs.rst @@ -39,27 +39,28 @@ 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. + 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. + 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: +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: +If the environment requires proxies for external communication, these can be set +using: .. code-block:: console @@ -107,8 +108,8 @@ The ports required and their locations are as follows: * /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. +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:: @@ -120,24 +121,24 @@ 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. +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 +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: +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: +The kernel environment variables can also be specified during boot by placing the +following in /boot/loader.conf: :: @@ -149,9 +150,9 @@ The variables can be inspected using the following command: 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. +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::