app/testpmd: fix statistics after reset
[dpdk.git] / doc / guides / sample_app_ug / hello_world.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2010-2014 Intel Corporation.
3
4 Hello World Sample Application
5 ==============================
6
7 The Hello World sample application is an example of the simplest DPDK application that can be written.
8 The application simply prints an "helloworld" message on every enabled lcore.
9
10 Compiling the Application
11 -------------------------
12
13 To compile the sample application see :doc:`compiling`.
14
15 The application is located in the ``helloworld`` sub-directory.
16
17 Running the Application
18 -----------------------
19
20 To run the example in a linux environment:
21
22 .. code-block:: console
23
24     $ ./build/helloworld -l 0-3 -n 4
25
26 Refer to *DPDK Getting Started Guide* for general information on running applications
27 and the Environment Abstraction Layer (EAL) options.
28
29 Explanation
30 -----------
31
32 The following sections provide some explanation of code.
33
34 EAL Initialization
35 ~~~~~~~~~~~~~~~~~~
36
37 The first task is to initialize the Environment Abstraction Layer (EAL).
38 This is done in the main() function using the following code:
39
40 .. code-block:: c
41
42     int
43
44     main(int argc, char **argv)
45
46     {
47         ret = rte_eal_init(argc, argv);
48         if (ret < 0)
49             rte_panic("Cannot init EAL\n");
50
51 This call finishes the initialization process that was started before main() is called (in case of a Linux environment).
52 The argc and argv arguments are provided to the rte_eal_init() function.
53 The value returned is the number of parsed arguments.
54
55 Starting Application Unit Lcores
56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57
58 Once the EAL is initialized, the application is ready to launch a function on an lcore.
59 In this example, lcore_hello() is called on every available lcore.
60 The following is the definition of the function:
61
62 .. code-block:: c
63
64     static int
65     lcore_hello(__rte_unused void *arg)
66     {
67         unsigned lcore_id;
68
69         lcore_id = rte_lcore_id();
70         printf("hello from core %u\n", lcore_id);
71         return 0;
72     }
73
74 The code that launches the function on each lcore is as follows:
75
76 .. code-block:: c
77
78     /* call lcore_hello() on every slave lcore */
79
80     RTE_LCORE_FOREACH_SLAVE(lcore_id) {
81        rte_eal_remote_launch(lcore_hello, NULL, lcore_id);
82     }
83
84     /* call it on master lcore too */
85
86     lcore_hello(NULL);
87
88 The following code is equivalent and simpler:
89
90 .. code-block:: c
91
92     rte_eal_mp_remote_launch(lcore_hello, NULL, CALL_MASTER);
93
94 Refer to the *DPDK API Reference* for detailed information on the rte_eal_mp_remote_launch() function.