From patchwork Wed Oct 11 15:51:27 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Kovacevic, Marko" X-Patchwork-Id: 30154 Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id C624F1B208; Wed, 11 Oct 2017 17:51:42 +0200 (CEST) Received: from mga04.intel.com (mga04.intel.com [192.55.52.120]) by dpdk.org (Postfix) with ESMTP id 1D6AC1B201 for ; Wed, 11 Oct 2017 17:51:39 +0200 (CEST) Received: from fmsmga005.fm.intel.com ([10.253.24.32]) by fmsmga104.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 11 Oct 2017 08:51:39 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.43,361,1503385200"; d="scan'208";a="161507690" Received: from silpixa00379011.ir.intel.com (HELO silpixa00379011.ger.corp.intel.com) ([10.237.223.212]) by fmsmga005.fm.intel.com with ESMTP; 11 Oct 2017 08:51:38 -0700 From: Marko Kovacevic To: john.mcnamara@intel.com Cc: dev@dpdk.org, marko.kovacevic@intel.com Date: Wed, 11 Oct 2017 16:51:27 +0100 Message-Id: <1507737087-138205-2-git-send-email-marko.kovacevic@intel.com> X-Mailer: git-send-email 2.5.5 In-Reply-To: <1507737087-138205-1-git-send-email-marko.kovacevic@intel.com> References: <1507565946-223643-1-git-send-email-marko.kovacevic@intel.com> <1507737087-138205-1-git-send-email-marko.kovacevic@intel.com> Subject: [dpdk-dev] [PATCH v6 2/2] doc: add new introduction to sample app guides X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Add new Introduction Section into the sample app guides. Signed-off-by: Marko Kovacevic Reviewed-by: John McNamara Acked-by: John McNamara --- 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 `. +See the Primary and Secondary examples in the :ref:`multi-process sample application `. 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`: 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`: 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`: The Network Layer 2 + forwarding, or ``l2fwd`` application does forwarding based on Ethernet MAC + addresses like a simple switch. + +* :ref:`Network Layer 3 forwarding`: The Network Layer3 + forwarding, or ``l3fwd`` application does forwarding based on Internet + Protocol, IPv4 or IPv6 like a simple router. + +* :ref:`Packet Distributor`: The Packet Distributor + demonstrates how to distribute packets arriving on an Rx port to different + cores for processing and transmission. + +* :ref:`Multi-Process Application`: 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`: 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`: 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`: 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`: 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 ` +:ref:`client-server sample application ` 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 ===================================