[dpdk-dev,v7,2/2] doc: add new introduction to sample app guides
Checks
Commit Message
Add new Introduction Section into the sample app guides.
Signed-off-by: Marko Kovacevic <marko.kovacevic@intel.com>
---
V7:
removed :ref: targets. (Thomas)
doc/guides/faq/faq.rst | 2 +-
doc/guides/sample_app_ug/dist_app.rst | 1 +
doc/guides/sample_app_ug/exception_path.rst | 2 +-
doc/guides/sample_app_ug/hello_world.rst | 1 +
doc/guides/sample_app_ug/index.rst | 2 +
doc/guides/sample_app_ug/intro.rst | 153 +++++++++++++++------
doc/guides/sample_app_ug/ipsec_secgw.rst | 1 +
.../sample_app_ug/l2_forward_real_virtual.rst | 1 -
doc/guides/sample_app_ug/l3_forward.rst | 1 +
doc/guides/sample_app_ug/multi_process.rst | 1 -
doc/guides/sample_app_ug/qos_scheduler.rst | 1 +
doc/guides/sample_app_ug/server_node_efd.rst | 2 +-
12 files changed, 123 insertions(+), 45 deletions(-)
Comments
> -----Original Message-----
> From: Kovacevic, Marko
> Sent: Monday, October 16, 2017 3:51 PM
> To: Mcnamara, John <john.mcnamara@intel.com>
> Cc: dev@dpdk.org; Kovacevic, Marko <marko.kovacevic@intel.com>
> Subject: [PATCH v7 2/2] doc: add new introduction to sample app guides
>
> Add new Introduction Section into the sample app guides.
>
> Signed-off-by: Marko Kovacevic <marko.kovacevic@intel.com>
>
> ---
>
Hi Marko,
There are some doc build issues with missing targets.
$ make doc-guides-html -j
sphinx processing guides-html...
doc/guides/faq/faq.rst:224: WARNING: undefined label:
sample_app_multi_process_app (if the link has no caption the label must precede a section header)
doc/guides/sample_app_ug/exception_path.rst:118: WARNING: undefined label:
sample_app_l2_fwd (if the link has no caption the label must precede a section header)
doc/guides/sample_app_ug/server_node_efd.rst:38: WARNING: undefined label:
sample_app_multi_process_app (if the link has no caption the label must precede a section header)
Also some of the files extraneous added blank lines.
John
@@ -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?
@@ -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.
+
Distributor Sample Application
==============================
@@ -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:
@@ -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.
+
Hello World Sample Application
==============================
@@ -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
===============================
@@ -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.
+
+
+* :doc:`Hello World<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.
+
+* :doc:`Basic Forwarding/Skeleton Application<skeleton>`: 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.
+
+* :doc:`Network Layer 2 forwarding<l2_forward_real_virtual>`: The Network Layer 2
+ forwarding, or ``l2fwd`` application does forwarding based on Ethernet MAC
+ addresses like a simple switch.
+
+* :doc:`Network Layer 3 forwarding<l3_forward>`: The Network Layer3
+ forwarding, or ``l3fwd`` application does forwarding based on Internet
+ Protocol, IPv4 or IPv6 like a simple router.
+
+* :doc:`Packet Distributor<dist_app>`: The Packet Distributor
+ demonstrates how to distribute packets arriving on an Rx port to different
+ cores for processing and transmission.
+
+* :doc:`Multi-Process Application<multi_process>`: The
+ multi-process application shows how two DPDK processes can work together using
+ queues and memory pools to share information.
+
+* :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
+ 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
+ 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
+ master clock to synchronize time on a Network Interface Card (NIC) using the
+ IEEE1588 protocol.
+
+* :doc:`Quality of Service (QoS) Scheduler<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.
@@ -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.
+
IPsec Security Gateway Sample Application
=========================================
@@ -28,7 +28,6 @@
(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:
L2 Forwarding Sample Application (in Real and Virtualized Environments)
=======================================================================
@@ -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.
+
L3 Forwarding Sample Application
================================
@@ -28,7 +28,6 @@
(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:
Multi-process Sample Application
================================
@@ -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.
+
QoS Scheduler Sample Application
================================
@@ -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).