# 开发指导
#### 使用场景
Huawei LiteOS提供的Shell作为在线调试工具，可以通过串口工具输入输出，支持常用的基本调试功能。同时用户可以新增定制的命令，新增命令需重新编译烧录后才能执行。
#### 功能
1. Huawei LiteOS提供的Shell命令参见后面"命令参考"章节。
2. Huawei LiteOS的Shell模块为用户提供下面几个接口，接口详细信息可以查看API参考。
   
   | 功能分类 | 接口名            | 描述     |
   |:---|:---|:---|
   | 注册命令 | SHELLCMD_ENTRY | 静态注册命令 |
   | 注册命令 | osCmdReg       | 动态注册命令 |
      
   ![](https://support.huaweicloud.com/maintenance-LiteOS/public_sys-resources/note_3.0-zh-cn.png)
   静态注册命令方式一般用于注册系统常用命令，动态注册命令方式一般用于注册用户命令。
   静态注册命令有5个入参，动态注册命令有4个入参。下面除去第一个入参是静态注册独有的，剩余的四个入参两个注册命令是一致的。
   - 第一个入参：命令变量名，用于设置链接选项（build/mk/liteos_tables_ldflags.mk的LITEOS_TABLES_LDFLAGS变量）。例如变量名为ls_shellcmd，链接选项就应该设置为：LITEOS_TABLES_LDFLAGS += -uls_shellcmd。这个入参是静态注册独有的，动态注册中没有这个入参。
   
   - 第二个入参：命令类型，目前支持两种命令类型。
     - CMD_TYPE_EX：不支持标准命令参数输入，会把用户填写的命令关键字屏蔽掉。例如：输入ls /ramfs，传入给命令处理函数的参数只有/ramfs，对应于命令处理函数中的argv\[0\]，而ls命令关键字并不会被传入。
     
     - CMD_TYPE_STD：支持的标准命令参数输入，所有输入的字符都会通过命令解析后被传入。例如：输入ls /ramfs，ls和/ramfs都会被传入命令处理函数，分别对应于命令处理函数中的argv\[0\]和argv\[1\]。
      
   
   - 第三个入参：命令关键字，是命令处理函数在Shell中对应的名称。**命令关键字必须唯一**，即两个不同的命令项不能有相同的命令关键字，否则只会执行其中一个。Shell在执行用户命令时，如果存在多个命令关键字相同的命令，只会执行在"help"命令中排在最前面的那个。
   
   - 第四个入参：命令处理函数的入参最大个数。
     - 静态注册命令暂不支持设置。
     
     - 动态注册命令支持设置不超过32的入参最大个数，或者设置为XARGS（其在代码中被定义为0xffffffff）表示不限制参数个数。
      
   
   - 第五个入参：命令处理函数名，即在Shell中执行命令时被调用的函数。
     
 
#### 配置项
执行make menuconfig命令，进入Debug ---\> Enable a Debug Version ---\> Enable Shell菜单，完成Shell的配置。
| 配置项                             | 含义                  | 取值范围   | 默认值 | 依赖                                                    |
|:---|:---|:---|:---|:---|
| LOSCFG_SHELL                    | Shell功能的裁剪开关        | YES/NO | YES | LOSCFG_DEBUG_VERSION(=y) \&\& LOSCFG_DRIVERS_UART(=y) |
| LOSCFG_SHELL_CONSOLE（开源版本无该配置项） | 设置Shell直接与Console交互 | YES/NO | YES | LOSCFG_SHELL(=y)                                      |
| LOSCFG_SHELL_UART               | 设置Shell直接与uart驱动交互  | YES/NO | NO  | LOSCFG_DRIVERS_UART(=y)                               |
   
#### 新增命令开发流程
下面以注册系统命令ls为例，介绍新增Shell命令的典型开发流程。
1. 定义Shell命令处理函数。 Shell命令处理函数用于处理注册的命令。例如定义一个命令处理函数osShellCmdLs，处理ls命令，并在头文件中声明命令处理函数原型。
   ```
   int osShellCmdLs(int argc, const char **argv);
   ```
   ![](https://support.huaweicloud.com/maintenance-LiteOS/public_sys-resources/notice_3.0-zh-cn.png)
   命令处理函数的参数与C语言中main函数的参数类似，包括两个入参：
   - argc：Shell命令的参数个数。个数中是否包括命令关键字，和注册命令时的命令类型有关。
   
   - argv：为指针数组，每个元素指向一个字符串，该字符串就是执行shell命令时传入命令处理函数的参数。参数中是否包括命令关键字，和注册命令时的命令类型有关。
     
2. 注册命令。 有静态注册命令和系统运行时动态注册命令两种注册方式。
   - 静态注册ls命令：
     ```
     #include "shcmd.h"
     SHELLCMD_ENTRY(ls_shellcmd, CMD_TYPE_EX, "ls", XARGS, (CMD_CBK_FUNC)osShellCmdLs);
     ```
     
   
   - 动态注册ls命令：
     ```
     #include "shell.h"
     osCmdReg(CMD_TYPE_EX, "ls", XARGS, (CMD_CBK_FUNC)osShellCmdLs);
     ```
     
    
3. 对于静态注册命令方式，在build/mk/liteos_tables_ldflags.mk中设置链接选项（LITEOS_TABLES_LDFLAGS变量）。
4. 通过make menuconfig使能Shell，详见[配置项](https://support.huaweicloud.com/maintenance-LiteOS/zh-cn_topic_0175230296.html#ZH-CN_TOPIC_0175230296__section1161804935819)。
5. 编译烧录系统后，可以执行新增的Shell命令。
 
#### 执行Shell命令
1. 通过串口终端工具（比如xShell），连接串口。
2. 选择SERIAL协议，然后配置SERIAL：选择对应的串口号，设置波特率为115200。
3. 重启开发板，系统启动后可以在串口工具中看到"Huawei LiteOS #"的提示符。 
   ```
   Huawei LiteOS #
   ```
   这时可以输入命令，按回车键执行。
   - 按Tab键可自动联想补全，若有多个匹配项则补全共同字符，并打印多个匹配项。
   
   - 按退格键可删除一个字符，如果在UTF8格式下输入了中文字符，只能通过回退三次来删除。默认模式为英文输入。
   
   - 按方向键上下可选择历史命令。