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.