-.. BSD LICENSE
- Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
- All rights reserved.
-
- Redistribution and use in source and binary forms, with or without
- modification, are permitted provided that the following conditions
- are met:
-
- * Redistributions of source code must retain the above copyright
- notice, this list of conditions and the following disclaimer.
- * Redistributions in binary form must reproduce the above copyright
- notice, this list of conditions and the following disclaimer in
- the documentation and/or other materials provided with the
- distribution.
- * Neither the name of Intel Corporation nor the names of its
- contributors may be used to endorse or promote products derived
- from this software without specific prior written permission.
-
- THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
- LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
- LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
- DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
- OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.. SPDX-License-Identifier: BSD-3-Clause
+ Copyright(c) 2010-2014 Intel Corporation.
Command Line Sample Application
===============================
This chapter describes the Command Line sample application that
-is part of the Intel® Data Plane Development Kit (Intel® DPDK).
+is part of the Data Plane Development Kit (DPDK).
Overview
--------
The Command Line sample application is a simple application that
-demonstrates the use of the command line interface in the Intel® DPDK.
+demonstrates the use of the command line interface in the DPDK.
This application is a readline-like interface that can be used
-to debug an Intel® DPDK application, in a Linux* application environment.
+to debug a DPDK application, in a Linux* application environment.
.. note::
The rte_cmdline library should not be used in production code since
- it is not validated to the same standard as other Intel® DPDK libraries.
+ it is not validated to the same standard as other DPDK libraries.
See also the "rte_cmdline library should not be used in production code due to limited testing" item
in the "Known Issues" section of the Release Notes.
Compiling the Application
-------------------------
-#. Go to example directory:
+To compile the sample application see :doc:`compiling`
- .. code-block:: console
-
- export RTE_SDK=/path/to/rte_sdk
- cd ${RTE_SDK}/examples/cmdline
-
-#. Set the target (a default target is used if not specified). For example:
-
- .. code-block:: console
-
- export RTE_TARGET=x86_64-native-linuxapp-gcc
-
- Refer to the *Intel® DPDK Getting Started Guide* for possible RTE_TARGET values.
-
-#. Build the application:
-
- .. code-block:: console
-
- make
+The application is located in the ``cmd_line`` sub-directory.
Running the Application
-----------------------
-To run the application in linuxapp environment, issue the following command:
+To run the application in linux environment, issue the following command:
.. code-block:: console
- $ ./build/cmdline -c f -n 4
+ $ ./<build_dir>/examples/dpdk-cmdline -l 0-3 -n 4
-Refer to the *Intel® DPDK Getting Started Guide* for general information on running applications
+Refer to the *DPDK Getting Started Guide* for general information on running applications
and the Environment Abstraction Layer (EAL) options.
Explanation
The first task is the initialization of the Environment Abstraction Layer (EAL).
This is achieved as follows:
-.. code-block:: c
-
- int main(int argc, char **argv)
- {
- ret = rte_eal_init(argc, argv);
- if (ret < 0)
- rte_panic("Cannot init EAL\n");
+.. literalinclude:: ../../../examples/cmdline/main.c
+ :language: c
+ :start-after: Initialization of the Environment Abstraction Layer (EAL). 8<
+ :end-before: >8 End of initialization of Environment Abstraction Layer (EAL).
Then, a new command line object is created and started to interact with the user through the console:
-.. code-block:: c
-
- cl = cmdline_stdin_new(main_ctx, "example> ");
- cmdline_interact(cl);
- cmdline_stdin_exit(cl);
+.. literalinclude:: ../../../examples/cmdline/main.c
+ :language: c
+ :start-after: Creating a new command line object. 8<
+ :end-before: >8 End of creating a new command line object.
+ :dedent: 1
The cmd line_interact() function returns when the user types **Ctrl-d** and in this case,
the application exits.
A cmdline context is a list of commands that are listed in a NULL-terminated table, for example:
-.. code-block:: c
-
- cmdline_parse_ctx_t main_ctx[] = {
- (cmdline_parse_inst_t *) &cmd_obj_del_show,
- (cmdline_parse_inst_t *) &cmd_obj_add,
- (cmdline_parse_inst_t *) &cmd_help,
- NULL,
- };
+.. literalinclude:: ../../../examples/cmdline/commands.c
+ :language: c
+ :start-after: Cmdline context list of commands in NULL-terminated table. 8<
+ :end-before: >8 End of context list.
Each command (of type cmdline_parse_inst_t) is defined statically.
It contains a pointer to a callback function that is executed when the command is parsed,
For example, the cmd_obj_del_show command is defined as shown below:
-.. code-block:: c
-
- struct cmd_obj_add_result {
- cmdline_fixed_string_t action;
- cmdline_fixed_string_t name;
- struct object *obj;
- };
-
- static void cmd_obj_del_show_parsed(void *parsed_result, struct cmdline *cl, attribute ((unused)) void *data)
- {
- /* ... */
- }
-
- cmdline_parse_token_string_t cmd_obj_action = TOKEN_STRING_INITIALIZER(struct cmd_obj_del_show_result, action, "show#del");
-
- parse_token_obj_list_t cmd_obj_obj = TOKEN_OBJ_LIST_INITIALIZER(struct cmd_obj_del_show_result, obj, &global_obj_list);
-
- cmdline_parse_inst_t cmd_obj_del_show = {
- .f = cmd_obj_del_show_parsed, /* function to call */
- .data = NULL, /* 2nd arg of func */
- .help_str = "Show/del an object",
- .tokens = { /* token list, NULL terminated */
- (void *)&cmd_obj_action,
- (void *)&cmd_obj_obj,
- NULL,
- },
- };
+.. literalinclude:: ../../../examples/cmdline/commands.c
+ :language: c
+ :start-after: Show or delete tokens. 8<
+ :end-before: >8 End of show or delete tokens.
This command is composed of two tokens: