shell.h

Go to the documentation of this file.

/*
 * Copyright (c) 2018 Nordic Semiconductor ASA
 *
 * SPDX-License-Identifier: Apache-2.0
 */
 
#ifndef SHELL_H__
#define SHELL_H__
 
#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>
 
#if defined CONFIG_SHELL_GETOPT
#include <getopt.h>
#endif
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef CONFIG_SHELL_PROMPT_BUFF_SIZE
#define CONFIG_SHELL_PROMPT_BUFF_SIZE 0
#endif
 
#ifndef CONFIG_SHELL_CMD_BUFF_SIZE
#define CONFIG_SHELL_CMD_BUFF_SIZE 0
#endif
 
#ifndef CONFIG_SHELL_PRINTF_BUFF_SIZE
#define CONFIG_SHELL_PRINTF_BUFF_SIZE 0
#endif
 
#ifndef CONFIG_SHELL_HISTORY_BUFFER
#define CONFIG_SHELL_HISTORY_BUFFER 0
#endif
 
#define Z_SHELL_CMD_ROOT_LVL (0u)
 
#define SHELL_HEXDUMP_BYTES_IN_LINE 16
 
#define SHELL_OPT_ARG_RAW (0xFE)
 
#define SHELL_OPT_ARG_CHECK_SKIP (0xFF)
 
#define SHELL_OPT_ARG_MAX (0xFD)
 
struct shell_static_entry;
 
typedef void (*shell_dynamic_get)(size_t idx,
 struct shell_static_entry *entry);
 
union shell_cmd_entry {
 shell_dynamic_get dynamic_get;
 
 const struct shell_static_entry *entry;
};
 
struct shell;
 
struct shell_static_args {
 uint8_t mandatory; 
 uint8_t optional; 
};
 
const struct device *shell_device_lookup(size_t idx,
 const char *prefix);
 
typedef bool (*shell_device_filter_t)(const struct device *dev);
 
const struct device *shell_device_filter(size_t idx,
 shell_device_filter_t filter);
 
typedef int (*shell_cmd_handler)(const struct shell *sh,
 size_t argc, char **argv);
 
typedef int (*shell_dict_cmd_handler)(const struct shell *sh, size_t argc,
 char **argv, void *data);
 
/* When entries are added to the memory section a padding is applied for
 * native_posix_64 and x86_64 targets. Adding padding to allow handle data
 * in the memory section as array.
 */
#if (defined(CONFIG_ARCH_POSIX) && defined(CONFIG_64BIT)) || defined(CONFIG_X86_64)
#define Z_SHELL_STATIC_ENTRY_PADDING 24
#else
#define Z_SHELL_STATIC_ENTRY_PADDING 0
#endif
 
/*
 * @brief Shell static command descriptor.
 */
struct shell_static_entry {
 const char *syntax; 
 const char *help; 
 const union shell_cmd_entry *subcmd; 
 shell_cmd_handler handler; 
 struct shell_static_args args; 
 uint8_t padding[Z_SHELL_STATIC_ENTRY_PADDING];
};
 
#define SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, \
 mandatory, optional) \
 static const struct shell_static_entry UTIL_CAT(_shell_, syntax) = \
 SHELL_CMD_ARG(syntax, subcmd, help, handler, mandatory, optional); \
 static const TYPE_SECTION_ITERABLE(union shell_cmd_entry, \
 UTIL_CAT(shell_cmd_, syntax), shell_root_cmds, \
 UTIL_CAT(shell_cmd_, syntax) \
 ) = { \
 .entry = &UTIL_CAT(_shell_, syntax) \
 }
 
#define SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, \
 mandatory, optional) \
 COND_CODE_1(\
 flag, \
 (\
 SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, \
 mandatory, optional) \
 ), \
 (\
 static shell_cmd_handler dummy_##syntax##_handler __unused = \
 handler;\
 static const union shell_cmd_entry *dummy_subcmd_##syntax \
 __unused = subcmd\
 ) \
 )
#define SHELL_CMD_REGISTER(syntax, subcmd, help, handler) \
 SHELL_CMD_ARG_REGISTER(syntax, subcmd, help, handler, 0, 0)
 
#define SHELL_COND_CMD_REGISTER(flag, syntax, subcmd, help, handler) \
 SHELL_COND_CMD_ARG_REGISTER(flag, syntax, subcmd, help, handler, 0, 0)
 
#define SHELL_STATIC_SUBCMD_SET_CREATE(name, ...) \
 static const struct shell_static_entry shell_##name[] = { \
 __VA_ARGS__ \
 }; \
 static const union shell_cmd_entry name = { \
 .entry = shell_##name \
 }
 
#define Z_SHELL_UNDERSCORE(x) _##x
#define Z_SHELL_SUBCMD_NAME(...) \
 UTIL_CAT(shell_subcmds, MACRO_MAP_CAT(Z_SHELL_UNDERSCORE, __VA_ARGS__))
#define Z_SHELL_SUBCMD_SECTION_TAG(...) MACRO_MAP_CAT(Z_SHELL_UNDERSCORE, __VA_ARGS__)
#define Z_SHELL_SUBCMD_SET_SECTION_TAG(x) \
 Z_SHELL_SUBCMD_SECTION_TAG(NUM_VA_ARGS_LESS_1 x, __DEBRACKET x)
#define Z_SHELL_SUBCMD_ADD_SECTION_TAG(x, y) \
 Z_SHELL_SUBCMD_SECTION_TAG(NUM_VA_ARGS_LESS_1 x, __DEBRACKET x, y)
 
#define SHELL_SUBCMD_SET_CREATE(_name, _parent) \
 static const TYPE_SECTION_ITERABLE(struct shell_static_entry, _name, shell_subcmds, \
 Z_SHELL_SUBCMD_SET_SECTION_TAG(_parent))
 
 
#define SHELL_SUBCMD_COND_ADD(_flag, _parent, _syntax, _subcmd, _help, _handler, \
 _mand, _opt) \
 COND_CODE_1(_flag, \
 (static const TYPE_SECTION_ITERABLE(struct shell_static_entry, \
 Z_SHELL_SUBCMD_NAME(__DEBRACKET _parent, _syntax), \
 shell_subcmds, \
 Z_SHELL_SUBCMD_ADD_SECTION_TAG(_parent, _syntax)) = \
 SHELL_EXPR_CMD_ARG(1, _syntax, _subcmd, _help, \
 _handler, _mand, _opt)\
 ), \
 (static shell_cmd_handler dummy_handler_##_syntax __unused = _handler;\
 static const union shell_cmd_entry dummy_subcmd_##_syntax __unused = { \
 .entry = (const struct shell_static_entry *)_subcmd\
 } \
 ) \
 )
 
#define SHELL_SUBCMD_ADD(_parent, _syntax, _subcmd, _help, _handler, _mand, _opt) \
 SHELL_SUBCMD_COND_ADD(1, _parent, _syntax, _subcmd, _help, _handler, _mand, _opt)
 
#define SHELL_SUBCMD_SET_END {NULL}
 
#define SHELL_DYNAMIC_CMD_CREATE(name, get) \
 static const TYPE_SECTION_ITERABLE(union shell_cmd_entry, name, \
 shell_dynamic_subcmds, name) = \
 { \
 .dynamic_get = get \
 }
 
#define SHELL_CMD_ARG(syntax, subcmd, help, handler, mand, opt) \
 SHELL_EXPR_CMD_ARG(1, syntax, subcmd, help, handler, mand, opt)
 
#define SHELL_COND_CMD_ARG(flag, syntax, subcmd, help, handler, mand, opt) \
 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) \
 { \
 .syntax = (_expr) ? (const char *)STRINGIFY(_syntax) : "", \
 .help = (_expr) ? (const char *)_help : NULL, \
 .subcmd = (const union shell_cmd_entry *)((_expr) ? \
 _subcmd : NULL), \
 .handler = (shell_cmd_handler)((_expr) ? _handler : NULL), \
 .args = { .mandatory = _mand, .optional = _opt} \
 }
 
#define SHELL_CMD(_syntax, _subcmd, _help, _handler) \
 SHELL_CMD_ARG(_syntax, _subcmd, _help, _handler, 0, 0)
 
#define SHELL_COND_CMD(_flag, _syntax, _subcmd, _help, _handler) \
 SHELL_COND_CMD_ARG(_flag, _syntax, _subcmd, _help, _handler, 0, 0)
 
#define SHELL_EXPR_CMD(_expr, _syntax, _subcmd, _help, _handler) \
 SHELL_EXPR_CMD_ARG(_expr, _syntax, _subcmd, _help, _handler, 0, 0)
 
/* Internal macro used for creating handlers for dictionary commands. */
#define Z_SHELL_CMD_DICT_HANDLER_CREATE(_data, _handler) \
static int UTIL_CAT(UTIL_CAT(cmd_dict_, UTIL_CAT(_handler, _)), \
 GET_ARG_N(1, __DEBRACKET _data))( \
 const struct shell *sh, size_t argc, char **argv) \
{ \
 return _handler(sh, argc, argv, \
 (void *)GET_ARG_N(2, __DEBRACKET _data)); \
}
 
/* Internal macro used for creating dictionary commands. */
#define SHELL_CMD_DICT_CREATE(_data, _handler) \
 SHELL_CMD_ARG(GET_ARG_N(1, __DEBRACKET _data), NULL, GET_ARG_N(3, __DEBRACKET _data), \
 UTIL_CAT(UTIL_CAT(cmd_dict_, UTIL_CAT(_handler, _)), \
 GET_ARG_N(1, __DEBRACKET _data)), 1, 0)
 
#define SHELL_SUBCMD_DICT_SET_CREATE(_name, _handler, ...) \
 FOR_EACH_FIXED_ARG(Z_SHELL_CMD_DICT_HANDLER_CREATE, (), \
 _handler, __VA_ARGS__) \
 SHELL_STATIC_SUBCMD_SET_CREATE(_name, \
 FOR_EACH_FIXED_ARG(SHELL_CMD_DICT_CREATE, (,), _handler, __VA_ARGS__), \
 SHELL_SUBCMD_SET_END \
 )
 
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
};
 
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);
 
struct shell_transport;
 
struct shell_transport_api {
 int (*init)(const struct shell_transport *transport,
 const void *config,
 shell_transport_handler_t evt_handler,
 void *context);
 
 int (*uninit)(const struct shell_transport *transport);
 
 int (*enable)(const struct shell_transport *transport,
 bool blocking_tx);
 
 int (*write)(const struct shell_transport *transport,
 const void *data, size_t length, size_t *cnt);
 
 int (*read)(const struct shell_transport *transport,
 void *data, size_t length, size_t *cnt);
 
 void (*update)(const struct shell_transport *transport);
 
};
 
struct shell_transport {
 const struct shell_transport_api *api;
 void *ctx;
};
 
struct shell_stats {
 atomic_t log_lost_cnt; 
};
 
#ifdef CONFIG_SHELL_STATS
#define Z_SHELL_STATS_DEFINE(_name) static struct shell_stats _name##_stats
#define Z_SHELL_STATS_PTR(_name) (&(_name##_stats))
#else
#define Z_SHELL_STATS_DEFINE(_name)
#define Z_SHELL_STATS_PTR(_name) NULL
#endif /* CONFIG_SHELL_STATS */
 
struct shell_backend_config_flags {
 uint32_t insert_mode :1; 
 uint32_t echo :1; 
 uint32_t obscure :1; 
 uint32_t mode_delete :1; 
 uint32_t use_colors :1; 
 uint32_t use_vt100 :1; 
};
 
BUILD_ASSERT((sizeof(struct shell_backend_config_flags) == sizeof(uint32_t)),
 "Structure must fit in 4 bytes");
 
#define SHELL_DEFAULT_BACKEND_CONFIG_FLAGS \
{ \
 .insert_mode = 0, \
 .echo = 1, \
 .obscure = IS_ENABLED(CONFIG_SHELL_START_OBSCURED), \
 .mode_delete = 1, \
 .use_colors = 1, \
 .use_vt100 = 1, \
};
 
struct shell_backend_ctx_flags {
 uint32_t processing :1; 
 uint32_t tx_rdy :1;
 uint32_t history_exit :1; 
 uint32_t last_nl :8; 
 uint32_t cmd_ctx :1; 
 uint32_t print_noinit :1; 
 uint32_t sync_mode :1; 
 uint32_t handle_log :1; 
};
 
BUILD_ASSERT((sizeof(struct shell_backend_ctx_flags) == sizeof(uint32_t)),
 "Structure must fit in 4 bytes");
 
union shell_backend_cfg {
 atomic_t value;
 struct shell_backend_config_flags flags;
};
 
union shell_backend_ctx {
 uint32_t value;
 struct shell_backend_ctx_flags flags;
};
 
enum shell_signal {
 SHELL_SIGNAL_RXRDY,
 SHELL_SIGNAL_LOG_MSG,
 SHELL_SIGNAL_KILL,
 SHELL_SIGNAL_TXDONE, /* TXDONE must be last one before SHELL_SIGNALS */
 SHELL_SIGNALS
};
 
struct shell_ctx {
#if defined(CONFIG_SHELL_PROMPT_CHANGE) && CONFIG_SHELL_PROMPT_CHANGE
 char prompt[CONFIG_SHELL_PROMPT_BUFF_SIZE]; 
#else
 const char *prompt;
#endif
 
 enum shell_state state; 
 enum shell_receive_state receive_state;
 struct shell_static_entry active_cmd;
 
 const struct shell_static_entry *selected_cmd;
 
 struct shell_vt100_ctx vt100_ctx;
 
 shell_uninit_cb_t uninit_cb;
 
 shell_bypass_cb_t bypass;
 
 uint32_t log_level;
 
#if defined CONFIG_SHELL_GETOPT
 struct getopt_state getopt;
#endif
 
 uint16_t cmd_buff_len; 
 uint16_t cmd_buff_pos; 
 uint16_t cmd_tmp_buff_len; 
 char cmd_buff[CONFIG_SHELL_CMD_BUFF_SIZE];
 
 char temp_buff[CONFIG_SHELL_CMD_BUFF_SIZE];
 
 char printf_buff[CONFIG_SHELL_PRINTF_BUFF_SIZE];
 
 volatile union shell_backend_cfg cfg;
 volatile union shell_backend_ctx ctx;
 
 struct k_poll_signal signals[SHELL_SIGNALS];
 
 struct k_poll_event events[SHELL_SIGNALS];
 
 struct k_mutex wr_mtx;
 k_tid_t tid;
 int ret_val;
};
 
extern const struct log_backend_api log_backend_shell_api;
 
enum shell_flag {
 SHELL_FLAG_CRLF_DEFAULT = (1<<0), 
 SHELL_FLAG_OLF_CRLF = (1<<1) 
};
 
struct shell {
 const char *default_prompt; 
 const struct shell_transport *iface; 
 struct shell_ctx *ctx; 
 struct shell_history *history;
 
 const enum shell_flag shell_flag;
 
 const struct shell_fprintf *fprintf_ctx;
 
 struct shell_stats *stats;
 
 const struct shell_log_backend *log_backend;
 
 LOG_INSTANCE_PTR_DECLARE(log);
 
 const char *name;
 struct k_thread *thread;
 k_thread_stack_t *stack;
};
 
extern void z_shell_print_stream(const void *user_ctx, const char *data,
 size_t data_len);
#define SHELL_DEFINE(_name, _prompt, _transport_iface, \
 _log_queue_size, _log_timeout, _shell_flag) \
 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, \
 CONFIG_SHELL_PRINTF_BUFF_SIZE, \
 _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, \
 CONFIG_SHELL_PRINTF_BUFF_SIZE, \
 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) \
 .name = STRINGIFY(_name), \
 .thread = &_name##_thread, \
 .stack = _name##_stack \
 }
 
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);
 
void shell_uninit(const struct shell *sh, shell_uninit_cb_t cb);
 
int shell_start(const struct shell *sh);
 
int shell_stop(const struct shell *sh);
 
#define SHELL_NORMAL SHELL_VT100_COLOR_DEFAULT
 
#define SHELL_INFO SHELL_VT100_COLOR_GREEN
 
#define SHELL_OPTION SHELL_VT100_COLOR_CYAN
 
#define SHELL_WARNING SHELL_VT100_COLOR_YELLOW
 
#define SHELL_ERROR SHELL_VT100_COLOR_RED
 
void __printf_like(3, 4) shell_fprintf_impl(const struct shell *sh, enum shell_vt100_color color,
 const char *fmt, ...);
 
#define shell_fprintf(sh, color, fmt, ...) shell_fprintf_impl(sh, color, fmt, ##__VA_ARGS__)
 
void shell_vfprintf(const struct shell *sh, enum shell_vt100_color color,
 const char *fmt, va_list args);
 
void shell_hexdump_line(const struct shell *sh, unsigned int offset,
 const uint8_t *data, size_t len);
 
void shell_hexdump(const struct shell *sh, const uint8_t *data, size_t len);
 
#define shell_info(_sh, _ft, ...) \
 shell_fprintf(_sh, SHELL_INFO, _ft "\n", ##__VA_ARGS__)
 
#define shell_print(_sh, _ft, ...) \
 shell_fprintf(_sh, SHELL_NORMAL, _ft "\n", ##__VA_ARGS__)
 
#define shell_warn(_sh, _ft, ...) \
 shell_fprintf(_sh, SHELL_WARNING, _ft "\n", ##__VA_ARGS__)
 
#define shell_error(_sh, _ft, ...) \
 shell_fprintf(_sh, SHELL_ERROR, _ft "\n", ##__VA_ARGS__)
 
void shell_process(const struct shell *sh);
 
int shell_prompt_change(const struct shell *sh, const char *prompt);
 
void shell_help(const struct shell *sh);
 
#define SHELL_CMD_HELP_PRINTED (1)
 
int shell_execute_cmd(const struct shell *sh, const char *cmd);
 
int shell_set_root_cmd(const char *cmd);
 
void shell_set_bypass(const struct shell *sh, shell_bypass_cb_t bypass);
 
bool shell_ready(const struct shell *sh);
 
int shell_insert_mode_set(const struct shell *sh, bool val);
 
int shell_use_colors_set(const struct shell *sh, bool val);
 
int shell_use_vt100_set(const struct shell *sh, bool val);
 
int shell_echo_set(const struct shell *sh, bool val);
 
int shell_obscure_set(const struct shell *sh, bool obscure);
 
int shell_mode_delete_set(const struct shell *sh, bool val);
 
int shell_get_return_value(const struct shell *sh);
 
#ifdef __cplusplus
}
#endif
 
#ifdef CONFIG_SHELL_CUSTOM_HEADER
/* This include must always be at the end of shell.h */
#include <zephyr_custom_shell.h>
#endif
 
#endif /* SHELL_H__ */