组件-FinSh组件

目录

1、简介

1.1、msh

1.2、FinSH 内置命令

1.2.1、常用命令

2、命令实现原理

3、配置

4、FinS功能和函数

4.1、 finsh_system_init()函数

4.2、权限验证

4.2.1、finsh_get_password()函数

4.2.2、finsh_set_password()函数

4.2.3、finsh_wait_auth()函数

4.3、prompt

4.3.1、finsh_get_prompt_mode()函数

4.3.2、finsh_set_prompt_mode()函数

4.3.3、finsh_get_prompt()函数

4.3.4、finsh_set_prompt()函数

4.4、历史记录

4.4.1、shell_handle_history()函数

4.4.2、shell_push_history()函数

---

1、简介

FinSH是RT-Thread的命令行组件，提供一套供用户在命令行调用的操作接口，主要用于调试或查看系统信息。它可以使用串口 / 以太网 / USB 等与 PC 机进行通信。

用户在控制终端输入命令，控制终端通过串口、USB、网络等方式将命令传给设备里的 FinSH，FinSH 会读取设备输入命令，解析并自动扫描内部函数表，寻找对应函数名，执行函数后输出回应，回应通过原路返回，将结果显示在控制终端上。

1.1、msh

msh(module shell)称为传统命令行模式。

msh 通过解析，将输入字符分解成以空格区分开的命令和参数。其命令执行格式如下所示：

command [arg1] [arg2] [...]

注：command既可以是RT-Thread 内置的命令，也可以是可执行的文件。

1.2、FinSH 内置命令

在 RT-Thread 中默认内置了一些 FinSH 命令，在 FinSH 中输入 help 后回车或者直接按下 Tab 键，就可以打印当前系统支持的所有命令。

注：默认命令的数量不是固定的。例如，当打开 DFS 组件时，就会把 ls，cp，cd 等命令加到 FinSH 中。

1.2.1、常用命令

version	显示版本信息
list_thread	显示线程状态
list_sem	显示信号量状态
list_event	显示事件状态
list_mutex	显示互斥量状态
list_mailbox	显示邮箱状态
list_msgqueue	显示消息队列状态
list_mempool	显示内存池状态
list_timer	显示定时器状态
list_device	显示设备状态
list	显示命令。根据不同的参数显示不同的信息
free	显示动态内存状态

2、命令实现原理

1）每个命令使用宏MSH_CMD_EXPORT定义一个finsh_syscall结构体，并将其存放到FSymTab段。__fsym_##cmd##_name和__fsym_##cmd##_desc放在在.rodata.name段。

注：FSymTab段的范围为FSymTab$$Base段至FSymTab$$Limit段。

2）调用时从FSymTab段中比较finsh_syscall结构体的name查找func，然后调用。

struct finsh_syscall
{
    const char     *name;       /* the name of system call */
#if defined(FINSH_USING_DESCRIPTION) && defined(FINSH_USING_SYMTAB)
    const char     *desc;       /* description of system call */
#endif
    syscall_func func;      /* the function address of system call */
};

#define MSH_CMD_EXPORT(command, desc)   \
    MSH_FUNCTION_EXPORT_CMD(command, command, desc)

#define MSH_FUNCTION_EXPORT_CMD(name, cmd, desc)                      \
                const char __fsym_##cmd##_name[] RT_SECTION(".rodata.name") = #cmd;    \
                const char __fsym_##cmd##_desc[] RT_SECTION(".rodata.name") = #desc;   \
                RT_USED const struct finsh_syscall __fsym_##cmd RT_SECTION("FSymTab")= \
                {                           \
                    __fsym_##cmd##_name,    \
                    __fsym_##cmd##_desc,    \
                    (syscall_func)&name     \
                };

3、配置

FINSH_THREAD_NAME	finsh线程名称
FINSH_THREAD_PRIORITY	finsh线程优先级
FINSH_THREAD_STACK_SIZE	finsh线程栈大小
MSH_USING_BUILT_IN_COMMANDS	使能finsh内置命令。 1）cmd_ps命令。显示线程信息或模块信息 2）cmd_free命令。显示动态内存状态
FINSH_CMD_SIZE	finsh命令行大小
FINSH_ARG_MAX	最大参数
FINSH_USING_HISTORY	开启历史记录
FINSH_HISTORY_LINES	finsh历史记录数量
FINSH_USING_SYMTAB	使能finsh符号表
FINSH_USING_DESCRIPTION	finsh命令描述
FINSH_ECHO_DISABLE_DEFAULT	关闭finsh的echo模式
FINSH_USING_AUTH	开启权限验证功能
FINSH_PASSWORD_MAX	密码最大长度
FINSH_PASSWORD_MIN	密码最小长度
FINSH_DEFAULT_PASSWORD	默认密码

4、FinS功能和函数

FinSH 源码位于components/finsh目录下。

FinSH 支持自动补全、查看历史命令等功能，通过键盘上的按键可以很方便的使用这些功能，FinSH 支持的按键如下表所示：

按键	功能描述
Tab 键	当没有输入任何字符时按下 Tab 键将会打印当前系统支持的所有命令。若已经输入部分字符时按下 Tab 键，将会查找匹配的命令，也会按照文件系统的当前目录下的文件名进行补全，并可以继续输入，多次补全
↑↓键	上下翻阅最近输入的历史命令
退格键	删除符
←→键	向左或向右移动标

struct finsh_shell
{
    struct rt_semaphore rx_sem;

    enum input_stat stat;

    rt_uint8_t echo_mode: 1;
    rt_uint8_t prompt_mode: 1;

#ifdef FINSH_USING_HISTORY
    rt_uint16_t current_history;
    rt_uint16_t history_count;

    char cmd_history[FINSH_HISTORY_LINES][FINSH_CMD_SIZE];
#endif

    char line[FINSH_CMD_SIZE + 1];
    rt_uint16_t line_position;
    rt_uint16_t line_curpos;

#if !defined(RT_USING_POSIX_STDIO) && defined(RT_USING_DEVICE)
    rt_device_t device;
#endif

#ifdef FINSH_USING_AUTH
    char password[FINSH_PASSWORD_MAX];
#endif
};

4.1、 finsh_system_init()函数

此函数用于创建finsh线程finsh_thread_entry。

int finsh_system_init(void)

4.2、权限验证

FinSH 支持权限验证功能，系统在启动后会进行权限验证，只有权限验证通过，才会开启 FinSH 功能，提升系统输入的安全性。

4.2.1、finsh_get_password()函数

获取验证密码。

const char *finsh_get_password(void)

4.2.2、finsh_set_password()函数

修改验证密码。

rt_err_t finsh_set_password(const char *password)

4.2.3、finsh_wait_auth()函数

此函数用于密码验证。

1）等待输入密码(以回车确认输入完成)

2）密码比较

static void finsh_wait_auth(void)

注：默认验证失败后需等待2S后，才能进行下次验证。

4.3、prompt

4.3.1、finsh_get_prompt_mode()函数

此函数用于获取是否支持prompt。

rt_uint32_t finsh_get_prompt_mode(void)

4.3.2、finsh_set_prompt_mode()函数

此函数用于设置是否支持prompt。

void finsh_set_prompt_mode(rt_uint32_t prompt_mode)

4.3.3、finsh_get_prompt()函数

此函数用于获取prompt。

const char *finsh_get_prompt(void)

注：默认prompt为"msh "

4.3.4、finsh_set_prompt()函数

此函数用于设置prompt。
 

4.4、历史记录

4.4.1、shell_handle_history()函数

输出历史记录。

static rt_bool_t shell_handle_history(struct finsh_shell *shell)

4.4.2、shell_push_history()函数

保存历史记录。

static void shell_push_history(struct finsh_shell *shell)