diff --git a/rt-thread-version/rt-thread-standard/programming-manual/finsh/finsh.md b/rt-thread-version/rt-thread-standard/programming-manual/finsh/finsh.md index 4a2d95ce889f4bbaed2eab9f0cd3469805c362ca..3babef77cad151697ea017baba2c11753a0bdd4f 100644 --- a/rt-thread-version/rt-thread-standard/programming-manual/finsh/finsh.md +++ b/rt-thread-version/rt-thread-standard/programming-manual/finsh/finsh.md @@ -29,11 +29,7 @@ FinSH 支持自动补全、查看历史命令等功能，通过键盘上的按 | 退格键 | 删除符 | | ←→键 | 向左或向右移动标 | -FinSH 支持两种输入模式，分别是传统命令行模式和 C 语言解释器模式。 - -### 传统命令行模式 - -此模式又称为 msh(module shell)，msh 模式下，FinSH 与传统 shell（dos/bash）执行方式一致，例如，可以通过 `cd /` 命令将目录切换至根目录。 +FinSH 支持命令行模式，此模式又称为 msh(module shell)，msh 模式下，FinSH 与传统 shell（dos/bash）执行方式一致，例如，可以通过 `cd /` 命令将目录切换至根目录。 msh 通过解析，将输入字符分解成以空格区分开的命令和参数。其命令执行格式如下所示： @@ -41,55 +37,63 @@ msh 通过解析，将输入字符分解成以空格区分开的命令和参数 其中 command 既可以是 RT-Thread 内置的命令，也可以是可执行的文件。 -### C 语言解释器模式 - -此模式又称为 C-Style 模式。C 语言解释器模式下，FinSH 能够解析执行大部分 C 语言的表达式，并使用类似 C 语言的函数调用方式访问系统中的函数及全局变量，此外它也能够通过命令行方式创建变量。在该模式下，输入的命令必须类似 C 语言中的函数调用方式，即必须携带 () 符号，例如，要输出系统当前所有线程及其状态，在 FinSH 中输入 `list_thread()` 即可打印出需要的信息。FinSH 命令的输出为此函数的返回值。对于一些不存在返回值的函数（void 返回值），这个打印输出没有意义。 - -最初 FinSH 仅支持 C-Style 模式，后来随着 RT-Thread 的不断发展，C-Style 模式在运行脚本或者程序时不太方便，而使用传统的 shell 方式则比较方便。另外，C-Style 模式下，FinSH 占用体积比较大。出于这些考虑，在 RT-Thread 中增加了 msh 模式，msh 模式体积小，使用方便，推荐大家使用 msh 模式。 - -如果在 RT-Thread 中同时使能了这两种模式，那它们可以动态切换，在 msh 模式下输入 exit 后回车，即可切换到 C-Style 模式。在 C-Style 模式输入 msh() 后回车，即可进入 msh 模式。两种模式的命令不通用，msh 命令无法在 C-Style 模式下使用，反之同理。 ## FinSH 内置命令 -在 RT-Thread 中默认内置了一些 FinSH 命令，在 FinSH 中输入 help 后回车或者直接按下 Tab 键，就可以打印当前系统支持的所有命令。C-Style 和 msh 模式下的内置命令基本一致，这里就以 msh 为例。 +在 RT-Thread 中默认内置了一些 FinSH 命令，在 FinSH 中输入 help 后回车或者直接按下 Tab 键，就可以打印当前系统支持的所有命令。 msh 模式下，按下 Tab 键后可以列出当前支持的所有命令。默认命令的数量不是固定的，RT-Thread 的各个组件会向 FinSH 输出一些命令。例如，当打开 DFS 组件时，就会把 ls，cp，cd 等命令加到 FinSH 中，方便开发者调试。 以下为按下 Tab 键后打印出来的当前支持的所有显示 RT-Thread 内核状态信息的命令，左边是命令名称，右边是关于命令的描述： ```c +msh /> RT-Thread shell commands: -version - show RT-Thread version information -list_thread - list thread -list_sem - list semaphore in system -list_event - list event in system -list_mutex - list mutex in system -list_mailbox - list mail box in system -list_msgqueue - list message queue in system -list_timer - list timer in system -list_device - list device in system -exit - return to RT-Thread shell mode. -help - RT-Thread shell help. -ps - List threads in the system. -time - Execute command with time. -free - Show the memory usage in the system. +pin - pin [option] +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 命令来列出系统中的所有线程信息，包括线程优先级、状态、栈的最大使用量等。 +使用 ps 或者 list thread 命令来列出系统中的所有线程信息，包括线程优先级、状态、栈的最大使用量等。 ```c -msh />list_thread +msh />list thread thread pri status sp stack size max used left tick error -------- --- ------- ---------- ---------- ------ ---------- --- -tshell 20 ready 0x00000118 0x00001000 29% 0x00000009 000 -tidle 31 ready 0x0000005c 0x00000200 28% 0x00000005 000 -timer 4 suspend 0x00000078 0x00000400 11% 0x00000009 000 +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 返回字段的描述: +list thread 返回字段的描述: |**字段** |**描述** | |------------|----------------------------| @@ -104,17 +108,22 @@ list_thread 返回字段的描述: ### 显示信号量状态 -使用 list_sem 命令来显示系统中所有信号量信息，包括信号量的名称、信号量的值和等待这个信号量的线程数目。 +使用 list sem 命令来显示系统中所有信号量信息，包括信号量的名称、信号量的值和等待这个信号量的线程数目。 ```c -msh />list_sem -semaphore v suspend thread +msh />list sem +semaphor v suspend thread -------- --- -------------- shrx 000 0 -e0 000 0 +sem_sd0 001 0 +psem 001 0 +pmq 001 0 +wqueue 000 0 +sd_ack 000 0 +wqueue 000 0 ``` -list_sem 返回字段的描述: +list sem 返回字段的描述: |**字段** |**描述** | |----------------|--------------------------| @@ -124,15 +133,15 @@ list_sem 返回字段的描述: ### 显示事件状态 -使用 list_event 命令来显示系统中所有的事件信息，包括事件名称、事件的值和等待这个事件的线程数目。 +使用 list event 命令来显示系统中所有的事件信息，包括事件名称、事件的值和等待这个事件的线程数目。 ```c -msh />list_event +msh />list event event set suspend thread ----- ---------- -------------- ``` -list_event 返回字段的描述: +list event 返回字段的描述: |**字段** |**描述** | |----------------|----------------------------------| @@ -142,17 +151,21 @@ list_event 返回字段的描述: ### 显示互斥量状态 -使用 list_mutex 命令来显示系统中所有的互斥量信息，包括互斥量名称、互斥量的所有者和所有者在互斥量上持有的嵌套次数等。 +使用 list mutex 命令来显示系统中所有的互斥量信息，包括互斥量名称、互斥量的所有者和所有者在互斥量上持有的嵌套次数等。 ```c -msh />list_mutex -mutex owner hold suspend thread --------- -------- ---- -------------- -fat0 (NULL) 0000 0 -sal_lock (NULL) 0000 0 +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 返回字段的描述: +list mutex 返回字段的描述: |**字段** |**描述** | |----------------|------------------------------------| @@ -160,39 +173,40 @@ list_mutex 返回字段的描述: | owner | 当前持有互斥量的线程 | | hold | 持有者在这个互斥量上嵌套持有的次数 | | suspend thread | 等待这个互斥量的线程数目 | +| priority | 持有线程的优先级 | ### 显示邮箱状态 -使用 list_mailbox 命令显示系统中所有的邮箱信息，包括邮箱名称、邮箱中邮件的数目和邮箱能容纳邮件的最大数目等。 +使用 list mailbox 命令显示系统中所有的邮箱信息，包括邮箱名称、邮箱中邮件的数目和邮箱能容纳邮件的最大数目等。 ```c -msh />list_mailbox +msh />list mailbox mailbox entry size suspend thread -------- ---- ---- -------------- -etxmb 0000 0008 1:etx -erxmb 0000 0008 1:erx +mmcsdhot 0001 0004 0 +mmcsdmb 0000 0004 1:mmcsd_de ``` -list_mailbox 返回字段的描述: +list mailbox 返回字段的描述: |**字段** |**描述** | |----------------|----------------------------| | mailbox | 邮箱的名称 | | entry | 邮箱中包含的邮件数目 | | size | 邮箱能够容纳的最大邮件数目 | -| suspend thread | 等待这个邮箱的线程数目 | +| suspend thread | 等待这个邮箱的线程数目 | ### 显示消息队列状态 -使用 list_msgqueue 命令来显示系统中所有的消息队列信息，包括消息队列的名称、包含的消息数目和等待这个消息队列的线程数目。 +使用 list msgqueue 命令来显示系统中所有的消息队列信息，包括消息队列的名称、包含的消息数目和等待这个消息队列的线程数目。 ```c -msh />list_msgqueue +msh />list msgqueue msgqueue entry suspend thread -------- ---- -------------- ``` -list_msgqueue 返回字段的描述: +list msgqueue 返回字段的描述: |**字段** |**描述** | |----------------|----------------------------| @@ -202,16 +216,16 @@ list_msgqueue 返回字段的描述: ### 显示内存池状态 -使用 list_mempool 命令来显示系统中所有的内存池信息，包括内存池的名称、内存池的大小和最大使用的内存大小等。 +使用 list mempool 命令来显示系统中所有的内存池信息，包括内存池的名称、内存池的大小和最大使用的内存大小等。 ```c -msh />list_mempool +msh />list mempool mempool block total free suspend thread ------- ---- ---- ---- -------------- signal 0012 0032 0032 0 ``` -list_mempool 返回字段的描述: +list mempool 返回字段的描述: |**字段** |**描述** | |----------------|--------------------| @@ -223,39 +237,50 @@ list_mempool 返回字段的描述: ### 显示定时器状态 -使用 list_timer 命令来显示系统中所有的定时器信息，包括定时器的名称、是否是周期性定时器和定时器超时的节拍数等。 +使用 list timer 命令来显示系统中所有的定时器信息，包括定时器的名称、是否是周期性定时器和定时器超时的节拍数等。 ```c -msh />list_timer -timer periodic timeout flag --------- ---------- ---------- ----------- -tshell 0x00000000 0x00000000 deactivated -tidle 0x00000000 0x00000000 deactivated -timer 0x00000000 0x00000000 deactivated +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 返回字段的描述: +list timer 返回字段的描述: |**字段**|**描述** | |----------|--------------------------------| | timer | 定时器的名称 | | periodic | 定时器是否是周期性的 | | timeout | 定时器超时时的节拍数 | -| flag | 定时器的状态，activated 表示活动的，deactivated 表示不活动的 | +| activated | 定时器的状态，activated 表示活动的，deactivated 表示不活动的 | +| mode | 定时器类型，one shot 表示单次定时，periodic 表示周期定时 | + +current tick 表示当前系统的 tick 数。 ### 显示设备状态 -使用 list_device 命令来显示系统中所有的设备信息，包括设备名称、设备类型和设备被打开次数。 +使用 list device 命令来显示系统中所有的设备信息，包括设备名称、设备类型和设备被打开次数。 ```c -msh />list_device -device type ref count ------- ----------------- ---------- -e0 Network Interface 0 -uart0 Character Device 2 +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 返回字段的描述: +list device 返回字段的描述: |**字段** |**描述** | |-----------|----------------| @@ -269,9 +294,10 @@ list_device 返回字段的描述: ```c msh />free -total memory: 7669836 -used memory : 15240 -maximum allocated memory: 18520 +total : 66606976 +used : 17792 +maximum : 20000 +available: 66589184 ``` free 返回字段的描述: @@ -281,6 +307,7 @@ free 返回字段的描述: | total memory | 内存总大小 | | used memory | 已使用的内存大小 | | maximum allocated memory | 最大分配内存 | +| available | 可用内存大小 | ## 自定义 FinSH 命令 @@ -319,44 +346,6 @@ static void atcmd(int argc, char**argv) MSH_CMD_EXPORT(atcmd, atcmd sample: atcmd ); ``` -### 自定义 C-Style 命令和变量 - -将自定义命令导出到 C-Style 模式可以使用如下接口： - -`FINSH_FUNCTION_EXPORT(name, desc);` - -|**参数**|**描述** | -|----------|----------------| -| name | 要导出的命令 | -| desc | 导出命令的描述 | - -以下示例定义了一个 hello 函数，并将它导出成 C-Style 模式下的命令： - -```c -void hello(void) -{ - rt_kprintf("hello RT-Thread!\n"); -} - -FINSH_FUNCTION_EXPORT(hello , say hello to RT-Thread); -``` - -按照类似的方式，也可以导出一个变量，可以通过如下接口： - -`FINSH_VAR_EXPORT(name, type, desc);` - -|**参数**|**描述** | -|----------|----------------| -| name | 要导出的变量 | -| type | 变量的类型 | -| desc | 导出变量的描述 | - -以下示例定义了一个 dummy 变量，并将它导出成 C-Style 模式下的变量命令： - -```c -static int dummy = 0; -FINSH_VAR_EXPORT(dummy, finsh_type_int, dummy variable for finsh) -``` ### 自定义命令重命名 FinSH 的函数名字长度有一定限制，它由 finsh.h 中的宏定义 FINSH_NAME_MAX 控制，默认是 16 字节，这意味着 FinSH 命令长度不会超过 16 字节。这里有个潜在的问题：当一个函数名长度超过 FINSH_NAME_MAX 时，使用 FINSH_FUNCTION_EXPORT 导出这个函数到命令表中后，在 FinSH 符号表中看到完整的函数名，但是完整输入执行会出现 null node 错误。这是因为虽然显示了完整的函数名，但是实际上 FinSH 中却保存了前 16 字节作为命令，过多的输入会导致无法正确找到命令，这时就可以使用 FINSH_FUNCTION_EXPORT_ALIAS 来对导出的命令进行重命名。 @@ -392,7 +381,6 @@ FinSH 功能可以裁剪，宏配置选项在 rtconfig.h 文件中定义，具 | #define FINSH_USING_SYMTAB | 无 | 可以在 FinSH 中使用符号表 | 开启 | |#define FINSH_USING_DESCRIPTION | 无 | 给每个 FinSH 的符号添加一段描述 | 开启 | | #define FINSH_USING_MSH| 无 | 使能 msh 模式 | 开启 | -| #define FINSH_USING_MSH_ONLY | 无 | 只使用 msh 模式 | 开启 | | #define FINSH_ARG_MAX | 整数型 | 最大输入参数数量 | 10 | | #define FINSH_USING_AUTH | 无 | 使能权限验证 | 关闭 | | #define FINSH_DEFAULT_PASSWORD | 字符串 | 权限验证密码 | 关闭 | @@ -425,8 +413,6 @@ rtconfig.h 中的参考配置示例如下所示，可以根据实际功能需求 /* 开启 msh 功能 */ #define FINSH_USING_MSH -/* 默认使用 msh 功能 */ -#define FINSH_USING_MSH_DEFAULT /* 最大输入参数数量为 10 个 */ #define FINSH_ARG_MAX 10 ``` @@ -455,7 +441,6 @@ msh /> RT-Thread shell commands: hello - say hello to RT-Thread version - show RT-Thread version information -list_thread - list thread …… ``` @@ -507,7 +492,6 @@ RT-Thread shell commands: hello - say hello to RT-Thread atcmd - atcmd sample: atcmd version - show RT-Thread version information -list_thread - list thread …… ```