xref: /dpdk/doc/guides/sample_app_ug/hello_world.rst (revision 8809f78c7dd9f33a44a4f89c58fc91ded34296ed) 
1o..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2010-2014 Intel Corporation.
3
4Hello World Sample Application
5==============================
6
7The Hello World sample application is an example of the simplest DPDK application that can be written.
8The application simply prints an "helloworld" message on every enabled lcore.
9
10Compiling the Application
11-------------------------
12
13To compile the sample application see :doc:`compiling`.
14
15The application is located in the ``helloworld`` sub-directory.
16
17Running the Application
18-----------------------
19
20To run the example in a linux environment:
21
22.. code-block:: console
23
24    $ ./<build_dir>/examples/dpdk-helloworld -l 0-3 -n 4
25
26Refer to *DPDK Getting Started Guide* for general information on running applications
27and the Environment Abstraction Layer (EAL) options.
28
29Explanation
30-----------
31
32The following sections provide some explanation of code.
33
34EAL Initialization
35~~~~~~~~~~~~~~~~~~
36
37The first task is to initialize the Environment Abstraction Layer (EAL).
38This 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
51This call finishes the initialization process that was started before main() is called (in case of a Linux environment).
52The argc and argv arguments are provided to the rte_eal_init() function.
53The value returned is the number of parsed arguments.
54
55Starting Application Unit Lcores
56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57
58Once the EAL is initialized, the application is ready to launch a function on an lcore.
59In this example, lcore_hello() is called on every available lcore.
60The 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
74The code that launches the function on each lcore is as follows:
75
76.. code-block:: c
77
78    /* call lcore_hello() on every worker lcore */
79
80    RTE_LCORE_FOREACH_WORKER(lcore_id) {
81       rte_eal_remote_launch(lcore_hello, NULL, lcore_id);
82    }
83
84    /* call it on main lcore too */
85
86    lcore_hello(NULL);
87
88The following code is equivalent and simpler:
89
90.. code-block:: c
91
92    rte_eal_mp_remote_launch(lcore_hello, NULL, CALL_MAIN);
93
94Refer to the *DPDK API Reference* for detailed information on the rte_eal_mp_remote_launch() function.
95