From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga14.intel.com (mga14.intel.com [192.55.52.115]) by dpdk.org (Postfix) with ESMTP id 556957F50 for ; Tue, 2 Dec 2014 15:08:39 +0100 (CET) Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by fmsmga103.fm.intel.com with ESMTP; 02 Dec 2014 05:56:11 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.07,501,1413270000"; d="scan'208";a="631384843" Received: from irvmail001.ir.intel.com ([163.33.26.43]) by fmsmga001.fm.intel.com with ESMTP; 02 Dec 2014 06:02:49 -0800 Received: from sivswdev02.ir.intel.com (sivswdev02.ir.intel.com [10.237.217.46]) by irvmail001.ir.intel.com (8.14.3/8.13.6/MailSET/Hub) with ESMTP id sB2E2lV4007647; Tue, 2 Dec 2014 14:02:47 GMT Received: from sivswdev02.ir.intel.com (localhost [127.0.0.1]) by sivswdev02.ir.intel.com with ESMTP id sB2E2lcY005072; Tue, 2 Dec 2014 14:02:47 GMT Received: (from sabutler@localhost) by sivswdev02.ir.intel.com with id sB2E2la5005068; Tue, 2 Dec 2014 14:02:47 GMT From: Siobhan Butler To: dev@dpdk.org Date: Tue, 2 Dec 2014 14:02:46 +0000 Message-Id: <1417528966-4974-1-git-send-email-siobhan.a.butler@intel.com> X-Mailer: git-send-email 1.7.4.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subject: [dpdk-dev] =?utf-8?q?=5BPATCH=5D_Doc=3A_Adding_Distributor_Sample?= =?utf-8?q?_Application_to_Sample_App_UG?= X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 02 Dec 2014 14:08:48 -0000 New distributor sample app user guide section for sample app ug. Signed-off-by: Siobhan Butler --- doc/guides/sample_app_ug/dist_app.rst | 173 +++++++++++ doc/guides/sample_app_ug/img/dist_app.svg | 442 +++++++++++++++++++++++++++ doc/guides/sample_app_ug/img/dist_perf.svg | 459 +++++++++++++++++++++++++++++ doc/guides/sample_app_ug/index.rst | 5 + 4 files changed, 1079 insertions(+) create mode 100644 doc/guides/sample_app_ug/dist_app.rst create mode 100644 doc/guides/sample_app_ug/img/dist_app.svg create mode 100644 doc/guides/sample_app_ug/img/dist_perf.svg diff --git a/doc/guides/sample_app_ug/dist_app.rst b/doc/guides/sample_app_ug/dist_app.rst new file mode 100644 index 0000000..3064ff8 --- /dev/null +++ b/doc/guides/sample_app_ug/dist_app.rst @@ -0,0 +1,173 @@ +.. 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. + +Distributor Sample Application +============================== + +The distributor sample application is a simple example of packet distribution +to cores using the Data Plane Development Kit (DPDK). + +Overview +-------- + +The distributor application performs the distribution of packets that are received +on an RX_PORT to different cores. When processed by the cores, the destination +port of a packet is the port from the enabled port mask adjacent to the one on +which the packet was received, that is, if the first four ports are enabled +(port mask 0xf), ports 0 and 1 RX/TX into each other, and ports 2 and 3 RX/TX +into each other. + +This application can be used to benchmark performance using the traffic +generator as shown in the figure below. + +.. _figure_22: + +**Figure 22. Performance Benchmarking Setup (Basic Environment)** + +|dist_perf| + +Compiling the Application +------------------------- + +#. Go to the sample application directory: + + .. code-block:: console + + export RTE_SDK=/path/to/rte_sdk + cd ${RTE_SDK}/examples/l3fwd-acl + +#. Set the target (a default target is used if not specified). For example: + + .. code-block:: console + + export RTE_TARGET=x86_64-native-linuxapp-gcc + + See the DPDK Getting Started Guide for possible RTE_TARGET values. + +#. Build the application: + + .. code-block:: console + + make + +Running the Application +----------------------- + +#. The application has a number of command line options: + +.. code-block:: console + + ./build/distributor_app [EAL options] -- -p PORTMASK + +where, + +* -p PORTMASK: Hexadecimal bitmask of ports to configure + +#. To run the application in linuxapp environment with 11 lcores, 4 ports, +issue the command: + +.. code-block:: console + + $ ./build/distributor_app -c 0x4003fe -n 4 -- -p f + +#. Refer to the DPDK Getting Started Guide for general information on running +applications and the Environment Abstraction Layer (EAL) options. + +Explanation +----------- + +The distributor application consists of three types of threads: a receive +thread (lcore_rx()), a set of worker threads(locre_worker()) +and a transmit thread(lcore_tx()).How these threads work together is shown +in Fig2 below. The main() function launches threads of these three types. +Each thread has a while loop which will be doing processing and which is +terminated only upon SIGINT or ctrl+C. The receive and transmit threads +communicate using a software ring (rte_ring structure). + +The receive thread receives the packets using rte_eth_rx_burst()and gives +them to the distributor (using rte_distributor_process() API) which will +be called in context of the receive thread itself. The distributor distributes +the packets to workers threads based on the tagging of the packet - +indicated by the hash field in the mbuf. For IP traffic, this field is +automatically filled by the NIC with the "usr" hash value for the packet, +which works as a per-flow tag. + +More than one worker thread can exist as part of the application, and these +worker threads do simple packet processing by requesting packets from +the distributor, doing a simple XOR operation on the input port mbuf field +(to indicate the output port which will be used later for packet transmission) +and then finally returning the packets back to the distributor in the RX thread. + +Meanwhile, the receive thread will call the distributor api +rte_distributor_returned_pkts() to get the packets processed, and will enqueue +them to a ring for transfer to the TX thread for transmission on the output port. +The transmit thread will dequeue the packets from the ring and transmit them on +the output port specified in packet mbuf. + +Users who wish to terminate the running of the application have to press ctrl+C +(or send SIGINT to the app). Upon this signal, a signal handler provided +in the application will terminate all running threads gracefully and print +final statistics to the user. + +.. _figure_23: + +**Figure 23.Distributor Sample Application Layout** + +|dist_app| + +Debug Logging Support +--------------------- + +Debug logging is provided as part of the application; the user needs to uncomment +the line "#define DEBUG" defined in start of the application in main.c to enable debug logs. + +Statistics +---------- + +Upon SIGINT (or) ctrl+C, the print_stats() function displays the count of packets +processed at the different stages in the application. + +Application Initialization +-------------------------- + +Command line parsing is done in the same way as it is done in the L2 Forwarding Sample +Application. See Section 9.4.1, "Command Line Arguments". +Mbuf pool initialization is done in the same way as it is done in the L2 Forwarding +Sample Application. See Section 9.4.2, "Mbuf Pool Initialization". +Driver Initialization is done in same way as it is done in the L2 Forwarding Sample +Application. See Section 9.4.3, "Driver Initialization". +RX queue initialization is done in the same way as it is done in the L2 Forwarding +Sample Application. See Section 9.4.4, "RX Queue Initialization". +TX queue initialization is done in the same way as it is done in the L2 Forwarding +Sample Application. See Section 9.4.5, "TX Queue Initialization". + +.. |dist_perf| image:: img/dist_perf.svg + +.. |dist_app| image:: img/dist_app.svg diff --git a/doc/guides/sample_app_ug/img/dist_app.svg b/doc/guides/sample_app_ug/img/dist_app.svg new file mode 100644 index 0000000..3bb912b --- /dev/null +++ b/doc/guides/sample_app_ug/img/dist_app.svg @@ -0,0 +1,442 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + Request packet + Mbuf pointer + WorkerThread1 + WorkerThread2 + WorkerThread3 + WorkerThreadN + TX thread + RX thread & Distributor + + + Mbufs In + Mbufs Out + + SW Ring + + diff --git a/doc/guides/sample_app_ug/img/dist_perf.svg b/doc/guides/sample_app_ug/img/dist_perf.svg new file mode 100644 index 0000000..5a2720b --- /dev/null +++ b/doc/guides/sample_app_ug/img/dist_perf.svg @@ -0,0 +1,459 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + Port2 + Port0 + DPDK board + Traffic Generator + Port1 + Port3 + + + + + + + + + + + + + + + Port2 + Port0 + Port1 + Port3 + + diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst index ad2ca28..47abe40 100644 --- a/doc/guides/sample_app_ug/index.rst +++ b/doc/guides/sample_app_ug/index.rst @@ -100,6 +100,7 @@ Copyright © 2012 - 2014, Intel Corporation. All rights reserved. netmap_compatibility internet_proto_ip_pipeline test_pipeline + dist_app **Figures** @@ -147,6 +148,10 @@ Copyright © 2012 - 2014, Intel Corporation. All rights reserved. :ref:`Figure 21.Test Pipeline Application ` +:ref:`Figure 22.Performance Benchmarking Setup (Basic Environment) ` + +:ref:`Figure 23.Distributor Sample Application Layout ` + **Tables** :ref:`Table 1.Output Traffic Marking ` -- 1.9.4.msysgit.2