1.. BSD LICENSE 2 Copyright(c) 2010-2014 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 31Hello World Sample Application 32============================== 33 34The Hello World sample application is an example of the simplest Intel® DPDK application that can be written. 35The application simply prints an "helloworld" message on every enabled lcore. 36 37Compiling the Application 38------------------------- 39 40#. Go to the example directory: 41 42 .. code-block:: console 43 44 export RTE_SDK=/path/to/rte_sdk 45 cd ${RTE_SDK}/examples/helloworld 46 47#. Set the target (a default target is used if not specified). For example: 48 49 .. code-block:: console 50 51 export RTE_TARGET=x86_64-native-linuxapp-gcc 52 53 See the *Intel® DPDK Getting Started* Guide for possible RTE_TARGET values. 54 55#. Build the application: 56 57 .. code-block:: console 58 59 make 60 61Running the Application 62----------------------- 63 64To run the example in a linuxapp environment: 65 66.. code-block:: console 67 68 $ ./build/helloworld -c f -n 4 69 70Refer to *Intel® DPDK Getting Started Guide* for general information on running applications 71and the Environment Abstraction Layer (EAL) options. 72 73Explanation 74----------- 75 76The following sections provide some explanation of code. 77 78EAL Initialization 79~~~~~~~~~~~~~~~~~~ 80 81The first task is to initialize the Environment Abstraction Layer (EAL). 82This is done in the main() function using the following code: 83 84.. code-block:: c 85 86 int 87 88 MAIN(int argc, char **argv) 89 90 { 91 ret = rte_eal_init(argc, argv); 92 if (ret < 0) 93 rte_panic("Cannot init EAL\n"); 94 95This call finishes the initialization process that was started before main() is called (in case of a Linuxapp environment). 96The argc and argv arguments are provided to the rte_eal_init() function. 97The value returned is the number of parsed arguments. 98 99Starting Application Unit Lcores 100~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 101 102Once the EAL is initialized, the application is ready to launch a function on an lcore. 103In this example, lcore_hello() is called on every available lcore. 104The following is the definition of the function: 105 106.. code-block:: c 107 108 static int 109 lcore_hello( attribute ((unused)) void *arg) 110 { 111 unsigned lcore_id; 112 113 lcore_id = rte_lcore_id(); 114 printf("hello from core %u\n", lcore_id); 115 return 0; 116 } 117 118The code that launches the function on each lcore is as follows: 119 120.. code-block:: c 121 122 /* call lcore_hello() on every slave lcore */ 123 124 RTE_LCORE_FOREACH_SLAVE(lcore_id) { 125 rte_eal_remote_launch(lcore_hello, NULL, lcore_id); 126 } 127 128 /* call it on master lcore too */ 129 130 lcore_hello(NULL); 131 132The following code is equivalent and simpler: 133 134.. code-block:: c 135 136 rte_eal_mp_remote_launch(lcore_hello, NULL, CALL_MASTER); 137 138Refer to the *Intel® DPDK API Reference* for detailed information on the rte_eal_mp_remote_launch() function. 139