Line data Source code
1 0 : /*
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 0 : #define CONFIG_SHELL_PROMPT_BUFF_SIZE 0
31 : #endif
32 :
33 : #ifndef CONFIG_SHELL_CMD_BUFF_SIZE
34 0 : #define CONFIG_SHELL_CMD_BUFF_SIZE 0
35 : #endif
36 :
37 : #ifndef CONFIG_SHELL_PRINTF_BUFF_SIZE
38 0 : #define CONFIG_SHELL_PRINTF_BUFF_SIZE 0
39 : #endif
40 :
41 : #ifndef CONFIG_SHELL_HISTORY_BUFFER
42 0 : #define CONFIG_SHELL_HISTORY_BUFFER 0
43 : #endif
44 :
45 : #define Z_SHELL_CMD_ROOT_LVL (0u)
46 :
47 0 : #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 1 : #define SHELL_OPT_ARG_RAW (0xFE)
61 :
62 : /**
63 : * @brief Flag indicating that number of optional arguments is not limited.
64 : */
65 1 : #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 1 : #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 1 : typedef void (*shell_dynamic_get)(size_t idx,
96 : struct shell_static_entry *entry);
97 :
98 : /**
99 : * @brief Shell command descriptor.
100 : */
101 1 : union shell_cmd_entry {
102 : /** Pointer to function returning dynamic commands.*/
103 1 : shell_dynamic_get dynamic_get;
104 :
105 : /** Pointer to array of static commands. */
106 1 : const struct shell_static_entry *entry;
107 : };
108 :
109 : struct shell;
110 :
111 0 : struct shell_static_args {
112 1 : uint8_t mandatory; /*!< Number of mandatory arguments. */
113 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 0 : struct shell_static_entry {
229 1 : const char *syntax; /*!< Command syntax strings. */
230 1 : const char *help; /*!< Command help string. */
231 1 : const union shell_cmd_entry *subcmd; /*!< Pointer to subcommand. */
232 1 : shell_cmd_handler handler; /*!< Command handler. */
233 1 : struct shell_static_args args; /*!< Command arguments. */
234 0 : 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 1 : 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 1 : 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 1 : #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 1 : #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 1 : #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 1 : #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 1 : _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 1 : #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 1 : #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 1 : #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 1 : #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 1 : #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 1 : _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 1 : #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 1 : #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 1 : #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 0 : #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 1 : #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 0 : 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 0 : 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 0 : enum shell_transport_evt {
642 : SHELL_TRANSPORT_EVT_RX_RDY,
643 : SHELL_TRANSPORT_EVT_TX_RDY
644 : };
645 :
646 0 : typedef void (*shell_transport_handler_t)(enum shell_transport_evt evt,
647 : void *context);
648 :
649 :
650 0 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : void (*update)(const struct shell_transport *transport);
743 :
744 : };
745 :
746 0 : struct shell_transport {
747 0 : const struct shell_transport_api *api;
748 0 : void *ctx;
749 : };
750 :
751 : /**
752 : * @brief Shell statistics structure.
753 : */
754 1 : struct shell_stats {
755 1 : 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 0 : struct shell_backend_config_flags {
770 1 : uint32_t insert_mode :1; /*!< Controls insert mode for text introduction */
771 1 : uint32_t echo :1; /*!< Controls shell echo */
772 1 : uint32_t obscure :1; /*!< If echo on, print asterisk instead */
773 1 : uint32_t mode_delete :1; /*!< Operation mode of backspace key */
774 1 : uint32_t use_colors :1; /*!< Controls colored syntax */
775 1 : 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 0 : #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 0 : struct shell_backend_ctx_flags {
795 1 : uint32_t processing :1; /*!< Shell is executing process function */
796 0 : uint32_t tx_rdy :1;
797 1 : uint32_t history_exit :1; /*!< Request to exit history mode */
798 1 : uint32_t last_nl :8; /*!< Last received new line character */
799 1 : uint32_t cmd_ctx :1; /*!< Shell is executing command */
800 1 : uint32_t print_noinit :1; /*!< Print request from not initialized shell */
801 1 : uint32_t sync_mode :1; /*!< Shell in synchronous mode */
802 1 : 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 0 : union shell_backend_cfg {
812 0 : atomic_t value;
813 0 : struct shell_backend_config_flags flags;
814 : };
815 :
816 : /**
817 : * @internal @brief Union for internal shell usage.
818 : */
819 0 : union shell_backend_ctx {
820 0 : uint32_t value;
821 0 : struct shell_backend_ctx_flags flags;
822 : };
823 :
824 0 : 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 1 : 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 0 : const char *prompt;
840 : #endif
841 :
842 1 : enum shell_state state; /*!< Internal module state.*/
843 1 : enum shell_receive_state receive_state;/*!< Escape sequence indicator.*/
844 :
845 : /** Currently executed command.*/
846 1 : struct shell_static_entry active_cmd;
847 :
848 : /** New root command. If NULL shell uses default root commands. */
849 1 : const struct shell_static_entry *selected_cmd;
850 :
851 : /** VT100 color and cursor position, terminal width.*/
852 1 : 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 1 : shell_uninit_cb_t uninit_cb;
858 :
859 : /** When bypass is set, all incoming data is passed to the callback. */
860 1 : shell_bypass_cb_t bypass;
861 :
862 : /*!< Logging level for a backend. */
863 0 : 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 1 : uint16_t cmd_buff_len; /*!< Command length.*/
871 1 : uint16_t cmd_buff_pos; /*!< Command buffer cursor position.*/
872 :
873 1 : uint16_t cmd_tmp_buff_len; /*!< Command length in tmp buffer.*/
874 :
875 : /** Command input buffer.*/
876 1 : char cmd_buff[CONFIG_SHELL_CMD_BUFF_SIZE];
877 :
878 : /** Command temporary buffer.*/
879 1 : char temp_buff[CONFIG_SHELL_CMD_BUFF_SIZE];
880 :
881 : /** Printf buffer size.*/
882 1 : char printf_buff[CONFIG_SHELL_PRINTF_BUFF_SIZE];
883 :
884 0 : volatile union shell_backend_cfg cfg;
885 0 : volatile union shell_backend_ctx ctx;
886 :
887 0 : 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 1 : struct k_poll_event events[SHELL_SIGNALS];
893 :
894 0 : struct k_mutex wr_mtx;
895 0 : k_tid_t tid;
896 0 : int ret_val;
897 : };
898 :
899 0 : extern const struct log_backend_api log_backend_shell_api;
900 :
901 : /**
902 : * @brief Flags for setting shell output newline sequence.
903 : */
904 1 : 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 1 : struct shell {
913 1 : const char *default_prompt; /*!< shell default prompt. */
914 :
915 1 : const struct shell_transport *iface; /*!< Transport interface.*/
916 1 : struct shell_ctx *ctx; /*!< Internal context.*/
917 :
918 0 : struct shell_history *history;
919 :
920 0 : const enum shell_flag shell_flag;
921 :
922 0 : const struct shell_fprintf *fprintf_ctx;
923 :
924 0 : struct shell_stats *stats;
925 :
926 0 : const struct shell_log_backend *log_backend;
927 :
928 0 : LOG_INSTANCE_PTR_DECLARE(log);
929 :
930 0 : const char *name;
931 0 : struct k_thread *thread;
932 0 : 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 1 : #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 1 : 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 1 : 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 1 : 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 1 : int shell_stop(const struct shell *sh);
1034 :
1035 : /**
1036 : * @brief Terminal default text color for shell_fprintf function.
1037 : */
1038 1 : #define SHELL_NORMAL SHELL_VT100_COLOR_DEFAULT
1039 :
1040 : /**
1041 : * @brief Green text color for shell_fprintf function.
1042 : */
1043 1 : #define SHELL_INFO SHELL_VT100_COLOR_GREEN
1044 :
1045 : /**
1046 : * @brief Cyan text color for shell_fprintf function.
1047 : */
1048 1 : #define SHELL_OPTION SHELL_VT100_COLOR_CYAN
1049 :
1050 : /**
1051 : * @brief Yellow text color for shell_fprintf function.
1052 : */
1053 1 : #define SHELL_WARNING SHELL_VT100_COLOR_YELLOW
1054 :
1055 : /**
1056 : * @brief Red text color for shell_fprintf function.
1057 : */
1058 1 : #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 1 : void __printf_like(3, 4) shell_fprintf_impl(const struct shell *sh, enum shell_vt100_color color,
1072 : const char *fmt, ...);
1073 :
1074 0 : #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 1 : 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 1 : 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 1 : 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 1 : #define shell_info(_sh, _ft, ...) \
1128 : shell_fprintf_info(_sh, _ft "\n", ##__VA_ARGS__)
1129 0 : 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 1 : #define shell_print(_sh, _ft, ...) \
1141 : shell_fprintf_normal(_sh, _ft "\n", ##__VA_ARGS__)
1142 0 : 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 1 : #define shell_warn(_sh, _ft, ...) \
1154 : shell_fprintf_warn(_sh, _ft "\n", ##__VA_ARGS__)
1155 0 : 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 1 : #define shell_error(_sh, _ft, ...) \
1167 : shell_fprintf_error(_sh, _ft "\n", ##__VA_ARGS__)
1168 0 : 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 1 : 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 1 : 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 1 : void shell_help(const struct shell *sh);
1198 :
1199 : /** @brief Command's help has been printed */
1200 1 : #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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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 1 : 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__ */
|
