shell.h File Reference

#include <zephyr/kernel.h>
#include <zephyr/shell/shell_types.h>
#include <zephyr/shell/shell_history.h>
#include <zephyr/shell/shell_fprintf.h>
#include <zephyr/shell/shell_log_backend.h>
#include <zephyr/shell/shell_string_conv.h>
#include <zephyr/logging/log_instance.h>
#include <zephyr/logging/log.h>
#include <zephyr/sys/iterable_sections.h>
#include <zephyr/sys/util.h>

Go to the source code of this file.

Data Structures
union	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_backend_config_flags
struct	shell_backend_ctx_flags
union	shell_backend_cfg
union	shell_backend_ctx
struct	shell_ctx
	Shell instance context. More...
struct	shell
	Shell instance internals. More...

Macros
#define	CONFIG_SHELL_CMD_BUFF_SIZE   0
#define	CONFIG_SHELL_PRINTF_BUFF_SIZE   0
#define	CONFIG_SHELL_HISTORY_BUFFER   0
#define	SHELL_HEXDUMP_BYTES_IN_LINE   16
#define	SHELL_OPT_ARG_RAW   (0xFE)
	Flag indicates that optional arguments will be treated as one, unformatted argument.
#define	SHELL_OPT_ARG_CHECK_SKIP   (0xFF)
	Flag indicating that number of optional arguments is not limited.
#define	SHELL_OPT_ARG_MAX   (0xFD)
	Flag indicating maximum number of optional arguments that can be validated.
#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.
#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.
#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.
#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.
#define	SHELL_STATIC_SUBCMD_SET_CREATE(name, ...)
	Macro for creating a subcommand set.
#define	SHELL_SUBCMD_SET_CREATE(_name, _parent)
	Create set of subcommands.
#define	SHELL_SUBCMD_COND_ADD(_flag, _parent, _syntax, _subcmd, _help, _handler, _mand, _opt)
	Conditionally add command to the set of subcommands.
#define	SHELL_SUBCMD_ADD(_parent, _syntax, _subcmd, _help, _handler, _mand, _opt)    SHELL_SUBCMD_COND_ADD(1, _parent, _syntax, _subcmd, _help, _handler, _mand, _opt)
	Add command to the set of subcommands.
#define	SHELL_SUBCMD_SET_END   {NULL}
	Define ending subcommands set.
#define	SHELL_DYNAMIC_CMD_CREATE(name, get)
	Macro for creating a dynamic entry.
#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.
#define	SHELL_COND_CMD_ARG(flag, syntax, subcmd, help, handler, mand, opt)
	Initializes a conditional shell command with arguments.
#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.
#define	SHELL_CMD(_syntax, _subcmd, _help, _handler)    SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)
	Initializes a shell command.
#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.
#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.
#define	SHELL_CMD_DICT_CREATE(_data, _handler)
#define	SHELL_SUBCMD_DICT_SET_CREATE(_name, _handler, ...)
	Initializes shell dictionary commands.
#define	SHELL_DEFAULT_BACKEND_CONFIG_FLAGS
#define	SHELL_DEFINE(_name, _prompt, _transport_iface, _log_queue_size, _log_timeout, _shell_flag)
	Macro for defining a shell instance.
#define	SHELL_NORMAL   SHELL_VT100_COLOR_DEFAULT
	Terminal default text color for shell_fprintf function.
#define	SHELL_INFO   SHELL_VT100_COLOR_GREEN
	Green text color for shell_fprintf function.
#define	SHELL_OPTION   SHELL_VT100_COLOR_CYAN
	Cyan text color for shell_fprintf function.
#define	SHELL_WARNING   SHELL_VT100_COLOR_YELLOW
	Yellow text color for shell_fprintf function.
#define	SHELL_ERROR   SHELL_VT100_COLOR_RED
	Red text color for shell_fprintf function.
#define	shell_info(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_INFO, _ft "\n", ##__VA_ARGS__)
	Print info message to the shell.
#define	shell_print(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_NORMAL, _ft "\n", ##__VA_ARGS__)
	Print normal message to the shell.
#define	shell_warn(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_WARNING, _ft "\n", ##__VA_ARGS__)
	Print warning message to the shell.
#define	shell_error(_sh, _ft, ...)    shell_fprintf(_sh, SHELL_ERROR, _ft "\n", ##__VA_ARGS__)
	Print error message to the shell.
#define	SHELL_CMD_HELP_PRINTED   (1)
	Command's help has been printed.

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

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 device *	shell_device_lookup (size_t idx, const char *prefix)
	Get by index a device that matches .
int	shell_init (const struct shell *sh, const void *transport_config, struct shell_backend_config_flags cfg_flags, bool log_backend, uint32_t init_log_level)
	Function for initializing a transport layer and internal shell state.
void	shell_uninit (const struct shell *sh, shell_uninit_cb_t cb)
	Uninitializes the transport layer and the internal shell state.
int	shell_start (const struct shell *sh)
	Function for starting shell processing.
int	shell_stop (const struct shell *sh)
	Function for stopping shell processing.
void	shell_fprintf (const struct shell *sh, enum shell_vt100_color color, const char *fmt,...)
	printf-like function which sends formatted data stream to the shell.
void	shell_vfprintf (const struct shell *sh, enum shell_vt100_color color, const char *fmt, va_list args)
	vprintf-like function which sends formatted data stream to the shell.
void	shell_hexdump_line (const struct shell *sh, unsigned int offset, const uint8_t *data, size_t len)
	Print a line of data in hexadecimal format.
void	shell_hexdump (const struct shell *sh, const uint8_t *data, size_t len)
	Print data in hexadecimal format.
void	shell_process (const struct shell *sh)
	Process function, which should be executed when data is ready in the transport interface.
int	shell_prompt_change (const struct shell *sh, const char *prompt)
	Change displayed shell prompt.
void	shell_help (const struct shell *sh)
	Prints the current command help.
int	shell_execute_cmd (const struct shell *sh, const char *cmd)
	Execute command.
int	shell_set_root_cmd (const char *cmd)
	Set root command for all shell instances.
void	shell_set_bypass (const struct shell *sh, shell_bypass_cb_t bypass)
	Set bypass callback.
bool	shell_ready (const struct shell *sh)
	Get shell readiness to execute commands.
int	shell_insert_mode_set (const struct shell *sh, bool val)
	Allow application to control text insert mode.
int	shell_use_colors_set (const struct shell *sh, bool val)
	Allow application to control whether terminal output uses colored syntax.
int	shell_use_vt100_set (const struct shell *sh, bool val)
	Allow application to control whether terminal is using vt100 commands.
int	shell_echo_set (const struct shell *sh, bool val)
	Allow application to control whether user input is echoed back.
int	shell_obscure_set (const struct shell *sh, bool obscure)
	Allow application to control whether user input is obscured with asterisks – useful for implementing passwords.
int	shell_mode_delete_set (const struct shell *sh, bool val)
	Allow application to control whether the delete key backspaces or deletes.
int	shell_get_return_value (const struct shell *sh)
	Retrieve return value of most recently executed shell command.

Variables
const struct log_backend_api	log_backend_shell_api

Macro Definition Documentation

CONFIG_SHELL_CMD_BUFF_SIZE

#define CONFIG_SHELL_CMD_BUFF_SIZE   0

CONFIG_SHELL_HISTORY_BUFFER

#define CONFIG_SHELL_HISTORY_BUFFER   0

CONFIG_SHELL_PRINTF_BUFF_SIZE

#define CONFIG_SHELL_PRINTF_BUFF_SIZE   0

SHELL_HEXDUMP_BYTES_IN_LINE

#define SHELL_HEXDUMP_BYTES_IN_LINE   16

SHELL_OPT_ARG_CHECK_SKIP

#define SHELL_OPT_ARG_CHECK_SKIP   (0xFF)

Flag indicating that number of optional arguments is not limited.

SHELL_OPT_ARG_MAX

#define SHELL_OPT_ARG_MAX   (0xFD)

Flag indicating maximum number of optional arguments that can be validated.

SHELL_OPT_ARG_RAW

#define SHELL_OPT_ARG_RAW   (0xFE)

Flag indicates that optional arguments will be treated as one, unformatted argument.

By default, shell is parsing all arguments, treats all spaces as argument separators unless they are within quotation marks which are removed in that case. If command rely on unformatted argument then this flag shall be used in place of number of optional arguments in command definition to indicate that only mandatory arguments shall be parsed and remaining command string is passed as a raw string.