doc: reword some sample app guides

I have reviewed these sections for grammar/clarity
and made small modifications to the formatting of sections
to adhere to a template which will create uniformality
in the sample application user guides overall.

Signed-off-by: Nandini Persad <[email protected]>
Acked-by: Chengwen Feng <[email protected]>

.mailmap

@@ -1064,6 +1064,7 @@ Naga Suresh Somarowthu <[email protected]>
 Nalla Pradeep <[email protected]>
 Na Na <[email protected]>
 Nan Chen <[email protected]>
+Nandini Persad <[email protected]>
 Nannan Lu <[email protected]>
 Nan Zhou <[email protected]>
 Narcisa Vasile <[email protected]> <[email protected]> <[email protected]>

doc/guides/sample_app_ug/cmd_line.rst

@@ -13,7 +13,7 @@ Overview
 The Command Line sample application is a simple application that
 demonstrates the use of the command line interface in the DPDK.
 This application is a readline-like interface that can be used
-to debug a DPDK application, in a Linux* application environment.
+to debug a DPDK application in a Linux* application environment.
 
 .. note::
 
@@ -22,10 +22,13 @@ to debug a DPDK application, in a Linux* application environment.
     See also the "rte_cmdline library should not be used in production code due to limited testing" item
     in the "Known Issues" section of the Release Notes.
 
-The Command Line sample application supports some of the features of the GNU readline library such as, completion,
-cut/paste and some other special bindings that make configuration and debug faster and easier.
+The Command Line sample application supports some of the features of the GNU readline library
+such as completion, cut/paste and other special bindings
+that make configuration and debug faster and easier.
+
+The application shows how the ``cmdline`` library can be extended
+to handle a list of objects.
 
-The application shows how the rte_cmdline application can be extended to handle a list of objects.
 There are three simple commands:
 
 *   add obj_name IP: Add a new object with an IP/IPv6 address associated to it.
@@ -48,7 +51,7 @@ The application is located in the ``cmd_line`` sub-directory.
 Running the Application
 -----------------------
 
-To run the application in linux environment, issue the following command:
+To run the application in a Linux environment, issue the following command:
 
 .. code-block:: console
 
@@ -60,7 +63,7 @@ and the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide some explanation of the code.
+The following sections provide explanation of the code.
 
 EAL Initialization and cmdline Start
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -73,21 +76,22 @@ This is achieved as follows:
     :start-after: Initialization of the Environment Abstraction Layer (EAL). 8<
     :end-before: >8 End of initialization of Environment Abstraction Layer (EAL).
 
-Then, a new command line object is created and started to interact with the user through the console:
+Then, a new command line object is created and starts to interact with the user through the console:
 
 .. literalinclude:: ../../../examples/cmdline/main.c
     :language: c
     :start-after: Creating a new command line object. 8<
     :end-before: >8 End of creating a new command line object.
     :dedent: 1
 
-The cmd line_interact() function returns when the user types **Ctrl-d** and in this case,
-the application exits.
+The ``cmdline_interact()`` function returns when the user types **Ctrl-d** and,
+in this case, the application exits.
 
 Defining a cmdline Context
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A cmdline context is a list of commands that are listed in a NULL-terminated table, for example:
+A cmdline context is a list of commands that are listed in a NULL-terminated table.
+For example:
 
 .. literalinclude:: ../../../examples/cmdline/commands.c
     :language: c

doc/guides/sample_app_ug/dma.rst

@@ -10,10 +10,10 @@ Overview
 --------
 
 This sample is intended as a demonstration of the basic components of a DPDK
-forwarding application and example of how to use the DMAdev API to make a packet
+forwarding application and an example of how to use the DMAdev API to make a packet
 copy application.
 
-Also while forwarding, the MAC addresses are affected as follows:
+Also, while forwarding, the MAC addresses are affected as follows:
 
 *   The source MAC address is replaced by the TX port MAC address
 
@@ -27,7 +27,7 @@ received/send packets and packets dropped or failed to copy.
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``dma`` sub-directory.
 
@@ -38,8 +38,7 @@ Running the Application
 In order to run the hardware copy application, the copying device
 needs to be bound to user-space IO driver.
 
-Refer to the "DMAdev library" chapter in the "Programmers guide" for information
-on using the library.
+Refer to the :doc:`../prog_guide/dmadev` for information on using the library.
 
 The application requires a number of command line options:
 
@@ -70,11 +69,11 @@ where,
 
 *   i SI: set the interval, in second, between statistics prints (default is 1)
 
-The application can be launched in various configurations depending on
+The application can be launched in various configurations depending on the
 provided parameters. The app can use up to 2 lcores: one of them receives
 incoming traffic and makes a copy of each packet. The second lcore then
-updates MAC address and sends the copy. If one lcore per port is used,
-both operations are done sequentially. For each configuration an additional
+updates the MAC address and sends the copy. If one lcore per port is used,
+both operations are done sequentially. For each configuration, an additional
 lcore is needed since the main lcore does not handle traffic but is
 responsible for configuration, statistics printing and safe shutdown of
 all ports and devices.
@@ -159,7 +158,7 @@ multiple DMA channels per port:
     :end-before: >8 End of configuring port to use RSS for multiple RX queues.
     :dedent: 1
 
-For this example the ports are set up with the number of Rx queues provided
+For this example, the ports are set up with the number of Rx queues provided
 with -q option and 1 Tx queue using the ``rte_eth_rx_queue_setup()``
 and ``rte_eth_tx_queue_setup()`` functions.
 
@@ -172,7 +171,7 @@ The Ethernet port is then started:
     :dedent: 1
 
 
-Finally the Rx port is set in promiscuous mode:
+Finally, the Rx port is set in promiscuous mode:
 
 .. literalinclude:: ../../../examples/dma/dmafwd.c
     :language: c
@@ -181,7 +180,7 @@ Finally the Rx port is set in promiscuous mode:
     :dedent: 1
 
 
-After that each port application assigns resources needed.
+After that, each port application assigns resources needed.
 
 .. literalinclude:: ../../../examples/dma/dmafwd.c
     :language: c
@@ -224,7 +223,7 @@ using ``rte_dma_start()`` function. Each of the above operations is done in
 If initialization is successful, memory for hardware device
 statistics is allocated.
 
-Finally ``main()`` function starts all packet handling lcores and starts
+Finally, the ``main()`` function starts all packet handling lcores and starts
 printing stats in a loop on the main lcore. The application can be
 interrupted and closed using ``Ctrl-C``. The main lcore waits for
 all worker lcores to finish, deallocates resources and exits.
@@ -273,13 +272,13 @@ packet using ``pktmbuf_sw_copy()`` function and enqueue them to an rte_ring:
     :dedent: 0
 
 The packets are received in burst mode using ``rte_eth_rx_burst()``
-function. When using hardware copy mode the packets are enqueued in
+function. When using hardware copy mode the packets are enqueued in the
 copying device's buffer using ``dma_enqueue_packets()`` which calls
 ``rte_dma_copy()``. When all received packets are in the
-buffer the copy operations are started by calling ``rte_dma_submit()``.
+buffer, the copy operations are started by calling ``rte_dma_submit()``.
 Function ``rte_dma_copy()`` operates on physical address of
 the packet. Structure ``rte_mbuf`` contains only physical address to
-start of the data buffer (``buf_iova``). Thus the ``rte_pktmbuf_iova()`` API is
+start of the data buffer (``buf_iova``). Thus, the ``rte_pktmbuf_iova()`` API is
 used to get the address of the start of the data within the mbuf.
 
 .. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -291,11 +290,11 @@ used to get the address of the start of the data within the mbuf.
 
 Once the copies have been completed (this includes gathering the completions in
 HW copy mode), the copied packets are enqueued to the ``rx_to_tx_ring``, which
-is used to pass the packets to the TX function.
+is used to pass the packets to the Tx function.
 
 All completed copies are processed by ``dma_tx_port()`` function. This function
-dequeues copied packets from the ``rx_to_tx_ring``. Then each packet MAC address is changed
-if it was enabled. After that copies are sent in burst mode using ``rte_eth_tx_burst()``.
+dequeues copied packets from the ``rx_to_tx_ring``. Then, each packet MAC address is changed
+if it was enabled. After that, copies are sent in burst mode using ``rte_eth_tx_burst()``.
 
 
 .. literalinclude:: ../../../examples/dma/dmafwd.c
@@ -307,7 +306,7 @@ if it was enabled. After that copies are sent in burst mode using ``rte_eth_tx_b
 The Packet Copying Functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In order to perform SW packet copy, there are user-defined functions to first copy
+In order to perform SW packet copy, there are user-defined functions to the first copy
 the packet metadata (``pktmbuf_metadata_copy()``) and then the packet data
 (``pktmbuf_sw_copy()``):
 
@@ -321,5 +320,4 @@ The metadata in this example is copied from ``rx_descriptor_fields1`` marker of
 ``rte_mbuf`` struct up to ``buf_len`` member.
 
 In order to understand why software packet copying is done as shown
-above please refer to the "Mbuf Library" section of the
-*DPDK Programmer's Guide*.
+above, please refer to the :doc:`../prog_guide/mbuf_lib`.

doc/guides/sample_app_ug/ethtool.rst

@@ -4,6 +4,12 @@
 Ethtool Sample Application
 ==========================
 
+This chapter describes the Ethtool sample application
+that is part of the Data Plane Development Kit (DPDK).
+
+Overview
+--------
+
 The Ethtool sample application shows an implementation of an
 ethtool-like API and provides a console environment that allows
 its use to query and change Ethernet card parameters. The sample
@@ -30,17 +36,14 @@ Refer to the *DPDK Getting Started Guide* for general information on
 running applications and the Environment Abstraction Layer (EAL)
 options.
 
-Using the application
----------------------
-
 The application is console-driven using the cmdline DPDK interface:
 
 .. code-block:: console
 
         EthApp>
 
-From this interface the available commands and descriptions of what
-they do as follows:
+From this interface, the available commands and descriptions
+of what they do are as follows:
 
 * ``drvinfo``: Print driver info
 * ``eeprom``: Dump EEPROM to file
@@ -80,7 +83,7 @@ Ethtool Shell
 ~~~~~~~~~~~~~
 
 The foreground part of the Ethtool sample is a console-based
-interface that accepts commands as described in `using the
+interface that accepts commands as described in `running the
 application`_. Individual call-back functions handle the detail
 associated with each command, which make use of the functions
 defined in the `Ethtool interface`_ to the DPDK functions.

doc/guides/sample_app_ug/flow_filtering.rst

@@ -4,6 +4,9 @@
 Flow Filtering Sample Application
 =================================
 
+Overview
+--------
+
 The flow filtering sample application provides a simple example of creating flow rules.
 
 It serves as a demonstration of the fundamental components of flow rules.
@@ -14,7 +17,7 @@ It demonstrates how to create rules and configure them, using both template and
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``flow_filtering`` sub-directory.
 

doc/guides/sample_app_ug/hello_world.rst

@@ -4,6 +4,10 @@
 Hello World Sample Application
 ==============================
 
+
+Overview
+--------
+
 The Hello World sample application is an example of the simplest DPDK application that can be written.
 The application simply prints an "helloworld" message on every enabled lcore.
 
@@ -29,7 +33,7 @@ and the Environment Abstraction Layer (EAL) options.
 Explanation
 -----------
 
-The following sections provide some explanation of code.
+The following sections provide an explanation of the code.
 
 EAL Initialization
 ~~~~~~~~~~~~~~~~~~

doc/guides/sample_app_ug/intro.rst

@@ -4,17 +4,17 @@
 Introduction to the DPDK Sample Applications
 ============================================
 
-The DPDK Sample Applications are small standalone applications which
+The DPDK Sample Applications are small standalone applications that
 demonstrate various features of DPDK. They can be considered as a cookbook of
-DPDK features.  Users interested in getting started with DPDK can take the
+DPDK features. Users interested in getting started with DPDK can take the
 applications, try out the features, and then extend them to fit their needs.
 
 
 Running Sample Applications
 ---------------------------
 
 Some sample applications may have their own command-line parameters described in
-their respective guides, however all of them also share the same EAL parameters.
+their respective guides. However, they all also share the same EAL parameters.
 Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>`
 or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for
 a list of available EAL command-line options.
@@ -24,16 +24,16 @@ The DPDK Sample Applications
 ----------------------------
 
 There are many sample applications available in the examples directory of DPDK.
-These examples range from simple to reasonably complex but most are designed
+These examples range from simple to reasonably complex, but most are designed
 to demonstrate one particular feature of DPDK. Some of the more interesting
 examples are highlighted below.
 
 
 * :doc:`Hello World<hello_world>`: As with most introductions to a
-  programming framework a good place to start is with the Hello World
+  programming framework, a good place to start is with the Hello World
   application. The Hello World example sets up the DPDK Environment Abstraction
   Layer (EAL), and prints a simple "Hello World" message to each of the DPDK
-  enabled cores. This application doesn't do any packet forwarding but it is a
+  enabled cores. This application doesn't do any packet forwarding, but it is a
   good way to test if the DPDK environment is compiled and set up properly.
 
 * :doc:`Basic Forwarding/Skeleton Application<skeleton>`: The Basic
@@ -72,19 +72,19 @@ examples are highlighted below.
 
 * :doc:`RX/TX callbacks Application<rxtx_callbacks>`: The RX/TX
   callbacks sample application is a packet forwarding application that
-  demonstrates the use of user defined callbacks on received and transmitted
+  demonstrates the use of user-defined callbacks on received and transmitted
   packets. The application calculates the latency of a packet between RX
   (packet arrival) and TX (packet transmission) by adding callbacks to the RX
   and TX packet processing functions.
 
 * :doc:`IPsec Security Gateway<ipsec_secgw>`: The IPsec Security
-  Gateway application is minimal example of something closer to a real world
+  Gateway application is a minimal example of something closer to a real world
   example. This is also a good example of an application using the DPDK
   Cryptodev framework.
 
 * :doc:`Precision Time Protocol (PTP) client<ptpclient>`: The PTP
   client is another minimal implementation of a real world application.
-  In this case the application is a PTP client that communicates with a PTP
+  In this case, the application is a PTP client that communicates with a PTP
   time transmitter to synchronize time on a Network Interface Card (NIC) using the
   IEEE1588 protocol.
 
@@ -93,4 +93,4 @@ examples are highlighted below.
 
 There are many more examples shown in the following chapters. Each of the
 documented sample applications show how to compile, configure and run the
-application as well as explaining the main functionality of the code.
+application, as well as explaining the main functionality of the code.

doc/guides/sample_app_ug/ip_frag.rst

@@ -25,17 +25,18 @@ There are three key differences from the L2 Forwarding sample application:
 *   The third difference is that the application differentiates between
     IP and non-IP traffic by means of offload flags.
 
-The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table is used to store/lookup an outgoing port number,
-associated with that IP address.
+The Longest Prefix Match (LPM for IPv4, LPM6 for IPv6) table
+is used to store/lookup an outgoing port number associated with that IP address.
 Any unmatched packets are forwarded to the originating port.
 
 By default, input frame sizes up to 9.5 KB are supported.
-Before forwarding, the input IP packet is fragmented to fit into the "standard" Ethernet* v2 MTU (1500 bytes).
+Before forwarding, the input IP packet is fragmented
+to fit into the "standard" Ethernet* v2 MTU (1500 bytes).
 
 Compiling the Application
 -------------------------
 
-To compile the sample application see :doc:`compiling`.
+To compile the sample application, see :doc:`compiling`.
 
 The application is located in the ``ip_fragmentation`` sub-directory.
 
@@ -46,7 +47,7 @@ The LPM object is created and loaded with the pre-configured entries read from
 global l3fwd_ipv4_route_array and l3fwd_ipv6_route_array tables.
 For each input packet, the packet forwarding decision
 (that is, the identification of the output interface for the packet) is taken as a result of LPM lookup.
-If the IP packet size is greater than default output MTU,
+If the IP packet size is greater than the default output MTU,
 then the input packet is fragmented and several fragments are sent via the output interface.
 
 Application usage: