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 at intel.com>
---
doc/guides/freebsd_gsg/build_dpdk.rst | 110 +++++++++++++++------------
doc/guides/freebsd_gsg/build_sample_apps.rst | 80 ++++++++++---------
doc/guides/freebsd_gsg/intro.rst | 44 ++++++-----
doc/guides/freebsd_gsg/sys_reqs.rst | 47 ++++++------
4 files changed, 157 insertions(+), 124 deletions(-)
diff --git a/doc/guides/freebsd_gsg/build_dpdk.rst
b/doc/guides/freebsd_gsg/build_dpdk.rst
index 9b78840..8f72a5e 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=<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 at pci0:2:0:0 and ix3 at pci0:2:0: to the nic_uio
module upon loading, use the following command:
+For example to re-bind ix2 at pci0:2:0:0 and ix3 at 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 7e85467..3b2d0c1 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 <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
diff --git a/doc/guides/freebsd_gsg/intro.rst b/doc/guides/freebsd_gsg/intro.rst
index bb19615..fc27ed0 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
<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 2314f39..8ce0ba4 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 at host:~ # portsnap fetch
root at 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 at host:~ # kenv hw.contigmem.num_buffers=n
root at 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 at 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::
--
1.9.3
