doc/guides/sample_app_ug/cmd_line.rst

   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
  31 Command Line Sample Application
  32 ===============================
  33
  34 This chapter describes the Command Line sample application that
  35 is part of the Data Plane Development Kit (DPDK).
  36
  37 Overview
  38 --------
  39
  40 The Command Line sample application is a simple application that
  41 demonstrates the use of the command line interface in the DPDK.
  42 This application is a readline-like interface that can be used
  43 to debug a 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 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
  52 The Command Line sample application supports some of the features of the GNU readline library such as, completion,
  53 cut/paste and some other special bindings that make configuration and debug faster and easier.
  54
  55 The application shows how the rte_cmdline application can be extended to handle a list of objects.
  56 There 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
  68 Compiling 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 *DPDK Getting Started Guide* for possible RTE_TARGET values.
  85
  86 #.  Build the application:
  87
  88     .. code-block:: console
  89
  90         make
  91
  92 Running the Application
  93 -----------------------
  94
  95 To run the application in linuxapp environment, issue the following command:
  96
  97 .. code-block:: console
  98
  99     $ ./build/cmdline -l 0-3 -n 4
 100
 101 Refer to the *DPDK Getting Started Guide* for general information on running applications
 102 and the Environment Abstraction Layer (EAL) options.
 103
 104 Explanation
 105 -----------
 106
 107 The following sections provide some explanation of the code.
 108
 109 EAL Initialization and cmdline Start
 110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 111
 112 The first task is the initialization of the Environment Abstraction Layer (EAL).
 113 This 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
 123 Then, 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
 131 The cmd line_interact() function returns when the user types **Ctrl-d** and in this case,
 132 the application exits.
 133
 134 Defining a cmdline Context
 135 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 136
 137 A 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
 148 Each command (of type cmdline_parse_inst_t) is defined statically.
 149 It contains a pointer to a callback function that is executed when the command is parsed,
 150 an opaque pointer, a help string and a list of tokens in a NULL-terminated table.
 151
 152 The 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
 162 In this example, a new token type obj_list is defined and implemented
 163 in the parse_obj_list.c and parse_obj_list.h files.
 164
 165 For 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
 195 This 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
 201 Once the command is parsed, the rte_cmdline application fills a cmd_obj_del_show_result structure.
 202 A pointer to this structure is given as an argument to the callback function and can be used in the body of this function.