| Table of Contents |
|---|
Before going into an example of µC/Shell usage, a few design concepts have to be explained. Since µC/Shell is not associated with any particular product, modules in need of a shell facility (such as µC/TELNETs) interact with it by means of an application callback function. This way, those modules are able to use or not to use the shell in a totally transparent manner.
From the caller point of view, once the commands have been developed and the initialization performed, all that is needed to do is a call the main µC/Shell execution function:
This function parses the ‘ in ’ parameter, a NUL terminated string containing a complete command line (command name, followed by possible arguments being separated by spaces), just like this one:
Once parsed, that is once the command name and its arguments have been extracted, µC/Shell looks into its command tables for a command match (in this case App_Test is the name of the command), and invokes it.
Note that the Shell_Exec() function also has a ‘out_fnct’ argument, which is a pointer to a callback that handles the details of responding to the requester. In other words, if called by µC/TELNETs, then µC/TELNETs has to provide the details of the response; if called by a UART, the UART should handle the response. Finally, the ‘pcmd_param’ is a pointer to a structure containing additional parameters for the command to use.
For more details on this function, please proceed with the next section.
Commands, Callbacks, and Data Types
µC/Shell commands (i.e., commands placed in a ‘command table’) all have this prototype:
where ‘argc’ is a count of the arguments supplied and ‘argv’, an array of pointers to the strings which are those arguments. As for the return value, it is command specific, and will be used as the return value for the Shell_Exec() function. However, in case of an error, SHELL_EXEC_ERR should be returned.
Commands are also defined by the SHELL_CMD_FNCT data type:
s mentioned in the preceding section, each command is responsible for responding to its requester, and this is done with the help of the last parameter: the pointer to the output function. This function has the following prototype:
where ‘pbuf’ is a pointer to a response buffer having a length of ‘buf_len’. The third parameter, ‘popt’, is an optional argument used to provide implementation specific information (port number, UART identification, etc.). As for the return value, it is suggested to return the number of data octets transmitted, SHELL_OUT_RTN_CODE_CONN_CLOSED if the link has been closed, and SHELL_OUT_ERR for any other error.
The output function is also defined by a data type, SHELL_OUT_FNCT:
Finally the ‘pcmd_param’ is used to pass additional information to the command. The current implementation has provision for the current working directory, as well as an option parameter used by the output function:
Note that future implementation could add members to this structure to support more parameters.
µC/Shell startup code
We provide you with an example (i.e the application code) use of µC/Shell which is found in app.c and it was written to provide a startup example on how to use the capabilities of the µC/Shell module. app.c simply initializes µC/OS?II, µC/TCP-IP and µC/Shell, and creates a few tasks and other kernel objects that will give the user information about the state of the system. Note that you DO NOT need an RTOS like µC/OS?II or a TCP/IP stack like µC/TCP-IP to use µC/Shell.
Before you can use µC/Shell, the following has to be performed:
1. Develop/create your command(s)
2. Implement output functions (if needed)
3. Initialize µC/Shell
This section of the manual will give you some examples of the above steps. Note that some sections of the source code have been removed or modified to help focus on the µC/Shell module use.
Listing 3-2 - Command
CPU_INT16S App_TestCmd (CPU_INT16U argc, (1)
CPU_CHAR *argv[],
SHELL_OUT_FNCT out_fnct,
SHELL_CMD_PARAM *pcmd_param)
{
CPU_INT16U cmd_namd_len;
CPU_INT16S output;
CPU_INT16S ret_val;
cmd_namd_len = Str_Len(argv[0]);
output = out_fnct(argv[0], (2)
cmd_namd_len,
pcmd_param->pout_opt );
switch (output) {
case SHELL_OUT_RTN_CODE_CONN_CLOSED:
case SHELL_OUT_ERR:
ret_val = SHELL_EXEC_ERR;
break;
default:
ret_val = output;
}
return (ret_val); (3)
}
L3-2(1) Function implementing a test command.
L3-2(2)
| Code Block | ||
|---|---|---|
| ||
CPU_INT16S Shell_Exec (CPU_CHAR *in,
SHELL_OUT_FNCT out_fnct,
SHELL_CMD_PARAM *pcmd_param,
SHELL_ERR *perr); |
This function parses the ‘ in ’ parameter, a NUL terminated string containing a complete command line (command name, followed by possible arguments being separated by spaces), just like this one:
| Code Block | ||
|---|---|---|
| ||
App_Test -a -b -c readme.txt |
Once parsed, that is once the command name and its arguments have been extracted, µC/Shell looks into its command tables for a command match (in this case App_Test is the name of the command), and invokes it.
Note that the Shell_Exec() function also has a ‘out_fnct’ argument, which is a pointer to a callback that handles the details of responding to the requester. In other words, if called by µC/TELNETs, then µC/TELNETs has to provide the details of the response; if called by a UART, the UART should handle the response. Finally, the ‘pcmd_param’ is a pointer to a structure containing additional parameters for the command to use.
For more details on this function, please proceed with the next section.
Commands, Callbacks, and Data Types
µC/Shell commands (i.e., commands placed in a ‘command table’) all have this prototype:
| Code Block | ||
|---|---|---|
| ||
CPU_INT16S My_Cmd (CPU_INT16U argc,
CPU_CHAR *argv[],
SHELL_OUT_FNCT out_fnct,
SHELL_CMD_PARAM *pcmd_param); |
where ‘ argc ’ is a count of the arguments supplied and ‘ argv ’, an array of pointers to the strings which are those arguments. As for the return value, it is command specific, and will be used as the return value for the Shell_Exec() function. However, in case of an error, SHELL_EXEC_ERR should be returned.
Commands are also defined by the SHELL_CMD_FNCT data type:
| Code Block | ||
|---|---|---|
| ||
typedef CPU_INT16S (*SHELL_CMD_FNCT)(CPU_INT16U ,
CPU_CHAR **,
SHELL_OUT_FNCT ,
SHELL_CMD_PARAM *); |
As mentioned in the preceding section, each command is responsible for responding to its requester, and this is done with the help of the last parameter: the pointer to the output function. This function has the following prototype:
| Code Block | ||
|---|---|---|
| ||
CPU_INT16S My_Out_Fnct (CPU_CHAR *pbuf,
CPU_INT16U buf_len,
void *popt); |
where ‘pbuf’ is a pointer to a response buffer having a length of ‘buf_len’. The third parameter, ‘popt’, is an optional argument used to provide implementation specific information (port number, UART identification, etc.). As for the return value, it is suggested to return the number of data octets transmitted, SHELL_OUT_RTN_CODE_CONN_CLOSED if the link has been closed, and SHELL_OUT_ERR for any other error.
The output function is also defined by a data type, SHELL_OUT_FNCT:
| Code Block | ||
|---|---|---|
| ||
typedef CPU_INT16S (*SHELL_OUT_FNCT)(CPU_CHAR *,
CPU_INT16U ,
void * ); |
Finally the ‘ pcmd_param ’ is used to pass additional information to the command. The current implementation has provision for the current working directory, as well as an option parameter used by the output function:
| Code Block | ||
|---|---|---|
| ||
typedef struct shell_cmd_param {
void *pcur_working_dir;
void *pout_opt;
CPU_BOOLEAN *psession_active;
} SHELL_CMD_PARAM; |
Note that future implementation could add members to this structure to support more parameters.
µC/Shell Startup Code
We provide you with an example (i.e the application code) use of µC/Shell which is found in app.c and it was written to provide a startup example on how to use the capabilities of the µC/Shell module. app.c simply initializes µC/OS?II, µC/TCP-IP and µC/Shell, and creates a few tasks and other kernel objects that will give the user information about the state of the system. Note that you DO NOT need an RTOS like µC/OS?II or a TCP/IP stack like µC/TCP-IP to use µC/Shell.
Before you can use µC/Shell, the following has to be performed:
- Develop/create your command(s)
- Implement output functions (if needed)
- Initialize µC/Shell
This section of the manual will give you some examples of the above steps. Note that some sections of the source code have been removed or modified to help focus on the µC/Shell module use.
| Anchor | ||||
|---|---|---|---|---|
|
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
CPU_INT16S App_TestShellOut (CPU_CHAR *pbuf, (1)
CPU_INT16U buf_len,
void *popt)
{
APP_TRACE_DEBUG((pbuf)); (2)
APP_TRACE_DEBUG((" executed.\n\r"));
return (buf_len); (3)
} |
| Panel | ||
|---|---|---|
| ||
(1) Function implementing the ‘output’ facility. This function MUST have the prototype specified in section 2.01. (2) This implementation simply outputs ‘pbuf’, using the trace mechanism (typically the console output). (3) Returns the number of positive data octets transmitted (no error). |
| Anchor | ||||
|---|---|---|---|---|
|
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
CPU_INT16S App_TestCmd (CPU_INT16U argc, (1)
CPU_CHAR *argv[],
SHELL_OUT_FNCT out_fnct,
SHELL_CMD_PARAM *pcmd_param)
{
CPU_INT16U cmd_namd_len;
CPU_INT16S output;
CPU_INT16S ret_val;
cmd_namd_len = Str_Len(argv[0]);
output = out_fnct(argv[0], (2)
cmd_namd_len,
pcmd_param->pout_opt );
switch (output) {
case SHELL_OUT_RTN_CODE_CONN_CLOSED:
case SHELL_OUT_ERR:
ret_val = SHELL_EXEC_ERR;
break;
default:
ret_val = output;
}
return (ret_val); (3)
} |
| Panel | ||
|---|---|---|
| ||
(1) Function implementing a test command. (2) Use the output function to display the command name. |
...
(3) |
...
The return value is command specific, with the exception of SHELL_EXEC_ERR in case of |
...
Listing 3-3 - Initialization of module
static SHELL_CMD AppShellCmdTbl[] = (1)
{
...
an error. |
| Anchor | ||||
|---|---|---|---|---|
|
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
static SHELL_CMD AppShellCmdTbl[] = (1) { {"App_test", App_TestCmd}, |
...
{0, |
...
};
void App_InitShell (void)
{
CPU_BOOLEAN success;
SHELL_ERR err;
...
0 } }; void App_InitShell (void) { CPU_BOOLEAN success; SHELL_ERR err; APP_TRACE_DEBUG(("Initialize Shell ... ")) |
...
...
; success = Shell_Init() |
...
; (2) if (success == DEF_OK) |
...
{ APP_TRACE_DEBUG(("done.\n\r")); |
...
} else {
...
} else { APP_TRACE_DEBUG(("failed.\n\r")); |
...
return;
}
...
return; } APP_TRACE_DEBUG(("Adding Shell command table ... ")); |
...
...
Shell_CmdTblAdd("App", App_ShellAppCmdTbl |
...
, &err); (3) if (err == SHELL_ERR_NONE) |
...
{ APP_TRACE_DEBUG(("done.\n\r")); |
...
} else {
...
} else { APP_TRACE_DEBUG(("failed.\n\r")); |
...
}
}
...
}
} |
| Panel | ||
|---|---|---|
| ||
(1) |
...
Declare and populate a SHELL_CMD structure table that will hold the |
...
‘App’ shell commands. |
...
The first member of this structure is the command name, and the other member a pointer to a function implementing the command itself. |
...
This command table MUST have its last entry set to ‘0’. |
...
(2) |
...
Initializes µC/Shell internal variables. |
...
(3) |
...
Add the AppShellCmdTbl module command |
...
3.03µC/Shell example use
Listing 3-4 - Example use
void App_TestShell (void)
{
SHELL_ERR err;
SHELL_CMD_PARAM cmd_param;
#if APP_FS_EN
FS_DIR *pdir;
#endif
...
table to the Shell. |
µC/Shell Example Use
Once μC/Shell has been initialized, the only thing left to do it to call the Shell_Exec() function, like depicted above.
| Anchor | ||||
|---|---|---|---|---|
|
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
void App_TestShell (void) { SHELL_ERR err; SHELL_CMD_PARAM cmd_param; #if APP_FS_EN FS_DIR *pdir; #endif APP_TRACE_DEBUG(("Testing Shell, executing command ...\n\r")); |
...
...
#if APP_FS_EN |
...
pdir = FS_OpenDir(""); |
...
cmd_param.pcur_working_dir = (void *)pdir; |
...
#else
...
#else cmd_param.pcur_working_dir = (void *)0; |
...
#endif
...
#endif cmd_param.pout_ |
...
opt = (void *)0; |
...
...
Shell_Exec( "App_test -a -b -c", &App_TestShellOut, &err); |
...
...
(1) switch (err) |
...
{ case SHELL_ERR_NONE: |
...
APP_TRACE_DEBUG(("Command executed, no error.\n |
...
break;
...
\r")); break; case SHELL_ERR_NULL_PTR: |
...
APP_TRACE_DEBUG(("Error, NULL pointer passed.\n\r |
...
break;
...
")); break; case SHELL_ERR_CMD_NOT_FOUND: |
...
APP_TRACE_DEBUG(("Error, command NOT found.\n\r")) |
...
break;
...
; break; case SHELL_ERR_CMD_SEARCH: |
...
APP_TRACE_DEBUG(("Error, searching command.\n\r")); |
...
break;
...
break; case SHELL_ERR_ARG_TBL_FULL: |
...
APP_TRACE_DEBUG(("Error, too many arguments\n\r")); |
...
break;
default:
break;
}
}
...
break;
default:
break;
}
} |
| Panel | ||
|---|---|---|
| ||
(1) Invoke the |
...
In this case, passing |
...
‘App_ |
...
Test’ will result in the function App_TestCmd() to be called |
...
. |
...
µC/
...
Shell Module Configuration
The µC/Shell module has to be configured according to your specific needs. A template configuration file (shell_cfg.h) is included in the module package (see Chapter 1, Directories and Files), and this file should be copied and added to your project. Here is the list of the values and description for each of the configuration variable. However, keep in mind that future releases of this module might include more configuration options.
...
Maximum length for module command name, including the termination NUL character.
...
µC/
...
Shell Internal Details
At initialization time, that is when the Shell_Init() function is called, two module command pools are being created: the free and the used. Right after initialization, no module command are being used, so all of the SHELL_CFG_CMD_TBL_SIZE module command are located into the free pool, and the used pool is empty, like displayed below (SHELL_CFG_CMD_TBL_SIZE set to 3 in this example).
| Anchor | ||||
|---|---|---|---|---|
|
|
| Panel | ||||
|---|---|---|---|---|
| ||||
|
Adding module command tables to the shell with Shell_CmdTblAdd() results in a free module command being taken from that pool, initialized, and taken into the used pool. Below is a representation of the pools after two module command tables have been inserted.
3-2 - Anchor Figure - Pools after modules insertion Figure - Pools after modules insertion
| Panel | ||||
|---|---|---|---|---|
| ||||
|
When the Shell_Exec() function is being called in order to parse a line and execute a command, the lists of module commands have to be searched to find a match. Since the module command tables are inserted in a way analog to a stack, the search begins with the last addition. For instance, if the ‘OS’ table has been inserted just after the ‘Net’ one, command search will always look at the ‘OS’ command table, then proceed with the ‘Net’ command table if a match has not been found.
Two searches are necessary to locate a command. First, the correct module command table has to be found based on the command prefix, and then the corresponding command inside that table is looked for. The second search also starts with index ‘0’ of the command table, and increments that index by ‘1’ until a match is found.
...