From patchwork Thu Oct 5 11:12:37 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: "Kovacevic, Marko" X-Patchwork-Id: 29679 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 29D121AEE8; Thu, 5 Oct 2017 13:12:55 +0200 (CEST) Received: from mga03.intel.com (mga03.intel.com [134.134.136.65]) by dpdk.org (Postfix) with ESMTP id E448637B1 for ; Thu, 5 Oct 2017 13:12:52 +0200 (CEST) Received: from orsmga003.jf.intel.com ([10.7.209.27]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 05 Oct 2017 04:12:51 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos; i="5.42,481,1500966000"; d="scan'208"; a="1021949007" Received: from silpixa00379011.ir.intel.com (HELO silpixa00379011.ger.corp.intel.com) ([10.237.223.212]) by orsmga003.jf.intel.com with ESMTP; 05 Oct 2017 04:12:50 -0700 From: Marko Kovacevic To: john.mcnamara@intel.com Cc: dev@dpdk.org, marko.kovacevic@intel.com Date: Thu, 5 Oct 2017 12:12:37 +0100 Message-Id: <1507201957-237765-2-git-send-email-marko.kovacevic@intel.com> X-Mailer: git-send-email 2.5.5 In-Reply-To: <1507201957-237765-1-git-send-email-marko.kovacevic@intel.com> References: <1507201957-237765-1-git-send-email-marko.kovacevic@intel.com> MIME-Version: 1.0 Subject: [dpdk-dev] [PATCH v4 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 --- 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 `. +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..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 ` +: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 ===================================