doc: add cryptodev sample code
[dpdk.git] / doc / guides / sample_app_ug / skeleton.rst
1 ..  BSD LICENSE
2     Copyright(c) 2015 Intel Corporation. All rights reserved.
3     All rights reserved.
4
5     Redistribution and use in source and binary forms, with or without
6     modification, are permitted provided that the following conditions
7     are met:
8
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
14     distribution.
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.
18
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.
30
31
32 Basic Forwarding Sample Application
33 ===================================
34
35 The Basic Forwarding sample application is a simple *skeleton* example of a
36 forwarding application.
37
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
40 sample applications.
41
42
43 Compiling the Application
44 -------------------------
45
46 To compile the application export the path to the DPDK source tree and go to
47 the example directory:
48
49 .. code-block:: console
50
51     export RTE_SDK=/path/to/rte_sdk
52
53     cd ${RTE_SDK}/examples/skeleton
54
55 Set the target, for example:
56
57 .. code-block:: console
58
59     export RTE_TARGET=x86_64-native-linuxapp-gcc
60
61 See the *DPDK Getting Started* Guide for possible ``RTE_TARGET`` values.
62
63 Build the application as follows:
64
65 .. code-block:: console
66
67     make
68
69
70 Running the Application
71 -----------------------
72
73 To run the example in a ``linuxapp`` environment:
74
75 .. code-block:: console
76
77     ./build/basicfwd -l 1 -n 4
78
79 Refer to *DPDK Getting Started Guide* for general information on running
80 applications and the Environment Abstraction Layer (EAL) options.
81
82
83 Explanation
84 -----------
85
86 The following sections provide an explanation of the main components of the
87 code.
88
89 All DPDK library functions used in the sample code are prefixed with ``rte_``
90 and are explained in detail in the *DPDK API Documentation*.
91
92
93 The Main Function
94 ~~~~~~~~~~~~~~~~~
95
96 The ``main()`` function performs the initialization and calls the execution
97 threads for each lcore.
98
99 The first task is to initialize the Environment Abstraction Layer (EAL).  The
100 ``argc`` and ``argv`` arguments are provided to the ``rte_eal_init()``
101 function. The value returned is the number of parsed arguments:
102
103 .. code-block:: c
104
105     int ret = rte_eal_init(argc, argv);
106     if (ret < 0)
107         rte_exit(EXIT_FAILURE, "Error with EAL initialization\n");
108
109
110 The ``main()`` also allocates a mempool to hold the mbufs (Message Buffers)
111 used by the application:
112
113 .. code-block:: c
114
115     mbuf_pool = rte_mempool_create("MBUF_POOL",
116                                    NUM_MBUFS * nb_ports,
117                                    MBUF_SIZE,
118                                    MBUF_CACHE_SIZE,
119                                    sizeof(struct rte_pktmbuf_pool_private),
120                                    rte_pktmbuf_pool_init, NULL,
121                                    rte_pktmbuf_init,      NULL,
122                                    rte_socket_id(),
123                                    0);
124
125 Mbufs are the packet buffer structure used by DPDK. They are explained in
126 detail in the "Mbuf Library" section of the *DPDK Programmer's Guide*.
127
128 The ``main()`` function also initializes all the ports using the user defined
129 ``port_init()`` function which is explained in the next section:
130
131 .. code-block:: c
132
133     for (portid = 0; portid < nb_ports; portid++) {
134         if (port_init(portid, mbuf_pool) != 0) {
135             rte_exit(EXIT_FAILURE,
136                      "Cannot init port %" PRIu8 "\n", portid);
137         }
138     }
139
140
141 Once the initialization is complete, the application is ready to launch a
142 function on an lcore. In this example ``lcore_main()`` is called on a single
143 lcore.
144
145
146 .. code-block:: c
147
148         lcore_main();
149
150 The ``lcore_main()`` function is explained below.
151
152
153
154 The Port Initialization  Function
155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
156
157 The main functional part of the port initialization used in the Basic
158 Forwarding application is shown below:
159
160 .. code-block:: c
161
162     static inline int
163     port_init(uint8_t port, struct rte_mempool *mbuf_pool)
164     {
165         struct rte_eth_conf port_conf = port_conf_default;
166         const uint16_t rx_rings = 1, tx_rings = 1;
167         struct ether_addr addr;
168         int retval;
169         uint16_t q;
170
171         if (port >= rte_eth_dev_count())
172             return -1;
173
174         /* Configure the Ethernet device. */
175         retval = rte_eth_dev_configure(port, rx_rings, tx_rings, &port_conf);
176         if (retval != 0)
177             return retval;
178
179         /* Allocate and set up 1 RX queue per Ethernet port. */
180         for (q = 0; q < rx_rings; q++) {
181             retval = rte_eth_rx_queue_setup(port, q, RX_RING_SIZE,
182                     rte_eth_dev_socket_id(port), NULL, mbuf_pool);
183             if (retval < 0)
184                 return retval;
185         }
186
187         /* Allocate and set up 1 TX queue per Ethernet port. */
188         for (q = 0; q < tx_rings; q++) {
189             retval = rte_eth_tx_queue_setup(port, q, TX_RING_SIZE,
190                     rte_eth_dev_socket_id(port), NULL);
191             if (retval < 0)
192                 return retval;
193         }
194
195         /* Start the Ethernet port. */
196         retval = rte_eth_dev_start(port);
197         if (retval < 0)
198             return retval;
199
200         /* Enable RX in promiscuous mode for the Ethernet device. */
201         rte_eth_promiscuous_enable(port);
202
203         return 0;
204     }
205
206 The Ethernet ports are configured with default settings using the
207 ``rte_eth_dev_configure()`` function and the ``port_conf_default`` struct:
208
209 .. code-block:: c
210
211     static const struct rte_eth_conf port_conf_default = {
212         .rxmode = { .max_rx_pkt_len = ETHER_MAX_LEN }
213     };
214
215 For this example the ports are set up with 1 RX and 1 TX queue using the
216 ``rte_eth_rx_queue_setup()`` and ``rte_eth_tx_queue_setup()`` functions.
217
218 The Ethernet port is then started:
219
220 .. code-block:: c
221
222         retval  = rte_eth_dev_start(port);
223
224
225 Finally the RX port is set in promiscuous mode:
226
227 .. code-block:: c
228
229         rte_eth_promiscuous_enable(port);
230
231
232 The Lcores Main
233 ~~~~~~~~~~~~~~~
234
235 As we saw above the ``main()`` function calls an application function on the
236 available lcores. For the Basic Forwarding application the lcore function
237 looks like the following:
238
239 .. code-block:: c
240
241     static __attribute__((noreturn)) void
242     lcore_main(void)
243     {
244         const uint8_t nb_ports = rte_eth_dev_count();
245         uint8_t port;
246
247         /*
248          * Check that the port is on the same NUMA node as the polling thread
249          * for best performance.
250          */
251         for (port = 0; port < nb_ports; port++)
252             if (rte_eth_dev_socket_id(port) > 0 &&
253                     rte_eth_dev_socket_id(port) !=
254                             (int)rte_socket_id())
255                 printf("WARNING, port %u is on remote NUMA node to "
256                         "polling thread.\n\tPerformance will "
257                         "not be optimal.\n", port);
258
259         printf("\nCore %u forwarding packets. [Ctrl+C to quit]\n",
260                 rte_lcore_id());
261
262         /* Run until the application is quit or killed. */
263         for (;;) {
264             /*
265              * Receive packets on a port and forward them on the paired
266              * port. The mapping is 0 -> 1, 1 -> 0, 2 -> 3, 3 -> 2, etc.
267              */
268             for (port = 0; port < nb_ports; port++) {
269
270                 /* Get burst of RX packets, from first port of pair. */
271                 struct rte_mbuf *bufs[BURST_SIZE];
272                 const uint16_t nb_rx = rte_eth_rx_burst(port, 0,
273                         bufs, BURST_SIZE);
274
275                 if (unlikely(nb_rx == 0))
276                     continue;
277
278                 /* Send burst of TX packets, to second port of pair. */
279                 const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0,
280                         bufs, nb_rx);
281
282                 /* Free any unsent packets. */
283                 if (unlikely(nb_tx < nb_rx)) {
284                     uint16_t buf;
285                     for (buf = nb_tx; buf < nb_rx; buf++)
286                         rte_pktmbuf_free(bufs[buf]);
287                 }
288             }
289         }
290     }
291
292
293 The main work of the application is done within the loop:
294
295 .. code-block:: c
296
297         for (;;) {
298             for (port = 0; port < nb_ports; port++) {
299
300                 /* Get burst of RX packets, from first port of pair. */
301                 struct rte_mbuf *bufs[BURST_SIZE];
302                 const uint16_t nb_rx = rte_eth_rx_burst(port, 0,
303                         bufs, BURST_SIZE);
304
305                 if (unlikely(nb_rx == 0))
306                     continue;
307
308                 /* Send burst of TX packets, to second port of pair. */
309                 const uint16_t nb_tx = rte_eth_tx_burst(port ^ 1, 0,
310                         bufs, nb_rx);
311
312                 /* Free any unsent packets. */
313                 if (unlikely(nb_tx < nb_rx)) {
314                     uint16_t buf;
315                     for (buf = nb_tx; buf < nb_rx; buf++)
316                         rte_pktmbuf_free(bufs[buf]);
317                 }
318             }
319         }
320
321 Packets are received in bursts on the RX ports and transmitted in bursts on
322 the TX ports. The ports are grouped in pairs with a simple mapping scheme
323 using the an XOR on the port number::
324
325     0 -> 1
326     1 -> 0
327
328     2 -> 3
329     3 -> 2
330
331     etc.
332
333 The ``rte_eth_tx_burst()`` function frees the memory buffers of packets that
334 are transmitted. If packets fail to transmit, ``(nb_tx < nb_rx)``, then they
335 must be freed explicitly using ``rte_pktmbuf_free()``.
336
337 The forwarding loop can be interrupted and the application closed using
338 ``Ctrl-C``.