1 /* 2 * Copyright (c) 2018 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #ifndef SHELL_H__ 8 #define SHELL_H__ 9 10 #include <zephyr.h> 11 #include <shell/shell_types.h> 12 #include <shell/shell_history.h> 13 #include <shell/shell_fprintf.h> 14 #include <shell/shell_log_backend.h> 15 #include <logging/log_instance.h> 16 #include <logging/log.h> 17 #include <sys/util.h> 18 19 #if defined CONFIG_SHELL_GETOPT 20 #include <shell/shell_getopt.h> 21 #endif 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 #ifndef CONFIG_SHELL_CMD_BUFF_SIZE 28 #define CONFIG_SHELL_CMD_BUFF_SIZE 0 29 #endif 30 31 #ifndef CONFIG_SHELL_PRINTF_BUFF_SIZE 32 #define CONFIG_SHELL_PRINTF_BUFF_SIZE 0 33 #endif 34 35 #ifndef CONFIG_SHELL_HISTORY_BUFFER 36 #define CONFIG_SHELL_HISTORY_BUFFER 0 37 #endif 38 39 #define Z_SHELL_CMD_ROOT_LVL (0u) 40 41 #define SHELL_HEXDUMP_BYTES_IN_LINE 16 42 43 /** 44 * @brief Flag indicates that optional arguments will be treated as one, 45 * unformatted argument. 46 * 47 * By default, shell is parsing all arguments, treats all spaces as argument 48 * separators unless they are within quotation marks which are removed in that 49 * case. If command rely on unformatted argument then this flag shall be used 50 * in place of number of optional arguments in command definition to indicate 51 * that only mandatory arguments shall be parsed and remaining command string is 52 * passed as a raw string. 53 */ 54 #define SHELL_OPT_ARG_RAW (0xFE) 55 56 /** 57 * @brief Flag indicateding that number of optional arguments is not limited. 58 */ 59 #define SHELL_OPT_ARG_CHECK_SKIP (0xFF) 60 61 /** 62 * @brief Flag indicating maximum number of optional arguments that can be 63 * validated. 64 */ 65 #define SHELL_OPT_ARG_MAX (0xFD) 66 67 /** 68 * @brief Shell API 69 * @defgroup shell_api Shell API 70 * @ingroup shell 71 * @{ 72 */ 73 74 struct getopt_state; 75 struct shell_static_entry; 76 77 /** 78 * @brief Shell dynamic command descriptor. 79 * 80 * @details Function shall fill the received shell_static_entry structure 81 * with requested (idx) dynamic subcommand data. If there is more than 82 * one dynamic subcommand available, the function shall ensure that the 83 * returned commands: entry->syntax are sorted in alphabetical order. 84 * If idx exceeds the available dynamic subcommands, the function must 85 * write to entry->syntax NULL value. This will indicate to the shell 86 * module that there are no more dynamic commands to read. 87 */ 88 typedef void (*shell_dynamic_get)(size_t idx, 89 struct shell_static_entry *entry); 90 91 /** 92 * @brief Shell command descriptor. 93 */ 94 struct shell_cmd_entry { 95 bool is_dynamic; 96 union union_cmd_entry { 97 /*!< Pointer to function returning dynamic commands.*/ 98 shell_dynamic_get dynamic_get; 99 100 /*!< Pointer to array of static commands. */ 101 const struct shell_static_entry *entry; 102 } u; 103 }; 104 105 struct shell; 106 107 struct shell_static_args { 108 uint8_t mandatory; /*!< Number of mandatory arguments. */ 109 uint8_t optional; /*!< Number of optional arguments. */ 110 }; 111 112 /** 113 * @brief Get by index a device that matches . 114 * 115 * This can be used, for example, to identify I2C_1 as the second I2C 116 * device. 117 * 118 * Devices that failed to initialize or do not have a non-empty name 119 * are excluded from the candidates for a match. 120 * 121 * @param idx the device number starting from zero. 122 * 123 * @param prefix optional name prefix used to restrict candidate 124 * devices. Indexing is done relative to devices with names that 125 * start with this text. Pass null if no prefix match is required. 126 */ 127 const struct device *shell_device_lookup(size_t idx, 128 const char *prefix); 129 130 /** 131 * @brief Shell command handler prototype. 132 * 133 * @param shell Shell instance. 134 * @param argc Arguments count. 135 * @param argv Arguments. 136 * 137 * @retval 0 Successful command execution. 138 * @retval 1 Help printed and command not executed. 139 * @retval -EINVAL Argument validation failed. 140 * @retval -ENOEXEC Command not executed. 141 */ 142 typedef int (*shell_cmd_handler)(const struct shell *shell, 143 size_t argc, char **argv); 144 145 /** 146 * @brief Shell dictionary command handler prototype. 147 * 148 * @param shell Shell instance. 149 * @param argc Arguments count. 150 * @param argv Arguments. 151 * @param data Pointer to the user data. 152 * 153 * @retval 0 Successful command execution. 154 * @retval 1 Help printed and command not executed. 155 * @retval -EINVAL Argument validation failed. 156 * @retval -ENOEXEC Command not executed. 157 */ 158 typedef int (*shell_dict_cmd_handler)(const struct shell *shell, size_t argc, 159 char **argv, void *data); 160 161 /* 162 * @brief Shell static command descriptor. 163 */ 164 struct shell_static_entry { 165 const char *syntax; /*!< Command syntax strings. */ 166 const char *help; /*!< Command help string. */ 167 const struct shell_cmd_entry *subcmd; /*!< Pointer to subcommand. */ 168 shell_cmd_handler handler; /*!< Command handler. */ 169 struct shell_static_args args; /*!< Command arguments. */ 170 }; 171 172 /** 173 * @brief Macro for defining and adding a root command (level 0) with required 174 * number of arguments. 175 * 176 * @note Each root command shall have unique syntax. If a command will be called 177 * with wrong number of arguments shell will print an error message and command 178 * handler will not be called. 179 * 180 * @param[in] syntax Command syntax (for example: history). 181 * @param[in] subcmd Pointer to a subcommands array. 182 * @param[in] help Pointer to a command help string. 183 * @param[in] handler Pointer to a function handler. 184 * @param[in] mandatory Number of mandatory arguments includig command name. 185 * @param[in] optional Number of optional arguments. 186 */ 187 #define SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, \ 188 mandatory, optional) \ 189 static const struct shell_static_entry UTIL_CAT(_shell_, syntax) = \ 190 SHELL_CMD_ARG(syntax, subcmd, help, handler, mandatory, optional); \ 191 static const struct shell_cmd_entry UTIL_CAT(shell_cmd_, syntax) \ 192 __attribute__ ((section("." \ 193 STRINGIFY(UTIL_CAT(shell_root_cmd_, syntax))))) \ 194 __attribute__((used)) = { \ 195 .is_dynamic = false, \ 196 .u = {.entry = &UTIL_CAT(_shell_, syntax)} \ 197 } 198 199 /** 200 * @brief Macro for defining and adding a conditional root command (level 0) 201 * with required number of arguments. 202 * 203 * @see SHELL_CMD_ARG_REGISTER for details. 204 * 205 * Macro can be used to create a command which can be conditionally present. 206 * It is and alternative to \#ifdefs around command registration and command 207 * handler. If command is disabled handler and subcommands are removed from 208 * the application. 209 * 210 * @param[in] flag Compile time flag. Command is present only if flag 211 * exists and equals 1. 212 * @param[in] syntax Command syntax (for example: history). 213 * @param[in] subcmd Pointer to a subcommands array. 214 * @param[in] help Pointer to a command help string. 215 * @param[in] handler Pointer to a function handler. 216 * @param[in] mandatory Number of mandatory arguments includig command name. 217 * @param[in] optional Number of optional arguments. 218 */ 219 #define SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, \ 220 mandatory, optional) \ 221 COND_CODE_1(\ 222 flag, \ 223 (\ 224 SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, \ 225 mandatory, optional) \ 226 ), \ 227 (\ 228 static shell_cmd_handler dummy_##syntax##_handler __unused = \ 229 handler;\ 230 static const struct shell_cmd_entry *dummy_subcmd_##syntax \ 231 __unused = subcmd\ 232 )\ 233 ) 234 /** 235 * @brief Macro for defining and adding a root command (level 0) with 236 * arguments. 237 * 238 * @note All root commands must have different name. 239 * 240 * @param[in] syntax Command syntax (for example: history). 241 * @param[in] subcmd Pointer to a subcommands array. 242 * @param[in] help Pointer to a command help string. 243 * @param[in] handler Pointer to a function handler. 244 */ 245 #define SHELL_CMD_REGISTER(syntax, subcmd, help, handler) \ 246 SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, 0, 0) 247 248 /** 249 * @brief Macro for defining and adding a conditional root command (level 0) 250 * with arguments. 251 * 252 * @see SHELL_COND_CMD_ARG_REGISTER. 253 * 254 * @param[in] flag Compile time flag. Command is present only if flag 255 * exists and equals 1. 256 * @param[in] syntax Command syntax (for example: history). 257 * @param[in] subcmd Pointer to a subcommands array. 258 * @param[in] help Pointer to a command help string. 259 * @param[in] handler Pointer to a function handler. 260 */ 261 #define SHELL_COND_CMD_REGISTER(flag, syntax, subcmd, help, handler) \ 262 SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, 0, 0) 263 264 /** 265 * @brief Macro for creating a subcommand set. It must be used outside of any 266 * function body. 267 * 268 * Example usage: 269 * SHELL_STATIC_SUBCMD_SET_CREATE( 270 * foo, 271 * SHELL_CMD(abc, ...), 272 * SHELL_CMD(def, ...), 273 * SHELL_SUBCMD_SET_END 274 * ) 275 * 276 * @param[in] name Name of the subcommand set. 277 * @param[in] ... List of commands created with @ref SHELL_CMD_ARG or 278 * or @ref SHELL_CMD 279 */ 280 #define SHELL_STATIC_SUBCMD_SET_CREATE(name, ...) \ 281 static const struct shell_static_entry shell_##name[] = { \ 282 __VA_ARGS__ \ 283 }; \ 284 static const struct shell_cmd_entry name = { \ 285 .is_dynamic = false, \ 286 .u = { .entry = shell_##name } \ 287 } 288 289 /** 290 * @brief Define ending subcommands set. 291 * 292 */ 293 #define SHELL_SUBCMD_SET_END {NULL} 294 295 /** 296 * @brief Macro for creating a dynamic entry. 297 * 298 * @param[in] name Name of the dynamic entry. 299 * @param[in] get Pointer to the function returning dynamic commands array 300 */ 301 #define SHELL_DYNAMIC_CMD_CREATE(name, get) \ 302 static const struct shell_cmd_entry name = { \ 303 .is_dynamic = true, \ 304 .u = { .dynamic_get = get } \ 305 } 306 307 /** 308 * @brief Initializes a shell command with arguments. 309 * 310 * @note If a command will be called with wrong number of arguments shell will 311 * print an error message and command handler will not be called. 312 * 313 * @param[in] syntax Command syntax (for example: history). 314 * @param[in] subcmd Pointer to a subcommands array. 315 * @param[in] help Pointer to a command help string. 316 * @param[in] handler Pointer to a function handler. 317 * @param[in] mand Number of mandatory arguments includig command name. 318 * @param[in] opt Number of optional arguments. 319 */ 320 #define SHELL_CMD_ARG(syntax, subcmd, help, handler, mand, opt) \ 321 SHELL_EXPR_CMD_ARG(1, syntax, subcmd, help, handler, mand, opt) 322 323 /** 324 * @brief Initializes a conditional shell command with arguments. 325 * 326 * @see SHELL_CMD_ARG. Based on the flag, creates a valid entry or an empty 327 * command which is ignored by the shell. It is an alternative to \#ifdefs 328 * around command registration and command handler. However, empty structure is 329 * present in the flash even if command is disabled (subcommands and handler are 330 * removed). Macro internally handles case if flag is not defined so flag must 331 * be provided without any wrapper, e.g.: SHELL_COND_CMD_ARG(CONFIG_FOO, ...) 332 * 333 * @param[in] flag Compile time flag. Command is present only if flag 334 * exists and equals 1. 335 * @param[in] syntax Command syntax (for example: history). 336 * @param[in] subcmd Pointer to a subcommands array. 337 * @param[in] help Pointer to a command help string. 338 * @param[in] handler Pointer to a function handler. 339 * @param[in] mand Number of mandatory arguments includig command name. 340 * @param[in] opt Number of optional arguments. 341 */ 342 #define SHELL_COND_CMD_ARG(flag, syntax, subcmd, help, handler, mand, opt) \ 343 SHELL_EXPR_CMD_ARG(IS_ENABLED(flag), syntax, subcmd, help, \ 344 handler, mand, opt) 345 346 /** 347 * @brief Initializes a conditional shell command with arguments if expression 348 * gives non-zero result at compile time. 349 * 350 * @see SHELL_CMD_ARG. Based on the expression, creates a valid entry or an 351 * empty command which is ignored by the shell. It should be used instead of 352 * @ref SHELL_COND_CMD_ARG if condition is not a single configuration flag, 353 * e.g.: 354 * SHELL_EXPR_CMD_ARG(IS_ENABLED(CONFIG_FOO) && 355 * IS_ENABLED(CONFIG_FOO_SETTING_1), ...) 356 * 357 * @param[in] _expr Expression. 358 * @param[in] _syntax Command syntax (for example: history). 359 * @param[in] _subcmd Pointer to a subcommands array. 360 * @param[in] _help Pointer to a command help string. 361 * @param[in] _handler Pointer to a function handler. 362 * @param[in] _mand Number of mandatory arguments includig command name. 363 * @param[in] _opt Number of optional arguments. 364 */ 365 #define SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, \ 366 _mand, _opt) \ 367 { \ 368 .syntax = (_expr) ? (const char *)STRINGIFY(_syntax) : "", \ 369 .help = (_expr) ? (const char *)_help : NULL, \ 370 .subcmd = (const struct shell_cmd_entry *)((_expr) ? \ 371 _subcmd : NULL), \ 372 .handler = (shell_cmd_handler)((_expr) ? _handler : NULL), \ 373 .args = { .mandatory = _mand, .optional = _opt} \ 374 } 375 376 /** 377 * @brief Initializes a shell command. 378 * 379 * @param[in] _syntax Command syntax (for example: history). 380 * @param[in] _subcmd Pointer to a subcommands array. 381 * @param[in] _help Pointer to a command help string. 382 * @param[in] _handler Pointer to a function handler. 383 */ 384 #define SHELL_CMD(_syntax, _subcmd, _help, _handler) \ 385 SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0) 386 387 /** 388 * @brief Initializes a conditional shell command. 389 * 390 * @see SHELL_COND_CMD_ARG. 391 * 392 * @param[in] _flag Compile time flag. Command is present only if flag 393 * exists and equals 1. 394 * @param[in] _syntax Command syntax (for example: history). 395 * @param[in] _subcmd Pointer to a subcommands array. 396 * @param[in] _help Pointer to a command help string. 397 * @param[in] _handler Pointer to a function handler. 398 */ 399 #define SHELL_COND_CMD(_flag, _syntax, _subcmd, _help, _handler) \ 400 SHELL_COND_CMD_ARG(_flag, _syntax, _subcmd, _help, _handler, 0, 0) 401 402 /** 403 * @brief Initializes shell command if expression gives non-zero result at 404 * compile time. 405 * 406 * @see SHELL_EXPR_CMD_ARG. 407 * 408 * @param[in] _expr Compile time expression. Command is present only if 409 * expression is non-zero. 410 * @param[in] _syntax Command syntax (for example: history). 411 * @param[in] _subcmd Pointer to a subcommands array. 412 * @param[in] _help Pointer to a command help string. 413 * @param[in] _handler Pointer to a function handler. 414 */ 415 #define SHELL_EXPR_CMD(_expr, _syntax, _subcmd, _help, _handler) \ 416 SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, 0, 0) 417 418 /* Internal macro used for creating handlers for dictionary commands. */ 419 #define Z_SHELL_CMD_DICT_HANDLER_CREATE(_data, _handler) \ 420 static int UTIL_CAT(cmd_dict_, GET_ARG_N(1, __DEBRACKET _data))( \ 421 const struct shell *shell, size_t argc, char **argv) \ 422 { \ 423 return _handler(shell, argc, argv, \ 424 (void *)GET_ARG_N(2, __DEBRACKET _data)); \ 425 } 426 427 /* Internal macro used for creating dictionary commands. */ 428 #define SHELL_CMD_DICT_CREATE(_data) \ 429 SHELL_CMD_ARG(GET_ARG_N(1, __DEBRACKET _data), NULL, NULL, \ 430 UTIL_CAT(cmd_dict_, GET_ARG_N(1, __DEBRACKET _data)), 1, 0) 431 432 /** 433 * @brief Initializes shell dictionary commands. 434 * 435 * This is a special kind of static commands. Dictionary commands can be used 436 * every time you want to use a pair: (string <-> corresponding data) in 437 * a command handler. The string is usually a verbal description of a given 438 * data. The idea is to use the string as a command syntax that can be prompted 439 * by the shell and corresponding data can be used to process the command. 440 * 441 * @param[in] _name Name of the dictionary subcommand set 442 * @param[in] _handler Command handler common for all dictionary commands. 443 * @see shell_dict_cmd_handler 444 * @param[in] ... Dictionary pairs: (command_syntax, value). Value will be 445 * passed to the _handler as user data. 446 * 447 * Example usage: 448 * static int my_handler(const struct shell *shell, 449 * size_t argc, char **argv, void *data) 450 * { 451 * int val = (int)data; 452 * 453 * shell_print(shell, "(syntax, value) : (%s, %d)", argv[0], val); 454 * return 0; 455 * } 456 * 457 * SHELL_SUBCMD_DICT_SET_CREATE(sub_dict_cmds, my_handler, 458 * (value_0, 0), (value_1, 1), (value_2, 2), (value_3, 3) 459 * ); 460 * SHELL_CMD_REGISTER(dictionary, &sub_dict_cmds, NULL, NULL); 461 */ 462 #define SHELL_SUBCMD_DICT_SET_CREATE(_name, _handler, ...) \ 463 FOR_EACH_FIXED_ARG(Z_SHELL_CMD_DICT_HANDLER_CREATE, (), \ 464 _handler, __VA_ARGS__) \ 465 SHELL_STATIC_SUBCMD_SET_CREATE(_name, \ 466 FOR_EACH(SHELL_CMD_DICT_CREATE, (,), __VA_ARGS__), \ 467 SHELL_SUBCMD_SET_END \ 468 ) 469 470 /** 471 * @internal @brief Internal shell state in response to data received from the 472 * terminal. 473 */ 474 enum shell_receive_state { 475 SHELL_RECEIVE_DEFAULT, 476 SHELL_RECEIVE_ESC, 477 SHELL_RECEIVE_ESC_SEQ, 478 SHELL_RECEIVE_TILDE_EXP 479 }; 480 481 /** 482 * @internal @brief Internal shell state. 483 */ 484 enum shell_state { 485 SHELL_STATE_UNINITIALIZED, 486 SHELL_STATE_INITIALIZED, 487 SHELL_STATE_ACTIVE, 488 SHELL_STATE_PANIC_MODE_ACTIVE, /*!< Panic activated.*/ 489 SHELL_STATE_PANIC_MODE_INACTIVE /*!< Panic requested, not supported.*/ 490 }; 491 492 /** @brief Shell transport event. */ 493 enum shell_transport_evt { 494 SHELL_TRANSPORT_EVT_RX_RDY, 495 SHELL_TRANSPORT_EVT_TX_RDY 496 }; 497 498 typedef void (*shell_transport_handler_t)(enum shell_transport_evt evt, 499 void *context); 500 501 502 typedef void (*shell_uninit_cb_t)(const struct shell *shell, int res); 503 504 /** @brief Bypass callback. 505 * 506 * @param shell Shell instance. 507 * @param data Raw data from transport. 508 * @param len Data length. 509 */ 510 typedef void (*shell_bypass_cb_t)(const struct shell *shell, 511 uint8_t *data, 512 size_t len); 513 514 struct shell_transport; 515 516 /** 517 * @brief Unified shell transport interface. 518 */ 519 struct shell_transport_api { 520 /** 521 * @brief Function for initializing the shell transport interface. 522 * 523 * @param[in] transport Pointer to the transfer instance. 524 * @param[in] config Pointer to instance configuration. 525 * @param[in] evt_handler Event handler. 526 * @param[in] context Pointer to the context passed to event 527 * handler. 528 * 529 * @return Standard error code. 530 */ 531 int (*init)(const struct shell_transport *transport, 532 const void *config, 533 shell_transport_handler_t evt_handler, 534 void *context); 535 536 /** 537 * @brief Function for uninitializing the shell transport interface. 538 * 539 * @param[in] transport Pointer to the transfer instance. 540 * 541 * @return Standard error code. 542 */ 543 int (*uninit)(const struct shell_transport *transport); 544 545 /** 546 * @brief Function for enabling transport in given TX mode. 547 * 548 * Function can be used to reconfigure TX to work in blocking mode. 549 * 550 * @param transport Pointer to the transfer instance. 551 * @param blocking_tx If true, the transport TX is enabled in blocking 552 * mode. 553 * 554 * @return NRF_SUCCESS on successful enabling, error otherwise (also if 555 * not supported). 556 */ 557 int (*enable)(const struct shell_transport *transport, 558 bool blocking_tx); 559 560 /** 561 * @brief Function for writing data to the transport interface. 562 * 563 * @param[in] transport Pointer to the transfer instance. 564 * @param[in] data Pointer to the source buffer. 565 * @param[in] length Source buffer length. 566 * @param[out] cnt Pointer to the sent bytes counter. 567 * 568 * @return Standard error code. 569 */ 570 int (*write)(const struct shell_transport *transport, 571 const void *data, size_t length, size_t *cnt); 572 573 /** 574 * @brief Function for reading data from the transport interface. 575 * 576 * @param[in] p_transport Pointer to the transfer instance. 577 * @param[in] p_data Pointer to the destination buffer. 578 * @param[in] length Destination buffer length. 579 * @param[out] cnt Pointer to the received bytes counter. 580 * 581 * @return Standard error code. 582 */ 583 int (*read)(const struct shell_transport *transport, 584 void *data, size_t length, size_t *cnt); 585 586 /** 587 * @brief Function called in shell thread loop. 588 * 589 * Can be used for backend operations that require longer execution time 590 * 591 * @param[in] transport Pointer to the transfer instance. 592 */ 593 void (*update)(const struct shell_transport *transport); 594 595 }; 596 597 struct shell_transport { 598 const struct shell_transport_api *api; 599 void *ctx; 600 }; 601 602 /** 603 * @brief Shell statistics structure. 604 */ 605 struct shell_stats { 606 atomic_t log_lost_cnt; /*!< Lost log counter.*/ 607 }; 608 609 #ifdef CONFIG_SHELL_STATS 610 #define Z_SHELL_STATS_DEFINE(_name) static struct shell_stats _name##_stats 611 #define Z_SHELL_STATS_PTR(_name) (&(_name##_stats)) 612 #else 613 #define Z_SHELL_STATS_DEFINE(_name) 614 #define Z_SHELL_STATS_PTR(_name) NULL 615 #endif /* CONFIG_SHELL_STATS */ 616 617 /** 618 * @internal @brief Flags for internal shell usage. 619 */ 620 struct shell_flags { 621 uint32_t insert_mode :1; /*!< Controls insert mode for text introduction.*/ 622 uint32_t use_colors :1; /*!< Controls colored syntax.*/ 623 uint32_t echo :1; /*!< Controls shell echo.*/ 624 uint32_t obscure :1; /*!< If echo on, print asterisk instead */ 625 uint32_t processing :1; /*!< Shell is executing process function.*/ 626 uint32_t tx_rdy :1; 627 uint32_t mode_delete :1; /*!< Operation mode of backspace key */ 628 uint32_t history_exit:1; /*!< Request to exit history mode */ 629 uint32_t last_nl :8; /*!< Last received new line character */ 630 uint32_t cmd_ctx :1; /*!< Shell is executing command */ 631 uint32_t print_noinit:1; /*!< Print request from not initialized shell*/ 632 uint32_t panic_mode :1; /*!< Shell in panic mode */ 633 }; 634 635 BUILD_ASSERT((sizeof(struct shell_flags) == sizeof(uint32_t)), 636 "Structure must fit in 4 bytes"); 637 638 /** 639 * @internal @brief Union for internal shell usage. 640 */ 641 union shell_internal { 642 uint32_t value; 643 struct shell_flags flags; 644 }; 645 646 enum shell_signal { 647 SHELL_SIGNAL_RXRDY, 648 SHELL_SIGNAL_LOG_MSG, 649 SHELL_SIGNAL_KILL, 650 SHELL_SIGNAL_TXDONE, /* TXDONE must be last one before SHELL_SIGNALS */ 651 SHELL_SIGNALS 652 }; 653 654 /** 655 * @brief Shell instance context. 656 */ 657 struct shell_ctx { 658 const char *prompt; /*!< shell current prompt. */ 659 660 enum shell_state state; /*!< Internal module state.*/ 661 enum shell_receive_state receive_state;/*!< Escape sequence indicator.*/ 662 663 /*!< Currently executed command.*/ 664 struct shell_static_entry active_cmd; 665 666 /* New root command. If NULL shell uses default root commands. */ 667 const struct shell_static_entry *selected_cmd; 668 669 /*!< VT100 color and cursor position, terminal width.*/ 670 struct shell_vt100_ctx vt100_ctx; 671 672 /*!< Callback called from shell thread context when unitialization is 673 * completed just before aborting shell thread. 674 */ 675 shell_uninit_cb_t uninit_cb; 676 677 /*!< When bypass is set, all incoming data is passed to the callback. */ 678 shell_bypass_cb_t bypass; 679 680 #if defined CONFIG_SHELL_GETOPT 681 /*!< getopt context for a shell backend. */ 682 struct getopt_state getopt_state; 683 #endif 684 685 uint16_t cmd_buff_len; /*!< Command length.*/ 686 uint16_t cmd_buff_pos; /*!< Command buffer cursor position.*/ 687 688 uint16_t cmd_tmp_buff_len; /*!< Command length in tmp buffer.*/ 689 690 /*!< Command input buffer.*/ 691 char cmd_buff[CONFIG_SHELL_CMD_BUFF_SIZE]; 692 693 /*!< Command temporary buffer.*/ 694 char temp_buff[CONFIG_SHELL_CMD_BUFF_SIZE]; 695 696 /*!< Printf buffer size.*/ 697 char printf_buff[CONFIG_SHELL_PRINTF_BUFF_SIZE]; 698 699 volatile union shell_internal internal; /*!< Internal shell data.*/ 700 701 struct k_poll_signal signals[SHELL_SIGNALS]; 702 703 /*!< Events that should be used only internally by shell thread. 704 * Event for SHELL_SIGNAL_TXDONE is initialized but unused. 705 */ 706 struct k_poll_event events[SHELL_SIGNALS]; 707 708 struct k_mutex wr_mtx; 709 k_tid_t tid; 710 }; 711 712 extern const struct log_backend_api log_backend_shell_api; 713 714 /** 715 * @brief Flags for setting shell output newline sequence. 716 */ 717 enum shell_flag { 718 SHELL_FLAG_CRLF_DEFAULT = (1<<0), /* Do not map CR or LF */ 719 SHELL_FLAG_OLF_CRLF = (1<<1) /* Map LF to CRLF on output */ 720 }; 721 722 /** 723 * @brief Shell instance internals. 724 */ 725 struct shell { 726 const char *default_prompt; /*!< shell default prompt. */ 727 728 const struct shell_transport *iface; /*!< Transport interface.*/ 729 struct shell_ctx *ctx; /*!< Internal context.*/ 730 731 struct shell_history *history; 732 733 const enum shell_flag shell_flag; 734 735 const struct shell_fprintf *fprintf_ctx; 736 737 struct shell_stats *stats; 738 739 const struct shell_log_backend *log_backend; 740 741 LOG_INSTANCE_PTR_DECLARE(log); 742 743 const char *thread_name; 744 struct k_thread *thread; 745 k_thread_stack_t *stack; 746 }; 747 748 extern void z_shell_print_stream(const void *user_ctx, const char *data, 749 size_t data_len); 750 /** 751 * @brief Macro for defining a shell instance. 752 * 753 * @param[in] _name Instance name. 754 * @param[in] _prompt Shell default prompt string. 755 * @param[in] _transport_iface Pointer to the transport interface. 756 * @param[in] _log_queue_size Logger processing queue size. 757 * @param[in] _log_timeout Logger thread timeout in milliseconds on full 758 * log queue. If queue is full logger thread is 759 * blocked for given amount of time before log 760 * message is dropped. 761 * @param[in] _shell_flag Shell output newline sequence. 762 */ 763 #define SHELL_DEFINE(_name, _prompt, _transport_iface, \ 764 _log_queue_size, _log_timeout, _shell_flag) \ 765 static const struct shell _name; \ 766 static struct shell_ctx UTIL_CAT(_name, _ctx); \ 767 static uint8_t _name##_out_buffer[CONFIG_SHELL_PRINTF_BUFF_SIZE]; \ 768 Z_SHELL_LOG_BACKEND_DEFINE(_name, _name##_out_buffer, \ 769 CONFIG_SHELL_PRINTF_BUFF_SIZE, \ 770 _log_queue_size, _log_timeout); \ 771 Z_SHELL_HISTORY_DEFINE(_name##_history, CONFIG_SHELL_HISTORY_BUFFER); \ 772 Z_SHELL_FPRINTF_DEFINE(_name##_fprintf, &_name, _name##_out_buffer, \ 773 CONFIG_SHELL_PRINTF_BUFF_SIZE, \ 774 true, z_shell_print_stream); \ 775 LOG_INSTANCE_REGISTER(shell, _name, CONFIG_SHELL_LOG_LEVEL); \ 776 Z_SHELL_STATS_DEFINE(_name); \ 777 static K_KERNEL_STACK_DEFINE(_name##_stack, CONFIG_SHELL_STACK_SIZE); \ 778 static struct k_thread _name##_thread; \ 779 static const STRUCT_SECTION_ITERABLE(shell, _name) = { \ 780 .default_prompt = _prompt, \ 781 .iface = _transport_iface, \ 782 .ctx = &UTIL_CAT(_name, _ctx), \ 783 .history = IS_ENABLED(CONFIG_SHELL_HISTORY) ? \ 784 &_name##_history : NULL, \ 785 .shell_flag = _shell_flag, \ 786 .fprintf_ctx = &_name##_fprintf, \ 787 .stats = Z_SHELL_STATS_PTR(_name), \ 788 .log_backend = Z_SHELL_LOG_BACKEND_PTR(_name), \ 789 LOG_INSTANCE_PTR_INIT(log, shell, _name) \ 790 .thread_name = STRINGIFY(_name), \ 791 .thread = &_name##_thread, \ 792 .stack = _name##_stack \ 793 } 794 795 /** 796 * @brief Function for initializing a transport layer and internal shell state. 797 * 798 * @param[in] shell Pointer to shell instance. 799 * @param[in] transport_config Transport configuration during initialization. 800 * @param[in] use_colors Enables colored prints. 801 * @param[in] log_backend If true, the console will be used as logger 802 * backend. 803 * @param[in] init_log_level Default severity level for the logger. 804 * 805 * @return Standard error code. 806 */ 807 int shell_init(const struct shell *shell, const void *transport_config, 808 bool use_colors, bool log_backend, uint32_t init_log_level); 809 810 /** 811 * @brief Uninitializes the transport layer and the internal shell state. 812 * 813 * @param shell Pointer to shell instance. 814 * @param cb Callback called when uninitialization is completed. 815 * 816 * @return Standard error code. 817 */ 818 void shell_uninit(const struct shell *shell, shell_uninit_cb_t cb); 819 820 /** 821 * @brief Function for starting shell processing. 822 * 823 * @param shell Pointer to the shell instance. 824 * 825 * @return Standard error code. 826 */ 827 int shell_start(const struct shell *shell); 828 829 /** 830 * @brief Function for stopping shell processing. 831 * 832 * @param shell Pointer to shell instance. 833 * 834 * @return Standard error code. 835 */ 836 int shell_stop(const struct shell *shell); 837 838 /** 839 * @brief Terminal default text color for shell_fprintf function. 840 */ 841 #define SHELL_NORMAL SHELL_VT100_COLOR_DEFAULT 842 843 /** 844 * @brief Green text color for shell_fprintf function. 845 */ 846 #define SHELL_INFO SHELL_VT100_COLOR_GREEN 847 848 /** 849 * @brief Cyan text color for shell_fprintf function. 850 */ 851 #define SHELL_OPTION SHELL_VT100_COLOR_CYAN 852 853 /** 854 * @brief Yellow text color for shell_fprintf function. 855 */ 856 #define SHELL_WARNING SHELL_VT100_COLOR_YELLOW 857 858 /** 859 * @brief Red text color for shell_fprintf function. 860 */ 861 #define SHELL_ERROR SHELL_VT100_COLOR_RED 862 863 /** 864 * @brief printf-like function which sends formatted data stream to the shell. 865 * 866 * This function can be used from the command handler or from threads, but not 867 * from an interrupt context. 868 * 869 * @param[in] shell Pointer to the shell instance. 870 * @param[in] color Printed text color. 871 * @param[in] fmt Format string. 872 * @param[in] ... List of parameters to print. 873 */ 874 void shell_fprintf(const struct shell *shell, enum shell_vt100_color color, 875 const char *fmt, ...); 876 877 /** 878 * @brief vprintf-like function which sends formatted data stream to the shell. 879 * 880 * This function can be used from the command handler or from threads, but not 881 * from an interrupt context. It is similar to shell_fprintf() but takes a 882 * va_list instead of variable arguments. 883 * 884 * @param[in] shell Pointer to the shell instance. 885 * @param[in] color Printed text color. 886 * @param[in] fmt Format string. 887 * @param[in] args List of parameters to print. 888 */ 889 void shell_vfprintf(const struct shell *shell, enum shell_vt100_color color, 890 const char *fmt, va_list args); 891 892 /** 893 * @brief Print a line of data in hexadecimal format. 894 * 895 * Each line shows the offset, bytes and then ASCII representation. 896 * 897 * For example: 898 * 899 * 00008010: 20 25 00 20 2f 48 00 08 80 05 00 20 af 46 00 900 * | %. /H.. ... .F. | 901 * 902 * @param[in] shell Pointer to the shell instance. 903 * @param[in] offset Offset to show for this line. 904 * @param[in] data Pointer to data. 905 * @param[in] len Length of data. 906 */ 907 void shell_hexdump_line(const struct shell *shell, unsigned int offset, 908 const uint8_t *data, size_t len); 909 910 /** 911 * @brief Print data in hexadecimal format. 912 * 913 * @param[in] shell Pointer to the shell instance. 914 * @param[in] data Pointer to data. 915 * @param[in] len Length of data. 916 */ 917 void shell_hexdump(const struct shell *shell, const uint8_t *data, size_t len); 918 919 /** 920 * @brief Print info message to the shell. 921 * 922 * See @ref shell_fprintf. 923 * 924 * @param[in] _sh Pointer to the shell instance. 925 * @param[in] _ft Format string. 926 * @param[in] ... List of parameters to print. 927 */ 928 #define shell_info(_sh, _ft, ...) \ 929 shell_fprintf(_sh, SHELL_INFO, _ft "\n", ##__VA_ARGS__) 930 931 /** 932 * @brief Print normal message to the shell. 933 * 934 * See @ref shell_fprintf. 935 * 936 * @param[in] _sh Pointer to the shell instance. 937 * @param[in] _ft Format string. 938 * @param[in] ... List of parameters to print. 939 */ 940 #define shell_print(_sh, _ft, ...) \ 941 shell_fprintf(_sh, SHELL_NORMAL, _ft "\n", ##__VA_ARGS__) 942 943 /** 944 * @brief Print warning message to the shell. 945 * 946 * See @ref shell_fprintf. 947 * 948 * @param[in] _sh Pointer to the shell instance. 949 * @param[in] _ft Format string. 950 * @param[in] ... List of parameters to print. 951 */ 952 #define shell_warn(_sh, _ft, ...) \ 953 shell_fprintf(_sh, SHELL_WARNING, _ft "\n", ##__VA_ARGS__) 954 955 /** 956 * @brief Print error message to the shell. 957 * 958 * See @ref shell_fprintf. 959 * 960 * @param[in] _sh Pointer to the shell instance. 961 * @param[in] _ft Format string. 962 * @param[in] ... List of parameters to print. 963 */ 964 #define shell_error(_sh, _ft, ...) \ 965 shell_fprintf(_sh, SHELL_ERROR, _ft "\n", ##__VA_ARGS__) 966 967 /** 968 * @brief Process function, which should be executed when data is ready in the 969 * transport interface. To be used if shell thread is disabled. 970 * 971 * @param[in] shell Pointer to the shell instance. 972 */ 973 void shell_process(const struct shell *shell); 974 975 /** 976 * @brief Change displayed shell prompt. 977 * 978 * @param[in] shell Pointer to the shell instance. 979 * @param[in] prompt New shell prompt. 980 * 981 * @return 0 Success. 982 * @return -EINVAL Pointer to new prompt is not correct. 983 */ 984 int shell_prompt_change(const struct shell *shell, const char *prompt); 985 986 /** 987 * @brief Prints the current command help. 988 * 989 * Function will print a help string with: the currently entered command 990 * and subcommands (if they exist). 991 * 992 * @param[in] shell Pointer to the shell instance. 993 */ 994 void shell_help(const struct shell *shell); 995 996 /* @brief Command's help has been printed */ 997 #define SHELL_CMD_HELP_PRINTED (1) 998 999 #if defined CONFIG_SHELL_GETOPT 1000 /** 1001 * @brief Parses the command-line arguments. 1002 * 1003 * It is based on FreeBSD implementation. 1004 * 1005 * @param[in] shell Pointer to the shell instance. 1006 * @param[in] argc Arguments count. 1007 * @param[in] argv Arguments. 1008 * @param[in] ostr String containing the legitimate option characters. 1009 * 1010 * @return If an option was successfully found, function returns 1011 * the option character. 1012 * @return If options have been detected that is not in @p ostr 1013 * function will return '?'. 1014 * If function encounters an option with a missing 1015 * argument, then the return value depends on the first 1016 * character in optstring: if it is ':', then ':' is 1017 * returned; otherwise '?' is returned. 1018 * @return -1 If all options have been parsed. 1019 */ 1020 int shell_getopt(const struct shell *shell, int argc, char *const argv[], 1021 const char *ostr); 1022 1023 /** 1024 * @brief Returns shell_getopt state. 1025 * 1026 * @param[in] shell Pointer to the shell instance. 1027 * 1028 * @return Pointer to struct getopt_state. 1029 */ 1030 struct getopt_state *shell_getopt_state_get(const struct shell *shell); 1031 #endif /* CONFIG_SHELL_GETOPT */ 1032 1033 /** @brief Execute command. 1034 * 1035 * Pass command line to shell to execute. 1036 * 1037 * Note: This by no means makes any of the commands a stable interface, so 1038 * this function should only be used for debugging/diagnostic. 1039 * 1040 * This function must not be called from shell command context! 1041 1042 * 1043 * @param[in] shell Pointer to the shell instance. 1044 * It can be NULL when the 1045 * @kconfig{CONFIG_SHELL_BACKEND_DUMMY} option is enabled. 1046 * @param[in] cmd Command to be executed. 1047 * 1048 * @return Result of the execution 1049 */ 1050 int shell_execute_cmd(const struct shell *shell, const char *cmd); 1051 1052 /** @brief Set root command for all shell instances. 1053 * 1054 * It allows setting from the code the root command. It is an equivalent of 1055 * calling select command with one of the root commands as the argument 1056 * (e.g "select log") except it sets command for all shell instances. 1057 * 1058 * @param cmd String with one of the root commands or null pointer to reset. 1059 * 1060 * @retval 0 if root command is set. 1061 * @retval -EINVAL if invalid root command is provided. 1062 */ 1063 int shell_set_root_cmd(const char *cmd); 1064 1065 /** @brief Set bypass callback. 1066 * 1067 * Bypass callback is called whenever data is received. Shell is bypassed and 1068 * data is passed directly to the callback. Use null to disable bypass functionality. 1069 * 1070 * @param[in] shell Pointer to the shell instance. 1071 * @param[in] bypass Bypass callback or null to disable. 1072 */ 1073 void shell_set_bypass(const struct shell *shell, shell_bypass_cb_t bypass); 1074 1075 /** 1076 * @brief Allow application to control text insert mode. 1077 * Value is modified atomically and the previous value is returned. 1078 * 1079 * @param[in] shell Pointer to the shell instance. 1080 * @param[in] val Insert mode. 1081 * 1082 * @retval 0 or 1: previous value 1083 * @retval -EINVAL if shell is NULL. 1084 */ 1085 int shell_insert_mode_set(const struct shell *shell, bool val); 1086 1087 /** 1088 * @brief Allow application to control whether terminal output uses colored 1089 * syntax. 1090 * Value is modified atomically and the previous value is returned. 1091 * 1092 * @param[in] shell Pointer to the shell instance. 1093 * @param[in] val Color mode. 1094 * 1095 * @retval 0 or 1: previous value 1096 * @retval -EINVAL if shell is NULL. 1097 */ 1098 int shell_use_colors_set(const struct shell *shell, bool val); 1099 1100 /** 1101 * @brief Allow application to control whether user input is echoed back. 1102 * Value is modified atomically and the previous value is returned. 1103 * 1104 * @param[in] shell Pointer to the shell instance. 1105 * @param[in] val Echo mode. 1106 * 1107 * @retval 0 or 1: previous value 1108 * @retval -EINVAL if shell is NULL. 1109 */ 1110 int shell_echo_set(const struct shell *shell, bool val); 1111 1112 /** 1113 * @brief Allow application to control whether user input is obscured with 1114 * asterisks -- useful for implementing passwords. 1115 * Value is modified atomically and the previous value is returned. 1116 * 1117 * @param[in] shell Pointer to the shell instance. 1118 * @param[in] obscure Obscure mode. 1119 * 1120 * @retval 0 or 1: previous value. 1121 * @retval -EINVAL if shell is NULL. 1122 */ 1123 int shell_obscure_set(const struct shell *shell, bool obscure); 1124 1125 /** 1126 * @brief Allow application to control whether the delete key backspaces or 1127 * deletes. 1128 * Value is modified atomically and the previous value is returned. 1129 * 1130 * @param[in] shell Pointer to the shell instance. 1131 * @param[in] val Delete mode. 1132 * 1133 * @retval 0 or 1: previous value 1134 * @retval -EINVAL if shell is NULL. 1135 */ 1136 int shell_mode_delete_set(const struct shell *shell, bool val); 1137 1138 /** 1139 * @} 1140 */ 1141 1142 #ifdef __cplusplus 1143 } 1144 #endif 1145 1146 #endif /* SHELL_H__ */ 1147
