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>
#include <zephyr/toolchain.h>
 
#if defined CONFIG_SHELL_GETOPT
#include <zephyr/sys/sys_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);

const struct device *shell_device_lookup_all(size_t idx,
                                             const char *prefix);

const struct device *shell_device_lookup_non_ready(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);

const struct device *shell_device_get_binding(const char *name);

const struct device *shell_device_get_binding_all(const char *name);

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
 * the posix architecture with 64bits builds 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];
};

struct shell_cmd_help {
        /* @cond INTERNAL_HIDDEN */
        uint32_t magic;
        /* @endcond */
        const char *description; 
        const char *usage;       
};


#define SHELL_STRUCTURED_HELP_MAGIC 0x86D20BC4


static inline bool shell_help_is_structured(const char *help)
{
        const uint32_t magic32 = SHELL_STRUCTURED_HELP_MAGIC;
        const char *magic = (const char *)&magic32;

        return help != NULL && (magic[0] == help[0]) && (magic[1] == help[1])
               && (magic[2] == help[2]) && (magic[3] == help[3]);
}
 
#if defined(CONFIG_SHELL_HELP) || defined(__DOXYGEN__)
#define SHELL_HELP(_description, _usage)                                                           \
        ((const char *)&(const struct shell_cmd_help){                                             \
                .magic = SHELL_STRUCTURED_HELP_MAGIC,                                              \
                .description = (_description),                                                     \
                .usage = (_usage),                                                                 \
        })
#else
#define SHELL_HELP(_description, _usage) NULL
#endif /* CONFIG_SHELL_HELP */

#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 {0}

#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,
                                  void *user_data);
 
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 = BIT(0),
        SHELL_SIGNAL_LOG_MSG = BIT(1),
        SHELL_SIGNAL_KILL = BIT(2),
        SHELL_SIGNAL_TXDONE = BIT(3),
};

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;

        void *bypass_user_data;

        uint32_t log_level;
 
#if defined CONFIG_SHELL_GETOPT
        struct sys_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_event signal_event;
 
        struct k_sem lock_sem;
        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 Z_SHELL_DEFINE(_name, _prompt, _transport_iface, _out_buf, _log_backend, _shell_flag)      \
        static const struct shell _name;                                                           \
        static struct shell_ctx UTIL_CAT(_name, _ctx);                                             \
        Z_SHELL_HISTORY_DEFINE(_name##_history, CONFIG_SHELL_HISTORY_BUFFER);                      \
        Z_SHELL_FPRINTF_DEFINE(_name##_fprintf, &_name, _out_buf, CONFIG_SHELL_PRINTF_BUFF_SIZE,   \
                               IS_ENABLED(CONFIG_SHELL_PRINTF_AUTOFLUSH), 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 = _log_backend,                                                       \
                LOG_INSTANCE_PTR_INIT(log, shell, _name).name =                                    \
                        STRINGIFY(_name), .thread = &_name##_thread, .stack = _name##_stack}

#define SHELL_DEFINE(_name, _prompt, _transport_iface, _log_queue_size, _log_timeout, _shell_flag) \
        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_DEFINE(_name, _prompt, _transport_iface, _name##_out_buffer,                       \
                       Z_SHELL_LOG_BACKEND_PTR(_name), _shell_flag)

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_info(_sh, _ft "\n", ##__VA_ARGS__)
void __printf_like(2, 3) shell_fprintf_info(const struct shell *sh, const char *fmt, ...);

#define shell_print(_sh, _ft, ...) \
        shell_fprintf_normal(_sh, _ft "\n", ##__VA_ARGS__)
void __printf_like(2, 3) shell_fprintf_normal(const struct shell *sh, const char *fmt, ...);

#define shell_warn(_sh, _ft, ...) \
        shell_fprintf_warn(_sh, _ft "\n", ##__VA_ARGS__)
void __printf_like(2, 3) shell_fprintf_warn(const struct shell *sh, const char *fmt, ...);

#define shell_error(_sh, _ft, ...) \
        shell_fprintf_error(_sh, _ft "\n", ##__VA_ARGS__)
void __printf_like(2, 3) shell_fprintf_error(const struct shell *sh, const char *fmt, ...);

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, void *user_data);

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__ */