Zephyr API Documentation  2.7.0-rc2
A Scalable Open Source RTOS
Shell API

Shell API. More...

Data Structures

struct  shell_cmd_entry
 Shell command descriptor. More...
 
struct  shell_static_args
 
struct  shell_static_entry
 
struct  shell_transport_api
 Unified shell transport interface. More...
 
struct  shell_transport
 
struct  shell_stats
 Shell statistics structure. More...
 
struct  shell_flags
 
union  shell_internal
 
struct  shell_ctx
 Shell instance context. More...
 
struct  shell
 Shell instance internals. More...
 

Macros

#define SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, mandatory, optional)
 Macro for defining and adding a root command (level 0) with required number of arguments. More...
 
#define SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, mandatory, optional)
 Macro for defining and adding a conditional root command (level 0) with required number of arguments. More...
 
#define SHELL_CMD_REGISTER(syntax, subcmd, help, handler)    SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, 0, 0)
 Macro for defining and adding a root command (level 0) with arguments. More...
 
#define SHELL_COND_CMD_REGISTER(flag, syntax, subcmd, help, handler)    SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, 0, 0)
 Macro for defining and adding a conditional root command (level 0) with arguments. More...
 
#define SHELL_STATIC_SUBCMD_SET_CREATE(name, ...)
 Macro for creating a subcommand set. It must be used outside of any function body. More...
 
#define SHELL_SUBCMD_SET_END   {NULL}
 Define ending subcommands set. More...
 
#define SHELL_DYNAMIC_CMD_CREATE(name, get)
 Macro for creating a dynamic entry. More...
 
#define SHELL_CMD_ARG(syntax, subcmd, help, handler, mand, opt)    SHELL_EXPR_CMD_ARG(1, syntax, subcmd, help, handler, mand, opt)
 Initializes a shell command with arguments. More...
 
#define SHELL_COND_CMD_ARG(flag, syntax, subcmd, help, handler, mand, opt)
 Initializes a conditional shell command with arguments. More...
 
#define SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, _mand, _opt)
 Initializes a conditional shell command with arguments if expression gives non-zero result at compile time. More...
 
#define SHELL_CMD(_syntax, _subcmd, _help, _handler)    SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)
 Initializes a shell command. More...
 
#define SHELL_COND_CMD(_flag, _syntax, _subcmd, _help, _handler)    SHELL_COND_CMD_ARG(_flag, _syntax, _subcmd, _help, _handler, 0, 0)
 Initializes a conditional shell command. More...
 
#define SHELL_EXPR_CMD(_expr, _syntax, _subcmd, _help, _handler)    SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, 0, 0)
 Initializes shell command if expression gives non-zero result at compile time. More...
 
#define SHELL_CMD_DICT_CREATE(_data)
 
#define SHELL_SUBCMD_DICT_SET_CREATE(_name, _handler, ...)
 Initializes shell dictionary commands. More...
 
#define SHELL_DEFINE(_name, _prompt, _transport_iface, _log_queue_size, _log_timeout, _shell_flag)
 Macro for defining a shell instance. More...
 
#define SHELL_NORMAL   SHELL_VT100_COLOR_DEFAULT
 Terminal default text color for shell_fprintf function. More...
 
#define SHELL_INFO   SHELL_VT100_COLOR_GREEN
 Green text color for shell_fprintf function. More...
 
#define SHELL_OPTION   SHELL_VT100_COLOR_CYAN
 Cyan text color for shell_fprintf function. More...
 
#define SHELL_WARNING   SHELL_VT100_COLOR_YELLOW
 Yellow text color for shell_fprintf function. More...
 
#define SHELL_ERROR   SHELL_VT100_COLOR_RED
 Red text color for shell_fprintf function. More...
 
#define shell_info(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_INFO, _ft "\n", ##__VA_ARGS__)
 Print info message to the shell. More...
 
#define shell_print(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_NORMAL, _ft "\n", ##__VA_ARGS__)
 Print normal message to the shell. More...
 
#define shell_warn(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_WARNING, _ft "\n", ##__VA_ARGS__)
 Print warning message to the shell. More...
 
#define shell_error(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_ERROR, _ft "\n", ##__VA_ARGS__)
 Print error message to the shell. More...
 
#define SHELL_CMD_HELP_PRINTED   (1)
 

Typedefs

typedef void(* shell_dynamic_get) (size_t idx, struct shell_static_entry *entry)
 Shell dynamic command descriptor. More...
 
typedef int(* shell_cmd_handler) (const struct shell *shell, size_t argc, char **argv)
 Shell command handler prototype. More...
 
typedef int(* shell_dict_cmd_handler) (const struct shell *shell, size_t argc, char **argv, void *data)
 Shell dictionary command handler prototype. More...
 
typedef void(* shell_transport_handler_t) (enum shell_transport_evt evt, void *context)
 
typedef void(* shell_uninit_cb_t) (const struct shell *shell, int res)
 
typedef void(* shell_bypass_cb_t) (const struct shell *shell, uint8_t *data, size_t len)
 Bypass callback. More...
 

Enumerations

enum  shell_receive_state { SHELL_RECEIVE_DEFAULT , SHELL_RECEIVE_ESC , SHELL_RECEIVE_ESC_SEQ , SHELL_RECEIVE_TILDE_EXP }
 
enum  shell_state {
  SHELL_STATE_UNINITIALIZED , SHELL_STATE_INITIALIZED , SHELL_STATE_ACTIVE , SHELL_STATE_PANIC_MODE_ACTIVE ,
  SHELL_STATE_PANIC_MODE_INACTIVE
}
 
enum  shell_transport_evt { SHELL_TRANSPORT_EVT_RX_RDY , SHELL_TRANSPORT_EVT_TX_RDY }
 Shell transport event. More...
 
enum  shell_signal {
  SHELL_SIGNAL_RXRDY , SHELL_SIGNAL_LOG_MSG , SHELL_SIGNAL_KILL , SHELL_SIGNAL_TXDONE ,
  SHELL_SIGNALS
}
 
enum  shell_flag { SHELL_FLAG_CRLF_DEFAULT = (1<<0) , SHELL_FLAG_OLF_CRLF = (1<<1) }
 Flags for setting shell output newline sequence. More...
 

Functions

const struct deviceshell_device_lookup (size_t idx, const char *prefix)
 Get by index a device that matches . More...
 
int shell_init (const struct shell *shell, const void *transport_config, bool use_colors, bool log_backend, uint32_t init_log_level)
 Function for initializing a transport layer and internal shell state. More...
 
void shell_uninit (const struct shell *shell, shell_uninit_cb_t cb)
 Uninitializes the transport layer and the internal shell state. More...
 
int shell_start (const struct shell *shell)
 Function for starting shell processing. More...
 
int shell_stop (const struct shell *shell)
 Function for stopping shell processing. More...
 
void shell_fprintf (const struct shell *shell, enum shell_vt100_color color, const char *fmt,...)
 printf-like function which sends formatted data stream to the shell. More...
 
void shell_vfprintf (const struct shell *shell, enum shell_vt100_color color, const char *fmt, va_list args)
 vprintf-like function which sends formatted data stream to the shell. More...
 
void shell_hexdump_line (const struct shell *shell, unsigned int offset, const uint8_t *data, size_t len)
 Print a line of data in hexadecimal format. More...
 
void shell_hexdump (const struct shell *shell, const uint8_t *data, size_t len)
 Print data in hexadecimal format. More...
 
void shell_process (const struct shell *shell)
 Process function, which should be executed when data is ready in the transport interface. To be used if shell thread is disabled. More...
 
int shell_prompt_change (const struct shell *shell, const char *prompt)
 Change displayed shell prompt. More...
 
void shell_help (const struct shell *shell)
 Prints the current command help. More...
 
int shell_execute_cmd (const struct shell *shell, const char *cmd)
 Execute command. More...
 
int shell_set_root_cmd (const char *cmd)
 Set root command for all shell instances. More...
 
void shell_set_bypass (const struct shell *shell, shell_bypass_cb_t bypass)
 Set bypass callback. More...
 
int shell_insert_mode_set (const struct shell *shell, bool val)
 Allow application to control text insert mode. Value is modified atomically and the previous value is returned. More...
 
int shell_use_colors_set (const struct shell *shell, bool val)
 Allow application to control whether terminal output uses colored syntax. Value is modified atomically and the previous value is returned. More...
 
int shell_echo_set (const struct shell *shell, bool val)
 Allow application to control whether user input is echoed back. Value is modified atomically and the previous value is returned. More...
 
int shell_obscure_set (const struct shell *shell, bool obscure)
 Allow application to control whether user input is obscured with asterisks – useful for implementing passwords. Value is modified atomically and the previous value is returned. More...
 
int shell_mode_delete_set (const struct shell *shell, bool val)
 Allow application to control whether the delete key backspaces or deletes. Value is modified atomically and the previous value is returned. More...
 

Variables

const struct log_backend_api log_backend_shell_api
 

Detailed Description

Shell API.

Macro Definition Documentation

◆ SHELL_CMD

#define SHELL_CMD (   _syntax,
  _subcmd,
  _help,
  _handler 
)     SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)

#include <include/shell/shell.h>

Initializes a shell command.

Parameters
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.

◆ SHELL_CMD_ARG

#define SHELL_CMD_ARG (   syntax,
  subcmd,
  help,
  handler,
  mand,
  opt 
)     SHELL_EXPR_CMD_ARG(1, syntax, subcmd, help, handler, mand, opt)

#include <include/shell/shell.h>

Initializes a shell command with arguments.

Note
If a command will be called with wrong number of arguments shell will print an error message and command handler will not be called.
Parameters
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.
[in]mandNumber of mandatory arguments includig command name.
[in]optNumber of optional arguments.

◆ SHELL_CMD_ARG_REGISTER

#define SHELL_CMD_ARG_REGISTER (   syntax,
  subcmd,
  help,
  handler,
  mandatory,
  optional 
)

#include <include/shell/shell.h>

Value:
static const struct shell_static_entry UTIL_CAT(_shell_, syntax) = \
SHELL_CMD_ARG(syntax, subcmd, help, handler, mandatory, optional); \
static const struct shell_cmd_entry UTIL_CAT(shell_cmd_, syntax) \
__attribute__ ((section("." \
STRINGIFY(UTIL_CAT(shell_root_cmd_, syntax))))) \
__attribute__((used)) = { \
.is_dynamic = false, \
.u = {.entry = &UTIL_CAT(_shell_, syntax)} \
}
#define STRINGIFY(s)
Definition: common.h:121
Shell command descriptor.
Definition: shell.h:94
Definition: shell.h:164
const struct shell_cmd_entry * subcmd
Definition: shell.h:167
const char * help
Definition: shell.h:166
const char * syntax
Definition: shell.h:165
static void handler(struct k_timer *timer)
Definition: main.c:19
#define UTIL_CAT(a,...)
Definition: util_internal.h:84

Macro for defining and adding a root command (level 0) with required number of arguments.

Note
Each root command shall have unique syntax. If a command will be called with wrong number of arguments shell will print an error message and command handler will not be called.
Parameters
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.
[in]mandatoryNumber of mandatory arguments includig command name.
[in]optionalNumber of optional arguments.

◆ SHELL_CMD_DICT_CREATE

#define SHELL_CMD_DICT_CREATE (   _data)

#include <include/shell/shell.h>

Value:
SHELL_CMD_ARG(GET_ARG_N(1, __DEBRACKET _data), NULL, NULL, \
UTIL_CAT(cmd_dict_, GET_ARG_N(1, __DEBRACKET _data)), 1, 0)
#define SHELL_CMD_ARG(syntax, subcmd, help, handler, mand, opt)
Initializes a shell command with arguments.
Definition: shell.h:320
#define GET_ARG_N(N,...)
Get nth argument from argument list.
Definition: util_macro.h:308

◆ SHELL_CMD_HELP_PRINTED

#define SHELL_CMD_HELP_PRINTED   (1)

◆ SHELL_CMD_REGISTER

#define SHELL_CMD_REGISTER (   syntax,
  subcmd,
  help,
  handler 
)     SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, 0, 0)

#include <include/shell/shell.h>

Macro for defining and adding a root command (level 0) with arguments.

Note
All root commands must have different name.
Parameters
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.

◆ SHELL_COND_CMD

#define SHELL_COND_CMD (   _flag,
  _syntax,
  _subcmd,
  _help,
  _handler 
)     SHELL_COND_CMD_ARG(_flag, _syntax, _subcmd, _help, _handler, 0, 0)

#include <include/shell/shell.h>

Initializes a conditional shell command.

See also
SHELL_COND_CMD_ARG.
Parameters
[in]_flagCompile time flag. Command is present only if flag exists and equals 1.
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.

◆ SHELL_COND_CMD_ARG

#define SHELL_COND_CMD_ARG (   flag,
  syntax,
  subcmd,
  help,
  handler,
  mand,
  opt 
)

#include <include/shell/shell.h>

Value:
SHELL_EXPR_CMD_ARG(IS_ENABLED(flag), syntax, subcmd, help, \
handler, mand, opt)
#define SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, _mand, _opt)
Initializes a conditional shell command with arguments if expression gives non-zero result at compile...
Definition: shell.h:365
#define IS_ENABLED(config_macro)
Check for macro definition in compiler-visible expressions.
Definition: util_macro.h:101
static uint32_t flag[3]
Definition: thread_competition.c:23

Initializes a conditional shell command with arguments.

See also
SHELL_CMD_ARG. Based on the flag, creates a valid entry or an empty command which is ignored by the shell. It is an alternative to #ifdefs around command registration and command handler. However, empty structure is present in the flash even if command is disabled (subcommands and handler are removed). Macro internally handles case if flag is not defined so flag must be provided without any wrapper, e.g.: SHELL_COND_CMD_ARG(CONFIG_FOO, ...)
Parameters
[in]flagCompile time flag. Command is present only if flag exists and equals 1.
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.
[in]mandNumber of mandatory arguments includig command name.
[in]optNumber of optional arguments.

◆ SHELL_COND_CMD_ARG_REGISTER

#define SHELL_COND_CMD_ARG_REGISTER (   flag,
  syntax,
  subcmd,
  help,
  handler,
  mandatory,
  optional 
)

#include <include/shell/shell.h>

Value:
flag, \
(\
SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, \
mandatory, optional) \
), \
(\
static shell_cmd_handler dummy_##syntax##_handler __unused = \
static const struct shell_cmd_entry *dummy_subcmd_##syntax \
__unused = subcmd\
)\
)
int(* shell_cmd_handler)(const struct shell *shell, size_t argc, char **argv)
Shell command handler prototype.
Definition: shell.h:142
#define SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, mandatory, optional)
Macro for defining and adding a root command (level 0) with required number of arguments.
Definition: shell.h:187
#define COND_CODE_1(_flag, _if_1_code, _else_code)
Insert code depending on whether _flag expands to 1 or not.
Definition: util_macro.h:156

Macro for defining and adding a conditional root command (level 0) with required number of arguments.

See also
SHELL_CMD_ARG_REGISTER for details.

Macro can be used to create a command which can be conditionally present. It is and alternative to #ifdefs around command registration and command handler. If command is disabled handler and subcommands are removed from the application.

Parameters
[in]flagCompile time flag. Command is present only if flag exists and equals 1.
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.
[in]mandatoryNumber of mandatory arguments includig command name.
[in]optionalNumber of optional arguments.

◆ SHELL_COND_CMD_REGISTER

#define SHELL_COND_CMD_REGISTER (   flag,
  syntax,
  subcmd,
  help,
  handler 
)     SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, 0, 0)

#include <include/shell/shell.h>

Macro for defining and adding a conditional root command (level 0) with arguments.

See also
SHELL_COND_CMD_ARG_REGISTER.
Parameters
[in]flagCompile time flag. Command is present only if flag exists and equals 1.
[in]syntaxCommand syntax (for example: history).
[in]subcmdPointer to a subcommands array.
[in]helpPointer to a command help string.
[in]handlerPointer to a function handler.

◆ SHELL_DEFINE

#define SHELL_DEFINE (   _name,
  _prompt,
  _transport_iface,
  _log_queue_size,
  _log_timeout,
  _shell_flag 
)

#include <include/shell/shell.h>

Value:
static const struct shell _name; \
static struct shell_ctx UTIL_CAT(_name, _ctx); \
static uint8_t _name##_out_buffer[CONFIG_SHELL_PRINTF_BUFF_SIZE]; \
Z_SHELL_LOG_BACKEND_DEFINE(_name, _name##_out_buffer, \
_log_queue_size, _log_timeout); \
Z_SHELL_HISTORY_DEFINE(_name##_history, CONFIG_SHELL_HISTORY_BUFFER); \
Z_SHELL_FPRINTF_DEFINE(_name##_fprintf, &_name, _name##_out_buffer, \
true, z_shell_print_stream); \
LOG_INSTANCE_REGISTER(shell, _name, CONFIG_SHELL_LOG_LEVEL); \
Z_SHELL_STATS_DEFINE(_name); \
static K_KERNEL_STACK_DEFINE(_name##_stack, CONFIG_SHELL_STACK_SIZE); \
static struct k_thread _name##_thread; \
static const STRUCT_SECTION_ITERABLE(shell, _name) = { \
.default_prompt = _prompt, \
.iface = _transport_iface, \
.ctx = &UTIL_CAT(_name, _ctx), \
.history = IS_ENABLED(CONFIG_SHELL_HISTORY) ? \
&_name##_history : NULL, \
.shell_flag = _shell_flag, \
.fprintf_ctx = &_name##_fprintf, \
.stats = Z_SHELL_STATS_PTR(_name), \
.log_backend = Z_SHELL_LOG_BACKEND_PTR(_name), \
LOG_INSTANCE_PTR_INIT(log, shell, _name) \
.thread_name = STRINGIFY(_name), \
.thread = &_name##_thread, \
.stack = _name##_stack \
}
#define STRUCT_SECTION_ITERABLE(struct_type, name)
Defines a new iterable section.
Definition: common.h:199
#define K_KERNEL_STACK_DEFINE(sym, size)
Define a toplevel kernel stack memory region.
Definition: thread_stack.h:216
#define CONFIG_SHELL_HISTORY_BUFFER
Definition: shell.h:36
#define CONFIG_SHELL_PRINTF_BUFF_SIZE
Definition: shell.h:32
__UINT8_TYPE__ uint8_t
Definition: stdint.h:58
Definition: thread.h:201
Shell instance context.
Definition: shell.h:656
Shell instance internals.
Definition: shell.h:720

Macro for defining a shell instance.

Parameters
[in]_nameInstance name.
[in]_promptShell default prompt string.
[in]_transport_ifacePointer to the transport interface.
[in]_log_queue_sizeLogger processing queue size.
[in]_log_timeoutLogger thread timeout in milliseconds on full log queue. If queue is full logger thread is blocked for given amount of time before log message is dropped.
[in]_shell_flagShell output newline sequence.

◆ SHELL_DYNAMIC_CMD_CREATE

#define SHELL_DYNAMIC_CMD_CREATE (   name,
  get 
)

#include <include/shell/shell.h>

Value:
static const struct shell_cmd_entry name = { \
.is_dynamic = true, \
.u = { .dynamic_get = get } \
}
bool is_dynamic
Definition: shell.h:95

Macro for creating a dynamic entry.

Parameters
[in]nameName of the dynamic entry.
[in]getPointer to the function returning dynamic commands array

◆ SHELL_ERROR

#define SHELL_ERROR   SHELL_VT100_COLOR_RED

#include <include/shell/shell.h>

Red text color for shell_fprintf function.

◆ shell_error

#define shell_error (   _sh,
  _ft,
  ... 
)     shell_fprintf(_sh, SHELL_ERROR, _ft "\n", ##__VA_ARGS__)

#include <include/shell/shell.h>

Print error message to the shell.

See shell_fprintf.

Parameters
[in]_shPointer to the shell instance.
[in]_ftFormat string.
[in]...List of parameters to print.

◆ SHELL_EXPR_CMD

#define SHELL_EXPR_CMD (   _expr,
  _syntax,
  _subcmd,
  _help,
  _handler 
)     SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, 0, 0)

#include <include/shell/shell.h>

Initializes shell command if expression gives non-zero result at compile time.

See also
SHELL_EXPR_CMD_ARG.
Parameters
[in]_exprCompile time expression. Command is present only if expression is non-zero.
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.

◆ SHELL_EXPR_CMD_ARG

#define SHELL_EXPR_CMD_ARG (   _expr,
  _syntax,
  _subcmd,
  _help,
  _handler,
  _mand,
  _opt 
)

#include <include/shell/shell.h>

Value:
{ \
.syntax = (_expr) ? (const char *)STRINGIFY(_syntax) : "", \
.help = (_expr) ? (const char *)_help : NULL, \
.subcmd = (const struct shell_cmd_entry *)((_expr) ? \
_subcmd : NULL), \
.handler = (shell_cmd_handler)((_expr) ? _handler : NULL), \
.args = { .mandatory = _mand, .optional = _opt} \
}

Initializes a conditional shell command with arguments if expression gives non-zero result at compile time.

See also
SHELL_CMD_ARG. Based on the expression, creates a valid entry or an empty command which is ignored by the shell. It should be used instead of SHELL_COND_CMD_ARG if condition is not a single configuration flag, e.g.: SHELL_EXPR_CMD_ARG(IS_ENABLED(CONFIG_FOO) && IS_ENABLED(CONFIG_FOO_SETTING_1), ...)
Parameters
[in]_exprExpression.
[in]_syntaxCommand syntax (for example: history).
[in]_subcmdPointer to a subcommands array.
[in]_helpPointer to a command help string.
[in]_handlerPointer to a function handler.
[in]_mandNumber of mandatory arguments includig command name.
[in]_optNumber of optional arguments.

◆ SHELL_INFO

#define SHELL_INFO   SHELL_VT100_COLOR_GREEN

#include <include/shell/shell.h>

Green text color for shell_fprintf function.

◆ shell_info

#define shell_info (   _sh,
  _ft,
  ... 
)     shell_fprintf(_sh, SHELL_INFO, _ft "\n", ##__VA_ARGS__)

#include <include/shell/shell.h>

Print info message to the shell.

See shell_fprintf.

Parameters
[in]_shPointer to the shell instance.
[in]_ftFormat string.
[in]...List of parameters to print.

◆ SHELL_NORMAL

#define SHELL_NORMAL   SHELL_VT100_COLOR_DEFAULT

#include <include/shell/shell.h>

Terminal default text color for shell_fprintf function.

◆ SHELL_OPTION

#define SHELL_OPTION   SHELL_VT100_COLOR_CYAN

#include <include/shell/shell.h>

Cyan text color for shell_fprintf function.

◆ shell_print

#define shell_print (   _sh,
  _ft,
  ... 
)     shell_fprintf(_sh, SHELL_NORMAL, _ft "\n", ##__VA_ARGS__)

#include <include/shell/shell.h>

Print normal message to the shell.

See shell_fprintf.

Parameters
[in]_shPointer to the shell instance.
[in]_ftFormat string.
[in]...List of parameters to print.

◆ SHELL_STATIC_SUBCMD_SET_CREATE

#define SHELL_STATIC_SUBCMD_SET_CREATE (   name,
  ... 
)

#include <include/shell/shell.h>

Value:
static const struct shell_static_entry shell_##name[] = { \
__VA_ARGS__ \
}; \
static const struct shell_cmd_entry name = { \
.is_dynamic = false, \
.u = { .entry = shell_##name } \
}

Macro for creating a subcommand set. It must be used outside of any function body.

Example usage: SHELL_STATIC_SUBCMD_SET_CREATE( foo, SHELL_CMD(abc, ...), SHELL_CMD(def, ...), SHELL_SUBCMD_SET_END )

Parameters
[in]nameName of the subcommand set.
[in]...List of commands created with SHELL_CMD_ARG or or SHELL_CMD

◆ SHELL_SUBCMD_DICT_SET_CREATE

#define SHELL_SUBCMD_DICT_SET_CREATE (   _name,
  _handler,
  ... 
)

#include <include/shell/shell.h>

Value:
FOR_EACH_FIXED_ARG(Z_SHELL_CMD_DICT_HANDLER_CREATE, (), \
_handler, __VA_ARGS__) \
SHELL_STATIC_SUBCMD_SET_CREATE(_name, \
FOR_EACH(SHELL_CMD_DICT_CREATE, (,), __VA_ARGS__), \
)
#define SHELL_SUBCMD_SET_END
Define ending subcommands set.
Definition: shell.h:293
#define SHELL_CMD_DICT_CREATE(_data)
Definition: shell.h:428
#define FOR_EACH_FIXED_ARG(F, sep, fixed_arg,...)
Call macro F on each provided argument, with an additional fixed argument as a parameter.
Definition: util_macro.h:512
FOR_EACH(SYS_INIT_CREATE,(;), PRE_KERNEL_1, PRE_KERNEL_2, POST_KERNEL)

Initializes shell dictionary commands.

This is a special kind of static commands. Dictionary commands can be used every time you want to use a pair: (string <-> corresponding data) in a command handler. The string is usually a verbal description of a given data. The idea is to use the string as a command syntax that can be prompted by the shell and corresponding data can be used to process the command.

Parameters
[in]_nameName of the dictionary subcommand set
[in]_handlerCommand handler common for all dictionary commands.
See also
shell_dict_cmd_handler
Parameters
[in]...Dictionary pairs: (command_syntax, value). Value will be passed to the _handler as user data.

Example usage: static int my_handler(const struct shell *shell, size_t argc, char **argv, void *data) { int val = (int)data;

shell_print(shell, "(syntax, value) : (%s, %d)", argv[0], val); return 0; }

SHELL_SUBCMD_DICT_SET_CREATE(sub_dict_cmds, my_handler, (value_0, 0), (value_1, 1), (value_2, 2), (value_3, 3) ); SHELL_CMD_REGISTER(dictionary, &sub_dict_cmds, NULL, NULL);

◆ SHELL_SUBCMD_SET_END

#define SHELL_SUBCMD_SET_END   {NULL}

#include <include/shell/shell.h>

Define ending subcommands set.

◆ shell_warn

#define shell_warn (   _sh,
  _ft,
  ... 
)     shell_fprintf(_sh, SHELL_WARNING, _ft "\n", ##__VA_ARGS__)

#include <include/shell/shell.h>

Print warning message to the shell.

See shell_fprintf.

Parameters
[in]_shPointer to the shell instance.
[in]_ftFormat string.
[in]...List of parameters to print.

◆ SHELL_WARNING

#define SHELL_WARNING   SHELL_VT100_COLOR_YELLOW

#include <include/shell/shell.h>

Yellow text color for shell_fprintf function.

Typedef Documentation

◆ shell_bypass_cb_t

typedef void(* shell_bypass_cb_t) (const struct shell *shell, uint8_t *data, size_t len)

#include <include/shell/shell.h>

Bypass callback.

Parameters
shellShell instance.
dataRaw data from transport.
lenData length.

◆ shell_cmd_handler

typedef int(* shell_cmd_handler) (const struct shell *shell, size_t argc, char **argv)

#include <include/shell/shell.h>

Shell command handler prototype.

Parameters
shellShell instance.
argcArguments count.
argvArguments.
Return values
0Successful command execution.
1Help printed and command not executed.
-EINVALArgument validation failed.
-ENOEXECCommand not executed.

◆ shell_dict_cmd_handler

typedef int(* shell_dict_cmd_handler) (const struct shell *shell, size_t argc, char **argv, void *data)

#include <include/shell/shell.h>

Shell dictionary command handler prototype.

Parameters
shellShell instance.
argcArguments count.
argvArguments.
dataPointer to the user data.
Return values
0Successful command execution.
1Help printed and command not executed.
-EINVALArgument validation failed.
-ENOEXECCommand not executed.

◆ shell_dynamic_get

typedef void(* shell_dynamic_get) (size_t idx, struct shell_static_entry *entry)

#include <include/shell/shell.h>

Shell dynamic command descriptor.

Function shall fill the received shell_static_entry structure with requested (idx) dynamic subcommand data. If there is more than one dynamic subcommand available, the function shall ensure that the returned commands: entry->syntax are sorted in alphabetical order. If idx exceeds the available dynamic subcommands, the function must write to entry->syntax NULL value. This will indicate to the shell module that there are no more dynamic commands to read.

◆ shell_transport_handler_t

typedef void(* shell_transport_handler_t) (enum shell_transport_evt evt, void *context)

◆ shell_uninit_cb_t

typedef void(* shell_uninit_cb_t) (const struct shell *shell, int res)

Enumeration Type Documentation

◆ shell_flag

enum shell_flag

#include <include/shell/shell.h>

Flags for setting shell output newline sequence.

Enumerator
SHELL_FLAG_CRLF_DEFAULT 
SHELL_FLAG_OLF_CRLF 

◆ shell_receive_state

#include <include/shell/shell.h>

Enumerator
SHELL_RECEIVE_DEFAULT 
SHELL_RECEIVE_ESC 
SHELL_RECEIVE_ESC_SEQ 
SHELL_RECEIVE_TILDE_EXP 

◆ shell_signal

#include <include/shell/shell.h>

Enumerator
SHELL_SIGNAL_RXRDY 
SHELL_SIGNAL_LOG_MSG 
SHELL_SIGNAL_KILL 
SHELL_SIGNAL_TXDONE 
SHELL_SIGNALS 

◆ shell_state

#include <include/shell/shell.h>

Enumerator
SHELL_STATE_UNINITIALIZED 
SHELL_STATE_INITIALIZED 
SHELL_STATE_ACTIVE 
SHELL_STATE_PANIC_MODE_ACTIVE 

Panic activated.

SHELL_STATE_PANIC_MODE_INACTIVE 

Panic requested, not supported.

◆ shell_transport_evt

#include <include/shell/shell.h>

Shell transport event.

Enumerator
SHELL_TRANSPORT_EVT_RX_RDY 
SHELL_TRANSPORT_EVT_TX_RDY 

Function Documentation

◆ shell_device_lookup()

const struct device * shell_device_lookup ( size_t  idx,
const char *  prefix 
)

#include <include/shell/shell.h>

Get by index a device that matches .

This can be used, for example, to identify I2C_1 as the second I2C device.

Devices that failed to initialize or do not have a non-empty name are excluded from the candidates for a match.

Parameters
idxthe device number starting from zero.
prefixoptional name prefix used to restrict candidate devices. Indexing is done relative to devices with names that start with this text. Pass null if no prefix match is required.

◆ shell_echo_set()

int shell_echo_set ( const struct shell shell,
bool  val 
)

#include <include/shell/shell.h>

Allow application to control whether user input is echoed back. Value is modified atomically and the previous value is returned.

Parameters
[in]shellPointer to the shell instance.
[in]valEcho mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_execute_cmd()

int shell_execute_cmd ( const struct shell shell,
const char *  cmd 
)

#include <include/shell/shell.h>

Execute command.

Pass command line to shell to execute.

Note: This by no means makes any of the commands a stable interface, so this function should only be used for debugging/diagnostic.

This function must not be called from shell command context!

Parameters
[in]shellPointer to the shell instance. It can be NULL when the
embed:rst:inline :kconfig:`CONFIG_SHELL_BACKEND_DUMMY` 
option is enabled.
[in]cmdCommand to be executed.
Returns
Result of the execution

◆ shell_fprintf()

void shell_fprintf ( const struct shell shell,
enum shell_vt100_color  color,
const char *  fmt,
  ... 
)

#include <include/shell/shell.h>

printf-like function which sends formatted data stream to the shell.

This function can be used from the command handler or from threads, but not from an interrupt context.

Parameters
[in]shellPointer to the shell instance.
[in]colorPrinted text color.
[in]fmtFormat string.
[in]...List of parameters to print.

◆ shell_help()

void shell_help ( const struct shell shell)

#include <include/shell/shell.h>

Prints the current command help.

Function will print a help string with: the currently entered command and subcommands (if they exist).

Parameters
[in]shellPointer to the shell instance.

◆ shell_hexdump()

void shell_hexdump ( const struct shell shell,
const uint8_t data,
size_t  len 
)

#include <include/shell/shell.h>

Print data in hexadecimal format.

Parameters
[in]shellPointer to the shell instance.
[in]dataPointer to data.
[in]lenLength of data.

◆ shell_hexdump_line()

void shell_hexdump_line ( const struct shell shell,
unsigned int  offset,
const uint8_t data,
size_t  len 
)

#include <include/shell/shell.h>

Print a line of data in hexadecimal format.

Each line shows the offset, bytes and then ASCII representation.

For example:

00008010: 20 25 00 20 2f 48 00 08 80 05 00 20 af 46 00 | %. /H.. ... .F. |

Parameters
[in]shellPointer to the shell instance.
[in]offsetOffset to show for this line.
[in]dataPointer to data.
[in]lenLength of data.

◆ shell_init()

int shell_init ( const struct shell shell,
const void transport_config,
bool  use_colors,
bool  log_backend,
uint32_t  init_log_level 
)

#include <include/shell/shell.h>

Function for initializing a transport layer and internal shell state.

Parameters
[in]shellPointer to shell instance.
[in]transport_configTransport configuration during initialization.
[in]use_colorsEnables colored prints.
[in]log_backendIf true, the console will be used as logger backend.
[in]init_log_levelDefault severity level for the logger.
Returns
Standard error code.

◆ shell_insert_mode_set()

int shell_insert_mode_set ( const struct shell shell,
bool  val 
)

#include <include/shell/shell.h>

Allow application to control text insert mode. Value is modified atomically and the previous value is returned.

Parameters
[in]shellPointer to the shell instance.
[in]valInsert mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_mode_delete_set()

int shell_mode_delete_set ( const struct shell shell,
bool  val 
)

#include <include/shell/shell.h>

Allow application to control whether the delete key backspaces or deletes. Value is modified atomically and the previous value is returned.

Parameters
[in]shellPointer to the shell instance.
[in]valDelete mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_obscure_set()

int shell_obscure_set ( const struct shell shell,
bool  obscure 
)

#include <include/shell/shell.h>

Allow application to control whether user input is obscured with asterisks – useful for implementing passwords. Value is modified atomically and the previous value is returned.

Parameters
[in]shellPointer to the shell instance.
[in]obscureObscure mode.
Return values
0or 1: previous value.
-EINVALif shell is NULL.

◆ shell_process()

void shell_process ( const struct shell shell)

#include <include/shell/shell.h>

Process function, which should be executed when data is ready in the transport interface. To be used if shell thread is disabled.

Parameters
[in]shellPointer to the shell instance.

◆ shell_prompt_change()

int shell_prompt_change ( const struct shell shell,
const char *  prompt 
)

#include <include/shell/shell.h>

Change displayed shell prompt.

Parameters
[in]shellPointer to the shell instance.
[in]promptNew shell prompt.
Returns
0 Success.
-EINVAL Pointer to new prompt is not correct.

◆ shell_set_bypass()

void shell_set_bypass ( const struct shell shell,
shell_bypass_cb_t  bypass 
)

#include <include/shell/shell.h>

Set bypass callback.

Bypass callback is called whenever data is received. Shell is bypassed and data is passed directly to the callback. Use null to disable bypass functionality.

Parameters
[in]shellPointer to the shell instance.
[in]bypassBypass callback or null to disable.

◆ shell_set_root_cmd()

int shell_set_root_cmd ( const char *  cmd)

#include <include/shell/shell.h>

Set root command for all shell instances.

It allows setting from the code the root command. It is an equivalent of calling select command with one of the root commands as the argument (e.g "select log") except it sets command for all shell instances.

Parameters
cmdString with one of the root commands or null pointer to reset.
Return values
0if root command is set.
-EINVALif invalid root command is provided.

◆ shell_start()

int shell_start ( const struct shell shell)

#include <include/shell/shell.h>

Function for starting shell processing.

Parameters
shellPointer to the shell instance.
Returns
Standard error code.

◆ shell_stop()

int shell_stop ( const struct shell shell)

#include <include/shell/shell.h>

Function for stopping shell processing.

Parameters
shellPointer to shell instance.
Returns
Standard error code.

◆ shell_uninit()

void shell_uninit ( const struct shell shell,
shell_uninit_cb_t  cb 
)

#include <include/shell/shell.h>

Uninitializes the transport layer and the internal shell state.

Parameters
shellPointer to shell instance.
cbCallback called when uninitialization is completed.
Returns
Standard error code.

◆ shell_use_colors_set()

int shell_use_colors_set ( const struct shell shell,
bool  val 
)

#include <include/shell/shell.h>

Allow application to control whether terminal output uses colored syntax. Value is modified atomically and the previous value is returned.

Parameters
[in]shellPointer to the shell instance.
[in]valColor mode.
Return values
0or 1: previous value
-EINVALif shell is NULL.

◆ shell_vfprintf()

void shell_vfprintf ( const struct shell shell,
enum shell_vt100_color  color,
const char *  fmt,
va_list  args 
)

#include <include/shell/shell.h>

vprintf-like function which sends formatted data stream to the shell.

This function can be used from the command handler or from threads, but not from an interrupt context. It is similar to shell_fprintf() but takes a va_list instead of variable arguments.

Parameters
[in]shellPointer to the shell instance.
[in]colorPrinted text color.
[in]fmtFormat string.
[in]argsList of parameters to print.

Variable Documentation

◆ log_backend_shell_api

const struct log_backend_api log_backend_shell_api
extern