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 31Command Line Sample Application 32=============================== 33 34This chapter describes the Command Line sample application that 35is part of the Intel® Data Plane Development Kit (Intel® DPDK). 36 37Overview 38-------- 39 40The Command Line sample application is a simple application that 41demonstrates the use of the command line interface in the Intel® DPDK. 42This application is a readline-like interface that can be used 43to debug an Intel® DPDK application, in a Linux* application environment. 44 45.. note:: 46 47 The rte_cmdline library should not be used in production code since 48 it is not validated to the same standard as other Intel® DPDK libraries. 49 See also the "rte_cmdline library should not be used in production code due to limited testing" item 50 in the "Known Issues" section of the Release Notes. 51 52The Command Line sample application supports some of the features of the GNU readline library such as, completion, 53cut/paste and some other special bindings that make configuration and debug faster and easier. 54 55The application shows how the rte_cmdline application can be extended to handle a list of objects. 56There are three simple commands: 57 58* add obj_name IP: Add a new object with an IP/IPv6 address associated to it. 59 60* del obj_name: Delete the specified object. 61 62* show obj_name: Show the IP associated with the specified object. 63 64.. note:: 65 66 To terminate the application, use **Ctrl-d**. 67 68Compiling the Application 69------------------------- 70 71#. Go to example directory: 72 73 .. code-block:: console 74 75 export RTE_SDK=/path/to/rte_sdk 76 cd ${RTE_SDK}/examples/cmdline 77 78#. Set the target (a default target is used if not specified). For example: 79 80 .. code-block:: console 81 82 export RTE_TARGET=x86_64-native-linuxapp-gcc 83 84 Refer to the *Intel® DPDK Getting Started Guide* for possible RTE_TARGET values. 85 86#. Build the application: 87 88 .. code-block:: console 89 90 make 91 92Running the Application 93----------------------- 94 95To run the application in linuxapp environment, issue the following command: 96 97.. code-block:: console 98 99 $ ./build/cmdline -c f -n 4 100 101Refer to the *Intel® DPDK Getting Started Guide* for general information on running applications 102and the Environment Abstraction Layer (EAL) options. 103 104Explanation 105----------- 106 107The following sections provide some explanation of the code. 108 109EAL Initialization and cmdline Start 110~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 111 112The first task is the initialization of the Environment Abstraction Layer (EAL). 113This is achieved as follows: 114 115.. code-block:: c 116 117 int MAIN(int argc, char **argv) 118 { 119 ret = rte_eal_init(argc, argv); 120 if (ret < 0) 121 rte_panic("Cannot init EAL\n"); 122 123Then, a new command line object is created and started to interact with the user through the console: 124 125.. code-block:: c 126 127 cl = cmdline_stdin_new(main_ctx, "example> "); 128 cmdline_interact(cl); 129 cmdline_stdin_exit(cl); 130 131The cmd line_interact() function returns when the user types **Ctrl-d** and in this case, 132the application exits. 133 134Defining a cmdline Context 135~~~~~~~~~~~~~~~~~~~~~~~~~~ 136 137A cmdline context is a list of commands that are listed in a NULL-terminated table, for example: 138 139.. code-block:: c 140 141 cmdline_parse_ctx_t main_ctx[] = { 142 (cmdline_parse_inst_t *) &cmd_obj_del_show, 143 (cmdline_parse_inst_t *) &cmd_obj_add, 144 (cmdline_parse_inst_t *) &cmd_help, 145 NULL, 146 }; 147 148Each command (of type cmdline_parse_inst_t) is defined statically. 149It contains a pointer to a callback function that is executed when the command is parsed, 150an opaque pointer, a help string and a list of tokens in a NULL-terminated table. 151 152The rte_cmdline application provides a list of pre-defined token types: 153 154* String Token: Match a static string, a list of static strings or any string. 155 156* Number Token: Match a number that can be signed or unsigned, from 8-bit to 32-bit. 157 158* IP Address Token: Match an IPv4 or IPv6 address or network. 159 160* Ethernet* Address Token: Match a MAC address. 161 162In this example, a new token type obj_list is defined and implemented 163in the parse_obj_list.c and parse_obj_list.h files. 164 165For example, the cmd_obj_del_show command is defined as shown below: 166 167.. code-block:: c 168 169 struct cmd_obj_add_result { 170 cmdline_fixed_string_t action; 171 cmdline_fixed_string_t name; 172 struct object *obj; 173 }; 174 175 static void cmd_obj_del_show_parsed(void *parsed_result, struct cmdline *cl, attribute ((unused)) void *data) 176 { 177 /* ... */ 178 } 179 180 cmdline_parse_token_string_t cmd_obj_action = TOKEN_STRING_INITIALIZER(struct cmd_obj_del_show_result, action, "show#del"); 181 182 parse_token_obj_list_t cmd_obj_obj = TOKEN_OBJ_LIST_INITIALIZER(struct cmd_obj_del_show_result, obj, &global_obj_list); 183 184 cmdline_parse_inst_t cmd_obj_del_show = { 185 .f = cmd_obj_del_show_parsed, /* function to call */ 186 .data = NULL, /* 2nd arg of func */ 187 .help_str = "Show/del an object", 188 .tokens = { /* token list, NULL terminated */ 189 (void *)&cmd_obj_action, 190 (void *)&cmd_obj_obj, 191 NULL, 192 }, 193 }; 194 195This command is composed of two tokens: 196 197* The first token is a string token that can be show or del. 198 199* The second token is an object that was previously added using the add command in the global_obj_list variable. 200 201Once the command is parsed, the rte_cmdline application fills a cmd_obj_del_show_result structure. 202A pointer to this structure is given as an argument to the callback function and can be used in the body of this function. 203