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