X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fsample_app_ug%2Fintro.rst;h=8ff223b16c4a4078677f122fd61464f2af1bb835;hb=c12f4f217d8519582d60050a928b68a965a7b37c;hp=d3f261b341c23133c33c78e6d9b050b07b44e361;hpb=e0c7c47319576799f5affced83caf776ea4de61b;p=dpdk.git diff --git a/doc/guides/sample_app_ug/intro.rst b/doc/guides/sample_app_ug/intro.rst index d3f261b341..8ff223b16c 100644 --- a/doc/guides/sample_app_ug/intro.rst +++ b/doc/guides/sample_app_ug/intro.rst @@ -1,69 +1,96 @@ -.. BSD LICENSE - Copyright(c) 2010-2014 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (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. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2010-2017 Intel Corporation. + +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. + + +Running Sample Applications +--------------------------- + +Some sample applications may have their own command-line parameters described in +their respective guides, however all of them also share the same EAL parameters. +Please refer to :doc:`EAL parameters (Linux) <../linux_gsg/linux_eal_parameters>` +or :doc:`EAL parameters (FreeBSD) <../freebsd_gsg/freebsd_eal_parameters>` for +a list of available EAL command-line options. + + +The DPDK Sample Applications +---------------------------- + +There are many sample applications available in the examples directory of DPDK. +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`: 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`: 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`: The Network Layer 2 + forwarding, or ``l2fwd`` application does forwarding based on Ethernet MAC + addresses like a simple switch. + +* :doc:`Network Layer 2 forwarding`: The Network Layer 2 + forwarding, or ``l2fwd-event`` application does forwarding based on Ethernet MAC + addresses like a simple switch. It demonstrates usage of poll and event mode + IO mechanism under a single application. + +* :doc:`Network Layer 3 forwarding`: The Network Layer3 + forwarding, or ``l3fwd`` application does forwarding based on Internet + Protocol, IPv4 or IPv6 like a simple router. + +* :doc:`Network Layer 3 forwarding Graph`: The Network Layer3 + forwarding Graph, or ``l3fwd_graph`` application does forwarding based on IPv4 + like a simple router with DPDK Graph framework. + +* :doc:`Hardware packet copying`: The Hardware packet copying, + or ``ioatfwd`` application demonstrates how to use IOAT rawdev driver for + copying packets between two threads. + +* :doc:`Packet Distributor`: The Packet Distributor + demonstrates how to distribute packets arriving on an Rx port to different + cores for processing and transmission. + +* :doc:`Multi-Process Application`: 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`: 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`: 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`: 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`: 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.