1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2015 Intel Corporation.
4 Basic Forwarding Sample Application
5 ===================================
7 The Basic Forwarding sample application is a simple *skeleton* example of a
8 forwarding application.
10 It is intended as a demonstration of the basic components of a DPDK forwarding
11 application. For more detailed implementations see the L2 and L3 forwarding
14 Compiling the Application
15 -------------------------
17 To compile the sample application see :doc:`compiling`.
19 The application is located in the ``skeleton`` sub-directory.
21 Running the Application
22 -----------------------
24 To run the example in a ``linux`` environment:
26 .. code-block:: console
28 ./<build_dir>/examples/dpdk-skeleton -l 1 -n 4
30 Refer to *DPDK Getting Started Guide* for general information on running
31 applications and the Environment Abstraction Layer (EAL) options.
37 The following sections provide an explanation of the main components of the
40 All DPDK library functions used in the sample code are prefixed with ``rte_``
41 and are explained in detail in the *DPDK API Documentation*.
47 The ``main()`` function performs the initialization and calls the execution
48 threads for each lcore.
50 The first task is to initialize the Environment Abstraction Layer (EAL). The
51 ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
52 function. The value returned is the number of parsed arguments:
54 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
56 :start-after: Initializion the Environment Abstraction Layer (EAL). 8<
57 :end-before: >8 End of initializion the Environment Abstraction Layer (EAL).
61 The ``main()`` also allocates a mempool to hold the mbufs (Message Buffers)
62 used by the application:
64 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
66 :start-after: Allocates mempool to hold the mbufs. 8<
67 :end-before: >8 End of allocating mempool to hold mbuf.
70 Mbufs are the packet buffer structure used by DPDK. They are explained in
71 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
73 The ``main()`` function also initializes all the ports using the user defined
74 ``port_init()`` function which is explained in the next section:
76 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
78 :start-after: Initializing all ports. 8<
79 :end-before: >8 End of initializing all ports.
82 Once the initialization is complete, the application is ready to launch a
83 function on an lcore. In this example ``lcore_main()`` is called on a single
87 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
89 :start-after: Called on single lcore. 8<
90 :end-before: >8 End of called on single lcore.
93 The ``lcore_main()`` function is explained below.
97 The Port Initialization Function
98 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100 The main functional part of the port initialization used in the Basic
101 Forwarding application is shown below:
103 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
105 :start-after: Main functional part of port initialization. 8<
106 :end-before: >8 End of main functional part of port initialization.
108 The Ethernet ports are configured with default settings using the
109 ``rte_eth_dev_configure()`` function.
111 For this example the ports are set up with 1 RX and 1 TX queue using the
112 ``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
114 The Ethernet port is then started:
116 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
118 :start-after: Starting Ethernet port. 8<
119 :end-before: >8 End of starting of ethernet port.
123 Finally the RX port is set in promiscuous mode:
125 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
127 :start-after: Enable RX in promiscuous mode for the Ethernet device.
128 :end-before: End of setting RX port in promiscuous mode.
135 As we saw above the ``main()`` function calls an application function on the
136 available lcores. For the Basic Forwarding application the lcore function
137 looks like the following:
139 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
141 :start-after: Basic forwarding application lcore. 8<
142 :end-before: >8 End Basic forwarding application lcore.
144 The main work of the application is done within the loop:
146 .. literalinclude:: ../../../examples/skeleton/basicfwd.c
148 :start-after: Main work of application loop. 8<
149 :end-before: >8 End of loop.
152 Packets are received in bursts on the RX ports and transmitted in bursts on
153 the TX ports. The ports are grouped in pairs with a simple mapping scheme
154 using the an XOR on the port number::
164 The ``rte_eth_tx_burst()`` function frees the memory buffers of packets that
165 are transmitted. If packets fail to transmit, ``(nb_tx < nb_rx)``, then they
166 must be freed explicitly using ``rte_pktmbuf_free()``.
168 The forwarding loop can be interrupted and the application closed using