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 26such as completion, cut/paste and other special bindings 27that make configuration and debug faster and easier. 28 29The application shows how the ``cmdline`` library can be extended 30to handle a list of objects. 31 32There are three simple commands: 33 34* add obj_name IP: Add a new object with an IP/IPv6 address associated to it. 35 36* del obj_name: Delete the specified object. 37 38* show obj_name: Show the IP associated with the specified object. 39 40.. note:: 41 42 To terminate the application, use **Ctrl-d**. 43 44Compiling the Application 45------------------------- 46 47To compile the sample application see :doc:`compiling` 48 49The application is located in the ``cmd_line`` sub-directory. 50 51Running the Application 52----------------------- 53 54To run the application in a Linux environment, issue the following command: 55 56.. code-block:: console 57 58 $ ./<build_dir>/examples/dpdk-cmdline -l 0-3 -n 4 59 60Refer to the *DPDK Getting Started Guide* for general information on running applications 61and the Environment Abstraction Layer (EAL) options. 62 63Explanation 64----------- 65 66The following sections provide explanation of the code. 67 68EAL Initialization and cmdline Start 69~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 70 71The first task is the initialization of the Environment Abstraction Layer (EAL). 72This is achieved as follows: 73 74.. literalinclude:: ../../../examples/cmdline/main.c 75 :language: c 76 :start-after: Initialization of the Environment Abstraction Layer (EAL). 8< 77 :end-before: >8 End of initialization of Environment Abstraction Layer (EAL). 78 79Then, a new command line object is created and starts to interact with the user through the console: 80 81.. literalinclude:: ../../../examples/cmdline/main.c 82 :language: c 83 :start-after: Creating a new command line object. 8< 84 :end-before: >8 End of creating a new command line object. 85 :dedent: 1 86 87The ``cmdline_interact()`` function returns when the user types **Ctrl-d** and, 88in this case, the 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. 94For example: 95 96.. literalinclude:: ../../../examples/cmdline/commands.c 97 :language: c 98 :start-after: Cmdline context list of commands in NULL-terminated table. 8< 99 :end-before: >8 End of context list. 100 101Each command (of type cmdline_parse_inst_t) is defined statically. 102It contains a pointer to a callback function that is executed when the command is parsed, 103an opaque pointer, a help string and a list of tokens in a NULL-terminated table. 104 105The rte_cmdline application provides a list of pre-defined token types: 106 107* String Token: Match a static string, a list of static strings or any string. 108 109* Number Token: Match a number that can be signed or unsigned, from 8-bit to 32-bit. 110 111* IP Address Token: Match an IPv4 or IPv6 address or network. 112 113* Ethernet* Address Token: Match a MAC address. 114 115In this example, a new token type obj_list is defined and implemented 116in the parse_obj_list.c and parse_obj_list.h files. 117 118For example, the cmd_obj_del_show command is defined as shown below: 119 120.. literalinclude:: ../../../examples/cmdline/commands.c 121 :language: c 122 :start-after: Show or delete tokens. 8< 123 :end-before: >8 End of show or delete tokens. 124 125This command is composed of two tokens: 126 127* The first token is a string token that can be show or del. 128 129* The second token is an object that was previously added using the add command in the global_obj_list variable. 130 131Once the command is parsed, the rte_cmdline application fills a cmd_obj_del_show_result structure. 132A pointer to this structure is given as an argument to the callback function and can be used in the body of this function. 133