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_dir>/examples/dpdk-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 .. literalinclude:: ../../../examples/helloworld/main.c
  41     :language: c
  42     :start-after: Initialization of Environment Abstraction Layer (EAL). 8<
  43     :end-before: >8 End of initialization of Environment Abstraction Layer
  44
  45 This call finishes the initialization process that was started before main() is called (in case of a Linux environment).
  46 The argc and argv arguments are provided to the rte_eal_init() function.
  47 The value returned is the number of parsed arguments.
  48
  49 Starting Application Unit Lcores
  50 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  51
  52 Once the EAL is initialized, the application is ready to launch a function on an lcore.
  53 In this example, lcore_hello() is called on every available lcore.
  54 The following is the definition of the function:
  55
  56 .. literalinclude:: ../../../examples/helloworld/main.c
  57     :language: c
  58     :start-after: Launch a function on lcore. 8<
  59     :end-before: >8 End of launching function on lcore.
  60
  61 The code that launches the function on each lcore is as follows:
  62
  63 .. literalinclude:: ../../../examples/helloworld/main.c
  64     :language: c
  65     :start-after: Launches the function on each lcore. 8<
  66     :end-before: >8 End of launching the function on each lcore.
  67     :dedent: 1
  68
  69 The following code is equivalent and simpler:
  70
  71 .. literalinclude:: ../../../examples/helloworld/main.c
  72     :language: c
  73     :start-after: Simpler equivalent. 8<
  74     :end-before: >8 End of simpler equivalent.
  75     :dedent: 2
  76
  77 Refer to the *DPDK API Reference* for detailed information on the rte_eal_mp_remote_launch() function.