Add new Introduction Section into the sample app guides.
Signed-off-by: Marko Kovacevic <[email protected]>
---
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 | 152 +++++++++++++++------
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, 132 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..b276714 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,114 @@
(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
+============================================
+
+This article describes the Data Plane Development Kit Sample Applications.
+
+The DPDK Sample Applications are small standalone applications which
demonstrate
+various features of DPDK. They can be considered a cookbook of DPDK features.
+User 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_:
+ .. 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 reasonable complex but most are designed to
+demonstrate one particular feature of DPDK. Some of the more interesting
+examples are highlighted below.
+
+
+* :ref:`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
+ applicatioin doesn’t do any packet formatting but it is a good way to test if
+ the DPDK environment is compiled and set up properly.
+
+* :ref:`sample_app_basic_fwd`: The Basic Forwarding/Skeleton contains the
+ minimum amount of code required to enable basic packet forwarding with DPDK.
+ This will allow the user to test if their network interfaces are working with
+ DPDK.
+
+* :ref:`sample_app_l2_fwd`: The Network Layer 2 forwarding, or l2fwd
+ application does forwarding based on Ethernet MAC addresses like a simple
+ switch.
+
+* :ref:`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:`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:`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:`sample_app_rxtx_callbck`: The RX/TX callbacks sample application is
+ apacket forwarding application that demonstrates the use of user defined
+ callbacks on received and transmitted packets. The application calculates the
+ latency of the packet between RX (packet arrival) and TX (packet
transmission)
+ by adding callbacks to the RX and TX packet processing functions.
+
+* :ref:`sample_app_ipsec_secgw`: The IPSec Security Gateway application is
+ minimal example of something closer to a real world usage example. This is
also
+ a good example of an application using the DPDK Cryptodev framework.
+
+* :ref:`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:`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 application show how to compile, configure and run the
+application as well as explaining the main code behind the functionality.
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
