1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2010-2014 Intel Corporation. 3 4Command Line Sample Application 5=============================== 6 7This chapter describes the Command Line sample application that 8is part of the Data Plane Development Kit (DPDK). 9 10Overview 11-------- 12 13The Command Line sample application is a simple application that 14demonstrates the use of the command line interface in the DPDK. 15This application is a readline-like interface that can be used 16to debug a DPDK application, in a Linux* application environment. 17 18.. note:: 19 20 The rte_cmdline library should not be used in production code since 21 it is not validated to the same standard as other DPDK libraries. 22 See also the "rte_cmdline library should not be used in production code due to limited testing" item 23 in the "Known Issues" section of the Release Notes. 24 25The Command Line sample application supports some of the features of the GNU readline library such as, completion, 26cut/paste and some other special bindings that make configuration and debug faster and easier. 27 28The application shows how the rte_cmdline application can be extended to handle a list of objects. 29There are three simple commands: 30 31* add obj_name IP: Add a new object with an IP/IPv6 address associated to it. 32 33* del obj_name: Delete the specified object. 34 35* show obj_name: Show the IP associated with the specified object. 36 37.. note:: 38 39 To terminate the application, use **Ctrl-d**. 40 41Compiling the Application 42------------------------- 43 44To compile the sample application see :doc:`compiling` 45 46The application is located in the ``cmd_line`` sub-directory. 47 48Running the Application 49----------------------- 50 51To run the application in linux environment, issue the following command: 52 53.. code-block:: console 54 55 $ ./<build_dir>/examples/dpdk-cmdline -l 0-3 -n 4 56 57Refer to the *DPDK Getting Started Guide* for general information on running applications 58and the Environment Abstraction Layer (EAL) options. 59 60Explanation 61----------- 62 63The following sections provide some explanation of the code. 64 65EAL Initialization and cmdline Start 66~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 67 68The first task is the initialization of the Environment Abstraction Layer (EAL). 69This is achieved as follows: 70 71.. code-block:: c 72 73 int main(int argc, char **argv) 74 { 75 ret = rte_eal_init(argc, argv); 76 if (ret < 0) 77 rte_panic("Cannot init EAL\n"); 78 79Then, a new command line object is created and started to interact with the user through the console: 80 81.. code-block:: c 82 83 cl = cmdline_stdin_new(main_ctx, "example> "); 84 cmdline_interact(cl); 85 cmdline_stdin_exit(cl); 86 87The cmd line_interact() function returns when the user types **Ctrl-d** and in this case, 88the application exits. 89 90Defining a cmdline Context 91~~~~~~~~~~~~~~~~~~~~~~~~~~ 92 93A cmdline context is a list of commands that are listed in a NULL-terminated table, for example: 94 95.. code-block:: c 96 97 cmdline_parse_ctx_t main_ctx[] = { 98 (cmdline_parse_inst_t *) &cmd_obj_del_show, 99 (cmdline_parse_inst_t *) &cmd_obj_add, 100 (cmdline_parse_inst_t *) &cmd_help, 101 NULL, 102 }; 103 104Each command (of type cmdline_parse_inst_t) is defined statically. 105It contains a pointer to a callback function that is executed when the command is parsed, 106an opaque pointer, a help string and a list of tokens in a NULL-terminated table. 107 108The rte_cmdline application provides a list of pre-defined token types: 109 110* String Token: Match a static string, a list of static strings or any string. 111 112* Number Token: Match a number that can be signed or unsigned, from 8-bit to 32-bit. 113 114* IP Address Token: Match an IPv4 or IPv6 address or network. 115 116* Ethernet* Address Token: Match a MAC address. 117 118In this example, a new token type obj_list is defined and implemented 119in the parse_obj_list.c and parse_obj_list.h files. 120 121For example, the cmd_obj_del_show command is defined as shown below: 122 123.. code-block:: c 124 125 struct cmd_obj_add_result { 126 cmdline_fixed_string_t action; 127 cmdline_fixed_string_t name; 128 struct object *obj; 129 }; 130 131 static void cmd_obj_del_show_parsed(void *parsed_result, struct cmdline *cl, __rte_unused void *data) 132 { 133 /* ... */ 134 } 135 136 cmdline_parse_token_string_t cmd_obj_action = TOKEN_STRING_INITIALIZER(struct cmd_obj_del_show_result, action, "show#del"); 137 138 parse_token_obj_list_t cmd_obj_obj = TOKEN_OBJ_LIST_INITIALIZER(struct cmd_obj_del_show_result, obj, &global_obj_list); 139 140 cmdline_parse_inst_t cmd_obj_del_show = { 141 .f = cmd_obj_del_show_parsed, /* function to call */ 142 .data = NULL, /* 2nd arg of func */ 143 .help_str = "Show/del an object", 144 .tokens = { /* token list, NULL terminated */ 145 (void *)&cmd_obj_action, 146 (void *)&cmd_obj_obj, 147 NULL, 148 }, 149 }; 150 151This command is composed of two tokens: 152 153* The first token is a string token that can be show or del. 154 155* The second token is an object that was previously added using the add command in the global_obj_list variable. 156 157Once the command is parsed, the rte_cmdline application fills a cmd_obj_del_show_result structure. 158A pointer to this structure is given as an argument to the callback function and can be used in the body of this function. 159