Shell API#
Shell_ConfigureCmdUsage()#
Description#
Configure the properties of the commands used by the Shell sub-module.
Files#
shell.h/shell.c
Prototype#
void Shell_ConfigureCmdUsage (SHELL_CFG_CMD_USAGE *p_cfg)
Arguments#
p_cfg
Pointer to the structure containing the command usage parameters.
Returned Value#
None.
Notes / Warnings#
This function is optional. If it is called, it must be called before
Shell_Init()
. If it is not called, default values will be used to initialize the module.
Shell_ConfigureMemSeg()#
Description#
Configure the memory segment that will be used to allocate internal data needed by Shell instead of the default memory segment.
Files#
shell.h/shell.c
Prototype#
void Shell_ConfigureMemSeg (MEM_SEG *p_mem_seg)
Arguments#
p_mem_seg
Pointer to the memory segment from which the internal data will be allocated.
If
DEF_NULL
, the internal data will be allocated from the global Heap.
Returned Value#
None.
Notes / Warnings#
This function is optional. If it is called, it must be called before
Shell_Init()
. If it is not called, default values will be used to initialize the module.
Shell_Init()#
Description#
Initializes the shell module.
Files#
shell.h/shell.c
Prototype#
void Shell_Init (RTOS_ERR *p_err)
Arguments#
p_err
Pointer to variable that receives the following return error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_OWNERSHIP
RTOS_ERR_ALREADY_EXISTS
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_SEG_OVF
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_NOT_AVAIL
RTOS_ERR_OS_ILLEGAL_RUN_TIME
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_OVF
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_INVALID_ARG
RTOS_ERR_NO_MORE_RSRC
RTOS_ERR_IS_OWNER
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT
Returned Value#
None.
Notes / Warnings#
Shell_Init()
MUST be called before the other Shell functions are invoked.Shell_Init()
MUST ONLY be called ONCE from the product's application.Module command pools MUST be initialized before initializing the pool with pointers to module commands.
The functions
Shell_Configure...()
can be used to configure more specific properties of the Shell sub-module, whenRTOS_CFG_EXTERNALIZE_OPTIONAL_CFG_EN
is set to 1. If set to 1, the structure Shell_InitCfg needs to be declared and filled by the application to configure these specific properties for the module.
Shell_Exec()#
Description#
Parses and executes a command passed in the following parameters :
(a) Parse input string
(b) Search command
(c) Execute command
Files#
shell.h/shell.c
Prototype#
CPU_INT16S Shell_Exec (CPU_CHAR *in,
SHELL_OUT_FNCT out_fnct,
SHELL_CMD_PARAM *p_cmd_param,
RTOS_ERR *p_err)
Arguments#
in
Pointer to a CPU_CHAR string holding a complete command and its argument(s). This string MUST be editable, it cannot be 'const'.
out_fnct
Pointer to the 'output' function used by command (see Note #1).
p_cmd_param
Pointer to the command additional parameters.
p_err
Pointer to variable that receives the following return error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_SHELL_CMD_EXEC
RTOS_ERR_NOT_FOUND
RTOS_ERR_CMD_EMPTY
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_NOT_AVAIL
RTOS_ERR_WOULD_OVF
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_IS_OWNER
RTOS_ERR_NO_MORE_RSRC
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT
Returned Value#
Command specific return value.
Notes / Warnings#
The command may generate some output that should be transmitted to some devices (socket, RS-232 link, ...). The caller of this function is responsible for the implementation of such functions, if output is desired.
Shell_CmdTblAdd()#
Description#
Allocates and initializes a module command as follows :
(a) Validate module command
(b) Get a free module command
(c) Initialize module command
(d) Add to module command used pool.
The module command pools are implemented as doubly-linked lists :
(a) 'Shell_ModuleCmdUsedPoolPtr' and 'Shell_ModuleCmdFreePoolPtr' points to the head of the module command pool.
(b) Module command NextModuleCmdPtr's and PrevModuleCmdPtr's links each command to form the module command pool doubly-linked list.
(c) Module command are inserted and removed at the head of the module command pool lists.
Module commands are inserted & removed at the head (see Note #2c) | NextModuleCmdPtr | (see Note #2b) v | | ------- ------- v ------- ------- Module command Pool ---->| |------>| |------>| |------>| | Pointer | | | | | | | | | |<------| |<------| |<------| | (see Note #2a) ------- ------- ------- ^ ------ | | PrevModuleCmdPtr (see Note #2b) | | |<-----Pool of Free/Used Module Commands ------>| | (see Note #2) |
Files#
shell.h/shell.c
Prototype#
void Shell_CmdTblAdd (CPU_CHAR *cmd_tbl_name,
SHELL_CMD cmd_tbl[],
RTOS_ERR *p_err)
Arguments#
cmd_tbl_name
Pointer to character string representing the name of the command table.
cmd_tbl
Command table to add.
p_err
Pointer to variable that receives the following return error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_OWNERSHIP
RTOS_ERR_ALREADY_EXISTS
RTOS_ERR_BLK_ALLOC_CALLBACK
RTOS_ERR_SEG_OVF
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_NOT_AVAIL
RTOS_ERR_POOL_EMPTY
RTOS_ERR_WOULD_OVF
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_INVALID_ARG
RTOS_ERR_NO_MORE_RSRC
RTOS_ERR_IS_OWNER
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT
Returned Value#
None.
Notes / Warnings#
The 'cmd_tbl_name' parameter is not mandatory in the current implementation. Although you could pass a 'NULL' value for this parameter, it is recommended to provide it to allow the removal of 'cmd_tbl' from the Shell_CmdTblRem().
However, passing NULL for this parameter will result in the first command prefix to be extracted and used as the command table name.
If an empty character array is passed in the cmd_tbl_name parameter, the function will extract the first command prefix to use as the command table name.
Shell_CmdTblRem()#
Description#
Removes a module command as follows :
(a) Search module command (b) Remove module command (c) Update module command pools
Files#
shell.h/shell.c
Prototype#
void Shell_CmdTblRem (CPU_CHAR *cmd_tbl_name, RTOS_ERR *p_err)
Arguments#
cmd_tbl_name
Pointer to character string representing the name of the command table.
p_err
Pointer to variable that receives the following return error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_NOT_AVAIL
RTOS_ERR_POOL_FULL
RTOS_ERR_WOULD_OVF
RTOS_ERR_OWNERSHIP
RTOS_ERR_OS_OBJ_DEL
RTOS_ERR_NOT_FOUND
RTOS_ERR_WOULD_BLOCK
RTOS_ERR_IS_OWNER
RTOS_ERR_OS_SCHED_LOCKED
RTOS_ERR_ABORT
RTOS_ERR_TIMEOUT
Returned Value#
None.
Notes / Warnings#
None.
Shell_Scanner()#
Description#
Scans and parses the command line.
Files#
shell.h/shell.c
Prototype#
CPU_INT16U Shell_Scanner (CPU_CHAR *in,
CPU_CHAR *arg_tbl[],
CPU_INT16U arg_tbl_size,
RTOS_ERR *p_err)
Arguments#
in
Pointer to a NUL terminated string holding a complete command and its argument(s).
arg_tbl
Array of pointer that will receive pointers to token.
arg_tbl_size
Size of arg_tbl array.
p_err
Pointer to variable that receives the following return error codes from this function :
RTOS_ERR_NONE
RTOS_ERR_NO_MORE_RSRC
Returned Value#
Number of token(s) (command name and argument(s)).
Notes / Warnings#
The first token is always the command name itself.
This function modify the 'in' arguments by replacing token's delimiter characters by termination character ('\0').
Shell_OptParse()#
Description#
Parses optional command line arguments.
Files#
shell.h/shell.c
Prototype#
SHELL_OPTPARSE_STATE Shell_OptParse (CPU_INT16U argc,
CPU_CHAR *argv[],
SHELL_OPTPARSE_STATE state,
CPU_CHAR *opt_str)
Arguments#
argc
Argument count.
argv
Pointer to argument table.
state
Argument parsing state structure.
opt_str
Argument string to parse.
Returned Value#
SHELL_OPTPARSE_STATE.
Notes / Warnings#
None.