1# Shell Command Development Guidelines<a name="EN-US_TOPIC_0000001133846468"></a> 2 3- [Development Guidelines](#section13408945163812) 4 5## Development Guidelines<a name="section13408945163812"></a> 6 7You can perform the following operations to add shell commands: 8 91. Include the following header files: 10 11 ``` 12 #include "shell.h" 13 #include "shcmd.h" 14 ``` 15 162. Register commands. You can register commands either statically or dynamically when the system is running. In most cases, static registration is widely used by common system commands, and dynamic registration is widely used by user commands. 17 18 1. Static registration: 19 20 1. Register a command using a macro. 21 22 The prototype of the macro is as follows: 23 24 ``` 25 SHELLCMD_ENTRY(l, cmdType, cmdKey, paraNum, cmdHook) 26 ``` 27 28 **Table 1** Parameters of the SHELLCMD\_ENTRY macro 29 30 <a name="table1198543584513"></a> 31 <table><thead align="left"><tr id="row209856358456"><th class="cellrowborder" valign="top" width="20.91%" id="mcps1.2.3.1.1"><p id="p998583517456"><a name="p998583517456"></a><a name="p998583517456"></a><strong id="b1195317394217"><a name="b1195317394217"></a><a name="b1195317394217"></a>Parameter</strong></p> 32 </th> 33 <th class="cellrowborder" valign="top" width="79.09%" id="mcps1.2.3.1.2"><p id="p169851735174511"><a name="p169851735174511"></a><a name="p169851735174511"></a><strong id="b1958216251314"><a name="b1958216251314"></a><a name="b1958216251314"></a>Description</strong></p> 34 </th> 35 </tr> 36 </thead> 37 <tbody><tr id="row13985153574517"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p6985113513452"><a name="p6985113513452"></a><a name="p6985113513452"></a>l</p> 38 </td> 39 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p998573514457"><a name="p998573514457"></a><a name="p998573514457"></a>Specifies the global variable name passed in static registration. Note that the name cannot be the same as other symbol names in the system.</p> 40 </td> 41 </tr> 42 <tr id="row398513594518"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p59856356450"><a name="p59856356450"></a><a name="p59856356450"></a>cmdType</p> 43 </td> 44 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p119859355458"><a name="p119859355458"></a><a name="p119859355458"></a>Specifies the command type, which can be any of the following:</p> 45 <a name="ul11135144114816"></a><a name="ul11135144114816"></a><ul id="ul11135144114816"><li><p id="p21351144488"><a name="p21351144488"></a><a name="p21351144488"></a><strong id="b189416548121"><a name="b189416548121"></a><a name="b189416548121"></a>CMD_TYPE_EX</strong>: does not support standard command parameters and will mask the command keywords you entered. For example, if you enter <strong id="b1940315357339"><a name="b1940315357339"></a><a name="b1940315357339"></a>ls /ramfs</strong>, only <strong id="b67371541123316"><a name="b67371541123316"></a><a name="b67371541123316"></a>/ramfs</strong> will be passed to the registration function, and <strong id="b1145320313411"><a name="b1145320313411"></a><a name="b1145320313411"></a>ls</strong> will be masked.</p> 46 </li><li><p id="p21353410482"><a name="p21353410482"></a><a name="p21353410482"></a><strong id="b15922145203418"><a name="b15922145203418"></a><a name="b15922145203418"></a>CMD_TYPE_STD</strong>: supports standard command parameters. All the characters you entered will be passed to the registration function after being parsed.</p> 47 </li></ul> 48 </td> 49 </tr> 50 <tr id="row20985153524519"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p1098693510451"><a name="p1098693510451"></a><a name="p1098693510451"></a>cmdKey</p> 51 </td> 52 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p11986735144514"><a name="p11986735144514"></a><a name="p11986735144514"></a>Specifies the command keyword, which is the name used to access a shell function.</p> 53 </td> 54 </tr> 55 <tr id="row1398683511450"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p598613359451"><a name="p598613359451"></a><a name="p598613359451"></a>paraNum</p> 56 </td> 57 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p11986535144516"><a name="p11986535144516"></a><a name="p11986535144516"></a>Specifies the maximum number of input parameters in the execution function to be called. This parameter is not supported currently.</p> 58 </td> 59 </tr> 60 <tr id="row39861935154516"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p5986735114518"><a name="p5986735114518"></a><a name="p5986735114518"></a>cmdHook</p> 61 </td> 62 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p398683574515"><a name="p398683574515"></a><a name="p398683574515"></a>Specifies the address of the execution function, that is, the function executed by the command.</p> 63 </td> 64 </tr> 65 </tbody> 66 </table> 67 68 Example: 69 70 ``` 71 SHELLCMD_ENTRY(ls_shellcmd, CMD_TYPE_EX, "ls", XARGS, (CMD_CBK_FUNC)osShellCmdLs) 72 ``` 73 74 2. Add options to the **build/mk/liteos\_tables\_ldflags.mk** file. 75 76 For example, when registering the **ls** command, add **-uls\_shellcmd** to the **build/mk/liteos\_tables\_ldflags.mk** file. **-u** is followed by the first parameter of **SHELLCMD\_ENTRY**. 77 78 2. Dynamic registration: 79 80 The prototype of the function to register is as follows: 81 82 ``` 83 UINT32 osCmdReg(CmdT ype cmdType, CHAR *cmdKey, UINT32 paraNum, CmdCallBackFunc cmdProc) 84 ``` 85 86 **Table 2** Parameters of UINT32 osCmdReg 87 88 <a name="table194461933114919"></a> 89 <table><thead align="left"><tr id="row1644693318490"><th class="cellrowborder" valign="top" width="20.91%" id="mcps1.2.3.1.1"><p id="p1644618337493"><a name="p1644618337493"></a><a name="p1644618337493"></a><strong id="b414914114815"><a name="b414914114815"></a><a name="b414914114815"></a>Parameter</strong></p> 90 </th> 91 <th class="cellrowborder" valign="top" width="79.09%" id="mcps1.2.3.1.2"><p id="p444603317491"><a name="p444603317491"></a><a name="p444603317491"></a><strong id="b19862274819"><a name="b19862274819"></a><a name="b19862274819"></a>Description</strong></p> 92 </th> 93 </tr> 94 </thead> 95 <tbody><tr id="row844643374912"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p14446133319498"><a name="p14446133319498"></a><a name="p14446133319498"></a>cmdType</p> 96 </td> 97 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p174461339496"><a name="p174461339496"></a><a name="p174461339496"></a>Specifies the command type, which can be any of the following:</p> 98 <a name="ul1244773317496"></a><a name="ul1244773317496"></a><ul id="ul1244773317496"><li><p id="p1844719331495"><a name="p1844719331495"></a><a name="p1844719331495"></a><strong id="b1596594718"><a name="b1596594718"></a><a name="b1596594718"></a>CMD_TYPE_EX</strong>: does not support standard command parameters and will mask the command keywords you entered. For example, if you enter <strong id="b134411664"><a name="b134411664"></a><a name="b134411664"></a>ls /ramfs</strong>, only <strong id="b384234630"><a name="b384234630"></a><a name="b384234630"></a>/ramfs</strong> will be passed to the registration function, and <strong id="b1102747310"><a name="b1102747310"></a><a name="b1102747310"></a>ls</strong> will be masked.</p> 99 </li><li><p id="p20447143315498"><a name="p20447143315498"></a><a name="p20447143315498"></a><strong id="b97295345"><a name="b97295345"></a><a name="b97295345"></a>CMD_TYPE_STD</strong>: supports standard command parameters. All the characters you entered will be passed to the registration function after being parsed.</p> 100 </li></ul> 101 </td> 102 </tr> 103 <tr id="row14471733184915"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p744783319494"><a name="p744783319494"></a><a name="p744783319494"></a>cmdKey</p> 104 </td> 105 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p18447833124914"><a name="p18447833124914"></a><a name="p18447833124914"></a>Specifies the command keyword, which is the name used to access a shell function.</p> 106 </td> 107 </tr> 108 <tr id="row17447143317495"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p174477331495"><a name="p174477331495"></a><a name="p174477331495"></a>paraNum</p> 109 </td> 110 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p8447233184914"><a name="p8447233184914"></a><a name="p8447233184914"></a>Specifies the maximum number of input parameters in the execution function to be called. This parameter is not supported currently. The default value is <strong id="b1425195414484"><a name="b1425195414484"></a><a name="b1425195414484"></a>XARGS(0xFFFFFFFF)</strong>.</p> 111 </td> 112 </tr> 113 <tr id="row10447233174913"><td class="cellrowborder" valign="top" width="20.91%" headers="mcps1.2.3.1.1 "><p id="p18447183334920"><a name="p18447183334920"></a><a name="p18447183334920"></a>cmdHook</p> 114 </td> 115 <td class="cellrowborder" valign="top" width="79.09%" headers="mcps1.2.3.1.2 "><p id="p44471533184912"><a name="p44471533184912"></a><a name="p44471533184912"></a>Specifies the address of the execution function, that is, the function executed by the command.</p> 116 </td> 117 </tr> 118 </tbody> 119 </table> 120 121 Example: 122 123 ``` 124 osCmdReg(CMD_TYPE_EX, "ls", XARGS, (CMD_CBK_FUNC)osShellCmdLs) 125 ``` 126 127 > **NOTE:** 128 >The command keyword must be unique. That is, two different commands cannot share the same command keyword. Otherwise, only one command is executed. 129 >When executing user commands sharing the same keyword, the shell executes only the first command in the **help** commands. 130 1313. Use the following function prototype to add built-in commands: 132 133 ``` 134 UINT32 osShellCmdLs(UINT32 argc, CHAR **argv) 135 ``` 136 137 **Table 3** Parameters of osShellCmdLs 138 139 <a name="table174451958105116"></a> 140 <table><thead align="left"><tr id="row84451058105117"><th class="cellrowborder" valign="top" width="24.42%" id="mcps1.2.3.1.1"><p id="p1644515855111"><a name="p1644515855111"></a><a name="p1644515855111"></a><strong id="b710871813012"><a name="b710871813012"></a><a name="b710871813012"></a>Parameter</strong></p> 141 </th> 142 <th class="cellrowborder" valign="top" width="75.58%" id="mcps1.2.3.1.2"><p id="p18445145805113"><a name="p18445145805113"></a><a name="p18445145805113"></a><strong id="b12608195015"><a name="b12608195015"></a><a name="b12608195015"></a>Description</strong></p> 143 </th> 144 </tr> 145 </thead> 146 <tbody><tr id="row194461458185112"><td class="cellrowborder" valign="top" width="24.42%" headers="mcps1.2.3.1.1 "><p id="p64461158145120"><a name="p64461158145120"></a><a name="p64461158145120"></a>argc</p> 147 </td> 148 <td class="cellrowborder" valign="top" width="75.58%" headers="mcps1.2.3.1.2 "><p id="p1844625885112"><a name="p1844625885112"></a><a name="p1844625885112"></a>Specifies the number of parameters in the shell command.</p> 149 </td> 150 </tr> 151 <tr id="row144620587511"><td class="cellrowborder" valign="top" width="24.42%" headers="mcps1.2.3.1.1 "><p id="p244625811517"><a name="p244625811517"></a><a name="p244625811517"></a>argv</p> 152 </td> 153 <td class="cellrowborder" valign="top" width="75.58%" headers="mcps1.2.3.1.2 "><p id="p11446958105119"><a name="p11446958105119"></a><a name="p11446958105119"></a>Specifies a pointer array, where each element points to a string. You can determine whether to pass the command keyword to the registration function by specifying the command type.</p> 154 </td> 155 </tr> 156 </tbody> 157 </table> 158 1594. Enter the shell command in either of the following methods: 160 - Enter the shell command in a serial port tool. 161 162 - Enter the shell command in the Telnet tool. For details, see [telnet](kernel-small-debug-shell-net-telnet.md). 163 164 165 166
