-.. BSD LICENSE
- Copyright(c) 2010-2015 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.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2015 Intel Corporation.
L2 Forwarding Sample Application (in Real and Virtualized Environments) with core load statistics.
==================================================================================================
* The destination MAC address is replaced by 02:00:00:00:00:TX_PORT_ID
-This application can be used to benchmark performance using a traffic-generator, as shown in the Figure 3.
+This application can be used to benchmark performance using a traffic-generator, as shown in the :numref:`figure_l2_fwd_benchmark_setup_jobstats`.
-The application can also be used in a virtualized environment as shown in Figure 4.
+The application can also be used in a virtualized environment as shown in :numref:`figure_l2_fwd_virtenv_benchmark_setup_jobstats`.
The L2 Forwarding application can also be used as a starting point for developing a new application based on the DPDK.
-.. _figure_3:
+.. _figure_l2_fwd_benchmark_setup_jobstats:
-**Figure 3. Performance Benchmark Setup (Basic Environment)**
+.. figure:: img/l2_fwd_benchmark_setup.*
-.. image4_png has been replaced
+ Performance Benchmark Setup (Basic Environment)
-|l2_fwd_benchmark_setup|
+.. _figure_l2_fwd_virtenv_benchmark_setup_jobstats:
-.. _figure_4:
+.. figure:: img/l2_fwd_virtenv_benchmark_setup.*
-**Figure 4. Performance Benchmark Setup (Virtualized Environment)**
+ Performance Benchmark Setup (Virtualized Environment)
-.. image5_png has been renamed
-
-|l2_fwd_virtenv_benchmark_setup|
Virtual Function Setup Instructions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Compiling the Application
-------------------------
-#. Go to the example directory:
-
- .. code-block:: console
-
- export RTE_SDK=/path/to/rte_sdk cd ${RTE_SDK}/examples/l2fwd-jobstats
-
-#. 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:
+To compile the sample application see :doc:`compiling`.
- .. code-block:: console
-
- make
+The application is located in the ``l2fwd-jobstats`` sub-directory.
Running the Application
-----------------------
.. code-block:: console
- $ ./build/l2fwd-jobstats -c f -n 4 -- -q 8 -p ffff -l
+ $ ./build/l2fwd-jobstats -l 0-3 -n 4 -- -q 8 -p ffff -l
Refer to the *DPDK Getting Started Guide* for general information on running applications
and the Environment Abstraction Layer (EAL) options.
~~~~~~~~~~~~~~~~~~~~~~
The L2 Forwarding sample application takes specific parameters,
-in addition to Environment Abstraction Layer (EAL) arguments (see Section 9.3).
+in addition to Environment Abstraction Layer (EAL) arguments
+(see `Running the Application`_).
The preferred way to parse parameters is to use the getopt() function,
since it is part of a well-defined and portable library.
.. code-block:: c
/* create the mbuf pool */
- l2fwd_pktmbuf_pool =
- rte_mempool_create("mbuf_pool", NB_MBUF,
- MBUF_SIZE, 32,
- sizeof(struct rte_pktmbuf_pool_private),
- rte_pktmbuf_pool_init, NULL,
- rte_pktmbuf_init, NULL,
- rte_socket_id(), 0);
+ l2fwd_pktmbuf_pool = rte_pktmbuf_pool_create("mbuf_pool", NB_MBUF,
+ MEMPOOL_CACHE_SIZE, 0, RTE_MBUF_DEFAULT_BUF_SIZE,
+ rte_socket_id());
if (l2fwd_pktmbuf_pool == NULL)
rte_exit(EXIT_FAILURE, "Cannot init mbuf pool\n");
The rte_mempool is a generic structure used to handle pools of objects.
-In this case, it is necessary to create a pool that will be used by the driver,
-which expects to have some reserved space in the mempool structure,
-sizeof(struct rte_pktmbuf_pool_private) bytes.
-The number of allocated pkt mbufs is NB_MBUF, with a size of MBUF_SIZE each.
-A per-lcore cache of 32 mbufs is kept.
+In this case, it is necessary to create a pool that will be used by the driver.
+The number of allocated pkt mbufs is NB_MBUF, with a data room size of
+RTE_MBUF_DEFAULT_BUF_SIZE each.
+A per-lcore cache of MEMPOOL_CACHE_SIZE mbufs is kept.
The memory is allocated in rte_socket_id() socket,
but it is possible to extend this code to allocate one mbuf pool per socket.
-Two callback pointers are also given to the rte_mempool_create() function:
-
-* The first callback pointer is to rte_pktmbuf_pool_init() and is used
- to initialize the private data of the mempool, which is needed by the driver.
- This function is provided by the mbuf API, but can be copied and extended by the developer.
-
-* The second callback pointer given to rte_mempool_create() is the mbuf initializer.
- The default is used, that is, rte_pktmbuf_init(), which is provided in the rte_mbuf library.
- If a more complex application wants to extend the rte_pktmbuf structure for its own needs,
- a new function derived from rte_pktmbuf_init( ) can be created.
+The rte_pktmbuf_pool_create() function uses the default mbuf pool and mbuf
+initializers, respectively rte_pktmbuf_pool_init() and rte_pktmbuf_init().
+An advanced application may want to use the mempool API to create the
+mbuf pool with more control.
Driver Initialization
~~~~~~~~~~~~~~~~~~~~~
if (nb_ports == 0)
rte_exit(EXIT_FAILURE, "No Ethernet ports - bye\n");
- if (nb_ports > RTE_MAX_ETHPORTS)
- nb_ports = RTE_MAX_ETHPORTS;
-
/* reset l2fwd_dst_ports */
for (portid = 0; portid < RTE_MAX_ETHPORTS; portid++)
Values of struct lcore_queue_conf:
* n_rx_port and rx_port_list[] are used in the main packet processing loop
- (see Section 9.4.6 "Receive, Process and Transmit Packets" later in this chapter).
+ (see Section `Receive, Process and Transmit Packets`_ later in this chapter).
* rx_timers and flush_timer are used to ensure forced TX on low packet rate.
rte_pause();
}
-First inifnite for loop is to minimize impact of stats reading. Lock is only locked/unlocked when asked.
+First infinite for loop is to minimize impact of stats reading. Lock is only locked/unlocked when asked.
Second inner while loop do the whole jobs management. When any job is ready, the use rte_timer_manage() is used to call the job handler.
In this place functions l2fwd_fwd_job() and l2fwd_flush_job() are called when needed.
Then rte_jobstats_context_finish() is called to mark loop end - no other jobs are ready to execute. By this time stats are ready to be read
and if stats_read_pending is set, loop breaks allowing stats to be read.
-Third do-while loop is the idle job (idle stats counter). Its only purpose is moniting if any job is ready or stats job read is pending
-for this lcore. Statistics from this part of code is considered as the headroom available fo additional processing.
+Third do-while loop is the idle job (idle stats counter). Its only purpose is monitoring if any job is ready or stats job read is pending
+for this lcore. Statistics from this part of code is considered as the headroom available for additional processing.
Receive, Process and Transmit Packets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
After first read second try is issued.
-.. code::
+.. code-block:: c
if (total_nb_rx == MAX_PKT_BURST) {
const uint16_t nb_rx = rte_eth_rx_burst((uint8_t) portid, 0, pkts_burst,
This second read is important to give job stats library a feedback how many packets was processed.
-.. code::
+.. code-block:: c
/* Adjust period time in which we are running here. */
if (rte_jobstats_finish(job, total_nb_rx) != 0) {
/* Send the packet on an output interface */
static int
- l2fwd_send_packet(struct rte_mbuf *m, uint8_t port)
+ l2fwd_send_packet(struct rte_mbuf *m, uint16_t port)
{
unsigned lcore_id, len;
struct lcore_queue_conf *qconf;
}
To ensure that no packets remain in the tables, the flush job exists. The l2fwd_flush_job()
-is called periodicaly to for each lcore draining TX queue of each port.
+is called periodically to for each lcore draining TX queue of each port.
This technique introduces some latency when there are not many packets to send,
however it improves performance:
unsigned lcore_id;
struct lcore_queue_conf *qconf;
struct mbuf_table *m_table;
- uint8_t portid;
+ uint16_t portid;
lcore_id = rte_lcore_id();
qconf = &lcore_queue_conf[lcore_id];
* in which it was called. */
rte_jobstats_finish(&qconf->flush_job, qconf->flush_job.target);
}
-
-.. |l2_fwd_benchmark_setup| image:: img/l2_fwd_benchmark_setup.*
-
-.. |l2_fwd_virtenv_benchmark_setup| image:: img/l2_fwd_virtenv_benchmark_setup.*