2 Copyright(c) 2015 Intel Corporation. All rights reserved.
5 Redistribution and use in source and binary forms, with or without
6 modification, are permitted provided that the following conditions
9 * Redistributions of source code must retain the above copyright
10 notice, this list of conditions and the following disclaimer.
11 * Redistributions in binary form must reproduce the above copyright
12 notice, this list of conditions and the following disclaimer in
13 the documentation and/or other materials provided with the
15 * Neither the name of Intel Corporation nor the names of its
16 contributors may be used to endorse or promote products derived
17 from this software without specific prior written permission.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 Basic Forwarding Sample Application
33 ===================================
35 The Basic Forwarding sample application is a simple *skeleton* example of a
36 forwarding application.
38 It is intended as a demonstration of the basic components of a DPDK forwarding
39 application. For more detailed implementations see the L2 and L3 forwarding
42 Compiling the Application
43 -------------------------
45 To compile the sample application see :doc:`compiling`.
47 The application is located in the ``skeleton`` sub-directory.
49 Running the Application
50 -----------------------
52 To run the example in a ``linuxapp`` environment:
54 .. code-block:: console
56 ./build/basicfwd -l 1 -n 4
58 Refer to *DPDK Getting Started Guide* for general information on running
59 applications and the Environment Abstraction Layer (EAL) options.
65 The following sections provide an explanation of the main components of the
68 All DPDK library functions used in the sample code are prefixed with ``rte_``
69 and are explained in detail in the *DPDK API Documentation*.
75 The ``main()`` function performs the initialization and calls the execution
76 threads for each lcore.
78 The first task is to initialize the Environment Abstraction Layer (EAL). The
79 ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
80 function. The value returned is the number of parsed arguments:
84 int ret = rte_eal_init(argc, argv);
86 rte_exit(EXIT_FAILURE, "Error with EAL initialization\n");
89 The ``main()`` also allocates a mempool to hold the mbufs (Message Buffers)
90 used by the application:
94 mbuf_pool = rte_mempool_create("MBUF_POOL",
98 sizeof(struct rte_pktmbuf_pool_private),
99 rte_pktmbuf_pool_init, NULL,
100 rte_pktmbuf_init, NULL,
104 Mbufs are the packet buffer structure used by DPDK. They are explained in
105 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
107 The ``main()`` function also initializes all the ports using the user defined
108 ``port_init()`` function which is explained in the next section:
112 for (portid = 0; portid < nb_ports; portid++) {
113 if (port_init(portid, mbuf_pool) != 0) {
114 rte_exit(EXIT_FAILURE,
115 "Cannot init port %" PRIu8 "\n", portid);
120 Once the initialization is complete, the application is ready to launch a
121 function on an lcore. In this example ``lcore_main()`` is called on a single
129 The ``lcore_main()`` function is explained below.
133 The Port Initialization Function
134 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136 The main functional part of the port initialization used in the Basic
137 Forwarding application is shown below:
142 port_init(uint16_t port, struct rte_mempool *mbuf_pool)
144 struct rte_eth_conf port_conf = port_conf_default;
145 const uint16_t rx_rings = 1, tx_rings = 1;
146 struct ether_addr addr;
150 if (port >= rte_eth_dev_count())
153 /* Configure the Ethernet device. */
154 retval = rte_eth_dev_configure(port, rx_rings, tx_rings, &port_conf);
158 /* Allocate and set up 1 RX queue per Ethernet port. */
159 for (q = 0; q < rx_rings; q++) {
160 retval = rte_eth_rx_queue_setup(port, q, RX_RING_SIZE,
161 rte_eth_dev_socket_id(port), NULL, mbuf_pool);
166 /* Allocate and set up 1 TX queue per Ethernet port. */
167 for (q = 0; q < tx_rings; q++) {
168 retval = rte_eth_tx_queue_setup(port, q, TX_RING_SIZE,
169 rte_eth_dev_socket_id(port), NULL);
174 /* Start the Ethernet port. */
175 retval = rte_eth_dev_start(port);
179 /* Enable RX in promiscuous mode for the Ethernet device. */
180 rte_eth_promiscuous_enable(port);
185 The Ethernet ports are configured with default settings using the
186 ``rte_eth_dev_configure()`` function and the ``port_conf_default`` struct:
190 static const struct rte_eth_conf port_conf_default = {
191 .rxmode = { .max_rx_pkt_len = ETHER_MAX_LEN }
194 For this example the ports are set up with 1 RX and 1 TX queue using the
195 ``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
197 The Ethernet port is then started:
201 retval = rte_eth_dev_start(port);
204 Finally the RX port is set in promiscuous mode:
208 rte_eth_promiscuous_enable(port);
214 As we saw above the ``main()`` function calls an application function on the
215 available lcores. For the Basic Forwarding application the lcore function
216 looks like the following:
220 static __attribute__((noreturn)) void
223 const uint16_t nb_ports = rte_eth_dev_count();
227 * Check that the port is on the same NUMA node as the polling thread
228 * for best performance.
230 for (port = 0; port < nb_ports; port++)
231 if (rte_eth_dev_socket_id(port) > 0 &&
232 rte_eth_dev_socket_id(port) !=
233 (int)rte_socket_id())
234 printf("WARNING, port %u is on remote NUMA node to "
235 "polling thread.\n\tPerformance will "
236 "not be optimal.\n", port);
238 printf("\nCore %u forwarding packets. [Ctrl+C to quit]\n",
241 /* Run until the application is quit or killed. */
244 * Receive packets on a port and forward them on the paired
245 * port. The mapping is 0 -> 1, 1 -> 0, 2 -> 3, 3 -> 2, etc.
247 for (port = 0; port < nb_ports; port++) {
249 /* Get burst of RX packets, from first port of pair. */
250 struct rte_mbuf *bufs[BURST_SIZE];
251 const uint16_t nb_rx = rte_eth_rx_burst(port, 0,
254 if (unlikely(nb_rx == 0))
257 /* Send burst of TX packets, to second port of pair. */
258 const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0,
261 /* Free any unsent packets. */
262 if (unlikely(nb_tx < nb_rx)) {
264 for (buf = nb_tx; buf < nb_rx; buf++)
265 rte_pktmbuf_free(bufs[buf]);
272 The main work of the application is done within the loop:
277 for (port = 0; port < nb_ports; port++) {
279 /* Get burst of RX packets, from first port of pair. */
280 struct rte_mbuf *bufs[BURST_SIZE];
281 const uint16_t nb_rx = rte_eth_rx_burst(port, 0,
284 if (unlikely(nb_rx == 0))
287 /* Send burst of TX packets, to second port of pair. */
288 const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0,
291 /* Free any unsent packets. */
292 if (unlikely(nb_tx < nb_rx)) {
294 for (buf = nb_tx; buf < nb_rx; buf++)
295 rte_pktmbuf_free(bufs[buf]);
300 Packets are received in bursts on the RX ports and transmitted in bursts on
301 the TX ports. The ports are grouped in pairs with a simple mapping scheme
302 using the an XOR on the port number::
312 The ``rte_eth_tx_burst()`` function frees the memory buffers of packets that
313 are transmitted. If packets fail to transmit, ``(nb_tx < nb_rx)``, then they
314 must be freed explicitly using ``rte_pktmbuf_free()``.
316 The forwarding loop can be interrupted and the application closed using