doc: adjust line lengths in freebsd guide
authorBruce Richardson <bruce.richardson@intel.com>
Mon, 24 Nov 2014 15:48:56 +0000 (15:48 +0000)
committerThomas Monjalon <thomas.monjalon@6wind.com>
Fri, 5 Dec 2014 16:28:34 +0000 (17:28 +0100)
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 <bruce.richardson@intel.com>
Acked-by: Bernard Iremonger <bernard.iremonger@intel.com>
doc/guides/freebsd_gsg/build_dpdk.rst
doc/guides/freebsd_gsg/build_sample_apps.rst
doc/guides/freebsd_gsg/intro.rst
doc/guides/freebsd_gsg/sys_reqs.rst

index 9b78840..8f72a5e 100644 (file)
@@ -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=<target> 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=<target> 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=<target> 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 <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.
+    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.
 
 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
 
index 7e85467..3b2d0c1 100644 (file)
 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 <domain:bus:devid.func>
-    : 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
 
index bb19615..fc27ed0 100644 (file)
 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 <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.
index 2314f39..8ce0ba4 100644 (file)
@@ -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::