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#

  1. 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#

  1. 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#

  1. Shell_Init() MUST be called before the other Shell functions are invoked.

  2. Shell_Init() MUST ONLY be called ONCE from the product's application.

  3. Module command pools MUST be initialized before initializing the pool with pointers to module commands.

  4. The functions Shell_Configure...() can be used to configure more specific properties of the Shell sub-module, when RTOS_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#

  1. 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#

  1. 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.

  2. 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#

  1. 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.

  1. 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#

  1. The first token is always the command name itself.

  2. 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.