[dpdk-dev] [PATCH v5 2/2] doc: add new introduction to sample app guides

[Marko Kovacevic <marko.kovacevic@intel.com>]

Add new Introduction Section into the sample app guides.

Signed-off-by: Marko Kovacevic <marko.kovacevic@intel.com>
Reviewed-by: John McNamara <john.mcnamara@intel.com>
---

v5:
   All changes to your comments have been dealt with (John)


 doc/guides/faq/faq.rst                             |   2 +-
 doc/guides/sample_app_ug/dist_app.rst              |   2 +
 doc/guides/sample_app_ug/exception_path.rst        |   2 +-
 doc/guides/sample_app_ug/hello_world.rst           |   2 +
 doc/guides/sample_app_ug/index.rst                 |   2 +
 doc/guides/sample_app_ug/intro.rst                 | 153 +++++++++++++++------
 doc/guides/sample_app_ug/ipsec_secgw.rst           |   2 +
 .../sample_app_ug/l2_forward_real_virtual.rst      |   2 +-
 doc/guides/sample_app_ug/l3_forward.rst            |   2 +
 doc/guides/sample_app_ug/multi_process.rst         |   2 +-
 doc/guides/sample_app_ug/ptpclient.rst             |   1 +
 doc/guides/sample_app_ug/qos_scheduler.rst         |   2 +
 doc/guides/sample_app_ug/rxtx_callbacks.rst        |   1 +
 doc/guides/sample_app_ug/server_node_efd.rst       |   2 +-
 doc/guides/sample_app_ug/skeleton.rst              |   1 +
 15 files changed, 133 insertions(+), 45 deletions(-)

diff --git a/doc/guides/faq/faq.rst b/doc/guides/faq/faq.rst
index dac8050..da9b484 100644
--- a/doc/guides/faq/faq.rst
+++ b/doc/guides/faq/faq.rst
@@ -221,7 +221,7 @@ I350 has RSS support and 8 queue pairs can be used in RSS mode. It should work w
 How can hugepage-backed memory be shared among multiple processes?
 ------------------------------------------------------------------
 
-See the Primary and Secondary examples in the :ref:`multi-process sample application <multi_process_app>`.
+See the Primary and Secondary examples in the :ref:`multi-process sample application <sample_app_multi_process_app>`.
 
 
 Why can't my application receive packets on my system with UEFI Secure Boot enabled?
diff --git a/doc/guides/sample_app_ug/dist_app.rst b/doc/guides/sample_app_ug/dist_app.rst
index 466115d..0431b97 100644
--- a/doc/guides/sample_app_ug/dist_app.rst
+++ b/doc/guides/sample_app_ug/dist_app.rst
@@ -28,6 +28,8 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _sample_app_dist_app:
+
 Distributor Sample Application
 ==============================
 
diff --git a/doc/guides/sample_app_ug/exception_path.rst b/doc/guides/sample_app_ug/exception_path.rst
index 2dee8bf..40e5b5c 100644
--- a/doc/guides/sample_app_ug/exception_path.rst
+++ b/doc/guides/sample_app_ug/exception_path.rst
@@ -115,7 +115,7 @@ The following sections provide some explanation of the code.
 Initialization
 ~~~~~~~~~~~~~~
 
-Setup of the mbuf pool, driver and queues is similar to the setup done in the :ref:`l2_fwd_app_real_and_virtual`.
+Setup of the mbuf pool, driver and queues is similar to the setup done in the :ref:`sample_app_l2_fwd`.
 In addition, the TAP interfaces must also be created.
 A TAP interface is created for each lcore that is being used.
 The code for creating the TAP interface is as follows:
diff --git a/doc/guides/sample_app_ug/hello_world.rst b/doc/guides/sample_app_ug/hello_world.rst
index 8196702..8cf23a3 100644
--- a/doc/guides/sample_app_ug/hello_world.rst
+++ b/doc/guides/sample_app_ug/hello_world.rst
@@ -28,6 +28,8 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _sample_app_hello_world:
+
 Hello World Sample Application
 ==============================
 
diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index 4f8340a..163b468 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -1,4 +1,5 @@
 ..  BSD LICENSE
+
     Copyright(c) 2010-2015 Intel Corporation. All rights reserved.
     All rights reserved.
 
@@ -28,6 +29,7 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+
 Sample Applications User Guides
 ===============================
 
diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst
index d3f261b..9498d3d 100644
--- a/doc/guides/sample_app_ug/intro.rst
+++ b/doc/guides/sample_app_ug/intro.rst
@@ -1,5 +1,5 @@
 ..  BSD LICENSE
-    Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
+    Copyright(c) 2010-2017 Intel Corporation. All rights reserved.
     All rights reserved.
 
     Redistribution and use in source and binary forms, with or without
@@ -28,42 +28,115 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-Introduction
-============
-
-This document describes the sample applications that are included in the Data Plane Development Kit (DPDK).
-Each chapter describes a sample application that showcases specific functionality and
-provides instructions on how to compile, run and use the sample application.
-
-Documentation Roadmap
----------------------
-
-The following is a list of DPDK documents in 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.
-
-*   **Getting Started Guides** : Describes how to install and
-    configure the DPDK software for your operating system;
-    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 content of the DPDK, the build system
-        (including the commands that can be used in the root 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
-
-A glossary of terms is also provided.
-
-*   **API Reference**  : Provides detailed information about 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.
+Introduction to the DPDK Sample Applications
+============================================
+
+The DPDK Sample Applications are small standalone applications which
+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
+applications, try out the features, and then extend them to fit their needs.
+
+
+The DPDK Sample Applications
+----------------------------
+
+Table :numref:`table_sample_apps` shows a list of some of the main sample
+applications that are available in the examples directory of DPDK:
+
+ .. _table_sample_apps:
+
+ .. table:: **Some of the DPDK Sample applications**
+
+    +---------------------------------------+--------------------------------------+
+    | Bonding                               | Netmap Compatibility                 |
+    +---------------------------------------+--------------------------------------+
+    | Command Line                          | Packet Ordering                      |
+    +---------------------------------------+--------------------------------------+
+    | Distributor                           | Performance Thread                   |
+    +---------------------------------------+--------------------------------------+
+    | Ethtool                               | Precision Time Protocol (PTP) Client |
+    +---------------------------------------+--------------------------------------+
+    | Exception Path                        | Quality of Service (QoS) Metering    |
+    +---------------------------------------+--------------------------------------+
+    | Hello World                           | QoS Scheduler                        |
+    +---------------------------------------+--------------------------------------+
+    | Internet Protocol (IP) Fragmentation  | Quota and Watermark                  |
+    +---------------------------------------+--------------------------------------+
+    | IP Pipeline                           | RX/TX Callbacks                      |
+    +---------------------------------------+--------------------------------------+
+    | IP Reassembly                         | Server node EFD                      |
+    +---------------------------------------+--------------------------------------+
+    | IPsec Security Gateway                | Basic Forwarding/Skeleton App        |
+    +---------------------------------------+--------------------------------------+
+    | IPv4 multicast                        | Tunnel End Point (TEP) termination   |
+    +---------------------------------------+--------------------------------------+
+    | Kernel NIC Interface                  | Timer                                |
+    +---------------------------------------+--------------------------------------+
+    | Network Layer 2 Forwarding + variants | Vhost                                |
+    +---------------------------------------+--------------------------------------+
+    | Network Layer 3 Forwarding + variants | Vhost Xen                            |
+    +---------------------------------------+--------------------------------------+
+    | Link Status Interrupt                 | VMDQ Forwarding                      |
+    +---------------------------------------+--------------------------------------+
+    | Load Balancer                         | VMDQ and DCB Forwarding              |
+    +---------------------------------------+--------------------------------------+
+    | Multi-process                         | VM Power Management                  |
+    +---------------------------------------+--------------------------------------+
+
+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.
+
+
+* :ref:`Hello World<sample_app_hello_world>`: As with most introductions to a
+  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
+  good way to test if the DPDK environment is compiled and set up properly.
+
+* :ref:`Basic Forwarding/Skeleton Application<sample_app_basic_fwd>`: The Basic
+  Forwarding/Skeleton contains the minimum amount of code required to enable
+  basic packet forwarding with DPDK. This allows you to test if your network
+  interfaces are working with DPDK.
+
+* :ref:`Network Layer 2 forwarding<sample_app_l2_fwd>`: The Network Layer 2
+  forwarding, or ``l2fwd`` application does forwarding based on Ethernet MAC
+  addresses like a simple switch.
+
+* :ref:`Network Layer 3 forwarding<sample_app_l3_fwd>`: The Network Layer3
+  forwarding, or ``l3fwd`` application does forwarding based on Internet
+  Protocol, IPv4 or IPv6 like a simple router.
+
+* :ref:`Packet Distributor<sample_app_dist_app>`: The Packet Distributor
+  demonstrates how to distribute packets arriving on an Rx port to different
+  cores for processing and transmission.
+
+* :ref:`Multi-Process Application<sample_app_multi_process_app>`: The
+  multi-process application shows how two DPDK processes can work together using
+  queues and memory pools to share information.
+
+* :ref:`RX/TX callbacks Application<sample_app_rxtx_callbck>`: The RX/TX
+  callbacks sample application is a packet forwarding application that
+  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.
+
+* :ref:`IPSec Security Gateway<sample_app_ipsec_secgw>`: The IPSec Security
+  Gateway application is minimal example of something closer to a real world
+  example. This is also a good example of an application using the DPDK
+  Cryptodev framework.
+
+* :ref:`Precision Time Protocol (PTP) client<sample_app_ptp_client>`: 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
+  master clock to synchronize time on a Network Interface Card (NIC) using the
+  IEEE1588 protocol.
+
+* :ref:`Quality of Service (QoS) Scheduler<sample_app_qos_scheduler>`: The QoS
+  Scheduler application demonstrates the use of DPDK to provide QoS scheduling.
+
+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.
diff --git a/doc/guides/sample_app_ug/ipsec_secgw.rst b/doc/guides/sample_app_ug/ipsec_secgw.rst
index c6af171..8efa614 100644
--- a/doc/guides/sample_app_ug/ipsec_secgw.rst
+++ b/doc/guides/sample_app_ug/ipsec_secgw.rst
@@ -28,6 +28,8 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _sample_app_ipsec_secgw:
+
 IPsec Security Gateway Sample Application
 =========================================
 
diff --git a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst
index ba64ea2..901603e 100644
--- a/doc/guides/sample_app_ug/l2_forward_real_virtual.rst
+++ b/doc/guides/sample_app_ug/l2_forward_real_virtual.rst
@@ -28,7 +28,7 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-.. _l2_fwd_app_real_and_virtual:
+.. _sample_app_l2_fwd:
 
 L2 Forwarding Sample Application (in Real and Virtualized Environments)
 =======================================================================
diff --git a/doc/guides/sample_app_ug/l3_forward.rst b/doc/guides/sample_app_ug/l3_forward.rst
index 1eb12c4..c80bc31 100644
--- a/doc/guides/sample_app_ug/l3_forward.rst
+++ b/doc/guides/sample_app_ug/l3_forward.rst
@@ -28,6 +28,8 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _sample_app_l3_fwd:
+
 L3 Forwarding Sample Application
 ================================
 
diff --git a/doc/guides/sample_app_ug/multi_process.rst b/doc/guides/sample_app_ug/multi_process.rst
index 4b6df70..51c7ef4 100644
--- a/doc/guides/sample_app_ug/multi_process.rst
+++ b/doc/guides/sample_app_ug/multi_process.rst
@@ -28,7 +28,7 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-.. _multi_process_app:
+.. _sample_app_multi_process_app:
 
 Multi-process Sample Application
 ================================
diff --git a/doc/guides/sample_app_ug/ptpclient.rst b/doc/guides/sample_app_ug/ptpclient.rst
index b456e33..9710a87 100644
--- a/doc/guides/sample_app_ug/ptpclient.rst
+++ b/doc/guides/sample_app_ug/ptpclient.rst
@@ -28,6 +28,7 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _sample_app_ptp_client:
 
 PTP Client Sample Application
 =============================
diff --git a/doc/guides/sample_app_ug/qos_scheduler.rst b/doc/guides/sample_app_ug/qos_scheduler.rst
index e618e2a..79e3ff7 100644
--- a/doc/guides/sample_app_ug/qos_scheduler.rst
+++ b/doc/guides/sample_app_ug/qos_scheduler.rst
@@ -28,6 +28,8 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _sample_app_qos_scheduler:
+
 QoS Scheduler Sample Application
 ================================
 
diff --git a/doc/guides/sample_app_ug/rxtx_callbacks.rst b/doc/guides/sample_app_ug/rxtx_callbacks.rst
index 4feb19b..4dc4a9f 100644
--- a/doc/guides/sample_app_ug/rxtx_callbacks.rst
+++ b/doc/guides/sample_app_ug/rxtx_callbacks.rst
@@ -28,6 +28,7 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _sample_app_rxtx_callbck:
 
 RX/TX Callbacks Sample Application
 ==================================
diff --git a/doc/guides/sample_app_ug/server_node_efd.rst b/doc/guides/sample_app_ug/server_node_efd.rst
index ee7d460..facdd28 100644
--- a/doc/guides/sample_app_ug/server_node_efd.rst
+++ b/doc/guides/sample_app_ug/server_node_efd.rst
@@ -36,7 +36,7 @@ load balancer, for more information about the EFD Library please refer to the
 DPDK programmer's guide.
 
 This sample application is a variant of the
-:ref:`client-server sample application <multi_process_app>`
+:ref:`client-server sample application <sample_app_multi_process_app>`
 where a specific target node is specified for every and each flow
 (not in a round-robin fashion as the original load balancing sample application).
 
diff --git a/doc/guides/sample_app_ug/skeleton.rst b/doc/guides/sample_app_ug/skeleton.rst
index 4eb65af..66d0004 100644
--- a/doc/guides/sample_app_ug/skeleton.rst
+++ b/doc/guides/sample_app_ug/skeleton.rst
@@ -28,6 +28,7 @@
     (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+.. _sample_app_basic_fwd:
 
 Basic Forwarding Sample Application
 ===================================
-- 
2.5.5