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