RTEMS 4.9.1 On-Line Library

Configuration and Initialization Adding Custom Commands

RTEMS Shell User's Guide

1.2.2: Adding Custom Commands

One of the design goals of the RTEMS Shell was to make it easy for a user to add custom commands specific to their application. We believe this design goal was accomplished. In order to add a custom command, the user is required to do the following:

Provide a main-style function which implements the command. If that command function uses a getopt related function to parse arguments, it MUST use the reentrant form.
Provide a command definition structure of type rtems_shell_cmd_t.
Configure that command using the CONFIGURE_SHELL_USER_COMMANDS macro.

Custom aliases are configured similarly but the user only provides an alias definition structure of type rtems_shell_alias_t and configures the alias via the CONFIGURE_SHELL_USER_ALIASES macro.

In the following example, we have implemented a custom command named usercmd which simply prints the arguments it was passed. We have also provided an alias for usercmd named userecho.

#include <rtems/shell.h>

int main_usercmd(int argc, char **argv)
{
  int i;
  printf( "UserCommand: argc=%d\n", argc );
  for (i=0 ; i<argc ; i++ )
    printf( "argv[%d]= %s\n", i, argv[i] );
  return 0;
}

rtems_shell_cmd_t Shell_USERCMD_Command = {
  "usercmd",                  /* name */
  "usercmd n1 [n2 [n3...]]",  /* usage */
  "user",                     /* topic */
  main_usercmd,               /* command */
  NULL,                       /* alias */
  NULL                        /* next */
};

rtems_shell_alias_t Shell_USERECHO_Alias = {
  "usercmd",                  /* command */
  "userecho"                  /* alias */
};

#define CONFIGURE_SHELL_USER_COMMANDS &Shell_USERCMD_Command
#define CONFIGURE_SHELL_USER_ALIASES &Shell_USERECHO_Alias
#define CONFIGURE_SHELL_COMMANDS_INIT
#define CONFIGURE_SHELL_COMMANDS_ALL
#define CONFIGURE_SHELL_MOUNT_MSDOS

#include <rtems/shellconfig.h>

Notice in the above example, that the user wrote the main for their command (e.g. main_usercmd) which looks much like any other main(). They then defined a rtems_shell_cmd_t structure named Shell_USERCMD_Command which describes that command. This command definition structure is registered into the static command set by defining CONFIGURE_SHELL_USER_COMMANDS to &Shell_USERCMD_Command.

Similarly, to add the userecho alias, the user provides the alias definition structure named Shell_USERECHO_Alias and defines CONFIGURE_SHELL_USER_ALIASES to configure the alias.

The user can configure any number of commands and aliases in this manner.

RTEMS Shell User's Guide