513b07238a
MANY references in the sample applications user guide are wrong because they are hard-coded and section numbers have changed over the time. This patch changes thoses references to dynamic ones, in this way if section numbers change the reference get updated automatically. Signed-off-by: Mauricio Vasquez B <mauricio.vasquezbernal@studenti.polito.it>
176 lines
6.6 KiB
ReStructuredText
176 lines
6.6 KiB
ReStructuredText
.. 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_dist_perf:
|
|
|
|
.. figure:: img/dist_perf.*
|
|
|
|
Performance Benchmarking Setup (Basic Environment)
|
|
|
|
|
|
Compiling the Application
|
|
-------------------------
|
|
|
|
#. Go to the sample application directory:
|
|
|
|
.. code-block:: console
|
|
|
|
export RTE_SDK=/path/to/rte_sdk
|
|
cd ${RTE_SDK}/examples/distributor
|
|
|
|
#. 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 10 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(lcore_worker())
|
|
and a transmit thread(lcore_tx()). How these threads work together is shown
|
|
in :numref:`figure_dist_app` 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_dist_app:
|
|
|
|
.. figure:: img/dist_app.*
|
|
|
|
Distributor Sample Application Layout
|
|
|
|
|
|
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 :ref:`l2_fwd_app_cmd_arguments`.
|
|
|
|
Mbuf pool initialization is done in the same way as it is done in the L2 Forwarding
|
|
Sample Application. See :ref:`l2_fwd_app_mbuf_init`.
|
|
|
|
Driver Initialization is done in same way as it is done in the L2 Forwarding Sample
|
|
Application. See :ref:`l2_fwd_app_dvr_init`.
|
|
|
|
RX queue initialization is done in the same way as it is done in the L2 Forwarding
|
|
Sample Application. See :ref:`l2_fwd_app_rx_init`.
|
|
|
|
TX queue initialization is done in the same way as it is done in the L2 Forwarding
|
|
Sample Application. See :ref:`l2_fwd_app_tx_init`.
|