FinSH 控制台
在计算机发展的早期，图形系统出现之前，没有鼠标，甚至没有键盘。那时候人们如何与计算机交互呢？最早期的计算机使用打孔的纸条向计算机输入命令，编写程序。后来随着计算机的不断发展，显示器、键盘成为计算机的标准配置，但此时的操作系统还不支持图形界面，计算机先驱们开发了一种软件，它接受用户输入的命令，解释之后，传递给操作系统，并将操作系统执行的结果返回给用户。这个程序像一层外壳包裹在操作系统的外面，所以它被称为 shell。
嵌入式设备通常需要将开发板与 PC 机连接起来通讯，常见连接方式包括：串口、USB、以太网、Wi-Fi 等。一个灵活的 shell 也应该支持在多种连接方式上工作。有了 shell，就像在开发者和计算机之间架起了一座沟通的桥梁，开发者能很方便的获取系统的运行情况，并通过命令控制系统的运行。特别是在调试阶段，有了 shell，开发者除了能更快的定位到问题之外，也能利用 shell 调用测试函数，改变测试函数的参数，减少代码的烧录次数，缩短项目的开发时间。
FinSH 是 RT-Thread 的命令行组件（shell），正是基于上面这些考虑而诞生的，FinSH 的发音为 [ˈfɪnʃ]。读完本章，我们会对 FinSH 的工作方式以及**如何导出自己的命令到 FinSH **有更加深入的了解。
1. FinSH 简介
FinSH 是 RT-Thread 的命令行组件，提供一套供用户在命令行调用的操作接口，主要用于调试或查看系统信息。它可以使用串口 / 以太网 / USB 等与 PC 机进行通信，硬件拓扑结构如下图所示：
用户在控制终端输入命令，控制终端通过串口、USB、网络等方式将命令传给目标设备里的 FinSH，FinSH 会读取设备输入命令，解析并自动扫描内部函数表，寻找对应函数名，执行函数后输出回应，回应通过原路返回，将结果显示在控制终端上。因此，FinSH可以执行/调用任何函数！！！
当使用串口连接设备与控制终端时，FinSH 命令的执行流程，如下图所示：
FinSH 支持权限验证功能，系统在启动后会进行权限验证，只有权限验证通过，才会开启 FinSH 功能，提升系统输入的安全性。
备注：
FinSH本身是一个内核组件的线程，该线程会解析命令，并把命令解析成特定的函数调用。
msh />list_thread
thread cpu pri status sp stack size max used left tick error
tshell 0 20 running 0x00000188 0x00001000 18% 0x00000005 000
aio N/A 16 suspend 0x0000008c 0x00000800 07% 0x0000000a 000
sys_work N/A 23 suspend 0x0000008c 0x00000800 55% 0x0000000a 000
mmcsd_de N/A 22 suspend 0x000000b8 0x00000400 46% 0x00000014 000
tcpip N/A 10 suspend 0x000000f4 0x00000400 93% 0x00000011 000
etx N/A 12 suspend 0x000000b4 0x00000400 23% 0x00000010 000
erx N/A 12 suspend 0x000000b8 0x00000400 66% 0x00000010 000
tidle1 N/A 31 ready 0x00000048 0x00000400 07% 0x00000020 000
tidle0 N/A 31 ready 0x00000064 0x00000400 21% 0x0000001b 000
timer N/A 4 suspend 0x00000080 0x00000400 21% 0x0000000a 000
msh />
FinSH 支持自动补全、查看历史命令等功能，通过键盘上的按键可以很方便的使用这些功能，FinSH 支持的按键如下表所示：
按键****功能描述Tab 键当没有输入任何字符时按下 Tab 键将会打印当前系统支持的所有命令。若已经输入部分字符时按下 Tab 键，将会查找匹配的命令，也会按照文件系统的当前目录下的文件名进行补全，并可以继续输入，多次补全↑↓键上下翻阅最近输入的历史命令退格键删除符←→键向左或向右移动标
FinSH 支持命令行模式，此模式又称为 msh(module shell)，msh 模式下，FinSH 与传统 shell（dos/bash）执行方式一致，例如，可以通过
cd /
命令将目录切换至根目录。
msh 通过解析，将输入字符分解成以空格区分开的命令和参数。其命令执行格式如下所示：
command [arg1] [arg2] [...]
其中 command 既可以是** RT-Thread 内置的命令，也可以是可执行的文件。**
2. FinSH 内置命令 - 内核代码自身提供的命令
在 RT-Thread 中默认内置了一些 FinSH 命令，在 FinSH 中输入 help 后回车或者直接按下 Tab 键，就可以打印当前系统支持的所有命令。
msh 模式下，按下 Tab 键后可以列出当前支持的所有命令。默认命令的数量不是固定的，RT-Thread 的各个组件会向 FinSH 输出一些命令。例如，当打开 DFS 组件时，就会把 ls，cp，cd 等命令加到 FinSH 中，方便开发者调试。
以下为按下 Tab 键后打印出来的当前支持的所有显示 RT-Thread 内核状态信息的命令，左边是命令名称，右边是关于命令的描述：
msh />
RT-Thread shell commands:
reboot - Reboot System
help - RT-Thread shell help.
ps - List threads in the system.
free - Show the memory usage in the system
clear - clear the terminal screen
version - show RT-Thread version information
list - list objects
msh />list
Usage: list [options]
[options]:
thread - list threads
timer - list timers
sem - list semaphores
mutex - list mutexs
event - list events
mailbox - list mailboxs
msgqueue - list message queues
memheap - list memory heaps
mempool - list memory pools
device - list devices
fd - list file descriptors
msh />
复制错误复制成功
这里列出输入常用命令后返回的字段信息，方便开发者理解返回的信息内容。
显示线程状态
使用 ps 或者 list thread 命令来列出系统中的所有线程信息，包括线程优先级、状态、栈的最大使用量等。
msh />list thread
thread pri status sp stack size max used left tick error
-------- --- ------- ---------- ---------- ------ ---------- ---
tshell 20 running 0x00000160 0x00001000 15% 0x00000003 OK
aio 128 suspend 0x00000084 0x00000800 06% 0x0000000a OK
sys work 23 suspend 0x00000084 0x00000800 06% 0x0000000a OK
tidle0 255 ready 0x0000005c 0x00001000 04% 0x00000016 OK
timer 4 suspend 0x00000078 0x00000400 11% 0x00000009 OK复制错误复制成功
list thread 返回字段的描述:
字段****描述thread线程的名称pri线程的优先级status线程当前的状态sp线程当前的栈位置stack size线程的栈大小max used线程历史中使用的最大栈位置left tick线程剩余的运行节拍数error线程的错误码
显示信号量状态
使用 list sem 命令来显示系统中所有信号量信息，包括信号量的名称、信号量的值和等待这个信号量的线程数目。
msh />list sem
semaphor v suspend thread
-------- --- --------------
shrx 000 0
sem_sd0 001 0
psem 001 0
pmq 001 0
wqueue 000 0
sd_ack 000 0
wqueue 000 0复制错误复制成功
list sem 返回字段的描述:
字段****描述semaphore信号量的名称v信号量当前的值suspend thread等待这个信号量的线程数目
显示事件状态
使用 list event 命令来显示系统中所有的事件信息，包括事件名称、事件的值和等待这个事件的线程数目。
msh />list event
event set suspend thread
----- ---------- --------------复制错误复制成功
list event 返回字段的描述:
字段****描述event事件集的名称set事件集中当前发生的事件suspend thread在这个事件集中等待事件的线程数目
显示互斥量状态
使用 list mutex 命令来显示系统中所有的互斥量信息，包括互斥量名称、互斥量的所有者和所有者在互斥量上持有的嵌套次数等。
msh />list mutex
mutex owner hold suspend thread priority
-------- -------- ---- -------------- --------
fat0 (NULL) 0000 0 255
sd_bus_l (NULL) 0000 0 255
fdlock (NULL) 0000 0 255
fslock (NULL) 0000 0 255
dfs_mgr (NULL) 0000 0 255
heap (NULL) 0000 0 255复制错误复制成功
list mutex 返回字段的描述:
字段****描述mutxe互斥量的名称owner当前持有互斥量的线程hold持有者在这个互斥量上嵌套持有的次数suspend thread等待这个互斥量的线程数目priority持有线程的优先级
显示邮箱状态
使用 list mailbox 命令显示系统中所有的邮箱信息，包括邮箱名称、邮箱中邮件的数目和邮箱能容纳邮件的最大数目等。
msh />list mailbox
mailbox entry size suspend thread
-------- ---- ---- --------------
mmcsdhot 0001 0004 0
mmcsdmb 0000 0004 1:mmcsd_de复制错误复制成功
list mailbox 返回字段的描述:
字段****描述mailbox邮箱的名称entry邮箱中包含的邮件数目size邮箱能够容纳的最大邮件数目suspend thread等待这个邮箱的线程数目
显示消息队列状态
使用 list msgqueue 命令来显示系统中所有的消息队列信息，包括消息队列的名称、包含的消息数目和等待这个消息队列的线程数目。
msh />list msgqueue
msgqueue entry suspend thread
-------- ---- --------------复制错误复制成功
list msgqueue 返回字段的描述:
字段****描述msgqueue消息队列的名称entry消息队列当前包含的消息数目suspend thread等待这个消息队列的线程数目
显示内存池状态
使用 list mempool 命令来显示系统中所有的内存池信息，包括内存池的名称、内存池的大小和最大使用的内存大小等。
msh />list mempool
mempool block total free suspend thread
------- ---- ---- ---- --------------
signal 0012 0032 0032 0复制错误复制成功
list mempool 返回字段的描述:
字段****描述mempool内存池名称block内存块大小total总内存块free空闲内存块suspend thread等待这个内存池的线程数目
显示定时器状态
使用 list timer 命令来显示系统中所有的定时器信息，包括定时器的名称、是否是周期性定时器和定时器超时的节拍数等。
msh />list timer
timer periodic timeout activated mode
-------- ---------- ---------- ----------- ---------
tshell 0x00000000 0x00000000 deactivated one shot
aio 0x00000000 0x00000000 deactivated one shot
mmcsd_de 0x00000001 0x0000000d deactivated one shot
sys work 0x00000000 0x00000000 deactivated one shot
tidle0 0x00000000 0x00000000 deactivated one shot
timer 0x00000000 0x00000000 deactivated one shot
current tick:0x00017c0d复制错误复制成功
list timer 返回字段的描述:
字段****描述timer定时器的名称periodic定时器是否是周期性的timeout定时器超时时的节拍数activated定时器的状态，activated 表示活动的，deactivated 表示不活动的mode定时器类型，one shot 表示单次定时，periodic 表示周期定时
current tick 表示当前系统的 tick 数。
显示设备状态
使用 list device 命令来显示系统中所有的设备信息，包括设备名称、设备类型和设备被打开次数。
msh />list device
device type ref count
-------- -------------------- ----------
sd Block Device 1
rtc RTC 0
zero Miscellaneous Device 0
shm Unknown 0
uart1 Character Device 0
uart0 Character Device 2复制错误复制成功
list device 返回字段的描述:
字段****描述device设备的名称type设备的类型ref count设备被打开次数
显示动态内存状态
使用 free 命令来显示系统中所有的内存信息。
msh />free
total : 66606976
used : 17792
maximum : 20000
available: 66589184复制错误复制成功
free 返回字段的描述:
字段****描述total memory内存总大小used memory已使用的内存大小maximum allocated memory最大分配内存available可用内存大小
3. 自定义 FinSH 命令 - 用户新增加的命令
除了 FinSH 自带的命令，FinSH 还也提供了多个宏接口来导出自定义命令，导出的命令可以直接在 FinSH 中执行。
自定义 msh 命令
自定义的 msh 命令，可以在 msh 模式下被运行，将一个命令导出到 msh 模式可以使用如下宏接口：
MSH_CMD_EXPORT(name, desc);
参数****描述name要导出的命令desc导出命令的描述
这个命令可以导出有参数的命令，也可以导出无参数的命令。导出无参数命令时，函数的入参为 void，示例如下：
void hello(void)
{
rt_kprintf("hello RT-Thread!\n");
}
MSH_CMD_EXPORT(hello , say hello to RT-Thread);复制错误复制成功
导出有参数的命令时，函数的入参为
int argc
和
char**argv
。argc 表示参数的个数，argv 表示命令行参数字符串指针数组指针。导出有参数命令示例如下：
static void atcmd(int argc, char**argv)
{
……
}
MSH_CMD_EXPORT(atcmd, atcmd sample: atcmd <server|client>);复制错误复制成功
自定义命令重命名
FinSH 的函数名字长度有一定限制，它由 finsh.h 中的宏定义 FINSH_NAME_MAX 控制，默认是 16 字节，这意味着 FinSH 命令长度不会超过 16 字节。这里有个潜在的问题：当一个函数名长度超过 FINSH_NAME_MAX 时，使用 FINSH_FUNCTION_EXPORT 导出这个函数到命令表中后，在 FinSH 符号表中看到完整的函数名，但是完整输入执行会出现 null node 错误。这是因为虽然显示了完整的函数名，但是实际上 FinSH 中却保存了前 16 字节作为命令，过多的输入会导致无法正确找到命令，这时就可以使用 FINSH_FUNCTION_EXPORT_ALIAS 来对导出的命令进行重命名。
FINSH_FUNCTION_EXPORT_ALIAS(name, alias, desc);
参数****描述name要导出的命令alias导出到 FinSH 时显示的名字desc导出命令的描述
在重命名的命令名字前加
__cmd_
就可以将命令导出到 msh 模式，否则，命令会被导出到 C-Style 模式。以下示例定义了一个 hello 函数，并将它重命名为 ho 后导出成 C-Style 模式下的命令。
void hello(void)
{
rt_kprintf("hello RT-Thread!\n");
}
FINSH_FUNCTION_EXPORT_ALIAS(hello , ho, say hello to RT-Thread);复制错误复制成功
4. FinSH 功能配置
FinSH 功能可以裁剪，宏配置选项在 rtconfig.h 文件中定义，具体配置项如下表所示。
宏定义取值类型描述****默认值#define RT_USING_FINSH无使能 FinSH开启#define FINSH_THREAD_NAME字符串FinSH 线程的名字**"tshell"#define FINSH_USING_HISTORY无打开历史回溯功能开启#define FINSH_HISTORY_LINES整数型能回溯的历史命令行数5**#define FINSH_USING_SYMTAB无可以在 FinSH 中使用符号表开启#define FINSH_USING_DESCRIPTION无给每个 FinSH 的符号添加一段描述开启#define FINSH_USING_MSH无使能 msh 模式开启#define FINSH_ARG_MAX整数型最大输入参数数量10#define FINSH_USING_AUTH无使能权限验证关闭#define FINSH_DEFAULT_PASSWORD字符串权限验证密码关闭
msh />list_thread
thread cpu pri status sp stack size max used left tick error
tshell 0 20 running 0x00000188 0x00001000 18% 0x00000005 000
aio N/A 16 suspend 0x0000008c 0x00000800 07% 0x0000000a 000
sys_work N/A 23 suspend 0x0000008c 0x00000800 55% 0x0000000a 000
mmcsd_de N/A 22 suspend 0x000000b8 0x00000400 46% 0x00000014 000
tcpip N/A 10 suspend 0x000000f4 0x00000400 93% 0x00000011 000
etx N/A 12 suspend 0x000000b4 0x00000400 23% 0x00000010 000
erx N/A 12 suspend 0x000000b8 0x00000400 66% 0x00000010 000
tidle1 N/A 31 ready 0x00000048 0x00000400 07% 0x00000020 000
tidle0 N/A 31 ready 0x00000064 0x00000400 21% 0x0000001b 000
timer N/A 4 suspend 0x00000080 0x00000400 21% 0x0000000a 000
msh />
在RT-Thread中，msh和FinSH都是命令行相关的组件，但它们的定位和功能有所不同。
msh是RT-Thread的一个组件，它依赖于FinSH，并为其提供了在msh模式下运行自定义命令的功能。具体来说，msh利用FinSH提供的宏接口（如MSH_CMD_EXPORT）来导出自定义命令，这些命令可以直接在msh中执行。例如，你可以编写一个函数并使用MSH_CMD_EXPORT宏将其导出为msh命令，然后在msh命令行中输入该命令来触发这个函数。
另一方面，FinSH是RT-Thread的命令行组件，它提供了一套供用户在命令行调用的操作接口，主要用于调试或查看系统信息。FinSH支持多种通信方式（如串口、以太网、USB等）与PC机进行通信，并且提供了多个宏接口来导出自定义命令。
综上所述，msh和FinSH在RT-Thread中协同工作，共同为用户提供命令行交互的功能。msh依赖于FinSH的命令行接口来执行自定义命令，而FinSH则为msh提供了导出和执行这些命令的能力。
rtconfig.h 中的参考配置示例如下所示，可以根据实际功能需求情况进行配置。
/* 开启 FinSH */
#define RT_USING_FINSH
/* 将线程名称定义为 tshell */
#define FINSH_THREAD_NAME "tshell"
/* 开启历史命令 */
#define FINSH_USING_HISTORY
/* 记录 5 行历史命令 */
#define FINSH_HISTORY_LINES 5
/* 开启使用 Tab 键 */
#define FINSH_USING_SYMTAB
/* 开启描述功能 */
#define FINSH_USING_DESCRIPTION
/* 定义 FinSH 线程优先级为 20 */
#define FINSH_THREAD_PRIORITY 20
/* 定义 FinSH 线程的栈大小为 4KB */
#define FINSH_THREAD_STACK_SIZE 4096
/* 定义命令字符长度为 80 字节 */
#define FINSH_CMD_SIZE 80
/* 开启 msh 功能 */
#define FINSH_USING_MSH
/* 最大输入参数数量为 10 个 */
#define FINSH_ARG_MAX 10复制错误复制成功
5. FinSH 应用示例
5.1 不带参数的 msh 命令示例
本小节将演示如何将一个自定义的命令导出到 msh 中，示例代码如下所示，代码中创建了 hello 函数，然后通过 MSH_CMD_EXPORT 命令即可将 hello 函数导出到 FinSH 命令列表中。
#include <rtthread.h>
void hello(void)
{
rt_kprintf("hello RT-Thread!\n");
}
MSH_CMD_EXPORT(hello , say hello to RT-Thread);复制错误复制成功
系统运行起来后，在 FinSH 控制台按 tab 键可以看到导出的命令：
msh />
RT-Thread shell commands:
**hello - say hello to RT-Thread**
version - show RT-Thread version information
……复制错误复制成功
运行 hello 命令，运行结果如下所示：
msh />hello
hello RT_Thread!
msh />复制错误复制成功
5.2 带参数的 msh 命令示例
本小节将演示如何将一个带参数的自定义的命令导出到 FinSH 中, 示例代码如下所示，代码中创建了
atcmd()
函数，然后通过 MSH_CMD_EXPORT 命令即可将
atcmd()
函数导出到 msh 命令列表中。
#include <rtthread.h>
static void atcmd(int argc, char**argv)
{
if (argc < 2)
{
rt_kprintf("Please input'atcmd <server|client>'\n");
return;
}
if (!rt_strcmp(argv[1], "server"))
{
rt_kprintf("AT server!\n");
}
else if (!rt_strcmp(argv[1], "client"))
{
rt_kprintf("AT client!\n");
}
else
{
rt_kprintf("Please input'atcmd <server|client>'\n");
}
}
MSH_CMD_EXPORT(atcmd, atcmd sample: atcmd <server|client>);复制错误复制成功
系统运行起来后，在 FinSH 控制台按 tab 键可以看到导出的命令：
msh />
RT-Thread shell commands:
hello - say hello to RT-Thread
atcmd - atcmd sample: atcmd <server|client>
version - show RT-Thread version information
……复制错误复制成功
运行 atcmd 命令，运行结果如下所示：
msh />atcmd
Please input 'atcmd <server|client>'
msh />复制错误复制成功
运行 atcmd server 命令，运行结果如下所示：
msh />atcmd server
AT server!
msh />复制错误复制成功
运行 atcmd client 命令，运行结果如下所示：
msh />atcmd client
AT client!
msh />复制错误复制成功
6. FinSH 移植
FinSH 完全采用 ANSI C 编写，具备极好的移植性；
内存占用少，如果不使用前面章节中介绍的函数方式动态地向 FinSH 添加符号，FinSH 将不会动态申请内存。FinSH 源码位于
components/finsh
目录下。移植 FinSH 需要注意以下几个方面：
- FinSH 线程：
每次的命令执行都是在 FinSH 线程（即 tshell 线程）的上下文中完成的。
当定义 RT_USING_FINSH 宏时，就可以在初始化线程中调用 finsh_system_init() 初始化 FinSH 线程。
RT-Thread 1.2.0 之后的版本中可以不使用
finsh_set_device(const char* device_name)
函数去显式指定使用的设备，而是会自动调用
rt_console_get_device()
函数去使用 console 设备（RT-Thread 1.1.x 及以下版本中必须使用
finsh_set_device(const char* device_name)
指定 FinSH 使用的设备）。FinSH 线程在函数
finsh_system_init()
函数中被创建，它将一直等待 rx_sem 信号量。
- FinSH 的输出：
FinSH 的输出依赖于系统的输出，在 RT-Thread 中依赖**
rt_kprintf()
输出**。在启动函数
rt_hw_board_init()
中，
**rt_console_set_device**(const char* name)
函数设置了 FinSH 的打印输出设备。
- FinSH 的输入：
FinSH 线程在获得了 rx_sem 信号量后，调用
rt_device_read()
函数从设备 (选用串口设备) 中获得一个字符然后处理。所以 FinSH 的移植需要
rt_device_read()
函数的实现。而 rx_sem 信号量的释放通过调用
rx_indicate()
函数以完成对 FinSH 线程的输入通知。
通常的过程是，**当串口接收中断发生时（即串口有输入），接受中断服务例程调用
rx_indicate()
函数通知 FinSH 线程有输入**，而后 FinSH 线程获取串口输入最后做相应的命令处理。如下图所示：
版权归原作者 文火冰糖的硅基工坊 所有， 如有侵权，请联系我们删除。