]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | .. SPDX-License-Identifier: BSD-3-Clause |
2 | Copyright(c) 2010-2014 Intel Corporation. | |
7c673cae FG |
3 | |
4 | Command Line Sample Application | |
5 | =============================== | |
6 | ||
7 | This chapter describes the Command Line sample application that | |
8 | is part of the Data Plane Development Kit (DPDK). | |
9 | ||
10 | Overview | |
11 | -------- | |
12 | ||
13 | The Command Line sample application is a simple application that | |
14 | demonstrates the use of the command line interface in the DPDK. | |
15 | This application is a readline-like interface that can be used | |
16 | to 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 | ||
25 | The Command Line sample application supports some of the features of the GNU readline library such as, completion, | |
26 | cut/paste and some other special bindings that make configuration and debug faster and easier. | |
27 | ||
28 | The application shows how the rte_cmdline application can be extended to handle a list of objects. | |
29 | There 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 | ||
41 | Compiling the Application | |
42 | ------------------------- | |
43 | ||
11fdf7f2 | 44 | To compile the sample application see :doc:`compiling` |
7c673cae | 45 | |
11fdf7f2 | 46 | The application is located in the ``cmd_line`` sub-directory. |
7c673cae FG |
47 | |
48 | Running the Application | |
49 | ----------------------- | |
50 | ||
9f95a23c | 51 | To run the application in linux environment, issue the following command: |
7c673cae FG |
52 | |
53 | .. code-block:: console | |
54 | ||
11fdf7f2 | 55 | $ ./build/cmdline -l 0-3 -n 4 |
7c673cae FG |
56 | |
57 | Refer to the *DPDK Getting Started Guide* for general information on running applications | |
58 | and the Environment Abstraction Layer (EAL) options. | |
59 | ||
60 | Explanation | |
61 | ----------- | |
62 | ||
63 | The following sections provide some explanation of the code. | |
64 | ||
65 | EAL Initialization and cmdline Start | |
66 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
67 | ||
68 | The first task is the initialization of the Environment Abstraction Layer (EAL). | |
69 | This 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 | ||
79 | Then, 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 | ||
87 | The cmd line_interact() function returns when the user types **Ctrl-d** and in this case, | |
88 | the application exits. | |
89 | ||
90 | Defining a cmdline Context | |
91 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
92 | ||
93 | A 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 | ||
104 | Each command (of type cmdline_parse_inst_t) is defined statically. | |
105 | It contains a pointer to a callback function that is executed when the command is parsed, | |
106 | an opaque pointer, a help string and a list of tokens in a NULL-terminated table. | |
107 | ||
108 | The 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 | ||
118 | In this example, a new token type obj_list is defined and implemented | |
119 | in the parse_obj_list.c and parse_obj_list.h files. | |
120 | ||
121 | For 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, attribute ((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 | ||
151 | This 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 | ||
157 | Once the command is parsed, the rte_cmdline application fills a cmd_obj_del_show_result structure. | |
158 | A pointer to this structure is given as an argument to the callback function and can be used in the body of this function. |